viem 0.0.1-cjs.10 → 0.0.1-sushi.26

package/src/utils/ens/normalize.bench.ts

@@ -0,0 +1,14 @@
+import { describe, bench } from 'vitest'
+import { ens_normalize } from '@adraffy/ens-normalize'
+
+import { normalize } from './normalize'
+
+describe('Normalize ENS name', () => {
+  bench('viem: `normalize`', () => {
+    normalize('\u{0061}wkw𝝣b.eth')
+  })
+
+  bench('@adraffy/ens-normalize: `ens_normalize`', () => {
+    ens_normalize('\u{0061}wkw𝝣b.eth')
+  })
+})

package/src/utils/ens/normalize.test.ts

@@ -0,0 +1,35 @@
+import { test, expect } from 'vitest'
+import { normalize } from './normalize'
+
+test.each([
+  { name: 'awkweb.eth', expected: 'awkweb.eth' },
+  { name: 'Awkweb.eth', expected: 'awkweb.eth' },
+  { name: '🖖.eth', expected: '🖖.eth' },
+  { name: 'awkw𝝣b.eth', expected: 'awkwξb.eth' },
+  { name: '\u{0061}wkweb.eth', expected: 'awkweb.eth' },
+  { name: '\u{0061}wkw\u{0065}b.eth', expected: 'awkweb.eth' },
+  { name: 'awkweb.eth', expected: 'awkweb.eth' },
+  //       ^ latin small "a"
+  { name: 'awkweb.eth', expected: 'awkweb.eth' },
+  //           ^ latin small "e"
+])("normalize('$name') -> '$expected'", ({ name, expected }) => {
+  expect(normalize(name)).toBe(expected)
+})
+
+test('invalid label extension', () => {
+  expect(() => normalize('34--A.eth')).toThrowErrorMatchingInlineSnapshot(
+    '"Failed to validate 34--a"',
+  )
+})
+
+test('illegal placement: leading combining mark', () => {
+  expect(() => normalize('\u{303}.eth')).toThrowErrorMatchingInlineSnapshot(
+    '"Label contains illegal character: 771"',
+  )
+})
+
+test('underscore allowed only at start', () => {
+  expect(() => normalize('a_b_c.eth')).toThrowErrorMatchingInlineSnapshot(
+    '"Illegal char _"',
+  )
+})

package/src/utils/ens/normalize.ts

@@ -0,0 +1,14 @@
+import { toUnicode } from 'idna-uts46-hx'
+
+/**
+ * @description Normalizes ENS name
+ *
+ * @example
+ * normalize('wagmi-dev.eth')
+ * 'wagmi-dev.eth'
+ *
+ * @see https://docs.ens.domains/contract-api-reference/name-processing#normalising-names
+ */
+export function normalize(name: string) {
+  return toUnicode(name, { useStd3ASCII: true })
+}

package/src/utils/ens/packetToBytes.test.ts

@@ -0,0 +1,11 @@
+import { test, expect } from 'vitest'
+import { encodeHex } from '../encoding'
+import { packetToBytes } from './packetToBytes'
+
+test.each([
+  { packet: 'awkweb.eth', expected: '0x0661776b7765620365746800' },
+  { packet: 'foo.awkweb.eth', expected: '0x03666f6f0661776b7765620365746800' },
+  { packet: '.', expected: '0x00' },
+])("packetToBytes('$packet') -> '$expected'", ({ packet, expected }) => {
+  expect(encodeHex(packetToBytes(packet))).toBe(expected)
+})

package/src/utils/ens/packetToBytes.ts

@@ -0,0 +1,29 @@
+// Adapted from https://github.com/mafintosh/dns-packet
+import { ByteArray } from '../../types'
+import { encodeBytes } from '../encoding'
+
+/*
+ * @description Encodes a DNS packet into a ByteArray containing a UDP payload.
+ */
+export function packetToBytes(packet: string): ByteArray {
+  function length(value: string) {
+    if (value === '.' || value === '..') return 1
+    return encodeBytes(value.replace(/^\.|\.$/gm, '')).length + 2
+  }
+
+  const bytes = new Uint8Array(length(packet))
+  // strip leading and trailing `.`
+  const value = packet.replace(/^\.|\.$/gm, '')
+  if (!value.length) return bytes
+
+  let offset = 0
+  const list = value.split('.')
+  for (let i = 0; i < list.length; i++) {
+    const encoded = encodeBytes(list[i])
+    bytes[offset] = encoded.length
+    bytes.set(encoded, offset + 1)
+    offset += encoded.length + 1
+  }
+
+  return bytes
+}

