@ottochain/sdk 2.3.0 → 2.4.0

package/dist/cjs/signing.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * DataUpdate Signing Wrappers — dropNulls applied internally
+ *
+ * Metakit (>= 1.8) computes content hashes by recursively dropping
+ * null-valued OBJECT fields (array nulls are preserved) before RFC 8785
+ * canonicalization (`JsonBinaryCodec.dropNulls`). This makes
+ * `Option = None` indistinguishable from an absent field, so schema
+ * evolution never changes prior hashes.
+ *
+ * The upstream `@constellation-network/metagraph-sdk` signs over the
+ * payload as-is, so a payload containing explicit nulls would be signed
+ * over different bytes than the metagraph hashes — and the node rejects
+ * the signature (HTTP 400).
+ *
+ * These wrappers shadow the upstream dataUpdate signing surface and apply
+ * `dropNulls` internally, unconditionally. Standard-mode signing
+ * (currency transactions etc.) is passed through unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signDataUpdate = signDataUpdate;
+exports.createSignedObject = createSignedObject;
+exports.addSignature = addSignature;
+exports.batchSign = batchSign;
+const metagraph_sdk_1 = require("@constellation-network/metagraph-sdk");
+const drop_nulls_js_1 = require("./ottochain/drop-nulls.js");
+function resolveMode(options = {}) {
+    if (options.mode)
+        return options.mode;
+    if (options.isDataUpdate)
+        return 'dataUpdate';
+    return 'standard';
+}
+/**
+ * Sign data as a DataUpdate, hashing over null-dropped canonical bytes.
+ *
+ * Applies `dropNulls` internally so that explicit-null and absent optional
+ * fields produce identical signatures, matching metakit's content-hash rule
+ * (drop null object fields, preserve array nulls, then RFC 8785).
+ */
+function signDataUpdate(data, privateKey) {
+    return (0, metagraph_sdk_1.signDataUpdate)((0, drop_nulls_js_1.dropNulls)(data), privateKey);
+}
+/**
+ * Create a signed object. In `dataUpdate` mode the signature is computed
+ * over the null-dropped canonical bytes (the returned `value` is the
+ * caller's original payload, untouched).
+ */
+function createSignedObject(value, privateKey, options = {}) {
+    if (resolveMode(options) === 'dataUpdate') {
+        const signed = (0, metagraph_sdk_1.createSignedObject)((0, drop_nulls_js_1.dropNulls)(value), privateKey, options);
+        return { ...signed, value };
+    }
+    return (0, metagraph_sdk_1.createSignedObject)(value, privateKey, options);
+}
+/**
+ * Add an additional signature to an existing signed object. In
+ * `dataUpdate` mode the new signature is computed over the null-dropped
+ * canonical bytes of `signed.value`.
+ */
+function addSignature(signed, privateKey, options) {
+    const mode = options ? resolveMode(options) : (signed.mode ?? 'standard');
+    if (mode === 'dataUpdate') {
+        const result = (0, metagraph_sdk_1.addSignature)({ ...signed, value: (0, drop_nulls_js_1.dropNulls)(signed.value) }, privateKey, options);
+        return { ...result, value: signed.value };
+    }
+    return (0, metagraph_sdk_1.addSignature)(signed, privateKey, options);
+}
+/**
+ * Create a signed object with multiple signatures at once. In
+ * `dataUpdate` mode all signatures are computed over the null-dropped
+ * canonical bytes (the returned `value` is the caller's original payload).
+ */
+function batchSign(value, privateKeys, options = {}) {
+    if (resolveMode(options) === 'dataUpdate') {
+        const signed = (0, metagraph_sdk_1.batchSign)((0, drop_nulls_js_1.dropNulls)(value), privateKeys, options);
+        return { ...signed, value };
+    }
+    return (0, metagraph_sdk_1.batchSign)(value, privateKeys, options);
+}

package/dist/cjs/types.js

