@cofhe/sdk 0.7.1 → 1.0.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @cofhe/sdk Changelog
 
+## 0.8.0
+
+### Minor Changes
+
+- 0fe40c3: Add the `ethereum` (chain id 1) and `arbitrum` (Arbitrum One, chain id 42161) mainnet chains to `@cofhe/sdk/chains`, both with `environment: 'MAINNET'`. They are included in `chains`, `getChainById` and `getChainByName`.
+- 6f7a4c5: Resolve the Task Manager through the `CoFHEAddressBook` (`@fhenixprotocol/cofhe-contracts@1.0.0`). **Breaking:** `TASK_MANAGER_ADDRESS` is removed from `@cofhe/sdk`. Use `getTaskManagerAddress(publicClient)`, which reads `getTm(TASK_MANAGER_ID)` from the book at `COFHE_ADDRESS_BOOK_ADDRESS` (both exported) and caches the result per chain. If the chain has no book, or the id is unset, it throws `TASK_MANAGER_UNRESOLVED`. `verifyDecryptResult`, the ACL/ACP lookups and `useCofheEnabled` / `useCofheReadDecryptionResults` now resolve the Task Manager this way. `@cofhe/react` adds `useCofheTaskManagerAddress()`.
+
+  Mocks: a new `MockCoFHEAddressBook` is deployed at FHE.sol's `COFHE_ADDRESS_BOOK`, and `MockTaskManager` moves to `MOCKS_TASK_MANAGER_ADDRESS` (`0x…5000`) and is registered in the book. `MockACL` now stores its Task Manager (`setTaskManager` / `getTaskManagerAddress`) instead of reading a constant, so its `TASK_MANAGER_ADDRESS_()` getter is gone. All three plugins deploy and wire the book. Hardhat 2 exposes `hre.cofhe.mocks.getMockCoFHEAddressBook()`, Hardhat 3 exposes `conn.cofhe.mocks.MockCoFHEAddressBook`, and Foundry exposes `CofheTest.mockAddressBook`. Contracts must be built against `@fhenixprotocol/cofhe-contracts@1.0.0` or later (the hardhat plugin's peer range is now `>=1.0.0`). Each FHE op now makes one extra `getTm` call on the book, as it does on real networks, so expect slightly higher gas numbers.
+
+- 552d118: The CRS is now cached per security zone. It was fetched per zone but cached under the chain id alone, so after encrypting on zone 0, encrypting on zone 1 reused zone 0's CRS and produced a proof the ZK verifier rejects.
+
+  **Breaking (`KeysStorage`):** `crs` is now keyed by chain and zone, like `fhe`. `getCrs(chainId, securityZone = 0)` takes the zone, and `setCrs(chainId, securityZone, crs)` matches `setFheKey`'s argument order. A CRS persisted in the old per-chain shape is dropped on rehydrate and refetched.
+
+### Patch Changes
+
+- 17ff23e: Scoped decryption with shared ACPs.
+
+  **@cofhe/sdk**
+
+  - `client.acp.importShared` and `client.acp.importFromChain` take an `activate` option (default `true`). With `activate: false` the imported ACP is stored without becoming the active ACP, so decrypts that use the active ACP are unaffected; use the imported ACP explicitly, e.g. `.withACP(acp)`. `importShared`'s second argument is now `{ activate?, publicClient?, walletClient? }`; passing `{ publicClient, walletClient }` works as before.
+  - New `client.acp.checkAccess(acp, handle?)` (and `ACPUtils.checkAccessOnChain`) returns an ACP on-chain status instead of reverting: `valid`, `expired`, `revoked` or an invalid signature, and with a handle `allowed`, `out-of-scope` or `issuer-not-allowed`. New exported type: `ACPAccessStatus`. ACL reverts are now recognized when the public client comes from another copy of viem than the SDK, which also fixes `checkValidityOnChain` throwing a generic error in that setup. ACL reverts reported only as text (`custom error 0x…`, e.g. by a transport that drops the error data) are decoded too. For the issuer copy of a share (type `sharing`, no recipient signature yet) the handle-less check reports expiry and revocation instead of failing on the missing signature.
+  - `@cofhe/sdk/acps` exports the on-chain sharing pieces: `ACP_SHARE_REGISTRY_ABI`, `ACP_REVOKER_ABI`, `ACP_SHARE_TUPLE_ABI`, `toChainShare`, `computeShareId`, `shareIdOfChainShare`, `getAclAddress`, `getAclServedAddresses` and `clearAclServedAddresses`, so an app can send registry and revoker writes through its own transaction path and still agree with the registry on share ids.
+
+  **@cofhe/react**
+
+  - Decrypt with a chosen ACP in part of the tree without changing the active ACP. New `<CofheACPScope acp={acp | hash}>` and `useCofheACPScope()`; `useCofheReadContractAndDecrypt`, `useCofheReadContract`, `useCofheReadContracts` and `useCofheTokenDecryptedBalance` take an `acp` option that wins over the scope. Inside a scope `useCofheTokenDecryptedBalance` reads the ACP issuer balance unless given an account, and an invalid or unknown scoped ACP disables the reads (`disabledDueToMissingValidACP`) instead of falling back to the active ACP. The decrypt cache key gains a fifth segment, the hash of the ACP that decrypts (the chosen one, else the active one), so a value decrypted with one ACP never answers for another. New exported types: `CofheACPInput`, `CofheACPScopeValue`.
+  - `<CofheACPScope>` and the per-hook `acp` option check the chosen ACP on chain (`client.acp.checkAccess`) when mounted, every minute and on window focus, so a revoked share turns the scope off and drops its decrypted values while the view is open. `useCofheACPScope()` gains `status` (`checking`, `valid`, `expired`, `revoked`, `invalid`, `unverified`); the scope decrypts only while it is `valid`. For a SNAPSHOT (handle-scope) ACP, `useCofheReadContractAndDecrypt` and `useCofheTokenDecryptedBalance` report `isOutOfScope` for a value the share does not list and never send it for decryption. New exported type: `CofheACPStatus`.
+  - Plaintext decrypted with a shared (non-self) ACP is kept in memory only: it is no longer written to the persisted query cache. Decrypts are cached under the ACP that made them and dropped when that ACP leaves the ACP store (e.g. `removeACP`) or when a non-self ACP expires while in use, so a revoked or expired share does not keep serving its values from cache.
+  - The sharing hooks are exported: `useCofheIncomingShares` (registry inbox, polled; shares already imported by the connected account are left out), `useCofheShareOnChain`, `useCofheImportShared({ activate })` (exported JSON or an `IncomingShare`), `useCofheRemoveShare`, `useCofheRevokeACP` and `useCofheACPStatus` (an ACP on-chain status, re-read after a revoke mines). The write hooks resolve once mined. The package-internal names (`useIncomingShares`, `useShareOnChain`, `useImportFromChain`, `useRemoveShare`) stay as deprecated aliases.
+  - New `useCofheACPs({ chainId?, type? })`: the connected account stored ACPs on a chain (the connected chain by default), optionally narrowed to one type, e.g. `useCofheACPs({ type: 'recipient' })` for received shares. `useCofheAllACPs` is deprecated: it returned only the connected account ACPs on the connected chain, not all ACPs, and is now an alias of `useCofheACPs()`.
+  - `useCofheDecrypt` is exported: decrypt a ciphertext handle directly (no contract read), with the same `acp` option and scope behaviour as `useCofheReadContractAndDecrypt`.
+
+- 22eebcc: The Node in-memory storage fallback (used when the filesystem key cache is not writable) no longer JSON-encodes values a second time. Previously cached FHE keys and CRS read back from the fallback as strings instead of objects, so they were effectively lost and refetched.
+- 42fccae: Add `tfheThreads` config option (`'auto'` | number | `false`, default `'auto'`) to multi-thread ZK proof generation on cross-origin-isolated web pages, and export the `TfheThreadsSetting` and `TfheInitializer` types.
+
 ## 0.7.1
 
 ## 0.7.0

