@imtbl/wallet 2.12.5-alpha.8 → 2.12.5

package/src/sequence/signer/identityInstrumentSigner.ts

@@ -0,0 +1,193 @@
+import { hashMessage, toHex, concat } from 'viem';
+import { Identity } from '@0xsequence/wallet-wdk';
+import { IdentityInstrument, IdTokenChallenge } from '@0xsequence/identity-instrument';
+import { WalletError, WalletErrorType } from '../../errors';
+import { Auth, User, decodeJwtPayload } from '@imtbl/auth';
+import { Hex, Address } from 'ox';
+import {
+  Payload,
+  Signature as SequenceSignature,
+} from '@0xsequence/wallet-primitives';
+import { SequenceSigner } from './types';
+
+interface IdTokenPayload {
+  iss: string;
+  aud: string;
+  sub: string;
+}
+
+interface AuthKey {
+  address: string;
+  privateKey: CryptoKey;
+  identitySigner: string;
+  expiresAt: Date;
+}
+
+interface UserWallet {
+  userIdentifier: string;
+  signerAddress: string;
+  authKey: AuthKey;
+  identityInstrument: IdentityInstrument;
+}
+
+export interface IdentityInstrumentSignerConfig {
+  /** Sequence Identity Instrument endpoint URL */
+  identityInstrumentEndpoint: string;
+}
+
+export class IdentityInstrumentSigner implements SequenceSigner {
+  readonly #auth: Auth;
+
+  readonly #config: IdentityInstrumentSignerConfig;
+
+  #userWallet: UserWallet | null = null;
+
+  #createWalletPromise: Promise<UserWallet> | null = null;
+
+  constructor(auth: Auth, config: IdentityInstrumentSignerConfig) {
+    this.#auth = auth;
+    this.#config = config;
+  }
+
+  async #getUserOrThrow(): Promise<User> {
+    const user = await this.#auth.getUser();
+    if (!user) {
+      throw new WalletError(
+        'User not authenticated',
+        WalletErrorType.NOT_LOGGED_IN_ERROR,
+      );
+    }
+    return user;
+  }
+
+  async #getUserWallet(): Promise<UserWallet> {
+    let userWallet = this.#userWallet;
+    if (!userWallet) {
+      userWallet = await this.#createWallet();
+    }
+
+    const user = await this.#getUserOrThrow();
+    if (user.profile.sub !== userWallet.userIdentifier) {
+      userWallet = await this.#createWallet(user);
+    }
+
+    return userWallet;
+  }
+
+  async #createWallet(user?: User): Promise<UserWallet> {
+    if (this.#createWalletPromise) return this.#createWalletPromise;
+
+    this.#createWalletPromise = (async () => {
+      try {
+        this.#userWallet = null;
+        await this.#auth.forceUserRefresh(); // TODO shouldn't have to refresh all the time
+
+        const authenticatedUser = user || await this.#getUserOrThrow();
+
+        if (!authenticatedUser.idToken) {
+          throw new WalletError(
+            'User idToken not available',
+            WalletErrorType.NOT_LOGGED_IN_ERROR,
+          );
+        }
+
+        const { idToken } = authenticatedUser;
+        const decoded = decodeJwtPayload<IdTokenPayload>(idToken);
+        const issuer = decoded.iss;
+        const audience = decoded.aud;
+
+        const keyPair = await window.crypto.subtle.generateKey(
+          { name: 'ECDSA', namedCurve: 'P-256' },
+          false,
+          ['sign', 'verify'],
+        );
+
+        const publicKey = await window.crypto.subtle.exportKey('raw', keyPair.publicKey);
+        const authKey: AuthKey = {
+          address: Hex.fromBytes(new Uint8Array(publicKey)),
+          privateKey: keyPair.privateKey,
+          identitySigner: '',
+          expiresAt: new Date(Date.now() + 3600000),
+        };
+
+        const identityInstrument = new IdentityInstrument(
+          this.#config.identityInstrumentEndpoint,
+          '@14:test',
+        );
+        const challenge = new IdTokenChallenge(issuer, audience, idToken);
+
+        await identityInstrument.commitVerifier(
+          Identity.toIdentityAuthKey(authKey),
+          challenge,
+        );
+
+        const result = await identityInstrument.completeAuth(
+          Identity.toIdentityAuthKey(authKey),
+          challenge,
+        );
+
+        const signerAddress = result.signer.address;
+        authKey.identitySigner = signerAddress;
+
+        this.#userWallet = {
+          userIdentifier: authenticatedUser.profile.sub,
+          signerAddress,
+          authKey,
+          identityInstrument,
+        };
+
+        return this.#userWallet;
+      } catch (error) {
+        const errorMessage = `Identity Instrument: Failed to create signer: ${(error as Error).message}`;
+        throw new WalletError(errorMessage, WalletErrorType.WALLET_CONNECTION_ERROR);
+      } finally {
+        this.#createWalletPromise = null;
+      }
+    })();
+
+    return this.#createWalletPromise;
+  }
+
+  async getAddress(): Promise<string> {
+    const wallet = await this.#getUserWallet();
+    return wallet.signerAddress;
+  }
+
+  async signPayload(
+    walletAddress: Address.Address,
+    chainId: number,
+    payload: Payload.Parented,
+  ): Promise<SequenceSignature.SignatureOfSignerLeaf> {
+    const wallet = await this.#getUserWallet();
+
+    const signer = new Identity.IdentitySigner(
+      wallet.identityInstrument,
+      wallet.authKey,
+    );
+
+    return signer.sign(walletAddress, chainId, payload);
+  }
+
+  async signMessage(message: string | Uint8Array): Promise<string> {
+    const wallet = await this.#getUserWallet();
+
+    const signer = new Identity.IdentitySigner(
+      wallet.identityInstrument,
+      wallet.authKey,
+    );
+
+    const messageBytes = typeof message === 'string'
+      ? new TextEncoder().encode(message)
+      : message;
+    const digest = hashMessage({ raw: messageBytes });
+
+    const signature = await signer.signDigest(Hex.toBytes(digest));
+
+    // Format signature: r (32 bytes) + s (32 bytes) + v (1 byte)
+    const r = toHex(signature.r, { size: 32 });
+    const s = toHex(signature.s, { size: 32 });
+    const v = toHex(signature.yParity + 27, { size: 1 });
+
+    return concat([r, s, v]);
+  }
+}

