@ottochain/sdk 2.3.0 → 2.5.0

package/dist/esm/zk/prover.js

@@ -0,0 +1,82 @@
+/**
+ * Driving the SP1 zk-jlvm host (`rust/zk-jlvm/script`, `--mode groth16`) to produce a
+ * {@link Groth16Bundle} from a JLVM `expr` + `data`.
+ *
+ * THE load-bearing step: the host's guest hashes the RAW `--expr` / `--data` strings
+ * (`exprHash = keccak256(expr_bytes)`), so this driver feeds it `canonicalForSigning(expr)` /
+ * `canonicalForSigning(data)`. That makes a proof's `exprHash` word equal {@link exprHash}`(rule)`
+ * equal a policy's `logicHash` — without it the binding silently never matches.
+ *
+ * Proving is heavy (SP1; minutes, optionally `SP1_PROVER=cuda`) and needs the Rust toolchain, so this
+ * is an out-of-process driver, not an in-SDK prover. Point it at a prebuilt `binaryPath`, or at the
+ * crate via `cargoManifestPath`; configure either explicitly or through `ZK_JLVM_BIN` /
+ * `ZK_JLVM_MANIFEST` env vars.
+ */
+import { canonicalForSigning } from './preimage';
+const reLine = (label) => new RegExp(`^${label}:\\s*(0x[0-9a-fA-F]+)\\s*$`, 'm');
+/** Parse the host's `vkey:` / `public values:` / `proof bytes:` stdout lines into a bundle. */
+export function parseGroth16Stdout(stdout) {
+    const grab = (label, key) => {
+        const m = stdout.match(reLine(label));
+        if (!m)
+            throw new Error(`zk-jlvm host produced no "${label}:" line (could not read ${key})`);
+        return m[1].toLowerCase();
+    };
+    return {
+        vkey: grab('vkey', 'vkey'),
+        publicValues: grab('public values', 'publicValues'),
+        proof: grab('proof bytes', 'proof'),
+    };
+}
+/** Drives the zk-jlvm host out-of-process. */
+export class SubprocessProver {
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async proveGroth16(req) {
+        // Canonicalize BEFORE proving so exprHash/dataHash bind the same bytes the chain signs over.
+        const expr = canonicalForSigning(req.expr);
+        const data = canonicalForSigning(req.data);
+        const modeArgs = ['--mode', 'groth16', '--expr', expr, '--data', data];
+        const binaryPath = this.opts.binaryPath ?? process.env.ZK_JLVM_BIN;
+        const manifest = this.opts.cargoManifestPath ?? process.env.ZK_JLVM_MANIFEST;
+        let command;
+        let args;
+        if (binaryPath) {
+            command = binaryPath;
+            args = modeArgs;
+        }
+        else if (manifest) {
+            command = 'cargo';
+            args = ['run', '--release', '--manifest-path', manifest, '--', ...modeArgs];
+        }
+        else {
+            throw new Error('SubprocessProver: set `binaryPath` (or ZK_JLVM_BIN), or `cargoManifestPath` (or ZK_JLVM_MANIFEST)');
+        }
+        const stdout = await this.run(command, args);
+        return parseGroth16Stdout(stdout);
+    }
+    run(command, args) {
+        const { env, cwd, timeoutMs = 1800000 } = this.opts;
+        // Lazy-load child_process so importing the zk slice stays light for non-proving consumers.
+        return import('node:child_process').then(({ spawn }) => new Promise((resolve, reject) => {
+            // argv (no shell) — `expr`/`data` are JSON with quotes/braces; never interpolate into a shell.
+            const child = spawn(command, args, {
+                cwd,
+                env: { ...process.env, ...env },
+                timeout: timeoutMs,
+            });
+            let out = '';
+            let err = '';
+            child.stdout.on('data', (d) => (out += d.toString()));
+            child.stderr.on('data', (d) => (err += d.toString()));
+            child.on('error', reject);
+            child.on('close', (code) => {
+                if (code === 0)
+                    resolve(out);
+                else
+                    reject(new Error(`zk-jlvm host exited ${code}: ${err.trim() || out.trim()}`));
+            });
+        }));
+    }
+}

package/dist/esm/zk/registry.js