package/acps/acp.ts

@@ -1,5 +1,6 @@
 import { keccak256, toHex, zeroAddress, parseAbi, type Hex, type PublicClient, type WalletClient } from 'viem';
 import {
+  type ACPAccessStatus,
   type ACP,
   type SelfACP,
   type SharingACP,
@@ -25,7 +26,12 @@ import {
 } from './validation.js';
 import { SignatureUtils } from './signature.js';
 import { GenerateSealingKey, unsealWithPrivateKey } from './sealing.js';
-import { checkACPValidityOnChain, getAclEIP712Domain } from './onchain-utils.js';
+import { checkACPValidityOnChain, getACPAccessStatusOnChain, getAclEIP712Domain } from './onchain-utils.js';
+import { encodeShareMetadata } from './share-metadata/encode.js';
+import { UNLABELLED } from './share-metadata/presets';
+
+/** The name of an imported acp unless the recipient gives one: who it came from. */
+const sharedByName = (issuer: Hex): string => `Shared by ${issuer.slice(0, 6)}…${issuer.slice(-4)}`;
 
 /**
  * Main ACP utilities - functional approach for React compatibility
@@ -56,6 +62,15 @@ export const ACPUtils = {
    */
   createSharing: (options: CreateSharingACPOptions): SharingACP => {
     const validation = validateSharingACPOptions(options);
+    const { labels, appKey } = options;
+    if (labels != null && labels.length !== validation.handles.length) {
+      throw new Error(`Cannot label a share of ${validation.handles.length} handles with ${labels.length} labels`);
+    }
+    // With an app key but no labels, the handles are listed as unlabelled so the key has a blob to sit in.
+    const metadata =
+      labels != null || appKey != null
+        ? encodeShareMetadata(labels ?? validation.handles.map(() => UNLABELLED), { issuer: validation.issuer, appKey })
+        : undefined;
 
     // Always generate a new sealing key - users cannot provide their own
     const sealingPair = GenerateSealingKey();
@@ -63,6 +78,7 @@ export const ACPUtils = {
     const acp = {
       hash: ACPUtils.getHash(validation),
       ...validation,
+      ...(metadata != null && { metadata }),
       sealingPrivateKey: sealingPair.privateKey,
       sealingKey: sealingPair.publicKey,
       _signedDomain: undefined,
@@ -72,9 +88,10 @@ export const ACPUtils = {
   },
 
   /**
-   * Import a shared acp from various input formats
+   * Import a shared acp from various input formats. The acp is named `name`, or after its issuer
+   * ("Shared by 0x1234…abcd"); a `name` in the share itself is ignored.
    */
-  importShared: (options: ImportSharedACPOptions | string): RecipientACP => {
+  importShared: (options: ImportSharedACPOptions | string, { name }: { name?: string } = {}): RecipientACP => {
     let parsedOptions: ImportSharedACPOptions;
 
     // Handle different input types
@@ -105,6 +122,7 @@ export const ACPUtils = {
     const acp = {
       hash: ACPUtils.getHash(validation),
       ...validation,
+      name: name?.trim() || sharedByName(validation.issuer),
       sealingPrivateKey: sealingPair.privateKey,
       sealingKey: sealingPair.publicKey,
       _signedDomain: undefined,
@@ -183,9 +201,10 @@ export const ACPUtils = {
   importSharedAndSign: async (
     options: ImportSharedACPOptions | string,
     publicClient: PublicClient,
-    walletClient: WalletClient
+    walletClient: WalletClient,
+    importOptions: { name?: string } = {}
   ): Promise<RecipientACP> => {
-    const acp = ACPUtils.importShared(options);
+    const acp = ACPUtils.importShared(options, importOptions);
     return ACPUtils.sign(acp, publicClient, walletClient);
   },
 
@@ -217,6 +236,7 @@ export const ACPUtils = {
       recipientSignature: acp.recipientSignature,
       _signedDomain: acp._signedDomain,
       sealingPrivateKey: acp.sealingPrivateKey,
+      ...(acp.metadata != null && { metadata: acp.metadata }),
     };
   },
 
@@ -296,7 +316,7 @@ export const ACPUtils = {
   /**
    * Export acp data for sharing (strips the private component).
    * Fixed `SharedACP` shape — every field always present, aligned with
-   * `ACPPublic` and the on-chain sharing payload.
+   * `ACPPublic` and the on-chain sharing payload — plus `metadata` when the acp has labels.
    */
   export: (acp: ACP): string => {
     if (acp.type !== 'sharing') {
@@ -311,7 +331,6 @@ export const ACPUtils = {
     }
 
     const shared: SharedACP = {
-      name: acp.name,
       type: acp.type,
       issuer: acp.issuer,
       expiration: acp.expiration,
@@ -322,6 +341,7 @@ export const ACPUtils = {
       contracts: acp.contracts,
       handles: acp.handles,
       issuerSignature: acp.issuerSignature,
+      ...(acp.metadata != null && acp.metadata !== '0x' && { metadata: acp.metadata }),
     };
 
     return JSON.stringify(shared, undefined, 2);
@@ -408,4 +428,12 @@ export const ACPUtils = {
     const publicAcp = ACPUtils.getPublic(acp);
     return checkACPValidityOnChain(publicAcp, publicClient);
   },
+
+  /**
+   * The acp on-chain status as a value instead of a revert: 'valid' or why not, and given a
+   * handle, whether the acp may read it (see `ACPAccessStatus`).
+   */
+  checkAccessOnChain: async (acp: ACP, publicClient: PublicClient, handle?: bigint | Hex): Promise<ACPAccessStatus> => {
+    return getACPAccessStatusOnChain(ACPUtils.getPublic(acp), publicClient, handle);
+  },
 };

package/acps/index.ts

@@ -9,15 +9,31 @@ export type {
   ACPPublic,
   SharedACP,
   IncomingShare,
+  LabelledShare,
   EIP712Domain,
   EIP712Types,
   EIP712Message,
   ValidationResult,
   ACPSignaturePrimaryType,
-} from './types.js';
+} from './types';
 
 // Main utilities
-export { ACPUtils } from './acp.js';
+export { ACPUtils } from './acp';
+
+// On-chain sharing: registry / revoker ABIs, the registry payload and share id of a sharing ACP,
+// and the read of posted shares from their Shared events
+export * from './registry';
+
+// Share metadata: labels saying where each handle of a SNAPSHOT share came from
+export * from './share-metadata/index';
+
+// Addresses the chain ACL serves (TaskManager -> acl() -> default revoker, share registry)
+export {
+  getAclAddress,
+  getAclServedAddresses,
+  clearAclServedAddresses,
+  type AclServedAddresses,
+} from './onchain-utils';
 
 // Validation utilities
 export {
@@ -38,10 +54,10 @@ export {
   validateImportACP,
   // Common utilities
   ValidationUtils,
-} from './validation.js';
+} from './validation';
 
 // Signature utilities
-export { SignatureUtils, getSignatureTypesAndMessage, SignatureTypes } from './signature.js';
+export { SignatureUtils, getSignatureTypesAndMessage, SignatureTypes } from './signature';
 
 // Storage utilities
 export {
@@ -56,15 +72,15 @@ export {
   removeActiveACPHash,
   clearStaleStore,
   ACP_STORE_DEFAULTS,
-} from './store.js';
+} from './store';
 
 // Sealing utilities
-export { GenerateSealingKey, seal, unsealWithPrivateKey, type SealingKeyPair } from './sealing.js';
-export type { EthEncryptedData } from './sealing.js';
+export { GenerateSealingKey, seal, unsealWithPrivateKey, type SealingKeyPair } from './sealing';
+export type { EthEncryptedData } from './sealing';
 
 // Re-export everything for convenience
-export * from './types.js';
-export * from './acp.js';
-export * from './validation.js';
-export * from './signature.js';
-export * from './store.js';
+export * from './types';
+export * from './acp';
+export * from './validation';
+export * from './signature';
+export * from './store';

package/acps/onchain-utils.ts

@@ -1,13 +1,6 @@
-import {
-  BaseError,
-  ContractFunctionRevertedError,
-  type Hex,
-  type PublicClient,
-  decodeErrorResult,
-  parseAbi,
-} from 'viem';
-import type { EIP712Domain, ACPPublic } from './types';
-import { TASK_MANAGER_ADDRESS } from '../core/consts.js';
+import { type Hex, type PublicClient, decodeErrorResult, parseAbi, zeroAddress } from 'viem';
+import type { ACPAccessStatus, EIP712Domain, ACPPublic } from './types';
+import { getTaskManagerAddress } from '../core/taskManager.js';
 
 export const getAclAddress = async (publicClient: PublicClient): Promise<Hex> => {
   const ACL_IFACE = 'function acl() view returns (address)';
@@ -17,7 +10,7 @@ export const getAclAddress = async (publicClient: PublicClient): Promise<Hex> =>
 
   // Get the ACL address
   return (await publicClient.readContract({
-    address: TASK_MANAGER_ADDRESS as `0x${string}`,
+    address: await getTaskManagerAddress(publicClient),
     abi: aclAbi,
     functionName: 'acl',
   })) as `0x${string}`;
@@ -59,6 +52,48 @@ export const getAclEIP712Domain = async (publicClient: PublicClient): Promise<EI
   };
 };
 
+const toACPTuple = (acp: ACPPublic) => ({
+  issuer: acp.issuer,
+  expiration: BigInt(acp.expiration),
+  recipient: acp.recipient,
+  revokerData: BigInt(acp.revokerData),
+  revokerContract: acp.revokerContract,
+  scope: acp.scope,
+  contracts: acp.contracts,
+  handles: acp.handles,
+  sealingKey: acp.sealingKey,
+  issuerSignature: acp.issuerSignature,
+  recipientSignature: acp.recipientSignature,
+});
+
+/**
+ * The custom error a reverted ACL call carries, however the node reports it: a viem revert, a
+ * Hardhat-style 'reverted with custom error' detail, or raw return data. `undefined` when the
+ * failure is not a contract revert (e.g. a network error).
+ */
+function revertErrorName(err: unknown, abi: readonly any[]): string | undefined {
+  // Viem revert. Matched by name, not `instanceof`: the public client may come from another copy of
+  // viem than this package (an app bringing its own), and then no class check ever matches.
+  const walk = (err as { walk?: (fn: (e: unknown) => boolean) => unknown } | null)?.walk;
+  if (typeof walk === 'function') {
+    const revertError = walk.call(err, (e) => (e as { name?: string })?.name === 'ContractFunctionRevertedError') as
+      | { data?: { errorName?: string } }
+      | null
+      | undefined;
+    if (revertError) return revertError.data?.errorName ?? '';
+  }
+
+  // Check details field for custom error names (e.g., from Hardhat test nodes)
+  const customErrorName = extractCustomErrorFromDetails(err, abi);
+  if (customErrorName) return customErrorName;
+
+  // Hardhat wrapped error will need to be unwrapped to get the return data
+  const hhDetailsData = extractReturnData(err);
+  if (hhDetailsData != null) return decodeErrorResult({ abi, data: hhDetailsData }).errorName;
+
+  return undefined;
+}
+
 export const checkACPValidityOnChain = async (acp: ACPPublic, publicClient: PublicClient): Promise<boolean> => {
   const aclAddress = await getAclAddress(publicClient);
 
@@ -68,51 +103,69 @@ export const checkACPValidityOnChain = async (acp: ACPPublic, publicClient: Publ
       address: aclAddress,
       abi: checkACPValidityAbi,
       functionName: 'checkPermissionValidity',
-      args: [
-        {
-          issuer: acp.issuer,
-          expiration: BigInt(acp.expiration),
-          recipient: acp.recipient,
-          revokerData: BigInt(acp.revokerData),
-          revokerContract: acp.revokerContract,
-          scope: acp.scope,
-          contracts: acp.contracts,
-          handles: acp.handles,
-          sealingKey: acp.sealingKey,
-          issuerSignature: acp.issuerSignature,
-          recipientSignature: acp.recipientSignature,
-        },
-      ],
+      args: [toACPTuple(acp)],
     });
     return true;
   } catch (err: any) {
-    // Viem default handling
-    if (err instanceof BaseError) {
-      const revertError = err.walk((err: any) => err instanceof ContractFunctionRevertedError);
-      if (revertError instanceof ContractFunctionRevertedError) {
-        const errorName = revertError.data?.errorName ?? '';
-        throw new Error(errorName);
-      }
-    }
+    const errorName = revertErrorName(err, checkACPValidityAbi);
+    if (errorName !== undefined) throw new Error(errorName);
+    // Fallback throw the original error
+    throw err;
+  }
+};
 
-    // Check details field for custom error names (e.g., from Hardhat test nodes)
-    const customErrorName = extractCustomErrorFromDetails(err, checkACPValidityAbi);
-    if (customErrorName) {
-      throw new Error(customErrorName);
-    }
+/** The ACL permission reverts, as statuses. */
+const PERMISSION_ERROR_STATUS: Record<string, ACPAccessStatus> = {
+  PermissionInvalid_Expired: 'expired',
+  PermissionInvalid_Disabled: 'revoked',
+  PermissionInvalid_IssuerSignature: 'invalid-issuer-signature',
+  PermissionInvalid_RecipientSignature: 'invalid-recipient-signature',
+};
 
-    // Hardhat wrapped error will need to be unwrapped to get the return data
-    const hhDetailsData = extractReturnData(err);
-    if (hhDetailsData != null) {
-      const decoded = decodeErrorResult({
-        abi: checkACPValidityAbi,
-        data: hhDetailsData,
-      });
+/**
+ * An ACP status on chain, read from the ACL: its validity (expiration, signatures, revocation)
+ * and, given a handle, whether the ACP may read it. The ACL reverts for an invalid ACP; those
+ * reverts come back as statuses. Anything else (e.g. a network error) still throws.
+ */
+export const getACPAccessStatusOnChain = async (
+  acp: ACPPublic,
+  publicClient: PublicClient,
+  handle?: bigint | Hex
+): Promise<ACPAccessStatus> => {
+  const aclAddress = await getAclAddress(publicClient);
 
-      throw new Error(decoded.errorName);
+  try {
+    if (handle === undefined) {
+      await publicClient.simulateContract({
+        address: aclAddress,
+        abi: acpAccessAbi,
+        functionName: 'checkPermissionValidity',
+        args: [toACPTuple(acp)],
+      });
+      return 'valid';
     }
 
-    // Fallback throw the original error
+    const ctHash = BigInt(handle);
+    const allowed = await publicClient.readContract({
+      address: aclAddress,
+      abi: acpAccessAbi,
+      functionName: 'isAllowedWithPermission',
+      args: [toACPTuple(acp), ctHash],
+    });
+    if (allowed) return 'allowed';
+
+    // The ACL answers false both when the scope misses the handle and when the issuer itself may
+    // not read it; the issuer own allowance tells the two apart.
+    const issuerAllowed = await publicClient.readContract({
+      address: aclAddress,
+      abi: acpAccessAbi,
+      functionName: 'isAllowed',
+      args: [ctHash, acp.issuer],
+    });
+    return issuerAllowed ? 'out-of-scope' : 'issuer-not-allowed';
+  } catch (err) {
+    const status = PERMISSION_ERROR_STATUS[revertErrorName(err, acpAccessAbi) ?? ''];
+    if (status) return status;
     throw err;
   }
 };
@@ -143,7 +196,10 @@ function extractReturnData(err: unknown): `0x${string}` | undefined {
   const anyErr = err as any;
   const s = anyErr?.details ?? anyErr?.cause?.details ?? anyErr?.shortMessage ?? anyErr?.message ?? String(err);
 
-  return s.match(/return data:\s*(0x[a-fA-F0-9]+)/)?.[1] as `0x${string}` | undefined;
+  // Hardhat: "return data: 0x...". A node that reports only the selector in text (e.g. anvil through
+  // a transport that drops the structured error data): "custom error 0x...".
+  const match = s.match(/return data:\s*(0x[a-fA-F0-9]+)/) ?? s.match(/custom error (0x[a-fA-F0-9]{8,})/);
+  return match?.[1] as `0x${string}` | undefined;
 }
 
 const checkACPValidityAbi = [
@@ -244,3 +300,86 @@ const checkACPValidityAbi = [
     inputs: [],
   },
 ] as const;
+
+const acpAccessAbi = [
+  ...checkACPValidityAbi,
+  {
+    type: 'function',
+    name: 'isAllowedWithPermission',
+    inputs: [checkACPValidityAbi[0].inputs[0], { name: 'handle', type: 'uint256', internalType: 'uint256' }],
+    outputs: [{ name: '', type: 'bool', internalType: 'bool' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'isAllowed',
+    inputs: [
+      { name: 'handle', type: 'uint256', internalType: 'uint256' },
+      { name: 'account', type: 'address', internalType: 'address' },
+    ],
+    outputs: [{ name: '', type: 'bool', internalType: 'bool' }],
+    stateMutability: 'view',
+  },
+] as const;
+
+// ACL-SERVED ADDRESSES (defaultRevokerContract / shareRegistry)
+
+const ACL_SERVED_ADDRESSES_ABI = parseAbi([
+  'function acl() view returns (address)',
+  'function defaultRevokerContract() view returns (address)',
+  'function shareRegistry() view returns (address)',
+]);
+
+export interface AclServedAddresses {
+  defaultRevoker?: Hex;
+  shareRegistry?: Hex;
+}
+
+const aclServedAddressesCache = new Map<number, AclServedAddresses>();
+
+/** Test hook: forget resolved addresses (e.g. between redeployments on one chainId). */
+export const clearAclServedAddresses = () => aclServedAddressesCache.clear();
+
+/**
+ * The ACP infrastructure addresses the chain's ACL serves (CoFHEAddressBook ->
+ * TaskManager -> acl() -> getters). Zero addresses and pre-upgrade ACLs (getters absent -> revert)
+ * resolve to `undefined` — callers fall back to `acp.*` config.
+ *
+ * Resolutions are cached per chainId. A failure to reach the TaskManager (network
+ * error, no CoFHE deployment) is NOT cached, so a transient outage does not pin
+ * an empty result for the whole session.
+ */
+export const getAclServedAddresses = async (
+  publicClient: PublicClient,
+  chainId: number
+): Promise<AclServedAddresses> => {
+  const cached = aclServedAddressesCache.get(chainId);
+  if (cached != null) return cached;
+
+  let aclAddress: Hex;
+  try {
+    aclAddress = await publicClient.readContract({
+      address: await getTaskManagerAddress(publicClient, chainId),
+      abi: ACL_SERVED_ADDRESSES_ABI,
+      functionName: 'acl',
+    });
+  } catch {
+    return {};
+  }
+
+  const [defaultRevoker, shareRegistry] = await Promise.all([
+    publicClient
+      .readContract({ address: aclAddress, abi: ACL_SERVED_ADDRESSES_ABI, functionName: 'defaultRevokerContract' })
+      .catch(() => undefined),
+    publicClient
+      .readContract({ address: aclAddress, abi: ACL_SERVED_ADDRESSES_ABI, functionName: 'shareRegistry' })
+      .catch(() => undefined),
+  ]);
+
+  const resolved: AclServedAddresses = {
+    defaultRevoker: defaultRevoker != null && defaultRevoker !== zeroAddress ? defaultRevoker : undefined,
+    shareRegistry: shareRegistry != null && shareRegistry !== zeroAddress ? shareRegistry : undefined,
+  };
+  aclServedAddressesCache.set(chainId, resolved);
+  return resolved;
+};