viem 0.2.11 → 0.2.13

package/src/clients/decorators/test.ts

@@ -0,0 +1,137 @@
+import type {
+  DropTransactionParameters,
+  GetAutomineReturnType,
+  GetTxpoolContentReturnType,
+  GetTxpoolStatusReturnType,
+  ImpersonateAccountParameters,
+  IncreaseTimeParameters,
+  InspectTxpoolReturnType,
+  MineParameters,
+  ResetParameters,
+  RevertParameters,
+  SendUnsignedTransactionParameters,
+  SendUnsignedTransactionReturnType,
+  SetBalanceParameters,
+  SetBlockGasLimitParameters,
+  SetBlockTimestampIntervalParameters,
+  SetCodeParameters,
+  SetCoinbaseParameters,
+  SetIntervalMiningParameters,
+  SetMinGasPriceParameters,
+  SetNextBlockBaseFeePerGasParameters,
+  SetNextBlockTimestampParameters,
+  SetNonceParameters,
+  SetStorageAtParameters,
+  StopImpersonatingAccountParameters,
+} from '../../actions/test/index.js'
+import {
+  dropTransaction,
+  getAutomine,
+  getTxpoolContent,
+  getTxpoolStatus,
+  impersonateAccount,
+  increaseTime,
+  inspectTxpool,
+  mine,
+  removeBlockTimestampInterval,
+  reset,
+  revert,
+  sendUnsignedTransaction,
+  setAutomine,
+  setBalance,
+  setBlockGasLimit,
+  setBlockTimestampInterval,
+  setCode,
+  setCoinbase,
+  setIntervalMining,
+  setLoggingEnabled,
+  setMinGasPrice,
+  setNextBlockBaseFeePerGas,
+  setNextBlockTimestamp,
+  setNonce,
+  setRpcUrl,
+  setStorageAt,
+  snapshot,
+  stopImpersonatingAccount,
+} from '../../actions/test/index.js'
+import type { Chain, Quantity } from '../../types/index.js'
+import type { TestClient, TestClientMode } from '../createTestClient.js'
+import type { Transport } from '../transports/index.js'
+
+export type TestActions = {
+  dropTransaction: (args: DropTransactionParameters) => Promise<void>
+  getAutomine: () => Promise<GetAutomineReturnType>
+  getTxpoolContent: () => Promise<GetTxpoolContentReturnType>
+  getTxpoolStatus: () => Promise<GetTxpoolStatusReturnType>
+  impersonateAccount: (args: ImpersonateAccountParameters) => Promise<void>
+  increaseTime: (args: IncreaseTimeParameters) => Promise<Quantity>
+  inspectTxpool: () => Promise<InspectTxpoolReturnType>
+  mine: (args: MineParameters) => Promise<void>
+  removeBlockTimestampInterval: () => Promise<void>
+  reset: (args?: ResetParameters) => Promise<void>
+  revert: (args: RevertParameters) => Promise<void>
+  sendUnsignedTransaction: (
+    args: SendUnsignedTransactionParameters,
+  ) => Promise<SendUnsignedTransactionReturnType>
+  setAutomine: (args: boolean) => Promise<void>
+  setBalance: (args: SetBalanceParameters) => Promise<void>
+  setBlockGasLimit: (args: SetBlockGasLimitParameters) => Promise<void>
+  setBlockTimestampInterval: (
+    args: SetBlockTimestampIntervalParameters,
+  ) => Promise<void>
+  setCode: (args: SetCodeParameters) => Promise<void>
+  setCoinbase: (args: SetCoinbaseParameters) => Promise<void>
+  setIntervalMining: (args: SetIntervalMiningParameters) => Promise<void>
+  setLoggingEnabled: (args: boolean) => Promise<void>
+  setMinGasPrice: (args: SetMinGasPriceParameters) => Promise<void>
+  setNextBlockBaseFeePerGas: (
+    args: SetNextBlockBaseFeePerGasParameters,
+  ) => Promise<void>
+  setNextBlockTimestamp: (
+    args: SetNextBlockTimestampParameters,
+  ) => Promise<void>
+  setNonce: (args: SetNonceParameters) => Promise<void>
+  setRpcUrl: (args: string) => Promise<void>
+  setStorageAt: (args: SetStorageAtParameters) => Promise<void>
+  snapshot: () => Promise<Quantity>
+  stopImpersonatingAccount: (
+    args: StopImpersonatingAccountParameters,
+  ) => Promise<void>
+}
+
+export function testActions<TChain extends Chain | undefined>(
+  client: TestClient<TestClientMode, Transport, TChain>,
+): TestActions {
+  return {
+    dropTransaction: (args) => dropTransaction(client, args),
+    getAutomine: () => getAutomine(client),
+    getTxpoolContent: () => getTxpoolContent(client),
+    getTxpoolStatus: () => getTxpoolStatus(client),
+    impersonateAccount: (args) => impersonateAccount(client, args),
+    increaseTime: (args) => increaseTime(client, args),
+    inspectTxpool: () => inspectTxpool(client),
+    mine: (args) => mine(client, args),
+    removeBlockTimestampInterval: () => removeBlockTimestampInterval(client),
+    reset: (args) => reset(client, args),
+    revert: (args) => revert(client, args),
+    sendUnsignedTransaction: (args) => sendUnsignedTransaction(client, args),
+    setAutomine: (args) => setAutomine(client, args),
+    setBalance: (args) => setBalance(client, args),
+    setBlockGasLimit: (args) => setBlockGasLimit(client, args),
+    setBlockTimestampInterval: (args) =>
+      setBlockTimestampInterval(client, args),
+    setCode: (args) => setCode(client, args),
+    setCoinbase: (args) => setCoinbase(client, args),
+    setIntervalMining: (args) => setIntervalMining(client, args),
+    setLoggingEnabled: (args) => setLoggingEnabled(client, args),
+    setMinGasPrice: (args) => setMinGasPrice(client, args),
+    setNextBlockBaseFeePerGas: (args) =>
+      setNextBlockBaseFeePerGas(client, args),
+    setNextBlockTimestamp: (args) => setNextBlockTimestamp(client, args),
+    setNonce: (args) => setNonce(client, args),
+    setRpcUrl: (args) => setRpcUrl(client, args),
+    setStorageAt: (args) => setStorageAt(client, args),
+    snapshot: () => snapshot(client),
+    stopImpersonatingAccount: (args) => stopImpersonatingAccount(client, args),
+  }
+}

