@totemsdk/omnia-vtxo 0.6.0 → 0.6.2

package/dist/cjs/transfer.js

@@ -1,10 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.transferVtxo = transferVtxo;
+exports.transferVtxoWithExit = transferVtxoWithExit;
 const errors_js_1 = require("./errors.js");
 const commitment_js_1 = require("./commitment.js");
+const exit_entitlement_js_1 = require("./exit-entitlement.js");
+const exit_tx_js_1 = require("./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.
  */
 function transferVtxo(vtxo, params, now) {
@@ -18,6 +31,15 @@ function transferVtxo(vtxo, params, now) {
     if (params.amount > vtxo.amount) {
         throw new errors_js_1.VtxoAmountError(`Transfer amount ${params.amount} exceeds VTXO amount ${vtxo.amount}`);
     }
+    if (params.exitEntitlement) {
+        if (params.amount !== vtxo.amount) {
+            throw new errors_js_1.VtxoAmountError('exit entitlement requires a full-value transfer');
+        }
+        const check = (0, exit_entitlement_js_1.verifyVtxoExitEntitlement)(params.exitEntitlement, vtxo);
+        if (!check.valid) {
+            throw new errors_js_1.VtxoAmountError(`invalid exit entitlement: ${check.errors.join('; ')}`);
+        }
+    }
     const isPartial = params.amount < vtxo.amount;
     const changeAmount = vtxo.amount - params.amount;
     const outputId = (0, commitment_js_1.computeVtxoId)({
@@ -62,6 +84,7 @@ function transferVtxo(vtxo, params, now) {
         tokenId: vtxo.tokenId,
         status: 'active',
         epoch: vtxo.epoch,
+        ...(params.exitEntitlement ? { exitEntitlement: params.exitEntitlement } : {}),
         proof: {
             leaf: '',
             root: '',
@@ -150,3 +173,19 @@ function transferVtxo(vtxo, params, now) {
         },
     };
 }
+/**
+ * V1 transfer: build the recipient's independent exit before moving the claim,
+ * then transfer only if the exit package verifies against the input VTXO.
+ */
+async function transferVtxoWithExit(vtxo, params, exitParams, exitDeps, now) {
+    if (exitParams.vtxo.vtxoId !== vtxo.vtxoId) {
+        throw new errors_js_1.VtxoAmountError('exit entitlement VTXO does not match transfer input');
+    }
+    if (params.amount !== vtxo.amount) {
+        throw new errors_js_1.VtxoAmountError('transferVtxoWithExit requires a full-value transfer');
+    }
+    const exit = await (0, exit_tx_js_1.buildExitTransaction)(exitParams, exitDeps);
+    const entitlement = (0, exit_entitlement_js_1.createVtxoExitEntitlement)(exitParams, exit);
+    const transferred = transferVtxo(vtxo, { ...params, exitEntitlement: entitlement }, now);
+    return { ...transferred, exitEntitlement: entitlement };
+}

package/dist/cjs/types.d.ts

@@ -1,3 +1,5 @@
+import type { VtxoClaimPolicy } from './claim-policy.js';
+import type { VtxoExitEntitlement } from './exit-entitlement.js';
 export type VtxoId = string;
 export type VtxoStatus = 'active' | 'transferred' | 'split' | 'merged' | 'refreshed' | 'exiting' | 'exited' | 'spent' | 'expired' | 'invalid';
 export type VtxoOp = 'mint' | 'transfer' | 'split' | 'merge' | 'refresh' | 'exit_initiated' | 'exit_complete' | 'spent';
@@ -50,6 +52,10 @@ export interface OmniaVtxo {
     expiresAt?: number;
     /** The on-chain funding proof recorded at mint (deep proof, #28). */
     fundingProof?: unknown;
+    /** Opt-in multiparty claim policy (M8–M18). */
+    claimPolicy?: VtxoClaimPolicy;
+    /** V1: independently executable exit package delivered to the owner. */
+    exitEntitlement?: VtxoExitEntitlement;
     /** Set when an exit draft consumed this VTXO — prevents double-exit. */
     exitConsumedAt?: number;
     exitReceiptId?: string;
@@ -99,6 +105,8 @@ export interface TransferVtxoParams {
     amount: bigint;
     nonce: string;
     changeNonce?: string;
+    /** V1: exit package the recipient must receive with the claim. */
+    exitEntitlement?: VtxoExitEntitlement;
 }
 export interface SplitVtxoParams {
     amounts: bigint[];

package/dist/cjs/yield.d.ts

@@ -0,0 +1,2 @@
+/** Deterministic pro-rata yield distribution for multiparty VTXO/pool claims. */
+export declare function distributeYield(total: bigint, weights: Record<string, bigint>): Record<string, bigint>;

package/dist/cjs/yield.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.distributeYield = distributeYield;
+/** Deterministic pro-rata yield distribution for multiparty VTXO/pool claims. */
+function distributeYield(total, weights) {
+    if (total < 0n)
+        throw new Error('yield total must be non-negative');
+    const entries = Object.entries(weights).filter(([, weight]) => weight > 0n);
+    if (entries.length === 0)
+        throw new Error('yield requires positive weights');
+    const denominator = entries.reduce((sum, [, weight]) => sum + weight, 0n);
+    if (denominator <= 0n)
+        throw new Error('yield weight sum must be positive');
+    const out = {};
+    let allocated = 0n;
+    for (const [id, weight] of entries) {
+        const share = (total * weight) / denominator;
+        out[id] = share;
+        allocated += share;
+    }
+    // Deterministic remainder assignment to the first entry.
+    const remainder = total - allocated;
+    if (remainder > 0n)
+        out[entries[0][0]] += remainder;
+    return out;
+}

package/dist/claim-policy.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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).
+ */
+import type { OmniaVtxo } from './types.js';
+export interface VtxoPolicyBinding {
+    poolId?: string;
+    tokenId?: string;
+}
+export type VtxoClaimPolicy = ({
+    type: 'single';
+    owner: string;
+} | {
+    type: 'threshold';
+    threshold: number;
+    owners: string[];
+} | {
+    type: 'conditional';
+    owner: string;
+    refundOwner: string;
+    hashlock: string;
+    timeoutBlock: number;
+} | {
+    type: 'dvp';
+    owner: string;
+    counterparty: string;
+    paymentId: string;
+    hashlock: string;
+    timeoutBlock: number;
+} | {
+    type: 'delegated';
+    owner: string;
+    delegate: string;
+    scope: 'claim' | 'transfer';
+    expiresAtBlock: number;
+    revoked?: boolean;
+} | {
+    type: 'rotation';
+    fromOperator: string;
+    toOperator: string;
+    rotateAtBlock: number;
+} | {
+    type: 'vesting';
+    owner: string;
+    beneficiary: string;
+    startBlock: number;
+    cliffBlock: number;
+    endBlock: number;
+} | {
+    type: 'recovery';
+    owner: string;
+    guardians: string[];
+    threshold: number;
+    recoverAfterBlock: number;
+} | {
+    type: 'collateral';
+    owner: string;
+    counterparty: string;
+    releaseAtBlock?: number;
+}) & {
+    binding?: VtxoPolicyBinding;
+};
+export interface VtxoClaimWitness {
+    signers: string[];
+    preimage?: string;
+    /** 'claim' (before timeout) or 'refund' (after timeout). */
+    path?: 'claim' | 'refund';
+    /** Delegated policy scope being exercised. */
+    scope?: 'claim' | 'transfer';
+    /** Vesting claim amount. */
+    claimAmount?: bigint;
+}
+export interface VtxoClaimContext {
+    block: number;
+    poolId?: string;
+    tokenId?: string;
+    htlc?: {
+        paymentId: string;
+        hashlock: string;
+        status: 'pending' | 'fulfilled' | 'timed_out';
+    };
+}
+export interface VtxoClaimResult {
+    valid: boolean;
+    error?: string;
+}
+export declare function verifyClaimPolicy(policy: VtxoClaimPolicy, witness: VtxoClaimWitness, ctx: VtxoClaimContext): VtxoClaimResult;
+/** Resolve the policy attached to a VTXO, defaulting to its single owner. */
+export declare function claimPolicyOf(vtxo: OmniaVtxo): VtxoClaimPolicy;
+export declare function verifyVtxoClaim(vtxo: OmniaVtxo, witness: VtxoClaimWitness, ctx: VtxoClaimContext): VtxoClaimResult;

package/dist/claim-policy.js

@@ -0,0 +1,144 @@
+/**
+ * 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).
+ */
+import { HTLCHelper } from '@totemsdk/core';
+function uniqueSigners(signers) {
+    return [...new Set(signers)];
+}
+function preimageMatches(preimage, hashlock) {
+    if (!preimage)
+        return false;
+    try {
+        return HTLCHelper.verifyPreimage(preimage, hashlock, 'sha3');
+    }
+    catch {
+        return false;
+    }
+}
+export 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. */
+export function claimPolicyOf(vtxo) {
+    return vtxo.claimPolicy
+        ?? { type: 'single', owner: vtxo.owner };
+}
+export function verifyVtxoClaim(vtxo, witness, ctx) {
+    if (witness.signers.length === 0)
+        return { valid: false, error: 'no signers' };
+    return verifyClaimPolicy(claimPolicyOf(vtxo), witness, ctx);
+}

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

@@ -5,6 +5,7 @@ export const VTXO_ID_DOMAIN = 'totemsdk/omnia-vtxo/vtxo/v1';
 export const VTXO_POOL_ID_DOMAIN = 'totemsdk/omnia-vtxo/pool/v1';
 export const VTXO_LEAF_DOMAIN = 'totemsdk/omnia-vtxo/leaf/v1';
 export const VTXO_RECEIPT_DOMAIN = 'totemsdk/omnia-vtxo/receipt/v1';
+export const VTXO_RECEIPT_BINDING_DOMAIN = 'totemsdk/omnia-vtxo/receipt-binding/v1';
 export const VTXO_BATCH_DOMAIN = 'totemsdk/omnia-vtxo/batch/v1';
 /**
  * Canonical batch commitment (RFC-038 §3.2): the operator signs this over the
@@ -13,6 +14,23 @@ export const VTXO_BATCH_DOMAIN = 'totemsdk/omnia-vtxo/batch/v1';
 export function computeBatchCommitment(poolId, epoch, root, orderedIds) {
     return sha3hex(`${VTXO_BATCH_DOMAIN}|${poolId}|${epoch}|${root}|${[...orderedIds].join(',')}`);
 }
+/** Receipt commitment binds every semantically relevant receipt field. */
+export function computeVtxoReceiptCommitment(receipt, root) {
+    return sha3hex([
+        VTXO_RECEIPT_BINDING_DOMAIN,
+        receipt.poolId,
+        receipt.epoch.toString(),
+        root,
+        receipt.receiptId,
+        receipt.op,
+        [...receipt.inputIds].join(','),
+        [...receipt.outputIds].join(','),
+        receipt.at.toString(),
+    ].join('|'));
+}
+export function computeVtxoReceiptCommitmentBytes(receipt, root) {
+    return hexToBytes(computeVtxoReceiptCommitment(receipt, root));
+}
 /** The 32-byte digest of a batch commitment, for signing. */
 export function computeBatchCommitmentBytes(poolId, epoch, root, orderedIds) {
     return hexToBytes(computeBatchCommitment(poolId, epoch, root, orderedIds));

package/dist/durable-store.js

@@ -11,6 +11,10 @@ import { createRevisionedSnapshotStore, } from '@totemsdk/storage/snapshot';
 import { StorageError } from '@totemsdk/storage/errors';
 import { VtxoStatusError } from './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 StorageError('omnia-vtxo registry state is not an object', 'corrupt');
@@ -44,6 +48,10 @@ export 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 VtxoStatusError(`Cannot resurrect VTXO ${vtxo.vtxoId}: status is '${existing.status}'`, existing.status);
+                }
                 const vtxos = { ...state.vtxos, [vtxo.vtxoId]: vtxo };
                 return { ...state, vtxos };
             });

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

@@ -0,0 +1,66 @@
+/**
+ * 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 { deserializeTxDraft } from '@totemsdk/omnia';
+import { exitTransactionDigest } from './exit-tx.js';
+export 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,
+    };
+}
+export 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 = deserializeTxDraft(entitlement.txHex);
+            const digest = Buffer.from(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/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/exit-tx.js

@@ -11,7 +11,7 @@
  * The caller must pass the holder signer; neither the operator nor another holder
  * can build a valid witness for this holder's share.
  */
-import { computeOmniaTxDigest, omniaDraftToMinimaBytes, serializeTxDraft, } from '@totemsdk/omnia';
+import { computeOmniaTxDigest, serializeOmniaWitness, omniaDraftToMinimaBytes, serializeTxDraft, } from '@totemsdk/omnia';
 import { serializeTxBody, mineTxPoW, TX_POW_MIN_DIFFICULTY } from '@totemsdk/txpow';
 import { concatBytes, wotsAddressData } from '@totemsdk/core';
 import { poolStateVariables } from './anchor.js';
@@ -32,14 +32,17 @@ export function buildExitTransactionDraft(params) {
             stateVariables: [],
         }];
     const carriesState = params.amount > share;
+    const remaining = params.shares.map((s, i) => (i === params.holderIndex ? 0n : s));
+    const exitState = carriesState
+        ? poolStateVariables(params.root, params.epoch, params.exitBlock, remaining)
+        : 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: poolStateVariables(params.root, params.epoch, params.exitBlock, remaining),
+            stateVariables: exitState,
         });
     }
     return {
@@ -50,10 +53,11 @@ export 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,
     };
 }
 export function exitTransactionDigest(draft) {
@@ -67,6 +71,11 @@ export async function buildExitTransaction(params, deps) {
     const draft = buildExitTransactionDraft(params);
     const digest = exitTransactionDigest(draft);
     const signature = await deps.signDigest(digest);
+    const witness = serializeOmniaWitness({
+        signatures: [signature],
+        coinProofs: deps.coinProofs ?? [],
+        scriptProofs: deps.scriptProofs ?? [],
+    });
     const result = {
         vtxoId: params.vtxo.vtxoId,
         owner: params.vtxo.owner,
@@ -74,16 +83,28 @@ export 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) => mineTxPoW(txBody, difficulty));
         const draftBytes = omniaDraftToMinimaBytes(draft);
-        const txBody = serializeTxBody(draftBytes, signature);
-        const mined = await mine(txBody, TX_POW_MIN_DIFFICULTY);
-        const fullTxPoW = concatBytes(concatBytes(mined.minedHeaderBytes, new Uint8Array([0x01])), txBody);
-        await deps.chainProvider.broadcastTxPoW(Buffer.from(fullTxPoW).toString('hex'));
-        result.txpowId = Buffer.from(mined.txpowId).toString('hex');
+        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) => mineTxPoW(txBody, difficulty));
+            const txBody = serializeTxBody(draftBytes, witness);
+            const mined = await mine(txBody, TX_POW_MIN_DIFFICULTY);
+            const fullTxPoW = concatBytes(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/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';