The tree that remembers every transfer

Quantus keeps a 4-ary Poseidon Merkle tree over every transfer on the chain — one leaf per transfer, folded once per block, its root published in the block header. It is the backbone of the wormhole privacy exits: your ZK proof of "I was paid" is a Merkle path in this tree. This desk watches it live, recomputes its hashes exactly, and lets you prove things against it.

Arity4 children / node

HashPoseidon2 · Goldilocks

Circuit ceilingdepth 16 · 4.29B leaves

Leaf floor≥ 1 leaf / block (mining reward)

🔭 Tree Observatory

Live reads from wss://rpc.quantus.network via the ZkTreeApi runtime API (state_call), with state_getStorage fallback on the ZkTree storage keys. If the node is unreachable the desk says so — it never invents numbers.

RPC endpoint not connected

Leaves—LeafCount

Depth—capacity —

Pending this block—UnprocessedLeaves

Root (in block header)—Root · set via frame_system::set_zk_tree_root in on_finalize

Capacity gauge

depth 0 · capacity 0circuit ceiling · depth 16 · 4.29B leaves

How leaves get in

Every block the mining-rewards pallet records the block reward — that is the ≥ 1 leaf/block floor (pallets/mining-rewards/src/lib.rs).
SafeSend reversible transfers and vesting payouts each record a leaf per transfer (pallets/reversible-transfers, pallets/vesting).
Leaves are appended during the block (UnprocessedLeaves counts them) and folded into the tree once per block in on_finalize — the root you read mid-block covers the previous block's leaves.
Only leaves already folded are provable: get_merkle_proof returns LeafNotYetSettled for this block's fresh leaves.

🍃 Leaf Lab — the exact `hash_leaf`

Recomputes tree::hash_leaf exactly as the runtime does — the same 8-felt layout, the same lossy compact encoding, the same quantization. Pinned against the upstream golden vector (tests.rs::hash_leaf_golden_vector).

Recipient qz… SS58 address or 32-byte hex

transfer_count asset_id

amount QTC (decimals ok)

Felt preimage 8 felts → Poseidon2

#	field	value (felt)
Hash a leaf to see its 8-felt preimage.

Why is from not in the leaf? Uniqueness comes from (to, transfer_count) — each recipient's counter only moves forward, so every transfer to them gets a unique index. The sender is irrelevant to proving "I received funds once".

The lossy-encoding invariant. Each 8-byte limb is reduced mod the Goldilocks prime, so a recipient and its non-canonical byte-alias hash identically. The wormhole keys transfer counts on the canonical form so two deposits can never commit to the same leaf (and the same nullifier). This desk canonicalizes before hashing and tells you when it had to.

Two decimals of privacy. Amounts are quantized to amount / 10¹⁰ (2 QTC decimals) and committed as a u32 — oversized values saturate at u32::MAX rather than wrapping, so a huge transfer can never alias a small one in the tree.

🌱 Tree Simulator — grow your own 4-ary tree

Appends leaves like the runtime does (pending → folded once per "block"), hashes with the exact hash_node (children sorted before hashing), and grows depth exactly when capacity is exceeded. Empty subtrees read as the zero hash — same as on-chain.

empty tree

Tree state

Settled leaves0

Pending0

Depth0

Capacity0

root: —

Event log LeafInserted · TreeGrew

No events yet — append a leaf, then finalize.

Tree map click a node for its hash

Click any node to inspect its hash.

Batched folding. The runtime does not rehash the path on every insert — inserts only append, and on_finalize folds the whole block's range in one bottom-up pass (~n/3 node hashes instead of n · depth). Pressing "Finalize block" runs that same fold here.

Sorted children. Proofs need no path indices because every node sorts its 4 children before hashing — the verifier just sorts and hashes. Try it: the simulator hashes children in shuffled order and still lands on the same node.

🧾 Proof Lab — generate & verify Merkle proofs

Generate proofs for leaves in your simulated tree, paste proofs to verify by hand, or — the real thing — pull a live proof from the chain and verify it against the live root, entirely in your browser.

From the simulator

leaf index

Verify pasted proof

proof JSON {leaf_index, siblings: [[h,h,h], …]}

expected root hex

The leaf fields come from the Leaf Lab — hash one there first, or fill them below.

transfer_count asset_id amount (QTC)

⚡ Live chain proof needs Observatory connection

Fetches the leaf's SCALE bytes from the ZkTree.Leaves map, decodes them, fetches ZkTreeApi_get_merkle_proof, and runs the exact verify_proof against the live root — a trustless check that this desk's math matches the chain's.

leaf index

Honest caveat: only leaves already folded into the root are provable — a leaf appended in the current block returns LeafNotYetSettled until the next block finalizes.

🌀 Wormhole & circuits — what the tree is for

The tree is the commitment layer for private exits. When a transfer is recorded, its leaf commits to (recipient, per-recipient count, asset, quantized amount) — no sender, no secrets. Later, the recipient proves in zero knowledge: "some leaf in this tree paid me, and I know the secret that lets me spend it". The wormhole pallet checks that proof with verify_private_batch / verify_public_batch (pallet 20) and enforces one-spend-per-leaf with nullifiers.

1Recordtransfer → record_transfer → leaf appended

2Foldon_finalize folds the block's leaves; root → block header

3Proverecipient fetches ZkTreeApi_get_merkle_proof, builds a ZK proof off-chain