package/src/utils/formatters/block.bench.ts

@@ -0,0 +1,51 @@
+import { providers } from 'ethers'
+import { bench, describe } from 'vitest'
+
+import type { RpcBlock } from '../../types'
+import { formatBlock } from './block'
+
+const block: RpcBlock = {
+  baseFeePerGas: '0x1',
+  difficulty: '0x2d3a678cddba9b',
+  extraData: '0x',
+  gasLimit: '0x1c9c347',
+  gasUsed: '0x0',
+  hash: '0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd',
+  logsBloom:
+    '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
+  miner: '0x0000000000000000000000000000000000000000',
+  mixHash: '0x0000000000000000000000000000000000000000000000000000000000000000',
+  nonce: '0x0000000000000000',
+  number: '0xec6fc6',
+  parentHash:
+    '0xe55516ad8029e53cd32087f14653d851401b05245abb1b2d6ed4ddcc597ac5a6',
+  receiptsRoot:
+    '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
+  sealFields: [
+    '0x0000000000000000000000000000000000000000000000000000000000000000',
+    '0x0000000000000000',
+  ],
+  sha3Uncles:
+    '0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347',
+  size: '0x208',
+  stateRoot:
+    '0x0000000000000000000000000000000000000000000000000000000000000000',
+  timestamp: '0x63198f6f',
+  totalDifficulty: '0x1',
+  transactions: [],
+  transactionsRoot:
+    '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
+  uncles: [],
+}
+
+const formatter = new providers.Formatter()
+
+describe('Format Block', () => {
+  bench('viem: `formatBlock`', () => {
+    formatBlock(block)
+  })
+
+  bench('ethers: `formatter.block`', () => {
+    formatter.block(block)
+  })
+})

package/src/utils/formatters/block.test.ts

@@ -0,0 +1,115 @@
+import { expect, test } from 'vitest'
+
+import type { RpcBlock } from '../../types'
+
+import { formatBlock } from './block'
+
+const block: RpcBlock = {
+  baseFeePerGas: '0x0',
+  difficulty: '0x2d3a678cddba9b',
+  extraData: '0x',
+  gasLimit: '0x1c9c347',
+  gasUsed: '0x0',
+  hash: '0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd',
+  logsBloom:
+    '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
+  miner: '0x0000000000000000000000000000000000000000',
+  mixHash: '0x0000000000000000000000000000000000000000000000000000000000000000',
+  nonce: '0x0000000000000000',
+  number: '0xec6fc6',
+  parentHash:
+    '0xe55516ad8029e53cd32087f14653d851401b05245abb1b2d6ed4ddcc597ac5a6',
+  receiptsRoot:
+    '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
+  sealFields: [
+    '0x0000000000000000000000000000000000000000000000000000000000000000',
+    '0x0000000000000000',
+  ],
+  sha3Uncles:
+    '0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347',
+  size: '0x208',
+  stateRoot:
+    '0x0000000000000000000000000000000000000000000000000000000000000000',
+  timestamp: '0x63198f6f',
+  totalDifficulty: '0x1',
+  transactions: [],
+  transactionsRoot:
+    '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
+  uncles: [],
+}
+
+test('deserializes block', () => {
+  expect(formatBlock(block)).toMatchInlineSnapshot(`
+    {
+      "baseFeePerGas": 0n,
+      "difficulty": 12730590371363483n,
+      "extraData": "0x",
+      "gasLimit": 29999943n,
+      "gasUsed": 0n,
+      "hash": "0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd",
+      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+      "miner": "0x0000000000000000000000000000000000000000",
+      "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+      "nonce": "0x0000000000000000",
+      "number": 15495110n,
+      "parentHash": "0xe55516ad8029e53cd32087f14653d851401b05245abb1b2d6ed4ddcc597ac5a6",
+      "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+      "sealFields": [
+        "0x0000000000000000000000000000000000000000000000000000000000000000",
+        "0x0000000000000000",
+      ],
+      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+      "size": 520n,
+      "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
+      "timestamp": 1662619503n,
+      "totalDifficulty": 1n,
+      "transactions": [],
+      "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+      "uncles": [],
+    }
+  `)
+})
+
+test('nullish values', () => {
+  expect(
+    formatBlock({
+      ...block,
+      difficulty: undefined,
+      number: null,
+      baseFeePerGas: undefined,
+      gasLimit: undefined,
+      gasUsed: undefined,
+      size: undefined,
+      timestamp: undefined,
+      totalDifficulty: undefined,
+    }),
+  ).toMatchInlineSnapshot(`
+    {
+      "baseFeePerGas": null,
+      "difficulty": undefined,
+      "extraData": "0x",
+      "gasLimit": undefined,
+      "gasUsed": undefined,
+      "hash": "0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd",
+      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+      "miner": "0x0000000000000000000000000000000000000000",
+      "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+      "nonce": "0x0000000000000000",
+      "number": null,
+      "parentHash": "0xe55516ad8029e53cd32087f14653d851401b05245abb1b2d6ed4ddcc597ac5a6",
+      "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+      "sealFields": [
+        "0x0000000000000000000000000000000000000000000000000000000000000000",
+        "0x0000000000000000",
+      ],
+      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+      "size": undefined,
+      "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
+      "timestamp": undefined,
+      "totalDifficulty": null,
+      "transactions": [],
+      "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+      "uncles": [],
+    }
+  `)
+})

