@cofhe/sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @cofhe/sdk Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- 35024b6: Remove `sdk` from function names and exported types. Rename:
+
+  - `createCofhesdkConfig` -> `createCofheConfig`
+  - `createCofhesdkClient` -> `createCofheClient`
+  - `hre.cofhesdk.*` -> `hre.cofhe.*`
+  - `hre.cofhesdk.createCofheConfig()` → `hre.cofhe.createConfig()`
+  - `hre.cofhesdk.createCofheClient()` → `hre.cofhe.createClient()`
+  - `hre.cofhesdk.createBatteriesIncludedCofheClient()` → `hre.cofhe.createClientWithBatteries()`
+
+- 29c2401: implement decrypt-with-proof flows and related tests:
+
+  - Implement production `decryptForTx` backed by Threshold Network `POST /decrypt`, with explicit permit vs global-allowance selection.
+  - Rename mocks “Query Decrypter” -> “Threshold Network” and update SDK constants/contracts/artifacts accordingly.
+  - Extend mock contracts + hardhat plugin to publish & verify decryption results on-chain, and add end-to-end integration tests.
+
+- 650ea48: Align builder patterns in cofhe client api (`client.encryptInputs(..).encrypt()` and `client.decryptHandles(..).decrypt()`) to use the same terminator function `.execute()` instead of `.encrypt()`/`.decrypt()`.
+
+  Rename `setStepCallback` of encryptInputs builder to `onStep` to improve ergonomics.
+
+### Patch Changes
+
+- 5467d77: Adds `config.mocks.encryptDelay: number | [number, number, number, number, number]` to allow configurable mock encryption delay. Defaults to 0 delay on hardhat to keep tests quick.
+- 73b1502: Add `cofheClient.connection` getter which exposes inner connection state without using `getSnapshot()` reactive utility.
+
+## 0.2.1
+
+### Patch Changes
+
+- 409bfdf: Add `hash` field to permits, calculated at permit creation time. Replaces `PermitUtils.getHash(permit)` with `permit.hash`.
+- ac47e2f: Add `PermitUtils.checkValidityOnChain` to validate permits against the on-chain deployed ACL (source of truth).
+- 8af1b70: Updated to Zod 4 for improved performance and type safety. Includes internal changes to validation schemas and error handling that should not affect external API usage.
+
 ## 0.2.0
 
 ### Minor Changes

package/chains/defineChain.ts

@@ -1,4 +1,5 @@
 import { CofheChainSchema, type CofheChain } from './types.js';
+import { z } from 'zod';
 
 /**
  * Defines and validates a CofheChain configuration
@@ -10,8 +11,7 @@ export function defineChain(chainConfig: CofheChain): CofheChain {
   const result = CofheChainSchema.safeParse(chainConfig);
 
   if (!result.success) {
-    const errorMessages = result.error.errors.map((err) => `${err.path.join('.')}: ${err.message}`);
-    throw new Error(`Invalid chain configuration: ${errorMessages.join(', ')}`);
+    throw new Error(`Invalid chain configuration: ${z.prettifyError(result.error)}`, { cause: result.error });
   }
 
   return result.data;

package/chains/types.ts

@@ -16,11 +16,11 @@ export const CofheChainSchema = z.object({
   /** Network identifier */
   network: z.string().min(1),
   /** coFhe service URL */
-  coFheUrl: z.string().url(),
+  coFheUrl: z.url(),
   /** Verifier service URL */
-  verifierUrl: z.string().url(),
+  verifierUrl: z.url(),
   /** Threshold network service URL */
-  thresholdNetworkUrl: z.string().url(),
+  thresholdNetworkUrl: z.url(),
   /** Environment type */
   environment: EnvironmentSchema,
 });

package/core/baseBuilder.ts

@@ -1,12 +1,12 @@
 import { type PublicClient, type WalletClient } from 'viem';