package/src/sequence/signer/index.ts

@@ -0,0 +1,45 @@
+import { Auth, IAuthConfiguration } from '@imtbl/auth';
+import { SequenceSigner } from './types';
+import { IdentityInstrumentSigner } from './identityInstrumentSigner';
+import { PrivateKeySigner } from './privateKeySigner';
+
+export type { SequenceSigner } from './types';
+export { IdentityInstrumentSigner } from './identityInstrumentSigner';
+export type { IdentityInstrumentSignerConfig } from './identityInstrumentSigner';
+export { PrivateKeySigner } from './privateKeySigner';
+
+const DEV_AUTH_DOMAIN = 'https://auth.dev.immutable.com';
+
+export interface CreateSequenceSignerConfig {
+  /** Identity Instrument endpoint (required for prod/sandbox) */
+  identityInstrumentEndpoint?: string;
+}
+
+/**
+ * Create the appropriate signer based on environment.
+ * - Dev environment (behind VPN): uses PrivateKeySigner
+ * - Prod/Sandbox: uses IdentityInstrumentSigner
+ *
+ * @param auth - Auth instance
+ * @param authConfig - Auth configuration (to determine environment)
+ * @param config - Signer configuration
+ */
+export function createSequenceSigner(
+  auth: Auth,
+  authConfig: IAuthConfiguration,
+  config: CreateSequenceSignerConfig = {},
+): SequenceSigner {
+  const isDevEnvironment = authConfig.authenticationDomain === DEV_AUTH_DOMAIN;
+
+  if (isDevEnvironment) {
+    return new PrivateKeySigner(auth);
+  }
+
+  if (!config.identityInstrumentEndpoint) {
+    throw new Error('identityInstrumentEndpoint is required for non-dev environments');
+  }
+
+  return new IdentityInstrumentSigner(auth, {
+    identityInstrumentEndpoint: config.identityInstrumentEndpoint,
+  });
+}

package/src/sequence/signer/privateKeySigner.ts