@@ -8,18 +8,17 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isValidFiberId = exports.isValidAddress = void 0;
+exports.isValidAddress = isValidAddress;
+exports.isValidFiberId = isValidFiberId;
 /**
  * Validate a DAG address format.
  */
 function isValidAddress(value) {
     return /^DAG[0-9a-zA-Z]+$/.test(value);
 }
-exports.isValidAddress = isValidAddress;
 /**
  * Validate a UUID format.
  */
 function isValidFiberId(value) {
     return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
 }
-exports.isValidFiberId = isValidFiberId;

package/dist/cjs/validation.js

@@ -7,7 +7,14 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assert = exports.safeParse = exports.validateKeyPair = exports.validateAddress = exports.validatePublicKey = exports.validatePrivateKey = exports.validate = exports.CompleteContractRequestSchema = exports.AcceptContractRequestSchema = exports.ProposeContractRequestSchema = exports.ContractTermsSchema = exports.PlatformLinkSchema = exports.AgentIdentityRegistrationSchema = exports.TransferParamsSchema = exports.CurrencyTransactionSchema = exports.CurrencyTransactionValueSchema = exports.TransactionReferenceSchema = exports.SignedSchema = exports.SignatureProofSchema = exports.KeyPairSchema = exports.PublicKeySchema = exports.PrivateKeySchema = exports.DagAddressSchema = void 0;
+exports.CompleteContractRequestSchema = exports.AcceptContractRequestSchema = exports.ProposeContractRequestSchema = exports.ContractTermsSchema = exports.PlatformLinkSchema = exports.AgentIdentityRegistrationSchema = exports.TransferParamsSchema = exports.CurrencyTransactionSchema = exports.CurrencyTransactionValueSchema = exports.TransactionReferenceSchema = exports.SignedSchema = exports.SignatureProofSchema = exports.KeyPairSchema = exports.PublicKeySchema = exports.PrivateKeySchema = exports.DagAddressSchema = void 0;
+exports.validate = validate;
+exports.validatePrivateKey = validatePrivateKey;
+exports.validatePublicKey = validatePublicKey;
+exports.validateAddress = validateAddress;
+exports.validateKeyPair = validateKeyPair;
+exports.safeParse = safeParse;
+exports.assert = assert;
 const zod_1 = require("zod");
 const errors_js_1 = require("./errors.js");
 // ============================================================================
@@ -209,7 +216,6 @@ function validate(schema, data, fieldName) {
     }
     return result.data;
 }
