@ottochain/sdk 2.3.0 → 2.5.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,141 @@
+/**
+ * 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" }) },
+ *   ],
+ * }
+ * ```
+ */
+import type { ProtoStateMachineDefinition } from './fiber-app.js';
+/** 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>;
+/**
+ * `_transferAsset`: move one or more WHOLE asset instances the emitting fiber holds, each to a single
+ * recipient. The directive rides INSIDE a `merge` effect map (the engine extracts `_`-prefixed keys
+ * before merging into state); a transition-level `emits` block is silently stripped by
+ * `toProtoDefinition`, which would strand the asset.
+ *
+ * Each directive is `{ assetId, recipient }` ONLY — there is NO `amount` field. The combiner reassigns
+ * `holder := recipient` on the WHOLE asset record (`AssetCombiner.applyFiberTransfer`); value is moved
+ * one whole instance at a time, never split. `recipient` must resolve to the canonical `AssetHolder`
+ * OBJECT form — `{"Fiber":{"fiberId":..}}` / `{"Wallet":{"address":..}}` — built with {@link toFiber} /
+ * {@link toWallet}; the chain raises a graceful `CombineRejected` on a bare string or malformed object
+ * (`EffectExtractor.parseAssetTransfer`). `assetId` is a UUID; the holder id may be a literal or an
+ * expression (e.g. `{ var: "event.agent" }`).
+ *
+ * Combiner-side holder defense (R1) independently re-validates every directive: the asset must resolve,
+ * be held by `Fiber(self)`, be `behavior.transferable`, and (Fiber recipient) the recipient fiber must be
+ * live — else the whole transition is `CombineRejected`. There is a hard cap of 32 asset mutations per
+ * transition (all-or-nothing); keep emitting fibers at ≤1 transfer per transition for claim/withdraw/slash.
+ *
+ * @example
+ * effect: { merge: [ { var: "state" }, {
+ *   status: "SETTLED",
+ *   ...transferAsset([{ assetId: { var: "event.rewardAssetId" }, recipient: toWallet({ var: "event.agent" }) }]),
+ * } ] }
+ */
+export declare const transferAsset: (transfers: {
+    assetId: JsonLogicValue;
+    recipient: JsonLogicValue;
+}[]) => Record<string, unknown>;
+/**
+ * Build a `_transferAsset` `recipient` as the canonical `AssetHolder` OBJECT form. The chain requires the
+ * object form ONLY — `{"Fiber":{"fiberId":..}}` / `{"Wallet":{"address":..}}` — and raises a graceful
+ * `CombineRejected` on a bare string or a malformed object (`EffectExtractor.parseAssetTransfer`); the
+ * legacy bare-string UUID/DAG-address disambiguation has been removed. These mirror the typed
+ * {@link fiberHolder} / {@link walletHolder} `AssetHolder` builders (used for `MintAsset.holder` /
+ * `ApplyMorphism.recipient`) but accept a `JsonLogicValue`, so the id can be a runtime expression:
+ *
+ * ```ts
+ * transferAsset([{ assetId, recipient: toFiber({ var: "event.retailerId" }) }]);  // → {"Fiber":{"fiberId":..}}
+ * transferAsset([{ assetId, recipient: toWallet({ var: "event.agent" }) }]);       // → {"Wallet":{"address":..}}
+ * ```
+ */
+export declare const toFiber: (fiberId: JsonLogicValue) => JsonLogicValue;
+/** See {@link toFiber}: a `transferAsset` recipient held by a wallet — `{"Wallet":{"address":..}}`. */
+export declare const toWallet: (address: JsonLogicValue) => JsonLogicValue;
+/**
+ * `_triggers` (F4): fire one or more CROSS-FIBER events. Each entry is projected to
+ * `{ targetMachineId, eventName, payload }` — the exact shape the chain's `EffectExtractor` reads
+ * (`ReservedKeys.scala`, `EffectExtractor.scala`). `target` is the recipient fiber id (a literal UUID
+ * or an expression, e.g. `{ var: "event.retailerId" }`); `event` is the event NAME to enqueue on it;
+ * `payload` is the event body — omit it and the builder emits `{}` (never `null`).
+ *
+ * Authoring this as a builder makes a typo'd `_trigger` / `triggres` a TypeScript error rather than a
+ * silently-merged state field (the F4 foot-gun). Place the fragment INSIDE the effect's state-update
+ * map so it rides in the evaluated result the extractor reads.
+ *
+ * @example
+ * effect: { merge: [ { var: "state" }, {
+ *   status: "debt_current",
+ *   ...triggers([{ target: { var: "event.retailerId" }, event: "process_sale",
+ *     payload: { buyerId: { var: "machineId" }, quantity: { var: "event.quantity" } } }]),
+ * } ] }
+ */
+export declare const triggers: (ts: {
+    target: JsonLogicValue;
+    event: string;
+    payload?: Record<string, unknown>;
+}[]) => Record<string, unknown>;
+/**
+ * `_spawn`: create one or more CHILD fibers, each from a literal machine `definition`. Each entry is
+ * `{ childId, definition, initialData, owners }` (`ReservedKeys.scala`, `EffectExtractor.scala`).
+ *
+ * The chain extracts `_spawn` from the effect EXPRESSION, not the evaluated result, so `definition`
+ * MUST be a literal {@link ProtoStateMachineDefinition} (e.g. a nested `machine().wireDefinition()` /
+ * `toProtoDefinition(child)` output) — NOT an expression the engine would evaluate at runtime.
+ *
+ * F8 gotcha — `owners` is load-bearing. A spawned child's transitions are gated by
+ * `owners ∪ authorizedSigners` (`riverdale-economy/README.md`), so EVERY party that will later drive
+ * the child (e.g. every bidder on a spawned auction) MUST be listed in `owners`, or their events are
+ * rejected. `owners` may be a literal id array or an expression (e.g. `{ var: "event.auctionOwners" }`);
+ * `childId` / `initialData` likewise accept literals or expressions.
+ */
+export declare const spawn: (ds: {
+    childId: JsonLogicValue;
+    definition: ProtoStateMachineDefinition;
+    initialData: Record<string, unknown>;
+    owners: JsonLogicValue;
+}[]) => Record<string, unknown>;
+/**
+ * `_emit`: emit one or more domain events to the fiber's outbox. Each entry is
+ * `{ name, data, destination? }` (`ReservedKeys.scala`, `EffectExtractor.scala`). `name` is the event
+ * name, `data` the body (a literal or an expression), and `destination` an OPTIONAL routing target —
+ * omit it when absent (callers never pass `null`, so it is simply absent on the wire).
+ */
+export declare const emit: (es: {
+    name: string;
+    data: JsonLogicValue;
+    destination?: string;
+}[]) => Record<string, unknown>;
+/**
+ * The complete set of `_`-prefixed RESERVED effect keys the chain's `EffectExtractor` consumes and
+ * `StateMerger` strips from state (`ReservedKeys.scala:12-49`). Exported so a validator (Proposal 01)
+ * can reject an unknown `_`-prefixed key (a typo'd directive) instead of letting it silently leak into
+ * persisted state.
+ */
+export declare const RESERVED_EFFECT_KEYS: readonly ["_triggers", "_spawn", "_emit", "_transferAsset", "_scriptCall", "_addDependency", "_setDependencyActive"];
+export {};