Skip to content
Ashen Docs

Finalized History MMR & Proof RPCs

Source: docs/design/light-client-mmr-onchain.md, src/storage/finalized_mmr.rs, src/rpc/node_rpc_v1.idl

Overview

Section titled “Overview”

The chain maintains an append-only Merkle Mountain Range (MMR) over finalized blocks. This provides compact inclusion proofs for any finalized height and is used by light clients, RPC nodes, and verified fast sync.

Key properties:

  • Leaves are (height, block_hash) entries.
  • The MMR is append-only and only advances with finalized blocks.
  • Proofs are short and verifiable against a single root.

Data Model

Section titled “Data Model”

Leaf hash

Section titled “Leaf hash”

Each leaf is hashed as:

BLAKE3("finalized_entry_v1" || height_le || block_hash)

Root

Section titled “Root”

The MMR root is a 32-byte BLAKE3 hash computed from all finalized entries.

Proof

Section titled “Proof”

A membership proof includes:

  • leaf_position (0-indexed)
  • leaf_count at time of proof
  • siblings: a list of (hash, is_left) pairs

Verification folds siblings from leaf to root, using the is_left flag to order concatenation.

RPC Endpoints

Section titled “RPC Endpoints”

All endpoints are in node_rpc_v1:

finality_proof

Section titled “finality_proof”

Returns a FinalityProofResult for a block height:

  • height, block_hash, epoch, view, parent_view
  • key_version
  • certificate (BLS threshold signature, hex)
  • proof_bytes (borsh-encoded proof, hex)

light_client_context

Section titled “light_client_context”

Returns LightClientContextResult for verifying a finality proof:

  • commitment_root (validator set root)
  • aggregate_bls_pubkey
  • validators (addresses + voting power)
  • aggregate_key_proof (Merkle proof for aggregate key)
  • context_bytes (borsh-encoded context, hex)

finalized_history_root

Section titled “finalized_history_root”

Returns FinalizedHistoryRootResult:

  • root (hex) or null if no finalized blocks
  • leaf_count

finalized_history_proof

Section titled “finalized_history_proof”

Returns FinalizedHistoryProofResult:

  • height, block_hash
  • leaf_position, leaf_count
  • siblings (hash + is_left)
  • root

get_light_snapshot

Section titled “get_light_snapshot”

Returns GetLightSnapshotResult for checkpoint fast sync:

  • checkpoint (height + state_root)
  • header (block header fields)
  • mmr_proof (finalized history proof)
  • finality_proof (optional)
  • validators
  • snapshot_bytes (borsh-encoded snapshot)

Verification Flow (Light Client)

Section titled “Verification Flow (Light Client)”

  1. Finality proof

    • Fetch finality_proof(height) and light_client_context(height).
    • Verify the BLS certificate against the aggregate key and validator set.

  2. MMR inclusion (optional but recommended)

    • Fetch finalized_history_root() and finalized_history_proof(height).
    • Recompute the leaf hash and fold siblings to verify the root.
    • This proves the finalized block is included in the append-only history.

  3. Fast sync (checkpoints)

    • Fetch get_light_snapshot(height).
    • Verify the snapshot header and MMR proof against a trusted root.

CLI Helpers (Local Verification)

Section titled “CLI Helpers (Local Verification)”

The node CLI includes helpers for proof verification:

node verify --height 100 --rpc-url http://127.0.0.1:3030
node verify-snapshot --height 100 --trusted-root 0x...

Caching and Consistency

Section titled “Caching and Consistency”
  • Proofs are cached server-side but invalidated on each append to the MMR.
  • leaf_count is part of the proof. A proof is valid only for that count.

Error Cases

Section titled “Error Cases”

Common errors:

  • NOT_FOUND: height not in MMR
  • MMR_EMPTY: no finalized blocks recorded
  • MMR_POSITION_OUT_OF_BOUNDS: bad leaf position
Section titled “Related Docs”
  • docs/design/light-client-mmr-onchain.md
  • docs/design/state-layout.md
  • docs/design/data-availability-sampling.md