@ottochain/sdk 2.2.5 → 2.4.0

package/dist/cjs/privacy/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vickreyAuctionDef = exports.shieldedSealedBidDef = exports.sealedBidAccountDef = exports.SHIELDED_POOL_STATE = exports.shieldApp = void 0;
+/**
+ * Privacy: shield any fiber app into a zk-jlvm-shielded private-state pool.
+ * See docs/design/zk-private-contract-state-rfc.md.
+ */
+var shield_app_js_1 = require("./shield-app.js");
+Object.defineProperty(exports, "shieldApp", { enumerable: true, get: function () { return shield_app_js_1.shieldApp; } });
+Object.defineProperty(exports, "SHIELDED_POOL_STATE", { enumerable: true, get: function () { return shield_app_js_1.SHIELDED_POOL_STATE; } });
+var sealed_bid_js_1 = require("./sealed-bid.js");
+Object.defineProperty(exports, "sealedBidAccountDef", { enumerable: true, get: function () { return sealed_bid_js_1.sealedBidAccountDef; } });
+Object.defineProperty(exports, "shieldedSealedBidDef", { enumerable: true, get: function () { return sealed_bid_js_1.shieldedSealedBidDef; } });
+Object.defineProperty(exports, "vickreyAuctionDef", { enumerable: true, get: function () { return sealed_bid_js_1.vickreyAuctionDef; } });