-exports.validate = validate;
 /**
  * Validate a private key
  *
@@ -220,7 +226,6 @@ exports.validate = validate;
 function validatePrivateKey(privateKey) {
     return validate(exports.PrivateKeySchema, privateKey, 'privateKey');
 }
-exports.validatePrivateKey = validatePrivateKey;
 /**
  * Validate a public key
  *
@@ -231,7 +236,6 @@ exports.validatePrivateKey = validatePrivateKey;
 function validatePublicKey(publicKey) {
     return validate(exports.PublicKeySchema, publicKey, 'publicKey');
 }
-exports.validatePublicKey = validatePublicKey;
 /**
  * Validate a DAG address
  *
@@ -242,7 +246,6 @@ exports.validatePublicKey = validatePublicKey;
 function validateAddress(address) {
     return validate(exports.DagAddressSchema, address, 'address');
 }
-exports.validateAddress = validateAddress;
 /**
  * Validate a KeyPair
  *
@@ -253,7 +256,6 @@ exports.validateAddress = validateAddress;
 function validateKeyPair(keyPair) {
     return validate(exports.KeyPairSchema, keyPair, 'keyPair');
 }
-exports.validateKeyPair = validateKeyPair;
 /**
  * Safe validation that returns a result object instead of throwing
  *
@@ -295,7 +297,6 @@ function safeParse(schema, data) {
         }),
     };
 }
-exports.safeParse = safeParse;
 /**
  * Assert that a condition is true, throwing ValidationError if not
  *
@@ -309,4 +310,3 @@ function assert(condition, message, field) {
         throw new errors_js_1.ValidationError(message, { field });
     }
 }
-exports.assert = assert;

package/dist/cjs/verify.js

@@ -5,13 +5,18 @@
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verify = void 0;
+exports.verify = verify;
 const metagraph_sdk_1 = require("@constellation-network/metagraph-sdk");
+const drop_nulls_js_1 = require("./ottochain/drop-nulls.js");
 function verify(signed, isDataUpdate) {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const { mode, ...rest } = signed;
-    return (0, metagraph_sdk_1.verify)(rest, isDataUpdate);
+    const isDU = isDataUpdate ?? mode === 'dataUpdate';
+    const target = isDU ? { ...rest, value: (0, drop_nulls_js_1.dropNulls)(signed.value) } : rest;
+    return (0, metagraph_sdk_1.verify)(target, isDU);
 }
-exports.verify = verify;

package/dist/cjs/zk/commit.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.frToHex = exports.toFr = exports.R = void 0;
+exports.randomSalt = randomSalt;
+exports.poseidonCommitN = poseidonCommitN;
+exports.poseidonCommit = poseidonCommit;
+exports.openCommitment = openCommitment;
+/**
+ * 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.)
+ */
+const metagraph_sdk_jlvm_1 = require("@constellation-network/metagraph-sdk-jlvm");
+const node_crypto_1 = require("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.
+ */
+exports.R = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/** Reduce an arbitrary bigint into a canonical BN254 Fr element `[0, R)`. */
+const toFr = (x) => ((x % exports.R) + exports.R) % exports.R;
+exports.toFr = toFr;
+/** Encode a field element as the lowercase `0x` 32-byte big-endian hex the crypto opcodes expect. */
+const frToHex = (x) => `0x${(0, exports.toFr)(x).toString(16).padStart(64, '0')}`;
+exports.frToHex = frToHex;
+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). */
+function randomSalt() {
+    for (;;) {
+        const v = bytesToBig((0, node_crypto_1.randomBytes)(32));
+        if (v < exports.R)
+            return v;
+    }
+}
+/** `cm = Poseidon([...fields, salt])` via the VM's own opcode. Returns the `0x` 32-byte commitment. */
+function poseidonCommitN(fields, saltFr) {
+    const inputs = [...fields.map(exports.frToHex), (0, exports.frToHex)(saltFr)];
+    // The bundled poseidon supports width t ≤ 5 (≤ 4 inputs incl. the salt); the opcode throws past it.
+    return metagraph_sdk_jlvm_1.jsonLogic.apply({ poseidon: inputs }, {});
+}
+/** `cm = Poseidon([fieldFr, saltFr])` — the commitment for one value field (a bid, a score). */
+function poseidonCommit(fieldFr, saltFr) {
+    return poseidonCommitN([fieldFr], saltFr);
+}
+/** Commit `fields` under a fresh (or supplied) salt; returns the commitment + opening. */
+function openCommitment(fields, salt = randomSalt()) {
+    return { cm: poseidonCommitN(fields, salt), fields, salt };
+}

