viem 0.0.1-alpha.14 → 0.0.1-alpha.16

package/src/chains.ts

@@ -0,0 +1,167 @@
+// TODO: Remove chain formatter implementation once @wagmi/chains supports it.
+
+import type { Chain as Chain_ } from '@wagmi/chains'
+import {
+  arbitrumGoerli as arbitrumGoerli_,
+  arbitrum as arbitrum_,
+  avalancheFuji as avalancheFuji_,
+  avalanche as avalanche_,
+  bscTestnet as bscTestnet_,
+  bsc as bsc_,
+  fantomTestnet as fantomTestnet_,
+  fantom as fantom_,
+  foundry as foundry_,
+  goerli as goerli_,
+  hardhat as hardhat_,
+  localhost as localhost_,
+  mainnet as mainnet_,
+  optimismGoerli as optimismGoerli_,
+  optimism as optimism_,
+  polygonMumbai as polygonMumbai_,
+  polygon as polygon_,
+  sepolia as sepolia_,
+} from '@wagmi/chains'
+
+import type {
+  Address,
+  Block,
+  Hex,
+  Quantity,
+  RpcBlock,
+  RpcTransaction,
+  RpcTransactionReceipt,
+  RpcTransactionRequest,
+  Transaction,
+  TransactionReceipt,
+  TransactionRequest,
+} from './types'
+import {
+  formatBlock,
+  formatTransaction,
+  formatTransactionRequest,
+} from './utils'
+import { formatTransactionReceipt } from './utils/formatters/transactionReceipt'
+
+export type Formatter<TSource = any, TTarget = any> = (
+  value: TSource & { [key: string]: unknown },
+) => TTarget
+
+export type Formatters = {
+  block?: Formatter<RpcBlock, Block>
+  transaction?: Formatter<RpcTransaction, Transaction>
+  transactionReceipt?: Formatter<RpcTransactionReceipt, TransactionReceipt>
+  transactionRequest?: Formatter<TransactionRequest, RpcTransactionRequest>
+}
+
+export type Chain<TFormatters extends Formatters = Formatters> = Chain_ & {
+  formatters?: TFormatters
+}
+
+export function defineChain<
+  TFormatters extends Formatters = Formatters,
+  TChain extends Chain<TFormatters> = Chain<TFormatters>,
+>(chain: TChain) {
+  return chain
+}
+
+function defineFormatter<TSource extends Record<string, unknown>, TFormatted>({
+  format,
+}: {
+  format: (data: TSource) => TFormatted
+}) {
+  return <
+      TFormat extends Formatter<
+        TSource,
+        Partial<TFormatted> & { [key: string]: unknown }
+      >,
+      TExclude extends (keyof TSource)[] = [],
+    >({
+      exclude,
+      format: formatOverride,
+    }: {
+      exclude?: TExclude
+      format?: TFormat
+    }) =>
+    (data: TSource & { [key: string]: unknown }) => {
+      const formatted = format(data)
+      if (exclude) {
+        for (const key of exclude) {
+          delete (formatted as any)[key]
+        }
+      }
+      return {
+        ...formatted,
+        ...formatOverride?.(data),
+      } as TFormatted &
+        ReturnType<TFormat> & {
+          [K in TExclude[number]]: never
+        }
+    }
+}
+
+export const defineBlock = defineFormatter({ format: formatBlock })
+export const defineTransaction = defineFormatter({ format: formatTransaction })
+export const defineTransactionRequest = defineFormatter({
+  format: formatTransactionRequest,
+})
+export const defineTransactionReceipt = defineFormatter({
+  format: formatTransactionReceipt,
+})
+
+export const arbitrumGoerli = defineChain(arbitrumGoerli_)
+export const arbitrum = defineChain(arbitrum_)
+export const avalancheFuji = defineChain(avalancheFuji_)
+export const avalanche = defineChain(avalanche_)
+export const bscTestnet = defineChain(bscTestnet_)
+export const bsc = defineChain(bsc_)
+export const celo = defineChain({
+  id: 42220,
+  name: 'Celo',
+  network: 'celo',
+  nativeCurrency: { name: 'Celo', symbol: 'CELO', decimals: 18 },
+  rpcUrls: {
+    public: { http: ['https://rpc.ankr.com/celo'] },
+    default: { http: ['https://rpc.ankr.com/celo'] },
+  },
+  formatters: {
+    block: defineBlock({
+      exclude: ['difficulty', 'gasLimit', 'mixHash', 'nonce', 'uncles'],
+      format: (block) => ({
+        randomness: block.randomness as {
+          committed: Hex
+          revealed: Hex
+        },
+      }),
+    }),
+    transaction: defineTransaction({
+      format: (transaction) => ({
+        feeCurrency: transaction.feeCurrency as Address | null,
+        gatewayFee: transaction.gatewayFee
+          ? BigInt(transaction.gatewayFee as Quantity)
+          : null,
+        gatewayFeeRecipient: transaction.gatewayFeeRecipient as Address | null,
+      }),
+    }),
+    transactionRequest: defineTransactionRequest({
+      format: (transactionRequest) => ({
+        feeCurrency: transactionRequest.feeCurrency as Address | undefined,
+        gatewayFee: transactionRequest.gatewayFee as Quantity | undefined,
+        gatewayFeeRecipient: transactionRequest.gatewayFeeRecipient as
+          | Address
+          | undefined,
+      }),
+    }),
+  },
+})
+export const fantomTestnet = defineChain(fantomTestnet_)
+export const fantom = defineChain(fantom_)
+export const foundry = defineChain(foundry_)
+export const goerli = defineChain(goerli_)
+export const hardhat = defineChain(hardhat_)
+export const localhost = defineChain(localhost_)
+export const mainnet = defineChain(mainnet_)
+export const optimismGoerli = defineChain(optimismGoerli_)
+export const optimism = defineChain(optimism_)
+export const polygonMumbai = defineChain(polygonMumbai_)
+export const polygon = defineChain(polygon_)
+export const sepolia = defineChain(sepolia_)

