@ottochain/sdk 2.3.0 → 2.5.0

package/dist/types/validation.d.ts

@@ -23,21 +23,10 @@ export declare const PublicKeySchema: z.ZodString;
  * Schema for a KeyPair
  */
 export declare const KeyPairSchema: z.ZodObject<{
-    /** Private key in hex format */
     privateKey: z.ZodString;
-    /** Public key in hex format (uncompressed, with 04 prefix) */
     publicKey: z.ZodString;
-    /** DAG address derived from the public key */
     address: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    address: string;
-    publicKey: string;
-    privateKey: string;
-}, {
-    address: string;
-    publicKey: string;
-    privateKey: string;
-}>;
+}, z.core.$strip>;
 /**
  * Type for a validated KeyPair
  */
@@ -46,17 +35,9 @@ export type ValidatedKeyPair = z.infer<typeof KeyPairSchema>;
  * Schema for a SignatureProof
  */
 export declare const SignatureProofSchema: z.ZodObject<{
-    /** Public key hex (uncompressed, without 04 prefix) - 128 characters */
     id: z.ZodString;
-    /** DER-encoded ECDSA signature in hex format */
     signature: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    id: string;
-    signature: string;
-}, {
-    id: string;
-    signature: string;
-}>;
+}, z.core.$strip>;
 /**
  * Type for a validated SignatureProof
  */
@@ -67,87 +48,17 @@ export type ValidatedSignatureProof = z.infer<typeof SignatureProofSchema>;
 export declare const SignedSchema: <T extends z.ZodTypeAny>(valueSchema: T) => z.ZodObject<{
     value: T;
     proofs: z.ZodArray<z.ZodObject<{
-        /** Public key hex (uncompressed, without 04 prefix) - 128 characters */
         id: z.ZodString;
-        /** DER-encoded ECDSA signature in hex format */
         signature: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        signature: string;
-    }, {
-        id: string;
-        signature: string;
-    }>, "many">;
-}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
-    value: T;
-    proofs: z.ZodArray<z.ZodObject<{
-        /** Public key hex (uncompressed, without 04 prefix) - 128 characters */
-        id: z.ZodString;
-        /** DER-encoded ECDSA signature in hex format */
-        signature: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        signature: string;
-    }, {
-        id: string;
-        signature: string;
-    }>, "many">;
-}>, any> extends infer T_1 ? { [k in keyof T_1]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
-    value: T;
-    proofs: z.ZodArray<z.ZodObject<{
-        /** Public key hex (uncompressed, without 04 prefix) - 128 characters */
-        id: z.ZodString;
-        /** DER-encoded ECDSA signature in hex format */
-        signature: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        signature: string;
-    }, {
-        id: string;
-        signature: string;
-    }>, "many">;
-}>, any>[k]; } : never, z.baseObjectInputType<{
-    value: T;
-    proofs: z.ZodArray<z.ZodObject<{
-        /** Public key hex (uncompressed, without 04 prefix) - 128 characters */
-        id: z.ZodString;
-        /** DER-encoded ECDSA signature in hex format */
-        signature: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        signature: string;
-    }, {
-        id: string;
-        signature: string;
-    }>, "many">;
-}> extends infer T_2 ? { [k_1 in keyof T_2]: z.baseObjectInputType<{
-    value: T;
-    proofs: z.ZodArray<z.ZodObject<{
-        /** Public key hex (uncompressed, without 04 prefix) - 128 characters */
-        id: z.ZodString;
-        /** DER-encoded ECDSA signature in hex format */
-        signature: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        signature: string;
-    }, {
-        id: string;
-        signature: string;
-    }>, "many">;
-}>[k_1]; } : never>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /**
  * Schema for TransactionReference
  */
 export declare const TransactionReferenceSchema: z.ZodObject<{
     ordinal: z.ZodNumber;
     hash: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    hash: string;
-    ordinal: number;
-}, {
-    hash: string;
-    ordinal: number;
-}>;
+}, z.core.$strip>;
 /**
  * Schema for CurrencyTransactionValue
  */
