@totemsdk/omnia-vtxo 0.2.0 → 0.3.0

package/dist/anchor.d.ts

@@ -0,0 +1,87 @@
+/**
+ * VTXO batch on-chain anchoring (RFC-038 V1).
+ *
+ * Builds a batch-anchor transaction that (re)commits an epoch's Merkle root into
+ * the pool's on-chain state output, signs the tx digest, and — when a chain
+ * provider is supplied — mines and broadcasts the assembled TxPoW. The signing
+ * and mining are injected so the construction is testable without key material or
+ * real PoW.
+ */
+import { type OmniaTxDraft, type StateValue } from '@totemsdk/omnia';
+import type { ChainStateProvider } from '@totemsdk/chain-provider';
+export interface BatchAnchorParams {
+    operatorPublicKeyDigest: string;
+    /** The epoch's Merkle root (32-byte hex). */
+    root: string;
+    epoch: number;
+    /** The pool's current on-chain coin (input). */
+    fundingCoinId: string;
+    fundingAddress: string;
+    fundingScript: string;
+    /** Raw on-chain amount (token base units). */
+    amount: bigint;
+    tokenId: string;
+}
+/** State variables carried by the pool output: STATE(100)=root, STATE(101)=epoch. */
+export declare function poolStateVariables(root: string, epoch: number): StateValue[];
+/** Build the batch-anchor draft (input = pool coin, output = pool state output). */
+export declare function buildBatchAnchorDraft(params: BatchAnchorParams): OmniaTxDraft;
+export declare function batchAnchorDigest(draft: OmniaTxDraft): Uint8Array;
+interface MinedTxPow {
+    minedHeaderBytes: Uint8Array;
+    txpowId: Uint8Array;
+}
+export interface BatchAnchorDeps {
+    /** Sign the batch-anchor tx digest (e.g. via a leased WOTS signer). */
+    signDigest: (digest: Uint8Array) => Promise<Uint8Array>;
+    chainProvider?: ChainStateProvider;
+    /** PoW miner (defaults to `@totemsdk/txpow`'s mineTxPoW). */
+    mine?: (txBody: Uint8Array, difficulty: Uint8Array) => Promise<MinedTxPow>;
+}
+export interface BatchAnchorResult {
+    root: string;
+    epoch: number;
+    digest: string;
+    witnessHex: string;
+    txpowId?: string;
+}
+/** Sign (and, when a chain provider is given, mine + broadcast) a batch anchor. */
+export declare function anchorBatch(params: BatchAnchorParams, deps: BatchAnchorDeps): Promise<BatchAnchorResult>;
+export interface PoolFundingExpectation {
+    address: string;
+    /** Raw base-unit amount, decimal string. */
+    amount: string;
+    tokenId: string;
+}
+export interface PoolFundingCheck {
+    ok: boolean;
+    coinId: string;
+    coin?: {
+        address: string;
+        amount: string;
+        tokenId: string;
+        spent: boolean;
+    };
+    /** The fetched MMR proof (present when `ok` and the node served one). */
+    proof?: unknown;
+    /**
+     * Whether the MMR proof was cryptographically verified. `false` unless a
+     * `verifyProof` callback was supplied — this function checks existence,
+     * address/amount/token match, and unspent status, but does NOT itself verify the
+     * proof against the tip. Pass `verifyProof` to verify it (RFC-038 §3.3 open).
+     */
+    proofVerified: boolean;
+    error?: string;
+}
+/**
+ * Check that the pool's on-chain coin exists, matches the expected
+ * (address, amount, token), is unspent, and that the node serves an MMR proof.
+ *
+ * NOTE: this is a **presence/shape check**, not a cryptographic proof
+ * verification, unless a `verifyProof` callback is supplied — see
+ * `PoolFundingCheck.proofVerified`.
+ */
+export declare function checkPoolFunding(coinId: string, expected: PoolFundingExpectation, chainProvider: ChainStateProvider, options?: {
+    verifyProof?: (proof: unknown, coinId: string) => boolean;
+}): Promise<PoolFundingCheck>;
+export {};

