@totemsdk/omnia-vtxo 0.4.0 → 0.5.1

package/README.md

@@ -2,6 +2,14 @@
 
 Virtual UTXO (vTXO) / payment-pool claim layer for the Totem Edge ecosystem.
 
+> **Role:** the **spendable balances**. A VTXO is a cash-like off-chain bearer
+> claim on a pool's on-chain capacity. This package owns the pool output script,
+> the VTXO lifecycle (mint / transfer / split / merge / refresh / exit), the
+> operator co-signature, and the per-share exit. It is **not** the LP accounting
+> layer — that is `@totemsdk/liquidity-bond` + `@totemsdk/omnia-pool`, which
+> allocate capital *into* a VTXO pool. They compose; they don't overlap.
+> See [`docs/examples/meridian-vtxo-payments.md`](../../docs/examples/meridian-vtxo-payments.md).
+
 ## 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.

package/dist/anchor.d.ts

@@ -11,8 +11,11 @@ import { type OmniaTxDraft, type StateValue } from '@totemsdk/omnia';
 import type { ChainStateProvider } from '@totemsdk/chain-provider';
 export interface BatchAnchorParams {
     operatorPublicKeyDigest: string;
-    ownerPublicKeyDigest: string;
-    /** Absolute block height after which the owner may exit unilaterally (STATE(102)). */
+    /** Holder WOTS public-key digests (one per pool share). */
+    holders: string[];
+    /** Committed share per holder (aligned with `holders`); Σ = pool capacity. */
+    shares: bigint[];
+    /** Absolute block height after which holders may exit unilaterally (STATE(102)). */
     exitBlock: number;
     /** The epoch's Merkle root (32-byte hex). */
     root: string;
@@ -25,8 +28,8 @@ export interface BatchAnchorParams {
     amount: bigint;
     tokenId: string;
 }
-/** Pool output state: STATE(100)=root, STATE(101)=epoch, STATE(102)=exitBlock. */
-export declare function poolStateVariables(root: string, epoch: number, exitBlock: number): StateValue[];
+/** Pool output state: STATE(100)=root, STATE(101)=epoch, STATE(102)=exitBlock, STATE(300+k)=share k. */
+export declare function poolStateVariables(root: string, epoch: number, exitBlock: number, shares?: bigint[]): StateValue[];
 /** Build the batch-anchor draft (input = pool coin, output = pool state output). */
 export declare function buildBatchAnchorDraft(params: BatchAnchorParams): OmniaTxDraft;
 export declare function batchAnchorDigest(draft: OmniaTxDraft): Uint8Array;

package/dist/anchor.js

@@ -10,20 +10,24 @@
 import { computeOmniaTxDigest, omniaDraftToMinimaBytes, } from '@totemsdk/omnia';
 import { serializeTxBody, mineTxPoW, TX_POW_MIN_DIFFICULTY } from '@totemsdk/txpow';
 import { concatBytes } from '@totemsdk/core';
-import { buildAndHashPoolScript } from './pool-script.js';
-/** Pool output state: STATE(100)=root, STATE(101)=epoch, STATE(102)=exitBlock. */
-export function poolStateVariables(root, epoch, exitBlock) {
+import { buildAndHashPoolScript, POOL_SHARE_PORT_BASE } from './pool-script.js';
+/** Pool output state: STATE(100)=root, STATE(101)=epoch, STATE(102)=exitBlock, STATE(300+k)=share k. */
+export function poolStateVariables(root, epoch, exitBlock, shares = []) {
     return [
         { port: 100, value: root, type: 'string' },
         { port: 101, value: BigInt(epoch), type: 'number' },
         { port: 102, value: BigInt(exitBlock), type: 'number' },
+        ...shares.map((share, k) => ({ port: POOL_SHARE_PORT_BASE + k, value: share, type: 'number' })),
     ];
 }
 /** Build the batch-anchor draft (input = pool coin, output = pool state output). */
 export function buildBatchAnchorDraft(params) {
+    if (params.holders.length !== params.shares.length) {
+        throw new Error('anchorBatch: holders and shares must be the same length');
+    }
     const { script, address } = buildAndHashPoolScript({
         operatorPublicKeyDigest: params.operatorPublicKeyDigest,
-        ownerPublicKeyDigest: params.ownerPublicKeyDigest,
+        holders: params.holders,
         exitBlock: params.exitBlock,
     });
     // The input must be the operator's own pool output, not a foreign script.
@@ -33,7 +37,7 @@ export function buildBatchAnchorDraft(params) {
     if (params.fundingAddress !== address) {
         throw new Error('anchorBatch: fundingAddress does not match the pool address');
     }
-    const stateVariables = poolStateVariables(params.root, params.epoch, params.exitBlock);
+    const stateVariables = poolStateVariables(params.root, params.epoch, params.exitBlock, params.shares);
     return {
         type: 'settlement',
         inputs: [{

package/dist/cjs/anchor.d.ts

@@ -11,8 +11,11 @@ import { type OmniaTxDraft, type StateValue } from '@totemsdk/omnia';
 import type { ChainStateProvider } from '@totemsdk/chain-provider';
 export interface BatchAnchorParams {
     operatorPublicKeyDigest: string;
-    ownerPublicKeyDigest: string;
-    /** Absolute block height after which the owner may exit unilaterally (STATE(102)). */
+    /** Holder WOTS public-key digests (one per pool share). */
+    holders: string[];
+    /** Committed share per holder (aligned with `holders`); Σ = pool capacity. */
+    shares: bigint[];
+    /** Absolute block height after which holders may exit unilaterally (STATE(102)). */
     exitBlock: number;
     /** The epoch's Merkle root (32-byte hex). */
     root: string;
@@ -25,8 +28,8 @@ export interface BatchAnchorParams {
     amount: bigint;
     tokenId: string;
 }
-/** Pool output state: STATE(100)=root, STATE(101)=epoch, STATE(102)=exitBlock. */
-export declare function poolStateVariables(root: string, epoch: number, exitBlock: number): StateValue[];
+/** Pool output state: STATE(100)=root, STATE(101)=epoch, STATE(102)=exitBlock, STATE(300+k)=share k. */
+export declare function poolStateVariables(root: string, epoch: number, exitBlock: number, shares?: bigint[]): StateValue[];
 /** Build the batch-anchor draft (input = pool coin, output = pool state output). */
 export declare function buildBatchAnchorDraft(params: BatchAnchorParams): OmniaTxDraft;
 export declare function batchAnchorDigest(draft: OmniaTxDraft): Uint8Array;

package/dist/cjs/anchor.js

@@ -18,19 +18,23 @@ const omnia_1 = require("@totemsdk/omnia");
 const txpow_1 = require("@totemsdk/txpow");
 const core_1 = require("@totemsdk/core");
 const pool_script_js_1 = require("./pool-script.js");
-/** Pool output state: STATE(100)=root, STATE(101)=epoch, STATE(102)=exitBlock. */
-function poolStateVariables(root, epoch, exitBlock) {
+/** Pool output state: STATE(100)=root, STATE(101)=epoch, STATE(102)=exitBlock, STATE(300+k)=share k. */
+function poolStateVariables(root, epoch, exitBlock, shares = []) {
     return [
         { port: 100, value: root, type: 'string' },
         { port: 101, value: BigInt(epoch), type: 'number' },
         { port: 102, value: BigInt(exitBlock), type: 'number' },
+        ...shares.map((share, k) => ({ port: pool_script_js_1.POOL_SHARE_PORT_BASE + k, value: share, type: 'number' })),
     ];
 }
 /** Build the batch-anchor draft (input = pool coin, output = pool state output). */
 function buildBatchAnchorDraft(params) {
+    if (params.holders.length !== params.shares.length) {
+        throw new Error('anchorBatch: holders and shares must be the same length');
+    }
     const { script, address } = (0, pool_script_js_1.buildAndHashPoolScript)({
         operatorPublicKeyDigest: params.operatorPublicKeyDigest,
-        ownerPublicKeyDigest: params.ownerPublicKeyDigest,
+        holders: params.holders,
         exitBlock: params.exitBlock,
     });
     // The input must be the operator's own pool output, not a foreign script.
@@ -40,7 +44,7 @@ function buildBatchAnchorDraft(params) {
     if (params.fundingAddress !== address) {
         throw new Error('anchorBatch: fundingAddress does not match the pool address');
     }
-    const stateVariables = poolStateVariables(params.root, params.epoch, params.exitBlock);
+    const stateVariables = poolStateVariables(params.root, params.epoch, params.exitBlock, params.shares);
     return {
         type: 'settlement',
         inputs: [{

package/dist/cjs/exit-tx.d.ts

@@ -1,21 +1,20 @@
 /**
- * VTXO exit transaction (RFC-038 V2 — owner-unilateral).
+ * VTXO exit transaction (RFC-038 V3 — per-share, owner-signed).
  *
- * The exit spends the pool's on-chain coin and pays the VTXO's owner, carrying
- * the exit delay in STATE(110). It is signed with the **owner's** key (not the
- * operator's): the pool script's `IF @BLOCK GT EXITBLOCK THEN RETURN
- * SIGNEDBY(OWNER)` branch authorizes it after the exit window, so the owner can
- * broadcast it without any operator signature or liveness. The digest is signed
- * (injected signer) and, when a chain provider is supplied, mined + broadcast
- * (injected miner).
+ * The exit spends the pool's on-chain coin and pays the exiting holder **only
+ * its committed share** (`shares[holderIndex]`), returning the remainder to the
+ * pool with that holder's share state zeroed. It is signed with the holder's key
+ * — the pool script's `IF @BLOCK GT EXITBLOCK … IF SIGNEDBY(holder) … VERIFYOUT(0
+ * holder SHARE @TOKENID FALSE)` branch authorizes it, so the holder can broadcast
+ * without any operator signature or liveness, and cannot take more than its share.
  *
- * The caller must pass the owner signer; the operator cannot construct a valid
- * exit witness for itself.
+ * The caller must pass the holder signer; neither the operator nor another holder
+ * can build a valid witness for this holder's share.
  */
 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 on the owner's output. */
+/** State port carrying an optional exit delay on the holder's output. */
 export declare const EXIT_DELAY_PORT = 110;
 export interface ExitTxParams {
     vtxo: OmniaVtxo;
@@ -23,12 +22,19 @@ export interface ExitTxParams {
     fundingCoinId: string;
     fundingAddress: string;
     fundingScript: string;
-    /** Raw base-unit amount to pay the owner (the VTXO amount, pre-scaled). */
+    /** Total pool amount (raw base units). */
     amount: bigint;
-    /** Exit delay carried as STATE(102). */
-    exitDelayBlocks: number;
+    /** Pool holders + committed shares (aligned arrays). */
+    holders: string[];
+    shares: bigint[];
+    /** Index of the exiting holder (must match `vtxo.owner`). */
+    holderIndex: number;
+    /** Pool state, needed to rebuild the remainder output's state. */
+    root: string;
+    epoch: number;
+    exitBlock: number;
 }
-/** Draft that spends the pool coin to the VTXO owner with the exit delay encoded. */
+/** Draft that spends the pool coin: output 0 = holder's share, remainder = pool. */
 export declare function buildExitTransactionDraft(params: ExitTxParams): OmniaTxDraft;
 export declare function exitTransactionDigest(draft: OmniaTxDraft): Uint8Array;
 export declare function exitTransactionHex(draft: OmniaTxDraft): string;
@@ -44,14 +50,13 @@ export interface ExitTxDeps {
 export interface ExitTxResult {
     vtxoId: string;
     owner: string;
-    amount: string;
-    exitDelayBlocks: number;
+    share: string;
     draftType: 'vtxo-exit';
     txHex: string;
     digest: string;
     witnessHex: string;
     txpowId?: string;
 }
-/** Build, sign (and optionally mine + broadcast) a VTXO exit transaction. */
+/** Build, sign (and optionally mine + broadcast) a per-share VTXO exit transaction. */
 export declare function buildExitTransaction(params: ExitTxParams, deps: ExitTxDeps): Promise<ExitTxResult>;
 export {};

package/dist/cjs/exit-tx.js

@@ -1,17 +1,16 @@
 "use strict";
 /**
- * VTXO exit transaction (RFC-038 V2 — owner-unilateral).
+ * VTXO exit transaction (RFC-038 V3 — per-share, owner-signed).
  *
- * The exit spends the pool's on-chain coin and pays the VTXO's owner, carrying
- * the exit delay in STATE(110). It is signed with the **owner's** key (not the
- * operator's): the pool script's `IF @BLOCK GT EXITBLOCK THEN RETURN
- * SIGNEDBY(OWNER)` branch authorizes it after the exit window, so the owner can
- * broadcast it without any operator signature or liveness. The digest is signed
- * (injected signer) and, when a chain provider is supplied, mined + broadcast
- * (injected miner).
+ * The exit spends the pool's on-chain coin and pays the exiting holder **only
+ * its committed share** (`shares[holderIndex]`), returning the remainder to the
+ * pool with that holder's share state zeroed. It is signed with the holder's key
+ * — the pool script's `IF @BLOCK GT EXITBLOCK … IF SIGNEDBY(holder) … VERIFYOUT(0
+ * holder SHARE @TOKENID FALSE)` branch authorizes it, so the holder can broadcast
+ * without any operator signature or liveness, and cannot take more than its share.
  *
- * The caller must pass the owner signer; the operator cannot construct a valid
- * exit witness for itself.
+ * The caller must pass the holder signer; neither the operator nor another holder
+ * can build a valid witness for this holder's share.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EXIT_DELAY_PORT = void 0;
@@ -22,13 +21,34 @@ 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 on the owner's output. */
+const anchor_js_1 = require("./anchor.js");
+/** State port carrying an optional exit delay on the holder's output. */
 exports.EXIT_DELAY_PORT = 110;
-/** Draft that spends the pool coin to the VTXO owner with the exit delay encoded. */
+/** Draft that spends the pool coin: output 0 = holder's share, remainder = pool. */
 function buildExitTransactionDraft(params) {
-    const stateVariables = [
-        { port: exports.EXIT_DELAY_PORT, value: BigInt(params.exitDelayBlocks), type: 'number' },
-    ];
+    const share = params.shares[params.holderIndex];
+    if (share === undefined)
+        throw new Error('exit: holderIndex out of range');
+    if (share <= 0n)
+        throw new Error('exit: holder share must be positive');
+    const outputs = [{
+            address: params.vtxo.owner,
+            amount: share,
+            tokenId: params.vtxo.tokenId,
+            storeState: false,
+            stateVariables: [],
+        }];
+    const carriesState = params.amount > share;
+    if (carriesState) {
+        const remaining = params.shares.map((s, i) => (i === params.holderIndex ? 0n : s));
+        outputs.push({
+            address: params.fundingAddress,
+            amount: params.amount - share,
+            tokenId: params.vtxo.tokenId,
+            storeState: true,
+            stateVariables: (0, anchor_js_1.poolStateVariables)(params.root, params.epoch, params.exitBlock, remaining),
+        });
+    }
     return {
         type: 'settlement',
         inputs: [{
@@ -38,15 +58,9 @@ function buildExitTransactionDraft(params) {
                 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,
+        outputs,
+        storeState: carriesState,
+        stateVariables: [],
     };
 }
 function exitTransactionDigest(draft) {
@@ -55,7 +69,7 @@ function exitTransactionDigest(draft) {
 function exitTransactionHex(draft) {
     return (0, omnia_1.serializeTxDraft)(draft);
 }
-/** Build, sign (and optionally mine + broadcast) a VTXO exit transaction. */
+/** Build, sign (and optionally mine + broadcast) a per-share VTXO exit transaction. */
 async function buildExitTransaction(params, deps) {
     const draft = buildExitTransactionDraft(params);
     const digest = exitTransactionDigest(draft);
@@ -63,8 +77,7 @@ async function buildExitTransaction(params, deps) {
     const result = {
         vtxoId: params.vtxo.vtxoId,
         owner: params.vtxo.owner,
-        amount: params.vtxo.amount.toString(),
-        exitDelayBlocks: params.exitDelayBlocks,
+        share: params.shares[params.holderIndex].toString(),
         draftType: 'vtxo-exit',
         txHex: exitTransactionHex(draft),
         digest: Buffer.from(digest).toString('hex'),

package/dist/cjs/pool-script.d.ts

@@ -1,33 +1,38 @@
 /**
- * VTXO pool on-chain script (RFC-038 V2 — non-custodial).
+ * VTXO pool on-chain script (RFC-038 V3 — per-share non-custodial).
  *
  * The pool is an on-chain state output holding `totalCapacity`. An epoch's batch
- * root is committed as STATE(100), the epoch number in STATE(101), and the
- * owner's absolute exit-eligibility block in STATE(102).
+ * root is committed as STATE(100), the epoch number in STATE(101), the absolute
+ * exit-eligibility block in STATE(102), and each holder's committed share in
+ * STATE(200+k).
  *
- * Custody (RFC-044 / CUSTODY-POLICY §2):
- *   - **Unilateral owner exit.** After `@BLOCK GT EXITBLOCK` the owner alone may
- *     spend (`RETURN SIGNEDBY(OWNER)`) — no operator signature or liveness. This
- *     is exercised by the pre-signed exit tx (`exit-tx.ts`).
+ * Custody (RFC-039 / CUSTODY-POLICY §2):
+ *   - **Per-share unilateral exit.** After `@BLOCK GT PREVSTATE(102)` each holder
+ *     may withdraw **only its own committed share** (`PREVSTATE(200+k)`, the spent
+ *     coin's share), to its own key, zeroing that share in the successor
+ *     (`STATE(200+k) EQ 0`) and returning the remainder to the pool. A holder
+ *     cannot pay itself more than its share, so one holder can never rug the others.
  *   - **Cooperative update.** Before the exit window the pool may only move by
- *     `MULTISIG(2 OPERATOR OWNER)`, epoch-monotone (`ASSERT EPOCH GT
+ *     `MULTISIG(operator + all holders)`, epoch-monotone (`ASSERT EPOCH GT
  *     PREVSTATE(101)`), with the exit block immutable (`ASSERT SAMESTATE(102
- *     102)`) so the operator can never push the owner's escape clock, and the
- *     value confined to the same script address (`ASSERT VERIFYOUT(@INPUT
- *     @ADDRESS @AMOUNT @TOKENID TRUE)`) so the operator can never pay itself.
+ *     102)`) so no one can push the escape clock, and value confined to the same
+ *     script address (`ASSERT VERIFYOUT(@INPUT @ADDRESS @AMOUNT @TOKENID TRUE)`)
+ *     so the operator can never pay itself.
  *
- * The operator holds no unilateral path: it cannot move funds, cannot advance
- * the exit block, and cannot stop the owner's exit. It is a liveness-only peer.
+ * The operator holds no unilateral path: it cannot move funds, cannot advance the
+ * exit block, and cannot stop a holder's exit. It is a liveness-only peer.
  */
+/** State port base for per-holder shares: holder k ⇒ port 200+k (ports are bytes, ≤255). */
+export declare const POOL_SHARE_PORT_BASE = 200;
 export interface PoolScriptParams {
     /** Operator WOTS public-key digest (64 hex). */
     operatorPublicKeyDigest: string;
-    /** Pool owner WOTS public-key digest (64 hex). */
-    ownerPublicKeyDigest: string;
-    /** Absolute block height after which the owner may exit unilaterally. */
+    /** Holder WOTS public-key digests (64 hex), one per beneficial owner. */
+    holders: string[];
+    /** Absolute block height after which holders may exit unilaterally. */
     exitBlock: number;
 }
-/** Non-custodial, epoch-monotone, owner-escapable state-carrying pool script. */
+/** Per-share-constrained, epoch-monotone, state-carrying pool script. */
 export declare function buildPoolScript(params: PoolScriptParams): string;
 export declare function poolScriptAddress(script: string): string;
 export declare function buildAndHashPoolScript(params: PoolScriptParams): {

package/dist/cjs/pool-script.js

@@ -1,30 +1,36 @@
 "use strict";
 /**
- * VTXO pool on-chain script (RFC-038 V2 — non-custodial).
+ * VTXO pool on-chain script (RFC-038 V3 — per-share non-custodial).
  *
  * The pool is an on-chain state output holding `totalCapacity`. An epoch's batch
- * root is committed as STATE(100), the epoch number in STATE(101), and the
- * owner's absolute exit-eligibility block in STATE(102).
+ * root is committed as STATE(100), the epoch number in STATE(101), the absolute
+ * exit-eligibility block in STATE(102), and each holder's committed share in
+ * STATE(200+k).
  *
- * Custody (RFC-044 / CUSTODY-POLICY §2):
- *   - **Unilateral owner exit.** After `@BLOCK GT EXITBLOCK` the owner alone may
- *     spend (`RETURN SIGNEDBY(OWNER)`) — no operator signature or liveness. This
- *     is exercised by the pre-signed exit tx (`exit-tx.ts`).
+ * Custody (RFC-039 / CUSTODY-POLICY §2):
+ *   - **Per-share unilateral exit.** After `@BLOCK GT PREVSTATE(102)` each holder
+ *     may withdraw **only its own committed share** (`PREVSTATE(200+k)`, the spent
+ *     coin's share), to its own key, zeroing that share in the successor
+ *     (`STATE(200+k) EQ 0`) and returning the remainder to the pool. A holder
+ *     cannot pay itself more than its share, so one holder can never rug the others.
  *   - **Cooperative update.** Before the exit window the pool may only move by
- *     `MULTISIG(2 OPERATOR OWNER)`, epoch-monotone (`ASSERT EPOCH GT
+ *     `MULTISIG(operator + all holders)`, epoch-monotone (`ASSERT EPOCH GT
  *     PREVSTATE(101)`), with the exit block immutable (`ASSERT SAMESTATE(102
- *     102)`) so the operator can never push the owner's escape clock, and the
- *     value confined to the same script address (`ASSERT VERIFYOUT(@INPUT
- *     @ADDRESS @AMOUNT @TOKENID TRUE)`) so the operator can never pay itself.
+ *     102)`) so no one can push the escape clock, and value confined to the same
+ *     script address (`ASSERT VERIFYOUT(@INPUT @ADDRESS @AMOUNT @TOKENID TRUE)`)
+ *     so the operator can never pay itself.
  *
- * The operator holds no unilateral path: it cannot move funds, cannot advance
- * the exit block, and cannot stop the owner's exit. It is a liveness-only peer.
+ * The operator holds no unilateral path: it cannot move funds, cannot advance the
+ * exit block, and cannot stop a holder's exit. It is a liveness-only peer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.POOL_SHARE_PORT_BASE = void 0;
 exports.buildPoolScript = buildPoolScript;
 exports.poolScriptAddress = poolScriptAddress;
 exports.buildAndHashPoolScript = buildAndHashPoolScript;
 const core_1 = require("@totemsdk/core");
+/** State port base for per-holder shares: holder k ⇒ port 200+k (ports are bytes, ≤255). */
+exports.POOL_SHARE_PORT_BASE = 200;
 function pkHex(digest, label) {
     const raw = digest.replace(/^0x/i, '');
     if (!/^[0-9a-fA-F]{64}$/.test(raw)) {
@@ -32,24 +38,48 @@ function pkHex(digest, label) {
     }
     return '0X' + raw.toUpperCase();
 }
-/** Non-custodial, epoch-monotone, owner-escapable state-carrying pool script. */
+/** Per-share-constrained, epoch-monotone, state-carrying pool script. */
 function buildPoolScript(params) {
-    const owner = pkHex(params.ownerPublicKeyDigest, 'owner');
     const operator = pkHex(params.operatorPublicKeyDigest, 'operator');
+    if (!Array.isArray(params.holders) || params.holders.length < 1) {
+        throw new Error('pool requires at least one holder');
+    }
+    const holders = params.holders.map((h, i) => pkHex(h, `holder[${i}]`));
     if (!Number.isInteger(params.exitBlock) || params.exitBlock < 0) {
         throw new Error(`exitBlock must be a non-negative integer, got ${JSON.stringify(params.exitBlock)}`);
     }
-    return [
+    const lines = [
         'LET EPOCH=STATE(101)',
-        'LET EXITBLOCK=STATE(102)',
+        'LET EXITBLOCK=PREVSTATE(102)',
         'IF @BLOCK GT EXITBLOCK THEN',
-        `  RETURN SIGNEDBY(${owner})`,
-        'ENDIF',
-        'ASSERT EPOCH GT PREVSTATE(101)',
-        'ASSERT SAMESTATE(102 102)',
-        'ASSERT VERIFYOUT(@INPUT @ADDRESS @AMOUNT @TOKENID TRUE)',
-        `RETURN MULTISIG(2 ${operator} ${owner})`,
-    ].join('\n');
+    ];
+    holders.forEach((holder, k) => {
+        const port = exports.POOL_SHARE_PORT_BASE + k;
+        lines.push(`  LET SHARE${k}=PREVSTATE(${port})`);
+        lines.push(`  IF SIGNEDBY(${holder}) THEN`);
+        lines.push(`    IF SHARE${k} GT 0 THEN`);
+        lines.push(`      ASSERT VERIFYOUT(0 ${holder} SHARE${k} @TOKENID FALSE)`);
+        for (let j = 0; j < holders.length; j++) {
+            if (j === k)
+                continue;
+            lines.push(`      ASSERT STATE(${exports.POOL_SHARE_PORT_BASE + j}) EQ PREVSTATE(${exports.POOL_SHARE_PORT_BASE + j})`);
+        }
+        lines.push(`      ASSERT STATE(${port}) EQ 0`);
+        // Remainder (other holders' shares) stays in the pool; skip it when the
+        // withdrawing holder's share is the whole pool (no room for another output).
+        lines.push(`      IF @AMOUNT GT SHARE${k} THEN`);
+        lines.push(`        RETURN VERIFYOUT(@INPUT @ADDRESS @AMOUNT SUB SHARE${k} @TOKENID TRUE)`);
+        lines.push('      ENDIF');
+        lines.push('      RETURN TRUE');
+        lines.push('    ENDIF');
+        lines.push('  ENDIF');
+    });
+    lines.push('ENDIF');
+    lines.push('ASSERT EPOCH GT PREVSTATE(101)');
+    lines.push('ASSERT SAMESTATE(102 102)');
+    lines.push('ASSERT VERIFYOUT(@INPUT @ADDRESS @AMOUNT @TOKENID TRUE)');
+    lines.push(`RETURN MULTISIG(${holders.length + 1} ${operator} ${holders.join(' ')})`);
+    return lines.join('\n');
 }
 function poolScriptAddress(script) {
     return (0, core_1.computeScriptAddress)(script);

package/dist/exit-tx.d.ts

@@ -1,21 +1,20 @@
 /**
- * VTXO exit transaction (RFC-038 V2 — owner-unilateral).
+ * VTXO exit transaction (RFC-038 V3 — per-share, owner-signed).
  *
- * The exit spends the pool's on-chain coin and pays the VTXO's owner, carrying
- * the exit delay in STATE(110). It is signed with the **owner's** key (not the
- * operator's): the pool script's `IF @BLOCK GT EXITBLOCK THEN RETURN
- * SIGNEDBY(OWNER)` branch authorizes it after the exit window, so the owner can
- * broadcast it without any operator signature or liveness. The digest is signed
- * (injected signer) and, when a chain provider is supplied, mined + broadcast
- * (injected miner).
+ * The exit spends the pool's on-chain coin and pays the exiting holder **only
+ * its committed share** (`shares[holderIndex]`), returning the remainder to the
+ * pool with that holder's share state zeroed. It is signed with the holder's key
+ * — the pool script's `IF @BLOCK GT EXITBLOCK … IF SIGNEDBY(holder) … VERIFYOUT(0
+ * holder SHARE @TOKENID FALSE)` branch authorizes it, so the holder can broadcast
+ * without any operator signature or liveness, and cannot take more than its share.
  *
- * The caller must pass the owner signer; the operator cannot construct a valid
- * exit witness for itself.
+ * The caller must pass the holder signer; neither the operator nor another holder
+ * can build a valid witness for this holder's share.
  */
 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 on the owner's output. */
+/** State port carrying an optional exit delay on the holder's output. */
 export declare const EXIT_DELAY_PORT = 110;
 export interface ExitTxParams {
     vtxo: OmniaVtxo;
@@ -23,12 +22,19 @@ export interface ExitTxParams {
     fundingCoinId: string;
     fundingAddress: string;
     fundingScript: string;
-    /** Raw base-unit amount to pay the owner (the VTXO amount, pre-scaled). */
+    /** Total pool amount (raw base units). */
     amount: bigint;
-    /** Exit delay carried as STATE(102). */
-    exitDelayBlocks: number;
+    /** Pool holders + committed shares (aligned arrays). */
+    holders: string[];
+    shares: bigint[];
+    /** Index of the exiting holder (must match `vtxo.owner`). */
+    holderIndex: number;
+    /** Pool state, needed to rebuild the remainder output's state. */
+    root: string;
+    epoch: number;
+    exitBlock: number;
 }
-/** Draft that spends the pool coin to the VTXO owner with the exit delay encoded. */
+/** Draft that spends the pool coin: output 0 = holder's share, remainder = pool. */
 export declare function buildExitTransactionDraft(params: ExitTxParams): OmniaTxDraft;
 export declare function exitTransactionDigest(draft: OmniaTxDraft): Uint8Array;
 export declare function exitTransactionHex(draft: OmniaTxDraft): string;
@@ -44,14 +50,13 @@ export interface ExitTxDeps {
 export interface ExitTxResult {
     vtxoId: string;
     owner: string;
-    amount: string;
-    exitDelayBlocks: number;
+    share: string;
     draftType: 'vtxo-exit';
     txHex: string;
     digest: string;
     witnessHex: string;
     txpowId?: string;
 }
-/** Build, sign (and optionally mine + broadcast) a VTXO exit transaction. */
+/** Build, sign (and optionally mine + broadcast) a per-share VTXO exit transaction. */
 export declare function buildExitTransaction(params: ExitTxParams, deps: ExitTxDeps): Promise<ExitTxResult>;
 export {};

package/dist/exit-tx.js

@@ -1,27 +1,47 @@
 /**
- * VTXO exit transaction (RFC-038 V2 — owner-unilateral).
+ * VTXO exit transaction (RFC-038 V3 — per-share, owner-signed).
  *
- * The exit spends the pool's on-chain coin and pays the VTXO's owner, carrying
- * the exit delay in STATE(110). It is signed with the **owner's** key (not the
- * operator's): the pool script's `IF @BLOCK GT EXITBLOCK THEN RETURN
- * SIGNEDBY(OWNER)` branch authorizes it after the exit window, so the owner can
- * broadcast it without any operator signature or liveness. The digest is signed
- * (injected signer) and, when a chain provider is supplied, mined + broadcast
- * (injected miner).
+ * The exit spends the pool's on-chain coin and pays the exiting holder **only
+ * its committed share** (`shares[holderIndex]`), returning the remainder to the
+ * pool with that holder's share state zeroed. It is signed with the holder's key
+ * — the pool script's `IF @BLOCK GT EXITBLOCK … IF SIGNEDBY(holder) … VERIFYOUT(0
+ * holder SHARE @TOKENID FALSE)` branch authorizes it, so the holder can broadcast
+ * without any operator signature or liveness, and cannot take more than its share.
  *
- * The caller must pass the owner signer; the operator cannot construct a valid
- * exit witness for itself.
+ * The caller must pass the holder signer; neither the operator nor another holder
+ * can build a valid witness for this holder's share.
  */
 import { computeOmniaTxDigest, omniaDraftToMinimaBytes, serializeTxDraft, } from '@totemsdk/omnia';
 import { serializeTxBody, mineTxPoW, TX_POW_MIN_DIFFICULTY } from '@totemsdk/txpow';
 import { concatBytes } from '@totemsdk/core';
-/** State port carrying the exit delay on the owner's output. */
+import { poolStateVariables } from './anchor.js';
+/** State port carrying an optional exit delay on the holder's output. */
 export const EXIT_DELAY_PORT = 110;
-/** Draft that spends the pool coin to the VTXO owner with the exit delay encoded. */
+/** Draft that spends the pool coin: output 0 = holder's share, remainder = pool. */
 export function buildExitTransactionDraft(params) {
-    const stateVariables = [
-        { port: EXIT_DELAY_PORT, value: BigInt(params.exitDelayBlocks), type: 'number' },
-    ];
+    const share = params.shares[params.holderIndex];
+    if (share === undefined)
+        throw new Error('exit: holderIndex out of range');
+    if (share <= 0n)
+        throw new Error('exit: holder share must be positive');
+    const outputs = [{
+            address: params.vtxo.owner,
+            amount: share,
+            tokenId: params.vtxo.tokenId,
+            storeState: false,
+            stateVariables: [],
+        }];
+    const carriesState = params.amount > share;
+    if (carriesState) {
+        const remaining = params.shares.map((s, i) => (i === params.holderIndex ? 0n : s));
+        outputs.push({
+            address: params.fundingAddress,
+            amount: params.amount - share,
+            tokenId: params.vtxo.tokenId,
+            storeState: true,
+            stateVariables: poolStateVariables(params.root, params.epoch, params.exitBlock, remaining),
+        });
+    }
     return {
         type: 'settlement',
         inputs: [{
@@ -31,15 +51,9 @@ export function buildExitTransactionDraft(params) {
                 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,
+        outputs,
+        storeState: carriesState,
+        stateVariables: [],
     };
 }
 export function exitTransactionDigest(draft) {
@@ -48,7 +62,7 @@ export function exitTransactionDigest(draft) {
 export function exitTransactionHex(draft) {
     return serializeTxDraft(draft);
 }
-/** Build, sign (and optionally mine + broadcast) a VTXO exit transaction. */
+/** Build, sign (and optionally mine + broadcast) a per-share VTXO exit transaction. */
 export async function buildExitTransaction(params, deps) {
     const draft = buildExitTransactionDraft(params);
     const digest = exitTransactionDigest(draft);
@@ -56,8 +70,7 @@ export async function buildExitTransaction(params, deps) {
     const result = {
         vtxoId: params.vtxo.vtxoId,
         owner: params.vtxo.owner,
-        amount: params.vtxo.amount.toString(),
-        exitDelayBlocks: params.exitDelayBlocks,
+        share: params.shares[params.holderIndex].toString(),
         draftType: 'vtxo-exit',
         txHex: exitTransactionHex(draft),
         digest: Buffer.from(digest).toString('hex'),

package/dist/pool-script.d.ts

@@ -1,33 +1,38 @@
 /**
- * VTXO pool on-chain script (RFC-038 V2 — non-custodial).
+ * VTXO pool on-chain script (RFC-038 V3 — per-share non-custodial).
  *
  * The pool is an on-chain state output holding `totalCapacity`. An epoch's batch
- * root is committed as STATE(100), the epoch number in STATE(101), and the
- * owner's absolute exit-eligibility block in STATE(102).
+ * root is committed as STATE(100), the epoch number in STATE(101), the absolute
+ * exit-eligibility block in STATE(102), and each holder's committed share in
+ * STATE(200+k).
  *
- * Custody (RFC-044 / CUSTODY-POLICY §2):
- *   - **Unilateral owner exit.** After `@BLOCK GT EXITBLOCK` the owner alone may
- *     spend (`RETURN SIGNEDBY(OWNER)`) — no operator signature or liveness. This
- *     is exercised by the pre-signed exit tx (`exit-tx.ts`).
+ * Custody (RFC-039 / CUSTODY-POLICY §2):
+ *   - **Per-share unilateral exit.** After `@BLOCK GT PREVSTATE(102)` each holder
+ *     may withdraw **only its own committed share** (`PREVSTATE(200+k)`, the spent
+ *     coin's share), to its own key, zeroing that share in the successor
+ *     (`STATE(200+k) EQ 0`) and returning the remainder to the pool. A holder
+ *     cannot pay itself more than its share, so one holder can never rug the others.
  *   - **Cooperative update.** Before the exit window the pool may only move by
- *     `MULTISIG(2 OPERATOR OWNER)`, epoch-monotone (`ASSERT EPOCH GT
+ *     `MULTISIG(operator + all holders)`, epoch-monotone (`ASSERT EPOCH GT
  *     PREVSTATE(101)`), with the exit block immutable (`ASSERT SAMESTATE(102
- *     102)`) so the operator can never push the owner's escape clock, and the
- *     value confined to the same script address (`ASSERT VERIFYOUT(@INPUT
- *     @ADDRESS @AMOUNT @TOKENID TRUE)`) so the operator can never pay itself.
+ *     102)`) so no one can push the escape clock, and value confined to the same
+ *     script address (`ASSERT VERIFYOUT(@INPUT @ADDRESS @AMOUNT @TOKENID TRUE)`)
+ *     so the operator can never pay itself.
  *
- * The operator holds no unilateral path: it cannot move funds, cannot advance
- * the exit block, and cannot stop the owner's exit. It is a liveness-only peer.
+ * The operator holds no unilateral path: it cannot move funds, cannot advance the
+ * exit block, and cannot stop a holder's exit. It is a liveness-only peer.
  */
+/** State port base for per-holder shares: holder k ⇒ port 200+k (ports are bytes, ≤255). */
+export declare const POOL_SHARE_PORT_BASE = 200;
 export interface PoolScriptParams {
     /** Operator WOTS public-key digest (64 hex). */
     operatorPublicKeyDigest: string;
-    /** Pool owner WOTS public-key digest (64 hex). */
-    ownerPublicKeyDigest: string;
-    /** Absolute block height after which the owner may exit unilaterally. */
+    /** Holder WOTS public-key digests (64 hex), one per beneficial owner. */
+    holders: string[];
+    /** Absolute block height after which holders may exit unilaterally. */
     exitBlock: number;
 }
-/** Non-custodial, epoch-monotone, owner-escapable state-carrying pool script. */
+/** Per-share-constrained, epoch-monotone, state-carrying pool script. */
 export declare function buildPoolScript(params: PoolScriptParams): string;
 export declare function poolScriptAddress(script: string): string;
 export declare function buildAndHashPoolScript(params: PoolScriptParams): {

package/dist/pool-script.js

@@ -1,25 +1,30 @@
 /**
- * VTXO pool on-chain script (RFC-038 V2 — non-custodial).
+ * VTXO pool on-chain script (RFC-038 V3 — per-share non-custodial).
  *
  * The pool is an on-chain state output holding `totalCapacity`. An epoch's batch
- * root is committed as STATE(100), the epoch number in STATE(101), and the
- * owner's absolute exit-eligibility block in STATE(102).
+ * root is committed as STATE(100), the epoch number in STATE(101), the absolute
+ * exit-eligibility block in STATE(102), and each holder's committed share in
+ * STATE(200+k).
  *
- * Custody (RFC-044 / CUSTODY-POLICY §2):
- *   - **Unilateral owner exit.** After `@BLOCK GT EXITBLOCK` the owner alone may
- *     spend (`RETURN SIGNEDBY(OWNER)`) — no operator signature or liveness. This
- *     is exercised by the pre-signed exit tx (`exit-tx.ts`).
+ * Custody (RFC-039 / CUSTODY-POLICY §2):
+ *   - **Per-share unilateral exit.** After `@BLOCK GT PREVSTATE(102)` each holder
+ *     may withdraw **only its own committed share** (`PREVSTATE(200+k)`, the spent
+ *     coin's share), to its own key, zeroing that share in the successor
+ *     (`STATE(200+k) EQ 0`) and returning the remainder to the pool. A holder
+ *     cannot pay itself more than its share, so one holder can never rug the others.
  *   - **Cooperative update.** Before the exit window the pool may only move by
- *     `MULTISIG(2 OPERATOR OWNER)`, epoch-monotone (`ASSERT EPOCH GT
+ *     `MULTISIG(operator + all holders)`, epoch-monotone (`ASSERT EPOCH GT
  *     PREVSTATE(101)`), with the exit block immutable (`ASSERT SAMESTATE(102
- *     102)`) so the operator can never push the owner's escape clock, and the
- *     value confined to the same script address (`ASSERT VERIFYOUT(@INPUT
- *     @ADDRESS @AMOUNT @TOKENID TRUE)`) so the operator can never pay itself.
+ *     102)`) so no one can push the escape clock, and value confined to the same
+ *     script address (`ASSERT VERIFYOUT(@INPUT @ADDRESS @AMOUNT @TOKENID TRUE)`)
+ *     so the operator can never pay itself.
  *
- * The operator holds no unilateral path: it cannot move funds, cannot advance
- * the exit block, and cannot stop the owner's exit. It is a liveness-only peer.
+ * The operator holds no unilateral path: it cannot move funds, cannot advance the
+ * exit block, and cannot stop a holder's exit. It is a liveness-only peer.
  */
 import { computeScriptAddress } from '@totemsdk/core';
+/** State port base for per-holder shares: holder k ⇒ port 200+k (ports are bytes, ≤255). */
+export const POOL_SHARE_PORT_BASE = 200;
 function pkHex(digest, label) {
     const raw = digest.replace(/^0x/i, '');
     if (!/^[0-9a-fA-F]{64}$/.test(raw)) {
@@ -27,24 +32,48 @@ function pkHex(digest, label) {
     }
     return '0X' + raw.toUpperCase();
 }
-/** Non-custodial, epoch-monotone, owner-escapable state-carrying pool script. */
+/** Per-share-constrained, epoch-monotone, state-carrying pool script. */
 export function buildPoolScript(params) {
-    const owner = pkHex(params.ownerPublicKeyDigest, 'owner');
     const operator = pkHex(params.operatorPublicKeyDigest, 'operator');
+    if (!Array.isArray(params.holders) || params.holders.length < 1) {
+        throw new Error('pool requires at least one holder');
+    }
+    const holders = params.holders.map((h, i) => pkHex(h, `holder[${i}]`));
     if (!Number.isInteger(params.exitBlock) || params.exitBlock < 0) {
         throw new Error(`exitBlock must be a non-negative integer, got ${JSON.stringify(params.exitBlock)}`);
     }
-    return [
+    const lines = [
         'LET EPOCH=STATE(101)',
-        'LET EXITBLOCK=STATE(102)',
+        'LET EXITBLOCK=PREVSTATE(102)',
         'IF @BLOCK GT EXITBLOCK THEN',
-        `  RETURN SIGNEDBY(${owner})`,
-        'ENDIF',
-        'ASSERT EPOCH GT PREVSTATE(101)',
-        'ASSERT SAMESTATE(102 102)',
-        'ASSERT VERIFYOUT(@INPUT @ADDRESS @AMOUNT @TOKENID TRUE)',
-        `RETURN MULTISIG(2 ${operator} ${owner})`,
-    ].join('\n');
+    ];
+    holders.forEach((holder, k) => {
+        const port = POOL_SHARE_PORT_BASE + k;
+        lines.push(`  LET SHARE${k}=PREVSTATE(${port})`);
+        lines.push(`  IF SIGNEDBY(${holder}) THEN`);
+        lines.push(`    IF SHARE${k} GT 0 THEN`);
+        lines.push(`      ASSERT VERIFYOUT(0 ${holder} SHARE${k} @TOKENID FALSE)`);
+        for (let j = 0; j < holders.length; j++) {
+            if (j === k)
+                continue;
+            lines.push(`      ASSERT STATE(${POOL_SHARE_PORT_BASE + j}) EQ PREVSTATE(${POOL_SHARE_PORT_BASE + j})`);
+        }
+        lines.push(`      ASSERT STATE(${port}) EQ 0`);
+        // Remainder (other holders' shares) stays in the pool; skip it when the
+        // withdrawing holder's share is the whole pool (no room for another output).
+        lines.push(`      IF @AMOUNT GT SHARE${k} THEN`);
+        lines.push(`        RETURN VERIFYOUT(@INPUT @ADDRESS @AMOUNT SUB SHARE${k} @TOKENID TRUE)`);
+        lines.push('      ENDIF');
+        lines.push('      RETURN TRUE');
+        lines.push('    ENDIF');
+        lines.push('  ENDIF');
+    });
+    lines.push('ENDIF');
+    lines.push('ASSERT EPOCH GT PREVSTATE(101)');
+    lines.push('ASSERT SAMESTATE(102 102)');
+    lines.push('ASSERT VERIFYOUT(@INPUT @ADDRESS @AMOUNT @TOKENID TRUE)');
+    lines.push(`RETURN MULTISIG(${holders.length + 1} ${operator} ${holders.join(' ')})`);
+    return lines.join('\n');
 }
 export function poolScriptAddress(script) {
     return computeScriptAddress(script);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totemsdk/omnia-vtxo",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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",
@@ -25,10 +25,10 @@
   ],
   "dependencies": {
     "@totemsdk/chain-provider": "^0.2.1",
-    "@totemsdk/omnia": "^2.0.0",
+    "@totemsdk/core": "^1.3.0",
+    "@totemsdk/omnia": "^2.0.1",
     "@totemsdk/storage": "^0.1.0",
     "@totemsdk/txpow": "^1.0.2",
-    "@totemsdk/core": "^1.2.11",
     "@totemsdk/wots-lease": "^1.0.1"
   },
   "devDependencies": {