@@ -156,17 +67,7 @@ export declare const CurrencyTransactionValueSchema: z.ZodObject<{
     destination: z.ZodString;
     amount: z.ZodNumber;
     fee: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    amount: number;
-    destination: string;
-    source: string;
-    fee: number;
-}, {
-    amount: number;
-    destination: string;
-    source: string;
-    fee?: number | undefined;
-}>;
+}, z.core.$strip>;
 /**
  * Schema for CurrencyTransaction
  */
@@ -176,50 +77,12 @@ export declare const CurrencyTransactionSchema: z.ZodObject<{
         destination: z.ZodString;
         amount: z.ZodNumber;
         fee: z.ZodDefault<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        amount: number;
-        destination: string;
-        source: string;
-        fee: number;
-    }, {
-        amount: number;
-        destination: string;
-        source: string;
-        fee?: number | undefined;
-    }>;
+    }, z.core.$strip>;
     parent: z.ZodObject<{
         ordinal: z.ZodNumber;
         hash: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        hash: string;
-        ordinal: number;
-    }, {
-        hash: string;
-        ordinal: number;
-    }>;
-}, "strip", z.ZodTypeAny, {
-    value: {
-        amount: number;
-        destination: string;
-        source: string;
-        fee: number;
-    };
-    parent: {
-        hash: string;
-        ordinal: number;
-    };
-}, {
-    value: {
-        amount: number;
-        destination: string;
-        source: string;
-        fee?: number | undefined;
-    };
-    parent: {
-        hash: string;
-        ordinal: number;
-    };
-}>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 /**
  * Type for a validated CurrencyTransaction
  */
@@ -232,17 +95,7 @@ export declare const TransferParamsSchema: z.ZodObject<{
     to: z.ZodString;
     amount: z.ZodNumber;
     fee: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-}, "strip", z.ZodTypeAny, {
-    from: string;
-    to: string;
-    amount: number;
-    fee: number;
-}, {
-    from: string;
-    to: string;
-    amount: number;
-    fee?: number | undefined;
-}>;
+}, z.core.$strip>;
 /**
  * Type for validated TransferParams
  */
@@ -251,21 +104,10 @@ export type ValidatedTransferParams = z.infer<typeof TransferParamsSchema>;
  * Schema for AgentIdentity registration
  */
 export declare const AgentIdentityRegistrationSchema: z.ZodObject<{
-    /** Public key in hex format */
     publicKey: z.ZodString;
-    /** Display name for the agent */
     displayName: z.ZodString;
-    /** Initial reputation (default: 10) */
     reputation: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-}, "strip", z.ZodTypeAny, {
-    reputation: number;
-    publicKey: string;
-    displayName: string;
-}, {
-    publicKey: string;
-    displayName: string;
-    reputation?: number | undefined;
-}>;
+}, z.core.$strip>;
 /**
  * Type for validated AgentIdentity registration
  */
@@ -274,21 +116,17 @@ export type ValidatedAgentIdentityRegistration = z.infer<typeof AgentIdentityReg
  * Schema for PlatformLink
  */
 export declare const PlatformLinkSchema: z.ZodObject<{
-    platform: z.ZodEnum<["DISCORD", "TELEGRAM", "TWITTER", "GITHUB", "CUSTOM"]>;
+    platform: z.ZodEnum<{
+        DISCORD: "DISCORD";
+        TELEGRAM: "TELEGRAM";
+        TWITTER: "TWITTER";
+        GITHUB: "GITHUB";
+        CUSTOM: "CUSTOM";
+    }>;
     platformUserId: z.ZodString;
     platformUsername: z.ZodString;
     verified: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, "strip", z.ZodTypeAny, {
-    platform: "DISCORD" | "TELEGRAM" | "TWITTER" | "GITHUB" | "CUSTOM";
-    platformUserId: string;
-    platformUsername: string;
-    verified: boolean;
-}, {
-    platform: "DISCORD" | "TELEGRAM" | "TWITTER" | "GITHUB" | "CUSTOM";
-    platformUserId: string;
-    platformUsername: string;
-    verified?: boolean | undefined;
-}>;
+}, z.core.$strip>;
 /**
  * Type for validated PlatformLink
  */