package/dist/anchor.js

@@ -0,0 +1,107 @@
+/**
+ * VTXO batch on-chain anchoring (RFC-038 V1).
+ *
+ * Builds a batch-anchor transaction that (re)commits an epoch's Merkle root into
+ * the pool's on-chain state output, signs the tx digest, and — when a chain
+ * provider is supplied — mines and broadcasts the assembled TxPoW. The signing
+ * and mining are injected so the construction is testable without key material or
+ * real PoW.
+ */
+import { computeOmniaTxDigest, omniaDraftToMinimaBytes, } from '@totemsdk/omnia';
+import { serializeTxBody, mineTxPoW, TX_POW_MIN_DIFFICULTY } from '@totemsdk/txpow';
+import { concatBytes } from '@totemsdk/core';
+import { buildAndHashPoolScript } from './pool-script.js';
+/** State variables carried by the pool output: STATE(100)=root, STATE(101)=epoch. */
+export function poolStateVariables(root, epoch) {
+    return [
+        { port: 100, value: root, type: 'string' },
+        { port: 101, value: BigInt(epoch), type: 'number' },
+    ];
+}
+/** Build the batch-anchor draft (input = pool coin, output = pool state output). */
+export function buildBatchAnchorDraft(params) {
+    const { script, address } = buildAndHashPoolScript(params.operatorPublicKeyDigest);
+    // The input must be the operator's own pool output, not a foreign script.
+    if (params.fundingScript !== script) {
+        throw new Error('anchorBatch: fundingScript does not match the operator pool script');
+    }
+    if (params.fundingAddress !== address) {
+        throw new Error('anchorBatch: fundingAddress does not match the operator pool address');
+    }
+    const stateVariables = poolStateVariables(params.root, params.epoch);
+    return {
+        type: 'settlement',
+        inputs: [{
+                coinId: params.fundingCoinId,
+                address: params.fundingAddress,
+                amount: params.amount,
+                tokenId: params.tokenId,
+                scriptHex: params.fundingScript,
+            }],
+        outputs: [{
+                address,
+                amount: params.amount,
+                tokenId: params.tokenId,
+                storeState: true,
+                stateVariables,
+            }],
+        storeState: true,
+        stateVariables,
+    };
+}
+export function batchAnchorDigest(draft) {
+    return computeOmniaTxDigest(draft);
+}
+/** Sign (and, when a chain provider is given, mine + broadcast) a batch anchor. */
+export async function anchorBatch(params, deps) {
+    const draft = buildBatchAnchorDraft(params);
+    const digest = batchAnchorDigest(draft);
+    const signature = await deps.signDigest(digest);
+    const result = {
+        root: params.root,
+        epoch: params.epoch,
+        digest: Buffer.from(digest).toString('hex'),
+        witnessHex: Buffer.from(signature).toString('hex'),
+    };
+    if (deps.chainProvider) {
+        const mine = deps.mine ?? ((txBody, difficulty) => mineTxPoW(txBody, difficulty));
+        const draftBytes = omniaDraftToMinimaBytes(draft);
+        const txBody = serializeTxBody(draftBytes, signature);
+        const mined = await mine(txBody, TX_POW_MIN_DIFFICULTY);
+        const fullTxPoW = concatBytes(concatBytes(mined.minedHeaderBytes, new Uint8Array([0x01])), txBody);
+        await deps.chainProvider.broadcastTxPoW(Buffer.from(fullTxPoW).toString('hex'));
+        result.txpowId = Buffer.from(mined.txpowId).toString('hex');
+    }
+    return result;
+}
+/**
+ * Check that the pool's on-chain coin exists, matches the expected
+ * (address, amount, token), is unspent, and that the node serves an MMR proof.
+ *
+ * NOTE: this is a **presence/shape check**, not a cryptographic proof
+ * verification, unless a `verifyProof` callback is supplied — see
+ * `PoolFundingCheck.proofVerified`.
+ */
+export async function checkPoolFunding(coinId, expected, chainProvider, options = {}) {
+    const coin = await chainProvider.getCoin(coinId);
+    if (!coin)
+        return { ok: false, coinId, proofVerified: false, error: 'pool coin not found' };
+    if (coin.spent)
+        return { ok: false, coinId, proofVerified: false, error: 'pool coin is already spent' };
+    const matches = coin.address === expected.address &&
+        String(coin.amount) === expected.amount &&
+        (coin.tokenid ?? '0x00') === expected.tokenId;
+    if (!matches)
+        return { ok: false, coinId, proofVerified: false, error: 'pool coin does not match expected address/amount/token' };
+    const proof = await chainProvider.getProof(coinId).catch(() => null);
+    if (!proof)
+        return { ok: false, coinId, proofVerified: false, error: 'no MMR proof for pool coin' };
+    const proofVerified = options.verifyProof ? options.verifyProof(proof, coinId) : false;
+    return {
+        ok: true,
+        coinId,
+        coin: { address: coin.address, amount: String(coin.amount), tokenId: coin.tokenid, spent: Boolean(coin.spent) },
+        proof,
+        proofVerified,
+    };
+}

