@utxopia/sdk 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/client.js

@@ -25,6 +25,7 @@ import { setupKeysFromWallet, setupKeysFromSeed, setupKeysFromAuthSignature, rec
 import { scanUnifiedNotesMulti, scanAnnouncementsViewOnlyMulti, computeNullifierHashForNote, computeNullifierBytes, isDepositForViewerHex, createDepositFromConfig, createTweakDeposit, depositViewingNode, createStealthOutputWithKeys, } from "./stealth";
 import { selectUtxos } from "./psbt";
 import { hexToBytes } from "./crypto";
+import { getAddressEncoder } from "@solana/kit";
 import { EventClient } from "./event-client";
 // ─── Client ─────────────────────────────────────────────────────────
 let _instance = null;
@@ -183,25 +184,17 @@ export class UTXOpiaClient {
         const cached = this._tokenIdCache.get(mintAddress);
         if (cached !== undefined)
             return cached;
-        // Requires PublicKey — import dynamically to avoid hard dep
-        const mintBytes = hexToBytes(mintAddress.padStart(64, "0"));
-        // If it's a base58 address, convert via PublicKey
-        let bytes;
-        try {
-            // Try as raw hex first (64 chars)
-            if (mintAddress.length === 64 && /^[0-9a-fA-F]+$/.test(mintAddress)) {
-                bytes = hexToBytes(mintAddress);
-            }
-            else {
-                // Assume base58 PublicKey — need to decode
-                // Use the SDK's reduceToField which handles the conversion
-                const { PublicKey } = require("@solana/web3.js");
-                bytes = new PublicKey(mintAddress).toBytes();
-            }
-        }
-        catch {
-            bytes = mintBytes;
-        }
+        // 64 hex chars is a raw token id; anything else is a base58 mint.
+        //
+        // Decoded with getAddressEncoder, the same path pda.ts uses, because
+        // require("@solana/web3.js") is not callable from an ESM browser bundle —
+        // it threw for every base58 mint, and the hex fallback behind it threw
+        // again on the same input. There is no fallback now: both branches are
+        // total for their input, and a malformed mint should raise, not be padded
+        // into a different token's id.
+        const bytes = mintAddress.length === 64 && /^[0-9a-fA-F]+$/.test(mintAddress)
+            ? hexToBytes(mintAddress)
+            : new Uint8Array(getAddressEncoder().encode(mintAddress));
         const tokenId = computeTokenId(bytes);
         this._tokenIdCache.set(mintAddress, tokenId);
         return tokenId;

package/dist/config.js

@@ -175,8 +175,11 @@ export const MAINNET_CONFIG = {
     // Bitcoin Network
     bitcoinNetwork: "mainnet",
     esploraUrl: "https://mempool.space/api",
-    // Circuit CDN
-    circuitCdnUrl: "https://circuit.utxopia.com",
+    // Circuit CDN. Must carry the full versioned path: `resolveCircuitPath` turns a bare host
+    // into `<host>/circuits/groth16`, which is a DIFFERENT, stale build that still serves 200s
+    // for every shape with a different delta. Proofs built from it verify locally and are
+    // rejected on chain as "proof invalid".
+    circuitCdnUrl: "https://circuit.utxopia.com/circuits/v2/groth16",
     // Groth16 Verifier (placeholder)
     groth16VerifierProgramId: address("11111111111111111111111111111111"),
     // VK Hashes (placeholder - update when deployed)

package/dist/index.d.ts

@@ -54,7 +54,7 @@ export { createFetchConnectionAdapter, createConnectionAdapterFromWeb3, createCo
 export { resolveSnsName, resolveStealthName, parseSnsStealthData, isSnsStealthAddress, isAuditorDisclosable, SnsComplianceFlags, SNS_COMPLIANCE_AUDITOR_OFFSET, SNS_COMPLIANCE_AUDITOR_BYTES, deriveParentDomainKey, SNS_STEALTH_DATA_SIZE, type SnsStealthAddress, } from "./sns-resolver";
 export { COMMITMENT_TREE_DISCRIMINATOR, parseCommitmentTreeData, isValidRoot, fetchCommitmentTree, getCommitmentIndex, saveCommitmentIndex, CommitmentTreeIndex, buildCommitmentTreeFromChain, fetchLeafIndexForCommitment, fetchMerkleProofForCommitment, getMerkleProofFromTree, type CommitmentTreeState, type RpcClient, type OnChainMerkleProof, } from "./commitment-tree";
 export { INSTRUCTION_DISCRIMINATORS, buildShieldInstructionData, buildShieldInstruction, type ShieldInstructionOptions, buildApproveRedemptionSigningInstructionData, buildApproveRedemptionSigningInstruction, buildCancelRedemptionInstructionData, buildCancelRedemptionInstruction, type CancelRedemptionInstructionOptions, bigintTo32Bytes, bytes32ToBigint, buildTransactInstructionData, buildTransactInstruction, buildRedeemInstructionData, buildUnshieldInstructionData, buildUnshieldInstruction, buildProposePoolUpdateInstructionData, buildProposePoolUpdateInstruction, buildExecutePoolUpdateInstructionData, buildExecutePoolUpdateInstruction, buildCancelPoolUpdateInstructionData, buildCancelPoolUpdateInstruction, buildRotateTreeInstructionData, buildRotateTreeInstruction, type RotateTreeOptions, buildMagicBlockDelegateInstructionData, buildMagicBlockDelegateInstruction, buildMagicBlockCommitInstructionData, buildMagicBlockCommitInstruction, buildMagicBlockPerPermissionInstructionData, buildMagicBlockPerPermissionInstruction, buildPolicyRequestHash, buildPolicyIntentParts, buildRegisterExitDestinationInstruction, buildRegisterExitDestinationInstructionData, MAX_POLICY_INTENT_PARTS, buildInitializePolicyApprovalInstructionData, buildInitializePolicyApprovalInstruction, buildPolicyApprovalDecisionInstruction, buildPolicyApprovalCommitInstruction, buildCompleteDepositPermissionedInstructionData, buildCompleteDepositPermissionedInstruction, buildShieldPermissionedInstructionData, buildShieldPermissionedInstruction, buildRotateAuditorInstructionData, buildRotateAuditorInstruction, type MagicBlockDelegateTarget, type MagicBlockDelegateInstructionOptions, type MagicBlockCommitInstructionOptions, type MagicBlockPerPermissionOperation, type MagicBlockPerPermissionMember, type MagicBlockPerPermissionInstructionOptions, type PolicyApprovalDecision, type InitializePolicyApprovalOptions, type CompleteDepositPermissionedOptions, type ShieldPermissionedInstructionOptions, type RotateAuditorOptions, buildVerifyTransactionInstructionData, buildCompleteDepositInstructionData, buildVerifyDepositInstructionData, buildVerifyDepositPermissionedInstructionData, buildSetPoolConfigInstructionData, parsePoolConfig, type ParsedPoolConfig, POOL_CONFIG_DISCRIMINATOR, POOL_CONFIG_LEN, POOL_SCRIPT_MAX_LEN, type Instruction, type ApproveRedemptionSigningInstructionOptions, type TransactInstructionOptions, type UnshieldInstructionOptions, type ProposePoolUpdateOptions, type ExecutePoolUpdateOptions, type CancelPoolUpdateOptions, } from "./instructions";
-export { VK_REGISTRY_DISCRIMINATOR, VK_REGISTRY_LEN, MAX_IC_POINTS, MAX_SAFE_JOINSPLIT_SIZE, INIT_VK_REGISTRY_DISCRIMINATOR, UPDATE_VK_REGISTRY_DISCRIMINATOR, joinSplitNumPublicInputs, computeVkHash, vkeyJsonToVkMaterial, buildVkRegistryData, parseVkRegistry, assertVkRegistryForShape, isVkRegistryReady, type JoinSplitVkMaterial, type SnarkjsVkeyJson, type ParsedVkRegistry, } from "./vk-registry";
+export { VK_REGISTRY_DISCRIMINATOR, VK_REGISTRY_LEN, MAX_IC_POINTS, MAX_SAFE_JOINSPLIT_SIZE, INIT_VK_REGISTRY_DISCRIMINATOR, UPDATE_VK_REGISTRY_DISCRIMINATOR, joinSplitNumPublicInputs, computeVkHash, vkeyJsonToVkMaterial, buildVkRegistryData, parseVkRegistry, assertVkRegistryForShape, assertVkeyMatchesRegistry, isVkRegistryReady, type JoinSplitVkMaterial, type SnarkjsVkeyJson, type ParsedVkRegistry, } from "./vk-registry";
 export { fetchExplorerDeposits, fetchExplorerTransfers, fetchExplorerRedemptions, parseNullifierRecord, parseRedemptionRequest, NULLIFIER_RECORD_SIZE, REDEMPTION_REQUEST_SIZE, NULLIFIER_RECORD_DISCRIMINATOR, REDEMPTION_REQUEST_DISCRIMINATOR, OPERATION_TYPE_LABELS, type ExplorerDeposit, type ExplorerTransferEvent, type ExplorerRedemption, type IndexerLeaf, } from "./explorer";
 export { parseProgramEvents, parseNullifierSpentEvent, parseStealthAnnouncementEvent, parseSenderMemoEvent, parseBtcOriginAttestationEvent, parseAuditorCiphertextEvent, EVENT_NULLIFIER_SPENT, EVENT_STEALTH_ANNOUNCEMENT, EVENT_NULLIFIERS_BATCH, EVENT_ANNOUNCEMENTS_BATCH, EVENT_SENDER_MEMO, EVENT_BTC_ORIGIN_ATTESTATION, EVENT_AUDITOR_CIPHERTEXT, type NullifierSpentEvent, type StealthAnnouncementEvent, type SenderMemoEvent, type BtcOriginAttestationEvent, type AuditorCiphertextEvent, type ProgramEvent, } from "./events";
 export { AnnouncementClient, type AnnouncementClientConfig, type AnnouncementListener, } from "./announcement-client";

package/dist/index.js

@@ -187,7 +187,7 @@ buildSetPoolConfigInstructionData, parsePoolConfig, POOL_CONFIG_DISCRIMINATOR, P
 // ==========================================================================
 // VK Registry (JoinSplit Groth16 on-chain verification keys)
 // ==========================================================================
-export { VK_REGISTRY_DISCRIMINATOR, VK_REGISTRY_LEN, MAX_IC_POINTS, MAX_SAFE_JOINSPLIT_SIZE, INIT_VK_REGISTRY_DISCRIMINATOR, UPDATE_VK_REGISTRY_DISCRIMINATOR, joinSplitNumPublicInputs, computeVkHash, vkeyJsonToVkMaterial, buildVkRegistryData, parseVkRegistry, assertVkRegistryForShape, isVkRegistryReady, } from "./vk-registry";
+export { VK_REGISTRY_DISCRIMINATOR, VK_REGISTRY_LEN, MAX_IC_POINTS, MAX_SAFE_JOINSPLIT_SIZE, INIT_VK_REGISTRY_DISCRIMINATOR, UPDATE_VK_REGISTRY_DISCRIMINATOR, joinSplitNumPublicInputs, computeVkHash, vkeyJsonToVkMaterial, buildVkRegistryData, parseVkRegistry, assertVkRegistryForShape, assertVkeyMatchesRegistry, isVkRegistryReady, } from "./vk-registry";
 // ==========================================================================
 // ChadBuffer Relay
 // ==========================================================================

package/dist/prover/web.d.ts

@@ -19,6 +19,14 @@ export interface ProofData {
     verificationKey?: Uint8Array;
 }
 export type CircuitType = `joinsplit_${number}x${number}`;
+/**
+ * Fetch a circuit's `*.vkey.json` from the same base path its zkey comes from.
+ *
+ * Deliberately reads `circuitBasePath` rather than taking a URL: the point of the check this
+ * feeds (`assertVkeyMatchesRegistry`) is that the vkey describes the artifacts actually being
+ * proved with, and a caller-supplied URL could describe a different build entirely.
+ */
+export declare function fetchCircuitVkey(circuitType: CircuitType): Promise<unknown>;
 /**
  * Set the base path for circuit artifacts
  */

package/dist/prover/web.js

@@ -41,6 +41,26 @@ const isBrowser = typeof window !== "undefined";
 const isNode = typeof process !== "undefined" && process.versions?.node;
 // Configurable circuit paths
 let circuitBasePath = isBrowser ? "/circuits/groth16" : "./circuits";
+/**
+ * Fetch a circuit's `*.vkey.json` from the same base path its zkey comes from.
+ *
+ * Deliberately reads `circuitBasePath` rather than taking a URL: the point of the check this
+ * feeds (`assertVkeyMatchesRegistry`) is that the vkey describes the artifacts actually being
+ * proved with, and a caller-supplied URL could describe a different build entirely.
+ */
+export async function fetchCircuitVkey(circuitType) {
+    const cached = vkeyCache.get(circuitType);
+    if (cached)
+        return cached;
+    const url = `${circuitBasePath}/${circuitType}/${circuitType}.vkey.json`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Could not fetch circuit vkey ${url}: ${res.status} ${res.statusText}`);
+    }
+    const vkey = await res.json();
+    vkeyCache.set(circuitType, vkey);
+    return vkey;
+}
 /**
  * Set the base path for circuit artifacts
  */
@@ -49,12 +69,14 @@ export function setCircuitPath(path) {
         return;
     circuitBasePath = path;
     circuitCache.clear();
+    vkeyCache.clear();
     artifactBytesCache.clear();
     artifactDownloadCache.clear();
 }
 // Lazy-loaded snarkjs module
 let snarkjs = null;
 const circuitCache = new Map();
+const vkeyCache = new Map();
 let proverInitialized = false;
 /**
  * Load snarkjs module

package/dist/vk-registry.d.ts

@@ -98,3 +98,24 @@ export declare function parseVkRegistry(data: Uint8Array): ParsedVkRegistry;
 export declare function assertVkRegistryForShape(data: Uint8Array | null | undefined, nInputs: number, nOutputs: number): ParsedVkRegistry;
 /** True if `data` is an initialized `VkRegistry` for the given shape. */
 export declare function isVkRegistryReady(data: Uint8Array | null | undefined, nInputs: number, nOutputs: number): boolean;
+/**
+ * Assert the circuit artifacts this client loaded correspond to the verifying key the chain
+ * will check against.
+ *
+ * `assertVkRegistryForShape` proves the registry exists and names the right shape;
+ * `setCircuitArtifactDigests` proves the artifacts are the bytes this build expects. Neither
+ * ties the two together, and that gap is a real one: a zkey from a different phase-2 setup
+ * proves fine, downloads fine, passes every integrity check, and is then rejected on chain as
+ * "proof invalid" — with nothing pointing at the version mismatch.
+ *
+ * It is not hypothetical. `https://circuit.utxopia.com/circuits/groth16` and
+ * `.../circuits/v2/groth16` both serve 200s for every shape, with different `delta` — same
+ * ceremony, different per-circuit setup. Both therefore satisfy the program's own vk_hash
+ * recomputation, which binds delta+IC to the compiled-in alpha/beta/gamma and so catches a
+ * foreign ceremony but NOT a stale phase-2 from the right one. This is the check that does.
+ *
+ * @param vkey          The `*.vkey.json` fetched from the SAME base path as the zkey. Fetching
+ *                      it from anywhere else makes this assertion meaningless.
+ * @param registryData  Raw `VkRegistry` account data for the shape.
+ */
+export declare function assertVkeyMatchesRegistry(vkey: SnarkjsVkeyJson, registryData: Uint8Array | null | undefined, nInputs: number, nOutputs: number): void;

package/dist/vk-registry.js

@@ -210,3 +210,42 @@ export function isVkRegistryReady(data, nInputs, nOutputs) {
         return false;
     }
 }
+/**
+ * Assert the circuit artifacts this client loaded correspond to the verifying key the chain
+ * will check against.
+ *
+ * `assertVkRegistryForShape` proves the registry exists and names the right shape;
+ * `setCircuitArtifactDigests` proves the artifacts are the bytes this build expects. Neither
+ * ties the two together, and that gap is a real one: a zkey from a different phase-2 setup
+ * proves fine, downloads fine, passes every integrity check, and is then rejected on chain as
+ * "proof invalid" — with nothing pointing at the version mismatch.
+ *
+ * It is not hypothetical. `https://circuit.utxopia.com/circuits/groth16` and
+ * `.../circuits/v2/groth16` both serve 200s for every shape, with different `delta` — same
+ * ceremony, different per-circuit setup. Both therefore satisfy the program's own vk_hash
+ * recomputation, which binds delta+IC to the compiled-in alpha/beta/gamma and so catches a
+ * foreign ceremony but NOT a stale phase-2 from the right one. This is the check that does.
+ *
+ * @param vkey          The `*.vkey.json` fetched from the SAME base path as the zkey. Fetching
+ *                      it from anywhere else makes this assertion meaningless.
+ * @param registryData  Raw `VkRegistry` account data for the shape.
+ */
+export function assertVkeyMatchesRegistry(vkey, registryData, nInputs, nOutputs) {
+    const registry = assertVkRegistryForShape(registryData, nInputs, nOutputs);
+    const expectedIc = joinSplitNumPublicInputs(nInputs, nOutputs) + 1;
+    if (vkey.IC.length !== expectedIc) {
+        throw new Error(`Circuit vkey for JoinSplit ${nInputs}x${nOutputs} has ${vkey.IC.length} IC points, ` +
+            `expected ${expectedIc} — the artifacts are for a different shape.`);
+    }
+    const local = computeVkHash(vkey);
+    if (!local.every((b, i) => b === registry.vkHash[i])) {
+        throw new Error(`Circuit artifacts for JoinSplit ${nInputs}x${nOutputs} do not match the on-chain ` +
+            `verifying key (artifact vkHash ${bytesToHex(local)}, registry ${bytesToHex(registry.vkHash)}). ` +
+            `A proof built from these would be rejected as invalid. Usually the circuit base URL ` +
+            `points at a stale build — check it resolves to the same version the registry was ` +
+            `registered from.`);
+    }
+}
+function bytesToHex(b) {
+    return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utxopia/sdk",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "description": "UTXOpia SDK - Private Bitcoin across Solana and Sui",
   "type": "module",
   "main": "dist/index.js",

package/src/client.ts

@@ -55,6 +55,7 @@ import {
 } from "./stealth";
 import { selectUtxos, type UtxoDescriptor } from "./psbt";
 import { hexToBytes, bytesToHex, bigintToBytes } from "./crypto";
+import { getAddressEncoder, type Address } from "@solana/kit";
 import { EventClient } from "./event-client";
 import { type DepositOpReturnContext, type BitcoinNetwork } from "./taproot";
 
@@ -269,23 +270,18 @@ export class UTXOpiaClient {
     const cached = this._tokenIdCache.get(mintAddress);
     if (cached !== undefined) return cached;
 
-    // Requires PublicKey — import dynamically to avoid hard dep
-    const mintBytes = hexToBytes(mintAddress.padStart(64, "0"));
-    // If it's a base58 address, convert via PublicKey
-    let bytes: Uint8Array;
-    try {
-      // Try as raw hex first (64 chars)
-      if (mintAddress.length === 64 && /^[0-9a-fA-F]+$/.test(mintAddress)) {
-        bytes = hexToBytes(mintAddress);
-      } else {
-        // Assume base58 PublicKey — need to decode
-        // Use the SDK's reduceToField which handles the conversion
-        const { PublicKey } = require("@solana/web3.js");
-        bytes = new PublicKey(mintAddress).toBytes();
-      }
-    } catch {
-      bytes = mintBytes;
-    }
+    // 64 hex chars is a raw token id; anything else is a base58 mint.
+    //
+    // Decoded with getAddressEncoder, the same path pda.ts uses, because
+    // require("@solana/web3.js") is not callable from an ESM browser bundle —
+    // it threw for every base58 mint, and the hex fallback behind it threw
+    // again on the same input. There is no fallback now: both branches are
+    // total for their input, and a malformed mint should raise, not be padded
+    // into a different token's id.
+    const bytes =
+      mintAddress.length === 64 && /^[0-9a-fA-F]+$/.test(mintAddress)
+        ? hexToBytes(mintAddress)
+        : new Uint8Array(getAddressEncoder().encode(mintAddress as Address));
 
     const tokenId = computeTokenId(bytes);
     this._tokenIdCache.set(mintAddress, tokenId);

package/src/config.ts

@@ -358,8 +358,11 @@ export const MAINNET_CONFIG: NetworkConfig = {
   bitcoinNetwork: "mainnet",
   esploraUrl: "https://mempool.space/api",
 
-  // Circuit CDN
-  circuitCdnUrl: "https://circuit.utxopia.com",
+  // Circuit CDN. Must carry the full versioned path: `resolveCircuitPath` turns a bare host
+  // into `<host>/circuits/groth16`, which is a DIFFERENT, stale build that still serves 200s
+  // for every shape with a different delta. Proofs built from it verify locally and are
+  // rejected on chain as "proof invalid".
+  circuitCdnUrl: "https://circuit.utxopia.com/circuits/v2/groth16",
 
   // Groth16 Verifier (placeholder)
   groth16VerifierProgramId: address("11111111111111111111111111111111"),

package/src/index.ts

@@ -807,6 +807,7 @@ export {
   buildVkRegistryData,
   parseVkRegistry,
   assertVkRegistryForShape,
+  assertVkeyMatchesRegistry,
   isVkRegistryReady,
   type JoinSplitVkMaterial,
   type SnarkjsVkeyJson,

package/src/prover/web.ts

@@ -67,6 +67,27 @@ const isNode = typeof process !== "undefined" && process.versions?.node;
 // Configurable circuit paths
 let circuitBasePath = isBrowser ? "/circuits/groth16" : "./circuits";
 
+/**
+ * Fetch a circuit's `*.vkey.json` from the same base path its zkey comes from.
+ *
+ * Deliberately reads `circuitBasePath` rather than taking a URL: the point of the check this
+ * feeds (`assertVkeyMatchesRegistry`) is that the vkey describes the artifacts actually being
+ * proved with, and a caller-supplied URL could describe a different build entirely.
+ */
+export async function fetchCircuitVkey(circuitType: CircuitType): Promise<unknown> {
+  const cached = vkeyCache.get(circuitType);
+  if (cached) return cached;
+
+  const url = `${circuitBasePath}/${circuitType}/${circuitType}.vkey.json`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Could not fetch circuit vkey ${url}: ${res.status} ${res.statusText}`);
+  }
+  const vkey = await res.json();
+  vkeyCache.set(circuitType, vkey);
+  return vkey;
+}
+
 /**
  * Set the base path for circuit artifacts
  */
@@ -74,6 +95,7 @@ export function setCircuitPath(path: string): void {
   if (path === circuitBasePath) return;
   circuitBasePath = path;
   circuitCache.clear();
+  vkeyCache.clear();
   artifactBytesCache.clear();
   artifactDownloadCache.clear();
 }
@@ -87,6 +109,7 @@ interface CircuitArtifact {
 }
 
 const circuitCache = new Map<CircuitType, CircuitArtifact>();
+const vkeyCache = new Map<CircuitType, unknown>();
 let proverInitialized = false;
 
 /**

package/src/vk-registry.ts

@@ -293,3 +293,55 @@ export function isVkRegistryReady(
     return false;
   }
 }
+
+/**
+ * Assert the circuit artifacts this client loaded correspond to the verifying key the chain
+ * will check against.
+ *
+ * `assertVkRegistryForShape` proves the registry exists and names the right shape;
+ * `setCircuitArtifactDigests` proves the artifacts are the bytes this build expects. Neither
+ * ties the two together, and that gap is a real one: a zkey from a different phase-2 setup
+ * proves fine, downloads fine, passes every integrity check, and is then rejected on chain as
+ * "proof invalid" — with nothing pointing at the version mismatch.
+ *
+ * It is not hypothetical. `https://circuit.utxopia.com/circuits/groth16` and
+ * `.../circuits/v2/groth16` both serve 200s for every shape, with different `delta` — same
+ * ceremony, different per-circuit setup. Both therefore satisfy the program's own vk_hash
+ * recomputation, which binds delta+IC to the compiled-in alpha/beta/gamma and so catches a
+ * foreign ceremony but NOT a stale phase-2 from the right one. This is the check that does.
+ *
+ * @param vkey          The `*.vkey.json` fetched from the SAME base path as the zkey. Fetching
+ *                      it from anywhere else makes this assertion meaningless.
+ * @param registryData  Raw `VkRegistry` account data for the shape.
+ */
+export function assertVkeyMatchesRegistry(
+  vkey: SnarkjsVkeyJson,
+  registryData: Uint8Array | null | undefined,
+  nInputs: number,
+  nOutputs: number,
+): void {
+  const registry = assertVkRegistryForShape(registryData, nInputs, nOutputs);
+
+  const expectedIc = joinSplitNumPublicInputs(nInputs, nOutputs) + 1;
+  if (vkey.IC.length !== expectedIc) {
+    throw new Error(
+      `Circuit vkey for JoinSplit ${nInputs}x${nOutputs} has ${vkey.IC.length} IC points, ` +
+        `expected ${expectedIc} — the artifacts are for a different shape.`,
+    );
+  }
+
+  const local = computeVkHash(vkey);
+  if (!local.every((b, i) => b === registry.vkHash[i])) {
+    throw new Error(
+      `Circuit artifacts for JoinSplit ${nInputs}x${nOutputs} do not match the on-chain ` +
+        `verifying key (artifact vkHash ${bytesToHex(local)}, registry ${bytesToHex(registry.vkHash)}). ` +
+        `A proof built from these would be rejected as invalid. Usually the circuit base URL ` +
+        `points at a stale build — check it resolves to the same version the registry was ` +
+        `registered from.`,
+    );
+  }
+}
+
+function bytesToHex(b: Uint8Array): string {
+  return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+}