web3-tools-mcp 2.0.1 → 3.0.0

package/src/wallet-client.ts

@@ -3,18 +3,23 @@ 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)
+/**
+ * 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 +90,23 @@ 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 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 +139,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 +162,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 +214,7 @@ export class WalletClient {
         clearTimeout(timer)
         ws.off('message', onHandshake)
         this.ws = ws
+        this.rearmIdle()
         resolve()
       }
 
@@ -249,11 +266,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,10 +324,14 @@ export class WalletClient {
 
     return new Promise((resolve, reject) => {
       this.pending.set(request.id, { resolve, reject })
+      this.rearmIdle()
       ws.send(JSON.stringify(request))
 
       setTimeout(() => {
-        if (this.pending.delete(request.id)) reject(new Error('Transaction request timed out'))
+        if (this.pending.delete(request.id)) {
+          this.rearmIdle()
+          reject(new Error('Transaction request timed out'))
+        }
       }, REQUEST_TIMEOUT)
     })
   }
@@ -318,8 +355,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 +428,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>()
 
-export function getWalletClient(relayOptions?: { port?: number; token?: string }): WalletClient {
-  if (!client) client = new WalletClient(relayOptions)
+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
+}
+
+/**
+ * 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()]
+}

package/src/walletconnect.ts

@@ -1,8 +1,11 @@
 import { mkdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { getClientManager } from './client.js'
+import { DEFAULT_IDENTITY } from './context.js'
 import { getKeyValueStorage } from './kv-storage.js'
+import { log } from './log.js'
 import type { ChainName } from './types.js'
 
 /**
@@ -27,6 +30,42 @@ interface Session {
   peer?: string
 }
 
+/** Sessions do not record who paired them, so the mapping is kept alongside in the same store. */
+const BINDINGS_KEY = 'web3-tools-mcp:session-identities'
+
+/**
+ * The sessions an identity may sign with.
+ *
+ * Matched by the binding recorded when the session was approved, never by the accounts it
+ * reports — a wallet states its own account list, so trusting that would let a peer claim
+ * someone else's address and be handed their signing requests.
+ *
+ * An unbound session is one paired before bindings existed. It counts only for the shared
+ * identity, which is a server with a single user; under a real identity it belongs to
+ * nobody rather than to whoever asks first.
+ */
+export function ownedSessions<T extends { topic: string }>(live: T[], bindings: Record<string, string>, identity: string): T[] {
+  return live.filter((s) => bindings[s.topic] === identity || (identity === DEFAULT_IDENTITY && !bindings[s.topic]))
+}
+
+/**
+ * Bindings with no session behind them any more.
+ *
+ * An empty session list yields nothing: a store that has not hydrated looks exactly like one
+ * with no sessions, and clearing every binding would strand wallets that are still paired.
+ */
+export function orphanedBindings(live: { topic: string }[], bindings: Record<string, string>): string[] {
+  if (live.length === 0) return []
+  const known = new Set(live.map((session) => session.topic))
+  return Object.keys(bindings).filter((topic) => !known.has(topic))
+}
+
+/** What was paired before and is not paired now — a wallet that ended its own session. */
+export function droppedSessions<T extends { topic: string }>(before: T[], after: { topic: string }[]): T[] {
+  const live = new Set(after.map((session) => session.topic))
+  return before.filter((session) => !live.has(session.topic))
+}
+
 const METHODS = ['eth_sendTransaction', 'personal_sign', 'eth_signTypedData_v4']
 const EVENTS = ['chainChanged', 'accountsChanged']
 const APPROVAL_TIMEOUT = 300_000