package/dist/cjs/anchor.d.ts

@@ -0,0 +1,87 @@
+/**
+ * VTXO batch on-chain anchoring (RFC-038 V1).
+ *
+ * Builds a batch-anchor transaction that (re)commits an epoch's Merkle root into
+ * the pool's on-chain state output, signs the tx digest, and — when a chain
+ * provider is supplied — mines and broadcasts the assembled TxPoW. The signing
+ * and mining are injected so the construction is testable without key material or
+ * real PoW.
+ */
+import { type OmniaTxDraft, type StateValue } from '@totemsdk/omnia';
+import type { ChainStateProvider } from '@totemsdk/chain-provider';
+export interface BatchAnchorParams {
+    operatorPublicKeyDigest: string;
+    /** The epoch's Merkle root (32-byte hex). */
+    root: string;
+    epoch: number;
+    /** The pool's current on-chain coin (input). */
+    fundingCoinId: string;
+    fundingAddress: string;
+    fundingScript: string;
+    /** Raw on-chain amount (token base units). */
+    amount: bigint;
+    tokenId: string;
+}
+/** State variables carried by the pool output: STATE(100)=root, STATE(101)=epoch. */
+export declare function poolStateVariables(root: string, epoch: number): StateValue[];
+/** Build the batch-anchor draft (input = pool coin, output = pool state output). */
+export declare function buildBatchAnchorDraft(params: BatchAnchorParams): OmniaTxDraft;
+export declare function batchAnchorDigest(draft: OmniaTxDraft): Uint8Array;
+interface MinedTxPow {
+    minedHeaderBytes: Uint8Array;
+    txpowId: Uint8Array;
+}
+export interface BatchAnchorDeps {
+    /** Sign the batch-anchor tx digest (e.g. via a leased WOTS signer). */
+    signDigest: (digest: Uint8Array) => Promise<Uint8Array>;
+    chainProvider?: ChainStateProvider;
+    /** PoW miner (defaults to `@totemsdk/txpow`'s mineTxPoW). */
+    mine?: (txBody: Uint8Array, difficulty: Uint8Array) => Promise<MinedTxPow>;
+}
+export interface BatchAnchorResult {
+    root: string;
+    epoch: number;
+    digest: string;
+    witnessHex: string;
+    txpowId?: string;
+}
+/** Sign (and, when a chain provider is given, mine + broadcast) a batch anchor. */
+export declare function anchorBatch(params: BatchAnchorParams, deps: BatchAnchorDeps): Promise<BatchAnchorResult>;
+export interface PoolFundingExpectation {
+    address: string;
+    /** Raw base-unit amount, decimal string. */
+    amount: string;
+    tokenId: string;
+}
+export interface PoolFundingCheck {
+    ok: boolean;
+    coinId: string;
+    coin?: {
+        address: string;
+        amount: string;
+        tokenId: string;
+        spent: boolean;
+    };
+    /** The fetched MMR proof (present when `ok` and the node served one). */
+    proof?: unknown;
+    /**
+     * Whether the MMR proof was cryptographically verified. `false` unless a
+     * `verifyProof` callback was supplied — this function checks existence,
+     * address/amount/token match, and unspent status, but does NOT itself verify the
+     * proof against the tip. Pass `verifyProof` to verify it (RFC-038 §3.3 open).
+     */
+    proofVerified: boolean;
+    error?: string;
+}
+/**
+ * Check that the pool's on-chain coin exists, matches the expected
+ * (address, amount, token), is unspent, and that the node serves an MMR proof.
+ *
+ * NOTE: this is a **presence/shape check**, not a cryptographic proof
+ * verification, unless a `verifyProof` callback is supplied — see
+ * `PoolFundingCheck.proofVerified`.
+ */
+export declare function checkPoolFunding(coinId: string, expected: PoolFundingExpectation, chainProvider: ChainStateProvider, options?: {
+    verifyProof?: (proof: unknown, coinId: string) => boolean;
+}): Promise<PoolFundingCheck>;
+export {};