-import { type CofhesdkConfig } from './config.js';
-import { CofhesdkError, CofhesdkErrorCode } from './error.js';
+import { type CofheConfig } from './config.js';
+import { CofheError, CofheErrorCode } from './error.js';
 
 /**
  * Base parameters that all builders need
  */
 export type BaseBuilderParams = {
-  config: CofhesdkConfig | undefined;
+  config: CofheConfig | undefined;
   publicClient: PublicClient | undefined;
   walletClient: WalletClient | undefined;
 
@@ -21,7 +21,7 @@ export type BaseBuilderParams = {
  * for working with clients, config, and chain IDs
  */
 export abstract class BaseBuilder {
-  protected config: CofhesdkConfig;
+  protected config: CofheConfig;
 
   protected publicClient: PublicClient | undefined;
   protected walletClient: WalletClient | undefined;
@@ -32,8 +32,8 @@ export abstract class BaseBuilder {
   constructor(params: BaseBuilderParams) {
     // Check that config is provided
     if (!params.config) {
-      throw new CofhesdkError({
-        code: CofhesdkErrorCode.MissingConfig,
+      throw new CofheError({
+        code: CofheErrorCode.MissingConfig,
         message: 'Builder config is undefined',
         hint: 'Ensure client has been created with a config.',
         context: {
@@ -55,12 +55,12 @@ export abstract class BaseBuilder {
 
   /**
    * Asserts that this.chainId is populated
-   * @throws {CofhesdkError} If chainId is not set
+   * @throws {CofheError} If chainId is not set
    */
   protected assertChainId(): asserts this is this & { chainId: number } {
     if (this.chainId) return;
-    throw new CofhesdkError({
-      code: CofhesdkErrorCode.ChainIdUninitialized,
+    throw new CofheError({
+      code: CofheErrorCode.ChainIdUninitialized,
       message: 'Chain ID is not set',
       hint: 'Ensure client.connect() has been called and awaited, or use setChainId(...) to set the chainId explicitly.',
       context: {
@@ -71,12 +71,12 @@ export abstract class BaseBuilder {
 
   /**
    * Asserts that this.account is populated
-   * @throws {CofhesdkError} If account is not set
+   * @throws {CofheError} If account is not set
    */
   protected assertAccount(): asserts this is this & { account: string } {
     if (this.account) return;
-    throw new CofhesdkError({
-      code: CofhesdkErrorCode.AccountUninitialized,
+    throw new CofheError({
+      code: CofheErrorCode.AccountUninitialized,
       message: 'Account is not set',
       hint: 'Ensure client.connect() has been called and awaited, or use setAccount(...) to set the account explicitly.',
       context: {
@@ -87,12 +87,12 @@ export abstract class BaseBuilder {
 
   /**
    * Asserts that this.publicClient is populated
-   * @throws {CofhesdkError} If publicClient is not set
+   * @throws {CofheError} If publicClient is not set
    */
   protected assertPublicClient(): asserts this is this & { publicClient: PublicClient } {
     if (this.publicClient) return;
-    throw new CofhesdkError({
-      code: CofhesdkErrorCode.MissingPublicClient,
+    throw new CofheError({
+      code: CofheErrorCode.MissingPublicClient,
       message: 'Public client not found',
       hint: 'Ensure client.connect() has been called with a publicClient.',
       context: {
@@ -103,12 +103,12 @@ export abstract class BaseBuilder {
 
   /**
    * Asserts that this.walletClient is populated
-   * @throws {CofhesdkError} If walletClient is not set
+   * @throws {CofheError} If walletClient is not set
    */
   protected assertWalletClient(): asserts this is this & { walletClient: WalletClient } {
     if (this.walletClient) return;
-    throw new CofhesdkError({
-      code: CofhesdkErrorCode.MissingWalletClient,
+    throw new CofheError({
+      code: CofheErrorCode.MissingWalletClient,
       message: 'Wallet client not found',
       hint: 'Ensure client.connect() has been called with a walletClient.',
       context: {

package/core/client.test.ts

@@ -1,8 +1,8 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createCofhesdkClientBase } from './client.js';
-import { type CofhesdkClient, type CofhesdkClientConnectionState } from './clientTypes.js';
-import { createCofhesdkConfigBase, type CofhesdkEnvironment } from './config.js';
-import { CofhesdkError, CofhesdkErrorCode } from './error.js';
+import { createCofheClientBase } from './client.js';
+import { type CofheClient, type CofheClientConnectionState } from './clientTypes.js';
+import { createCofheConfigBase, type CofheEnvironment } from './config.js';
+import { CofheError, CofheErrorCode } from './error.js';
 import { type PublicClient, type WalletClient } from 'viem';
 import { EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
 import { Encryptable } from './types.js';
@@ -31,9 +31,9 @@ const createMockWalletClient = (addresses = ['0x12345678901234567890123456789012
     getAddresses: vi.fn().mockResolvedValue(addresses),
   }) as any;
 
-const createTestClient = (): CofhesdkClient => {
-  const config = createCofhesdkConfigBase({ supportedChains: [] });
-  return createCofhesdkClientBase({
+const createTestClient = (): CofheClient => {
+  const config = createCofheConfigBase({ supportedChains: [] });
+  return createCofheClientBase({
     config,
     zkBuilderAndCrsGenerator: {} as any,
     tfhePublicKeyDeserializer: {} as any,
@@ -42,8 +42,8 @@ const createTestClient = (): CofhesdkClient => {
   });
 };
 
-describe('createCofhesdkClientBase', () => {
-  let client: CofhesdkClient;
+describe('createCofheClientBase', () => {
+  let client: CofheClient;
 
   beforeEach(() => {
     client = createTestClient();
@@ -59,11 +59,15 @@ describe('createCofhesdkClientBase', () => {
       expect(snapshot.account).toBe(undefined);
       expect(snapshot.publicClient).toBe(undefined);
       expect(snapshot.walletClient).toBe(undefined);
+
+      const connection = client.connection;
+      expect(connection).toEqual(snapshot);
     });
 
     it('should expose convenience flags', () => {
       expect(client.connected).toBe(false);
       expect(client.connecting).toBe(false);
+      expect(client.connection.connected).toBe(false);
     });
 
     it('should expose config', () => {
@@ -74,10 +78,10 @@ describe('createCofhesdkClientBase', () => {
 
   describe('environment', () => {
     it('should create a client with the correct environment', async () => {
-      const environments: CofhesdkEnvironment[] = ['node', 'hardhat', 'web', 'react'];
+      const environments: CofheEnvironment[] = ['node', 'hardhat', 'web', 'react'];
       for (const environment of environments) {
-        const config = createCofhesdkConfigBase({ environment, supportedChains: [] });
-        const client = createCofhesdkClientBase({
+        const config = createCofheConfigBase({ environment, supportedChains: [] });
+        const client = createCofheClientBase({
           config,
           zkBuilderAndCrsGenerator: {} as any,
           tfhePublicKeyDeserializer: {} as any,
@@ -92,7 +96,7 @@ describe('createCofhesdkClientBase', () => {
 
   describe('reactive state', () => {
     it('should notify subscribers of state changes', async () => {
-      const states: CofhesdkClientConnectionState[] = [];
+      const states: CofheClientConnectionState[] = [];
       client.subscribe((snapshot) => states.push(snapshot));
 
       const publicClient = createMockPublicClient();
@@ -117,7 +121,7 @@ describe('createCofhesdkClientBase', () => {
     });
 
     it('should stop notifications after unsubscribe', async () => {
-      const states: CofhesdkClientConnectionState[] = [];
+      const states: CofheClientConnectionState[] = [];
       const unsubscribe = client.subscribe((snapshot) => states.push(snapshot));
 
       unsubscribe();
@@ -141,11 +145,11 @@ describe('createCofhesdkClientBase', () => {
       expect(client.connected).toBe(true);
       expect(client.connecting).toBe(false);
 
-      const snapshot = client.getSnapshot();
-      expect(snapshot.chainId).toBe(11155111);
-      expect(snapshot.account).toBe('0xabcd');
-      expect(snapshot.publicClient).toBe(publicClient);
-      expect(snapshot.walletClient).toBe(walletClient);
+      const connection = client.connection;
+      expect(connection.chainId).toBe(11155111);
+      expect(connection.account).toBe('0xabcd');
+      expect(connection.publicClient).toBe(publicClient);
+      expect(connection.walletClient).toBe(walletClient);
     });
 
     it('should set connecting state during connection', async () => {
@@ -176,6 +180,97 @@ describe('createCofhesdkClientBase', () => {
       await promise1;
     });
 
+    it('should ensure the latest connection attempt wins when connecting twice', async () => {
+      let resolveChainId1: (value: number) => void;
+      let resolveAddresses1: (value: string[]) => void;
+      let resolveChainId2: (value: number) => void;
+      let resolveAddresses2: (value: string[]) => void;
+
+      const chainIdPromise1 = new Promise<number>((resolve) => {
+        resolveChainId1 = resolve;
+      });
+      const addressesPromise1 = new Promise<string[]>((resolve) => {
+        resolveAddresses1 = resolve;
+      });
+
+      const chainIdPromise2 = new Promise<number>((resolve) => {
+        resolveChainId2 = resolve;
+      });
+      const addressesPromise2 = new Promise<string[]>((resolve) => {
+        resolveAddresses2 = resolve;
+      });
+
+      const publicClient1 = createMockPublicClient() as any;
+      publicClient1.getChainId = vi.fn().mockReturnValue(chainIdPromise1);
+      const walletClient1 = createMockWalletClient() as any;
+      walletClient1.getAddresses = vi.fn().mockReturnValue(addressesPromise1);
+
+      const publicClient2 = createMockPublicClient() as any;
+      publicClient2.getChainId = vi.fn().mockReturnValue(chainIdPromise2);
+      const walletClient2 = createMockWalletClient() as any;
+      walletClient2.getAddresses = vi.fn().mockReturnValue(addressesPromise2);
+
+      const promise1 = client.connect(publicClient1, walletClient1);
+      expect(client.connecting).toBe(true);
+
+      const promise2 = client.connect(publicClient2, walletClient2);
+
+      // Resolve the second connect first
+      resolveChainId2!(222);
+      resolveAddresses2!(['0x2222222222222222222222222222222222222222']);
+      await promise2;
+
+      expect(client.connected).toBe(true);
+      expect(client.connecting).toBe(false);
+      expect(client.connection.chainId).toBe(222);
+      expect(client.connection.account).toBe('0x2222222222222222222222222222222222222222');
+      expect(client.connection.publicClient).toBe(publicClient2);
+      expect(client.connection.walletClient).toBe(walletClient2);
+
+      // Now resolve the first connect; it must not overwrite the latest state.
+      resolveChainId1!(111);
+      resolveAddresses1!(['0x1111111111111111111111111111111111111111']);
+      await promise1;
+
+      expect(client.connection.chainId).toBe(222);
+      expect(client.connection.account).toBe('0x2222222222222222222222222222222222222222');
+      expect(client.connection.publicClient).toBe(publicClient2);
+      expect(client.connection.walletClient).toBe(walletClient2);
+    });
+
+    it('should allow disconnect while connecting and never end up connected afterwards', async () => {
+      let resolveChainId: (value: number) => void;
+      let resolveAddresses: (value: string[]) => void;
+
+      const chainIdPromise = new Promise<number>((resolve) => {
+        resolveChainId = resolve;
+      });
+      const addressesPromise = new Promise<string[]>((resolve) => {
+        resolveAddresses = resolve;
+      });
+
+      const publicClient = createMockPublicClient() as any;
+      publicClient.getChainId = vi.fn().mockReturnValue(chainIdPromise);
+
+      const walletClient = createMockWalletClient() as any;
+      walletClient.getAddresses = vi.fn().mockReturnValue(addressesPromise);
+
+      const connectPromise = client.connect(publicClient, walletClient);
+      expect(client.connecting).toBe(true);
+
+      client.disconnect();
+      expect(client.connected).toBe(false);
+      expect(client.connecting).toBe(false);
+
+      resolveChainId!(11155111);
+      resolveAddresses!(['0x1234567890123456789012345678901234567890']);
+
+      await connectPromise;
+
+      expect(client.connected).toBe(false);
+      expect(client.connecting).toBe(false);
+    });
+
     it('should handle publicClient.getChainId throwing an error', async () => {
       const publicClient = createMockPublicClient();
       const getChainIdError = new Error('Network error');
@@ -185,12 +280,12 @@ describe('createCofhesdkClientBase', () => {
       try {
         await client.connect(publicClient, walletClient);
       } catch (error) {
-        expect(error).toBeInstanceOf(CofhesdkError);
-        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.PublicWalletGetChainIdFailed);
-        expect((error as CofhesdkError).message).toBe(
+        expect(error).toBeInstanceOf(CofheError);
+        expect((error as CofheError).code).toBe(CofheErrorCode.PublicWalletGetChainIdFailed);
+        expect((error as CofheError).message).toBe(
           'getting chain ID from public client failed | Caused by: Network error'
         );
-        expect((error as CofhesdkError).cause).toBe(getChainIdError);
+        expect((error as CofheError).cause).toBe(getChainIdError);
       }
     });
 
@@ -204,9 +299,9 @@ describe('createCofhesdkClientBase', () => {
       try {
         await connectPromise;
       } catch (error) {
-        expect(error).toBeInstanceOf(CofhesdkError);
-        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.PublicWalletGetChainIdFailed);
-        expect((error as CofhesdkError).message).toBe('chain ID from public client is null');
+        expect(error).toBeInstanceOf(CofheError);
+        expect((error as CofheError).code).toBe(CofheErrorCode.PublicWalletGetChainIdFailed);
+        expect((error as CofheError).message).toBe('chain ID from public client is null');
       }
     });
 
@@ -221,12 +316,12 @@ describe('createCofhesdkClientBase', () => {
       try {
         await connectPromise;
       } catch (error) {
-        expect(error).toBeInstanceOf(CofhesdkError);
-        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.PublicWalletGetAddressesFailed);
-        expect((error as CofhesdkError).message).toBe(
+        expect(error).toBeInstanceOf(CofheError);
+        expect((error as CofheError).code).toBe(CofheErrorCode.PublicWalletGetAddressesFailed);
+        expect((error as CofheError).message).toBe(
           'getting address from wallet client failed | Caused by: Network error'
         );
-        expect((error as CofhesdkError).cause).toBe(getAddressesError);
+        expect((error as CofheError).cause).toBe(getAddressesError);
       }
     });
 
@@ -239,9 +334,9 @@ describe('createCofhesdkClientBase', () => {
       try {
         await connectPromise;
       } catch (error) {
-        expect(error).toBeInstanceOf(CofhesdkError);
-        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.PublicWalletGetAddressesFailed);
-        expect((error as CofhesdkError).message).toBe('address from wallet client is null');
+        expect(error).toBeInstanceOf(CofheError);
+        expect((error as CofheError).code).toBe(CofheErrorCode.PublicWalletGetAddressesFailed);
+        expect((error as CofheError).message).toBe('address from wallet client is null');
       }
     });
 
@@ -256,23 +351,42 @@ describe('createCofhesdkClientBase', () => {
       try {
         await connectPromise;
       } catch (error) {
-        expect(error).toBeInstanceOf(CofhesdkError);
-        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.PublicWalletGetChainIdFailed);
-        expect((error as CofhesdkError).message).toBe(
+        expect(error).toBeInstanceOf(CofheError);
+        expect((error as CofheError).code).toBe(CofheErrorCode.PublicWalletGetChainIdFailed);
+        expect((error as CofheError).message).toBe(
           'getting chain ID from public client failed | Caused by: Network error'
         );
-        expect((error as CofhesdkError).cause).toBe(getChainIdError);
+        expect((error as CofheError).cause).toBe(getChainIdError);
       }
     });
+
+    it('should disconnect and clear connection state', async () => {
+      const publicClient = createMockPublicClient(11155111);
+      const walletClient = createMockWalletClient(['0xabcd']);
+
+      await client.connect(publicClient, walletClient);
+      expect(client.connected).toBe(true);
+
+      client.disconnect();
+
+      expect(client.connected).toBe(false);
+      expect(client.connecting).toBe(false);
+
+      expect(client.connection.chainId).toBe(undefined);
+      expect(client.connection.account).toBe(undefined);
+      expect(client.connection.publicClient).toBe(undefined);
+      expect(client.connection.walletClient).toBe(undefined);
+      expect(client.connection.connectError).toBe(undefined);
+    });
   });
 
   describe('encryptInputs', () => {
     it('should throw if not connected', async () => {
       try {
-        await client.encryptInputs([Encryptable.uint8(1n), Encryptable.uint8(2n), Encryptable.uint8(3n)]).encrypt();
+        await client.encryptInputs([Encryptable.uint8(1n), Encryptable.uint8(2n), Encryptable.uint8(3n)]).execute();
       } catch (error) {
-        expect(error).toBeInstanceOf(CofhesdkError);
-        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.NotConnected);
+        expect(error).toBeInstanceOf(CofheError);
+        expect((error as CofheError).code).toBe(CofheErrorCode.NotConnected);
       }
     });
 
@@ -286,7 +400,7 @@ describe('createCofhesdkClientBase', () => {
 
       expect(builder).toBeDefined();
       expect(builder).toBeInstanceOf(EncryptInputsBuilder);
-      expect(builder).toHaveProperty('encrypt');
+      expect(builder).toHaveProperty('execute');
       expect(builder.getChainId()).toBe(123);
       expect(builder.getAccount()).toBe('0xtest');
     });