package/src/utils/formatters/block.ts

@@ -0,0 +1,37 @@
+import type { Chain, Block, Formatter, Formatters, RpcBlock } from '../../types'
+import { defineFormatter, ExtractFormatter, Formatted } from './format'
+import { formatTransaction } from './transaction'
+
+export type BlockFormatter<TChain extends Chain = Chain> = ExtractFormatter<
+  TChain,
+  'block',
+  NonNullable<Formatters['block']>
+>
+
+export type FormattedBlock<
+  TFormatter extends Formatter | undefined = Formatter,
+> = Formatted<TFormatter, Block>
+
+export function formatBlock(block: Partial<RpcBlock>) {
+  // TODO: Properly format transactions with a custom formatter
+  const transactions = block.transactions?.map((transaction) => {
+    if (typeof transaction === 'string') return transaction
+    return formatTransaction(transaction)
+  })
+  return {
+    ...block,
+    baseFeePerGas: block.baseFeePerGas ? BigInt(block.baseFeePerGas) : null,
+    difficulty: block.difficulty ? BigInt(block.difficulty) : undefined,
+    gasLimit: block.gasLimit ? BigInt(block.gasLimit) : undefined,
+    gasUsed: block.gasUsed ? BigInt(block.gasUsed) : undefined,
+    number: block.number ? BigInt(block.number) : null,
+    size: block.size ? BigInt(block.size) : undefined,
+    timestamp: block.timestamp ? BigInt(block.timestamp) : undefined,
+    transactions,
+    totalDifficulty: block.totalDifficulty
+      ? BigInt(block.totalDifficulty)
+      : null,
+  } as Block
+}
+
+export const defineBlock = defineFormatter({ format: formatBlock })

package/src/utils/formatters/extract.test.ts

@@ -0,0 +1,14 @@
+import { expect, test } from 'vitest'
+import { extract } from './extract'
+
+test('default', () => {
+  expect(
+    extract({ foo: 1, bar: 'wagmi' }, { formatter: () => ({ foo: null }) }),
+  ).toEqual({ foo: 1 })
+  expect(
+    extract({ foo: 1, bar: 'wagmi' }, { formatter: () => ({ baz: null }) }),
+  ).toEqual({})
+  expect(extract({ foo: 1, bar: 'wagmi' }, { formatter: undefined })).toEqual(
+    {},
+  )
+})

package/src/utils/formatters/extract.ts

@@ -0,0 +1,18 @@
+import { Formatter } from '../../types'
+
+/**
+ * @description Picks out the keys from `value` that exist in the formatter.
+ */
+export function extract(
+  value: Record<string, unknown>,
+  { formatter }: { formatter?: Formatter },
+) {
+  if (!formatter) return {}
+  const keys = Object.keys(formatter({}))
+  return keys.reduce((data, key) => {
+    if (value?.hasOwnProperty(key)) {
+      ;(data as any)[key] = value[key]
+    }
+    return data
+  }, {})
+}

package/src/utils/formatters/feeHistory.test.ts

