@totemsdk/omnia-vtxo 0.2.1 → 0.3.0

package/dist/cjs/merge.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeVtxos = mergeVtxos;
+const errors_js_1 = require("./errors.js");
+const commitment_js_1 = require("./commitment.js");
+/**
+ * Merges multiple VTXOs into one.
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+function mergeVtxos(vtxos, params, now) {
+    const ts = now !== undefined ? now : Date.now();
+    if (vtxos.length < 2) {
+        throw new errors_js_1.VtxoMergeError('Merge requires at least 2 VTXOs');
+    }
+    const ids = vtxos.map(v => v.vtxoId);
+    const uniqueIds = new Set(ids);
+    if (uniqueIds.size !== ids.length) {
+        throw new errors_js_1.VtxoMergeError('Duplicate VTXO IDs detected in merge — double-counting prevented');
+    }
+    for (const vtxo of vtxos) {
+        if (vtxo.status !== 'active') {
+            throw new errors_js_1.VtxoStatusError(`Cannot merge VTXO ${vtxo.vtxoId}: status is '${vtxo.status}'`, vtxo.status);
+        }
+    }
+    const poolId = vtxos[0].poolId;
+    const tokenId = vtxos[0].tokenId;
+    const inputOwner = vtxos[0].owner;
+    for (const vtxo of vtxos) {
+        if (vtxo.poolId !== poolId) {
+            throw new errors_js_1.VtxoMergeError(`Cannot merge VTXOs from different pools: ${vtxo.poolId} vs ${poolId}`);
+        }
+        if (vtxo.tokenId !== tokenId) {
+            throw new errors_js_1.VtxoMergeError(`Cannot merge VTXOs with different tokenIds: ${vtxo.tokenId} vs ${tokenId}`);
+        }
+        if (vtxo.owner !== inputOwner) {
+            throw new errors_js_1.VtxoOwnershipError(`Cannot merge VTXOs with different owners: ${vtxo.owner} vs ${inputOwner}`);
+        }
+    }
+    if (params.owner !== inputOwner) {
+        throw new errors_js_1.VtxoOwnershipError(`Merge output owner '${params.owner}' must match input owner '${inputOwner}'`);
+    }
+    const totalAmount = vtxos.reduce((sum, v) => sum + v.amount, BigInt(0));
+    const outputId = (0, commitment_js_1.computeVtxoId)({
+        poolId,
+        owner: params.owner,
+        amount: totalAmount,
+        tokenId,
+        nonce: params.nonce,
+    });
+    const inputVtxos = vtxos.map(vtxo => ({
+        ...vtxo,
+        status: 'merged',
+        updatedAt: ts,
+        history: [
+            ...vtxo.history,
+            {
+                op: 'merge',
+                at: ts,
+                relatedIds: [outputId],
+            },
+        ],
+    }));
+    const rawOutput = {
+        vtxoId: outputId,
+        poolId,
+        owner: params.owner,
+        amount: totalAmount,
+        tokenId,
+        status: 'active',
+        epoch: vtxos[0].epoch,
+        proof: {
+            leaf: '',
+            root: '',
+            siblings: [],
+            positions: [],
+            epoch: vtxos[0].epoch,
+            batchId: '',
+        },
+        history: [
+            {
+                op: 'merge',
+                at: ts,
+                relatedIds: ids,
+            },
+        ],
+        createdAt: ts,
+        updatedAt: ts,
+    };
+    const { proofs } = (0, commitment_js_1.buildVtxoProofSet)([rawOutput]);
+    const output = { ...rawOutput, proof: proofs[outputId] };
+    const receiptId = (0, commitment_js_1.computeReceiptId)(poolId, 'merge', ids, [outputId], ts);
+    return {
+        inputs: inputVtxos,
+        output,
+        receipt: {
+            receiptId,
+            poolId,
+            op: 'merge',
+            inputIds: ids,
+            outputIds: [outputId],
+            epoch: vtxos[0].epoch,
+            at: ts,
+            signature: '',
+        },
+    };
+}

package/dist/cjs/operator.d.ts

@@ -0,0 +1,29 @@
+/**
+ * VTXO operator co-signature (RFC-038 V0).
+ *
+ * The operator signs the canonical batch commitment with a unified WOTS
+ * `TreeKey` (RFC-037), allocating one leaf per signature under a WOTS lease
+ * (RFC-013). This retires the mock operator-signature placeholder: a receipt's
+ * `signature` is now a real serialized `TreeSignature` over the commitment, and
+ * `verify` checks it against the operator's tree-root public key.
+ *
+ * The operator's identity is the TreeKey root public key, so a holder can verify
+ * a receipt without trusting transport identity.
+ */
+import { type TreeKey } from '@totemsdk/core';
+import type { WotsLeaseProvider } from '@totemsdk/wots-lease';
+import type { OmniaVtxoOperator } from './types.js';
+/** Lease treeId for a pool's operator signatures. */
+export declare function vtxoOperatorTreeId(poolId: string): string;
+export interface VtxoOperatorOptions {
+    poolId: string;
+    /** The operator's unified WOTS TreeKey (RFC-037). */
+    treeKey: TreeKey;
+    /** Lease provider for one-time leaf allocation (RFC-013). */
+    leaseProvider: WotsLeaseProvider;
+}
+export interface VtxoOperatorWithIdentity extends OmniaVtxoOperator {
+    /** The operator's tree-root public key (its identity). */
+    readonly publicKey: string;
+}
+export declare function createVtxoOperator(options: VtxoOperatorOptions): VtxoOperatorWithIdentity;

