@cofhe/sdk 0.8.0 → 1.0.0-alpha.0

package/core/acps.ts

@@ -16,7 +16,12 @@ import {
   ACP_SHARE_REGISTRY_ABI,
   toChainShare,
   computeShareId,
-  shareIdOfChainShare,
+  readSharesFor,
+  readShare,
+  decodeShareAppKey,
+  encodeShareMetadata,
+  type PostedShare,
+  type ShareLabel,
   getAclServedAddresses,
   clearAclServedAddresses,
 } from '@/acps';
@@ -98,13 +103,28 @@ export type ImportActivationOptions = {
   activate?: boolean;
 };
 
+/** Options for importing a shared acp: activation, and the recipient's own name for it. */
+export type ImportSharedOptions = ImportActivationOptions & {
+  /**
+   * The name of the imported acp. Defaults to "Shared by 0x1234…abcd" (its issuer); the issuer's
+   * own name for the share is not exported and is ignored if present.
+   */
+  name?: string;
+};
+
 const importShared = async (
   options: ImportSharedACPOptions | string,
   publicClient: PublicClient,
   walletClient: WalletClient,
-  { activate = true }: ImportActivationOptions = {}
+  { activate = true, name }: ImportSharedOptions = {}
 ): Promise<RecipientACP> => {
-  return createACPWithSign(options, publicClient, walletClient, ACPUtils.importSharedAndSign, activate);
+  return createACPWithSign(
+    options,
+    publicClient,
+    walletClient,
+    (o, pc, wc) => ACPUtils.importSharedAndSign(o, pc, wc, { name }),
+    activate
+  );
 };
 
 // ACP UTILS
