doc: add python-bitcoinlib example

Add an example on using python-bitcoinlib, to help inspecting
the bytes objects returned by the bitcoinkernel API.

Author: stickies-v

README.md

@@ -3,7 +3,7 @@
 [![versions](https://img.shields.io/pypi/pyversions/py-bitcoinkernel.svg)](https://github.com/stickies-v/py-bitcoinkernel)
 [![license](https://img.shields.io/github/license/stickies-v/py-bitcoinkernel.svg)](https://github.com/stickies-v/py-bitcoinkernel/blob/main/LICENSE)
 
-`py-bitcoinkernel` is a Python wrapper around
+`py-bitcoinkernel` (or `pbk` in short) is a Python wrapper around
 [`libbitcoinkernel`](https://github.com/bitcoin/bitcoin/pull/30595)
 providing a clean, Pythonic interface while handling the low-level
 ctypes bindings and memory management.
@@ -138,6 +138,10 @@ with open("raw_blocks.txt", "r") as file:
 
 ### Common operations
 
+> [!NOTE]
+> See [doc/examples](./doc/examples/) for more common usage examples of
+> `pbk`
+
 ChainstateManager exposes a range of functionality to interact with the
 chainstate. For example, to print the current block tip:
 
@@ -175,6 +179,10 @@ with open(filename, "wb") as f:
   want to use `py-bitcoinkernel` with an existing chainstate, you'll
   need to either first shut down `Bitcoin Core`, or clone the `blocks/`
   and `chainstate/` directories to a new location.
+- The `bitcoinkernel` API currently does not offer granular inspection
+  of most kernel objects. See [doc/examples](./doc/examples/) for ideas
+  on using third-party (de)serialization libraries to convert kernel
+  objects to/from bytes.
 
 ## Resources
 Some helpful resources for learning about `libbitcoinkernel`:

doc/examples/README.md

@@ -0,0 +1,4 @@
+# Example usage of py-bitcoinkernel
+
+- Using `python-bitcoinlib` to (de)serialize and inspect kernel objects:
+  [python-bitcoinlib.md](./python-bitcoinlib.md)

doc/examples/python-bitcoinlib.md

@@ -0,0 +1,51 @@
+# Python-bitcoinlib Examples
+
+The [`python-bitcoinlib`](https://github.com/petertodd/python-bitcoinlib)
+library allows constructing various objects from bytes. We can use this
+to more granularly inspect kernel objects that expose their contents as
+bytes, such as [`Block`](#inspecting-block-data) (`kernel_Block`) and
+[`TransactionOutput`](#inspecting-transactionoutput-data)
+(`kernel_TransactionOutput`).
+
+> [!NOTE]
+> The `python-bitcoinlib` library is unrelated to this project, and
+> information here is provided only on a best-effort basis.
+
+## Setup
+
+First, we'll create a ChainstateManager and load the current chain tip:
+
+```py
+import pbk
+chainman = pbk.load_chainman("/tmp/bitcoin/signet/", pbk.ChainType.SIGNET)
+tip = chainman.get_block_index_from_tip()
+```
+
+## Inspecting Block Data
+
+To analyze the block, we can use the `python-bitcoinlib` `CBlock` class:
+
+```py
+from bitcoin.core import CBlock
+
+block_bytes = chainman.read_block_from_disk(tip).data
+cblock = CBlock.deserialize(block_bytes)
+
+assert tip.block_hash.hex == cblock.GetHash().hex()
+print(f"Block {cblock.GetHash().hex()} has {len(cblock.vtx)} transactions and {cblock.GetWeight()} weight")
+print(f"The last transaction has witness data: {cblock.vtx[-1].wit.vtxinwit}")
+```
+
+## Inspecting TransactionOutput data
+
+```py
+from bitcoin.core.script import CScript
+from pprint import pprint
+
+undo = chainman.read_block_undo_from_disk(tip)
+result = {}
+for i, tx in enumerate(undo.iter_transactions()):
+    result[i] = [CScript(output.script_pubkey.data) for output in tx.iter_outputs()]
+print(f"Block {tip.height} has transactions spending the following previous outputs:")
+pprint(result)
+```