@ottochain/sdk 2.3.0 → 2.4.0

package/dist/types/privacy/sealed-bid.d.ts

@@ -0,0 +1,348 @@
+/**
+ * Sealed-bid (Vickrey) auction — the worked example for the privacy stack.
+ *
+ * Two pieces (RFC §4):
+ *  1. `sealedBidAccountDef` — the PRIVATE per-bidder bid. `shieldApp` turns it into a shielded
+ *     pool (`shieldedSealedBidDef`): a bidder commits a bid note and proves it well-formed with a
+ *     zk-jlvm-shielded Groth16 proof, so the amount stays sealed *until the deadline*. This is the
+ *     mechanical per-instance / single-owner case.
+ *  2. `vickreyAuctionDef` — the PUBLIC settlement (reveal-then-tally). After the deadline bidders
+ *     open their notes; the combine computes winner = argmax and clearingPrice = second-highest
+ *     (the Vickrey price). This is the one shared-state step, kept simple for v1; a zk settlement
+ *     proof that seals losers' amounts forever is the deferred upgrade (RFC §10).
+ */
+import { type FiberAppDefinition } from "../schema/fiber-app.js";
+import { type ShieldOptions } from "./shield-app.js";
+/** The per-bidder PRIVATE state: a bid note `{ amount, bidder, nonce }`. */
+export declare const sealedBidAccountDef: {
+    readonly metadata: {
+        readonly name: "SealedBidAccount";
+        readonly app: "markets";
+        readonly type: "sealed-bid-account";
+        readonly version: "1.0.0";
+        readonly description: "A single bidder's sealed bid (private amount). Shielded via shieldApp.";
+    };
+    readonly stateSchema: {
+        readonly properties: {
+            readonly amount: {
+                readonly type: "number";
+                readonly description: "the (private) bid amount";
+            };
+            readonly bidder: {
+                readonly type: "address";
+            };
+            readonly nonce: {
+                readonly type: "number";
+                readonly description: "per-note randomness; keeps the commitment hiding";
+            };
+        };
+    };
+    readonly eventSchemas: {
+        readonly place_bid: {
+            readonly description: "Set the sealed bid amount";
+            readonly required: readonly ["amount"];
+            readonly properties: {
+                readonly amount: {
+                    readonly type: "number";
+                    readonly minimum: 1;
+                };
+            };
+        };
+    };
+    readonly states: {
+        readonly OPEN: {
+            readonly id: "OPEN";
+            readonly isFinal: false;
+            readonly metadata: {
+                readonly label: "Open";
+                readonly description: "No bid yet";
+                readonly category: "initial";
+            };
+        };
+        readonly BID: {
+            readonly id: "BID";
+            readonly isFinal: false;
+            readonly metadata: {
+                readonly label: "Bid";
+                readonly description: "Bid committed";
+                readonly category: "active";
+            };
+        };
+    };
+    readonly initialState: "OPEN";
+    readonly transitions: readonly [{
+        readonly from: "OPEN";
+        readonly to: "BID";
+        readonly eventName: "place_bid";
+        readonly guard: {
+            readonly ">": readonly [{
+                readonly var: "event.amount";
+            }, 0];
+        };
+        readonly effect: {
+            readonly merge: readonly [{
+                readonly var: "state";
+            }, {
+                readonly amount: {
+                    readonly var: "event.amount";
+                };
+            }];
+        };
+        readonly dependencies: readonly [];
+    }];
+};
+/**
+ * The shielded sealed-bid pool. `vkey`/`exprHash` come from the built zk-jlvm-shielded circuit
+ * (these are placeholders until the circuit's program vkey + the keccak of the `place_bid` effect
+ * are wired in by the genesis/build step).
+ */
+export declare function shieldedSealedBidDef(opts: ShieldOptions): FiberAppDefinition;
+/**
+ * Public reveal-then-tally settlement. `reveal` appends an opened bid (in a full build the opening
+ * is checked against the recorded commitment in the shielded pool); `settle` computes the winner
+ * and the Vickrey (second-price) clearing price over the revealed bids in one reduce.
+ */
+export declare const vickreyAuctionDef: {
+    readonly metadata: {
+        readonly name: "VickreyAuction";
+        readonly app: "markets";
+        readonly type: "vickrey-auction";
+        readonly version: "1.0.0";
+        readonly description: "Sealed-bid second-price auction: public reveal-then-tally over shielded bids.";
+        readonly crossReferences: {
+            readonly bidPool: "the ShieldedSealedBidAccount pool holding the sealed bids";
+        };
+    };
+    readonly createSchema: {
+        readonly required: readonly ["seller", "deadline"];
+        readonly properties: {
+            readonly seller: {
+                readonly type: "address";
+                readonly immutable: true;
+            };
+            readonly deadline: {
+                readonly type: "timestamp";
+                readonly immutable: true;
+            };
+        };
+    };
+    readonly stateSchema: {
+        readonly properties: {
+            readonly seller: {
+                readonly type: "address";
+                readonly immutable: true;
+            };
+            readonly deadline: {
+                readonly type: "timestamp";
+                readonly immutable: true;
+            };
+            readonly status: {
+                readonly type: "string";
+                readonly computed: true;
+            };
+            readonly revealed: {
+                readonly type: "array";
+                readonly computed: true;
+                readonly description: "opened bids [{bidder, amount}]";
+            };
+            readonly winner: {
+                readonly type: "address";
+                readonly computed: true;
+            };
+            readonly clearingPrice: {
+                readonly type: "number";
+                readonly computed: true;
+                readonly description: "second-highest bid (Vickrey)";
+            };
+        };
+    };
+    readonly eventSchemas: {
+        readonly reveal: {
+            readonly description: "Open a sealed bid after the deadline";
+            readonly required: readonly ["bidder", "amount"];
+            readonly properties: {
+                readonly bidder: {
+                    readonly type: "address";
+                };
+                readonly amount: {
+                    readonly type: "number";
+                    readonly minimum: 1;
+                };
+            };
+        };
+        readonly settle: {
+            readonly description: "Tally the revealed bids (winner + second price)";
+        };
+    };
+    readonly states: {
+        readonly OPEN: {
+            readonly id: "OPEN";
+            readonly isFinal: false;
+            readonly metadata: {
+                readonly label: "Open";
+                readonly description: "Bidding (sealed)";
+                readonly category: "initial";
+            };
+        };
+        readonly REVEAL: {
+            readonly id: "REVEAL";
+            readonly isFinal: false;
+            readonly metadata: {
+                readonly label: "Reveal";
+                readonly description: "Opening bids";
+                readonly category: "active";
+            };
+        };
+        readonly SETTLED: {
+            readonly id: "SETTLED";
+            readonly isFinal: true;
+            readonly metadata: {
+                readonly label: "Settled";
+                readonly description: "Winner + price set";
+                readonly category: "terminal";
+            };
+        };
+    };
+    readonly initialState: "OPEN";
+    readonly transitions: readonly [{
+        readonly from: "OPEN";
+        readonly to: "REVEAL";
+        readonly eventName: "reveal";
+        readonly guard: {
+            readonly ">=": readonly [{
+                readonly var: "$timestamp";
+            }, {
+                readonly var: "state.deadline";
+            }];
+        };
+        readonly effect: {
+            readonly merge: readonly [{
+                readonly var: "state";
+            }, {
+                readonly status: "REVEAL";
+                readonly revealed: {
+                    readonly cat: readonly [{
+                        readonly var: "state.revealed";
+                    }, readonly [{
+                        readonly bidder: {
+                            readonly var: "event.bidder";
+                        };
+                        readonly amount: {
+                            readonly var: "event.amount";
+                        };
+                    }]];
+                };
+            }];
+        };
+        readonly dependencies: readonly [];
+    }, {
+        readonly from: "REVEAL";
+        readonly to: "REVEAL";
+        readonly eventName: "reveal";
+        readonly guard: {
+            readonly ">=": readonly [{
+                readonly var: "$timestamp";
+            }, {
+                readonly var: "state.deadline";
+            }];
+        };
+        readonly effect: {
+            readonly merge: readonly [{
+                readonly var: "state";
+            }, {
+                readonly revealed: {
+                    readonly cat: readonly [{
+                        readonly var: "state.revealed";
+                    }, readonly [{
+                        readonly bidder: {
+                            readonly var: "event.bidder";
+                        };
+                        readonly amount: {
+                            readonly var: "event.amount";
+                        };
+                    }]];
+                };
+            }];
+        };
+        readonly dependencies: readonly [];
+    }, {
+        readonly from: "REVEAL";
+        readonly to: "SETTLED";
+        readonly eventName: "settle";
+        readonly guard: {
+            readonly ">": readonly [{
+                readonly reduce: readonly [{
+                    readonly var: "state.revealed";
+                }, {
+                    readonly "+": readonly [{
+                        readonly var: "accumulator";
+                    }, 1];
+                }, 0];
+            }, 0];
+        };
+        readonly effect: {
+            readonly merge: readonly [{
+                readonly var: "state";
+            }, {
+                readonly status: "SETTLED";
+                readonly settledAt: {
+                    readonly var: "$timestamp";
+                };
+                readonly winner: {
+                    readonly var: readonly ["tally.winner", null];
+                };
+                readonly clearingPrice: {
+                    readonly var: readonly ["tally.second", 0];
+                };
+                readonly tally: {
+                    readonly reduce: readonly [{
+                        readonly var: "state.revealed";
+                    }, {
+                        readonly if: readonly [{
+                            readonly ">": readonly [{
+                                readonly var: "current.amount";
+                            }, {
+                                readonly var: "accumulator.max";
+                            }];
+                        }, {
+                            readonly max: {
+                                readonly var: "current.amount";
+                            };
+                            readonly second: {
+                                readonly var: "accumulator.max";
+                            };
+                            readonly winner: {
+                                readonly var: "current.bidder";
+                            };
+                        }, {
+                            readonly if: readonly [{
+                                readonly ">": readonly [{
+                                    readonly var: "current.amount";
+                                }, {
+                                    readonly var: "accumulator.second";
+                                }];
+                            }, {
+                                readonly max: {
+                                    readonly var: "accumulator.max";
+                                };
+                                readonly second: {
+                                    readonly var: "current.amount";
+                                };
+                                readonly winner: {
+                                    readonly var: "accumulator.winner";
+                                };
+                            }, {
+                                readonly var: "accumulator";
+                            }];
+                        }];
+                    }, {
+                        readonly max: 0;
+                        readonly second: 0;
+                        readonly winner: null;
+                    }];
+                };
+            }];
+        };
+        readonly dependencies: readonly [];
+    }];
+};