package/dist/cjs/anchor.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * VTXO batch on-chain anchoring (RFC-038 V1).
+ *
+ * Builds a batch-anchor transaction that (re)commits an epoch's Merkle root into
+ * the pool's on-chain state output, signs the tx digest, and — when a chain
+ * provider is supplied — mines and broadcasts the assembled TxPoW. The signing
+ * and mining are injected so the construction is testable without key material or
+ * real PoW.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.poolStateVariables = poolStateVariables;
+exports.buildBatchAnchorDraft = buildBatchAnchorDraft;
+exports.batchAnchorDigest = batchAnchorDigest;
+exports.anchorBatch = anchorBatch;
+exports.checkPoolFunding = checkPoolFunding;
+const omnia_1 = require("@totemsdk/omnia");
+const txpow_1 = require("@totemsdk/txpow");
+const core_1 = require("@totemsdk/core");
+const pool_script_js_1 = require("./pool-script.js");
+/** State variables carried by the pool output: STATE(100)=root, STATE(101)=epoch. */
+function poolStateVariables(root, epoch) {
+    return [
+        { port: 100, value: root, type: 'string' },
+        { port: 101, value: BigInt(epoch), type: 'number' },
+    ];
+}
+/** Build the batch-anchor draft (input = pool coin, output = pool state output). */
+function buildBatchAnchorDraft(params) {
+    const { script, address } = (0, pool_script_js_1.buildAndHashPoolScript)(params.operatorPublicKeyDigest);
+    // The input must be the operator's own pool output, not a foreign script.
+    if (params.fundingScript !== script) {
+        throw new Error('anchorBatch: fundingScript does not match the operator pool script');
+    }
+    if (params.fundingAddress !== address) {
+        throw new Error('anchorBatch: fundingAddress does not match the operator pool address');
+    }
+    const stateVariables = poolStateVariables(params.root, params.epoch);
+    return {
+        type: 'settlement',
+        inputs: [{
+                coinId: params.fundingCoinId,
+                address: params.fundingAddress,
+                amount: params.amount,
+                tokenId: params.tokenId,
+                scriptHex: params.fundingScript,
+            }],
+        outputs: [{
+                address,
+                amount: params.amount,
+                tokenId: params.tokenId,
+                storeState: true,
+                stateVariables,
+            }],
+        storeState: true,
+        stateVariables,
+    };
+}
+function batchAnchorDigest(draft) {
+    return (0, omnia_1.computeOmniaTxDigest)(draft);
+}
+/** Sign (and, when a chain provider is given, mine + broadcast) a batch anchor. */
+async function anchorBatch(params, deps) {
+    const draft = buildBatchAnchorDraft(params);
+    const digest = batchAnchorDigest(draft);
+    const signature = await deps.signDigest(digest);
+    const result = {
+        root: params.root,
+        epoch: params.epoch,
+        digest: Buffer.from(digest).toString('hex'),
+        witnessHex: Buffer.from(signature).toString('hex'),
+    };
+    if (deps.chainProvider) {
+        const mine = deps.mine ?? ((txBody, difficulty) => (0, txpow_1.mineTxPoW)(txBody, difficulty));
+        const draftBytes = (0, omnia_1.omniaDraftToMinimaBytes)(draft);
+        const txBody = (0, txpow_1.serializeTxBody)(draftBytes, signature);
+        const mined = await mine(txBody, txpow_1.TX_POW_MIN_DIFFICULTY);
+        const fullTxPoW = (0, core_1.concatBytes)((0, core_1.concatBytes)(mined.minedHeaderBytes, new Uint8Array([0x01])), txBody);
+        await deps.chainProvider.broadcastTxPoW(Buffer.from(fullTxPoW).toString('hex'));
+        result.txpowId = Buffer.from(mined.txpowId).toString('hex');
+    }
+    return result;
+}
+/**
+ * Check that the pool's on-chain coin exists, matches the expected
+ * (address, amount, token), is unspent, and that the node serves an MMR proof.
+ *
+ * NOTE: this is a **presence/shape check**, not a cryptographic proof
+ * verification, unless a `verifyProof` callback is supplied — see
+ * `PoolFundingCheck.proofVerified`.
+ */
+async function checkPoolFunding(coinId, expected, chainProvider, options = {}) {
+    const coin = await chainProvider.getCoin(coinId);
+    if (!coin)
+        return { ok: false, coinId, proofVerified: false, error: 'pool coin not found' };
+    if (coin.spent)
+        return { ok: false, coinId, proofVerified: false, error: 'pool coin is already spent' };
+    const matches = coin.address === expected.address &&
+        String(coin.amount) === expected.amount &&
+        (coin.tokenid ?? '0x00') === expected.tokenId;
+    if (!matches)
+        return { ok: false, coinId, proofVerified: false, error: 'pool coin does not match expected address/amount/token' };
+    const proof = await chainProvider.getProof(coinId).catch(() => null);
+    if (!proof)
+        return { ok: false, coinId, proofVerified: false, error: 'no MMR proof for pool coin' };
+    const proofVerified = options.verifyProof ? options.verifyProof(proof, coinId) : false;
+    return {
+        ok: true,
+        coinId,
+        coin: { address: coin.address, amount: String(coin.amount), tokenId: coin.tokenid, spent: Boolean(coin.spent) },
+        proof,
+        proofVerified,
+    };
+}

