Skip to content

Block

Block

Bases: KernelOpaquePtr

A deserialized Bitcoin block.

Source code in pbk/block.py 
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
class Block(KernelOpaquePtr):
    """A deserialized Bitcoin block."""

    _create_fn = k.btck_block_create
    _destroy_fn = k.btck_block_destroy

    def __init__(self, raw_block: bytes):
        """Create a block from serialized data.

        Args:
            raw_block: The serialized block data in consensus format.

        Raises:
            RuntimeError: If parsing the block data fails (propagated from base class).
        """
        super().__init__((ctypes.c_ubyte * len(raw_block))(*raw_block), len(raw_block))

    @property
    def block_hash(self) -> BlockHash:
        """The hash of this block.

        Computes the double-SHA256 hash of the block header.

        Returns:
            The block hash.
        """
        return BlockHash._from_handle(k.btck_block_get_hash(self))

    def __bytes__(self) -> bytes:
        """Serialize the block to bytes.

        Returns:
            The serialized block data in consensus format, suitable for
            P2P network transmission.
        """
        writer = ByteWriter()
        return writer.write(k.btck_block_to_bytes, self)

    def _get_transaction_at(self, transaction_index: int) -> Transaction:
        """Get the transaction at the given index."""
        return Transaction._from_view(
            k.btck_block_get_transaction_at(self, transaction_index), self
        )

    @property
    def transactions(self) -> TransactionSequence:
        """All transactions in this block.

        Returns:
            A lazy sequence of transactions, including the coinbase.
        """
        return TransactionSequence(self)

    def __repr__(self) -> str:
        """Return a string representation of the block."""
        return f"<Block hash={str(self.block_hash)} txs={len(self.transactions)}>"

block_hash property 

block_hash: BlockHash

The hash of this block.

Computes the double-SHA256 hash of the block header.

RETURNS DESCRIPTION
BlockHash

The block hash.

transactions property 

transactions: TransactionSequence

All transactions in this block.

RETURNS DESCRIPTION
TransactionSequence

A lazy sequence of transactions, including the coinbase.

__bytes__ 

__bytes__() -> bytes

Serialize the block to bytes.

RETURNS DESCRIPTION
bytes

The serialized block data in consensus format, suitable for
bytes

P2P network transmission.
Source code in pbk/block.py 
205
206
207
208
209
210
211
212
213
def __bytes__(self) -> bytes:
    """Serialize the block to bytes.

    Returns:
        The serialized block data in consensus format, suitable for
        P2P network transmission.
    """
    writer = ByteWriter()
    return writer.write(k.btck_block_to_bytes, self)

__init__ 

__init__(raw_block: bytes)

Create a block from serialized data.

PARAMETER DESCRIPTION
raw_block

The serialized block data in consensus format.

TYPE: bytes

RAISES DESCRIPTION
RuntimeError

If parsing the block data fails (propagated from base class).
Source code in pbk/block.py 
183
184
185
186
187
188
189
190
191
192
def __init__(self, raw_block: bytes):
    """Create a block from serialized data.

    Args:
        raw_block: The serialized block data in consensus format.

    Raises:
        RuntimeError: If parsing the block data fails (propagated from base class).
    """
    super().__init__((ctypes.c_ubyte * len(raw_block))(*raw_block), len(raw_block))

__repr__ 

__repr__() -> str

Return a string representation of the block.

Source code in pbk/block.py 
230
231
232
def __repr__(self) -> str:
    """Return a string representation of the block."""
    return f"<Block hash={str(self.block_hash)} txs={len(self.transactions)}>"

BlockHash

Bases: KernelOpaquePtr

Identifier for a block.

