Struct MerkleTree 

pub struct MerkleTree { /* private fields */ }

A Merkle tree built from XorNames (content addresses)

Used for batch payment system where:

• Build tree from XorNames (min: 2, max: 65,536)
• Tree is automatically padded to next power of 2
• Root is committed on-chain for payment
• Intersections at level depth/2 determine candidate pools
• Individual address proofs verify addresses belong to paid batch

Implementations

impl MerkleTree

pub fn from_xornames( leaves: Vec<XorName>, ) -> Result<MerkleTree, MerkleTreeError>

Create a new Merkle tree from XorNames

Arguments

• leaves - Vector of XorNames (address addresses). Min: 2, Max: 65,536

Returns

A new MerkleTree with automatic padding to next power of 2

Errors

• TooFewLeaves if less than 2 leaves
• TooManyLeaves if more than 65,536 leaves

Example

let addresses: Vec<XorName> = vec![
    XorName::from_content(b"address1"),
    XorName::from_content(b"address2"),
    XorName::from_content(b"address3"),
];

let tree = MerkleTree::from_xornames(addresses)?;
println!("Root: {:?}", tree.root());
println!("Depth: {}", tree.depth());

pub fn root(&self) -> XorName

Get the root hash of the tree

This is the hash committed on-chain for batch payment

pub fn depth(&self) -> u8

Get the depth of the tree

pub fn leaf_count(&self) -> usize

Get the original leaf count (before padding)

pub fn reward_candidates( &self, merkle_payment_timestamp: u64, ) -> Result<Vec<MidpointProof>, MerkleTreeError>

Get reward candidates for batch payment

Computes candidate addresses as hash(midpoint_hash || root || merkle_payment_timestamp). Network nodes closest to these addresses are eligible for payment rewards. Each candidate contains a proof that the midpoint belongs to the tree. Returns 2^ceil(depth/2) reward candidates.

Arguments

• merkle_payment_timestamp - Unix timestamp of the transaction (seconds since epoch)

Returns

A vector of RewardCandidatePool or an error if proof generation fails

Example

let tree = MerkleTree::from_xornames(addresses)?;
let merkle_payment_timestamp = SystemTime::now()
    .duration_since(UNIX_EPOCH)
    .expect("Failed to get current time")
    .as_secs();

let candidates = tree.reward_candidates(merkle_payment_timestamp)?;

// Each candidate's branch can be verified independently
for candidate in candidates {
    assert!(candidate.branch.verify());
}

pub fn generate_address_proof( &self, address_index: usize, address_hash: XorName, ) -> Result<MerkleBranch, MerkleTreeError>

Generate a proof that a address belongs to this tree

Arguments

• address_index - Index of the address (0-based, must be < leaf_count)
• address_hash - The XorName hash of the address data

Important: Index vs Hash

Both the index and hash are required:

• Index: Tells us the address’s position in the tree (which leaf)
• Hash: The actual XorName we’re proving belongs at that position

The proof verifies: “This specific hash is at this specific index in the tree”

Example

// You have addresses with their original order preserved
let addresses: Vec<XorName> = vec![
    XorName::from_content(b"address 0 data"),
    XorName::from_content(b"address 1 data"),
    XorName::from_content(b"address 2 data"),
];

// Build tree from the addresses
let tree = MerkleTree::from_xornames(addresses.clone())?;

// Generate proofs for all addresses
for (index, address_hash) in addresses.iter().enumerate() {
    // index: position in the tree (0, 1, 2)
    // address_hash: the actual XorName at that position
    let proof = tree.generate_address_proof(index, *address_hash)?;

    // Each proof can be verified independently
    assert!(proof.verify());
}

Returns

A MerkleBranch proof from address to root

Errors

• InvalidLeafIndex if index >= leaf_count