@totemsdk/omnia-vtxo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Totem SDK Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+# `@totemsdk/omnia-vtxo`
+
+Virtual UTXO (vTXO) / payment-pool claim layer for the Totem Edge ecosystem.
+
+## What is Omnia VTXO?
+
+`@totemsdk/omnia-vtxo` is a **cash-like off-chain balance primitive** that gives Totem Edge applications a way to hold, transfer, split, merge, and exit token balances without requiring a live Minima node for every operation. Each VTXO (Virtual Transaction Output) is a claim on a pool of on-chain capacity, backed by a deterministic Merkle commitment tree.
+
+Think of it as a bearer note inside a shared liquidity pool. The pool operator holds the on-chain UTXO; the holder holds the VTXO proof.
+
+### How it differs from Statechains
+
+| | Statechain | Omnia VTXO |
+|---|---|---|
+| Ownership transfer | Blind SE co-signature | Pure functional, no live signing needed |
+| Privacy model | Blind Mercury SE | Local commitment root |
+| Splitting | Not supported | Supported natively |
+| Merging | Not supported | Supported natively |
+| Exit model | On-chain UTXO handoff | Pool epoch settlement |
+| Use case | Privacy UTXO custody | Merchant receipts, credits, pool liquidity |
+
+### Relation to other `@totemsdk` packages
+
+```
+@totemsdk/omnia              ← L2 channel layer (eltoo state machine)
+@totemsdk/omnia-factory      ← N-of-N funding factory
+@totemsdk/omnia-vtxo         ← Virtual UTXO claim layer (this package)
+@totemsdk/statechain         ← Mercury off-chain ownership records
+```
+
+## Install
+
+```bash
+pnpm add @totemsdk/omnia-vtxo @noble/hashes
+```
+
+## Import
+
+```ts
+import {
+  createPool,
+  mintVtxo,
+  transferVtxo,
+  splitVtxo,
+  mergeVtxos,
+  refreshVtxo,
+  createExitDraft,
+  verifyVtxo,
+  verifyConservation,
+  MemoryOmniaVtxoStore,
+  serializeVtxo,
+  deserializeVtxo,
+} from '@totemsdk/omnia-vtxo';
+```
+
+## Full Lifecycle Example
+
+```ts
+import {
+  createPool,
+  mintVtxo,
+  transferVtxo,
+  splitVtxo,
+  mergeVtxos,
+  refreshVtxo,
+  createExitDraft,
+  markExiting,
+  markExited,
+  verifyVtxo,
+  verifyConservation,
+  MemoryOmniaVtxoStore,
+} from '@totemsdk/omnia-vtxo';
+
+const NOW = Date.now();
+
+// 1. Create a pool (deterministic — poolId derived from operator + tokenId + nonce)
+const pool = createPool({
+  operator: 'MxOperatorAddress',
+  tokenId: '0x00',         // Minima native token
+  totalCapacity: BigInt(1_000_000_000),
+  nonce: 'pool-genesis-v1',
+}, NOW);
+
+// 2. Mint a VTXO (reduces pool.availableCapacity)
+const { pool: p1, vtxo: note, receipt: mintReceipt } = mintVtxo(
+  pool,
+  { owner: 'MxAlice', amount: BigInt(100_000), nonce: 'note-1' },
+  NOW,
+);
+
+// 3. Transfer the note to Bob (full transfer: note → transferred, bobNote → active)
+const { input: spentNote, output: bobNote, transfer } = transferVtxo(
+  note,
+  { recipient: 'MxBob', amount: BigInt(100_000), nonce: 'tx-1' },
+  NOW + 1,
+);
+
+// 4. Split Bob's note into two pieces
+const { input: splitInput, outputs: [piece1, piece2] } = splitVtxo(
+  bobNote,
+  { amounts: [BigInt(60_000), BigInt(40_000)], nonces: ['sp-1', 'sp-2'] },
+  NOW + 2,
+);
+
+// 5. Merge the two pieces back together
+const { output: mergedNote } = mergeVtxos(
+  [piece1, piece2],
+  { nonce: 'mg-1', owner: 'MxBob' },
+  NOW + 3,
+);
+
+// 6. Refresh the note to a new epoch (re-anchor against pool epoch)
+const { old: staleNote, refreshed: freshNote } = refreshVtxo(
+  mergedNote,
+  { newEpoch: 1, nonce: 'ref-1' },
+  NOW + 4,
+);
+
+// 7. Create a mock exit draft
+const { draft, receipt: exitReceipt } = createExitDraft(freshNote, NOW + 5);
+console.log('Exit draft type:', draft.draftType); // 'mock-exit'
+
+// 8. Verify proofs and conservation
+const vtxoCheck = verifyVtxo(freshNote);
+console.log('VTXO valid:', vtxoCheck.valid);
+
+const conservation = verifyConservation({
+  inputs: [note],
+  outputs: [spentNote],   // full transfer: input sum must equal output sum
+});
+
+// 9. Persist with MemoryOmniaVtxoStore
+const store = new MemoryOmniaVtxoStore();
+await store.savePool(p1);
+await store.saveVtxo(freshNote);
+const loaded = await store.getVtxo(freshNote.vtxoId);
+```
+
+## API Reference
+
+### Pool
+
+| Function | Description |
+|---|---|
+| `createPool(params, now)` | Creates a new VTXO pool. `poolId` is deterministic from `operator + tokenId + nonce`. Never calls `Date.now()` internally. |
+| `assertPoolCanMint(pool, amount)` | Validates capacity and policy. Throws `VtxoPoolCapacityError` or `VtxoPolicyError`. |
+| `updatePoolRoot(pool, root)` | Returns a new pool with an updated commitment root (immutable). |
+| `advancePoolEpoch(pool, newEpoch)` | Advances epoch; throws if `newEpoch <= pool.epoch`. |
+
+### VTXO Lifecycle
+
+| Function | Status transition | Notes |
+|---|---|---|
+| `mintVtxo(pool, params, now)` | — → `active` | Reduces `pool.availableCapacity`. |
+| `transferVtxo(vtxo, params, now)` | `active` → `transferred`/`split` | Full: input `transferred`, output `active`. Partial: input `split`, output+change `active`. |
+| `splitVtxo(vtxo, params, now)` | `active` → `split` | Outputs `active`. Sum must equal input amount. |
+| `mergeVtxos(vtxos, params, now)` | `active[]` → `merged` | Output `active`. Rejects duplicate IDs. Same pool+token required. |
+| `refreshVtxo(vtxo, params, now)` | `active` → `refreshed` | New VTXO `active` with higher epoch. |
+| `markExiting(vtxo, now)` | `active` → `exiting` | Initiates unilateral exit. |
+| `markExited(vtxo, now)` | `exiting` → `exited` | Finalises exit. |
+| `createExitDraft(vtxo, now)` | — | Returns `draftType: 'mock-exit'` and a receipt. |
+| `markVtxoSpent(vtxo, now)` | `active` → `spent` | Direct spend (used by operator settlement). |
+
+### Verification & Conservation
+
+```ts
+verifyVtxo(vtxo)                          // validate fields + proof
+verifyVtxoProof(vtxo, proof)              // verify Merkle path
+verifyVtxoTransfer(input, output, tx)     // validate transfer struct
+verifyConservation({ inputs, outputs })   // sum(inputs) must equal sum(outputs)
+```
+
+### Serialization (BigInt-safe)
+
+```ts
+serializeVtxo(vtxo)    // → JSON string (BigInt serialized as "__bigint__:<value>")
+deserializeVtxo(json)  // → OmniaVtxo (BigInt restored)
+serializePool(pool)    // → JSON string
+deserializePool(json)  // → OmniaVtxoPool
+```
+
+### Store Interface
+
+`OmniaVtxoStore` is a simple async interface:
+
+```ts
+interface OmniaVtxoStore {
+  savePool(pool): Promise<void>;
+  getPool(poolId): Promise<OmniaVtxoPool | undefined>;
+  saveVtxo(vtxo): Promise<void>;
+  getVtxo(vtxoId): Promise<OmniaVtxo | undefined>;
+  listVtxos(poolId?): Promise<OmniaVtxo[]>;
+  markVtxoSpent(vtxoId, now?): Promise<void>;
+}
+```
+
+`MemoryOmniaVtxoStore` ships as the in-memory MVP implementation.
+
+### Policy Helpers
+
+```ts
+buildVtxoTransferIntent(vtxo, recipient, amount, nonce, changeNonce?)
+buildVtxoExitIntent(vtxo)
+```
+
+## VtxoStatus State Machine
+
+```
+        ┌──────── mint ────────┐
+        ▼                     │
+     active ──transfer──► transferred
+        │
+        ├─ partial-transfer ──► split  (input)
+        │                       │
+        ├─ split ────────────► split  (input)
+        │
+        ├─ merge ────────────► merged (inputs)
+        │
+        ├─ refresh ──────────► refreshed (old)
+        │
+        ├─ exit_initiated ───► exiting
+        │                         │
+        │                      exited
+        └─ spent ──────────── spent
+```
+
+## Error Hierarchy
+
+```
+OmniaVtxoError
+  ├── VtxoAmountError       — invalid amounts (zero, overflow, sum mismatch)
+  ├── VtxoStatusError       — wrong status for the requested operation
+  ├── VtxoOwnershipError    — owner mismatch
+  ├── VtxoProofError        — Merkle proof verification failure
+  ├── VtxoPoolCapacityError — insufficient pool capacity
+  ├── VtxoPolicyError       — policy violation (min/max amounts, epoch ordering)
+  ├── VtxoMergeError        — merge precondition failure (cross-pool, duplicates)
+  ├── VtxoSplitError        — split precondition failure
+  └── VtxoExitError         — exit precondition failure
+```
+
+## Security Notes
+
+> **This is an MVP SDK — not a production Ark implementation.**
+
+The current implementation provides deterministic, locally-verifiable commitment proofs, but several critical components are stubs:
+
+- **Operator receipts** are signed with `MOCK_OPERATOR_SIGNATURE`. In production, the operator signs over the commitment root using a real WOTS or Schnorr key, and clients must verify against the operator's published public key.
+- **Commitment roots** are single-batch local roots, not pool-wide epoch roots. A full deployment requires the operator to broadcast a pool-wide commitment root across all live VTXOs each epoch, giving every holder a verifiable place in the pool's state tree.
+- **Exit scripts** use `draftType: 'mock-exit'`. Real exits require audited KISSVM covenant exit scripts, a watchtower monitoring the on-chain dispute window, and Omnia factory settlement logic.
+- **No watchtower / dispute monitoring.** Operator equivocation (signing two conflicting pool roots) is not detected. A production system needs an independent watchtower service.
+- **No replay protection beyond nonce uniqueness.** Nonces must be globally unique per pool. Implementations must enforce this.
+
+## Future Roadmap
+
+- **Real Omnia factory backing** — Pool funds held in an N-of-N Omnia factory UTXO, with batch settlement on exit.
+- **Batch refresh rounds** — Operator posts a new commitment root; all live VTXOs are refreshed in a single Minima transaction.
+- **Operator signing** — Real WOTS receipts replacing `MOCK_OPERATOR_SIGNATURE`, with client-side signature verification.
+- **Wallet integration** — Direct integration with Totem Wallet's coin selection and WOTS signing infrastructure.
+- **Connect API methods** — `totem_mintVtxo`, `totem_transferVtxo`, `totem_listVtxos` exposed via the TOTEM_CONNECT dApp API.
+- **Persistence adapters** — PostgreSQL and IndexedDB adapters for `OmniaVtxoStore`.
+- **KISSVM exit script** — Audited on-chain exit covenant for unilateral exit with timelock enforcement.
+
+## Canary Scenario
+
+```ts
+// Create pool → mint note → transfer → split → merge → refresh → exit → verify
+
+const pool = createPool({ operator, tokenId, totalCapacity, nonce }, NOW);
+const { pool: p1, vtxo: note } = mintVtxo(pool, { owner, amount, nonce: 'n1' }, NOW);
+const { output: received } = transferVtxo(note, { recipient: 'MxBob', amount, nonce: 'n2' }, NOW + 1);
+const { outputs: [a, b] } = splitVtxo(received, { amounts: [amount / 2n, amount / 2n], nonces: ['n3', 'n4'] }, NOW + 2);
+const { output: merged } = mergeVtxos([a, b], { nonce: 'n5', owner: 'MxBob' }, NOW + 3);
+const { refreshed } = refreshVtxo(merged, { newEpoch: 1, nonce: 'n6' }, NOW + 4);
+const { draft } = createExitDraft(refreshed, NOW + 5);
+
+const check = verifyVtxo(refreshed);
+const conservation = verifyConservation({ inputs: [note], outputs: [received] });
+
+console.assert(check.valid, 'VTXO proof must be valid');
+console.assert(conservation.valid, 'Conservation must hold');
+console.assert(draft.draftType === 'mock-exit', 'Exit draft type must be mock-exit');
+```
+
+## Runtime Compatibility
+
+This package is **runtime-neutral** and compatible with Bare/Pear-style Totem Edge deployments. It does not import `node:crypto`, `fs`, `path`, `net`, `http`, `child_process`, DOM APIs, `window`, `document`, or `localStorage`. All deterministic functions accept injected `now` and `nonce` parameters — no hidden `Date.now()` or `randomUUID()` calls inside pure logic.
+
+The only runtime dependency is `@noble/hashes` (SHA3-256), which is itself runtime-neutral and browser/Bare-compatible.
+
+## License
+
+MIT