Source code in pbk/block.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
class BlockHash(KernelOpaquePtr):
    """Identifier for a block."""

    _create_fn = k.btck_block_hash_create
    _destroy_fn = k.btck_block_hash_destroy

    def __init__(self, block_hash: bytes):
        """Create a block hash from raw bytes.

        Args:
            block_hash: The 32-byte block hash in little-endian byte order.

        Raises:
            ValueError: If the block hash is not exactly 32 bytes.
            RuntimeError: If the C constructor fails (propagated from base class).
        """
        if len(block_hash) != 32:
            raise ValueError(
                f"block_hash argument must be bytes of length 32, got {len(block_hash)}"
            )
        hash_array = (ctypes.c_ubyte * 32).from_buffer_copy(block_hash)
        super().__init__(hash_array)

    def __bytes__(self) -> bytes:
        """Serialize the block hash to bytes.

        Returns:
            The 32-byte block hash in little-endian byte order.
        """
        hash_array = (ctypes.c_ubyte * 32)()
        k.btck_block_hash_to_bytes(self, hash_array)
        return bytes(hash_array)

    def __str__(self) -> str:
        """Get the hexadecimal representation of the block hash.

        Returns:
            The block hash as a 64-character hex string in big-endian
            byte order (standard Bitcoin display format).
        """
        # bytes are serialized in little-endian byte order, typically displayed in big-endian byte order
        return bytes(self)[::-1].hex()

    def __eq__(self, other: object) -> bool:
        """Check equality with another block hash.

        Args:
            other: Object to compare with.

        Returns:
            True if both are BlockHash instances with equal values.
        """
        if isinstance(other, BlockHash):
            return bool(k.btck_block_hash_equals(self, other))
        return False

    def __hash__(self) -> int:
        """Get hash value for use in sets and dictionaries.

        Returns:
            Hash of the block hash bytes.
        """
        return hash(bytes(self))

    def __repr__(self) -> str:
        """Return a string representation of the block hash."""
        return f"BlockHash({bytes(self)!r})"

__bytes__ 

__bytes__() -> bytes

Serialize the block hash to bytes.

RETURNS DESCRIPTION
bytes

The 32-byte block hash in little-endian byte order.
Source code in pbk/block.py 
33
34
35
36
37
38
39
40
41
def __bytes__(self) -> bytes:
    """Serialize the block hash to bytes.

    Returns:
        The 32-byte block hash in little-endian byte order.
    """
    hash_array = (ctypes.c_ubyte * 32)()
    k.btck_block_hash_to_bytes(self, hash_array)
    return bytes(hash_array)

__eq__ 

__eq__(other: object) -> bool

Check equality with another block hash.

PARAMETER DESCRIPTION
other

Object to compare with.

TYPE: object

RETURNS DESCRIPTION
bool

True if both are BlockHash instances with equal values.
Source code in pbk/block.py 
53
54
55
56
57
58
59
60
61
62
63
64
def __eq__(self, other: object) -> bool:
    """Check equality with another block hash.

    Args:
        other: Object to compare with.

    Returns:
        True if both are BlockHash instances with equal values.
    """
    if isinstance(other, BlockHash):
        return bool(k.btck_block_hash_equals(self, other))
    return False

__hash__ 

__hash__() -> int

Get hash value for use in sets and dictionaries.

RETURNS DESCRIPTION
int

Hash of the block hash bytes.
Source code in pbk/block.py 
66
67
68
69
70
71
72
def __hash__(self) -> int:
    """Get hash value for use in sets and dictionaries.

    Returns:
        Hash of the block hash bytes.
    """
    return hash(bytes(self))

__init__ 

__init__(block_hash: bytes)

Create a block hash from raw bytes.

PARAMETER DESCRIPTION
block_hash

The 32-byte block hash in little-endian byte order.

TYPE: bytes

RAISES DESCRIPTION
ValueError

If the block hash is not exactly 32 bytes.
RuntimeError

If the C constructor fails (propagated from base class).
Source code in pbk/block.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def __init__(self, block_hash: bytes):
    """Create a block hash from raw bytes.

    Args:
        block_hash: The 32-byte block hash in little-endian byte order.

    Raises:
        ValueError: If the block hash is not exactly 32 bytes.
        RuntimeError: If the C constructor fails (propagated from base class).
    """
    if len(block_hash) != 32:
        raise ValueError(
            f"block_hash argument must be bytes of length 32, got {len(block_hash)}"
        )
    hash_array = (ctypes.c_ubyte * 32).from_buffer_copy(block_hash)
    super().__init__(hash_array)

