web3-tools-mcp 2.0.2 → 3.1.0

package/src/utils.ts

@@ -7,13 +7,16 @@ export function createTool<T extends z.ZodType>(
   title: string,
   description: string,
   schema: T,
-  handler: (args: z.infer<T>) => Promise<ToolResult>
+  handler: (args: z.infer<T>, identity: string) => Promise<ToolResult>,
+  /** Whether this server can serve the tool at all; one it cannot is never offered. */
+  available?: () => boolean
 ) {
   return {
     title,
     description,
     schema,
-    handler
+    handler,
+    available
   }
 }
 
@@ -133,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)
@@ -192,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.infuraApiKey, 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)

package/src/wallet-client.ts

@@ -3,18 +3,30 @@ 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, type TransactionRequest, type TransactionResponse, WalletRelay } from 'web3-wallet-relay'
+import { LOCAL_PORT_ATTEMPTS, roomToken, type TransactionRequest, type TransactionResponse, WalletRelay } from 'web3-wallet-relay'
 import { WebSocket } from 'ws'
+import { HOSTED } from './hosted.js'
 
 const REQUEST_TIMEOUT = 300_000
 
-/** Serving over HTTP means no desktop here: never try to open a browser, and never
- *  hand out a loopback URL as the place to open the signing page. */
-const HOSTED = Boolean(process.env.MCP_HTTP_PORT)
+/**
+ * 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
+ * of the process. The next call reconnects.
+ */
+const IDLE_TIMEOUT = 10 * 60_000
 