package/src/clients/decorators/wallet.ts

@@ -0,0 +1,116 @@
+import type { Abi, TypedData } from 'abitype'
+import type {
+  AddChainParameters,
+  DeployContractParameters,
+  DeployContractReturnType,
+  GetAddressesReturnType,
+  GetChainIdReturnType,
+  GetPermissionsReturnType,
+  RequestAddressesReturnType,
+  RequestPermissionsParameters,
+  RequestPermissionsReturnType,
+  SendTransactionParameters,
+  SendTransactionReturnType,
+  SignMessageParameters,
+  SignMessageReturnType,
+  SignTypedDataParameters,
+  SignTypedDataReturnType,
+  SwitchChainParameters,
+  WatchAssetParameters,
+  WatchAssetReturnType,
+  WriteContractParameters,
+  WriteContractReturnType,
+} from '../../actions/wallet/index.js'
+import {
+  addChain,
+  deployContract,
+  getAddresses,
+  getChainId,
+  getPermissions,
+  requestAddresses,
+  requestPermissions,
+  sendTransaction,
+  signMessage,
+  signTypedData,
+  switchChain,
+  watchAsset,
+  writeContract,
+} from '../../actions/wallet/index.js'
+import type { Account, Chain } from '../../types/index.js'
+import type { WalletClient } from '../createWalletClient.js'
+import type { Transport } from '../transports/index.js'
+
+export type WalletActions<
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends Account | undefined = Account | undefined,
+> = {
+  addChain: (args: AddChainParameters) => Promise<void>
+  deployContract: <
+    TAbi extends Abi | readonly unknown[],
+    TChainOverride extends Chain | undefined,
+  >(
+    args: DeployContractParameters<TAbi, TChain, TAccount, TChainOverride>,
+  ) => Promise<DeployContractReturnType>
+  getAddresses: () => Promise<GetAddressesReturnType>
+  getChainId: () => Promise<GetChainIdReturnType>
+  getPermissions: () => Promise<GetPermissionsReturnType>
+  requestAddresses: () => Promise<RequestAddressesReturnType>
+  requestPermissions: (
+    args: RequestPermissionsParameters,
+  ) => Promise<RequestPermissionsReturnType>
+  sendTransaction: <TChainOverride extends Chain | undefined>(
+    args: SendTransactionParameters<TChain, TAccount, TChainOverride>,
+  ) => Promise<SendTransactionReturnType>
+  signMessage: (
+    args: SignMessageParameters<TAccount>,
+  ) => Promise<SignMessageReturnType>
+  signTypedData: <
+    TTypedData extends TypedData | { [key: string]: unknown },
+    TPrimaryType extends string,
+  >(
+    args: SignTypedDataParameters<TTypedData, TPrimaryType, TAccount>,
+  ) => Promise<SignTypedDataReturnType>
+  switchChain: (args: SwitchChainParameters) => Promise<void>
+  watchAsset: (args: WatchAssetParameters) => Promise<WatchAssetReturnType>
+  writeContract: <
+    TAbi extends Abi | readonly unknown[],
+    TFunctionName extends string,
+    TChainOverride extends Chain | undefined,
+  >(
+    args: WriteContractParameters<
+      TAbi,
+      TFunctionName,
+      TChain,
+      TAccount,
+      TChainOverride
+    >,
+  ) => Promise<WriteContractReturnType>
+}
+
+export const walletActions: <
+  TTransport extends Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends Account | undefined = Account | undefined,
+>(
+  client: WalletClient<TTransport, TChain, TAccount>,
+) => WalletActions<TChain, TAccount> = <
+  TTransport extends Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends Account | undefined = Account | undefined,
+>(
+  client: WalletClient<TTransport, TChain, TAccount>,
+): WalletActions<TChain, TAccount> => ({
+  addChain: (args) => addChain(client, args),
+  deployContract: (args) => deployContract(client, args),
+  getAddresses: () => getAddresses(client),
+  getChainId: () => getChainId(client),
+  getPermissions: () => getPermissions(client),
+  requestAddresses: () => requestAddresses(client),
+  requestPermissions: (args) => requestPermissions(client, args),
+  sendTransaction: (args) => sendTransaction(client, args),
+  signMessage: (args) => signMessage(client, args),
+  signTypedData: (args) => signTypedData(client, args),
+  switchChain: (args) => switchChain(client, args),
+  watchAsset: (args) => watchAsset(client, args),
+  writeContract: (args) => writeContract(client, args),
+})