package/dist/types/privacy/shield-app.d.ts

@@ -0,0 +1,48 @@
+/**
+ * shieldApp — turn a fiber app into a PRIVATE-state pool.
+ *
+ * Given a base {@link FiberAppDefinition} (the app whose state + transition you want to keep
+ * private), `shieldApp` returns a new `FiberAppDefinition` for a "shielded pool" Machine fiber.
+ * The pool's state is PUBLIC scaffolding only — the spent-nullifier set, the commitment log, and
+ * the set of valid anchors — while the app's real state lives off-chain in a note committed to
+ * the tree. Each app transition is carried out off-chain and attested by a single
+ * `zk-jlvm-shielded` Groth16 proof; the on-chain combine just verifies the proof, rejects an
+ * already-spent nullifier, and records the new commitment.
+ *
+ * Division of labour (see ottochain-sdk RFC docs/design/zk-private-contract-state-rfc.md):
+ *  - the CIRCUIT proves membership ∧ authorization ∧ `jlvm-core` effect ∧ new commitment;
+ *  - this GUARD (combine) verifies the proof, pins which app logic ran (`exprHash`), checks the
+ *    anchor is recent, and checks the nullifier is fresh — all combiner-only (CLAUDE.md);
+ *  - block-validity stays structural (proof / publicValues present + hex).
+ *
+ * It uses NO new metakit opcode: `groth16_verify` verifies the proof, and the four-`bytes32`
+ * public values (`anchor`, `nullifier`, `newCommitment`, `exprHash`) are extracted from the
+ * VERIFIED `publicValues` string with fixed-offset `substr` — slicing the verified bytes IS the
+ * binding (§8.1).
+ *
+ * NOTE on cost: the note model rehashes the whole state each transition, so proving cost is
+ * O(state size) (RFC §8). Keep shielded note state small (a few KB); for large keyed state use
+ * the auth-DB variant (RFC §3.1.1).
+ */
+import { type FiberAppDefinition, type SchemaField } from "../schema/fiber-app.js";
+export interface ShieldOptions {
+    /** SP1 program vkey for the zk-jlvm-shielded circuit (0x-prefixed bytes32 hex). Pinned at creation. */
+    vkey: string;
+    /**
+     * `keccak256(effectExpr)` the circuit commits — pins WHICH app logic the accepted proofs ran.
+     * Compute it from the base app's transition effect; one pinned effect per pool (the per-event /
+     * multi-effect generalization is RFC §10 open question 1).
+     */
+    exprHash: string;
+    /** How many recent anchors stay spendable (rolling window). Default 64. */
+    rootWindow?: number;
+}
+/** Standard public state every shielded pool carries (the rest of the app state is private/off-chain). */
+export declare const SHIELDED_POOL_STATE: Record<string, SchemaField>;
+/**
+ * Build the shielded-pool variant of `base`.
+ *
+ * @param base  the app being shielded (used for naming + to document the pinned logic).
+ * @param opts  the circuit vkey + the pinned `exprHash` + the anchor window.
+ */
+export declare function shieldApp(base: FiberAppDefinition, opts: ShieldOptions): FiberAppDefinition;

