@cofhe/sdk 0.7.1 → 1.0.0-alpha.0

package/core/clientTypes.ts

@@ -6,10 +6,11 @@ import { type DecryptForTxBuilderUnset } from './decrypt/decryptForTxBuilder.js'
 import { type EncryptInputsBuilderUnset } from './encrypt/encryptInputsBuilder.js';
 import { type ZkBuilderAndCrsGenerator, type ZkProveWorkerFunction } from './encrypt/zkPackProveVerify.js';
 import { type FheKeyDeserializer } from './fetchKeys.js';
-import { acps } from './acps.js';
+import { acps, type ImportSharedOptions, type ShareOnChainOptions } from './acps.js';
 import type { EncryptableItem, FheTypes, TfheInitializer } from './types.js';
 import type { ACPUtils } from 'acps/acp.js';
 import type {
+  ACPAccessStatus,
   CreateSelfACPOptions,
   ACP,
   CreateSharingACPOptions,
@@ -18,7 +19,9 @@ import type {
   RecipientACP,
   SelfACP,
   IncomingShare,
+  LabelledShare,
 } from 'acps/types.js';
+import type { ShareLabelCheck, ShareLabelVerifyMode } from 'acps/share-metadata/verify.js';
 
 // CLIENT
 
@@ -74,6 +77,14 @@ export type CofheClientACPsClients = {
   walletClient: WalletClient;
 };
 
+/**
+ * Options for `importShared`. `activate: false` stores the imported acp without making it the active
+ * one (default `true`). `name` names it (default "Shared by 0x1234…abcd"). Clients default to the
+ * connected ones; pass both to override.
+ */
+export type CofheClientImportSharedOptions = ImportSharedOptions &
+  (CofheClientACPsClients | { publicClient?: undefined; walletClient?: undefined });
+
 export type CofheClientACPs = {
   getSnapshot: typeof acps.getSnapshot;
   subscribe: typeof acps.subscribe;
@@ -81,7 +92,10 @@ export type CofheClientACPs = {
   // Creation methods (require connection, no params)
   createSelf: (options: CreateSelfACPOptions, clients?: CofheClientACPsClients) => Promise<SelfACP>;
   createSharing: (options: CreateSharingACPOptions, clients?: CofheClientACPsClients) => Promise<SharingACP>;
-  importShared: (options: ImportSharedACPOptions | string, clients?: CofheClientACPsClients) => Promise<RecipientACP>;
+  importShared: (
+    options: ImportSharedACPOptions | string,
+    importOptions?: CofheClientImportSharedOptions
+  ) => Promise<RecipientACP>;
 
   // Retrieval methods (chainId/account optional)
   getACP: (hash: string, chainId?: number, account?: string) => ACP | undefined;
@@ -102,13 +116,35 @@ export type CofheClientACPs = {
   revokeACP: (acp: ACP) => Promise<`0x${string}`>;
   revokeAllACPs: (revokerContract?: `0x${string}`) => Promise<`0x${string}`>;
   isACPRevoked: (acp: ACP) => Promise<boolean>;
+  /**
+   * The ACP on-chain status as a value instead of a revert. Without a handle: 'valid', or
+   * 'expired' / 'revoked' / an invalid signature. With a handle, a valid ACP reports
+   * 'allowed', 'out-of-scope' or 'issuer-not-allowed'. For the issuer copy of a share (type
+   * 'sharing', no recipient signature yet) the handle-less check covers expiry and revocation only.
+   */
+  checkAccess: (acp: ACP, handle?: bigint | `0x${string}`) => Promise<ACPAccessStatus>;
 
-  /** Post a signed sharing ACP to the on-chain share registry (ACL-served, or config `acp.sharingRegistry`). */
-  shareOnChain: (acp: ACP) => Promise<{ txHash: `0x${string}`; shareId: `0x${string}` }>;
-  /** Importable shares addressed to the connected account (unexpired, not revoked). */
+  /**
+   * Post a signed sharing ACP to the on-chain share registry (ACL-served, or config `acp.sharingRegistry`),
+   * optionally with the labels of its handles (`options.labels`, one per handle) or an encoded blob.
+   */
+  shareOnChain: (acp: ACP, options?: ShareOnChainOptions) => Promise<{ txHash: `0x${string}`; shareId: `0x${string}` }>;
+  /** Importable shares addressed to the connected account (unexpired, not revoked), with their metadata. */
   getIncomingShares: () => Promise<IncomingShare[]>;
-  /** Import a share read from the registry: sign as recipient, store and activate. */
-  importFromChain: (share: IncomingShare) => Promise<RecipientACP>;
+  /** One share by id, as posted; null when unknown or removed. */
+  getShareFromChain: (shareId: `0x${string}`) => Promise<IncomingShare | null>;
+  /**
+   * Check a share's labels against the chain, index for index with its handles, as far as
+   * `verify` says (default 'all'). Takes a share read from the registry or an acp imported from
+   * exported JSON (or the issuer's sharing acp). Null for a share without metadata. Throws on a
+   * malformed blob.
+   */
+  verifyShareLabels: (
+    share: LabelledShare,
+    options?: { verify?: ShareLabelVerifyMode }
+  ) => Promise<ShareLabelCheck[] | null>;
+  /** Import a share read from the registry: sign as recipient, store and (unless `activate: false`) activate. */
+  importFromChain: (share: IncomingShare, options?: ImportSharedOptions) => Promise<RecipientACP>;
   /** Recipient-side: remove a share from the registry (after import, or to decline). */
   dismissShare: (shareId: `0x${string}`) => Promise<`0x${string}`>;
   /** Issuer-side: retract a pending share from the registry. */
@@ -128,4 +164,11 @@ export type CofheClientParams<TConfig extends CofheConfig> = {
   compactPkeCrsDeserializer: FheKeyDeserializer;
   initTfhe: TfheInitializer;
   zkProveWorkerFn?: ZkProveWorkerFunction;
+  /**
+   * Runs right before a ZK proof is generated on the calling thread, i.e. only
+   * when the worker path is disabled, unavailable or has failed. Platforms use
+   * it for setup that only pays off when that thread does the proving (web
+   * starts tfhe's rayon thread pool here).
+   */
+  beforeMainThreadProve?: () => Promise<void>;
 };

package/core/config.ts

@@ -3,7 +3,7 @@ import { type CofheChain } from '@/chains';
 import { z } from 'zod';
 import { type WalletClient } from 'viem';
 import { CofheError, CofheErrorCode } from './error.js';
-import { type IStorage } from './types.js';
+import { type IStorage, type TfheThreadsSetting } from './types.js';
 
 export type CofheEnvironment = 'node' | 'hardhat' | 'web' | 'react';
 
@@ -29,6 +29,25 @@ export type CofheConfig = {
    * Default: true
    */
   useWorkers: boolean;
+  /**
+   * How many threads tfhe's rayon pool may use for ZK proof generation
+   * (web platform only; ignored on node/hardhat).
+   *
+   * Proving dominates the cost of `encryptInputs`, and tfhe's wasm is built with
+   * rayon, so spreading it across threads is a large win — roughly 5x on an
+   * 8-thread pool.
+   *
+   * Requires a cross-origin-isolated page (`Cross-Origin-Opener-Policy: same-origin`
+   * plus `Cross-Origin-Embedder-Policy: require-corp` or `credentialless`). When the
+   * page isn't isolated the pool is skipped and proving stays single-threaded, so
+   * this is safe to leave on.
+   *
+   * `'auto'` derives the count from `navigator.hardwareConcurrency` (capped, since
+   * the speedup flattens out); a number requests exactly that many; `false` keeps
+   * tfhe single-threaded.
+   * Default: 'auto'
+   */
+  tfheThreads: TfheThreadsSetting;
   /** ACP acp defaults, applied when creating acps (user options always win) */
   acp: {
     /**
@@ -54,6 +73,13 @@ export type CofheConfig = {
      * names a registry.
      */
     sharingRegistry?: Record<number, `0x${string}`>;
+    /**
+     * The name of this app, e.g. 'explorer.fhenix.io'. Set, every share the client creates
+     * carries the app's key (`shareAppKey(app)`, kept in the share metadata), and
+     * `getIncomingShares` lists only the shares posted for this app. Unset, shares carry no
+     * key and every importable share is listed.
+     */
+    app?: string;
   };
   /** Mocks configs */
   mocks: {
@@ -108,12 +134,18 @@ export const CofheConfigSchema = z.object({
     .default(null),
   /** Whether to use Web Workers for ZK proof generation (web platform only) */
   useWorkers: z.boolean().optional().default(true),
+  /** How many threads tfhe's rayon pool may use for ZK proof generation (web platform only) */
+  tfheThreads: z
+    .union([z.number().int().positive(), z.literal('auto'), z.literal(false)])
+    .optional()
+    .default('auto'),
   /** ACP acp defaults */
   acp: z
     .object({
       defaultRevoker: z.custom<Record<number, `0x${string}`>>().optional(),
       defaultContractScopes: z.custom<Record<number, `0x${string}`[]>>().optional(),
       sharingRegistry: z.custom<Record<number, `0x${string}`>>().optional(),
+      app: z.string().min(1).optional(),
     })
     .optional()
     .default({}),

package/core/consts.ts

@@ -1,5 +1,17 @@
-/** Main Task Manager contract address */
-export const TASK_MANAGER_ADDRESS = '0xeA30c4B8b44078Bbf8a6ef5b9f1eC1626C7848D9' as const;
+/**
+ * CoFHEAddressBook contract address - the same on every chain. Resolves `TASK_MANAGER_ID` to the
+ * chain's Task Manager. Keep in sync with `COFHE_ADDRESS_BOOK` in `@fhenixprotocol/cofhe-contracts/FHE.sol`.
+ */
+export const COFHE_ADDRESS_BOOK_ADDRESS = '0xC0F4e00E531a2B086492Ae3DCC1515038307196b' as const;
+
+/** Id of the Task Manager in the CoFHEAddressBook. Keep in sync with `TASK_MANAGER_ID` in FHE.sol */
+export const TASK_MANAGER_ID = 1n;
+
+/**
+ * Mock Task Manager contract address (used for testing). Registered in the mock CoFHEAddressBook;
+ * SDK reads still resolve the Task Manager through the book.
+ */
+export const MOCKS_TASK_MANAGER_ADDRESS = '0x0000000000000000000000000000000000005000' as const;
 
 /** Mock ZK Verifier contract address (used for testing) */
 export const MOCKS_ZK_VERIFIER_ADDRESS = '0x0000000000000000000000000000000000005001' as const;

package/core/decrypt/apiError.ts

@@ -48,7 +48,10 @@ const BACKEND_ERROR_CODE_TO_COFHE_ERROR_CODE: Record<BackendApiErrorCode, CofheE
 };
 
 function isBackendApiErrorCode(value: string): value is BackendApiErrorCode {
-  return value in BACKEND_ERROR_CODE_TO_COFHE_ERROR_CODE;
+  // Own-property check, not `in`: `in` also matches Object.prototype keys, so codes like
+  // `toString` or `constructor` would be treated as recognised and the lookup would return a
+  // function instead of a CofheErrorCode.
+  return Object.prototype.hasOwnProperty.call(BACKEND_ERROR_CODE_TO_COFHE_ERROR_CODE, value);
 }
 
 export type ParsedApiError = {

package/core/decrypt/verifyDecryptResult.ts

@@ -9,7 +9,7 @@ import {
   type Hex,
   type PublicClient,
 } from 'viem';
-import { TASK_MANAGER_ADDRESS } from '../consts.js';
+import { getTaskManagerAddress } from '../taskManager.js';
 
 const decryptResultSignerAbi = parseAbi(['function decryptResultSigner() view returns (address)']);
 const UINT_TYPE_MASK = 0x7fn;
@@ -30,10 +30,14 @@ const buildDecryptResultHash = (ctHash: bigint, cleartext: bigint, chainId: numb
  *
  * The recovered signer must equal the on-chain configured `decryptResultSigner`.
  *
+ * Fails closed: if the chain has no `decryptResultSigner` set (zero address), this returns `false`.
+ * The on-chain `verifyDecryptResult` instead accepts any signature in that case.
+ *
  * This mirrors the TaskManager decrypt-result hash format:
  * `keccak256(abi.encodePacked(result, encType, chainId, ctHash))`
  *
- * The only on-chain read performed is `TaskManager.decryptResultSigner()` (via `eth_call`).
+ * The only on-chain reads performed are the Task Manager lookup in the CoFHEAddressBook (cached
+ * per chain) and `TaskManager.decryptResultSigner()` (via `eth_call`).
  *
  * Works with both production and mock deployments.
  */
@@ -45,13 +49,13 @@ export async function verifyDecryptResult(
 ): Promise<boolean> {
   const chainId = publicClient.chain?.id ?? (await publicClient.getChainId());
   const expectedSigner = await publicClient.readContract({
-    address: TASK_MANAGER_ADDRESS,
+    address: await getTaskManagerAddress(publicClient, chainId),
     abi: decryptResultSignerAbi,
     functionName: 'decryptResultSigner',
     args: [],
   });
 
-  if (isAddressEqual(expectedSigner, zeroAddress)) return true;
+  if (isAddressEqual(expectedSigner, zeroAddress)) return false;
 
   const ctHash = BigInt(handle);
   const messageHash = buildDecryptResultHash(ctHash, cleartext, chainId);

package/core/encrypt/cofheMocksZkVerifySign.ts

@@ -1,5 +1,14 @@
 import { type EncryptableItem, FheTypes } from '../types.js';
-import { type VerifyBatchResult } from './zkPackProveVerify.js';
+import {
+  type VerifyBatchResult,
+  MAX_UINT8,
+  MAX_UINT16,
+  MAX_UINT32,
+  MAX_UINT64,
+  MAX_UINT128,
+  MAX_UINT160,
+} from './zkPackProveVerify.js';
+import { toBigIntOrThrow, validateBigIntInRange } from '../utils.js';
 import { createWalletClient, http, encodePacked, keccak256, type PublicClient, type WalletClient } from 'viem';
 import { MockZkVerifierAbi } from './MockZkVerifierAbi.js';
 import { hardhat } from 'viem/chains';
@@ -19,7 +28,9 @@ function createMockZkVerifierSigner() {
   });
 }
 /**
- * The mocks don't use a tfhe builder, so we check the encryptable bits here to preserve parity
+ * The mocks don't use a tfhe builder, so we check the encryptable bits and value ranges here to
+ * preserve parity with `zkPack`. Without the range check, MockCoFHE masks an out-of-range value
+ * with the utype mask (e.g. uint8(256) -> 0) instead of rejecting it like the production path.
  */
 export async function cofheMocksCheckEncryptableBits(items: EncryptableItem[]): Promise<void> {
   let totalBits = 0;
@@ -30,22 +41,27 @@ export async function cofheMocksCheckEncryptableBits(items: EncryptableItem[]):
         break;
       }
       case FheTypes.Uint8: {
+        validateBigIntInRange(toBigIntOrThrow(item.data), MAX_UINT8);
         totalBits += 8;
         break;
       }
       case FheTypes.Uint16: {
+        validateBigIntInRange(toBigIntOrThrow(item.data), MAX_UINT16);
         totalBits += 16;
         break;
       }
       case FheTypes.Uint32: {
+        validateBigIntInRange(toBigIntOrThrow(item.data), MAX_UINT32);
         totalBits += 32;
         break;
       }
       case FheTypes.Uint64: {
+        validateBigIntInRange(toBigIntOrThrow(item.data), MAX_UINT64);
         totalBits += 64;
         break;
       }
       case FheTypes.Uint128: {
+        validateBigIntInRange(toBigIntOrThrow(item.data), MAX_UINT128);
         totalBits += 128;
         break;
       }
@@ -55,6 +71,7 @@ export async function cofheMocksCheckEncryptableBits(items: EncryptableItem[]):
       //   break;
       // }
       case FheTypes.Uint160: {
+        validateBigIntInRange(toBigIntOrThrow(item.data), MAX_UINT160);
         totalBits += 160;
         break;
       }

package/core/encrypt/encryptInputsBuilder.ts

@@ -37,6 +37,7 @@ type EncryptInputsBuilderParams<T extends EncryptableItem[]> = BaseBuilderParams
   zkBuilderAndCrsGenerator: ZkBuilderAndCrsGenerator | undefined;
   initTfhe: TfheInitializer | undefined;
   zkProveWorkerFn: ZkProveWorkerFunction | undefined;
+  beforeMainThreadProve?: (() => Promise<void>) | undefined;
 
   keysStorage: KeysStorage | undefined;
 };
@@ -69,6 +70,7 @@ export class EncryptInputsBuilder<T extends EncryptableItem[]> extends BaseBuild
   private zkBuilderAndCrsGenerator: ZkBuilderAndCrsGenerator;
   private initTfhe: TfheInitializer | undefined;
   private zkProveWorkerFn: ZkProveWorkerFunction | undefined;
+  private beforeMainThreadProve: (() => Promise<void>) | undefined;
 
   private keysStorage: KeysStorage | undefined;
 
@@ -143,6 +145,9 @@ export class EncryptInputsBuilder<T extends EncryptableItem[]> extends BaseBuild
     // Optional zkProve worker function, will be used on web if useWorkers is true and worker function is provided
     this.zkProveWorkerFn = params.zkProveWorkerFn;
 
+    // Optional platform setup that only matters when this thread generates the proof
+    this.beforeMainThreadProve = params.beforeMainThreadProve;
+
     // Keys storage is used to store the FHE key and CRS
     this.keysStorage = params.keysStorage;
 
@@ -582,6 +587,7 @@ export class EncryptInputsBuilder<T extends EncryptableItem[]> extends BaseBuild
 
     if (proof == null) {
       // Use main thread directly (workers disabled or unavailable)
+      await this.beforeMainThreadProve?.();
       proof = await zkProve(zkBuilder, zkCrs, metadata);
       usedWorker = false;
     }

package/core/encrypt/zkPackProveVerify.ts

@@ -1,6 +1,6 @@
 import { TFHE_RS_ZK_MAX_BITS, TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT } from '../consts';
 import { CofheError, CofheErrorCode } from '../error';
-import { type EncryptableItem, FheTypes } from '../types';
+import { type EncryptableItem, FheTypes, type TfheThreadsSetting } from '../types';
 import { toBigIntOrThrow, validateBigIntInRange, toHexString, hexToBytes } from '../utils';
 
 // ===== TYPES =====
@@ -29,6 +29,12 @@ export interface ZkProveWorkerRequest {
     data: any;
   }>;
   metadata: number[]; // Uint8Array serialized as array
+  /**
+   * Forwarded from `config.tfheThreads`. The worker applies it the first time it
+   * initialises tfhe — `initThreadPool` can only run once per wasm instance, so
+   * later requests carrying a different value have no effect.
+   */
+  tfheThreads?: TfheThreadsSetting;
 }
 
 /**

package/core/error.ts

@@ -43,6 +43,7 @@ export enum CofheErrorCode {
   PublicWalletGetChainIdFailed = 'PUBLIC_WALLET_GET_CHAIN_ID_FAILED',
   PublicWalletGetAddressesFailed = 'PUBLIC_WALLET_GET_ADDRESSES_FAILED',
   RehydrateKeysStoreFailed = 'REHYDRATE_KEYS_STORE_FAILED',
+  TaskManagerUnresolved = 'TASK_MANAGER_UNRESOLVED',
 
   // Threshold-network stable error codes (decrypt/sealoutput), see API-RESPONSES.md
   BadRequest = 'BAD_REQUEST',

package/core/fetchKeys.ts

@@ -77,7 +77,7 @@ const fetchCrs = async (
   keysStorage?: KeysStorage | null
 ): Promise<[string, boolean]> => {
   // Escape if key already exists
-  const storedKey = keysStorage?.getCrs(chainId);
+  const storedKey = keysStorage?.getCrs(chainId, securityZone);
   const [storedKeyValid] = checkKeyValidity(storedKey, compactPkeCrsDeserializer);
   if (storedKeyValid) return [storedKey!, false];
 
@@ -108,7 +108,7 @@ const fetchCrs = async (
     throw new Error(`Error serializing CRS; ${err}`);
   }
 
-  keysStorage?.setCrs(chainId, crs_data);
+  keysStorage?.setCrs(chainId, securityZone, crs_data);
 
   return [crs_data, true];
 };

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;
+};