Skip to main content

Merkle Proofs

A Merkle proof demonstrates that a Block hash is included in the leaf collection represented by a specified Merkle root hash. Applications can verify inclusion using only the Block hash, the proof, and the trusted Merkle root without loading the entire tree.

Merkle Proof Model​

The optional Merkle extension orders each pair of bytes32 values before hashing with Keccak-256. Core ALX conformance does not require Merkle proofs. Because every implementation that claims the extension applies the same ordering rule, proofs do not need to record left or right sibling positions, and equivalent inputs produce the same Merkle root.

Proof Verification​

getMerkleProof() and verifyMerkleProof() from @alx-protocol/sdk/merkle implement the steps below; getMerkleProof() returns null for a Block hash outside the leaf collection. To verify a proof:

  1. Start with the Block hash.
  2. Combine the current hash with each sibling hash in the proof.
  3. Order the pair by raw 32-byte value, smaller value first.
  4. Hash the 64-byte concatenation with Keccak-256.
  5. Repeat until every proof element has been processed.

Verification succeeds when the final computed hash matches the expected Merkle root. An empty proof succeeds only through direct equality between the Block hash and Merkle root.

When to Use a Merkle Proof​

Use a Merkle proof when a verifier trusts a Merkle root but does not need every Block hash in the tree. A successful proof confirms only that the Block hash is included in the leaf collection represented by that Merkle root. A proof for a Block hash that occurs more than once in the leaf collection establishes inclusion of the value, not the number or position of occurrences.