@ottochain/sdk 2.4.0 → 2.5.0

package/dist/esm/apps/privacy/state-machines/note-pool.js

@@ -0,0 +1,470 @@
+/**
+ * shielded-note-pool — a Tornado-style fixed-denomination UTXO-private asset pool.
+ *
+ * One fiber instance is one shielded pool. The pool's PUBLIC state is the privacy
+ * scaffolding only — a Poseidon-Merkle commitment ROOT window, a spent-NULLIFIER set,
+ * an append-only output-COMMITMENT log, and the asset-record UUIDs the pool custodies.
+ * The real value model is a UTXO note layer that lives OFF-chain in notes committed to
+ * the tree; each spend is attested by a single Groth16 proof of the `zk-shielded` circuit.
+ *
+ * Division of labour (the Kachina/Midnight split — a general verifier in the VM, the
+ * shielded pool as ordinary state + transitions on top of it; see
+ * docs/design/ergo-patterns-as-fiber-primitives.md §"shielded-note-pool" and
+ * docs/design/shielded-transfer-app-sketch.md):
+ *   - the CIRCUIT proves membership (Poseidon-Merkle inclusion) ∧ authorization
+ *     (`owner == Poseidon([nsk])`) ∧ nullifier derivation (`nf == Poseidon([rho, nsk])`)
+ *     ∧ intra-transfer nullifier uniqueness ∧ per-asset conservation ∧ u64 range;
+ *   - this GUARD (combine) verifies the proof against the pinned `vkey`, binds the
+ *     public inputs by slicing them from the VERIFIED `publicValues` bytes, rejects an
+ *     already-spent nullifier (`none`), checks the spend's anchor is still honored
+ *     (`in [anchor, knownRoots]`), and pins the fee word to a configured value;
+ *   - the EFFECT (combine) spends the nullifier, logs the output commitment, advances
+ *     the rolling anchor window, and (on `unshield`) releases exactly one whole
+ *     `denom`-valued asset record to a clear recipient.
+ *
+ * It uses NO new metakit opcode. `groth16_verify` verifies the proof; the public-input
+ * words are extracted from the verified `publicValues` string with fixed-offset `substr`
+ * and re-prefixed `0x` (`{cat:['0x', {substr:[pv,off,64]}]}`) — slicing the verified
+ * bytes IS the binding, so no field can be mauled independently of the proof.
+ *
+ * ──────────────────────────────────────────────────────────────────────────────────────
+ *  ⚠ UNAUDITED — TEST ASSETS ONLY. The `zk-shielded` circuit and its Groth16 verifier are
+ *  UNAUDITED; BN254 is ~100-bit security. This MVP is test-assets-only and pins
+ *  N=1 input / M=1 output / zero fee, with a SINGLE TRUSTED RELAYER for root advancement.
+ *  Do NOT deploy with value-bearing assets until the circuit + verifier are audited and the
+ *  in-circuit `newRoot` (which removes the trusted relayer) has landed. See §"Scope" / the
+ *  Risks list in the design doc.
+ * ──────────────────────────────────────────────────────────────────────────────────────
+ *
+ * MVP constraints (CONFIRMED DEFAULTS):
+ *   - test assets only;
+ *   - single trusted relayer gates root advancement (`event.newRoot` is NOT in the proven
+ *     public values, so a non-relayer could otherwise flood `knownRoots` and evict honest
+ *     in-flight anchors — a real DoS). LATER: prove `newRoot` in-circuit and drop the relayer.
+ *   - fixed denomination; the deposit mint is transparent (Tornado-style), the amount is
+ *     hidden among same-`denom` notes (anonymity set = all live `denom` notes).
+ *
+ * On-chain primitive facts this builder relies on (re-verified against
+ * `@constellation-network/metagraph-sdk-jlvm@1.8.0-rc.5`, see tests/note-pool.test.ts):
+ *   - array APPEND is `merge([arr,[item]])` (flatten one level); `cat` on arrays ERRORS
+ *     ("Unexpected input for `cat`") — never use `cat` for array append on-chain;
+ *   - every crypto/compare value is `0x`-prefixed; an extracted word MUST be re-prefixed
+ *     `{cat:['0x', {substr:[pv,off,64]}]}` before comparing with a stored `0x` hash;
+ *   - `none [arr, {===:[{var:""}, x]}]` fires correctly (fresh→true, spent→false);
+ *   - `groth16_verify` on a garbage bundle returns `false` (graceful deny, never throws);
+ *   - `pmt_verify([root, leaf, index, [siblings]])` is Poseidon-Merkle inclusion with
+ *     ROOT-FIRST siblings and a leaf-position `index` (depth range-checked) — exported as
+ *     {@link pmtMembership} for off-chain witness building / a membership-gated variant.
+ */
+import { defineFiberApp, } from '../../../schema/fiber-app.js';
+import { signerIsParty } from '../../../schema/guards.js';
+import { transferAsset, toWallet } from '../../../schema/effects.js';
+// =============================================================================
+// Public-input layout the guard expects (for fixture / circuit generation)
+// =============================================================================
+/**
+ * The EXACT `publicValues` layout the guard slices, for the N=1 input / M=1 output MVP.
+ *
+ * `publicValues` is the abi-encoded `ShieldedTransferPublicValues` carried as a single
+ * `0x`-prefixed lowercase-hex string. Each 32-byte ABI word is 64 hex chars; word `w`
+ * begins at hex offset `2 + 64*w` (the leading `2` skips `0x`).
+ *
+ * `ShieldedTransferPublicValues { bytes32 anchor; bytes32[] nullifiers; bytes32[] outputCms;
+ *  uint64 fee; bytes32 feeAsset; }`. The circuit commits this via `alloy_sol_types::abi_encode`,
+ * which — the struct being a DYNAMIC tuple (it holds the two dynamic arrays) — emits a single leading
+ * `0x20` tuple-offset HEAD WORD before the struct body, then the body's own head of array offsets +
+ * a tail of (len, elems). For FIXED N=1/M=1 the tail is static and `substr`-addressable.
+ *
+ * ┌── field ─────────────┬── hex offset ─┬── width ─┬── notes ─────────────────────────────────┐
+ * │ tuple head (0x20)    │      2        │   64     │ abi_encode dynamic-tuple offset; NOT a field│
+ * │ anchor               │     66        │   64     │ Poseidon-Merkle root the inputs prove under │
+ * │ nullifiers off (0xa0)│    130        │   64     │ body-relative offset of the nullifiers array│
+ * │ outputCms  off (0xe0)│    194        │   64     │ body-relative offset of the outputCms array │
+ * │ fee  (uint64 word)   │    258        │   64     │ transparent fee, right-aligned in the word  │
+ * │ feeAsset             │    322        │   64     │ asset-as-Fr the fee is denominated in       │
+ * │ nullifiers.len       │    386        │   64     │ == 1 for the N=1 MVP                         │
+ * │ nullifiers[0]        │    450        │   64     │ the revealed input nullifier                │
+ * │ outputCms.len        │    514        │   64     │ == 1 for the M=1 MVP                         │
+ * │ outputCms[0]         │    578        │   64     │ the revealed output commitment              │
+ * └──────────────────────┴───────────────┴──────────┴─────────────────────────────────────────────┘
+ *
+ * The word ORDER and ENCODING a matching SP1 fixture MUST produce (so the placeholder can be
+ * swapped for a real proof): the `0x`-string is
+ *   0x ‖ 0x20 ‖ anchor ‖ nullifiers.off ‖ outputCms.off ‖ fee ‖ feeAsset ‖
+ *      nullifiers.len ‖ nullifiers[0] ‖ outputCms.len ‖ outputCms[0]
+ * laid out by the circuit's `commit_slice(abi_encode(ShieldedTransferPublicValues{..}))`, such that
+ * the five field offsets below land on the words above. Every word is a lowercase 32-byte hex with
+ * NO `0x` per-word prefix (the single `0x` is on the whole string).
+ *
+ * RECONCILED 2026-06 against the REAL `zk-shielded` circuit (~/repos/metakit-sdk/rust/zk-shielded):
+ * an earlier version of this layout omitted the leading `0x20` dynamic-tuple head word, so every
+ * offset was one 32-byte word (64 hex) too low and the guard sliced the WRONG words. The circuit is
+ * the source of truth; the offsets above were corrected (+64 each) to match a real SP1 Groth16 proof
+ * whose `publicValues` is `0x ‖ 0x20 ‖ anchor ‖ 0xa0 ‖ 0xe0 ‖ fee ‖ feeAsset ‖ 1 ‖ nf ‖ 1 ‖ cm`.
+ *
+ * cm / nf preimages (the circuit's, fixed and byte-for-byte across Scala/Rust/TS):
+ *   - `cm = Poseidon([value_as_fr, owner, asset, rho])` (4-input, MAX poseidon arity);
+ *   - `owner = Poseidon([nsk])`;
+ *   - `nf = Poseidon([rho, nsk])` (FIELD ORDER rho, nsk).
+ */
+export const PV_LAYOUT = {
+    /** anchor — word 1 (word 0 is the dynamic-tuple `0x20` head word; see the table). */
+    anchor: 66,
+    /** fee — word 4 (uint64 right-aligned). MVP pins this whole word to {@link NotePoolOptions.feeWord}. */
+    fee: 258,
+    /** feeAsset — word 5. */
+    feeAsset: 322,
+    /** nullifiers[0] — after the nullifiers length word @386. */
+    nullifier: 450,
+    /** outputCms[0] — after the outputCms length word @514. */
+    outputCm: 578,
+};
+// =============================================================================
+// Field extraction — slice the VERIFIED bytes, re-prefix 0x (the binding)
+// =============================================================================
+const WORD_HEX = 64; // a 32-byte ABI word as hex chars
+/**
+ * Lift `publicValues` word at hex `offset` back to a `0x`-hex value comparable with a stored
+ * `bytes32`/`hash`. `cat` of two STRINGS is valid on-chain; `cat` of arrays ERRORS — this is
+ * strings only. The slice is taken from the SAME bytes `groth16_verify` consumed, so a changed
+ * field invalidates the proof: re-prefixing the verified slice IS the public-input binding.
+ */
+export const pvField = (offset) => ({
+    cat: ['0x', { substr: [{ var: 'event.publicValues' }, offset, WORD_HEX] }],
+});
+/**
+ * `pmt_verify([root, leaf, index, [siblings]])` Poseidon-Merkle inclusion (root-first siblings,
+ * leaf-position `index`, depth = `siblings.length`, range-checked). Exported for off-chain witness
+ * building and for a membership-gated pool variant. NOTE: the MVP `transfer`/`unshield` guards do
+ * NOT call `pmt_verify` — membership is proven INSIDE the circuit (`verify_inclusion`) and bound to
+ * the verified `anchor`; the chain only checks `anchor ∈ knownRoots`. This helper exists so a
+ * downstream pool that wants an additional ON-CHAIN inclusion check (e.g. for a transparent leaf)
+ * can express it with the verified operand format.
+ */
+export const pmtMembership = (rootVar, leafVar, indexVar, siblingsVar) => ({ pmt_verify: [rootVar, leafVar, indexVar, siblingsVar] });
+/** The all-zero 32-byte word — the MVP `feeWord` (pins fee=0). */
+export const ZERO_WORD = '0x' + '0'.repeat(64);
+/** Public state every shielded note-pool carries (the note value model itself is private/off-chain). */
+export const NOTE_POOL_STATE = {
+    vkey: {
+        type: 'hash',
+        immutable: true,
+        description: 'zk-shielded program vkey (32B, 0x)',
+    },
+    depth: {
+        type: 'integer',
+        immutable: true,
+        description: 'merkle depth pinned at creation',
+    },
+    denom: {
+        type: 'integer',
+        immutable: true,
+        description: 'fixed note denomination (asset units)',
+    },
+    poolPolicyRef: {
+        type: 'string',
+        immutable: true,
+        description: 'asset policy the pool mints/burns note-records under',
+    },
+    feeAsset: {
+        type: 'hash',
+        immutable: true,
+        description: '0x Fr label fees are charged in (== asset-as-Fr)',
+    },
+    feeWord: {
+        type: 'hash',
+        immutable: true,
+        description: 'the EXACT 0x 32-byte word `fee` must equal (MVP: zero word)',
+    },
+    relayer: {
+        type: 'string',
+        immutable: true,
+        description: 'DAG address authorized to advance the root (MVP single trusted relayer)',
+    },
+    rootWindow: { type: 'integer', immutable: true, default: 64 },
+    currentRoot: { type: 'hash', computed: true },
+    knownRoots: {
+        type: 'array',
+        computed: true,
+        description: 'rolling window of valid anchors (0x)',
+    },
+    nullifiers: {
+        type: 'array',
+        computed: true,
+        description: 'spent set (0x); monotonic — O(n) `none` scan, see ceiling note',
+    },
+    commitments: {
+        type: 'array',
+        computed: true,
+        description: 'append-only output-commitment log (0x)',
+    },
+    noteRecords: {
+        type: 'array',
+        computed: true,
+        description: 'assetId UUIDs of live note-records the pool holds',
+    },
+    leafCount: { type: 'integer', computed: true, default: 0 },
+    transfers: { type: 'integer', computed: true, default: 0 },
+};
+// =============================================================================
+// Guard / effect builders
+// =============================================================================
+/** Extracted, 0x-re-prefixed public-input words (shared by `transfer` and `unshield`). */
+const pvWords = () => ({
+    anchor: pvField(PV_LAYOUT.anchor),
+    feeWord: pvField(PV_LAYOUT.fee),
+    feeAsset: pvField(PV_LAYOUT.feeAsset),
+    nullifier: pvField(PV_LAYOUT.nullifier),
+    newCm: pvField(PV_LAYOUT.outputCm),
+});
+/**
+ * The proof + nullifier + anchor + fee binding shared by every spend (combiner-only, all
+ * stateful). Binds against the EXACT verified bytes: any field change invalidates the Groth16.
+ */
+const spendBinding = (w) => [
+    // 1. the proof verifies against the pool's pinned vkey over EXACTLY these public bytes
+    {
+        groth16_verify: [{ var: 'state.vkey' }, { var: 'event.publicValues' }, { var: 'event.proof' }],
+    },
+    // 2. the spend's anchor is a root we produced and still honor
+    { in: [w.anchor, { var: 'state.knownRoots' }] },
+    // 3. INTER-transfer double-spend: the (0x-prefixed) nullifier is not already spent
+    {
+        none: [{ var: 'state.nullifiers' }, { '===': [{ var: '' }, w.nullifier] }],
+    },
+    // 4. no fee-asset spoofing
+    { '===': [w.feeAsset, { var: 'state.feeAsset' }] },
+    // 5. no value siphon via fee: the whole fee word is pinned (MVP: the zero word ⇒ fee==0)
+    { '===': [w.feeWord, { var: 'state.feeWord' }] },
+];
+/**
+ * Build the shielded-note-pool fiber app.
+ *
+ * Single state `ACTIVE → ACTIVE` with three transitions:
+ *   - `transfer`  — note-to-note spend (no public asset move); advances the tree. Relayer-gated.
+ *   - `noteMinted`— witness transition recording a deposit's commitment + record UUID (the deposit
+ *                   itself is an asset-model `MintAsset` into `Fiber(poolId)`, gated by the
+ *                   `poolPolicyRef` mintPolicy — NOT a fiber transition).
+ *   - `unshield`  — burn a note (nullify), release one whole `denom` note-record to a clear recipient.
+ *                   Self-sufficient because it is CASCADE-REACHABLE (asset transfers fire from cascades).
+ */
+export function notePoolDef(opts) {
+    const feeWord = opts.feeWord ?? ZERO_WORD;
+    const w = pvWords();
+    // --- transfer: note-to-note spend, advance the rolling anchor window ---------------------
+    const transferGuard = {
+        and: [
+            ...spendBinding(w),
+            // Root-advance authz: only the pinned relayer's signed `transfer` advances the tree, so a
+            // non-relayer cannot flood `knownRoots` and evict honest in-flight anchors (DoS). Uses
+            // `proofs[].address` (verified signers) — NOT a forgeable `event.*` field.
+            signerIsParty('state.relayer'),
+        ],
+    };
+    const transferEffect = {
+        merge: [
+            { var: 'state' },
+            {
+                // append via merge (NOT cat — cat errors on arrays on-chain)
+                nullifiers: { merge: [{ var: 'state.nullifiers' }, [w.nullifier]] },
+                commitments: { merge: [{ var: 'state.commitments' }, [w.newCm]] },
+                currentRoot: { var: 'event.newRoot' },
+                // append newRoot, then trim to the last rootWindow anchors via negative-start slice
+                knownRoots: {
+                    slice: [
+                        {
+                            merge: [{ var: 'state.knownRoots' }, [{ var: 'event.newRoot' }]],
+                        },
+                        { '*': [-1, { var: 'state.rootWindow' }] },
+                    ],
+                },
+                leafCount: { '+': [{ var: 'state.leafCount' }, 1] },
+                transfers: { '+': [{ var: 'state.transfers' }, 1] },
+            },
+        ],
+    };
+    // --- noteMinted: witness a deposit (record its commitment + record UUID) ------------------
+    // The deposit is an asset-model MintAsset of a `denom`-valued record into Fiber(poolId), gated by
+    // the poolPolicyRef mintPolicy (pins amount==denom, holder==pool, depositor-signed). This witness
+    // transition only records bookkeeping; `unshield` independently re-checks record custody at
+    // withdrawal (the asset combiner's R1 holder defense), so a forged noteMinted cannot extract value.
+    const noteMintedGuard = {
+        // the depositor (who signed the mint) signs this witness; the commitment + recordId are theirs.
+        // No balance read (no guard can witness an escrow). The release-time custody check is the real gate.
+        and: [signerIsParty('event.depositor')],
+    };
+    const noteMintedEffect = {
+        merge: [
+            { var: 'state' },
+            {
+                commitments: {
+                    merge: [{ var: 'state.commitments' }, [{ var: 'event.commitment' }]],
+                },
+                noteRecords: {
+                    merge: [{ var: 'state.noteRecords' }, [{ var: 'event.recordId' }]],
+                },
+                leafCount: { '+': [{ var: 'state.leafCount' }, 1] },
+            },
+        ],
+    };
+    // --- unshield: burn a note, release exactly one whole note-record ------------------------
+    const unshieldGuard = {
+        and: [
+            ...spendBinding(w),
+            // can only release a record the pool actually holds (combiner R1 holder defense re-checks too)
+            { in: [{ var: 'event.recordId' }, { var: 'state.noteRecords' }] },
+        ],
+    };
+    const unshieldEffect = {
+        merge: [
+            { var: 'state' },
+            {
+                nullifiers: { merge: [{ var: 'state.nullifiers' }, [w.nullifier]] },
+                // remove the released record id from the live set
+                noteRecords: {
+                    filter: [{ var: 'state.noteRecords' }, { '!==': [{ var: '' }, { var: 'event.recordId' }] }],
+                },
+                transfers: { '+': [{ var: 'state.transfers' }, 1] },
+                // release exactly one whole denom-valued record to a clear recipient wallet
+                ...transferAsset([
+                    {
+                        assetId: { var: 'event.recordId' },
+                        recipient: toWallet({ var: 'event.recipient' }),
+                    },
+                ]),
+            },
+        ],
+    };
+    return defineFiberApp({
+        metadata: {
+            name: 'ShieldedNotePool',
+            app: 'privacy',
+            type: 'shielded-note-pool',
+            version: '0.1.0',
+            description: 'UNAUDITED, TEST-ASSETS-ONLY fixed-denomination UTXO-private asset pool over the zk-shielded ' +
+                'Groth16 circuit (BN254 ~100-bit). Notes live off-chain in a Poseidon-Merkle tree; spends are ' +
+                'attested by a Groth16 proof. Public state = nullifier set + anchor window + commitment log. ' +
+                'Single trusted relayer advances the root (MVP). Do NOT deploy with value-bearing assets.',
+        },
+        createSchema: {
+            required: ['vkey', 'depth', 'denom', 'poolPolicyRef', 'feeAsset', 'relayer'],
+            properties: {
+                vkey: { type: 'hash', immutable: true, default: opts.vkey },
+                depth: { type: 'integer', immutable: true, default: opts.depth },
+                denom: { type: 'integer', immutable: true, default: opts.denom },
+                poolPolicyRef: {
+                    type: 'string',
+                    immutable: true,
+                    default: opts.poolPolicyRef,
+                },
+                feeAsset: { type: 'hash', immutable: true, default: opts.feeAsset },
+                feeWord: { type: 'hash', immutable: true, default: feeWord },
+                relayer: { type: 'string', immutable: true, default: opts.relayer },
+                rootWindow: {
+                    type: 'integer',
+                    immutable: true,
+                    default: opts.rootWindow ?? 64,
+                },
+            },
+        },
+        stateSchema: { properties: { ...NOTE_POOL_STATE } },
+        eventSchemas: {
+            transfer: {
+                description: 'Note-to-note shielded spend (N=1/M=1), attested by a zk-shielded Groth16 proof; advances the tree.',
+                required: ['proof', 'publicValues', 'newRoot'],
+                properties: {
+                    proof: {
+                        type: 'string',
+                        description: 'Groth16 proof bytes (0x hex)',
+                    },
+                    publicValues: {
+                        type: 'string',
+                        description: 'abi-encoded ShieldedTransferPublicValues (0x hex); see PV_LAYOUT',
+                    },
+                    newRoot: {
+                        type: 'hash',
+                        description: 'wallet/relayer-computed root after appending outputCms[0]',
+                    },
+                },
+            },
+            noteMinted: {
+                description: "Witness a deposit: record its commitment + the minted note-record's UUID.",
+                required: ['commitment', 'recordId', 'depositor'],
+                properties: {
+                    commitment: {
+                        type: 'hash',
+                        description: 'client-computed cm = Poseidon([denom, owner, feeAsset, rho]) (0x)',
+                    },
+                    recordId: {
+                        type: 'uuid',
+                        description: 'assetId of the denom-valued record minted into Fiber(poolId)',
+                    },
+                    depositor: {
+                        type: 'address',
+                        description: 'DAG address of the depositor who signed the mint',
+                    },
+                },
+            },
+            unshield: {
+                description: 'Burn a note, release one whole denom-valued note-record to a clear recipient.',
+                required: ['proof', 'publicValues', 'recordId', 'recipient'],
+                properties: {
+                    proof: {
+                        type: 'string',
+                        description: 'Groth16 proof bytes (0x hex)',
+                    },
+                    publicValues: {
+                        type: 'string',
+                        description: 'abi-encoded ShieldedTransferPublicValues (0x hex); see PV_LAYOUT',
+                    },
+                    recordId: {
+                        type: 'uuid',
+                        description: 'note-record to release; MUST be in state.noteRecords',
+                    },
+                    recipient: {
+                        type: 'address',
+                        description: 'clear DAG address that receives the released record',
+                    },
+                },
+            },
+        },
+        states: {
+            ACTIVE: {
+                id: 'ACTIVE',
+                isFinal: false,
+                metadata: {
+                    label: 'Active',
+                    description: 'Pool accepts shielded transfers, deposits, and withdrawals',
+                    category: 'active',
+                },
+            },
+        },
+        initialState: 'ACTIVE',
+        transitions: [
+            {
+                from: 'ACTIVE',
+                to: 'ACTIVE',
+                eventName: 'transfer',
+                guard: transferGuard,
+                effect: transferEffect,
+                dependencies: [],
+            },
+            {
+                from: 'ACTIVE',
+                to: 'ACTIVE',
+                eventName: 'noteMinted',
+                guard: noteMintedGuard,
+                effect: noteMintedEffect,
+                dependencies: [],
+            },
+            {
+                from: 'ACTIVE',
+                to: 'ACTIVE',
+                eventName: 'unshield',
+                guard: unshieldGuard,
+                effect: unshieldEffect,
+                dependencies: [],
+            },
+        ],
+    });
+}

