@multiplatform.one/web3 7.31.1 → 7.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/web3",
-  "version": "7.31.1",
+  "version": "7.32.0",
   "description": "Web3 wallet integration for multiplatform.one ecosystem with ConnectKit and wagmi",
   "keywords": [
     "connectkit",
@@ -114,10 +114,10 @@
     "@aave/account": "^0.2.0",
     "@coinbase/wallet-sdk": "^4.3.6",
     "@metamask/connect-evm": "^2.1.1",
-    "@multiplatform.one/connectkit": "7.31.1",
-    "@multiplatform.one/gpg": "7.31.1",
-    "@multiplatform.one/platform": "7.31.1",
-    "@multiplatform.one/theme": "7.31.1",
+    "@multiplatform.one/connectkit": "7.32.0",
+    "@multiplatform.one/gpg": "7.32.0",
+    "@multiplatform.one/platform": "7.32.0",
+    "@multiplatform.one/theme": "7.32.0",
     "@noble/curves": "^1.9.7",
     "@solana/kit": "^8.3.0",
     "@solana/wallet-adapter-base": "^0.9.27",
@@ -139,7 +139,7 @@
     "wagmi": "^3.7.1"
   },
   "devDependencies": {
-    "@multiplatform.one/config": "7.31.1",
+    "@multiplatform.one/config": "7.32.0",
     "@tamagui/build": "2.7.6",
     "@tanstack/react-query": "^5.100.7",
     "@testing-library/jest-dom": "^6.9.1",

package/src/clients/evm.ts

@@ -2,6 +2,7 @@ import {
   createPublicClient,
   createWalletClient,
   custom,
+  encodeFunctionData,
   erc20Abi,
   http,
   type Abi,
@@ -21,6 +22,12 @@ import {
   type WalletClient,
   type WriteContractParameters,
 } from "viem";
+import {
+  prepareEvmSend,
+  type CurrentWalletState,
+  type Eip1193Request,
+  type PreparedEvmSend,
+} from "./preparedSend";
 import type { ChainClient, ClientCapability } from "./types";
 
 /** A viem wallet client with its account and chain hoisted, the shape wagmi's getWalletClient returns. */
@@ -289,6 +296,32 @@ export interface Erc20Actions {
   }): Promise<Hash | null>;
 }
 