__repr__ 

__repr__() -> str

Return a string representation of the block hash.

Source code in pbk/block.py 
74
75
76
def __repr__(self) -> str:
    """Return a string representation of the block hash."""
    return f"BlockHash({bytes(self)!r})"

__str__ 

__str__() -> str

Get the hexadecimal representation of the block hash.

RETURNS DESCRIPTION
str

The block hash as a 64-character hex string in big-endian
str

byte order (standard Bitcoin display format).
Source code in pbk/block.py 
43
44
45
46
47
48
49
50
51
def __str__(self) -> str:
    """Get the hexadecimal representation of the block hash.

    Returns:
        The block hash as a 64-character hex string in big-endian
        byte order (standard Bitcoin display format).
    """
    # bytes are serialized in little-endian byte order, typically displayed in big-endian byte order
    return bytes(self)[::-1].hex()

BlockTreeEntry

Bases: KernelOpaquePtr

Entry in the block tree.

A block tree entry represents a single block in the block tree maintained by the chainstate manager. Each entry (except genesis) points to a single parent, and multiple entries may share a parent, forming a tree structure. Each entry corresponds to a single block and may be used to retrieve its data and validation status.

Source code in pbk/block.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
class BlockTreeEntry(KernelOpaquePtr):
    """Entry in the block tree.

    A block tree entry represents a single block in the block tree
    maintained by the chainstate manager. Each entry (except genesis)
    points to a single parent, and multiple entries may share a parent,
    forming a tree structure. Each entry corresponds to a single block
    and may be used to retrieve its data and validation status.
    """

    @property
    def block_hash(self) -> BlockHash:
        """The hash of the block this entry represents.

        Returns:
            The block hash associated with this entry.
        """
        return BlockHash._from_view(k.btck_block_tree_entry_get_block_hash(self))

    @property
    def height(self) -> int:
        """The height of this block in the chain.

        Returns:
            The block height. Genesis block is at height 0.
        """
        return k.btck_block_tree_entry_get_height(self)

    @property
    def previous(self) -> "BlockTreeEntry":
        """The parent block tree entry.

        Returns:
            The previous block tree entry in the tree.

        Raises:
            RuntimeError: If the C constructor fails (propagated from base class).
        """
        return BlockTreeEntry._from_view(k.btck_block_tree_entry_get_previous(self))

    def __eq__(self, other: object) -> bool:
        """Check equality with another block tree entry.

        Args:
            other: Object to compare with.

        Returns:
            True if both are BlockTreeEntry instances with equal height and hash.
        """
        if isinstance(other, BlockTreeEntry):
            return self.height == other.height and self.block_hash == other.block_hash
        return False

    def __hash__(self) -> int:
        """Get hash value for use in sets and dictionaries.

        Returns:
            Hash combining height and block hash.
        """
        return hash((self.height, bytes(self.block_hash)))

    def __repr__(self) -> str:
        """Return a string representation of the block tree entry."""
        return f"<BlockTreeEntry height={self.height} hash={str(self.block_hash)}>"

block_hash property 

block_hash: BlockHash

The hash of the block this entry represents.

RETURNS DESCRIPTION
BlockHash

The block hash associated with this entry.

height property 

height: int

The height of this block in the chain.

RETURNS DESCRIPTION
int

The block height. Genesis block is at height 0.

previous property 

previous: BlockTreeEntry

The parent block tree entry.

RETURNS DESCRIPTION
BlockTreeEntry

The previous block tree entry in the tree.
RAISES DESCRIPTION
RuntimeError

If the C constructor fails (propagated from base class).

__eq__ 

__eq__(other: object) -> bool

Check equality with another block tree entry.

PARAMETER DESCRIPTION
other

Object to compare with.

TYPE: object

RETURNS DESCRIPTION
bool

True if both are BlockTreeEntry instances with equal height and hash.
Source code in pbk/block.py 
119
120
121
122
123
124
125
126
127
128
129
130
def __eq__(self, other: object) -> bool:
    """Check equality with another block tree entry.

    Args:
        other: Object to compare with.

    Returns:
        True if both are BlockTreeEntry instances with equal height and hash.
    """
    if isinstance(other, BlockTreeEntry):
        return self.height == other.height and self.block_hash == other.block_hash
    return False