@@ -301,25 +139,11 @@ export declare const ContractTermsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>
  * Schema for ProposeContractRequest
  */
 export declare const ProposeContractRequestSchema: z.ZodObject<{
-    /** Proposer's DAG address */
     proposer: z.ZodString;
-    /** Counterparty's DAG address */
     counterparty: z.ZodString;
-    /** Contract terms */
     terms: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    /** Human-readable description */
     description: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    description: string;
-    proposer: string;
-    terms: Record<string, unknown>;
-    counterparty: string;
-}, {
-    description: string;
-    proposer: string;
-    terms: Record<string, unknown>;
-    counterparty: string;
-}>;
+}, z.core.$strip>;
 /**
  * Type for validated ProposeContractRequest
  */
@@ -328,17 +152,9 @@ export type ValidatedProposeContractRequest = z.infer<typeof ProposeContractRequ
  * Schema for AcceptContractRequest
  */
 export declare const AcceptContractRequestSchema: z.ZodObject<{
-    /** Contract ID to accept */
     contractId: z.ZodString;
-    /** Acceptor's DAG address */
     acceptor: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    contractId: string;
-    acceptor: string;
-}, {
-    contractId: string;
-    acceptor: string;
-}>;
+}, z.core.$strip>;
 /**
  * Type for validated AcceptContractRequest
  */
@@ -347,21 +163,10 @@ export type ValidatedAcceptContractRequest = z.infer<typeof AcceptContractReques
  * Schema for CompleteContractRequest
  */
 export declare const CompleteContractRequestSchema: z.ZodObject<{
-    /** Contract ID to complete */
     contractId: z.ZodString;
-    /** Completer's DAG address */
     completer: z.ZodString;
-    /** Proof of completion */
     proof: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    contractId: string;
-    completer: string;
-    proof: string;
-}, {
-    contractId: string;
-    completer: string;
-    proof: string;
-}>;
+}, z.core.$strip>;
 /**
  * Type for validated CompleteContractRequest
  */

package/dist/types/verify.d.ts

@@ -4,6 +4,10 @@
  * 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 type { Signed, VerificationResult } from '@constellation-network/metagraph-sdk';
 export declare function verify<T>(signed: Signed<T>, isDataUpdate?: boolean): VerificationResult;

package/dist/types/zk/commit.d.ts

@@ -0,0 +1,28 @@
+/** Lowercase `0x` 32-byte big-endian hex — the JLVM-opcode Fr encoding. */
+export type FrHex = `0x${string}`;
+/**
+ * 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 declare const R = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/** Reduce an arbitrary bigint into a canonical BN254 Fr element `[0, R)`. */
+export declare const toFr: (x: bigint) => bigint;
+/** Encode a field element as the lowercase `0x` 32-byte big-endian hex the crypto opcodes expect. */
+export declare const frToHex: (x: bigint) => FrHex;
+/** A fresh random salt as a canonical Fr (rejection-sampled to avoid modulo bias near R). */
+export declare function randomSalt(): bigint;
+/** `cm = Poseidon([...fields, salt])` via the VM's own opcode. Returns the `0x` 32-byte commitment. */
+export declare function poseidonCommitN(fields: bigint[], saltFr: bigint): FrHex;
+/** `cm = Poseidon([fieldFr, saltFr])` — the commitment for one value field (a bid, a score). */
+export declare function poseidonCommit(fieldFr: bigint, saltFr: bigint): FrHex;
+/** A client-held commitment + its opening. The opening is SECRET; only `cm` is published. */
+export interface Commitment {
+    /** The 32-byte commitment published on-chain. */
+    cm: FrHex;
+    /** The committed field values (client-held). */
+    fields: bigint[];
+    /** The blinding salt (client-held). */
+    salt: bigint;
+}
+/** Commit `fields` under a fresh (or supplied) salt; returns the commitment + opening. */
+export declare function openCommitment(fields: bigint[], salt?: bigint): Commitment;

