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

package/dist/client.js

@@ -183,8 +183,6 @@ 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 {
@@ -200,7 +198,9 @@ export class UTXOpiaClient {
             }
         }
         catch {
-            bytes = mintBytes;
+            // Lazy on purpose: a base58 mint padded to 64 is not hex, so computing
+            // this eagerly threw before the branch above ever ran.
+            bytes = hexToBytes(mintAddress.padStart(64, "0"));
         }
         const tokenId = computeTokenId(bytes);
         this._tokenIdCache.set(mintAddress, 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.6",
   "description": "UTXOpia SDK - Private Bitcoin across Solana and Sui",
   "type": "module",
   "main": "dist/index.js",

package/src/client.ts

@@ -269,8 +269,6 @@ 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 {
@@ -284,7 +282,9 @@ export class UTXOpiaClient {
         bytes = new PublicKey(mintAddress).toBytes();
       }
     } catch {
-      bytes = mintBytes;
+      // Lazy on purpose: a base58 mint padded to 64 is not hex, so computing
+      // this eagerly threw before the branch above ever ran.
+      bytes = hexToBytes(mintAddress.padStart(64, "0"));
     }
 
     const tokenId = computeTokenId(bytes);

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("");
+}