package/dist/cjs/commitment.d.ts

@@ -0,0 +1,41 @@
+import { OmniaVtxo, VtxoId, VtxoProof } from './types.js';
+/** Domain-separated hash prefixes (#33) — a hash on one record cannot replay against another. */
+export declare const VTXO_ID_DOMAIN = "totemsdk/omnia-vtxo/vtxo/v1";
+export declare const VTXO_POOL_ID_DOMAIN = "totemsdk/omnia-vtxo/pool/v1";
+export declare const VTXO_LEAF_DOMAIN = "totemsdk/omnia-vtxo/leaf/v1";
+export declare const VTXO_RECEIPT_DOMAIN = "totemsdk/omnia-vtxo/receipt/v1";
+export declare const VTXO_BATCH_DOMAIN = "totemsdk/omnia-vtxo/batch/v1";
+/**
+ * Canonical batch commitment (RFC-038 §3.2): the operator signs this over the
+ * pool, epoch, Merkle root, and the ordered VTXO ids in the batch.
+ */
+export declare function computeBatchCommitment(poolId: string, epoch: number, root: string, orderedIds: readonly string[]): string;
+/** The 32-byte digest of a batch commitment, for signing. */
+export declare function computeBatchCommitmentBytes(poolId: string, epoch: number, root: string, orderedIds: readonly string[]): Uint8Array;
+export declare function computeVtxoLeaf(vtxo: OmniaVtxo): string;
+export interface ComputeVtxoIdParams {
+    poolId: string;
+    owner: string;
+    amount: bigint;
+    tokenId: string;
+    nonce: string;
+}
+export declare function computeVtxoId(params: ComputeVtxoIdParams): string;
+export interface ComputePoolIdParams {
+    operator: string;
+    tokenId: string;
+    nonce: string;
+}
+export declare function computePoolId(params: ComputePoolIdParams): string;
+export declare function computeCommitmentRoot(leaves: string[]): string;
+export interface MerkleProofNode {
+    sibling: string;
+    position: 'left' | 'right';
+}
+export declare function verifyMerkleProof(leaf: string, proof: MerkleProofNode[], root: string): boolean;
+export interface VtxoProofSet {
+    root: string;
+    proofs: Record<VtxoId, VtxoProof>;
+}
+export declare function buildVtxoProofSet(vtxos: OmniaVtxo[]): VtxoProofSet;
+export declare function computeReceiptId(poolId: string, op: string, inputIds: string[], outputIds: string[], at: number): string;