package/src/clients/index.ts

@@ -0,0 +1,41 @@
+export {
+  createTransport,
+  custom,
+  fallback,
+  http,
+  webSocket,
+} from './transports/index.js'
+export type {
+  CustomTransport,
+  CustomTransportConfig,
+  Transport,
+  TransportConfig,
+  FallbackTransport,
+  FallbackTransportConfig,
+  HttpTransport,
+  HttpTransportConfig,
+  WebSocketTransport,
+  WebSocketTransportConfig,
+} from './transports/index.js'
+
+export { createClient } from './createClient.js'
+export type { Client, ClientConfig } from './createClient.js'
+
+export { createPublicClient } from './createPublicClient.js'
+export type {
+  PublicClient,
+  PublicClientConfig,
+} from './createPublicClient.js'
+
+export { createTestClient } from './createTestClient.js'
+export type {
+  TestClient,
+  TestClientConfig,
+  TestClientMode,
+} from './createTestClient.js'
+
+export { createWalletClient } from './createWalletClient.js'
+export type {
+  WalletClient,
+  WalletClientConfig,
+} from './createWalletClient.js'

package/src/clients/transports/createTransport.ts

@@ -0,0 +1,70 @@
+import type { Chain } from '../../types/index.js'
+import type { Requests } from '../../types/eip1193.js'
+import { buildRequest } from '../../utils/index.js'
+import type { ClientConfig } from '../createClient.js'
+
+export type BaseRpcRequests = {
+  request(...args: any): Promise<any>
+}
+
+export type TransportConfig<
+  TType extends string = string,
+  TRequests extends BaseRpcRequests['request'] = Requests['request'],
+> = {
+  /** The name of the transport. */
+  name: string
+  /** The key of the transport. */
+  key: string
+  /** The JSON-RPC request function that matches the EIP-1193 request spec. */
+  request: TRequests
+  /** The base delay (in ms) between retries. */
+  retryDelay?: number
+  /** The max number of times to retry. */
+  retryCount?: number
+  /** The timeout (in ms) for requests. */
+  timeout?: number
+  /** The type of the transport. */
+  type: TType
+}
+
+export type Transport<
+  TType extends string = string,
+  TRpcAttributes = Record<string, any>,
+  TRequests extends BaseRpcRequests['request'] = Requests['request'],
+> = <TChain extends Chain | undefined = Chain>({
+  chain,
+}: {
+  chain?: TChain
+  pollingInterval?: ClientConfig['pollingInterval']
+  retryCount?: TransportConfig['retryCount']
+  timeout?: TransportConfig['timeout']
+}) => {
+  config: TransportConfig<TType>
+  request: TRequests
+  value?: TRpcAttributes
+}
+
+/**
+ * @description Creates an transport intended to be used with a client.
+ */
+export function createTransport<
+  TType extends string,
+  TRpcAttributes extends Record<string, any>,
+>(
+  {
+    key,
+    name,
+    request,
+    retryCount = 3,
+    retryDelay = 150,
+    timeout,
+    type,
+  }: TransportConfig<TType>,
+  value?: TRpcAttributes,
+): ReturnType<Transport<TType, TRpcAttributes>> {
+  return {
+    config: { key, name, request, retryCount, retryDelay, timeout, type },
+    request: buildRequest(request, { retryCount, retryDelay }),
+    value,
+  }
+}