+/** What `prepareTransaction` takes: the transaction, and optionally its gas, nonce and lifetime. */
+export interface EvmPrepareTransactionParameters {
+  to: Address;
+  data?: Hex;
+  value?: bigint;
+  gas?: bigint;
+  nonce?: number;
+  /** How long the prepared send stays good. 60 s by default. */
+  maxAgeMs?: number;
+}
+
+/** What `prepareWriteContract` takes: viem's contract call, simulated before the tap. */
+export interface EvmPrepareWriteContractParameters<
+  abi extends Abi | readonly unknown[] = Abi,
+  functionName extends WritableFunctionName<abi> = WritableFunctionName<abi>,
+> {
+  address: Address;
+  abi: abi;
+  functionName: functionName;
+  args?: ContractFunctionArgs<abi, "nonpayable" | "payable", functionName>;
+  value?: bigint;
+  gas?: bigint;
+  nonce?: number;
+  maxAgeMs?: number;
+}
+
 export interface EvmClient extends ChainClient<"evm"> {
   readonly address: Address;
   readonly chainId: number;
@@ -326,6 +359,19 @@ export interface EvmClient extends ChainClient<"evm"> {
   confirmTransaction(hash: Hash, options?: EvmWaitOptions): Promise<TransactionReceipt>;
   /** The chain explorer's page for `hash`, when the chain names an explorer. */
   explorerTxUrl(hash: Hash): string | undefined;
+  /**
+   * Does the network work for a send ahead of the user's tap (nonce, gas,
+   * fees), so the tap's handler calls `send()` with nothing awaited and the
+   * wallet app opens without "Continue to MetaMask?". See PreparedEvmSend.
+   */
+  prepareTransaction(parameters: EvmPrepareTransactionParameters): Promise<PreparedEvmSend>;
+  /** prepareTransaction for a contract call: simulates it, then encodes it. */
+  prepareWriteContract<
+    const abi extends Abi | readonly unknown[],
+    functionName extends WritableFunctionName<abi>,
+  >(
+    parameters: EvmPrepareWriteContractParameters<abi, functionName>,
+  ): Promise<PreparedEvmSend>;
   readonly erc20: Erc20Actions;
 }
 
@@ -344,6 +390,8 @@ export type EvmClientConfig = (
   /** Reads go here. Defaults to an http client on `rpcUrl`, else the chain's default RPC. */
   publicClient?: PublicClient;
   rpcUrl?: string;
+  /** The wallet's account and chain now, which a prepared send checks before it sends. */
+  current?: CurrentWalletState;
 };
 
 /**
@@ -415,6 +463,42 @@ export function evmClient(config: EvmClientConfig): EvmClient {
     return walletClient.writeContract({ ...request, account, chain } as EvmWriteContractParameters);
   };
 
+  const prepareTransaction = ({ maxAgeMs, ...transaction }: EvmPrepareTransactionParameters) =>
+    prepareEvmSend({
+      publicClient,
+      request: walletClient.request as unknown as Eip1193Request,
+      from: account.address,
+      chainId: chain.id,
+      ...transaction,
+      ...(config.current ? { current: config.current } : {}),
+      ...(maxAgeMs !== undefined ? { maxAgeMs } : {}),
+    });
+
+  const prepareWriteContract = async ({
+    address,
+    abi,
+    functionName,
+    args,
+    value,
+    ...rest
+  }: EvmPrepareWriteContractParameters) => {
+    await publicClient.simulateContract({
+      account,
+      address,
+      abi,
+      functionName,
+      args,
+      ...(value !== undefined ? { value } : {}),
+    } as never);
+    const data = encodeFunctionData({ abi, functionName, args } as never);
+    return prepareTransaction({
+      to: address,
+      data,
+      ...(value !== undefined ? { value } : {}),
+      ...rest,
+    });
+  };
+
   const explorer = chain.blockExplorers?.default.url.replace(/\/+$/, "");
   const explorerTxUrl = (hash: Hash) => (explorer ? `${explorer}/tx/${hash}` : undefined);
 
@@ -723,5 +807,7 @@ export function evmClient(config: EvmClientConfig): EvmClient {
     confirmTransaction: (hash, options) => confirmTransaction(hash, options),
     explorerTxUrl,
     erc20,
+    prepareTransaction,
+    prepareWriteContract: prepareWriteContract as EvmClient["prepareWriteContract"],
   };
 }

package/src/clients/hooks.spec.tsx

@@ -21,6 +21,7 @@ vi.mock("wagmi", () => ({
   useAccount: mockUseAccount,
   useWalletClient: mockUseWalletClient,
   usePublicClient: mockUsePublicClient,
+  useConfig: () => ({}),
 }));
 
 import { useBitcoinClient, useEvmClient, useSuiClient } from "./hooks";

package/src/clients/hooks.ts

@@ -1,5 +1,6 @@
 import { useMemo } from "react";
 import { useAccount, useChainId, useConfig, usePublicClient, useWalletClient } from "wagmi";
+import { getAccount } from "wagmi/actions";
 import { isSyntheticChainId } from "../connectkit/connectors/syntheticChains";
 import { useOptionalConnection } from "../core/react";
 import { bitcoinClient, type BitcoinClient } from "./bitcoin";
@@ -18,6 +19,7 @@ import type { PublicClient } from "viem";
  */
 export function useEvmClient(parameters: { chainId?: number } = {}): EvmClient | undefined {
   const connection = useOptionalConnection();
+  const config = useConfig();
   const fromStore = connection !== null && parameters.chainId === undefined;
   const { connector, chainId: connectedChainId } = useAccount();
   const evm =
@@ -40,9 +42,10 @@ export function useEvmClient(parameters: { chainId?: number } = {}): EvmClient |
       ? evmClient({
           walletClient: walletClient as unknown as EvmWalletClient,
           publicClient: publicClient as PublicClient,
+          current: () => getAccount(config),
         })
       : undefined;
-  }, [fromStore, connection, evm, walletClient, publicClient]);
+  }, [fromStore, connection, evm, walletClient, publicClient, config]);
 }
 
 /**

package/src/clients/index.ts

@@ -21,6 +21,8 @@ export {
   type Erc20Actions,
   type EvmClient,
   type EvmClientConfig,
+  type EvmPrepareTransactionParameters,
+  type EvmPrepareWriteContractParameters,
   type EvmReplacementReason,
   type EvmSendTransactionParameters,
   type EvmWaitOptions,
@@ -28,6 +30,16 @@ export {
   type EvmWriteContractParameters,
   type TxErrorKind,
 } from "./evm";
+export {
+  DEFAULT_PREPARED_SEND_MAX_AGE_MS,
+  prepareEvmSend,
+  PreparedSendStaleError,
+  type CurrentWalletState,
+  type Eip1193Request,
+  type PrepareEvmSendParameters,
+  type PreparedEvmSend,
+  type PreparedSendStaleReason,
+} from "./preparedSend";
 export {
   evmReadClient,
   evmReadClients,

package/src/clients/preparedSend.spec.ts

@@ -0,0 +1,214 @@
+import {
+  createPublicClient,
+  createWalletClient,
+  custom,
+  encodeFunctionData,
+  erc20Abi,
+  type Address,
+  type PublicClient,
+} from "viem";
+import { baseSepolia } from "viem/chains";
+import { describe, expect, it, vi } from "vitest";
+
+import { evmClient } from "./evm";
+import { prepareEvmSend, PreparedSendStaleError } from "./preparedSend";
+
+const from = "0x12a5CF52c94c164ec2ba7dED0741c80bD5842f95" as Address;
+const other = "0x00000000000000000000000000000000000000bb" as Address;
+const token = "0xc6fe3521644e0f5439fe345f64d372cd6ed37491" as Address;
+const treasury = "0x00000000000000000000000000000000000000cc" as Address;
+const hash = `0x${"ab".repeat(32)}` as const;
+
+/** An RPC node: what prepareTransactionRequest and simulateContract ask for. */
+function rpc() {
+  const calls: string[] = [];
+  const request = async ({ method }: { method: string }) => {
+    calls.push(method);
+    switch (method) {
+      case "eth_chainId":
+        return "0x14a34";
+      case "eth_getTransactionCount":
+        return "0x7";
+      case "eth_estimateGas":
+        return "0xc350";
+      case "eth_maxPriorityFeePerGas":
+        return "0x3b9aca00";
+      case "eth_getBlockByNumber":
+        return { number: "0x10", baseFeePerGas: "0x3b9aca00", timestamp: "0x1", transactions: [] };
+      case "eth_call":
+        return `0x${"0".repeat(63)}1`;
+      default:
+        throw new Error(`unexpected RPC ${method}`);
+    }
+  };
+  const publicClient = createPublicClient({
+    chain: baseSepolia,
+    transport: custom({ request }),
+  }) as PublicClient;
+  return { publicClient, calls };
+}
+
+/** A wallet: records each request and whether it arrived before a microtask ran. */
+function wallet() {
+  const seen: { method: string; params?: unknown; beforeMicrotask: boolean }[] = [];
+  let microtaskRan = false;
+  const request = vi.fn(async ({ method, params }: { method: string; params?: unknown }) => {
+    seen.push({ method, params, beforeMicrotask: !microtaskRan });
+    if (method === "eth_sendTransaction") return hash;
+    if (method === "eth_chainId") return "0x14a34";
+    if (method === "eth_accounts") return [from];
+    throw new Error(`unexpected wallet call ${method}`);
+  });
+  const arm = () => {
+    microtaskRan = false;
+    queueMicrotask(() => {
+      microtaskRan = true;
+    });
+  };
+  return { request, seen, arm };
+}
+
+describe("prepareEvmSend", () => {
+  it("does the network work up front and hands eth_sendTransaction to the wallet before send() returns", async () => {
+    const { publicClient, calls } = rpc();
+    const w = wallet();
+    const prepared = await prepareEvmSend({
+      publicClient,
+      request: w.request,
+      from,
+      chainId: baseSepolia.id,
+      to: treasury,
+      value: 10n ** 15n,
+    });
+    expect(calls).toEqual(expect.arrayContaining(["eth_getTransactionCount", "eth_estimateGas"]));
+    expect(w.request).not.toHaveBeenCalled();
+    calls.length = 0;
+
+    w.arm();
+    const sent = prepared.send();
+
+    expect(w.seen).toHaveLength(1);
+    expect(w.seen[0]).toMatchObject({ method: "eth_sendTransaction", beforeMicrotask: true });
+    expect(calls).toEqual([]);
+    await expect(sent).resolves.toBe(hash);
+    expect(prepared.request).toMatchObject({
+      from,
+      to: treasury,
+      value: "0x38d7ea4c68000",
+      nonce: "0x7",
+      gas: "0xc350",
+      chainId: "0x14a34",
+    });
+    expect(prepared.request.maxFeePerGas).toBeDefined();
+  });
+
+  it("refuses, sending nothing, when the wallet moved to another account", async () => {
+    const { publicClient } = rpc();
+    const w = wallet();
+    const prepared = await prepareEvmSend({
+      publicClient,
+      request: w.request,
+      from,
+      chainId: baseSepolia.id,
+      to: treasury,
+      value: 1n,
+      current: () => ({ address: other, chainId: baseSepolia.id }),
+    });
+
+    const error = await prepared.send().catch((e) => e);
+
+    expect(error).toBeInstanceOf(PreparedSendStaleError);
+    expect(error.reason).toBe("account");
+    expect(w.request).not.toHaveBeenCalled();
+  });
+
+  it("refuses, sending nothing, when the wallet moved to another chain", async () => {
+    const { publicClient } = rpc();
+    const w = wallet();
+    const prepared = await prepareEvmSend({
+      publicClient,
+      request: w.request,
+      from,
+      chainId: baseSepolia.id,
+      to: treasury,
+      value: 1n,
+      current: () => ({ address: from.toLowerCase(), chainId: 1 }),
+    });
+
+    const error = await prepared.send().catch((e) => e);
+
+    expect(error.reason).toBe("chain");
+    expect(w.request).not.toHaveBeenCalled();
+  });
+
+  it("refuses, sending nothing, once the gas and nonce are older than maxAgeMs", async () => {
+    const { publicClient } = rpc();
+    const w = wallet();
+    const prepared = await prepareEvmSend({
+      publicClient,
+      request: w.request,
+      from,
+      chainId: baseSepolia.id,
+      to: treasury,
+      value: 1n,
+      maxAgeMs: 1_000,
+    });
+    vi.useFakeTimers({ now: prepared.preparedAt + 1_001 });
+    try {
+      const error = await prepared.send().catch((e) => e);
+
+      expect(error.reason).toBe("expired");
+      expect(w.request).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("evmClient prepared sends", () => {
+  function client(current?: () => { address?: string; chainId?: number }) {
+    const { publicClient, calls } = rpc();
+    const w = wallet();
+    const walletClient = createWalletClient({
+      account: from,
+      chain: baseSepolia,
+      transport: custom({ request: w.request }),
+    });
+    return {
+      evm: evmClient({ walletClient, publicClient, ...(current ? { current } : {}) }),
+      w,
+      calls,
+    };
+  }
+
+  it("sends a prepared ERC-20 transfer through the viem wallet client with no await before the wallet", async () => {
+    const { evm, w, calls } = client(() => ({ address: from, chainId: baseSepolia.id }));
+    const prepared = await evm.prepareWriteContract({
+      address: token,
+      abi: erc20Abi,
+      functionName: "transfer",
+      args: [treasury, 5n],
+    });
+    expect(calls).toContain("eth_call");
+    expect(w.request).not.toHaveBeenCalled();
+
+    w.arm();
+    const sent = prepared.send();
+
+    expect(w.seen.map((call) => call.method)).toEqual(["eth_sendTransaction"]);
+    expect(w.seen[0]!.beforeMicrotask).toBe(true);
+    expect((w.seen[0]!.params as [{ data: string; to: string }])[0]).toMatchObject({
+      to: token,
+      data: encodeFunctionData({ abi: erc20Abi, functionName: "transfer", args: [treasury, 5n] }),
+    });
+    await expect(sent).resolves.toBe(hash);
+  });
+
+  it("checks the wallet's current state it was built with", async () => {
+    const { evm, w } = client(() => ({ address: from, chainId: 97 }));
+    const prepared = await evm.prepareTransaction({ to: treasury, value: 1n });
+
+    await expect(prepared.send()).rejects.toBeInstanceOf(PreparedSendStaleError);
+    expect(w.request).not.toHaveBeenCalled();
+  });
+});

package/src/clients/preparedSend.ts

@@ -0,0 +1,136 @@
+import {
+  formatTransactionRequest,
+  numberToHex,
+  type Address,
+  type Hash,
+  type Hex,
+  type PublicClient,
+  type RpcTransactionRequest,
+} from "viem";
+
+/**
+ * A phone wallet reached by deeplink (MetaMask Connect, Phantom) opens only
+ * while the tap that asked for it still has its user activation. Chrome on
+ * Android asks "Continue to MetaMask?" when the request comes after an await,
+ * and iOS always asks. So everything that needs the network (nonce, gas, fees,
+ * a simulation) happens before the tap, and the tap's handler calls `send()`,
+ * which hands eth_sendTransaction to the wallet before it returns.
+ */
+
+/** The wallet's EIP-1193 `request`: an injected provider's, MetaMask Connect's, Phantom's. */
+export type Eip1193Request = (args: { method: string; params?: unknown }) => Promise<unknown>;
+
+/** What a prepared send carries, the transaction to send and the state it was built for. */
+export interface PreparedEvmSend {
+  /** The eth_sendTransaction parameter, hex encoded. */
+  readonly request: RpcTransactionRequest & { from: Address; chainId: Hex };
+  readonly from: Address;
+  readonly chainId: number;
+  /** `Date.now()` when it was prepared. */
+  readonly preparedAt: number;
+  /**
+   * Sends it. Call it synchronously from the tap's handler with nothing awaited
+   * before it: the wallet gets eth_sendTransaction before `send()` returns.
+   * Rejects with PreparedSendStaleError, sending nothing, when the wallet's
+   * account or chain moved since it was prepared or it is older than `maxAgeMs`.
+   */
+  send(): Promise<Hash>;
+}
+
+export type PreparedSendStaleReason = "account" | "chain" | "expired";
+
+/** A prepared send refused because the wallet or the clock moved on. Nothing was sent. */
+export class PreparedSendStaleError extends Error {
+  readonly reason: PreparedSendStaleReason;
+  constructor(reason: PreparedSendStaleReason, detail: string) {
+    super(`Prepared transaction is stale (${reason}): ${detail}. Prepare it again.`);
+    this.name = "PreparedSendStaleError";
+    this.reason = reason;
+  }
+}
+
+/** The wallet's account and chain right now, read without awaiting (wagmi's `getAccount`). */
+export type CurrentWalletState = () => { address?: string; chainId?: number } | undefined;
+
+export interface PrepareEvmSendParameters {
+  /** Reads: nonce, gas and fees come from here, never from the wallet. */
+  publicClient: PublicClient;
+  /** The wallet that signs and sends. */
+  request: Eip1193Request;
+  from: Address;
+  chainId: number;
+  to: Address;
+  data?: Hex;
+  value?: bigint;
+  /** Skip the estimate. */
+  gas?: bigint;
+  /** Skip the lookup. */
+  nonce?: number;
+  /** Checked by `send()` before it sends. */
+  current?: CurrentWalletState;
+  /** How long the gas, fees and nonce stay good. 60 s by default. */
+  maxAgeMs?: number;
+}
+
+export const DEFAULT_PREPARED_SEND_MAX_AGE_MS = 60_000;
+
+const same = (a?: string, b?: string) => !!a && !!b && a.toLowerCase() === b.toLowerCase();
+
+/**
+ * Prepares a transaction for any EIP-1193 wallet so the send fires inside the
+ * user's tap. Works for a native-coin transfer (`value`) and for a contract
+ * call (`data`, from viem's `encodeFunctionData`).
+ */
+export async function prepareEvmSend(
+  parameters: PrepareEvmSendParameters,
+): Promise<PreparedEvmSend> {
+  const { publicClient, request, from, chainId, current } = parameters;
+  const maxAgeMs = parameters.maxAgeMs ?? DEFAULT_PREPARED_SEND_MAX_AGE_MS;
+  const prepared = await publicClient.prepareTransactionRequest({
+    account: from,
+    chain: publicClient.chain,
+    to: parameters.to,
+    ...(parameters.data ? { data: parameters.data } : {}),
+    ...(parameters.value !== undefined ? { value: parameters.value } : {}),
+    ...(parameters.gas !== undefined ? { gas: parameters.gas } : {}),
+    ...(parameters.nonce !== undefined ? { nonce: parameters.nonce } : {}),
+    parameters: ["fees", "gas", "nonce", "type"],
+  } as never);
+  const { account: _account, chain: _chain, ...transaction } = prepared as Record<string, unknown>;
+  const rpc = {
+    ...formatTransactionRequest(transaction as never),
+    from,
+    chainId: numberToHex(chainId),
+  } as PreparedEvmSend["request"];
+  const preparedAt = Date.now();
+
+  return Object.freeze({
+    request: Object.freeze(rpc),
+    from,
+    chainId,
+    preparedAt,
+    send(): Promise<Hash> {
+      const age = Date.now() - preparedAt;
+      if (age > maxAgeMs)
+        return Promise.reject(
+          new PreparedSendStaleError("expired", `prepared ${age} ms ago, limit ${maxAgeMs} ms`),
+        );
+      const now = current?.();
+      if (now?.address !== undefined && !same(now.address, from))
+        return Promise.reject(
+          new PreparedSendStaleError(
+            "account",
+            `prepared for ${from}, wallet is on ${now.address}`,
+          ),
+        );
+      if (now?.chainId !== undefined && now.chainId !== chainId)
+        return Promise.reject(
+          new PreparedSendStaleError(
+            "chain",
+            `prepared for ${chainId}, wallet is on ${now.chainId}`,
+          ),
+        );
+      return request({ method: "eth_sendTransaction", params: [rpc] }) as Promise<Hash>;
+    },
+  });
+}