@@ -0,0 +1,55 @@
+/**
+ * The expression registry binds a human name → a published JLVM rule → its `logicHash`
+ * (`keccak256(canonicalize(rule))`). The `logicHash` is the load-bearing public value: it equals the
+ * `exprHash` word a zk-jlvm proof commits AND the literal a semi-private guard pins. Registering a
+ * rule with a LITERAL bound ("pin the bound into the rule", e.g. `{">=":[{"var":"score"},700]}`)
+ * makes "the proof's exprHash == this logicHash" mean "the hidden value satisfies THIS public,
+ * legible rule" — privacy of the value, transparency of the predicate.
+ */
+import { exprHash } from './preimage';
+/** A client-side registry mapping rule names to their canonical `logicHash`. */
+export class ExprRegistry {
+    constructor() {
+        this.byName = new Map();
+    }
+    /** Register (or replace) a named rule; returns the entry with its computed `logicHash`. */
+    register(name, rule) {
+        const entry = { rule, logicHash: exprHash(rule) };
+        this.byName.set(name, entry);
+        return entry;
+    }
+    /** Whether a rule is registered under `name`. */
+    has(name) {
+        return this.byName.has(name);
+    }
+    /** The registered rule, or throw if unknown. */
+    ruleOf(name) {
+        return this.require(name).rule;
+    }
+    /** The registered rule's `logicHash`, or throw if unknown. */
+    logicHashOf(name) {
+        return this.require(name).logicHash;
+    }
+    /** All registered names, in insertion order. */
+    names() {
+        return [...this.byName.keys()];
+    }
+    require(name) {
+        const entry = this.byName.get(name);
+        if (!entry)
+            throw new Error(`ExprRegistry: no rule registered under "${name}"`);
+        return entry;
+    }
+}
+/**
+ * A single-bound predicate `{[op]:[{var:varName}, bound]}` — the "pinned bound" a proof binds to.
+ * `bound` stays a JSON primitive (number/string) so the canonical bytes the prover hashes match the
+ * canonical bytes the rule registers under (bigint is not JSON-serializable — pre-encode if needed).
+ */
+export function boundRule(varName, op, bound) {
+    return { [op]: [{ var: varName }, bound] };
+}
+/** `{">=":[{"var":varName}, bound]}` — "the hidden `varName` is at least `bound`". */
+export const atLeast = (varName, bound) => boundRule(varName, '>=', bound);
+/** `{"<=":[{"var":varName}, bound]}` — "the hidden `varName` is at most `bound`". */
+export const atMost = (varName, bound) => boundRule(varName, '<=', bound);

package/dist/esm/zk/types.js

@@ -0,0 +1,25 @@
+/**
+ * SP1 zk-jlvm public-values types + decode.
+ *
+ * The guest commits `abi_encode(JlvmPublicValues{ bytes32 exprHash, bytes32 dataHash,
+ * bytes32 outputHash, bool ok })` — four 32-byte words, the bool right-aligned in its word.
+ * There is no on-chain `jlvm_pv_decode` opcode: the chain guard parses the same blob with the
+ * native JLVM `cat`/`substr` ops. This decode mirrors that for client-side binding/inspection.
+ */
+/**
+ * Decode `abi_encode(JlvmPublicValues)`: four 32-byte words `[exprHash | dataHash | outputHash | ok]`.
+ * The bool is right-aligned in its word (final byte `0x00`/`0x01`).
+ */
+export function decodeJlvmPublicValues(pv) {
+    const b = pv.startsWith('0x') ? pv.slice(2) : pv;
+    if (b.length < 4 * 64) {
+        throw new Error(`publicValues too short: ${b.length} hex chars (need >= 256)`);
+    }
+    const word = (i) => `0x${b.slice(i * 64, i * 64 + 64)}`;
+    return {
+        exprHash: word(0),
+        dataHash: word(1),
+        outputHash: word(2),
+        ok: b.slice(3 * 64 + 62, 3 * 64 + 64) !== '00',
+    };
+}

package/dist/esm/zk/witness.js

@@ -0,0 +1,15 @@
+import { decodeJlvmPublicValues } from './types';
+/**
+ * Shape a produced {@link Groth16Bundle} into the on-op witness map (`{publicValues, proof}`) and
+ * surface its decoded public values. The vkey rides in the guard, not the witness, so it is dropped.
+ */
+export function groth16Witness(bundle) {
+    return {
+        witness: { publicValues: bundle.publicValues, proof: bundle.proof },
+        decoded: decodeJlvmPublicValues(bundle.publicValues),
+    };
+}
+/** Shape a Poseidon-Merkle inclusion path into the on-op `pmt_verify` witness map. */
+export function pmtWitness(leaf, index, siblings) {
+    return { leaf, index, siblings };
+}