package/dist/commitment.d.ts

@@ -0,0 +1,28 @@
+import { OmniaVtxo, VtxoId, VtxoProof } from './types.js';
+export declare function computeVtxoLeaf(vtxo: OmniaVtxo): string;
+export interface ComputeVtxoIdParams {
+    poolId: string;
+    owner: string;
+    amount: bigint;
+    tokenId: string;
+    nonce: string;
+}
+export declare function computeVtxoId(params: ComputeVtxoIdParams): string;
+export interface ComputePoolIdParams {
+    operator: string;
+    tokenId: string;
+    nonce: string;
+}
+export declare function computePoolId(params: ComputePoolIdParams): string;
+export declare function computeCommitmentRoot(leaves: string[]): string;
+export interface MerkleProofNode {
+    sibling: string;
+    position: 'left' | 'right';
+}
+export declare function verifyMerkleProof(leaf: string, proof: MerkleProofNode[], root: string): boolean;
+export interface VtxoProofSet {
+    root: string;
+    proofs: Record<VtxoId, VtxoProof>;
+}
+export declare function buildVtxoProofSet(vtxos: OmniaVtxo[]): VtxoProofSet;
+export declare function computeReceiptId(poolId: string, op: string, inputIds: string[], outputIds: string[], at: number): string;