package/dist/cjs/zk/guard.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wordOffset = void 0;
+exports.semiPrivateGuard = semiPrivateGuard;
+exports.verifyGroth16Bundle = verifyGroth16Bundle;
+exports.checkSemiPrivateBinding = checkSemiPrivateBinding;
+exports.verifySemiPrivate = verifySemiPrivate;
+/**
+ * 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.
+ */
+const metagraph_sdk_jlvm_1 = require("@constellation-network/metagraph-sdk-jlvm");
+const preimage_1 = require("./preimage");
+const types_1 = require("./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. */
+const wordOffset = (w) => HEX_PREFIX + WORD_HEX * w;
+exports.wordOffset = wordOffset;
+/** 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' }, (0, exports.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.
+ */
+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), preimage_1.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' }, (0, exports.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.
+ */
+function verifyGroth16Bundle(bundle) {
+    try {
+        return metagraph_sdk_jlvm_1.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}).
+ */
+function checkSemiPrivateBinding(bundle, expectedLogicHash, opts = {}) {
+    const { requireTrue = true } = opts;
+    const decoded = (0, types_1.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, preimage_1.KECCAK_TRUE))
+        reasons.push(`outputHash ${decoded.outputHash} != keccak256("true") ${preimage_1.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.
+ */
+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/cjs/zk/index.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGroth16Stdout = exports.SubprocessProver = exports.verifySemiPrivate = exports.checkSemiPrivateBinding = exports.verifyGroth16Bundle = exports.semiPrivateGuard = exports.wordOffset = exports.atMost = exports.atLeast = exports.boundRule = exports.ExprRegistry = exports.pmtWitness = exports.groth16Witness = exports.decodeJlvmPublicValues = exports.openCommitment = exports.poseidonCommitN = exports.poseidonCommit = exports.randomSalt = exports.frToHex = exports.toFr = exports.R = exports.KECCAK_TRUE = exports.dataHash = exports.exprHash = exports.proverPreimage = exports.canonicalForSigning = void 0;
+/**
+ * `@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.
+ */
+var preimage_1 = require("./preimage");
+Object.defineProperty(exports, "canonicalForSigning", { enumerable: true, get: function () { return preimage_1.canonicalForSigning; } });
+Object.defineProperty(exports, "proverPreimage", { enumerable: true, get: function () { return preimage_1.proverPreimage; } });
+Object.defineProperty(exports, "exprHash", { enumerable: true, get: function () { return preimage_1.exprHash; } });
+Object.defineProperty(exports, "dataHash", { enumerable: true, get: function () { return preimage_1.dataHash; } });
+Object.defineProperty(exports, "KECCAK_TRUE", { enumerable: true, get: function () { return preimage_1.KECCAK_TRUE; } });
+var commit_1 = require("./commit");
+Object.defineProperty(exports, "R", { enumerable: true, get: function () { return commit_1.R; } });
+Object.defineProperty(exports, "toFr", { enumerable: true, get: function () { return commit_1.toFr; } });
+Object.defineProperty(exports, "frToHex", { enumerable: true, get: function () { return commit_1.frToHex; } });
+Object.defineProperty(exports, "randomSalt", { enumerable: true, get: function () { return commit_1.randomSalt; } });
+Object.defineProperty(exports, "poseidonCommit", { enumerable: true, get: function () { return commit_1.poseidonCommit; } });
+Object.defineProperty(exports, "poseidonCommitN", { enumerable: true, get: function () { return commit_1.poseidonCommitN; } });
+Object.defineProperty(exports, "openCommitment", { enumerable: true, get: function () { return commit_1.openCommitment; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "decodeJlvmPublicValues", { enumerable: true, get: function () { return types_1.decodeJlvmPublicValues; } });
+var witness_1 = require("./witness");
+Object.defineProperty(exports, "groth16Witness", { enumerable: true, get: function () { return witness_1.groth16Witness; } });
+Object.defineProperty(exports, "pmtWitness", { enumerable: true, get: function () { return witness_1.pmtWitness; } });
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "ExprRegistry", { enumerable: true, get: function () { return registry_1.ExprRegistry; } });
+Object.defineProperty(exports, "boundRule", { enumerable: true, get: function () { return registry_1.boundRule; } });
+Object.defineProperty(exports, "atLeast", { enumerable: true, get: function () { return registry_1.atLeast; } });
+Object.defineProperty(exports, "atMost", { enumerable: true, get: function () { return registry_1.atMost; } });
+var guard_1 = require("./guard");
+Object.defineProperty(exports, "wordOffset", { enumerable: true, get: function () { return guard_1.wordOffset; } });
+Object.defineProperty(exports, "semiPrivateGuard", { enumerable: true, get: function () { return guard_1.semiPrivateGuard; } });
+Object.defineProperty(exports, "verifyGroth16Bundle", { enumerable: true, get: function () { return guard_1.verifyGroth16Bundle; } });
+Object.defineProperty(exports, "checkSemiPrivateBinding", { enumerable: true, get: function () { return guard_1.checkSemiPrivateBinding; } });
+Object.defineProperty(exports, "verifySemiPrivate", { enumerable: true, get: function () { return guard_1.verifySemiPrivate; } });
+var prover_1 = require("./prover");
+Object.defineProperty(exports, "SubprocessProver", { enumerable: true, get: function () { return prover_1.SubprocessProver; } });
+Object.defineProperty(exports, "parseGroth16Stdout", { enumerable: true, get: function () { return prover_1.parseGroth16Stdout; } });

package/dist/cjs/zk/preimage.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KECCAK_TRUE = exports.dataHash = exports.exprHash = void 0;
+exports.canonicalForSigning = canonicalForSigning;
+exports.proverPreimage = proverPreimage;
+/**
+ * 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.
+ */
+const metagraph_sdk_1 = require("@constellation-network/metagraph-sdk");
+const sha3_js_1 = require("@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). */
+function canonicalForSigning(x) {
+    return (0, metagraph_sdk_1.canonicalize)(x);
+}
+/** keccak256 of the canonical bytes — the value the zk-jlvm guest commits as exprHash / dataHash. */
+function proverPreimage(x) {
+    return `0x${toHex((0, sha3_js_1.keccak_256)(utf8(canonicalForSigning(x))))}`;
+}
+/** exprHash of a published JLVM rule (canonicalized + keccak'd). Equals the chain's `logicHash`. */
+const exprHash = (rule) => proverPreimage(rule);
+exports.exprHash = exprHash;
+/** dataHash of a private data context — kept private; only its hash is public. */
+const dataHash = (data) => proverPreimage(data);
+exports.dataHash = dataHash;
+/** `keccak256(canonicalize(true))` — the `outputHash` a guard binds for a "rule returned true" proof. */
+exports.KECCAK_TRUE = proverPreimage(true);

package/dist/cjs/zk/prover.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubprocessProver = void 0;
+exports.parseGroth16Stdout = parseGroth16Stdout;
+/**
+ * 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.
+ */
+const preimage_1 = require("./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. */
+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. */
+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 = (0, preimage_1.canonicalForSigning)(req.expr);
+        const data = (0, preimage_1.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()}`));
+            });
+        }));
+    }
+}
+exports.SubprocessProver = SubprocessProver;

package/dist/cjs/zk/registry.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.atMost = exports.atLeast = exports.ExprRegistry = void 0;
+exports.boundRule = boundRule;
+/**
+ * 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.
+ */
+const preimage_1 = require("./preimage");
+/** A client-side registry mapping rule names to their canonical `logicHash`. */
+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: (0, preimage_1.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;
+    }
+}
+exports.ExprRegistry = ExprRegistry;
+/**
+ * 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).
+ */
+function boundRule(varName, op, bound) {
+    return { [op]: [{ var: varName }, bound] };
+}
+/** `{">=":[{"var":varName}, bound]}` — "the hidden `varName` is at least `bound`". */
+const atLeast = (varName, bound) => boundRule(varName, '>=', bound);
+exports.atLeast = atLeast;
+/** `{"<=":[{"var":varName}, bound]}` — "the hidden `varName` is at most `bound`". */
+const atMost = (varName, bound) => boundRule(varName, '<=', bound);
+exports.atMost = atMost;

package/dist/cjs/zk/types.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeJlvmPublicValues = decodeJlvmPublicValues;
+/**
+ * Decode `abi_encode(JlvmPublicValues)`: four 32-byte words `[exprHash | dataHash | outputHash | ok]`.
+ * The bool is right-aligned in its word (final byte `0x00`/`0x01`).
+ */
+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/cjs/zk/witness.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groth16Witness = groth16Witness;
+exports.pmtWitness = pmtWitness;
+const types_1 = require("./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.
+ */
+function groth16Witness(bundle) {
+    return {
+        witness: { publicValues: bundle.publicValues, proof: bundle.proof },
+        decoded: (0, types_1.decodeJlvmPublicValues)(bundle.publicValues),
+    };
+}
+/** Shape a Poseidon-Merkle inclusion path into the on-op `pmt_verify` witness map. */
+function pmtWitness(leaf, index, siblings) {
+    return { leaf, index, siblings };
+}