@@ -0,0 +1,111 @@
+import { keccak256, toBytes } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { WalletError, WalletErrorType } from '../../errors';
+import { Auth, User } from '@imtbl/auth';
+import { Signers } from '@0xsequence/wallet-core';
+import {
+  Payload,
+  Signature as SequenceSignature,
+} from '@0xsequence/wallet-primitives';
+import { SequenceSigner } from './types';
+import { Address } from 'ox';
+
+interface PrivateKeyWallet {
+  userIdentifier: string;
+  signerAddress: string;
+  signer: Signers.Pk.Pk;
+  privateKey: `0x${string}`;
+}
+
+/**
+ * Private key signer for dev environments (behind VPN).
+ * Uses a deterministic private key derived from the user's sub.
+ */
+export class PrivateKeySigner implements SequenceSigner {
+  readonly #auth: Auth;
+
+  #privateKeyWallet: PrivateKeyWallet | null = null;
+
+  #createWalletPromise: Promise<PrivateKeyWallet> | null = null;
+
+  constructor(auth: Auth) {
+    this.#auth = auth;
+  }
+
+  async #getUserOrThrow(): Promise<User> {
+    const user = await this.#auth.getUser();
+    if (!user) {
+      throw new WalletError('User not authenticated', WalletErrorType.NOT_LOGGED_IN_ERROR);
+    }
+    return user;
+  }
+
+  async #getWalletInstance(): Promise<PrivateKeyWallet> {
+    let privateKeyWallet = this.#privateKeyWallet;
+    if (!privateKeyWallet) {
+      privateKeyWallet = await this.#createWallet();
+    }
+
+    const user = await this.#getUserOrThrow();
+    if (user.profile.sub !== privateKeyWallet.userIdentifier) {
+      privateKeyWallet = await this.#createWallet(user);
+    }
+
+    return privateKeyWallet;
+  }
+
+  async #createWallet(user?: User): Promise<PrivateKeyWallet> {
+    if (this.#createWalletPromise) return this.#createWalletPromise;
+
+    this.#createWalletPromise = (async () => {
+      try {
+        this.#privateKeyWallet = null;
+        const authenticatedUser = user || (await this.#getUserOrThrow());
+
+        const privateKeyHash = keccak256(toBytes(`${authenticatedUser.profile.sub}-sequence`));
+        const signer = new Signers.Pk.Pk(privateKeyHash);
+        const signerAddress = signer.address;
+
+        this.#privateKeyWallet = {
+          userIdentifier: authenticatedUser.profile.sub,
+          signerAddress,
+          signer,
+          privateKey: privateKeyHash,
+        };
+
+        return this.#privateKeyWallet;
+      } catch (error) {
+        const errorMessage = `Failed to create private key wallet: ${(error as Error).message}`;
+        throw new WalletError(errorMessage, WalletErrorType.WALLET_CONNECTION_ERROR);
+      } finally {
+        this.#createWalletPromise = null;
+      }
+    })();
+
+    return this.#createWalletPromise;
+  }
+
+  async getAddress(): Promise<string> {
+    const wallet = await this.#getWalletInstance();
+    return wallet.signerAddress;
+  }
+
+  async signPayload(
+    walletAddress: Address.Address,
+    chainId: number,
+    payload: Payload.Parented,
+  ): Promise<SequenceSignature.SignatureOfSignerLeaf> {
+    const pkWallet = await this.#getWalletInstance();
+    return pkWallet.signer.sign(walletAddress, chainId, payload);
+  }
+
+  async signMessage(message: string | Uint8Array): Promise<string> {
+    const pkWallet = await this.#getWalletInstance();
+
+    // Use viem's account to sign
+    const account = privateKeyToAccount(pkWallet.privateKey);
+    const messageToSign = typeof message === 'string' ? message : { raw: message };
+
+    return await account.signMessage({ message: messageToSign });
+  }
+}

package/src/sequence/signer/types.ts

@@ -0,0 +1,24 @@
+import { Address } from 'ox';
+import {
+  Payload,
+  Signature as SequenceSignature,
+} from '@0xsequence/wallet-primitives';
+
+/**
+ * Signer interface for Sequence wallet operations.
+ * Used by non-zkEVM chains (e.g., Arbitrum).
+ */
+export interface SequenceSigner {
+  /** Get the signer's address */
+  getAddress(): Promise<string>;
+
+  /** Sign a Sequence payload (for transactions) */
+  signPayload(
+    walletAddress: Address.Address,
+    chainId: number,
+    payload: Payload.Parented,
+  ): Promise<SequenceSignature.SignatureOfSignerLeaf>;
+
+  /** Sign a message (EIP-191 personal_sign) */
+  signMessage(message: string | Uint8Array): Promise<string>;
+}

package/src/sequence/user/index.ts

@@ -0,0 +1,2 @@
+export { registerUser } from './registerUser';
+export type { RegisterUserInput } from './registerUser';

package/src/sequence/user/registerUser.ts

