@totemsdk/omnia-vtxo 0.3.0 → 0.5.0

package/dist/anchor.d.ts

@@ -11,6 +11,12 @@ import { type OmniaTxDraft, type StateValue } from '@totemsdk/omnia';
 import type { ChainStateProvider } from '@totemsdk/chain-provider';
 export interface BatchAnchorParams {
     operatorPublicKeyDigest: string;
+    /** 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;
     epoch: number;
@@ -22,8 +28,8 @@ export interface BatchAnchorParams {
     amount: bigint;
     tokenId: string;
 }
-/** State variables carried by the pool output: STATE(100)=root, STATE(101)=epoch. */
-export declare function poolStateVariables(root: string, epoch: 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,25 +10,34 @@
 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';
-/** State variables carried by the pool output: STATE(100)=root, STATE(101)=epoch. */
-export function poolStateVariables(root, epoch) {
+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) {
-    const { script, address } = buildAndHashPoolScript(params.operatorPublicKeyDigest);
+    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,
+        holders: params.holders,
+        exitBlock: params.exitBlock,
+    });
     // The input must be the operator's own pool output, not a foreign script.
     if (params.fundingScript !== script) {
-        throw new Error('anchorBatch: fundingScript does not match the operator pool script');
+        throw new Error('anchorBatch: fundingScript does not match the pool script');
     }
     if (params.fundingAddress !== address) {
-        throw new Error('anchorBatch: fundingAddress does not match the operator pool address');
+        throw new Error('anchorBatch: fundingAddress does not match the pool address');
     }
-    const stateVariables = poolStateVariables(params.root, params.epoch);
+    const stateVariables = poolStateVariables(params.root, params.epoch, params.exitBlock, params.shares);
     return {
         type: 'settlement',
         inputs: [{

package/dist/cjs/anchor.d.ts

@@ -11,6 +11,12 @@ import { type OmniaTxDraft, type StateValue } from '@totemsdk/omnia';
 import type { ChainStateProvider } from '@totemsdk/chain-provider';
 export interface BatchAnchorParams {
     operatorPublicKeyDigest: string;
+    /** 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;
     epoch: number;
@@ -22,8 +28,8 @@ export interface BatchAnchorParams {
     amount: bigint;
     tokenId: string;
 }
-/** State variables carried by the pool output: STATE(100)=root, STATE(101)=epoch. */
-export declare function poolStateVariables(root: string, epoch: 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,24 +18,33 @@ 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");
-/** State variables carried by the pool output: STATE(100)=root, STATE(101)=epoch. */
-function poolStateVariables(root, epoch) {
+/** 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) {
-    const { script, address } = (0, pool_script_js_1.buildAndHashPoolScript)(params.operatorPublicKeyDigest);
+    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,
+        holders: params.holders,
+        exitBlock: params.exitBlock,
+    });
     // The input must be the operator's own pool output, not a foreign script.
     if (params.fundingScript !== script) {
-        throw new Error('anchorBatch: fundingScript does not match the operator pool script');
+        throw new Error('anchorBatch: fundingScript does not match the pool script');
     }
     if (params.fundingAddress !== address) {
-        throw new Error('anchorBatch: fundingAddress does not match the operator pool address');
+        throw new Error('anchorBatch: fundingAddress does not match the pool address');
     }
-    const stateVariables = poolStateVariables(params.root, params.epoch);
+    const stateVariables = poolStateVariables(params.root, params.epoch, params.exitBlock, params.shares);
     return {
         type: 'settlement',
         inputs: [{

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

@@ -1,32 +1,40 @@
 /**
- * VTXO exit transaction (RFC-038 V2).
+ * VTXO exit transaction (RFC-038 V3 — per-share, owner-signed).
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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. */
-export declare const EXIT_DELAY_PORT = 102;
+/** State port carrying an optional exit delay on the holder's output. */
+export declare const EXIT_DELAY_PORT = 110;
 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). */
+    /** 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;
@@ -42,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,15 +1,16 @@
 "use strict";
 /**
- * VTXO exit transaction (RFC-038 V2).
+ * VTXO exit transaction (RFC-038 V3 — per-share, owner-signed).
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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;
@@ -20,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. */
-exports.EXIT_DELAY_PORT = 102;
-/** Draft that spends the pool coin to the VTXO owner with the exit delay encoded. */
+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: 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: [{
@@ -36,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) {
@@ -53,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);
@@ -61,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,19 +1,40 @@
 /**
- * VTXO pool on-chain script (RFC-038 V1).
+ * 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) with the epoch number in STATE(101), and the
- * update requires a strictly-greater epoch (`ASSERT EPOCH GT PREVSTATE(101)`) so a
- * old root cannot be re-anchored (RFC-038 §5 "stale/rolled-back root").
+ * 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), the absolute
+ * exit-eligibility block in STATE(102), and each holder's committed share in
+ * STATE(300+k).
  *
- * CUSTODY NOTE: this script is currently **operator-only** (`SIGNEDBY(operator)`),
- * so until V2 lands the owner-unilateral timelock branch the pool output is
- * custodied by the operator on-chain. This is surfaced in RFC-038 §3.3/§5.
+ * Custody (RFC-039 / CUSTODY-POLICY §2):
+ *   - **Per-share unilateral exit.** After `@BLOCK GT EXITBLOCK` each holder may
+ *     withdraw **only its own committed share** (`STATE(300+k)`), to its own key,
+ *     zeroing that share 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(operator + all holders)`, epoch-monotone (`ASSERT EPOCH GT
+ *     PREVSTATE(101)`), with the exit block immutable (`ASSERT SAMESTATE(102
+ *     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 a holder's exit. It is a liveness-only peer.
  */
-/** Operator-controlled, epoch-monotone state-carrying pool script. */
-export declare function buildPoolScript(operatorPublicKeyDigest: string): string;
+/** 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;
+    /** Holder WOTS public-key digests (64 hex), one per beneficial owner. */
+    holders: string[];
+    /** Absolute block height after which holders may exit unilaterally. */
+    exitBlock: number;
+}
+/** 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(operatorPublicKeyDigest: string): {
+export declare function buildAndHashPoolScript(params: PoolScriptParams): {
     script: string;
     address: string;
 };

package/dist/cjs/pool-script.js

@@ -1,41 +1,89 @@
 "use strict";
 /**
- * VTXO pool on-chain script (RFC-038 V1).
+ * 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) with the epoch number in STATE(101), and the
- * update requires a strictly-greater epoch (`ASSERT EPOCH GT PREVSTATE(101)`) so a
- * old root cannot be re-anchored (RFC-038 §5 "stale/rolled-back root").
+ * 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), the absolute
+ * exit-eligibility block in STATE(102), and each holder's committed share in
+ * STATE(300+k).
  *
- * CUSTODY NOTE: this script is currently **operator-only** (`SIGNEDBY(operator)`),
- * so until V2 lands the owner-unilateral timelock branch the pool output is
- * custodied by the operator on-chain. This is surfaced in RFC-038 §3.3/§5.
+ * Custody (RFC-039 / CUSTODY-POLICY §2):
+ *   - **Per-share unilateral exit.** After `@BLOCK GT EXITBLOCK` each holder may
+ *     withdraw **only its own committed share** (`STATE(300+k)`), to its own key,
+ *     zeroing that share 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(operator + all holders)`, epoch-monotone (`ASSERT EPOCH GT
+ *     PREVSTATE(101)`), with the exit block immutable (`ASSERT SAMESTATE(102
+ *     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 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");
-function operatorPkHex(operatorPublicKeyDigest) {
-    const raw = operatorPublicKeyDigest.replace(/^0x/i, '');
+/** 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)) {
-        throw new Error(`operator public key digest must be 64 hex chars, got ${JSON.stringify(operatorPublicKeyDigest)}`);
+        throw new Error(`${label} public key digest must be 64 hex chars, got ${JSON.stringify(digest)}`);
     }
     return '0X' + raw.toUpperCase();
 }
-/** Operator-controlled, epoch-monotone state-carrying pool script. */
-function buildPoolScript(operatorPublicKeyDigest) {
-    return [
-        'LET ROOT=STATE(100)',
+/** Per-share-constrained, epoch-monotone, state-carrying pool script. */
+function buildPoolScript(params) {
+    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)}`);
+    }
+    const lines = [
         'LET EPOCH=STATE(101)',
-        'ASSERT EPOCH GT PREVSTATE(101)',
-        `RETURN SIGNEDBY(${operatorPkHex(operatorPublicKeyDigest)})`,
-    ].join('\n');
+        'LET EXITBLOCK=STATE(102)',
+        'IF @BLOCK GT EXITBLOCK THEN',
+    ];
+    holders.forEach((holder, k) => {
+        const port = exports.POOL_SHARE_PORT_BASE + k;
+        lines.push(`  LET SHARE${k}=STATE(${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);
 }
-function buildAndHashPoolScript(operatorPublicKeyDigest) {
-    const script = buildPoolScript(operatorPublicKeyDigest);
+function buildAndHashPoolScript(params) {
+    const script = buildPoolScript(params);
     return { script, address: poolScriptAddress(script) };
 }

package/dist/exit-tx.d.ts

@@ -1,32 +1,40 @@
 /**
- * VTXO exit transaction (RFC-038 V2).
+ * VTXO exit transaction (RFC-038 V3 — per-share, owner-signed).
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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. */
-export declare const EXIT_DELAY_PORT = 102;
+/** State port carrying an optional exit delay on the holder's output. */
+export declare const EXIT_DELAY_PORT = 110;
 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). */
+    /** 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;
@@ -42,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,25 +1,47 @@
 /**
- * VTXO exit transaction (RFC-038 V2).
+ * VTXO exit transaction (RFC-038 V3 — per-share, owner-signed).
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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. */
-export const EXIT_DELAY_PORT = 102;
-/** Draft that spends the pool coin to the VTXO owner with the exit delay encoded. */
+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: 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: [{
@@ -29,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) {
@@ -46,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);
@@ -54,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,19 +1,40 @@
 /**
- * VTXO pool on-chain script (RFC-038 V1).
+ * 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) with the epoch number in STATE(101), and the
- * update requires a strictly-greater epoch (`ASSERT EPOCH GT PREVSTATE(101)`) so a
- * old root cannot be re-anchored (RFC-038 §5 "stale/rolled-back root").
+ * 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), the absolute
+ * exit-eligibility block in STATE(102), and each holder's committed share in
+ * STATE(300+k).
  *
- * CUSTODY NOTE: this script is currently **operator-only** (`SIGNEDBY(operator)`),
- * so until V2 lands the owner-unilateral timelock branch the pool output is
- * custodied by the operator on-chain. This is surfaced in RFC-038 §3.3/§5.
+ * Custody (RFC-039 / CUSTODY-POLICY §2):
+ *   - **Per-share unilateral exit.** After `@BLOCK GT EXITBLOCK` each holder may
+ *     withdraw **only its own committed share** (`STATE(300+k)`), to its own key,
+ *     zeroing that share 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(operator + all holders)`, epoch-monotone (`ASSERT EPOCH GT
+ *     PREVSTATE(101)`), with the exit block immutable (`ASSERT SAMESTATE(102
+ *     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 a holder's exit. It is a liveness-only peer.
  */
-/** Operator-controlled, epoch-monotone state-carrying pool script. */
-export declare function buildPoolScript(operatorPublicKeyDigest: string): string;
+/** 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;
+    /** Holder WOTS public-key digests (64 hex), one per beneficial owner. */
+    holders: string[];
+    /** Absolute block height after which holders may exit unilaterally. */
+    exitBlock: number;
+}
+/** 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(operatorPublicKeyDigest: string): {
+export declare function buildAndHashPoolScript(params: PoolScriptParams): {
     script: string;
     address: string;
 };

package/dist/pool-script.js

@@ -1,36 +1,83 @@
 /**
- * VTXO pool on-chain script (RFC-038 V1).
+ * 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) with the epoch number in STATE(101), and the
- * update requires a strictly-greater epoch (`ASSERT EPOCH GT PREVSTATE(101)`) so a
- * old root cannot be re-anchored (RFC-038 §5 "stale/rolled-back root").
+ * 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), the absolute
+ * exit-eligibility block in STATE(102), and each holder's committed share in
+ * STATE(300+k).
  *
- * CUSTODY NOTE: this script is currently **operator-only** (`SIGNEDBY(operator)`),
- * so until V2 lands the owner-unilateral timelock branch the pool output is
- * custodied by the operator on-chain. This is surfaced in RFC-038 §3.3/§5.
+ * Custody (RFC-039 / CUSTODY-POLICY §2):
+ *   - **Per-share unilateral exit.** After `@BLOCK GT EXITBLOCK` each holder may
+ *     withdraw **only its own committed share** (`STATE(300+k)`), to its own key,
+ *     zeroing that share 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(operator + all holders)`, epoch-monotone (`ASSERT EPOCH GT
+ *     PREVSTATE(101)`), with the exit block immutable (`ASSERT SAMESTATE(102
+ *     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 a holder's exit. It is a liveness-only peer.
  */
 import { computeScriptAddress } from '@totemsdk/core';
-function operatorPkHex(operatorPublicKeyDigest) {
-    const raw = operatorPublicKeyDigest.replace(/^0x/i, '');
+/** 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)) {
-        throw new Error(`operator public key digest must be 64 hex chars, got ${JSON.stringify(operatorPublicKeyDigest)}`);
+        throw new Error(`${label} public key digest must be 64 hex chars, got ${JSON.stringify(digest)}`);
     }
     return '0X' + raw.toUpperCase();
 }
-/** Operator-controlled, epoch-monotone state-carrying pool script. */
-export function buildPoolScript(operatorPublicKeyDigest) {
-    return [
-        'LET ROOT=STATE(100)',
+/** Per-share-constrained, epoch-monotone, state-carrying pool script. */
+export function buildPoolScript(params) {
+    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)}`);
+    }
+    const lines = [
         'LET EPOCH=STATE(101)',
-        'ASSERT EPOCH GT PREVSTATE(101)',
-        `RETURN SIGNEDBY(${operatorPkHex(operatorPublicKeyDigest)})`,
-    ].join('\n');
+        'LET EXITBLOCK=STATE(102)',
+        'IF @BLOCK GT EXITBLOCK THEN',
+    ];
+    holders.forEach((holder, k) => {
+        const port = POOL_SHARE_PORT_BASE + k;
+        lines.push(`  LET SHARE${k}=STATE(${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);
 }
-export function buildAndHashPoolScript(operatorPublicKeyDigest) {
-    const script = buildPoolScript(operatorPublicKeyDigest);
+export function buildAndHashPoolScript(params) {
+    const script = buildPoolScript(params);
     return { script, address: poolScriptAddress(script) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totemsdk/omnia-vtxo",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Virtual UTXO / payment-pool claim layer for Omnia — cash-like off-chain balance primitive for Totem Edge",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
@@ -25,11 +25,11 @@
   ],
   "dependencies": {
     "@totemsdk/chain-provider": "^0.2.1",
-    "@totemsdk/omnia": "^1.0.3",
-    "@totemsdk/core": "^1.2.11",
+    "@totemsdk/omnia": "^2.0.1",
+    "@totemsdk/txpow": "^1.0.2",
     "@totemsdk/storage": "^0.1.0",
-    "@totemsdk/wots-lease": "^1.0.1",
-    "@totemsdk/txpow": "^1.0.2"
+    "@totemsdk/core": "^1.2.11",
+    "@totemsdk/wots-lease": "^1.0.1"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",