@totemsdk/omnia-vtxo 0.6.1 → 0.7.0

package/dist/cjs/owner-pool.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OWNER_POOL_ADDR_PORT = exports.OWNER_POOL_PK_PORT = exports.OWNER_POOL_EXIT_BLOCK_PORT = exports.OWNER_POOL_EPOCH_PORT = exports.OWNER_POOL_ROOT_PORT = void 0;
+exports.ownerAddressFor = ownerAddressFor;
+exports.buildOwnerPoolScript = buildOwnerPoolScript;
+exports.buildOwnerPoolState = buildOwnerPoolState;
+exports.ownerPoolAddress = ownerPoolAddress;
+exports.buildOwnerTransferDraft = buildOwnerTransferDraft;
+exports.buildOwnerExitDraft = buildOwnerExitDraft;
+exports.buildOwnerTransferTransaction = buildOwnerTransferTransaction;
+exports.buildOwnerExitTransaction = buildOwnerExitTransaction;
+const core_1 = require("@totemsdk/core");
+exports.OWNER_POOL_ROOT_PORT = 100;
+exports.OWNER_POOL_EPOCH_PORT = 101;
+exports.OWNER_POOL_EXIT_BLOCK_PORT = 102;
+exports.OWNER_POOL_PK_PORT = 103;
+exports.OWNER_POOL_ADDR_PORT = 104;
+/** Derive the committed payout address from an owner public-key digest. */
+function ownerAddressFor(ownerPk) {
+    return (0, core_1.wotsAddressData)(ownerPk);
+}
+/**
+ * The transferable owner-pool script. State ports 100–104 are the only state;
+ * there are no fixed holder constants.
+ */
+function buildOwnerPoolScript() {
+    return (0, core_1.toNodeScript)([
+        // Unilateral exit: only the previously committed owner, only after the
+        // committed block, and only to the committed owner address.
+        'IF @BLOCK GT PREVSTATE(102) THEN',
+        '  ASSERT SIGNEDBY(PREVSTATE(103))',
+        '  ASSERT VERIFYOUT(0 PREVSTATE(104) @AMOUNT @TOKENID FALSE)',
+        '  RETURN TRUE',
+        'ENDIF',
+        // Transfer: the previous owner authorizes a new owner. Root and exit block
+        // are immutable; the coin stays at the same address with the same amount.
+        'ASSERT SIGNEDBY(PREVSTATE(103))',
+        'ASSERT STATE(101) GT PREVSTATE(101)',
+        'ASSERT STATE(100) EQ PREVSTATE(100)',
+        'ASSERT STATE(102) EQ PREVSTATE(102)',
+        'ASSERT STATE(103) NEQ PREVSTATE(103)',
+        'ASSERT STATE(103) NEQ 0x00',
+        'ASSERT STATE(104) NEQ 0x00',
+        'ASSERT VERIFYOUT(0 @ADDRESS @AMOUNT @TOKENID TRUE)',
+        'RETURN TRUE',
+    ].join('\n'));
+}
+function buildOwnerPoolState(state) {
+    if (!Number.isInteger(state.exitBlock) || state.exitBlock < 0) {
+        throw new Error(`owner pool: invalid exitBlock ${String(state.exitBlock)}`);
+    }
+    if (!/^0x[0-9a-fA-F]{64}$/.test(state.ownerPk)) {
+        throw new Error('owner pool: ownerPk must be a 0x-prefixed 32-byte hex digest');
+    }
+    if (!state.ownerAddr)
+        throw new Error('owner pool: ownerAddr is required');
+    return [
+        { port: exports.OWNER_POOL_ROOT_PORT, value: state.root, type: 'string' },
+        { port: exports.OWNER_POOL_EPOCH_PORT, value: BigInt(state.epoch), type: 'number' },
+        { port: exports.OWNER_POOL_EXIT_BLOCK_PORT, value: BigInt(state.exitBlock), type: 'number' },
+        { port: exports.OWNER_POOL_PK_PORT, value: state.ownerPk, type: 'string' },
+        { port: exports.OWNER_POOL_ADDR_PORT, value: state.ownerAddr, type: 'string' },
+    ];
+}
+function ownerPoolAddress() {
+    return (0, core_1.computeScriptAddress)(buildOwnerPoolScript());
+}
+/**
+ * Build the transfer transaction: same script address, same amount/token,
+ * new owner state and a higher epoch.
+ */
+function buildOwnerTransferDraft(params) {
+    if (params.to.epoch <= params.from.epoch) {
+        throw new Error('owner transfer: new epoch must be greater than the previous epoch');
+    }
+    if (params.to.exitBlock !== params.from.exitBlock) {
+        throw new Error('owner transfer: exitBlock is immutable');
+    }
+    if (params.to.ownerAddr !== ownerAddressFor(params.to.ownerPk)) {
+        throw new Error('owner transfer: ownerAddr must be derived from ownerPk');
+    }
+    return {
+        type: 'settlement',
+        inputs: [{
+                coinId: params.coin.coinId,
+                address: params.coin.address,
+                amount: params.coin.amount,
+                tokenId: params.coin.tokenId,
+                scriptHex: params.coin.scriptHex ?? buildOwnerPoolScript(),
+                ...(params.coin.mmrEntry !== undefined ? { mmrEntry: params.coin.mmrEntry } : {}),
+            }],
+        outputs: [{
+                address: params.coin.address,
+                amount: params.coin.amount,
+                tokenId: params.coin.tokenId,
+                storeState: true,
+                stateVariables: buildOwnerPoolState(params.to),
+            }],
+        storeState: true,
+        stateVariables: buildOwnerPoolState(params.to),
+    };
+}
+/** Build the unilateral exit: full amount to the committed owner address. */
+function buildOwnerExitDraft(params) {
+    if (params.state.ownerAddr !== ownerAddressFor(params.state.ownerPk)) {
+        throw new Error('owner exit: ownerAddr must be derived from ownerPk');
+    }
+    return {
+        type: 'settlement',
+        inputs: [{
+                coinId: params.coin.coinId,
+                address: params.coin.address,
+                amount: params.coin.amount,
+                tokenId: params.coin.tokenId,
+                scriptHex: params.coin.scriptHex ?? buildOwnerPoolScript(),
+                ...(params.coin.mmrEntry !== undefined ? { mmrEntry: params.coin.mmrEntry } : {}),
+            }],
+        outputs: [{
+                address: params.state.ownerAddr,
+                amount: params.coin.amount,
+                tokenId: params.coin.tokenId,
+                storeState: false,
+                stateVariables: [],
+            }],
+        storeState: false,
+        stateVariables: [],
+    };
+}
+// ── Signed transaction assembly ───────────────────────────────────────────────
+const omnia_1 = require("@totemsdk/omnia");
+const core_2 = require("@totemsdk/core");
+const txpow_1 = require("@totemsdk/txpow");
+async function assembleOwnerPoolTx(draft, kind, state, deps) {
+    const digest = (0, omnia_1.computeOmniaTxDigest)(draft);
+    const signature = await deps.signDigest(digest);
+    const witness = (0, omnia_1.serializeOmniaWitness)({
+        signatures: [signature],
+        coinProofs: deps.coinProofs ?? [],
+        scriptProofs: deps.scriptProofs ?? [],
+    });
+    const result = {
+        kind,
+        txHex: (0, omnia_1.serializeTxDraft)(draft),
+        digest: Buffer.from(digest).toString('hex'),
+        witnessHex: Buffer.from(witness).toString('hex'),
+        state,
+    };
+    if (deps.chainProvider) {
+        const draftBytes = (0, omnia_1.omniaDraftToMinimaBytes)(draft);
+        if (typeof deps.chainProvider.submitTransaction === 'function') {
+            const submitted = await deps.chainProvider.submitTransaction(draftBytes, witness);
+            if (submitted?.success === false) {
+                throw new Error(`owner-pool submit 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_2.concatBytes)((0, core_2.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(`owner-pool broadcast failed: ${broadcast.message ?? 'unknown error'}`);
+            }
+            result.txpowId = broadcast?.txpowid ?? Buffer.from(mined.txpowId).toString('hex');
+        }
+    }
+    return result;
+}
+/** Sign and assemble the owner-rotation transfer transaction. */
+async function buildOwnerTransferTransaction(params, deps) {
+    return assembleOwnerPoolTx(buildOwnerTransferDraft(params), 'owner-transfer', params.to, deps);
+}
+/** Sign and assemble the unilateral owner exit transaction. */
+async function buildOwnerExitTransaction(params, deps) {
+    return assembleOwnerPoolTx(buildOwnerExitDraft(params), 'owner-exit', params.state, deps);
+}

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;
+}>;

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;