Merkle Tools

The SDK ships three sets of merkle helpers. Pick the set that matches your data lifecycle.

Choose the Right Helpers

Goal	Helpers
Prepare a tree and derive proofs at runtime	Builders
Store data compactly and derive proofs on demand later	Serialized helpers
Pre-compute every proof and embed in a static payload	Payload helpers

For large recipient sets stored in Redis, KV, databases, or object storage, the serialized helpers are usually the right choice.

Builders

Build trees in memory, then derive proofs from the in-memory tree object.

`buildMerkleTree`


buildMerkleTree(recipients, { airdrop, rootIndex })

Builds one in-memory tree for a single root. Use it when your full recipient set fits into one root or when you want direct access to one tree object.

rootIndex identifies this tree’s position within the airdrop’s overall root set — even a single-root airdrop stores its root at an index on-chain, and buildMerkleRoots emits a rootIndex for every root it produces. Use 0 for a single-root layout.

`buildMerkleRoots`


buildMerkleRoots(recipients, { airdrop, maxRoots?, maxLeavesPerRoot? })

Splits recipients into multiple roots when needed and returns:

rootEntries — pass these into registerMerkleRoot
trees — keep these to derive proofs or claim parameters later

`getMerkleProof`


getMerkleProof(tree, leafIndex)

Derives the proof path for one leaf from an in-memory tree.

`createClaimMerkleParams`


createClaimMerkleParams(tree, leafIndex)

Builds the ClaimMerkleParams object expected by claimMerkleTokens.

Use buildMerkleRoots when you need both registration data and proof derivation. Use buildMerkleTree when you only need one root.

Serialized Helpers

Convert in-memory trees into a compact, JSON-friendly format. Each node is stored once; proofs are reconstructed on demand.

`serializeMerkleTree`


serializeMerkleTree(tree)

Converts one in-memory tree into a JSON-friendly format that stores leaves and layers once.

`serializeMerkleRoots`


serializeMerkleRoots(result)

Serializes the output of buildMerkleRoots, including both root entries and trees.

`getMerkleProofFromSerializedTree`


getMerkleProofFromSerializedTree(serializedTree, leafIndex)

Rebuilds the proof path for one leaf from serialized layers.

`createClaimMerkleParamsFromSerializedTree`


createClaimMerkleParamsFromSerializedTree(serializedTree, leafIndex)

Rebuilds the full claim parameters directly from serialized data.

Payload Helpers

Pre-compute every proof and embed in the output payload. Larger output, but no runtime derivation needed.

`createMerklePayload`


createMerklePayload(leaves)

Builds a single-root payload that includes root metadata, leaf hashes, and proofs. leaves here is an array of already-constructed merkle leaves (hashed recipient entries), not raw { wallet, amount } recipients — use createMerklePayloadBundle if you want to start from raw recipients.

`createMerklePayloadBundle`


createMerklePayloadBundle(recipients, options)

Builds a multi-root payload bundle with all proofs expanded.

Payload helpers produce much larger output than serialized tree storage. Prefer serialized helpers when you have a large number of recipients.

Next Step

Continue to On-chain List if your recipient source is on-chain list chunk data instead of merkle leaves.