@cofhe/sdk 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @cofhe/sdk Changelog
 
+## 0.3.1
+
+### Patch Changes
+
+- 370f0c7: no-op
+
+## 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

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 () => {
@@ -218,20 +222,20 @@ describe('createCofhesdkClientBase', () => {
 
       expect(client.connected).toBe(true);
       expect(client.connecting).toBe(false);
-      expect(client.getSnapshot().chainId).toBe(222);
-      expect(client.getSnapshot().account).toBe('0x2222222222222222222222222222222222222222');
-      expect(client.getSnapshot().publicClient).toBe(publicClient2);
-      expect(client.getSnapshot().walletClient).toBe(walletClient2);
+      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.getSnapshot().chainId).toBe(222);
-      expect(client.getSnapshot().account).toBe('0x2222222222222222222222222222222222222222');
-      expect(client.getSnapshot().publicClient).toBe(publicClient2);
-      expect(client.getSnapshot().walletClient).toBe(walletClient2);
+      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 () => {
@@ -276,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);
       }
     });
 
@@ -295,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');
       }
     });
 
@@ -312,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);
       }
     });
 
@@ -330,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');
       }
     });
 
@@ -347,12 +351,12 @@ 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);
       }
     });
 
@@ -368,22 +372,21 @@ describe('createCofhesdkClientBase', () => {
       expect(client.connected).toBe(false);
       expect(client.connecting).toBe(false);
 
-      const snapshot = client.getSnapshot();
-      expect(snapshot.chainId).toBe(undefined);
-      expect(snapshot.account).toBe(undefined);
-      expect(snapshot.publicClient).toBe(undefined);
-      expect(snapshot.walletClient).toBe(undefined);
-      expect(snapshot.connectError).toBe(undefined);
+      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);
       }
     });
 
@@ -397,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');
     });

package/core/client.ts

