@ottochain/sdk 2.3.0 → 2.5.0

package/dist/esm/templates/asset-policy.js

@@ -0,0 +1,182 @@
+/**
+ * Asset-policy preset builders (§1.1 of the SDK std-lib/templates handoff).
+ *
+ * Each builder is a PURE function that emits the exact {@link CreateAssetPolicy} wire body the chain
+ * re-derives — no `Date.now()`/`Math.random()`/`crypto.randomUUID()`; fixed inputs → fixed output. The
+ * on-chain policy `schemaHash` and `logicHash` are both `RegistryShape.AssetPolicy.computeDigest` over
+ * `behavior`/`supply`/`morphisms`/`stateShape` (no JSON-Logic body), so these presets are pure data.
+ *
+ * Hard invariants (CLAUDE.md rule #1 — the signed canonical is frozen):
+ *  - `behavior` is ALWAYS summed from {@link TOKEN_BEHAVIOR_BITS} (T=16, S=8, C=4, E=2, G=1), never a
+ *    magic literal int.
+ *  - `morphisms` is REQUIRED on the wire (presence required, emptiness meaningful) — emit `{}` when empty,
+ *    NEVER omit it.
+ *  - `supply` is REQUIRED — emit `{}` when there is no supply authority, never omit it.
+ *  - Absent optionals are OMITTED, never emitted as `null`/`undefined` (the chain signs over
+ *    `JCS(dropNulls(payload))`).
+ *
+ * @see src/ottochain/types.ts — CreateAssetPolicy, SupplyPolicy, MorphismSpec, MorphismKind, TOKEN_BEHAVIOR_BITS
+ */
+import { TOKEN_BEHAVIOR_BITS, } from '../ottochain/types.js';
+/** The default mint/burn guard the riverdale presets use: an always-true predicate `{"==":[1,1]}`. */
+const alwaysTrue = () => ({ '==': [1, 1] });
+/** A `PUBLIC`-visibility morphism spec (the riverdale preset visibility). Fresh object per call. */
+const publicMorphism = () => ({ visibility: 'PUBLIC' });
+/** Sum behavior bits from their NAMES — never a magic literal int (CLAUDE.md #1). */
+export function sumBehavior(bits) {
+    return bits.reduce((acc, name) => acc + TOKEN_BEHAVIOR_BITS[name], 0);
+}
+/**
+ * Derive the default `stateShape.typeName`: strip a trailing `.asset` label, PascalCase the remainder
+ * (splitting on `.`/`-`/`_`/space), then append `State`.
+ *   `rvd.asset` → `RvdState`, `goods.asset` → `GoodsState`, `capped.asset` → `CappedState`.
+ */
+export function defaultStateTypeName(name) {
+    const ASSET_SUFFIX = '.asset';
+    const base = name.endsWith(ASSET_SUFFIX) ? name.slice(0, -ASSET_SUFFIX.length) : name;
+    const pascal = base
+        .split(/[.\-_\s]+/)
+        .filter(Boolean)
+        .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1))
+        .join('');
+    return `${pascal}State`;
+}
+/** Build a {@link SupplyPolicy}, OMITTING every absent field (no `undefined`/`null` keys). */
+function buildSupply(opts) {
+    const supply = {};
+    if (opts.maxSupply !== undefined)
+        supply.maxSupply = opts.maxSupply;
+    if (opts.mintPolicy !== undefined)
+        supply.mintPolicy = opts.mintPolicy;
+    if (opts.burnPolicy !== undefined)
+        supply.burnPolicy = opts.burnPolicy;
+    if (opts.decimals !== undefined)
+        supply.decimals = opts.decimals;
+    return supply;
+}
+/** Assemble the final {@link CreateAssetPolicy}, attaching `metadata` only when present. */
+function assemble(args) {
+    const stateShape = {
+        typeName: args.stateTypeName ?? defaultStateTypeName(args.name),
+        fields: [],
+    };
+    const policy = {
+        name: args.name,
+        version: args.version,
+        behavior: args.behavior,
+        supply: args.supply,
+        morphisms: args.morphisms,
+        stateShape,
+    };
+    if (args.metadata !== undefined)
+        policy.metadata = args.metadata;
+    return policy;
+}
+/**
+ * Fungible currency. Behavior `T|S|C = 28` (transferable + splittable + combinable). Standard morphism
+ * set TRANSFER + FRACTIONALIZE + STAKE (`stakeable`, default true) + BURN (when `burnable`), all PUBLIC.
+ *
+ * Reproduces `riverdale-economy/rvd-policy.json` exactly via
+ * `fungiblePolicy({ name: 'rvd.asset', version: '1.0.0', mintable: true, burnable: true })`.
+ */
+export function fungiblePolicy(p) {
+    const behavior = sumBehavior(['transferable', 'splittable', 'combinable']); // 28
+    const morphisms = {
+        TRANSFER: publicMorphism(),
+        FRACTIONALIZE: publicMorphism(),
+    };
+    if (p.stakeable !== false)
+        morphisms.STAKE = publicMorphism();
+    if (p.burnable)
+        morphisms.BURN = publicMorphism();
+    let mintPolicy;
+    if (p.mintGuard !== undefined)
+        mintPolicy = p.mintGuard;
+    else if (p.mintable)
+        mintPolicy = alwaysTrue();
+    const supply = buildSupply({
+        maxSupply: p.maxSupply,
+        mintPolicy,
+        burnPolicy: p.burnable ? alwaysTrue() : undefined,
+        decimals: p.decimals,
+    });
+    return assemble({
+        name: p.name,
+        version: p.version,
+        behavior,
+        supply,
+        morphisms,
+        stateTypeName: p.stateTypeName,
+        metadata: p.metadata,
+    });
+}
+/**
+ * Non-fungible token. Behavior `T = 16`, or `T|C = 20` with `combinable: true` (the riverdale
+ * `goods.asset`); `transferable: false` drops the T bit (a bound collectible). `morphisms` is `{}` by
+ * default (emitted explicitly, never omitted). Mintable by default ⇒ `supply.mintPolicy = {"==":[1,1]}`.
+ *
+ * Reproduces `riverdale-economy/goods-policy.json` exactly via
+ * `nftPolicy({ name: 'goods.asset', version: '1.0.0', combinable: true })`.
+ */
+export function nftPolicy(p) {
+    const bits = [];
+    if (p.transferable !== false)
+        bits.push('transferable');
+    if (p.combinable)
+        bits.push('combinable');
+    const behavior = sumBehavior(bits);
+    let mintPolicy;
+    if (p.mintGuard !== undefined)
+        mintPolicy = p.mintGuard;
+    else if (p.mintable !== false)
+        mintPolicy = alwaysTrue();
+    const supply = buildSupply({ maxSupply: p.maxSupply, mintPolicy });
+    return assemble({
+        name: p.name,
+        version: p.version,
+        behavior,
+        supply,
+        morphisms: {},
+        stateTypeName: p.stateTypeName,
+        metadata: p.metadata,
+    });
+}
+/**
+ * Soulbound token: non-transferable, governable only (`G = 1`; `+E = 3` when `expirable`). No TRANSFER
+ * morphism (`morphisms: {}`); minting is closed after issue (empty `supply`).
+ */
+export function soulboundPolicy(p) {
+    const bits = ['governable'];
+    if (p.expirable)
+        bits.push('expirable');
+    const behavior = sumBehavior(bits);
+    return assemble({
+        name: p.name,
+        version: p.version,
+        behavior,
+        supply: buildSupply({}), // mint closed after issue
+        morphisms: {}, // non-transferable: no TRANSFER morphism
+        stateTypeName: p.stateTypeName,
+        metadata: p.metadata,
+    });
+}
+/**
+ * Escape hatch: declare `behavior` by NAME (summed from {@link TOKEN_BEHAVIOR_BITS}, never a magic int)
+ * and pass `supply` + `morphisms` through raw. Use when no preset fits.
+ *
+ * Reproduces `riverdale-economy/capped-policy.json` exactly via
+ * `customPolicy({ name: 'capped.asset', version: '1.0.0',
+ *                 behavior: ['transferable', 'splittable', 'combinable'],
+ *                 supply: { maxSupply: 100, mintPolicy: { '==': [1, 1] } }, morphisms: {} })`.
+ */
+export function customPolicy(p) {
+    return assemble({
+        name: p.name,
+        version: p.version,
+        behavior: sumBehavior(p.behavior),
+        supply: p.supply,
+        morphisms: p.morphisms,
+        stateTypeName: p.stateTypeName,
+        metadata: p.metadata,
+    });
+}