@@ -0,0 +1,100 @@
+import { MultiRollupApiClients } from '@imtbl/generated-clients';
+import { Flow } from '@imtbl/metrics';
+import type { PublicClient } from 'viem';
+import { getEip155ChainId } from '../../zkEvm/walletHelpers';
+import { Auth } from '@imtbl/auth';
+import { JsonRpcError, RpcErrorCode } from '../../zkEvm/JsonRpcError';
+import { SequenceSigner } from '../signer';
+
+export type RegisterUserInput = {
+  auth: Auth;
+  ethSigner: SequenceSigner;
+  multiRollupApiClients: MultiRollupApiClients;
+  accessToken: string;
+  rpcProvider: PublicClient;
+  flow: Flow;
+};
+
+const MESSAGE_TO_SIGN = 'Only sign this message from Immutable Passport';
+
+/**
+ * Format the signature for the registration API.
+ * Converts v value from 27/28 format to 0/1 recovery param format.
+ */
+function formatSignature(signature: string): string {
+  const sig = signature.startsWith('0x') ? signature.slice(2) : signature;
+  const r = sig.substring(0, 64);
+  const s = sig.substring(64, 128);
+  const v = sig.substring(128, 130);
+
+  const vNum = parseInt(v, 16);
+  const recoveryParam = vNum >= 27 ? vNum - 27 : vNum;
+  const vHex = recoveryParam.toString(16).padStart(2, '0');
+
+  return `0x${r}${s}${vHex}`;
+}
+
+/**
+ * Register a user for a non-zkEVM chain (e.g., Arbitrum).
+ * Creates a counterfactual address for the user on the specified chain.
+ */
+export async function registerUser({
+  auth,
+  ethSigner,
+  multiRollupApiClients,
+  accessToken,
+  rpcProvider,
+  flow,
+}: RegisterUserInput): Promise<string> {
+  // Parallelize the operations that can happen concurrently
+  const getAddressPromise = ethSigner.getAddress();
+  getAddressPromise.then(() => flow.addEvent('endGetAddress'));
+
+  const signMessagePromise = ethSigner.signMessage(MESSAGE_TO_SIGN).then(formatSignature);
+  signMessagePromise.then(() => flow.addEvent('endSignRaw'));
+
+  const detectNetworkPromise = rpcProvider.getChainId();
+  detectNetworkPromise.then(() => flow.addEvent('endDetectNetwork'));
+
+  const listChainsPromise = multiRollupApiClients.chainsApi.listChains();
+  listChainsPromise.then(() => flow.addEvent('endListChains'));
+
+  const [ethereumAddress, ethereumSignature, chainId, chainListResponse] = await Promise.all([
+    getAddressPromise,
+    signMessagePromise,
+    detectNetworkPromise,
+    listChainsPromise,
+  ]);
+
+  const eipChainId = getEip155ChainId(Number(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 for chain id ${chainId}`,
+    );
+  }
+
+  try {
+    const registrationResponse = await multiRollupApiClients.passportApi.createCounterfactualAddressV2({
+      chainName,
+      createCounterfactualAddressRequest: {
+        ethereum_address: ethereumAddress,
+        ethereum_signature: ethereumSignature,
+      },
+    }, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    flow.addEvent('endCreateCounterfactualAddress');
+
+    auth.forceUserRefreshInBackground();
+
+    return registrationResponse.data.counterfactual_address;
+  } catch (error) {
+    flow.addEvent('errorRegisteringUser');
+    throw new JsonRpcError(
+      RpcErrorCode.INTERNAL_ERROR,
+      `Failed to create counterfactual address: ${error}`,
+    );
+  }
+}

package/src/types.ts

@@ -4,6 +4,11 @@ import {
 } from '@imtbl/auth';
 import { JsonRpcError } from './zkEvm/JsonRpcError';
 
+export enum EvmChain {
+  ZKEVM = 'zkevm',
+  ARBITRUM_ONE = 'arbitrum_one',
+}
+
 /**
  * A viem-compatible signer interface for wallet operations.
  * This replaces ethers' AbstractSigner/Signer.
@@ -41,8 +46,16 @@ export interface PassportEventMap extends AuthEventMap {
   [WalletEvents.ACCOUNTS_REQUESTED]: [AccountsRequestedEvent];
 }
 
-// Re-export zkEVM Provider type for public API
-export type { Provider } from './zkEvm/types';
+/**
+ * EIP-1193 Provider Interface
+ * Standard Ethereum provider interface for all chain 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;
@@ -191,6 +204,17 @@ export interface ChainConfig {
    * Defaults to 'https://tee.express.magiclabs.com'
    */
   magicTeeBasePath?: string;
+
+  /** Preferred token symbol for relayer fees (default: 'IMX') */
+  feeTokenSymbol?: string;
+
+  /** Sequence RPC node URL TODO: check if this can be removed and only use rpcUrl */
+  nodeUrl?: string;
+
+  /**
+   * Sequence Identity Instrument endpoint (for non-zkEVM chains in prod/sandbox)
+   */
+  sequenceIdentityInstrumentEndpoint?: string;
 }
 
 /**

package/src/zkEvm/types.ts

@@ -1,4 +1,5 @@
 import { JsonRpcError } from './JsonRpcError';
+import type { Provider as ProviderType } from '../types';
 
 export enum RelayerTransactionStatus {
   PENDING = 'PENDING',
@@ -91,16 +92,9 @@ export interface JsonRpcResponsePayload {
   id?: string | number;
 }
 
-/**
- * EIP-1193 Provider Interface
- * Standard Ethereum provider interface
- */
-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 type { Provider } from '../types';
+
+type Provider = ProviderType;
 
 export enum ProviderEvent {
   ACCOUNTS_CHANGED = 'accountsChanged',