package/dist/types/zk/guard.d.ts

@@ -0,0 +1,46 @@
+import { type DecodedPublicValues, type Groth16Bundle } from './types';
+/** Char offset of public-values word `w` (0=exprHash, 1=dataHash, 2=outputHash, 3=ok) in the `0x` string. */
+export declare const wordOffset: (w: number) => number;
+/** Options for {@link semiPrivateGuard} / {@link checkSemiPrivateBinding}. */
+export interface SemiPrivateGuardOptions {
+    /** Require the rule to have evaluated to `true` (`outputHash == keccak256("true")`). Default true. */
+    requireTrue?: boolean;
+}
+/**
+ * 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 declare function semiPrivateGuard(vkey: `0x${string}`, logicHash: `0x${string}`, opts?: SemiPrivateGuardOptions): Record<string, unknown>;
+/** The outcome of {@link verifyGroth16Bundle} + binding checks: `ok`, with `reasons` when it is not. */
+export interface BindingResult {
+    ok: boolean;
+    /** Empty when `ok`; otherwise one human-readable reason per failed check. */
+    reasons: string[];
+    decoded: DecodedPublicValues;
+}
+/**
+ * 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 declare function verifyGroth16Bundle(bundle: Groth16Bundle): boolean;
+/**
+ * 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 declare function checkSemiPrivateBinding(bundle: Groth16Bundle, expectedLogicHash: `0x${string}`, opts?: SemiPrivateGuardOptions): BindingResult;
+/**
+ * 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 declare function verifySemiPrivate(bundle: Groth16Bundle, expectedLogicHash: `0x${string}`, opts?: SemiPrivateGuardOptions): BindingResult;

package/dist/types/zk/index.d.ts

@@ -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 { type FrHex, R, toFr, frToHex, randomSalt, poseidonCommit, poseidonCommitN, type Commitment, openCommitment, } from './commit';
+export { type DecodedPublicValues, type Groth16Bundle, decodeJlvmPublicValues } from './types';
+export { type Groth16WitnessMap, type Groth16Witness, groth16Witness, type PmtWitnessMap, pmtWitness } from './witness';
+export { type RegisteredRule, ExprRegistry, type Comparator, boundRule, atLeast, atMost } from './registry';
+export { type SemiPrivateGuardOptions, wordOffset, semiPrivateGuard, type BindingResult, verifyGroth16Bundle, checkSemiPrivateBinding, verifySemiPrivate, } from './guard';
+export { type ZkProver, type Groth16ProveRequest, SubprocessProver, type SubprocessProverOptions, parseGroth16Stdout, } from './prover';

package/dist/types/zk/preimage.d.ts

@@ -0,0 +1,10 @@
+/** The single canonical string both the signer and the prover-feed share (JCS ∘ dropNullFields). */
+export declare function canonicalForSigning(x: unknown): string;
+/** keccak256 of the canonical bytes — the value the zk-jlvm guest commits as exprHash / dataHash. */
+export declare function proverPreimage(x: unknown): `0x${string}`;
+/** exprHash of a published JLVM rule (canonicalized + keccak'd). Equals the chain's `logicHash`. */
+export declare const exprHash: (rule: unknown) => `0x${string}`;
+/** dataHash of a private data context — kept private; only its hash is public. */
+export declare const dataHash: (data: unknown) => `0x${string}`;
+/** `keccak256(canonicalize(true))` — the `outputHash` a guard binds for a "rule returned true" proof. */
+export declare const KECCAK_TRUE: `0x${string}`;

