web3-tools-mcp 1.4.0 → 1.6.0

package/src/preview.ts

@@ -9,8 +9,9 @@ import {
   toFunctionSelector
 } from 'viem'
 import { simulateBlocks } from 'viem/actions'
-import { whatsabi } from '@shazow/whatsabi'
 import { getClientManager } from './client.js'
+import { addressLabel, loadAbi, tokenMeta, UNLIMITED_THRESHOLD } from './chain-meta.js'
+import { lookupContract, protocolLabel, resolveClearSigning } from './clear-signing.js'
 import type { ChainName } from './types.js'
 
 export interface PreviewField {
@@ -46,6 +47,9 @@ export interface TxPreview {
     functionName: string
     signature: string
     fields: PreviewField[]
+    /** From the ERC-7730 registry: what this call means, and whose contract it is. */
+    intent?: string
+    protocol?: string
     /** 'verified' = ABI from Sourcify/Etherscan, 'guessed' = selector lookup on bytecode */
     source: 'verified' | 'guessed'
     proxy?: string
@@ -64,14 +68,7 @@ export interface RawTx {
   value?: string
 }
 
-const ERC20_META_ABI = [
-  parseAbiItem('function decimals() view returns (uint8)'),
-  parseAbiItem('function symbol() view returns (string)')
-]
-
 const TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
-const MAX_UINT256 = (1n << 256n) - 1n
-const UNLIMITED_THRESHOLD = MAX_UINT256 / 2n
 
 // Selectors whose amount argument is denominated in the token at tx.to.
 const ERC20_AMOUNT_ARGS: Record<string, { arg: string; approval?: boolean }> = {
@@ -80,89 +77,6 @@ const ERC20_AMOUNT_ARGS: Record<string, { arg: string; approval?: boolean }> = {
   [toFunctionSelector('function transferFrom(address,address,uint256)')]: { arg: 'amount' }
 }
 
-const abiCache = new Map<string, { abi: Abi; source: 'verified' | 'guessed'; proxy?: string; name?: string }>()
-const labelCache = new Map<string, string | undefined>()
-const metaCache = new Map<string, { symbol?: string; decimals?: number }>()
-
-async function loadAbi(chain: ChainName, address: string) {
-  const key = `${chain}:${address.toLowerCase()}`
-  const cached = abiCache.get(key)
-  if (cached) return cached
-
-  const clientManager = getClientManager()
-  const client = clientManager.getClient(chain)
-  const etherscanApiKey = clientManager.getConfig().etherscanApiKey
-
-  const loaders: whatsabi.loaders.ABILoader[] = [new whatsabi.loaders.SourcifyABILoader({ chainId: clientManager.getChainId(chain) })]
-  if (etherscanApiKey) {
-    loaders.push(new whatsabi.loaders.EtherscanV2ABILoader({ apiKey: etherscanApiKey, chainId: clientManager.getChainId(chain) }))
-  }
-
-  const result = await whatsabi.autoload(address as Address, {
-    provider: client,
-    abiLoader: new whatsabi.loaders.MultiABILoader(loaders),
-    signatureLookup: new whatsabi.loaders.OpenChainSignatureLookup(),
-    followProxies: true
-  })
-
-  // Bytecode-guessed ABIs carry no argument names; verified ones do.
-  const source = result.abi.some((item) => item.type === 'function' && item.inputs?.some((i) => i.name)) ? 'verified' : 'guessed'
-  const loaded = {
-    abi: result.abi as Abi,
-    source: source as 'verified' | 'guessed',
-    proxy: result.address !== address ? result.address : undefined,
-    name: result.contractResult?.name ?? undefined
-  }
-  abiCache.set(key, loaded)
-  return loaded
-}
-
-async function tokenMeta(chain: ChainName, token: string) {
-  const key = `${chain}:${token.toLowerCase()}`
-  const cached = metaCache.get(key)
-  if (cached) return cached
-
-  const client = getClientManager().getClient(chain)
-  const [decimals, symbol] = await client.multicall({
-    contracts: [
-      { address: token as Address, abi: ERC20_META_ABI, functionName: 'decimals' },
-      { address: token as Address, abi: ERC20_META_ABI, functionName: 'symbol' }
-    ],
-    ...(chain === 'localhost' && { deployless: true })
-  })
-
-  const meta = {
-    decimals: decimals.status === 'success' ? Number(decimals.result) : undefined,
-    symbol: symbol.status === 'success' ? (symbol.result as string) : undefined
-  }
-  metaCache.set(key, meta)
-  return meta
-}
-
-/**
- * Human label for an address: token symbol first (more recognisable than the contract
- * name — "USDC" beats "FiatTokenProxy"), then the verified contract name. EOAs get none,
- * and the bytecode check keeps us from asking explorers about plain wallets.
- */
-async function addressLabel(chain: ChainName, address: string): Promise<string | undefined> {
-  const key = `${chain}:${address.toLowerCase()}`
-  if (labelCache.has(key)) return labelCache.get(key)
-
-  let label: string | undefined
-  try {
-    const code = await getClientManager().getClient(chain).getBytecode({ address: address as Address })
-    if (code && code !== '0x') {
-      label = (await tokenMeta(chain, address).catch(() => ({ symbol: undefined }))).symbol
-      if (!label) label = (await loadAbi(chain, address)).name
-    }
-  } catch {
-    // Unknown address — show it bare rather than failing the preview.
-  }
-
-  labelCache.set(key, label)
-  return label
-}
-
 function stringify(value: unknown): string {
   if (typeof value === 'bigint') return value.toString()
   if (Array.isArray(value)) return `[${value.map(stringify).join(', ')}]`
@@ -222,6 +136,34 @@ async function decodeCalldata(chain: ChainName, tx: RawTx): Promise<TxPreview['d
     ? `${functionName}(${inputs.map((i) => `${i.type}${i.name ? ` ${i.name}` : ''}`).join(', ')})`
     : functionName
 
+  // Map positional args to their parameter names so registry field paths resolve.
+  const named: Record<string, unknown> = {}
+  inputs.forEach((input, i) => {
+    if (input.name) named[input.name] = (args ?? [])[i]
+  })
+
+  // A registry descriptor says what the call means and how the protocol wants each field
+  // labelled, which beats raw ABI argument names. Fall back to those when it has none.
+  const clearSigning = await resolveClearSigning(chain, tx, named).catch(() => null)
+  if (clearSigning) {
+    return {
+      functionName,
+      signature,
+      source,
+      proxy,
+      intent: clearSigning.intent,
+      protocol: clearSigning.protocol,
+      fields: clearSigning.fields.map((field) => ({
+        name: field.label,
+        type: field.format,
+        value: field.value,
+        ...(field.address && { address: field.address }),
+        ...(field.name && { label: field.name }),
+        ...(field.value.startsWith('Unlimited') && { warning: 'Unlimited spending approval' })
+      }))
+    }
+  }
+
   return { functionName, signature, fields, source, proxy }
 }
 
@@ -302,9 +244,22 @@ export async function buildTxPreview(chain: ChainName, tx: RawTx, from?: string)
   const value = tx.value ? BigInt(tx.value).toString() : undefined
 
   const [decoded, simulation, toLabel] = await Promise.all([
-    decodeCalldata(chain, tx).catch(() => undefined),
-    from ? simulate(chain, tx, from as Address).catch(() => undefined) : Promise.resolve(undefined),
-    addressLabel(chain, tx.to).catch(() => undefined)
+    // A preview that cannot be built must not block the transaction, but swallowing the
+    // reason makes "no details shown" impossible to diagnose.
+    decodeCalldata(chain, tx).catch((error) => {
+      console.error('[Preview] Could not decode calldata:', error instanceof Error ? error.message : error)
+      return undefined
+    }),
+    from
+      ? simulate(chain, tx, from as Address).catch((error) => {
+          console.error('[Preview] Could not simulate:', error instanceof Error ? error.message : error)
+          return undefined
+        })
+      : Promise.resolve(undefined),
+    // The registry's protocol name beats anything on-chain: "Aave", not a proxy's class name.
+    Promise.resolve(lookupContract(chain, tx.to))
+      .then((entry) => (entry ? protocolLabel(entry.protocol) : addressLabel(chain, tx.to)))
+      .catch(() => undefined)
   ])
 
   return {

package/src/tools/transactions.ts

@@ -1,11 +1,18 @@
 import { z } from 'zod'
 import { getWalletClient } from '../wallet-client.js'
 import { getClientManager, SUPPORTED_CHAINS } from '../client.js'
-import { encodeFunctionData, isAddress, parseAbiItem, parseUnits, type AbiFunction, type Address } from 'viem'
+import { encodeFunctionData, isAddress, parseAbiItem, parseUnits, toHex, type AbiFunction, type Address } from 'viem'
 import { randomBytes } from 'node:crypto'
 import type { ChainName } from '../types.js'
-import { buildTxPreview, type RawTx } from '../preview.js'
+import { buildTxPreview, type RawTx, type TxPreview } from '../preview.js'
+import { getPhoneSigner } from '../walletconnect.js'
 import { createTool, formatResponse } from '../utils.js'
+import qrcode from 'qrcode-terminal'
+
+/** Render a pairing URI as an ASCII QR, so it can be scanned straight from the chat. */
+function qrFor(uri: string): Promise<string> {
+  return new Promise((resolve) => qrcode.generate(uri, { small: true }, resolve))
+}
 
 function generateRequestId(): string {
   return randomBytes(16).toString('hex')
@@ -21,10 +28,28 @@ function explorerTxUrl(chain: ChainName, txHash: unknown): string {
 }
 
 /**
- * Send a transaction for signing, with a decoded + simulated preview attached so the
- * wallet page can show what it actually does instead of raw calldata.
+ * Send a transaction for signing.
+ *
+ * A paired phone wins over the browser page: it was set up deliberately and is the only
+ * option when there is no browser to open. Either way the transaction is decoded and
+ * simulated first — the phone wallet shows its own summary, so the preview is returned to
+ * the caller as well, where it can be read before the prompt is approved.
  */
 async function requestSignature(chain: ChainName, tx: RawTx & { data?: string }) {
+  const phone = getPhoneSigner()
+
+  if (await phone?.isPaired()) {
+    const session = await phone!.session()
+    const from = session?.accounts[0]
+    const preview = await buildTxPreview(chain, tx, from)
+
+    const txHash = await phone!.request(chain, 'eth_sendTransaction', [
+      { from, to: tx.to, value: tx.value ?? '0x0', ...(tx.data && { data: tx.data }) }
+    ])
+
+    return { txHash, preview, signedWith: 'phone' as const }
+  }
+
   const wallet = getWalletClient()
   await wallet.waitForSigner()
 
@@ -38,14 +63,42 @@ async function requestSignature(chain: ChainName, tx: RawTx & { data?: string })
       data: { to: tx.to, value: tx.value ?? '0x0', ...(tx.data && { data: tx.data }) },
       preview
     }),
-    preview
+    preview,
+    signedWith: 'browser' as const
+  }
+}
+
+/** What the caller should see about a transaction before it is approved. */
+function previewSummary(preview: TxPreview) {
+  return {
+    action: preview.decoded?.intent ?? preview.decoded?.functionName,
+    protocol: preview.decoded?.protocol ?? preview.toLabel,
+    details: preview.decoded?.fields.map((f) => `${f.name}: ${f.value}${f.warning ? ` (${f.warning})` : ''}`),
+    simulation: preview.simulation
   }
 }
 
+/**
+ * WalletConnect rejects with a plain `{ code, message }` rather than an Error, which
+ * String() renders as "[object Object]" — the reason a wallet gave for refusing is the
+ * whole point of the message, so dig it out.
+ */
+function describeError(error: unknown): string {
+  if (error instanceof Error) return error.message
+  if (error && typeof error === 'object') {
+    const { message, code, reason } = error as { message?: string; code?: number; reason?: string }
+    const text = message ?? reason
+    if (text) return code === undefined ? text : `${text} (code ${code})`
+    return JSON.stringify(error)
+  }
+  return String(error)
+}
+
 function failure(error: unknown, message: string) {
+  console.error('[Transaction]', message, '—', describeError(error))
   return formatResponse({
     success: false,
-    error: error instanceof Error ? error.message : String(error),
+    error: describeError(error),
     message
   })
 }
@@ -65,7 +118,7 @@ export default {
         const to = requireAddress('recipient address', args.to)
         const value = `0x${parseUnits(args.amount, 18).toString(16)}`
 
-        const { txHash, preview } = await requestSignature(args.chain as ChainName, { to, value, data: args.data })
+        const { txHash, preview, signedWith } = await requestSignature(args.chain as ChainName, { to, value, data: args.data })
 
         return formatResponse({
           success: true,
@@ -73,7 +126,8 @@ export default {
           transactionHash: txHash,
           to,
           amount: args.amount,
-          simulation: preview.simulation,
+          signedWith,
+          preview: previewSummary(preview),
           explorerUrl: explorerTxUrl(args.chain as ChainName, txHash)
         })
       } catch (error) {
@@ -102,7 +156,7 @@ export default {
           args: [to, parseUnits(args.amount, args.decimals ?? 18)]
         })
 
-        const { txHash, preview } = await requestSignature(args.chain as ChainName, { to: tokenAddress, data, value: '0x0' })
+        const { txHash, preview, signedWith } = await requestSignature(args.chain as ChainName, { to: tokenAddress, data, value: '0x0' })
 
         return formatResponse({
           success: true,
@@ -111,7 +165,8 @@ export default {
           tokenAddress,
           to,
           amount: args.amount,
-          simulation: preview.simulation,
+          signedWith,
+          preview: previewSummary(preview),
           explorerUrl: explorerTxUrl(args.chain as ChainName, txHash)
         })
       } catch (error) {
@@ -145,7 +200,7 @@ export default {
         })
         const value = args.value ? `0x${parseUnits(args.value, 18).toString(16)}` : '0x0'
 
-        const { txHash, preview } = await requestSignature(args.chain as ChainName, { to: contractAddress, data, value })
+        const { txHash, preview, signedWith } = await requestSignature(args.chain as ChainName, { to: contractAddress, data, value })
 
         return formatResponse({
           success: true,
@@ -153,7 +208,8 @@ export default {
           transactionHash: txHash,
           contractAddress,
           functionName: abiItem.name,
-          simulation: preview.simulation,
+          signedWith,
+          preview: previewSummary(preview),
           explorerUrl: explorerTxUrl(args.chain as ChainName, txHash)
         })
       } catch (error) {
@@ -164,23 +220,30 @@ export default {
 
   sign_message: createTool(
     'Sign Message',
-    'Sign a message with the connected wallet. Opens browser wallet for approval.',
+    'Sign a message with the connected wallet — a paired phone if there is one, otherwise the browser wallet.',
     z.object({
       message: z.string().describe('Message to sign')
     }),
     async (args) => {
       try {
-        const signature = await getWalletClient().request({
-          id: generateRequestId(),
-          type: 'sign_message',
-          chain: 'any',
-          data: { message: args.message }
-        })
+        // Same precedence as transactions: a hosted server has no browser to fall back on.
+        const phone = getPhoneSigner()
+        const session = await phone?.session()
+
+        const signature = session
+          ? await phone!.request('mainnet', 'personal_sign', [toHex(args.message), session.accounts[0]])
+          : await getWalletClient().request({
+              id: generateRequestId(),
+              type: 'sign_message',
+              chain: 'any',
+              data: { message: args.message }
+            })
 
         return formatResponse({
           success: true,
           message: args.message,
           signature,
+          signedWith: session ? 'phone' : 'browser',
           signatureType: 'personal_sign'
         })
       } catch (error) {
@@ -189,13 +252,74 @@ export default {
     }
   ),
 
+  pair_phone_wallet: createTool(
+    'Pair Phone Wallet',
+    'Pair a phone wallet over WalletConnect, so transactions are signed on the phone instead of in a browser. Returns a QR code to scan. Requires a WalletConnect project id.',
+    z.object({
+      chains: z
+        .array(z.enum(SUPPORTED_CHAINS))
+        .optional()
+        .describe('Chains to request access to (defaults to every supported network)')
+    }),
+    async (args) => {
+      const phone = getPhoneSigner()
+      if (!phone) {
+        return formatResponse({
+          success: false,
+          message:
+            'No WalletConnect project id configured. Get a free one at https://dashboard.reown.com and pass --walletconnect-project-id or set WALLETCONNECT_PROJECT_ID.'
+        })
+      }
+
+      try {
+        const existing = await phone.session()
+        if (existing) {
+          return formatResponse({
+            alreadyPaired: true,
+            address: existing.accounts[0],
+            wallet: existing.peer,
+            message: 'A phone wallet is already paired. Transactions will be sent to it.'
+          })
+        }
+
+        const chains = (args.chains ?? SUPPORTED_CHAINS.filter((c) => c !== 'localhost')) as ChainName[]
+        const uri = await phone.pair(chains)
+
+        return formatResponse({
+          qr: await qrFor(uri),
+          uri,
+          message:
+            'Scan this QR with your phone wallet (MetaMask, Rabby, Trust…), or open the uri on the phone. ' +
+            'Approve the session, then run wallet_status to confirm.'
+        })
+      } catch (error) {
+        return failure(error, 'Could not start WalletConnect pairing')
+      }
+    }
+  ),
+
   wallet_status: createTool(
     'Wallet Status',
     'Check if a wallet is connected to the browser interface',
     z.object({}),
     async () => {
-      const wallet = getWalletClient()
+      // A paired phone is the signer of record, so look there first. Connecting to the
+      // browser relay before checking would start one on a hosted server, which has no
+      // browser to open it in.
+      const phone = getPhoneSigner()
+      const phoneSession = await phone?.session().catch(() => undefined)
+      if (phoneSession) {
+        return formatResponse({
+          connected: true,
+          signer: 'phone',
+          address: phoneSession.accounts[0],
+          wallet: phoneSession.peer,
+          chains: phoneSession.chains,
+          message: 'A phone wallet is paired over WalletConnect. Transactions are sent there for signing.'
+        })
+      }
 
+      const wallet = getWalletClient()
       try {
         await wallet.connect()
       } catch (error) {
@@ -206,6 +330,8 @@ export default {
 
       return formatResponse({
         connected: wallet.isConnected(),
+        signer: 'browser',
+        phonePairing: phone ? 'Not paired — run pair_phone_wallet to sign from a phone.' : undefined,
         address: wallet.getAddress(),
         walletUrl: wallet.getUrl(),
         openTab: wallet.getPageUrl(),

package/src/types.ts

@@ -14,6 +14,7 @@ export interface Config {
   infuraApiKey?: string
   customRpcUrls?: Record<string, string>
   hypersyncApiKey?: string
+  walletConnectProjectId?: string
 }
 
 // Chain names

package/src/utils.ts

@@ -1,5 +1,5 @@
 import type { AbiParameter } from 'viem'
-import type { ToolResult } from './types.js'
+import type { Config, ToolResult } from './types.js'
 import { z } from 'zod'
 
 // Create tool helper
@@ -264,22 +264,8 @@ export function formatResponse(data: unknown): ToolResult {
 }
 
 // Parse command line arguments
-export function parseCommandLineArgs(): {
-  etherscanApiKey?: string
-  alchemyApiKey?: string
-  infuraApiKey?: string
-  customRpcUrls?: Record<string, string>
-  hypersyncApiKey?: string
-  showHelp?: boolean
-} {
-  const config: {
-    etherscanApiKey?: string
-    alchemyApiKey?: string
-    infuraApiKey?: string
-    customRpcUrls?: Record<string, string>
-    hypersyncApiKey?: string
-    showHelp?: boolean
-  } = {}
+export function parseCommandLineArgs(): Config & { showHelp?: boolean } {
+  const config: Config & { showHelp?: boolean } = {}
 
   function getArgValue(argName: string): string | undefined {
     const args = process.argv
@@ -302,6 +288,7 @@ export function parseCommandLineArgs(): {
   config.alchemyApiKey = process.env.ALCHEMY_API_KEY || getArgValue('--alchemy-api-key')
   config.infuraApiKey = process.env.INFURA_API_KEY || getArgValue('--infura-api-key')
   config.hypersyncApiKey = process.env.HYPERSYNC_API_KEY || getArgValue('--hypersync-api-key')
+  config.walletConnectProjectId = process.env.WALLETCONNECT_PROJECT_ID || getArgValue('--walletconnect-project-id')
 
   // Parse custom RPC URLs
   const customRpcs = getArgValue('--custom-rpc')

package/src/walletconnect.ts

@@ -0,0 +1,157 @@
+import { mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { getClientManager } from './client.js'
+import { getKeyValueStorage } from './kv-storage.js'
+import type { ChainName } from './types.js'
+
+/**
+ * Signing from a phone, with no page to load and nothing to host: the MCP server acts as
+ * the dApp, the wallet app is the signer, and WalletConnect's relay carries the (end-to-end
+ * encrypted) messages between them. Pair once by scanning a QR; the session is stored on
+ * disk, so it survives restarts.
+ */
+
+type SignClientType = Awaited<ReturnType<typeof importSignClient>>['prototype']
+
+async function importSignClient() {
+  // Imported lazily: several MB of SDK that is pointless to load without a project ID.
+  const { SignClient } = await import('@walletconnect/sign-client')
+  return SignClient
+}
+
+interface Session {
+  topic: string
+  accounts: string[]
+  chains: number[]
+  peer?: string
+}
+
+const METHODS = ['eth_sendTransaction', 'personal_sign', 'eth_signTypedData_v4']
+const EVENTS = ['chainChanged', 'accountsChanged']
+const APPROVAL_TIMEOUT = 300_000
+
+function storePath(): string {
+  const dir = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'web3-tools-mcp')
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  return join(dir, 'walletconnect.db')
+}
+
+export class PhoneSigner {
+  private client: SignClientType | undefined
+  private starting: Promise<void> | undefined
+  private pairing: { uri: string; expiresAt: number } | undefined
+
+  constructor(private projectId: string) {}
+
+  private async start(): Promise<void> {
+    if (this.client) return
+    if (this.starting) return this.starting
+
+    this.starting = (async () => {
+      const SignClient = await importSignClient()
+      // Redis when hosted (a free-tier filesystem is ephemeral, and losing the store means
+      // re-pairing by QR after every sleep); a file next to the other config locally.
+      const storage = getKeyValueStorage()
+      this.client = (await SignClient.init({
+        projectId: this.projectId,
+        ...(storage ? { storage } : { storageOptions: { database: storePath() } }),
+        metadata: {
+          name: 'web3-tools-mcp',
+          description: 'Blockchain tools for AI agents',
+          url: 'https://github.com/hajnalben/web3-tools-mcp',
+          icons: []
+        }
+      })) as SignClientType
+    })().finally(() => {
+      this.starting = undefined
+    })
+
+    return this.starting
+  }
+
+  /** The most recent still-valid session, if the phone is already paired. */
+  async session(): Promise<Session | undefined> {
+    await this.start()
+    const sessions = this.client?.session.getAll() ?? []
+    const live = sessions.filter((s) => s.expiry * 1000 > Date.now())
+    const session = live[live.length - 1]
+    if (!session) return undefined
+
+    const accounts = session.namespaces.eip155?.accounts ?? []
+    return {
+      topic: session.topic,
+      // "eip155:8453:0xabc…" → address / chain id
+      accounts: [...new Set(accounts.map((a) => a.split(':')[2] as string))],
+      chains: [...new Set(accounts.map((a) => Number(a.split(':')[1])))],
+      peer: session.peer?.metadata?.name
+    }
+  }
+
+  async isPaired(): Promise<boolean> {
+    return Boolean(await this.session())
+  }
+
+  /**
+   * Start a pairing and return its URI immediately, resolving the wallet's approval in the
+   * background — a tool result only reaches the user once it returns, so blocking here
+   * would hide the QR they are supposed to scan.
+   */
+  async pair(chains: ChainName[]): Promise<string> {
+    await this.start()
+    if (!this.client) throw new Error('WalletConnect failed to start')
+
+    const clientManager = getClientManager()
+    const eip155 = chains.map((chain) => `eip155:${clientManager.getChainId(chain)}`)
+
+    const { uri, approval } = await this.client.connect({
+      // Optional rather than required: wallets reject a session outright when they cannot
+      // serve every required chain, and few support all thirteen.
+      optionalNamespaces: { eip155: { chains: eip155, methods: METHODS, events: EVENTS } }
+    })
+
+    if (!uri) throw new Error('WalletConnect did not return a pairing URI')
+    this.pairing = { uri, expiresAt: Date.now() + APPROVAL_TIMEOUT }
+
+    approval()
+      .then((session) => console.error(`[WalletConnect] Paired with ${session.peer?.metadata?.name ?? 'a wallet'}`))
+      .catch((error) => console.error('[WalletConnect] Pairing was not completed:', error.message))
+
+    return uri
+  }
+
+  /** Send a request to the paired wallet. Throws if the chain is outside the session. */
+  async request(chain: ChainName, method: string, params: unknown[]): Promise<unknown> {
+    const session = await this.session()
+    if (!session || !this.client) throw new Error('No phone wallet paired')
+
+    const chainId = getClientManager().getChainId(chain)
+    if (!session.chains.includes(chainId)) {
+      throw new Error(
+        `The paired wallet did not approve ${chain} (chain ${chainId}). It approved: ${session.chains.join(', ')}. Re-pair to add it.`
+      )
+    }
+
+    return this.client.request({
+      topic: session.topic,
+      chainId: `eip155:${chainId}`,
+      request: { method, params }
+    })
+  }
+
+  async unpair(): Promise<void> {
+    const session = await this.session()
+    if (!session || !this.client) return
+    await this.client.disconnect({ topic: session.topic, reason: { code: 6000, message: 'User disconnected' } })
+  }
+}
+
+let signer: PhoneSigner | null = null
+
+/** Configured only when a WalletConnect project id is present. */
+export function getPhoneSigner(): PhoneSigner | null {
+  const projectId = getClientManager().getConfig().walletConnectProjectId
+  if (!projectId) return null
+  if (!signer) signer = new PhoneSigner(projectId)
+  return signer
+}