@ottochain/sdk 2.4.0 → 2.5.0

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;

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

@@ -0,0 +1,29 @@
+/**
+ * Cross-fiber consumer-read helpers for a SETTLED staked/oracle pool ("pull the answer").
+ *
+ * Two-phase (#24): a consumer first BINDS the pool dependency and PINS the epoch it intends to consume
+ * (transition N), then GATES on lifecycle + epoch and READS `result` (transition N+1). The epoch pin
+ * (M4) makes the read epoch-EXACT: between bind and read the pool can cycle SETTLED→COLLECTING→SETTLED,
+ * so a bare `depInState(SETTLED)` could read a DIFFERENT epoch's answer.
+ *
+ * Verified against the VM: `machines.<poolId>.state.{epoch,result}` reads resolve, and
+ * `depInState`/the epoch-`===` gate evaluate true only for the pinned, settled epoch.
+ */
+import type { JsonLogicRule } from '../../schema/fiber-app.js';
+/**
+ * PHASE 1 effect fragment — bind the pool dependency AND pin its current epoch into `epochField`
+ * (default `"expectedPoolEpoch"`). Spread into the consumer's `merge` effect on the bind transition.
+ * NOTE: `machines.<poolId>` is only readable AFTER a prior `_addDependency`, so the epoch pin records the
+ * value the consumer observes at bind time; on the first bind the pool dep may be unbound and the pin
+ * resolves null — bind in one transition, pin in the next if the registry/pool was not yet a dependency.
+ */
+export declare function bindAndPinPoolEpoch(poolIdVar?: string, epochField?: string): Record<string, unknown>;
+/**
+ * PHASE 2 guard — the pool is SETTLED for the EXACT epoch the consumer pinned. Compose into the read
+ * transition's guard alongside the consumer's own auth.
+ */
+export declare function poolSettledForPinnedEpoch(poolIdVar?: string, epochField?: string): JsonLogicRule;
+/** PHASE 2 value read — the published `result` object (use `.value` for the scalar answer). */
+export declare function readPoolResult(poolIdVar?: string): JsonLogicRule;
+/** PHASE 2 value read — the scalar `result.value`. */
+export declare function readPoolResultValue(poolIdVar?: string): JsonLogicRule;

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

@@ -0,0 +1,51 @@
+/**
+ * Staked-pool Application — a reusable staked-epoch-pool std-lib BASE plus an oracle-pool specialization.
+ *
+ * The base is a long-lived account-layer fiber proving the chain can carry real economic coordination:
+ * registry-gated, stake-backed membership; an append-only submission array; a state-resident claim
+ * entitlement ledger (zero finalize-time transfers); and one-whole-asset claim/withdraw custody moves.
+ * The oracle specialization adds an outlier-bounded (trimmed-mean) consensus aggregation whose published
+ * answer a consumer reads cross-fiber via an epoch-pinned `depInState(SETTLED)` gate.
+ *
+ * Composes EXISTING SDK primitives only (+ two helpers added this workstream — `transferAsset`,
+ * `actorNotInArray`): `signerIsParty` / `actorIsSigner` / `signerHasReputationVia` / `depInState`
+ * (`src/schema/guards.ts`), `addDependency` / `transferAsset` (`src/schema/effects.ts`), and the lending
+ * family's asset payload builders (`src/apps/lending/assets.ts`).
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getStakedPoolDefinition,
+ *   makeOraclePoolDef,
+ *   stakePolicy,
+ *   rewardPotPolicy,
+ *   bindAndPinPoolEpoch,
+ *   poolSettledForPinnedEpoch,
+ *   readPoolResultValue,
+ * } from '@ottochain/sdk/apps/staked-pool';
+ *
+ * const oracle = getStakedPoolDefinition('oraclePool');
+ * const plainMean = makeOraclePoolDef({ aggregation: 'mean' });
+ * const stake = stakePolicy();
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { stakedPoolBaseDef, stakedPoolOracleDef } from './state-machines/index.js';
+import type { FiberAppDefinition } from '../../schema/fiber-app.js';
+export { stakedPoolBaseDef, stakedPoolOracleDef };
+/** All staked-pool state machine definitions. */
+export declare const STAKED_POOL_DEFINITIONS: {
+    readonly base: FiberAppDefinition<string, string>;
+    readonly oraclePool: FiberAppDefinition<string, string>;
+};
+export type StakedPoolType = keyof typeof STAKED_POOL_DEFINITIONS;
+/**
+ * Get a staked-pool state machine definition by type.
+ * @param type - 'base' | 'oraclePool' (default: 'oraclePool')
+ */
+export declare function getStakedPoolDefinition(type?: StakedPoolType): FiberAppDefinition;
+export { makeStakedPoolDef, defaultSubmitArm, baseInitialStateData, type StakedPoolOverrides } from './base.js';
+export { makeOraclePoolDef, type OracleAggregation, type OraclePoolOptions } from './state-machines/index.js';
+export { stakePolicy, rewardPotPolicy, stakeJoinOp, mintRewardInstancesOp, createAssetPolicyPayload, createMintAssetPayload, createApplyMorphismPayload, fiberHolder, walletHolder, TokenBehaviors, type CreateAssetPolicyParams, type MintAssetMessage, type ApplyMorphismMessage, type PolicyRef, } from './assets.js';
+export { bindAndPinPoolEpoch, poolSettledForPinnedEpoch, readPoolResult, readPoolResultValue } from './consumer.js';

