@orbinum/sdk 0.10.0 → 0.12.0

package/dist/index.d.mts

@@ -3,7 +3,7 @@ import { PolkadotClient, TxFinalizedPayload, PolkadotSigner, TxOptions } from 'p
 export { PolkadotSigner, getSs58AddressInfo } from 'polkadot-api';
 import { getDynamicBuilder } from '@polkadot-api/metadata-builders';
 import { getExtrinsicDecoder } from '@polkadot-api/tx-utils';
-import { ArtifactProvider, ProofResult } from '@orbinum/proof-generator';
+import { CircuitType, ArtifactProvider, ProofResult } from '@orbinum/proof-generator';
 export { ArtifactProvider, CircuitType, ProofResult, WebArtifactProvider } from '@orbinum/proof-generator';
 export { AccountId, Blake2256, Keccak256, Storage, u128, u64 } from '@polkadot-api/substrate-bindings';
 export { base58 } from '@scure/base';
@@ -520,18 +520,10 @@ interface ShieldedCommitment {
     blockNumber: number;
     extrinsicIndex: number | null;
     leafIndex: number;
-    /**
-     * Asset ID as decimal string.
-     * For `source: 'shield'` and `source: 'unshield'` this reflects the real asset.
-     * For `source: 'transfer'` it is always `"0"` — the chain intentionally omits the asset ID
-     * from `CommitmentsInserted` events to prevent graph correlation across assets.
-     * The true asset is recoverable only by decrypting `encryptedMemo`.
-     */
     assetId: string;
-    /** Origin of the commitment: direct shield, output of private transfer, or change from unshield. */
     source: 'shield' | 'transfer' | 'unshield';
-    /** 0x-prefixed encrypted memo hex, null if not present. */
     encryptedMemo: string | null;
+    circuitVersion: number | null;
     timestampMs: number | null;
 }
 /** A spent nullifier stored by the indexer. */
@@ -816,7 +808,8 @@ interface StealthScanHint {
     assetId: string;
     /** Ephemeral public key (last 32 bytes of encrypted_memo), 0x-prefixed. null if memo absent. */
     ephPkHex: string | null;
-    /** Full 168-byte encrypted memo (0x-prefixed hex). null if not present. */
+    /** Full 180-byte encrypted memo (0x-prefixed hex). null if not present. The note's
+     * circuit version travels inside this memo — recovered by NoteDecryptor on scan. */
     encryptedMemo: string | null;
 }
 
@@ -847,7 +840,7 @@ declare 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).
      */
