@imtbl/wallet 2.10.7-alpha.2

package/src/zkEvm/signTypedDataV4.ts

@@ -0,0 +1,103 @@
+import { Flow } from '@imtbl/metrics';
+import { Signer, JsonRpcProvider } from 'ethers';
+import GuardianClient from '../guardian';
+import { signAndPackTypedData } from './walletHelpers';
+import { TypedDataPayload } from './types';
+import { JsonRpcError, RpcErrorCode } from './JsonRpcError';
+import { RelayerClient } from './relayerClient';
+
+export type SignTypedDataV4Params = {
+  ethSigner: Signer;
+  rpcProvider: JsonRpcProvider;
+  relayerClient: RelayerClient;
+  method: string;
+  params: Array<any>;
+  guardianClient: GuardianClient;
+  flow: Flow;
+};
+
+const REQUIRED_TYPED_DATA_PROPERTIES = ['types', 'domain', 'primaryType', 'message'];
+const isValidTypedDataPayload = (typedData: object): typedData is TypedDataPayload => (
+  REQUIRED_TYPED_DATA_PROPERTIES.every((key) => key in typedData)
+);
+
+const transformTypedData = (typedData: string | object, chainId: bigint): TypedDataPayload => {
+  let transformedTypedData: object | TypedDataPayload;
+
+  if (typeof typedData === 'string') {
+    try {
+      transformedTypedData = JSON.parse(typedData);
+    } catch (err: any) {
+      throw new JsonRpcError(RpcErrorCode.INVALID_PARAMS, `Failed to parse typed data JSON: ${err}`);
+    }
+  } else if (typeof typedData === 'object') {
+    transformedTypedData = typedData;
+  } else {
+    throw new JsonRpcError(RpcErrorCode.INVALID_PARAMS, `Invalid typed data argument: ${typedData}`);
+  }
+
+  if (!isValidTypedDataPayload(transformedTypedData)) {
+    throw new JsonRpcError(
+      RpcErrorCode.INVALID_PARAMS,
+      // eslint-disable-next-line max-len
+      `Invalid typed data argument. The following properties are required: ${REQUIRED_TYPED_DATA_PROPERTIES.join(', ')}`,
+    );
+  }
+
+  const providedChainId = transformedTypedData.domain?.chainId;
+
+  if (providedChainId) {
+    // domain.chainId (if defined) can be a number, string, or hex value, but the relayer & guardian only accept a number.
+    if (typeof providedChainId === 'string') {
+      if (providedChainId.startsWith('0x')) {
+        transformedTypedData.domain.chainId = parseInt(providedChainId, 16).toString();
+      } else {
+        transformedTypedData.domain.chainId = parseInt(providedChainId, 10).toString();
+      }
+    }
+
+    if (BigInt(transformedTypedData.domain.chainId ?? 0) !== chainId) {
+      throw new JsonRpcError(RpcErrorCode.INVALID_PARAMS, `Invalid chainId, expected ${chainId}`);
+    }
+  }
+
+  return transformedTypedData;
+};
+
+export const signTypedDataV4 = async ({
+  params,
+  method,
+  ethSigner,
+  rpcProvider,
+  relayerClient,
+  guardianClient,
+  flow,
+}: SignTypedDataV4Params): Promise<string> => {
+  const fromAddress: string = params[0];
+  const typedDataParam: string | object = params[1];
+
+  if (!fromAddress || !typedDataParam) {
+    throw new JsonRpcError(RpcErrorCode.INVALID_PARAMS, `${method} requires an address and a typed data JSON`);
+  }
+
+  const { chainId } = await rpcProvider.getNetwork();
+  const typedData = transformTypedData(typedDataParam, chainId);
+  flow.addEvent('endDetectNetwork');
+
+  await guardianClient.evaluateEIP712Message({ chainID: String(chainId), payload: typedData });
+  flow.addEvent('endValidateMessage');
+
+  const relayerSignature = await relayerClient.imSignTypedData(fromAddress, typedData);
+  flow.addEvent('endRelayerSignTypedData');
+
+  const signature = await signAndPackTypedData(
+    typedData,
+    relayerSignature,
+    BigInt(chainId),
+    fromAddress,
+    ethSigner,
+  );
+  flow.addEvent('getSignedTypedData');
+
+  return signature;
+};

package/src/zkEvm/transactionHelpers.ts

