[AR-92] Improve builder api

.changeset/warm-scissors-count.md

@@ -0,0 +1,8 @@
+---
+'@cofhe/react': minor
+'@cofhe/sdk': minor
+---
+
+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.

README.md

@@ -104,5 +104,5 @@ Type `CofheInUint8` -> `EncryptedUint8Input`
 
 # Changes
 
-- Fhe keys aren't fetched until `client.encryptInputs(...).encrypt()`, they aren't used anywhere else other than encrypting inputs, so their fetching is deferred until then.
-- Initializing the tfhe wasm is also deferred until `client.encryptInputs(...).encrypt()` is called
+- Fhe keys aren't fetched until `client.encryptInputs(...).execute()`, they aren't used anywhere else other than encrypting inputs, so their fetching is deferred until then.
+- Initializing the tfhe wasm is also deferred until `client.encryptInputs(...).execute()` is called

packages/hardhat-plugin-test/test/encrypt-inputs.test.ts

@@ -11,15 +11,15 @@ describe('Encrypt Inputs Test', () => {
 
     const client = await hre.cofhe.createClientWithBatteries(signer);
 
-    const encrypted = await client.encryptInputs([Encryptable.uint32(7n)]).encrypt();
+    const encrypted = await client.encryptInputs([Encryptable.uint32(7n)]).execute();
 
     // Add number to TestBed
     const testBed = await hre.cofhe.mocks.getTestBed();
     await testBed.setNumber(encrypted[0]);
     const ctHash = await testBed.numberHash();
 
     // Decrypt number from TestBed
-    const unsealed = await client.decryptHandle(ctHash, FheTypes.Uint32).decrypt();
+    const unsealed = await client.decryptHandle(ctHash, FheTypes.Uint32).execute();
 
     expect(unsealed).to.be.equal(7n);
   });

packages/hardhat-plugin-test/test/integration-base-sepolia.test.ts

