web3-tools-mcp 3.0.0 → 3.2.0

package/src/tools/read/signing.ts

@@ -52,12 +52,18 @@ export default {
         }
 
         if (request.state === 'failed') {
+          // Only an explicit rejection proves nothing was signed. A timeout or a dropped
+          // connection can land after the wallet signed and broadcast.
+          const rejected = request.stage === 'approval' && /rejected|denied/i.test(request.error ?? '')
           return formatResponse({
             success: false,
-            status: 'rejected_or_failed',
+            status: rejected ? 'rejected' : 'outcome_unknown',
             what: request.summary,
             error: request.error,
-            message: 'Nothing was signed. The wallet rejected it, or it expired before anybody approved.'
+            ...(request.txHash && { transactionHash: request.txHash }),
+            message: rejected
+              ? 'The wallet rejected it. Nothing was signed.'
+              : 'It did not complete here, but it may still have been signed or broadcast. Do not retry until the wallet or a block explorer shows it did not go through.'
           })
         }
 

package/src/tools/sign/transactions.ts

@@ -1,12 +1,13 @@
 import { randomBytes } from 'node:crypto'
 import { type AbiFunction, type Address, encodeFunctionData, isAddress, parseAbiItem, parseUnits, toHex } from 'viem'
 import { z } from 'zod'
+import { tokenMeta } from '../../chain-meta.js'
 import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
 import { log } from '../../log.js'
 import { buildTxPreview, type RawTx, type TxPreview } from '../../preview.js'
 import { type SigningProgress, type SigningRequest, signingCall } from '../../signing-requests.js'
 import type { ChainName } from '../../types.js'
-import { createTool, formatResponse } from '../../utils.js'
+import { convertArgumentsToTypes, createTool, formatResponse } from '../../utils.js'
 import { getWalletClient } from '../../wallet-client.js'
 import { getPhoneSigner } from '../../walletconnect.js'
 import { failure } from './errors.js'
@@ -74,6 +75,33 @@ async function requirePhoneSession(identity: string, account?: string) {
   return { phone, session, from }
 }
 
+/** The phone's wallet reaches chains through its own RPC, which cannot see this machine's node. */
+function requireReachable(chain: ChainName, signWith: SignWith) {
+  if (chain === 'localhost' && signWith === 'phone') {
+    throw new Error('A phone wallet cannot sign on localhost: it has no route to this machine\'s node. Use signWith "browser".')
+  }
+}
+
+/**
+ * The token's own decimals. A caller-supplied figure is only a cross-check: trusting a wrong
+ * one moves orders of magnitude more or less than was asked for.
+ */
+async function tokenDecimals(chain: ChainName, token: Address, claimed?: number): Promise<number> {
+  const onChain = (await tokenMeta(chain, token).catch(() => undefined))?.decimals
+  if (onChain === undefined) {
+    if (claimed === undefined) {
+      throw new Error(
+        `Could not read decimals() from ${token} on ${chain}. Check it is an ERC20 token on this chain, or pass "decimals" explicitly.`
+      )
+    }
+    return claimed
+  }
+  if (claimed !== undefined && claimed !== onChain) {
+    throw new Error(`"decimals" was ${claimed}, but ${token} reports ${onChain} on ${chain}. Nothing was sent.`)
+  }
+  return onChain
+}
+
 /** Long enough for a congested chain, short enough that a stuck one is reported rather than hung on. */
 const RECEIPT_TIMEOUT = 180_000
 
