@totemsdk/omnia-vtxo 0.6.1 → 0.7.0

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

@@ -5,6 +5,7 @@ export * from './commitment.js';
 export * from './operator.js';
 export * from './receipt.js';
 export * from './pool-script.js';
+export * from './owner-pool.js';
 export * from './anchor.js';
 export * from './exit-tx.js';
 export * from './pool.js';
@@ -19,3 +20,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

@@ -21,6 +21,7 @@ __exportStar(require("./commitment.js"), exports);
 __exportStar(require("./operator.js"), exports);
 __exportStar(require("./receipt.js"), exports);
 __exportStar(require("./pool-script.js"), exports);
+__exportStar(require("./owner-pool.js"), exports);
 __exportStar(require("./anchor.js"), exports);
 __exportStar(require("./exit-tx.js"), exports);
 __exportStar(require("./pool.js"), exports);
@@ -35,3 +36,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/owner-pool.d.ts

@@ -0,0 +1,95 @@
+/**
+ * V1 transferable owner-pool covenant.
+ *
+ * A single-owner claim coin whose **current owner is committed in state**, not
+ * in the script. The owner can:
+ *
+ *   - transfer the whole coin by signing a state update that recreates it at
+ *     the same address/amount with a new owner (epoch increments); or
+ *   - exit after `exitBlock` to the committed owner address, with no operator
+ *     signature or liveness.
+ *
+ * The script authenticates the **previous** committed owner
+ * (`SIGNEDBY(PREVSTATE(103))`), so a spender cannot substitute their own key.
+ * `PREVSTATE(104)` is the committed payout address. This is the V1 recovery
+ * path: a recipient holds a coin they can spend unilaterally.
+ */
+import type { OmniaTxDraft, StateValue } from '@totemsdk/omnia';
+export declare const OWNER_POOL_ROOT_PORT = 100;
+export declare const OWNER_POOL_EPOCH_PORT = 101;
+export declare const OWNER_POOL_EXIT_BLOCK_PORT = 102;
+export declare const OWNER_POOL_PK_PORT = 103;
+export declare const OWNER_POOL_ADDR_PORT = 104;
+export interface OwnerPoolState {
+    /** Batch/root commitment (opaque to this covenant; owner cannot change it). */
+    root: string;
+    /** Monotonic state epoch; every transfer increments it. */
+    epoch: number;
+    /** Absolute block after which the committed owner may exit unilaterally. */
+    exitBlock: number;
+    /** Current owner public-key digest (32-byte hex, `0x`-prefixed). */
+    ownerPk: string;
+    /** Current owner payout address (derived from `ownerPk` by the transfer builder). */
+    ownerAddr: string;
+}
+/** Derive the committed payout address from an owner public-key digest. */
+export declare function ownerAddressFor(ownerPk: string): string;
+/**
+ * The transferable owner-pool script. State ports 100–104 are the only state;
+ * there are no fixed holder constants.
+ */
+export declare function buildOwnerPoolScript(): string;
+export declare function buildOwnerPoolState(state: OwnerPoolState): StateValue[];
+export declare function ownerPoolAddress(): string;
+export interface OwnerPoolCoin {
+    coinId: string;
+    address: string;
+    amount: bigint;
+    tokenId: string;
+    scriptHex?: string;
+    mmrEntry?: bigint;
+}
+export interface OwnerTransferParams {
+    /** The coin being transferred (input). */
+    coin: OwnerPoolCoin;
+    /** The previously committed state (must match the input coin's state). */
+    from: OwnerPoolState;
+    /** The new owner. `epoch` must be greater than `from.epoch`. */
+    to: OwnerPoolState;
+}
+/**
+ * Build the transfer transaction: same script address, same amount/token,
+ * new owner state and a higher epoch.
+ */
+export declare function buildOwnerTransferDraft(params: OwnerTransferParams): OmniaTxDraft;
+export interface OwnerExitParams {
+    coin: OwnerPoolCoin;
+    state: OwnerPoolState;
+}
+/** Build the unilateral exit: full amount to the committed owner address. */
+export declare function buildOwnerExitDraft(params: OwnerExitParams): OmniaTxDraft;
+import type { ChainStateProvider } from '@totemsdk/chain-provider';
+export interface OwnerPoolTxDeps {
+    /** Sign the transaction digest with the previous (transfer) or current (exit) owner key. */
+    signDigest: (digest: Uint8Array) => Promise<Uint8Array>;
+    coinProofs?: Uint8Array[];
+    scriptProofs?: Uint8Array[];
+    chainProvider?: ChainStateProvider;
+    mine?: (txBody: Uint8Array, difficulty: Uint8Array) => Promise<{
+        minedHeaderBytes: Uint8Array;
+        txpowId: Uint8Array;
+    }>;
+}
+export interface OwnerPoolTxResult {
+    kind: 'owner-transfer' | 'owner-exit';
+    txHex: string;
+    digest: string;
+    witnessHex: string;
+    txpowId?: string;
+    /** The state committed by the new pool output (transfer) or spent state (exit). */
+    state: OwnerPoolState;
+}
+/** Sign and assemble the owner-rotation transfer transaction. */
+export declare function buildOwnerTransferTransaction(params: OwnerTransferParams, deps: OwnerPoolTxDeps): Promise<OwnerPoolTxResult>;
+/** Sign and assemble the unilateral owner exit transaction. */
+export declare function buildOwnerExitTransaction(params: OwnerExitParams, deps: OwnerPoolTxDeps): Promise<OwnerPoolTxResult>;