@ocash/sdk 0.1.4-rc.0 → 0.1.4-rc.2

package/dist/index.cjs

@@ -3289,8 +3289,8 @@ var MemoryStore = class {
     this.utxos = /* @__PURE__ */ new Map();
     this.operations = [];
     this.merkleLeavesByChain = /* @__PURE__ */ new Map();
-    this.merkleTreesByChain = /* @__PURE__ */ new Map();
-    this.merkleNodesByChain = /* @__PURE__ */ new Map();
+    this.chairmanMerkleVersionsByChain = /* @__PURE__ */ new Map();
+    this.chairmanMerkleNodesByChain = /* @__PURE__ */ new Map();
     this.entryMemosByChain = /* @__PURE__ */ new Map();
     this.entryNullifiersByChain = /* @__PURE__ */ new Map();
     const max = options?.maxOperations;
@@ -3306,8 +3306,8 @@ var MemoryStore = class {
       this.utxos.clear();
       this.operations = [];
       this.merkleLeavesByChain.clear();
-      this.merkleTreesByChain.clear();
-      this.merkleNodesByChain.clear();
+      this.chairmanMerkleVersionsByChain.clear();
+      this.chairmanMerkleNodesByChain.clear();
       this.entryMemosByChain.clear();
       this.entryNullifiersByChain.clear();
     }
@@ -3423,49 +3423,64 @@ var MemoryStore = class {
     return { chainId, cid: row.cid, commitment: row.commitment };
   }
   /**
-   * Get a merkle node by id.
+   * Get a chairmanMerkle tree node by id.
    */
-  async getMerkleNode(chainId, id) {
-    return this.merkleNodesByChain.get(chainId)?.get(id);
+  async getChairmanMerkleNode(chainId, id) {
+    return this.chairmanMerkleNodesByChain.get(chainId)?.get(id);
   }
   /**
-   * Upsert merkle nodes for a chain.
+   * Put chairmanMerkle tree nodes for a chain.
    */
-  async upsertMerkleNodes(chainId, nodes) {
+  async putChairmanMerkleNodes(chainId, nodes) {
     if (!nodes.length) return;
-    let map = this.merkleNodesByChain.get(chainId);
+    let map = this.chairmanMerkleNodesByChain.get(chainId);
     if (!map) {
       map = /* @__PURE__ */ new Map();
-      this.merkleNodesByChain.set(chainId, map);
+      this.chairmanMerkleNodesByChain.set(chainId, map);
     }
     for (const node of nodes) {
       map.set(node.id, { ...node, chainId });
     }
   }
   /**
-   * Clear merkle nodes for a chain.
+   * Get a chairmanMerkle version record by chain and version number.
    */
-  async clearMerkleNodes(chainId) {
-    this.merkleNodesByChain.delete(chainId);
+  async getChairmanMerkleVersion(chainId, version) {
+    const byVersion = this.chairmanMerkleVersionsByChain.get(chainId);
+    const record = byVersion?.get(version);
+    return record ? { ...record } : void 0;
   }
   /**
-   * Get persisted merkle tree state.
+   * Get the latest chairmanMerkle version record (highest version number) for a chain.
    */
-  async getMerkleTree(chainId) {
-    const tree = this.merkleTreesByChain.get(chainId);
-    return tree ? { ...tree } : void 0;
+  async getLatestChairmanMerkleVersion(chainId) {
+    const byVersion = this.chairmanMerkleVersionsByChain.get(chainId);
+    if (!byVersion || byVersion.size === 0) return void 0;
+    let latest;
+    for (const record of byVersion.values()) {
+      if (!latest || record.version > latest.version) {
+        latest = record;
+      }
+    }
+    return latest ? { ...latest } : void 0;
   }
   /**
-   * Persist merkle tree state.
+   * Persist a chairmanMerkle version record.
    */
-  async setMerkleTree(chainId, tree) {
-    this.merkleTreesByChain.set(chainId, { ...tree, chainId });
+  async putChairmanMerkleVersion(chainId, record) {
+    let byVersion = this.chairmanMerkleVersionsByChain.get(chainId);
+    if (!byVersion) {
+      byVersion = /* @__PURE__ */ new Map();
+      this.chairmanMerkleVersionsByChain.set(chainId, byVersion);
+    }
+    byVersion.set(record.version, { ...record, chainId });
   }
   /**
-   * Clear merkle tree state.
+   * Clear all chairmanMerkle tree state (both nodes and versions) for a chain.
    */
-  async clearMerkleTree(chainId) {
-    this.merkleTreesByChain.delete(chainId);
+  async clearChairmanMerkleTree(chainId) {
+    this.chairmanMerkleNodesByChain.delete(chainId);
+    this.chairmanMerkleVersionsByChain.delete(chainId);
   }
   /**
    * Upsert entry memos (raw EntryService cache).
@@ -3989,13 +4004,14 @@ var KeyValueStore = class {
     this.utxoCache = /* @__PURE__ */ new Map();
     this.operationCache = /* @__PURE__ */ new Map();
     this.merkleLeafCids = {};
-    this.merkleTrees = {};
-    this.merkleNodeIds = {};
+    this.chairmanMerkleLatestVersions = {};
+    this.chairmanMerkleNodeIds = {};
+    this.chairmanMerkleVersionNums = {};
     this.entryMemoCids = {};
     this.entryNullifierNids = {};
     this.loadedMerkleLeaves = /* @__PURE__ */ new Set();
-    this.loadedMerkleTrees = /* @__PURE__ */ new Set();
-    this.loadedMerkleNodes = /* @__PURE__ */ new Set();
+    this.loadedChairmanMerkleVersions = /* @__PURE__ */ new Set();
+    this.loadedChairmanMerkleNodes = /* @__PURE__ */ new Set();
     this.loadedEntryMemos = /* @__PURE__ */ new Set();
     this.loadedEntryNullifiers = /* @__PURE__ */ new Set();
     this.saveChain = Promise.resolve();
@@ -4029,9 +4045,6 @@ var KeyValueStore = class {
   walletOperationKey(id) {
     return `${this.walletBaseKey()}:operation:${id}`;
   }
-  sharedChainKey(part, chainId) {
-    return `${this.keyPrefix()}:shared:${part}:${chainId}`;
-  }
   sharedChainMetaKey(part, chainId) {
     return `${this.keyPrefix()}:shared:${part}:${chainId}:meta`;
   }
@@ -4084,13 +4097,14 @@ var KeyValueStore = class {
     this.operationCache.clear();
     this.walletMetaLoaded = false;
     this.merkleLeafCids = {};
-    this.merkleTrees = {};
-    this.merkleNodeIds = {};
+    this.chairmanMerkleLatestVersions = {};
+    this.chairmanMerkleNodeIds = {};
+    this.chairmanMerkleVersionNums = {};
     this.entryMemoCids = {};
     this.entryNullifierNids = {};
     this.loadedMerkleLeaves.clear();
-    this.loadedMerkleTrees.clear();
-    this.loadedMerkleNodes.clear();
+    this.loadedChairmanMerkleVersions.clear();
+    this.loadedChairmanMerkleNodes.clear();
     this.loadedEntryMemos.clear();
     this.loadedEntryNullifiers.clear();
   }
@@ -4185,20 +4199,19 @@ var KeyValueStore = class {
     this.merkleLeafCids[key] = new Set(this.parseNumberIndex(cidsRaw));
     this.loadedMerkleLeaves.add(chainId);
   }
-  async ensureMerkleTreeLoaded(chainId) {
-    if (this.loadedMerkleTrees.has(chainId)) return;
+  async ensureChairmanMerkleVersionsLoaded(chainId) {
+    if (this.loadedChairmanMerkleVersions.has(chainId)) return;
     const key = String(chainId);
-    const raw = await this.options.client.get(this.sharedChainKey("merkleTrees", chainId));
-    const row = this.parseJson(raw, null);
-    if (row && typeof row === "object") this.merkleTrees[key] = row;
-    this.loadedMerkleTrees.add(chainId);
+    const numsRaw = await this.options.client.get(this.sharedChainMetaKey("chairmanMerkleVersions", chainId));
+    this.chairmanMerkleVersionNums[key] = new Set(this.parseNumberIndex(numsRaw));
+    this.loadedChairmanMerkleVersions.add(chainId);
   }
-  async ensureMerkleNodesLoaded(chainId) {
-    if (this.loadedMerkleNodes.has(chainId)) return;
+  async ensureChairmanMerkleNodesLoaded(chainId) {
+    if (this.loadedChairmanMerkleNodes.has(chainId)) return;
     const key = String(chainId);
-    const idsRaw = await this.options.client.get(this.sharedChainMetaKey("merkleNodes", chainId));
-    this.merkleNodeIds[key] = new Set(this.parseStringIndex(idsRaw));
-    this.loadedMerkleNodes.add(chainId);
+    const idsRaw = await this.options.client.get(this.sharedChainMetaKey("chairmanMerkleNodes", chainId));
+    this.chairmanMerkleNodeIds[key] = new Set(this.parseStringIndex(idsRaw));
+    this.loadedChairmanMerkleNodes.add(chainId);
   }
   async ensureEntryMemosLoaded(chainId) {
     if (this.loadedEntryMemos.has(chainId)) return;
@@ -4214,64 +4227,88 @@ var KeyValueStore = class {
     this.entryNullifierNids[key] = new Set(this.parseNumberIndex(nidsRaw));
     this.loadedEntryNullifiers.add(chainId);
   }
-  async getMerkleNode(chainId, id) {
-    await this.ensureMerkleNodesLoaded(chainId);
-    if (!this.merkleNodeIds[String(chainId)]?.has(id)) return void 0;
-    const raw = await this.options.client.get(this.sharedRecordKey("merkleNodes", chainId, id));
+  async getChairmanMerkleNode(chainId, id) {
+    await this.ensureChairmanMerkleNodesLoaded(chainId);
+    if (!this.chairmanMerkleNodeIds[String(chainId)]?.has(id)) return void 0;
+    const raw = await this.options.client.get(this.sharedRecordKey("chairmanMerkleNodes", chainId, id));
     const node = this.parseJson(raw, null);
     if (!node) return void 0;
     const hash = node.hash;
     if (typeof hash !== "string" || !hash.startsWith("0x")) return void 0;
     return { ...node, chainId };
   }
-  async upsertMerkleNodes(chainId, nodes) {
+  async putChairmanMerkleNodes(chainId, nodes) {
     if (!nodes.length) return;
-    await this.ensureMerkleNodesLoaded(chainId);
+    await this.ensureChairmanMerkleNodesLoaded(chainId);
     const key = String(chainId);
-    const ids = this.merkleNodeIds[key] ?? /* @__PURE__ */ new Set();
+    const ids = this.chairmanMerkleNodeIds[key] ?? /* @__PURE__ */ new Set();
     const beforeSize = ids.size;
     for (const node of nodes) {
       ids.add(node.id);
     }
-    this.merkleNodeIds[key] = ids;
+    this.chairmanMerkleNodeIds[key] = ids;
     await this.enqueueWrite(async () => {
-      await Promise.all(nodes.map((node) => this.writeJson(this.sharedRecordKey("merkleNodes", chainId, node.id), { ...node, chainId })));
+      await Promise.all(nodes.map((node) => this.writeJson(this.sharedRecordKey("chairmanMerkleNodes", chainId, node.id), { ...node, chainId })));
       if (ids.size !== beforeSize) {
-        await this.writeJson(this.sharedChainMetaKey("merkleNodes", chainId), Array.from(ids));
+        await this.writeJson(this.sharedChainMetaKey("chairmanMerkleNodes", chainId), Array.from(ids));
       }
     });
   }
-  async clearMerkleNodes(chainId) {
-    await this.ensureMerkleNodesLoaded(chainId);
-    const ids = Array.from(this.merkleNodeIds[String(chainId)] ?? []);
-    delete this.merkleNodeIds[String(chainId)];
+  async getChairmanMerkleVersion(chainId, version) {
+    await this.ensureChairmanMerkleVersionsLoaded(chainId);
+    if (!this.chairmanMerkleVersionNums[String(chainId)]?.has(version)) return void 0;
+    const raw = await this.options.client.get(this.sharedRecordKey("chairmanMerkleVersions", chainId, version));
+    const record = this.parseJson(raw, null);
+    if (!record) return void 0;
+    if (typeof record.rootHash !== "string" || !record.rootHash.startsWith("0x")) return void 0;
+    if (typeof record.rootId !== "string") return void 0;
+    const v = Number(record.version);
+    if (!Number.isFinite(v) || v < 0) return void 0;
+    return { chainId, version: Math.floor(v), rootId: record.rootId, rootHash: record.rootHash };
+  }
+  async getLatestChairmanMerkleVersion(chainId) {
+    await this.ensureChairmanMerkleVersionsLoaded(chainId);
+    const nums = this.chairmanMerkleVersionNums[String(chainId)];
+    if (!nums || nums.size === 0) return void 0;
+    const maxVersion = Math.max(...nums);
+    return this.getChairmanMerkleVersion(chainId, maxVersion);
+  }
+  async putChairmanMerkleVersion(chainId, record) {
+    await this.ensureChairmanMerkleVersionsLoaded(chainId);
+    const key = String(chainId);
+    const nums = this.chairmanMerkleVersionNums[key] ?? /* @__PURE__ */ new Set();
+    const beforeSize = nums.size;
+    nums.add(record.version);
+    this.chairmanMerkleVersionNums[key] = nums;
+    const current = this.chairmanMerkleLatestVersions[key];
+    if (!current || record.version >= current.version) {
+      this.chairmanMerkleLatestVersions[key] = { ...record, chainId };
+    }
+    const row = { ...record, chainId };
     await this.enqueueWrite(async () => {
-      await Promise.all(ids.map((id) => this.deleteOrReset(this.sharedRecordKey("merkleNodes", chainId, id), null)));
-      await this.deleteOrReset(this.sharedChainMetaKey("merkleNodes", chainId), []);
+      await this.writeJson(this.sharedRecordKey("chairmanMerkleVersions", chainId, record.version), row);
+      if (nums.size !== beforeSize) {
+        await this.writeJson(this.sharedChainMetaKey("chairmanMerkleVersions", chainId), Array.from(nums).sort((a, b) => a - b));
+      }
     });
   }
-  async getMerkleTree(chainId) {
-    await this.ensureMerkleTreeLoaded(chainId);
-    const row = this.merkleTrees[String(chainId)];
-    if (!row) return void 0;
-    const totalElements = Number(row.totalElements);
-    const lastUpdated = Number(row.lastUpdated);
-    const root = row.root;
-    if (typeof root !== "string" || !root.startsWith("0x")) return void 0;
-    if (!Number.isFinite(totalElements) || totalElements < 0) return void 0;
-    return { chainId, root, totalElements: Math.floor(totalElements), lastUpdated: Number.isFinite(lastUpdated) ? Math.floor(lastUpdated) : 0 };
-  }
-  async setMerkleTree(chainId, tree) {
-    await this.ensureMerkleTreeLoaded(chainId);
-    const row = { ...tree, chainId };
-    this.merkleTrees[String(chainId)] = row;
-    await this.enqueueWrite(() => this.writeJson(this.sharedChainKey("merkleTrees", chainId), row));
-  }
-  async clearMerkleTree(chainId) {
-    await this.ensureMerkleTreeLoaded(chainId);
-    delete this.merkleTrees[String(chainId)];
+  async clearChairmanMerkleTree(chainId) {
+    await this.ensureChairmanMerkleNodesLoaded(chainId);
+    await this.ensureChairmanMerkleVersionsLoaded(chainId);
+    const nodeIds = Array.from(this.chairmanMerkleNodeIds[String(chainId)] ?? []);
+    const versionNums = Array.from(this.chairmanMerkleVersionNums[String(chainId)] ?? []);
+    delete this.chairmanMerkleNodeIds[String(chainId)];
+    delete this.chairmanMerkleVersionNums[String(chainId)];
+    delete this.chairmanMerkleLatestVersions[String(chainId)];
     await this.enqueueWrite(async () => {
-      await this.deleteOrReset(this.sharedChainKey("merkleTrees", chainId), null);
+      await Promise.all([
+        ...nodeIds.map((id) => this.deleteOrReset(this.sharedRecordKey("chairmanMerkleNodes", chainId, id), null)),
+        ...versionNums.map((v) => this.deleteOrReset(this.sharedRecordKey("chairmanMerkleVersions", chainId, v), null))
+      ]);
+      await Promise.all([
+        this.deleteOrReset(this.sharedChainMetaKey("chairmanMerkleNodes", chainId), []),
+        this.deleteOrReset(this.sharedChainMetaKey("chairmanMerkleVersions", chainId), [])
+      ]);
     });
   }
   async upsertEntryMemos(memos) {
@@ -7115,6 +7152,7 @@ var MerkleEngine = class _MerkleEngine {
     this.hydrateInFlight = /* @__PURE__ */ new Map();
     this.mode = options?.mode ?? "hybrid";
     this.treeDepth = Math.max(1, Math.floor(options?.treeDepth ?? TREE_DEPTH_DEFAULT));
+    this.readContractRoot = options?.readContractRoot;
   }
   /**
    * Compute the current merkle root index from total elements.
@@ -7123,9 +7161,6 @@ var MerkleEngine = class _MerkleEngine {
     if (totalElements <= tempArraySize) return 0;
     return Math.floor((totalElements - 1) / tempArraySize);
   }
-  /**
-   * Get or initialize the pending leaf buffer for a chain.
-   */
   ensurePendingLeaves(chainId) {
     let pending = this.pendingLeavesByChain.get(chainId);
     if (!pending) {
@@ -7134,9 +7169,6 @@ var MerkleEngine = class _MerkleEngine {
     }
     return pending;
   }
-  /**
-   * Get or initialize chain-level merkle state.
-   */
   ensureChainState(chainId) {
     let state = this.chainStateByChain.get(chainId);
     if (!state) {
@@ -7145,15 +7177,32 @@ var MerkleEngine = class _MerkleEngine {
     }
     return state;
   }
-  /**
-   * Poseidon2 merkle hash for a left/right pair.
-   */
+  // ── Hashing ──
   static hashPair(left, right) {
     return Poseidon2.hashToHex(BigInt(left), BigInt(right), Poseidon2Domain.Merkle);
   }
+  static normalizeHex32(value, name) {
+    try {
+      const bi = BigInt(value);
+      if (bi < 0n) throw new Error("negative");
+      const hex = bi.toString(16).padStart(64, "0");
+      if (hex.length > 64) throw new Error("too_large");
+      return `0x${hex}`;
+    } catch (error) {
+      throw new SdkError("MERKLE", `Invalid ${name}`, { value }, error);
+    }
+  }
+  // ── Static helpers ──
+  static totalElementsInTree(totalElements, tempArraySize = TEMP_ARRAY_SIZE_DEFAULT) {
+    if (tempArraySize <= 0) throw new SdkError("MERKLE", "tempArraySize must be greater than zero", { tempArraySize });
+    if (totalElements <= 0n) return 0;
+    const size = BigInt(tempArraySize);
+    return Number((totalElements - 1n) / size * size);
+  }
+  // ── Subtree (levels 0-5, 32 leaves → 1 root) ──
   /**
    * Build a fixed-depth subtree from 32 contiguous leaves.
-   * Returns the subtree root and all intermediate nodes for storage.
+   * Returns the subtree root hash and all intermediate nodes for storage.
    */
   static buildSubtree(leafCommitments, baseIndex) {
     if (leafCommitments.length !== SUBTREE_SIZE) {
@@ -7174,71 +7223,71 @@ var MerkleEngine = class _MerkleEngine {
         const position = basePos + i;
         nodesToStore.push({
           chainId: 0,
-          id: `${level}-${position}`,
-          level,
-          position,
-          hash: next[i]
+          id: `st-${level}-${position}`,
+          hash: next[i],
+          leftId: null,
+          rightId: null
         });
       }
       currentLevel = next;
     }
     return { subtreeRoot: currentLevel[0], nodesToStore };
   }
+  // ── ChairmanMerkle tree (persistent segment tree, levels 5-32) ──
   /**
-   * Fetch a node hash from storage if available.
-   */
-  async getNodeHash(chainId, id) {
-    const node = await this.storage?.getMerkleNode?.(chainId, id);
-    return node?.hash;
-  }
-  /**
-   * Merge a completed subtree root into the main tree, updating frontier nodes.
-   */
-  async mergeSubtreeToMainTree(input) {
-    let currentValue = input.subtreeRoot;
-    let frontierUpdated = false;
-    const nodesToStore = [];
-    for (let level = SUBTREE_DEPTH; level < this.treeDepth; level++) {
-      const nodeIndex = input.newTotalElements - 1 >> level;
-      if ((nodeIndex & 1) === 0) {
-        if (!frontierUpdated) {
-          nodesToStore.push({
-            chainId: input.chainId,
-            id: `frontier-${level}`,
-            level,
-            position: nodeIndex,
-            hash: currentValue
-          });
-          frontierUpdated = true;
+   * Insert a subtree root into the persistent main tree.
+   *
+   * Top-down recursive: descends from root (level treeDepth) to the target
+   * leaf position (level SUBTREE_DEPTH).  At each level only the node on the
+   * update path is newly created; the sibling is shared from the previous
+   * version's tree.
+   *
+   * @returns new root node ID/hash and all newly created nodes.
+   */
+  async insertSubtreeRoot(chainId, prevRootId, subtreeRootHash, batchIndex, version) {
+    const MAIN_DEPTH = this.treeDepth - SUBTREE_DEPTH;
+    const nodes = [];
+    const descend = async (nodeId, depth) => {
+      const originalLevel = this.treeDepth - depth;
+      if (depth === MAIN_DEPTH) {
+        const newId2 = `cm-${version}-${originalLevel}`;
+        nodes.push({ chainId, id: newId2, hash: subtreeRootHash, leftId: null, rightId: null });
+        return { id: newId2, hash: subtreeRootHash };
+      }
+      let prevLeftId = null;
+      let prevRightId = null;
+      if (nodeId) {
+        const prevNode = await this.storage?.getChairmanMerkleNode?.(chainId, nodeId);
+        if (prevNode) {
+          prevLeftId = prevNode.leftId;
+          prevRightId = prevNode.rightId;
         }
-        currentValue = _MerkleEngine.hashPair(currentValue, getZeroHash(level));
-      } else {
-        const leftHash = await this.getNodeHash(input.chainId, `frontier-${level}`) ?? getZeroHash(level);
-        currentValue = _MerkleEngine.hashPair(leftHash, currentValue);
       }
-      const nextLevel = level + 1;
-      nodesToStore.push({
-        chainId: input.chainId,
-        id: `${nextLevel}-${nodeIndex >> 1}`,
-        level: nextLevel,
-        position: nodeIndex >> 1,
-        hash: currentValue
-      });
-    }
-    return { finalRoot: currentValue, nodesToStore };
-  }
-  /**
-   * Convert on-chain totalElements to the count of fully merged elements.
-   */
-  static totalElementsInTree(totalElements, tempArraySize = TEMP_ARRAY_SIZE_DEFAULT) {
-    if (tempArraySize <= 0) throw new SdkError("MERKLE", "tempArraySize must be greater than zero", { tempArraySize });
-    if (totalElements <= 0n) return 0;
-    const size = BigInt(tempArraySize);
-    return Number((totalElements - 1n) / size * size);
+      const childLevel = originalLevel - 1;
+      const remainingDepth = MAIN_DEPTH - depth - 1;
+      const goRight = (batchIndex >> remainingDepth & 1) === 1;
+      let leftResult;
+      let rightResult;
+      if (goRight) {
+        const leftHash = prevLeftId ? (await this.storage?.getChairmanMerkleNode?.(chainId, prevLeftId))?.hash ?? getZeroHash(childLevel) : getZeroHash(childLevel);
+        leftResult = { id: prevLeftId, hash: leftHash };
+        const right = await descend(prevRightId, depth + 1);
+        rightResult = { id: right.id, hash: right.hash };
+      } else {
+        const left = await descend(prevLeftId, depth + 1);
+        leftResult = { id: left.id, hash: left.hash };
+        const rightHash = prevRightId ? (await this.storage?.getChairmanMerkleNode?.(chainId, prevRightId))?.hash ?? getZeroHash(childLevel) : getZeroHash(childLevel);
+        rightResult = { id: prevRightId, hash: rightHash };
+      }
+      const hash = _MerkleEngine.hashPair(leftResult.hash, rightResult.hash);
+      const newId = `cm-${version}-${originalLevel}`;
+      nodes.push({ chainId, id: newId, hash, leftId: leftResult.id, rightId: rightResult.id });
+      return { id: newId, hash };
+    };
+    const root = await descend(prevRootId, 0);
+    return { rootId: root.id, rootHash: root.hash, nodes };
   }
-  /**
-   * Hydrate local merkle state from storage on first use.
-   */
+  // ── Hydration ──
   async hydrateFromStorage(chainId) {
     if (this.mode === "remote") return;
     if (this.hydratedChains.has(chainId)) return;
@@ -7247,31 +7296,17 @@ var MerkleEngine = class _MerkleEngine {
     const task = (async () => {
       try {
         const state = this.ensureChainState(chainId);
-        const leaves = await this.storage?.getMerkleLeaves?.(chainId);
-        if (!leaves || leaves.length === 0) return;
-        const sorted = [...leaves].map((l) => ({
-          cid: l.cid,
-          commitment: _MerkleEngine.normalizeHex32(l.commitment, "memo.commitment")
-        })).sort((a, b) => a.cid - b.cid);
-        for (let i = 0; i < sorted.length; i++) {
-          if (sorted[i].cid !== i) throw new Error(`Non-contiguous persisted merkle leaves: expected cid=${i}, got cid=${sorted[i].cid}`);
-        }
-        const storedTree = await this.storage?.getMerkleTree?.(chainId);
-        const leafCount = sorted.length;
-        const mergedFromLeaves = _MerkleEngine.totalElementsInTree(BigInt(leafCount));
-        const mergedFromTree = typeof storedTree?.totalElements === "number" && storedTree.totalElements > 0 ? storedTree.totalElements : 0;
-        const mergedElements = Math.max(mergedFromLeaves, mergedFromTree);
         const pending = this.ensurePendingLeaves(chainId);
-        pending.length = 0;
-        state.mergedElements = mergedElements;
-        if (leafCount > mergedElements) {
-          pending.push(...sorted.slice(mergedElements).map((l) => l.commitment));
+        const latest = await this.storage?.getLatestChairmanMerkleVersion?.(chainId);
+        if (latest) {
+          state.mergedElements = latest.version;
+          state.root = _MerkleEngine.normalizeHex32(latest.rootHash, "chairmanMerkleVersion.rootHash");
         }
-        if (storedTree?.root) {
-          state.root = _MerkleEngine.normalizeHex32(storedTree.root, "merkleTree.root");
-        } else {
-          const rootNode = await this.storage?.getMerkleNode?.(chainId, `${this.treeDepth}-0`);
-          state.root = rootNode?.hash ?? getZeroHash(this.treeDepth);
+        const leaves = await this.storage?.getMerkleLeaves?.(chainId);
+        if (leaves && leaves.length > state.mergedElements) {
+          const sorted = [...leaves].sort((a, b) => a.cid - b.cid).slice(state.mergedElements);
+          pending.length = 0;
+          pending.push(...sorted.map((l) => _MerkleEngine.normalizeHex32(l.commitment, "leaf.commitment")));
         }
       } catch (error) {
         if (this.mode === "hybrid") return;
@@ -7284,26 +7319,7 @@ var MerkleEngine = class _MerkleEngine {
     this.hydrateInFlight.set(chainId, task);
     return task;
   }
-  /**
-   * Normalize unknown values to a 32-byte hex string.
-   */
-  static normalizeHex32(value, name) {
-    try {
-      const bi = BigInt(value);
-      if (bi < 0n) throw new Error("negative");
-      const hex = bi.toString(16).padStart(64, "0");
-      if (hex.length > 64) throw new Error("too_large");
-      return `0x${hex}`;
-    } catch (error) {
-      throw new SdkError("MERKLE", `Invalid ${name}`, { value }, error);
-    }
-  }
-  /**
-   * Feed contiguous (cid-ordered) memo leaves into the local merkle tree.
-   *
-   * This mirrors the client/app behavior: only after we have a full consecutive batch of 32 leaves
-   * do we merge them into the main tree. Leaves that are still in the buffer do not get local proofs.
-   */
+  // ── Ingestion ──
   async ingestEntryMemos(chainId, memos) {
     if (this.mode === "remote") return;
     await this.hydrateFromStorage(chainId);
@@ -7331,26 +7347,42 @@ var MerkleEngine = class _MerkleEngine {
         expected++;
         while (pending.length >= SUBTREE_SIZE) {
           const batch = pending.splice(0, SUBTREE_SIZE);
-          const baseIndex = state.mergedElements;
-          const subtree = _MerkleEngine.buildSubtree(batch, baseIndex);
-          const merged = await this.mergeSubtreeToMainTree({ chainId, subtreeRoot: subtree.subtreeRoot, newTotalElements: baseIndex + SUBTREE_SIZE });
-          state.mergedElements += SUBTREE_SIZE;
-          state.root = merged.finalRoot;
-          const checkpointNode = {
-            chainId,
-            id: `checkpoint-${state.mergedElements}`,
-            level: -1,
-            position: 0,
-            hash: state.root
-          };
-          const nodes = [...subtree.nodesToStore, ...merged.nodesToStore, checkpointNode].map((n) => ({ ...n, chainId }));
-          await this.storage?.upsertMerkleNodes?.(chainId, nodes);
-          await this.storage?.setMerkleTree?.(chainId, {
+          const batchIndex = state.mergedElements / SUBTREE_SIZE;
+          const subtree = _MerkleEngine.buildSubtree(batch, state.mergedElements);
+          const subtreeNodes = subtree.nodesToStore.map((n) => ({ ...n, chainId }));
+          const prevVersion = await this.storage?.getLatestChairmanMerkleVersion?.(chainId);
+          const prevRootId = prevVersion?.rootId ?? null;
+          const newVersion = state.mergedElements + SUBTREE_SIZE;
+          const result = await this.insertSubtreeRoot(chainId, prevRootId, subtree.subtreeRoot, batchIndex, newVersion);
+          if (this.readContractRoot) {
+            const rootIndex = newVersion / SUBTREE_SIZE;
+            const onChainRoot = await this.readContractRoot(chainId, rootIndex).catch(() => null);
+            if (onChainRoot !== null) {
+              const onChainNorm = _MerkleEngine.normalizeHex32(onChainRoot, "onChainRoot");
+              const isZero = BigInt(onChainNorm) === 0n;
+              if (!isZero && onChainNorm !== result.rootHash) {
+                const target = state.mergedElements;
+                await this.rollback(chainId, target);
+                throw new SdkError("MERKLE", "Local merkle root mismatch with on-chain root \u2014 rolled back", {
+                  chainId,
+                  rootIndex,
+                  localRoot: result.rootHash,
+                  onChainRoot: onChainNorm,
+                  version: newVersion,
+                  rollbackTarget: target
+                });
+              }
+            }
+          }
+          await this.storage?.putChairmanMerkleNodes?.(chainId, [...subtreeNodes, ...result.nodes]);
+          await this.storage?.putChairmanMerkleVersion?.(chainId, {
             chainId,
-            root: state.root,
-            totalElements: state.mergedElements,
-            lastUpdated: Date.now()
+            version: newVersion,
+            rootId: result.rootId,
+            rootHash: result.rootHash
           });
+          state.mergedElements = newVersion;
+          state.root = result.rootHash;
         }
       }
       this.hydratedChains.add(chainId);
@@ -7361,15 +7393,59 @@ var MerkleEngine = class _MerkleEngine {
       throw new SdkError("MERKLE", "Failed to ingest local merkle leaves", { chainId, leafCount: leaves.length }, error);
     }
   }
+  // ── Rollback (tree O(1) + sync cursor reset) ──
   /**
-   * Convenience wrapper to request a single proof.
+   * Unified rollback: rewind tree to a previous batch boundary AND reset the
+   * sync cursor so memo sync restarts from the same point.
+   *
+   * What gets rolled back:
+   * - ChairmanMerkle tree version pointer (O(1) — old nodes still in storage)
+   * - Pending leaves buffer (cleared)
+   * - Sync cursor: memo + merkle fields (nullifier left unchanged — independent)
+   *
+   * @param targetMergedElements Must be a non-negative multiple of 32.
+   *   Pass 0 to reset to the empty tree.
+   * @returns true if rollback succeeded, false if the target version doesn't exist.
    */
-  async getProofByCid(input) {
-    return this.getProofByCids({ chainId: input.chainId, cids: [input.cid], totalElements: input.totalElements });
+  async rollback(chainId, targetMergedElements) {
+    if (targetMergedElements < 0 || targetMergedElements % SUBTREE_SIZE !== 0) {
+      throw new SdkError("MERKLE", "rollback target must be a non-negative multiple of 32", { targetMergedElements });
+    }
+    const state = this.ensureChainState(chainId);
+    const pending = this.ensurePendingLeaves(chainId);
+    if (targetMergedElements === 0) {
+      state.mergedElements = 0;
+      state.root = getZeroHash(this.treeDepth);
+      pending.length = 0;
+      await this.resetSyncCursor(chainId, 0);
+      return true;
+    }
+    const version = await this.storage?.getChairmanMerkleVersion?.(chainId, targetMergedElements);
+    if (!version) return false;
+    state.mergedElements = targetMergedElements;
+    state.root = _MerkleEngine.normalizeHex32(version.rootHash, "version.rootHash");
+    pending.length = 0;
+    this.hydratedChains.add(chainId);
+    await this.resetSyncCursor(chainId, targetMergedElements);
+    return true;
   }
   /**
-   * Get merkle proofs for a set of cids using local/hybrid/remote logic.
+   * Reset the sync cursor's memo field to `targetMemo` (and derive merkle cursor),
+   * but only if the current cursor is ahead of the target.
+   * Nullifier cursor is left unchanged — nullifiers are independent of tree state.
    */
+  async resetSyncCursor(chainId, targetMemo) {
+    if (!this.storage?.getSyncCursor || !this.storage?.setSyncCursor) return;
+    const cursor = await this.storage.getSyncCursor(chainId);
+    if (!cursor || cursor.memo <= targetMemo) return;
+    cursor.memo = targetMemo;
+    cursor.merkle = this.currentMerkleRootIndex(targetMemo);
+    await this.storage.setSyncCursor(chainId, cursor);
+  }
+  // ── Proof generation ──
+  async getProofByCid(input) {
+    return this.getProofByCids({ chainId: input.chainId, cids: [input.cid], totalElements: input.totalElements });
+  }
   async getProofByCids(input) {
     const cids = [...input.cids];
     if (cids.length === 0) throw new SdkError("MERKLE", "No cids provided", { chainId: input.chainId });
@@ -7384,15 +7460,16 @@ var MerkleEngine = class _MerkleEngine {
     await this.hydrateFromStorage(input.chainId);
     const canUseLocal = this.mode !== "remote";
     if (canUseLocal) {
-      const tree = await this.storage?.getMerkleTree?.(input.chainId);
-      const hasDb = typeof this.storage?.getMerkleLeaf === "function" && typeof this.storage?.getMerkleNode === "function" && typeof tree?.totalElements === "number" && typeof tree?.root === "string";
-      if (hasDb && tree) {
-        if (tree.totalElements < contractTreeElements) {
+      const version = contractTreeElements > 0 ? await this.storage?.getChairmanMerkleVersion?.(input.chainId, contractTreeElements) : void 0;
+      const hasDb = typeof this.storage?.getMerkleLeaf === "function" && typeof this.storage?.getChairmanMerkleNode === "function" && (contractTreeElements === 0 || !!version);
+      if (hasDb) {
+        const state = this.ensureChainState(input.chainId);
+        if (contractTreeElements > 0 && state.mergedElements < contractTreeElements) {
           if (this.mode === "local") {
             throw new SdkError("MERKLE", "Local merkle db is behind contract", {
               chainId: input.chainId,
               cids,
-              localTotalElements: tree.totalElements,
+              localMergedElements: state.mergedElements,
               contractTreeElements
             });
           }
@@ -7404,30 +7481,13 @@ var MerkleEngine = class _MerkleEngine {
                 proof.push({ leaf_index: cid, path: new Array(this.treeDepth + 1).fill("0") });
                 continue;
               }
-              const leaf = await this.storage.getMerkleLeaf(input.chainId, cid);
-              if (!leaf) throw new Error(`missing_leaf:${cid}`);
-              const path = [leaf.commitment];
-              for (let level = 1; level <= this.treeDepth; level++) {
-                const siblingIndex = cid >> level - 1 ^ 1;
-                if (level === 1) {
-                  const siblingLeaf = await this.storage.getMerkleLeaf(input.chainId, siblingIndex);
-                  path.push(siblingLeaf?.commitment ?? getZeroHash(0));
-                  continue;
-                }
-                const targetLevel = level - 1;
-                const siblingNode = await this.storage.getMerkleNode(input.chainId, `${targetLevel}-${siblingIndex}`);
-                path.push(siblingNode?.hash ?? getZeroHash(targetLevel));
-              }
+              const path = await this.buildLocalProofPath(input.chainId, cid, version);
               proof.push({ leaf_index: cid, path });
             }
-            let effectiveRoot = tree.root;
-            if (tree.totalElements > contractTreeElements && contractTreeElements > 0) {
-              const checkpoint = await this.storage.getMerkleNode(input.chainId, `checkpoint-${contractTreeElements}`);
-              if (checkpoint) effectiveRoot = checkpoint.hash;
-            }
+            const effectiveRoot = contractTreeElements > 0 ? _MerkleEngine.normalizeHex32(version.rootHash, "version.rootHash") : getZeroHash(this.treeDepth);
             return {
               proof,
-              merkle_root: _MerkleEngine.normalizeHex32(effectiveRoot, "merkleTree.root"),
+              merkle_root: effectiveRoot,
               latest_cid: totalElements > 0n ? Number(totalElements - 1n) : -1
             };
           } catch (error) {
@@ -7437,7 +7497,7 @@ var MerkleEngine = class _MerkleEngine {
           }
         }
       } else if (this.mode === "local" && needsTreeProof.length) {
-        throw new SdkError("MERKLE", "Local merkle db unavailable", { chainId: input.chainId, cids, reason: "missing_adapter_merkle_db" });
+        throw new SdkError("MERKLE", "Local merkle db unavailable", { chainId: input.chainId, cids, reason: "missing_adapter_or_version" });
       }
     }
     if (needsTreeProof.length === 0) {
@@ -7462,15 +7522,64 @@ var MerkleEngine = class _MerkleEngine {
     };
   }
   /**
-   * Fetch a remote merkle root (used when no proofs are needed).
+   * Build a local proof path by traversing the chairmanMerkle tree.
+   *
+   * Levels 0-4: sibling hashes from subtree internal nodes (st-{level}-{pos}).
+   * Levels 5-31: sibling hashes from chairmanMerkle tree traversal (top-down from version root).
    */
+  async buildLocalProofPath(chainId, cid, version) {
+    const leaf = await this.storage.getMerkleLeaf(chainId, cid);
+    if (!leaf) throw new Error(`missing_leaf:${cid}`);
+    const path = [leaf.commitment];
+    for (let level = 1; level <= SUBTREE_DEPTH; level++) {
+      const siblingPos = cid >> level - 1 ^ 1;
+      if (level === 1) {
+        const siblingLeaf = await this.storage.getMerkleLeaf(chainId, siblingPos);
+        path.push(siblingLeaf?.commitment ?? getZeroHash(0));
+      } else {
+        const targetLevel = level - 1;
+        const node = await this.storage.getChairmanMerkleNode(chainId, `st-${targetLevel}-${siblingPos}`);
+        path.push(node?.hash ?? getZeroHash(targetLevel));
+      }
+    }
+    const batchIndex = cid >> SUBTREE_DEPTH;
+    const MAIN_DEPTH = this.treeDepth - SUBTREE_DEPTH;
+    const mainSiblings = [];
+    let nodeId = version.rootId;
+    for (let depth = 0; depth < MAIN_DEPTH; depth++) {
+      const childLevel = this.treeDepth - depth - 1;
+      if (!nodeId) {
+        mainSiblings.push(getZeroHash(childLevel));
+        continue;
+      }
+      const node = await this.storage.getChairmanMerkleNode(chainId, nodeId);
+      if (!node) {
+        mainSiblings.push(getZeroHash(childLevel));
+        nodeId = null;
+        continue;
+      }
+      const remainingDepth = MAIN_DEPTH - depth - 1;
+      const goRight = (batchIndex >> remainingDepth & 1) === 1;
+      if (goRight) {
+        const leftNode = node.leftId ? await this.storage.getChairmanMerkleNode(chainId, node.leftId) : null;
+        mainSiblings.push(leftNode?.hash ?? getZeroHash(childLevel));
+        nodeId = node.rightId;
+      } else {
+        const rightNode = node.rightId ? await this.storage.getChairmanMerkleNode(chainId, node.rightId) : null;
+        mainSiblings.push(rightNode?.hash ?? getZeroHash(childLevel));
+        nodeId = node.leftId;
+      }
+    }
+    for (let i = mainSiblings.length - 1; i >= 0; i--) {
+      path.push(mainSiblings[i]);
+    }
+    return path;
+  }
+  // ── Remote helpers ──
   async fetchRemoteRootOnly(chainId) {
     const remote = await this.fetchRemoteProofFromService({ chainId, cids: [0] });
     return _MerkleEngine.normalizeHex32(remote.merkle_root, "remote.merkle_root");
   }
-  /**
-   * Fetch proofs from the remote merkle service.
-   */
   async fetchRemoteProofFromService(input) {
     const chain = this.getChain(input.chainId);
     if (!chain.merkleProofUrl) {
@@ -7479,9 +7588,7 @@ var MerkleEngine = class _MerkleEngine {
     const client = new MerkleClient(chain.merkleProofUrl);
     return client.getProofByCids(input.cids);
   }
-  /**
-   * Build membership witnesses for provided UTXOs from a remote proof response.
-   */
+  // ── Witness builders (unchanged) ──
   buildAccMemberWitnesses(input) {
     return input.utxos.map((utxo, idx) => {
       const remoteProof = input.remote.proof[idx];
@@ -7495,9 +7602,6 @@ var MerkleEngine = class _MerkleEngine {
       };
     });
   }
-  /**
-   * Convert UTXOs into circuit input secrets, decrypting memos and padding if needed.
-   */
   async buildInputSecretsFromUtxos(input) {
     if (!Array.isArray(input.utxos) || input.utxos.length === 0) {
       throw new SdkError("MERKLE", "No utxos provided", { count: 0 });