@@ -1036,6 +1029,12 @@ type OrbinumClientConfig = {
     indexerUrl?: string;
     /** Timeout for the initial WebSocket handshake in milliseconds. Default: `15_000`. */
     connectTimeoutMs?: number;
+    /**
+     * Base URL of a circuits-artifact mirror (serving `manifest.json` + artifacts).
+     * Passed to the `CircuitVersionResolver`'s provider. Omit to use the default
+     * npm CDN (unpkg). Use to point at a self-hosted/multi-version manifest.
+     */
+    circuitsBaseUrl?: string;
 };
 /** Result returned by extrinsic-submitting methods (shield, unshield, transfer, …). */
 type TxResult = {
@@ -1055,32 +1054,51 @@ type TxResult = {
 type UnsafeTxOptions = TxOptions<void, Record<string, unknown>>;
 declare function toTxResult(payload: TxFinalizedPayload): TxResult;
 
+/** On-chain Merkle tree state for the shielded pool. */
 type MerkleTreeInfo = {
+    /** 0x-prefixed current Merkle root hex. */
     root: string;
+    /** Number of leaves (commitments) inserted so far. */
     treeSize: number;
+    /** Tree depth (levels from leaf to root). */
     depth: number;
 };
+/** A commitment surfaced by the indexer scan feed, for trial-decryption. */
 type ScanCommitment = {
+    /** 0x-prefixed 32-byte commitment hex. */
     commitmentHex: string;
+    /** Leaf position of the commitment in the Merkle tree. */
     leafIndex: number;
+    /** 0x-prefixed encrypted memo hex, or null if none was published. */
     encryptedMemo: string | null;
 };
+/** Plaintext fields recovered from a note's encrypted memo. */
 type DecryptedMemo = {
+    /** Note amount in planck. */
     value: bigint;
+    /** Owner's BabyJubJub Ax coordinate. */
     ownerPk: bigint;
+    /** Blinding scalar used in the commitment. */
     blinding: bigint;
+    /** Asset ID of the note. */
     assetId: bigint;
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
     counterpartyPk: bigint;
+    /** ZK circuit version the note is spent under, recovered from the memo plaintext. */
+    circuitVersion: number;
 };
+/** Parameters for shieldedPool.shield — deposits one note into the pool. */
 type ShieldParams = {
+    /** Asset ID being deposited. */
     assetId: number;
+    /** Amount to deposit in planck. */
     amount: bigint;
     /** 0x-prefixed 32-byte commitment hex */
     commitment: string;
-    /** Encrypted memo bytes (168 bytes). Required — notes without valid memos are irrecoverable. */
+    /** Encrypted memo bytes (180 bytes). Required — notes without valid memos are irrecoverable. */
     encryptedMemo: Uint8Array;
 };
+/** Parameters for shieldedPool.unshield — withdraws from the pool to a clear address. */
 type UnshieldParams = {
     /** ZK proof bytes */
     proof: Uint8Array;
@@ -1088,6 +1106,7 @@ type UnshieldParams = {
     merkleRoot: string;
     /** 0x-prefixed nullifier hex */
     nullifier: string;
+    /** Asset ID being withdrawn. */
     assetId: number;
     /** Net amount recipient receives (planck) */
     amount: bigint;
@@ -1102,11 +1121,13 @@ type UnshieldParams = {
      */
     changeCommitment?: string;
     /**
-     * Encrypted memo for the change note (176 bytes).
+     * Encrypted memo for the change note (180 bytes).
      * Required for partial unshield so the change note can be recovered via blockchain scan.
      * Omit for total unshield.
      */
     changeEncryptedMemo?: Uint8Array;
+    /** Circuit version the spent note was created under. Verified against that version's VK. */
+    circuitVersion: number;
 };
 type PrivateTransferInput = {
     /** 0x-prefixed nullifier hex */
@@ -1117,11 +1138,13 @@ type PrivateTransferInput = {
 type PrivateTransferOutput = {
     /** 0x-prefixed commitment hex */
     commitment: string;
-    /** Encrypted memo bytes (168 bytes). Required — notes without valid memos are irrecoverable. */
+    /** Encrypted memo bytes (180 bytes). Required — notes without valid memos are irrecoverable. */
     encryptedMemo: Uint8Array;
 };
 type PrivateTransferParams = {
+    /** Input notes being spent (nullifier + commitment each). */
     inputs: PrivateTransferInput[];
+    /** Output notes being created (commitment + encrypted memo each). */
     outputs: PrivateTransferOutput[];
     /** ZK proof bytes */
     proof: Uint8Array;
@@ -1132,6 +1155,8 @@ type PrivateTransferParams = {
     /** Gasless fee in planck (default 0n; input_sum == output_sum + fee in circuit).
      *  The fee is paid to the block author (validator) by the pallet runtime. */
     fee?: bigint;
+    /** Circuit version the input notes were created under. Verified against that version's VK. */
+    circuitVersion: number;
 };
 /** Input params for NoteBuilder.build(). All fields except value have defaults. */
 type NoteInput = {
@@ -1147,7 +1172,7 @@ type NoteInput = {
     spendingKey?: bigint;
     /**
      * 32-byte LE-encoded packed BJJ viewing public key of the recipient (from their privacy address).
-     * When provided, NoteBuilder.build() will auto-generate the 168-byte ECDH-encrypted memo.
+     * When provided, NoteBuilder.build() will auto-generate the 180-byte ECDH-encrypted memo.
      * Omit to skip memo generation (use buildMemo() separately if needed).
      */
     viewingPublicKey?: Uint8Array;
@@ -1160,7 +1185,16 @@ type NoteInput = {
     recipientOwnerPk?: bigint;
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. Default 0n. */
     counterpartyPk?: bigint;
+    /** Circuit version to stamp on the note. Defaults to `CURRENT_CIRCUIT_VERSION`. */
+    circuitVersion?: number;
 };
+/**
+ * Circuit version notes are created under today. A note carries its version
+ * (`ZkNote.circuitVersion`) so that, after a VK rotation, it is always proven
+ * and verified against the circuit that created it. Only one version exists
+ * today; callers may pass the chain's active version explicitly.
+ */
+declare const CURRENT_CIRCUIT_VERSION = 1;
 /**
  * Computed ZK note (commitment + nullifier). Built entirely off-chain.
  *
@@ -1168,11 +1202,18 @@ type NoteInput = {
  * nullifier  = Poseidon(commitment, spendingKey)
  */
 type ZkNote = {
+    /** Note amount in planck. */
     value: bigint;
+    /** Asset ID of the note. */
     assetId: bigint;
+    /** Owner's BabyJubJub Ax coordinate (or stealth owner Pk for stealth notes). */
     ownerPk: bigint;
+    /** Blinding scalar mixed into the commitment. */
     blinding: bigint;
+    /** Secret spending key used to derive the nullifier. */
     spendingKey: bigint;
+    /** Circuit version this note was created under (see `CURRENT_CIRCUIT_VERSION`). Required. */
+    circuitVersion: number;
     /** Whether the note has been spent/nullified on-chain. */
     spent: boolean;
     /** Local timestamp when this note was marked spent, or null if still active/unknown. */
@@ -1186,7 +1227,7 @@ type ZkNote = {
     /** 0x-prefixed 32-byte little-endian hex nullifier. */
     nullifierHex: string;
     /**
-     * 168-byte encrypted memo (ChaCha20-Poly1305 ECDH) as number[] for SCALE encoding.
+     * 180-byte encrypted memo (ChaCha20-Poly1305 ECDH) as number[] for SCALE encoding.
      * Always populated: uses a dummy memo when no viewingPublicKey is provided.
      */
     memo: number[];
@@ -1195,15 +1236,18 @@ type ZkNote = {
 };
 /** Parameters for a single item in a shield_batch extrinsic. */
 type ShieldBatchItem = {
+    /** Asset ID being deposited. */
     assetId: number;
+    /** Amount to deposit in planck. */
     amount: bigint;
     /** 0x-prefixed 32-byte commitment hex */
     commitment: string;
-    /** Encrypted memo bytes (168 bytes). Required — notes without valid memos are irrecoverable. */
+    /** Encrypted memo bytes (180 bytes). Required — notes without valid memos are irrecoverable. */
     encryptedMemo: Uint8Array;
 };
 /** Parameters for shieldedPool.shieldBatch — deposits up to 20 notes in one extrinsic. */
 type ShieldBatchParams = {
+    /** The notes to deposit (up to 20). */
     items: ShieldBatchItem[];
 };
 /**
@@ -1224,8 +1268,10 @@ type ClaimShieldedFeesParams = {
     proof: Uint8Array;
     /** 76-byte public signals buffer (commitment || amount_u64_le || assetId_u32_le || owner_hash) */
     publicSignals: Uint8Array;
-    /** Encrypted memo bytes (168 bytes). Required — notes without valid memos are irrecoverable. */
+    /** Encrypted memo bytes (180 bytes). Required — notes without valid memos are irrecoverable. */
     encryptedMemo: Uint8Array;
+    /** Circuit version of the fee-claim note. Verified against that version's VK. */
+    circuitVersion: number;
 };
 
 /**
@@ -1252,14 +1298,14 @@ declare class ShieldedPoolModule {
      * 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)
      */
     unshield(params: UnshieldParams, signer?: PolkadotSigner, txOptions?: UnsafeTxOptions): Promise<TxResult>;
     /**
      * 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)
      */
     privateTransfer(params: PrivateTransferParams, signer?: PolkadotSigner, txOptions?: UnsafeTxOptions): Promise<TxResult>;
     /**
@@ -1272,7 +1318,7 @@ declare class ShieldedPoolModule {
      * 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)
      */
     claimShieldedFees(params: ClaimShieldedFeesParams, signer: PolkadotSigner, txOptions?: UnsafeTxOptions): Promise<TxResult>;
 }
@@ -1635,6 +1681,61 @@ declare class ZkVerifierModule {
     getCircuitVersionInfo(circuitId: number): Promise<ZkVerifierCircuitVersionInfo | null>;
 }
 
+/** The resolved version + VK hash the prover reports for a circuit. */
+type ResolvedProverVersion = {
+    version: number;
+    vkHash: string;
+};
+/**
+ * A provider that can both serve artifacts and report the version it resolved
+ * for a circuit (`WebArtifactProvider` implements both). The resolver needs the
+ * version-reporting half; it is a separate type so tests can inject a fake.
+ */
+type VersionedArtifactProvider = ArtifactProvider & {
+    getResolvedVersion(circuit: CircuitType): Promise<ResolvedProverVersion>;
+};
+/**
+ * Builds a provider pinned to `noteVersion` for `circuit`. The default uses the
+ * npm CDN (or `baseUrl` mirror); tests inject a fake.
+ */
+type ProviderFactory = (circuit: CircuitType, noteVersion: number) => VersionedArtifactProvider;
+/**
+ * The single fail-closed choke point for spending a note under a specific
+ * circuit version.
+ *
+ * A note carries the circuit version it was created under (`ZkNote.circuitVersion`).
+ * When that note is spent, the proof MUST be generated against that version's
+ * artifacts and verified on-chain against that version's VK — never the current
+ * `active_version`, or a VK rotation would make old notes unspendable.
+ *
+ * `resolve()` pins the prover to the note's version, cross-checks that the
+ * prover's VK hash matches what the chain declares for that version, and confirms
+ * the chain still supports it. On any mismatch it throws BEFORE any proof is
+ * generated — there is no fallback to the active version. The returned
+ * `{ provider, version }` is fed to the proof generator and the extrinsic.
+ */
+type ResolvedSpendVersion = {
+    /** Artifact provider pinned to the note's circuit version. Pass to `generate*Proof`. */
+    provider: ArtifactProvider;
+    /** The circuit version to send in the extrinsic (`circuit_version` arg). */
+    version: number;
+};
+declare class CircuitVersionResolver {
+    private readonly zkVerifier;
+    private readonly makeProvider;
+    constructor(zkVerifier: ZkVerifierModule, 
+    /** Optional base URL for a self-hosted artifact mirror (else the npm CDN). */
+    baseUrl?: string, 
+    /** Override how the pinned provider is built (tests inject a fake). */
+    providerFactory?: ProviderFactory);
+    /**
+     * 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.
+     */
+    resolve(circuit: CircuitType, noteVersion: number): Promise<ResolvedSpendVersion>;
+}
+
 /**
  * Status info for a registered relayer account.
  */
@@ -1735,7 +1836,8 @@ declare class ShieldedPoolPrecompile {
     shield(params: ShieldParams, signer: EvmSigner): Promise<string>;
     /**
      * 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: PrivateTransferParams): string;
     /**
@@ -1778,7 +1880,7 @@ declare class ShieldedPoolPrecompile {
     estimateUnshieldGas(params: UnshieldParams, from: string): Promise<bigint>;
     /**
      * 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)
@@ -1787,6 +1889,7 @@ declare class ShieldedPoolPrecompile {
      * - `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.
@@ -2092,6 +2195,11 @@ declare class OrbinumClient {
     readonly chain: ChainModule;
     /** Typed access to `zkVerifier_*` custom RPC endpoints. */
     readonly zkVerifier: ZkVerifierModule;
+    /**
+     * Resolves a note's circuit version to a pinned prover + on-chain version
+     * before spending it (fail-closed: throws on unsupported version / VK mismatch).
+     */
+    readonly circuitVersionResolver: CircuitVersionResolver;
     /** Typed access to `relayer_*` RPC endpoints (registry lookup and pending fee queries). */
     readonly relayerStatus: RelayerStatusModule;
     /**
@@ -2138,6 +2246,8 @@ interface ClientProviderConfig {
     evmRpc?: string;
     /** Base URL of the Orbinum indexer REST API (e.g. `"https://indexer.orbinum.io"`). Omit to disable indexer support. */
     indexerUrl?: string;
+    /** Base URL of a circuits-artifact mirror (manifest.json + artifacts). Omit to use the default npm CDN. */
+    circuitsBaseUrl?: string;
     /** Timeout for the initial WebSocket handshake in milliseconds. Default: `8_000`. */
     connectTimeoutMs?: number;
     /** Interval between heartbeat probes in milliseconds. Default: `5_000`. */
@@ -2299,7 +2409,7 @@ declare class OrbinumClientProvider {
  *
  * Memo scheme (EncryptedMemo — native TypeScript, no WASM):
  *   ChaCha20-Poly1305 with ECDH ephemeral key — SHA256(sharedSecret || commitment || domain)
- *   Result: nonce(12) || ciphertext(108 + 16 MAC) || ephPk(32) = 168 bytes
+ *   Result: nonce(12) || ciphertext(120 + 16 MAC) || ephPk(32) = 180 bytes
  *
  * Stealth scheme (when viewingPublicKey + recipientOwnerPk are both provided):
  *   ephSk is generated once and shared between the ECDH memo and the stealth Pk derivation.
@@ -2324,7 +2434,7 @@ declare class NoteBuilder {
      */
     static build(input: NoteInput): Promise<ZkNote>;
     /**
-     * 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).
@@ -2343,11 +2453,11 @@ declare class NoteBuilder {
  *
  * Mirrors primitives/encrypted-memo in the node repository; no WASM required.
  *
- * Layout (176 bytes, ECDH):
- *   nonce(12) || ciphertext+MAC(132) || ephPk_packed(32) = 176
+ * Layout (180 bytes, ECDH):
+ *   nonce(12) || ciphertext+MAC(136) || ephPk_packed(32) = 180
  *
- * Plaintext layout (116 bytes):
- *   value_lo(8 LE) || value_hi(8 LE) || owner_pk(32) || blinding(32) || asset_id(4 LE) || counterparty_pk(32)
+ * Plaintext layout (120 bytes):
+ *   value_lo(8 LE) || value_hi(8 LE) || owner_pk(32) || blinding(32) || asset_id(4 LE) || counterparty_pk(32) || circuit_version(4 LE)
  *
  * value is stored as a 128-bit LE unsigned integer (two uint64 words), supporting
  * amounts up to ~3.4 × 10^38 planck — well above any realistic token supply.
@@ -2362,11 +2472,11 @@ declare class NoteBuilder {
  * Cipher: ChaCha20-Poly1305 (IETF, 96-bit nonce)
  */
 
-/** Memo size: nonce(12) + ciphertext+MAC(132) + ephPk(32) = 176 */
+/** Memo size: nonce(12) + ciphertext+MAC(136) + ephPk(32) = 180 */
 declare const ENCRYPTED_MEMO_SIZE: number;
 declare const 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).
@@ -2378,22 +2488,24 @@ declare const 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: bigint, ownerPk: Uint8Array, blinding: Uint8Array, assetId: number, commitment: Uint8Array, recipientIvkPacked: Uint8Array, counterpartyPk?: Uint8Array, ephSkOverride?: Uint8Array): Uint8Array;
+    encrypt(value: bigint, ownerPk: Uint8Array, blinding: Uint8Array, assetId: number, commitment: Uint8Array, recipientIvkPacked: Uint8Array, counterpartyPk?: Uint8Array, circuitVersion?: number, ephSkOverride?: Uint8Array): Uint8Array;
     /**
-     * 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: bigint, ownerPk: Uint8Array, blinding: Uint8Array, assetId: number, commitment: Uint8Array): Uint8Array;
+    encryptPublic(value: bigint, ownerPk: Uint8Array, blinding: Uint8Array, assetId: number, commitment: Uint8Array, circuitVersion?: number): Uint8Array;
     /**
-     * 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(): Uint8Array;
     /**
      * 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.
@@ -2407,7 +2519,7 @@ declare const 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().
      */
@@ -2416,13 +2528,13 @@ declare const 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: Uint8Array, viewingSecretKey: Uint8Array): Uint8Array | null;
@@ -2592,6 +2704,11 @@ declare function generateTransferProof(params: PrivateTransferProofInputs, optio
  *   2. The smallest pair whose sum >= needed →  [noteA, noteB]
  *   3. No combination covers needed          →  null  (consolidation via merge required)
  *
+ * Both inputs of a transfer are proven together against ONE circuit VK, so a
+ * pair MUST share a circuitVersion — mixing v1 and v2 would produce an invalid
+ * proof. Priority 2 only pairs notes of the same version; a single note (P1) is
+ * always one version so it needs no check.
+ *
  * Only unspent notes with value > 0 are considered.
  */
 declare function selectNotes(notes: ZkNote[], needed: bigint): [ZkNote, ZkNote | null] | null;
@@ -3303,18 +3420,22 @@ type CircuitId = (typeof CircuitId)[keyof typeof CircuitId];
 /**
  * Named constants for all supported ZK circuits.
  *
+ * Values MUST match the node's `CircuitId` constants
+ * (`node/frame/zk-verifier/src/types.rs`). Note: ValueProof is 6, not 4 or
+ * sequential.
+ *
  * | Name         | Value | Circuit                         |
  * |--------------|-------|---------------------------------|
  * | Transfer     | 1     | 2-in-2-out private transfer     |
  * | Unshield     | 2     | Withdrawal from the pool        |
- * | ValueProof   | 4     | Note value binding (fee-claim)  |
  * | PrivateLink  | 5     | Private chain-link proof        |
+ * | ValueProof   | 6     | Note value binding (fee-claim)  |
  */
 declare const CircuitId: {
     readonly Transfer: 1;
     readonly Unshield: 2;
-    readonly ValueProof: 4;
     readonly PrivateLink: 5;
+    readonly ValueProof: 6;
 };
 /**
  * A single verification key registration entry used in batch operations.
@@ -3955,10 +4076,11 @@ type AccountMappingEvent = {
  */
 type Bytes32 = number[];
 /**
- * 176-byte encrypted memo (ChaCha20-Poly1305 ECDH).
- * Layout: nonce(12) || ciphertext(132) || tag(16) || ephPk(32) = 176 bytes.
+ * 180-byte encrypted memo (ChaCha20-Poly1305 ECDH).
+ * Layout: nonce(12) || ciphertext(136) || ephPk(32) = 180 bytes
+ * (ciphertext = plaintext 120 + MAC 16).
  */
-type Bytes176 = number[];
+type Bytes180 = number[];
 /**
  * A single shield operation for use in `shield_batch`.
  */
@@ -3967,7 +4089,7 @@ type ShieldOperation = {
     amount: bigint;
     /** 32-byte Poseidon commitment (LE). */
     commitment: Bytes32;
-    /** Encrypted memo bytes — exactly 104 bytes. */
+    /** Encrypted memo bytes — exactly 180 bytes. */
     encryptedMemo: number[];
 };
 /**
@@ -3979,7 +4101,7 @@ type ShieldArgs = {
     amount: bigint;
     /** 32-byte Poseidon commitment (LE). */
     commitment: Bytes32;
-    /** Encrypted memo — exactly 104 bytes. */
+    /** Encrypted memo — exactly 180 bytes. */
     encryptedMemo: number[];
 };
 /**
@@ -4000,7 +4122,7 @@ type RawTransferInput = {
 type RawTransferOutput = {
     /** 32-byte Poseidon commitment (LE). */
     commitment: Bytes32;
-    /** Encrypted memo — exactly 104 bytes. */
+    /** Encrypted memo — exactly 180 bytes. */
     memo: number[];
 };
 /**
@@ -4021,6 +4143,8 @@ type PrivateTransferArgs = {
     assetId: number;
     /** Gasless fee in planck. Paid to the block author (validator). */
     fee: bigint;
+    /** Circuit version the input notes were created under (verified against that version's VK). */
+    circuitVersion: number;
 };
 /**
  * Call index 2 — `unshield` (Unsigned/gasless origin)
@@ -4048,10 +4172,12 @@ type UnshieldArgs = {
      */
     changeCommitment: Bytes32;
     /**
-     * Encrypted memo for the change note (176 bytes, empty for total unshield).
+     * Encrypted memo for the change note (180 bytes, empty for total unshield).
      * Enables note recovery via blockchain scan for partial unshield.
      */
-    changeEncryptedMemo?: Bytes176;
+    changeEncryptedMemo?: Bytes180;
+    /** Circuit version the spent note was created under (verified against that version's VK). */
+    circuitVersion: number;
 };
 /**
  * Call index 9 — `register_asset` (Root origin)
@@ -4577,4 +4703,4 @@ interface ExtrinsicFailedData {
     dispatch_info: DispatchInfo;
 }
 
-export { type AccountListing, type AccountMappedData, type AccountMappedEvent, type AccountMappingCall, type AccountMappingEvent, AccountMappingModule, AccountMappingPrecompile, type AccountMetadata, type AccountUnmappedEvent, type ActiveVersionSetEvent, type ActivityBucket, type AddChainLinkArgs, type AddChainLinkParams, type AddSupportedChainArgs, type AliasFullIdentity, type AliasInfo, type AliasListedForSaleEvent, type AliasOnSaleData, type AliasRegisteredData, type AliasRegisteredEvent, type AliasReleasedEvent, type AliasSaleCancelledEvent, type AliasSoldData, type AliasSoldEvent, type AliasTransferredData, type AliasTransferredEvent, type AssetRegisteredEvent, type AssetUnverifiedEvent, type AssetVerifiedEvent, BABYJUB_SUBORDER, BN254_R, type BatchRegisterVerificationKeysArgs, type BatchVerificationKeysRegisteredEvent, type BlockInfo, type BuyAliasArgs, type Bytes32, type ChainInfo, type ChainLink, type ChainLinkAddedEvent, type ChainLinkRemovedEvent, CircuitId, CircuitId as CircuitIdType, type ClaimShieldedFeesParams, type ClientProviderConfig, type CommitmentsInsertedEvent, type CommitmentsInsertedEventData, type ConnectionStatus, CryptoPrecompiles, type DecodedAddChainLinkArgs, type DecodedBatchArgs, type DecodedDispatchAsPrivateLinkArgs, type DecodedEthereumTransactArgs, type DecodedEvmCallArgs, type DecodedPrecompile, type DecodedPrivateTransferArgs, type DecodedPutAliasForSaleArgs, type DecodedRegisterAliasArgs, type DecodedRemarkArgs, type DecodedRevealPrivateLinkArgs, type DecodedSetAccountMetadataArgs, type DecodedShieldArgs, type DecodedShieldBatchArgs, type DecodedShieldBatchOperation, type DecodedSudoArgs, type DecodedTransferAllArgs, type DecodedTransferArgs, type DecodedTransferKeepAliveArgs, type DecodedUnshieldArgs, type DecryptedMemo, type DispatchAsLinkedAccountArgs, type DispatchAsLinkedParams, type DispatchAsPrivateLinkArgs, type DispatchError, type DispatchInfo, type DynamicBuilder, ENCRYPTED_MEMO_SIZE, EncryptedMemo, type EncryptedNoteRecord, type EndowedEventData, type EthereumExecutedData, type EventData, type EventPhase, type EventRecord, type EvmAddressInfo, type EvmBlock, EvmClient, type EvmExecutedData, type EvmExitReason, EvmExplorer, type EvmLog, type EvmSigner, type EvmTransaction, type EvmTxRequest, type EvmTxSummary, type ExtrinsicDecoder, type ExtrinsicFailedData, type ExtrinsicSuccessData, type FeeClaimProofInputs, type FormatOptions, type IndexedBlock, type IndexedEvmTx, type IndexedExtrinsic, type IndexedSession, type IndexedValidator, type IndexerActivity, IndexerClient, type IndexerClientConfig, type IndexerStats, KNOWN_PRECOMPILES, type KnownPrecompileInfo, type ListingInfo, type MerkleRoot, type MerkleRootUpdatedData, type MerkleRootUpdatedEvent, type MerkleTreeInfo, type MetadataUpdatedEvent, NoteBuilder, type NoteDisclosure, type NoteInput, type NoteStatusUpdate, type NullifierChunkInfo, type NullifierManifest, type NullifierStatusResult, type NullifierTail, type NullifiersSpentEvent, type NullifiersSpentEventData, OrbinumClient, type OrbinumClientConfig, OrbinumClientProvider, PRECOMPILE_ADDR, type PaginatedResult, PrivacyKeyManager, type PrivacyMerkleProof, PrivacyModule, type PrivateChainLinkAddedEvent, type PrivateChainLinkRemovedEvent, type PrivateChainLinkRevealedEvent, type PrivateLink, type PrivateLinkDispatchExecutedEvent, type PrivateTransferArgs, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PrivateTransferProofInputs, type PrivateTransferTimestamp, type ProofVerificationFailedEvent, type ProofVerifiedEvent, type ProxyCallExecutedEvent, type PutAliasOnSaleArgs, type PutOnSaleParams, type RawBlock, type RawBlockHeader, type RawTransferInput, type RawTransferOutput, type RegisterAliasArgs, type RegisterAssetArgs, type RegisterPrivateLinkArgs, type RegisterVerificationKeyArgs, type RegisteredAsset, type RelayFeeEvent, type RelayFeeSummaryEntry, type Relayer, type RelayerInfo, RelayerStatusModule, type RemoveChainLinkArgs, type RemovePrivateLinkArgs, type RemoveSupportedChainArgs, type RemoveVerificationKeyArgs, type ReservedEventData, type ResolvedAlias, type RevealPrivateLinkArgs, type RpcV2MerkleProof, type RpcV2NullifierStatus, type RpcV2PoolAssetBalance, type RpcV2PoolStats, SLIP0044_NAMESPACE, type ScanCommitment, type SetAccountMetadataArgs, type SetActiveVersionArgs, type SetMetadataParams, type ShieldArgs, type ShieldBatchArgs, type ShieldBatchItem, type ShieldBatchParams, type ShieldOperation, type ShieldParams, type ShieldedAddressEvent, type ShieldedCommitment, type ShieldedEvent, type ShieldedEventData, type ShieldedPoolCall, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, SignatureScheme, type SpentNullifier, type StatusChangeEvent, type StatusListener, type StealthScanHint, SubstrateClient, type SupportedChain, type SupportedChainAddedEvent, type SupportedChainRemovedEvent, type SystemHealth, type TokenInfo, type TokenTransfer, type TransferAliasArgs, type TransferEventData, type TransferInputNote, type TransferOutputNote, type TxResult, type UnsafeTxOptions, type Unshield, type UnshieldArgs, type UnshieldParams, type UnshieldProofInputs, type UnshieldedEvent, type UnshieldedEventData, type UnverifyAssetArgs, VaultLockedError, type VerificationKeyRegisteredEvent, type VerificationKeyRemovedEvent, type VerifyAssetArgs, type VerifyProofArgs, type VkEntry, type ZkNote, type ZkVerifierCall, type ZkVerifierCircuitVersionInfo, type ZkVerifierEvent, type ZkVerifierHistoricalVersion, ZkVerifierModule, type ZkVerifierVersionStats, type ZkVerifierVkHash, accountIdHexToSs58, addressToAccountIdHex, applyNoteStatus, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, blindTag, buildDummyTransferInput, bytesToBigintLE, computeNullifier, computePathIndices, createNoteDisclosureKey, decodeNoteDisclosureKey, decodePrecompileCalldata, decryptJson, decryptNoteRecord, deriveMasterKeyBytes, deriveOwnerPk, deriveSpendingKeyFromSignature, deriveSpendingKeyMessage, deriveStealthOwnerPk, deriveStealthSk, deriveVaultBlindKey, deriveVaultKey, deriveViewingPublicKey, deriveViewingSecretKey, encryptJson, encryptNote, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToMappedAccountHex, evmToSubstrate, formatBalance, formatORB, fromBase64, fromHex, generateFeeClaimProof, generateTransferProof, generateUnshieldProof, getPrecompileLabel, hexToBigint, hexToNumber, implicitSubstrateToEvm, isEvmAddress, isImplicitEvmAccount, isSs58, isSubstrateAddress, isUnifiedAddress, leHexToBigint, mapExtrinsicArgs, mapZkEventData, normalizeEvmAddress, noteBlindTag, randomBlinding, recoverOwnerPkPoint, selectNotes, shortHash, substrateSs58ToAccountIdHex, substrateToEvm, toBase64, toHex, toTxResult, truncateMiddle, tryDecryptNote, tryDecryptNoteVerbose, vaultReplacer, vaultReviver };
+export { type AccountListing, type AccountMappedData, type AccountMappedEvent, type AccountMappingCall, type AccountMappingEvent, AccountMappingModule, AccountMappingPrecompile, type AccountMetadata, type AccountUnmappedEvent, type ActiveVersionSetEvent, type ActivityBucket, type AddChainLinkArgs, type AddChainLinkParams, type AddSupportedChainArgs, type AliasFullIdentity, type AliasInfo, type AliasListedForSaleEvent, type AliasOnSaleData, type AliasRegisteredData, type AliasRegisteredEvent, type AliasReleasedEvent, type AliasSaleCancelledEvent, type AliasSoldData, type AliasSoldEvent, type AliasTransferredData, type AliasTransferredEvent, type AssetRegisteredEvent, type AssetUnverifiedEvent, type AssetVerifiedEvent, BABYJUB_SUBORDER, BN254_R, type BatchRegisterVerificationKeysArgs, type BatchVerificationKeysRegisteredEvent, type BlockInfo, type BuyAliasArgs, type Bytes32, CURRENT_CIRCUIT_VERSION, type ChainInfo, type ChainLink, type ChainLinkAddedEvent, type ChainLinkRemovedEvent, CircuitId, CircuitId as CircuitIdType, CircuitVersionResolver, type ClaimShieldedFeesParams, type ClientProviderConfig, type CommitmentsInsertedEvent, type CommitmentsInsertedEventData, type ConnectionStatus, CryptoPrecompiles, type DecodedAddChainLinkArgs, type DecodedBatchArgs, type DecodedDispatchAsPrivateLinkArgs, type DecodedEthereumTransactArgs, type DecodedEvmCallArgs, type DecodedPrecompile, type DecodedPrivateTransferArgs, type DecodedPutAliasForSaleArgs, type DecodedRegisterAliasArgs, type DecodedRemarkArgs, type DecodedRevealPrivateLinkArgs, type DecodedSetAccountMetadataArgs, type DecodedShieldArgs, type DecodedShieldBatchArgs, type DecodedShieldBatchOperation, type DecodedSudoArgs, type DecodedTransferAllArgs, type DecodedTransferArgs, type DecodedTransferKeepAliveArgs, type DecodedUnshieldArgs, type DecryptedMemo, type DispatchAsLinkedAccountArgs, type DispatchAsLinkedParams, type DispatchAsPrivateLinkArgs, type DispatchError, type DispatchInfo, type DynamicBuilder, ENCRYPTED_MEMO_SIZE, EncryptedMemo, type EncryptedNoteRecord, type EndowedEventData, type EthereumExecutedData, type EventData, type EventPhase, type EventRecord, type EvmAddressInfo, type EvmBlock, EvmClient, type EvmExecutedData, type EvmExitReason, EvmExplorer, type EvmLog, type EvmSigner, type EvmTransaction, type EvmTxRequest, type EvmTxSummary, type ExtrinsicDecoder, type ExtrinsicFailedData, type ExtrinsicSuccessData, type FeeClaimProofInputs, type FormatOptions, type IndexedBlock, type IndexedEvmTx, type IndexedExtrinsic, type IndexedSession, type IndexedValidator, type IndexerActivity, IndexerClient, type IndexerClientConfig, type IndexerStats, KNOWN_PRECOMPILES, type KnownPrecompileInfo, type ListingInfo, type MerkleRoot, type MerkleRootUpdatedData, type MerkleRootUpdatedEvent, type MerkleTreeInfo, type MetadataUpdatedEvent, NoteBuilder, type NoteDisclosure, type NoteInput, type NoteStatusUpdate, type NullifierChunkInfo, type NullifierManifest, type NullifierStatusResult, type NullifierTail, type NullifiersSpentEvent, type NullifiersSpentEventData, OrbinumClient, type OrbinumClientConfig, OrbinumClientProvider, PRECOMPILE_ADDR, type PaginatedResult, PrivacyKeyManager, type PrivacyMerkleProof, PrivacyModule, type PrivateChainLinkAddedEvent, type PrivateChainLinkRemovedEvent, type PrivateChainLinkRevealedEvent, type PrivateLink, type PrivateLinkDispatchExecutedEvent, type PrivateTransferArgs, type PrivateTransferInput, type PrivateTransferOutput, type PrivateTransferParams, type PrivateTransferProofInputs, type PrivateTransferTimestamp, type ProofVerificationFailedEvent, type ProofVerifiedEvent, type ProxyCallExecutedEvent, type PutAliasOnSaleArgs, type PutOnSaleParams, type RawBlock, type RawBlockHeader, type RawTransferInput, type RawTransferOutput, type RegisterAliasArgs, type RegisterAssetArgs, type RegisterPrivateLinkArgs, type RegisterVerificationKeyArgs, type RegisteredAsset, type RelayFeeEvent, type RelayFeeSummaryEntry, type Relayer, type RelayerInfo, RelayerStatusModule, type RemoveChainLinkArgs, type RemovePrivateLinkArgs, type RemoveSupportedChainArgs, type RemoveVerificationKeyArgs, type ReservedEventData, type ResolvedAlias, type ResolvedSpendVersion, type RevealPrivateLinkArgs, type RpcV2MerkleProof, type RpcV2NullifierStatus, type RpcV2PoolAssetBalance, type RpcV2PoolStats, SLIP0044_NAMESPACE, type ScanCommitment, type SetAccountMetadataArgs, type SetActiveVersionArgs, type SetMetadataParams, type ShieldArgs, type ShieldBatchArgs, type ShieldBatchItem, type ShieldBatchParams, type ShieldOperation, type ShieldParams, type ShieldedAddressEvent, type ShieldedCommitment, type ShieldedEvent, type ShieldedEventData, type ShieldedPoolCall, type ShieldedPoolEvent, ShieldedPoolModule, ShieldedPoolPrecompile, SignatureScheme, type SpentNullifier, type StatusChangeEvent, type StatusListener, type StealthScanHint, SubstrateClient, type SupportedChain, type SupportedChainAddedEvent, type SupportedChainRemovedEvent, type SystemHealth, type TokenInfo, type TokenTransfer, type TransferAliasArgs, type TransferEventData, type TransferInputNote, type TransferOutputNote, type TxResult, type UnsafeTxOptions, type Unshield, type UnshieldArgs, type UnshieldParams, type UnshieldProofInputs, type UnshieldedEvent, type UnshieldedEventData, type UnverifyAssetArgs, VaultLockedError, type VerificationKeyRegisteredEvent, type VerificationKeyRemovedEvent, type VerifyAssetArgs, type VerifyProofArgs, type VkEntry, type ZkNote, type ZkVerifierCall, type ZkVerifierCircuitVersionInfo, type ZkVerifierEvent, type ZkVerifierHistoricalVersion, ZkVerifierModule, type ZkVerifierVersionStats, type ZkVerifierVkHash, accountIdHexToSs58, addressToAccountIdHex, applyNoteStatus, bigintTo32Be, bigintTo32Le, bigintTo32LeArr, blindTag, buildDummyTransferInput, bytesToBigintLE, computeNullifier, computePathIndices, createNoteDisclosureKey, decodeNoteDisclosureKey, decodePrecompileCalldata, decryptJson, decryptNoteRecord, deriveMasterKeyBytes, deriveOwnerPk, deriveSpendingKeyFromSignature, deriveSpendingKeyMessage, deriveStealthOwnerPk, deriveStealthSk, deriveVaultBlindKey, deriveVaultKey, deriveViewingPublicKey, deriveViewingSecretKey, encryptJson, encryptNote, ensureHexPrefix, evmAddressToAccountId, evmToImplicitSubstrate, evmToMappedAccountHex, evmToSubstrate, formatBalance, formatORB, fromBase64, fromHex, generateFeeClaimProof, generateTransferProof, generateUnshieldProof, getPrecompileLabel, hexToBigint, hexToNumber, implicitSubstrateToEvm, isEvmAddress, isImplicitEvmAccount, isSs58, isSubstrateAddress, isUnifiedAddress, leHexToBigint, mapExtrinsicArgs, mapZkEventData, normalizeEvmAddress, noteBlindTag, randomBlinding, recoverOwnerPkPoint, selectNotes, shortHash, substrateSs58ToAccountIdHex, substrateToEvm, toBase64, toHex, toTxResult, truncateMiddle, tryDecryptNote, tryDecryptNoteVerbose, vaultReplacer, vaultReviver };