feat: add methods.{include|exclude} on transport options (#3238)

* feat: add `methods.{include|exclude}` on transport options

* docs: add

* chore: changeset

* u

Author: jxom

.changeset/shaggy-taxis-dance.md

@@ -0,0 +1,5 @@
+---
+"viem": patch
+---
+
+Added `methods` property to `http`, `ipc`, and `webSocket` transports to include or exclude RPC methods from being executed.

package.json

@@ -121,7 +121,7 @@
     {
       "name": "import { createClient, http } from 'viem'",
       "path": "./src/_esm/index.js",
-      "limit": "6.5 kB",
+      "limit": "6.6 kB",
       "import": "{ createClient, http }"
     },
     {

site/pages/docs/clients/transports/http.md

@@ -156,6 +156,22 @@ const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
 })
 ```
 
+### methods (optional)
+
+- **Type:** `{ include?: string[], exclude?: string[] }`
+
+Methods to include or exclude from sending RPC requests.
+
+```ts twoslash
+import { http } from 'viem'
+// ---cut---
+const transport = http('https://eth-mainnet.g.alchemy.com/v2/...', {
+  methods: {
+    include: ['eth_sendTransaction', 'eth_signTypedData_v4'],
+  },
+})
+```
+
 ### name (optional)
 
 - **Type:** `string`

site/pages/docs/clients/transports/ipc.md

@@ -50,6 +50,22 @@ const transport = ipc('/tmp/reth.ipc', {
 })
 ```
 
+### methods (optional)
+
+- **Type:** `{ include?: string[], exclude?: string[] }`
+
+Methods to include or exclude from sending RPC requests.
+
+```ts twoslash
+import { ipc } from 'viem/node'
+// ---cut---
+const transport = ipc('/tmp/reth.ipc', {
+  methods: {
+    include: ['eth_sendTransaction', 'eth_signTypedData_v4'],
+  },
+})
+```
+
 ### name (optional)
 
 - **Type:** `string`

site/pages/docs/clients/transports/websocket.md

@@ -68,6 +68,22 @@ const transport = webSocket('wss://eth-mainnet.g.alchemy.com/v2/...', {
 })
 ```
 
+### methods (optional)
+
+- **Type:** `{ include?: string[], exclude?: string[] }`
+
+Methods to include or exclude from sending RPC requests.
+
+```ts twoslash
+import { webSocket } from 'viem'
+// ---cut---
+const transport = webSocket('wss://eth-mainnet.g.alchemy.com/v2/...', {
+  methods: {
+    include: ['eth_sendTransaction', 'eth_signTypedData_v4'],
+  },
+})
+```
+
 ### name (optional)
 
 - **Type:** `string`

src/clients/transports/createTransport.ts

@@ -1,6 +1,7 @@
 import type { ErrorType } from '../../errors/utils.js'
 import type { Chain } from '../../types/chain.js'
 import type { EIP1193RequestFn } from '../../types/eip1193.js'
+import type { OneOf } from '../../types/utils.js'
 import { buildRequest } from '../../utils/buildRequest.js'
 import { uid as uid_ } from '../../utils/uid.js'
 import type { ClientConfig } from '../createClient.js'
@@ -13,6 +14,17 @@ export type TransportConfig<
   name: string
   /** The key of the transport. */
   key: string
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?:
+    | OneOf<
+        | {
+            include?: string[] | undefined
+          }
+        | {
+            exclude?: string[] | undefined
+          }
+      >
+    | undefined
   /** The JSON-RPC request function that matches the EIP-1193 request spec. */
   request: eip1193RequestFn
   /** The base delay (in ms) between retries. */
@@ -53,6 +65,7 @@ export function createTransport<
 >(
   {
     key,
+    methods,
     name,
     request,
     retryCount = 3,
@@ -73,7 +86,7 @@ export function createTransport<
       timeout,
       type,
     },
-    request: buildRequest(request, { retryCount, retryDelay, uid }),
+    request: buildRequest(request, { methods, retryCount, retryDelay, uid }),
     value,
   }
 }

src/clients/transports/custom.ts

@@ -11,6 +11,8 @@ type EthereumProvider = { request(...args: any): Promise<any> }
 export type CustomTransportConfig = {
   /** The key of the transport. */
   key?: TransportConfig['key'] | undefined
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?: TransportConfig['methods'] | undefined
   /** The name of the transport. */
   name?: TransportConfig['name'] | undefined
   /** The max number of times to retry. */
@@ -34,10 +36,16 @@ export function custom<provider extends EthereumProvider>(
   provider: provider,
   config: CustomTransportConfig = {},
 ): CustomTransport {
-  const { key = 'custom', name = 'Custom Provider', retryDelay } = config
+  const {
+    key = 'custom',
+    methods,
+    name = 'Custom Provider',
+    retryDelay,
+  } = config
   return ({ retryCount: defaultRetryCount }) =>
     createTransport({
       key,
+      methods,
       name,
       request: provider.request.bind(provider),
       retryCount: config.retryCount ?? defaultRetryCount,

src/clients/transports/fallback.test.ts

@@ -216,6 +216,57 @@ describe('request', () => {
     `)
   })
 