package/dist/commitment.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeVtxoLeaf = computeVtxoLeaf;
+exports.computeVtxoId = computeVtxoId;
+exports.computePoolId = computePoolId;
+exports.computeCommitmentRoot = computeCommitmentRoot;
+exports.verifyMerkleProof = verifyMerkleProof;
+exports.buildVtxoProofSet = buildVtxoProofSet;
+exports.computeReceiptId = computeReceiptId;
+const sha3_1 = require("@noble/hashes/sha3");
+const utils_1 = require("@noble/hashes/utils");
+const constants_js_1 = require("./constants.js");
+function sha3hex(input) {
+    const bytes = new TextEncoder().encode(input);
+    return (0, utils_1.bytesToHex)((0, sha3_1.sha3_256)(bytes));
+}
+function hashPair(a, b) {
+    const [left, right] = a <= b ? [a, b] : [b, a];
+    const combined = left + right;
+    const bytes = (0, utils_1.hexToBytes)(combined);
+    return (0, utils_1.bytesToHex)((0, sha3_1.sha3_256)(bytes));
+}
+function computeVtxoLeaf(vtxo) {
+    const input = [
+        vtxo.vtxoId,
+        vtxo.owner,
+        vtxo.amount.toString(),
+        vtxo.tokenId,
+        vtxo.epoch.toString(),
+        vtxo.poolId,
+    ].join(':');
+    return sha3hex(input);
+}
+function computeVtxoId(params) {
+    const input = [
+        'vtxo',
+        params.poolId,
+        params.owner,
+        params.amount.toString(),
+        params.tokenId,
+        params.nonce,
+    ].join(':');
+    return sha3hex(input);
+}
+function computePoolId(params) {
+    const input = [
+        'pool',
+        params.operator,
+        params.tokenId,
+        params.nonce,
+    ].join(':');
+    return sha3hex(input);
+}
+function nextPowerOfTwo(n) {
+    if (n <= 1)
+        return 1;
+    let p = 1;
+    while (p < n)
+        p <<= 1;
+    return p;
+}
+function computeCommitmentRoot(leaves) {
+    if (leaves.length === 0)
+        return constants_js_1.EMPTY_LEAF;
+    const size = nextPowerOfTwo(leaves.length);
+    const level = new Array(size).fill(constants_js_1.EMPTY_LEAF);
+    for (let i = 0; i < leaves.length; i++) {
+        level[i] = leaves[i];
+    }
+    let current = level;
+    while (current.length > 1) {
+        const next = [];
+        for (let i = 0; i < current.length; i += 2) {
+            next.push(hashPair(current[i], current[i + 1]));
+        }
+        current = next;
+    }
+    return current[0];
+}
+function verifyMerkleProof(leaf, proof, root) {
+    let current = leaf;
+    for (const node of proof) {
+        if (node.position === 'left') {
+            current = hashPair(node.sibling, current);
+        }
+        else {
+            current = hashPair(current, node.sibling);
+        }
+    }
+    return current === root;
+}
+function buildVtxoProofSet(vtxos) {
+    if (vtxos.length === 0) {
+        return { root: constants_js_1.EMPTY_LEAF, proofs: {} };
+    }
+    const sorted = [...vtxos].sort((a, b) => a.vtxoId < b.vtxoId ? -1 : a.vtxoId > b.vtxoId ? 1 : 0);
+    const leafMap = new Map();
+    const leaves = sorted.map(v => {
+        const leaf = computeVtxoLeaf(v);
+        leafMap.set(v.vtxoId, leaf);
+        return leaf;
+    });
+    const size = nextPowerOfTwo(leaves.length);
+    const paddedLeaves = [...leaves];
+    while (paddedLeaves.length < size)
+        paddedLeaves.push(constants_js_1.EMPTY_LEAF);
+    const levels = [paddedLeaves];
+    let current = paddedLeaves;
+    while (current.length > 1) {
+        const next = [];
+        for (let i = 0; i < current.length; i += 2) {
+            next.push(hashPair(current[i], current[i + 1]));
+        }
+        levels.push(next);
+        current = next;
+    }
+    const root = current[0];
+    const proofs = {};
+    sorted.forEach((vtxo, idx) => {
+        const siblings = [];
+        const positions = [];
+        let pos = idx;
+        for (let lvl = 0; lvl < levels.length - 1; lvl++) {
+            const isLeft = pos % 2 === 0;
+            const siblingIdx = isLeft ? pos + 1 : pos - 1;
+            const sibling = levels[lvl][siblingIdx] ?? constants_js_1.EMPTY_LEAF;
+            siblings.push(sibling);
+            positions.push(isLeft ? 'right' : 'left');
+            pos = Math.floor(pos / 2);
+        }
+        const leaf = leafMap.get(vtxo.vtxoId);
+        proofs[vtxo.vtxoId] = {
+            leaf,
+            root,
+            siblings,
+            positions,
+            epoch: vtxo.epoch,
+            batchId: constants_js_1.MOCK_BATCH_ID,
+        };
+    });
+    return { root, proofs };
+}
+function computeReceiptId(poolId, op, inputIds, outputIds, at) {
+    const input = [
+        'receipt',
+        poolId,
+        op,
+        inputIds.sort().join(','),
+        outputIds.sort().join(','),
+        at.toString(),
+    ].join(':');
+    return sha3hex(input);
+}

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const EMPTY_LEAF = "0000000000000000000000000000000000000000000000000000000000000000";
+export declare const EMPTY_TREE_ROOT = "0000000000000000000000000000000000000000000000000000000000000000";
+export declare const EPOCH_ZERO = 0;
+export declare const DEFAULT_POLICY: {
+    readonly minAmount: bigint;
+    readonly maxAmount: bigint;
+    readonly maxMergeInputs: 8;
+    readonly maxSplitOutputs: 8;
+    readonly exitTimelockSeconds: 86400;
+};
+export declare const MOCK_OPERATOR_SIGNATURE = "mock-operator-sig-v0";
+export declare const MOCK_BATCH_ID = "batch-local-mvp";

