@totemsdk/omnia-vtxo 0.2.0 → 0.3.0

package/dist/exit.js

@@ -1,19 +1,13 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.markExiting = markExiting;
-exports.markExited = markExited;
-exports.createExitDraft = createExitDraft;
-const errors_js_1 = require("./errors.js");
-const constants_js_1 = require("./constants.js");
-const commitment_js_1 = require("./commitment.js");
+import { VtxoStatusError, VtxoExitError, VtxoProofError } from './errors.js';
+import { computeReceiptId, computeVtxoLeaf } from './commitment.js';
 /**
  * Transitions an active VTXO to 'exiting' status.
  * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
  */
-function markExiting(vtxo, now) {
+export function markExiting(vtxo, now) {
     const ts = now !== undefined ? now : Date.now();
     if (vtxo.status !== 'active') {
-        throw new errors_js_1.VtxoStatusError(`Cannot initiate exit for VTXO ${vtxo.vtxoId}: status is '${vtxo.status}'`, vtxo.status);
+        throw new VtxoStatusError(`Cannot initiate exit for VTXO ${vtxo.vtxoId}: status is '${vtxo.status}'`, vtxo.status);
     }
     return {
         ...vtxo,
@@ -29,18 +23,19 @@ function markExiting(vtxo, now) {
  * Transitions an exiting VTXO to 'exited' status.
  * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
  */
-function markExited(vtxo, now) {
-    const ts = now !== undefined ? now : Date.now();
+export function markExited(vtxo, options = {}) {
+    const ts = options.now !== undefined ? options.now : Date.now();
     if (vtxo.status !== 'exiting') {
-        throw new errors_js_1.VtxoStatusError(`Cannot mark VTXO ${vtxo.vtxoId} as exited: status is '${vtxo.status}'`, vtxo.status);
+        throw new VtxoStatusError(`Cannot mark VTXO ${vtxo.vtxoId} as exited: status is '${vtxo.status}'`, vtxo.status);
     }
     return {
         ...vtxo,
         status: 'exited',
         updatedAt: ts,
+        ...(options.txpowId ? { exitTxpowId: options.txpowId } : {}),
         history: [
             ...vtxo.history,
-            { op: 'exit_complete', at: ts },
+            { op: 'exit_complete', at: ts, ...(options.txpowId ? { meta: { txpowId: options.txpowId } } : {}) },
         ],
     };
 }
@@ -51,20 +46,25 @@ function markExited(vtxo, now) {
 function assertProofLeafValid(vtxo) {
     if (!vtxo.proof.leaf)
         return;
-    const expectedLeaf = (0, commitment_js_1.computeVtxoLeaf)(vtxo);
+    const expectedLeaf = computeVtxoLeaf(vtxo);
     if (vtxo.proof.leaf !== expectedLeaf) {
-        throw new errors_js_1.VtxoProofError(`Exit draft rejected: VTXO ${vtxo.vtxoId} proof leaf mismatch. ` +
+        throw new VtxoProofError(`Exit draft rejected: VTXO ${vtxo.vtxoId} proof leaf mismatch. ` +
             `Expected ${expectedLeaf}, got ${vtxo.proof.leaf}`);
     }
 }
 /**
- * Creates a mock exit draft for a VTXO. Validates the proof leaf before drafting.
+ * Creates a mock exit draft for a VTXO. Validates the proof leaf before
+ * drafting, caps the exit at the verified share, and consumes the VTXO's
+ * receipt so a second exit draft is refused (double-exit prevention, #28).
  * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
  */
-function createExitDraft(vtxo, now) {
+export function createExitDraft(vtxo, now) {
     const ts = now !== undefined ? now : Date.now();
     if (vtxo.status !== 'active' && vtxo.status !== 'exiting') {
-        throw new errors_js_1.VtxoExitError(`Cannot create exit draft for VTXO ${vtxo.vtxoId}: status is '${vtxo.status}'`);
+        throw new VtxoExitError(`Cannot create exit draft for VTXO ${vtxo.vtxoId}: status is '${vtxo.status}'`);
+    }
+    if (vtxo.exitConsumedAt !== undefined) {
+        throw new VtxoExitError(`Cannot create exit draft for VTXO ${vtxo.vtxoId}: exit already consumed by ${vtxo.exitReceiptId}`);
     }
     assertProofLeafValid(vtxo);
     const draft = {
@@ -73,11 +73,12 @@ function createExitDraft(vtxo, now) {
         owner: vtxo.owner,
         amount: vtxo.amount,
         tokenId: vtxo.tokenId,
-        draftType: 'mock-exit',
+        draftType: 'vtxo-exit',
         timelockSeconds: 86400,
         createdAt: ts,
+        verifiedShare: vtxo.amount,
     };
-    const receiptId = (0, commitment_js_1.computeReceiptId)(vtxo.poolId, 'exit_initiated', [vtxo.vtxoId], [], ts);
+    const receiptId = computeReceiptId(vtxo.poolId, 'exit_initiated', [vtxo.vtxoId], [], ts);
     const receipt = {
         receiptId,
         poolId: vtxo.poolId,
@@ -86,8 +87,23 @@ function createExitDraft(vtxo, now) {
         outputIds: [],
         epoch: vtxo.epoch,
         at: ts,
-        signature: constants_js_1.MOCK_OPERATOR_SIGNATURE,
-        draftType: 'mock-exit',
+        signature: '',
+        draftType: 'vtxo-exit',
     };
     return { draft, receipt };
 }
+/**
+ * Consume a VTXO's exit receipt — the single-spend marker that prevents a
+ * second exit draft for the same VTXO. Returns the updated VTXO.
+ */
+export function consumeExitReceipt(vtxo, receiptId, now) {
+    if (vtxo.exitConsumedAt !== undefined) {
+        throw new VtxoExitError(`VTXO ${vtxo.vtxoId} exit already consumed by ${vtxo.exitReceiptId}`);
+    }
+    return {
+        ...vtxo,
+        exitConsumedAt: now ?? Date.now(),
+        exitReceiptId: receiptId,
+        updatedAt: now ?? Date.now(),
+    };
+}

package/dist/index.d.ts

@@ -2,6 +2,11 @@ export * from './types.js';
 export * from './errors.js';
 export * from './constants.js';
 export * from './commitment.js';
+export * from './operator.js';
+export * from './receipt.js';
+export * from './pool-script.js';
+export * from './anchor.js';
+export * from './exit-tx.js';
 export * from './pool.js';
 export * from './vtxo.js';
 export * from './transfer.js';
@@ -11,5 +16,6 @@ export * from './refresh.js';
 export * from './exit.js';
 export * from './verify.js';
 export * from './memory-store.js';
+export * from './durable-store.js';
 export * from './serialization.js';
 export * from './policy.js';

package/dist/index.js

@@ -1,31 +1,21 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./types.js"), exports);
-__exportStar(require("./errors.js"), exports);
-__exportStar(require("./constants.js"), exports);
-__exportStar(require("./commitment.js"), exports);
-__exportStar(require("./pool.js"), exports);
-__exportStar(require("./vtxo.js"), exports);
-__exportStar(require("./transfer.js"), exports);
-__exportStar(require("./split.js"), exports);
-__exportStar(require("./merge.js"), exports);
-__exportStar(require("./refresh.js"), exports);
-__exportStar(require("./exit.js"), exports);
-__exportStar(require("./verify.js"), exports);
-__exportStar(require("./memory-store.js"), exports);
-__exportStar(require("./serialization.js"), exports);
-__exportStar(require("./policy.js"), exports);
+export * from './types.js';
+export * from './errors.js';
+export * from './constants.js';
+export * from './commitment.js';
+export * from './operator.js';
+export * from './receipt.js';
+export * from './pool-script.js';
+export * from './anchor.js';
+export * from './exit-tx.js';
+export * from './pool.js';
+export * from './vtxo.js';
+export * from './transfer.js';
+export * from './split.js';
+export * from './merge.js';
+export * from './refresh.js';
+export * from './exit.js';
+export * from './verify.js';
+export * from './memory-store.js';
+export * from './durable-store.js';
+export * from './serialization.js';
+export * from './policy.js';

package/dist/memory-store.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryOmniaVtxoStore = void 0;
-const errors_js_1 = require("./errors.js");
-class MemoryOmniaVtxoStore {
+import { VtxoStatusError } from './errors.js';
+export class MemoryOmniaVtxoStore {
     constructor() {
         this.pools = new Map();
         this.vtxos = new Map();
@@ -36,7 +33,7 @@ class MemoryOmniaVtxoStore {
         if (!vtxo)
             throw new Error(`VTXO ${vtxoId} not found`);
         if (vtxo.status !== 'active') {
-            throw new errors_js_1.VtxoStatusError(`Cannot mark VTXO ${vtxoId} as spent: status is '${vtxo.status}'`, vtxo.status);
+            throw new VtxoStatusError(`Cannot mark VTXO ${vtxoId} as spent: status is '${vtxo.status}'`, vtxo.status);
         }
         // NOTE: Date.now() fallback is intentional and documented above.
         const ts = now !== undefined ? now : Date.now();
@@ -48,4 +45,3 @@ class MemoryOmniaVtxoStore {
         });
     }
 }
-exports.MemoryOmniaVtxoStore = MemoryOmniaVtxoStore;

package/dist/merge.js

@@ -1,26 +1,22 @@
-"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");
-const constants_js_1 = require("./constants.js");
+import { VtxoStatusError, VtxoMergeError, VtxoOwnershipError } from './errors.js';
+import { computeVtxoId, buildVtxoProofSet, computeReceiptId } from './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) {
+export 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');
+        throw new 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');
+        throw new 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);
+            throw new VtxoStatusError(`Cannot merge VTXO ${vtxo.vtxoId}: status is '${vtxo.status}'`, vtxo.status);
         }
     }
     const poolId = vtxos[0].poolId;
@@ -28,20 +24,20 @@ function mergeVtxos(vtxos, params, now) {
     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}`);
+            throw new 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}`);
+            throw new 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}`);
+            throw new 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}'`);
+        throw new 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)({
+    const outputId = computeVtxoId({
         poolId,
         owner: params.owner,
         amount: totalAmount,
@@ -75,7 +71,7 @@ function mergeVtxos(vtxos, params, now) {
             siblings: [],
             positions: [],
             epoch: vtxos[0].epoch,
-            batchId: constants_js_1.MOCK_BATCH_ID,
+            batchId: '',
         },
         history: [
             {
@@ -87,9 +83,9 @@ function mergeVtxos(vtxos, params, now) {
         createdAt: ts,
         updatedAt: ts,
     };
-    const { proofs } = (0, commitment_js_1.buildVtxoProofSet)([rawOutput]);
+    const { proofs } = buildVtxoProofSet([rawOutput]);
     const output = { ...rawOutput, proof: proofs[outputId] };
-    const receiptId = (0, commitment_js_1.computeReceiptId)(poolId, 'merge', ids, [outputId], ts);
+    const receiptId = computeReceiptId(poolId, 'merge', ids, [outputId], ts);
     return {
         inputs: inputVtxos,
         output,
@@ -101,7 +97,7 @@ function mergeVtxos(vtxos, params, now) {
             outputIds: [outputId],
             epoch: vtxos[0].epoch,
             at: ts,
-            signature: constants_js_1.MOCK_OPERATOR_SIGNATURE,
+            signature: '',
         },
     };
 }

package/dist/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/operator.js

@@ -0,0 +1,61 @@
+/**
+ * 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 { bytesToHex, deserializeTreeSignature, hexToBytes, serializeTreeSignature, sha3_256, verifyTreeSignature, } from '@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. */
+export function vtxoOperatorTreeId(poolId) {
+    return `omnia-vtxo:${poolId}`;
+}
+export 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: bytesToHex(sha3_256(data)),
+        });
+        const flat = reservation.indices.l1 * KEYS_PER_LEVEL + reservation.indices.l2;
+        try {
+            treeKey.setUses(flat);
+            const signature = serializeTreeSignature(treeKey.sign(data));
+            await leaseProvider.commitKeyUse(reservation.reservationId, 'vtxo-operator');
+            return '0x' + bytesToHex(signature);
+        }
+        catch (err) {
+            await leaseProvider.burnReservation(reservation.reservationId, 'sign-failed').catch(() => { });
+            throw err;
+        }
+    };
+    return {
+        poolId,
+        publicKey: '0x' + 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 verifyTreeSignature(rootPubkey, data, deserializeTreeSignature(hexToBytes(sig)));
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}

package/dist/policy.d.ts

@@ -16,7 +16,7 @@ export interface VtxoExitIntent {
     owner: string;
     amount: bigint;
     tokenId: string;
-    draftType: 'mock-exit';
+    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/policy.js

@@ -1,8 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildVtxoTransferIntent = buildVtxoTransferIntent;
-exports.buildVtxoExitIntent = buildVtxoExitIntent;
-function buildVtxoTransferIntent(vtxo, recipient, amount, nonce, changeNonce) {
+export function buildVtxoTransferIntent(vtxo, recipient, amount, nonce, changeNonce) {
     return {
         type: 'vtxo-transfer',
         poolId: vtxo.poolId,
@@ -14,7 +10,7 @@ function buildVtxoTransferIntent(vtxo, recipient, amount, nonce, changeNonce) {
         changeNonce,
     };
 }
-function buildVtxoExitIntent(vtxo) {
+export function buildVtxoExitIntent(vtxo) {
     return {
         type: 'vtxo-exit',
         poolId: vtxo.poolId,
@@ -22,6 +18,6 @@ function buildVtxoExitIntent(vtxo) {
         owner: vtxo.owner,
         amount: vtxo.amount,
         tokenId: vtxo.tokenId,
-        draftType: 'mock-exit',
+        draftType: 'vtxo-exit',
     };
 }

package/dist/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/pool-script.js

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+import { computeScriptAddress } from '@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. */
+export function buildPoolScript(operatorPublicKeyDigest) {
+    return [
+        'LET ROOT=STATE(100)',
+        'LET EPOCH=STATE(101)',
+        'ASSERT EPOCH GT PREVSTATE(101)',
+        `RETURN SIGNEDBY(${operatorPkHex(operatorPublicKeyDigest)})`,
+    ].join('\n');
+}
+export function poolScriptAddress(script) {
+    return computeScriptAddress(script);
+}
+export function buildAndHashPoolScript(operatorPublicKeyDigest) {
+    const script = buildPoolScript(operatorPublicKeyDigest);
+    return { script, address: poolScriptAddress(script) };
+}

package/dist/pool.js

@@ -1,24 +1,18 @@
-"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) {
+import { VtxoPoolCapacityError, VtxoPolicyError } from './errors.js';
+import { DEFAULT_POLICY, EMPTY_TREE_ROOT, EPOCH_ZERO } from './constants.js';
+import { computePoolId } from './commitment.js';
+export 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,
+        minAmount: params.policy?.minAmount ?? DEFAULT_POLICY.minAmount,
+        maxAmount: params.policy?.maxAmount ?? DEFAULT_POLICY.maxAmount,
+        maxMergeInputs: params.policy?.maxMergeInputs ?? DEFAULT_POLICY.maxMergeInputs,
+        maxSplitOutputs: params.policy?.maxSplitOutputs ?? DEFAULT_POLICY.maxSplitOutputs,
+        exitTimelockSeconds: params.policy?.exitTimelockSeconds ?? DEFAULT_POLICY.exitTimelockSeconds,
     };
     if (params.totalCapacity <= BigInt(0)) {
-        throw new errors_js_1.VtxoPolicyError('Pool totalCapacity must be > 0');
+        throw new VtxoPolicyError('Pool totalCapacity must be > 0');
     }
-    const poolId = (0, commitment_js_1.computePoolId)({
+    const poolId = computePoolId({
         operator: params.operator,
         tokenId: params.tokenId,
         nonce: params.nonce,
@@ -29,32 +23,32 @@ function createPool(params, now) {
         tokenId: params.tokenId,
         totalCapacity: params.totalCapacity,
         availableCapacity: params.totalCapacity,
-        epoch: constants_js_1.EPOCH_ZERO,
-        commitmentRoot: constants_js_1.EMPTY_TREE_ROOT,
+        epoch: EPOCH_ZERO,
+        commitmentRoot: EMPTY_TREE_ROOT,
         createdAt: now,
         policy,
     };
 }
-function assertPoolCanMint(pool, amount) {
+export function assertPoolCanMint(pool, amount) {
     if (amount <= BigInt(0)) {
-        throw new errors_js_1.VtxoPolicyError(`Mint amount must be > 0, got ${amount}`);
+        throw new 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}`);
+        throw new 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}`);
+        throw new 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);
+        throw new VtxoPoolCapacityError(`Insufficient pool capacity: requested ${amount}, available ${pool.availableCapacity}`, amount, pool.availableCapacity);
     }
 }
-function updatePoolRoot(pool, root) {
+export function updatePoolRoot(pool, root) {
     return { ...pool, commitmentRoot: root };
 }
-function advancePoolEpoch(pool, newEpoch) {
+export 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}`);
+        throw new VtxoPolicyError(`New epoch ${newEpoch} must be greater than current epoch ${pool.epoch}`);
     }
     return { ...pool, epoch: newEpoch };
 }

package/dist/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/receipt.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { computeBatchCommitmentBytes, computeCommitmentRoot, computeVtxoLeaf } from './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.
+ */
+export 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 = computeCommitmentRoot(batch.outputs.map(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 = 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. */
+export async function verifyVtxoReceipt(operator, receipt, root) {
+    if (!receipt.signature)
+        return false;
+    const data = computeBatchCommitmentBytes(receipt.poolId, receipt.epoch, root, receipt.outputIds);
+    return operator.verify(data, receipt.signature);
+}