@orbinum/sdk 0.11.0 → 0.12.0

package/dist/index.js

@@ -26,8 +26,10 @@ __export(index_exports, {
   BABYJUB_SUBORDER: () => BABYJUB_SUBORDER,
   BN254_R: () => BN254_R,
   Blake2256: () => import_substrate_bindings3.Blake2256,
+  CURRENT_CIRCUIT_VERSION: () => CURRENT_CIRCUIT_VERSION,
   CircuitId: () => CircuitId,
-  CircuitType: () => import_proof_generator.CircuitType,
+  CircuitType: () => import_proof_generator2.CircuitType,
+  CircuitVersionResolver: () => CircuitVersionResolver,
   CryptoPrecompiles: () => CryptoPrecompiles,
   ENCRYPTED_MEMO_SIZE: () => ENCRYPTED_MEMO_SIZE,
   EncryptedMemo: () => EncryptedMemo,
@@ -50,7 +52,7 @@ __export(index_exports, {
   Storage: () => import_substrate_bindings3.Storage,
   SubstrateClient: () => SubstrateClient,
   VaultLockedError: () => VaultLockedError,
-  WebArtifactProvider: () => import_proof_generator.WebArtifactProvider,
+  WebArtifactProvider: () => import_proof_generator2.WebArtifactProvider,
   ZkVerifierModule: () => ZkVerifierModule,
   accountIdHexToSs58: () => accountIdHexToSs58,
   addressToAccountIdHex: () => addressToAccountIdHex,
@@ -1228,7 +1230,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).
    */
@@ -1648,8 +1650,8 @@ var BABYJUB_SUBORDER = 273603035897990940278080071815715938607681397215856725920
 // src/shielded-pool/protocol/memo.ts
 var import_sha2 = require("@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);
@@ -1658,6 +1660,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) {
@@ -1670,7 +1673,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) {
@@ -1689,14 +1692,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).
@@ -1708,11 +1712,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 = (0, import_utils.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;
@@ -1743,29 +1756,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.
@@ -1786,7 +1801,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().
    */
@@ -1798,13 +1813,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) {
@@ -2008,7 +2023,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");
@@ -2032,8 +2047,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(
@@ -2046,7 +2062,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);
@@ -2067,8 +2083,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(
@@ -2102,7 +2119,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");
@@ -2113,7 +2130,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))
@@ -2631,6 +2649,74 @@ var ZkVerifierModule = class {
   }
 };
 
+// src/shielded-pool/CircuitVersionResolver.ts
+var import_proof_generator = require("@orbinum/proof-generator");
+var CircuitVersionResolver = class {
+  constructor(zkVerifier, baseUrl, providerFactory) {
+    this.zkVerifier = zkVerifier;
+    this.makeProvider = providerFactory ?? ((circuit, noteVersion) => new import_proof_generator.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 = (0, import_proof_generator.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) {
@@ -2876,12 +2962,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) ─────────────────────────────────────────────
@@ -2925,9 +3011,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)"
     }
   }
 };
@@ -2981,7 +3067,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));
@@ -3002,7 +3089,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) }
     );
   }
   /**
@@ -3043,7 +3131,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) }
     );
   }
   /**
@@ -3093,7 +3182,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)
@@ -3102,6 +3191,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.
@@ -3127,7 +3217,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) }
     );
   }
   /**
@@ -3565,6 +3656,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;
   /**
@@ -3573,7 +3669,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;
@@ -3583,6 +3679,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),
@@ -3603,7 +3700,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() {
@@ -3725,6 +3822,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;
@@ -3911,6 +4010,9 @@ var OrbinumClientProvider = class {
   }
 };
 
+// src/shielded-pool/protocol/types.ts
+var CURRENT_CIRCUIT_VERSION = 1;
+
 // src/utils/stealth.ts
 var import_sha22 = require("@noble/hashes/sha2.js");
 var import_hkdf = require("@noble/hashes/hkdf.js");
@@ -4019,6 +4121,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) {
@@ -4053,6 +4156,7 @@ var NoteBuilder = class {
           stealthCommitmentBytes,
           recipientIvkPacked,
           bigintTo32Le(counterpartyPk),
+          circuitVersion,
           ephSk
         )
       );
@@ -4070,6 +4174,7 @@ var NoteBuilder = class {
         ownerPk: effectiveOwnerPk,
         blinding,
         spendingKey,
+        circuitVersion,
         spent: false,
         spentAt: null,
         commitment: commitment2,
@@ -4092,7 +4197,8 @@ var NoteBuilder = class {
         Number(assetId),
         commitmentBytes,
         input.viewingPublicKey,
-        bigintTo32Le(counterpartyPk)
+        bigintTo32Le(counterpartyPk),
+        circuitVersion
       )
     ) : Array.from(EncryptedMemo.dummy());
     if (memo.length !== ENCRYPTED_MEMO_SIZE)
@@ -4105,6 +4211,7 @@ var NoteBuilder = class {
       ownerPk,
       blinding,
       spendingKey,
+      circuitVersion,
       spent: false,
       spentAt: null,
       commitment,
@@ -4116,7 +4223,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).
@@ -4135,7 +4242,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
     );
   }
 };
@@ -4197,6 +4305,7 @@ function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwn
       ownerPk: effectiveOwnerPk,
       blinding: plaintext.blinding,
       spendingKey: effectiveSpendingKey,
+      circuitVersion: plaintext.circuitVersion,
       spent: false,
       spentAt: null,
       commitment: recomputed,
@@ -4270,7 +4379,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];
       }
     }
@@ -4627,6 +4736,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
@@ -4637,7 +4751,7 @@ async function noteBlindTag(blindKey, hex) {
 }
 
 // src/proof-generator/unshield.ts
-var import_proof_generator = require("@orbinum/proof-generator");
+var import_proof_generator2 = require("@orbinum/proof-generator");
 var import_utils3 = require("@noble/ciphers/utils.js");
 var import_baby_jubjub6 = require("@zk-kit/baby-jubjub");
 var import_poseidon_lite4 = require("poseidon-lite");
@@ -4683,15 +4797,15 @@ async function generateUnshieldProof(inputs, options = {}) {
     change_blinding: changeBlinding.toString(),
     change_owner_pubkey: changeOwnerPubkey.toString()
   };
-  const provider = options.provider ?? new import_proof_generator.WebArtifactProvider();
+  const provider = options.provider ?? new import_proof_generator2.WebArtifactProvider();
   const opts = { provider };
   if (options.verbose !== void 0) opts.verbose = options.verbose;
-  const proofResult = await (0, import_proof_generator.generateProof)(import_proof_generator.CircuitType.Unshield, circuitInputs, opts);
+  const proofResult = await (0, import_proof_generator2.generateProof)(import_proof_generator2.CircuitType.Unshield, circuitInputs, opts);
   return { ...proofResult, changeCommitment, changeValue, changeBlinding, changeOwnerPubkey };
 }
 
 // src/proof-generator/transfer.ts
-var import_proof_generator2 = require("@orbinum/proof-generator");
+var import_proof_generator3 = require("@orbinum/proof-generator");
 async function generateTransferProof(params, options = {}) {
   const root = leHexToBigint(params.merkleRoot).toString();
   const [i0, i1] = params.inputs;
@@ -4716,14 +4830,14 @@ 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 import_proof_generator2.WebArtifactProvider();
+  const provider = options.provider ?? new import_proof_generator3.WebArtifactProvider();
   const opts = { provider };
   if (options.verbose !== void 0) opts.verbose = options.verbose;
-  return (0, import_proof_generator2.generateProof)(import_proof_generator2.CircuitType.Transfer, circuitInputs, opts);
+  return (0, import_proof_generator3.generateProof)(import_proof_generator3.CircuitType.Transfer, circuitInputs, opts);
 }
 
 // src/proof-generator/fee-claim.ts
-var import_proof_generator3 = require("@orbinum/proof-generator");
+var import_proof_generator4 = require("@orbinum/proof-generator");
 async function generateFeeClaimProof(inputs, options = {}) {
   if (inputs.amount <= 0n) {
     throw new Error("Fee claim amount must be greater than zero.");
@@ -4735,10 +4849,10 @@ async function generateFeeClaimProof(inputs, options = {}) {
     owner_pubkey: inputs.ownerPubkey.toString(),
     blinding: inputs.blinding.toString()
   };
-  const provider = options.provider ?? new import_proof_generator3.WebArtifactProvider();
+  const provider = options.provider ?? new import_proof_generator4.WebArtifactProvider();
   const opts = { provider };
   if (options.verbose !== void 0) opts.verbose = options.verbose;
-  const proofResult = await (0, import_proof_generator3.generateProof)(import_proof_generator3.CircuitType.ValueProof, circuitInputs, opts);
+  const proofResult = await (0, import_proof_generator4.generateProof)(import_proof_generator4.CircuitType.ValueProof, circuitInputs, opts);
   const [sigCommitment, sigValue, sigAssetId, sigOwnerHash] = proofResult.publicSignals.map(BigInt);
   const buf = new Uint8Array(76);
   buf.set(bigintTo32Le(sigCommitment), 0);
@@ -4794,9 +4908,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: {} };
@@ -4812,7 +4936,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: {} };
     }
@@ -4823,7 +4948,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: {} };
     }
@@ -4835,8 +4961,8 @@ function decodePrecompileCalldata(address, input) {
 var CircuitId = {
   Transfer: 1,
   Unshield: 2,
-  ValueProof: 4,
-  PrivateLink: 5
+  PrivateLink: 5,
+  ValueProof: 6
 };
 
 // src/utils/string.ts
@@ -5508,8 +5634,10 @@ var import_polkadot_api4 = require("polkadot-api");
   BABYJUB_SUBORDER,
   BN254_R,
   Blake2256,
+  CURRENT_CIRCUIT_VERSION,
   CircuitId,
   CircuitType,
+  CircuitVersionResolver,
   CryptoPrecompiles,
   ENCRYPTED_MEMO_SIZE,
   EncryptedMemo,