package/dist/cjs/operator.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * VTXO operator co-signature (RFC-038 V0).
+ *
+ * The operator signs the canonical batch commitment with a unified WOTS
+ * `TreeKey` (RFC-037), allocating one leaf per signature under a WOTS lease
+ * (RFC-013). This retires the mock operator-signature placeholder: a receipt's
+ * `signature` is now a real serialized `TreeSignature` over the commitment, and
+ * `verify` checks it against the operator's tree-root public key.
+ *
+ * The operator's identity is the TreeKey root public key, so a holder can verify
+ * a receipt without trusting transport identity.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vtxoOperatorTreeId = vtxoOperatorTreeId;
+exports.createVtxoOperator = createVtxoOperator;
+const core_1 = require("@totemsdk/core");
+/** Keys per tree level — the flat leaf index is `l1 * KEYS_PER_LEVEL + l2`. */
+const KEYS_PER_LEVEL = 64;
+/** Lease treeId for a pool's operator signatures. */
+function vtxoOperatorTreeId(poolId) {
+    return `omnia-vtxo:${poolId}`;
+}
+function createVtxoOperator(options) {
+    const { poolId, treeKey, leaseProvider } = options;
+    const rootPubkey = treeKey.getPublicKey();
+    // The TreeKey carries mutable state (setUses + sign); serialize signing so
+    // concurrent co-signs cannot race on a shared key.
+    let signLock = Promise.resolve();
+    const doSign = async (data) => {
+        const reservation = await leaseProvider.reserveKeyUse({
+            treeId: vtxoOperatorTreeId(poolId),
+            purpose: 'vtxo-operator',
+            payloadHash: (0, core_1.bytesToHex)((0, core_1.sha3_256)(data)),
+        });
+        const flat = reservation.indices.l1 * KEYS_PER_LEVEL + reservation.indices.l2;
+        try {
+            treeKey.setUses(flat);
+            const signature = (0, core_1.serializeTreeSignature)(treeKey.sign(data));
+            await leaseProvider.commitKeyUse(reservation.reservationId, 'vtxo-operator');
+            return '0x' + (0, core_1.bytesToHex)(signature);
+        }
+        catch (err) {
+            await leaseProvider.burnReservation(reservation.reservationId, 'sign-failed').catch(() => { });
+            throw err;
+        }
+    };
+    return {
+        poolId,
+        publicKey: '0x' + (0, core_1.bytesToHex)(rootPubkey).toLowerCase(),
+        sign(data) {
+            const run = signLock.then(() => doSign(data), () => doSign(data));
+            signLock = run.then(() => undefined, () => undefined);
+            return run;
+        },
+        async verify(data, sig) {
+            try {
+                return (0, core_1.verifyTreeSignature)(rootPubkey, data, (0, core_1.deserializeTreeSignature)((0, core_1.hexToBytes)(sig)));
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/policy.d.ts

@@ -0,0 +1,22 @@
+import { OmniaVtxo, VtxoId } from './types.js';
+export interface VtxoTransferIntent {
+    type: 'vtxo-transfer';
+    poolId: string;
+    inputId: VtxoId;
+    recipient: string;
+    amount: bigint;
+    tokenId: string;
+    nonce: string;
+    changeNonce?: string;
+}
+export interface VtxoExitIntent {
+    type: 'vtxo-exit';
+    poolId: string;
+    vtxoId: VtxoId;
+    owner: string;
+    amount: bigint;
+    tokenId: string;
+    draftType: 'vtxo-exit';
+}
+export declare function buildVtxoTransferIntent(vtxo: OmniaVtxo, recipient: string, amount: bigint, nonce: string, changeNonce?: string): VtxoTransferIntent;
+export declare function buildVtxoExitIntent(vtxo: OmniaVtxo): VtxoExitIntent;

package/dist/cjs/policy.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVtxoTransferIntent = buildVtxoTransferIntent;
+exports.buildVtxoExitIntent = buildVtxoExitIntent;
+function buildVtxoTransferIntent(vtxo, recipient, amount, nonce, changeNonce) {
+    return {
+        type: 'vtxo-transfer',
+        poolId: vtxo.poolId,
+        inputId: vtxo.vtxoId,
+        recipient,
+        amount,
+        tokenId: vtxo.tokenId,
+        nonce,
+        changeNonce,
+    };
+}
+function buildVtxoExitIntent(vtxo) {
+    return {
+        type: 'vtxo-exit',
+        poolId: vtxo.poolId,
+        vtxoId: vtxo.vtxoId,
+        owner: vtxo.owner,
+        amount: vtxo.amount,
+        tokenId: vtxo.tokenId,
+        draftType: 'vtxo-exit',
+    };
+}

package/dist/cjs/pool-script.d.ts

@@ -0,0 +1,19 @@
+/**
+ * VTXO pool on-chain script (RFC-038 V1).
+ *
+ * The pool is an on-chain state output holding `totalCapacity`; an epoch's batch
+ * root is committed as STATE(100) with the epoch number in STATE(101), and the
+ * update requires a strictly-greater epoch (`ASSERT EPOCH GT PREVSTATE(101)`) so a
+ * old root cannot be re-anchored (RFC-038 §5 "stale/rolled-back root").
+ *
+ * CUSTODY NOTE: this script is currently **operator-only** (`SIGNEDBY(operator)`),
+ * so until V2 lands the owner-unilateral timelock branch the pool output is
+ * custodied by the operator on-chain. This is surfaced in RFC-038 §3.3/§5.
+ */
+/** Operator-controlled, epoch-monotone state-carrying pool script. */
+export declare function buildPoolScript(operatorPublicKeyDigest: string): string;
+export declare function poolScriptAddress(script: string): string;
+export declare function buildAndHashPoolScript(operatorPublicKeyDigest: string): {
+    script: string;
+    address: string;
+};

package/dist/cjs/pool-script.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * VTXO pool on-chain script (RFC-038 V1).
+ *
+ * The pool is an on-chain state output holding `totalCapacity`; an epoch's batch
+ * root is committed as STATE(100) with the epoch number in STATE(101), and the
+ * update requires a strictly-greater epoch (`ASSERT EPOCH GT PREVSTATE(101)`) so a
+ * old root cannot be re-anchored (RFC-038 §5 "stale/rolled-back root").
+ *
+ * CUSTODY NOTE: this script is currently **operator-only** (`SIGNEDBY(operator)`),
+ * so until V2 lands the owner-unilateral timelock branch the pool output is
+ * custodied by the operator on-chain. This is surfaced in RFC-038 §3.3/§5.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPoolScript = buildPoolScript;
+exports.poolScriptAddress = poolScriptAddress;
+exports.buildAndHashPoolScript = buildAndHashPoolScript;
+const core_1 = require("@totemsdk/core");
+function operatorPkHex(operatorPublicKeyDigest) {
+    const raw = operatorPublicKeyDigest.replace(/^0x/i, '');
+    if (!/^[0-9a-fA-F]{64}$/.test(raw)) {
+        throw new Error(`operator public key digest must be 64 hex chars, got ${JSON.stringify(operatorPublicKeyDigest)}`);
+    }
+    return '0X' + raw.toUpperCase();
+}
+/** Operator-controlled, epoch-monotone state-carrying pool script. */
+function buildPoolScript(operatorPublicKeyDigest) {
+    return [
+        'LET ROOT=STATE(100)',
+        'LET EPOCH=STATE(101)',
+        'ASSERT EPOCH GT PREVSTATE(101)',
+        `RETURN SIGNEDBY(${operatorPkHex(operatorPublicKeyDigest)})`,
+    ].join('\n');
+}
+function poolScriptAddress(script) {
+    return (0, core_1.computeScriptAddress)(script);
+}
+function buildAndHashPoolScript(operatorPublicKeyDigest) {
+    const script = buildPoolScript(operatorPublicKeyDigest);
+    return { script, address: poolScriptAddress(script) };
+}

package/dist/cjs/pool.d.ts

@@ -0,0 +1,5 @@
+import { OmniaVtxoPool, CreatePoolParams } from './types.js';
+export declare function createPool(params: CreatePoolParams, now: number): OmniaVtxoPool;
+export declare function assertPoolCanMint(pool: OmniaVtxoPool, amount: bigint): void;
+export declare function updatePoolRoot(pool: OmniaVtxoPool, root: string): OmniaVtxoPool;
+export declare function advancePoolEpoch(pool: OmniaVtxoPool, newEpoch: number): OmniaVtxoPool;

package/dist/cjs/pool.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPool = createPool;
+exports.assertPoolCanMint = assertPoolCanMint;
+exports.updatePoolRoot = updatePoolRoot;
+exports.advancePoolEpoch = advancePoolEpoch;
+const errors_js_1 = require("./errors.js");
+const constants_js_1 = require("./constants.js");
+const commitment_js_1 = require("./commitment.js");
+function createPool(params, now) {
+    const policy = {
+        minAmount: params.policy?.minAmount ?? constants_js_1.DEFAULT_POLICY.minAmount,
+        maxAmount: params.policy?.maxAmount ?? constants_js_1.DEFAULT_POLICY.maxAmount,
+        maxMergeInputs: params.policy?.maxMergeInputs ?? constants_js_1.DEFAULT_POLICY.maxMergeInputs,
+        maxSplitOutputs: params.policy?.maxSplitOutputs ?? constants_js_1.DEFAULT_POLICY.maxSplitOutputs,
+        exitTimelockSeconds: params.policy?.exitTimelockSeconds ?? constants_js_1.DEFAULT_POLICY.exitTimelockSeconds,
+    };
+    if (params.totalCapacity <= BigInt(0)) {
+        throw new errors_js_1.VtxoPolicyError('Pool totalCapacity must be > 0');
+    }
+    const poolId = (0, commitment_js_1.computePoolId)({
+        operator: params.operator,
+        tokenId: params.tokenId,
+        nonce: params.nonce,
+    });
+    return {
+        poolId,
+        operator: params.operator,
+        tokenId: params.tokenId,
+        totalCapacity: params.totalCapacity,
+        availableCapacity: params.totalCapacity,
+        epoch: constants_js_1.EPOCH_ZERO,
+        commitmentRoot: constants_js_1.EMPTY_TREE_ROOT,
+        createdAt: now,
+        policy,
+    };
+}
+function assertPoolCanMint(pool, amount) {
+    if (amount <= BigInt(0)) {
+        throw new errors_js_1.VtxoPolicyError(`Mint amount must be > 0, got ${amount}`);
+    }
+    if (amount < pool.policy.minAmount) {
+        throw new errors_js_1.VtxoPolicyError(`Mint amount ${amount} is below pool minimum ${pool.policy.minAmount}`);
+    }
+    if (amount > pool.policy.maxAmount) {
+        throw new errors_js_1.VtxoPolicyError(`Mint amount ${amount} exceeds pool maximum ${pool.policy.maxAmount}`);
+    }
+    if (amount > pool.availableCapacity) {
+        throw new errors_js_1.VtxoPoolCapacityError(`Insufficient pool capacity: requested ${amount}, available ${pool.availableCapacity}`, amount, pool.availableCapacity);
+    }
+}
+function updatePoolRoot(pool, root) {
+    return { ...pool, commitmentRoot: root };
+}
+function advancePoolEpoch(pool, newEpoch) {
+    if (newEpoch <= pool.epoch) {
+        throw new errors_js_1.VtxoPolicyError(`New epoch ${newEpoch} must be greater than current epoch ${pool.epoch}`);
+    }
+    return { ...pool, epoch: newEpoch };
+}

package/dist/cjs/receipt.d.ts

@@ -0,0 +1,31 @@
+/**
+ * VTXO receipt co-signing (RFC-038 V0, verify-before-sign per §3.5).
+ *
+ * A mutation emits its `VtxoOperatorReceipt` **unsigned**; the operator co-signs
+ * it only after **recomputing** the batch root from the batch's leaves and
+ * checking epoch monotonicity, output membership, and (when supplied) amount
+ * conservation. This prevents a caller from getting the operator to co-sign an
+ * arbitrary `(root, epoch, ids)` tuple whose root does not commit the outputs.
+ */
+import type { OmniaVtxo, OmniaVtxoOperator, VtxoOperatorReceipt } from './types.js';
+/** The batch the receipt belongs to — the operator's source of truth. */
+export interface VtxoReceiptBatch {
+    /** The VTXOs committed in this epoch's batch. */
+    outputs: OmniaVtxo[];
+    /** The batch root the receipt claims (the operator recomputes and compares). */
+    root: string;
+    /** The batch epoch. */
+    epoch: number;
+    /** The pool's current epoch, for monotonicity (must be strictly less). */
+    previousEpoch?: number;
+    /** Optional: total input amount, for a conservation check. */
+    inputsAmount?: bigint;
+}
+/**
+ * Co-sign a receipt with the operator, after verifying the batch.
+ * @throws if the root does not commit the leaves, the epoch is stale, an output
+ * is not in the batch, or conservation fails.
+ */
+export declare function signVtxoReceipt(operator: OmniaVtxoOperator, receipt: VtxoOperatorReceipt, batch: VtxoReceiptBatch): Promise<VtxoOperatorReceipt>;
+/** Verify a co-signed receipt against the operator and the batch root. */
+export declare function verifyVtxoReceipt(operator: OmniaVtxoOperator, receipt: VtxoOperatorReceipt, root: string): Promise<boolean>;

package/dist/cjs/receipt.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * VTXO receipt co-signing (RFC-038 V0, verify-before-sign per §3.5).
+ *
+ * A mutation emits its `VtxoOperatorReceipt` **unsigned**; the operator co-signs
+ * it only after **recomputing** the batch root from the batch's leaves and
+ * checking epoch monotonicity, output membership, and (when supplied) amount
+ * conservation. This prevents a caller from getting the operator to co-sign an
+ * arbitrary `(root, epoch, ids)` tuple whose root does not commit the outputs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signVtxoReceipt = signVtxoReceipt;
+exports.verifyVtxoReceipt = verifyVtxoReceipt;
+const commitment_js_1 = require("./commitment.js");
+/**
+ * Co-sign a receipt with the operator, after verifying the batch.
+ * @throws if the root does not commit the leaves, the epoch is stale, an output
+ * is not in the batch, or conservation fails.
+ */
+async function signVtxoReceipt(operator, receipt, batch) {
+    if (receipt.epoch !== batch.epoch) {
+        throw new Error(`receipt epoch ${receipt.epoch} does not match batch epoch ${batch.epoch}`);
+    }
+    if (batch.previousEpoch !== undefined && batch.epoch <= batch.previousEpoch) {
+        throw new Error(`batch epoch ${batch.epoch} is not greater than the pool epoch ${batch.previousEpoch}`);
+    }
+    const idSet = new Set(batch.outputs.map((v) => v.vtxoId));
+    for (const id of receipt.outputIds) {
+        if (!idSet.has(id))
+            throw new Error(`receipt output '${id}' is not a VTXO in the batch`);
+    }
+    const recomputedRoot = (0, commitment_js_1.computeCommitmentRoot)(batch.outputs.map(commitment_js_1.computeVtxoLeaf));
+    if (recomputedRoot !== batch.root) {
+        throw new Error('batch root does not commit the batch leaves');
+    }
+    if (batch.inputsAmount !== undefined) {
+        const outputSum = batch.outputs.reduce((sum, v) => sum + v.amount, 0n);
+        if (outputSum > batch.inputsAmount) {
+            throw new Error(`conservation violated: outputs ${outputSum} exceed inputs ${batch.inputsAmount}`);
+        }
+    }
+    const data = (0, commitment_js_1.computeBatchCommitmentBytes)(receipt.poolId, receipt.epoch, batch.root, receipt.outputIds);
+    const signature = await operator.sign(data);
+    return { ...receipt, signature };
+}
+/** Verify a co-signed receipt against the operator and the batch root. */
+async function verifyVtxoReceipt(operator, receipt, root) {
+    if (!receipt.signature)
+        return false;
+    const data = (0, commitment_js_1.computeBatchCommitmentBytes)(receipt.poolId, receipt.epoch, root, receipt.outputIds);
+    return operator.verify(data, receipt.signature);
+}

package/dist/cjs/refresh.d.ts

@@ -0,0 +1,8 @@
+import { OmniaVtxo, RefreshVtxoParams, RefreshResult, VtxoOperatorReceipt } from './types.js';
+/**
+ * Refreshes a VTXO to a new epoch.
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+export declare function refreshVtxo(vtxo: OmniaVtxo, params: RefreshVtxoParams, now?: number): RefreshResult & {
+    receipt: VtxoOperatorReceipt;
+};

package/dist/cjs/refresh.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshVtxo = refreshVtxo;
+const errors_js_1 = require("./errors.js");
+const commitment_js_1 = require("./commitment.js");
+/**
+ * Refreshes a VTXO to a new epoch.
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+function refreshVtxo(vtxo, params, now) {
+    const ts = now !== undefined ? now : Date.now();
+    if (vtxo.status !== 'active') {
+        throw new errors_js_1.VtxoStatusError(`Cannot refresh VTXO ${vtxo.vtxoId}: status is '${vtxo.status}'`, vtxo.status);
+    }
+    if (params.newEpoch <= vtxo.epoch) {
+        throw new errors_js_1.VtxoPolicyError(`Refresh epoch ${params.newEpoch} must be strictly greater than current epoch ${vtxo.epoch}`);
+    }
+    const refreshedId = (0, commitment_js_1.computeVtxoId)({
+        poolId: vtxo.poolId,
+        owner: vtxo.owner,
+        amount: vtxo.amount,
+        tokenId: vtxo.tokenId,
+        nonce: params.nonce,
+    });
+    const oldVtxo = {
+        ...vtxo,
+        status: 'refreshed',
+        updatedAt: ts,
+        history: [
+            ...vtxo.history,
+            {
+                op: 'refresh',
+                at: ts,
+                relatedIds: [refreshedId],
+                meta: { newEpoch: params.newEpoch },
+            },
+        ],
+    };
+    const rawRefreshed = {
+        vtxoId: refreshedId,
+        poolId: vtxo.poolId,
+        owner: vtxo.owner,
+        amount: vtxo.amount,
+        tokenId: vtxo.tokenId,
+        status: 'active',
+        epoch: params.newEpoch,
+        proof: {
+            leaf: '',
+            root: '',
+            siblings: [],
+            positions: [],
+            epoch: params.newEpoch,
+            batchId: '',
+        },
+        history: [
+            {
+                op: 'refresh',
+                at: ts,
+                relatedIds: [vtxo.vtxoId],
+                meta: { prevEpoch: vtxo.epoch, newEpoch: params.newEpoch },
+            },
+        ],
+        createdAt: ts,
+        updatedAt: ts,
+        expiresAt: vtxo.expiresAt,
+    };
+    const { proofs } = (0, commitment_js_1.buildVtxoProofSet)([rawRefreshed]);
+    const refreshedVtxo = { ...rawRefreshed, proof: proofs[refreshedId] };
+    const receiptId = (0, commitment_js_1.computeReceiptId)(vtxo.poolId, 'refresh', [vtxo.vtxoId], [refreshedId], ts);
+    return {
+        old: oldVtxo,
+        refreshed: refreshedVtxo,
+        receipt: {
+            receiptId,
+            poolId: vtxo.poolId,
+            op: 'refresh',
+            inputIds: [vtxo.vtxoId],
+            outputIds: [refreshedId],
+            epoch: params.newEpoch,
+            at: ts,
+            signature: '',
+        },
+    };
+}

package/dist/cjs/serialization.d.ts

@@ -0,0 +1,5 @@
+import { OmniaVtxo, OmniaVtxoPool } from './types.js';
+export declare function serializeVtxo(vtxo: OmniaVtxo): string;
+export declare function deserializeVtxo(json: string): OmniaVtxo;
+export declare function serializePool(pool: OmniaVtxoPool): string;
+export declare function deserializePool(json: string): OmniaVtxoPool;

package/dist/cjs/serialization.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeVtxo = serializeVtxo;
+exports.deserializeVtxo = deserializeVtxo;
+exports.serializePool = serializePool;
+exports.deserializePool = deserializePool;
+const BIGINT_PREFIX = '__bigint__:';
+function replacer(_key, value) {
+    if (typeof value === 'bigint') {
+        return `${BIGINT_PREFIX}${value.toString()}`;
+    }
+    return value;
+}
+function reviver(_key, value) {
+    if (typeof value === 'string' && value.startsWith(BIGINT_PREFIX)) {
+        return BigInt(value.slice(BIGINT_PREFIX.length));
+    }
+    return value;
+}
+function serializeVtxo(vtxo) {
+    return JSON.stringify(vtxo, replacer);
+}
+function deserializeVtxo(json) {
+    return JSON.parse(json, reviver);
+}
+function serializePool(pool) {
+    return JSON.stringify(pool, replacer);
+}
+function deserializePool(json) {
+    return JSON.parse(json, reviver);
+}

package/dist/cjs/split.d.ts

@@ -0,0 +1,8 @@
+import { OmniaVtxo, SplitVtxoParams, SplitResult, VtxoOperatorReceipt } from './types.js';
+/**
+ * Splits a VTXO into multiple outputs.
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+export declare function splitVtxo(vtxo: OmniaVtxo, params: SplitVtxoParams, now?: number): SplitResult & {
+    receipt: VtxoOperatorReceipt;
+};