package/dist/constants.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOCK_BATCH_ID = exports.MOCK_OPERATOR_SIGNATURE = exports.DEFAULT_POLICY = exports.EPOCH_ZERO = exports.EMPTY_TREE_ROOT = exports.EMPTY_LEAF = void 0;
+exports.EMPTY_LEAF = '0000000000000000000000000000000000000000000000000000000000000000';
+exports.EMPTY_TREE_ROOT = '0000000000000000000000000000000000000000000000000000000000000000';
+exports.EPOCH_ZERO = 0;
+exports.DEFAULT_POLICY = {
+    minAmount: BigInt(1),
+    maxAmount: BigInt(1000000000000000),
+    maxMergeInputs: 8,
+    maxSplitOutputs: 8,
+    exitTimelockSeconds: 86400,
+};
+exports.MOCK_OPERATOR_SIGNATURE = 'mock-operator-sig-v0';
+exports.MOCK_BATCH_ID = 'batch-local-mvp';

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+export declare class OmniaVtxoError extends Error {
+    constructor(message: string);
+}
+export declare class VtxoAmountError extends OmniaVtxoError {
+    constructor(message: string);
+}
+export declare class VtxoStatusError extends OmniaVtxoError {
+    readonly currentStatus: string;
+    constructor(message: string, currentStatus: string);
+}
+export declare class VtxoOwnershipError extends OmniaVtxoError {
+    constructor(message: string);
+}
+export declare class VtxoProofError extends OmniaVtxoError {
+    constructor(message: string);
+}
+export declare class VtxoPoolCapacityError extends OmniaVtxoError {
+    readonly requested: bigint;
+    readonly available: bigint;
+    constructor(message: string, requested: bigint, available: bigint);
+}
+export declare class VtxoPolicyError extends OmniaVtxoError {
+    constructor(message: string);
+}
+export declare class VtxoMergeError extends OmniaVtxoError {
+    constructor(message: string);
+}
+export declare class VtxoSplitError extends OmniaVtxoError {
+    constructor(message: string);
+}
+export declare class VtxoExitError extends OmniaVtxoError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VtxoExitError = exports.VtxoSplitError = exports.VtxoMergeError = exports.VtxoPolicyError = exports.VtxoPoolCapacityError = exports.VtxoProofError = exports.VtxoOwnershipError = exports.VtxoStatusError = exports.VtxoAmountError = exports.OmniaVtxoError = void 0;
+class OmniaVtxoError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OmniaVtxoError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.OmniaVtxoError = OmniaVtxoError;
+class VtxoAmountError extends OmniaVtxoError {
+    constructor(message) {
+        super(message);
+        this.name = 'VtxoAmountError';
+    }
+}
+exports.VtxoAmountError = VtxoAmountError;
+class VtxoStatusError extends OmniaVtxoError {
+    constructor(message, currentStatus) {
+        super(message);
+        this.name = 'VtxoStatusError';
+        this.currentStatus = currentStatus;
+    }
+}
+exports.VtxoStatusError = VtxoStatusError;
+class VtxoOwnershipError extends OmniaVtxoError {
+    constructor(message) {
+        super(message);
+        this.name = 'VtxoOwnershipError';
+    }
+}
+exports.VtxoOwnershipError = VtxoOwnershipError;
+class VtxoProofError extends OmniaVtxoError {
+    constructor(message) {
+        super(message);
+        this.name = 'VtxoProofError';
+    }
+}
+exports.VtxoProofError = VtxoProofError;
+class VtxoPoolCapacityError extends OmniaVtxoError {
+    constructor(message, requested, available) {
+        super(message);
+        this.name = 'VtxoPoolCapacityError';
+        this.requested = requested;
+        this.available = available;
+    }
+}
+exports.VtxoPoolCapacityError = VtxoPoolCapacityError;
+class VtxoPolicyError extends OmniaVtxoError {
+    constructor(message) {
+        super(message);
+        this.name = 'VtxoPolicyError';
+    }
+}
+exports.VtxoPolicyError = VtxoPolicyError;
+class VtxoMergeError extends OmniaVtxoError {
+    constructor(message) {
+        super(message);
+        this.name = 'VtxoMergeError';
+    }
+}
+exports.VtxoMergeError = VtxoMergeError;
+class VtxoSplitError extends OmniaVtxoError {
+    constructor(message) {
+        super(message);
+        this.name = 'VtxoSplitError';
+    }
+}
+exports.VtxoSplitError = VtxoSplitError;
+class VtxoExitError extends OmniaVtxoError {
+    constructor(message) {
+        super(message);
+        this.name = 'VtxoExitError';
+    }
+}
+exports.VtxoExitError = VtxoExitError;

package/dist/exit.d.ts

@@ -0,0 +1,19 @@
+import { OmniaVtxo, ExitDraft, VtxoOperatorReceipt } from './types.js';
+/**
+ * Transitions an active VTXO to 'exiting' status.
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+export declare function markExiting(vtxo: OmniaVtxo, now?: number): OmniaVtxo;
+/**
+ * Transitions an exiting VTXO to 'exited' status.
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+export declare function markExited(vtxo: OmniaVtxo, now?: number): OmniaVtxo;
+/**
+ * Creates a mock exit draft for a VTXO. Validates the proof leaf before drafting.
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+export declare function createExitDraft(vtxo: OmniaVtxo, now?: number): {
+    draft: ExitDraft;
+    receipt: VtxoOperatorReceipt;
+};