Struct GenericTreeServer 

pub struct GenericTreeServer<S: ShardStore<H = MerkleHashVote, CheckpointId = u32>> { /* private fields */ }

An append-only Poseidon Merkle tree server backed by any shardtree::store::ShardStore.

Use the type aliases TreeServer (KV-backed) and MemoryTreeServer (in-memory) rather than naming this type directly.

Methods that mutate the tree return Result so storage failures are visible to callers. For MemoryTreeServer the error type is Infallible, so those results can be safely .unwrap()-ed; for TreeServer the error type is crate::kv_shard_store::KvError and must be propagated.

Implementations

impl GenericTreeServer<KvShardStore>

pub fn new(cb: KvCallbacks, next_position: u64) -> Self

Create a new KV-backed tree server.

next_position is CommitmentTreeState.NextIndex from KV (0 on first boot). On a cold start, latest_checkpoint is initialised from the maximum checkpoint ID persisted in the KV store, so that root() returns the correct value even before the first checkpoint after restart.

impl GenericTreeServer<KvShardStore>

pub fn append_from_kv( &mut self, cursor: u64, count: u64, ) -> Result<(), AppendFromKvError>

Append count leaves starting at cursor by reading them directly from the application KV store via KV callbacks, skipping the Go-side leaf fetch and CGO serialization round-trip.

Each leaf is stored at 0x02 || u64 BE index in the Cosmos KV store (the CommitmentLeafKey format from types/keys.go). On success, the tree’s internal leaf count advances by count.

This is the production delta-append path: a single CGO call to this function replaces the newLeaves allocation + per-leaf KV read loop that was previously done in ensureTreeLoaded.

impl<S> GenericTreeServer<S>

where S: ShardStore<H = MerkleHashVote, CheckpointId = u32>, S::Error: Debug,

pub fn append(&mut self, leaf: Fp) -> Result<u64, ShardTreeError<S::Error>>

Append a single leaf (e.g. one VAN from MsgDelegateVote).

The leaf is marked so witnesses can be generated for it later. Returns the leaf index.

pub fn append_two( &mut self, first: Fp, second: Fp, ) -> Result<u64, ShardTreeError<S::Error>>

Append two leaves (e.g. new VAN + VC from MsgCastVote).

Returns the index of the first leaf.

pub fn checkpoint( &mut self, height: u32, ) -> Result<(), CheckpointError<S::Error>>

Snapshot the current tree state at the given block height.

Called by EndBlocker after processing all transactions in a block. The root at this checkpoint becomes a valid anchor for ZKP #2 / ZKP #3.

Errors

Returns CheckpointError::NotMonotonic if height is not strictly greater than the previous checkpoint height. Returns CheckpointError::Tree if the underlying shard store fails.

pub fn root(&self) -> Fp

Current Merkle root (at the latest checkpoint).

pub fn root_at_height(&self, height: u32) -> Option<Fp>

Root at a specific checkpoint height (anchor lookup).

Returns None if the checkpoint does not exist.

pub fn size(&self) -> u64

Number of leaves appended.

pub fn set_next_position(&mut self, pos: u64)

Set the leaf count directly (e.g. to restore after a cold start when next_position was not passed to TreeServer::new).

pub fn path(&self, position: u64, anchor_height: u32) -> Option<MerklePath>

Build a Merkle path for the leaf at position, valid at the given checkpoint anchor_height.

Returns None if the position or checkpoint is invalid.