Stricter error handling (#250)

Author: kroist

ts/shielder-sdk-tests/web/fixtures/callbacks.ts

@@ -22,6 +22,18 @@ export const setupCallbacks = (): CallbacksFixture => {
         txHistory.set(token, []);
       }
       txHistory.get(token)!.push(tx);
+    },
+    onAccountNotOnChain: (error, stage, operation) => {
+      console.error(
+        `Account not on chain during ${stage} for operation ${operation}:`,
+        error
+      );
+    },
+    onSdkOutdated: (error, stage, operation) => {
+      console.warn(
+        `SDK outdated during ${stage} for operation ${operation}:`,
+        error
+      );
     }
   };
 

ts/shielder-sdk/__tests/client/actions.test.ts

@@ -176,7 +176,7 @@ describe("ShielderActions", () => {
 
     await expect(method()).rejects.toThrow(mockError);
 
-    expect(mockCallbacks.onError).toHaveBeenCalledWith(
+    expect(mockCallbacks.onSdkOutdated).toHaveBeenCalledWith(
       mockError,
       "generation",
       operation
@@ -258,7 +258,9 @@ describe("ShielderActions", () => {
     mockCallbacks = {
       onCalldataGenerated: vitest.fn(),
       onCalldataSent: vitest.fn(),
-      onError: vitest.fn()
+      onError: vitest.fn(),
+      onAccountNotOnChain: vitest.fn(),
+      onSdkOutdated: vitest.fn()
     };
 
     // Setup mock account state

ts/shielder-sdk/__tests/client/client.test.ts

@@ -5,7 +5,10 @@ import { MockedCryptoClient } from "../helpers";
 import { ShielderClient } from "../../src/client/client";
 import { createShielderClient } from "../../src/client/factories";
 import { Contract } from "../../src/chain/contract";
-import { quotedFeesFromExpectedTokenFee, Relayer } from "../../src/chain/relayer";
+import {
+  quotedFeesFromExpectedTokenFee,
+  Relayer
+} from "../../src/chain/relayer";
 import { InjectedStorageInterface } from "../../src/storage/storageSchema";
 import {
   AccountStateMerkleIndexed,
@@ -89,7 +92,9 @@ describe("ShielderClient", () => {
     callbacks = {
       onCalldataGenerated: vitest.fn(),
       onCalldataSent: vitest.fn(),
-      onError: vitest.fn()
+      onError: vitest.fn(),
+      onSdkOutdated: vitest.fn(),
+      onAccountNotOnChain: vitest.fn()
     };
 
     // Create client instance with mocked components
@@ -141,7 +146,11 @@ describe("ShielderClient", () => {
         contractAddress: mockContractAddress,
         relayerUrl: mockRelayerUrl,
         storage: mockStorageInterface,
-        cryptoClient: mockCryptoClient
+        cryptoClient: mockCryptoClient,
+        callbacks: {
+          onSdkOutdated: vitest.fn(),
+          onAccountNotOnChain: vitest.fn()
+        }
       });
     });
 
@@ -157,15 +166,20 @@ describe("ShielderClient", () => {
     it("should create ShielderClient with default callbacks", () => {
       expect(client).toBeInstanceOf(ShielderClient);
       // Verify that the client was created with empty callbacks object
-      expect(client["callbacks"]).toEqual({});
+      expect(client["callbacks"]).toEqual({
+        onSdkOutdated: expect.any(Function),
+        onAccountNotOnChain: expect.any(Function)
+      });
     });
 
     it("should create ShielderClient with provided callbacks", () => {
       const mockCallbacks = {
         onCalldataGenerated: vitest.fn(),
         onCalldataSent: vitest.fn(),
         onNewTransaction: vitest.fn(),
-        onError: vitest.fn()
+        onError: vitest.fn(),
+        onAccountNotOnChain: vitest.fn(),
+        onSdkOutdated: vitest.fn()
       };
 
       client = createShielderClient({
@@ -209,7 +223,7 @@ describe("ShielderClient", () => {
       mockStateSynchronizer.syncAllAccounts.mockRejectedValue(mockError);
 
       await expect(client.syncShielder()).rejects.toThrow(mockError);
-      expect(callbacks.onError).toHaveBeenCalledWith(
+      expect(callbacks.onSdkOutdated).toHaveBeenCalledWith(
         mockError,
         "syncing",
         "sync"

ts/shielder-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardinal-cryptography/shielder-sdk",
-  "version": "0.2.0-beta.9",
+  "version": "0.2.0-beta.10",
   "description": "A web package for interacting with Shielder, a part of zkOS privacy engine.",
   "license": "Apache-2.0",
   "keywords": [

ts/shielder-sdk/src/client/actions.ts

@@ -18,6 +18,7 @@ import { WithdrawAction } from "@/actions/withdraw";
 import { contractVersion } from "@/constants";
 import { Calldata } from "@/actions/types";
 import { AccountStateMerkleIndexed } from "@/state/types";
+import { handleShielderError } from "@/utils/errorHandler";
 
 export class ShielderActions {
   constructor(
@@ -224,7 +225,7 @@ export class ShielderActions {
     try {
       calldata = await generateCalldata();
     } catch (error) {
-      this.callbacks.onError?.(error, "generation", operation);
+      handleShielderError(error, this.callbacks, "generation", operation);
       throw error;
     }
     this.callbacks.onCalldataGenerated?.(calldata, operation);
@@ -234,7 +235,7 @@ export class ShielderActions {
       this.callbacks.onCalldataSent?.(txHash, operation);
       return txHash;
     } catch (error) {
-      this.callbacks.onError?.(error, "sending", operation);
+      handleShielderError(error, this.callbacks, "sending", operation);
       throw error;
     }
   }

ts/shielder-sdk/src/client/client.ts

@@ -8,6 +8,7 @@ import { AccountRegistry } from "@/state/accountRegistry";
 import { ShielderActions } from "./actions";
 import { ShielderComponents } from "./factories";
 import { QuotedFees } from "@/chain/relayer";
+import { handleShielderError } from "@/utils/errorHandler";
 
 export class ShielderClient {
   private accountRegistry: AccountRegistry;
@@ -22,10 +23,7 @@ export class ShielderClient {
    * @param {ShielderComponents} components - components for the shielder client
    * @param {ShielderCallbacks} callbacks - callbacks for the shielder actions
    */
-  constructor(
-    components: ShielderComponents,
-    callbacks: ShielderCallbacks = {}
-  ) {
+  constructor(components: ShielderComponents, callbacks: ShielderCallbacks) {
     this.accountRegistry = components.accountRegistry;
     this.stateSynchronizer = components.stateSynchronizer;
     this.historyFetcher = components.historyFetcher;
@@ -47,7 +45,7 @@ export class ShielderClient {
     try {
       return await this.stateSynchronizer.syncAllAccounts();
     } catch (error) {
-      this.callbacks.onError?.(error, "syncing", "sync");
+      handleShielderError(error, this.callbacks, "syncing", "sync");
       throw error;
     }
   }
@@ -87,7 +85,7 @@ export class ShielderClient {
         yield transaction;
       }
     } catch (error) {
-      this.callbacks.onError?.(error, "syncing", "sync");
+      handleShielderError(error, this.callbacks, "syncing", "sync");
       throw error;
     }
   }

ts/shielder-sdk/src/client/factories.ts

@@ -32,7 +32,7 @@ type BaseShielderConfig = {
   storage: InjectedStorageInterface;
   cryptoClient: CryptoClient;
   publicClient: PublicClient;
-  callbacks?: ShielderCallbacks;
+  callbacks: ShielderCallbacks;
 };
 
 // Public config for creating a client
@@ -64,7 +64,7 @@ export const createShielderClient = (
     relayer
   });
 
-  return new ShielderClient(components, config.callbacks || {});
+  return new ShielderClient(components, config.callbacks);
 };
 
 // Internal config for component creation
@@ -124,7 +124,7 @@ function createShielderComponents(
     actionComponents.depositAction,
     actionComponents.withdrawAction,
     config.publicClient,
-    config.callbacks || {}
+    config.callbacks
   );
 
   return {

ts/shielder-sdk/src/client/types.ts

@@ -29,6 +29,24 @@ export interface ShielderCallbacks {
    * @param tx - new transaction
    */
   onNewTransaction?: (tx: ShielderTransaction) => unknown;
+  /**
+   * Fired when the current shielder state is broken. Usually this means that the chain
+   * has been reorganized and the shielder state is no longer valid.
+   * The client should be re-initialized to recover from this state.
+   */
+  onAccountNotOnChain: (
+    error: unknown,
+    stage: "generation" | "sending" | "syncing",
+    operation: ShielderOperation
+  ) => unknown;
+  /**
+   * Fired when the SDK version is outdated and cannot be used for the operation.
+   */
+  onSdkOutdated: (
+    error: unknown,
+    stage: "generation" | "sending" | "syncing",
+    operation: ShielderOperation
+  ) => unknown;
   /**
    * Fired when an error occurs during the generation or sending of the calldata, or during syncing.
    */

ts/shielder-sdk/src/utils/errorHandler.ts

@@ -0,0 +1,26 @@
+import { ShielderCallbacks, ShielderOperation } from "@/client/types";
+import { OutdatedSdkError, AccountNotOnChainError } from "@/errors";
+
+/**
+ * Handles errors in a consistent way across the Shielder SDK.
+ * Checks for specific error types and calls appropriate callbacks.
+ *
+ * @param error - The error that occurred
+ * @param callbacks - The callbacks object containing error handlers
+ * @param stage - The stage where the error occurred
+ * @param operation - The operation being performed when the error occurred
+ */
+export function handleShielderError(
+  error: unknown,
+  callbacks: ShielderCallbacks,
+  stage: "generation" | "sending" | "syncing",
+  operation: ShielderOperation
+) {
+  if (error instanceof OutdatedSdkError) {
+    callbacks.onSdkOutdated(error, stage, operation);
+  } else if (error instanceof AccountNotOnChainError) {
+    callbacks.onAccountNotOnChain(error, stage, operation);
+  } else {
+    callbacks.onError?.(error, stage, operation);
+  }
+}