package/dist/types/apps/staked-pool/state-machines/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Staked-pool state machine definitions.
+ * Re-exports from TypeScript definition files.
+ */
+export { stakedPoolBaseDef } from './staked-pool-base.js';
+export { stakedPoolOracleDef, makeOraclePoolDef, type OracleAggregation, type OraclePoolOptions, } from './staked-pool-oracle.js';

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

@@ -0,0 +1,8 @@
+/**
+ * The generic staked-pool BASE definition (`StakedPool`) — the reusable epoch-pool skeleton with a
+ * minimal pass-through `finalize` (authority settles; publishes a trivial result and an EMPTY in-consensus
+ * set, zero transfers). It is the lowest-common-denominator def; downstream apps should prefer a
+ * specialization (e.g. the oracle pool) that supplies real aggregation. Exposed for definition-validity
+ * round-tripping and as the explicit "base, unspecialized" instance.
+ */
+export declare const stakedPoolBaseDef: import("../../../schema/fiber-app.js").FiberAppDefinition<string, string>;

package/dist/types/apps/staked-pool/state-machines/staked-pool-oracle.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Oracle-pool specialization of the staked-pool base (`StakedPoolOracle`).
+ *
+ * `submit` appends a numeric datapoint `{ addr, value }` (the base default arm).
+ * `finalize` (COLLECTING→SETTLED) aggregates the array with an outlier-bounded mean and publishes the
+ * answer + the in-consensus address set — emitting ZERO asset transfers (the entitlement ledger is
+ * `inConsensus`; rewards are pulled per-claim via the base `claim_reward` arm).
+ *
+ * Aggregation (default `trimmedMean`):
+ *   1. vals    = map(submissions, .value)
+ *   2. trimmed = filter(submissions, value != min(vals) && value != max(vals))   — drop single min + single max
+ *   3. center  = sum(trimmed.value) / count(trimmed)                              — EXACT rational (no truncation)
+ *   4. kept    = filter(submissions, abs(value - center) <= outlierBound)         — the in-consensus set
+ *   5. answer  = sum(kept.value) / count(kept)
+ *
+ * CRITICAL JLVM SCOPING (verified against @constellation-network/metagraph-sdk-jlvm@1.8.0-rc.5):
+ *   - Inside a `map`/`filter` callback the data scope is the BARE element, BUT the outer `state.*` is
+ *     still readable (verified: `{cat:[addr,"|",{var:"state.epoch"}]}` reads epoch correctly).
+ *   - A `let`-bound name does NOT cross into a `map`/`filter` callback. So `center` is INLINED into the
+ *     `kept` predicate (it reads `state.submissions`, which IS visible) rather than `let`-hoisted — a
+ *     `let`-bound `center` resolves to null inside `filter`, evicting every submission (div-by-zero).
+ *   - A `reduce` with a MAP initial accumulator is rejected (`opReduce` requires `isPrimitive(init)`),
+ *     so the reward ledger is NOT a folded `{addr:int}` map — it is the `inConsensus` array (membership =
+ *     entitlement), consumed by `claim_reward` + a `claimed` dedup map.
+ */
+export type OracleAggregation = 'mean' | 'trimmedMean';
+export interface OraclePoolOptions {
+    /** Aggregation strategy. Default `trimmedMean` (drop single min + single max — the robustness ceiling). */
+    aggregation?: OracleAggregation;
+}
+/** Build the oracle-pool definition. `outlierPenalty` is soft-only (no-credit for outliers); hard slash is v2. */
+export declare function makeOraclePoolDef(options?: OraclePoolOptions): import("../../../schema/fiber-app.js").FiberAppDefinition<string, string>;
+/** Default oracle-pool definition (trimmed-mean). */
+export declare const stakedPoolOracleDef: import("../../../schema/fiber-app.js").FiberAppDefinition<string, string>;

