@ottochain/sdk 2.3.0 → 2.5.0

package/dist/esm/privacy/shield-app.js

@@ -0,0 +1,127 @@
+/**
+ * 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 { defineFiberApp } from '../schema/fiber-app.js';
+/**
+ * Field extractors over the abi-encoded `JlvmTransitionPublicValues` — four static `bytes32`
+ * `[anchor | nullifier | newCommitment | exprHash]`, a fixed 128-byte (256 hex char) layout with
+ * NO dynamic arrays. `publicValues` is the 0x-prefixed hex from the prover, so each field is 64
+ * hex chars starting at: anchor=2, nullifier=66, newCommitment=130, exprHash=194.
+ */
+const pvField = (publicValues, hexOffset) => ({
+    substr: [publicValues, hexOffset, 64],
+});
+/** Standard public state every shielded pool carries (the rest of the app state is private/off-chain). */
+export const SHIELDED_POOL_STATE = {
+    vkey: { type: 'hash', immutable: true },
+    exprHash: { type: 'hash', immutable: true },
+    rootWindow: { type: 'integer', immutable: true },
+    currentRoot: { type: 'hash', computed: true },
+    knownRoots: { type: 'array', computed: true, description: 'rolling window of valid anchors (hex)' },
+    nullifiers: { type: 'array', computed: true, description: 'spent set (hex); monotonic — see RFC §5.3' },
+    commitments: { type: 'array', computed: true, description: 'append-only log of output commitments (hex)' },
+    leafCount: { type: 'integer', computed: true, default: 0 },
+    transitions: { type: 'integer', computed: true, default: 0 },
+};
+/**
+ * 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 function shieldApp(base, opts) {
+    const publicValues = { var: 'event.publicValues' };
+    const anchor = pvField(publicValues, 2);
+    const nullifier = pvField(publicValues, 66);
+    const newCommitment = pvField(publicValues, 130);
+    const exprHash = pvField(publicValues, 194);
+    // GUARD (combine): all stateful, combiner-only.
+    const guard = {
+        and: [
+            // 1. the proof verifies against the pool's pinned vkey over EXACTLY these public bytes
+            { groth16_verify: [{ var: 'state.vkey' }, publicValues, { var: 'event.proof' }] },
+            // 2. it ran the app logic this pool pins (binds which effect produced the transition)
+            { '===': [exprHash, { var: 'state.exprHash' }] },
+            // 3. the spent note was proven under an anchor we still honor
+            { in: [anchor, { var: 'state.knownRoots' }] },
+            // 4. inter-transfer double-spend guard: the nullifier is not already spent
+            { none: [{ var: 'state.nullifiers' }, { '===': [{ var: '' }, nullifier] }] },
+        ],
+    };
+    // EFFECT (combine): spend the nullifier, record the new commitment, advance counters.
+    // Root advancement (turning the appended commitment into the next anchor) is wallet/Bridge-side
+    // per RFC §6.2 / §10; the chain records the commitment + nullifier here.
+    const effect = {
+        merge: [
+            { var: 'state' },
+            {
+                nullifiers: { cat: [{ var: 'state.nullifiers' }, [nullifier]] },
+                commitments: { cat: [{ var: 'state.commitments' }, [newCommitment]] },
+                leafCount: { '+': [{ var: 'state.leafCount' }, 1] },
+                transitions: { '+': [{ var: 'state.transitions' }, 1] },
+                lastTransitionAt: { var: '$ordinal' },
+            },
+        ],
+    };
+    return defineFiberApp({
+        metadata: {
+            name: `Shielded${base.metadata.name}`,
+            app: 'privacy',
+            type: `shielded-${base.metadata.type}`,
+            version: base.metadata.version,
+            description: `Shielded (zk-jlvm-shielded) variant of ${base.metadata.name}: private state transitions ` +
+                `verified by a Groth16 proof; the nullifier set + anchors are public pool state.`,
+        },
+        createSchema: {
+            required: ['vkey', 'exprHash'],
+            properties: {
+                vkey: { type: 'hash', immutable: true, default: opts.vkey },
+                exprHash: { type: 'hash', immutable: true, default: opts.exprHash },
+                rootWindow: { type: 'integer', immutable: true, default: opts.rootWindow ?? 64 },
+            },
+        },
+        stateSchema: { properties: { ...SHIELDED_POOL_STATE } },
+        eventSchemas: {
+            transition: {
+                description: `A private state transition of ${base.metadata.name}, attested by a zk-jlvm-shielded Groth16 proof.`,
+                required: ['proof', 'publicValues'],
+                properties: {
+                    proof: { type: 'string', description: 'Groth16 proof bytes (0x hex)' },
+                    publicValues: { type: 'string', description: 'abi-encoded JlvmTransitionPublicValues (4×bytes32, 0x hex)' },
+                },
+            },
+        },
+        states: {
+            ACTIVE: {
+                id: 'ACTIVE',
+                isFinal: false,
+                metadata: { label: 'Active', description: 'Pool accepts shielded transitions', category: 'active' },
+            },
+        },
+        initialState: 'ACTIVE',
+        transitions: [{ from: 'ACTIVE', to: 'ACTIVE', eventName: 'transition', guard, effect, dependencies: [] }],
+    });
+}

package/dist/esm/schema/effects.js

@@ -0,0 +1,145 @@
+/**
+ * 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" }) },
+ *   ],
+ * }
+ * ```
+ */
+/**
+ * `_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 const addDependency = (fiberId) => ({
+    _addDependency: [{ fiberId }],
+});
+/**
+ * `_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 const setDependencyActive = (fiberId, active) => ({
+    _setDependencyActive: [{ fiberId, active }],
+});
+/**
+ * `_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 const transferAsset = (transfers) => ({ _transferAsset: transfers });
+/**
+ * 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 const toFiber = (fiberId) => ({
+    Fiber: { fiberId },
+});
+/** See {@link toFiber}: a `transferAsset` recipient held by a wallet — `{"Wallet":{"address":..}}`. */
+export const toWallet = (address) => ({
+    Wallet: { address },
+});
+/**
+ * `_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 const triggers = (ts) => ({
+    _triggers: ts.map((t) => ({
+        targetMachineId: t.target,
+        eventName: t.event,
+        payload: t.payload ?? {},
+    })),
+});
+/**
+ * `_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 const spawn = (ds) => ({ _spawn: ds });
+/**
+ * `_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 const emit = (es) => ({
+    _emit: es,
+});
+/**
+ * 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 const RESERVED_EFFECT_KEYS = [
+    '_triggers',
+    '_spawn',
+    '_emit',
+    '_transferAsset',
+    '_scriptCall',
+    '_addDependency',
+    '_setDependencyActive',
+];

package/dist/esm/schema/fiber-app.js

@@ -4,6 +4,121 @@
  * TypeScript-first definitions for fiber apps. This is the source of truth —
  * no JSON, no code generation. Import types directly.
  */
