@cofhe/sdk 0.7.1 → 0.8.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,7 @@ 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';
 
 /**
  * Main ACP utilities - functional approach for React compatibility
@@ -408,4 +409,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

@@ -19,6 +19,17 @@ export type {
 // Main utilities
 export { ACPUtils } from './acp.js';
 
+// On-chain sharing: registry / revoker ABIs, the registry payload and share id of a sharing ACP
+export * from './registry.js';
+
+// Addresses the chain ACL serves (TaskManager -> acl() -> default revoker, share registry)
+export {
+  getAclAddress,
+  getAclServedAddresses,
+  clearAclServedAddresses,
+  type AclServedAddresses,
+} from './onchain-utils.js';
+
 // Validation utilities
 export {
   // Self ACP validators

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

package/acps/registry.ts

@@ -0,0 +1,73 @@
+import { encodeAbiParameters, keccak256, parseAbi, type AbiParameterToPrimitiveType, type Hex } from 'viem';
+import { ACPUtils } from './acp.js';
+import type { ACP } from './types.js';
+
+/**
+ * The on-chain sharing pieces: the share registry and revoker ABIs, the registry payload of a
+ * sharing ACP and its share id. Exported so an app can send these writes through its own
+ * transaction path and still agree with the registry on ids.
+ */
+
+// ACP default revoker (timestamp-based revocation) — interface shared by all revokers
+export const ACP_REVOKER_ABI = parseAbi([
+  'function revokeSingle(uint256 id)',
+  'function revokeAllExisting()',
+  'function disabled(address issuer, uint256 id) view returns (bool)',
+]);
+
+// SHARE (on-chain, via the ACPShareRegistry)
+
+export const ACP_SHARE_REGISTRY_ABI = parseAbi([
+  'struct ACP { address issuer; uint64 expiration; address recipient; uint256 revokerData; address revokerContract; uint8 scope; address[] contracts; bytes32[] handles; bytes32 sealingKey; bytes issuerSignature; bytes recipientSignature; }',
+  'function share(ACP calldata acp) external returns (bytes32)',
+  'function removeShare(bytes32 shareId) external',
+  'function sharesFor(address recipient) external view returns (ACP[] memory)',
+  'function getShare(bytes32 shareId) external view returns (ACP memory)',
+  'function isShareValid(bytes32 shareId) external view returns (bool)',
+]);
+
+export const ACP_SHARE_TUPLE_ABI = [
+  {
+    type: 'tuple',
+    components: [
+      { name: 'issuer', type: 'address' },
+      { name: 'expiration', type: 'uint64' },
+      { name: 'recipient', type: 'address' },
+      { name: 'revokerData', type: 'uint256' },
+      { name: 'revokerContract', type: 'address' },
+      { name: 'scope', type: 'uint8' },
+      { name: 'contracts', type: 'address[]' },
+      { name: 'handles', type: 'bytes32[]' },
+      { name: 'sealingKey', type: 'bytes32' },
+      { name: 'issuerSignature', type: 'bytes' },
+      { name: 'recipientSignature', type: 'bytes' },
+    ],
+  },
+] as const;
+
+const ZERO_BYTES32 = `0x${'0'.repeat(64)}` as Hex;
+
+/** The on-chain payload for a sharing ACP: recipient-side fields empty. */
+export const toChainShare = (acp: ACP) => {
+  // Same public struct as the off-chain export flow (ACPUtils.getPublic), with
+  // the recipient-side fields blanked — the recipient supplies them at import —
+  // and uint fields widened for the ABI encoder.
+  const pub = ACPUtils.getPublic(acp, true);
+  return {
+    ...pub,
+    expiration: BigInt(pub.expiration),
+    revokerData: BigInt(pub.revokerData),
+    sealingKey: ZERO_BYTES32,
+    recipientSignature: '0x' as Hex,
+  };
+};
+
+/** Mirrors the registry's `keccak256(abi.encode(acp))` share id. */
+export const computeShareId = (acp: ACP): Hex => {
+  const p = toChainShare(acp);
+  return keccak256(encodeAbiParameters(ACP_SHARE_TUPLE_ABI, [p]));
+};
+
+/** The share id of a registry payload as read back from `sharesFor` / `getShare`. */
+export const shareIdOfChainShare = (share: AbiParameterToPrimitiveType<(typeof ACP_SHARE_TUPLE_ABI)[0]>): Hex =>
+  keccak256(encodeAbiParameters(ACP_SHARE_TUPLE_ABI, [share]));