package/src/clients/transports/custom.ts

@@ -0,0 +1,40 @@
+import type {
+  BaseRpcRequests,
+  Transport,
+  TransportConfig,
+} from './createTransport.js'
+import { createTransport } from './createTransport.js'
+
+type EthereumProvider = { request: BaseRpcRequests['request'] }
+
+export type CustomTransportConfig = {
+  /** The key of the transport. */
+  key?: TransportConfig['key']
+  /** The name of the transport. */
+  name?: TransportConfig['name']
+  /** The max number of times to retry. */
+  retryCount?: TransportConfig['retryCount']
+  /** The base delay (in ms) between retries. */
+  retryDelay?: TransportConfig['retryDelay']
+}
+
+export type CustomTransport = Transport<'custom', EthereumProvider['request']>
+
+/**
+ * @description Creates a custom transport given an EIP-1193 compliant `request` attribute.
+ */
+export function custom<TProvider extends EthereumProvider>(
+  provider: TProvider,
+  config: CustomTransportConfig = {},
+): CustomTransport {
+  const { key = 'custom', name = 'Custom Provider', retryDelay } = config
+  return ({ retryCount: defaultRetryCount }) =>
+    createTransport({
+      key,
+      name,
+      request: provider.request.bind(provider),
+      retryCount: config.retryCount ?? defaultRetryCount,
+      retryDelay,
+      type: 'custom',
+    })
+}

package/src/clients/transports/fallback.ts