+/**
+ * The wire (and authoring) tag for the `Immutable` policy VARIANT: the bare JSON string
+ * `"Immutable"`. EXACT casing, capital-I — this is the POLICY-LEVEL variant name and is
+ * DISTINCT from the `upgradePolicy` dial VALUE `"immutable"` (lowercase). The chain emits
+ * exactly this capital-I string for `Immutable`, so the SDK must too, byte-for-byte.
+ */
+export const IMMUTABLE_POLICY = 'Immutable';
+/** The names of the 15 policy dials, in declaration order. Used by the projector. */
+const FIBER_POLICY_DIALS = [
+    'selfReproducing',
+    'allowedEffects',
+    'spawnOwnerPolicy',
+    'maxGenerations',
+    'maxSpawnFanout',
+    'acceptedCallers',
+    'sealedStates',
+    'transitionPolicy',
+    'transferPolicy',
+    'dependencyPolicy',
+    'upgradePolicy',
+    'version',
+    'compatibleWith',
+    'interfaces',
+    'migrationAuthority',
+];
+/**
+ * The canonical UNCONSTRAINED policy: omission. Provided as a named export for
+ * readability at call sites — `policy: unconstrained()` documents intent, and projects
+ * to NO `policy` key (identical to leaving `policy` off entirely).
+ */
+export function unconstrained() {
+    return undefined;
+}
+/**
+ * The canonical IMMUTABLE policy: the definition is permanently locked. Projects to the
+ * bare JSON string `"Immutable"` ({@link IMMUTABLE_POLICY}), the chain's `Immutable`
+ * variant tag. Semantically equivalent to `constrained({ upgradePolicy: 'immutable' })`
+ * with no other dial set — which `constrained()`/`projectFiberPolicy()` collapse to the
+ * same string for wire parity (see {@link constrained}).
+ *
+ * @example
+ * ```ts
+ * const def = defineFiberApp({ ...spec, policy: immutable() });
+ * ```
+ */
+export function immutable() {
+    return IMMUTABLE_POLICY;
+}
+/**
+ * Build a CONSTRAINED `FiberPolicy` from any subset of the 15 dials.
+ *
+ * Pass only the dials you want to set. Dials left `undefined`/`null` are dropped so the
+ * result is a clean, minimal object that serializes identically to the chain's
+ * `dropNulls`-stripped `Constrained`. If NO dial is effectively set, this returns
+ * `undefined` (an empty constraint == `Unconstrained`), which projects to no `policy`
+ * key — preserving wire parity.
+ *
+ * CANONICAL COLLAPSE: `constrained({ upgradePolicy: 'immutable' })` with NO other dial set
+ * collapses to the bare string `"Immutable"` ({@link IMMUTABLE_POLICY}), because the chain
+ * collapses that exact `Constrained` into the `Immutable` variant. NOTE the casing: the
+ * collapse triggers on the chain's LOWERCASE upgradePolicy dial value `"immutable"`, and
+ * the result is the capital-I policy-variant tag `"Immutable"`. Signing the dials object
+ * `{ "upgradePolicy": "immutable" }` instead would diverge the canonical (the chain
+ * re-encodes it as `"Immutable"`) and break the create signature. Adding ANY other dial
+ * keeps it a dials object.
+ *
+ * @example
+ * ```ts
+ * const policy = constrained({
+ *   selfReproducing: false,
+ *   maxGenerations: 3,
+ *   allowedEffects: ['EMIT', 'TRANSFER'],
+ *   sealedStates: ['ARCHIVED'],
+ * });
+ * ```
+ */
+export function constrained(dials) {
+    const out = {};
+    for (const k of FIBER_POLICY_DIALS) {
+        const v = dials[k];
+        if (v === undefined || v === null)
+            continue;
+        out[k] = v;
+    }
+    const keys = Object.keys(out);
+    if (keys.length === 0)
+        return undefined;
+    // Canonical collapse: a lone LOWERCASE `upgradePolicy: 'immutable'` (the chain's dial
+    // value) IS the `Immutable` variant — emit the capital-I `"Immutable"` tag, not the dials.
+    if (keys.length === 1 && out.upgradePolicy === 'immutable')
+        return IMMUTABLE_POLICY;
+    return out;
+}
+/**
+ * Project an authoring `policy` value onto the wire form. Returns one of:
+ *   - `undefined` when the policy is (effectively) `Unconstrained` — i.e. omit the `policy`
+ *     key entirely;
+ *   - the bare string `"Immutable"` ({@link IMMUTABLE_POLICY}) for the `Immutable` variant
+ *     (also the collapse of a lone LOWERCASE `upgradePolicy: 'immutable'`); or
+ *   - the minimal `Constrained` dials object otherwise.
+ *
+ * Centralizes the omit-on-unconstrained AND the Immutable-collapse parity rules so every
+ * projection path (`toProtoDefinition`, the genesis manifest) stays consistent.
+ */
+export function projectFiberPolicy(policy) {
+    if (policy === undefined || policy === null)
+        return undefined;
+    // The Immutable variant is already its canonical bare-string wire form.
+    if (policy === IMMUTABLE_POLICY)
+        return IMMUTABLE_POLICY;
+    // Re-run the dial filter so a hand-built object with explicit-undefined/empty dials
+    // collapses to Unconstrained, and a lone `upgradePolicy: 'immutable'` collapses to
+    // `"Immutable"`, exactly like `constrained()` does.
+    return constrained(policy);
+}
 // =============================================================================
 // Helper: defineFiberApp
 // =============================================================================