package/dist/cjs/privacy/sealed-bid.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vickreyAuctionDef = exports.sealedBidAccountDef = void 0;
+exports.shieldedSealedBidDef = shieldedSealedBidDef;
+const fiber_app_js_1 = require("../schema/fiber-app.js");
+const shield_app_js_1 = require("./shield-app.js");
+// ── 1. The private bid (base app, shielded by shieldApp) ──────────────────────
+/** The per-bidder PRIVATE state: a bid note `{ amount, bidder, nonce }`. */
+exports.sealedBidAccountDef = (0, fiber_app_js_1.defineFiberApp)({
+    metadata: {
+        name: "SealedBidAccount",
+        app: "markets",
+        type: "sealed-bid-account",
+        version: "1.0.0",
+        description: "A single bidder's sealed bid (private amount). Shielded via shieldApp.",
+    },
+    stateSchema: {
+        properties: {
+            amount: { type: "number", description: "the (private) bid amount" },
+            bidder: { type: "address" },
+            nonce: { type: "number", description: "per-note randomness; keeps the commitment hiding" },
+        },
+    },
+    eventSchemas: {
+        place_bid: {
+            description: "Set the sealed bid amount",
+            required: ["amount"],
+            properties: { amount: { type: "number", minimum: 1 } },
+        },
+    },
+    states: {
+        OPEN: { id: "OPEN", isFinal: false, metadata: { label: "Open", description: "No bid yet", category: "initial" } },
+        BID: { id: "BID", isFinal: false, metadata: { label: "Bid", description: "Bid committed", category: "active" } },
+    },
+    initialState: "OPEN",
+    transitions: [
+        {
+            // This effect is what the zk-jlvm-shielded circuit runs in-zkVM; `exprHash` pins it.
+            from: "OPEN",
+            to: "BID",
+            eventName: "place_bid",
+            guard: { ">": [{ var: "event.amount" }, 0] },
+            effect: { merge: [{ var: "state" }, { amount: { var: "event.amount" } }] },
+            dependencies: [],
+        },
+    ],
+});
+/**
+ * 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).
+ */
+function shieldedSealedBidDef(opts) {
+    return (0, shield_app_js_1.shieldApp)(exports.sealedBidAccountDef, opts);
+}
+// ── 2. The public Vickrey settlement ──────────────────────────────────────────
+/**
+ * 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.
+ */
+exports.vickreyAuctionDef = (0, fiber_app_js_1.defineFiberApp)({
+    metadata: {
+        name: "VickreyAuction",
+        app: "markets",
+        type: "vickrey-auction",
+        version: "1.0.0",
+        description: "Sealed-bid second-price auction: public reveal-then-tally over shielded bids.",
+        crossReferences: { bidPool: "the ShieldedSealedBidAccount pool holding the sealed bids" },
+    },
+    createSchema: {
+        required: ["seller", "deadline"],
+        properties: {
+            seller: { type: "address", immutable: true },
+            deadline: { type: "timestamp", immutable: true },
+        },
+    },
+    stateSchema: {
+        properties: {
+            seller: { type: "address", immutable: true },
+            deadline: { type: "timestamp", immutable: true },
+            status: { type: "string", computed: true },
+            revealed: { type: "array", computed: true, description: "opened bids [{bidder, amount}]" },
+            winner: { type: "address", computed: true },
+            clearingPrice: { type: "number", computed: true, description: "second-highest bid (Vickrey)" },
+        },
+    },
+    eventSchemas: {
+        reveal: {
+            description: "Open a sealed bid after the deadline",
+            required: ["bidder", "amount"],
+            properties: { bidder: { type: "address" }, amount: { type: "number", minimum: 1 } },
+        },
+        settle: { description: "Tally the revealed bids (winner + second price)" },
+    },
+    states: {
+        OPEN: { id: "OPEN", isFinal: false, metadata: { label: "Open", description: "Bidding (sealed)", category: "initial" } },
+        REVEAL: { id: "REVEAL", isFinal: false, metadata: { label: "Reveal", description: "Opening bids", category: "active" } },
+        SETTLED: { id: "SETTLED", isFinal: true, metadata: { label: "Settled", description: "Winner + price set", category: "terminal" } },
+    },
+    initialState: "OPEN",
+    transitions: [
+        {
+            from: "OPEN",
+            to: "REVEAL",
+            eventName: "reveal",
+            guard: { ">=": [{ var: "$timestamp" }, { var: "state.deadline" }] },
+            effect: {
+                merge: [
+                    { var: "state" },
+                    {
+                        status: "REVEAL",
+                        revealed: {
+                            cat: [
+                                { var: "state.revealed" },
+                                [{ bidder: { var: "event.bidder" }, amount: { var: "event.amount" } }],
+                            ],
+                        },
+                    },
+                ],
+            },
+            dependencies: [],
+        },
+        {
+            from: "REVEAL",
+            to: "REVEAL",
+            eventName: "reveal",
+            guard: { ">=": [{ var: "$timestamp" }, { var: "state.deadline" }] },
+            effect: {
+                merge: [
+                    { var: "state" },
+                    {
+                        revealed: {
+                            cat: [
+                                { var: "state.revealed" },
+                                [{ bidder: { var: "event.bidder" }, amount: { var: "event.amount" } }],
+                            ],
+                        },
+                    },
+                ],
+            },
+            dependencies: [],
+        },
+        {
+            // Vickrey tally: fold the revealed bids tracking (max, second, winner).
+            from: "REVEAL",
+            to: "SETTLED",
+            eventName: "settle",
+            guard: { ">": [{ reduce: [{ var: "state.revealed" }, { "+": [{ var: "accumulator" }, 1] }, 0] }, 0] },
+            effect: {
+                merge: [
+                    { var: "state" },
+                    {
+                        status: "SETTLED",
+                        settledAt: { var: "$timestamp" },
+                        winner: {
+                            var: [
+                                "tally.winner",
+                                null,
+                            ],
+                        },
+                        clearingPrice: { var: ["tally.second", 0] },
+                        // compute the tally once and expose it for the two fields above
+                        tally: {
+                            reduce: [
+                                { var: "state.revealed" },
+                                {
+                                    if: [
+                                        { ">": [{ var: "current.amount" }, { var: "accumulator.max" }] },
+                                        {
+                                            max: { var: "current.amount" },
+                                            second: { var: "accumulator.max" },
+                                            winner: { var: "current.bidder" },
+                                        },
+                                        {
+                                            if: [
+                                                { ">": [{ var: "current.amount" }, { var: "accumulator.second" }] },
+                                                {
+                                                    max: { var: "accumulator.max" },
+                                                    second: { var: "current.amount" },
+                                                    winner: { var: "accumulator.winner" },
+                                                },
+                                                { var: "accumulator" },
+                                            ],
+                                        },
+                                    ],
+                                },
+                                { max: 0, second: 0, winner: null },
+                            ],
+                        },
+                    },
+                ],
+            },
+            dependencies: [],
+        },
+    ],
+});

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

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHIELDED_POOL_STATE = void 0;
+exports.shieldApp = shieldApp;
+const fiber_app_js_1 = require("../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). */
+exports.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.
+ */
+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 (0, fiber_app_js_1.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: { ...exports.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/cjs/schema/effects.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * 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" }) },
+ *   ],
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setDependencyActive = exports.addDependency = void 0;
+/**
+ * `_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).
+ */
+const addDependency = (fiberId) => ({
+    _addDependency: [{ fiberId }],
+});
+exports.addDependency = addDependency;
+/**
+ * `_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.
+ */
+const setDependencyActive = (fiberId, active) => ({
+    _setDependencyActive: [{ fiberId, active }],
+});
+exports.setDependencyActive = setDependencyActive;

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

@@ -6,7 +6,12 @@
  * no JSON, no code generation. Import types directly.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toProtoDefinition = exports.toJSON = exports.isFinalState = exports.getEventsFrom = exports.getTransitionsFrom = exports.defineFiberApp = void 0;
+exports.defineFiberApp = defineFiberApp;
+exports.getTransitionsFrom = getTransitionsFrom;
+exports.getEventsFrom = getEventsFrom;
+exports.isFinalState = isFinalState;
+exports.toJSON = toJSON;
+exports.toProtoDefinition = toProtoDefinition;
 // =============================================================================
 // Helper: defineFiberApp
 // =============================================================================
@@ -32,27 +37,22 @@ function defineFiberApp(definition) {
     // Runtime validation could go here
     return definition;
 }
-exports.defineFiberApp = defineFiberApp;
 /** Get valid transitions from a given state */
 function getTransitionsFrom(def, state) {
     return def.transitions.filter(t => t.from === state);
 }
-exports.getTransitionsFrom = getTransitionsFrom;
 /** Get valid event names from a given state */
 function getEventsFrom(def, state) {
     return getTransitionsFrom(def, state).map(t => t.eventName);
 }
-exports.getEventsFrom = getEventsFrom;
 /** Check if a state is final */
 function isFinalState(def, state) {
     return def.states[state]?.isFinal ?? false;
 }
-exports.isFinalState = isFinalState;
 /** Convert definition to plain JSON (for serialization) */
 function toJSON(def) {
     return JSON.parse(JSON.stringify(def));
 }
-exports.toJSON = toJSON;
 /**
  * Extract proto-compatible StateMachineDefinition from a FiberAppDefinition.
  * Use this when submitting to the metagraph.
@@ -76,8 +76,13 @@ function toProtoDefinition(def) {
             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)
@@ -87,10 +92,11 @@ 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.
     return protoDef;
 }
-exports.toProtoDefinition = toProtoDefinition;