web3-tools-mcp 1.6.0 → 2.0.1

package/src/tools/signatures.ts

@@ -2,12 +2,12 @@ import {
   type AbiEvent,
   type AbiFunction,
   type AbiParameter,
+  encodeFunctionData,
   keccak256,
   parseAbiItem,
   toBytes,
   toEventSignature,
-  toFunctionSignature,
-  encodeFunctionData
+  toFunctionSignature
 } from 'viem'
 import { z } from 'zod'
 import type { AbiError } from '../types.js'
@@ -24,9 +24,7 @@ const EventAbiSchema = z.object({
 })
 
 const ErrorAbiSchema = z.object({
-  errorAbi: z
-    .string()
-    .describe('Error ABI definition (e.g., "error InsufficientBalance(uint256 available, uint256 required)")')
+  errorAbi: z.string().describe('Error ABI definition (e.g., "error InsufficientBalance(uint256 available, uint256 required)")')
 })
 
 export default {
@@ -34,33 +32,27 @@ export default {
     'Calculate Function Signatures',
     'Generate 4-byte function selectors from ABI definitions. BATCH OPTIMIZED - use for transaction decoding.',
     z.object({
-      items: z
-        .array(FunctionAbiSchema)
-        .describe('Array of function ABI definitions. Batch multiple functions for efficiency.')
+      items: z.array(FunctionAbiSchema).describe('Array of function ABI definitions. Batch multiple functions for efficiency.')
     }),
     async (args) => {
-      try {
-        const results = args.items.map((item) => {
-          const abiItem = parseAbiItem(item.functionAbi) as AbiFunction
-          const signature = toFunctionSignature(abiItem)
-          const hash = keccak256(toBytes(signature))
-          const selector = hash.slice(0, 10)
+      const results = args.items.map((item) => {
+        const abiItem = parseAbiItem(item.functionAbi) as AbiFunction
+        const signature = toFunctionSignature(abiItem)
+        const hash = keccak256(toBytes(signature))
+        const selector = hash.slice(0, 10)
 
-          return {
-            signature: selector,
-            fullSignature: signature,
-            functionName: abiItem.name,
-            inputs: abiItem.inputs,
-            outputs: abiItem.outputs || [],
-            stateMutability: abiItem.stateMutability,
-            originalAbi: item.functionAbi
-          }
-        })
+        return {
+          signature: selector,
+          fullSignature: signature,
+          functionName: abiItem.name,
+          inputs: abiItem.inputs,
+          outputs: abiItem.outputs || [],
+          stateMutability: abiItem.stateMutability,
+          originalAbi: item.functionAbi
+        }
+      })
 
-        return formatResponse(results)
-      } catch (error) {
-        throw new Error(`Failed to parse function ABI: ${error}`)
-      }
+      return formatResponse(results)
     }
   ),
 
@@ -71,27 +63,23 @@ export default {
       items: z.array(EventAbiSchema).describe('Array of event ABI definitions. Batch multiple events for optimal performance.')
     }),
     async (args) => {
-      try {
-        const results = args.items.map((item) => {
-          const abiItem = parseAbiItem(item.eventAbi) as AbiEvent
-          const signature = toEventSignature(abiItem)
-          const hash = keccak256(toBytes(signature))
+      const results = args.items.map((item) => {
+        const abiItem = parseAbiItem(item.eventAbi) as AbiEvent
+        const signature = toEventSignature(abiItem)
+        const hash = keccak256(toBytes(signature))
 
-          return {
-            signature: hash,
-            topic0: hash,
-            fullSignature: signature,
-            eventName: abiItem.name,
-            inputs: abiItem.inputs,
-            anonymous: abiItem.anonymous || false,
-            originalAbi: item.eventAbi
-          }
-        })
+        return {
+          signature: hash,
+          topic0: hash,
+          fullSignature: signature,
+          eventName: abiItem.name,
+          inputs: abiItem.inputs,
+          anonymous: abiItem.anonymous || false,
+          originalAbi: item.eventAbi
+        }
+      })
 
-        return formatResponse(results)
-      } catch (error) {
-        throw new Error(`Failed to parse event ABI: ${error}`)
-      }
+      return formatResponse(results)
     }
   ),
 
