web3-tools-mcp 1.5.0 → 2.0.0

package/src/tools/transactions.ts

@@ -1,11 +1,18 @@
+import { randomBytes } from 'node:crypto'
+import qrcode from 'qrcode-terminal'
+import { type AbiFunction, type Address, encodeFunctionData, isAddress, parseAbiItem, parseUnits, toHex } from 'viem'
 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 { randomBytes } from 'node:crypto'
+import { buildTxPreview, type RawTx, type TxPreview } from '../preview.js'
 import type { ChainName } from '../types.js'
-import { buildTxPreview, type RawTx } from '../preview.js'
 import { createTool, formatResponse } from '../utils.js'
+import { getWalletClient } from '../wallet-client.js'
+import { getPhoneSigner, pairingLinks } from '../walletconnect.js'
+
+/** 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')
@@ -16,15 +23,51 @@ function requireAddress(label: string, address: string): Address {
   return address
 }
 
-function explorerTxUrl(chain: ChainName, txHash: unknown): string {
-  return `https://${getClientManager().getEtherscanDomain(chain)}/tx/${txHash}`
+function explorerTxUrl(chain: ChainName, txHash: unknown): string | undefined {
+  return getClientManager().explorerUrl(chain, `/tx/${txHash}`)
 }
 
 /**
- * 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.
+ * Which wallet to send the request to. Deliberately required on every signing tool: both
+ * signers can be live at once, and only the person holding the devices knows which one is
+ * actually to hand. Guessing strands the request in front of a screen nobody is looking at.
+ *
+ * Either way the transaction is decoded and simulated first — the wallet shows its own
+ * summary, so the preview is returned to the caller too, to be read before approving.
  */
-async function requestSignature(chain: ChainName, tx: RawTx & { data?: string }) {
+const SignWithSchema = z
+  .enum(['phone', 'browser'])
+  .describe(
+    'Where to approve this: "phone" for a paired WalletConnect wallet, "browser" for the wallet signing page. Ask the user which they want — do not assume, even when only one is connected. Call wallet_status first: it says which signers are ready, and when no signing page is open it returns walletUrl. In that case give the user that link, ask them to open it and connect a wallet, and only call this once they confirm — a signing request cannot reach a page nobody has open.'
+  )
+
+type SignWith = z.infer<typeof SignWithSchema>
+
+async function signOnPhone(chain: ChainName, tx: RawTx & { data?: string }) {
+  const phone = getPhoneSigner()
+  if (!phone) {
+    throw new Error(
+      'Phone signing is not configured on this server. Set WALLETCONNECT_PROJECT_ID, or sign in the browser instead.'
+    )
+  }
+  if (!(await phone.isPaired())) {
+    throw new Error('No phone wallet is paired. Run pair_phone_wallet and scan the QR, or sign in the browser instead.')
+  }
+
+  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 }
+}
+
+async function requestSignature(chain: ChainName, tx: RawTx & { data?: string }, signWith: SignWith) {
+  if (signWith === 'phone') return signOnPhone(chain, tx)
+
   const wallet = getWalletClient()
   await wallet.waitForSigner()
 
@@ -38,14 +81,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
   })
 }