package/dist/esm/apps/staked-pool/assets.js

@@ -0,0 +1,91 @@
+/**
+ * Asset-subsystem integration for the staked-pool family.
+ *
+ * Two asset roles:
+ *   - STAKE token: a governed fungible. Joining is a custody `Transfer` of the whole stake instance into
+ *     `AssetHolder.Fiber(poolId)` (the loan family's "lock = Transfer into Fiber holder" pattern); the
+ *     pool's `stake_and_join` guard verifies the custody via `heldAssets` (H5). Withdraw/slash move it back
+ *     out via the fiber's `_transferAsset` directive.
+ *   - REWARD token: a shared fungible the pool pre-holds. `claim_reward` moves ONE whole reward instance to
+ *     a verified in-consensus claimant (per-claim model — the whole-asset transfer has no amount field).
+ *
+ * Reuses the lending family's asset payload builders (`createAssetPolicyPayload`, `createMintAssetPayload`,
+ * `createApplyMorphismPayload`, `fiberHolder`, `walletHolder`) — re-exported here so a staked-pool caller
+ * has a single import surface.
+ */
+import { createAssetPolicyPayload, createMintAssetPayload, createApplyMorphismPayload, fiberHolder, walletHolder, TokenBehaviors, } from '../lending/assets.js';
+export { createAssetPolicyPayload, createMintAssetPayload, createApplyMorphismPayload, fiberHolder, walletHolder, TokenBehaviors, };
+/**
+ * Stake-token policy: a governed fungible. `Transfer` is the custody move into/out of the pool fiber.
+ * Transferable so withdraw/slash can return it (a soulbound stake would fail the R1 transferable check
+ * on withdraw — see design §11; not the default here).
+ */
+export function stakePolicy(name = 'staked-pool-stake-v1.asset', version = '1.0.0') {
+    return {
+        name,
+        version,
+        behavior: TokenBehaviors.GovernedFungible,
+        supply: {
+            maxSupply: null,
+            mintPolicy: null,
+            // Only the holder may burn their own stake (defensive; the pool moves it via Transfer, not Burn).
+            burnPolicy: { in: [{ var: 'holder.Wallet.address' }, { var: 'signers' }] },
+            decimals: 0,
+        },
+        morphisms: {
+            // Custody Transfer is the join/withdraw mechanism; gated so the pool fiber authorizes movement.
+            Transfer: { visibility: 'Public' },
+            Burn: { visibility: 'Public' },
+        },
+        stateShape: {},
+        metadata: { family: 'staked-pool', role: 'stake' },
+    };
+}
+/**
+ * Reward-pot policy: a shared fungible the pool pre-holds and pays out one whole instance per claim.
+ * `mintGuard` (optional) gates who may mint reward instances into the pool (e.g. the pool authority);
+ * omit for an open mint pinned operationally.
+ */
+export function rewardPotPolicy(mintGuard = null, name = 'staked-pool-reward-v1.asset', version = '1.0.0') {
+    return {
+        name,
+        version,
+        behavior: TokenBehaviors.Fungible,
+        supply: {
+            maxSupply: null,
+            mintPolicy: mintGuard,
+            burnPolicy: null,
+            decimals: 0,
+        },
+        morphisms: {
+            Transfer: { visibility: 'Public' },
+        },
+        stateShape: {},
+        metadata: { family: 'staked-pool', role: 'reward' },
+    };
+}
+/**
+ * stake_and_join driver: the participant Transfers their whole stake instance into the pool fiber BEFORE
+ * the `stake_and_join` event (custody = Transfer to `AssetHolder.Fiber`). Mirrors `lockCollateralOp`.
+ */
+export function stakeJoinOp(args) {
+    return createApplyMorphismPayload({
+        assetId: args.stakeAssetId,
+        kind: 'Transfer',
+        recipient: fiberHolder(args.poolFiberId),
+        targetSequenceNumber: args.targetSequenceNumber,
+    });
+}
+/**
+ * Pre-mint reward instances into the pool fiber (sized to expected claimants for the epoch). Mirrors
+ * `mintPrincipalOp` but mints to `Fiber(poolId)` so `claim_reward` can later transfer one whole instance.
+ */
+export function mintRewardInstancesOp(args) {
+    return createMintAssetPayload({
+        assetId: args.rewardAssetId,
+        policyRef: args.rewardPolicyRef,
+        holder: fiberHolder(args.poolFiberId),
+        amount: args.amount,
+        ...(args.witness ? { witness: args.witness } : {}),
+    });
+}