package/src/clients/createClient.test.ts

@@ -0,0 +1,295 @@
+import { assertType, describe, expect, test, vi } from 'vitest'
+
+import { localhost } from '../chains'
+import type { Requests } from '../types/eip1193'
+import { localWsUrl } from '../_test'
+import { createClient } from './createClient'
+import { createTransport, custom, http, webSocket } from './transports'
+
+test('creates', () => {
+  const mockTransport = () =>
+    createTransport({
+      key: 'mock',
+      name: 'Mock Transport',
+      request: vi.fn(async () => null) as unknown as Requests['request'],
+      type: 'mock',
+    })
+  const { uid, ...client } = createClient({
+    transport: mockTransport,
+  })
+
+  assertType<Requests['request']>(client.request)
+
+  expect(uid).toBeDefined()
+  expect(client).toMatchInlineSnapshot(`
+    {
+      "chain": undefined,
+      "key": "base",
+      "name": "Base Client",
+      "pollingInterval": 4000,
+      "request": [Function],
+      "transport": {
+        "key": "mock",
+        "name": "Mock Transport",
+        "request": [MockFunction spy],
+        "type": "mock",
+      },
+      "type": "base",
+    }
+  `)
+})
+
+describe('transports', () => {
+  test('http', () => {
+    const { uid, ...client } = createClient({
+      chain: localhost,
+      transport: http(),
+    })
+
+    expect(uid).toBeDefined()
+    expect(client).toMatchInlineSnapshot(`
+      {
+        "chain": {
+          "id": 1337,
+          "name": "Localhost",
+          "nativeCurrency": {
+            "decimals": 18,
+            "name": "Ether",
+            "symbol": "ETH",
+          },
+          "network": "localhost",
+          "rpcUrls": {
+            "default": {
+              "http": [
+                "http://127.0.0.1:8545",
+              ],
+            },
+            "public": {
+              "http": [
+                "http://127.0.0.1:8545",
+              ],
+            },
+          },
+        },
+        "key": "base",
+        "name": "Base Client",
+        "pollingInterval": 4000,
+        "request": [Function],
+        "transport": {
+          "key": "http",
+          "name": "HTTP JSON-RPC",
+          "request": [Function],
+          "type": "http",
+          "url": undefined,
+        },
+        "type": "base",
+      }
+    `)
+  })
+
+  test('webSocket', () => {
+    const { uid, ...client } = createClient({
+      chain: localhost,
+      transport: webSocket(localWsUrl),
+    })
+
+    expect(uid).toBeDefined()
+    expect(client).toMatchInlineSnapshot(`
+      {
+        "chain": {
+          "id": 1337,
+          "name": "Localhost",
+          "nativeCurrency": {
+            "decimals": 18,
+            "name": "Ether",
+            "symbol": "ETH",
+          },
+          "network": "localhost",
+          "rpcUrls": {
+            "default": {
+              "http": [
+                "http://127.0.0.1:8545",
+              ],
+            },
+            "public": {
+              "http": [
+                "http://127.0.0.1:8545",
+              ],
+            },
+          },
+        },
+        "key": "base",
+        "name": "Base Client",
+        "pollingInterval": 4000,
+        "request": [Function],
+        "transport": {
+          "getSocket": [Function],
+          "key": "webSocket",
+          "name": "WebSocket JSON-RPC",
+          "request": [Function],
+          "subscribe": [Function],
+          "type": "webSocket",
+        },
+        "type": "base",
+      }
+    `)
+  })
+
+  test('custom', () => {
+    const { uid, ...client } = createClient({
+      transport: custom({ request: async () => null }),
+    })
+
+    expect(uid).toBeDefined()
+    expect(client).toMatchInlineSnapshot(`
+      {
+        "chain": undefined,
+        "key": "base",
+        "name": "Base Client",
+        "pollingInterval": 4000,
+        "request": [Function],
+        "transport": {
+          "key": "custom",
+          "name": "Custom Provider",
+          "request": [Function],
+          "type": "custom",
+        },
+        "type": "base",
+      }
+    `)
+  })
+})
+
+describe('config', () => {
+  test('key', () => {
+    const mockTransport = () =>
+      createTransport({
+        key: 'mock',
+        name: 'Mock Transport',
+        request: vi.fn(async () => null) as unknown as Requests['request'],
+        type: 'mock',
+      })
+    const { uid, ...client } = createClient({
+      key: 'bar',
+      transport: mockTransport,
+    })
+
+    assertType<Requests['request']>(client.request)
+    expect(uid).toBeDefined()
+    expect(client).toMatchInlineSnapshot(`
+      {
+        "chain": undefined,
+        "key": "bar",
+        "name": "Base Client",
+        "pollingInterval": 4000,
+        "request": [Function],
+        "transport": {
+          "key": "mock",
+          "name": "Mock Transport",
+          "request": [MockFunction spy],
+          "type": "mock",
+        },
+        "type": "base",
+      }
+    `)
+  })
+
+  test('name', () => {
+    const mockTransport = () =>
+      createTransport({
+        key: 'mock',
+        name: 'Mock Transport',
+        request: vi.fn(async () => null) as unknown as Requests['request'],
+        type: 'mock',
+      })
+    const { uid, ...client } = createClient({
+      name: 'Mock Client',
+      transport: mockTransport,
+    })
+
+    assertType<Requests['request']>(client.request)
+    expect(uid).toBeDefined()
+    expect(client).toMatchInlineSnapshot(`
+      {
+        "chain": undefined,
+        "key": "base",
+        "name": "Mock Client",
+        "pollingInterval": 4000,
+        "request": [Function],
+        "transport": {
+          "key": "mock",
+          "name": "Mock Transport",
+          "request": [MockFunction spy],
+          "type": "mock",
+        },
+        "type": "base",
+      }
+    `)
+  })
+
+  test('pollingInterval', () => {
+    const mockTransport = () =>
+      createTransport({
+        key: 'mock',
+        name: 'Mock Transport',
+        request: vi.fn(async () => null) as unknown as Requests['request'],
+        type: 'mock',
+      })
+    const { uid, ...client } = createClient({
+      pollingInterval: 10_000,
+      transport: mockTransport,
+    })
+
+    assertType<Requests['request']>(client.request)
+    expect(uid).toBeDefined()
+    expect(client).toMatchInlineSnapshot(`
+      {
+        "chain": undefined,
+        "key": "base",
+        "name": "Base Client",
+        "pollingInterval": 10000,
+        "request": [Function],
+        "transport": {
+          "key": "mock",
+          "name": "Mock Transport",
+          "request": [MockFunction spy],
+          "type": "mock",
+        },
+        "type": "base",
+      }
+    `)
+  })
+
+  test('type', () => {
+    const mockTransport = () =>
+      createTransport({
+        key: 'mock',
+        name: 'Mock Transport',
+        request: vi.fn(async () => null) as unknown as Requests['request'],
+        type: 'mock',
+      })
+    const { uid, ...client } = createClient({
+      transport: mockTransport,
+      type: 'foo',
+    })
+
+    assertType<Requests['request']>(client.request)
+    expect(uid).toBeDefined()
+    expect(client).toMatchInlineSnapshot(`
+      {
+        "chain": undefined,
+        "key": "base",
+        "name": "Base Client",
+        "pollingInterval": 4000,
+        "request": [Function],
+        "transport": {
+          "key": "mock",
+          "name": "Mock Transport",
+          "request": [MockFunction spy],
+          "type": "mock",
+        },
+        "type": "foo",
+      }
+    `)
+  })
+})