@@ -97,7 +97,7 @@ describe('Base Sepolia Integration Tests', () => {
     const testValue = 100n;
 
     // Encrypt and store a value
-    const encrypted = await cofheClient.encryptInputs([Encryptable.uint32(testValue)]).encrypt();
+    const encrypted = await cofheClient.encryptInputs([Encryptable.uint32(testValue)]).execute();
 
     const tx = await testContract.connect(baseSepoliaSigner).setValue(encrypted[0]);
     const receipt = await tx.wait();
@@ -107,7 +107,7 @@ describe('Base Sepolia Integration Tests', () => {
     const ctHash = await testContract.getValueHash();
 
     // Decrypt the value using the ctHash from the encrypted input
-    const unsealedResult = await cofheClient.decryptHandle(ctHash, FheTypes.Uint32).decrypt();
+    const unsealedResult = await cofheClient.decryptHandle(ctHash, FheTypes.Uint32).execute();
 
     // Verify the decrypted value matches
     expect(unsealedResult).to.be.equal(testValue);

packages/hardhat-plugin-test/test/integration-hardhat.test.ts

@@ -36,13 +36,13 @@ describe('Hardhat Integration Tests', () => {
     const testValue = 100n;
 
     // Encrypt and store a value
-    const encrypted = await cofheClient.encryptInputs([Encryptable.uint32(testValue)]).encrypt();
+    const encrypted = await cofheClient.encryptInputs([Encryptable.uint32(testValue)]).execute();
 
     const tx = await testContract.connect(signer).setValue(encrypted[0]);
     await tx.wait();
 
     // Decrypt the value using the ctHash from the encrypted input
-    const unsealedResult = await cofheClient.decryptHandle(encrypted[0].ctHash, FheTypes.Uint32).decrypt();
+    const unsealedResult = await cofheClient.decryptHandle(encrypted[0].ctHash, FheTypes.Uint32).execute();
 
     // Verify the decrypted value matches
     expect(unsealedResult).to.be.equal(testValue);

packages/hardhat-plugin-test/test/integration-localcofhe.test.ts

@@ -86,7 +86,7 @@ describe('Local Cofhe Integration Tests', () => {
     const testValue = 101n;
 
     // Encrypt and store a value
-    const encrypted = await cofheClient.encryptInputs([Encryptable.uint32(testValue)]).encrypt();
+    const encrypted = await cofheClient.encryptInputs([Encryptable.uint32(testValue)]).execute();
 
     const tx = await testContract.connect(localcofheSigner).setValue(encrypted[0]);
     await tx.wait();
@@ -96,7 +96,7 @@ describe('Local Cofhe Integration Tests', () => {
     const ctHash = await testContract.getValueHash();
 
     // Decrypt the value using the ctHash from the encrypted input
-    const unsealedResult = await cofheClient.decryptHandle(ctHash, FheTypes.Uint32).decrypt();
+    const unsealedResult = await cofheClient.decryptHandle(ctHash, FheTypes.Uint32).execute();
 
     // Verify the decrypted value matches
     expect(unsealedResult).to.be.equal(testValue);

packages/hardhat-plugin-test/test/permit-unseal.test.ts

@@ -17,7 +17,7 @@ describe('Permit Unseal Test', () => {
     const ctHash = await testBed.numberHash();
 
     // Decrypt number from TestBed
-    const unsealed = await client.decryptHandle(ctHash, FheTypes.Uint32).decrypt();
+    const unsealed = await client.decryptHandle(ctHash, FheTypes.Uint32).execute();
 
     expect(unsealed).to.be.equal(7n);
   });

packages/react/src/hooks/useCofheDecrypt.ts

@@ -30,7 +30,7 @@ export function useCofheDecrypt<U extends FheTypes, TSeletedData = UnsealedItem<
     queryKey: ['decryptCiphertext', input?.ctHash.toString(), input?.utype],
     queryFn: async () => {
       assert(input, 'input is guaranteed to be defined by enabled condition');
-      return client.decryptHandle(input.ctHash, input.utype).decrypt();
+      return client.decryptHandle(input.ctHash, input.utype).execute();
     },
     meta: {
       persist: true,

packages/react/src/hooks/useCofheEncrypt.ts

@@ -145,15 +145,15 @@ export function useCofheEncrypt(options?: UseCofheEncryptOptions): UseMutationRe
       };
 
       // Always set callback so we can track steps consistently.
-      builder.setStepCallback(combinedOnStepChange);
+      builder.onStep(combinedOnStepChange);
 
       if (hasEncryptInputsOptions(variables)) {
         if (variables.account) builder.setAccount(variables.account);
         if (variables.chainId) builder.setChainId(variables.chainId);
         if (variables.securityZone) builder.setSecurityZone(variables.securityZone);
       }
 
-      return builder.encrypt();
+      return builder.execute();
     },
   });
 

packages/sdk/core/client.test.ts

@@ -383,7 +383,7 @@ describe('createCofheClientBase', () => {
   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(CofheError);
         expect((error as CofheError).code).toBe(CofheErrorCode.NotConnected);
@@ -400,7 +400,7 @@ describe('createCofheClientBase', () => {
 
       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');
     });

packages/sdk/core/decrypt/decryptHandleBuilder.ts

@@ -19,7 +19,7 @@ import { tnSealOutputV2 } from './tnSealOutputV2.js';
  *   .setAccount(account)
  *   .setPermitHash(permitHash)
  *   .setPermit(permit)
- *   .decrypt()
+ *   .execute()
  *
  * If chainId not set, uses client's chainId
  * If account not set, uses client's account
@@ -67,7 +67,7 @@ export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
    * ```typescript
    * const unsealed = await decryptHandle(ctHash, utype)
    *   .setChainId(11155111)
-   *   .decrypt();
+   *   .execute();
    * ```
    *
    * @returns The chainable DecryptHandlesBuilder instance.
@@ -90,7 +90,7 @@ export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
    * ```typescript
    * const unsealed = await decryptHandle(ctHash, utype)
    *   .setAccount('0x1234567890123456789012345678901234567890')
-   *   .decrypt();
+   *   .execute();
    * ```
    *
    * @returns The chainable DecryptHandlesBuilder instance.
@@ -114,7 +114,7 @@ export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
    * ```typescript
    * const unsealed = await decryptHandle(ctHash, utype)
    *   .setPermitHash('0x1234567890123456789012345678901234567890')
-   *   .decrypt();
+   *   .execute();
    * ```
    *
    * @returns The chainable DecryptHandlesBuilder instance.
@@ -137,7 +137,7 @@ export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
    * ```typescript
    * const unsealed = await decryptHandle(ctHash, utype)
    *   .setPermit(permit)
-   *   .decrypt();
+   *   .execute();
    * ```
    *
    * @returns The chainable DecryptHandlesBuilder instance.
@@ -246,12 +246,12 @@ export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
    * const unsealed = await decryptHandle(ctHash, utype)
    *   .setChainId(11155111)      // optional
    *   .setAccount('0x123...890') // optional
-   *   .decrypt();                // execute
+   *   .execute();                // execute
    * ```
    *
    * @returns The unsealed item.
    */
-  async decrypt(): Promise<UnsealedItem<U>> {
+  async execute(): Promise<UnsealedItem<U>> {
     // Ensure utype is valid
     this.validateUtypeOrThrow();