Struct SealMerkleTree 

#[repr(C)]
pub struct SealMerkleTree {
    pub root: [u8; 32],
    /* private fields */
}

Seal Merkle Tree for incremental construction of historical payment roots.

This tree grows incrementally, adding each new payment merkle root as a leaf. It enables unlimited claim history while maintaining perfect security.

Growth Pattern

The seal tree grows incrementally:

• Epoch 0: [Payment Root 0]
• Epoch 1: [Payment Root 0] + [Payment Root 1] -> Seal Root 1
• Epoch 2: [Payment Root 0] + [Payment Root 1] + [Payment Root 2] -> Seal Root 2
• …
• Epoch N: [Payment Root 0] + … + [Payment Root N] -> Seal Root N

Security

• Each payment root is embedded in the seal tree
• Seal proofs demonstrate payment root authenticity
• Dual verification prevents all attack vectors

🚨 CRITICAL: Chronological Ordering Requirement

PAYMENT ROOTS MUST BE PROVIDED IN CHRONOLOGICAL ORDER (EPOCH 0, 1, 2, 3…)

This is essential for:

• Deterministic seal merkle root generation
• Consistent verification between Oracle and on-chain program
• Preventing 0x10 (InvalidPaymentProof) errors

The Oracle team MUST ensure:

1. Database queries return epochs in chronological order
2. Payment roots are collected in epoch sequence
3. SealMerkleTree::from_payment_roots() receives ordered data

Failure to maintain chronological ordering will result in:

• Different seal merkle roots between Oracle and on-chain
• Proof verification failures
• Inability to process claims

Fields

root: [u8; 32]

Current seal merkle root (32 bytes)

Implementations

impl SealMerkleTree

pub fn new() -> Self

Create a new empty seal merkle tree.

Returns

• Empty seal merkle tree with zero root

pub fn from_payment_roots(payment_roots: Vec<[u8; 32]>) -> Self

Create a seal merkle tree from existing payment roots.

Parameters

• payment_roots: Vector of historical payment merkle roots

Returns

• Seal merkle tree with all payment roots included

Important: Chronological Ordering

The payment roots MUST be provided in chronological order (epoch 0, 1, 2, 3…) to ensure deterministic and verifiable seal merkle roots across all systems. This ordering rule is enforced to maintain consistency between Oracle and on-chain verification.

pub fn add_payment_root(&mut self, payment_root: [u8; 32])

Add a new payment root to the seal merkle tree.

This function incrementally grows the seal tree by adding the new payment root and rebuilding the tree structure.

Parameters

• payment_root: New payment merkle root to add

Returns

• Updated seal merkle tree with new payment root included

Important: Chronological Ordering

Payment roots MUST be added in chronological order (epoch 0, 1, 2, 3…) to maintain deterministic tree structure. This method assumes the new payment root is for the next sequential epoch.

pub fn root(&self) -> [u8; 32]

Get the current seal merkle root.

Returns

• Current seal merkle root (32 bytes)

pub fn payment_root_count(&self) -> usize

Get the number of payment roots in the seal tree.

Returns

• Number of historical payment roots

pub fn payment_roots(&self) -> &[[u8; 32]]

Get all payment roots in the seal tree.

Returns

• Vector of all historical payment roots

pub fn validate_chronological_order(&self) -> bool

Validate that payment roots are in chronological order.

This method helps ensure the Oracle team is providing payment roots in the correct epoch sequence for deterministic tree construction.

Returns

• true if payment roots appear to be in chronological order
• false if there are potential ordering issues

Note

This is a best-effort validation since we can’t directly determine epoch numbers from payment root hashes. The Oracle team must ensure chronological ordering when calling this method.

pub fn generate_seal_proof(&self, payment_root: [u8; 32]) -> Option<SealProof>

Generate a seal proof for a specific payment root.

This function creates a proof that demonstrates a payment root is included in the current seal merkle tree.

Parameters

• payment_root: Payment root to generate proof for

Returns

• Some(SealProof) if payment root is found
• None if payment root is not in the tree

pub fn generate_seal_proof_for_epoch( &self, epoch_index: usize, ) -> Option<SealProof>

Find and generate a seal proof for a payment root by epoch.

This is a convenience function that finds a payment root by its epoch index and generates a seal proof for it.

Parameters

• epoch_index: Index of the epoch (0-based)

Returns

• Some(SealProof) if epoch exists
• None if epoch index is out of bounds

pub fn contains_payment_root(&self, payment_root: [u8; 32]) -> bool

Verify that a payment root is included in the seal tree.

Parameters

• payment_root: Payment root to verify

Returns

• true if payment root is in the seal tree
• false if payment root is not in the seal tree

Trait Implementations

impl Clone for SealMerkleTree

fn clone(&self) -> SealMerkleTree

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SealMerkleTree

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SealMerkleTree

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for SealMerkleTree

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.