@orbinum/sdk 0.10.0 → 0.12.0

package/dist/index.mjs

@@ -1020,11 +1020,27 @@ var EvmExplorer = class _EvmExplorer {
 };
 
 // src/indexer/IndexerClient.ts
+var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function normalizeBaseUrl(baseUrl) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new Error(`IndexerClient: invalid baseUrl ${JSON.stringify(baseUrl)}`);
+  }
+  const isLocal = LOCAL_HOSTS.has(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocal)) {
+    throw new Error(
+      `IndexerClient: baseUrl must use https:// (got ${url.protocol}//${url.hostname}). Plain http is only allowed for localhost.`
+    );
+  }
+  return baseUrl.replace(/\/$/, "");
+}
 var IndexerClient = class _IndexerClient {
   baseUrl;
   timeoutMs;
   constructor(config) {
-    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.baseUrl = normalizeBaseUrl(config.baseUrl);
     this.timeoutMs = config.timeoutMs ?? 1e4;
   }
   // ─── Internal helpers ──────────────────────────────────────────────────────
@@ -1082,7 +1098,7 @@ var IndexerClient = class _IndexerClient {
   /**
    * Returns a paginated list of stealth scan hints ordered ascending by leafIndex.
    * Each hint contains only the fields required for ECDH triage and decryption:
-   * leafIndex, commitmentHex, assetId, ephPkHex, encryptedMemo.
+   * leafIndex, commitmentHex, assetId, ephPkHex, encryptedMemo, circuitVersion.
    *
    * Use `sinceLeafIndex` for incremental scans (cursor = last seen leafIndex + 1).
    */
@@ -1502,8 +1518,8 @@ var BABYJUB_SUBORDER = 273603035897990940278080071815715938607681397215856725920
 // src/shielded-pool/protocol/memo.ts
 import { sha256 } from "@noble/hashes/sha2.js";
 var KEY_DOMAIN = new TextEncoder().encode("orbinum-note-encryption-v1");
-var MEMO_PLAINTEXT_SIZE = 116;
-function serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk) {
+var MEMO_PLAINTEXT_SIZE = 120;
+function serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk, circuitVersion) {
   const buf = new Uint8Array(MEMO_PLAINTEXT_SIZE);
   const view = new DataView(buf.buffer);
   view.setBigUint64(0, value & 0xffffffffffffffffn, true);
@@ -1512,6 +1528,7 @@ function serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk) {
   buf.set(blinding.slice(0, 32), 48);
   view.setUint32(80, assetId >>> 0, true);
   buf.set(counterpartyPk.slice(0, 32), 84);
+  view.setUint32(116, circuitVersion >>> 0, true);
   return buf;
 }
 function deriveEncryptionKey(sharedSecret, commitment) {
@@ -1524,7 +1541,7 @@ function deriveEncryptionKey(sharedSecret, commitment) {
 
 // src/shielded-pool/protocol/EncryptedMemo.ts
 var NONCE_SIZE = 12;
-var CIPHERTEXT_SIZE = 132;
+var CIPHERTEXT_SIZE = 136;
 var EPH_PK_SIZE = 32;
 var ENCRYPTED_MEMO_SIZE = NONCE_SIZE + CIPHERTEXT_SIZE + EPH_PK_SIZE;
 function bytesToBjjScalar(bytes) {
@@ -1543,14 +1560,15 @@ function parsePlaintext(nonce, ciphertextWithMac, encKey) {
     const blinding = bytesToBigintLE(plaintext.slice(48, 80));
     const assetId = BigInt(view.getUint32(80, true));
     const counterpartyPk = bytesToBigintLE(plaintext.slice(84, 116));
-    return { value, ownerPk, blinding, assetId, counterpartyPk };
+    const circuitVersion = view.getUint32(116, true);
+    return { value, ownerPk, blinding, assetId, counterpartyPk, circuitVersion };
   } catch {
     return null;
   }
 }
 var EncryptedMemo = {
   /**
-   * Build and encrypt a memo for a note using ECDH (v2, 168 bytes).
+   * Build and encrypt a memo for a note using ECDH (v2, 180 bytes).
    *
    * @param value              Note value in planck.
    * @param ownerPk            32-byte owner public key (LE).
@@ -1562,11 +1580,20 @@ var EncryptedMemo = {
    *                           decoded from a privacy address).
    *                           Pass `new Uint8Array(32)` (all zeros) for a publicly-readable memo.
    * @param counterpartyPk     32-byte counterparty BJJ Ax. Default: all zeros.
-   * @returns 168-byte encrypted memo: nonce(12) || ciphertext+MAC(124) || ephPk(32).
+   * @param circuitVersion     ZK circuit version the note is spent under. Default: 0.
+   * @param ephSkOverride      32-byte ephemeral secret key (stealth coordination). Optional.
+   * @returns 180-byte encrypted memo: nonce(12) || ciphertext+MAC(136) || ephPk(32).
    */
-  encrypt(value, ownerPk, blinding, assetId, commitment, recipientIvkPacked, counterpartyPk = new Uint8Array(32), ephSkOverride) {
+  encrypt(value, ownerPk, blinding, assetId, commitment, recipientIvkPacked, counterpartyPk = new Uint8Array(32), circuitVersion = 0, ephSkOverride) {
     const nonce = randomBytes(NONCE_SIZE);
-    const plaintext = serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk);
+    const plaintext = serializeMemo(
+      value,
+      ownerPk,
+      blinding,
+      assetId,
+      counterpartyPk,
+      circuitVersion
+    );
     const isZeroKey = recipientIvkPacked.every((b) => b === 0);
     let sharedSecret;
     let ephPkPackedBytes;
@@ -1597,29 +1624,31 @@ var EncryptedMemo = {
     return result;
   },
   /**
-   * Returns a 168-byte public memo encrypted with a zero viewing key.
+   * Returns a 180-byte public memo encrypted with a zero viewing key.
    * Decryptable by anyone with `decrypt(memo, commitment, new Uint8Array(32))`.
    * Convenience alias for `encrypt(..., new Uint8Array(32))`.
    */
-  encryptPublic(value, ownerPk, blinding, assetId, commitment) {
+  encryptPublic(value, ownerPk, blinding, assetId, commitment, circuitVersion = 0) {
     return EncryptedMemo.encrypt(
       value,
       ownerPk,
       blinding,
       assetId,
       commitment,
-      new Uint8Array(32)
+      new Uint8Array(32),
+      new Uint8Array(32),
+      circuitVersion
     );
   },
   /**
-   * Returns a 168-byte zeroed dummy memo (no information, always valid on-chain).
+   * Returns a 180-byte zeroed dummy memo (no information, always valid on-chain).
    */
   dummy() {
     return new Uint8Array(ENCRYPTED_MEMO_SIZE);
   },
   /**
    * Validates that `bytes` is a properly-sized encrypted memo.
-   * Throws an Error if the length is not ENCRYPTED_MEMO_SIZE (168 bytes).
+   * Throws an Error if the length is not ENCRYPTED_MEMO_SIZE (180 bytes).
    *
    * Call this at system boundaries (extrinsic builders, precompile encoders)
    * to catch malformed memos before they reach the chain and fail on-chain.
@@ -1640,7 +1669,7 @@ var EncryptedMemo = {
    * Returns null if decryption fails — wrong key, bad MAC, or malformed memo.
    * Never throws; safe for scan loops.
    *
-   * @param memoBytes        168-byte encrypted memo.
+   * @param memoBytes        180-byte encrypted memo.
    * @param commitment       32-byte note commitment (LE).
    * @param viewingSecretKey 32-byte HKDF viewing secret key from deriveViewingSecretKey().
    */
@@ -1652,13 +1681,13 @@ var EncryptedMemo = {
    * Extract the ECDH shared secret from an encrypted memo using the recipient's viewing secret key.
    *
    * Used by NoteDecryptor to obtain the shared secret needed for stealth address derivation
-   * without re-running the full decrypt path. Safe to call on any 168-byte memo.
+   * without re-running the full decrypt path. Safe to call on any 180-byte memo.
    *
    * Returns `new Uint8Array(32)` (all zeros) for public/dummy memos (zero ephPk).
    * Returns `null` if the memo is malformed or the ephPk is not a valid BJJ point.
    * Never throws; safe for scan loops.
    *
-   * @param memoBytes        168-byte encrypted memo.
+   * @param memoBytes        180-byte encrypted memo.
    * @param viewingSecretKey 32-byte HKDF viewing secret key from deriveViewingSecretKey().
    */
   extractSharedSecret(memoBytes, viewingSecretKey) {
@@ -1862,7 +1891,7 @@ var ShieldedPoolModule = class {
    * Withdraws tokens from the shielded pool to a public address.
    * Submits as an UNSIGNED (gasless) transaction — fee is embedded in the ZK proof.
    * Pass a `signer` to fall back to signed submission (e.g. for testing).
-   * Extrinsic: shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient, fee)
+   * Extrinsic: shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient, fee, changeCommitment, changeEncryptedMemo, relayer, circuitVersion)
    */
   async unshield(params, signer, txOptions) {
     const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "unshield");
@@ -1886,8 +1915,9 @@ var ShieldedPoolModule = class {
       fee: params.fee ?? 0n,
       change_commitment: changeCommitment,
       change_encrypted_memo: changeEncryptedMemo,
-      relayer: void 0
+      relayer: void 0,
       // Option<H160> — None for direct Substrate submissions
+      circuit_version: params.circuitVersion
     });
     if (signer) {
       return toTxResult(
@@ -1900,7 +1930,7 @@ var ShieldedPoolModule = class {
    * Performs a private (shielded) transfer between two notes.
    * Submits as an UNSIGNED (gasless) transaction — fee is embedded in the ZK proof.
    * Pass a `signer` to fall back to signed submission (e.g. for testing).
-   * Extrinsic: shieldedPool.privateTransfer(proof, merkleRoot, nullifiers, commitments, memos, assetId, fee)
+   * Extrinsic: shieldedPool.privateTransfer(proof, merkleRoot, nullifiers, commitments, memos, assetId, fee, relayer, circuitVersion)
    */
   async privateTransfer(params, signer, txOptions) {
     const nullifiers = params.inputs.map((inp) => inp.nullifier);
@@ -1921,8 +1951,9 @@ var ShieldedPoolModule = class {
       encrypted_memos: memos,
       asset_id: params.assetId,
       fee: params.fee ?? 0n,
-      relayer: void 0
+      relayer: void 0,
       // Option<H160> — None for direct Substrate submissions
+      circuit_version: params.circuitVersion
     });
     if (signer) {
       return toTxResult(
@@ -1956,7 +1987,7 @@ var ShieldedPoolModule = class {
    * This is a SIGNED transaction — the relayer must sign it with their wallet.
    * Before calling this, generate a ZK value proof with generateFeeClaimProof() (not yet implemented).
    *
-   * Extrinsic: shieldedPool.claim_shielded_fees(commitment, amount, asset_id, memo, proof, public_signals)
+   * Extrinsic: shieldedPool.claim_shielded_fees(commitment, amount, asset_id, memo, proof, public_signals, circuit_version)
    */
   async claimShieldedFees(params, signer, txOptions) {
     EncryptedMemo.validate(params.encryptedMemo, "claimShieldedFees.encryptedMemo");
@@ -1967,7 +1998,8 @@ var ShieldedPoolModule = class {
       asset_id: params.assetId,
       encrypted_memo: params.encryptedMemo,
       proof: params.proof,
-      public_signals: params.publicSignals
+      public_signals: params.publicSignals,
+      circuit_version: params.circuitVersion
     });
     return toTxResult(
       await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
@@ -2485,6 +2517,77 @@ var ZkVerifierModule = class {
   }
 };
 
+// src/shielded-pool/CircuitVersionResolver.ts
+import {
+  WebArtifactProvider,
+  circuitTypeToId
+} from "@orbinum/proof-generator";
+var CircuitVersionResolver = class {
+  constructor(zkVerifier, baseUrl, providerFactory) {
+    this.zkVerifier = zkVerifier;
+    this.makeProvider = providerFactory ?? ((circuit, noteVersion) => new WebArtifactProvider({
+      ...baseUrl ? { baseUrl } : {},
+      circuitVersions: { [circuit]: noteVersion }
+    }));
+  }
+  zkVerifier;
+  makeProvider;
+  /**
+   * Resolves the prover + on-chain version for spending a note of `circuit`
+   * created under `noteVersion`. Fail-closed: throws on unsupported version or
+   * VK-hash mismatch (CDN vs chain), before generating any proof.
+   */
+  async resolve(circuit, noteVersion) {
+    if (!Number.isInteger(noteVersion) || noteVersion <= 0) {
+      throw new Error(
+        `CircuitVersionResolver: invalid note circuitVersion ${noteVersion} for ${circuit}`
+      );
+    }
+    const provider = this.makeProvider(circuit, noteVersion);
+    const resolved = await provider.getResolvedVersion(circuit);
+    if (resolved.version !== noteVersion) {
+      throw new Error(
+        `CircuitVersionResolver: prover resolved ${circuit} to v${resolved.version}, expected v${noteVersion}`
+      );
+    }
+    const circuitId = circuitTypeToId(circuit);
+    const info = await this.zkVerifier.getCircuitVersionInfo(circuitId);
+    if (!info) {
+      throw new Error(
+        `CircuitVersionResolver: chain reports no version info for ${circuit} (id ${circuitId})`
+      );
+    }
+    if (!info.supportedVersions.includes(noteVersion)) {
+      throw new Error(
+        `CircuitVersionResolver: chain does not support ${circuit} v${noteVersion} (supported: ${info.supportedVersions.join(", ")})`
+      );
+    }
+    const chainVk = info.vkHashes.find((h) => h.version === noteVersion);
+    if (!chainVk) {
+      throw new Error(
+        `CircuitVersionResolver: chain has no VK hash for ${circuit} v${noteVersion}`
+      );
+    }
+    if (!vkHashEquals(chainVk.vkHash, resolved.vkHash)) {
+      throw new Error(
+        `CircuitVersionResolver: VK hash mismatch for ${circuit} v${noteVersion} \u2014 prover ${resolved.vkHash}, chain ${chainVk.vkHash}`
+      );
+    }
+    return { provider, version: noteVersion };
+  }
+};
+function vkHashEquals(a, b) {
+  const na = normalizeHash(a);
+  const nb = normalizeHash(b);
+  if (na === null || nb === null) return false;
+  return na === nb;
+}
+function normalizeHash(h) {
+  if (typeof h !== "string") return null;
+  const s = h.toLowerCase().startsWith("0x") ? h.toLowerCase().slice(2) : h.toLowerCase();
+  return /^[0-9a-f]{64}$/.test(s) ? s : null;
+}
+
 // src/relayer/RelayerStatusModule.ts
 var RelayerStatusModule = class {
   constructor(substrate) {
@@ -2730,12 +2833,12 @@ var AM_SEL = {
 var SP_SEL = {
   // shield(uint32,bytes32,bytes)                                               → 0x9feb22ea  (payable, amount = msg.value)
   SHIELD: new Uint8Array([159, 235, 34, 234]),
-  // privateTransfer(bytes,bytes32,bytes32[],bytes32[],bytes[],uint32,uint256)    → 0x8c0f5d24
-  PRIVATE_TRANSFER: new Uint8Array([140, 15, 93, 36]),
-  // unshield(bytes,bytes32,bytes32,uint32,uint256,bytes32,uint256,bytes32)               → 0xd21d9a79
-  UNSHIELD: new Uint8Array([210, 29, 154, 121]),
-  // claimShieldedFees(bytes32,uint256,uint32,bytes,bytes,bytes)                → 0x42e1e74c
-  CLAIM_SHIELDED_FEES: new Uint8Array([66, 225, 231, 76])
+  // privateTransfer(bytes,bytes32,bytes32[],bytes32[],bytes[],uint32,uint256,uint32)  → 0x66ed2cd4
+  PRIVATE_TRANSFER: new Uint8Array([102, 237, 44, 212]),
+  // unshield(bytes,bytes32,bytes32,uint32,uint256,bytes32,uint256,bytes32,bytes,uint32)  → 0x4e505348
+  UNSHIELD: new Uint8Array([78, 80, 83, 72]),
+  // claimShieldedFees(bytes32,uint256,uint32,bytes,bytes,bytes,uint32)         → 0x88d9deba
+  CLAIM_SHIELDED_FEES: new Uint8Array([136, 217, 222, 186])
 };
 var KNOWN_PRECOMPILES = {
   // ── Ethereum standard (EIP) ─────────────────────────────────────────────
@@ -2779,9 +2882,9 @@ var KNOWN_PRECOMPILES = {
     name: "ShieldedPool",
     functions: {
       "9feb22ea": "shield(uint32,bytes32,bytes)",
-      "8c0f5d24": "privateTransfer(bytes,bytes32,bytes32[],bytes32[],bytes[],uint32,uint256)",
-      d21d9a79: "unshield(bytes,bytes32,bytes32,uint32,uint256,bytes32,uint256,bytes32)",
-      "42e1e74c": "claimShieldedFees(bytes32,uint256,uint32,bytes,bytes,bytes)"
+      "66ed2cd4": "privateTransfer(bytes,bytes32,bytes32[],bytes32[],bytes[],uint32,uint256,uint32)",
+      "4e505348": "unshield(bytes,bytes32,bytes32,uint32,uint256,bytes32,uint256,bytes32,bytes,uint32)",
+      "88d9deba": "claimShieldedFees(bytes32,uint256,uint32,bytes,bytes,bytes,uint32)"
     }
   }
 };
@@ -2835,7 +2938,8 @@ var ShieldedPoolPrecompile = class {
   // ─── privateTransfer ───────────────────────────────────────────────────────
   /**
    * Returns the ABI-encoded calldata for
-   * `privateTransfer(bytes, bytes32, bytes32[], bytes32[], bytes[], uint32, uint256)`.
+   * `privateTransfer(bytes, bytes32, bytes32[], bytes32[], bytes[], uint32, uint256, uint32)`.
+   * The trailing `uint32` is the circuit version the input notes were created under.
    */
   buildPrivateTransferCalldata(params) {
     const nullifiers = params.inputs.map((i) => fromHex(i.nullifier));
@@ -2856,7 +2960,8 @@ var ShieldedPoolPrecompile = class {
       { type: "bytes32[]", value: commitments },
       { type: "bytes[]", value: memos },
       { type: "uint", value: BigInt(params.assetId) },
-      { type: "uint", value: params.fee ?? 0n }
+      { type: "uint", value: params.fee ?? 0n },
+      { type: "uint", value: BigInt(params.circuitVersion) }
     );
   }
   /**
@@ -2897,7 +3002,8 @@ var ShieldedPoolPrecompile = class {
       { type: "bytes32", value: recipientBytes },
       { type: "uint", value: params.fee ?? 0n },
       { type: "bytes32", value: changeCommitment },
-      { type: "bytes", value: changeEncryptedMemo }
+      { type: "bytes", value: changeEncryptedMemo },
+      { type: "uint", value: BigInt(params.circuitVersion) }
     );
   }
   /**
@@ -2947,7 +3053,7 @@ var ShieldedPoolPrecompile = class {
   // ─── claimShieldedFees ───────────────────────────────────────────────────────────────────
   /**
    * Returns the ABI-encoded calldata for
-   * `claimShieldedFees(bytes32,uint256,uint32,bytes,bytes,bytes)`.
+   * `claimShieldedFees(bytes32,uint256,uint32,bytes,bytes,bytes,uint32)`.
    *
    * ABI layout (params after selector):
    * - `commitment`    — bytes32 (fixed)
@@ -2956,6 +3062,7 @@ var ShieldedPoolPrecompile = class {
    * - `memo`          — bytes   (dynamic)
    * - `proof`         — bytes   (dynamic, 128 bytes Groth16)
    * - `publicSignals` — bytes   (dynamic, 76 bytes)
+   * - `circuitVersion` — uint32 (fixed, right-aligned)
    *
    * The validator identity is derived from `msg.sender` in the precompile —
    * do NOT include it in the calldata.
@@ -2981,7 +3088,8 @@ var ShieldedPoolPrecompile = class {
       { type: "uint", value: BigInt(params.assetId) },
       { type: "bytes", value: params.encryptedMemo },
       { type: "bytes", value: params.proof },
-      { type: "bytes", value: params.publicSignals }
+      { type: "bytes", value: params.publicSignals },
+      { type: "uint", value: BigInt(params.circuitVersion) }
     );
   }
   /**
@@ -3419,6 +3527,11 @@ var OrbinumClient = class _OrbinumClient {
   chain;
   /** Typed access to `zkVerifier_*` custom RPC endpoints. */
   zkVerifier;
+  /**
+   * Resolves a note's circuit version to a pinned prover + on-chain version
+   * before spending it (fail-closed: throws on unsupported version / VK mismatch).
+   */
+  circuitVersionResolver;
   /** Typed access to `relayer_*` RPC endpoints (registry lookup and pending fee queries). */
   relayerStatus;
   /**
@@ -3427,7 +3540,7 @@ var OrbinumClient = class _OrbinumClient {
    */
   precompiles;
   /** @internal Use `OrbinumClient.connect()` to obtain an instance. */
-  constructor(substrate, evm, indexer) {
+  constructor(substrate, evm, indexer, circuitsBaseUrl) {
     this.substrate = substrate;
     this.evm = evm;
     this.evmExplorer = evm ? new EvmExplorer(evm) : null;
@@ -3437,6 +3550,7 @@ var OrbinumClient = class _OrbinumClient {
     this.privacy = new PrivacyModule(substrate);
     this.chain = new ChainModule(substrate);
     this.zkVerifier = new ZkVerifierModule(substrate);
+    this.circuitVersionResolver = new CircuitVersionResolver(this.zkVerifier, circuitsBaseUrl);
     this.relayerStatus = new RelayerStatusModule(substrate);
     this.precompiles = evm ? {
       shieldedPool: new ShieldedPoolPrecompile(evm),
@@ -3457,7 +3571,7 @@ var OrbinumClient = class _OrbinumClient {
     );
     const evm = config.evmRpc ? new EvmClient(config.evmRpc) : null;
     const indexer = config.indexerUrl ? new IndexerClient({ baseUrl: config.indexerUrl }) : null;
-    return new _OrbinumClient(substrate, evm, indexer);
+    return new _OrbinumClient(substrate, evm, indexer, config.circuitsBaseUrl);
   }
   /** Closes the underlying Substrate WebSocket connection and releases all resources. */
   destroy() {
@@ -3579,6 +3693,8 @@ var OrbinumClientProvider = class {
       };
       if (this.config.evmRpc) connectConfig.evmRpc = this.config.evmRpc;
       if (this.config.indexerUrl) connectConfig.indexerUrl = this.config.indexerUrl;
+      if (this.config.circuitsBaseUrl)
+        connectConfig.circuitsBaseUrl = this.config.circuitsBaseUrl;
       const clientPromise = OrbinumClient.connect(connectConfig);
       const client = await Promise.race([clientPromise, timeoutPromise]);
       orphanClient = client;
@@ -3765,6 +3881,9 @@ var OrbinumClientProvider = class {
   }
 };
 
+// src/shielded-pool/protocol/types.ts
+var CURRENT_CIRCUIT_VERSION = 1;
+
 // src/utils/stealth.ts
 import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
 import { hkdf } from "@noble/hashes/hkdf.js";
@@ -3873,6 +3992,7 @@ var NoteBuilder = class {
     const blinding = input.blinding ?? BigInt(Date.now());
     const spendingKey = input.spendingKey ?? 0n;
     const counterpartyPk = input.counterpartyPk ?? 0n;
+    const circuitVersion = input.circuitVersion ?? CURRENT_CIRCUIT_VERSION;
     const useStealth = input.viewingPublicKey !== void 0 && input.recipientOwnerPk !== void 0;
     let memo;
     if (useStealth) {
@@ -3907,6 +4027,7 @@ var NoteBuilder = class {
           stealthCommitmentBytes,
           recipientIvkPacked,
           bigintTo32Le(counterpartyPk),
+          circuitVersion,
           ephSk
         )
       );
@@ -3924,6 +4045,7 @@ var NoteBuilder = class {
         ownerPk: effectiveOwnerPk,
         blinding,
         spendingKey,
+        circuitVersion,
         spent: false,
         spentAt: null,
         commitment: commitment2,
@@ -3946,7 +4068,8 @@ var NoteBuilder = class {
         Number(assetId),
         commitmentBytes,
         input.viewingPublicKey,
-        bigintTo32Le(counterpartyPk)
+        bigintTo32Le(counterpartyPk),
+        circuitVersion
       )
     ) : Array.from(EncryptedMemo.dummy());
     if (memo.length !== ENCRYPTED_MEMO_SIZE)
@@ -3959,6 +4082,7 @@ var NoteBuilder = class {
       ownerPk,
       blinding,
       spendingKey,
+      circuitVersion,
       spent: false,
       spentAt: null,
       commitment,
@@ -3970,7 +4094,7 @@ var NoteBuilder = class {
     };
   }
   /**
-   * Build the 168-byte ECDH-encrypted memo for a note.
+   * Build the 180-byte ECDH-encrypted memo for a note.
    *
    * Pure TypeScript implementation — no WASM dependency.
    * Uses ChaCha20-Poly1305 with ECDH key agreement (BabyJubJub ephemeral keypair).
@@ -3989,7 +4113,8 @@ var NoteBuilder = class {
       Number(note.assetId),
       bigintTo32Le(note.commitment),
       recipientIvkPacked ?? new Uint8Array(32),
-      counterpartyPk ?? bigintTo32Le(note.counterpartyPk ?? 0n)
+      counterpartyPk ?? bigintTo32Le(note.counterpartyPk ?? 0n),
+      note.circuitVersion
     );
   }
 };
@@ -4051,6 +4176,7 @@ function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwn
       ownerPk: effectiveOwnerPk,
       blinding: plaintext.blinding,
       spendingKey: effectiveSpendingKey,
+      circuitVersion: plaintext.circuitVersion,
       spent: false,
       spentAt: null,
       commitment: recomputed,
@@ -4124,7 +4250,7 @@ function selectNotes(notes, needed) {
     for (let j = i + 1; j < sorted.length; j++) {
       const a = sorted[i];
       const b = sorted[j];
-      if (a !== void 0 && b !== void 0 && a.value + b.value >= needed) {
+      if (a !== void 0 && b !== void 0 && a.circuitVersion === b.circuitVersion && a.value + b.value >= needed) {
         return [a, b];
       }
     }
@@ -4481,6 +4607,11 @@ async function encryptNote(key, blindKey, note) {
 }
 async function decryptNoteRecord(key, rec) {
   const note = await decryptJson(key, rec.iv, rec.ciphertext);
+  if (typeof note.circuitVersion !== "number") {
+    throw new Error(
+      "decryptNoteRecord: note is missing circuitVersion (invalid or corrupt record)"
+    );
+  }
   return applyNoteStatus(note, {
     ...rec.spent !== void 0 && { spent: rec.spent },
     spentAt: rec.spentAt ?? null
@@ -4492,9 +4623,9 @@ async function noteBlindTag(blindKey, hex) {
 
 // src/proof-generator/unshield.ts
 import {
-  CircuitType,
+  CircuitType as CircuitType2,
   generateProof,
-  WebArtifactProvider
+  WebArtifactProvider as WebArtifactProvider2
 } from "@orbinum/proof-generator";
 import { randomBytes as randomBytes3 } from "@noble/ciphers/utils.js";
 import { mulPointEscalar as mulPointEscalar6, Base8 as Base84 } from "@zk-kit/baby-jubjub";
@@ -4541,18 +4672,18 @@ async function generateUnshieldProof(inputs, options = {}) {
     change_blinding: changeBlinding.toString(),
     change_owner_pubkey: changeOwnerPubkey.toString()
   };
-  const provider = options.provider ?? new WebArtifactProvider();
+  const provider = options.provider ?? new WebArtifactProvider2();
   const opts = { provider };
   if (options.verbose !== void 0) opts.verbose = options.verbose;
-  const proofResult = await generateProof(CircuitType.Unshield, circuitInputs, opts);
+  const proofResult = await generateProof(CircuitType2.Unshield, circuitInputs, opts);
   return { ...proofResult, changeCommitment, changeValue, changeBlinding, changeOwnerPubkey };
 }
 
 // src/proof-generator/transfer.ts
 import {
-  CircuitType as CircuitType2,
+  CircuitType as CircuitType3,
   generateProof as generateProof2,
-  WebArtifactProvider as WebArtifactProvider2
+  WebArtifactProvider as WebArtifactProvider3
 } from "@orbinum/proof-generator";
 async function generateTransferProof(params, options = {}) {
   const root = leHexToBigint(params.merkleRoot).toString();
@@ -4578,17 +4709,17 @@ async function generateTransferProof(params, options = {}) {
     output_owner_pubkeys: [o0.ownerPk.toString(), o1.ownerPk.toString()],
     output_blindings: [o0.blinding.toString(), o1.blinding.toString()]
   };
-  const provider = options.provider ?? new WebArtifactProvider2();
+  const provider = options.provider ?? new WebArtifactProvider3();
   const opts = { provider };
   if (options.verbose !== void 0) opts.verbose = options.verbose;
-  return generateProof2(CircuitType2.Transfer, circuitInputs, opts);
+  return generateProof2(CircuitType3.Transfer, circuitInputs, opts);
 }
 
 // src/proof-generator/fee-claim.ts
 import {
-  CircuitType as CircuitType3,
+  CircuitType as CircuitType4,
   generateProof as generateProof3,
-  WebArtifactProvider as WebArtifactProvider3
+  WebArtifactProvider as WebArtifactProvider4
 } from "@orbinum/proof-generator";
 async function generateFeeClaimProof(inputs, options = {}) {
   if (inputs.amount <= 0n) {
@@ -4601,10 +4732,10 @@ async function generateFeeClaimProof(inputs, options = {}) {
     owner_pubkey: inputs.ownerPubkey.toString(),
     blinding: inputs.blinding.toString()
   };
-  const provider = options.provider ?? new WebArtifactProvider3();
+  const provider = options.provider ?? new WebArtifactProvider4();
   const opts = { provider };
   if (options.verbose !== void 0) opts.verbose = options.verbose;
-  const proofResult = await generateProof3(CircuitType3.ValueProof, circuitInputs, opts);
+  const proofResult = await generateProof3(CircuitType4.ValueProof, circuitInputs, opts);
   const [sigCommitment, sigValue, sigAssetId, sigOwnerHash] = proofResult.publicSignals.map(BigInt);
   const buf = new Uint8Array(76);
   buf.set(bigintTo32Le(sigCommitment), 0);
@@ -4660,9 +4791,19 @@ function decodePrecompileCalldata(address, input) {
       const recipient = toHex(data.slice(160, 192));
       const fee = decodeUint(data, 192);
       const changeCommitment = toHex(data.slice(224, 256));
+      const circuitVersion = decodeUint(data, 288);
       return {
         fnSig,
-        args: { root, nullifier, assetId, amount, recipient, fee, changeCommitment }
+        args: {
+          root,
+          nullifier,
+          assetId,
+          amount,
+          recipient,
+          fee,
+          changeCommitment,
+          circuitVersion
+        }
       };
     } catch {
       return { fnSig, args: {} };
@@ -4678,7 +4819,8 @@ function decodePrecompileCalldata(address, input) {
       const commitments = Number(decodeUint(data, commOffset));
       const assetId = decodeUint(data, 160);
       const fee = decodeUint(data, 192);
-      return { fnSig, args: { root, nullifiers, commitments, assetId, fee } };
+      const circuitVersion = decodeUint(data, 224);
+      return { fnSig, args: { root, nullifiers, commitments, assetId, fee, circuitVersion } };
     } catch {
       return { fnSig, args: {} };
     }
@@ -4689,7 +4831,8 @@ function decodePrecompileCalldata(address, input) {
       const commitment = toHex(data.slice(0, 32));
       const amount = decodeUint(data, 32);
       const assetId = decodeUint(data, 64);
-      return { fnSig, args: { commitment, amount, assetId } };
+      const circuitVersion = decodeUint(data, 192);
+      return { fnSig, args: { commitment, amount, assetId, circuitVersion } };
     } catch {
       return { fnSig, args: {} };
     }
@@ -4701,8 +4844,8 @@ function decodePrecompileCalldata(address, input) {
 var CircuitId = {
   Transfer: 1,
   Unshield: 2,
-  ValueProof: 4,
-  PrivateLink: 5
+  PrivateLink: 5,
+  ValueProof: 6
 };
 
 // src/utils/string.ts
@@ -5384,8 +5527,10 @@ export {
   BABYJUB_SUBORDER,
   BN254_R,
   Blake2256,
+  CURRENT_CIRCUIT_VERSION,
   CircuitId,
-  CircuitType,
+  CircuitType2 as CircuitType,
+  CircuitVersionResolver,
   CryptoPrecompiles,
   ENCRYPTED_MEMO_SIZE,
   EncryptedMemo,
@@ -5408,7 +5553,7 @@ export {
   Storage,
   SubstrateClient,
   VaultLockedError,
-  WebArtifactProvider,
+  WebArtifactProvider2 as WebArtifactProvider,
   ZkVerifierModule,
   accountIdHexToSs58,
   addressToAccountIdHex,