@cofhe/sdk 1.1.0-alpha.0 → 1.1.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @cofhe/sdk Changelog
 
+## 1.0.1
+
+### Patch Changes
+
+- fcc819c: **Breaking:** `encryptInputs(...).execute()` now binds the consuming contract into the ZK proof itself, and the CoFHE verifier requires it. Upgrade to 1.0.1: 1.0.0 is deprecated because of an issue in ZK verification, and once the verifier is updated a proof from 1.0.0 fails with `ZK_VERIFY_FAILED`. No code change is needed beyond the upgrade; `setConsumingContract(...)` was already required.
+
+  `execute()` now throws `CofheError` with code `CONSUMING_CONTRACT_INVALID` when `setConsumingContract(...)` was given something that is not an address, before TFHE is initialised or any proving starts. The check is byte-level, 20 bytes of hex in any case, and does not validate the EIP-55 checksum, so every address 1.0.0 accepted still passes. Previously the bad address reached the verifier and failed there, after the proof was generated. `CofheErrorCode` gains `ConsumingContractInvalid`; an exhaustive `switch` over the enum needs the new arm.
+
 ## 1.0.0
 
 ### Major Changes

package/core/decrypt/decryptForTxBuilder.ts

@@ -11,6 +11,7 @@ import { cofheMocksDecryptForTx } from './cofheMocksDecryptForTx';
 import { getPublicClientChainID, sleep } from '../utils';
 import { type DecryptPollCallbackFunction } from '../types';
 import { tnDecryptV2 } from './tnDecryptV2';
+import { assertDecryptTimeoutMs } from './submitRetry';
 
 const DEFAULT_404_RETRY_TIMEOUT_MS = 10_000;
 