package/dist/cjs/commitment.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VTXO_BATCH_DOMAIN = exports.VTXO_RECEIPT_DOMAIN = exports.VTXO_LEAF_DOMAIN = exports.VTXO_POOL_ID_DOMAIN = exports.VTXO_ID_DOMAIN = void 0;
+exports.computeBatchCommitment = computeBatchCommitment;
+exports.computeBatchCommitmentBytes = computeBatchCommitmentBytes;
+exports.computeVtxoLeaf = computeVtxoLeaf;
+exports.computeVtxoId = computeVtxoId;
+exports.computePoolId = computePoolId;
+exports.computeCommitmentRoot = computeCommitmentRoot;
+exports.verifyMerkleProof = verifyMerkleProof;
+exports.buildVtxoProofSet = buildVtxoProofSet;
+exports.computeReceiptId = computeReceiptId;
+const core_1 = require("@totemsdk/core");
+const constants_js_1 = require("./constants.js");
+/** Domain-separated hash prefixes (#33) — a hash on one record cannot replay against another. */
+exports.VTXO_ID_DOMAIN = 'totemsdk/omnia-vtxo/vtxo/v1';
+exports.VTXO_POOL_ID_DOMAIN = 'totemsdk/omnia-vtxo/pool/v1';
+exports.VTXO_LEAF_DOMAIN = 'totemsdk/omnia-vtxo/leaf/v1';
+exports.VTXO_RECEIPT_DOMAIN = 'totemsdk/omnia-vtxo/receipt/v1';
+exports.VTXO_BATCH_DOMAIN = 'totemsdk/omnia-vtxo/batch/v1';
+/**
+ * Canonical batch commitment (RFC-038 §3.2): the operator signs this over the
+ * pool, epoch, Merkle root, and the ordered VTXO ids in the batch.
+ */
+function computeBatchCommitment(poolId, epoch, root, orderedIds) {
+    return sha3hex(`${exports.VTXO_BATCH_DOMAIN}|${poolId}|${epoch}|${root}|${[...orderedIds].join(',')}`);
+}
+/** The 32-byte digest of a batch commitment, for signing. */
+function computeBatchCommitmentBytes(poolId, epoch, root, orderedIds) {
+    return (0, core_1.hexToBytes)(computeBatchCommitment(poolId, epoch, root, orderedIds));
+}
+function sha3hex(input) {
+    const bytes = new TextEncoder().encode(input);
+    return (0, core_1.bytesToHex)((0, core_1.sha3_256)(bytes));
+}
+function hashPair(a, b) {
+    const [left, right] = a <= b ? [a, b] : [b, a];
+    const combined = left + right;
+    const bytes = (0, core_1.hexToBytes)(combined);
+    return (0, core_1.bytesToHex)((0, core_1.sha3_256)(bytes));
+}
+function computeVtxoLeaf(vtxo) {
+    const input = [
+        exports.VTXO_LEAF_DOMAIN,
+        vtxo.vtxoId,
+        vtxo.owner,
+        vtxo.amount.toString(),
+        vtxo.tokenId,
+        vtxo.epoch.toString(),
+        vtxo.poolId,
+    ].join(':');
+    return sha3hex(input);
+}
+function computeVtxoId(params) {
+    const input = [
+        exports.VTXO_ID_DOMAIN,
+        params.poolId,
+        params.owner,
+        params.amount.toString(),
+        params.tokenId,
+        params.nonce,
+    ].join(':');
+    return sha3hex(input);
+}
+function computePoolId(params) {
+    const input = [
+        exports.VTXO_POOL_ID_DOMAIN,
+        params.operator,
+        params.tokenId,
+        params.nonce,
+    ].join(':');
+    return sha3hex(input);
+}
+function nextPowerOfTwo(n) {
+    if (n <= 1)
+        return 1;
+    let p = 1;
+    while (p < n)
+        p <<= 1;
+    return p;
+}
+function computeCommitmentRoot(leaves) {
+    if (leaves.length === 0)
+        return constants_js_1.EMPTY_LEAF;
+    const size = nextPowerOfTwo(leaves.length);
+    const level = new Array(size).fill(constants_js_1.EMPTY_LEAF);
+    for (let i = 0; i < leaves.length; i++) {
+        level[i] = leaves[i];
+    }
+    let current = level;
+    while (current.length > 1) {
+        const next = [];
+        for (let i = 0; i < current.length; i += 2) {
+            next.push(hashPair(current[i], current[i + 1]));
+        }
+        current = next;
+    }
+    return current[0];
+}
+function verifyMerkleProof(leaf, proof, root) {
+    let current = leaf;
+    for (const node of proof) {
+        if (node.position === 'left') {
+            current = hashPair(node.sibling, current);
+        }
+        else {
+            current = hashPair(current, node.sibling);
+        }
+    }
+    return current === root;
+}
+function buildVtxoProofSet(vtxos) {
+    if (vtxos.length === 0) {
+        return { root: constants_js_1.EMPTY_LEAF, proofs: {} };
+    }
+    const sorted = [...vtxos].sort((a, b) => a.vtxoId < b.vtxoId ? -1 : a.vtxoId > b.vtxoId ? 1 : 0);
+    const leafMap = new Map();
+    const leaves = sorted.map(v => {
+        const leaf = computeVtxoLeaf(v);
+        leafMap.set(v.vtxoId, leaf);
+        return leaf;
+    });
+    const size = nextPowerOfTwo(leaves.length);
+    const paddedLeaves = [...leaves];
+    while (paddedLeaves.length < size)
+        paddedLeaves.push(constants_js_1.EMPTY_LEAF);
+    const levels = [paddedLeaves];
+    let current = paddedLeaves;
+    while (current.length > 1) {
+        const next = [];
+        for (let i = 0; i < current.length; i += 2) {
+            next.push(hashPair(current[i], current[i + 1]));
+        }
+        levels.push(next);
+        current = next;
+    }
+    const root = current[0];
+    const proofs = {};
+    sorted.forEach((vtxo, idx) => {
+        const siblings = [];
+        const positions = [];
+        let pos = idx;
+        for (let lvl = 0; lvl < levels.length - 1; lvl++) {
+            const isLeft = pos % 2 === 0;
+            const siblingIdx = isLeft ? pos + 1 : pos - 1;
+            const sibling = levels[lvl][siblingIdx] ?? constants_js_1.EMPTY_LEAF;
+            siblings.push(sibling);
+            positions.push(isLeft ? 'right' : 'left');
+            pos = Math.floor(pos / 2);
+        }
+        const leaf = leafMap.get(vtxo.vtxoId);
+        proofs[vtxo.vtxoId] = {
+            leaf,
+            root,
+            siblings,
+            positions,
+            epoch: vtxo.epoch,
+            batchId: root,
+        };
+    });
+    return { root, proofs };
+}
+function computeReceiptId(poolId, op, inputIds, outputIds, at) {
+    const input = [
+        exports.VTXO_RECEIPT_DOMAIN,
+        poolId,
+        op,
+        inputIds.sort().join(','),
+        outputIds.sort().join(','),
+        at.toString(),
+    ].join(':');
+    return sha3hex(input);
+}