-function pairingUrlFor(port: number, token: string): string {
+/** 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=${token}`
+  return `${base.replace(/\/$/, '')}/#t=${roomToken(secret, identity, 'signer')}`
 }
 const SIGNER_WAIT_TIMEOUT = 30_000
 const CONNECT_ATTEMPTS = 8
@@ -85,13 +97,24 @@ export class WalletClient {
   private pageUrl: string | undefined
   private pageAgent: string | undefined
   private lastOpenedAt = 0
-  /** Instance field so tests can shorten the wait instead of sitting out the real one. */
+  private idleTimer: NodeJS.Timeout | null = null
+  /** 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
 
-  constructor(private relayOptions: { port?: number; token?: string } = {}) {}
+  /**
+   * `identity` is the room this client works in. Everything below it — the socket's token,
+   * the pairing link it hands out — is signed for that room, so two identities on one relay
+   * cannot see each other's pages or transactions.
+   */
+  constructor(
+    private identity: string,
+    private relayOptions: { port?: number; token?: string } = {}
+  ) {}
 
   get isRemote(): boolean {
     return Boolean(this.remoteUrl)
@@ -124,8 +147,8 @@ export class WalletClient {
     // minute to come back.
     for (let attempt = 0; attempt < CONNECT_ATTEMPTS; attempt++) {
       try {
-        await this.openSocket(url, this.remoteToken)
-        this.pairingUrl = `${this.remoteUrl}#t=${this.remoteToken}`
+        await this.openSocket(url, roomToken(this.remoteToken, this.identity, 'requester'))
+        this.pairingUrl = `${this.remoteUrl}#t=${roomToken(this.remoteToken, this.identity, 'signer')}`
         return
       } catch (error) {
         lastError = error as Error
@@ -147,23 +170,24 @@ export class WalletClient {
    * the fix would be for the higher port to hand over when a lower one answers.
    */
   private async connectLocal(): Promise<void> {
-    const token = this.relayOptions.token ?? localToken()
+    const secret = this.relayOptions.token ?? localToken()
+    const requester = roomToken(secret, this.identity, 'requester')
     const ports = this.relayOptions.port ? [this.relayOptions.port] : LOCAL_PORTS
 
     for (const port of ports) {
       try {
-        await this.openSocket(`ws://127.0.0.1:${port}`, token)
-        this.pairingUrl = pairingUrlFor(port, token)
+        await this.openSocket(`ws://127.0.0.1:${port}`, requester)
+        this.pairingUrl = pairingUrlFor(port, secret, this.identity)
         return
       } catch {
         // Nothing on this port, or something that isn't our relay — keep looking.
       }
     }
 
-    this.relay = new WalletRelay({ port: ports[0], token })
+    this.relay = new WalletRelay({ port: ports[0], token: secret })
     await this.relay.start()
-    await this.openSocket(`ws://127.0.0.1:${this.relay.getPort()}`, token)
-    this.pairingUrl = this.relay.getUrl()
+    await this.openSocket(`ws://127.0.0.1:${this.relay.getPort()}`, requester)
+    this.pairingUrl = pairingUrlFor(this.relay.getPort(), secret, this.identity)
   }
 
   /**
@@ -198,6 +222,7 @@ export class WalletClient {
         clearTimeout(timer)
         ws.off('message', onHandshake)
         this.ws = ws
+        this.rearmIdle()
         resolve()
       }
 
@@ -217,6 +242,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}`))
+        }
       })
     })
   }
@@ -249,11 +278,27 @@ export class WalletClient {
     const pending = this.pending.get(message.id)
     if (!pending) return
     this.pending.delete(message.id)
+    this.rearmIdle()
 
     if (message.success) pending.resolve(message.result)
     else pending.reject(new Error(message.error || 'Transaction failed'))
   }
 
+  /**
+   * Drop the socket, and this client, once nothing has needed it for a while. The owner of
+   * a local relay is exempt: it is the one that has to stop that relay at shutdown.
+   */
+  private rearmIdle() {
+    if (this.idleTimer) clearTimeout(this.idleTimer)
+    if (this.relay) return
+    this.idleTimer = setTimeout(() => {
+      if (this.pending.size > 0) return this.rearmIdle()
+      this.ws?.close()
+      if (clients.get(this.identity) === this) clients.delete(this.identity)
+    }, this.idleTimeout)
+    this.idleTimer.unref()
+  }
+
   /** Wait for a wallet page to connect, opening the browser first when running locally. */
   async waitForSigner(): Promise<void> {
     await this.connect()
@@ -291,11 +336,17 @@ export class WalletClient {
 
     return new Promise((resolve, reject) => {
       this.pending.set(request.id, { resolve, reject })
-      ws.send(JSON.stringify(request))
+      this.rearmIdle()
+      ws.send(JSON.stringify({ ...request, expiresAt: Date.now() + this.requestTimeout }))
 
       setTimeout(() => {
-        if (this.pending.delete(request.id)) reject(new Error('Transaction request timed out'))
-      }, REQUEST_TIMEOUT)
+        if (this.pending.delete(request.id)) {
+          this.rearmIdle()
+          // 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}`))
+        }
+      }, this.requestTimeout)
     })
   }
 
@@ -318,8 +369,11 @@ export class WalletClient {
    */
   getUrl(): string {
     if (this.pairingUrl) return this.pairingUrl
-    if (this.remoteUrl) return `${this.remoteUrl}#t=${this.remoteToken ?? ''}`
-    return `http://127.0.0.1:${LOCAL_PORTS[0]}/#t=${this.relayOptions.token ?? localToken()}`
+    if (this.remoteUrl) {
+      const token = this.remoteToken ? roomToken(this.remoteToken, this.identity, 'signer') : ''
+      return `${this.remoteUrl}#t=${token}`
+    }
+    return pairingUrlFor(LOCAL_PORTS[0], this.relayOptions.token ?? localToken(), this.identity)
   }
 
   /** A relay we do not own, or a server with no desktop, has no browser for us to open. */
@@ -388,15 +442,44 @@ export class WalletClient {
   }
 
   async stop(): Promise<void> {
+    if (this.idleTimer) clearTimeout(this.idleTimer)
     this.ws?.close()
     await this.relay?.stop()
     this.relay = null
   }
 }
 
-let client: WalletClient | null = null
+const clients = new Map<string, WalletClient>()
+
+let relayOptions: { port?: number; token?: string } = {}
+
+/**
+ * Where the relay is, for every client this process makes.
+ *
+ * A property of the deployment rather than of any one person: a hosted server runs the
+ * relay on its own port with its own secret, and each identity's client has to reach that
+ * one. Set it before anybody signs — a client that cannot find a relay starts its own,
+ * which then has nobody in it.
+ */
+export function configureWalletRelay(options: { port?: number; token?: string }): void {
+  relayOptions = options
+}
 
-export function getWalletClient(relayOptions?: { port?: number; token?: string }): WalletClient {
-  if (!client) client = new WalletClient(relayOptions)
+/**
+ * One client per identity, because everything it holds is that person's: the socket, the
+ * in-flight requests, and which page is open with which account. A single-user server has
+ * exactly one, which is every self-hosted run.
+ */
+export function getWalletClient(identity: string): WalletClient {
+  let client = clients.get(identity)
+  if (!client) {
+    client = new WalletClient(identity, relayOptions)
+    clients.set(identity, client)
+  }
   return client
 }
+
+/** Every live client, for shutdown — callers outside a tool call have no identity of their own. */
+export function allWalletClients(): WalletClient[] {
+  return [...clients.values()]
+}