@imtbl/wallet 2.10.7-alpha.2

package/dist/types/zkEvm/zkEvmProvider.d.ts

@@ -0,0 +1,25 @@
+import { MultiRollupApiClients } from '@imtbl/generated-clients';
+import { Signer } from 'ethers';
+import { Provider, RequestArguments } from './types';
+import { AuthManager } from '@imtbl/auth';
+import TypedEventEmitter from '../utils/typedEventEmitter';
+import { WalletConfiguration } from '../config';
+import { PassportEventMap, User } from '../types';
+import GuardianClient from '../guardian';
+export type ZkEvmProviderInput = {
+    authManager: AuthManager;
+    config: WalletConfiguration;
+    multiRollupApiClients: MultiRollupApiClients;
+    passportEventEmitter: TypedEventEmitter<PassportEventMap>;
+    guardianClient: GuardianClient;
+    ethSigner: Signer;
+    user: User | null;
+};
+export declare class ZkEvmProvider implements Provider {
+    #private;
+    readonly isPassport: boolean;
+    constructor({ authManager, config, multiRollupApiClients, passportEventEmitter, guardianClient, ethSigner, user, }: ZkEvmProviderInput);
+    request(request: RequestArguments): Promise<any>;
+    on(event: string, listener: (...args: any[]) => void): void;
+    removeListener(event: string, listener: (...args: any[]) => void): void;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@imtbl/wallet",
+  "version": "2.10.7-alpha.2",
+  "description": "Wallet SDK for Immutable",
+  "author": "Immutable",
+  "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
+  "homepage": "https://github.com/immutable/ts-immutable-sdk#readme",
+  "license": "Apache-2.0",
+  "main": "dist/node/index.js",
+  "module": "dist/node/index.mjs",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": {
+        "browser": "./dist/browser/index.mjs",
+        "default": "./dist/node/index.mjs"
+      },
+      "require": "./dist/node/index.js"
+    }
+  },
+  "dependencies": {
+    "@0xsequence/abi": "^2.0.25",
+    "@0xsequence/core": "^2.0.25",
+    "@imtbl/auth": "2.10.7-alpha.2",
+    "@imtbl/config": "2.10.7-alpha.2",
+    "@imtbl/generated-clients": "2.10.7-alpha.2",
+    "@imtbl/metrics": "2.10.7-alpha.2",
+    "@magic-ext/oidc": "12.0.5",
+    "@magic-sdk/provider": "^29.0.5",
+    "@metamask/detect-provider": "^2.0.0",
+    "axios": "^1.6.5",
+    "ethers": "^6.13.4",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@imtbl/toolkit": "2.10.7-alpha.2",
+    "@types/node": "^18.14.2",
+    "@types/uuid": "^8.3.4",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": "immutable/ts-immutable-sdk.git",
+  "scripts": {
+    "build": "pnpm transpile && pnpm typegen",
+    "transpile": "tsup src/index.ts --config ../../tsup.config.js",
+    "typegen": "tsc --customConditions default --emitDeclarationOnly --outDir dist/types",
+    "pack:root": "pnpm pack --pack-destination $(dirname $(pnpm root -w))",
+    "lint": "eslint ./src --ext .ts,.jsx,.tsx --max-warnings=0",
+    "typecheck": "tsc --customConditions default --noEmit --jsx preserve"
+  }
+}

package/src/config.ts