@@ -0,0 +1,295 @@
+import { Flow } from '@imtbl/metrics';
+import {
+  Signer, TransactionRequest, JsonRpcProvider,
+  BigNumberish,
+} from 'ethers';
+import {
+  getEip155ChainId,
+  signMetaTransactions,
+  encodedTransactions,
+  getNormalisedTransactions,
+  getNonce,
+} from './walletHelpers';
+import { RelayerClient } from './relayerClient';
+import GuardianClient, { convertBigNumberishToString } from '../guardian';
+import {
+  FeeOption,
+  MetaTransaction,
+  RelayerTransactionStatus,
+} from './types';
+import { JsonRpcError, RpcErrorCode } from './JsonRpcError';
+import { retryWithDelay } from '../network/retry';
+
+const MAX_TRANSACTION_HASH_RETRIEVAL_RETRIES = 30;
+const TRANSACTION_HASH_RETRIEVAL_WAIT = 1000;
+
+export type TransactionParams = {
+  ethSigner: Signer;
+  rpcProvider: JsonRpcProvider;
+  guardianClient: GuardianClient;
+  relayerClient: RelayerClient;
+  zkEvmAddress: string;
+  flow: Flow;
+  nonceSpace?: bigint;
+  isBackgroundTransaction?: boolean;
+};
+
+export type EjectionTransactionParams = Pick<TransactionParams, 'ethSigner' | 'zkEvmAddress' | 'flow'>;
+export type EjectionTransactionResponse = {
+  to: string;
+  data: string;
+  chainId: string;
+};
+
+const getFeeOption = async (
+  metaTransaction: MetaTransaction,
+  walletAddress: string,
+  relayerClient: RelayerClient,
+): Promise<FeeOption> => {
+  const normalisedMetaTransaction = getNormalisedTransactions([
+    metaTransaction,
+  ]);
+  const transactions = encodedTransactions(normalisedMetaTransaction);
+  const feeOptions = await relayerClient.imGetFeeOptions(
+    walletAddress,
+    transactions,
+  );
+
+  if (!feeOptions || !Array.isArray(feeOptions)) {
+    throw new Error('Invalid fee options received from relayer');
+  }
+
+  const imxFeeOption = feeOptions.find(
+    (feeOption) => feeOption.tokenSymbol === 'IMX',
+  );
+  if (!imxFeeOption) {
+    throw new Error('Failed to retrieve fees for IMX token');
+  }
+
+  return imxFeeOption;
+};
+
+/**
+ * Prepares the meta transactions array to be signed by estimating the fee and
+ * getting the nonce from the smart wallet.
+ */
+const buildMetaTransactions = async (
+  transactionRequest: TransactionRequest,
+  rpcProvider: JsonRpcProvider,
+  relayerClient: RelayerClient,
+  zkevmAddress: string,
+  nonceSpace?: bigint,
+): Promise<[MetaTransaction, ...MetaTransaction[]]> => {
+  if (!transactionRequest.to) {
+    throw new JsonRpcError(
+      RpcErrorCode.INVALID_PARAMS,
+      'eth_sendTransaction requires a "to" field',
+    );
+  }
+
+  const metaTransaction: MetaTransaction = {
+    to: transactionRequest.to.toString(),
+    data: transactionRequest.data,
+    nonce: BigInt(0), // NOTE: We don't need a valid nonce to estimate the fee
+    value: transactionRequest.value,
+    revertOnError: true,
+  };
+
+  // Estimate the fee and get the nonce from the smart wallet
+  const [nonce, feeOption] = await Promise.all([
+    getNonce(rpcProvider, zkevmAddress, nonceSpace),
+    getFeeOption(metaTransaction, zkevmAddress, relayerClient),
+  ]);
+
+  // Build the meta transactions array with a valid nonce and fee transaction
+  const metaTransactions: [MetaTransaction, ...MetaTransaction[]] = [
+    {
+      ...metaTransaction,
+      nonce,
+    },
+  ];
+
+  // Add a fee transaction if the fee is non-zero
+  const feeValue = BigInt(feeOption.tokenPrice);
+  if (feeValue !== BigInt(0)) {
+    metaTransactions.push({
+      nonce,
+      to: feeOption.recipientAddress,
+      value: feeValue,
+      revertOnError: true,
+    });
+  }
+
+  return metaTransactions;
+};
+
+export const pollRelayerTransaction = async (
+  relayerClient: RelayerClient,
+  relayerId: string,
+  flow: Flow,
+) => {
+  const retrieveRelayerTransaction = async () => {
+    const tx = await relayerClient.imGetTransactionByHash(relayerId);
+    // NOTE: The transaction hash is only available from the Relayer once the
+    // transaction is actually submitted onchain. Hence we need to poll the
+    // Relayer get transaction endpoint until the status transitions to one that
+    // has the hash available.
+    if (tx.status === RelayerTransactionStatus.PENDING) {
+      throw new Error();
+    }
+    return tx;
+  };
+
+  const relayerTransaction = await retryWithDelay(retrieveRelayerTransaction, {
+    retries: MAX_TRANSACTION_HASH_RETRIEVAL_RETRIES,
+    interval: TRANSACTION_HASH_RETRIEVAL_WAIT,
+    finalErr: new JsonRpcError(
+      RpcErrorCode.RPC_SERVER_ERROR,
+      'transaction hash not generated in time',
+    ),
+  });
+  flow.addEvent('endRetrieveRelayerTransaction');
+
+  if (
+    ![
+      RelayerTransactionStatus.SUBMITTED,
+      RelayerTransactionStatus.SUCCESSFUL,
+    ].includes(relayerTransaction.status)
+  ) {
+    let errorMessage = `Transaction failed to submit with status ${relayerTransaction.status}.`;
+    if (relayerTransaction.statusMessage) {
+      errorMessage += ` Error message: ${relayerTransaction.statusMessage}`;
+    }
+    throw new JsonRpcError(RpcErrorCode.RPC_SERVER_ERROR, errorMessage);
+  }
+
+  return relayerTransaction;
+};
+
+export const prepareAndSignTransaction = async ({
+  transactionRequest,
+  ethSigner,
+  rpcProvider,
+  guardianClient,
+  relayerClient,
+  zkEvmAddress,
+  flow,
+  nonceSpace,
+  isBackgroundTransaction,
+}: TransactionParams & { transactionRequest: TransactionRequest }) => {
+  const { chainId } = await rpcProvider.getNetwork();
+  const chainIdBigNumber = BigInt(chainId);
+  flow.addEvent('endDetectNetwork');
+
+  const metaTransactions = await buildMetaTransactions(
+    transactionRequest,
+    rpcProvider,
+    relayerClient,
+    zkEvmAddress,
+    nonceSpace,
+  );
+  flow.addEvent('endBuildMetaTransactions');
+
+  const { nonce } = metaTransactions[0];
+  if (typeof nonce === 'undefined') {
+    throw new Error('Failed to retrieve nonce from the smart wallet');
+  }
+
+  // Parallelize the validation and signing of the transaction
+  // without waiting for the validation to complete
+  const validateTransaction = async () => {
+    await guardianClient.validateEVMTransaction({
+      chainId: getEip155ChainId(Number(chainId)),
+      nonce: convertBigNumberishToString(nonce),
+      metaTransactions,
+      isBackgroundTransaction,
+    });
+    flow.addEvent('endValidateEVMTransaction');
+  };
+
+  // NOTE: We sign again because we now are adding the fee transaction, so the
+  // whole payload is different and needs a new signature.
+  const signTransaction = async () => {
+    const signed = await signMetaTransactions(
+      metaTransactions,
+      nonce,
+      chainIdBigNumber,
+      zkEvmAddress,
+      ethSigner,
+    );
+    flow.addEvent('endGetSignedMetaTransactions');
+    return signed;
+  };
+
+  const [, signedTransactions] = await Promise.all([
+    validateTransaction(),
+    signTransaction(),
+  ]);
+
+  const relayerId = await relayerClient.ethSendTransaction(zkEvmAddress, signedTransactions);
+  flow.addEvent('endRelayerSendTransaction');
+
+  return { signedTransactions, relayerId, nonce };
+};
+
+const buildMetaTransactionForEjection = async (
+  transactionRequest: TransactionRequest,
+): Promise<[MetaTransaction, ...MetaTransaction[]]> => {
+  if (!transactionRequest.to) {
+    throw new JsonRpcError(
+      RpcErrorCode.INVALID_PARAMS,
+      'im_signEjectionTransaction requires a "to" field',
+    );
+  }
+
+  if (typeof transactionRequest.nonce === 'undefined') {
+    throw new JsonRpcError(
+      RpcErrorCode.INVALID_PARAMS,
+      'im_signEjectionTransaction requires a "nonce" field',
+    );
+  }
+
+  if (!transactionRequest.chainId) {
+    throw new JsonRpcError(
+      RpcErrorCode.INVALID_PARAMS,
+      'im_signEjectionTransaction requires a "chainId" field',
+    );
+  }
+
+  const metaTransaction: MetaTransaction = {
+    to: transactionRequest.to.toString(),
+    data: transactionRequest.data,
+    nonce: transactionRequest.nonce ?? undefined,
+    value: transactionRequest.value,
+    revertOnError: true,
+  };
+
+  return [metaTransaction];
+};
+
+export const prepareAndSignEjectionTransaction = async ({
+  transactionRequest,
+  ethSigner,
+  zkEvmAddress,
+  flow,
+}: EjectionTransactionParams & { transactionRequest: TransactionRequest }): Promise<EjectionTransactionResponse> => {
+  const metaTransaction = await buildMetaTransactionForEjection(
+    transactionRequest,
+  );
+  flow.addEvent('endBuildMetaTransactions');
+
+  const signedTransaction = await signMetaTransactions(
+    metaTransaction,
+    transactionRequest.nonce as BigNumberish,
+    BigInt(transactionRequest.chainId ?? 0),
+    zkEvmAddress,
+    ethSigner,
+  );
+  flow.addEvent('endGetSignedMetaTransactions');
+
+  return {
+    to: zkEvmAddress,
+    data: signedTransaction,
+    chainId: getEip155ChainId(Number(transactionRequest.chainId ?? 0)),
+  };
+};

