@cofhe/sdk 0.8.0 → 1.0.0

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/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/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/utils.ts

@@ -5,9 +5,22 @@ import { FheTypes } from './types.js';
 export const toHexString = (bytes: Uint8Array) =>
   bytes.reduce((str, byte) => str + byte.toString(16).padStart(2, '0'), '');
 
+const HEX_BODY_REGEX = /^[0-9a-fA-F]*$/;
+
 export const fromHexString = (hexString: string): Uint8Array => {
-  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
-  const arr = cleanString.replace(/^0x/, '').match(/.{1,2}/g);
+  // Strip `0x` before padding: padding first turns `0x123` into `00x123`, which no
+  // longer matches the prefix and decodes to garbage bytes.
+  const body = hexString.replace(/^0x/, '');
+
+  // `parseInt` maps a non-hex pair to NaN, which `Uint8Array` stores as 0. Without this check a
+  // malformed hex string silently becomes zero bytes instead of failing.
+  if (!HEX_BODY_REGEX.test(body)) {
+    // The value is omitted on purpose: callers may pass private keys or sensitive payloads.
+    throw new Error('Invalid hex string: contains non-hexadecimal characters');
+  }
+
+  const padded = body.length % 2 === 1 ? `0${body}` : body;
+  const arr = padded.match(/.{1,2}/g);
   if (!arr) return new Uint8Array();
   return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
 };
@@ -35,13 +48,7 @@ export const validateBigIntInRange = (value: bigint, max: bigint, min: bigint =
 };
 
 // Helper function to convert hex string to bytes
-export const hexToBytes = (hex: string): Uint8Array => {
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < hex.length; i += 2) {
-    bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
-  }
-  return bytes;
-};
+export const hexToBytes = (hex: string): Uint8Array => fromHexString(hex);
 
 export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));