@totemsdk/omnia-vtxo 0.2.1 → 0.3.0

package/dist/cjs/durable-store.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Durable VTXO/pool snapshot store (RFC-007 G6).
+ *
+ * Drop-in replacement for `MemoryOmniaVtxoStore` — same `OmniaVtxoStore` port
+ * — backed by a storage adapter instead of heap maps: the whole pool/VTXO
+ * registry is a single revision-CAS snapshot record, so concurrent pool/VTXO
+ * transitions never lose an update, reopen restores every VTXO (incl. spent
+ * status and history), and corruption is surfaced — never treated as absence.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDurableOmniaVtxoStore = createDurableOmniaVtxoStore;
+const snapshot_1 = require("@totemsdk/storage/snapshot");
+const errors_1 = require("@totemsdk/storage/errors");
+const errors_js_1 = require("./errors.js");
+const DEFAULT_NAMESPACE = 'totem_omnia_vtxo:v1:';
+function assertRegistryState(state) {
+    if (typeof state !== 'object' || state === null || Array.isArray(state)) {
+        throw new errors_1.StorageError('omnia-vtxo registry state is not an object', 'corrupt');
+    }
+    for (const section of ['pools', 'vtxos']) {
+        const value = state[section];
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new errors_1.StorageError(`omnia-vtxo registry state is missing section "${section}"`, 'corrupt');
+        }
+    }
+}
+function createDurableOmniaVtxoStore(adapter, options = {}) {
+    const snapshots = (0, snapshot_1.createRevisionedSnapshotStore)(adapter, {
+        namespace: options.namespace ?? DEFAULT_NAMESPACE,
+        requireAckMode: options.requireAckMode,
+        empty: () => ({ pools: {}, vtxos: {} }),
+        validate: assertRegistryState,
+    });
+    async function mutate(fn) {
+        await snapshots.mutate(fn);
+    }
+    return {
+        async savePool(pool) {
+            await mutate((state) => {
+                const pools = { ...state.pools, [pool.poolId]: pool };
+                return { ...state, pools };
+            });
+        },
+        async getPool(poolId) {
+            return (await snapshots.load()).pools[poolId];
+        },
+        async saveVtxo(vtxo) {
+            await mutate((state) => {
+                const vtxos = { ...state.vtxos, [vtxo.vtxoId]: vtxo };
+                return { ...state, vtxos };
+            });
+        },
+        async getVtxo(vtxoId) {
+            return (await snapshots.load()).vtxos[vtxoId];
+        },
+        async listVtxos(poolId) {
+            const state = await snapshots.load();
+            const all = Object.values(state.vtxos);
+            if (poolId === undefined)
+                return all;
+            return all.filter((v) => v.poolId === poolId);
+        },
+        async markVtxoSpent(vtxoId, now) {
+            await mutate((state) => {
+                const existing = state.vtxos[vtxoId];
+                if (!existing) {
+                    // Preserve MemoryOmniaVtxoStore error behaviour exactly.
+                    throw new Error(`VTXO ${vtxoId} not found`);
+                }
+                if (existing.status !== 'active') {
+                    throw new errors_js_1.VtxoStatusError(`Cannot mark VTXO ${vtxoId} as spent: status is '${existing.status}'`, existing.status);
+                }
+                const ts = now !== undefined ? now : Date.now();
+                const vtxos = {
+                    ...state.vtxos,
+                    [vtxoId]: {
+                        ...existing,
+                        status: 'spent',
+                        updatedAt: ts,
+                        history: [...existing.history, { op: 'spent', at: ts }],
+                    },
+                };
+                return { ...state, vtxos };
+            });
+        },
+        getRevision: () => snapshots.getRevision(),
+        hasState: () => snapshots.hasState(),
+        async getSnapshot() {
+            return snapshots.load();
+        },
+    };
+}

package/dist/cjs/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/cjs/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/cjs/exit-tx.d.ts