package/src/clients/createClient.ts

@@ -0,0 +1,81 @@
+import type { Chain } from '../chains'
+import type { Requests } from '../types/eip1193'
+import { buildRequest } from '../utils/buildRequest'
+import { uid } from '../utils/uid'
+import type { BaseRpcRequests, Transport } from './transports/createTransport'
+
+export type Client<
+  TTransport extends Transport = Transport,
+  TChain extends Chain = Chain,
+  TRequests extends BaseRpcRequests = Requests,
+> = {
+  /** Chain for the client. */
+  chain?: TChain
+  /** A key for the client. */
+  key: string
+  /** A name for the client. */
+  name: string
+  /** Frequency (in ms) for polling enabled actions & events. Defaults to 4_000 milliseconds. */
+  pollingInterval: number
+  /** Request function wrapped with friendly error handling */
+  request: TRequests['request']
+  /** The RPC transport (http, webSocket, custom, etc) */
+  transport: ReturnType<TTransport>['config'] & ReturnType<TTransport>['value']
+  /** The type of client. */
+  type: string
+  /** A unique ID for the client. */
+  uid: string
+}
+
+export type ClientConfig<
+  TTransport extends Transport = Transport,
+  TChain extends Chain = Chain,
+  TRequests extends BaseRpcRequests = Requests,
+> = Partial<
+  Pick<
+    Client<TTransport, TChain, TRequests>,
+    'chain' | 'key' | 'name' | 'pollingInterval' | 'type'
+  >
+> & {
+  transport: TTransport
+}
+
+/**
+ * @description Creates a base RPC client with the given transport.
+ *
+ * - Intended to be used as a base for other RPC clients.
+ * - Has access to _all_ EIP-1474 RPC methods.
+ *
+ * @example
+ * import { mainnet } from 'viem/chains'
+ * import { createClient, http } from 'viem/clients'
+ * const client = createClient(http({ chain: mainnet }))
+ */
+export function createClient<
+  TTransport extends Transport,
+  TChain extends Chain,
+  TRequests extends BaseRpcRequests,
+>({
+  chain,
+  key = 'base',
+  name = 'Base Client',
+  pollingInterval = 4_000,
+  transport,
+  type = 'base',
+}: ClientConfig<TTransport, TChain, TRequests>): Client<
+  TTransport,
+  TChain,
+  TRequests
+> {
+  const { config, value } = transport({ chain })
+  return {
+    chain,
+    key,
+    name,
+    pollingInterval,
+    request: buildRequest(config.request),
+    transport: { ...config, ...value },
+    type,
+    uid: uid(),
+  }
+}

