@totemsdk/omnia-vtxo 0.6.0 → 0.6.2

package/dist/cjs/claim-policy.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Opt-in VTXO claim policies (M8–M10).
+ *
+ * The base OmniaVtxo is single-owner. These policies let a VTXO carry a
+ * threshold, conditional (HTLC-style) or DvP-bound claim rule. Signatures are
+ * assumed to have been cryptographically verified by the caller; this module
+ * enforces the authorization *policy* (who/what may claim, and when).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyClaimPolicy = verifyClaimPolicy;
+exports.claimPolicyOf = claimPolicyOf;
+exports.verifyVtxoClaim = verifyVtxoClaim;
+const core_1 = require("@totemsdk/core");
+function uniqueSigners(signers) {
+    return [...new Set(signers)];
+}
+function preimageMatches(preimage, hashlock) {
+    if (!preimage)
+        return false;
+    try {
+        return core_1.HTLCHelper.verifyPreimage(preimage, hashlock, 'sha3');
+    }
+    catch {
+        return false;
+    }
+}
+function verifyClaimPolicy(policy, witness, ctx) {
+    const signers = uniqueSigners(witness.signers);
+    if (policy.binding?.poolId !== undefined && policy.binding.poolId !== ctx.poolId) {
+        return { valid: false, error: 'policy pool binding mismatch' };
+    }
+    if (policy.binding?.tokenId !== undefined && policy.binding.tokenId !== ctx.tokenId) {
+        return { valid: false, error: 'policy token binding mismatch' };
+    }
+    switch (policy.type) {
+        case 'single':
+            return signers.includes(policy.owner)
+                ? { valid: true }
+                : { valid: false, error: `claim requires owner ${policy.owner}` };
+        case 'threshold': {
+            if (!Number.isInteger(policy.threshold) || policy.threshold <= 0) {
+                return { valid: false, error: 'threshold must be positive' };
+            }
+            if (policy.threshold > policy.owners.length) {
+                return { valid: false, error: 'threshold exceeds owner set' };
+            }
+            const approved = signers.filter((s) => policy.owners.includes(s));
+            return approved.length >= policy.threshold
+                ? { valid: true }
+                : { valid: false, error: `threshold ${policy.threshold}/${policy.owners.length} not met` };
+        }
+        case 'conditional': {
+            if (ctx.block <= policy.timeoutBlock) {
+                if (witness.path !== 'claim')
+                    return { valid: false, error: 'claim path required before timeout' };
+                if (!signers.includes(policy.owner))
+                    return { valid: false, error: 'owner signature required' };
+                if (!preimageMatches(witness.preimage, policy.hashlock)) {
+                    return { valid: false, error: 'invalid preimage' };
+                }
+                return { valid: true };
+            }
+            if (witness.path !== 'refund')
+                return { valid: false, error: 'refund path required after timeout' };
+            if (!signers.includes(policy.refundOwner))
+                return { valid: false, error: 'refund owner signature required' };
+            return { valid: true };
+        }
+        case 'delegated': {
+            if (policy.revoked)
+                return { valid: false, error: 'delegation revoked' };
+            if (ctx.block > policy.expiresAtBlock)
+                return { valid: false, error: 'delegation expired' };
+            if (witness.scope !== policy.scope)
+                return { valid: false, error: `scope must be ${policy.scope}` };
+            return signers.includes(policy.delegate)
+                ? { valid: true }
+                : { valid: false, error: 'delegate signature required' };
+        }
+        case 'rotation':
+            return signers.includes(ctx.block >= policy.rotateAtBlock ? policy.toOperator : policy.fromOperator)
+                ? { valid: true }
+                : { valid: false, error: 'wrong operator for epoch' };
+        case 'vesting': {
+            if (!signers.includes(policy.beneficiary))
+                return { valid: false, error: 'beneficiary signature required' };
+            if (ctx.block < policy.cliffBlock)
+                return { valid: false, error: 'vesting cliff not reached' };
+            const total = witness.claimAmount;
+            if (total === undefined || total <= 0n)
+                return { valid: false, error: 'claimAmount required' };
+            if (ctx.block >= policy.endBlock)
+                return { valid: true };
+            const elapsed = BigInt(ctx.block - policy.startBlock);
+            const span = BigInt(policy.endBlock - policy.startBlock);
+            if (elapsed <= 0n)
+                return { valid: false, error: 'vesting has not started' };
+            // Caller supplies the already-committed vested amount; linear schedule is
+            // represented by requiring the witness amount to be within the total.
+            return total > 0n ? { valid: true } : { valid: false, error: 'invalid claim amount' };
+        }
+        case 'recovery': {
+            if (ctx.block < policy.recoverAfterBlock)
+                return { valid: false, error: 'recovery window not open' };
+            const approved = signers.filter((s) => policy.guardians.includes(s));
+            return approved.length >= policy.threshold
+                ? { valid: true }
+                : { valid: false, error: `guardian threshold ${policy.threshold} not met` };
+        }
+        case 'collateral': {
+            if (policy.releaseAtBlock !== undefined && ctx.block < policy.releaseAtBlock) {
+                return { valid: false, error: 'collateral release not reached' };
+            }
+            if (!signers.includes(policy.owner) || !signers.includes(policy.counterparty)) {
+                return { valid: false, error: 'both collateral parties must authorize' };
+            }
+            return { valid: true };
+        }
+        case 'dvp': {
+            if (!ctx.htlc)
+                return { valid: false, error: 'DvP requires the bound HTLC' };
+            if (ctx.htlc.paymentId !== policy.paymentId)
+                return { valid: false, error: 'HTLC payment id mismatch' };
+            if (ctx.htlc.hashlock !== policy.hashlock)
+                return { valid: false, error: 'HTLC hashlock mismatch' };
+            if (ctx.htlc.status !== 'pending' && ctx.htlc.status !== 'fulfilled') {
+                return { valid: false, error: `HTLC is ${ctx.htlc.status}` };
+            }
+            if (!signers.includes(policy.owner) || !signers.includes(policy.counterparty)) {
+                return { valid: false, error: 'both DvP parties must authorize' };
+            }
+            if (!preimageMatches(witness.preimage, policy.hashlock)) {
+                return { valid: false, error: 'invalid DvP preimage' };
+            }
+            return { valid: true };
+        }
+    }
+}
+/** Resolve the policy attached to a VTXO, defaulting to its single owner. */
+function claimPolicyOf(vtxo) {
+    return vtxo.claimPolicy
+        ?? { type: 'single', owner: vtxo.owner };
+}
+function verifyVtxoClaim(vtxo, witness, ctx) {
+    if (witness.signers.length === 0)
+        return { valid: false, error: 'no signers' };
+    return verifyClaimPolicy(claimPolicyOf(vtxo), witness, ctx);
+}