package/dist/cjs/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const EMPTY_LEAF = "0000000000000000000000000000000000000000000000000000000000000000";
+export declare const EMPTY_TREE_ROOT = "0000000000000000000000000000000000000000000000000000000000000000";
+export declare const EPOCH_ZERO = 0;
+export declare const DEFAULT_POLICY: {
+    readonly minAmount: bigint;
+    readonly maxAmount: bigint;
+    readonly maxMergeInputs: 8;
+    readonly maxSplitOutputs: 8;
+    readonly exitTimelockSeconds: 86400;
+};

package/dist/cjs/constants.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_POLICY = exports.EPOCH_ZERO = exports.EMPTY_TREE_ROOT = exports.EMPTY_LEAF = void 0;
+exports.EMPTY_LEAF = '0000000000000000000000000000000000000000000000000000000000000000';
+exports.EMPTY_TREE_ROOT = '0000000000000000000000000000000000000000000000000000000000000000';
+exports.EPOCH_ZERO = 0;
+exports.DEFAULT_POLICY = {
+    minAmount: BigInt(1),
+    maxAmount: BigInt(1000000000000000),
+    maxMergeInputs: 8,
+    maxSplitOutputs: 8,
+    exitTimelockSeconds: 86400,
+};

package/dist/cjs/durable-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Durable VTXO/pool snapshot store (RFC-007 G6).
+ *
+ * Drop-in replacement for `MemoryOmniaVtxoStore` — same `OmniaVtxoStore` port
+ * — backed by a storage adapter instead of heap maps: the whole pool/VTXO
+ * registry is a single revision-CAS snapshot record, so concurrent pool/VTXO
+ * transitions never lose an update, reopen restores every VTXO (incl. spent
+ * status and history), and corruption is surfaced — never treated as absence.
+ */
+import type { StorageAdapterWithCapabilities, CasStore, WriteAckMode } from '@totemsdk/storage/types';
+import type { OmniaVtxo, OmniaVtxoPool, OmniaVtxoStore } from './types.js';
+export interface OmniaVtxoRegistryState {
+    pools: Record<string, OmniaVtxoPool>;
+    vtxos: Record<string, OmniaVtxo>;
+}
+export interface DurableOmniaVtxoStoreOptions {
+    /** Key namespace prefix; default `totem_omnia_vtxo:v1:`. */
+    readonly namespace?: string;
+    /**
+     * Required write acknowledgment; default `durably-acknowledged`. Pass
+     * `volatile` only for tests/scratch adapters (e.g. `MemoryStore`).
+     */
+    readonly requireAckMode?: WriteAckMode;
+}
+export interface DurableOmniaVtxoStore extends OmniaVtxoStore {
+    /** Current registry transition counter (0 before the first write). */
+    getRevision(): Promise<number>;
+    /** True once any snapshot record has been persisted. */
+    hasState(): Promise<boolean>;
+    /** Current persisted snapshot state (pool + vtxo maps). */
+    getSnapshot(): Promise<OmniaVtxoRegistryState>;
+}
+export declare function createDurableOmniaVtxoStore(adapter: StorageAdapterWithCapabilities & CasStore, options?: DurableOmniaVtxoStoreOptions): DurableOmniaVtxoStore;