__hash__ 

__hash__() -> int

Get hash value for use in sets and dictionaries.

RETURNS DESCRIPTION
int

Hash combining height and block hash.
Source code in pbk/block.py 
132
133
134
135
136
137
138
def __hash__(self) -> int:
    """Get hash value for use in sets and dictionaries.

    Returns:
        Hash combining height and block hash.
    """
    return hash((self.height, bytes(self.block_hash)))

__repr__ 

__repr__() -> str

Return a string representation of the block tree entry.

Source code in pbk/block.py 
140
141
142
def __repr__(self) -> str:
    """Return a string representation of the block tree entry."""
    return f"<BlockTreeEntry height={self.height} hash={str(self.block_hash)}>"

TransactionSequence

Bases: LazySequence[Transaction]

Lazily-evaluated sequence of transactions in a block.

This sequence provides indexed access to transactions within a block. The sequence is a view into the block and caches its length on first access.

Source code in pbk/block.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
class TransactionSequence(LazySequence[Transaction]):
    """Lazily-evaluated sequence of transactions in a block.

    This sequence provides indexed access to transactions within a block.
    The sequence is a view into the block and caches its length on first access.
    """

    def __init__(self, block: "Block"):
        """Create a sequence view of transactions.

        Args:
            block: The block to create a sequence view for.
        """
        self._block = block

    def __len__(self) -> int:
        """Number of transactions in the block.

        Returns:
            The transaction count (cached after first call).
        """
        if not hasattr(self, "_cached_len"):
            self._cached_len = k.btck_block_count_transactions(self._block)
        return self._cached_len

    def _get_item(self, index: int) -> Transaction:
        """Get the transaction at the given index."""
        return Transaction._from_view(
            k.btck_block_get_transaction_at(self._block, index), self._block
        )

__init__ 

__init__(block: Block)

Create a sequence view of transactions.

PARAMETER DESCRIPTION
block

The block to create a sequence view for.

TYPE: Block

Source code in pbk/block.py 
152
153
154
155
156
157
158
def __init__(self, block: "Block"):
    """Create a sequence view of transactions.

    Args:
        block: The block to create a sequence view for.
    """
    self._block = block

__len__ 

__len__() -> int

Number of transactions in the block.

RETURNS DESCRIPTION
int

The transaction count (cached after first call).
Source code in pbk/block.py 
160
161
162
163
164
165
166
167
168
def __len__(self) -> int:
    """Number of transactions in the block.

    Returns:
        The transaction count (cached after first call).
    """
    if not hasattr(self, "_cached_len"):
        self._cached_len = k.btck_block_count_transactions(self._block)
    return self._cached_len

TransactionSpentOutputsSequence

Bases: LazySequence[TransactionSpentOutputs]

Lazily-evaluated sequence of spent outputs for transactions in a block.

This sequence provides indexed access to the spent outputs (undo data) for each transaction in a block. The sequence excludes the coinbase transaction, which has no spent outputs.

Source code in pbk/block.py 
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
class TransactionSpentOutputsSequence(LazySequence[TransactionSpentOutputs]):
    """Lazily-evaluated sequence of spent outputs for transactions in a block.

    This sequence provides indexed access to the spent outputs (undo data)
    for each transaction in a block. The sequence excludes the coinbase
    transaction, which has no spent outputs.
    """

    def __init__(self, block_spent_outputs: "BlockSpentOutputs"):
        """Create a sequence view of transaction spent outputs.

        Args:
            block_spent_outputs: The block spent outputs to create a sequence view for.
        """
        self._block_spent_outputs = block_spent_outputs

    def __len__(self) -> int:
        """Number of transaction spent outputs in the block. Equals the number of transactions in
        the block, minus 1 because the coinbase transaction is excluded as it has no spent outputs.

        Returns:
            The count of transaction spent outputs (cached after first call).
        """
        if not hasattr(self, "_cached_len"):
            self._cached_len = k.btck_block_spent_outputs_count(
                self._block_spent_outputs
            )
        return self._cached_len

    def _get_item(self, index: int) -> TransactionSpentOutputs:
        """Get the transaction spent outputs at the given index."""
        ptr = k.btck_block_spent_outputs_get_transaction_spent_outputs_at(
            self._block_spent_outputs, index
        )
        return TransactionSpentOutputs._from_view(ptr, self._block_spent_outputs)