package/dist/esm/templates/index.js

@@ -0,0 +1,41 @@
+/**
+ * `@ottochain/sdk/templates` — the fiber & asset authoring template catalog.
+ *
+ * Typed builders that emit the EXACT canonical wire shapes app authors otherwise hand-roll as raw
+ * JSON-Logic (asset policies, versioned machines, effect directives, migrations, seeded state). Every
+ * builder is additive and pure — it returns the same wire shape the chain re-derives, so a template
+ * output signs to byte-identical `JCS(dropNulls(payload))` (CLAUDE.md rule #1). Hand-rolled JSON keeps
+ * working; these just make the recurring shapes typed, named, and mistake-resistant.
+ *
+ * Origin: the fiber-ergonomics program (ottochain `docs/proposals/fiber-ergonomics/`), Phase A — the
+ * `riverdale-economy` e2e is the migration proof (each preset reproduces its checked-in golden JSON).
+ *
+ * @example
+ * import {
+ *   fungiblePolicy, machine, transition, effect, guard,
+ *   transferAsset, triggers, spawn, seedState, seedFields,
+ * } from '@ottochain/sdk/templates';
+ */
+// ─── 1.1 Asset-policy presets ────────────────────────────────────────────────
+// fungiblePolicy / nftPolicy / soulboundPolicy / customPolicy (+ sumBehavior, defaultStateTypeName,
+// BehaviorBitName) — emit a `CreateAssetPolicy`; behavior is summed from TOKEN_BEHAVIOR_BITS, never a literal.
+export * from './asset-policy.js';
+// ─── 1.2 Versioned-machine skeleton + transition()/effect() ──────────────────
+// machine / transition / effect (+ TransitionSpec, MachineSpec, Machine, …). The skeleton owns ONE
+// canonical wire definition, so publish + create cannot drift (verified binding, F9).
+export * from './machine.js';
+// ─── 1.4 Migration helpers ───────────────────────────────────────────────────
+// seedFields / migration — hides the bare-state-root ({"var":""}) foot-gun.
+export * from './migration.js';
+// ─── 1.5 State-shape-with-defaults ───────────────────────────────────────────
+// seedState / declaredFields / StateShape — auto-seed accumulators so no field reads null (F5).
+export * from './state-shape.js';
+// ─── 1.3 Effect-directive builders ───────────────────────────────────────────
+// transferAsset / triggers / spawn / emit / toFiber / toWallet / addDependency / setDependencyActive /
+// RESERVED_EFFECT_KEYS — a typo'd directive is a TS error, not a silent state field (F4).
+export * from '../schema/effects.js';
+// ─── Authorization-guard builders (namespace) ────────────────────────────────
+// `guard.signerIsParty('state.borrower')` reads as intent at the call site.
+export * as guard from '../schema/guards.js';
+// ─── Existing machine/policy primitives re-surfaced for one-import authoring ──
+export { defineFiberApp, toProtoDefinition, constrained, unconstrained, immutable, projectFiberPolicy, } from '../schema/fiber-app.js';

