@ottochain/sdk 2.2.5 → 2.4.0

package/dist/esm/zk/commit.js

@@ -0,0 +1,44 @@
+/**
+ * Poseidon commitments over BN254 Fr, computed through the JLVM `poseidon` opcode — the SAME
+ * byte-for-byte implementation the chain and the Rust/Scala circuits use. We deliberately route
+ * through `jsonLogic.apply` rather than reimplementing Poseidon: the opcode locks the field order,
+ * the circomlib round constants, and the `0x` 32-byte big-endian Fr encoding every crypto opcode
+ * expects (hard acceptance vector: `poseidon([1,2]) == 0x115cc0f5…189a`).
+ *
+ * (The standalone `poseidonHash`/`encodeFr` functions exist inside `-jlvm` but are NOT part of its
+ * public export surface — only the VM opcodes are — so the opcode path is also the only stable one.)
+ */
+import { jsonLogic } from '@constellation-network/metagraph-sdk-jlvm';
+import { randomBytes } from 'node:crypto';
+/**
+ * BN254 (alt_bn128) scalar field modulus R. A public field constant (not a secret / not Poseidon
+ * itself); the `poseidon` opcode re-validates canonicity, so this only drives reduction + sampling.
+ */
+export const R = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/** Reduce an arbitrary bigint into a canonical BN254 Fr element `[0, R)`. */
+export const toFr = (x) => ((x % R) + R) % R;
+/** Encode a field element as the lowercase `0x` 32-byte big-endian hex the crypto opcodes expect. */
+export const frToHex = (x) => `0x${toFr(x).toString(16).padStart(64, '0')}`;
+const bytesToBig = (b) => b.reduce((a, x) => (a << 8n) | BigInt(x), 0n);
+/** A fresh random salt as a canonical Fr (rejection-sampled to avoid modulo bias near R). */
+export function randomSalt() {
+    for (;;) {
+        const v = bytesToBig(randomBytes(32));
+        if (v < R)
+            return v;
+    }
+}
+/** `cm = Poseidon([...fields, salt])` via the VM's own opcode. Returns the `0x` 32-byte commitment. */
+export function poseidonCommitN(fields, saltFr) {
+    const inputs = [...fields.map(frToHex), frToHex(saltFr)];
+    // The bundled poseidon supports width t ≤ 5 (≤ 4 inputs incl. the salt); the opcode throws past it.
+    return jsonLogic.apply({ poseidon: inputs }, {});
+}
+/** `cm = Poseidon([fieldFr, saltFr])` — the commitment for one value field (a bid, a score). */
+export function poseidonCommit(fieldFr, saltFr) {
+    return poseidonCommitN([fieldFr], saltFr);
+}
+/** Commit `fields` under a fresh (or supplied) salt; returns the commitment + opening. */
+export function openCommitment(fields, salt = randomSalt()) {
+    return { cm: poseidonCommitN(fields, salt), fields, salt };
+}

package/dist/esm/zk/guard.js

