@imtbl/wallet 2.10.7-alpha.2

package/src/magic/magicTEESigner.ts

@@ -0,0 +1,214 @@
+import { AbstractSigner, Signer } from 'ethers';
+import { MagicTeeApiClients } from '@imtbl/generated-clients';
+import { isAxiosError } from 'axios';
+import { Flow, trackDuration } from '@imtbl/metrics';
+import { WalletError, WalletErrorType } from '../errors';
+import { AuthManager } from '@imtbl/auth';
+import { withMetricsAsync } from '../utils/metrics';
+import { isUserImx, isUserZkEvm, User } from '../types';
+
+const CHAIN_IDENTIFIER = 'ETH';
+
+interface UserWallet {
+  userIdentifier: string;
+  walletAddress: string;
+}
+
+export default class MagicTEESigner extends AbstractSigner {
+  private readonly authManager: AuthManager;
+
+  private readonly magicTeeApiClient: MagicTeeApiClients;
+
+  private userWallet: UserWallet | null = null;
+
+  private createWalletPromise: Promise<UserWallet> | null = null;
+
+  constructor(authManager: AuthManager, magicTeeApiClient: MagicTeeApiClients) {
+    super();
+    this.authManager = authManager;
+    this.magicTeeApiClient = magicTeeApiClient;
+  }
+
+  private async getUserWallet(): Promise<UserWallet> {
+    let { userWallet } = this;
+    if (!userWallet) {
+      userWallet = await this.createWallet();
+    }
+
+    // Check if the user has changed since the last createWallet request was made. If so, initialise the new user's wallet.
+    const user = await this.getUserOrThrow();
+    if (user.profile.sub !== userWallet.userIdentifier) {
+      userWallet = await this.createWallet(user);
+    }
+
+    if (isUserImx(user) && user.imx.userAdminAddress.toLowerCase() !== userWallet.walletAddress.toLowerCase()) {
+      throw new WalletError(
+        'Wallet address mismatch.'
+          + `Rollup: IMX, TEE address: ${userWallet.walletAddress}, profile address: ${user.imx.userAdminAddress}`,
+        WalletErrorType.WALLET_CONNECTION_ERROR,
+      );
+    }
+
+    if (isUserZkEvm(user) && user.zkEvm.userAdminAddress.toLowerCase() !== userWallet.walletAddress.toLowerCase()) {
+      throw new WalletError(
+        'Wallet address mismatch.'
+          + `Rollup: zkEVM, TEE address: ${userWallet.walletAddress}, profile address: ${user.zkEvm.userAdminAddress}`,
+        WalletErrorType.WALLET_CONNECTION_ERROR,
+      );
+    }
+
+    return userWallet;
+  }
+
+  /**
+   * This method calls the createWallet endpoint. The user's wallet must be created before it can be used to sign messages.
+   * The createWallet endpoint is idempotent, so it can be called multiple times without causing an error.
+   * If a createWallet request is already in flight, return the existing promise.
+   */
+  private async createWallet(user?: User): Promise<UserWallet> {
+    if (this.createWalletPromise) return this.createWalletPromise;
+
+    // eslint-disable-next-line no-async-promise-executor
+    this.createWalletPromise = new Promise(async (resolve, reject) => {
+      try {
+        this.userWallet = null;
+
+        const authenticatedUser = user || await this.getUserOrThrow();
+        const headers = MagicTEESigner.getHeaders(authenticatedUser);
+
+        await withMetricsAsync(async (flow: Flow) => {
+          try {
+            const startTime = performance.now();
+            // The createWallet endpoint is idempotent, so it can be called multiple times without causing an error.
+            const response = await this.magicTeeApiClient.walletApi.createWalletV1WalletPost(
+              {
+                xMagicChain: CHAIN_IDENTIFIER,
+              },
+              { headers },
+            );
+
+            trackDuration(
+              'passport',
+              flow.details.flowName,
+              Math.round(performance.now() - startTime),
+            );
+
+            this.userWallet = {
+              userIdentifier: authenticatedUser.profile.sub,
+              walletAddress: response.data.public_address,
+            };
+
+            return resolve(this.userWallet);
+          } catch (error) {
+            let errorMessage: string = 'MagicTEE: Failed to initialise EOA';
+
+            if (isAxiosError(error)) {
+              if (error.response) {
+                errorMessage += ` with status ${error.response.status}: ${JSON.stringify(error.response.data)}`;
+              } else {
+                errorMessage += `: ${error.message}`;
+              }
+            } else {
+              errorMessage += `: ${(error as Error).message}`;
+            }
+
+            return reject(new Error(errorMessage));
+          }
+        }, 'magicCreateWallet');
+      } catch (error) {
+        reject(error);
+      } finally {
+        this.createWalletPromise = null;
+      }
+    });
+
+    return this.createWalletPromise;
+  }
+
+  private async getUserOrThrow(): Promise<User> {
+    const user = await this.authManager.getUser();
+    if (!user) {
+      throw new WalletError(
+        'User has been logged out',
+        WalletErrorType.NOT_LOGGED_IN_ERROR,
+      );
+    }
+    return user;
+  }
+
+  private static getHeaders(user: User): Record<string, string> {
+    if (!user) {
+      throw new WalletError(
+        'User has been logged out',
+        WalletErrorType.NOT_LOGGED_IN_ERROR,
+      );
+    }
+    return {
+      Authorization: `Bearer ${user.idToken}`,
+    };
+  }
+
+  public async getAddress(): Promise<string> {
+    const userWallet = await this.getUserWallet();
+    return userWallet.walletAddress;
+  }
+
+  public async signMessage(message: string | Uint8Array): Promise<string> {
+    // Call getUserWallet to ensure that the createWallet endpoint has been called at least once,
+    // as this is a prerequisite for signing messages.
+    await this.getUserWallet();
+
+    const messageToSign = message instanceof Uint8Array ? `0x${Buffer.from(message).toString('hex')}` : message;
+    const user = await this.getUserOrThrow();
+    const headers = await MagicTEESigner.getHeaders(user);
+
+    return withMetricsAsync(async (flow: Flow) => {
+      try {
+        const startTime = performance.now();
+        const response = await this.magicTeeApiClient.signOperationsApi.signMessageV1WalletSignMessagePost({
+          signMessageRequest: {
+            message_base64: Buffer.from(messageToSign, 'utf-8').toString('base64'),
+          },
+          xMagicChain: CHAIN_IDENTIFIER,
+        }, { headers });
+
+        trackDuration(
+          'passport',
+          flow.details.flowName,
+          Math.round(performance.now() - startTime),
+        );
+
+        return response.data.signature;
+      } catch (error) {
+        let errorMessage: string = 'MagicTEE: Failed to sign message using EOA';
+
+        if (isAxiosError(error)) {
+          if (error.response) {
+            errorMessage += ` with status ${error.response.status}: ${JSON.stringify(error.response.data)}`;
+          } else {
+            errorMessage += `: ${error.message}`;
+          }
+        } else {
+          errorMessage += `: ${(error as Error).message}`;
+        }
+
+        throw new Error(errorMessage);
+      }
+    }, 'magicSignMessage');
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  connect(): Signer {
+    throw new Error('Method not implemented.');
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  signTransaction(): Promise<string> {
+    throw new Error('Method not implemented.');
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  signTypedData(): Promise<string> {
+    throw new Error('Method not implemented.');
+  }
+}

package/src/network/chains.ts

@@ -0,0 +1,33 @@
+/**
+ * Enum representing different chain IDs.
+ * @enum {number}
+ * @property {number} IMTBL_ZKEVM_MAINNET - The chain ID for IMTBL ZKEVM Mainnet.
+ * @property {number} IMTBL_ZKEVM_TESTNET - The chain ID for IMTBL ZKEVM Testnet.
+ * @property {number} IMTBL_ZKEVM_DEVNET - The chain ID for IMTBL ZKEVM Devnet.
+ * @property {number} ETHEREUM - The chain ID for Ethereum.
+ * @property {number} SEPOLIA - The chain ID for Sepolia.
+ */
+export enum ChainId {
+  IMTBL_ZKEVM_MAINNET = 13371,
+  IMTBL_ZKEVM_TESTNET = 13473,
+  IMTBL_ZKEVM_DEVNET = 15003,
+  ETHEREUM = 1,
+  SEPOLIA = 11155111,
+}
+
+/**
+ * Enum representing different chain names.
+ * @enum {number}
+ * @property {number} IMTBL_ZKEVM_MAINNET - The chain name for IMTBL ZKEVM Mainnet.
+ * @property {number} IMTBL_ZKEVM_TESTNET - The chain name for IMTBL ZKEVM Testnet.
+ * @property {number} IMTBL_ZKEVM_DEVNET - The chain name for IMTBL ZKEVM Devnet.
+ * @property {number} ETHEREUM - The chain name for Ethereum.
+ * @property {number} SEPOLIA - The chain name for Sepolia.
+ */
+export enum ChainName {
+  ETHEREUM = 'Ethereum',
+  SEPOLIA = 'Sepolia',
+  IMTBL_ZKEVM_TESTNET = 'Immutable zkEVM Test',
+  IMTBL_ZKEVM_DEVNET = 'Immutable zkEVM Dev',
+  IMTBL_ZKEVM_MAINNET = 'Immutable zkEVM',
+}

package/src/network/constants.ts

@@ -0,0 +1,28 @@
+import { ChainId, ChainName } from './chains';
+
+export type ChainMap = Map<ChainId, ChainName>;
+export const CHAIN_NAME_MAP: ChainMap = new Map<
+ChainId,
+ChainName
+>([
+  [
+    ChainId.ETHEREUM,
+    ChainName.ETHEREUM,
+  ],
+  [
+    ChainId.SEPOLIA,
+    ChainName.SEPOLIA,
+  ],
+  [
+    ChainId.IMTBL_ZKEVM_MAINNET,
+    ChainName.IMTBL_ZKEVM_MAINNET,
+  ],
+  [
+    ChainId.IMTBL_ZKEVM_TESTNET,
+    ChainName.IMTBL_ZKEVM_TESTNET,
+  ],
+  [
+    ChainId.IMTBL_ZKEVM_DEVNET,
+    ChainName.IMTBL_ZKEVM_DEVNET,
+  ],
+]);

package/src/network/retry.ts

@@ -0,0 +1,37 @@
+const POLL_INTERVAL = 1 * 1000; // every 1 second
+export const MAX_RETRIES = 3;
+
+export type RetryOption = {
+  retries?: number;
+  interval?: number;
+  finalErr?: Error;
+  finallyFn?: () => void;
+};
+const wait = (ms: number) => new Promise<void>((resolve) => {
+  setTimeout(() => resolve(), ms);
+});
+
+export const retryWithDelay = async <T>(
+  fn: () => Promise<T>,
+  options?: RetryOption,
+): Promise<T> => {
+  const {
+    retries = MAX_RETRIES,
+    interval = POLL_INTERVAL,
+    finalErr = Error('Retry failed'),
+    finallyFn = () => {},
+  } = options || {};
+  try {
+    return await fn();
+  } catch (err) {
+    if (retries <= 0) {
+      return Promise.reject(finalErr);
+    }
+    await wait(interval);
+    return retryWithDelay(fn, { retries: retries - 1, finalErr, finallyFn });
+  } finally {
+    if (retries <= 0) {
+      finallyFn();
+    }
+  }
+};

package/src/provider/eip6963.ts

@@ -0,0 +1,25 @@
+import { v4 as uuidv4 } from 'uuid';
+import { EIP6963ProviderDetail, EIP6963ProviderInfo } from '../types';
+
+export const passportProviderInfo = {
+  // eslint-disable-next-line max-len
+  icon: 'data:image/svg+xml,<svg viewBox="0 0 48 48" class="SvgIcon undefined Logo Logo--PassportSymbolOutlined css-1dn9atd" xmlns="http://www.w3.org/2000/svg"><g data-testid="undefined__g"><circle cx="24" cy="24" r="22.5" fill="url(%23paint0_radial_6324_83922)"></circle><circle cx="24" cy="24" r="22.5" fill="url(%23paint1_radial_6324_83922)"></circle><path d="M24 0C10.7452 0 0 10.7452 0 24C0 37.2548 10.7452 48 24 48C37.2548 48 48 37.2548 48 24C48 10.7452 37.2548 0 24 0ZM23.0718 9.16608C23.7383 8.83951 24.4406 8.86188 25.087 9.2287C27.3282 10.5059 29.5627 11.7942 31.786 13.096C32.5018 13.5165 32.8686 14.1897 32.8708 15.0173C32.8843 17.9184 32.8798 20.8171 32.8708 23.7182C32.8708 23.8255 32.8015 23.9821 32.7143 24.0335C31.8531 24.548 30.9808 25.0423 30.0347 25.5881V25.1318C30.0347 22.148 30.0257 19.1664 30.0414 16.1827C30.0436 15.6101 29.8468 15.241 29.339 14.9525C26.7377 13.474 24.1499 11.9687 21.5575 10.4723C21.4457 10.4075 21.3361 10.3381 21.1661 10.2352C21.8326 9.85722 22.4321 9.47698 23.0673 9.16608H23.0718ZM22.5953 38.8451C22.45 38.7713 22.3426 38.7198 22.2375 38.6595C18.8041 36.68 15.3752 34.687 11.9307 32.7232C10.9644 32.173 10.5238 31.3879 10.5349 30.2852C10.5551 27.9411 10.5484 25.597 10.5372 23.2507C10.5327 22.1927 10.9622 21.4255 11.8926 20.8977C14.3105 19.5221 16.715 18.1264 19.1195 16.7284C19.3275 16.6076 19.4796 16.5875 19.6965 16.7172C20.5264 17.216 21.3719 17.6924 22.2554 18.2024C22.0876 18.3031 21.9601 18.3791 21.8304 18.4552C19.2268 19.9582 16.6278 21.4658 14.0175 22.9599C13.5903 23.2037 13.3912 23.5213 13.3957 24.0179C13.4091 25.8654 13.4114 27.713 13.3957 29.5605C13.3912 30.0705 13.5948 30.3948 14.0332 30.6453C16.7866 32.2199 19.5288 33.8125 22.28 35.3916C22.5126 35.5258 22.611 35.6645 22.6065 35.9418C22.5864 36.888 22.5998 37.8363 22.5998 38.8473L22.5953 38.8451ZM22.5953 33.553C22.356 33.4166 22.1838 33.3204 22.0116 33.2198C19.8285 31.9605 17.6477 30.6967 15.4602 29.4464C15.2231 29.3122 15.1359 29.1668 15.1381 28.8917C15.1538 27.4714 15.1471 26.0511 15.1426 24.6308C15.1426 24.4384 15.1717 24.3064 15.3618 24.1991C16.167 23.7495 16.9633 23.2798 17.7618 22.8212C17.8199 22.7877 17.8826 22.7631 17.9877 22.7116V24.3064C17.9877 25.1698 18.0011 26.0354 17.9832 26.8988C17.972 27.3909 18.1622 27.7241 18.5916 27.9657C19.8285 28.6636 21.0498 29.3883 22.2867 30.0839C22.5305 30.2203 22.6043 30.3724 22.5998 30.6408C22.5842 31.5847 22.5931 32.5308 22.5931 33.5508L22.5953 33.553ZM20.0746 14.91C19.6116 14.6371 19.2157 14.6393 18.7527 14.91C16.1581 16.4265 13.5523 17.9228 10.9487 19.4259C10.8391 19.4908 10.7251 19.5489 10.5305 19.6541C10.5998 18.6654 10.3873 17.7327 10.7251 16.8291C10.9085 16.3348 11.2529 15.9635 11.7092 15.6995C13.8811 14.4447 16.0507 13.1877 18.227 11.9396C19.0211 11.4833 19.8308 11.4945 20.6248 11.953C23.0964 13.3756 25.5657 14.8026 28.0306 16.2341C28.1357 16.2945 28.2677 16.4309 28.2677 16.5338C28.2856 17.5493 28.2788 18.567 28.2788 19.6563C27.3819 19.1396 26.5543 18.6609 25.7267 18.1823C23.8412 17.093 21.9512 16.0149 20.0746 14.91ZM37.4427 30.8779C37.3778 31.6764 36.9103 32.2423 36.2192 32.6404C33.5732 34.1614 30.9294 35.6913 28.2856 37.2168C27.4557 37.6954 26.6259 38.1741 25.7938 38.6527C25.6932 38.7109 25.5903 38.7601 25.4539 38.8317C25.4449 38.693 25.4337 38.5924 25.4337 38.4917C25.4337 37.6149 25.4382 36.7404 25.4293 35.8636C25.4293 35.6645 25.4762 35.5437 25.6596 35.4386C29.5157 33.2198 33.3696 30.9942 37.2212 28.7709C37.2794 28.7374 37.3443 28.7105 37.4539 28.6591C37.4539 29.4375 37.4986 30.1622 37.4427 30.8779ZM37.4628 25.3577C37.4561 26.2658 36.9663 26.9033 36.1901 27.3506C33.175 29.0841 30.1622 30.8265 27.1493 32.5666C26.5991 32.8842 26.0466 33.1996 25.4561 33.5396C25.4472 33.3897 25.436 33.2913 25.436 33.1907C25.436 32.3273 25.4449 31.4617 25.4293 30.5983C25.4248 30.3523 25.5075 30.2226 25.72 30.0995C28.46 28.5271 31.1911 26.9368 33.9355 25.3733C34.4231 25.096 34.6378 24.7538 34.6334 24.1812C34.6132 21.1974 34.6244 18.2136 34.6244 15.2298V14.7087C35.3402 15.1404 36.0112 15.496 36.624 15.9299C37.1832 16.3258 37.465 16.9253 37.4673 17.6164C37.4762 20.1976 37.4829 22.7788 37.465 25.3599L37.4628 25.3577Z" fill="%230D0D0D"></path><path fill-rule="evenodd" d="M24 0C10.7452 0 0 10.7452 0 24C0 37.2548 10.7452 48 24 48C37.2548 48 48 37.2548 48 24C48 10.7452 37.2548 0 24 0ZM24 2C11.8497 2 2 11.8497 2 24C2 36.1503 11.8497 46 24 46C36.1503 46 46 36.1503 46 24C46 11.8497 36.1503 2 24 2Z" fill="url(%23paint2_radial_6324_83922)"></path><path fill-rule="evenodd" d="M24 0C10.7452 0 0 10.7452 0 24C0 37.2548 10.7452 48 24 48C37.2548 48 48 37.2548 48 24C48 10.7452 37.2548 0 24 0ZM24 2C11.8497 2 2 11.8497 2 24C2 36.1503 11.8497 46 24 46C36.1503 46 46 36.1503 46 24C46 11.8497 36.1503 2 24 2Z" fill="url(%23paint3_radial_6324_83922)"></path><defs><radialGradient id="paint0_radial_6324_83922" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(13.4442 13.3899) rotate(44.9817) scale(46.7487 99.1435)"><stop stop-color="%23A3EEF8"></stop><stop offset="0.177083" stop-color="%23A4DCF5"></stop><stop offset="0.380208" stop-color="%23A6AEEC"></stop><stop offset="1" stop-color="%23ECBEE1"></stop></radialGradient><radialGradient id="paint1_radial_6324_83922" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(25.9515 43.7068) rotate(84.265) scale(24.2138 46.3215)"><stop stop-color="%23FCF5EE"></stop><stop offset="0.715135" stop-color="%23ECBEE1" stop-opacity="0"></stop></radialGradient><radialGradient id="paint2_radial_6324_83922" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(12.7405 12.6825) rotate(44.9817) scale(49.8653 105.753)"><stop stop-color="%23A3EEF8"></stop><stop offset="0.177083" stop-color="%23A4DCF5"></stop><stop offset="0.380208" stop-color="%23A6AEEC"></stop><stop offset="1" stop-color="%23ECBEE1"></stop></radialGradient><radialGradient id="paint3_radial_6324_83922" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(26.0816 45.0206) rotate(84.265) scale(25.828 49.4096)"><stop stop-color="%23FCF5EE"></stop><stop offset="0.715135" stop-color="%23ECBEE1" stop-opacity="0"></stop></radialGradient></defs></g></svg>',
+  name: 'Immutable Passport',
+  rdns: 'com.immutable.passport',
+  uuid: uuidv4(),
+} as EIP6963ProviderInfo;
+
+export function announceProvider(
+  detail: EIP6963ProviderDetail,
+) {
+  if (typeof window === 'undefined') return;
+  const event: CustomEvent<EIP6963ProviderDetail> = new CustomEvent(
+    'eip6963:announceProvider',
+    { detail: Object.freeze(detail) },
+  );
+
+  window.dispatchEvent(event);
+
+  const handler = () => window.dispatchEvent(event);
+  window.addEventListener('eip6963:requestProvider', handler);
+}

package/src/types.ts

@@ -0,0 +1,192 @@
+import { Environment, ModuleConfiguration } from '@imtbl/config';
+import { Flow } from '@imtbl/metrics';
+import { User } from '@imtbl/auth';
+import { BigNumberish } from 'ethers';
+import { JsonRpcError } from './zkEvm/JsonRpcError';
+
+// Re-export auth types for convenience
+export type {
+  User, UserProfile, UserImx, UserZkEvm, DirectLoginMethod,
+} from '@imtbl/auth';
+export { isUserImx, isUserZkEvm } from '@imtbl/auth';
+export type { RollupType } from '@imtbl/auth';
+
+export enum PassportEvents {
+  LOGGED_OUT = 'loggedOut',
+  LOGGED_IN = 'loggedIn',
+  ACCOUNTS_REQUESTED = 'accountsRequested',
+}
+
+export type AccountsRequestedEvent = {
+  environment: Environment;
+  sendTransaction: (params: Array<any>, flow: Flow) => Promise<string>;
+  walletAddress: string;
+  passportClient: string;
+  flow?: Flow;
+};
+
+export interface PassportEventMap extends Record<string, any> {
+  [PassportEvents.LOGGED_OUT]: [];
+  [PassportEvents.LOGGED_IN]: [User];
+  [PassportEvents.ACCOUNTS_REQUESTED]: [AccountsRequestedEvent];
+}
+
+// zkEVM/Wallet specific types
+export type Provider = {
+  request: (request: RequestArguments) => Promise<any>;
+  on: (event: string, listener: (...args: any[]) => void) => void;
+  removeListener: (event: string, listener: (...args: any[]) => void) => void;
+  isPassport: boolean;
+};
+
+export interface RequestArguments {
+  method: string;
+  params?: Array<any>;
+}
+
+export type JsonRpcRequestPayload = RequestArguments & {
+  jsonrpc?: string;
+  id?: string | number;
+};
+
+export interface JsonRpcRequestCallback {
+  (
+    err: JsonRpcError | null,
+    result?: JsonRpcResponsePayload | (JsonRpcResponsePayload | null)[] | null
+  ): void;
+}
+
+export interface JsonRpcResponsePayload {
+  result?: Array<any> | null;
+  error?: JsonRpcError | null;
+  jsonrpc?: string;
+  id?: string | number;
+}
+
+// https://eips.ethereum.org/EIPS/eip-712
+export interface TypedDataPayload {
+  types: {
+    EIP712Domain: Array<{ name: string; type: string }>;
+    [key: string]: Array<{ name: string; type: string }>;
+  };
+  domain: {
+    name?: string;
+    version?: string;
+    chainId?: number | string;
+    verifyingContract?: string;
+    salt?: string;
+  } | {
+    name?: string;
+    version?: string;
+    chainId?: number;
+    verifyingContract?: string;
+    salt?: string;
+  };
+  primaryType: string;
+  message: Record<string, any>;
+}
+
+export interface MetaTransaction {
+  to: string;
+  value?: BigNumberish | null;
+  data?: string | null;
+  nonce?: BigNumberish;
+  gasLimit?: BigNumberish;
+  delegateCall?: boolean;
+  revertOnError?: boolean;
+}
+
+export interface MetaTransactionNormalised {
+  delegateCall: boolean;
+  revertOnError: boolean;
+  gasLimit: BigNumberish;
+  target: string;
+  value: BigNumberish;
+  data: string;
+}
+
+export enum ProviderEvent {
+  ACCOUNTS_CHANGED = 'accountsChanged',
+}
+
+export type AccountsChangedEvent = Array<string>;
+
+export interface ProviderEventMap extends Record<string, any> {
+  [ProviderEvent.ACCOUNTS_CHANGED]: [AccountsChangedEvent];
+}
+
+export enum RelayerTransactionStatus {
+  PENDING = 'PENDING',
+  SUBMITTED = 'SUBMITTED',
+  SUCCESSFUL = 'SUCCESSFUL',
+  REVERTED = 'REVERTED',
+  FAILED = 'FAILED',
+  CANCELLED = 'CANCELLED',
+}
+
+export interface RelayerTransaction {
+  status: RelayerTransactionStatus;
+  chainId: string;
+  relayerId: string;
+  hash: string;
+  statusMessage?: string;
+}
+
+export interface FeeOption {
+  tokenPrice: string;
+  tokenSymbol: string;
+  tokenDecimals: number;
+  tokenAddress: string;
+  recipientAddress: string;
+}
+
+/**
+ * Event detail from the `eip6963:announceProvider` event.
+ */
+export interface EIP6963ProviderDetail {
+  info: EIP6963ProviderInfo;
+  provider: Provider;
+}
+
+/**
+ * Metadata of the EIP-1193 Provider.
+ */
+export interface EIP6963ProviderInfo {
+  icon: `data:image/${string}`; // RFC-2397
+  name: string;
+  rdns: string;
+  uuid: string;
+}
+
+/**
+ * Event type to announce an EIP-1193 Provider.
+ */
+export interface EIP6963AnnounceProviderEvent
+  extends CustomEvent<EIP6963ProviderDetail> {
+  type: 'eip6963:announceProvider';
+}
+
+// Wallet configuration types
+export interface WalletOverrides {
+  passportDomain: string;
+  zkEvmRpcUrl: string;
+  relayerUrl: string;
+  indexerMrBasePath: string;
+}
+
+export interface WalletModuleConfiguration extends ModuleConfiguration<WalletOverrides> {
+  /**
+   * Optional referrer URL to be sent with JSON-RPC requests.
+   */
+  jsonRpcReferrer?: string;
+
+  /**
+   * If true, forces SCW deployment before allowing message signature.
+   */
+  forceScwDeployBeforeMessageSignature?: boolean;
+
+  /**
+   * This flag indicates that Wallet is being used in a cross-sdk bridge scenario.
+   */
+  crossSdkBridgeEnabled?: boolean;
+}

package/src/utils/metrics.ts

@@ -0,0 +1,57 @@
+import { Flow, trackError, trackFlow } from '@imtbl/metrics';
+
+export const withMetrics = <T>(
+  fn: (flow: Flow) => T,
+  flowName: string,
+  trackStartEvent: boolean = true,
+  trackEndEvent: boolean = true,
+): T => {
+  const flow: Flow = trackFlow(
+    'passport',
+    flowName,
+    trackStartEvent,
+  );
+
+  try {
+    return fn(flow);
+  } catch (error) {
+    if (error instanceof Error) {
+      trackError('passport', flowName, error, { flowId: flow.details.flowId });
+    } else {
+      flow.addEvent('errored');
+    }
+    throw error;
+  } finally {
+    if (trackEndEvent) {
+      flow.addEvent('End');
+    }
+  }
+};
+
+export const withMetricsAsync = async <T>(
+  fn: (flow: Flow) => Promise<T>,
+  flowName: string,
+  trackStartEvent: boolean = true,
+  trackEndEvent: boolean = true,
+): Promise<T> => {
+  const flow: Flow = trackFlow(
+    'passport',
+    flowName,
+    trackStartEvent,
+  );
+
+  try {
+    return await fn(flow);
+  } catch (error) {
+    if (error instanceof Error) {
+      trackError('passport', flowName, error, { flowId: flow.details.flowId });
+    } else {
+      flow.addEvent('errored');
+    }
+    throw error;
+  } finally {
+    if (trackEndEvent) {
+      flow.addEvent('End');
+    }
+  }
+};

package/src/utils/string.ts

@@ -0,0 +1,12 @@
+import { getBytes, stripZerosLeft, toUtf8String } from 'ethers';
+
+export const hexToString = (hex: string) => {
+  if (!hex) return hex;
+
+  try {
+    const stripped = stripZerosLeft(getBytes(hex));
+    return toUtf8String(stripped);
+  } catch (e) {
+    return hex;
+  }
+};

package/src/utils/typedEventEmitter.ts

@@ -0,0 +1,26 @@
+import { EventEmitter } from 'events';
+
+export default class TypedEventEmitter<TEvents extends Record<string, any>> {
+  private emitter = new EventEmitter();
+
+  emit<TEventName extends keyof TEvents & string>(
+    eventName: TEventName,
+    ...eventArg: TEvents[TEventName]
+  ) {
+    this.emitter.emit(eventName, ...(eventArg as []));
+  }
+
+  on<TEventName extends keyof TEvents & string>(
+    eventName: TEventName,
+    handler: (...eventArg: TEvents[TEventName]) => void,
+  ) {
+    this.emitter.on(eventName, handler as any);
+  }
+
+  removeListener<TEventName extends keyof TEvents & string>(
+    eventName: TEventName,
+    handler: (...eventArg: TEvents[TEventName]) => void,
+  ) {
+    this.emitter.removeListener(eventName, handler as any);
+  }
+}

package/src/zkEvm/JsonRpcError.ts

@@ -0,0 +1,33 @@
+/**
+ * ProviderErrors should take priority over RpcErrorCodes
+ * https://eips.ethereum.org/EIPS/eip-1193#provider-errors
+ * https://eips.ethereum.org/EIPS/eip-1474#error-codes
+ */
+export enum ProviderErrorCode {
+  USER_REJECTED_REQUEST = 4001,
+  UNAUTHORIZED = 4100,
+  UNSUPPORTED_METHOD = 4200,
+  DISCONNECTED = 4900,
+}
+
+export enum RpcErrorCode {
+  RPC_SERVER_ERROR = -32000,
+  INVALID_REQUEST = -32600,
+  METHOD_NOT_FOUND = -32601,
+  INVALID_PARAMS = -32602,
+  INTERNAL_ERROR = -32603,
+  PARSE_ERROR = -32700,
+  TRANSACTION_REJECTED = -32003,
+}
+
+export class JsonRpcError extends Error {
+  public readonly message: string;
+
+  public readonly code: ProviderErrorCode | RpcErrorCode;
+
+  constructor(code: ProviderErrorCode | RpcErrorCode, message: string) {
+    super(message);
+    this.message = message;
+    this.code = code;
+  }
+}

package/src/zkEvm/index.ts

@@ -0,0 +1,2 @@
+export * from './zkEvmProvider';
+export * from './types';