package/dist/esm/templates/machine.js

@@ -0,0 +1,125 @@
+/**
+ * Versioned-machine skeleton + `transition()` / `effect()` composition (handoff §1.2).
+ *
+ * Two moves:
+ *   1. `transition()` / `effect()` build the wire `Transition` + its flat effect map from typed
+ *      fragments instead of a hand-rolled JSON blob.
+ *   2. `machine()` is a versioned-package SKELETON that OWNS exactly ONE canonical wire definition
+ *      (`toProtoDefinition(app)`, computed once) and hands the SAME object to BOTH `publishVersion()`
+ *      and `create()`. That is the verified-binding invariant (F9): because publish and create cannot
+ *      drift, the chain's `definition.computeDigest` equals the registered `logicHash` and the bind
+ *      admits the fiber. The skeleton REUSES `toProtoDefinition` (the one canonicalization path) — it
+ *      never re-derives the wire shape.
+ *
+ * Guardrail (CLAUDE.md #1): every builder here is a pure function emitting the exact wire shape the
+ * chain re-derives. Absent optionals (`metadata`/`participants`/`parentFiberId`/`migration`) are
+ * OMITTED, never `null`; required-no-default fields (`strict` on publish, `dependencies: []` per
+ * transition) are ALWAYS present.
+ */
+import { toProtoDefinition, } from '../schema/fiber-app.js';
+/**
+ * Build a wire {@link Transition} from a typed spec.
+ *
+ *   - `on` → `eventName` (the wire key);
+ *   - `guard` defaults to `{ "==": [1, 1] }`;
+ *   - `dependencies` defaults to `[]` and is ALWAYS present;
+ *   - `effect` is passed through (build it with {@link effect}).
+ *
+ * @example
+ * ```ts
+ * transition({
+ *   from: 'debt_current', to: 'debt_current', on: 'buy',
+ *   effect: effect(
+ *     { status: 'debt_current', purchaseCount: { '+': [{ var: 'state.purchaseCount' }, 1] } },
+ *     triggers([...]), transferAsset([...]),
+ *   ),
+ * });
+ * ```
+ */
+export function transition(t) {
+    return {
+        from: t.from,
+        to: t.to,
+        eventName: t.on,
+        guard: t.guard ?? { '==': [1, 1] },
+        effect: t.effect,
+        dependencies: t.dependencies ?? [],
+    };
+}
+// =============================================================================
+// effect()
+// =============================================================================
+/**
+ * Compose an effect into ONE FLAT map: the state-update fields PLUS any `_`-directive fragments,
+ * all in a single object (`Object.assign({}, stateUpdate, ...directives)`).
+ *
+ * Riverdale effects are flat maps that mix `_`-reserved directives (`_triggers`, `_transferAsset`,
+ * `_spawn`, …) with plain state-update fields — they are NOT `merge`-wrapped. Each directive fragment
+ * is a `Record` (e.g. the output of `transferAsset(...)` / `triggers(...)`), spread in here. Later
+ * fragments override earlier keys (`Object.assign` semantics).
+ *
+ * @example
+ * ```ts
+ * effect(
+ *   { status: 'debt_current', purchaseCount: { '+': [{ var: 'state.purchaseCount' }, 1] } },
+ *   { _triggers: [...] },
+ *   transferAsset([{ assetId: { var: 'event.payAssetId' }, recipient: toFiber({ var: 'event.retailerId' }) }]),
+ * );
+ * // => { status, purchaseCount, _triggers, _transferAsset }
+ * ```
+ */
+export function effect(stateUpdate, ...directives) {
+    return Object.assign({}, stateUpdate, ...directives);
+}
+/** A pinned-Exact `SchemaRef` for `name@version`. Wire: `{ name, version: { Exact: { version } } }`. */
+function exactRef(name, version) {
+    return { name, version: { Exact: { version } } };
+}
+/**
+ * Build a versioned-machine skeleton that binds publish + create to ONE canonical definition.
+ *
+ * The definition is projected ONCE here (`toProtoDefinition(spec.app)`) and the SAME reference is handed
+ * to `wireDefinition()`, `publishVersion().definition`, `create().definition`, and
+ * `upgradeFrom().newDefinition` — so they cannot drift and the chain's verified binding admits the fiber
+ * (F9). REUSES `toProtoDefinition` (the single canonicalization path); never re-derives the wire shape.
+ */
+export function machine(spec) {
+    // Project the canonical wire definition ONCE; every consumer reuses this exact reference.
+    const wireDef = toProtoDefinition(spec.app);
+    return {
+        wireDefinition() {
+            return wireDef;
+        },
+        publishVersion(o) {
+            return {
+                name: spec.name,
+                version: spec.version,
+                // REQUIRED-no-default on the wire; '' is valid empty base64 when no descriptor set is bound.
+                schemaB64: o?.schemaB64 ?? '',
+                machineShape: spec.schemaShape,
+                definition: wireDef, // SAME reference as wireDefinition()/create()
+                strict: o?.strict ?? false, // REQUIRED — never omitted
+                ...(o?.metadata ? { metadata: o.metadata } : {}), // OMIT when absent
+            };
+        },
+        create(o) {
+            return {
+                fiberId: o.fiberId,
+                definition: wireDef, // SAME reference as wireDefinition()/publishVersion()
+                initialData: o.initialData,
+                schemaRef: exactRef(spec.name, spec.version), // verified binding: name@version
+                ...(o.participants ? { participants: o.participants } : {}), // OMIT when absent
+                ...(o.parentFiberId ? { parentFiberId: o.parentFiberId } : {}), // OMIT when absent
+            };
+        },
+        upgradeFrom(o) {
+            return {
+                fiberId: o.fiberId,
+                targetRef: exactRef(spec.name, spec.version),
+                newDefinition: wireDef, // SAME reference — re-pin hashes to the same logicHash
+                targetSequenceNumber: o.targetSequenceNumber,
+                ...(o.migration !== undefined ? { migration: o.migration } : {}), // OMIT (Option) when absent
+            };
+        },
+    };
+}