@@ -140,6 +168,7 @@ async function requestSignature(
   progress: SigningProgress
 ) {
   log('info', 'Transaction', `${chain} → ${tx.to}, signing with ${signWith}`)
+  requireReachable(chain, signWith)
   if (signWith === 'phone') return signOnPhone(chain, tx, identity, account, progress)
 
   const wallet = getWalletClient(identity)
@@ -212,6 +241,8 @@ function previewSummary(preview: TxPreview) {
   return {
     action: preview.decoded?.intent ?? preview.decoded?.functionName,
     protocol: preview.decoded?.protocol ?? preview.toLabel,
+    // Labels come from the contracts themselves, so the address they belong to goes too.
+    to: preview.to,
     details: preview.decoded?.fields.map((f) => `${f.name}: ${f.value}${f.warning ? ` (${f.warning})` : ''}`),
     simulation: preview.simulation
   }
@@ -273,7 +304,11 @@ export default {
       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()
+        .int()
+        .optional()
+        .describe('Token decimals. Read from the token when omitted; when given, must match what the token reports.'),
       signWith: SignWithSchema,
       account: AccountSchema
     }),
@@ -281,10 +316,11 @@ export default {
       try {
         const tokenAddress = requireAddress('token address', args.tokenAddress)
         const to = requireAddress('recipient address', args.to)
+        const decimals = await tokenDecimals(args.chain as ChainName, tokenAddress, args.decimals)
 
         const data = encodeFunctionData({
           abi: [parseAbiItem('function transfer(address to, uint256 amount)')],
-          args: [to, parseUnits(args.amount, args.decimals ?? 18)]
+          args: [to, parseUnits(args.amount, decimals)]
         })
 
         const outcome = await signingCall(
@@ -327,9 +363,19 @@ export default {
       contractAddress: z.string().describe('Contract address'),
       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()]))
+        .array(
+          z.union([
+            z.string(),
+            // JSON numbers past 2^53 arrive already rounded, so signing one would send a different value.
+            z.number().refine(Number.isSafeInteger, {
+              message:
+                'Numbers must be integers within ±2^53-1. Pass large or exact values as strings, e.g. "1000000000000000000".'
+            }),
+            z.boolean()
+          ])
+        )
         .optional()
-        .describe('Function arguments in order matching the ABI signature'),
+        .describe('Function arguments in order matching the ABI signature. Pass uint/int values as strings.'),
       value: z.string().optional().describe('Optional native value to send with transaction (in ETH units, e.g., "0.1")'),
       signWith: SignWithSchema,
       account: AccountSchema
@@ -342,7 +388,7 @@ export default {
         const data = encodeFunctionData({
           abi: [abiItem],
           functionName: abiItem.name,
-          args: (args.args || []) as readonly unknown[]
+          args: convertArgumentsToTypes(args.args || [], abiItem.inputs)
         })
         const value = args.value ? `0x${parseUnits(args.value, 18).toString(16)}` : '0x0'
 
@@ -389,8 +435,11 @@ export default {
       try {
         const sign = async (progress: SigningProgress) => {
           if (args.signWith === 'phone') {
-            const { phone, from } = await requirePhoneSession(identity, args.account)
-            return phone.request('mainnet', 'personal_sign', [toHex(args.message), from], {
+            const { phone, session, from } = await requirePhoneSession(identity, args.account)
+            // personal_sign is chain-agnostic, but the request still has to name a chain the session holds.
+            const chain = SUPPORTED_CHAINS.find((c) => session.chains.includes(getClientManager().getChainId(c)))
+            if (!chain) throw new Error(`The paired wallet approved no chain this server knows: ${session.chains.join(', ')}.`)
+            return phone.request(chain, 'personal_sign', [toHex(args.message), from], {
               identity,
               account: args.account,
               onWaiting: progress.waiting
@@ -403,7 +452,9 @@ export default {
             id: generateRequestId(),
             type: 'sign_message',
             chain: 'any',
-            data: { message: args.message }
+            // Hex on both signers: a wallet reads a raw "0x…" string as bytes, so the same text
+            // would otherwise sign differently depending on where it was approved.
+            data: { message: toHex(args.message) }
           })
         }
 

package/src/types.ts

@@ -11,7 +11,6 @@ export interface AbiError {
 export interface Config {
   etherscanApiKey?: string
   alchemyApiKey?: string
-  infuraApiKey?: string
   customRpcUrls?: Record<string, string>
   hypersyncApiKey?: string
   walletConnectProjectId?: string

package/src/utils.ts

@@ -136,11 +136,13 @@ function findErrorInTrace(trace: unknown): { errorPath: SummarizedCall[]; errorM
 }
 
 /**
- * Coerce a JSON value into what viem expects for an ABI type. Tuples, arrays and anything
+ * Coerce a JSON value into what viem expects for an ABI type. A list is coerced element by
+ * element — an array argument, or an OR filter on an event argument. Tuples and anything
  * else pass through: viem validates them, and guessing here would only mangle them.
  */
 function coerce(value: unknown, type: string): unknown {
   if (value === null || value === undefined) return null
+  if (Array.isArray(value)) return value.map((item) => coerce(item, type))
 
   if (type === 'address' || type === 'string' || type.startsWith('bytes')) {
     return String(value)
@@ -195,6 +197,50 @@ export function convertEventArgsToTypes(
   )
 }
 
+/** One tool call is one quota unit, so an unbounded batch would be a way around the quota. */
+export const MAX_BATCH = 25
+
+/**
+ * Why an RPC call failed, without the request URL — viem puts it in `message`, and with a
+ * provider key configured that URL carries the key.
+ */
+export function rpcReason(error: unknown): string {
+  const { details, shortMessage } = error as { details?: string; shortMessage?: string }
+  return details || shortMessage || (error instanceof Error ? error.message : String(error))
+}
+
+/** Every configured key blanked out of `text`: RPC URLs carry them, and errors quote the URL. */
+export function redactSecrets(text: string, config: Config): string {
+  return [config.alchemyApiKey, config.etherscanApiKey, config.hypersyncApiKey].reduce<string>(
+    (out, secret) => (secret ? out.replaceAll(secret, '[redacted]') : out),
+    text
+  )
+}
+
+/** A Map whose entries expire after `ttlMs`, dropping the oldest once it holds `maxSize`. */
+export class TtlCache<V> {
+  private entries = new Map<string, { value: V; expires: number }>()
+
+  constructor(
+    private maxSize: number,
+    private ttlMs: number
+  ) {}
+
+  get(key: string): V | undefined {
+    const entry = this.entries.get(key)
+    if (!entry) return undefined
+    if (entry.expires > Date.now()) return entry.value
+    this.entries.delete(key)
+    return undefined
+  }
+
+  set(key: string, value: V): void {
+    this.entries.delete(key)
+    this.entries.set(key, { value, expires: Date.now() + this.ttlMs })
+    if (this.entries.size > this.maxSize) this.entries.delete(this.entries.keys().next().value as string)
+  }
+}
+
 // Format response as tool result
 export function formatResponse(data: unknown): ToolResult {
   const serializable = convertBigIntToString(data)
@@ -231,7 +277,6 @@ export function parseCommandLineArgs(): Config & { showHelp?: boolean } {
   // Parse environment variables and command line arguments
   config.etherscanApiKey = process.env.ETHERSCAN_API_KEY || getArgValue('--etherscan-api-key')
   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')
 

package/src/wallet-client.ts

@@ -3,12 +3,26 @@ import { randomBytes } from 'node:crypto'
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { LOCAL_PORT_ATTEMPTS, roomToken, type TransactionRequest, type TransactionResponse, WalletRelay } from 'web3-wallet-relay'
+import {
+  LOCAL_PORT_ATTEMPTS,
+  roomToken,
+  SIGN_PATH,
+  type TransactionRequest,
+  type TransactionResponse,
+  WalletRelay
+} from 'web3-wallet-relay'
 import { WebSocket } from 'ws'
 import { HOSTED } from './hosted.js'
 
 const REQUEST_TIMEOUT = 300_000
 
+/**
+ * Past this point the page may have signed and broadcast without the answer reaching us, so
+ * a failure is not a rejection: retrying blindly could send the same thing twice.
+ */
+const OUTCOME_UNKNOWN =
+  'The outcome is unknown — it may still have been signed or broadcast. Check the wallet or a block explorer before retrying.'
+
 /**
  * How long a client with nothing in flight keeps its socket. A hosted server makes one per
  * person who ever signed, and without this each would hold a relay connection for the life
@@ -19,7 +33,7 @@ const IDLE_TIMEOUT = 10 * 60_000
 /** Always the signer token: this URL goes to a browser, which may not act as a requester. */
 function pairingUrlFor(port: number, secret: string, identity: string): string {
   const base = HOSTED ? (process.env.MCP_PUBLIC_URL ?? `http://localhost:${port}`) : `http://127.0.0.1:${port}`
-  return `${base.replace(/\/$/, '')}/#t=${roomToken(secret, identity, 'signer')}`
+  return `${base.replace(/\/$/, '')}${SIGN_PATH}#t=${roomToken(secret, identity, 'signer')}`
 }
 const SIGNER_WAIT_TIMEOUT = 30_000
 const CONNECT_ATTEMPTS = 8
@@ -94,6 +108,7 @@ export class WalletClient {
   /** Instance fields so tests can shorten the waits instead of sitting out the real ones. */
   private signerWaitTimeout = SIGNER_WAIT_TIMEOUT
   private idleTimeout = IDLE_TIMEOUT
+  private requestTimeout = REQUEST_TIMEOUT
 
   private readonly remoteUrl = process.env.WALLET_SERVER_URL
   private readonly remoteToken = process.env.WALLET_TOKEN
@@ -234,6 +249,10 @@ export class WalletClient {
         this.signerAddress = undefined
         this.pageUrl = undefined
         this.pageAgent = undefined
+        for (const [id, pending] of this.pending) {
+          this.pending.delete(id)
+          pending.reject(new Error(`Lost the connection to the wallet relay before the wallet answered. ${OUTCOME_UNKNOWN}`))
+        }
       })
     })
   }
@@ -325,14 +344,16 @@ export class WalletClient {
     return new Promise((resolve, reject) => {
       this.pending.set(request.id, { resolve, reject })
       this.rearmIdle()
-      ws.send(JSON.stringify(request))
+      ws.send(JSON.stringify({ ...request, expiresAt: Date.now() + this.requestTimeout }))
 
       setTimeout(() => {
         if (this.pending.delete(request.id)) {
           this.rearmIdle()
-          reject(new Error('Transaction request timed out'))
+          // So the page stops offering it; its own expiresAt covers a cancel that never lands.
+          if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'cancel', id: request.id }))
+          reject(new Error(`Wallet request timed out. ${OUTCOME_UNKNOWN}`))
         }
-      }, REQUEST_TIMEOUT)
+      }, this.requestTimeout)
     })
   }