@ottochain/sdk 2.3.0 → 2.5.0

package/dist/types/apps/privacy/state-machines/mixer-ddhRing.d.ts

@@ -0,0 +1,337 @@
+import type { JsonLogicRule } from '../../../schema/fiber-app.js';
+/**
+ * sigma-mixer — a CDS OR-of-`dhtuple` Σ-protocol ring mixer.
+ *
+ * Anonymity comes from a Cramer–Damgård–Schoenmakers OR-proof over the deposited
+ * ring, verified by the `sigma_verify` JLVM opcode; double-spend safety comes
+ * from a WITNESS-BOUND nullifier carried as the shared DDH point of an
+ * OR-of-`dhtuple` proposition.
+ *
+ * Each ring branch is a DDH tuple `dhtuple(G, H, P_i, Nf)`. A satisfied dhtuple
+ * proves knowledge of one `x` with `P_i = x·G` AND `Nf = x·H` (the verifier uses
+ * a SINGLE shared response `z` for both coordinate reconstructions
+ * `a1 = z·G − e·P_i`, `a2 = z·H − e·Nf`). The OR uses the SAME
+ * `v = event.nullifier` in every branch, so it hides which branch while forcing
+ * `event.nullifier = x_j·H` for the one real branch `j`. With `H` a NUMS base of
+ * unknown dlog w.r.t. `G`, the map `x ↦ x·H` is injective, so the nullifier is
+ * cryptographically bound to the proven secret — closing the
+ * witness-unbound-nullifier double-spend hole an OR-of-`dlog` ring leaves open.
+ *
+ * Verified against `@constellation-network/metagraph-sdk-jlvm@1.8.0-rc.5`: the
+ * `sigma_verify` dhtuple operands are exactly `["type","g","h","u","v"]` (each a
+ * 64-byte G1 hex), the OR child challenges XOR to the node challenge, and the
+ * strong-FS root challenge folds the bound message. Array append uses `merge`
+ * (`merge([arr,[item]])` flattens one level == append). All operators used
+ * (`sigma_verify`, `has`, `set`, `none`, `cat`, `substr`, `merge`) are in
+ * KNOWN_OPERATORS.
+ *
+ * SCOPE: this base definition is CRYPTO + LIFECYCLE. Production custody
+ * (`_transferAsset` in on deposit / out on withdraw), a signer-bound deposit-auth
+ * clause, and a `mixerId`-prefixed bound message are layered on by a downstream
+ * specialization (see the §8 production-hardening note in the design doc).
+ */
+/**
+ * Emit the `or`-of-`dhtuple` proposition for an `n`-member ring, unrolling
+ * `{"var":"<pointsVar>.k"}` for `k in 0..n-1` as the `u` (commitment) of each
+ * branch, with `g = gHex`, `h = hHex` (literal 64-byte G1 hex) and a shared
+ * `v = {"var":"<nullifierVar>"}` across ALL branches.
+ *
+ * `n` is FIXED at definition time (the proposition shape is closed). `u` and `v`
+ * are `{"var":...}` map-node values that the evaluator resolves element-wise.
+ *
+ * @param pointsVar    state var holding the ordered ring points, e.g. `"state.points"`.
+ * @param nullifierVar event var holding the revealed nullifier, e.g. `"event.nullifier"`.
+ * @param gHex         the verifier generator `G=(1,2)` as 64-byte `0x` hex.
+ * @param hHex         the NUMS second base `H` as 64-byte `0x` hex (unknown dlog wrt G).
+ * @param n            ring size (number of unrolled branches).
+ */
+export declare function sigmaDdhRingOf(pointsVar: string, nullifierVar: string, gHex: string, hHex: string, n: number): JsonLogicRule;
+/**
+ * sigma-mixer fiber definition (pinned-ring v1, n=4).
+ *
+ * Trust model: PUBLIC. Anyone may deposit a ring point or submit a withdrawal.
+ * Privacy = a CDS OR-proof hides which of the n branches is being spent;
+ * anonymity set = exactly n (the ring size is public). Double-spend safety =
+ * the witness-bound nullifier + spent-set. Replay/front-run safety = the
+ * message-bound recipient.
+ */
+export declare const mixerDdhRingDef: {
+    metadata: {
+        name: string;
+        app: string;
+        type: string;
+        version: string;
+        description: string;
+    };
+    createSchema: {
+        required: readonly ["mixerId", "denomination", "anonymityTarget"];
+        properties: {
+            mixerId: {
+                type: "string";
+                immutable: true;
+                description: string;
+            };
+            denomination: {
+                type: "integer";
+                immutable: true;
+                description: string;
+            };
+            nullifierBaseH: {
+                type: "string";
+                immutable: true;
+                description: string;
+            };
+            anonymityTarget: {
+                type: "integer";
+                immutable: true;
+                description: string;
+            };
+            points: {
+                type: "array";
+                items: {
+                    type: "string";
+                };
+                default: never[];
+                description: string;
+            };
+            spentNullifiers: {
+                type: "object";
+                default: {};
+                description: string;
+            };
+            depositCount: {
+                type: "integer";
+                default: number;
+            };
+            withdrawCount: {
+                type: "integer";
+                default: number;
+            };
+            status: {
+                type: "string";
+                default: string;
+                description: string;
+            };
+        };
+    };
+    stateSchema: {
+        properties: {
+            mixerId: {
+                type: "string";
+                immutable: true;
+            };
+            denomination: {
+                type: "integer";
+                immutable: true;
+            };
+            nullifierBaseH: {
+                type: "string";
+                immutable: true;
+            };
+            anonymityTarget: {
+                type: "integer";
+                immutable: true;
+            };
+            points: {
+                type: "array";
+                items: {
+                    type: "string";
+                };
+                computed: true;
+            };
+            spentNullifiers: {
+                type: "object";
+                computed: true;
+            };
+            depositCount: {
+                type: "integer";
+                computed: true;
+            };
+            withdrawCount: {
+                type: "integer";
+                computed: true;
+            };
+            status: {
+                type: "string";
+                computed: true;
+            };
+        };
+    };
+    eventSchemas: {
+        deposit: {
+            description: string;
+        };
+        withdraw: {
+            description: string;
+        };
+    };
+    states: {
+        filling: {
+            id: string;
+            isFinal: false;
+            metadata: {
+                label: string;
+                description: string;
+                category: "active";
+            };
+        };
+        open: {
+            id: string;
+            isFinal: false;
+            metadata: {
+                label: string;
+                description: string;
+                category: "active";
+            };
+        };
+        drained: {
+            id: string;
+            isFinal: true;
+            metadata: {
+                label: string;
+                description: string;
+                category: "terminal";
+            };
+        };
+    };
+    initialState: "filling";
+    transitions: ({
+        from: "filling";
+        to: "open";
+        eventName: "deposit";
+        guard: {
+            and: ({
+                '===': ({
+                    '+': (number | {
+                        var: string;
+                    })[];
+                    var?: undefined;
+                } | {
+                    var: string;
+                    '+'?: undefined;
+                })[];
+                '!!'?: undefined;
+                none?: undefined;
+            } | {
+                '!!': {
+                    var: string;
+                }[];
+                '==='?: undefined;
+                none?: undefined;
+            } | {
+                none: ({
+                    var: string;
+                    '==='?: undefined;
+                } | {
+                    '===': {
+                        var: string;
+                    }[];
+                    var?: undefined;
+                })[];
+                '==='?: undefined;
+                '!!'?: undefined;
+            })[];
+        };
+        effect: {
+            merge: ({
+                var: string;
+                points?: undefined;
+                depositCount?: undefined;
+                status?: undefined;
+            } | {
+                points: {
+                    merge: ({
+                        var: string;
+                    } | {
+                        var: string;
+                    }[])[];
+                };
+                depositCount: {
+                    '+': (number | {
+                        var: string;
+                    })[];
+                };
+                status: string;
+                var?: undefined;
+            })[];
+        };
+        dependencies: never[];
+    } | {
+        from: "filling";
+        to: "filling";
+        eventName: "deposit";
+        guard: {
+            and: ({
+                '<': ({
+                    '+': (number | {
+                        var: string;
+                    })[];
+                    var?: undefined;
+                } | {
+                    var: string;
+                    '+'?: undefined;
+                })[];
+                '!!'?: undefined;
+                none?: undefined;
+            } | {
+                '!!': {
+                    var: string;
+                }[];
+                '<'?: undefined;
+                none?: undefined;
+            } | {
+                none: ({
+                    var: string;
+                    '==='?: undefined;
+                } | {
+                    '===': {
+                        var: string;
+                    }[];
+                    var?: undefined;
+                })[];
+                '<'?: undefined;
+                '!!'?: undefined;
+            })[];
+        };
+        effect: {
+            merge: ({
+                var: string;
+                points?: undefined;
+                depositCount?: undefined;
+            } | {
+                points: {
+                    merge: ({
+                        var: string;
+                    } | {
+                        var: string;
+                    }[])[];
+                };
+                depositCount: {
+                    '+': (number | {
+                        var: string;
+                    })[];
+                };
+                var?: undefined;
+            })[];
+        };
+        dependencies: never[];
+    } | {
+        from: "open";
+        to: "drained";
+        eventName: "withdraw";
+        guard: {
+            and: JsonLogicRule[];
+        };
+        effect: JsonLogicRule;
+        dependencies: never[];
+    } | {
+        from: "open";
+        to: "open";
+        eventName: "withdraw";
+        guard: {
+            and: JsonLogicRule[];
+        };
+        effect: JsonLogicRule;
+        dependencies: never[];
+    })[];
+};