@@ -0,0 +1,66 @@
+import { expect, test } from 'vitest'
+
+import type { RpcFeeHistory } from '../../types'
+
+import { formatFeeHistory } from './feeHistory'
+
+const feeHistory: RpcFeeHistory = {
+  baseFeePerGas: [
+    '0x27a818102',
+    '0x256704d4c',
+    '0x2831941e9',
+    '0x25fca330e',
+    '0x2433d4457',
+  ],
+  gasUsedRatio: [0.2726281302071925, 0.79851, 0.2803831724987217, 0.3121027],
+  oldestBlock: '0xe6e55d',
+  reward: [
+    ['0x3b9aca00', '0x9502f900', '0x70a6e163e'],
+    ['0x3b9aca00', '0x59682f00', '0x11eb2a58b4'],
+    ['0x8f13544', '0x77359400', '0xac25db817'],
+    ['0x3b9aca00', '0x5a6b9a89', '0x81a6b4ef2'],
+  ],
+}
+
+test('deserializes fee history', () => {
+  expect(formatFeeHistory(feeHistory)).toMatchInlineSnapshot(`
+    {
+      "baseFeePerGas": [
+        10645242114n,
+        10040134988n,
+        10789405161n,
+        10197021454n,
+        9718023255n,
+      ],
+      "gasUsedRatio": [
+        0.2726281302071925,
+        0.79851,
+        0.2803831724987217,
+        0.3121027,
+      ],
+      "oldestBlock": 15131997n,
+      "reward": [
+        [
+          1000000000n,
+          2500000000n,
+          30239757886n,
+        ],
+        [
+          1000000000n,
+          1500000000n,
+          76959865012n,
+        ],
+        [
+          150025540n,
+          2000000000n,
+          46210594839n,
+        ],
+        [
+          1000000000n,
+          1517001353n,
+          34802978546n,
+        ],
+      ],
+    }
+  `)
+})

package/src/utils/formatters/feeHistory.ts

@@ -0,0 +1,12 @@
+import type { FeeHistory, RpcFeeHistory } from '../../types'
+
+export function formatFeeHistory(feeHistory: RpcFeeHistory): FeeHistory {
+  return {
+    baseFeePerGas: feeHistory.baseFeePerGas.map((value) => BigInt(value)),
+    gasUsedRatio: feeHistory.gasUsedRatio,
+    oldestBlock: BigInt(feeHistory.oldestBlock),
+    reward: feeHistory.reward?.map((reward) =>
+      reward.map((value) => BigInt(value)),
+    ),
+  }
+}

package/src/utils/formatters/format.test.ts

@@ -0,0 +1,93 @@
+import { expect, test } from 'vitest'
+
+import type { RpcBlock } from '../../types'
+
+import { format } from './format'
+
+const data: RpcBlock = {
+  baseFeePerGas: '0x0',
+  difficulty: '0x2d3a678cddba9b',
+  extraData: '0x',
+  gasLimit: '0x1c9c347',
+  gasUsed: '0x0',
+  hash: '0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd',
+  logsBloom:
+    '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
+  miner: '0x0000000000000000000000000000000000000000',
+  mixHash: '0x0000000000000000000000000000000000000000000000000000000000000000',
+  nonce: '0x0000000000000000',
+  number: '0xec6fc6',
+  parentHash:
+    '0xe55516ad8029e53cd32087f14653d851401b05245abb1b2d6ed4ddcc597ac5a6',
+  receiptsRoot:
+    '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
+  sealFields: [
+    '0x0000000000000000000000000000000000000000000000000000000000000000',
+    '0x0000000000000000',
+  ],
+  sha3Uncles:
+    '0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347',
+  size: '0x208',
+  stateRoot:
+    '0x0000000000000000000000000000000000000000000000000000000000000000',
+  timestamp: '0x63198f6f',
+  totalDifficulty: null,
+  transactions: [],
+  transactionsRoot:
+    '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
+  uncles: [],
+}
+
+function formatter(block: RpcBlock & { [key: string]: unknown }) {
+  return {
+    ...block,
+    baseFeePerGas: block.baseFeePerGas ? BigInt(block.baseFeePerGas) : null,
+    difficulty: block.difficulty ? BigInt(block.difficulty) : undefined,
+    gasLimit: block.gasLimit ? BigInt(block.gasLimit) : undefined,
+    gasUsed: block.gasUsed ? BigInt(block.gasUsed) : undefined,
+    number: block.number ? BigInt(block.number) : null,
+    size: block.size ? BigInt(block.size) : undefined,
+    timestamp: block.timestamp ? BigInt(block.timestamp) : undefined,
+    totalDifficulty: block.totalDifficulty
+      ? BigInt(block.totalDifficulty)
+      : null,
+    foo: 'bar',
+  }
+}
+
+test('formats', () => {
+  expect(
+    format(data, {
+      formatter,
+    }),
+  ).toMatchInlineSnapshot(`
+    {
+      "baseFeePerGas": 0n,
+      "difficulty": 12730590371363483n,
+      "extraData": "0x",
+      "foo": "bar",
+      "gasLimit": 29999943n,
+      "gasUsed": 0n,
+      "hash": "0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd",
+      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+      "miner": "0x0000000000000000000000000000000000000000",
+      "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+      "nonce": "0x0000000000000000",
+      "number": 15495110n,
+      "parentHash": "0xe55516ad8029e53cd32087f14653d851401b05245abb1b2d6ed4ddcc597ac5a6",
+      "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+      "sealFields": [
+        "0x0000000000000000000000000000000000000000000000000000000000000000",
+        "0x0000000000000000",
+      ],
+      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+      "size": 520n,
+      "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
+      "timestamp": 1662619503n,
+      "totalDifficulty": null,
+      "transactions": [],
+      "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+      "uncles": [],
+    }
+  `)
+})