@@ -65,6 +66,7 @@ export class DecryptForTxBuilder extends BaseBuilder {
   private acpSelection: DecryptForTxACPSelection = 'unset';
   private pollCallback?: DecryptPollCallbackFunction;
   private retry404TimeoutMs = DEFAULT_404_RETRY_TIMEOUT_MS;
+  private timeoutMs?: number;
 
   constructor(params: DecryptForTxBuilderParams) {
     super({
@@ -153,6 +155,19 @@ export class DecryptForTxBuilder extends BaseBuilder {
     return this;
   }
 
+  /**
+   * The whole budget of this decrypt in milliseconds, submit retries and status polling together
+   * (5 minutes by default). Past it, `execute()` rejects with `DecryptFailed`; a request still
+   * processing on the threshold network is not cancelled.
+   */
+  setTimeout(this: DecryptForTxBuilderUnset, timeoutMs: number): DecryptForTxBuilderUnset;
+  setTimeout(this: DecryptForTxBuilderSelected, timeoutMs: number): DecryptForTxBuilderSelected;
+  setTimeout(timeoutMs: number): DecryptForTxBuilder {
+    assertDecryptTimeoutMs(timeoutMs, 'decryptForTx');
+    this.timeoutMs = timeoutMs;
+    return this;
+  }
+
   /**
    * Select "use acp" mode.
    *
@@ -326,6 +341,7 @@ export class DecryptForTxBuilder extends BaseBuilder {
       acp: wireAcp,
       thresholdNetworkUrl,
       retry404TimeoutMs: this.retry404TimeoutMs,
+      timeoutMs: this.timeoutMs,
       onPoll: this.pollCallback,
     });
 

package/core/decrypt/decryptForViewBuilder.ts

@@ -13,6 +13,7 @@ import { cofheMocksDecryptForView } from './cofheMocksDecryptForView.js';
 import { tnSealOutputV2 } from './tnSealOutputV2.js';
 import { sleep } from '../utils.js';
 import { type DecryptPollCallbackFunction } from '../types.js';
+import { assertDecryptTimeoutMs } from './submitRetry.js';
 
 const DEFAULT_404_RETRY_TIMEOUT_MS = 10_000;
 
@@ -51,6 +52,7 @@ export class DecryptForViewBuilder<U extends FheTypes> extends BaseBuilder {
   private acp?: ACP;
   private pollCallback?: DecryptPollCallbackFunction;
   private retry404TimeoutMs = DEFAULT_404_RETRY_TIMEOUT_MS;
+  private timeoutMs?: number;
 
   constructor(params: DecryptForViewBuilderParams<U>) {
     super({
@@ -134,6 +136,17 @@ export class DecryptForViewBuilder<U extends FheTypes> extends BaseBuilder {
     return this;
   }
 
+  /**
+   * The whole budget of this decrypt in milliseconds, submit retries and status polling together
+   * (5 minutes by default). Past it, `execute()` rejects with `SealOutputFailed`; a request still
+   * processing on the threshold network is not cancelled.
+   */
+  setTimeout(timeoutMs: number): DecryptForViewBuilder<U> {
+    assertDecryptTimeoutMs(timeoutMs, 'decryptForView');
+    this.timeoutMs = timeoutMs;
+    return this;
+  }
+
   /**
    * Select "use acp" mode (optional).
    *
@@ -295,6 +308,7 @@ export class DecryptForViewBuilder<U extends FheTypes> extends BaseBuilder {
       acp: wireAcp,
       thresholdNetworkUrl,
       retry404TimeoutMs: this.retry404TimeoutMs,
+      timeoutMs: this.timeoutMs,
       onPoll: this.pollCallback,
     });
     return ACPUtils.unseal(acp, sealed);

package/core/decrypt/submitRetry.ts

@@ -2,6 +2,22 @@ import { CofheError, CofheErrorCode } from '../error.js';
 import { mapApiErrorCodeToCofheErrorCode, parseApiErrorResponseBody } from './apiError.js';
 
 export const DEFAULT_404_RETRY_TIMEOUT_MS = 10_000;
+/** The default budget of one decrypt, submit retries and status polling together. */
+export const DEFAULT_DECRYPT_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Validates a builder's `setTimeout(timeoutMs)` argument: the overall budget must be a positive,
+ * finite number of milliseconds (0 would time out before the first attempt).
+ */
+export function assertDecryptTimeoutMs(timeoutMs: number, operationLabel: string): void {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new CofheError({
+      code: CofheErrorCode.InternalError,
+      message: `${operationLabel}: setTimeout(timeoutMs) expects a finite number greater than 0.`,
+      context: { timeoutMs },
+    });
+  }
+}
 
 export type SubmitRetryableStatus = 204 | 404;
 

package/core/decrypt/tnDecryptV2.ts

@@ -6,12 +6,16 @@ import { type DecryptPollCallbackFunction } from '../types';
 import { normalizeTnSignature, parseDecryptedBytesToBigInt } from './tnDecryptUtils';
 import { computeMinuteRampPollIntervalMs } from './polling.js';
 import { mapApiErrorCodeToCofheErrorCode, parseApiErrorResponseBody } from './apiError.js';
-import { classifySubmitResponse, normalize404RetryTimeoutMs, throwIfSubmitRetryTimedOut } from './submitRetry.js';
+import {
+  DEFAULT_DECRYPT_TIMEOUT_MS,
+  classifySubmitResponse,
+  normalize404RetryTimeoutMs,
+  throwIfSubmitRetryTimedOut,
+} from './submitRetry.js';
 
 // Polling configuration
 const POLL_INTERVAL_MS = 1000; // 1 second
 const POLL_MAX_INTERVAL_MS = 10_000; // 10 seconds
-const DECRYPT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes total across submit + poll
 const SUBMIT_RETRY_INTERVAL_MS = 1000; // 1 second
 
 type DecryptSubmitResponseV2 = {
@@ -182,6 +186,7 @@ async function submitDecryptRequestV2(
   acp: ACPPublic | null,
   overallStartTime: number,
   retry404TimeoutMs: number,
+  timeoutMs: number,
   onPoll?: DecryptPollCallbackFunction
 ): Promise<DecryptSubmitResultV2> {
   const body: {
@@ -306,7 +311,7 @@ async function submitDecryptRequestV2(
       status: responseClassification.status,
       elapsedMs,
       retry404TimeoutMs,
-      overallTimeoutMs: DECRYPT_TIMEOUT_MS,
+      overallTimeoutMs: timeoutMs,
       thresholdNetworkUrl,
       body,
       attemptIndex,
@@ -319,7 +324,7 @@ async function submitDecryptRequestV2(
       attemptIndex,
       elapsedMs,
       intervalMs: SUBMIT_RETRY_INTERVAL_MS,
-      timeoutMs: DECRYPT_TIMEOUT_MS,
+      timeoutMs,
     });
 
     await new Promise((resolve) => setTimeout(resolve, SUBMIT_RETRY_INTERVAL_MS));
@@ -331,6 +336,7 @@ async function pollDecryptStatusV2(
   thresholdNetworkUrl: string,
   requestId: string,
   overallStartTime: number,
+  timeoutMs: number,
   onPoll?: DecryptPollCallbackFunction
 ): Promise<{ decryptedValue: bigint; signature: `0x${string}` }> {
   let attemptIndex = 0;
@@ -348,18 +354,18 @@ async function pollDecryptStatusV2(
       attemptIndex,
       elapsedMs,
       intervalMs,
-      timeoutMs: DECRYPT_TIMEOUT_MS,
+      timeoutMs,
     });
 
-    if (elapsedMs > DECRYPT_TIMEOUT_MS) {
+    if (elapsedMs > timeoutMs) {
       throw new CofheError({
         code: CofheErrorCode.DecryptFailed,
-        message: `decrypt polling timed out after ${DECRYPT_TIMEOUT_MS}ms`,
+        message: `decrypt polling timed out after ${timeoutMs}ms`,
         hint: 'The request may still be processing. Try again later.',
         context: {
           thresholdNetworkUrl,
           requestId,
-          timeoutMs: DECRYPT_TIMEOUT_MS,
+          timeoutMs,
         },
       });
     }
@@ -462,9 +468,12 @@ export async function tnDecryptV2(params: {
   acp: ACPPublic | null;
   thresholdNetworkUrl: string;
   retry404TimeoutMs?: number;
+  /** The whole budget, submit retries and status polling together; `DEFAULT_DECRYPT_TIMEOUT_MS` by default. */
+  timeoutMs?: number;
   onPoll?: DecryptPollCallbackFunction;
 }): Promise<{ decryptedValue: bigint; signature: `0x${string}` }> {
   const { thresholdNetworkUrl, ctHash, chainId, acp, retry404TimeoutMs, onPoll } = params;
+  const timeoutMs = params.timeoutMs ?? DEFAULT_DECRYPT_TIMEOUT_MS;
   const normalized404RetryTimeoutMs = normalize404RetryTimeoutMs({
     timeoutMs: retry404TimeoutMs,
     operationLabel: 'decrypt',
@@ -478,6 +487,7 @@ export async function tnDecryptV2(params: {
     acp,
     overallStartTime,
     normalized404RetryTimeoutMs,
+    timeoutMs,
     onPoll
   );
 
@@ -485,5 +495,5 @@ export async function tnDecryptV2(params: {
     return submitResult;
   }
 
-  return await pollDecryptStatusV2(thresholdNetworkUrl, submitResult.requestId, overallStartTime, onPoll);
+  return await pollDecryptStatusV2(thresholdNetworkUrl, submitResult.requestId, overallStartTime, timeoutMs, onPoll);
 }

package/core/decrypt/tnSealOutputV2.ts

@@ -5,13 +5,17 @@ import { CofheError, CofheErrorCode } from '../error.js';
 import { type DecryptPollCallbackFunction } from '../types.js';
 import { computeMinuteRampPollIntervalMs } from './polling.js';
 import { mapApiErrorCodeToCofheErrorCode, parseApiErrorResponseBody } from './apiError.js';
-import { classifySubmitResponse, normalize404RetryTimeoutMs, throwIfSubmitRetryTimedOut } from './submitRetry.js';
+import {
+  DEFAULT_DECRYPT_TIMEOUT_MS,
+  classifySubmitResponse,
+  normalize404RetryTimeoutMs,
+  throwIfSubmitRetryTimedOut,
+} from './submitRetry.js';
 import {} from './tnDecryptUtils.js';
 
 // Polling configuration
 const POLL_INTERVAL_MS = 1000; // 1 second
 const POLL_MAX_INTERVAL_MS = 10_000; // 10 seconds
-const SEAL_OUTPUT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes total across submit + poll
 const SUBMIT_RETRY_INTERVAL_MS = 1000; // 1 second
 
 // V2 API response types
@@ -141,6 +145,7 @@ async function submitSealOutputRequest(
   acp: ACPPublic,
   overallStartTime: number,
   retry404TimeoutMs: number,
+  timeoutMs: number,
   onPoll?: DecryptPollCallbackFunction
 ): Promise<SealOutputSubmitResult> {
   const body = {
@@ -254,7 +259,7 @@ async function submitSealOutputRequest(
       status: responseClassification.status,
       elapsedMs,
       retry404TimeoutMs,
-      overallTimeoutMs: SEAL_OUTPUT_TIMEOUT_MS,
+      overallTimeoutMs: timeoutMs,
       thresholdNetworkUrl,
       body,
       attemptIndex,
@@ -267,7 +272,7 @@ async function submitSealOutputRequest(
       attemptIndex,
       elapsedMs,
       intervalMs: SUBMIT_RETRY_INTERVAL_MS,
-      timeoutMs: SEAL_OUTPUT_TIMEOUT_MS,
+      timeoutMs,
     });
 
     await new Promise((resolve) => setTimeout(resolve, SUBMIT_RETRY_INTERVAL_MS));
@@ -282,6 +287,7 @@ async function pollSealOutputStatus(
   thresholdNetworkUrl: string,
   requestId: string,
   overallStartTime: number,
+  timeoutMs: number,
   onPoll?: DecryptPollCallbackFunction
 ): Promise<EthEncryptedData> {
   let attemptIndex = 0;
@@ -299,19 +305,19 @@ async function pollSealOutputStatus(
       attemptIndex,
       elapsedMs,
       intervalMs,
-      timeoutMs: SEAL_OUTPUT_TIMEOUT_MS,
+      timeoutMs,
     });
 
     // Check timeout
-    if (elapsedMs > SEAL_OUTPUT_TIMEOUT_MS) {
+    if (elapsedMs > timeoutMs) {
       throw new CofheError({
         code: CofheErrorCode.SealOutputFailed,
-        message: `sealOutput polling timed out after ${SEAL_OUTPUT_TIMEOUT_MS}ms`,
+        message: `sealOutput polling timed out after ${timeoutMs}ms`,
         hint: 'The request may still be processing. Try again later.',
         context: {
           thresholdNetworkUrl,
           requestId,
-          timeoutMs: SEAL_OUTPUT_TIMEOUT_MS,
+          timeoutMs,
         },
       });
     }
@@ -416,9 +422,12 @@ export async function tnSealOutputV2(params: {
   acp: ACPPublic;
   thresholdNetworkUrl: string;
   retry404TimeoutMs?: number;
+  /** The whole budget, submit retries and status polling together; `DEFAULT_DECRYPT_TIMEOUT_MS` by default. */
+  timeoutMs?: number;
   onPoll?: DecryptPollCallbackFunction;
 }): Promise<EthEncryptedData> {
   const { thresholdNetworkUrl, ctHash, chainId, acp, retry404TimeoutMs, onPoll } = params;
+  const timeoutMs = params.timeoutMs ?? DEFAULT_DECRYPT_TIMEOUT_MS;
   const normalized404RetryTimeoutMs = normalize404RetryTimeoutMs({
     timeoutMs: retry404TimeoutMs,
     operationLabel: 'sealOutput',
@@ -434,6 +443,7 @@ export async function tnSealOutputV2(params: {
     acp,
     overallStartTime,
     normalized404RetryTimeoutMs,
+    timeoutMs,
     onPoll
   );
 
@@ -442,5 +452,5 @@ export async function tnSealOutputV2(params: {
   }
 
   // Step 2: Poll for status until completed
-  return await pollSealOutputStatus(thresholdNetworkUrl, submitResult.requestId, overallStartTime, onPoll);
+  return await pollSealOutputStatus(thresholdNetworkUrl, submitResult.requestId, overallStartTime, timeoutMs, onPoll);
 }

package/core/encrypt/encryptInputsBuilder.ts

@@ -21,7 +21,7 @@ import { cofheMocksCheckEncryptableBits, cofheMocksZkVerifySign } from './cofheM
 import { hardhat } from 'viem/chains';
 import { fetchKeys, type FheKeyDeserializer } from '../fetchKeys.js';
 import { getZkVerifierUrlOrThrow } from '../config.js';
-import { type WalletClient } from 'viem';
+import { type WalletClient, isAddress } from 'viem';
 import { sleep } from '../utils.js';
 import { BaseBuilder, type BaseBuilderParams } from '../baseBuilder.js';
 import { type KeysStorage } from '../keyStore.js';
@@ -256,19 +256,37 @@ export class EncryptInputsBuilder<T extends EncryptableItem[]> extends BaseBuild
   }
 
   /**
-   * Asserts that this.consumingContract is populated
-   * @throws {CofheError} If consumingContract is not set
+   * Asserts that this.consumingContract is populated and is an address.
+   * Runs before TFHE init, key fetching and proving, so a bad address costs
+   * nothing: the contract is bound into the proof, and a proof built for a
+   * non-address could only fail at the verifier, after the expensive step.
+   * @throws {CofheError} If consumingContract is not set or is not an address
    */
   private assertConsumingContract(): asserts this is this & { consumingContract: string } {
-    if (this.consumingContract) return;
-    throw new CofheError({
-      code: CofheErrorCode.ConsumingContractUninitialized,
-      message: 'Consuming contract is not set',
-      hint: 'Use setConsumingContract(...) to set the contract that will consume the encrypted inputs.',
-      context: {
-        consumingContract: this.consumingContract,
-      },
-    });
+    if (!this.consumingContract) {
+      throw new CofheError({
+        code: CofheErrorCode.ConsumingContractUninitialized,
+        message: 'Consuming contract is not set',
+        hint: 'Use setConsumingContract(...) to set the contract that will consume the encrypted inputs.',
+        context: {
+          consumingContract: this.consumingContract,
+        },
+      });
+    }
+    // strict: false — 20 bytes of hex in any case, no EIP-55 checksum check. The
+    // verifier decodes the address case-insensitively and the chain compares bytes,
+    // so a mixed-case address with a wrong checksum works end to end and a patch
+    // release must keep accepting it.
+    if (!isAddress(this.consumingContract, { strict: false })) {
+      throw new CofheError({
+        code: CofheErrorCode.ConsumingContractInvalid,
+        message: 'Consuming contract is not an address',
+        hint: 'setConsumingContract(...) takes the 20-byte address of the contract that will consume the encrypted inputs.',
+        context: {
+          consumingContract: this.consumingContract,
+        },
+      });
+    }
   }
 
   /**
@@ -567,7 +585,7 @@ export class EncryptInputsBuilder<T extends EncryptableItem[]> extends BaseBuild
     this.fireStepStart(EncryptStep.Prove);
 
     // Construct metadata once (used by both worker and main thread paths)
-    const metadata = constructZkPoKMetadata(this.account, this.securityZone, this.chainId);
+    const metadata = constructZkPoKMetadata(this.account, this.securityZone, this.chainId, this.consumingContract);
 
     let proof: Uint8Array | null = null;
     let usedWorker = false;

package/core/encrypt/zkPackProveVerify.ts

@@ -239,13 +239,24 @@ export const zkProve = async (
 };
 
 /**
- * Constructs the ZK Proof of Knowledge metadata for the proof
+ * Constructs the ZK Proof of Knowledge metadata for the proof:
+ * `securityZone (1) || account (20) || chainId (32, big-endian) || consumingContract (20)`.
+ *
+ * The verifier rebuilds the same bytes from the request fields before it checks the proof, so the
+ * proof is bound to the consuming contract itself, not only to the signature the verifier returns.
  * @internal - Used internally within the encrypt module
  */
-export const constructZkPoKMetadata = (accountAddr: string, securityZone: number, chainId: number): Uint8Array => {
-  // Decode the account address from hex
+export const constructZkPoKMetadata = (
+  accountAddr: string,
+  securityZone: number,
+  chainId: number,
+  consumingContract: string
+): Uint8Array => {
+  // Decode the account and contract addresses from hex
   const accountAddrNoPrefix = accountAddr.startsWith('0x') ? accountAddr.slice(2) : accountAddr;
   const accountBytes = hexToBytes(accountAddrNoPrefix);
+  const contractNoPrefix = consumingContract.startsWith('0x') ? consumingContract.slice(2) : consumingContract;
+  const contractBytes = hexToBytes(contractNoPrefix);
 
   // Encode chainId as 32 bytes (u256) in big-endian format
   const chainIdBytes = new Uint8Array(32);
@@ -259,10 +270,11 @@ export const constructZkPoKMetadata = (accountAddr: string, securityZone: number
     value = value >>> 8;
   }
 
-  const metadata = new Uint8Array(1 + accountBytes.length + 32);
+  const metadata = new Uint8Array(1 + accountBytes.length + 32 + contractBytes.length);
   metadata[0] = securityZone;
   metadata.set(accountBytes, 1);
   metadata.set(chainIdBytes, 1 + accountBytes.length);
+  metadata.set(contractBytes, 1 + accountBytes.length + 32);
 
   return metadata;
 };

package/core/error.ts

@@ -16,6 +16,7 @@ export enum CofheErrorCode {
   AccountUninitialized = 'ACCOUNT_UNINITIALIZED',
   ChainIdUninitialized = 'CHAIN_ID_UNINITIALIZED',
   ConsumingContractUninitialized = 'CONSUMING_CONTRACT_UNINITIALIZED',
+  ConsumingContractInvalid = 'CONSUMING_CONTRACT_INVALID',
   SealOutputFailed = 'SEAL_OUTPUT_FAILED',
   SealOutputReturnedNull = 'SEAL_OUTPUT_RETURNED_NULL',
   InvalidUtype = 'INVALID_UTYPE',

package/core/test/decryptBuilders.test.ts

@@ -224,6 +224,21 @@ describe('DecryptForTxBuilder', () => {
 
       expect(() => builder.set404RetryTimeout(-1)).toThrow('set404RetryTimeout(timeoutMs) expects');
     });
+
+    it('should allow configuring the overall timeout', () => {
+      const builder = createTxBuilder();
+      const result = builder.setTimeout(20_000);
+
+      expect(result).toBe(builder);
+      expect((builder as any).timeoutMs).toBe(20_000);
+    });
+
+    it('should throw for an overall timeout that is not a positive number', () => {
+      const builder = createTxBuilder();
+
+      expect(() => builder.setTimeout(0)).toThrow('setTimeout(timeoutMs) expects');
+      expect(() => builder.setTimeout(Number.NaN)).toThrow('setTimeout(timeoutMs) expects');
+    });
   });
 
   // --- execute error paths ---
@@ -367,6 +382,21 @@ describe('DecryptForViewBuilder', () => {
 
       expect(() => builder.set404RetryTimeout(-1)).toThrow('set404RetryTimeout(timeoutMs) expects');
     });
+
+    it('should allow configuring the overall timeout', () => {
+      const builder = createViewBuilder(FheTypes.Uint32);
+      const result = builder.setTimeout(20_000);
+
+      expect(result).toBe(builder);
+      expect((builder as any).timeoutMs).toBe(20_000);
+    });
+
+    it('should throw for an overall timeout that is not a positive number', () => {
+      const builder = createViewBuilder(FheTypes.Uint32);
+
+      expect(() => builder.setTimeout(0)).toThrow('setTimeout(timeoutMs) expects');
+      expect(() => builder.setTimeout(-5)).toThrow('setTimeout(timeoutMs) expects');
+    });
   });
 
   // --- execute error paths ---
@@ -503,6 +533,16 @@ describe('execute – expired acp (regression, issue #272)', () => {
       expect(result.decryptedValue).toBe(7n);
       expect(tnDecryptV2).toHaveBeenCalledOnce();
     });
+
+    it('passes the overall timeout to the threshold network call', async () => {
+      vi.mocked(tnDecryptV2).mockResolvedValue({ decryptedValue: 7n, signature: '0x1234' });
+      const acp = createSignedSelfACP(now() + 3600);
+      seedACP(acp);
+
+      await selectTxACP('active acp', acp).setTimeout(20_000).execute();
+
+      expect(tnDecryptV2).toHaveBeenCalledWith(expect.objectContaining({ timeoutMs: 20_000 }));
+    });
   });
 
   describe('decryptForView', () => {
@@ -522,5 +562,16 @@ describe('execute – expired acp (regression, issue #272)', () => {
       await expect(selectViewACP('active acp', acp).execute()).rejects.toThrow('stubbed threshold network');
       expect(tnSealOutputV2).toHaveBeenCalledOnce();
     });
+
+    it('passes the overall timeout to the threshold network call', async () => {
+      vi.mocked(tnSealOutputV2).mockRejectedValue(new Error('stubbed threshold network'));
+      const acp = createSignedSelfACP(now() + 3600);
+      seedACP(acp);
+
+      await expect(selectViewACP('active acp', acp).setTimeout(20_000).execute()).rejects.toThrow(
+        'stubbed threshold network'
+      );
+      expect(tnSealOutputV2).toHaveBeenCalledWith(expect.objectContaining({ timeoutMs: 20_000 }));
+    });
   });
 });

package/core/test/encryptInputsBuilder.test.ts

@@ -10,7 +10,7 @@ import {
 } from '../types.js';
 import { CofheError, CofheErrorCode } from '../error.js';
 import { fromHexString, toHexString } from '../utils.js';
-import { type PublicClient, createPublicClient, http, type WalletClient, createWalletClient } from 'viem';
+import { type PublicClient, createPublicClient, http, type WalletClient, createWalletClient, isAddress } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { arbitrumSepolia } from 'viem/chains';
 import { type CofheConfig, createCofheConfigBase } from '../config.js';
@@ -53,9 +53,9 @@ const unpackMetadata = (metadata: string) => {
 
 export const deconstructZkPoKMetadata = (
   metadata: Uint8Array
-): { accountAddr: string; securityZone: number; chainId: number } => {
-  if (metadata.length < 53) {
-    // 1 + 20 + 32 = 53 bytes minimum
+): { accountAddr: string; securityZone: number; chainId: number; contractAddr: string } => {
+  if (metadata.length < 73) {
+    // 1 + 20 + 32 + 20 = 73 bytes minimum
     throw new CofheError({
       code: CofheErrorCode.InternalError,
       message: 'Invalid metadata: insufficient length',
@@ -78,10 +78,14 @@ export const deconstructZkPoKMetadata = (
     chainId = (chainId << 8) | chainIdBytes[i];
   }
 
+  // Extract the consuming contract (last 20 bytes)
+  const contractAddr = '0x' + toHexString(metadata.slice(53, 73));
+
   return {
     accountAddr,
     securityZone,
     chainId,
+    contractAddr,
   };
 };
 
@@ -445,6 +449,38 @@ describe('EncryptInputsBuilder', () => {
         expect((error as CofheError).code).toBe(CofheErrorCode.ConsumingContractUninitialized);
       }
     });
+
+    it('accepts a mixed-case consuming contract whose checksum is wrong', async () => {
+      // The verifier decodes the address case-insensitively and the chain compares
+      // 20 bytes, so a 1.0.0 dApp with such an address must keep working.
+      const wrongChecksum = '0xBEEFbeefBEEFbeefBEEFbeefBEEFbeefBEEFbeef';
+      expect(isAddress(wrongChecksum)).toBe(false);
+      expect(isAddress(wrongChecksum, { strict: false })).toBe(true);
+
+      const result = await new EncryptInputsBuilder(createDefaultParams())
+        .setConsumingContract(wrongChecksum)
+        .execute();
+
+      expect(Array.isArray(result)).toBe(true);
+    });
+
+    it('rejects a consuming contract that is not an address before any encrypt step runs', async () => {
+      for (const notAnAddress of ['0x0', 'not-an-address', '0xbeefbeefbeefbeefbeefbeefbeefbeefbeefbee']) {
+        const steps = vi.fn();
+        const invalid = new EncryptInputsBuilder(createDefaultParams())
+          .setConsumingContract(notAnAddress)
+          .onStep(steps);
+        try {
+          await invalid.execute();
+          expect.unreachable(`execute() should have thrown for ${notAnAddress}`);
+        } catch (error) {
+          expect(error, notAnAddress).toBeInstanceOf(CofheError);
+          expect((error as CofheError).code, notAnAddress).toBe(CofheErrorCode.ConsumingContractInvalid);
+        }
+        // Rejected before initTfhe, so no step (and no proving) ever started.
+        expect(steps, notAnAddress).not.toHaveBeenCalled();
+      }
+    });
   });
 
   describe('zkVerifierUrl', () => {
@@ -595,6 +631,22 @@ describe('EncryptInputsBuilder', () => {
       expect(encryptedMetadata.chainId).toBe(defaultChainId);
     });
 
+    it('binds the consuming contract into the proof metadata', async () => {
+      mockFetch.mockClear();
+
+      await builder.execute();
+
+      const verifyCall = mockFetch.mock.calls.find(([url]) => url === `${MockZkVerifierUrl}/verifyBatch`);
+      expect(verifyCall).toBeDefined();
+      const body = JSON.parse(verifyCall![1].body as string);
+      const { metadata } = parseWithBigInt(new TextDecoder().decode(fromHexString(body.packed_list)));
+      const embedded = deconstructZkPoKMetadata(Uint8Array.from(Object.values(metadata) as number[]));
+      expect(embedded.accountAddr).toBe(defaultSender);
+      expect(embedded.securityZone).toBe(0);
+      expect(embedded.chainId).toBe(defaultChainId);
+      expect(embedded.contractAddr).toBe(defaultConsumingContract);
+    });
+
     it('should use overridden account when set', async () => {
       const overriddenSender = '0x5555555555555555555555555555555555555555';
       builder.setAccount(overriddenSender);

package/core/test/zkPoKMetadata.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { constructZkPoKMetadata } from '../encrypt/zkPackProveVerify.js';
+import { toHexString } from '../utils.js';
+
+describe('constructZkPoKMetadata', () => {
+  const account = '0x1234567890123456789012345678901234567890';
+  const contract = '0xbeefbeefbeefbeefbeefbeefbeefbeefbeefbeef';
+
+  it('lays out security zone, account, chain id and the consuming contract', () => {
+    const metadata = constructZkPoKMetadata(account, 3, 0x010203, contract);
+
+    expect(metadata.length).toBe(1 + 20 + 32 + 20);
+    expect(metadata[0]).toBe(3);
+    expect('0x' + toHexString(metadata.slice(1, 21))).toBe(account);
+    const chainId = metadata.slice(21, 53);
+    expect(Array.from(chainId.slice(0, 29))).toEqual(new Array(29).fill(0));
+    expect(Array.from(chainId.slice(29))).toEqual([1, 2, 3]);
+    expect('0x' + toHexString(metadata.slice(53))).toBe(contract);
+  });
+
+  it('accepts the consuming contract with or without the 0x prefix', () => {
+    const withPrefix = constructZkPoKMetadata(account, 0, 1, contract);
+    const withoutPrefix = constructZkPoKMetadata(account, 0, 1, contract.slice(2));
+
+    expect(Array.from(withoutPrefix)).toEqual(Array.from(withPrefix));
+  });
+});

package/dist/acps.js

@@ -1,2 +1,2 @@
-export { ACPScope, ACPUtils, ACP_REVOKER_ABI, ACP_SHARE_REGISTRY_ABI, ACP_SHARE_TUPLE_ABI, ACP_STORE_DEFAULTS, ERC7984_ABI, GenerateSealingKey, ImportACPOptionsValidator, ImportACPValidator, LAYOUT_VERSION as SHARE_METADATA_VERSION, SelfACPOptionsValidator, SelfACPValidator, SharingACPOptionsValidator, SharingACPValidator, SignatureTypes, SignatureUtils, UNLABELLED, ValidationUtils, _acpStore, acpStore, addressNotZeroSchema, addressSchema, bytesNotEmptySchema, bytesSchema, clearAclServedAddresses, clearStaleStore, computeShareId, contractsSchema, decodeShareAppKey, decodeShareMetadata, decodeShareMetadataFull, describeShareLabels, describeShareMetadata, encodeShareMetadata, eventLogLabel, getACP, getACPs, getAclAddress, getAclServedAddresses, getActiveACP, getActiveACPHash, getSignatureTypesAndMessage, handlesSchema, readPostedShares, readShare, readSharesFor, removeACP, removeActiveACPHash, resetStore, seal, setACP, setActiveACPHash, shareAppKey, shareIdOfChainShare, toChainShare, unsealWithPrivateKey, validateImportACP, validateImportACPOptions, validateSelfACP, validateSelfACPOptions, validateSharingACP, validateSharingACPOptions, verifyShareLabel, verifyShareLabels, viewFunctionLabel } from './chunk-3L2IVPMI.js';
-import './chunk-J23FYAI2.js';
+export { ACPScope, ACPUtils, ACP_REVOKER_ABI, ACP_SHARE_REGISTRY_ABI, ACP_SHARE_TUPLE_ABI, ACP_STORE_DEFAULTS, ERC7984_ABI, GenerateSealingKey, ImportACPOptionsValidator, ImportACPValidator, LAYOUT_VERSION as SHARE_METADATA_VERSION, SelfACPOptionsValidator, SelfACPValidator, SharingACPOptionsValidator, SharingACPValidator, SignatureTypes, SignatureUtils, UNLABELLED, ValidationUtils, _acpStore, acpStore, addressNotZeroSchema, addressSchema, bytesNotEmptySchema, bytesSchema, clearAclServedAddresses, clearStaleStore, computeShareId, contractsSchema, decodeShareAppKey, decodeShareMetadata, decodeShareMetadataFull, describeShareLabels, describeShareMetadata, encodeShareMetadata, eventLogLabel, getACP, getACPs, getAclAddress, getAclServedAddresses, getActiveACP, getActiveACPHash, getSignatureTypesAndMessage, handlesSchema, readPostedShares, readShare, readSharesFor, removeACP, removeActiveACPHash, resetStore, seal, setACP, setActiveACPHash, shareAppKey, shareIdOfChainShare, toChainShare, unsealWithPrivateKey, validateImportACP, validateImportACPOptions, validateSelfACP, validateSelfACPOptions, validateSharingACP, validateSharingACPOptions, verifyShareLabel, verifyShareLabels, viewFunctionLabel } from './chunk-WAA2U7CT.js';
+import './chunk-OC5TGQGG.js';

package/dist/{chunk-WJGTPW7K.js → chunk-3SD2UCRE.js}

@@ -1,4 +1,4 @@
-import { CofheError } from './chunk-J23FYAI2.js';
+import { CofheError } from './chunk-OC5TGQGG.js';
 import 'viem';
 
 // core/types.ts