@cofhe/sdk 0.7.1 → 1.0.0-alpha.0

package/core/test/decryptBuilders.test.ts

@@ -1,13 +1,26 @@
-import { describe, it, expect } from 'vitest';
-import { type PublicClient, type WalletClient, createPublicClient, createWalletClient, http } from 'viem';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { type PublicClient, type WalletClient, createPublicClient, createWalletClient, http, zeroAddress } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { arbitrumSepolia } from 'viem/chains';
+import { ACPUtils, acpStore, type ACP } from '@/acps';
 import { DecryptForTxBuilder } from '../decrypt/decryptForTxBuilder.js';
 import { DecryptForViewBuilder } from '../decrypt/decryptForViewBuilder.js';
+import { tnDecryptV2 } from '../decrypt/tnDecryptV2';
+import { tnSealOutputV2 } from '../decrypt/tnSealOutputV2';
 import { createCofheConfigBase, type CofheConfig } from '../config.js';
 import { CofheErrorCode } from '../error.js';
 import { FheTypes } from '../types.js';
 
+// Stub the threshold network calls so tests can assert whether a request was dispatched
+vi.mock('../decrypt/tnDecryptV2', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../decrypt/tnDecryptV2')>()),
+  tnDecryptV2: vi.fn(),
+}));
+vi.mock('../decrypt/tnSealOutputV2', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../decrypt/tnSealOutputV2')>()),
+  tnSealOutputV2: vi.fn(),
+}));
+
 const TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
 const account = privateKeyToAccount(TEST_PRIVATE_KEY);
 const TEST_CHAIN_ID = 421614;