package/dist/types/schema/effects.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Builders for the fiber-engine reserved EFFECT directives — the `_`-prefixed keys the chain extracts
+ * from an evaluated effect result and applies as side effects (then strips from the merged state).
+ *
+ * Place the returned fragment INSIDE the state-update map of a `merge` effect, so the directive rides in
+ * the evaluated result map (EffectExtractor reads it; StateMerger drops `_`-prefixed keys from state):
+ *
+ * ```ts
+ * effect: {
+ *   merge: [
+ *     { var: "state" },
+ *     { boundAt: { var: "$ordinal" }, ...addDependency({ var: "event.registryId" }) },
+ *   ],
+ * }
+ * ```
+ */
+/** A JSON-Logic value: a literal (string/number/bool) or a `{var}`/operator expression. */
+type JsonLogicValue = unknown;
+/**
+ * `_addDependency` (#24): add — or re-activate — a runtime DYNAMIC dependency on `fiberId`, so that
+ * fiber's state appears in `machines.<fiberId>` for SUBSEQUENT transitions of this fiber. `fiberId` may
+ * be a literal UUID string or an expression (e.g. `{ var: "event.registryId" }`, `{ var: "state.registryId" }`).
+ * The ledger is append-only, idempotent (one entry per fiber), and engine-bounded (active + ledger caps).
+ * Because the `machines` context is built BEFORE the effect runs, the bound dependency is readable only
+ * from the NEXT transition onward (two-phase: bind, then read).
+ */
+export declare const addDependency: (fiberId: JsonLogicValue) => Record<string, unknown>;
+/**
+ * `_setDependencyActive` (#24): toggle a dynamic dependency's `active` flag. The entry is NEVER removed —
+ * deactivation simply drops it from the `machines` context (and it can be cheaply re-activated). `fiberId`
+ * may be a literal or an expression.
+ */
+export declare const setDependencyActive: (fiberId: JsonLogicValue, active: boolean) => Record<string, unknown>;
+export {};