package/src/zkEvm/types.ts

@@ -0,0 +1,136 @@
+import { BigNumberish } from 'ethers';
+import { JsonRpcError } from './JsonRpcError';
+
+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;
+}
+
+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;
+}
+
+// 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 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;
+}
+
+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 enum ProviderEvent {
+  ACCOUNTS_CHANGED = 'accountsChanged',
+}
+
+export type AccountsChangedEvent = Array<string>;
+
+export interface ProviderEventMap extends Record<string, any> {
+  [ProviderEvent.ACCOUNTS_CHANGED]: [AccountsChangedEvent];
+}
+
+/**
+ * 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';
+}

package/src/zkEvm/user/index.ts

@@ -0,0 +1 @@
+export * from './registerZkEvmUser';

package/src/zkEvm/user/registerZkEvmUser.ts

@@ -0,0 +1,75 @@
+import { MultiRollupApiClients } from '@imtbl/generated-clients';
+import { signRaw } from '@imtbl/toolkit';
+import { Flow } from '@imtbl/metrics';
+import { Signer, JsonRpcProvider } from 'ethers';
+import { getEip155ChainId } from '../walletHelpers';
+import { AuthManager } from '@imtbl/auth';
+import { JsonRpcError, RpcErrorCode } from '../JsonRpcError';
+
+export type RegisterZkEvmUserInput = {
+  authManager: AuthManager;
+  ethSigner: Signer,
+  multiRollupApiClients: MultiRollupApiClients,
+  accessToken: string;
+  rpcProvider: JsonRpcProvider;
+  flow: Flow;
+};
+
+const MESSAGE_TO_SIGN = 'Only sign this message from Immutable Passport';
+
+export async function registerZkEvmUser({
+  authManager,
+  ethSigner,
+  multiRollupApiClients,
+  accessToken,
+  rpcProvider,
+  flow,
+}: RegisterZkEvmUserInput): Promise<string> {
+  // Parallelize the operations that can happen concurrently
+  const getAddressPromise = ethSigner.getAddress();
+  getAddressPromise.then(() => flow.addEvent('endGetAddress'));
+
+  const signRawPromise = signRaw(MESSAGE_TO_SIGN, ethSigner);
+  signRawPromise.then(() => flow.addEvent('endSignRaw'));
+
+  const detectNetworkPromise = rpcProvider.getNetwork();
+  detectNetworkPromise.then(() => flow.addEvent('endDetectNetwork'));
+
+  const listChainsPromise = multiRollupApiClients.chainsApi.listChains();
+  listChainsPromise.then(() => flow.addEvent('endListChains'));
+
+  const [ethereumAddress, ethereumSignature, network, chainListResponse] = await Promise.all([
+    getAddressPromise,
+    signRawPromise,
+    detectNetworkPromise,
+    listChainsPromise,
+  ]);
+
+  const eipChainId = getEip155ChainId(Number(network.chainId));
+  const chainName = chainListResponse.data?.result?.find((chain) => chain.id === eipChainId)?.name;
+  if (!chainName) {
+    throw new JsonRpcError(
+      RpcErrorCode.INTERNAL_ERROR,
+      `Chain name does not exist on for chain id ${network.chainId}`,
+    );
+  }
+
+  try {
+    const registrationResponse = await multiRollupApiClients.passportApi.createCounterfactualAddressV2({
+      chainName,
+      createCounterfactualAddressRequest: {
+        ethereum_address: ethereumAddress,
+        ethereum_signature: ethereumSignature,
+      },
+    }, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    flow.addEvent('endCreateCounterfactualAddress');
+
+    authManager.forceUserRefreshInBackground();
+
+    return registrationResponse.data.counterfactual_address;
+  } catch (error) {
+    throw new JsonRpcError(RpcErrorCode.INTERNAL_ERROR, `Failed to create counterfactual address: ${error}`);
+  }
+}