package/dist/types/apps/privacy/state-machines/note-pool.d.ts

@@ -0,0 +1,196 @@
+/**
+ * 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 { type FiberAppDefinition, type JsonLogicRule, type SchemaField } from '../../../schema/fiber-app.js';
+/**
+ * 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 declare const PV_LAYOUT: {
+    /** anchor — word 1 (word 0 is the dynamic-tuple `0x20` head word; see the table). */
+    readonly anchor: 66;
+    /** fee — word 4 (uint64 right-aligned). MVP pins this whole word to {@link NotePoolOptions.feeWord}. */
+    readonly fee: 258;
+    /** feeAsset — word 5. */
+    readonly feeAsset: 322;
+    /** nullifiers[0] — after the nullifiers length word @386. */
+    readonly nullifier: 450;
+    /** outputCms[0] — after the outputCms length word @514. */
+    readonly outputCm: 578;
+};
+/**
+ * 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 declare const pvField: (offset: number) => JsonLogicRule;
+/**
+ * `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 declare const pmtMembership: (rootVar: JsonLogicRule, leafVar: JsonLogicRule, indexVar: JsonLogicRule, siblingsVar: JsonLogicRule) => JsonLogicRule;
+export interface NotePoolOptions {
+    /** zk-shielded program vkey (32B, `0x`-hex). Pinned ONCE at creation; the guard reads it from state. */
+    vkey: string;
+    /** Merkle depth of the commitment tree, pinned at creation. */
+    depth: number;
+    /** Fixed note denomination (asset units). Each live note ⇔ one `denom`-valued asset record. */
+    denom: number;
+    /** Asset policy ref the pool mints/burns note-records under (the deposit authorization surface). */
+    poolPolicyRef: string;
+    /** `0x` Fr label fees are charged in (== asset-as-Fr). Must equal the proof's `feeAsset` word. */
+    feeAsset: string;
+    /**
+     * The EXACT `0x` 32-byte word `fee` must equal. MVP: the all-zero word (forces fee=0, rejects any
+     * value-siphoning fee). LATER, to allow a fixed nonzero fee, compare only the right 16 hex.
+     */
+    feeWord?: string;
+    /** DAG address authorized to advance the root (MVP single trusted relayer; anti-grief). */
+    relayer: string;
+    /** How many recent anchors stay spendable (rolling window). Default 64. */
+    rootWindow?: number;
+}
+/** The all-zero 32-byte word — the MVP `feeWord` (pins fee=0). */
+export declare const ZERO_WORD: string;
+/** Public state every shielded note-pool carries (the note value model itself is private/off-chain). */
+export declare const NOTE_POOL_STATE: Record<string, SchemaField>;
+/** `transfer` / `unshield` carry a Groth16 bundle; `unshield` also carries the record to release. */
+export interface ShieldedSpendPayload {
+    /** Groth16 proof bytes (0x hex). */
+    proof: string;
+    /** abi-encoded `ShieldedTransferPublicValues` (0x hex); see {@link PV_LAYOUT}. */
+    publicValues: string;
+}
+/** `transfer` advances the tree; `newRoot` is wallet/relayer-computed (NOT in the proven PV). */
+export interface TransferPayload extends ShieldedSpendPayload {
+    /** wallet/relayer-computed root after appending `outputCms[0]`. Authorized by the relayer signer gate. */
+    newRoot: string;
+}
+/** `unshield` releases one whole `denom`-valued record the pool holds to a clear recipient. */
+export interface UnshieldPayload extends ShieldedSpendPayload {
+    /** assetId UUID of the note-record to release; MUST be `in state.noteRecords`. */
+    recordId: string;
+    /** clear DAG address (→ `AssetHolder.Wallet`) that receives the released note-record. */
+    recipient: string;
+}
+/** `noteMinted` records a deposit's commitment + the freshly-minted record's UUID. */
+export interface NoteMintedPayload {
+    /** client-computed `cm = Poseidon([denom, owner, feeAsset, rho])` (0x). */
+    commitment: string;
+    /** assetId UUID of the `denom`-valued record the deposit minted into `Fiber(poolId)`. */
+    recordId: string;
+}
+/**
+ * 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 declare function notePoolDef(opts: NotePoolOptions): FiberAppDefinition;

package/dist/types/apps/staked-pool/assets.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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, type CreateAssetPolicyParams, type MintAssetMessage, type ApplyMorphismMessage, type PolicyRef, type JsonLogicRule } from '../lending/assets.js';
+export { createAssetPolicyPayload, createMintAssetPayload, createApplyMorphismPayload, fiberHolder, walletHolder, TokenBehaviors, };
+export type { CreateAssetPolicyParams, MintAssetMessage, ApplyMorphismMessage, PolicyRef, JsonLogicRule };
+/**
+ * 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 declare function stakePolicy(name?: string, version?: string): CreateAssetPolicyParams;
+/**
+ * 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 declare function rewardPotPolicy(mintGuard?: JsonLogicRule | null, name?: string, version?: string): CreateAssetPolicyParams;
+/**
+ * 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 declare function stakeJoinOp(args: {
+    stakeAssetId: string;
+    poolFiberId: string;
+    targetSequenceNumber: number;
+}): ApplyMorphismMessage;
+/**
+ * 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 declare function mintRewardInstancesOp(args: {
+    rewardAssetId: string;
+    rewardPolicyRef: PolicyRef;
+    poolFiberId: string;
+    amount: number | string;
+    witness?: {
+        publicValues: string;
+        proof: string;
+    };
+}): MintAssetMessage;

package/dist/types/apps/staked-pool/base.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Staked-pool BASE factory — a reusable staked-epoch-pool lifecycle skeleton.
+ *
+ * Lifecycle: FORMING → COLLECTING → SETTLED → COLLECTING (reset) … → CLOSED.
+ *   FORMING    (initial) — accepting stake/join; registry bound; not yet running epochs.
+ *   COLLECTING           — epoch open; participants submit datapoints/votes.
+ *   SETTLED              — result published; entitlement ledger credited; result readable cross-fiber.
+ *   CLOSED     (final)   — wound down; stakes + unclaimed rewards still withdrawable/claimable.
+ *
+ * The base composes EXISTING SDK primitives only:
+ *   - `signerIsParty` (authority gate), `actorIsSigner`/`actorHasEntry` (effect-key↔signer coupling),
+ *     `signerHasReputationVia` (the #24 dynamic-dep reputation-gated join), `actorNotInArray` (array dedup),
+ *     `depInState` (cross-fiber consumer read — used by the consumer, not the pool itself) — `src/schema/guards.ts`.
+ *   - `addDependency` (#24 bind), `transferAsset` (whole-instance custody move) — `src/schema/effects.ts`.
+ *
+ * Value model (design §2.1, §4 — resolved):
+ *   - Submissions are an APPEND-ONLY ARRAY of `{ addr, value }` records (no map-keyed-by-address, because
+ *     there is no `(array,int)` element-index op). Append is `merge[state.submissions, [record]]` — verified.
+ *   - finalize emits ZERO asset transfers: it publishes `result` and records the in-consensus address set
+ *     into `inConsensus` (the entitlement ledger). No reward map-fold (a map-valued `reduce` accumulator is
+ *     rejected by the VM — `isPrimitive` guard in `opReduce`); entitlement is membership in `inConsensus`.
+ *   - reward = PER-CLAIM on a shared fungible: `claim_reward` moves ONE whole reward instance the pool holds
+ *     to a verified, in-consensus, not-yet-claimed signer, and marks `claimed[addr] = true`. ≤1 transfer.
+ *   - withdraw_stake / hard-slash each emit exactly ONE whole `_transferAsset` ⇒ never the 32-cap.
+ *
+ * Multi-`from` arms are SPLIT into one transition per source state (chain `from` is a single string):
+ *   stake_and_join ×2, claim_reward ×2, withdraw_stake ×2, close ×3.
+ */
+import type { FiberAppDefinition, Transition } from '../../schema/fiber-app.js';
+/**
+ * submit COLLECTING→COLLECTING — append one `{addr,value}` datapoint. OVERRIDABLE per specialization.
+ * Guard = joined participant (signer-pinned) AND within window AND not-yet-submitted-this-epoch (array dedup).
+ */
+export declare function defaultSubmitArm(): Transition;
+/**
+ * Genesis state — EVERY map init'd to `{}` and EVERY array to `[]` so reads stay total (M1: `has`/`get`
+ * on null hard-error). `epoch`/`epochStartedAt` are 0 until `open_first_epoch`.
+ */
+export declare const baseInitialStateData: {
+    readonly status: "FORMING";
+    readonly epoch: 0;
+    readonly epochStartedAt: 0;
+    readonly participants: {};
+    readonly stakes: {};
+    readonly stakeAssetIds: {};
+    readonly submissions: readonly [];
+    readonly inConsensus: readonly [];
+    readonly claimed: {};
+    readonly result: null;
+};
+export interface StakedPoolOverrides {
+    /** Metadata identity for the specialization. */
+    metadata: {
+        name: string;
+        type: string;
+        description: string;
+        version?: string;
+    };
+    /** Override the COLLECTING→COLLECTING `submit` arm (e.g. oracle datapoint append). Defaults to {@link defaultSubmitArm}. */
+    submit?: Transition;
+    /** The finalize arm (COLLECTING→SETTLED) — REQUIRED; supplied by the specialization (e.g. trimmed-mean). */
+    finalize: Transition;
+    /** Extra arms (e.g. governance propose/vote/resolve/challenge/slash) appended after the base arms. */
+    extraTransitions?: readonly Transition[];
+    /** Extra states (e.g. governance VOTING). */
+    extraStates?: Record<string, {
+        id: string;
+        isFinal: boolean;
+        metadata?: unknown;
+    }>;
+    /** Extra create-schema properties merged onto the base. */
+    extraCreateProperties?: Record<string, unknown>;
+    /** Extra state-schema properties merged onto the base. */
+    extraStateProperties?: Record<string, unknown>;
+}
+/**
+ * Build a staked-pool definition from the shared base + a specialization's `submit`/`finalize` (+ extras).
+ * Emits all SPLIT multi-`from` arms; no two emitted entries share both `from` and `eventName`.
+ */
+export declare function makeStakedPoolDef(overrides: StakedPoolOverrides): FiberAppDefinition;