@@ -53,19 +124,24 @@ function failure(error: unknown, message: string) {
 export default {
   send_native_token: createTool(
     'Send Native Token',
-    'Send native tokens (ETH, MATIC, BNB, etc.) to an address. Simulates the transaction, then opens the browser wallet for approval.',
+    'Send native tokens (ETH, MATIC, BNB, etc.) to an address. Simulates the transaction, then sends it to the signer you choose for approval.',
     z.object({
       chain: z.enum(SUPPORTED_CHAINS).describe('Blockchain network'),
       to: z.string().describe('Recipient address'),
       amount: z.string().describe('Amount in native token (e.g., "0.1" for 0.1 ETH)'),
-      data: z.string().optional().describe('Optional hex-encoded data to include with transaction')
+      data: z.string().optional().describe('Optional hex-encoded data to include with transaction'),
+      signWith: SignWithSchema
     }),
     async (args) => {
       try {
         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 },
+          args.signWith
+        )
 
         return formatResponse({
           success: true,
@@ -73,7 +149,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) {
@@ -84,13 +161,14 @@ export default {
 
   send_erc20_token: createTool(
     'Send ERC20 Token',
-    'Send ERC20 tokens to an address. Simulates the transfer, then opens the browser wallet for approval.',
+    'Send ERC20 tokens to an address. Simulates the transfer, then sends it to the signer you choose for approval.',
     z.object({
       chain: z.enum(SUPPORTED_CHAINS).describe('Blockchain network'),
       tokenAddress: z.string().describe('ERC20 token contract address'),
       to: z.string().describe('Recipient address'),
       amount: z.string().describe('Amount in token units (e.g., "100" for 100 USDC)'),
-      decimals: z.number().optional().default(18).describe('Token decimals (default: 18)')
+      decimals: z.number().optional().default(18).describe('Token decimals (default: 18)'),
+      signWith: SignWithSchema
     }),
     async (args) => {
       try {
@@ -102,7 +180,15 @@ 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'
+          },
+          args.signWith
+        )
 
         return formatResponse({
           success: true,
@@ -111,7 +197,8 @@ export default {
           tokenAddress,
           to,
           amount: args.amount,
-          simulation: preview.simulation,
+          signedWith,
+          preview: previewSummary(preview),
           explorerUrl: explorerTxUrl(args.chain as ChainName, txHash)
         })
       } catch (error) {
@@ -120,9 +207,9 @@ export default {
     }
   ),
 
-  call_contract_write: createTool(
-    'Call Contract (Write)',
-    'Call a state-changing contract function. Simulates the call, then opens the browser wallet for approval.',
+  write_contract: createTool(
+    'Write Contract',
+    'Send a transaction that calls a state-changing contract function. Simulates it first, then asks your wallet to approve. Costs gas.',
     z.object({
       chain: z.enum(SUPPORTED_CHAINS).describe('Blockchain network'),
       contractAddress: z.string().describe('Contract address'),
@@ -131,7 +218,8 @@ export default {
         .array(z.union([z.string(), z.number(), z.boolean()]))
         .optional()
         .describe('Function arguments in order matching the ABI signature'),
-      value: z.string().optional().describe('Optional native value to send with transaction (in ETH units, e.g., "0.1")')
+      value: z.string().optional().describe('Optional native value to send with transaction (in ETH units, e.g., "0.1")'),
+      signWith: SignWithSchema
     }),
     async (args) => {
       try {
@@ -145,7 +233,15 @@ 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
+          },
+          args.signWith
+        )
 
         return formatResponse({
           success: true,
@@ -153,7 +249,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 +261,37 @@ export default {
 
   sign_message: createTool(
     'Sign Message',
-    'Sign a message with the connected wallet. Opens browser wallet for approval.',
+    'Sign a message with your wallet, on whichever signer you choose.',
     z.object({
-      message: z.string().describe('Message to sign')
+      message: z.string().describe('Message to sign'),
+      signWith: SignWithSchema
     }),
     async (args) => {
       try {
-        const signature = await getWalletClient().request({
-          id: generateRequestId(),
-          type: 'sign_message',
-          chain: 'any',
-          data: { message: args.message }
-        })
+        let signature: unknown
+
+        if (args.signWith === 'phone') {
+          const phone = getPhoneSigner()
+          const session = await phone?.session()
+          if (!session) {
+            throw new Error('No phone wallet is paired. Run pair_phone_wallet and scan the QR, or sign in the browser instead.')
+          }
+          signature = await phone!.request('mainnet', 'personal_sign', [toHex(args.message), session.accounts[0]])
+        } else {
+          await getWalletClient().waitForSigner()
+          signature = await getWalletClient().request({
+            id: generateRequestId(),
+            type: 'sign_message',
+            chain: 'any',
+            data: { message: args.message }
+          })
+        }
 
         return formatResponse({
           success: true,
           message: args.message,
           signature,
+          signedWith: args.signWith,
           signatureType: 'personal_sign'
         })
       } catch (error) {
@@ -189,31 +300,153 @@ 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 to scan plus links that open a wallet directly — show those to the user as clickable links. ' +
+      '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)'),
+      wallet: z.string().optional().describe('Name of the wallet to open, e.g. "rabby" — omit to list the common ones'),
+      agent: z
+        .string()
+        .optional()
+        .describe(
+          'Who is asking, shown in the wallet approval dialog, e.g. "Claude Code". Say who you actually are — ' +
+            'the user reads this when deciding whether to grant signing access.'
+        )
+    }),
+    async (args) => {
+      const phone = getPhoneSigner()
+      if (!phone) {
+        return formatResponse({
+          success: false,
+          message:
+            'No WalletConnect project id configured. Get a free one at https://dashboard.walletconnect.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, args.agent)
+        const projectId = getClientManager().getConfig().walletConnectProjectId as string
+
+        return formatResponse({
+          qr: await qrFor(uri),
+          uri,
+          // For an agent running on the phone itself there is nothing to scan, so hand over
+          // links that open the wallet directly. `wallet` narrows the list to one.
+          openOnThisDevice: await pairingLinks(projectId, uri, args.wallet),
+          // Approving grants an agent standing permission to request signatures, so the
+          // wallet dialog names the agent rather than implying a website is connecting.
+          shownInWallet: args.agent ? `${args.agent} via web3-tools-mcp` : 'web3-tools-mcp (AI agent)',
+          howToPresent:
+            'Render each openOnThisDevice entry as a clickable link labelled with the wallet name, and show the ' +
+            'uri as copyable text. On a phone that tap is the whole flow. Show the QR only when the user is on a ' +
+            'different device from their wallet — it is unreadable inline on the phone that holds the wallet. ' +
+            'If a link does nothing, some clients drop custom schemes like rabby://, so tell them to paste the uri.',
+          message:
+            'On another device: scan the QR with your wallet. On this device: tap one of the openOnThisDevice ' +
+            'links, or copy the uri and paste it into your wallet under WalletConnect — every wallet supports ' +
+            'that, and it is the one that always works. Then run wallet_status to confirm.'
+        })
+      } catch (error) {
+        return failure(error, 'Could not start WalletConnect pairing')
+      }
+    }
+  ),
+
+  disconnect_phone_wallet: createTool(
+    'Disconnect Phone Wallet',
+    'End every WalletConnect session and drop the pairings underneath them. Use before pairing a different wallet, or to clear out attempts that were never approved.',
+    z.object({}),
+    async () => {
+      const phone = getPhoneSigner()
+      if (!phone) {
+        return formatResponse({ success: false, message: 'No WalletConnect project id configured — nothing to disconnect.' })
+      }
+
+      try {
+        const before = await phone.sessions()
+        const removed = await phone.disconnectAll()
+
+        return formatResponse({
+          success: true,
+          disconnectedSessions: removed.sessions,
+          droppedPairings: removed.pairings,
+          wallets: before.map((session) => `${session.peer ?? 'unknown wallet'} (${session.accounts[0]})`),
+          message:
+            removed.sessions || removed.pairings
+              ? 'Disconnected. Transactions fall back to the browser wallet until a phone is paired again.'
+              : 'Nothing was connected.'
+        })
+      } catch (error) {
+        return failure(error, 'Could not disconnect the phone wallet')
+      }
+    }
+  ),
+
   wallet_status: createTool(
     'Wallet Status',
-    'Check if a wallet is connected to the browser interface',
+    'Report every signer and whether it is ready, so a signing tool can be given the right signWith.',
     z.object({}),
     async () => {
+      // Both signers are reported, never just the first one found: signWith makes this a
+      // choice the user owns, so the agent has to see everything available.
+      const phone = getPhoneSigner()
+      const phoneSession = await phone?.session().catch(() => undefined)
+
       const wallet = getWalletClient()
+      const relayError = await wallet
+        .connect()
+        .then(() => undefined)
+        .catch((error) => describeError(error))
 
-      try {
-        await wallet.connect()
-      } catch (error) {
-        return failure(error, 'Wallet relay unavailable')
+      const browserReady = !relayError && wallet.isConnected()
+      // Only raise a tab when there is no other way to sign — a status check should not
+      // open a window at someone who is about to use their phone.
+      if (!browserReady && !phoneSession && !relayError) wallet.openBrowser()
+
+      const signers = {
+        phone: phoneSession
+          ? { ready: true, address: phoneSession.accounts[0], wallet: phoneSession.peer, chains: phoneSession.chains }
+          : {
+              ready: false,
+              reason: phone
+                ? 'No phone paired. Run pair_phone_wallet and scan the QR.'
+                : 'Phone signing is not configured — set WALLETCONNECT_PROJECT_ID.'
+            },
+        browser: browserReady
+          ? { ready: true, address: wallet.getAddress(), openTab: wallet.getPageUrl() }
+          : {
+              ready: false,
+              reason: relayError ?? 'No signing page is open.',
+              walletUrl: relayError ? undefined : wallet.getUrl()
+            }
       }
 
-      if (!wallet.isConnected()) wallet.openBrowser()
-
-      return formatResponse({
-        connected: wallet.isConnected(),
-        address: wallet.getAddress(),
-        walletUrl: wallet.getUrl(),
-        openTab: wallet.getPageUrl(),
-        hosted: wallet.isRemote,
-        message: wallet.isConnected()
-          ? 'Wallet is connected and ready to sign transactions'
-          : `No wallet connected. Open ${wallet.getUrl()} and connect your wallet.`
-      })
+      const ready = [phoneSession ? 'phone' : undefined, browserReady ? 'browser' : undefined].filter(Boolean)
+      const message =
+        ready.length === 2
+          ? 'Both signers are ready. Ask the user which one to use, then pass it as signWith.'
+          : ready.length === 1
+            ? `Only ${ready[0]} is ready. Confirm with the user before signing there, or set the other one up.`
+            : `No signer is ready. For a browser, give the user this link and ask them to open it and connect a wallet: ${signers.browser.walletUrl ?? '(relay unavailable)'}. For a phone, run pair_phone_wallet.`
+
+      return formatResponse({ ready, signers, message })
     }
   )
 }

package/src/types.ts

@@ -14,23 +14,10 @@ export interface Config {
   infuraApiKey?: string
   customRpcUrls?: Record<string, string>
   hypersyncApiKey?: string
+  walletConnectProjectId?: string
 }
 
-// Chain names
-export type ChainName =
-  | 'mainnet'
-  | 'arbitrum'
-  | 'avalanche'
-  | 'base'
-  | 'bnb'
-  | 'gnosis'
-  | 'sonic'
-  | 'optimism'
-  | 'polygon'
-  | 'zksync'
-  | 'linea'
-  | 'unichain'
-  | 'localhost'
+export type { ChainName } from './chains.js'
 
 // Tool handler result type
 export interface ToolResult {