@cofhe/sdk 0.7.0 → 0.8.0

package/core/index.ts

@@ -62,6 +62,9 @@ export type {
   // Util types
   EncryptStepCallbackFunction as EncryptSetStateFn,
   EncryptStepCallbackContext,
+  // tfhe init types
+  TfheInitializer,
+  TfheThreadsSetting,
 } from './types.js';
 export {
   FheTypes,
@@ -103,7 +106,9 @@ export { zkProveWithWorker } from './encrypt/zkPackProveVerify.js';
 
 // Consts (contract addresses, serialized size limits)
 export {
-  TASK_MANAGER_ADDRESS,
+  COFHE_ADDRESS_BOOK_ADDRESS,
+  TASK_MANAGER_ID,
+  MOCKS_TASK_MANAGER_ADDRESS,
   MOCKS_ZK_VERIFIER_ADDRESS,
   MOCKS_ZK_VERIFIER_SIGNER_ADDRESS,
   MOCKS_ZK_VERIFIER_SIGNER_PRIVATE_KEY,
@@ -113,6 +118,9 @@ export {
   TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT,
 } from './consts.js';
 
+// Task Manager resolution (CoFHEAddressBook)
+export { getTaskManagerAddress } from './taskManager.js';
+
 // Decrypt result verification
 export { verifyDecryptResult } from './decrypt/verifyDecryptResult.js';
 

package/core/keyStore.ts

@@ -11,15 +11,15 @@ type SecurityZoneRecord<T> = Record<number, T>;
 // Keys store for FHE keys and CRS
 export type KeysStore = {
   fhe: ChainRecord<SecurityZoneRecord<string | undefined>>;
-  crs: ChainRecord<string | undefined>;
+  crs: ChainRecord<SecurityZoneRecord<string | undefined>>;
 };
 
 export type KeysStorage = {
   store: StoreApi<KeysStore>;
   getFheKey: (chainId: number | undefined, securityZone?: number) => string | undefined;
-  getCrs: (chainId: number | undefined) => string | undefined;
+  getCrs: (chainId: number | undefined, securityZone?: number) => string | undefined;
   setFheKey: (chainId: number, securityZone: number, key: string) => void;
-  setCrs: (chainId: number, crs: string) => void;
+  setCrs: (chainId: number, securityZone: number, crs: string) => void;
   clearKeysStorage: () => Promise<void>;
   rehydrateKeysStore: () => Promise<void>;
 };
@@ -45,6 +45,10 @@ const DEFAULT_KEYS_STORE: KeysStore = {
   crs: {},
 };
 
+function isSecurityZoneRecord(value: unknown): value is SecurityZoneRecord<string | undefined> {
+  return value != null && typeof value === 'object';
+}
+
 type StoreWithPersist = ReturnType<typeof createStoreWithPersit>;
 
 function isStoreWithPersist(store: StoreApi<KeysStore> | StoreWithPersist): store is StoreWithPersist {
@@ -72,9 +76,9 @@ export function createKeysStore(storage: IStorage | null): KeysStorage {
     return stored;
   };
 
-  const getCrs = (chainId: number | undefined) => {
-    if (chainId == null) return undefined;
-    const stored = keysStore.getState().crs[chainId];
+  const getCrs = (chainId: number | undefined, securityZone = 0) => {
+    if (chainId == null || securityZone == null) return undefined;
+    const stored = keysStore.getState().crs[chainId]?.[securityZone];
     return stored;
   };
 
@@ -87,10 +91,11 @@ export function createKeysStore(storage: IStorage | null): KeysStorage {
     );
   };
 
-  const setCrs = (chainId: number, crs: string) => {
+  const setCrs = (chainId: number, securityZone: number, crs: string) => {
     keysStore.setState(
       produce<KeysStore>((state: KeysStore) => {
-        state.crs[chainId] = crs;
+        if (state.crs[chainId] == null) state.crs[chainId] = {};
+        state.crs[chainId][securityZone] = crs;
       })
     );
   };
@@ -143,8 +148,16 @@ function createStoreWithPersit(storage: IStorage) {
           mergedFhe[chainId] = { ...persistedZones, ...currentZones };
         }
 
-        // Deep merge for crs
-        const mergedCrs: KeysStore['crs'] = { ...persisted.crs, ...current.crs };
+        // Deep merge for crs. A `crs` persisted before it was keyed by security zone holds a
+        // bare string per chain; those entries are dropped so the CRS is refetched per zone
+        // rather than indexed as a string.
+        const mergedCrs: KeysStore['crs'] = {};
+        const allCrsChainIds = new Set([...Object.keys(current.crs), ...Object.keys(persisted.crs)]);
+        for (const chainId of allCrsChainIds) {
+          const persistedZones = isSecurityZoneRecord(persisted.crs[chainId]) ? persisted.crs[chainId] : {};
+          const currentZones = isSecurityZoneRecord(current.crs[chainId]) ? current.crs[chainId] : {};
+          mergedCrs[chainId] = { ...persistedZones, ...currentZones };
+        }
 
         return {
           fhe: mergedFhe,

package/core/taskManager.ts

@@ -0,0 +1,48 @@
+import { parseAbi, type Address, type PublicClient } from 'viem';
+
+import { COFHE_ADDRESS_BOOK_ADDRESS, TASK_MANAGER_ID } from './consts.js';
+import { CofheError, CofheErrorCode } from './error.js';
+
+const ADDRESS_BOOK_ABI = parseAbi([
+  'function getTm(uint256 id) view returns (address)',
+  'error TaskManagerNotSet(uint256 id)',
+]);
+
+const taskManagerAddressCache = new Map<number, Promise<Address>>();
+
+/** Test hook: forget resolved addresses (e.g. between redeployments on one chainId). */
+export const clearTaskManagerAddressCache = () => taskManagerAddressCache.clear();
+
+/**
+ * The chain's Task Manager, resolved through the CoFHEAddressBook
+ * (`getTm(TASK_MANAGER_ID)`) - the same lookup FHE.sol performs on every call.
+ *
+ * Resolutions are cached per chainId. A failed resolution (network error, no
+ * CoFHE deployment, id unset) is NOT cached, so a later call retries.
+ */
+export const getTaskManagerAddress = async (publicClient: PublicClient, chainId?: number): Promise<Address> => {
+  const id = chainId ?? publicClient.chain?.id ?? (await publicClient.getChainId());
+
+  const cached = taskManagerAddressCache.get(id);
+  if (cached != null) return cached;
+
+  const pending = publicClient
+    .readContract({
+      address: COFHE_ADDRESS_BOOK_ADDRESS,
+      abi: ADDRESS_BOOK_ABI,
+      functionName: 'getTm',
+      args: [TASK_MANAGER_ID],
+    })
+    .catch((error: unknown) => {
+      taskManagerAddressCache.delete(id);
+      throw CofheError.fromError(error, {
+        code: CofheErrorCode.TaskManagerUnresolved,
+        message: `Failed to resolve the Task Manager from the CoFHEAddressBook on chain ${id}`,
+        hint: 'Ensure CoFHE is deployed on this chain. On a local hardhat / anvil chain, deploy the CoFHE mocks first.',
+        context: { chainId: id, addressBook: COFHE_ADDRESS_BOOK_ADDRESS, taskManagerId: TASK_MANAGER_ID },
+      });
+    });
+
+  taskManagerAddressCache.set(id, pending);
+  return pending;
+};

package/core/test/acps.test.ts

@@ -1,7 +1,7 @@
 /**
  * @vitest-environment happy-dom
  */
-import { acpStore } from '@/acps';
+import { ACPUtils, acpStore, type IncomingShare, type SharingACP } from '@/acps';
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 
@@ -152,6 +152,96 @@ describe('Core ACPs Tests', () => {
     });
   });
 
+  describe('checkAccess on the issuer copy of a share', () => {
+    it('is valid while unexpired and not revoked, without needing the recipient signature', async () => {
+      const sharing = await acps.createSharing(
+        { name: 'To Alice', issuer: bobAddress, recipient: aliceAddress },
+        publicClient,
+        bobWalletClient
+      );
+      expect(sharing.recipientSignature).toBe('0x');
+      // No revoker configured here, so nothing on chain can disable it: valid without any RPC.
+      expect(await acps.checkAccess(sharing, publicClient)).toBe('valid');
+    });
+
+    it('reports expiry locally', async () => {
+      const sharing = await acps.createSharing(
+        { name: 'Old', issuer: bobAddress, recipient: aliceAddress, expiration: 1 },
+        publicClient,
+        bobWalletClient
+      );
+      expect(await acps.checkAccess(sharing, publicClient)).toBe('expired');
+    });
+  });
+
+  describe('Import without activation', () => {
+    const ZERO_SHARE_ID = `0x${'0'.repeat(64)}` as const;
+
+    // Alice already decrypts with her own self acp; Bob then shares with her.
+    const setUp = async () => {
+      const self = await acps.createSelf({ name: 'Alice self', issuer: aliceAddress }, publicClient, aliceWalletClient);
+      const sharing = await acps.createSharing(
+        { name: 'Shared with Alice', issuer: bobAddress, recipient: aliceAddress },
+        publicClient,
+        bobWalletClient
+      );
+      return { self, sharing };
+    };
+
+    const toIncomingShare = (sharing: SharingACP): IncomingShare => {
+      const { sealingKey: _sealingKey, recipientSignature: _recipientSignature, ...pub } = ACPUtils.getPublic(sharing);
+      return { ...pub, shareId: ZERO_SHARE_ID };
+    };
+
+    it('importShared activates the imported acp by default', async () => {
+      const { sharing } = await setUp();
+      const imported = await acps.importShared(ACPUtils.export(sharing), publicClient, aliceWalletClient);
+
+      expect(acps.getActiveACPHash(chainId, aliceAddress)).toBe(imported.hash);
+    });
+
+    it('importShared with activate: false stores the acp and keeps the active one', async () => {
+      const { self, sharing } = await setUp();
+      const imported = await acps.importShared(ACPUtils.export(sharing), publicClient, aliceWalletClient, {
+        activate: false,
+      });
+
+      expect(acps.getACPs(chainId, aliceAddress)?.[imported.hash]).toBeDefined();
+      expect(acps.getActiveACPHash(chainId, aliceAddress)).toBe(self.hash);
+    });
+
+    it('importShared with activate: false leaves no active acp when there was none', async () => {
+      const sharing = await acps.createSharing(
+        { name: 'Shared with Alice', issuer: bobAddress, recipient: aliceAddress },
+        publicClient,
+        bobWalletClient
+      );
+      const imported = await acps.importShared(ACPUtils.export(sharing), publicClient, aliceWalletClient, {
+        activate: false,
+      });
+
+      expect(acps.getACPs(chainId, aliceAddress)?.[imported.hash]).toBeDefined();
+      expect(acps.getActiveACPHash(chainId, aliceAddress)).toBeUndefined();
+    });
+
+    it('importFromChain activates the imported acp by default', async () => {
+      const { sharing } = await setUp();
+      const imported = await acps.importFromChain(toIncomingShare(sharing), publicClient, aliceWalletClient);
+
+      expect(acps.getActiveACPHash(chainId, aliceAddress)).toBe(imported.hash);
+    });
+
+    it('importFromChain with activate: false stores the acp and keeps the active one', async () => {
+      const { self, sharing } = await setUp();
+      const imported = await acps.importFromChain(toIncomingShare(sharing), publicClient, aliceWalletClient, {
+        activate: false,
+      });
+
+      expect(acps.getACPs(chainId, aliceAddress)?.[imported.hash]).toBeDefined();
+      expect(acps.getActiveACPHash(chainId, aliceAddress)).toBe(self.hash);
+    });
+  });
+
   describe('ACP Retrieval', () => {
     let createdACP: any;
     let acpHash: string;

package/core/test/client.test.ts

@@ -6,6 +6,7 @@ import { CofheError, CofheErrorCode } from '../error.js';
 import { type PublicClient, type WalletClient } from 'viem';
 import { EncryptInputsBuilder } from '../encrypt/encryptInputsBuilder.js';
 import { Encryptable } from '../types.js';
+import { acps } from '../acps.js';
 
 // Mock dependencies
 vi.mock('../keyStore', () => ({
@@ -428,5 +429,45 @@ describe('createCofheClientBase', () => {
       expect(client.acp).toHaveProperty('selectActiveACP');
       expect(client.acp).toHaveProperty('removeActiveACP');
     });
+
+    describe('import activation', () => {
+      const share = { shareId: `0x${'0'.repeat(64)}` } as any;
+
+      it('importShared forwards activate with the connected clients', async () => {
+        const publicClient = createMockPublicClient();
+        const walletClient = createMockWalletClient();
+        await client.connect(publicClient, walletClient);
+        const spy = vi.spyOn(acps, 'importShared').mockResolvedValue({} as any);
+
+        await client.acp.importShared('{}', { activate: false });
+
+        expect(spy).toHaveBeenCalledWith('{}', publicClient, walletClient, { activate: false });
+        spy.mockRestore();
+      });
+
+      it('importShared still takes explicit clients, activating by default', async () => {
+        await client.connect(createMockPublicClient(), createMockWalletClient());
+        const publicClient = createMockPublicClient();
+        const walletClient = createMockWalletClient();
+        const spy = vi.spyOn(acps, 'importShared').mockResolvedValue({} as any);
+
+        await client.acp.importShared('{}', { publicClient, walletClient });
+
+        expect(spy).toHaveBeenCalledWith('{}', publicClient, walletClient, { activate: undefined });
+        spy.mockRestore();
+      });
+
+      it('importFromChain forwards activate', async () => {
+        const publicClient = createMockPublicClient();
+        const walletClient = createMockWalletClient();
+        await client.connect(publicClient, walletClient);
+        const spy = vi.spyOn(acps, 'importFromChain').mockResolvedValue({} as any);
+
+        await client.acp.importFromChain(share, { activate: false });
+
+        expect(spy).toHaveBeenCalledWith(share, publicClient, walletClient, { activate: false });
+        spy.mockRestore();
+      });
+    });
   });
 });

package/core/test/config.test.ts

@@ -162,6 +162,22 @@ describe('createCofheConfigBase', () => {
     expectValidConfigItem('useWorkers', undefined, true); // defaults to true
   });
 
+  it('tfheThreads', () => {
+    expectInvalidConfigItem('tfheThreads', 'not-a-setting');
+    expectInvalidConfigItem('tfheThreads', null);
+    expectInvalidConfigItem('tfheThreads', true);
+    expectInvalidConfigItem('tfheThreads', 0);
+    expectInvalidConfigItem('tfheThreads', -4);
+    expectInvalidConfigItem('tfheThreads', 2.5);
+    expectInvalidConfigItem('tfheThreads', {});
+
+    expectValidConfigItem('tfheThreads', 'auto', 'auto');
+    expectValidConfigItem('tfheThreads', false, false);
+    expectValidConfigItem('tfheThreads', 1, 1);
+    expectValidConfigItem('tfheThreads', 4, 4);
+    expectValidConfigItem('tfheThreads', undefined, 'auto'); // defaults to 'auto'
+  });
+
   it('should get config item', () => {
     const config: CofheInputConfig = {
       supportedChains: [sepolia],

package/core/test/decrypt.test.ts

@@ -1,5 +1,5 @@
 import { STAGING_TESTS, stagingViemChain } from './stagingRedirect';
-import { FheTypes, verifyDecryptResult, createCofheConfigBase, TASK_MANAGER_ADDRESS } from '@/core';
+import { FheTypes, verifyDecryptResult, createCofheConfigBase, getTaskManagerAddress } from '@/core';
 import { getChainById, stagingCofhe } from '@/chains';
 import {
   TEST_PRIVATE_KEY,
@@ -19,7 +19,12 @@ import { createPublicClient, createWalletClient, http, parseAbi } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { arbitrumSepolia, baseSepolia, sepolia } from 'viem/chains';
 
-const account = privateKeyToAccount(TEST_PRIVATE_KEY);
+// Live-chain suite: needs the funded TEST_PRIVATE_KEY (signs decrypt requests against
+// pre-deployed testnet fixtures). Without it — fork PRs, where secrets are unavailable —
+// the suite skips; CI runs it separately with the key (test-live job).
+const LIVE_TESTS = Boolean(TEST_PRIVATE_KEY);
+const DEFAULT_TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+const account = privateKeyToAccount(TEST_PRIVATE_KEY || DEFAULT_TEST_PRIVATE_KEY);
 
 const TEST_CHAIN_ID = STAGING_TESTS ? stagingViemChain.id : PRIMARY_TEST_CHAIN;
 
@@ -29,7 +34,7 @@ const VIEM_CHAINS: Record<number, Chain> = {
   11155111: sepolia,
 };
 
-describe('Core – Decrypt Tests', () => {
+describe.skipIf(!LIVE_TESTS)('Core – Decrypt Tests', () => {
   let publicClient: PublicClient;
   let walletClient: WalletClient;
   let config: ReturnType<typeof createCofheConfigBase>;
@@ -236,6 +241,8 @@ describe('Core – Decrypt Tests', () => {
         },
       ] as const;
 
+      const taskManagerAddress = await getTaskManagerAddress(publicClient);
+
       for (const sample of samples) {
         const sdkResult = await verifyDecryptResult(sample.handle, sample.cleartext, sample.signature, publicClient);
 
@@ -243,7 +250,7 @@ describe('Core – Decrypt Tests', () => {
           'function verifyDecryptResultSafe(uint256 ctHash, uint256 cleartext, bytes signature) view returns (bool)',
         ]);
         const tmResult = await publicClient.readContract({
-          address: TASK_MANAGER_ADDRESS,
+          address: taskManagerAddress,
           abi: verifyDecryptResultSafeAbi,
           functionName: 'verifyDecryptResultSafe',
           args: [sample.handle, sample.cleartext, sample.signature],

package/core/test/encryptInputsBuilder.test.ts

@@ -180,7 +180,7 @@ let keysStorage: KeysStorage;
 
 const insertMockKeys = (chainId: number, securityZone: number) => {
   keysStorage.setFheKey(chainId, securityZone, '0x1234567890');
-  keysStorage.setCrs(chainId, '0x1234567890');
+  keysStorage.setCrs(chainId, securityZone, '0x1234567890');
 };
 
 const mockTfhePublicKeyDeserializer: FheKeyDeserializer = (buff: string) => {

package/core/test/fetchKeys.test.ts

@@ -110,7 +110,7 @@ describe('fetchKeys', () => {
   it('should not fetch CRS if already cached', async () => {
     // Pre-populate with a cached CRS
     const mockCachedCrs = '0x2345678901';
-    keysStorage.setCrs(sepolia.id, mockCachedCrs);
+    keysStorage.setCrs(sepolia.id, 0, mockCachedCrs);
 
     const [[fheKey, fheKeyFetchedFromCoFHE], [crs, crsFetchedFromCoFHE]] = await fetchKeys(
       config,
@@ -133,12 +133,33 @@ describe('fetchKeys', () => {
     expect(retrievedKey).toBeDefined();
   });
 
+  it('should not reuse a cached CRS from a different security zone', async () => {
+    // CoFHE serves a distinct CRS per security zone, so a zone 0 CRS must not satisfy zone 1
+    const zone0Crs = '0x2345678901';
+    keysStorage.setCrs(sepolia.id, 0, zone0Crs);
+
+    const [, [crs, crsFetchedFromCoFHE]] = await fetchKeys(
+      config,
+      sepolia.id,
+      1,
+      mockTfhePublicKeyDeserializer,
+      mockCompactPkeCrsDeserializer,
+      keysStorage
+    );
+
+    expect(crsFetchedFromCoFHE).toBe(true);
+    expect(crs).not.toEqual(zone0Crs);
+
+    // The zone 0 entry is untouched
+    expect(keysStorage.getCrs(sepolia.id, 0)).toEqual(zone0Crs);
+  });
+
   it('should not make any network calls if both keys are cached', async () => {
     // Pre-populate both keys
     const mockCachedKey = '0x1234567890';
     const mockCachedCrs = '0x2345678901';
     keysStorage.setFheKey(sepolia.id, 0, mockCachedKey);
-    keysStorage.setCrs(sepolia.id, mockCachedCrs);
+    keysStorage.setCrs(sepolia.id, 0, mockCachedCrs);
 
     const [[fheKey, fheKeyFetchedFromCoFHE], [crs, crsFetchedFromCoFHE]] = await fetchKeys(
       config,

package/core/test/keyStore.test.ts

@@ -98,7 +98,7 @@ describe('KeyStore', () => {
     const testCrs = '0x1234567890';
 
     it('should set and get CRS', () => {
-      keysStorage.setCrs(testChainId, testCrs);
+      keysStorage.setCrs(testChainId, 0, testCrs);
 
       const retrievedCrs = keysStorage.getCrs(testChainId);
 
@@ -109,16 +109,28 @@ describe('KeyStore', () => {
       const crs1 = '0x1234567890';
       const crs2 = '0x2345678901';
 
-      keysStorage.setCrs(1, crs1);
-      keysStorage.setCrs(2, crs2);
+      keysStorage.setCrs(1, 0, crs1);
+      keysStorage.setCrs(2, 0, crs2);
 
       expect(keysStorage.getCrs(1)).toEqual(crs1);
       expect(keysStorage.getCrs(2)).toEqual(crs2);
     });
 
+    it('should keep CRS separate per security zone', () => {
+      const crsZone0 = '0xaaaaaaaaaa';
+      const crsZone1 = '0xbbbbbbbbbb';
+
+      keysStorage.setCrs(testChainId, 0, crsZone0);
+      keysStorage.setCrs(testChainId, 1, crsZone1);
+
+      expect(keysStorage.getCrs(testChainId, 0)).toEqual(crsZone0);
+      expect(keysStorage.getCrs(testChainId, 1)).toEqual(crsZone1);
+    });
+
     it('should return undefined for non-existent CRS', () => {
       expect(keysStorage.getCrs(999)).toBeUndefined();
       expect(keysStorage.getCrs(undefined)).toBeUndefined();
+      expect(keysStorage.getCrs(testChainId, 999)).toBeUndefined();
     });
   });
 
@@ -162,7 +174,7 @@ describe('KeyStore', () => {
       const testCrs = '0x2345678901';
 
       keysStorage.setFheKey(testChainId, 0, testKey);
-      keysStorage.setCrs(testChainId, testCrs);
+      keysStorage.setCrs(testChainId, 0, testCrs);
 
       expect(keysStorage.getFheKey(testChainId, 0)).toEqual(testKey);
       expect(keysStorage.getCrs(testChainId)).toEqual(testCrs);
@@ -194,13 +206,13 @@ describe('KeyStore', () => {
 
       keysStorage.setFheKey(1, 0, key1);
       keysStorage.setFheKey(2, 0, key2);
-      keysStorage.setCrs(1, crs1);
+      keysStorage.setCrs(1, 0, crs1);
 
       const state = keysStorage.store.getState();
 
       expect(state.fhe[1][0]).toEqual(key1);
       expect(state.fhe[2][0]).toEqual(key2);
-      expect(state.crs[1]).toEqual(crs1);
+      expect(state.crs[1][0]).toEqual(crs1);
     });
   });
 

package/core/test/taskManager.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { PublicClient } from 'viem';
+
+import { getTaskManagerAddress, clearTaskManagerAddressCache } from '../taskManager.js';
+import { COFHE_ADDRESS_BOOK_ADDRESS, TASK_MANAGER_ID } from '../consts.js';
+import { CofheErrorCode, isCofheError } from '../error.js';
+
+const TM = '0x0000000000000000000000000000000000005000';
+
+const fakeClient = (readContract: (...args: any[]) => Promise<unknown>, chainId = 31337) =>
+  ({ chain: { id: chainId }, readContract: vi.fn(readContract) }) as unknown as PublicClient & {
+    readContract: ReturnType<typeof vi.fn>;
+  };
+
+describe('getTaskManagerAddress', () => {
+  beforeEach(() => clearTaskManagerAddressCache());
+
+  it('resolves getTm(TASK_MANAGER_ID) on the CoFHEAddressBook', async () => {
+    const client = fakeClient(async () => TM);
+
+    expect(await getTaskManagerAddress(client)).to.equal(TM);
+    expect(client.readContract).toHaveBeenCalledWith(
+      expect.objectContaining({
+        address: COFHE_ADDRESS_BOOK_ADDRESS,
+        functionName: 'getTm',
+        args: [TASK_MANAGER_ID],
+      })
+    );
+  });
+
+  it('caches per chainId and shares an in-flight lookup', async () => {
+    const client = fakeClient(async () => TM);
+
+    await Promise.all([getTaskManagerAddress(client), getTaskManagerAddress(client)]);
+    await getTaskManagerAddress(client);
+    expect(client.readContract).toHaveBeenCalledTimes(1);
+
+    await getTaskManagerAddress(client, 11155111);
+    expect(client.readContract).toHaveBeenCalledTimes(2);
+  });
+
+  it('throws TASK_MANAGER_UNRESOLVED and does not cache the failure', async () => {
+    let calls = 0;
+    const client = fakeClient(async () => {
+      calls += 1;
+      if (calls === 1) throw new Error('returned no data ("0x")');
+      return TM;
+    });
+
+    const error = await getTaskManagerAddress(client).catch((e: unknown) => e);
+    expect(isCofheError(error)).to.equal(true);
+    expect((error as any).code).to.equal(CofheErrorCode.TaskManagerUnresolved);
+
+    expect(await getTaskManagerAddress(client)).to.equal(TM);
+    expect(client.readContract).toHaveBeenCalledTimes(2);
+  });
+});

package/core/types.ts

@@ -1,5 +1,13 @@
 export type TfheInitializer = () => Promise<boolean>;
 
+/**
+ * How many threads tfhe's rayon pool may use for ZK proof generation (web only).
+ * - `'auto'` (default): derive from `navigator.hardwareConcurrency`, capped
+ * - a positive number: request exactly that many
+ * - `false`: stay single-threaded
+ */
+export type TfheThreadsSetting = number | 'auto' | false;
+
 export interface IStorage {
   getItem: (name: string) => Promise<any>;
   setItem: (name: string, value: any) => Promise<void>;