package/acps/test/onchainAccessStatus.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { PublicClient } from 'viem';
+import { checkACPValidityOnChain, getACPAccessStatusOnChain } from '../onchain-utils';
+import type { ACPPublic } from '../types';
+
+const TASK_MANAGER = '0x0000000000000000000000000000000000005000';
+const ACL = '0x00000000000000000000000000000000000000ac';
+const ISSUER = '0x00000000000000000000000000000000000000b0';
+
+const acp: ACPPublic = {
+  issuer: ISSUER,
+  expiration: 2_000_000_000,
+  recipient: '0x00000000000000000000000000000000000000a1',
+  revokerData: 1,
+  revokerContract: '0x00000000000000000000000000000000000000cc',
+  scope: 2,
+  contracts: [],
+  handles: [],
+  sealingKey: `0x${'0'.repeat(64)}`,
+  issuerSignature: '0x01',
+  recipientSignature: '0x02',
+} as unknown as ACPPublic;
+
+/**
+ * A revert as a viem copy OTHER than the SDK one reports it: the same shape, but no class
+ * identity the SDK could match with `instanceof`.
+ */
+function foreignRevert(errorName: string) {
+  const reverted = { name: 'ContractFunctionRevertedError', data: { errorName } };
+  return Object.assign(new Error(`The contract function reverted: ${errorName}`), {
+    walk: (fn: (e: unknown) => boolean) => (fn(reverted) ? reverted : null),
+  });
+}
+
+function client({ simulate, reads = {} }: { simulate?: () => unknown; reads?: Record<string, () => unknown> }) {
+  return {
+    chain: { id: 31337 },
+    readContract: vi.fn(async ({ functionName }: { functionName: string }) => {
+      if (functionName === 'getTm') return TASK_MANAGER;
+      if (functionName === 'acl') return ACL;
+      const read = reads[functionName];
+      if (!read) throw new Error(`unexpected read ${functionName}`);
+      return read();
+    }),
+    simulateContract: vi.fn(async () => simulate?.()),
+  } as unknown as PublicClient;
+}
+
+describe('getACPAccessStatusOnChain', () => {
+  it('returns valid when the ACL accepts the ACP', async () => {
+    expect(await getACPAccessStatusOnChain(acp, client({}))).toBe('valid');
+  });
+
+  it.each([
+    ['PermissionInvalid_Expired', 'expired'],
+    ['PermissionInvalid_Disabled', 'revoked'],
+    ['PermissionInvalid_IssuerSignature', 'invalid-issuer-signature'],
+    ['PermissionInvalid_RecipientSignature', 'invalid-recipient-signature'],
+  ])('maps %s to %s, even from another viem copy', async (errorName, status) => {
+    const publicClient = client({
+      simulate: () => {
+        throw foreignRevert(errorName);
+      },
+    });
+    expect(await getACPAccessStatusOnChain(acp, publicClient)).toBe(status);
+  });
+
+  it('tells out-of-scope from issuer-not-allowed with the issuer own allowance', async () => {
+    const outOfScope = client({ reads: { isAllowedWithPermission: () => false, isAllowed: () => true } });
+    const notAllowed = client({ reads: { isAllowedWithPermission: () => false, isAllowed: () => false } });
+    const allowed = client({ reads: { isAllowedWithPermission: () => true } });
+    expect(await getACPAccessStatusOnChain(acp, outOfScope, 1n)).toBe('out-of-scope');
+    expect(await getACPAccessStatusOnChain(acp, notAllowed, '0x01')).toBe('issuer-not-allowed');
+    expect(await getACPAccessStatusOnChain(acp, allowed, 1n)).toBe('allowed');
+  });
+
+  it('maps a revert on the handle check too', async () => {
+    const publicClient = client({
+      reads: {
+        isAllowedWithPermission: () => {
+          throw foreignRevert('PermissionInvalid_Disabled');
+        },
+      },
+    });
+    expect(await getACPAccessStatusOnChain(acp, publicClient, 1n)).toBe('revoked');
+  });
+
+  it('reads a revert reported only as text with the error selector', async () => {
+    const publicClient = client({
+      simulate: () => {
+        throw new Error('Execution reverted with reason: RPC eth_call failed: custom error 0xcbd3a966.');
+      },
+    });
+    expect(await getACPAccessStatusOnChain(acp, publicClient)).toBe('revoked');
+  });
+
+  it('still throws what is not an ACL revert', async () => {
+    const publicClient = client({
+      simulate: () => {
+        throw new Error('fetch failed');
+      },
+    });
+    await expect(getACPAccessStatusOnChain(acp, publicClient)).rejects.toThrow('fetch failed');
+  });
+});
+
+describe('checkACPValidityOnChain', () => {
+  it('names the revert from another viem copy instead of rethrowing it raw', async () => {
+    const publicClient = client({
+      simulate: () => {
+        throw foreignRevert('PermissionInvalid_Disabled');
+      },
+    });
+    await expect(checkACPValidityOnChain(acp, publicClient)).rejects.toThrow(/^PermissionInvalid_Disabled$/);
+  });
+});