__init__ 

__init__(block_spent_outputs: BlockSpentOutputs)

Create a sequence view of transaction spent outputs.

PARAMETER DESCRIPTION
block_spent_outputs

The block spent outputs to create a sequence view for.

TYPE: BlockSpentOutputs

Source code in pbk/block.py 
243
244
245
246
247
248
249
def __init__(self, block_spent_outputs: "BlockSpentOutputs"):
    """Create a sequence view of transaction spent outputs.

    Args:
        block_spent_outputs: The block spent outputs to create a sequence view for.
    """
    self._block_spent_outputs = block_spent_outputs

__len__ 

__len__() -> int

Number of transaction spent outputs in the block. Equals the number of transactions in the block, minus 1 because the coinbase transaction is excluded as it has no spent outputs.

RETURNS DESCRIPTION
int

The count of transaction spent outputs (cached after first call).
Source code in pbk/block.py 
251
252
253
254
255
256
257
258
259
260
261
262
def __len__(self) -> int:
    """Number of transaction spent outputs in the block. Equals the number of transactions in
    the block, minus 1 because the coinbase transaction is excluded as it has no spent outputs.

    Returns:
        The count of transaction spent outputs (cached after first call).
    """
    if not hasattr(self, "_cached_len"):
        self._cached_len = k.btck_block_spent_outputs_count(
            self._block_spent_outputs
        )
    return self._cached_len

BlockSpentOutputs

Bases: KernelOpaquePtr

Spent outputs (undo data) for all transactions in a block.

Block spent outputs contain all the previous outputs consumed by all transactions in a specific block. This data is also known as "undo data" because it's necessary for reverting blocks during chain reorganizations. The data is stored as a nested structure: a sequence of transaction spent outputs, each containing the coins consumed by that transaction's inputs.

Source code in pbk/block.py 
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
class BlockSpentOutputs(KernelOpaquePtr):
    """Spent outputs (undo data) for all transactions in a block.

    Block spent outputs contain all the previous outputs consumed by all
    transactions in a specific block. This data is also known as "undo data"
    because it's necessary for reverting blocks during chain reorganizations.
    The data is stored as a nested structure: a sequence of transaction spent
    outputs, each containing the coins consumed by that transaction's inputs.
    """

    # Non-instantiable but can own pointers when read from disk
    _destroy_fn = k.btck_block_spent_outputs_destroy

    def _get_transaction_spent_outputs_at(self, index: int) -> TransactionSpentOutputs:
        """Get the transaction spent outputs at the given index."""
        ptr = k.btck_block_spent_outputs_get_transaction_spent_outputs_at(self, index)
        return TransactionSpentOutputs._from_view(ptr, self)

    @property
    def transactions(self) -> TransactionSpentOutputsSequence:
        """Spent outputs for each transaction in the block.

        Returns:
            A sequence of transaction spent outputs, excluding the coinbase.
        """
        return TransactionSpentOutputsSequence(self)

    def __repr__(self) -> str:
        """Return a string representation of the block spent outputs."""
        return f"<BlockSpentOutputs txs={len(self.transactions)}>"

transactions property 

transactions: TransactionSpentOutputsSequence

Spent outputs for each transaction in the block.

RETURNS DESCRIPTION
TransactionSpentOutputsSequence

A sequence of transaction spent outputs, excluding the coinbase.

__repr__ 

__repr__() -> str

Return a string representation of the block spent outputs.

Source code in pbk/block.py 
299
300
301
def __repr__(self) -> str:
    """Return a string representation of the block spent outputs."""
    return f"<BlockSpentOutputs txs={len(self.transactions)}>"