@@ -2,22 +2,18 @@ import type { CreateSelfPermitOptions, CreateSharingPermitOptions, ImportSharedP
 
 import { createStore } from 'zustand/vanilla';
 import { type PublicClient, type WalletClient } from 'viem';
-import { CofhesdkError, CofhesdkErrorCode } from './error.js';
+import { CofheError, CofheErrorCode } from './error.js';
 import { EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
 import { createKeysStore } from './keyStore.js';
 import { permits } from './permits.js';
-import { DecryptHandlesBuilder } from './decrypt/decryptHandleBuilder.js';
+import { DecryptForViewBuilder } from './decrypt/decryptForViewBuilder.js';
+import { DecryptForTxBuilder, type DecryptForTxBuilderUnset } from './decrypt/decryptForTxBuilder.js';
 import { getPublicClientChainID, getWalletClientAccount } from './utils.js';
-import type {
-  CofhesdkClientConnectionState,
-  CofhesdkClientParams,
-  CofhesdkClient,
-  CofhesdkClientPermits,
-} from './clientTypes.js';
+import type { CofheClientConnectionState, CofheClientParams, CofheClient, CofheClientPermits } from './clientTypes.js';
 import type { EncryptableItem, FheTypes } from './types.js';
-import type { CofhesdkConfig } from './config.js';
+import type { CofheConfig } from './config.js';
 
-export const InitialConnectStore: CofhesdkClientConnectionState = {
+export const InitialConnectStore: CofheClientConnectionState = {
   connected: false,
   connecting: false,
   connectError: undefined,
@@ -28,26 +24,26 @@ export const InitialConnectStore: CofhesdkClientConnectionState = {
 };
 
 /**
- * Creates a CoFHE SDK client instance (base implementation)
- * @param {CofhesdkClientParams} opts - Initialization options including config and platform-specific serializers
- * @returns {CofhesdkClient} - The CoFHE SDK client instance
+ * Creates a CoFHE client instance (base implementation)
+ * @param {CofheClientParams} opts - Initialization options including config and platform-specific serializers
+ * @returns {CofheClient} - The CoFHE client instance
  */
-export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
-  opts: CofhesdkClientParams<TConfig>
-): CofhesdkClient<TConfig> {
+export function createCofheClientBase<TConfig extends CofheConfig>(
+  opts: CofheClientParams<TConfig>
+): CofheClient<TConfig> {
   // Create keysStorage instance using configured storage
   const keysStorage = createKeysStore(opts.config.fheKeyStorage);
 
   // Zustand store for reactive state management
 
-  const connectStore = createStore<CofhesdkClientConnectionState>(() => InitialConnectStore);
+  const connectStore = createStore<CofheClientConnectionState>(() => InitialConnectStore);
 
   // Minimal cancellation mechanism: incremented on each connect/disconnect.
   // If a connect finishes after a disconnect, it must not overwrite the disconnected state.
   let connectAttemptId = 0;
 
   // Helper to update state
-  const updateConnectState = (partial: Partial<CofhesdkClientConnectionState>) => {
+  const updateConnectState = (partial: Partial<CofheClientConnectionState>) => {
     connectStore.setState((state) => ({ ...state, ...partial }));
   };
 
@@ -57,8 +53,8 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     const notConnected =
       !state.connected || !state.account || !state.chainId || !state.publicClient || !state.walletClient;
     if (notConnected) {
-      throw new CofhesdkError({
-        code: CofhesdkErrorCode.NotConnected,
+      throw new CofheError({
+        code: CofheErrorCode.NotConnected,
         message: 'Client must be connected, account and chainId must be initialized',
         hint: 'Ensure client.connect() has been called and awaited.',
         context: {
@@ -150,18 +146,34 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     });
   }
 
-  function decryptHandle<U extends FheTypes>(ctHash: bigint, utype: U): DecryptHandlesBuilder<U> {
+  function decryptForView<U extends FheTypes>(ctHash: bigint, utype: U): DecryptForViewBuilder<U> {
     const state = connectStore.getState();
 
-    return new DecryptHandlesBuilder({
+    return new DecryptForViewBuilder({
       ctHash,
       utype,
-      chainId: state.chainId ?? undefined,
-      account: state.account ?? undefined,
+      chainId: state.chainId,
+      account: state.account,
 
       config: opts.config,
-      publicClient: state.publicClient ?? undefined,
-      walletClient: state.walletClient ?? undefined,
+      publicClient: state.publicClient,
+      walletClient: state.walletClient,
+
+      requireConnected: _requireConnected,
+    });
+  }
+
+  function decryptForTx(ctHash: bigint): DecryptForTxBuilderUnset {
+    const state = connectStore.getState();
+
+    return new DecryptForTxBuilder({
+      ctHash,
+      chainId: state.chainId,
+      account: state.account,
+
+      config: opts.config,
+      publicClient: state.publicClient,
+      walletClient: state.walletClient,
 
       requireConnected: _requireConnected,
     });
@@ -175,8 +187,8 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     const _account = account ?? state.account;
 
     if (_chainId == null || _account == null) {
-      throw new CofhesdkError({
-        code: CofhesdkErrorCode.NotConnected,
+      throw new CofheError({
+        code: CofheErrorCode.NotConnected,
         message: 'ChainId or account not available.',
         hint: 'Ensure client.connect() has been called, or provide chainId and account explicitly.',
         context: {
@@ -189,7 +201,7 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     return { chainId: _chainId, account: _account };
   };
 
-  const clientPermits: CofhesdkClientPermits = {
+  const clientPermits: CofheClientPermits = {
     // Pass through store access
     getSnapshot: permits.getSnapshot,
     subscribe: permits.subscribe,
@@ -286,6 +298,9 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     subscribe: connectStore.subscribe,
 
     // flags (read-only: reflect snapshot)
+    get connection() {
+      return connectStore.getState();
+    },
     get connected() {
       return connectStore.getState().connected;
     },
@@ -299,7 +314,12 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     connect,
     disconnect,
     encryptInputs,
-    decryptHandle,
+    decryptForView,
+    /**
+     * @deprecated Use `decryptForView` instead. Kept for backward compatibility.
+     */
+    decryptHandle: decryptForView,
+    decryptForTx,
     permits: clientPermits,
 
     // Add SDK-specific methods below that require connection

package/core/clientTypes.ts

@@ -1,7 +1,8 @@
 // TODO: Extract client types to its own file, keep this one as primitives
 import { type PublicClient, type WalletClient } from 'viem';
-import { type CofhesdkConfig, type CofhesdkEnvironment } from './config.js';
-import { type DecryptHandlesBuilder } from './decrypt/decryptHandleBuilder.js';
+import { type CofheConfig } from './config.js';
+import { type DecryptForViewBuilder } from './decrypt/decryptForViewBuilder.js';
+import { type DecryptForTxBuilderUnset } from './decrypt/decryptForTxBuilder.js';
 import { type EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
 import { type ZkBuilderAndCrsGenerator, type ZkProveWorkerFunction } from './encrypt/zkPackProveVerify.js';
 import { type FheKeyDeserializer } from './fetchKeys.js';
@@ -20,12 +21,13 @@ import type {
 
 // CLIENT
 
-export type CofhesdkClient<TConfig extends CofhesdkConfig = CofhesdkConfig> = {
+export type CofheClient<TConfig extends CofheConfig = CofheConfig> = {
   // --- state access ---
-  getSnapshot(): CofhesdkClientConnectionState;
+  getSnapshot(): CofheClientConnectionState;
   subscribe(listener: Listener): () => void;
 
   // --- convenience flags (read-only) ---
+  readonly connection: CofheClientConnectionState;
   readonly connected: boolean;
   readonly connecting: boolean;
 
@@ -43,11 +45,16 @@ export type CofhesdkClient<TConfig extends CofhesdkConfig = CofhesdkConfig> = {
    * Types docstring
    */
   encryptInputs<T extends EncryptableItem[]>(inputs: [...T]): EncryptInputsBuilder<[...T]>;
-  decryptHandle<U extends FheTypes>(ctHash: bigint, utype: U): DecryptHandlesBuilder<U>;
-  permits: CofhesdkClientPermits;
+  /**
+   * @deprecated Use `decryptForView` instead. Kept for backward compatibility.
+   */
+  decryptHandle<U extends FheTypes>(ctHash: bigint, utype: U): DecryptForViewBuilder<U>;
+  decryptForView<U extends FheTypes>(ctHash: bigint, utype: U): DecryptForViewBuilder<U>;
+  decryptForTx(ctHash: bigint): DecryptForTxBuilderUnset;
+  permits: CofheClientPermits;
 };
 
-export type CofhesdkClientConnectionState = {
+export type CofheClientConnectionState = {
   connected: boolean;
   connecting: boolean;
   connectError: unknown | undefined;
@@ -57,26 +64,23 @@ export type CofhesdkClientConnectionState = {
   walletClient: WalletClient | undefined;
 };
 
-type Listener = (snapshot: CofhesdkClientConnectionState) => void;
+type Listener = (snapshot: CofheClientConnectionState) => void;
 
-export type CofhesdkClientPermitsClients = {
+export type CofheClientPermitsClients = {
   publicClient: PublicClient;
   walletClient: WalletClient;
 };
 
-export type CofhesdkClientPermits = {
+export type CofheClientPermits = {
   getSnapshot: typeof permits.getSnapshot;
   subscribe: typeof permits.subscribe;
 
   // Creation methods (require connection, no params)
-  createSelf: (options: CreateSelfPermitOptions, clients?: CofhesdkClientPermitsClients) => Promise<SelfPermit>;
-  createSharing: (
-    options: CreateSharingPermitOptions,
-    clients?: CofhesdkClientPermitsClients
-  ) => Promise<SharingPermit>;
+  createSelf: (options: CreateSelfPermitOptions, clients?: CofheClientPermitsClients) => Promise<SelfPermit>;
+  createSharing: (options: CreateSharingPermitOptions, clients?: CofheClientPermitsClients) => Promise<SharingPermit>;
   importShared: (
     options: ImportSharedPermitOptions | string,
-    clients?: CofhesdkClientPermitsClients
+    clients?: CofheClientPermitsClients
   ) => Promise<RecipientPermit>;
 
   // Retrieval methods (chainId/account optional)
@@ -104,7 +108,7 @@ export type CofhesdkClientPermits = {
   deserialize: typeof PermitUtils.deserialize;
 };
 
-export type CofhesdkClientParams<TConfig extends CofhesdkConfig> = {
+export type CofheClientParams<TConfig extends CofheConfig> = {
   config: TConfig;
   zkBuilderAndCrsGenerator: ZkBuilderAndCrsGenerator;
   tfhePublicKeyDeserializer: FheKeyDeserializer;