package/dist/types/schema/fiber-app.d.ts

@@ -192,8 +192,7 @@ export interface ProtoStateMachineDefinition {
         eventName: string;
         guard?: unknown;
         effect?: unknown;
-        dependencies?: unknown[];
-        emits?: unknown[];
+        dependencies: string[];
     }>;
     metadata?: Record<string, unknown>;
 }

package/dist/types/schema/guard-lint.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Regression-prevention lint for OttoChain std-app fiber definitions.
+ *
+ * Purpose
+ * -------
+ * Catch — at *authoring* time — the classes of SDK↔chain drift that the chain
+ * accepts structurally but then silently mis-parses, drops, or evaluates to a
+ * dead (always-true / always-false / always-throw) guard. Without this lint
+ * those mistakes ship as live, exploitable holes or as silent data corruption
+ * because nothing in `defineFiberApp` / `toProtoDefinition` rejects them.
+ *
+ * The drift classes (cross-referenced to docs/reviews/fiber-app-alignment-audit-2026-06.md):
+ *
+ *   A1 — `$timestamp` (and any non-injected `$`-key). `ReservedKeys` injects ONLY
+ *        `$ordinal`, `$lastSnapshotHash`, `$epochProgress`. `{"var":"$timestamp"}`
+ *        resolves to null → `0` in numeric contexts → deadline guards die silently.
+ *
+ *   A2 — Nonexistent JLVM opcodes used as operator tags: `size`, `getKey`,
+ *        `setKey`, `deleteKey`. metakit decodes an unknown single-key object as a
+ *        LITERAL Map, not an operator, so the guard is always-true/false and the
+ *        effect writes a junk key. (Canonical good set: `KNOWN_OPERATORS`.)
+ *
+ *   A3 — SDK directives the chain's `toProtoDefinition` silently drops:
+ *        transition-level `emits` / `spawns`, and object-form `dependencies`
+ *        entries `{machine,instanceRef,requiredState}` (chain parses `Set[UUID]`).
+ *        Authors believe these gate/emit; on-chain they evaporate.
+ *
+ *   per-context — `{"var":"witness.*"}` in a fiber TRANSITION. `witness` is only
+ *        injected in ASSET-guard contexts; a transition gets `event` (the proof
+ *        rides under `event.witness.*`). Reading `witness.*` resolves to null →
+ *        fail-closed (zk gate un-passable) or silently bypassed.
+ *
+ *   leading-dot — `{"var":".foo"}` resolves to null on chain.
+ *
+ * This is a STANDALONE validator. It is deliberately NOT wired into
+ * `defineFiberApp` / `toProtoDefinition`: doing so would break the build until
+ * every app is remediated. Run it via `scripts/lint-apps.mjs`.
+ */
+import type { FiberAppDefinition } from './fiber-app.js';
+export type LintSeverity = 'error' | 'warn';
+export interface LintViolation {
+    /** App identifier (`metadata.app/metadata.type` or `metadata.name`), when known. */
+    app?: string;
+    /** `eventName` (or `from→to`) of the offending transition, when applicable. */
+    transition?: string;
+    severity: LintSeverity;
+    /** Stable machine-readable rule code (see {@link LINT_CODES}). */
+    code: string;
+    /** Human-readable explanation including the correct alternative. */
+    message: string;
+    /** JSON-ish path to the offending node, e.g. `transitions[3].guard.or[0].var`. */
+    path: string;
+}
+/** Stable rule codes — referenced by tests and by report tooling. */
+export declare const LINT_CODES: {
+    readonly UNKNOWN_RESERVED_VAR: "unknown-reserved-var";
+    readonly UNKNOWN_OPERATOR: "unknown-operator";
+    readonly WITNESS_IN_TRANSITION: "witness-in-transition";
+    readonly DROPPED_DIRECTIVE: "dropped-directive";
+    readonly LEADING_DOT_VAR: "leading-dot-var";
+};
+/**
+ * The ONLY `$`-prefixed keys the engine injects (`ReservedKeys`). Anything else
+ * (`$timestamp`, `$now`, ...) resolves to null on chain.
+ */
+export declare const INJECTED_RESERVED_VARS: ReadonlySet<string>;
+/**
+ * Tags that LOOK like opcodes and appear in real definitions but are NOT valid
+ * JLVM operators — metakit mis-decodes each as a literal Map. These are always
+ * flagged as errors regardless of position (they are not plausible data fields).
+ * Mapped to the correct replacement opcode for the message.
+ */
+export declare const KNOWN_BAD_OPERATORS: ReadonlyMap<string, string>;
+interface WalkContext {
+    app?: string;
+    transition?: string;
+    /**
+     * When true, this transition expression runs in a context where `witness` is
+     * NOT injected (a fiber transition guard/effect). Reading `witness.*` here is
+     * a bug (rule 3). Asset-guard contexts would set this false (not walked here).
+     */
+    flagWitness: boolean;
+}
+/**
+ * Recursively lint a single JSON-Logic expression (a guard or an effect, or any
+ * sub-node). Walks every nested operand. Pushes a {@link LintViolation} for each
+ * rule-1 / rule-2 / rule-3 / rule-5 hit found at or below `node`.
+ *
+ * `inDataLiteral` tracks whether `node` sits in a position the evaluator treats
+ * as DATA rather than as an expression to evaluate (e.g. the 2nd operand of
+ * `merge`/`cat`, or a value nested inside such an operand). In a data-literal
+ * position an unknown single-key object is a legitimate field map, so the
+ * *generic* unknown-operator warning is suppressed there — but `$`-var keys,
+ * leading-dot vars, witness reads, and the known-BAD opcode tags are still
+ * flagged (those are bugs wherever they appear).
+ */
+export declare function lintGuardExpression(node: unknown, ctx: WalkContext, path: string, inDataLiteral?: boolean): LintViolation[];
+/**
+ * Lint a complete fiber app definition. Walks every transition guard + effect
+ * (rules 1/2/3/5) and every transition's structural directives (rule 4), plus a
+ * light pass over `states` to catch stray reserved-key / operator drift embedded
+ * in state metadata. Returns ALL violations (errors and warnings); callers
+ * decide the exit policy (e.g. fail on any `error`).
+ */
+export declare function lintFiberApp(def: FiberAppDefinition): LintViolation[];
+/**
+ * Convenience: lint many apps at once, returning a flat list. Each app's
+ * violations already carry its `app` label.
+ */
+export declare function lintFiberApps(defs: readonly FiberAppDefinition[]): LintViolation[];
+export {};