package/dist/types/generated/openapi.d.ts

@@ -428,11 +428,23 @@ export interface components {
             ordinal: number;
             state: components["schemas"]["CalculatedState"];
         };
+        /** DynamicDependency */
+        DynamicDependency: {
+            /** Format: uuid */
+            fiberId: string;
+            active: boolean;
+            /** Format: int64 */
+            addedAt: number;
+        };
         /** EmittedEvent */
         EmittedEvent: {
             name: string;
             data: unknown;
             destination?: string;
+            /** Format: uuid */
+            emitterFiberId: string;
+            /** Format: int32 */
+            emissionIndex: number;
         };
         /** EventReceipt */
         EventReceipt: {
@@ -562,6 +574,7 @@ export interface components {
             childFiberIds?: string[];
             schemaBinding?: components["schemas"]["SchemaBinding"];
             authorizedSigners?: string[];
+            dynamicDependencies?: components["schemas"]["DynamicDependency"][];
         };
         /** StateProofResponse */
         StateProofResponse: {

package/dist/types/generated/ottochain/v1/fiber.d.ts

@@ -53,6 +53,13 @@ export interface EmittedEvent {
     name: string;
     data?: any | undefined;
     destination?: string | undefined;
+    /**
+     * Engine-stamped at extraction (EffectExtractor), never user-supplied — make every
+     * emitted event attributable to the fiber that produced it (engine-default-fixes Fix 1).
+     */
+    emitterFiberId: string;
+    /** Sparse position within the raw `_emit` array at authoring time. */
+    emissionIndex: number;
 }
 /** Event receipt - log entry for state machine transition */
 export interface EventReceipt {

package/dist/types/index.d.ts

@@ -31,8 +31,8 @@ export { OttoChainError, NetworkError, ValidationError, SigningError, Transactio
 export { DagAddressSchema, PrivateKeySchema, PublicKeySchema, KeyPairSchema, SignatureProofSchema, SignedSchema, TransactionReferenceSchema, CurrencyTransactionValueSchema, CurrencyTransactionSchema, TransferParamsSchema, AgentIdentityRegistrationSchema, PlatformLinkSchema, ContractTermsSchema, ProposeContractRequestSchema, AcceptContractRequestSchema, CompleteContractRequestSchema, validate, validatePrivateKey, validatePublicKey, validateAddress, validateKeyPair, safeParse, assert, type ValidatedKeyPair, type ValidatedSignatureProof, type ValidatedCurrencyTransaction, type ValidatedTransferParams, type ValidatedAgentIdentityRegistration, type ValidatedPlatformLink, type ValidatedProposeContractRequest, type ValidatedAcceptContractRequest, type ValidatedCompleteContractRequest, } from './validation.js';
 export { MetagraphClient as OttoMetagraphClient } from './ottochain/metagraph-client.js';
 export type { MetagraphClientConfig, Checkpoint, SubscribeOptions, FiberStateCallback, Unsubscribe, } from './ottochain/metagraph-client.js';
-export { toProtoDefinition, defineFiberApp, type ProtoStateMachineDefinition, type FiberAppDefinition, type FiberAppMetadata, type StateDefinition, type StdStateMetadata, type StateCategory, type Transition, } from './schema/fiber-app.js';
-export { type GuardRule, signerIsParty, signerIsAnyParty, signerInSet, signerIsNotParty, signerHasEntry, assetSignerIs, actorIsSigner, actorInSet, actorHasEntry, signerHasReputation, signerHasRole, signerHasReputationVia, signerHasRoleVia, depInState, } from './schema/guards.js';
-export { addDependency, setDependencyActive } from './schema/effects.js';
+export { toProtoDefinition, defineFiberApp, constrained, unconstrained, immutable, IMMUTABLE_POLICY, projectFiberPolicy, type ProtoStateMachineDefinition, type FiberAppDefinition, type FiberAppMetadata, type FiberPolicy, type FiberPolicyDials, type ImmutablePolicy, type EffectKind, type SpawnOwnerPolicy, type DependencyMode, type TransferPolicy, type DependencyPolicy, type MigrationAuthority, type UpgradePolicy, type VersionRange, type StateDefinition, type StdStateMetadata, type StateCategory, type Transition, } from './schema/fiber-app.js';
+export { type GuardRule, signerIsParty, signerIsAnyParty, signerInSet, signerIsNotParty, signerHasEntry, assetSignerIs, actorIsSigner, actorInSet, actorHasEntry, signerHasReputation, signerHasRole, signerHasReputationVia, signerHasRoleVia, depInState, actorNotInArray, } from './schema/guards.js';
+export { addDependency, setDependencyActive, transferAsset, triggers, spawn, emit, toFiber, toWallet, RESERVED_EFFECT_KEYS, } from './schema/effects.js';
 export { shieldApp, SHIELDED_POOL_STATE, type ShieldOptions } from './privacy/shield-app.js';
 export type { paths as ApiPaths, operations as ApiOperations, components as ApiComponents, VersionInfo, TransitionFeeEstimate, ScriptFeeEstimate, SubscribeRequest, SubscribeResponse, Subscriber, SubscriberList, } from './openapi.js';

package/dist/types/openapi.d.ts

@@ -1,9 +1,11 @@
 /**
  * Typed OttoChain HTTP API surface.
  *
- * These types are generated from the metagraph's OpenAPI contract
- * (`openapi/ottochain-openapi.json`, emitted by ottochain's tapir `ApiEndpoints`) — so the SDK and the
+ * These types are generated from the metagraph's ML0 OpenAPI contract
+ * (`openapi/ottochain-openapi-ml0.json`, emitted by ottochain's tapir `ApiEndpoints`) — so the SDK and the
  * chain share ONE source of truth for request/response shapes, instead of reverse-engineering them inline.
+ * The vendored contract is pulled from ottochain's published RELEASE artifacts (see `openapi/README.md` +
+ * `openapi/source.json`); refresh it with `pnpm fetch:openapi`.
  *
  * Regenerate after the contract changes with `pnpm gen:openapi`. The raw generated module is
  * `src/generated/openapi.ts`; this file gives consumers stable, named aliases for the precise response

package/dist/types/ottochain/genesis-manifest.d.ts

@@ -90,6 +90,12 @@ export interface StateMachineDefinition {
         dependencies: unknown[];
     }>;
     metadata: unknown | null;
+    /**
+     * Fiber constitution. PRESENT for `Constrained` (a bare object of the SET dials) and for
+     * `Immutable` (the bare JSON string `"Immutable"`); ABSENT for `Unconstrained` (the chain
+     * emits no `policy` key for it).
+     */
+    policy?: Record<string, unknown> | string;
 }
 /**
  * One package to pre-register at genesis. This is the genesis INPUT, not the

package/dist/types/ottochain/transaction.d.ts

@@ -5,7 +5,7 @@
  * self-signed mode, where clients sign their own transactions.
  */
 import type { Signed } from '@constellation-network/metagraph-sdk';
-import type { CreateAssetPolicy, MintAsset, ApplyMorphism, AuthorizeCompose } from './types.js';
+import type { CreateAssetPolicy, MintAsset, ApplyMorphism, AuthorizeCompose, PublishMachineVersion, UpgradeFiber } from './types.js';
 /**
  * Parameters for creating a new state machine fiber
  */
@@ -202,6 +202,14 @@ export declare function createApplyMorphismPayload(params: ApplyMorphism): {
 export declare function createAuthorizeComposePayload(params: AuthorizeCompose): {
     AuthorizeCompose: AuthorizeCompose;
 };
+/** Wrap a {@link PublishMachineVersion} (create-or-append a STATE-MACHINE registry version). */
+export declare function createPublishMachineVersionPayload(params: PublishMachineVersion): {
+    PublishMachineVersion: PublishMachineVersion;
+};
+/** Wrap an {@link UpgradeFiber} (re-pin a fiber to another registered version of the SAME package). */
+export declare function createUpgradeFiberPayload(params: UpgradeFiber): {
+    UpgradeFiber: UpgradeFiber;
+};
 /**
  * Sign a transaction payload for self-signed mode.
  *

package/dist/types/ottochain/types.d.ts

@@ -7,7 +7,7 @@
  * @see modules/models/src/main/scala/xyz/kd5ujc/schema/
  * @packageDocumentation
  */
-export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, Timestamp, } from '../types.js';
+export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, Timestamp } from '../types.js';
 /**
  * JSON logic value - arbitrary JSON data used for state data and payloads.
  */

package/dist/types/privacy/index.d.ts

@@ -2,5 +2,5 @@
  * Privacy: shield any fiber app into a zk-jlvm-shielded private-state pool.
  * See docs/design/zk-private-contract-state-rfc.md.
  */
-export { shieldApp, SHIELDED_POOL_STATE, type ShieldOptions } from "./shield-app.js";
-export { sealedBidAccountDef, shieldedSealedBidDef, vickreyAuctionDef } from "./sealed-bid.js";
+export { shieldApp, SHIELDED_POOL_STATE, type ShieldOptions } from './shield-app.js';
+export { sealedBidAccountDef, shieldedSealedBidDef, vickreyAuctionDef } from './sealed-bid.js';