@@ -416,3 +429,98 @@ describe('DecryptForViewBuilder', () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Expired acp (regression, issue #272)
+//
+// The getOrCreate* half of #272 is covered in acps.test.ts. These cover the decrypt path:
+// execute() must reject an expired acp (ACPUtils.validate) before any request is dispatched
+// to the threshold network, however the acp was selected.
+// ---------------------------------------------------------------------------
+
+describe('execute – expired acp (regression, issue #272)', () => {
+  type Selection = 'active acp' | 'acp hash' | 'acp object';
+  const selections: Selection[] = ['active acp', 'acp hash', 'acp object'];
+
+  const now = () => Math.floor(Date.now() / 1000);
+
+  // Built by hand rather than with ACPUtils.sign, which reads the ACL's EIP-712 domain over RPC.
+  // validate() only checks that a signature is present, and the threshold network is stubbed.
+  function createSignedSelfACP(expiration: number): ACP {
+    return {
+      ...ACPUtils.createSelf({ name: 'Test Self ACP', issuer: account.address, expiration }),
+      issuerSignature: `0x${'11'.repeat(65)}`,
+      _signedDomain: { name: 'ACL', version: '1', chainId: TEST_CHAIN_ID, verifyingContract: zeroAddress },
+    };
+  }
+
+  // Stores the acp and makes it the active acp for the test chain + account
+  function seedACP(acp: ACP) {
+    acpStore.setACP(TEST_CHAIN_ID, account.address, acp);
+    acpStore.setActiveACPHash(TEST_CHAIN_ID, account.address, acp.hash);
+  }
+
+  function selectTxACP(selection: Selection, acp: ACP) {
+    const builder = createTxBuilder();
+    if (selection === 'acp hash') return builder.withACP(acp.hash);
+    if (selection === 'acp object') return builder.withACP(acp);
+    return builder.withACP();
+  }
+
+  function selectViewACP(selection: Selection, acp: ACP) {
+    const builder = createViewBuilder(FheTypes.Uint32);
+    if (selection === 'acp hash') return builder.withACP(acp.hash);
+    if (selection === 'acp object') return builder.withACP(acp);
+    return builder.withACP();
+  }
+
+  beforeEach(() => {
+    acpStore.store.setState({ acps: {}, activeACPHash: {} });
+    vi.mocked(tnDecryptV2).mockReset();
+    vi.mocked(tnSealOutputV2).mockReset();
+  });
+
+  afterEach(() => {
+    acpStore.store.setState({ acps: {}, activeACPHash: {} });
+  });
+
+  describe('decryptForTx', () => {
+    it.each(selections)('rejects an expired acp selected via %s without dispatching', async (selection) => {
+      const acp = createSignedSelfACP(now() - 3600);
+      seedACP(acp);
+
+      await expect(selectTxACP(selection, acp).execute()).rejects.toThrow('ACP is expired');
+      expect(tnDecryptV2).not.toHaveBeenCalled();
+    });
+
+    it('dispatches a valid acp (control for the expired cases)', async () => {
+      vi.mocked(tnDecryptV2).mockResolvedValue({ decryptedValue: 7n, signature: '0x1234' });
+      const acp = createSignedSelfACP(now() + 3600);
+      seedACP(acp);
+
+      const result = await selectTxACP('active acp', acp).execute();
+
+      expect(result.decryptedValue).toBe(7n);
+      expect(tnDecryptV2).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('decryptForView', () => {
+    it.each(selections)('rejects an expired acp selected via %s without dispatching', async (selection) => {
+      const acp = createSignedSelfACP(now() - 3600);
+      seedACP(acp);
+
+      await expect(selectViewACP(selection, acp).execute()).rejects.toThrow('ACP is expired');
+      expect(tnSealOutputV2).not.toHaveBeenCalled();
+    });
+
+    it('dispatches a valid acp (control for the expired cases)', async () => {
+      vi.mocked(tnSealOutputV2).mockRejectedValue(new Error('stubbed threshold network'));
+      const acp = createSignedSelfACP(now() + 3600);
+      seedACP(acp);
+
+      await expect(selectViewACP('active acp', acp).execute()).rejects.toThrow('stubbed threshold network');
+      expect(tnSealOutputV2).toHaveBeenCalledOnce();
+    });
+  });
+});

package/core/test/encryptInputsBuilder.test.ts

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

package/core/test/fetchKeys.test.ts

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

package/core/test/incomingShares.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { PublicClient } from 'viem';
+import { acps } from '../acps';
+import { UNLABELLED, encodeShareMetadata, shareAppKey } from '../../acps/share-metadata';
+import { shareIdOfChainShare, type ChainShare, type ShareHeader } from '../../acps/registry';
+
+const REGISTRY = '0x00000000000000000000000000000000000000e0';
+const ISSUER = '0x00000000000000000000000000000000000000b0';
+const RECIPIENT = '0x00000000000000000000000000000000000000a1';
+const ZERO = '0x0000000000000000000000000000000000000000';
+
+const chainShare = (handle: number): ChainShare => ({
+  issuer: ISSUER,
+  expiration: 2_000_000_000n,
+  recipient: RECIPIENT,
+  revokerData: 0n,
+  revokerContract: ZERO,
+  scope: 2,
+  contracts: [],
+  handles: [`0x${handle.toString(16).padStart(64, '0')}`],
+  sealingKey: `0x${'0'.repeat(64)}`,
+  issuerSignature: '0x11',
+  recipientSignature: '0x',
+});
+
+const header: ShareHeader = {
+  issuer: ISSUER,
+  expiration: 2_000_000_000n,
+  recipient: RECIPIENT,
+  blockNumber: 10n,
+  revokerContract: ZERO,
+  revokerData: 0n,
+};
+
+const EXPLORER = shareAppKey('explorer.fhenix.io');
+const WALLET = shareAppKey('wallet.example');
+
+/** Three shares in one block: one for the explorer, one for a wallet app, one for no app. */
+const shares = [chainShare(1), chainShare(2), chainShare(3)];
+const ids = shares.map(shareIdOfChainShare);
+const metadata = [
+  encodeShareMetadata([UNLABELLED], { appKey: EXPLORER }),
+  encodeShareMetadata([UNLABELLED], { appKey: WALLET }),
+  '0x',
+] as const;
+
+const client = {
+  readContract: vi.fn(async () => [ids, shares.map(() => header)]),
+  getContractEvents: vi.fn(async ({ args }: { args: { shareId: string[] } }) =>
+    shares
+      .map((acp, i) => ({ args: { shareId: ids[i], acp, metadata: metadata[i] } }))
+      .filter((e) => args.shareId.includes(e.args.shareId))
+  ),
+} as unknown as PublicClient;
+
+describe('getIncomingShares and the app key', () => {
+  it('lists every share without an app, each with the key it carries', async () => {
+    const incoming = await acps.getIncomingShares(client, REGISTRY, RECIPIENT);
+    expect(incoming.map((s) => s.shareId)).toEqual(ids);
+    expect(incoming.map((s) => s.appKey)).toEqual([EXPLORER, WALLET, undefined]);
+  });
+
+  it('lists only the shares posted for the app', async () => {
+    const incoming = await acps.getIncomingShares(client, REGISTRY, RECIPIENT, { appKey: EXPLORER });
+    expect(incoming.map((s) => s.shareId)).toEqual([ids[0]]);
+  });
+
+  it('leaves out a share whose event the node cannot serve yet, and keeps the rest', async () => {
+    const lagging = {
+      readContract: vi.fn(async () => [ids, shares.map(() => header)]),
+      getContractEvents: vi.fn(async ({ args }: { args: { shareId: string[] } }) =>
+        shares
+          .map((acp, i) => ({ args: { shareId: ids[i], acp, metadata: metadata[i] } }))
+          .filter((e) => args.shareId.includes(e.args.shareId) && e.args.shareId !== ids[1])
+      ),
+    } as unknown as PublicClient;
+    const incoming = await acps.getIncomingShares(lagging, REGISTRY, RECIPIENT);
+    expect(incoming.map((s) => s.shareId)).toEqual([ids[0], ids[2]]);
+  });
+
+  it('lists nothing for an app no share names', async () => {
+    expect(await acps.getIncomingShares(client, REGISTRY, RECIPIENT, { appKey: shareAppKey('other') })).toEqual([]);
+  });
+});

package/core/test/keyStore.test.ts

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

package/core/test/mocksEncryptRange.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, vi } from 'vitest';
+import { type PublicClient, type WalletClient } from 'viem';
+import { hardhat } from 'viem/chains';
+import { EncryptInputsBuilder } from '../encrypt/encryptInputsBuilder.js';
+import { Encryptable, FheTypes, type EncryptableItem } from '../types.js';
+import { createCofheConfigBase } from '../config.js';
+import { zkPack, type ZkCiphertextListBuilder } from '../encrypt/zkPackProveVerify.js';
+
+// The hardhat (mocks) encrypt path must reject the same out-of-range plaintexts that the
+// production path rejects in zkPack. Otherwise MockCoFHE._set masks the value with the utype
+// mask (e.g. uint8(256) -> 0) and tests pass on hardhat while the same call throws on a real chain.
+
+const account = '0x1234567890123456789012345678901234567890';
+const consumingContract = '0xbeefbeefbeefbeefbeefbeefbeefbeefbeefbeef';
+
+const fakeClients = () => {
+  const readContract = vi.fn(async ({ args }: any) => (args[0] as bigint[]).map((_, i) => BigInt(i + 1)));
+  const writeContract = vi.fn(async () => '0x' as `0x${string}`);
+  const publicClient = { readContract } as unknown as PublicClient;
+  const walletClient = { account: { address: account }, writeContract } as unknown as WalletClient;
+  return { publicClient, walletClient, readContract, writeContract };
+};
+
+const mocksBuilder = (inputs: EncryptableItem[]) => {
+  const { publicClient, walletClient, readContract, writeContract } = fakeClients();
+  const builder = new EncryptInputsBuilder({
+    inputs: inputs as any,
+    account,
+    chainId: hardhat.id,
+    config: createCofheConfigBase({ supportedChains: [], mocks: { encryptDelay: 0 } }),
+    publicClient,
+    walletClient,
+    zkvWalletClient: walletClient,
+    tfhePublicKeyDeserializer: vi.fn(),
+    compactPkeCrsDeserializer: vi.fn(),
+    zkBuilderAndCrsGenerator: vi.fn() as any,
+    initTfhe: undefined,
+    zkProveWorkerFn: undefined,
+    keysStorage: undefined,
+    requireConnected: vi.fn(),
+  });
+  builder.setConsumingContract(consumingContract);
+  return { builder, readContract, writeContract };
+};
+
+const noop = () => undefined;
+const noopZkBuilder = {
+  push_boolean: noop,
+  push_u8: noop,
+  push_u16: noop,
+  push_u32: noop,
+  push_u64: noop,
+  push_u128: noop,
+  push_u160: noop,
+  build_with_proof_packed: noop,
+} as unknown as ZkCiphertextListBuilder;
+
+const outOfRange: [string, EncryptableItem][] = [
+  ['uint8(256)', Encryptable.uint8(256n)],
+  ['uint16(65536)', Encryptable.uint16(65536n)],
+  ['uint32(2^32)', Encryptable.uint32(2n ** 32n)],
+  ['uint64(2^64)', Encryptable.uint64(2n ** 64n)],
+  ['uint128(2^128)', Encryptable.uint128(2n ** 128n)],
+  ['address(2^160)', { data: 2n ** 160n, securityZone: 0, utype: FheTypes.Uint160 } as EncryptableItem],
+];
+
+describe('mocks encrypt path value range parity', () => {
+  it.each(outOfRange)('production zkPack rejects %s', (_, item) => {
+    expect(() => zkPack([item], noopZkBuilder)).toThrow(/out of range/);
+  });
+
+  it.each(outOfRange)('hardhat mocks encrypt rejects %s before touching the chain', async (_, item) => {
+    const { builder, readContract, writeContract } = mocksBuilder([item]);
+    await expect(builder.execute()).rejects.toThrow(/out of range/);
+    expect(readContract).not.toHaveBeenCalled();
+    expect(writeContract).not.toHaveBeenCalled();
+  });
+
+  it('hardhat mocks encrypt still accepts the max value of each type', async () => {
+    const { builder, writeContract } = mocksBuilder([
+      Encryptable.uint8(255n),
+      Encryptable.uint16(65535n),
+      Encryptable.uint32(2n ** 32n - 1n),
+      Encryptable.uint64(2n ** 64n - 1n),
+      Encryptable.bool(true),
+    ]);
+    await expect(builder.execute()).resolves.toBeDefined();
+    expect(writeContract).toHaveBeenCalledTimes(1);
+  });
+});

package/core/test/taskManager.test.ts

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

package/core/test/utils.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from 'vitest';
+import {
+  fromHexString,
+  toHexString,
+  hexToBytes,
+  toBigIntOrThrow,
+  validateBigIntInRange,
+  fheTypeToString,
+} from '../utils.js';
+import { FheTypes } from '../types.js';
+
+describe('fromHexString', () => {
+  it('strips the 0x prefix before padding an odd-length string', () => {
+    // Regression: padding first produced `00x123`, which decoded to [0x00, NaN->0, 0x23].
+    expect(Array.from(fromHexString('0x123'))).toEqual([0x01, 0x23]);
+  });
+
+  it('pads odd-length strings without a prefix', () => {
+    expect(Array.from(fromHexString('123'))).toEqual([0x01, 0x23]);
+  });
+
+  it('decodes even-length strings with and without the 0x prefix identically', () => {
+    expect(Array.from(fromHexString('0x1234'))).toEqual([0x12, 0x34]);
+    expect(Array.from(fromHexString('1234'))).toEqual([0x12, 0x34]);
+  });
+
+  it('decodes uppercase hex', () => {
+    expect(Array.from(fromHexString('0xDEADBEEF'))).toEqual([0xde, 0xad, 0xbe, 0xef]);
+  });
+
+  it('returns an empty array for empty input', () => {
+    expect(fromHexString('')).toEqual(new Uint8Array());
+    expect(fromHexString('0x')).toEqual(new Uint8Array());
+  });
+
+  it('round-trips through toHexString', () => {
+    const hex = 'a3'.repeat(32);
+    const bytes = fromHexString(hex);
+
+    expect(bytes.length).toBe(32);
+    expect(toHexString(bytes)).toBe(hex);
+  });
+
+  it('throws instead of silently producing zero bytes for non-hex characters', () => {
+    expect(() => fromHexString('zzzz')).toThrow('Invalid hex string');
+  });
+
+  it('throws for hex strings with a single invalid character', () => {
+    expect(() => fromHexString('0x12g4')).toThrow('Invalid hex string');
+  });
+
+  it('only strips a lowercase 0x prefix', () => {
+    expect(() => fromHexString('0X12')).toThrow('Invalid hex string');
+  });
+
+  it('does not leak sensitive input in the error message', () => {
+    const secret = 'f'.repeat(63) + 'z';
+
+    expect(() => fromHexString(secret)).toThrow(
+      expect.objectContaining({ message: expect.not.stringContaining(secret) })
+    );
+  });
+});
+
+describe('hexToBytes', () => {
+  it('decodes even-length hex with and without prefix', () => {
+    expect(Array.from(hexToBytes('0x1234'))).toEqual([0x12, 0x34]);
+    expect(Array.from(hexToBytes('1234'))).toEqual([0x12, 0x34]);
+  });
+
+  it('handles odd-length hex correctly with prefix', () => {
+    expect(Array.from(hexToBytes('0x123'))).toEqual([0x01, 0x23]);
+    expect(Array.from(hexToBytes('123'))).toEqual([0x01, 0x23]);
+  });
+
+  it('throws for invalid hex characters', () => {
+    expect(() => hexToBytes('0x12z4')).toThrow('Invalid hex string');
+  });
+});
+
+describe('toHexString', () => {
+  it('pads each byte to 2 hex characters', () => {
+    const bytes = new Uint8Array([0x00, 0x0f, 0x10, 0xff]);
+    expect(toHexString(bytes)).toBe('000f10ff');
+  });
+});
+
+describe('toBigIntOrThrow', () => {
+  it('returns bigint unchanged if passed bigint', () => {
+    expect(toBigIntOrThrow(123n)).toBe(123n);
+  });
+
+  it('converts valid string to bigint', () => {
+    expect(toBigIntOrThrow('456')).toBe(456n);
+    expect(toBigIntOrThrow('0x10')).toBe(16n);
+  });
+
+  it('throws for invalid string', () => {
+    expect(() => toBigIntOrThrow('not-a-number')).toThrow('Invalid input: Unable to convert to bigint');
+  });
+});
+
+describe('validateBigIntInRange', () => {
+  it('accepts values within range', () => {
+    expect(() => validateBigIntInRange(10n, 20n, 0n)).not.toThrow();
+  });
+
+  it('throws when value exceeds max', () => {
+    expect(() => validateBigIntInRange(25n, 20n, 0n)).toThrow('Value out of range');
+  });
+
+  it('throws when value is below min', () => {
+    expect(() => validateBigIntInRange(5n, 20n, 10n)).toThrow('Value out of range');
+  });
+});
+
+describe('fheTypeToString', () => {
+  it('maps known types to string identifiers', () => {
+    expect(fheTypeToString(FheTypes.Bool)).toBe('bool');
+    expect(fheTypeToString(FheTypes.Uint8)).toBe('uint8');
+    expect(fheTypeToString(FheTypes.Uint16)).toBe('uint16');
+    expect(fheTypeToString(FheTypes.Uint32)).toBe('uint32');
+    expect(fheTypeToString(FheTypes.Uint64)).toBe('uint64');
+    expect(fheTypeToString(FheTypes.Uint128)).toBe('uint128');
+    expect(fheTypeToString(FheTypes.Uint160)).toBe('uint160');
+    expect(fheTypeToString(FheTypes.Uint256)).toBe('uint256');
+  });
+});

package/core/test/verifyDecryptResult.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { encodePacked, keccak256, zeroAddress, type Address, type PublicClient } from 'viem';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+
+import { verifyDecryptResult } from '../decrypt/verifyDecryptResult.js';
+import { clearTaskManagerAddressCache } from '../taskManager.js';
+
+const CHAIN_ID = 31337;
+const TM = '0x0000000000000000000000000000000000005000';
+// euint32 (utype 4) in the type byte
+const CT_HASH = (0xabcdefn << 16n) | (4n << 8n);
+const CLEARTEXT = 42n;
+
+const signer = privateKeyToAccount(generatePrivateKey());
+
+const signDecryptResult = (ctHash: bigint, cleartext: bigint) =>
+  signer.sign({
+    hash: keccak256(encodePacked(['uint256', 'uint32', 'uint64', 'uint256'], [cleartext, 4, BigInt(CHAIN_ID), ctHash])),
+  });
+
+const fakeClient = (decryptResultSigner: Address) =>
+  ({
+    chain: { id: CHAIN_ID },
+    readContract: vi.fn(async ({ functionName }: { functionName: string }) =>
+      functionName === 'getTm' ? TM : decryptResultSigner
+    ),
+  }) as unknown as PublicClient;
+
+describe('verifyDecryptResult', () => {
+  beforeEach(() => clearTaskManagerAddressCache());
+
+  it('accepts a result signed by the configured decryptResultSigner', async () => {
+    const signature = await signDecryptResult(CT_HASH, CLEARTEXT);
+
+    expect(await verifyDecryptResult(CT_HASH, CLEARTEXT, signature, fakeClient(signer.address))).to.equal(true);
+  });
+
+  it('rejects a result signed by a different key', async () => {
+    const signature = await signDecryptResult(CT_HASH, CLEARTEXT);
+    const other = privateKeyToAccount(generatePrivateKey());
+
+    expect(await verifyDecryptResult(CT_HASH, CLEARTEXT, signature, fakeClient(other.address))).to.equal(false);
+  });
+
+  it('fails closed when the decryptResultSigner is unset (zero address)', async () => {
+    const signature = await signDecryptResult(CT_HASH, CLEARTEXT);
+
+    expect(await verifyDecryptResult(CT_HASH, CLEARTEXT, signature, fakeClient(zeroAddress))).to.equal(false);
+    expect(await verifyDecryptResult(CT_HASH, CLEARTEXT, '0x', fakeClient(zeroAddress))).to.equal(false);
+  });
+});

package/core/types.ts

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