@@ -0,0 +1,51 @@
+import { Environment } from '@imtbl/config';
+import { WalletModuleConfiguration } from './types';
+
+export class WalletConfiguration {
+  readonly environment: Environment;
+
+  readonly passportDomain: string;
+
+  readonly zkEvmRpcUrl: string;
+
+  readonly relayerUrl: string;
+
+  readonly indexerMrBasePath: string;
+
+  readonly jsonRpcReferrer?: string;
+
+  readonly forceScwDeployBeforeMessageSignature: boolean;
+
+  readonly crossSdkBridgeEnabled: boolean;
+
+  constructor(config: WalletModuleConfiguration) {
+    this.environment = config.baseConfig.environment;
+    this.jsonRpcReferrer = config.jsonRpcReferrer;
+    this.forceScwDeployBeforeMessageSignature = config.forceScwDeployBeforeMessageSignature || false;
+    this.crossSdkBridgeEnabled = config.crossSdkBridgeEnabled || false;
+
+    if (config.overrides) {
+      this.passportDomain = config.overrides.passportDomain;
+      this.zkEvmRpcUrl = config.overrides.zkEvmRpcUrl;
+      this.relayerUrl = config.overrides.relayerUrl;
+      this.indexerMrBasePath = config.overrides.indexerMrBasePath;
+    } else {
+      switch (config.baseConfig.environment) {
+        case Environment.PRODUCTION:
+          this.passportDomain = 'https://passport.immutable.com';
+          this.zkEvmRpcUrl = 'https://rpc.immutable.com';
+          this.relayerUrl = 'https://api.immutable.com/relayer-mr';
+          this.indexerMrBasePath = 'https://api.immutable.com';
+          break;
+        case Environment.SANDBOX:
+          this.passportDomain = 'https://passport.sandbox.immutable.com';
+          this.zkEvmRpcUrl = 'https://rpc.testnet.immutable.com';
+          this.relayerUrl = 'https://api.sandbox.immutable.com/relayer-mr';
+          this.indexerMrBasePath = 'https://api.sandbox.immutable.com';
+          break;
+        default:
+          throw new Error(`Unsupported environment: ${config.baseConfig.environment}`);
+      }
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,33 @@
+export enum WalletErrorType {
+  WALLET_CONNECTION_ERROR = 'WALLET_CONNECTION_ERROR',
+  TRANSACTION_REJECTED = 'TRANSACTION_REJECTED',
+  INVALID_CONFIGURATION = 'INVALID_CONFIGURATION',
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  GUARDIAN_ERROR = 'GUARDIAN_ERROR',
+  SERVICE_UNAVAILABLE_ERROR = 'SERVICE_UNAVAILABLE_ERROR',
+  NOT_LOGGED_IN_ERROR = 'NOT_LOGGED_IN_ERROR',
+}
+
+export class WalletError extends Error {
+  readonly type: WalletErrorType;
+
+  constructor(message: string, type: WalletErrorType) {
+    super(message);
+    this.name = 'WalletError';
+    this.type = type;
+  }
+}
+
+export async function withWalletError<T>(
+  fn: () => Promise<T>,
+  defaultErrorType: WalletErrorType,
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (err: any) {
+    if (err instanceof WalletError) {
+      throw err;
+    }
+    throw new WalletError(err?.message ?? 'Unknown error', defaultErrorType);
+  }
+}

package/src/guardian/index.ts

@@ -0,0 +1,358 @@
+import * as GeneratedClients from '@imtbl/generated-clients';
+import { BigNumberish, ZeroAddress } from 'ethers';
+import axios from 'axios';
+import { AuthManager, ConfirmationScreen } from '@imtbl/auth';
+import { retryWithDelay } from '../network/retry';
+import { JsonRpcError, ProviderErrorCode, RpcErrorCode } from '../zkEvm/JsonRpcError';
+import { MetaTransaction, TypedDataPayload } from '../zkEvm/types';
+import { WalletConfiguration } from '../config';
+import { getEip155ChainId } from '../zkEvm/walletHelpers';
+import { WalletError, WalletErrorType } from '../errors';
+
+export type GuardianClientParams = {
+  confirmationScreen: ConfirmationScreen;
+  config: WalletConfiguration;
+  authManager: AuthManager;
+  guardianApi: GeneratedClients.mr.GuardianApi;
+};
+
+export type GuardianEvaluateImxTransactionParams = {
+  payloadHash: string;
+};
+
+type GuardianEVMTxnEvaluationParams = {
+  chainId: string;
+  nonce: string;
+  metaTransactions: MetaTransaction[];
+  isBackgroundTransaction?: boolean;
+};
+
+type GuardianEIP712MessageEvaluationParams = {
+  chainID: string;
+  payload: TypedDataPayload;
+};
+
+type GuardianERC191MessageEvaluationParams = {
+  chainID: bigint;
+  payload: string;
+};
+
+const transactionRejectedCrossSdkBridgeError = 'Transaction requires confirmation but this functionality is not'
+  + ' supported in this environment. Please contact Immutable support if you need to enable this feature.';
+
+export const convertBigNumberishToString = (
+  value: BigNumberish,
+): string => BigInt(value).toString();
+
+const transformGuardianTransactions = (
+  txs: MetaTransaction[],
+): GeneratedClients.mr.MetaTransaction[] => {
+  try {
+    return txs.map((t) => ({
+      delegateCall: t.delegateCall === true,
+      revertOnError: t.revertOnError === true,
+      gasLimit: t.gasLimit ? convertBigNumberishToString(t.gasLimit) : '0',
+      target: t.to ?? ZeroAddress,
+      value: t.value ? convertBigNumberishToString(t.value) : '0',
+      data: t.data ? t.data.toString() : '0x',
+    }));
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new JsonRpcError(
+      RpcErrorCode.INVALID_PARAMS,
+      `Transaction failed to parsing: ${errorMessage}`,
+    );
+  }
+};
+
+export default class GuardianClient {
+  private readonly guardianApi: GeneratedClients.mr.GuardianApi;
+
+  private readonly confirmationScreen: ConfirmationScreen;
+
+  private readonly crossSdkBridgeEnabled: boolean;
+
+  private readonly authManager: AuthManager;
+
+  constructor({
+    confirmationScreen, config, authManager, guardianApi,
+  }: GuardianClientParams) {
+    this.confirmationScreen = confirmationScreen;
+    this.crossSdkBridgeEnabled = config.crossSdkBridgeEnabled;
+    this.guardianApi = guardianApi;
+    this.authManager = authManager;
+  }
+
+  /**
+   * Open confirmation screen and close it automatically if the
+   * underlying task fails.
+   */
+  public withConfirmationScreen(popupWindowSize?: {
+    width: number;
+    height: number;
+  }) {
+    return <T>(task: () => Promise<T>): Promise<T> => this.withConfirmationScreenTask(popupWindowSize)(task)();
+  }
+
+  public withConfirmationScreenTask(popupWindowSize?: {
+    width: number;
+    height: number;
+  }) {
+    return <T>(task: () => Promise<T>): (() => Promise<T>) => async () => {
+      this.confirmationScreen.loading(popupWindowSize);
+
+      try {
+        return await task();
+      } catch (err) {
+        if (err instanceof WalletError && err.type === WalletErrorType.SERVICE_UNAVAILABLE_ERROR) {
+          await this.confirmationScreen.showServiceUnavailable();
+          throw err;
+        }
+
+        this.confirmationScreen.closeWindow();
+        throw err;
+      }
+    };
+  }
+
+  public withDefaultConfirmationScreenTask<T>(task: () => Promise<T>): (() => Promise<T>) {
+    return this.withConfirmationScreenTask()(task);
+  }
+
+  public async evaluateImxTransaction({ payloadHash }: GuardianEvaluateImxTransactionParams): Promise<void> {
+    try {
+      const finallyFn = () => {
+        this.confirmationScreen.closeWindow();
+      };
+      const user = await this.authManager.getUserImx();
+
+      const headers = { Authorization: `Bearer ${user.accessToken}` };
+      const transactionRes = await retryWithDelay(
+        async () => this.guardianApi.getTransactionByID({
+          transactionID: payloadHash,
+          chainType: 'starkex',
+        }, { headers }),
+        { finallyFn },
+      );
+
+      if (!transactionRes.data.id) {
+        throw new Error("Transaction doesn't exists");
+      }
+
+      const evaluateImxRes = await this.guardianApi.evaluateTransaction({
+        id: payloadHash,
+        transactionEvaluationRequest: {
+          chainType: 'starkex',
+        },
+      }, { headers });
+
+      const { confirmationRequired } = evaluateImxRes.data;
+      if (confirmationRequired) {
+        if (this.crossSdkBridgeEnabled) {
+          throw new Error(transactionRejectedCrossSdkBridgeError);
+        }
+
+        const confirmationResult = await this.confirmationScreen.requestConfirmation(
+          payloadHash,
+          user.imx.ethAddress,
+          GeneratedClients.mr.TransactionApprovalRequestChainTypeEnum.Starkex,
+        );
+
+        if (!confirmationResult.confirmed) {
+          throw new Error('Transaction rejected by user');
+        }
+      } else {
+        this.confirmationScreen.closeWindow();
+      }
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response?.status === 403) {
+        throw new WalletError('Service unavailable', WalletErrorType.SERVICE_UNAVAILABLE_ERROR);
+      }
+      throw error;
+    }
+  }
+
+  private async evaluateEVMTransaction({
+    chainId,
+    nonce,
+    metaTransactions,
+  }: GuardianEVMTxnEvaluationParams): Promise<GeneratedClients.mr.TransactionEvaluationResponse> {
+    const user = await this.authManager.getUserZkEvm();
+    const headers = { Authorization: `Bearer ${user.accessToken}` };
+    const guardianTransactions = transformGuardianTransactions(metaTransactions);
+    try {
+      const response = await this.guardianApi.evaluateTransaction(
+        {
+          id: 'evm',
+          transactionEvaluationRequest: {
+            chainType: 'evm',
+            chainId,
+            transactionData: {
+              nonce,
+              userAddress: user.zkEvm.ethAddress,
+              metaTransactions: guardianTransactions,
+            },
+          },
+        },
+        { headers },
+      );
+
+      return response.data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response?.status === 403) {
+        throw new WalletError('Service unavailable', WalletErrorType.SERVICE_UNAVAILABLE_ERROR);
+      }
+
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new JsonRpcError(
+        RpcErrorCode.INTERNAL_ERROR,
+        `Transaction failed to validate with error: ${errorMessage}`,
+      );
+    }
+  }
+
+  public async validateEVMTransaction({
+    chainId,
+    nonce,
+    metaTransactions,
+    isBackgroundTransaction,
+  }: GuardianEVMTxnEvaluationParams): Promise<void> {
+    const transactionEvaluationResponse = await this.evaluateEVMTransaction({
+      chainId,
+      nonce,
+      metaTransactions,
+    });
+
+    const { confirmationRequired, transactionId } = transactionEvaluationResponse;
+    if (confirmationRequired && this.crossSdkBridgeEnabled) {
+      throw new JsonRpcError(
+        RpcErrorCode.TRANSACTION_REJECTED,
+        transactionRejectedCrossSdkBridgeError,
+      );
+    }
+
+    if (confirmationRequired && !!transactionId) {
+      const user = await this.authManager.getUserZkEvm();
+      const confirmationResult = await this.confirmationScreen.requestConfirmation(
+        transactionId,
+        user.zkEvm.ethAddress,
+        GeneratedClients.mr.TransactionApprovalRequestChainTypeEnum.Evm,
+        chainId,
+      );
+
+      if (!confirmationResult.confirmed) {
+        throw new JsonRpcError(
+          RpcErrorCode.TRANSACTION_REJECTED,
+          'Transaction rejected by user',
+        );
+      }
+      // This verification is meant to ensure that it originates from zkEvmProvider#callSessionActivity
+      // and since it's a background transaction should not close the confirmation screen window.
+    } else if (!isBackgroundTransaction) {
+      this.confirmationScreen.closeWindow();
+    }
+  }
+
+  private async handleEIP712MessageEvaluation(
+    { chainID, payload }: GuardianEIP712MessageEvaluationParams,
+  ): Promise<GeneratedClients.mr.MessageEvaluationResponse> {
+    try {
+      const user = await this.authManager.getUserZkEvm();
+      if (user === null) {
+        throw new JsonRpcError(
+          ProviderErrorCode.UNAUTHORIZED,
+          'User not logged in. Please log in first.',
+        );
+      }
+      const messageEvalResponse = await this.guardianApi.evaluateMessage(
+        { messageEvaluationRequest: { chainID, payload } },
+        { headers: { Authorization: `Bearer ${user.accessToken}` } },
+      );
+      return messageEvalResponse.data;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new JsonRpcError(
+        RpcErrorCode.INTERNAL_ERROR,
+        `Message failed to validate with error: ${errorMessage}`,
+      );
+    }
+  }
+
+  public async evaluateEIP712Message({ chainID, payload }: GuardianEIP712MessageEvaluationParams) {
+    const { messageId, confirmationRequired } = await this.handleEIP712MessageEvaluation({ chainID, payload });
+    if (confirmationRequired && this.crossSdkBridgeEnabled) {
+      throw new JsonRpcError(RpcErrorCode.TRANSACTION_REJECTED, transactionRejectedCrossSdkBridgeError);
+    }
+    if (confirmationRequired && !!messageId) {
+      const user = await this.authManager.getUserZkEvm();
+      const confirmationResult = await this.confirmationScreen.requestMessageConfirmation(
+        messageId,
+        user.zkEvm.ethAddress,
+        'eip712',
+      );
+
+      if (!confirmationResult.confirmed) {
+        throw new JsonRpcError(
+          RpcErrorCode.TRANSACTION_REJECTED,
+          'Signature rejected by user',
+        );
+      }
+    } else {
+      this.confirmationScreen.closeWindow();
+    }
+  }
+
+  private async handleERC191MessageEvaluation(
+    { chainID, payload }: GuardianERC191MessageEvaluationParams,
+  ): Promise<GeneratedClients.mr.MessageEvaluationResponse> {
+    try {
+      const user = await this.authManager.getUserZkEvm();
+      if (user === null) {
+        throw new JsonRpcError(
+          ProviderErrorCode.UNAUTHORIZED,
+          'User not logged in. Please log in first.',
+        );
+      }
+      const messageEvalResponse = await this.guardianApi.evaluateErc191Message(
+        {
+          eRC191MessageEvaluationRequest: {
+            chainID: getEip155ChainId(Number(chainID)),
+            payload,
+          },
+        },
+        { headers: { Authorization: `Bearer ${user.accessToken}` } },
+      );
+      return messageEvalResponse.data;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new JsonRpcError(
+        RpcErrorCode.INTERNAL_ERROR,
+        `Message failed to validate with error: ${errorMessage}`,
+      );
+    }
+  }
+
+  public async evaluateERC191Message({ chainID, payload }: GuardianERC191MessageEvaluationParams) {
+    const { messageId, confirmationRequired } = await this.handleERC191MessageEvaluation({ chainID, payload });
+    if (confirmationRequired && this.crossSdkBridgeEnabled) {
+      throw new JsonRpcError(RpcErrorCode.TRANSACTION_REJECTED, transactionRejectedCrossSdkBridgeError);
+    }
+    if (confirmationRequired && !!messageId) {
+      const user = await this.authManager.getUserZkEvm();
+      const confirmationResult = await this.confirmationScreen.requestMessageConfirmation(
+        messageId,
+        user.zkEvm.ethAddress,
+        'erc191',
+      );
+
+      if (!confirmationResult.confirmed) {
+        throw new JsonRpcError(
+          RpcErrorCode.TRANSACTION_REJECTED,
+          'Signature rejected by user',
+        );
+      }
+    } else {
+      this.confirmationScreen.closeWindow();
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Export main wallet provider
+export { ZkEvmProvider } from './zkEvm/zkEvmProvider';
+
+// Export configuration
+export { WalletConfiguration } from './config';
+
+// Export types
+export * from './types';
+
+// Export errors
+export { WalletError, WalletErrorType } from './errors';
+export { JsonRpcError, ProviderErrorCode, RpcErrorCode } from './zkEvm/JsonRpcError';
+
+// Export zkEvm utilities
+export { RelayerClient } from './zkEvm/relayerClient';
+export * as walletHelpers from './zkEvm/walletHelpers';
+
+// Export guardian and magic
+export { default as GuardianClient } from './guardian';
+export { default as MagicTEESigner } from './magic/magicTEESigner';
+
+// Export utilities
+export { default as TypedEventEmitter } from './utils/typedEventEmitter';
+export { retryWithDelay } from './network/retry';
+
+// Export EIP-6963 provider announcement
+export { announceProvider, passportProviderInfo } from './provider/eip6963';

package/src/magic/index.ts

@@ -0,0 +1 @@
+export { default as MagicTEESigner } from './magicTEESigner';