@@ -31,11 +146,11 @@ export function defineFiberApp(definition) {
 }
 /** Get valid transitions from a given state */
 export function getTransitionsFrom(def, state) {
-    return def.transitions.filter(t => t.from === state);
+    return def.transitions.filter((t) => t.from === state);
 }
 /** Get valid event names from a given state */
 export function getEventsFrom(def, state) {
-    return getTransitionsFrom(def, state).map(t => t.eventName);
+    return getTransitionsFrom(def, state).map((t) => t.eventName);
 }
 /** Check if a state is final */
 export function isFinalState(def, state) {
@@ -62,14 +177,19 @@ export function toProtoDefinition(def) {
     const protoDef = {
         states: {},
         initialState: def.initialState,
-        transitions: def.transitions.map(t => ({
+        transitions: def.transitions.map((t) => ({
             from: t.from,
             to: t.to,
             eventName: t.eventName,
             guard: t.guard, // Required - Scala has no default
             effect: t.effect, // Required - Scala has no default
-            // dependencies has default Set.empty in Scala, so omit if empty
-            ...(t.dependencies?.length && { dependencies: [...t.dependencies] }),
+            // Chain `Transition.dependencies: Set[UUID]` is REQUIRED (no Scala default), and each
+            // element must be a fiber UUID string. A `DependencySpec` object is a build-time-only
+            // authoring affordance with no wire representation (concrete dependency UUIDs are per
+            // instance, not part of the definition template), so drop non-string entries. Always
+            // emit the array — omitting a no-default field diverges the canonical and the chain
+            // rejects the whole update (InvalidSignature / decode failure).
+            dependencies: (t.dependencies ?? []).filter((d) => typeof d === 'string'),
         })),
     };
     // Copy states (only id and isFinal)
@@ -79,9 +199,20 @@ export function toProtoDefinition(def) {
             isFinal: state.isFinal,
         };
     }
-    // Pass metadata through unchanged - it's an optional unstructured object
-    if (def.metadata) {
-        protoDef.metadata = def.metadata;
+    // NOTE: `def.metadata` is the SDK's FiberAppMetadata (name/app/type/version — app-routing
+    // packaging info), NOT chain metadata. Projecting it onto the wire would make the on-chain
+    // canonical + the registry `logicHash` depend on packaging fields (changing `description` would
+    // change the signed digest of an otherwise-identical machine), so it is deliberately NOT emitted
+    // (the chain's `StateMachineDefinition.metadata` stays absent → `None`). A caller that genuinely
+    // needs on-chain metadata sets `ProtoStateMachineDefinition.metadata` explicitly after conversion.
+    // Fiber constitution. OMIT the `policy` key entirely for `Unconstrained` (the chain
+    // emits nothing for it); emit the bare string `"Immutable"` for `Immutable`; emit a bare
+    // object of only the SET dials for `Constrained`. `projectFiberPolicy` returns `undefined`
+    // for an (effectively) unconstrained policy, so we assign only when it is a real policy —
+    // keeping the wire byte-for-byte identical to the chain's encoding.
+    const policy = projectFiberPolicy(def.policy);
+    if (policy !== undefined) {
+        protoDef.policy = policy;
     }
     return protoDef;
 }