package/dist/types/apps/compute/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Compute Application — bare computation substrates.
+ *
+ * Turing-complete JLVM substrates with no parties, assets, or governance: pure
+ * in-place state evolution. The flagship is `rule110`, an in-place Rule-110
+ * cellular automaton that proves the account layer is Turing-complete.
+ *
+ * @example
+ * ```typescript
+ * import { getComputeDefinition, COMPUTE_DEFINITIONS } from '@ottochain/sdk/apps/compute';
+ *
+ * const rule110Def = getComputeDefinition('rule110');
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { computeRule110Def } from './state-machines/index.js';
+import type { FiberAppDefinition } from '../../schema/fiber-app.js';
+export { computeRule110Def };
+/** All compute (bare-computation) state machine definitions. */
+export declare const COMPUTE_DEFINITIONS: {
+    readonly rule110: {
+        readonly metadata: {
+            readonly name: "ComputeRule110";
+            readonly app: "compute";
+            readonly type: "rule110";
+            readonly version: "1.0.0";
+            readonly description: string;
+        };
+        readonly createSchema: {
+            readonly required: readonly ["tape", "idx"];
+            readonly properties: {
+                readonly tape: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "integer";
+                    };
+                    readonly description: "0/1 CA row (length N).";
+                };
+                readonly idx: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "integer";
+                    };
+                    readonly immutable: true;
+                    readonly description: string;
+                };
+                readonly gen: {
+                    readonly type: "integer";
+                    readonly default: 0;
+                    readonly description: "Generation counter (TM step count).";
+                };
+                readonly maxGen: {
+                    readonly type: "integer";
+                    readonly description: "Optional halt bound; absent ⇒ unbounded.";
+                };
+            };
+        };
+        readonly stateSchema: {
+            readonly properties: {
+                readonly tape: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "integer";
+                    };
+                    readonly computed: true;
+                };
+                readonly idx: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "integer";
+                    };
+                    readonly immutable: true;
+                };
+                readonly gen: {
+                    readonly type: "integer";
+                    readonly computed: true;
+                };
+                readonly maxGen: {
+                    readonly type: "integer";
+                };
+                readonly status: {
+                    readonly type: "string";
+                    readonly computed: true;
+                };
+            };
+        };
+        readonly eventSchemas: {
+            readonly step: {
+                readonly description: "Advance one CA generation in place.";
+            };
+            readonly halt: {
+                readonly description: "Terminate once maxGen is reached (gated by gen >= maxGen).";
+            };
+        };
+        readonly states: {
+            readonly RUNNING: {
+                readonly id: "RUNNING";
+                readonly isFinal: false;
+                readonly metadata: {
+                    readonly label: "Running";
+                    readonly description: "CA evolving; each step = one generation.";
+                    readonly category: "active";
+                };
+            };
+            readonly HALTED: {
+                readonly id: "HALTED";
+                readonly isFinal: true;
+                readonly metadata: {
+                    readonly label: "Halted";
+                    readonly description: "maxGen reached; terminal.";
+                    readonly category: "terminal";
+                };
+            };
+        };
+        readonly initialState: "RUNNING";
+        readonly transitions: readonly [{
+            readonly from: "RUNNING";
+            readonly to: "RUNNING";
+            readonly eventName: "step";
+            readonly guard: {
+                readonly or: readonly [{
+                    readonly missing: readonly ["state.maxGen"];
+                }, {
+                    readonly '<': readonly [{
+                        readonly var: "state.gen";
+                    }, {
+                        readonly var: "state.maxGen";
+                    }];
+                }];
+            };
+            readonly effect: {
+                readonly merge: readonly [{
+                    readonly var: "state";
+                }, {
+                    readonly tape: {
+                        readonly map: readonly [{
+                            readonly var: "state.idx";
+                        }, import("../../schema/fiber-app.js").JsonLogicRule];
+                    };
+                    readonly gen: {
+                        readonly '+': readonly [{
+                            readonly var: "state.gen";
+                        }, 1];
+                    };
+                }];
+            };
+            readonly dependencies: readonly [];
+        }, {
+            readonly from: "RUNNING";
+            readonly to: "HALTED";
+            readonly eventName: "halt";
+            readonly guard: {
+                readonly '>=': readonly [{
+                    readonly var: "state.gen";
+                }, {
+                    readonly var: "state.maxGen";
+                }];
+            };
+            readonly effect: {
+                readonly merge: readonly [{
+                    readonly var: "state";
+                }, {
+                    readonly status: "halted";
+                }];
+            };
+            readonly dependencies: readonly [];
+        }];
+    };
+};
+export type ComputeDefType = keyof typeof COMPUTE_DEFINITIONS;
+/**
+ * Get a compute state machine definition by type.
+ * @param type - 'rule110' (default).
+ */
+export declare function getComputeDefinition(type?: ComputeDefType): FiberAppDefinition;

package/dist/types/apps/compute/state-machines/compute-rule110.d.ts

@@ -0,0 +1,157 @@
+import type { JsonLogicRule } from '../../../schema/fiber-app.js';
+/**
+ * Rule-110 cellular-automaton fiber definition.
+ *
+ * Trust model: PUBLIC / PERMISSIONLESS / pure compute. No assets, no parties,
+ * no owner — anyone may submit `step`. The DoS surface is bounded by per-event
+ * gas/fee (~987 gas/cell) and the optional `maxGen` halt bound (absent ⇒
+ * unbounded; runs until fees stop).
+ */
+export declare const computeRule110Def: {
+    readonly metadata: {
+        readonly name: "ComputeRule110";
+        readonly app: "compute";
+        readonly type: "rule110";
+        readonly version: "1.0.0";
+        readonly description: string;
+    };
+    readonly createSchema: {
+        readonly required: readonly ["tape", "idx"];
+        readonly properties: {
+            readonly tape: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "integer";
+                };
+                readonly description: "0/1 CA row (length N).";
+            };
+            readonly idx: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "integer";
+                };
+                readonly immutable: true;
+                readonly description: string;
+            };
+            readonly gen: {
+                readonly type: "integer";
+                readonly default: 0;
+                readonly description: "Generation counter (TM step count).";
+            };
+            readonly maxGen: {
+                readonly type: "integer";
+                readonly description: "Optional halt bound; absent ⇒ unbounded.";
+            };
+        };
+    };
+    readonly stateSchema: {
+        readonly properties: {
+            readonly tape: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "integer";
+                };
+                readonly computed: true;
+            };
+            readonly idx: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "integer";
+                };
+                readonly immutable: true;
+            };
+            readonly gen: {
+                readonly type: "integer";
+                readonly computed: true;
+            };
+            readonly maxGen: {
+                readonly type: "integer";
+            };
+            readonly status: {
+                readonly type: "string";
+                readonly computed: true;
+            };
+        };
+    };
+    readonly eventSchemas: {
+        readonly step: {
+            readonly description: "Advance one CA generation in place.";
+        };
+        readonly halt: {
+            readonly description: "Terminate once maxGen is reached (gated by gen >= maxGen).";
+        };
+    };
+    readonly states: {
+        readonly RUNNING: {
+            readonly id: "RUNNING";
+            readonly isFinal: false;
+            readonly metadata: {
+                readonly label: "Running";
+                readonly description: "CA evolving; each step = one generation.";
+                readonly category: "active";
+            };
+        };
+        readonly HALTED: {
+            readonly id: "HALTED";
+            readonly isFinal: true;
+            readonly metadata: {
+                readonly label: "Halted";
+                readonly description: "maxGen reached; terminal.";
+                readonly category: "terminal";
+            };
+        };
+    };
+    readonly initialState: "RUNNING";
+    readonly transitions: readonly [{
+        readonly from: "RUNNING";
+        readonly to: "RUNNING";
+        readonly eventName: "step";
+        readonly guard: {
+            readonly or: readonly [{
+                readonly missing: readonly ["state.maxGen"];
+            }, {
+                readonly '<': readonly [{
+                    readonly var: "state.gen";
+                }, {
+                    readonly var: "state.maxGen";
+                }];
+            }];
+        };
+        readonly effect: {
+            readonly merge: readonly [{
+                readonly var: "state";
+            }, {
+                readonly tape: {
+                    readonly map: readonly [{
+                        readonly var: "state.idx";
+                    }, JsonLogicRule];
+                };
+                readonly gen: {
+                    readonly '+': readonly [{
+                        readonly var: "state.gen";
+                    }, 1];
+                };
+            }];
+        };
+        readonly dependencies: readonly [];
+    }, {
+        readonly from: "RUNNING";
+        readonly to: "HALTED";
+        readonly eventName: "halt";
+        readonly guard: {
+            readonly '>=': readonly [{
+                readonly var: "state.gen";
+            }, {
+                readonly var: "state.maxGen";
+            }];
+        };
+        readonly effect: {
+            readonly merge: readonly [{
+                readonly var: "state";
+            }, {
+                readonly status: "halted";
+            }];
+        };
+        readonly dependencies: readonly [];
+    }];
+};

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

@@ -0,0 +1,5 @@
+/**
+ * Compute (bare-computation) state machine definitions.
+ * Re-exports from TypeScript definition files.
+ */
+export { computeRule110Def } from './compute-rule110.js';