@@ -102,58 +90,52 @@ export default {
       items: z.array(ErrorAbiSchema).describe('Array of error ABI definitions. Batch related errors for efficiency.')
     }),
     async (args) => {
-      try {
-        const results = args.items.map((item) => {
-          const abiItem = parseAbiItem(item.errorAbi) as AbiError
-          const signature = `${abiItem.name}(${abiItem.inputs.map((input: AbiParameter) => input.type).join(',')})`
-          const hash = keccak256(toBytes(signature))
-          const selector = hash.slice(0, 10)
+      const results = args.items.map((item) => {
+        const abiItem = parseAbiItem(item.errorAbi) as AbiError
+        const signature = `${abiItem.name}(${abiItem.inputs.map((input: AbiParameter) => input.type).join(',')})`
+        const hash = keccak256(toBytes(signature))
+        const selector = hash.slice(0, 10)
 
-          return {
-            signature: selector,
-            fullSignature: signature,
-            errorName: abiItem.name,
-            inputs: abiItem.inputs,
-            originalAbi: item.errorAbi
-          }
-        })
+        return {
+          signature: selector,
+          fullSignature: signature,
+          errorName: abiItem.name,
+          inputs: abiItem.inputs,
+          originalAbi: item.errorAbi
+        }
+      })
 
-        return formatResponse(results)
-      } catch (error) {
-        throw new Error(`Failed to parse error ABI: ${error}`)
-      }
+      return formatResponse(results)
     }
   ),
 
   encode_function_data: createTool(
     'Encode Function Call Data',
-    'Encode a function call with parameters into transaction data. Use this before calling call_contract_write.',
+    'Encode a function call with parameters into transaction data. Use this before calling write_contract.',
     z.object({
       functionAbi: z.string().describe('Function ABI definition (e.g., "function transfer(address to, uint256 amount)")'),
-      args: z.array(z.union([z.string(), z.number(), z.boolean()])).describe('Function arguments in order matching the ABI signature. Automatically type-converted.')
+      args: z
+        .array(z.union([z.string(), z.number(), z.boolean()]))
+        .describe('Function arguments in order matching the ABI signature. Automatically type-converted.')
     }),
     async (args) => {
-      try {
-        const abiItem = parseAbiItem(args.functionAbi) as AbiFunction
+      const abiItem = parseAbiItem(args.functionAbi) as AbiFunction
 
-        // Encode the function data
-        const data = encodeFunctionData({
-          abi: [abiItem],
-          functionName: abiItem.name,
-          args: args.args as readonly unknown[]
-        })
+      // Encode the function data
+      const data = encodeFunctionData({
+        abi: [abiItem],
+        functionName: abiItem.name,
+        args: args.args as readonly unknown[]
+      })
 
-        return formatResponse({
-          data,
-          functionName: abiItem.name,
-          functionSignature: toFunctionSignature(abiItem),
-          selector: data.slice(0, 10),
-          encodedArgs: data.slice(10),
-          message: 'Function data encoded successfully. Use this data with call_contract_write tool.'
-        })
-      } catch (error) {
-        throw new Error(`Failed to encode function data: ${error}`)
-      }
+      return formatResponse({
+        data,
+        functionName: abiItem.name,
+        functionSignature: toFunctionSignature(abiItem),
+        selector: data.slice(0, 10),
+        encodedArgs: data.slice(10),
+        message: 'Function data encoded successfully. Use this data with write_contract tool.'
+      })
     }
   )
 }

package/src/tools/transactions.ts

@@ -1,13 +1,13 @@
+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, toHex, type AbiFunction, type Address } from 'viem'
-import { randomBytes } from 'node:crypto'
-import type { ChainName } from '../types.js'
 import { buildTxPreview, type RawTx, type TxPreview } from '../preview.js'
-import { getPhoneSigner } from '../walletconnect.js'
+import type { ChainName } from '../types.js'
 import { createTool, formatResponse } from '../utils.js'
-import qrcode from 'qrcode-terminal'
+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> {
@@ -23,32 +23,50 @@ 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.
+ * 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.
  *
- * 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.
+ * 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.')
+  }
 
-  if (await phone?.isPaired()) {
-    const session = await phone!.session()
-    const from = session?.accounts[0]
-    const preview = await buildTxPreview(chain, tx, from)
+  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 }) }
-    ])
+  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 }
-  }
+  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()
@@ -106,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, signedWith } = 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,
@@ -138,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 {
@@ -156,7 +180,15 @@ export default {
           args: [to, parseUnits(args.amount, args.decimals ?? 18)]
         })
 
-        const { txHash, preview, signedWith } = 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,
@@ -175,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'),
@@ -186,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 {
@@ -200,7 +233,15 @@ export default {
         })
         const value = args.value ? `0x${parseUnits(args.value, 18).toString(16)}` : '0x0'
 
-        const { txHash, preview, signedWith } = 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,
@@ -220,30 +261,37 @@ export default {
 
   sign_message: createTool(
     'Sign Message',
-    'Sign a message with the connected wallet — a paired phone if there is one, otherwise the browser wallet.',
+    '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 {
-        // 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 }
-            })
+        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: session ? 'phone' : 'browser',
+          signedWith: args.signWith,
           signatureType: 'personal_sign'
         })
       } catch (error) {
@@ -254,12 +302,22 @@ 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.',
+    '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)')
+        .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()
@@ -267,7 +325,7 @@ export default {
         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.'
+            'No WalletConnect project id configured. Get a free one at https://dashboard.walletconnect.com and pass --walletconnect-project-id or set WALLETCONNECT_PROJECT_ID.'
         })
       }
 
@@ -283,14 +341,27 @@ export default {
         }
 
         const chains = (args.chains ?? SUPPORTED_CHAINS.filter((c) => c !== 'localhost')) as ChainName[]
-        const uri = await phone.pair(chains)
+        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:
-            '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.'
+            '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')
@@ -298,48 +369,84 @@ export default {
     }
   ),
 
-  wallet_status: createTool(
-    'Wallet Status',
-    'Check if a wallet is connected to the browser interface',
+  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 () => {
-      // 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) {
+      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({
-          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.'
+          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',
+    '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()
-      try {
-        await wallet.connect()
-      } catch (error) {
-        return failure(error, 'Wallet relay unavailable')
+      const relayError = await wallet
+        .connect()
+        .then(() => undefined)
+        .catch((error) => describeError(error))
+
+      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(),
-        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(),
-        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

@@ -17,21 +17,7 @@ export interface Config {
   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 {