package/src/clients/createPublicClient.test.ts

@@ -0,0 +1,165 @@
+import { assertType, describe, expect, test, vi } from 'vitest'
+
+import { createPublicClient } from './createPublicClient'
+import { createTransport } from './transports/createTransport'
+import { http } from './transports/http'
+import { custom } from './transports/custom'
+import { webSocket } from './transports/webSocket'
+import { localhost } from '../chains'
+import type { PublicRequests } from '../types/eip1193'
+import { localWsUrl } from '../_test'
+
+const mockTransport = () =>
+  createTransport({
+    key: 'mock',
+    name: 'Mock Transport',
+    request: vi.fn(() => null) as any,
+    type: 'mock',
+  })
+
+test('creates', () => {
+  const { uid, ...client } = createPublicClient({
+    transport: mockTransport,
+  })
+
+  assertType<PublicRequests['request']>(client.request)
+
+  expect(uid).toBeDefined()
+  expect(client).toMatchInlineSnapshot(`
+    {
+      "chain": undefined,
+      "key": "public",
+      "name": "Public Client",
+      "pollingInterval": 4000,
+      "request": [Function],
+      "transport": {
+        "key": "mock",
+        "name": "Mock Transport",
+        "request": [MockFunction spy],
+        "type": "mock",
+      },
+      "type": "publicClient",
+    }
+  `)
+})
+
+describe('transports', () => {
+  test('http', () => {
+    const { uid, ...client } = createPublicClient({
+      chain: localhost,
+      transport: http(),
+    })
+
+    expect(uid).toBeDefined()
+    expect(client).toMatchInlineSnapshot(`
+      {
+        "chain": {
+          "id": 1337,
+          "name": "Localhost",
+          "nativeCurrency": {
+            "decimals": 18,
+            "name": "Ether",
+            "symbol": "ETH",
+          },
+          "network": "localhost",
+          "rpcUrls": {
+            "default": {
+              "http": [
+                "http://127.0.0.1:8545",
+              ],
+            },
+            "public": {
+              "http": [
+                "http://127.0.0.1:8545",
+              ],
+            },
+          },
+        },
+        "key": "public",
+        "name": "Public Client",
+        "pollingInterval": 4000,
+        "request": [Function],
+        "transport": {
+          "key": "http",
+          "name": "HTTP JSON-RPC",
+          "request": [Function],
+          "type": "http",
+          "url": undefined,
+        },
+        "type": "publicClient",
+      }
+    `)
+  })
+
+  test('webSocket', () => {
+    const { uid, ...client } = createPublicClient({
+      chain: localhost,
+      transport: webSocket(localWsUrl),
+    })
+
+    expect(uid).toBeDefined()
+    expect(client).toMatchInlineSnapshot(`
+      {
+        "chain": {
+          "id": 1337,
+          "name": "Localhost",
+          "nativeCurrency": {
+            "decimals": 18,
+            "name": "Ether",
+            "symbol": "ETH",
+          },
+          "network": "localhost",
+          "rpcUrls": {
+            "default": {
+              "http": [
+                "http://127.0.0.1:8545",
+              ],
+            },
+            "public": {
+              "http": [
+                "http://127.0.0.1:8545",
+              ],
+            },
+          },
+        },
+        "key": "public",
+        "name": "Public Client",
+        "pollingInterval": 4000,
+        "request": [Function],
+        "transport": {
+          "getSocket": [Function],
+          "key": "webSocket",
+          "name": "WebSocket JSON-RPC",
+          "request": [Function],
+          "subscribe": [Function],
+          "type": "webSocket",
+        },
+        "type": "publicClient",
+      }
+    `)
+  })
+
+  test('custom', () => {
+    const { uid, ...client } = createPublicClient({
+      transport: custom({ request: async () => null }),
+    })
+
+    expect(uid).toBeDefined()
+    expect(client).toMatchInlineSnapshot(`
+      {
+        "chain": undefined,
+        "key": "public",
+        "name": "Public Client",
+        "pollingInterval": 4000,
+        "request": [Function],
+        "transport": {
+          "key": "custom",
+          "name": "Custom Provider",
+          "request": [Function],
+          "type": "custom",
+        },
+        "type": "publicClient",
+      }
+    `)
+  })
+})