package/dist/cjs/commitment.d.ts

@@ -4,12 +4,24 @@ 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_RECEIPT_BINDING_DOMAIN = "totemsdk/omnia-vtxo/receipt-binding/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;
+/** Receipt commitment binds every semantically relevant receipt field. */
+export declare function computeVtxoReceiptCommitment(receipt: {
+    receiptId: string;
+    poolId: string;
+    op: string;
+    inputIds: readonly string[];
+    outputIds: readonly string[];
+    epoch: number;
+    at: number;
+}, root: string): string;
+export declare function computeVtxoReceiptCommitmentBytes(receipt: Parameters<typeof computeVtxoReceiptCommitment>[0], root: string): Uint8Array;
 /** 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;

package/dist/cjs/commitment.js

@@ -1,7 +1,9 @@
 "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.VTXO_BATCH_DOMAIN = exports.VTXO_RECEIPT_BINDING_DOMAIN = exports.VTXO_RECEIPT_DOMAIN = exports.VTXO_LEAF_DOMAIN = exports.VTXO_POOL_ID_DOMAIN = exports.VTXO_ID_DOMAIN = void 0;
 exports.computeBatchCommitment = computeBatchCommitment;
+exports.computeVtxoReceiptCommitment = computeVtxoReceiptCommitment;
+exports.computeVtxoReceiptCommitmentBytes = computeVtxoReceiptCommitmentBytes;
 exports.computeBatchCommitmentBytes = computeBatchCommitmentBytes;
 exports.computeVtxoLeaf = computeVtxoLeaf;
 exports.computeVtxoId = computeVtxoId;
@@ -17,6 +19,7 @@ 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_RECEIPT_BINDING_DOMAIN = 'totemsdk/omnia-vtxo/receipt-binding/v1';
 exports.VTXO_BATCH_DOMAIN = 'totemsdk/omnia-vtxo/batch/v1';
 /**
  * Canonical batch commitment (RFC-038 §3.2): the operator signs this over the
@@ -25,6 +28,23 @@ exports.VTXO_BATCH_DOMAIN = 'totemsdk/omnia-vtxo/batch/v1';
 function computeBatchCommitment(poolId, epoch, root, orderedIds) {
     return sha3hex(`${exports.VTXO_BATCH_DOMAIN}|${poolId}|${epoch}|${root}|${[...orderedIds].join(',')}`);
 }
+/** Receipt commitment binds every semantically relevant receipt field. */
+function computeVtxoReceiptCommitment(receipt, root) {
+    return sha3hex([
+        exports.VTXO_RECEIPT_BINDING_DOMAIN,
+        receipt.poolId,
+        receipt.epoch.toString(),
+        root,
+        receipt.receiptId,
+        receipt.op,
+        [...receipt.inputIds].join(','),
+        [...receipt.outputIds].join(','),
+        receipt.at.toString(),
+    ].join('|'));
+}
+function computeVtxoReceiptCommitmentBytes(receipt, root) {
+    return (0, core_1.hexToBytes)(computeVtxoReceiptCommitment(receipt, root));
+}
 /** 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));

package/dist/cjs/durable-store.js

@@ -14,6 +14,10 @@ const snapshot_1 = require("@totemsdk/storage/snapshot");
 const errors_1 = require("@totemsdk/storage/errors");
 const errors_js_1 = require("./errors.js");
 const DEFAULT_NAMESPACE = 'totem_omnia_vtxo:v1:';
+const CONSUMED_STATUSES = new Set(['spent', 'transferred', 'split', 'merged', 'refreshed', 'exited']);
+function isConsumed(status) {
+    return CONSUMED_STATUSES.has(status);
+}
 function assertRegistryState(state) {
     if (typeof state !== 'object' || state === null || Array.isArray(state)) {
         throw new errors_1.StorageError('omnia-vtxo registry state is not an object', 'corrupt');
@@ -47,6 +51,10 @@ function createDurableOmniaVtxoStore(adapter, options = {}) {
         },
         async saveVtxo(vtxo) {
             await mutate((state) => {
+                const existing = state.vtxos[vtxo.vtxoId];
+                if (existing && isConsumed(existing.status) && !isConsumed(vtxo.status)) {
+                    throw new errors_js_1.VtxoStatusError(`Cannot resurrect VTXO ${vtxo.vtxoId}: status is '${existing.status}'`, existing.status);
+                }
                 const vtxos = { ...state.vtxos, [vtxo.vtxoId]: vtxo };
                 return { ...state, vtxos };
             });

package/dist/cjs/exit-entitlement.d.ts

@@ -0,0 +1,35 @@
+/**
+ * V1 transferable-exit artifact.
+ *
+ * A recipient must not accept a transferred VTXO unless it also receives a
+ * self-contained, independently executable exit entitlement. This module binds
+ * the exit transaction to the exact owner, amount, pool coin and exit block.
+ */
+import type { OmniaVtxo } from './types.js';
+import { type ExitTxParams, type ExitTxResult } from './exit-tx.js';
+export interface VtxoExitEntitlement {
+    version: 1;
+    vtxoId: string;
+    poolId: string;
+    owner: string;
+    amount: string;
+    tokenId: string;
+    fundingCoinId: string;
+    fundingAddress: string;
+    fundingScript: string;
+    holders: string[];
+    shares: string[];
+    holderIndex: number;
+    root: string;
+    epoch: number;
+    exitBlock: number;
+    txHex: string;
+    digest: string;
+    witnessHex: string;
+}
+export interface ExitEntitlementVerification {
+    valid: boolean;
+    errors: string[];
+}
+export declare function createVtxoExitEntitlement(params: ExitTxParams, result: ExitTxResult): VtxoExitEntitlement;
+export declare function verifyVtxoExitEntitlement(entitlement: VtxoExitEntitlement, vtxo: OmniaVtxo): ExitEntitlementVerification;