package/src/utils/formatters/format.ts

@@ -0,0 +1,90 @@
+import type { Chain, Formatter, OptionalNullable } from '../../types'
+
+export type ExtractFormatter<
+  TChain extends Chain,
+  TKey extends keyof NonNullable<TChain['formatters']>,
+  TFallbackFormatter extends Formatter = Formatter,
+> = NonNullable<TChain['formatters']>[TKey] extends NonNullable<unknown>
+  ? NonNullable<TChain['formatters']>[TKey]
+  : TFallbackFormatter
+
+export type FormatOptions<TSource, TTarget> = {
+  formatter: Formatter<TSource, TTarget>
+}
+
+/**
+ * Creates a type that is the result of applying `TFormatter` to `TSource`.
+ *
+ * @example
+ * Formatted<() => { a: undefined, b: bigint }, { a: bigint }>
+ * => { a: undefined, b: bigint }
+ *
+ * @example
+ * Formatted<() => {}, { a: bigint }>
+ * => { a: bigint }
+ *
+ * @example
+ * Formatted<() => { a: bigint | undefined, b: bigint }, { a: bigint, b: bigint }, true>
+ * => { a?: bigint | undefined, b: bigint }
+ */
+export type Formatted<
+  TFormatter,
+  TFallback,
+  TAllowOptional = false,
+> = TFormatter extends Formatter
+  ? // If Formatter attributes exist, attach them; otherwise attach the Target type (e.g. Block).
+    ReturnType<TFormatter> extends Record<string, never>
+    ? TFallback
+    : TAllowOptional extends true
+    ? OptionalNullable<ReturnType<TFormatter>>
+    : ReturnType<TFormatter>
+  : never
+
+/**
+ * @description Formats a data object using the given replacer and an optional formatter.
+ */
+export function format<
+  TFormatter,
+  TSource extends Record<string, any>,
+  TTarget,
+>(data: TSource, { formatter }: FormatOptions<TSource, TTarget>) {
+  return formatter(data) as Formatted<TFormatter, TTarget>
+}
+
+export 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
+        }
+    }
+}

package/src/utils/formatters/index.test.ts

@@ -0,0 +1,27 @@
+import { expect, test } from 'vitest'
+
+import * as formatters from './index'
+
+test('exports formatters', () => {
+  expect(formatters).toMatchInlineSnapshot(`
+    {
+      "defineBlock": [Function],
+      "defineFormatter": [Function],
+      "defineTransaction": [Function],
+      "defineTransactionReceipt": [Function],
+      "defineTransactionRequest": [Function],
+      "extract": [Function],
+      "format": [Function],
+      "formatBlock": [Function],
+      "formatFeeHistory": [Function],
+      "formatTransaction": [Function],
+      "formatTransactionReceipt": [Function],
+      "formatTransactionRequest": [Function],
+      "transactionType": {
+        "0x0": "legacy",
+        "0x1": "eip2930",
+        "0x2": "eip1559",
+      },
+    }
+  `)
+})

package/src/utils/formatters/index.ts

@@ -0,0 +1,34 @@
+export type { BlockFormatter, FormattedBlock } from './block'
+export { defineBlock, formatBlock } from './block'
+
+export { extract } from './extract'
+
+export { formatFeeHistory } from './feeHistory'
+
+export type { ExtractFormatter, FormatOptions, Formatted } from './format'
+export { defineFormatter, format } from './format'
+
+export type { FormattedTransaction, TransactionFormatter } from './transaction'
+export {
+  defineTransaction,
+  formatTransaction,
+  transactionType,
+} from './transaction'
+
+export type {
+  FormattedTransactionReceipt,
+  TransactionReceiptFormatter,
+} from './transactionReceipt'
+export {
+  defineTransactionReceipt,
+  formatTransactionReceipt,
+} from './transactionReceipt'
+
+export type {
+  FormattedTransactionRequest,
+  TransactionRequestFormatter,
+} from './transactionRequest'
+export {
+  defineTransactionRequest,
+  formatTransactionRequest,
+} from './transactionRequest'