viem 2.4.1 → 2.5.0

package/clients/transports/http.ts

@@ -4,8 +4,12 @@ import {
   type UrlRequiredErrorType,
 } from '../../errors/transport.js'
 import type { ErrorType } from '../../errors/utils.js'
+import type { RpcRequest } from '../../types/rpc.js'
 import { createBatchScheduler } from '../../utils/promise/createBatchScheduler.js'
-import { type HttpOptions, type RpcRequest, rpc } from '../../utils/rpc.js'
+import {
+  type HttpRpcClientOptions,
+  getHttpRpcClient,
+} from '../../utils/rpc/http.js'
 
 import {
   type CreateTransportErrorType,
@@ -31,7 +35,7 @@ export type HttpTransportConfig = {
    * Request configuration to pass to `fetch`.
    * @link https://developer.mozilla.org/en-US/docs/Web/API/fetch
    */
-  fetchOptions?: HttpOptions['fetchOptions']
+  fetchOptions?: HttpRpcClientOptions['fetchOptions']
   /** The key of the HTTP transport. */
   key?: TransportConfig['key']
   /** The name of the HTTP transport. */
@@ -79,6 +83,9 @@ export function http(
     const timeout = timeout_ ?? config.timeout ?? 10_000
     const url_ = url || chain?.rpcUrls.default.http[0]
     if (!url_) throw new UrlRequiredError()
+
+    const rpcClient = getHttpRpcClient(url_, { fetchOptions, timeout })
+
     return createTransport(
       {
         key,
@@ -93,10 +100,8 @@ export function http(
               return requests.length > batchSize
             },
             fn: (body: RpcRequest[]) =>
-              rpc.http(url_, {
+              rpcClient.request({
                 body,
-                fetchOptions,
-                timeout,
               }),
             sort: (a, b) => a.id - b.id,
           })
@@ -104,7 +109,11 @@ export function http(
           const fn = async (body: RpcRequest) =>
             batch
               ? schedule(body)
-              : [await rpc.http(url_, { body, fetchOptions, timeout })]
+              : [
+                  await rpcClient.request({
+                    body,
+                  }),
+                ]
 
           const [{ error, result }] = await fn(body)
           if (error)

package/clients/transports/ipc.ts

@@ -0,0 +1,144 @@
+import { RpcRequestError } from '../../errors/request.js'
+import { type UrlRequiredErrorType } from '../../errors/transport.js'
+import type { ErrorType } from '../../errors/utils.js'
+import type { Hash } from '../../types/misc.js'
+import type { RpcResponse } from '../../types/rpc.js'
+import { type IpcRpcClient, getIpcRpcClient } from '../../utils/rpc/ipc.js'
+import {
+  type CreateTransportErrorType,
+  type Transport,
+  type TransportConfig,
+  createTransport,
+} from './createTransport.js'
+
+type IpcTransportSubscribeParameters = {
+  onData: (data: RpcResponse) => void
+  onError?: (error: any) => void
+}
+
+type IpcTransportSubscribeReturnType = {
+  subscriptionId: Hash
+  unsubscribe: () => Promise<RpcResponse<boolean>>
+}
+
+type IpcTransportSubscribe = {
+  subscribe(
+    args: IpcTransportSubscribeParameters & {
+      /**
+       * @description Add information about compiled contracts
+       * @link https://hardhat.org/hardhat-network/docs/reference#hardhat_addcompilationresult
+       */
+      params: ['newHeads']
+    },
+  ): Promise<IpcTransportSubscribeReturnType>
+}
+
+export type IpcTransportConfig = {
+  /** The key of the Ipc transport. */
+  key?: TransportConfig['key']
+  /** The name of the Ipc transport. */
+  name?: TransportConfig['name']
+  /** The max number of times to retry. */
+  retryCount?: TransportConfig['retryCount']
+  /** The base delay (in ms) between retries. */
+  retryDelay?: TransportConfig['retryDelay']
+  /** The timeout (in ms) for async Ipc requests. Default: 10_000 */
+  timeout?: TransportConfig['timeout']
+}
+
+export type IpcTransport = Transport<
+  'ipc',
+  {
+    getRpcClient(): Promise<IpcRpcClient>
+    subscribe: IpcTransportSubscribe['subscribe']
+  }
+>
+
+export type IpcTransportErrorType =
+  | CreateTransportErrorType
+  | UrlRequiredErrorType
+  | ErrorType
+
+/**
+ * @description Creates an IPC transport that connects to a JSON-RPC API.
+ */
+export function ipc(
+  path: string,
+  config: IpcTransportConfig = {},
+): IpcTransport {
+  const { key = 'ipc', name = 'IPC JSON-RPC', retryDelay } = config
+  return ({ retryCount: retryCount_, timeout: timeout_ }) => {
+    const retryCount = config.retryCount ?? retryCount_
+    const timeout = timeout_ ?? config.timeout ?? 10_000
+    return createTransport(
+      {
+        key,
+        name,
+        async request({ method, params }) {
+          const body = { method, params }
+          const rpcClient = await getIpcRpcClient(path)
+          const { error, result } = await rpcClient.requestAsync({
+            body,
+            timeout,
+          })
+          if (error)
+            throw new RpcRequestError({
+              body,
+              error,
+              url: path,
+            })
+          return result
+        },
+        retryCount,
+        retryDelay,
+        timeout,
+        type: 'ipc',
+      },
+      {
+        getRpcClient() {
+          return getIpcRpcClient(path)
+        },
+        async subscribe({ params, onData, onError }: any) {
+          const rpcClient = await getIpcRpcClient(path)
+          const { result: subscriptionId } = await new Promise<any>(
+            (resolve, reject) =>
+              rpcClient.request({
+                body: {
+                  method: 'eth_subscribe',
+                  params,
+                },
+                onResponse(response) {
+                  if (response.error) {
+                    reject(response.error)
+                    onError?.(response.error)
+                    return
+                  }
+
+                  if (typeof response.id === 'number') {
+                    resolve(response)
+                    return
+                  }
+                  if (response.method !== 'eth_subscription') return
+                  onData(response.params)
+                },
+              }),
+          )
+          return {
+            subscriptionId,
+            async unsubscribe() {
+              return new Promise<any>((resolve) =>
+                rpcClient.request({
+                  body: {
+                    method: 'eth_unsubscribe',
+                    params: [subscriptionId],
+                  },
+                  onResponse: resolve,
+                }),
+              )
+            },
+          }
+        },
+      },
+    )
+  }
+}

package/clients/transports/webSocket.ts

@@ -5,7 +5,10 @@ import {
 } from '../../errors/transport.js'
 import type { ErrorType } from '../../errors/utils.js'
 import type { Hash } from '../../types/misc.js'
-import { type RpcResponse, getSocket, rpc } from '../../utils/rpc.js'
+import type { RpcResponse } from '../../types/rpc.js'
+import { getSocket } from '../../utils/rpc/compat.js'
+import type { SocketRpcClient } from '../../utils/rpc/socket.js'
+import { getWebSocketRpcClient } from '../../utils/rpc/webSocket.js'
 import {
   type CreateTransportErrorType,
   type Transport,
@@ -51,7 +54,11 @@ export type WebSocketTransportConfig = {
 export type WebSocketTransport = Transport<
   'webSocket',
   {
+    /**
+     * @deprecated use `getRpcClient` instead.
+     */
     getSocket(): Promise<WebSocket>
+    getRpcClient(): Promise<SocketRpcClient<WebSocket>>
     subscribe: WebSocketTransportSubscribe['subscribe']
   }
 >
@@ -81,8 +88,8 @@ export function webSocket(
         name,
         async request({ method, params }) {
           const body = { method, params }
-          const socket = await getSocket(url_)
-          const { error, result } = await rpc.webSocketAsync(socket, {
+          const rpcClient = await getWebSocketRpcClient(url_)
+          const { error, result } = await rpcClient.requestAsync({
             body,
             timeout,
           })
@@ -103,11 +110,14 @@ export function webSocket(
         getSocket() {
           return getSocket(url_)
         },
+        getRpcClient() {
+          return getWebSocketRpcClient(url_)
+        },
         async subscribe({ params, onData, onError }: any) {
-          const socket = await getSocket(url_)
+          const rpcClient = await getWebSocketRpcClient(url_)
           const { result: subscriptionId } = await new Promise<any>(
             (resolve, reject) =>
-              rpc.webSocket(socket, {
+              rpcClient.request({
                 body: {
                   method: 'eth_subscribe',
                   params,
@@ -132,7 +142,7 @@ export function webSocket(
             subscriptionId,
             async unsubscribe() {
               return new Promise<any>((resolve) =>
-                rpc.webSocket(socket, {
+                rpcClient.request({
                   body: {
                     method: 'eth_unsubscribe',
                     params: [subscriptionId],

package/errors/version.ts

@@ -1 +1 @@
-export const version = '2.4.1'
+export const version = '2.5.0'

package/node/index.ts

@@ -0,0 +1,11 @@
+export {
+  type IpcTransport,
+  type IpcTransportConfig,
+  type IpcTransportErrorType,
+  ipc,
+} from '../clients/transports/ipc.js'
+
+export {
+  type IpcRpcClient,
+  getIpcRpcClient,
+} from '../utils/rpc/ipc.js'

package/node/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../_types/node/index.d.ts",
+  "module": "../_esm/node/index.js",
+  "main": "../_cjs/node/index.js"
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "viem",
   "description": "TypeScript Interface for Ethereum",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",
@@ -52,6 +52,11 @@
       "import": "./_esm/ens/index.js",
       "default": "./_cjs/ens/index.js"
     },
+    "./node": {
+      "types": "./_types/node/index.d.ts",
+      "import": "./_esm/node/index.js",
+      "default": "./_cjs/node/index.js"
+    },
     "./op-stack": {
       "types": "./_types/chains/opStack/index.d.ts",
       "import": "./_esm/chains/opStack/index.js",
@@ -94,6 +99,9 @@
       "ens": [
         "./_types/ens/index.d.ts"
       ],
+      "node": [
+        "./_types/node/index.d.ts"
+      ],
       "op-stack": [
         "./_types/chains/opStack/index.d.ts"
       ],

package/types/rpc.ts

@@ -57,3 +57,47 @@ export type RpcTransaction<TPending extends boolean = boolean> = UnionOmit<
   >,
   'typeHex'
 >
+
+type SuccessResult<T> = {
+  method?: never
+  result: T
+  error?: never
+}
+type ErrorResult<T> = {
+  method?: never
+  result?: never
+  error: T
+}
+type Subscription<TResult, TError> = {
+  method: 'eth_subscription'
+  error?: never
+  result?: never
+  params: {
+    subscription: string
+  } & (
+    | {
+        result: TResult
+        error?: never
+      }
+    | {
+        result?: never
+        error: TError
+      }
+  )
+}
+
+export type RpcRequest = {
+  jsonrpc?: '2.0'
+  method: string
+  params?: any
+  id?: number
+}
+
+export type RpcResponse<TResult = any, TError = any> = {
+  jsonrpc: `${number}`
+  id: number
+} & (
+  | SuccessResult<TResult>
+  | ErrorResult<TError>
+  | Subscription<TResult, TError>
+)

package/utils/buildRequest.ts

@@ -57,7 +57,7 @@ import type {
 } from '../types/eip1193.js'
 import type { CreateBatchSchedulerErrorType } from './promise/createBatchScheduler.js'
 import { type WithRetryErrorType, withRetry } from './promise/withRetry.js'
-import type { GetSocketErrorType } from './rpc.js'
+import type { GetSocketRpcClientErrorType } from './rpc/socket.js'
 
 export type RequestErrorType =
   | ChainDisconnectedErrorType
@@ -67,7 +67,7 @@ export type RequestErrorType =
   | InvalidInputRpcErrorType
   | InvalidParamsRpcErrorType
   | InvalidRequestRpcErrorType
-  | GetSocketErrorType
+  | GetSocketRpcClientErrorType
   | JsonRpcVersionUnsupportedErrorType
   | LimitExceededRpcErrorType
   | MethodNotFoundRpcErrorType

package/utils/index.ts

@@ -32,13 +32,6 @@ export {
 export { arrayRegex, bytesRegex, integerRegex } from './regex.js'
 
 export {
-  type GetSocketErrorType,
-  type HttpErrorType,
-  type HttpOptions,
-  type HttpReturnType,
-  type RpcRequest,
-  type RpcResponse,
-  type Socket,
   type WebSocketAsyncErrorType,
   type WebSocketAsyncOptions,
   type WebSocketAsyncReturnType,
@@ -47,7 +40,25 @@ export {
   type WebSocketReturnType,
   getSocket,
   rpc,
-} from './rpc.js'
+} from './rpc/compat.js'
+export {
+  type HttpRpcClient,
+  type HttpRpcClientOptions,
+  type HttpRequestErrorType,
+  type HttpRequestParameters,
+  type HttpRequestReturnType,
+  getHttpRpcClient,
+} from './rpc/http.js'
+export {
+  type GetSocketRpcClientErrorType,
+  type GetSocketRpcClientParameters,
+  type GetSocketParameters,
+  type Socket,
+  type SocketRpcClient,
+  getSocketRpcClient,
+  socketClientCache,
+} from './rpc/socket.js'
+export { getWebSocketRpcClient } from './rpc/webSocket.js'
 export { type StringifyErrorType, stringify } from './stringify.js'
 export {
   type DomainSeparatorErrorType,

package/utils/rpc/compat.ts

@@ -0,0 +1,117 @@
+// TODO(v3): This file is here for backwards compatibility, and to prevent breaking changes.
+// These APIs will be removed in v3.
+
+/* c8 ignore start */
+import {
+  type TimeoutErrorType,
+  WebSocketRequestError,
+} from '../../errors/request.js'
+import type { ErrorType } from '../../errors/utils.js'
+import type { RpcResponse } from '../../types/rpc.js'
+import { type WithTimeoutErrorType } from '../promise/withTimeout.js'
+import { type HttpRequestParameters, getHttpRpcClient } from './http.js'
+import { type SocketRpcClient } from './socket.js'
+import { getWebSocketRpcClient } from './webSocket.js'
+
+export type WebSocketOptions = Parameters<
+  SocketRpcClient<WebSocket>['request']
+>[0]
+export type WebSocketReturnType = SocketRpcClient<WebSocket>
+export type WebSocketErrorType = WebSocketRequestError | ErrorType
+
+function webSocket(
+  socketClient: SocketRpcClient<WebSocket>,
+  { body, onError, onResponse }: WebSocketOptions,
+): WebSocketReturnType {
+  socketClient.request({
+    body,
+    onError,
+    onResponse,
+  })
+  return socketClient
+}
+
+export type WebSocketAsyncOptions = Parameters<
+  SocketRpcClient<WebSocket>['requestAsync']
+>[0]
+export type WebSocketAsyncReturnType = RpcResponse
+export type WebSocketAsyncErrorType =
+  | WebSocketErrorType
+  | TimeoutErrorType
+  | WithTimeoutErrorType
+  | ErrorType
+
+async function webSocketAsync(
+  socketClient: SocketRpcClient<WebSocket>,
+  { body, timeout = 10_000 }: WebSocketAsyncOptions,
+): Promise<WebSocketAsyncReturnType> {
+  return socketClient.requestAsync({
+    body,
+    timeout,
+  })
+}
+
+/**
+ * @deprecated use `getSocketClient` instead.
+ *
+ * ```diff
+ * -import { getSocket } from 'viem/utils'
+ * +import { getSocketClient } from 'viem/utils'
+ *
+ * -const socket = await getSocket(url)
+ * +const socketClient = await getSocketClient(url)
+ * +const socket = socketClient.socket
+ * ```
+ */
+export async function getSocket(url: string) {
+  const client = await getWebSocketRpcClient(url)
+  return Object.assign(client.socket, {
+    requests: client.requests,
+    subscriptions: client.subscriptions,
+  })
+}
+
+export const rpc = {
+  /**
+   * @deprecated use `getHttpRpcClient` instead.
+   *
+   * ```diff
+   * -import { rpc } from 'viem/utils'
+   * +import { getHttpRpcClient } from 'viem/utils'
+   *
+   * -rpc.http(url, params)
+   * +const httpClient = getHttpRpcClient(url)
+   * +httpClient.request(params)
+   * ```
+   */
+  http(url: string, params: HttpRequestParameters) {
+    return getHttpRpcClient(url).request(params)
+  },
+  /**
+   * @deprecated use `getWebSocketRpcClient` instead.
+   *
+   * ```diff
+   * -import { rpc } from 'viem/utils'
+   * +import { getWebSocketRpcClient } from 'viem/utils'
+   *
+   * -rpc.webSocket(url, params)
+   * +const webSocketClient = getWebSocketRpcClient(url)
+   * +webSocketClient.request(params)
+   * ```
+   */
+  webSocket,
+  /**
+   * @deprecated use `getWebSocketRpcClient` instead.
+   *
+   * ```diff
+   * -import { rpc } from 'viem/utils'
+   * +import { getWebSocketRpcClient } from 'viem/utils'
+   *
+   * -const response = await rpc.webSocketAsync(url, params)
+   * +const webSocketClient = getWebSocketRpcClient(url)
+   * +const response = await webSocketClient.requestAsync(params)
+   * ```
+   */
+  webSocketAsync,
+}
+/* c8 ignore end */

package/utils/rpc/http.ts

@@ -0,0 +1,132 @@
+import {
+  HttpRequestError,
+  type HttpRequestErrorType as HttpRequestErrorType_,
+  TimeoutError,
+  type TimeoutErrorType,
+} from '../../errors/request.js'
+import type { ErrorType } from '../../errors/utils.js'
+import type { RpcRequest, RpcResponse } from '../../types/rpc.js'
+import {
+  type WithTimeoutErrorType,
+  withTimeout,
+} from '../promise/withTimeout.js'
+import { stringify } from '../stringify.js'
+import { idCache } from './id.js'
+
+export type HttpRpcClientOptions = {
+  // Request configuration to pass to `fetch`.
+  fetchOptions?: Omit<RequestInit, 'body'>
+  // The timeout (in ms) for the request.
+  timeout?: number
+}
+
+export type HttpRequestParameters<
+  TBody extends RpcRequest | RpcRequest[] = RpcRequest,
+> = {
+  // The RPC request body.
+  body: TBody
+  // Request configuration to pass to `fetch`.
+  fetchOptions?: HttpRpcClientOptions['fetchOptions']
+  // The timeout (in ms) for the request.
+  timeout?: HttpRpcClientOptions['timeout']
+}
+
+export type HttpRequestReturnType<
+  TBody extends RpcRequest | RpcRequest[] = RpcRequest,
+> = TBody extends RpcRequest[] ? RpcResponse[] : RpcResponse
+
+export type HttpRequestErrorType =
+  | HttpRequestErrorType_
+  | TimeoutErrorType
+  | WithTimeoutErrorType
+  | ErrorType
+
+export type HttpRpcClient = {
+  request<TBody extends RpcRequest | RpcRequest[]>(
+    params: HttpRequestParameters<TBody>,
+  ): Promise<HttpRequestReturnType<TBody>>
+}
+
+export function getHttpRpcClient(
+  url: string,
+  options: HttpRpcClientOptions = {},
+): HttpRpcClient {
+  return {
+    async request(params) {
+      const {
+        body,
+        fetchOptions = {},
+        timeout = options.timeout ?? 10_000,
+      } = params
+      const {
+        headers,
+        method,
+        signal: signal_,
+      } = { ...options.fetchOptions, ...fetchOptions }
+
+      try {
+        const response = await withTimeout(
+          async ({ signal }) => {
+            const response = await fetch(url, {
+              ...fetchOptions,
+              body: Array.isArray(body)
+                ? stringify(
+                    body.map((body) => ({
+                      jsonrpc: '2.0',
+                      id: body.id ?? idCache.take(),
+                      ...body,
+                    })),
+                  )
+                : stringify({
+                    jsonrpc: '2.0',
+                    id: body.id ?? idCache.take(),
+                    ...body,
+                  }),
+              headers: {
+                ...headers,
+                'Content-Type': 'application/json',
+              },
+              method: method || 'POST',
+              signal: signal_ || (timeout > 0 ? signal : undefined),
+            })
+            return response
+          },
+          {
+            errorInstance: new TimeoutError({ body, url }),
+            timeout,
+            signal: true,
+          },
+        )
+
+        let data: any
+        if (
+          response.headers.get('Content-Type')?.startsWith('application/json')
+        ) {
+          data = await response.json()
+        } else {
+          data = await response.text()
+        }
+
+        if (!response.ok) {
+          throw new HttpRequestError({
+            body,
+            details: stringify(data.error) || response.statusText,
+            headers: response.headers,
+            status: response.status,
+            url,
+          })
+        }
+
+        return data
+      } catch (err) {
+        if (err instanceof HttpRequestError) throw err
+        if (err instanceof TimeoutError) throw err
+        throw new HttpRequestError({
+          body,
+          details: (err as Error).message,
+          url,
+        })
+      }
+    },
+  }
+}

package/utils/rpc/id.ts

@@ -0,0 +1,13 @@
+export function createIdStore() {
+  return {
+    current: 0,
+    take() {
+      return this.current++
+    },
+    reset() {
+      this.current = 0
+    },
+  }
+}
+
+export const idCache = /*#__PURE__*/ createIdStore()