package/dist/cjs/exit-entitlement.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * V1 transferable-exit artifact.
+ *
+ * A recipient must not accept a transferred VTXO unless it also receives a
+ * self-contained, independently executable exit entitlement. This module binds
+ * the exit transaction to the exact owner, amount, pool coin and exit block.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVtxoExitEntitlement = createVtxoExitEntitlement;
+exports.verifyVtxoExitEntitlement = verifyVtxoExitEntitlement;
+const omnia_1 = require("@totemsdk/omnia");
+const exit_tx_js_1 = require("./exit-tx.js");
+function createVtxoExitEntitlement(params, result) {
+    return {
+        version: 1,
+        vtxoId: params.vtxo.vtxoId,
+        poolId: params.vtxo.poolId,
+        owner: params.vtxo.owner,
+        amount: params.vtxo.amount.toString(),
+        tokenId: params.vtxo.tokenId,
+        fundingCoinId: params.fundingCoinId,
+        fundingAddress: params.fundingAddress,
+        fundingScript: params.fundingScript,
+        holders: [...params.holders],
+        shares: params.shares.map((s) => s.toString()),
+        holderIndex: params.holderIndex,
+        root: params.root,
+        epoch: params.epoch,
+        exitBlock: params.exitBlock,
+        txHex: result.txHex,
+        digest: result.digest,
+        witnessHex: result.witnessHex,
+    };
+}
+function verifyVtxoExitEntitlement(entitlement, vtxo) {
+    const errors = [];
+    if (entitlement.version !== 1)
+        errors.push('unsupported entitlement version');
+    if (entitlement.vtxoId !== vtxo.vtxoId)
+        errors.push('vtxo id mismatch');
+    if (entitlement.poolId !== vtxo.poolId)
+        errors.push('pool id mismatch');
+    if (entitlement.owner !== vtxo.owner)
+        errors.push('owner mismatch');
+    if (entitlement.amount !== vtxo.amount.toString())
+        errors.push('amount mismatch');
+    if (entitlement.tokenId !== vtxo.tokenId)
+        errors.push('token mismatch');
+    if (entitlement.holders[entitlement.holderIndex] !== vtxo.owner)
+        errors.push('holder index/owner mismatch');
+    if (entitlement.shares[entitlement.holderIndex] !== vtxo.amount.toString())
+        errors.push('holder share mismatch');
+    if (!entitlement.txHex)
+        errors.push('missing exit transaction');
+    if (!entitlement.witnessHex)
+        errors.push('missing exit witness');
+    if (entitlement.txHex && entitlement.digest) {
+        try {
+            const draft = (0, omnia_1.deserializeTxDraft)(entitlement.txHex);
+            const digest = Buffer.from((0, exit_tx_js_1.exitTransactionDigest)(draft)).toString('hex');
+            if (digest !== entitlement.digest.replace(/^0x/i, ''))
+                errors.push('exit digest mismatch');
+        }
+        catch (err) {
+            errors.push(`exit transaction does not decode: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/cjs/exit-tx.d.ts

@@ -29,6 +29,8 @@ export interface ExitTxParams {
     shares: bigint[];
     /** Index of the exiting holder (must match `vtxo.owner`). */
     holderIndex: number;
+    /** Real MMR entry number of the pool coin. */
+    fundingMmrEntry?: bigint;
     /** Pool state, needed to rebuild the remainder output's state. */
     root: string;
     epoch: number;
@@ -44,6 +46,10 @@ interface MinedTxPow {
 }
 export interface ExitTxDeps {
     signDigest: (digest: Uint8Array) => Promise<Uint8Array>;
+    /** Serialized CoinProof(s) for the pool input. */
+    coinProofs?: Uint8Array[];
+    /** Serialized ScriptProof(s) for the pool script. */
+    scriptProofs?: Uint8Array[];
     chainProvider?: ChainStateProvider;
     mine?: (txBody: Uint8Array, difficulty: Uint8Array) => Promise<MinedTxPow>;
 }

package/dist/cjs/exit-tx.js

@@ -39,14 +39,17 @@ function buildExitTransactionDraft(params) {
             stateVariables: [],
         }];
     const carriesState = params.amount > share;
+    const remaining = params.shares.map((s, i) => (i === params.holderIndex ? 0n : s));
+    const exitState = carriesState
+        ? (0, anchor_js_1.poolStateVariables)(params.root, params.epoch, params.exitBlock, remaining)
+        : (0, anchor_js_1.poolStateVariables)(params.root, params.epoch, params.exitBlock, params.shares.map(() => 0n));
     if (carriesState) {
-        const remaining = params.shares.map((s, i) => (i === params.holderIndex ? 0n : s));
         outputs.push({
             address: params.fundingAddress,
             amount: params.amount - share,
             tokenId: params.vtxo.tokenId,
             storeState: true,
-            stateVariables: (0, anchor_js_1.poolStateVariables)(params.root, params.epoch, params.exitBlock, remaining),
+            stateVariables: exitState,
         });
     }
     return {
@@ -57,10 +60,11 @@ function buildExitTransactionDraft(params) {
                 amount: params.amount,
                 tokenId: params.vtxo.tokenId,
                 scriptHex: params.fundingScript,
+                ...(params.fundingMmrEntry !== undefined ? { mmrEntry: params.fundingMmrEntry } : {}),
             }],
         outputs,
         storeState: carriesState,
-        stateVariables: [],
+        stateVariables: exitState,
     };
 }
 function exitTransactionDigest(draft) {
@@ -74,6 +78,11 @@ async function buildExitTransaction(params, deps) {
     const draft = buildExitTransactionDraft(params);
     const digest = exitTransactionDigest(draft);
     const signature = await deps.signDigest(digest);
+    const witness = (0, omnia_1.serializeOmniaWitness)({
+        signatures: [signature],
+        coinProofs: deps.coinProofs ?? [],
+        scriptProofs: deps.scriptProofs ?? [],
+    });
     const result = {
         vtxoId: params.vtxo.vtxoId,
         owner: params.vtxo.owner,
@@ -81,16 +90,28 @@ async function buildExitTransaction(params, deps) {
         draftType: 'vtxo-exit',
         txHex: exitTransactionHex(draft),
         digest: Buffer.from(digest).toString('hex'),
-        witnessHex: Buffer.from(signature).toString('hex'),
+        witnessHex: Buffer.from(witness).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');
+        if (typeof deps.chainProvider.submitTransaction === 'function') {
+            const submitted = await deps.chainProvider.submitTransaction(draftBytes, witness);
+            if (submitted?.success === false) {
+                throw new Error(`exitSubmit failed: ${submitted.message ?? 'unknown error'}`);
+            }
+            result.txpowId = submitted?.txpowid;
+        }
+        else {
+            const mine = deps.mine ?? ((txBody, difficulty) => (0, txpow_1.mineTxPoW)(txBody, difficulty));
+            const txBody = (0, txpow_1.serializeTxBody)(draftBytes, witness);
+            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);
+            const broadcast = await deps.chainProvider.broadcastTxPoW(Buffer.from(fullTxPoW).toString('hex'));
+            if (broadcast?.success === false) {
+                throw new Error(`exitBroadcast failed: ${broadcast.message ?? 'unknown error'}`);
+            }
+            result.txpowId = broadcast?.txpowid ?? Buffer.from(mined.txpowId).toString('hex');
+        }
     }
     return result;
 }

package/dist/cjs/index.d.ts

@@ -19,3 +19,6 @@ export * from './memory-store.js';
 export * from './durable-store.js';
 export * from './serialization.js';
 export * from './policy.js';
+export * from './claim-policy.js';
+export * from './yield.js';
+export * from './exit-entitlement.js';

package/dist/cjs/index.js

@@ -35,3 +35,6 @@ __exportStar(require("./memory-store.js"), exports);
 __exportStar(require("./durable-store.js"), exports);
 __exportStar(require("./serialization.js"), exports);
 __exportStar(require("./policy.js"), exports);
+__exportStar(require("./claim-policy.js"), exports);
+__exportStar(require("./yield.js"), exports);
+__exportStar(require("./exit-entitlement.js"), exports);

package/dist/cjs/memory-store.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryOmniaVtxoStore = void 0;
 const errors_js_1 = require("./errors.js");
+const CONSUMED_STATUSES = new Set(['spent', 'transferred', 'split', 'merged', 'refreshed', 'exited']);
+function isConsumed(status) {
+    return CONSUMED_STATUSES.has(status);
+}
 class MemoryOmniaVtxoStore {
     constructor() {
         this.pools = new Map();
@@ -14,6 +18,10 @@ class MemoryOmniaVtxoStore {
         return this.pools.get(poolId);
     }
     async saveVtxo(vtxo) {
+        const existing = this.vtxos.get(vtxo.vtxoId);
+        if (existing && isConsumed(existing.status) && !isConsumed(vtxo.status)) {
+            throw new errors_js_1.VtxoStatusError(`Cannot resurrect VTXO ${vtxo.vtxoId}: status is '${existing.status}'`, existing.status);
+        }
         this.vtxos.set(vtxo.vtxoId, vtxo);
     }
     async getVtxo(vtxoId) {

package/dist/cjs/pool-script.js

@@ -65,6 +65,10 @@ function buildPoolScript(params) {
         throw new Error(`exitBlock must be a non-negative integer, got ${JSON.stringify(params.exitBlock)}`);
     }
     const lines = [
+        // RFC-055/assessment P0: bind the exit clock before either branch. A
+        // successful exit returns early, so a SAMESTATE guard placed after the
+        // branch would be bypassable.
+        'ASSERT SAMESTATE(102 102)',
         'LET epoch=STATE(101)',
         'LET exitblock=PREVSTATE(102)',
         'IF @BLOCK GT exitblock THEN',
@@ -92,7 +96,6 @@ function buildPoolScript(params) {
     });
     lines.push('ENDIF');
     lines.push('ASSERT epoch GT PREVSTATE(101)');
-    lines.push('ASSERT SAMESTATE(102 102)');
     lines.push('ASSERT VERIFYOUT(@INPUT @ADDRESS @AMOUNT @TOKENID TRUE)');
     lines.push(`RETURN MULTISIG(${holders.length + 1} ${operator} ${holders.join(' ')})`);
     return (0, core_1.toNodeScript)(lines.join('\n'));

package/dist/cjs/receipt.d.ts

@@ -7,7 +7,7 @@
  * 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';
+import type { OmniaVtxo, OmniaVtxoOperator, OmniaVtxoPool, 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. */
@@ -26,6 +26,13 @@ export interface VtxoReceiptBatch {
  * @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 buildVtxoReceiptPayload(receipt: VtxoOperatorReceipt, batch: VtxoReceiptBatch): Uint8Array;
 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>;
+/**
+ * Verify a receipt against the pool's current anchored state, not a
+ * caller-supplied root. Rejects a receipt from another pool/epoch and requires
+ * the pool's committed root to be present.
+ */
+export declare function verifyVtxoReceiptForPool(operator: OmniaVtxoOperator, receipt: VtxoOperatorReceipt, pool: Pick<OmniaVtxoPool, 'poolId' | 'epoch' | 'commitmentRoot'>): Promise<boolean>;

package/dist/cjs/receipt.js

@@ -9,15 +9,17 @@
  * arbitrary `(root, epoch, ids)` tuple whose root does not commit the outputs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVtxoReceiptPayload = buildVtxoReceiptPayload;
 exports.signVtxoReceipt = signVtxoReceipt;
 exports.verifyVtxoReceipt = verifyVtxoReceipt;
+exports.verifyVtxoReceiptForPool = verifyVtxoReceiptForPool;
 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) {
+function buildVtxoReceiptPayload(receipt, batch) {
     if (receipt.epoch !== batch.epoch) {
         throw new Error(`receipt epoch ${receipt.epoch} does not match batch epoch ${batch.epoch}`);
     }
@@ -33,13 +35,19 @@ async function signVtxoReceipt(operator, receipt, batch) {
     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 outputSum = batch.outputs.reduce((sum, v) => sum + v.amount, 0n);
+    if (receipt.op !== 'mint') {
+        if (batch.inputsAmount === undefined) {
+            throw new Error(`conservation required for ${receipt.op} receipts`);
+        }
+        if (outputSum !== batch.inputsAmount) {
+            throw new Error(`conservation violated: outputs ${outputSum} != inputs ${batch.inputsAmount}`);
         }
     }
-    const data = (0, commitment_js_1.computeBatchCommitmentBytes)(receipt.poolId, receipt.epoch, batch.root, receipt.outputIds);
+    return (0, commitment_js_1.computeVtxoReceiptCommitmentBytes)(receipt, batch.root);
+}
+async function signVtxoReceipt(operator, receipt, batch) {
+    const data = buildVtxoReceiptPayload(receipt, batch);
     const signature = await operator.sign(data);
     return { ...receipt, signature };
 }
@@ -47,6 +55,20 @@ async function signVtxoReceipt(operator, receipt, batch) {
 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);
+    const data = (0, commitment_js_1.computeVtxoReceiptCommitmentBytes)(receipt, root);
     return operator.verify(data, receipt.signature);
 }
+/**
+ * Verify a receipt against the pool's current anchored state, not a
+ * caller-supplied root. Rejects a receipt from another pool/epoch and requires
+ * the pool's committed root to be present.
+ */
+async function verifyVtxoReceiptForPool(operator, receipt, pool) {
+    if (receipt.poolId !== pool.poolId)
+        return false;
+    if (receipt.epoch !== pool.epoch)
+        return false;
+    if (!pool.commitmentRoot)
+        return false;
+    return verifyVtxoReceipt(operator, receipt, pool.commitmentRoot);
+}

package/dist/cjs/transfer.d.ts

@@ -1,8 +1,28 @@
 import { OmniaVtxo, TransferVtxoParams, TransferResult, VtxoOperatorReceipt } from './types.js';
+import { type VtxoExitEntitlement } from './exit-entitlement.js';
+import { type ExitTxParams, type ExitTxDeps } from './exit-tx.js';
 /**
  * Transfers a VTXO (fully or partially) to a recipient.
+ *
+ * **Offline safety.** The returned output VTXOs are new claims. A Merkle proof
+ * establishes membership in a committed set; it does NOT prove the input was
+ * never spent elsewhere. The local host rejects a second transfer through its
+ * shared state, but disconnected receivers do not share that state. Treat a
+ * received VTXO as final only after an anti-double-spend check (online/operator
+ * spend check, operator-co-signed transfer, or an explicitly risk-bounded
+ * policy), and have the operator commit the new outputs — they do not
+ * automatically belong to the previous pool root.
+ *
  * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
  */
 export declare function transferVtxo(vtxo: OmniaVtxo, params: TransferVtxoParams, now?: number): TransferResult & {
     receipt: VtxoOperatorReceipt;
 };
+/**
+ * V1 transfer: build the recipient's independent exit before moving the claim,
+ * then transfer only if the exit package verifies against the input VTXO.
+ */
+export declare function transferVtxoWithExit(vtxo: OmniaVtxo, params: Omit<TransferVtxoParams, 'exitEntitlement'>, exitParams: ExitTxParams, exitDeps: ExitTxDeps, now?: number): Promise<TransferResult & {
+    receipt: VtxoOperatorReceipt;
+    exitEntitlement: VtxoExitEntitlement;
+}>;