package/dist/esm/templates/migration.js

@@ -0,0 +1,34 @@
+/**
+ * Migration builders — the `UpgradeFiber.migration` JSON-Logic transform applied on a version upgrade.
+ *
+ * THE FOOT-GUN (F9): a migration's evaluation root is the BARE prior state, not `state.x`.
+ * The chain evaluates the migration expression against `sm.stateData` directly
+ * (`MeteredEvaluator.eval(expr, sm.stateData, Migration)`, FiberEngine.scala:300), so:
+ *   - `{ var: '' }`            => the WHOLE prior state object
+ *   - `{ var: 'loyaltyPoints' }` => the top-level `loyaltyPoints` field
+ * This is UNLIKE an effect, where the root is the transition context and you read `{ var: 'state.x' }`.
+ * Writing `state.loyaltyPoints` in a migration silently reads `undefined`. These helpers hide that
+ * asymmetry by pinning the bare-state root for you.
+ *
+ * `migration` is `Option` on `UpgradeFiber` — when there is no transform, OMIT the key (never send `null`).
+ */
+/**
+ * Seed / overwrite top-level state fields on a version upgrade.
+ * Emits `{ merge: [{ var: '' }, fields] }` — merges `fields` onto the bare prior state, so existing
+ * fields are preserved and the named fields are added or overwritten.
+ *
+ * The `{ var: '' }` root is the BARE prior state (NOT `state.x` like an effect) — that asymmetry is
+ * exactly the F9 foot-gun this helper hides.
+ *
+ * @example seedFields({ loyaltyPoints: 0 }) // => { merge: [{ var: '' }, { loyaltyPoints: 0 }] }
+ */
+export const seedFields = (fields) => ({
+    merge: [{ var: '' }, fields],
+});
+/**
+ * General migration transform with the bare-state root made explicit. `build` receives `{ var: '' }`
+ * (the whole prior state) and returns the migration JSON-Logic.
+ *
+ * @example migration((s) => ({ merge: [s, { x: 1 }] })) // => { merge: [{ var: '' }, { x: 1 }] }
+ */
+export const migration = (build) => build({ var: '' });