@@ -36,9 +75,7 @@ const APPROVAL_TIMEOUT = 300_000
  * a local one is only reachable from the machine it runs on, and says so.
  */
 function serverUrl(): string {
-  if (process.env.MCP_PUBLIC_URL) return process.env.MCP_PUBLIC_URL.replace(/\/$/, '')
-  if (process.env.MCP_HTTP_PORT) return `http://localhost:${process.env.MCP_HTTP_PORT}`
-  return 'http://localhost'
+  return process.env.MCP_PUBLIC_URL?.replace(/\/$/, '') ?? 'http://localhost'
 }
 
 function storePath(): string {
@@ -53,6 +90,8 @@ export class PhoneSigner {
   private pairing: { uri: string; expiresAt: number } | undefined
   /** Label shown in the wallet; whoever is driving this server says who they are. */
   private agent: string | undefined
+  /** The last edit of the bindings key; the next one queues behind it. */
+  private bindingsEdit: Promise<unknown> = Promise.resolve()
 
   constructor(private projectId: string) {}
 
@@ -86,26 +125,100 @@ export class PhoneSigner {
     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
+  /**
+   * Who each session belongs to, kept in the client's own store so it lands in the file or
+   * in Redis exactly as the sessions themselves do.
+   */
+  private async bindings(): Promise<Record<string, string>> {
+    return (await this.client?.core.storage.getItem<Record<string, string>>(BINDINGS_KEY)) ?? {}
+  }
+
+  /**
+   * All bindings live under one key, so an edit is a read-modify-write — and two approvals
+   * settling together would each read the same map and the second would erase the first.
+   * Edits queue behind each other instead.
+   *
+   * ponytail: serialised per process only. Several server processes on one Redis still
+   * race; one key per topic would end that.
+   */
+  private updateBindings(edit: (bindings: Record<string, string>) => void): Promise<void> {
+    const next = this.bindingsEdit.then(async () => {
+      const bindings = await this.bindings()
+      edit(bindings)
+      await this.client?.core.storage.setItem(BINDINGS_KEY, bindings)
+    })
+    this.bindingsEdit = next.catch(() => {})
+    return next
+  }
+
+  private bind(topic: string, identity: string): Promise<void> {
+    return this.updateBindings((bindings) => {
+      bindings[topic] = identity
+    })
+  }
+
+  /**
+   * Some wallets keep one session per site, so approving a second pairing in the same app
+   * ends the first — the session vanishes from the store and the binding is left pointing at
+   * nothing. Worth saying out loud: `pair_phone_wallet` has just listed that wallet as still
+   * paired, and the next `wallet_status` will quietly show one fewer.
+   */
+  private async reportReplaced(identity: string, before: Session[]): Promise<void> {
+    const dropped = droppedSessions(before, await this.sessions(identity))
+    if (dropped.length === 0) return
+
+    for (const session of dropped) {
+      log(
+        'warning',
+        'WalletConnect',
+        `${session.peer ?? 'A wallet'} ended its earlier pairing for ${session.accounts[0] ?? 'an account'} when this one was approved — ` +
+          'it keeps one session per site. Pair a different wallet app to hold both at once.'
+      )
     }
+
+    await this.sweepBindings()
   }
 
-  async isPaired(): Promise<boolean> {
-    return Boolean(await this.session())
+  /**
+   * Bindings outlive the sessions they point at, so they accumulate. Swept here rather than
+   * on every read: a pairing has just settled, which is the one moment the session store is
+   * known to be populated.
+   */
+  private async sweepBindings(): Promise<void> {
+    const orphans = orphanedBindings(this.client?.session.getAll() ?? [], await this.bindings())
+    if (orphans.length === 0) return
+
+    await this.updateBindings((bindings) => {
+      for (const topic of orphans) delete bindings[topic]
+    })
+    log('info', 'WalletConnect', `Cleared ${orphans.length} binding(s) whose session is gone`)
+  }
+
+  /** Every session this identity owns, live or not — what disconnecting should sweep. */
+  private async owned(identity: string) {
+    await this.start()
+    return ownedSessions(this.client?.session.getAll() ?? [], await this.bindings(), identity)
+  }
+
+  /**
+   * One of this identity's paired wallets.
+   *
+   * `account` picks between them when more than one is paired; without it the most recent
+   * wins, which is the only one most people have. Selecting by address is safe here in a
+   * way that *identifying* by address would not be: the candidates are already narrowed to
+   * sessions this identity was bound to when they were approved, so a wallet claiming an
+   * address it does not hold can only reach its own owner.
+   */
+  async session(identity: string = DEFAULT_IDENTITY, account?: string): Promise<Session | undefined> {
+    const paired = await this.sessions(identity)
+    if (!account) return paired[paired.length - 1]
+
+    const wanted = account.toLowerCase()
+    return paired.find((session) => session.accounts.some((a) => a.toLowerCase() === wanted))
+  }
+
+  async isPaired(identity?: string): Promise<boolean> {
+    return Boolean(await this.session(identity))
   }
 
   /**
@@ -113,22 +226,41 @@ export class PhoneSigner {
    * 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[], agent?: string): Promise<string> {
-    // Metadata is fixed when the client starts, so a new label needs a new client. Only
-    // safe while nothing is connected — an existing session owns the old client.
-    if (agent && agent !== this.agent && this.client && this.client.session.getAll().length === 0) {
-      // Close it rather than dropping the reference. Two clients sharing one storage
-      // directory overwrite each other's subscription record, and the one that loses stops
-      // receiving replies on its own session — a signing request then reaches the wallet,
-      // gets approved, and the answer is published where nobody is listening.
-      await this.client.core.relayer.transportClose().catch(() => {})
-      this.client = undefined
-    }
-    if (agent) this.agent = agent
+  /**
+   * Name who is asking, for the wallet's approval dialog. Takes effect only before the
+   * client starts, because WalletConnect fixes metadata at init — call it first.
+   *
+   * There is deliberately no way to relabel a running client. Replacing it leaves the old
+   * one's engine alive, and its heartbeat sweeps "orphaned" subscriptions against its own,
+   * empty session list — unsubscribing the new session's topic two seconds after it
+   * settles, so every reply the wallet sends goes to a topic nobody is listening on. A
+   * stale name in the dialog is a far smaller cost than signing that silently hangs.
+   */
+  /**
+   * Hand every session one identity owns to another. A login pairs before anybody is known,
+   * under a placeholder, and the wallet it proved becomes that person's to sign with.
+   */
+  async rebind(from: string, to: string): Promise<void> {
+    await this.start()
+    await this.updateBindings((bindings) => {
+      for (const [topic, identity] of Object.entries(bindings)) {
+        if (identity === from) bindings[topic] = to
+      }
+    })
+  }
+
+  nameAgent(agent?: string): void {
+    if (agent && !this.client) this.agent = agent
+  }
 
+  async pair(chains: ChainName[], identity: string = DEFAULT_IDENTITY): Promise<string> {
     await this.start()
+    log('info', 'WalletConnect', `Pairing as "${this.agent ?? 'default name'}" for ${chains.length} chain(s)`)
     if (!this.client) throw new Error('WalletConnect failed to start')
 
+    // What this identity had before, so the approval can tell whether the wallet kept it.
+    const before = await this.sessions(identity)
+
     const clientManager = getClientManager()
     const eip155 = chains.map((chain) => `eip155:${clientManager.getChainId(chain)}`)
 
@@ -142,16 +274,37 @@ export class PhoneSigner {
     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))
+      .then(async (session) => {
+        // Recorded as the session settles: whoever asked for this pairing owns it.
+        await this.bind(session.topic, identity)
+        log('info', 'WalletConnect', `Paired with ${session.peer?.metadata?.name ?? 'a wallet'}`)
+        await this.reportReplaced(identity, before)
+      })
+      .catch((error) => log('warning', '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')
+  /** Send a request to one of this identity's wallets. Throws if the chain is outside the session. */
+  async request(
+    chain: ChainName,
+    method: string,
+    params: unknown[],
+    target: {
+      identity?: string
+      account?: string
+      /**
+       * Called once the request is with the wallet and only a human is left. Everything that
+       * can fail quickly — no session, a chain this one never approved — has already thrown
+       * by then, so the caller can stop waiting without hiding a real error.
+       */
+      onWaiting?: () => void
+    } = {}
+  ): Promise<unknown> {
+    const session = await this.session(target.identity, target.account)
+    if (!session || !this.client) {
+      throw new Error(target.account ? `No phone wallet paired for account ${target.account}` : 'No phone wallet paired')
+    }
 
     const chainId = getClientManager().getChainId(chain)
     if (!session.chains.includes(chainId)) {
@@ -160,52 +313,92 @@ export class PhoneSigner {
       )
     }
 
-    return this.client.request({
-      topic: session.topic,
-      chainId: `eip155:${chainId}`,
-      request: { method, params }
-    })
+    const started = Date.now()
+    log(
+      'info',
+      'WalletConnect',
+      `→ ${method} on ${chain}, session ${session.topic.slice(0, 8)}, waiting for ${session.peer ?? 'wallet'}`
+    )
+    try {
+      const answer = this.client.request({
+        topic: session.topic,
+        chainId: `eip155:${chainId}`,
+        request: { method, params }
+      })
+
+      // Neither MetaMask nor Rabby pushes a notification, so nobody is going to notice this
+      // in the next few seconds unless they already had the wallet open.
+      target.onWaiting?.()
+
+      const result = await answer
+      log('info', 'WalletConnect', `← ${method} answered in ${Date.now() - started}ms`)
+      return result
+    } catch (error) {
+      const reason = (error as { message?: string })?.message ?? String(error)
+      log('warning', 'WalletConnect', `← ${method} failed after ${Date.now() - started}ms: ${reason}`)
+      throw error
+    }
   }
 
-  /** Every live session, not just the one that would be used for signing. */
-  async sessions(): Promise<Session[]> {
-    await this.start()
-    return (this.client?.session.getAll() ?? []).map((session) => ({
-      topic: session.topic,
-      accounts: [...new Set((session.namespaces.eip155?.accounts ?? []).map((a) => a.split(':')[2] as string))],
-      chains: [...new Set((session.namespaces.eip155?.accounts ?? []).map((a) => Number(a.split(':')[1])))],
-      peer: session.peer?.metadata?.name
-    }))
+  /** Every wallet this identity can currently sign with, oldest pairing first. */
+  async sessions(identity: string = DEFAULT_IDENTITY): Promise<Session[]> {
+    const live = (await this.owned(identity)).filter((session) => session.expiry * 1000 > Date.now())
+    return live.map((session) => {
+      // "eip155:8453:0xabc…" → address / chain id
+      const accounts = session.namespaces.eip155?.accounts ?? []
+      return {
+        topic: session.topic,
+        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
+      }
+    })
   }
 
   /**
-   * Disconnect everything: sessions, and the pairings underneath them. Each pairing
-   * attempt leaves one behind whether or not a wallet ever approved it, so they
-   * accumulate quietly in the store.
+   * Disconnect one of this identity's wallets, or all of them when no account is named.
+   *
+   * Pairings underneath are swept only once no session is left at all. Each pairing attempt
+   * leaves one behind whether or not a wallet ever approved it, so they accumulate quietly —
+   * but a pairing does not record who made it, so dropping them while anyone still has a
+   * session could take somebody else's with it.
    */
-  async disconnectAll(): Promise<{ sessions: number; pairings: number }> {
+  async disconnect(identity: string = DEFAULT_IDENTITY, account?: string): Promise<{ sessions: number; pairings: number }> {
     await this.start()
     if (!this.client) return { sessions: 0, pairings: 0 }
 
-    const sessions = this.client.session.getAll()
-    for (const session of sessions) {
+    let topics: Set<string>
+    if (account) {
+      // Same rule that picks a wallet to sign with, so you can drop exactly what you chose.
+      const match = await this.session(identity, account)
+      if (!match) throw new Error(`No paired wallet holds ${account}`)
+      topics = new Set([match.topic])
+    } else {
+      // Expired sessions included: they are still this identity's to clean up.
+      topics = new Set((await this.owned(identity)).map((session) => session.topic))
+    }
+
+    for (const topic of topics) {
       await this.client
-        .disconnect({ topic: session.topic, reason: { code: 6000, message: 'User disconnected' } })
-        .catch((error) => console.error('[WalletConnect] Could not disconnect a session:', error.message))
+        .disconnect({ topic, reason: { code: 6000, message: 'User disconnected' } })
+        .catch((error) => log('warning', 'WalletConnect', `Could not disconnect a session: ${error.message}`))
     }
 
+    await this.updateBindings((bindings) => {
+      for (const topic of topics) delete bindings[topic]
+    })
+
+    const remaining = this.client.session.getAll().length
+    if (remaining > 0) return { sessions: topics.size, pairings: 0 }
+
     const pairings = this.client.core.pairing.getPairings()
     for (const pairing of pairings) {
       await this.client.core.pairing
         .disconnect({ topic: pairing.topic })
-        .catch((error) => console.error('[WalletConnect] Could not drop a pairing:', error.message))
+        .catch((error) => log('warning', 'WalletConnect', `Could not drop a pairing: ${error.message}`))
     }
 
-    return { sessions: sessions.length, pairings: pairings.length }
-  }
-
-  async unpair(): Promise<void> {
-    await this.disconnectAll()
+    return { sessions: topics.size, pairings: pairings.length }
   }
 }
 
@@ -263,6 +456,33 @@ export async function pairingLinks(projectId: string, uri: string, search?: stri
   )
 }
 
+// qrcode-terminal's own encoder, already a dependency for the chat QR; it ships untyped.
+const require = createRequire(import.meta.url)
+const QRCode = require('qrcode-terminal/vendor/QRCode') as new (
+  typeNumber: number,
+  level: number
+) => { addData(text: string): void; make(): void; getModuleCount(): number; isDark(row: number, col: number): boolean }
+const LOW_CORRECTION = 1
+
+/** A QR as SVG, for a page to show. The terminal QR is only legible in monospace. */
+export function qrSvg(text: string): string {
+  const qr = new QRCode(-1, LOW_CORRECTION)
+  qr.addData(text)
+  qr.make()
+
+  const size = qr.getModuleCount()
+  const quiet = 4
+  let path = ''
+  for (let row = 0; row < size; row++) {
+    for (let col = 0; col < size; col++) {
+      if (qr.isDark(row, col)) path += `M${col + quiet} ${row + quiet}h1v1h-1z`
+    }
+  }
+
+  const box = size + quiet * 2
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${box} ${box}" shape-rendering="crispEdges"><rect width="${box}" height="${box}" fill="#fff"/><path d="${path}"/></svg>`
+}
+
 let signer: PhoneSigner | null = null
 
 /** Configured only when a WalletConnect project id is present. */

package/dist/tools/advanced.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../../src/tools/advanced.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMvB,wBAqZC"}