@totemsdk/omnia-vtxo 0.6.1 → 0.6.2

package/dist/index.js

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

package/dist/memory-store.js

@@ -1,4 +1,8 @@
 import { VtxoStatusError } from './errors.js';
+const CONSUMED_STATUSES = new Set(['spent', 'transferred', 'split', 'merged', 'refreshed', 'exited']);
+function isConsumed(status) {
+    return CONSUMED_STATUSES.has(status);
+}
 export class MemoryOmniaVtxoStore {
     constructor() {
         this.pools = new Map();
@@ -11,6 +15,10 @@ export 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 VtxoStatusError(`Cannot resurrect VTXO ${vtxo.vtxoId}: status is '${existing.status}'`, existing.status);
+        }
         this.vtxos.set(vtxo.vtxoId, vtxo);
     }
     async getVtxo(vtxoId) {

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.6.2",
   "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/omnia": "^2.3.2",
+    "@totemsdk/storage": "^0.2.1",
     "@totemsdk/txpow": "^1.1.0",
+    "@totemsdk/chain-provider": "^0.3.0",
     "@totemsdk/wots-lease": "^1.0.1"
   },
   "devDependencies": {
@@ -44,7 +45,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"