@@ -0,0 +1,211 @@
+import type { Chain } from '../../types/index.js'
+import { isDeterministicError } from '../../utils/buildRequest.js'
+import { wait } from '../../utils/wait.js'
+import type { Transport, TransportConfig } from './createTransport.js'
+import { createTransport } from './createTransport.js'
+
+type RankOptions = {
+  /**
+   * The polling interval (in ms) at which the ranker should ping the RPC URL.
+   * @default client.pollingInterval
+   */
+  interval?: number
+  /**
+   * The number of previous samples to perform ranking on.
+   * @default 10
+   */
+  sampleCount?: number
+  /**
+   * Timeout when sampling transports.
+   * @default 1_000
+   */
+  timeout?: number
+  /**
+   * Weights to apply to the scores. Weight values are proportional.
+   */
+  weights?: {
+    /**
+     * The weight to apply to the latency score.
+     * @default 0.3
+     */
+    latency?: number
+    /**
+     * The weight to apply to the stability score.
+     * @default 0.7
+     */
+    stability?: number
+  }
+}
+
+export type FallbackTransportConfig = {
+  /** The key of the Fallback transport. */
+  key?: TransportConfig['key']
+  /** The name of the Fallback transport. */
+  name?: TransportConfig['name']
+  /** Toggle to enable ranking, or rank options. */
+  rank?: boolean | RankOptions
+  /** The max number of times to retry. */
+  retryCount?: TransportConfig['retryCount']
+  /** The base delay (in ms) between retries. */
+  retryDelay?: TransportConfig['retryDelay']
+}
+
+export type FallbackTransport = Transport<
+  'fallback',
+  { transports: ReturnType<Transport>[] }
+>
+
+export function fallback(
+  transports_: Transport[],
+  config: FallbackTransportConfig = {},
+): FallbackTransport {
+  const {
+    key = 'fallback',
+    name = 'Fallback',
+    rank = true,
+    retryCount,
+    retryDelay,
+  } = config
+  return ({ chain, pollingInterval = 4_000, timeout }) => {
+    let transports = transports_
+
+    const transport = createTransport(
+      {
+        key,
+        name,
+        async request({ method, params }) {
+          const fetch = async (i: number = 0): Promise<any> => {
+            const transport = transports[i]({ chain, retryCount: 0, timeout })
+            try {
+              return await transport.request({
+                method,
+                params,
+              } as any)
+            } catch (err) {
+              // If the error is deterministic, we don't need to fall back.
+              // So throw the error.
+              if (isDeterministicError(err as Error)) throw err
+
+              // If we've reached the end of the fallbacks, throw the error.
+              if (i === transports.length - 1) throw err
+
+              // Otherwise, try the next fallback.
+              return fetch(i + 1)
+            }
+          }
+          return fetch()
+        },
+        retryCount,
+        retryDelay,
+        type: 'fallback',
+      },
+      {
+        transports: transports.map((fn) => fn({ chain, retryCount: 0 })),
+      },
+    )
+
+    if (rank) {
+      const rankOptions = (typeof rank === 'object' ? rank : {}) as RankOptions
+      rankTransports({
+        chain,
+        interval: rankOptions.interval ?? pollingInterval,
+        onTransports: (transports_) => (transports = transports_),
+        sampleCount: rankOptions.sampleCount,
+        timeout: rankOptions.timeout,
+        transports,
+        weights: rankOptions.weights,
+      })
+    }
+    return transport
+  }
+}
+
+export function rankTransports({
+  chain,
+  interval = 4_000,
+  onTransports,
+  sampleCount = 10,
+  timeout = 1_000,
+  transports,
+  weights = {},
+}: {
+  chain?: Chain
+  interval: RankOptions['interval']
+  onTransports: (transports: Transport[]) => void
+  sampleCount?: RankOptions['sampleCount']
+  timeout?: RankOptions['timeout']
+  transports: Transport[]
+  weights?: RankOptions['weights']
+}) {
+  const { stability: stabilityWeight = 0.7, latency: latencyWeight = 0.3 } =
+    weights
+
+  type SampleData = { latency: number; success: number }
+  type Sample = SampleData[]
+  const samples: Sample[] = []
+
+  const rankTransports_ = async () => {
+    // 1. Take a sample from each Transport.
+    const sample: Sample = await Promise.all(
+      transports.map(async (transport) => {
+        const transport_ = transport({ chain, retryCount: 0, timeout })
+
+        const start = Date.now()
+        let end
+        let success
+        try {
+          await transport_.request({ method: 'net_listening' })
+          success = 1
+        } catch {
+          success = 0
+        } finally {
+          end = Date.now()
+        }
+        const latency = end - start
+        return { latency, success }
+      }),
+    )
+
+    // 2. Store the sample. If we have more than `sampleCount` samples, remove
+    // the oldest sample.
+    samples.push(sample)
+    if (samples.length > sampleCount) samples.shift()
+
+    // 3. Calculate the max latency from samples.
+    const maxLatency = Math.max(
+      ...samples.map((sample) =>
+        Math.max(...sample.map(({ latency }) => latency)),
+      ),
+    )
+
+    // 4. Calculate the score for each Transport.
+    const scores = transports
+      .map((_, i) => {
+        const latencies = samples.map((sample) => sample[i].latency)
+        const meanLatency =
+          latencies.reduce((acc, latency) => acc + latency, 0) /
+          latencies.length
+        const latencyScore = 1 - meanLatency / maxLatency
+
+        const successes = samples.map((sample) => sample[i].success)
+        const stabilityScore =
+          successes.reduce((acc, success) => acc + success, 0) /
+          successes.length
+
+        if (stabilityScore === 0) return [0, i]
+        return [
+          latencyWeight * latencyScore + stabilityWeight * stabilityScore,
+          i,
+        ]
+      })
+      .sort((a, b) => b[0] - a[0])
+
+    // 5. Sort the Transports by score.
+    onTransports(scores.map(([, i]) => transports[i]))
+
+    // 6. Wait, and then rank again.
+    await wait(interval)
+    rankTransports_()
+  }
+  rankTransports_()
+}