package/dist/esm/templates/state-shape.js

@@ -0,0 +1,34 @@
+/**
+ * State-shape-with-defaults — the SDK half of Proposal 01's "declared state shape" (removes F5).
+ *
+ * A declared shape carries a `default` (and optional `type`) per field. It seeds `initialData` so every
+ * accumulator starts at a concrete value — a counter read via `{ '+': [{ var: 'state.x' }, ...] }` never
+ * resolves `null` because `x` was never written. It also yields the set of declared field names for
+ * Proposal 01's var-path checks.
+ */
+/**
+ * Build `initialData` by overlaying `overrides` onto each field's declared `default`.
+ * Every declared field gets a concrete value, so no field reads `null` at runtime. An override for a
+ * field replaces that field's default; overrides for undeclared fields are ignored (only declared fields
+ * are emitted). Determinism: pure function of its inputs, stable key order (declared order).
+ *
+ * @example seedState({ fields: { purchaseCount: { default: 0 }, status: { default: 'ACTIVE' } } })
+ *          // => { purchaseCount: 0, status: 'ACTIVE' }
+ */
+export function seedState(shape, overrides) {
+    const seeded = {};
+    for (const [name, field] of Object.entries(shape.fields)) {
+        seeded[name] =
+            overrides !== undefined && Object.prototype.hasOwnProperty.call(overrides, name)
+                ? overrides[name]
+                : field.default;
+    }
+    return seeded;
+}
+/**
+ * The set of declared state-field names — the fields the effects may read.
+ * Feeds Proposal 01's var-path checks (a `{ var: 'state.foo' }` whose `foo` is not declared is suspect).
+ */
+export function declaredFields(shape) {
+    return new Set(Object.keys(shape.fields));
+}