package/acps/types.ts

@@ -221,6 +221,22 @@ export type SharedACP = Expand<
   }
 >;
 
+/**
+ * An ACP on-chain status, as `client.acp.checkAccess` reports it instead of a revert.
+ * Without a handle: 'valid' or the reason it is not. With a handle, a valid ACP reports
+ * 'allowed', 'out-of-scope' (the ACP scope does not cover the handle) or
+ * 'issuer-not-allowed' (the issuer itself may not read the handle, so no ACP of theirs can).
+ */
+export type ACPAccessStatus =
+  | 'valid'
+  | 'allowed'
+  | 'out-of-scope'
+  | 'issuer-not-allowed'
+  | 'expired'
+  | 'revoked'
+  | 'invalid-issuer-signature'
+  | 'invalid-recipient-signature';
+
 /**
  * A share read back from the on-chain ACPShareRegistry: the posted payload
  * (SharedACP minus the client-side name/type) plus its registry id.

package/chains/chains/arbitrum.ts

@@ -0,0 +1,14 @@
+import { defineChain } from '../defineChain.js';
+
+/**
+ * Arbitrum One mainnet chain configuration
+ */
+export const arbitrum = defineChain({
+  id: 42161,
+  name: 'Arbitrum One',
+  network: 'arbitrum',
+  coFheUrl: 'https://cofhe.mainnet.fhenix.zone',
+  verifierUrl: 'https://cofhe-vrf.mainnet.fhenix.zone',
+  thresholdNetworkUrl: 'https://cofhe-tn.mainnet.fhenix.zone',
+  environment: 'MAINNET',
+});

package/chains/chains/ethereum.ts

@@ -0,0 +1,14 @@
+import { defineChain } from '../defineChain.js';
+
+/**
+ * Ethereum mainnet chain configuration
+ */
+export const ethereum = defineChain({
+  id: 1,
+  name: 'Ethereum',
+  network: 'ethereum',
+  coFheUrl: 'https://cofhe.mainnet.fhenix.zone',
+  verifierUrl: 'https://cofhe-vrf.mainnet.fhenix.zone',
+  thresholdNetworkUrl: 'https://cofhe-tn.mainnet.fhenix.zone',
+  environment: 'MAINNET',
+});

package/chains/index.ts

@@ -5,17 +5,21 @@ export type { CofheChain, Environment } from './types.js';
 import { sepolia } from './chains/sepolia.js';
 import { arbSepolia } from './chains/arbSepolia.js';
 import { baseSepolia } from './chains/baseSepolia.js';
+import { ethereum } from './chains/ethereum.js';
+import { arbitrum } from './chains/arbitrum.js';
 import { hardhat } from './chains/hardhat.js';
 import { localcofhe } from './chains/localcofhe.js';
 import { stagingCofhe } from './chains/stagingCofhe.js';
 
-export { sepolia, arbSepolia, baseSepolia, hardhat, localcofhe, stagingCofhe };
+export { sepolia, arbSepolia, baseSepolia, ethereum, arbitrum, hardhat, localcofhe, stagingCofhe };
 
 // Export all chains as a collection
 export const chains = {
   sepolia,
   arbSepolia,
   baseSepolia,
+  ethereum,
+  arbitrum,
   hardhat,
   localcofhe,
   stagingCofhe,