package/dist/types/zk/prover.d.ts

@@ -0,0 +1,34 @@
+import type { Groth16Bundle } from './types';
+/** A request to prove that evaluating `expr` over `data` yields a result (raw JSON — canonicalized here). */
+export interface Groth16ProveRequest {
+    /** The JLVM rule (plain JSON). Canonicalized before it reaches the prover. */
+    expr: unknown;
+    /** The (private) data context (plain JSON). Canonicalized before it reaches the prover. */
+    data: unknown;
+}
+/** Produces SP1-Groth16 bundles for the semi-private tier. Swap implementations in tests. */
+export interface ZkProver {
+    proveGroth16(req: Groth16ProveRequest): Promise<Groth16Bundle>;
+}
+/** Configuration for {@link SubprocessProver}. Provide a binary OR a cargo manifest (binary wins). */
+export interface SubprocessProverOptions {
+    /** Path to a prebuilt zk-jlvm host binary. Defaults to `ZK_JLVM_BIN`. */
+    binaryPath?: string;
+    /** Path to the zk-jlvm `script` crate's `Cargo.toml` (run via `cargo run --release`). Defaults to `ZK_JLVM_MANIFEST`. */
+    cargoManifestPath?: string;
+    /** Extra environment for the child (e.g. `{ SP1_PROVER: 'cuda' }`). Merged over `process.env`. */
+    env?: Record<string, string>;
+    /** Working directory for the child process. */
+    cwd?: string;
+    /** Hard timeout in ms. Default 1_800_000 (30 min) — SP1 Groth16 wrapping is slow. */
+    timeoutMs?: number;
+}
+/** Parse the host's `vkey:` / `public values:` / `proof bytes:` stdout lines into a bundle. */
+export declare function parseGroth16Stdout(stdout: string): Groth16Bundle;
+/** Drives the zk-jlvm host out-of-process. */
+export declare class SubprocessProver implements ZkProver {
+    private readonly opts;
+    constructor(opts?: SubprocessProverOptions);
+    proveGroth16(req: Groth16ProveRequest): Promise<Groth16Bundle>;
+    private run;
+}

package/dist/types/zk/registry.d.ts

@@ -0,0 +1,34 @@
+/** A registered rule and the public `logicHash` that pins it on-chain and in proofs. */
+export interface RegisteredRule {
+    /** The JLVM rule, as plain JSON (canonicalized when hashed and when fed to the prover). */
+    rule: unknown;
+    /** `keccak256(canonicalize(rule))` — the on-chain `logicHash` and a proof's `exprHash` word. */
+    logicHash: `0x${string}`;
+}
+/** A client-side registry mapping rule names to their canonical `logicHash`. */
+export declare class ExprRegistry {
+    private readonly byName;
+    /** Register (or replace) a named rule; returns the entry with its computed `logicHash`. */
+    register(name: string, rule: unknown): RegisteredRule;
+    /** Whether a rule is registered under `name`. */
+    has(name: string): boolean;
+    /** The registered rule, or throw if unknown. */
+    ruleOf(name: string): unknown;
+    /** The registered rule's `logicHash`, or throw if unknown. */
+    logicHashOf(name: string): `0x${string}`;
+    /** All registered names, in insertion order. */
+    names(): string[];
+    private require;
+}
+/** The comparators a bound rule can pin a private value against. */
+export type Comparator = '>=' | '>' | '<=' | '<' | '==' | '!=';
+/**
+ * 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 declare function boundRule(varName: string, op: Comparator, bound: number | string): Record<string, unknown>;
+/** `{">=":[{"var":varName}, bound]}` — "the hidden `varName` is at least `bound`". */
+export declare const atLeast: (varName: string, bound: number | string) => Record<string, unknown>;
+/** `{"<=":[{"var":varName}, bound]}` — "the hidden `varName` is at most `bound`". */
+export declare const atMost: (varName: string, bound: number | string) => Record<string, unknown>;