4Exitwormhole verifies the batch proof; nullifier blocks replays

The depth-16 circuit ceiling

The chain lets the tree grow to depth 32, but the deployed ZK circuits only accept proofs up to depth 16 — every leaf proof pays a full 16-level path, so the cap keeps proving fast. 4¹⁶ ≈ 4.29 billion leaves. If the tree ever outgrows it, proof generation halts until a circuit update + runtime upgrade raises the ceiling — a deliberate "fix it when we get close" trade-off, documented in pallets/zk-tree/src/lib.rs. LeafCount is public storage, so exhaustion is visible years in advance.

leaves / block

1 leaf/block (mining-reward floor)—

10 transfers/sec chain-wide—

Saturated blocks (~50 tps)—

Chain facts this story stands on Quantus-Network/chain @ 482c5b9

4-ary tree, Poseidon2-Goldilocks, MAX_TREE_DEPTH = 32, CIRCUIT_MAX_TREE_DEPTH = 16 — pallets/zk-tree/src/lib.rs
Leaf = (to, transfer_count, asset_id, amount); AMOUNT_SCALE_DOWN_FACTOR = 10¹⁰ — pallets/zk-tree/src/tree.rs
Root published in the block header via frame_system::set_zk_tree_root in on_finalize
Leaf sources: mining rewards every block (pallets/mining-rewards/src/lib.rs:247), SafeSend (pallets/reversible-transfers/src/lib.rs:833), vesting (pallets/vesting/src/lib.rs:643)
Per-recipient transfer_count keyed on the canonical recipient; nullifier binds (secret, transfer_count) — pallets/wormhole/src/lib.rs
Wormhole dispatchables: verify_private_batch, verify_public_batch (pallet 20)

📖 Spec — constants, storage, events, RPC

Everything below is read from Quantus-Network/chain @ 482c5b9 and re-verified for this release.

Constants

constant	value	where
ARITY	4	tree.rs
MAX_TREE_DEPTH	32 (chain cap)	lib.rs
CIRCUIT_MAX_TREE_DEPTH	16 (circuit ceiling)	lib.rs
AMOUNT_SCALE_DOWN_FACTOR	10¹⁰	tree.rs
INSERT_LEAF_DB_OPS	(3 reads, 4 writes)	lib.rs
INSERT_LEAF_POSEIDON_EVALS	2	lib.rs
POSEIDON_EVAL_REF_TIME_PS	10,000,000 (10µs)	lib.rs
TREE_KEY_POV	2,600 bytes	lib.rs
pallet index	21	runtime/src/lib.rs
storage prefix	"ZkTree"	runtime/src/lib.rs

Storage

item	type	notes
Leaves	map u64 → ZkLeaf (Identity)	60-byte SCALE: to[32] ++ tc u64 LE ++ asset u32 LE ++ amount u128 LE
Nodes	map (u8, u64) → [u8; 32] (Identity)	level 0 unused; root lives in Root, not Nodes
LeafCount	u64	public — exhaustion is observable
Depth	u8	0 = empty
Root	[u8; 32]	covers leaves up to end of previous block
UnprocessedLeaves	u64	this block's pending leaves; drained by on_finalize

Events

event	payload	notes
LeafInserted	{ index: u64 }	leaf hash deliberately omitted — derivable from Leaves
TreeGrew	{ new_depth: u8 }	fired when capacity is exceeded

Runtime API (`ZkTreeApi` via `state_call`)

method	params (SCALE)	returns
ZkTreeApi_get_root	—	[u8; 32]
ZkTreeApi_get_leaf_count	—	u64 LE
ZkTreeApi_get_depth	—	u8
ZkTreeApi_get_merkle_proof	u64 LE leaf_index	Option<ZkMerkleProofRpc>

Honest limits

This desk recomputes hashes and verifies proofs — it does not generate ZK proofs or perform wormhole exits; proving needs the off-chain circuit crates.
Leaf contents (recipient, amount) are public on-chain data — the tree commits to transfers, it does not hide them. Privacy comes from the ZK proof layer on top.
Amounts in leaves have only 2 decimals of precision; dust below 10¹⁰ plancks quantizes to zero in the commitment.
The "live" views need a reachable node; this page never fabricates chain state when the node is down.

Built by @kshot9000 · github.com/Kshot3000 · upstream org
Donations (QTC): qznY8nwuvWcCCVys4da1oQdysyh8YUZYRjRqgk3S8Wos8kbau

The tree that remembers every transfer

🔭 Tree Observatory

Capacity gauge

How leaves get in

🍃 Leaf Lab — the exact hash_leaf

Felt preimage 8 felts → Poseidon2

🌱 Tree Simulator — grow your own 4-ary tree

Tree state

Event log LeafInserted · TreeGrew

Tree map click a node for its hash

🧾 Proof Lab — generate & verify Merkle proofs

From the simulator

Verify pasted proof

⚡ Live chain proof needs Observatory connection

🌀 Wormhole & circuits — what the tree is for

The depth-16 circuit ceiling

Chain facts this story stands on Quantus-Network/chain @ 482c5b9

📖 Spec — constants, storage, events, RPC

Constants

Storage

Events

Runtime API (ZkTreeApi via state_call)

Honest limits

🍃 Leaf Lab — the exact `hash_leaf`

Runtime API (`ZkTreeApi` via `state_call`)