Update docs/BLOCKS_AND_TRANSACTIONS.md

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.