@totemsdk/omnia-vtxo 0.6.1 → 0.7.0

package/dist/owner-pool.js

@@ -0,0 +1,183 @@
+/**
+ * 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 { computeScriptAddress, toNodeScript, wotsAddressData } from '@totemsdk/core';
+export const OWNER_POOL_ROOT_PORT = 100;
+export const OWNER_POOL_EPOCH_PORT = 101;
+export const OWNER_POOL_EXIT_BLOCK_PORT = 102;
+export const OWNER_POOL_PK_PORT = 103;
+export const OWNER_POOL_ADDR_PORT = 104;
+/** Derive the committed payout address from an owner public-key digest. */
+export function ownerAddressFor(ownerPk) {
+    return wotsAddressData(ownerPk);
+}
+/**
+ * The transferable owner-pool script. State ports 100–104 are the only state;
+ * there are no fixed holder constants.
+ */
+export function buildOwnerPoolScript() {
+    return 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'));
+}
+export 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: OWNER_POOL_ROOT_PORT, value: state.root, type: 'string' },
+        { port: OWNER_POOL_EPOCH_PORT, value: BigInt(state.epoch), type: 'number' },
+        { port: OWNER_POOL_EXIT_BLOCK_PORT, value: BigInt(state.exitBlock), type: 'number' },
+        { port: OWNER_POOL_PK_PORT, value: state.ownerPk, type: 'string' },
+        { port: OWNER_POOL_ADDR_PORT, value: state.ownerAddr, type: 'string' },
+    ];
+}
+export function ownerPoolAddress() {
+    return computeScriptAddress(buildOwnerPoolScript());
+}
+/**
+ * Build the transfer transaction: same script address, same amount/token,
+ * new owner state and a higher epoch.
+ */
+export 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. */
+export 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 ───────────────────────────────────────────────
+import { computeOmniaTxDigest, omniaDraftToMinimaBytes, serializeOmniaWitness, serializeTxDraft, } from '@totemsdk/omnia';
+import { concatBytes } from '@totemsdk/core';
+import { serializeTxBody, mineTxPoW, TX_POW_MIN_DIFFICULTY } from '@totemsdk/txpow';
+async function assembleOwnerPoolTx(draft, kind, state, deps) {
+    const digest = computeOmniaTxDigest(draft);
+    const signature = await deps.signDigest(digest);
+    const witness = serializeOmniaWitness({
+        signatures: [signature],
+        coinProofs: deps.coinProofs ?? [],
+        scriptProofs: deps.scriptProofs ?? [],
+    });
+    const result = {
+        kind,
+        txHex: serializeTxDraft(draft),
+        digest: Buffer.from(digest).toString('hex'),
+        witnessHex: Buffer.from(witness).toString('hex'),
+        state,
+    };
+    if (deps.chainProvider) {
+        const draftBytes = 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) => 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(`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. */
+export async function buildOwnerTransferTransaction(params, deps) {
+    return assembleOwnerPoolTx(buildOwnerTransferDraft(params), 'owner-transfer', params.to, deps);
+}
+/** Sign and assemble the unilateral owner exit transaction. */
+export async function buildOwnerExitTransaction(params, deps) {
+    return assembleOwnerPoolTx(buildOwnerExitDraft(params), 'owner-exit', params.state, deps);
+}

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

@@ -7,13 +7,13 @@
  * conservation. This prevents a caller from getting the operator to co-sign an
  * arbitrary `(root, epoch, ids)` tuple whose root does not commit the outputs.
  */
-import { computeBatchCommitmentBytes, computeCommitmentRoot, computeVtxoLeaf } from './commitment.js';
+import { computeCommitmentRoot, computeVtxoLeaf, computeVtxoReceiptCommitmentBytes } from './commitment.js';
 /**
  * Co-sign a receipt with the operator, after verifying the batch.
  * @throws if the root does not commit the leaves, the epoch is stale, an output
  * is not in the batch, or conservation fails.
  */
-export async function signVtxoReceipt(operator, receipt, batch) {
+export function buildVtxoReceiptPayload(receipt, batch) {
     if (receipt.epoch !== batch.epoch) {
         throw new Error(`receipt epoch ${receipt.epoch} does not match batch epoch ${batch.epoch}`);
     }
@@ -29,13 +29,19 @@ export 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 = computeBatchCommitmentBytes(receipt.poolId, receipt.epoch, batch.root, receipt.outputIds);
+    return computeVtxoReceiptCommitmentBytes(receipt, batch.root);
+}
+export async function signVtxoReceipt(operator, receipt, batch) {
+    const data = buildVtxoReceiptPayload(receipt, batch);
     const signature = await operator.sign(data);
     return { ...receipt, signature };
 }
@@ -43,6 +49,20 @@ export async function signVtxoReceipt(operator, receipt, batch) {
 export async function verifyVtxoReceipt(operator, receipt, root) {
     if (!receipt.signature)
         return false;
-    const data = computeBatchCommitmentBytes(receipt.poolId, receipt.epoch, root, receipt.outputIds);
+    const data = 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.
+ */
+export 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/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/transfer.js

@@ -1,7 +1,19 @@
 import { VtxoStatusError, VtxoAmountError } from './errors.js';
 import { computeVtxoId, buildVtxoProofSet, computeReceiptId } from './commitment.js';
+import { verifyVtxoExitEntitlement, createVtxoExitEntitlement } from './exit-entitlement.js';
+import { buildExitTransaction } 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 function transferVtxo(vtxo, params, now) {
@@ -15,6 +27,15 @@ export function transferVtxo(vtxo, params, now) {
     if (params.amount > vtxo.amount) {
         throw new VtxoAmountError(`Transfer amount ${params.amount} exceeds VTXO amount ${vtxo.amount}`);
     }
+    if (params.exitEntitlement) {
+        if (params.amount !== vtxo.amount) {
+            throw new VtxoAmountError('exit entitlement requires a full-value transfer');
+        }
+        const check = verifyVtxoExitEntitlement(params.exitEntitlement, vtxo);
+        if (!check.valid) {
+            throw new VtxoAmountError(`invalid exit entitlement: ${check.errors.join('; ')}`);
+        }
+    }
     const isPartial = params.amount < vtxo.amount;
     const changeAmount = vtxo.amount - params.amount;
     const outputId = computeVtxoId({
@@ -59,6 +80,7 @@ export function transferVtxo(vtxo, params, now) {
         tokenId: vtxo.tokenId,
         status: 'active',
         epoch: vtxo.epoch,
+        ...(params.exitEntitlement ? { exitEntitlement: params.exitEntitlement } : {}),
         proof: {
             leaf: '',
             root: '',
@@ -147,3 +169,19 @@ export 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.
+ */
+export async function transferVtxoWithExit(vtxo, params, exitParams, exitDeps, now) {
+    if (exitParams.vtxo.vtxoId !== vtxo.vtxoId) {
+        throw new VtxoAmountError('exit entitlement VTXO does not match transfer input');
+    }
+    if (params.amount !== vtxo.amount) {
+        throw new VtxoAmountError('transferVtxoWithExit requires a full-value transfer');
+    }
+    const exit = await buildExitTransaction(exitParams, exitDeps);
+    const entitlement = createVtxoExitEntitlement(exitParams, exit);
+    const transferred = transferVtxo(vtxo, { ...params, exitEntitlement: entitlement }, now);
+    return { ...transferred, exitEntitlement: entitlement };
+}

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

@@ -0,0 +1,23 @@
+/** Deterministic pro-rata yield distribution for multiparty VTXO/pool claims. */
+export 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totemsdk/omnia-vtxo",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Virtual UTXO / payment-pool claim layer for Omnia — cash-like off-chain balance primitive for Totem Edge",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
@@ -21,14 +21,15 @@
     "rust/pkg/",
     "rust/pkg-node/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "dependencies": {
-    "@totemsdk/core": "^1.4.0",
     "@totemsdk/chain-provider": "^0.3.0",
-    "@totemsdk/omnia": "^2.3.0",
-    "@totemsdk/storage": "^0.1.0",
+    "@totemsdk/core": "^1.4.0",
     "@totemsdk/txpow": "^1.1.0",
+    "@totemsdk/omnia": "^2.3.2",
+    "@totemsdk/storage": "^0.2.1",
     "@totemsdk/wots-lease": "^1.0.1"
   },
   "devDependencies": {
@@ -36,7 +37,8 @@
     "@types/node": "^20.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.0.0",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "@totemsdk/kissvm": "^1.3.0"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -44,7 +46,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "author": "Totem SDK",
   "homepage": "https://docs.totem.ing",
   "bugs": {

package/rust/pkg/package.json

@@ -6,7 +6,7 @@
   ],
   "description": "Virtual UTXO commitment layer — Merkle tree hashing, VTXO ID computation, proof verification, amount conservation (Rust/WASM)",
   "version": "0.1.0",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Totem-Edge/totem-sdk"

package/rust/pkg-node/package.json

@@ -5,7 +5,7 @@
   ],
   "description": "Virtual UTXO commitment layer — Merkle tree hashing, VTXO ID computation, proof verification, amount conservation (Rust/WASM)",
   "version": "0.1.0",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Totem-Edge/totem-sdk"