@ottochain/sdk 2.3.0 → 2.4.0

package/dist/types/schema/guards.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Canonical authorization-guard builders — bind "who may act" to the CHAIN-VERIFIED signer of the op,
+ * never to an attacker-supplied payload field.
+ *
+ * The forgeable anti-pattern (security audit class F1): `{"===":[{"var":"event.agent"}, {"var":"state.party"}]}`.
+ * The fiber engine injects `event` as the RAW transition payload (ContextProvider: `EVENT -> payload`),
+ * so `event.agent` is whatever the submitter wrote — a different party's address forges authorization.
+ * The chain ALSO injects `proofs` = `[{address, id, signature}]` where `address = id.toAddress` (the
+ * VERIFIED signer addresses). Authorization must bind to THAT. For ASSET ops (mint/burn/morphism) the
+ * context has no `event`/`proofs`; it injects `signers` (an array of verified address strings) instead.
+ *
+ * Use these so the safe pattern is consistent, greppable, and impossible to get subtly wrong.
+ */
+/** A JSON-Logic guard expression (plain JSON). */
+export type GuardRule = Record<string, unknown>;
+/**
+ * FIBER-transition authorization: the pinned `partyVar` (a `state` path holding an address, e.g.
+ * `"state.borrower"`) MUST be among the op's verified signers (`proofs[].address`). The replay-safe
+ * replacement for `{"===":[{"var":"event.agent"}, {"var":partyVar}]}`.
+ */
+export declare const signerIsParty: (partyVar: string) => GuardRule;
+/** FIBER-transition authorization where ANY of the pinned parties signed (e.g. borrower OR lender). */
+export declare const signerIsAnyParty: (partyVars: string[]) => GuardRule;
+/**
+ * FIBER-transition authorization where the actor must be a MEMBER of a pinned set: at least one
+ * VERIFIED signer is in the `setVar` array (e.g. `"state.signers"`, `"state.members"`, `"state.oracles"`).
+ * The replay-safe replacement for `{"in":[{"var":"event.agent"}, {"var":setVar}]}`.
+ */
+export declare const signerInSet: (setVar: string) => GuardRule;
+/**
+ * FIBER-transition ANTI-SELF guard: NO verified signer is the pinned party (e.g. a proposal author may
+ * not vote on their own proposal). The replay-safe replacement for `{"!==":[{"var":"event.agent"}, {"var":partyVar}]}`.
+ */
+export declare const signerIsNotParty: (partyVar: string) => GuardRule;
+/**
+ * FIBER-transition authorization / dedup over a state MAP keyed by address: at least one VERIFIED signer
+ * is a key in `mapVar` (e.g. `"state.members"`, `"state.balances"`). The replay-safe replacement for the
+ * forgeable `{"getKey":[{"var":mapVar}, {"var":"event.agent"}]}` membership/presence check (note metakit
+ * has no `getKey`; use `get`/`has`). For a "no signer has acted yet" dedup, negate: `{"!":[signerHasEntry(...)]}`.
+ * For a per-actor VALUE threshold (e.g. balance >= N), build the `some` directly:
+ * `{"some":[{"map":[proofs,address]},{">=":[{"get":[mapVar,{"var":""}]}, N]}]}`.
+ */
+export declare const signerHasEntry: (mapVar: string) => GuardRule;
+/**
+ * ASSET-op authorization (mintPolicy / burnPolicy / MorphismSpec.guard): the address at `addressVar`
+ * (e.g. `"holder.Wallet.address"`) MUST be among the op's verified `signers`. The asset context has no
+ * `event` or `proofs` — it injects `signers` directly.
+ */
+export declare const assetSignerIs: (addressVar: string) => GuardRule;
+/**
+ * EFFECT-KEY BINDING: prove the event's claimed actor (`actorVar`, default `event.agent`) is a
+ * CHAIN-VERIFIED signer, so that field is SAFE to use as a dynamic map key / array element in the
+ * EFFECT (`{"set":[map,{"var":"event.agent"},v]}`, `{"cat":[arr,[{"var":"event.agent"}]]}`).
+ *
+ * This is the coupling clause for the map-write remediation: a guard may authorize via membership /
+ * balance / reputation, but if the EFFECT writes under `event.agent` WITHOUT this clause, an attacker
+ * sets `event.agent` to a victim's address and writes under the victim's key (security class S1).
+ * Pair it with the authorization check expressed on the SAME `actorVar` — together they prove the actor
+ * both signed and is authorized, and the effect can only write under that one verified key.
+ * Structurally identical to {@link signerIsParty}; named for intent + greppability at write sites.
+ */
+export declare const actorIsSigner: (actorVar?: string) => GuardRule;
+/**
+ * EFFECT-KEY-BINDING membership: the event's claimed actor (`actorVar`, default `event.agent`) is BOTH
+ * a CHAIN-VERIFIED signer AND a member of the pinned set `setVar` (e.g. `"state.signers"`,
+ * `"state.members"`). Use when the EFFECT writes a map/array keyed by that actor and authorization is
+ * set-membership. It proves the EXACT actor whose key is written both signed and is authorized — closing
+ * the S1 forge AND the subtler gap {@link signerInSet} leaves open: `signerInSet` only proves SOME
+ * verified signer is a member, so an op co-signed by an authorized signer could still write a DIFFERENT
+ * verified-but-unauthorized address as the key (padding a signature/vote tally). `actorInSet` pins both
+ * to the same `actorVar`.
+ */
+export declare const actorInSet: (setVar: string, actorVar?: string) => GuardRule;
+/**
+ * EFFECT-KEY-BINDING map membership: the claimed actor (`actorVar`, default `event.agent`) is BOTH a
+ * CHAIN-VERIFIED signer AND a key in the pinned state MAP `mapVar` (e.g. `"state.members"`,
+ * `"state.balances"`). The map analog of {@link actorInSet} — use it when the membership set is a dict
+ * keyed by address, where `in` does not apply and `has` checks key presence. Use when the EFFECT writes
+ * `mapVar` (or a per-actor tally) keyed by that actor: it proves the EXACT written key both signed and
+ * is an authorized member, closing the vote/signature-stuffing gap that bare {@link signerHasEntry}
+ * leaves open (which only proves SOME verified signer is a key, not that the written key is).
+ */
+export declare const actorHasEntry: (mapVar: string, actorVar?: string) => GuardRule;
+/**
+ * IDENTITY-REGISTRY reputation gate: at least one VERIFIED signer has a reputation in the registry map
+ * at `repMapVar` (a declared-dependency read, e.g. `"machines.<registryDep>.state.reputations"`, shaped
+ * `{ <address>: int }`) that is `>=` the bar read from `thresholdVar` (a state path, e.g.
+ * `"state.voteThreshold"`). A missing entry reads as null → 0 numerically, so unregistered signers
+ * fail-closed for any positive bar. The replay-safe replacement for the forgeable
+ * `{">=":[{"var":"event.agentReputation"}, bar]}` (security class S1). See
+ * docs/design/app-hardening-identity-integration.md §3–§4.1.
+ */
+export declare const signerHasReputation: (repMapVar: string, thresholdVar: string) => GuardRule;
+/**
+ * IDENTITY-REGISTRY role gate: at least one VERIFIED signer holds an active role attestation, i.e. is a
+ * key in the registry's flat per-role map at `roleMapVar` (a declared-dependency read, e.g.
+ * `"machines.<registryDep>.state.arbiters"` / `".slashers"` / `".issuers"` / `".boardMembers"`, each
+ * shaped `{ <address>: true }`). The replay-safe replacement for bare `event.judicialRuling` / role
+ * escapes and `{"==":[1,1]}` missing-auth (security class S2). Roles are FLAT per-role maps (not a
+ * nested `roles[addr][ROLE]`) because metakit `get`/`has` on a null inner map ERROR rather than
+ * returning null; a flat map keeps the read total + fail-closed. See app-hardening §4.2.
+ */
+export declare const signerHasRole: (roleMapVar: string) => GuardRule;
+/**
+ * DYNAMIC identity-registry reputation gate — for when the registry instance is bound at RUNTIME via the
+ * fiber-engine `_addDependency` directive (#24) rather than hardcoded into the `machines.<uuid>` path.
+ * `registryIdVar` is a state/event path holding the registry fiber id (e.g. `"state.registryId"`); the
+ * read addresses `machines[<that id>].state.reputations[<signer>]` with dynamic `get`s. Guarded by a
+ * presence check so an UNBOUND registry yields a clean `false` (fail-closed) instead of an evaluation
+ * error. REQUIRES the registry dependency to have been added in a PRIOR transition (`_addDependency`),
+ * because the `machines` context is built before the effect runs (two-phase: bind, then read).
+ */
+export declare const signerHasReputationVia: (registryIdVar: string, thresholdVar: string) => GuardRule;
+/**
+ * DYNAMIC identity-registry role gate — the runtime-bound (`_addDependency`, #24) counterpart of
+ * {@link signerHasRole}. `registryIdVar` is a state/event path holding the registry fiber id;
+ * `roleField` is the registry's flat per-role state map name (`"arbiters"` / `"slashers"` / `"issuers"` /
+ * `"boardMembers"` — see REGISTRY_ROLE_MAP). Reads `machines[<id>].state.<roleField>[<signer>]`, guarded
+ * by a presence check so an UNBOUND registry yields a clean `false`. Same two-phase requirement as
+ * {@link signerHasReputationVia}.
+ */
+export declare const signerHasRoleVia: (registryIdVar: string, roleField: string) => GuardRule;
+/**
+ * CROSS-FIBER STATE GATE — assert a RUNTIME-bound dependency fiber is in a required lifecycle state. The
+ * replay-safe replacement for the dropped object-form dependency
+ * `{machine, instanceRef, requiredState}` (which the chain silently drops — `requiredState` gating never
+ * happens). `refVar` is a state/event path holding the dependency's fiber id; reads
+ * `machines[<refVar>].currentStateId == requiredState`, guarded by a presence check so an UNBOUND
+ * dependency yields a clean `false` (fail-closed). TWO-PHASE (#24): the dependency fiber must have been
+ * bound by an `_addDependency` in a PRIOR transition (the `machines` context is built before the effect),
+ * so a single gated transition is split into a bind step then this assert step. See
+ * docs/design/app-hardening-identity-integration.md §5–§6.
+ */
+export declare const depInState: (refVar: string, requiredState: string) => GuardRule;

package/dist/types/signing.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+import type { SignatureProof, Signed, SigningOptions } from '@constellation-network/metagraph-sdk';
+/**
+ * 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).
+ */
+export declare function signDataUpdate<T>(data: T, privateKey: string): SignatureProof;
+/**
+ * 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).
+ */
+export declare function createSignedObject<T>(value: T, privateKey: string, options?: SigningOptions): Signed<T>;
+/**
+ * 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`.
+ */
+export declare function addSignature<T>(signed: Signed<T>, privateKey: string, options?: SigningOptions): Signed<T>;
+/**
+ * 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).
+ */
+export declare function batchSign<T>(value: T, privateKeys: string[], options?: SigningOptions): Signed<T>;

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