@@ -222,15 +242,14 @@ const getOrCreateSharingACP = async (
 // CONFIG DEFAULTS
 
 /**
- * Applies the config's ACP acp defaults to creation options (pure).
- * Explicit user options always win:
- *  - revoker: injected only when the options carry NO revoker pair —
- *    revokerContract = config default, revokerData = creation timestamp
- *    ("every acp revocable by default")
+ * Applies the config's ACP defaults to creation options. Explicit user options always win:
+ *  - revoker: injected only when the options carry NO revoker pair. The contract is the
+ *    config's `defaultRevoker` for the chain, else the one the ACL serves; the id
+ *    (`revokerData`) is the latest block's timestamp ("every acp revocable by default")
  *  - contracts: injected only when the options carry NO scope fields at all —
  *    injecting scope makes the created acp non-global by default
  */
-const applyACPDefaults = <
+const applyACPDefaultsFromChain = async <
   T extends {
     revokerData?: number;
     revokerContract?: string;
@@ -241,20 +260,19 @@ const applyACPDefaults = <
 >(
   options: T,
   acpConfig: { defaultRevoker?: Record<number, Hex>; defaultContractScopes?: Record<number, Hex[]> } | undefined,
+  publicClient: PublicClient,
   chainId: number
-): T => {
+): Promise<T> => {
   const result = { ...options };
 
-  const defaultRevoker = acpConfig?.defaultRevoker?.[chainId];
-  const hasValidatorOptions = options.revokerData != null || options.revokerContract != null;
-  if (defaultRevoker != null && !hasValidatorOptions) {
-    result.revokerContract = defaultRevoker;
-    // Creation timestamp minus a clock-skew allowance: the revoker rejects
-    // future-dated ids (vs block.timestamp of the LAST block), so a local clock
-    // ahead of the chain — or a chain with sparse blocks — would otherwise make
-    // a fresh acp temporarily unusable. 60s of backdating costs nothing
-    // (revokeAllExisting at time T still kills this acp for any T >= id).
-    result.revokerData = Math.round(Date.now() / 1000) - 60;
+  const hasRevokerOptions = options.revokerData != null || options.revokerContract != null;
+  if (!hasRevokerOptions) {
+    const defaultRevoker =
+      acpConfig?.defaultRevoker?.[chainId] ?? (await getAclServedAddresses(publicClient, chainId)).defaultRevoker;
+    if (defaultRevoker != null) {
+      result.revokerContract = defaultRevoker;
+      result.revokerData = await getBlockRevokerData(publicClient);
+    }
   }
 
   const defaultContracts = acpConfig?.defaultContractScopes?.[chainId];
@@ -267,34 +285,20 @@ const applyACPDefaults = <
 };
 
 /**
- * `applyACPDefaults` with the ACL consulted for the default revoker when
- * `acp.defaultRevoker` config does not name one for this chain — explicit
- * config wins over the ACL-served address.
+ * The chain-aware revoker id source: the latest block timestamp, not the local
+ * clock. The revoker rejects future-dated ids against `block.timestamp` of the
+ * LAST block, so a local clock ahead of the chain (or a chain with sparse
+ * blocks) would otherwise make a freshly created acp temporarily unusable.
  */
-const applyACPDefaultsFromChain = async <
-  T extends {
-    revokerData?: number;
-    revokerContract?: string;
-    scope?: number;
-    contracts?: string[];
-    handles?: (bigint | number | string)[];
-  },
->(
-  options: T,
-  acpConfig: { defaultRevoker?: Record<number, Hex>; defaultContractScopes?: Record<number, Hex[]> } | undefined,
-  publicClient: PublicClient,
-  chainId: number
-): Promise<T> => {
-  const hasExplicitRevoker =
-    acpConfig?.defaultRevoker?.[chainId] != null || options.revokerData != null || options.revokerContract != null;
-  if (hasExplicitRevoker) return applyACPDefaults(options, acpConfig, chainId);
-
-  const served = await getAclServedAddresses(publicClient, chainId);
-  const effectiveConfig =
-    served.defaultRevoker != null
-      ? { ...acpConfig, defaultRevoker: { ...acpConfig?.defaultRevoker, [chainId]: served.defaultRevoker } }
-      : acpConfig;
-  return applyACPDefaults(options, effectiveConfig, chainId);
+const getBlockRevokerData = async (publicClient: PublicClient): Promise<number> => {
+  const block = await publicClient.getBlock();
+  const revokerData = Number(block.timestamp);
+  if (!Number.isSafeInteger(revokerData)) {
+    throw new Error(
+      `ACP revokerData cannot represent the chain block timestamp ${block.timestamp.toString()} as a safe integer`
+    );
+  }
+  return revokerData;
 };
 
 // REVOKE (on-chain, via the acp's revoker contract)
@@ -390,14 +394,33 @@ const isACPRevoked = async (acp: ACP, publicClient: PublicClient): Promise<boole
   });
 };
 
+/**
+ * What `shareOnChain` posts with a share: the labels of its handles (one per handle, in order;
+ * encoded with `encodeShareMetadata`), or an already encoded metadata blob. Written once, with the
+ * share. Omitted, the labels the acp was created with are posted (`createSharing({ labels })`),
+ * or none. `appKey` goes with given labels; a client configured with `acp: { app }` fills it in.
+ */
+export type ShareOnChainOptions = { labels?: readonly ShareLabel[]; metadata?: Hex; appKey?: Hex };
+
+const metadataOf = (acp: ACP, { labels, metadata, appKey }: ShareOnChainOptions): Hex => {
+  if (labels != null && metadata != null) throw new Error('Pass either labels or metadata, not both');
+  if (labels == null) return metadata ?? acp.metadata ?? '0x';
+  if (labels.length !== acp.handles.length) {
+    throw new Error(`Cannot label a share of ${acp.handles.length} handles with ${labels.length} labels`);
+  }
+  return encodeShareMetadata(labels, { issuer: acp.issuer, appKey });
+};
+
 /**
  * Post a signed sharing ACP to the on-chain share registry for its recipient
- * to discover and import — the on-chain alternative to `export()`.
+ * to discover and import — the on-chain alternative to `export()` — optionally
+ * with the labels of its handles.
  */
 const shareOnChain = async (
   acp: ACP,
   walletClient: WalletClient,
-  registry: Hex
+  registry: Hex,
+  options: ShareOnChainOptions = {}
 ): Promise<{ txHash: Hex; shareId: Hex }> => {
   if (acp.type !== 'sharing') {
     throw new Error(`Cannot share a '${acp.type}' ACP on-chain — only 'sharing' ACPs are shareable.`);
@@ -409,12 +432,13 @@ const shareOnChain = async (
   if (walletClient.account.address.toLowerCase() !== acp.issuer.toLowerCase()) {
     throw new Error('Only the ACP issuer can share it on-chain');
   }
+  const metadata = metadataOf(acp, options);
 
   const txHash = await walletClient.writeContract({
     address: registry,
     abi: ACP_SHARE_REGISTRY_ABI,
     functionName: 'share',
-    args: [toChainShare(acp)],
+    args: [toChainShare(acp), metadata],
     account: walletClient.account,
     chain: walletClient.chain ?? null,
   });
@@ -422,46 +446,71 @@ const shareOnChain = async (
   return { txHash, shareId: computeShareId(acp) };
 };
 
-/** All importable shares addressed to `recipient` (unexpired, not revoked). */
+const toIncomingShare = ({ shareId, share: s, metadata }: PostedShare): IncomingShare => ({
+  shareId,
+  issuer: s.issuer,
+  expiration: Number(s.expiration),
+  recipient: s.recipient,
+  revokerData: Number(s.revokerData),
+  revokerContract: s.revokerContract,
+  scope: Number(s.scope),
+  contracts: [...s.contracts],
+  handles: [...s.handles],
+  issuerSignature: s.issuerSignature,
+  metadata,
+  ...(appKeyOf(metadata, s.handles) && { appKey: appKeyOf(metadata, s.handles) }),
+});
+
+/** The app key of a posted share; undefined when it has none, or its metadata does not decode. */
+const appKeyOf = (metadata: Hex, handles: readonly Hex[]): Hex | undefined => {
+  try {
+    return decodeShareAppKey(metadata, handles);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * All importable shares addressed to `recipient` (unexpired, not revoked): the headers from
+ * `sharesFor`, then each share's `Shared` event from the block its header names (one
+ * single-block `getLogs` per block). A share whose event the node cannot serve yet is left out
+ * and turns up on a later read; it never fails the others (`readSharesFor` lists it as
+ * unreadable). Given an `appKey`, only the shares posted with that key.
+ */
 const getIncomingShares = async (
   publicClient: PublicClient,
   registry: Hex,
-  recipient: Hex
+  recipient: Hex,
+  { appKey }: { appKey?: Hex } = {}
 ): Promise<IncomingShare[]> => {
-  const raw = await publicClient.readContract({
-    address: registry,
-    abi: ACP_SHARE_REGISTRY_ABI,
-    functionName: 'sharesFor',
-    args: [recipient],
-  });
+  const shares = (await readSharesFor(publicClient, registry, recipient)).posted.map(toIncomingShare);
+  return appKey == null ? shares : shares.filter((share) => share.appKey === appKey);
+};
 
-  return raw.map((s) => ({
-    shareId: shareIdOfChainShare(s),
-    issuer: s.issuer,
-    expiration: Number(s.expiration),
-    recipient: s.recipient,
-    revokerData: Number(s.revokerData),
-    revokerContract: s.revokerContract,
-    scope: Number(s.scope),
-    contracts: [...s.contracts],
-    handles: [...s.handles],
-    issuerSignature: s.issuerSignature,
-  }));
+/** One share by id, as posted; null when unknown or removed. Expired or revoked shares are returned as is. */
+const getShareFromChain = async (
+  publicClient: PublicClient,
+  registry: Hex,
+  shareId: Hex
+): Promise<IncomingShare | null> => {
+  const posted = await readShare(publicClient, registry, shareId);
+  return posted && toIncomingShare(posted);
 };
 
 /**
  * Import a share read from the registry: fills the recipient's sealing key,
  * signs, stores and (unless `activate: false`) activates — the on-chain
- * counterpart of importing an exported JSON blob. The share stays on-chain
+ * counterpart of importing an exported JSON blob. Its metadata is kept on the
+ * recipient acp, as with an import of exported JSON. The share stays on-chain
  * until dismissed.
  */
 const importFromChain = async (
   share: IncomingShare,
   publicClient: PublicClient,
   walletClient: WalletClient,
-  importOptions: ImportActivationOptions = {}
+  importOptions: ImportSharedOptions = {}
 ): Promise<RecipientACP> => {
-  const { shareId: _shareId, ...options } = share;
+  const { shareId: _shareId, appKey: _appKey, ...options } = share;
   return importShared({ ...options, type: 'sharing' }, publicClient, walletClient, importOptions);
 };
 
@@ -519,11 +568,11 @@ export const acps = {
 
   shareOnChain,
   getIncomingShares,
+  getShareFromChain,
   importFromChain,
   removeShareOnChain,
   computeShareId,
 
-  applyACPDefaults,
   applyACPDefaultsFromChain,
   getAclServedAddresses,
   clearAclServedAddresses,

package/core/client.ts

@@ -1,4 +1,5 @@
 import type { CreateSelfACPOptions, CreateSharingACPOptions, ImportSharedACPOptions } from '@/acps';
+import { decodeShareMetadata, shareAppKey, verifyShareLabels } from '@/acps';
 
 import { createStore } from 'zustand/vanilla';
 import { type Hex, type PublicClient, type WalletClient } from 'viem';
@@ -50,6 +51,10 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
 
   // Share registry resolution: explicit `acp.sharingRegistry` config wins,
   // otherwise the address the chain's ACL serves.
+  /** `{ appKey }` of `config.acp.app`, for the shares this client creates, posts and lists; `{}` without an app. */
+  const withAppKey = (): { appKey?: `0x${string}` } =>
+    opts.config.acp?.app == null ? {} : { appKey: shareAppKey(opts.config.acp.app) };
+
   const _resolveSharingRegistry = async (publicClient: PublicClient, chainId: number): Promise<`0x${string}`> => {
     const configured = opts.config.acp?.sharingRegistry?.[chainId];
     if (configured != null) return configured;
@@ -254,7 +259,7 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
       const { publicClient, walletClient } = clients ?? connectStore.getState();
       const chainId = await publicClient!.getChainId();
       return acps.createSharing(
-        await acps.applyACPDefaultsFromChain(options, opts.config.acp, publicClient!, chainId),
+        await acps.applyACPDefaultsFromChain({ ...withAppKey(), ...options }, opts.config.acp, publicClient!, chainId),
         publicClient!,
         walletClient!
       );
@@ -262,9 +267,9 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
 
     importShared: async (options: ImportSharedACPOptions | string, importOptions = {}) => {
       _requireConnected();
-      const { activate, ...clients } = importOptions;
+      const { activate, name, ...clients } = importOptions;
       const { publicClient, walletClient } = clients.publicClient ? clients : connectStore.getState();
-      return acps.importShared(options, publicClient!, walletClient!, { activate });
+      return acps.importShared(options, publicClient!, walletClient!, { activate, name });
     },
 
     // Get or create methods (require connection)
@@ -288,7 +293,7 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
       return acps.getOrCreateSharingACP(
         publicClient!,
         walletClient!,
-        await acps.applyACPDefaultsFromChain(options, opts.config.acp, publicClient!, _chainId),
+        await acps.applyACPDefaultsFromChain({ ...withAppKey(), ...options }, opts.config.acp, publicClient!, _chainId),
         _chainId,
         _account
       );
@@ -320,12 +325,12 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
     },
 
     // On-chain sharing (require connection + config.acp.sharingRegistry)
-    shareOnChain: async (acp) => {
+    shareOnChain: async (acp, options) => {
       _requireConnected();
       const { publicClient, walletClient } = connectStore.getState();
       const chainId = await publicClient!.getChainId();
       const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
-      return acps.shareOnChain(acp, walletClient!, sharingRegistry);
+      return acps.shareOnChain(acp, walletClient!, sharingRegistry, { ...withAppKey(), ...options });
     },
 
     getIncomingShares: async () => {
@@ -334,7 +339,28 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
       const chainId = await publicClient!.getChainId();
       const account = walletClient!.account!.address;
       const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
-      return acps.getIncomingShares(publicClient!, sharingRegistry, account);
+      return acps.getIncomingShares(publicClient!, sharingRegistry, account, withAppKey());
+    },
+
+    getShareFromChain: async (shareId) => {
+      _requireConnected();
+      const { publicClient } = connectStore.getState();
+      const chainId = await publicClient!.getChainId();
+      const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
+      return acps.getShareFromChain(publicClient!, sharingRegistry, shareId);
+    },
+
+    verifyShareLabels: async (share, options) => {
+      _requireConnected();
+      const { publicClient } = connectStore.getState();
+      if (share.metadata == null || share.metadata === '0x') return null;
+      return verifyShareLabels({
+        labels: decodeShareMetadata(share.metadata, share.handles),
+        handles: share.handles,
+        issuer: share.issuer,
+        publicClient: publicClient!,
+        verify: options?.verify,
+      });
     },
 
     importFromChain: async (share, options) => {

package/core/clientTypes.ts

@@ -6,7 +6,7 @@ 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, type ImportActivationOptions } 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 {
@@ -19,7 +19,9 @@ import type {
   RecipientACP,
   SelfACP,
   IncomingShare,
+  LabelledShare,
 } from 'acps/types.js';
+import type { ShareLabelCheck, ShareLabelVerifyMode } from 'acps/share-metadata/verify.js';
 
 // CLIENT
 
@@ -77,9 +79,10 @@ export type CofheClientACPsClients = {
 
 /**
  * Options for `importShared`. `activate: false` stores the imported acp without making it the active
- * one (default `true`). Clients default to the connected ones; pass both to override.
+ * one (default `true`). `name` names it (default "Shared by 0x1234…abcd"). Clients default to the
+ * connected ones; pass both to override.
  */
-export type CofheClientImportSharedOptions = ImportActivationOptions &
+export type CofheClientImportSharedOptions = ImportSharedOptions &
   (CofheClientACPsClients | { publicClient?: undefined; walletClient?: undefined });
 
 export type CofheClientACPs = {
@@ -121,12 +124,27 @@ export type CofheClientACPs = {
    */
   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[]>;
+  /** 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?: ImportActivationOptions) => Promise<RecipientACP>;
+  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. */

package/core/config.ts

@@ -73,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: {
@@ -138,6 +145,7 @@ export const CofheConfigSchema = 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/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

@@ -30,6 +30,9 @@ 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))`
  *
@@ -52,7 +55,7 @@ export async function verifyDecryptResult(
     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;
       }