package/dist/esm/validation.js

@@ -23,9 +23,7 @@ const hexString = (length) => {
 /**
  * Schema for a DAG address
  */
-export const DagAddressSchema = z
-    .string()
-    .regex(/^DAG[0-9][a-zA-Z0-9]{36}$/, 'Must be a valid DAG address');
+export const DagAddressSchema = z.string().regex(/^DAG[0-9][a-zA-Z0-9]{36}$/, 'Must be a valid DAG address');
 // ============================================================================
 // Core Type Schemas
 // ============================================================================

package/dist/esm/verify.js

@@ -4,10 +4,16 @@
  * The package embeds `mode: "standard"|"dataUpdate"` in signed objects and
  * its verify() ignores the `isDataUpdate` parameter when `mode` is present.
  * This wrapper strips `mode` so callers' explicit `isDataUpdate` always wins.
+ *
+ * In dataUpdate mode, verification happens over the null-dropped canonical
+ * bytes (drop null object fields, preserve array nulls, then RFC 8785) —
+ * mirroring the SDK's dataUpdate signers and metakit's content-hash rule.
  */
 import { verify as _verify } from '@constellation-network/metagraph-sdk';
+import { dropNulls } from './ottochain/drop-nulls.js';
 export function verify(signed, isDataUpdate) {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const { mode, ...rest } = signed;
-    return _verify(rest, isDataUpdate);
+    const isDU = isDataUpdate ?? mode === 'dataUpdate';
+    const target = isDU ? { ...rest, value: dropNulls(signed.value) } : rest;
+    return _verify(target, isDU);
 }

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);