+  test('methods.exclude', async () => {
+    const server1 = await createHttpServer((_req, res) => {
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+      })
+      res.end(JSON.stringify({ result: '0x1' }))
+    })
+    const server2 = await createHttpServer((_req, res) => {
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+      })
+      res.end(JSON.stringify({ result: '0x2' }))
+    })
+
+    const transport = fallback([
+      http(server1.url, { methods: { exclude: ['eth_a'] } }),
+      http(server2.url),
+    ])({
+      chain: localhost,
+    })
+
+    expect(await transport.request({ method: 'eth_a' })).toBe('0x2')
+    expect(await transport.request({ method: 'eth_b' })).toBe('0x1')
+  })
+
+  test('methods.include', async () => {
+    const server1 = await createHttpServer((_req, res) => {
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+      })
+      res.end(JSON.stringify({ result: '0x1' }))
+    })
+    const server2 = await createHttpServer((_req, res) => {
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+      })
+      res.end(JSON.stringify({ result: '0x2' }))
+    })
+
+    const transport = fallback([
+      http(server1.url, { methods: { include: ['eth_a', 'eth_b'] } }),
+      http(server2.url),
+    ])({
+      chain: localhost,
+    })
+
+    expect(await transport.request({ method: 'eth_a' })).toBe('0x1')
+    expect(await transport.request({ method: 'eth_b' })).toBe('0x1')
+    expect(await transport.request({ method: 'eth_c' })).toBe('0x2')
+  })
+
   test('error (rpc)', async () => {
     let count = 0
     const server1 = await createHttpServer((_req, res) => {

src/clients/transports/http.test.ts

@@ -389,6 +389,53 @@ describe('request', () => {
     await server.close()
   })
 
+  test('behavior: methods.exclude', async () => {
+    const server = await createHttpServer((_, res) => {
+      res.end(JSON.stringify({ result: '0x1' }))
+    })
+
+    const transport = http(server.url, {
+      key: 'jsonRpc',
+      name: 'JSON RPC',
+      methods: { exclude: ['eth_a'] },
+    })({ chain: localhost })
+
+    await transport.request({ method: 'eth_b' })
+
+    await expect(() =>
+      transport.request({ method: 'eth_a' }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`
+      [MethodNotSupportedRpcError: Method "eth_a" is not supported.
+
+      Details: method not supported
+      Version: [email protected]]
+    `)
+  })
+
+  test('behavior: methods.include', async () => {
+    const server = await createHttpServer((_, res) => {
+      res.end(JSON.stringify({ result: '0x1' }))
+    })
+
+    const transport = http(server.url, {
+      key: 'jsonRpc',
+      name: 'JSON RPC',
+      methods: { include: ['eth_a', 'eth_b'] },
+    })({ chain: localhost })
+
+    await transport.request({ method: 'eth_a' })
+    await transport.request({ method: 'eth_b' })
+
+    await expect(() =>
+      transport.request({ method: 'eth_c' }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`
+      [MethodNotSupportedRpcError: Method "eth_c" is not supported.
+
+      Details: method not supported
+      Version: [email protected]]
+    `)
+  })
+
   test('behavior: retryCount', async () => {
     let retryCount = -1
     const server = await createHttpServer((_req, res) => {

src/clients/transports/http.ts

@@ -43,6 +43,8 @@ export type HttpTransportConfig = {
   onFetchResponse?: HttpRpcClientOptions['onResponse'] | undefined
   /** The key of the HTTP transport. */
   key?: TransportConfig['key'] | undefined
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?: TransportConfig['methods'] | undefined
   /** The name of the HTTP transport. */
   name?: TransportConfig['name'] | undefined
   /** The max number of times to retry. */
@@ -78,6 +80,7 @@ export function http(
     batch,
     fetchOptions,
     key = 'http',
+    methods,
     name = 'HTTP JSON-RPC',
     onFetchRequest,
     onFetchResponse,
@@ -101,6 +104,7 @@ export function http(
     return createTransport(
       {
         key,
+        methods,
         name,
         async request({ method, params }) {
           const body = { method, params }