@@ -0,0 +1,55 @@
+/**
+ * VTXO exit transaction (RFC-038 V2).
+ *
+ * Builds a real exit transaction: spend the pool's on-chain coin and pay the
+ * VTXO's owner, carrying the exit delay in STATE(102). The digest is signed
+ * (injected signer) and, when a chain provider is supplied, mined + broadcast
+ * (injected miner). This replaces the `'mock-exit'` draft with a concrete tx.
+ *
+ * NOTE (RFC-038 §3.4): the full owner-unilateral covenant (a timelock branch the
+ * owner can exercise without the operator, or a pre-signed exit tx) is a
+ * follow-on; this builds and broadcasts the transaction with the delay encoded.
+ */
+import { type OmniaTxDraft } from '@totemsdk/omnia';
+import type { ChainStateProvider } from '@totemsdk/chain-provider';
+import type { OmniaVtxo } from './types.js';
+/** State port carrying the exit delay. */
+export declare const EXIT_DELAY_PORT = 102;
+export interface ExitTxParams {
+    vtxo: OmniaVtxo;
+    /** The pool's on-chain coin (input). */
+    fundingCoinId: string;
+    fundingAddress: string;
+    fundingScript: string;
+    /** Raw base-unit amount to pay the owner (the VTXO amount, pre-scaled). */
+    amount: bigint;
+    /** Exit delay carried as STATE(102). */
+    exitDelayBlocks: number;
+}
+/** Draft that spends the pool coin to the VTXO owner with the exit delay encoded. */
+export declare function buildExitTransactionDraft(params: ExitTxParams): OmniaTxDraft;
+export declare function exitTransactionDigest(draft: OmniaTxDraft): Uint8Array;
+export declare function exitTransactionHex(draft: OmniaTxDraft): string;
+interface MinedTxPow {
+    minedHeaderBytes: Uint8Array;
+    txpowId: Uint8Array;
+}
+export interface ExitTxDeps {
+    signDigest: (digest: Uint8Array) => Promise<Uint8Array>;
+    chainProvider?: ChainStateProvider;
+    mine?: (txBody: Uint8Array, difficulty: Uint8Array) => Promise<MinedTxPow>;
+}
+export interface ExitTxResult {
+    vtxoId: string;
+    owner: string;
+    amount: string;
+    exitDelayBlocks: number;
+    draftType: 'vtxo-exit';
+    txHex: string;
+    digest: string;
+    witnessHex: string;
+    txpowId?: string;
+}
+/** Build, sign (and optionally mine + broadcast) a VTXO exit transaction. */
+export declare function buildExitTransaction(params: ExitTxParams, deps: ExitTxDeps): Promise<ExitTxResult>;
+export {};

package/dist/cjs/exit-tx.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * VTXO exit transaction (RFC-038 V2).
+ *
+ * Builds a real exit transaction: spend the pool's on-chain coin and pay the
+ * VTXO's owner, carrying the exit delay in STATE(102). The digest is signed
+ * (injected signer) and, when a chain provider is supplied, mined + broadcast
+ * (injected miner). This replaces the `'mock-exit'` draft with a concrete tx.
+ *
+ * NOTE (RFC-038 §3.4): the full owner-unilateral covenant (a timelock branch the
+ * owner can exercise without the operator, or a pre-signed exit tx) is a
+ * follow-on; this builds and broadcasts the transaction with the delay encoded.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT_DELAY_PORT = void 0;
+exports.buildExitTransactionDraft = buildExitTransactionDraft;
+exports.exitTransactionDigest = exitTransactionDigest;
+exports.exitTransactionHex = exitTransactionHex;
+exports.buildExitTransaction = buildExitTransaction;
+const omnia_1 = require("@totemsdk/omnia");
+const txpow_1 = require("@totemsdk/txpow");
+const core_1 = require("@totemsdk/core");
+/** State port carrying the exit delay. */
+exports.EXIT_DELAY_PORT = 102;
+/** Draft that spends the pool coin to the VTXO owner with the exit delay encoded. */
+function buildExitTransactionDraft(params) {
+    const stateVariables = [
+        { port: exports.EXIT_DELAY_PORT, value: BigInt(params.exitDelayBlocks), type: 'number' },
+    ];
+    return {
+        type: 'settlement',
+        inputs: [{
+                coinId: params.fundingCoinId,
+                address: params.fundingAddress,
+                amount: params.amount,
+                tokenId: params.vtxo.tokenId,
+                scriptHex: params.fundingScript,
+            }],
+        outputs: [{
+                address: params.vtxo.owner,
+                amount: params.amount,
+                tokenId: params.vtxo.tokenId,
+                storeState: false,
+                stateVariables,
+            }],
+        storeState: false,
+        stateVariables,
+    };
+}
+function exitTransactionDigest(draft) {
+    return (0, omnia_1.computeOmniaTxDigest)(draft);
+}
+function exitTransactionHex(draft) {
+    return (0, omnia_1.serializeTxDraft)(draft);
+}
+/** Build, sign (and optionally mine + broadcast) a VTXO exit transaction. */
+async function buildExitTransaction(params, deps) {
+    const draft = buildExitTransactionDraft(params);
+    const digest = exitTransactionDigest(draft);
+    const signature = await deps.signDigest(digest);
+    const result = {
+        vtxoId: params.vtxo.vtxoId,
+        owner: params.vtxo.owner,
+        amount: params.vtxo.amount.toString(),
+        exitDelayBlocks: params.exitDelayBlocks,
+        draftType: 'vtxo-exit',
+        txHex: exitTransactionHex(draft),
+        digest: Buffer.from(digest).toString('hex'),
+        witnessHex: Buffer.from(signature).toString('hex'),
+    };
+    if (deps.chainProvider) {
+        const mine = deps.mine ?? ((txBody, difficulty) => (0, txpow_1.mineTxPoW)(txBody, difficulty));
+        const draftBytes = (0, omnia_1.omniaDraftToMinimaBytes)(draft);
+        const txBody = (0, txpow_1.serializeTxBody)(draftBytes, signature);
+        const mined = await mine(txBody, txpow_1.TX_POW_MIN_DIFFICULTY);
+        const fullTxPoW = (0, core_1.concatBytes)((0, core_1.concatBytes)(mined.minedHeaderBytes, new Uint8Array([0x01])), txBody);
+        await deps.chainProvider.broadcastTxPoW(Buffer.from(fullTxPoW).toString('hex'));
+        result.txpowId = Buffer.from(mined.txpowId).toString('hex');
+    }
+    return result;
+}

