Tree paging & archive

The logical commitment tree remains depth 16, but its leaves are archived in bounded Solana accounts. The page archive is an authenticated storage layout for the same global Merkle root; it is not a second, alternative membership tree.

Account layout

• TreeState stores pool, generation, next index, sequence, compact frontier nodes, empty-subtree hashes and 32 roots with sequence/generation metadata.
• PageDirectory stores 16 page roots, integrity hashes for each page's canonical bytes and canonical page bumps.
• LeafPage stores a short header and raw 32-byte commitments. The first 12 tree levels form one page subtree.

Each page has depth 12 and holds 2^12 = 4,096 commitments. Sixteen pages compose the 16-bit global index space. The directory combines those 16 page roots through four upper levels.

The page PDA uses leaf-page, pool, little-endian generation and one-byte page index. A directory uses page-dir, pool and little-endian generation. Each populated page is checked against its canonical PDA, data length, leaf count, page hash and chunk digests before it is accepted.

Boundary behavior

The important cross-page boundary is index 4,096: index 4,095 is the final leaf in page 0, and index 4,096 is the first leaf in page 1. The Core transaction accepts the additional destination page when a two-output Private Swap crosses that boundary.

The 2026-10-07 release validation exercised an organic Private Swap that appended change at index 4,095 and output at index 4,096. Both notes were reconstructed after restart from the 18-account request, with zero history calls. That finalized transaction was 756 bytes and consumed 660,935 compute units.

Why paging is used on Solana

Paging keeps large append-only commitment bytes out of the frequently updated fixed-size tree account. It bounds each page's data size and rent growth, isolates append writes to the active page, and lets the directory authenticate page roots while Core verifies only the pages involved in an operation. TreeState and page updates remain atomic within a Solana transaction.

Rollover and historical generations

Capacity is 65,536 leaves per generation. Rollover becomes eligible when at most one slot remains; it creates a new TreeState and PageDirectory and updates the active tree pointer. Earlier generation accounts remain available for spends against roots from those trees.

The validation report did not execute a real organic Devnet Gen0→Gen1 rollover. The SDK/Core support generation-aware PDAs and witness reconstruction, but no real Devnet scale result for that rollover is claimed. See Validation evidence for the coverage details.