package/dist/types/zk/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+/** The decoded zk-jlvm public values: the keccak triple + the ok bit. */
+export interface DecodedPublicValues {
+    /** keccak256(canonicalize(expr)) — pins WHICH JLVM rule ran (equals the registry logicHash). */
+    exprHash: `0x${string}`;
+    /** keccak256(canonicalize(data)) — the (private) data context's hash. */
+    dataHash: `0x${string}`;
+    /** keccak256(canonicalize(output)) — for a guarded "rule == true" proof, equals KECCAK_TRUE. */
+    outputHash: `0x${string}`;
+    /** Whether the JLVM evaluation succeeded (false ⇒ the guest aborted / errored). */
+    ok: boolean;
+}
+/** A produced SP1-Groth16 bundle from the zk-jlvm prover (`--mode groth16`). */
+export interface Groth16Bundle {
+    /** `abi_encode(JlvmPublicValues)` as a `0x` hex string. */
+    publicValues: `0x${string}`;
+    /** SP1 Groth16 proof bytes as a `0x` hex string. */
+    proof: `0x${string}`;
+    /** The program verification key (`bytes32`) as a `0x` hex string. */
+    vkey: `0x${string}`;
+}
+/**
+ * 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 declare function decodeJlvmPublicValues(pv: `0x${string}`): DecodedPublicValues;

package/dist/types/zk/witness.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Witness shapers: turn a produced proof bundle (or a Merkle inclusion path) into the exact
+ * `JsonLogicValue` map a holder carries on a signed op's `witness` field. The combiner injects that
+ * map under the `witness` context key, and the policy guard reads `witness.publicValues` /
+ * `witness.proof` (groth16) or `witness.leaf` / `witness.index` / `witness.siblings` (pmt) — the
+ * shapes are fixed by metakit's guard opcodes (see ottochain ZkGatedMorphismSuite).
+ */
+import type { FrHex } from './commit';
+import { type DecodedPublicValues, type Groth16Bundle } from './types';
+/** The on-op map a `groth16_verify` guard reads. The vkey is NOT here — it is a literal in the guard. */
+export interface Groth16WitnessMap {
+    /** `abi_encode(JlvmPublicValues)` as `0x` hex — the guard's `witness.publicValues`. */
+    publicValues: `0x${string}`;
+    /** SP1-Groth16 proof bytes as `0x` hex — the guard's `witness.proof`. */
+    proof: `0x${string}`;
+}
+/** A groth16 witness ready to attach to an op, plus its decoded public values for client binding. */
+export interface Groth16Witness {
+    /** Attach this to the op's `witness` field (it is a plain `JsonLogicValue` map). */
+    witness: Groth16WitnessMap;
+    /** The decoded `{exprHash, dataHash, outputHash, ok}` — inspect/bind BEFORE submitting. */
+    decoded: DecodedPublicValues;
+}
+/**
+ * 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 declare function groth16Witness(bundle: Groth16Bundle): Groth16Witness;
+/**
+ * The on-op map a `pmt_verify` guard reads. `siblings` is the authentication path in the order the
+ * `pmt_verify` opcode folds it (ROOT-FIRST / top-down, as produced by metakit's PoseidonMerkleTree);
+ * `index` is the leaf position. Pass values straight through from the tree builder — do not reorder.
+ */
+export interface PmtWitnessMap {
+    leaf: FrHex;
+    index: number;
+    siblings: FrHex[];
+}
+/** Shape a Poseidon-Merkle inclusion path into the on-op `pmt_verify` witness map. */
+export declare function pmtWitness(leaf: FrHex, index: number, siblings: FrHex[]): PmtWitnessMap;