From adb32e73dba8e1cd1f1cfd6504d97cd6297efb37 Mon Sep 17 00:00:00 2001
From: contractless <contractless@noreply.localhost>
Date: Sun, 12 Jul 2026 21:00:45 +0000
Subject: [PATCH] Update docs/BLOCKS_AND_TRANSACTIONS.md

---
 docs/BLOCKS_AND_TRANSACTIONS.md | 46 ++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/docs/BLOCKS_AND_TRANSACTIONS.md b/docs/BLOCKS_AND_TRANSACTIONS.md
index aa55370..2f2c9a7 100644
--- a/docs/BLOCKS_AND_TRANSACTIONS.md
+++ b/docs/BLOCKS_AND_TRANSACTIONS.md
@@ -6,6 +6,7 @@ This page covers the general block and transaction CLI tools:
 - `broadcast_transaction`
 - `lookup_block_by_hash`
 - `lookup_block_by_height`
+- `lookup_torrent`
 - `lookup_total_transactions`
 - `lookup_transaction`
 
@@ -248,6 +249,49 @@ The hash must be 64 hexadecimal characters.
 
 The returned JSON has the same decoded block shape as `lookup_block_by_height`.
 
+## lookup_torrent
+
+`lookup_torrent` asks a configured node for the torrent metadata associated with a block height.
+
+Blocks and torrents work together in Contractless. The block file contains the block header and transaction payload. The torrent metadata describes how peers can retrieve and verify the block data used during sync and relay.
+
+### Usage
+
+```bash
+./lookup_torrent <block_number>
+```
+
+Example:
+
+```bash
+./lookup_torrent 31445
+```
+
+The tool asks for the wallet path and wallet decryption key for the node handshake. This lookup does not spend funds.
+
+### Example Return
+
+The exact fields depend on the torrent structure, but a successful response is printed as decoded torrent JSON.
+
+```json
+{
+  "announce": "<announce data>",
+  "info": {
+    "name": "31445.block",
+    "piece_length": 16384,
+    "pieces": "<piece hashes>"
+  }
+}
+```
+
+If the torrent is not found, the node may return a text error such as:
+
+```text
+error: Block 31445 not found
+```
+
+If the response cannot be decoded as a torrent but contains bytes, the tool prints a hex JSON fallback.
+
 ## lookup_total_transactions
 
 `lookup_total_transactions` asks a configured node for transaction totals grouped by transaction type.
@@ -371,4 +415,4 @@ A normal transfer flow is:
 
 ```bash
 ./lookup_block_by_height <block_number>
-```
+```
\ No newline at end of file