package/src/clients/transports/http.ts

@@ -0,0 +1,76 @@
+import { UrlRequiredError } from '../../errors/index.js'
+import type { HttpOptions } from '../../utils/index.js'
+import { rpc } from '../../utils/index.js'
+import type { Transport, TransportConfig } from './createTransport.js'
+import { createTransport } from './createTransport.js'
+
+export type HttpTransportConfig = {
+  /**
+   * Request configuration to pass to `fetch`.
+   * @link https://developer.mozilla.org/en-US/docs/Web/API/fetch
+   */
+  fetchOptions?: HttpOptions['fetchOptions']
+  /** The key of the HTTP transport. */
+  key?: TransportConfig['key']
+  /** The name of the HTTP 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 the HTTP request. Default: 10_000 */
+  timeout?: TransportConfig['timeout']
+}
+
+export type HttpTransport = Transport<
+  'http',
+  {
+    url?: string
+  }
+>
+
+/**
+ * @description Creates a HTTP transport that connects to a JSON-RPC API.
+ */
+export function http(
+  /** URL of the JSON-RPC API. Defaults to the chain's public RPC URL. */
+  url?: string,
+  config: HttpTransportConfig = {},
+): HttpTransport {
+  const {
+    fetchOptions,
+    key = 'http',
+    name = 'HTTP JSON-RPC',
+    retryDelay,
+  } = config
+  return ({ chain, retryCount: retryCount_, timeout: timeout_ }) => {
+    const retryCount = config.retryCount ?? retryCount_
+    const timeout = timeout_ ?? config.timeout ?? 10_000
+    const url_ = url || chain?.rpcUrls.default.http[0]
+    if (!url_) throw new UrlRequiredError()
+    return createTransport(
+      {
+        key,
+        name,
+        async request({ method, params }) {
+          const { result } = await rpc.http(url_, {
+            body: {
+              method,
+              params,
+            },
+            fetchOptions,
+            timeout,
+          })
+          return result
+        },
+        retryCount,
+        retryDelay,
+        timeout,
+        type: 'http',
+      },
+      {
+        url,
+      },
+    )
+  }
+}