package/dist/cjs/exit.d.ts

@@ -0,0 +1,29 @@
+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, options?: {
+    txpowId?: string;
+    now?: number;
+}): OmniaVtxo;
+/**
+ * Creates a mock exit draft for a VTXO. Validates the proof leaf before
+ * drafting, caps the exit at the verified share, and consumes the VTXO's
+ * receipt so a second exit draft is refused (double-exit prevention, #28).
+ * @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;
+};
+/**
+ * Consume a VTXO's exit receipt — the single-spend marker that prevents a
+ * second exit draft for the same VTXO. Returns the updated VTXO.
+ */
+export declare function consumeExitReceipt(vtxo: OmniaVtxo, receiptId: string, now?: number): OmniaVtxo;

package/dist/cjs/exit.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.markExiting = markExiting;
+exports.markExited = markExited;
+exports.createExitDraft = createExitDraft;
+exports.consumeExitReceipt = consumeExitReceipt;
+const errors_js_1 = require("./errors.js");
+const commitment_js_1 = require("./commitment.js");
+/**
+ * Transitions an active VTXO to 'exiting' status.
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+function markExiting(vtxo, now) {
+    const ts = now !== undefined ? now : Date.now();
+    if (vtxo.status !== 'active') {
+        throw new errors_js_1.VtxoStatusError(`Cannot initiate exit for VTXO ${vtxo.vtxoId}: status is '${vtxo.status}'`, vtxo.status);
+    }
+    return {
+        ...vtxo,
+        status: 'exiting',
+        updatedAt: ts,
+        history: [
+            ...vtxo.history,
+            { op: 'exit_initiated', at: ts },
+        ],
+    };
+}
+/**
+ * Transitions an exiting VTXO to 'exited' status.
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+function markExited(vtxo, options = {}) {
+    const ts = options.now !== undefined ? options.now : Date.now();
+    if (vtxo.status !== 'exiting') {
+        throw new errors_js_1.VtxoStatusError(`Cannot mark VTXO ${vtxo.vtxoId} as exited: status is '${vtxo.status}'`, vtxo.status);
+    }
+    return {
+        ...vtxo,
+        status: 'exited',
+        updatedAt: ts,
+        ...(options.txpowId ? { exitTxpowId: options.txpowId } : {}),
+        history: [
+            ...vtxo.history,
+            { op: 'exit_complete', at: ts, ...(options.txpowId ? { meta: { txpowId: options.txpowId } } : {}) },
+        ],
+    };
+}
+/**
+ * Validates the VTXO's proof leaf integrity before creating an exit draft.
+ * Throws VtxoProofError if the proof leaf is present but does not match the VTXO fields.
+ */
+function assertProofLeafValid(vtxo) {
+    if (!vtxo.proof.leaf)
+        return;
+    const expectedLeaf = (0, commitment_js_1.computeVtxoLeaf)(vtxo);
+    if (vtxo.proof.leaf !== expectedLeaf) {
+        throw new errors_js_1.VtxoProofError(`Exit draft rejected: VTXO ${vtxo.vtxoId} proof leaf mismatch. ` +
+            `Expected ${expectedLeaf}, got ${vtxo.proof.leaf}`);
+    }
+}
+/**
+ * Creates a mock exit draft for a VTXO. Validates the proof leaf before
+ * drafting, caps the exit at the verified share, and consumes the VTXO's
+ * receipt so a second exit draft is refused (double-exit prevention, #28).
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+function createExitDraft(vtxo, now) {
+    const ts = now !== undefined ? now : Date.now();
+    if (vtxo.status !== 'active' && vtxo.status !== 'exiting') {
+        throw new errors_js_1.VtxoExitError(`Cannot create exit draft for VTXO ${vtxo.vtxoId}: status is '${vtxo.status}'`);
+    }
+    if (vtxo.exitConsumedAt !== undefined) {
+        throw new errors_js_1.VtxoExitError(`Cannot create exit draft for VTXO ${vtxo.vtxoId}: exit already consumed by ${vtxo.exitReceiptId}`);
+    }
+    assertProofLeafValid(vtxo);
+    const draft = {
+        vtxoId: vtxo.vtxoId,
+        poolId: vtxo.poolId,
+        owner: vtxo.owner,
+        amount: vtxo.amount,
+        tokenId: vtxo.tokenId,
+        draftType: 'vtxo-exit',
+        timelockSeconds: 86400,
+        createdAt: ts,
+        verifiedShare: vtxo.amount,
+    };
+    const receiptId = (0, commitment_js_1.computeReceiptId)(vtxo.poolId, 'exit_initiated', [vtxo.vtxoId], [], ts);
+    const receipt = {
+        receiptId,
+        poolId: vtxo.poolId,
+        op: 'exit_initiated',
+        inputIds: [vtxo.vtxoId],
+        outputIds: [],
+        epoch: vtxo.epoch,
+        at: ts,
+        signature: '',
+        draftType: 'vtxo-exit',
+    };
+    return { draft, receipt };
+}
+/**
+ * Consume a VTXO's exit receipt — the single-spend marker that prevents a
+ * second exit draft for the same VTXO. Returns the updated VTXO.
+ */
+function consumeExitReceipt(vtxo, receiptId, now) {
+    if (vtxo.exitConsumedAt !== undefined) {
+        throw new errors_js_1.VtxoExitError(`VTXO ${vtxo.vtxoId} exit already consumed by ${vtxo.exitReceiptId}`);
+    }
+    return {
+        ...vtxo,
+        exitConsumedAt: now ?? Date.now(),
+        exitReceiptId: receiptId,
+        updatedAt: now ?? Date.now(),
+    };
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,21 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './constants.js';
+export * from './commitment.js';
+export * from './operator.js';
+export * from './receipt.js';
+export * from './pool-script.js';
+export * from './anchor.js';
+export * from './exit-tx.js';
+export * from './pool.js';
+export * from './vtxo.js';
+export * from './transfer.js';
+export * from './split.js';
+export * from './merge.js';
+export * from './refresh.js';
+export * from './exit.js';
+export * from './verify.js';
+export * from './memory-store.js';
+export * from './durable-store.js';
+export * from './serialization.js';
+export * from './policy.js';

package/dist/cjs/index.js

@@ -0,0 +1,37 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./constants.js"), exports);
+__exportStar(require("./commitment.js"), exports);
+__exportStar(require("./operator.js"), exports);
+__exportStar(require("./receipt.js"), exports);
+__exportStar(require("./pool-script.js"), exports);
+__exportStar(require("./anchor.js"), exports);
+__exportStar(require("./exit-tx.js"), exports);
+__exportStar(require("./pool.js"), exports);
+__exportStar(require("./vtxo.js"), exports);
+__exportStar(require("./transfer.js"), exports);
+__exportStar(require("./split.js"), exports);
+__exportStar(require("./merge.js"), exports);
+__exportStar(require("./refresh.js"), exports);
+__exportStar(require("./exit.js"), exports);
+__exportStar(require("./verify.js"), exports);
+__exportStar(require("./memory-store.js"), exports);
+__exportStar(require("./durable-store.js"), exports);
+__exportStar(require("./serialization.js"), exports);
+__exportStar(require("./policy.js"), exports);

package/dist/cjs/memory-store.d.ts

@@ -0,0 +1,17 @@
+import { OmniaVtxo, OmniaVtxoPool, OmniaVtxoStore, VtxoId } from './types.js';
+export declare class MemoryOmniaVtxoStore implements OmniaVtxoStore {
+    private readonly pools;
+    private readonly vtxos;
+    savePool(pool: OmniaVtxoPool): Promise<void>;
+    getPool(poolId: string): Promise<OmniaVtxoPool | undefined>;
+    saveVtxo(vtxo: OmniaVtxo): Promise<void>;
+    getVtxo(vtxoId: VtxoId): Promise<OmniaVtxo | undefined>;
+    listVtxos(poolId?: string): Promise<OmniaVtxo[]>;
+    /**
+     * Marks a VTXO as spent. Accepts an optional `now` timestamp for deterministic testing.
+     * When `now` is omitted the store falls back to `Date.now()` — this is intentional
+     * and explicitly documented: the store is a persistence layer, not a pure function,
+     * so wall-clock time is an acceptable default for production use. Pass `now` in tests.
+     */
+    markVtxoSpent(vtxoId: VtxoId, now?: number): Promise<void>;
+}

package/dist/cjs/memory-store.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryOmniaVtxoStore = void 0;
+const errors_js_1 = require("./errors.js");
+class MemoryOmniaVtxoStore {
+    constructor() {
+        this.pools = new Map();
+        this.vtxos = new Map();
+    }
+    async savePool(pool) {
+        this.pools.set(pool.poolId, pool);
+    }
+    async getPool(poolId) {
+        return this.pools.get(poolId);
+    }
+    async saveVtxo(vtxo) {
+        this.vtxos.set(vtxo.vtxoId, vtxo);
+    }
+    async getVtxo(vtxoId) {
+        return this.vtxos.get(vtxoId);
+    }
+    async listVtxos(poolId) {
+        const all = Array.from(this.vtxos.values());
+        if (poolId === undefined)
+            return all;
+        return all.filter(v => v.poolId === poolId);
+    }
+    /**
+     * Marks a VTXO as spent. Accepts an optional `now` timestamp for deterministic testing.
+     * When `now` is omitted the store falls back to `Date.now()` — this is intentional
+     * and explicitly documented: the store is a persistence layer, not a pure function,
+     * so wall-clock time is an acceptable default for production use. Pass `now` in tests.
+     */
+    async markVtxoSpent(vtxoId, now) {
+        const vtxo = this.vtxos.get(vtxoId);
+        if (!vtxo)
+            throw new Error(`VTXO ${vtxoId} not found`);
+        if (vtxo.status !== 'active') {
+            throw new errors_js_1.VtxoStatusError(`Cannot mark VTXO ${vtxoId} as spent: status is '${vtxo.status}'`, vtxo.status);
+        }
+        // NOTE: Date.now() fallback is intentional and documented above.
+        const ts = now !== undefined ? now : Date.now();
+        this.vtxos.set(vtxoId, {
+            ...vtxo,
+            status: 'spent',
+            updatedAt: ts,
+            history: [...vtxo.history, { op: 'spent', at: ts }],
+        });
+    }
+}
+exports.MemoryOmniaVtxoStore = MemoryOmniaVtxoStore;

package/dist/cjs/merge.d.ts

@@ -0,0 +1,8 @@
+import { OmniaVtxo, MergeVtxosParams, MergeResult, VtxoOperatorReceipt } from './types.js';
+/**
+ * Merges multiple VTXOs into one.
+ * @param now - Timestamp in ms. Defaults to Date.now() if omitted — pass explicitly for determinism.
+ */
+export declare function mergeVtxos(vtxos: OmniaVtxo[], params: MergeVtxosParams, now?: number): MergeResult & {
+    receipt: VtxoOperatorReceipt;
+};