@@ -0,0 +1,99 @@
+/**
+ * The semi-private guard: the JLVM predicate a policy embeds, and its client-side mirror.
+ *
+ * The guard pins THREE facts about the witness the holder carries, using only opcodes metakit
+ * already gas-meters — no new `jlvm_pv_decode`, the public-values blob is parsed with native
+ * `substr`/`cat`:
+ *   1. `groth16_verify[vkey, witness.publicValues, witness.proof]` — the SP1 proof is valid.
+ *   2. the `exprHash` word of the public values == the policy's `logicHash` — the proof ran the
+ *      INTENDED rule (the pinned, legible predicate).
+ *   3. the `outputHash` word == `keccak256("true")` — that rule evaluated to TRUE on the hidden data.
+ *
+ * `publicValues` rides as a `0x` + 256-hex-char string (`0x` | exprHash | dataHash | outputHash | ok),
+ * so word w begins at char `2 + 64*w` and is 64 chars wide. `cat("0x", substr(pv, off, 64))` lifts a
+ * word back to a `0x`-hex value comparable with a `bytes32` literal. These offsets are the on-chain
+ * guard's contract; the Scala policy mirrors this exact shape.
+ */
+import { jsonLogic } from '@constellation-network/metagraph-sdk-jlvm';
+import { KECCAK_TRUE } from './preimage';
+import { decodeJlvmPublicValues } from './types';
+const HEX_PREFIX = 2; // "0x"
+const WORD_HEX = 64; // 32-byte ABI word as hex chars
+/** Char offset of public-values word `w` (0=exprHash, 1=dataHash, 2=outputHash, 3=ok) in the `0x` string. */
+export const wordOffset = (w) => HEX_PREFIX + WORD_HEX * w;
+/** Lift public-values word `w` back to a `0x`-hex value (`cat("0x", substr(pv, off, 64))`). */
+const pvWord = (w) => ({
+    cat: ['0x', { substr: [{ var: 'witness.publicValues' }, wordOffset(w), WORD_HEX] }],
+});
+/**
+ * Build the JLVM guard a `Governed` morphism / mint policy embeds. `vkey` is the zk-jlvm program
+ * verification key (a `bytes32` `0x`-hex literal); `logicHash` is the pinned rule's hash (from
+ * {@link ExprRegistry.logicHashOf}). Returns plain JSON — feed it into an ASSET policy's guard/mintPolicy
+ * (the asset combiner injects the reserved `witness`). In a fiber TRANSITION there is no `witness` key —
+ * the proof rides in the event payload, so read `event.witness.*` instead.
+ *
+ * REPLAY (audit zk-guards): the proven public values commit only {exprHash, dataHash, outputHash, ok} —
+ * nothing situational (no fiber / asset / `$ordinal` / nonce). A valid `{publicValues, proof}` is therefore
+ * a reusable bearer token, replayable across any action pinning the same vkey + logicHash. Bind the action
+ * INSIDE the proven rule (pin a spender/asset/subject, as `reputationCreditRule` pins `subject`) and/or gate
+ * with a one-time nonce ledger until the public values carry action context.
+ */
+export function semiPrivateGuard(vkey, logicHash, opts = {}) {
+    const { requireTrue = true } = opts;
+    const clauses = [
+        { groth16_verify: [vkey, { var: 'witness.publicValues' }, { var: 'witness.proof' }] },
+        { '==': [pvWord(0), logicHash] },
+    ];
+    if (requireTrue) {
+        clauses.push({ '==': [pvWord(2), KECCAK_TRUE] });
+        // ok bit: the final hex pair of word 3 (offset 256) must be "01" — the JLVM run did not error.
+        clauses.push({ '==': [{ substr: [{ var: 'witness.publicValues' }, wordOffset(3) + 62, 2] }, '01'] });
+    }
+    return { and: clauses };
+}
+/**
+ * Locally run the SAME `groth16_verify` pairing the chain runs (the verifier opcode, not the prover).
+ * Returns `false` — never throws — on an invalid/garbage bundle, mirroring the guard's graceful deny.
+ */
+export function verifyGroth16Bundle(bundle) {
+    try {
+        return jsonLogic.apply({ groth16_verify: [bundle.vkey, bundle.publicValues, bundle.proof] }, {}) === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check the binding words WITHOUT the pairing: `exprHash == expectedLogicHash`, `ok` set, and
+ * (when `requireTrue`) `outputHash == keccak256("true")`. Pair with {@link verifyGroth16Bundle} for
+ * the full client-side mirror of the on-chain guard (see {@link verifySemiPrivate}).
+ */
+export function checkSemiPrivateBinding(bundle, expectedLogicHash, opts = {}) {
+    const { requireTrue = true } = opts;
+    const decoded = decodeJlvmPublicValues(bundle.publicValues);
+    const eq = (a, b) => a.toLowerCase() === b.toLowerCase();
+    const reasons = [];
+    if (!eq(decoded.exprHash, expectedLogicHash))
+        reasons.push(`exprHash ${decoded.exprHash} != expected logicHash ${expectedLogicHash}`);
+    if (!decoded.ok)
+        reasons.push('ok bit is false (guest evaluation errored)');
+    if (requireTrue && !eq(decoded.outputHash, KECCAK_TRUE))
+        reasons.push(`outputHash ${decoded.outputHash} != keccak256("true") ${KECCAK_TRUE}`);
+    return { ok: reasons.length === 0, reasons, decoded };
+}
+/**
+ * The full client-side mirror of the on-chain guard: the proof verifies AND its words bind to the
+ * pinned rule (and, by default, to a `true` result). Run this before submitting to fail fast instead
+ * of paying for an on-chain rejection.
+ */
+export function verifySemiPrivate(bundle, expectedLogicHash, opts = {}) {
+    const binding = checkSemiPrivateBinding(bundle, expectedLogicHash, opts);
+    if (!verifyGroth16Bundle(bundle)) {
+        return {
+            ok: false,
+            reasons: ['groth16_verify failed (invalid proof for this vkey/publicValues)', ...binding.reasons],
+            decoded: binding.decoded,
+        };
+    }
+    return binding;
+}

package/dist/esm/zk/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@ottochain/sdk/zk` — the client-side semi-private tier.
+ *
+ * Public-by-default, private-by-opt-in: a holder proves (off-chain, via SP1 zk-jlvm) that some
+ * PRIVATE data satisfies a PUBLIC, pinned JLVM rule, and carries only `{publicValues, proof}` on a
+ * signed op. A policy's {@link semiPrivateGuard} re-verifies the proof and binds it to the pinned
+ * rule on-chain — the value stays hidden, the predicate stays legible.
+ *
+ * The ONE canonical invariant tying it together: the prover is fed `canonicalForSigning(expr)` /
+ * `canonicalForSigning(data)`, so a proof's `exprHash` word equals {@link exprHash}`(rule)` equals a
+ * policy's `logicHash` — see {@link proverPreimage} and docs/design/client-side-private-data.md §3.0.
+ */
+export { canonicalForSigning, proverPreimage, exprHash, dataHash, KECCAK_TRUE, } from './preimage';
+export { R, toFr, frToHex, randomSalt, poseidonCommit, poseidonCommitN, openCommitment, } from './commit';
+export { decodeJlvmPublicValues, } from './types';
+export { groth16Witness, pmtWitness, } from './witness';
+export { ExprRegistry, boundRule, atLeast, atMost, } from './registry';
+export { wordOffset, semiPrivateGuard, verifyGroth16Bundle, checkSemiPrivateBinding, verifySemiPrivate, } from './guard';
+export { SubprocessProver, parseGroth16Stdout, } from './prover';

package/dist/esm/zk/preimage.js

@@ -0,0 +1,30 @@
+/**
+ * The ONE canonical path for the semi-private tier.
+ *
+ * metakit-sdk 1.8.x `canonicalize` = `serializeJcs(dropNullFields)` — it drops null object-fields
+ * before RFC 8785 (server-aligned), so it is the EXACT byte string the chain signs over. Feeding
+ * the zk-jlvm prover this same string makes the proof's keccak preimage equal the signature
+ * preimage — the determinism binding (see docs/design/client-side-private-data.md §3.0).
+ *
+ * Note the two hashes differ by design: signing is sha256 over the canonical bytes (+ Constellation
+ * prefix), the zk-jlvm guest is keccak256 over the canonical bytes — they bind the SAME canonical
+ * string, which is the load-bearing invariant.
+ */
+import { canonicalize } from '@constellation-network/metagraph-sdk';
+import { keccak_256 } from '@noble/hashes/sha3.js';
+const utf8 = (s) => new TextEncoder().encode(s);
+const toHex = (b) => Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+/** The single canonical string both the signer and the prover-feed share (JCS ∘ dropNullFields). */
+export function canonicalForSigning(x) {
+    return canonicalize(x);
+}
+/** keccak256 of the canonical bytes — the value the zk-jlvm guest commits as exprHash / dataHash. */
+export function proverPreimage(x) {
+    return `0x${toHex(keccak_256(utf8(canonicalForSigning(x))))}`;
+}
+/** exprHash of a published JLVM rule (canonicalized + keccak'd). Equals the chain's `logicHash`. */
+export const exprHash = (rule) => proverPreimage(rule);
+/** dataHash of a private data context — kept private; only its hash is public. */
+export const dataHash = (data) => proverPreimage(data);
+/** `keccak256(canonicalize(true))` — the `outputHash` a guard binds for a "rule returned true" proof. */
+export const KECCAK_TRUE = proverPreimage(true);

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 };
+}