jam.state.merkle package

Submodules

Module Contents

class jam.state.merkle.Node(hash_function: Hash | None = None)[source]

Bases: object

Node encoding for Merkle trees as defined in D.2.1

Nodes are fixed in size at 512 bit (64 bytes). Each node is either a branch or a leaf. The first bit discriminates between these two types.

NODE_SIZE = 64
ZERO_HASH = 0x0000000000000000000000000000000000000000000000000000000000000000
__init__(hash_function: Hash | None = None)[source]

Initialize node encoder with optional hash function

encode_branch(left_hash: ByteArray32, right_hash: ByteArray32) → ByteArray64[source]

Encode a branch node (B function in D.3)

For a branch, we: 1. Clear the first bit of left_hash (AND with 0xfe) 2. Concatenate with full right_hash

encode_leaf(key: ByteArray32, value: Bytes) → ByteArray64[source]

Encode a leaf node (L function in D.4)

For a leaf, the second bit discriminates between embedded-value leaves and regular leaves. For embedded values (|v| ≤ 32):

  • 6 bits store the embedded value size

  • First 31 bytes store key

  • Last 32 bytes store the value (zero-padded)

For regular leaves:

  • 6 bits are zeroed

  • First 31 bytes store key

  • Last 32 bytes store hash of value

class jam.state.merkle.MerkleTrie(hash_function: ~jam.types.protocol.crypto.Hash = <function Hash.blake2b>)[source]

Bases: object

Binary Merkle Trie implementation as defined in D.2

This implements the basic Merklization function Mσ which transforms a serialized state mapping into a cryptographic commitment.

__init__(hash_function: ~jam.types.protocol.crypto.Hash = <function Hash.blake2b>)[source]

Initialize an empty Merkle trie with optional hash function

class jam.state.merkle.StateMerkle(hash_function: ~jam.types.protocol.crypto.Hash = <function Hash.blake2b>)[source]

Bases: object

State Merklization implementation as defined in D.2

This class implements the Mσ function which transforms a serialized state mapping into a cryptographic commitment using a binary Merkle Patricia trie.

__init__(hash_function: ~jam.types.protocol.crypto.Hash = <function Hash.blake2b>)[source]

Initialize state merkle with optional hash function

_get_bit(key: ByteArray32, index: int) → bool[source]

Get bit at index from key.

Parameters:

  • key – 32-byte array to extract bit from

  • index – Position of bit to extract (0-255)

Returns:

Value of bit at specified index

Return type:

bool

_merkelize_recursive(items: List[Tuple[ByteArray32, ByteArray32]], bit_index: int) → Tuple[ByteArray32, ByteArray64][source]

Recursive merkelization

merkelize(state_dict: Dict[ByteArray32, ByteArray32]) → ByteArray32[source]

Merkelize a state dictionary into a cryptographic commitment (Mσ function)

Parameters:

state_dict – Dictionary mapping state keys to their serialized values

Returns:

The root hash of the resulting Merkle trie

Return type:

bytes

get_nodes() → Dict[ByteArray32, ByteArray64][source]

Get all nodes in the trie, useful for proof generation

clear() → None[source]

Clear the trie state