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

package/src/clients/transports/webSocket.ts

@@ -0,0 +1,117 @@
+import { UrlRequiredError } from '../../errors'
+import type { Hash } from '../../types'
+import type { RpcResponse } from '../../utils/rpc'
+import { getSocket, rpc } from '../../utils/rpc'
+import type { Transport, TransportConfig } from './createTransport'
+import { createTransport } from './createTransport'
+
+type WebSocketTransportSubscribeArgs = {
+  onData: (data: RpcResponse) => void
+  onError?: (error: any) => void
+}
+
+type WebSocketTransportSubscribeResponse = {
+  subscriptionId: Hash
+  unsubscribe: () => Promise<RpcResponse<boolean>>
+}
+
+type WebSocketTransportSubscribe = {
+  subscribe(
+    args: WebSocketTransportSubscribeArgs & {
+      /**
+       * @description Add information about compiled contracts
+       * @link https://hardhat.org/hardhat-network/docs/reference#hardhat_addcompilationresult
+       */
+      params: ['newHeads']
+    },
+  ): Promise<WebSocketTransportSubscribeResponse>
+}
+
+export type WebSocketTransportConfig = {
+  /** The key of the WebSocket transport. */
+  key?: TransportConfig['key']
+  /** The name of the WebSocket transport. */
+  name?: TransportConfig['name']
+}
+
+export type WebSocketTransport = Transport<
+  'webSocket',
+  {
+    getSocket(): Promise<WebSocket>
+    subscribe: WebSocketTransportSubscribe['subscribe']
+  }
+>
+
+/**
+ * @description Creates a WebSocket transport that connects to a JSON-RPC API.
+ */
+export function webSocket(
+  /** URL of the JSON-RPC API. Defaults to the chain's public RPC URL. */
+  url?: string,
+  {
+    key = 'webSocket',
+    name = 'WebSocket JSON-RPC',
+  }: WebSocketTransportConfig = {},
+): WebSocketTransport {
+  return ({ chain }) => {
+    const url_ = url || chain?.rpcUrls.default.webSocket?.[0]
+    if (!url_) throw new UrlRequiredError()
+    return createTransport(
+      {
+        key,
+        name,
+        async request({ method, params }) {
+          const socket = await getSocket(url_)
+          const { result } = await rpc.webSocketAsync(socket, {
+            body: { method, params },
+          })
+          return result
+        },
+        type: 'webSocket',
+      },
+      {
+        getSocket() {
+          return getSocket(url_)
+        },
+        async subscribe({ params, onData, onError }: any) {
+          const socket = await getSocket(url_)
+          const { result: subscriptionId } = await new Promise<any>(
+            (resolve, reject) =>
+              rpc.webSocket(socket, {
+                body: {
+                  method: 'eth_subscribe',
+                  params,
+                },
+                onData: (data) => {
+                  if (typeof data.id === 'number') {
+                    resolve(data)
+                    return
+                  }
+                  onData(data)
+                },
+                onError: (error) => {
+                  reject(error)
+                  onError?.(error)
+                },
+              }),
+          )
+          return {
+            subscriptionId,
+            async unsubscribe() {
+              return new Promise<any>((resolve, reject) =>
+                rpc.webSocket(socket, {
+                  body: {
+                    method: 'eth_unsubscribe',
+                    params: [subscriptionId],
+                  },
+                  onData: resolve,
+                  onError: reject,
+                }),
+              )
+            },
+          }
+        },
+      },
+    )
+  }
+}

package/src/constants.test.ts

@@ -0,0 +1,27 @@
+import { expect, test } from 'vitest'
+
+import * as constants from './constants'
+
+test('exports constants', () => {
+  expect(constants).toMatchInlineSnapshot(`
+    {
+      "etherUnits": {
+        "gwei": 9,
+        "wei": 18,
+      },
+      "gweiUnits": {
+        "ether": -9,
+        "wei": 9,
+      },
+      "transactionType": {
+        "0x0": "legacy",
+        "0x1": "eip2930",
+        "0x2": "eip1559",
+      },
+      "weiUnits": {
+        "ether": -18,
+        "gwei": -9,
+      },
+    }
+  `)
+})

package/src/constants.ts

@@ -0,0 +1,18 @@
+export const etherUnits = {
+  gwei: 9,
+  wei: 18,
+}
+export const gweiUnits = {
+  ether: -9,
+  wei: 9,
+}
+export const weiUnits = {
+  ether: -18,
+  gwei: -9,
+}
+
+export const transactionType = {
+  '0x0': 'legacy',
+  '0x1': 'eip2930',
+  '0x2': 'eip1559',
+} as const

package/src/errors/abi.test.ts

@@ -0,0 +1,83 @@
+import { expect, test } from 'vitest'
+import {
+  AbiDecodingDataSizeInvalidError,
+  AbiEncodingArrayLengthMismatchError,
+  AbiEncodingLengthMismatchError,
+  InvalidAbiDecodingTypeError,
+  InvalidAbiEncodingTypeError,
+  InvalidArrayError,
+} from './abi'
+
+test('AbiDecodingDataSizeInvalidError', () => {
+  expect(new AbiDecodingDataSizeInvalidError(69)).toMatchInlineSnapshot(`
+    [AbiDecodingDataSizeInvalidError: Data size of 69 bytes is invalid.
+    Size must be in increments of 32 bytes (size % 32 === 0).
+
+    Version: viem@1.0.2]
+  `)
+})
+
+test('InvalidAbiDecodingTypeError', () => {
+  expect(
+    new InvalidAbiDecodingTypeError('lol', { docsPath: '/lol' }),
+  ).toMatchInlineSnapshot(`
+    [InvalidAbiDecodingType: Type "lol" is not a valid decoding type.
+    Please provide a valid ABI type.
+
+    Docs: https://viem.sh/lol
+
+    Version: viem@1.0.2]
+  `)
+})
+
+test('AbiEncodingArrayLengthMismatchError', () => {
+  expect(
+    new AbiEncodingArrayLengthMismatchError({
+      expectedLength: 69,
+      givenLength: 420,
+      type: 'uint256[3]',
+    }),
+  ).toMatchInlineSnapshot(`
+    [AbiEncodingArrayLengthMismatchError: ABI encoding array length mismatch for type uint256[3].
+    Expected length: 69
+    Given length: 420
+
+    Version: viem@1.0.2]
+  `)
+})
+
+test('AbiEncodingLengthMismatchError', () => {
+  expect(
+    new AbiEncodingLengthMismatchError({
+      expectedLength: 69,
+      givenLength: 420,
+    }),
+  ).toMatchInlineSnapshot(`
+    [AbiEncodingLengthMismatchError: ABI encoding params/values length mismatch.
+    Expected length (params): 69
+    Given length (values): 420
+
+    Version: viem@1.0.2]
+  `)
+})
+
+test('InvalidAbiEncodingTypeError', () => {
+  expect(
+    new InvalidAbiEncodingTypeError('lol', { docsPath: '/lol' }),
+  ).toMatchInlineSnapshot(`
+    [InvalidAbiEncodingType: Type "lol" is not a valid encoding type.
+    Please provide a valid ABI type.
+
+    Docs: https://viem.sh/lol
+
+    Version: viem@1.0.2]
+  `)
+})
+
+test('InvalidArrayError', () => {
+  expect(new InvalidArrayError('lol')).toMatchInlineSnapshot(`
+    [InvalidArrayError: Value "lol" is not a valid array.
+
+    Version: viem@1.0.2]
+  `)
+})

package/src/errors/abi.ts

@@ -0,0 +1,238 @@
+import { Hex } from '../types'
+import { BaseError } from './base'
+
+export class AbiConstructorNotFoundError extends BaseError {
+  name = 'AbiConstructorNotFoundError'
+  constructor({ docsPath }: { docsPath: string }) {
+    super(
+      [
+        'A constructor was not found on the ABI.',
+        'Make sure you are using the correct ABI and that the constructor exists on it.',
+      ].join('\n'),
+      {
+        docsPath,
+      },
+    )
+  }
+}
+
+export class AbiConstructorParamsNotFoundError extends BaseError {
+  name = 'AbiConstructorParamsNotFoundError'
+  constructor({ docsPath }: { docsPath: string }) {
+    super(
+      [
+        'Constructor arguments were provided (`args`), but a constructor parameters (`inputs`) were not found on the ABI.',
+        'Make sure you are using the correct ABI, and that the `inputs` attribute on the constructor exists.',
+      ].join('\n'),
+      {
+        docsPath,
+      },
+    )
+  }
+}
+
+export class AbiDecodingDataSizeInvalidError extends BaseError {
+  name = 'AbiDecodingDataSizeInvalidError'
+  constructor(size: number) {
+    super(
+      [
+        `Data size of ${size} bytes is invalid.`,
+        'Size must be in increments of 32 bytes (size % 32 === 0).',
+      ].join('\n'),
+    )
+  }
+}
+
+export class AbiDecodingZeroDataError extends BaseError {
+  name = 'AbiDecodingZeroDataError'
+  constructor() {
+    super('Cannot decode zero data ("0x") with ABI parameters.')
+  }
+}
+
+export class AbiEncodingArrayLengthMismatchError extends BaseError {
+  name = 'AbiEncodingArrayLengthMismatchError'
+  constructor({
+    expectedLength,
+    givenLength,
+    type,
+  }: { expectedLength: number; givenLength: number; type: string }) {
+    super(
+      [
+        `ABI encoding array length mismatch for type ${type}.`,
+        `Expected length: ${expectedLength}`,
+        `Given length: ${givenLength}`,
+      ].join('\n'),
+    )
+  }
+}
+
+export class AbiEncodingLengthMismatchError extends BaseError {
+  name = 'AbiEncodingLengthMismatchError'
+  constructor({
+    expectedLength,
+    givenLength,
+  }: { expectedLength: number; givenLength: number }) {
+    super(
+      [
+        'ABI encoding params/values length mismatch.',
+        `Expected length (params): ${expectedLength}`,
+        `Given length (values): ${givenLength}`,
+      ].join('\n'),
+    )
+  }
+}
+
+export class AbiErrorInputsNotFoundError extends BaseError {
+  name = 'AbiErrorInputsNotFoundError'
+  constructor(errorName: string, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Arguments (\`args\`) were provided to "${errorName}", but "${errorName}" on the ABI does not contain any parameters (\`inputs\`).`,
+        'Cannot encode error result without knowing what the parameter types are.',
+        'Make sure you are using the correct ABI and that the inputs exist on it.',
+      ].join('\n'),
+      {
+        docsPath,
+      },
+    )
+  }
+}
+
+export class AbiErrorNotFoundError extends BaseError {
+  name = 'AbiErrorNotFoundError'
+  constructor(errorName: string, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Error "${errorName}" not found on ABI.`,
+        'Make sure you are using the correct ABI and that the error exists on it.',
+      ].join('\n'),
+      {
+        docsPath,
+      },
+    )
+  }
+}
+
+export class AbiErrorSignatureNotFoundError extends BaseError {
+  name = 'AbiErrorSignatureNotFoundError'
+  constructor(signature: Hex, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Encoded error signature "${signature}" not found on ABI.`,
+        'Make sure you are using the correct ABI and that the error exists on it.',
+        `You can look up the signature "${signature}" here: https://sig.eth.samczsun.com/.`,
+      ].join('\n'),
+      {
+        docsPath,
+      },
+    )
+  }
+}
+
+export class AbiEventNotFoundError extends BaseError {
+  name = 'AbiEventNotFoundError'
+  constructor(eventName: string, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Event "${eventName}" not found on ABI.`,
+        'Make sure you are using the correct ABI and that the event exists on it.',
+      ].join('\n'),
+      {
+        docsPath,
+      },
+    )
+  }
+}
+
+export class AbiFunctionNotFoundError extends BaseError {
+  name = 'AbiFunctionNotFoundError'
+  constructor(functionName: string, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Function "${functionName}" not found on ABI.`,
+        'Make sure you are using the correct ABI and that the function exists on it.',
+      ].join('\n'),
+      {
+        docsPath,
+      },
+    )
+  }
+}
+
+export class AbiFunctionOutputsNotFoundError extends BaseError {
+  name = 'AbiFunctionOutputsNotFoundError'
+  constructor(functionName: string, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Function "${functionName}" does not contain any \`outputs\` on ABI.`,
+        'Cannot decode function result without knowing what the parameter types are.',
+        'Make sure you are using the correct ABI and that the function exists on it.',
+      ].join('\n'),
+      {
+        docsPath,
+      },
+    )
+  }
+}
+
+export class AbiFunctionSignatureNotFoundError extends BaseError {
+  name = 'AbiFunctionSignatureNotFoundError'
+  constructor(signature: Hex, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Encoded function signature "${signature}" not found on ABI.`,
+        'Make sure you are using the correct ABI and that the function exists on it.',
+        `You can look up the signature "${signature}" here: https://sig.eth.samczsun.com/.`,
+      ].join('\n'),
+      {
+        docsPath,
+      },
+    )
+  }
+}
+
+export class InvalidAbiEncodingTypeError extends BaseError {
+  name = 'InvalidAbiEncodingType'
+  constructor(type: string, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Type "${type}" is not a valid encoding type.`,
+        'Please provide a valid ABI type.',
+      ].join('\n'),
+      { docsPath },
+    )
+  }
+}
+
+export class InvalidAbiDecodingTypeError extends BaseError {
+  name = 'InvalidAbiDecodingType'
+  constructor(type: string, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Type "${type}" is not a valid decoding type.`,
+        'Please provide a valid ABI type.',
+      ].join('\n'),
+      { docsPath },
+    )
+  }
+}
+
+export class InvalidArrayError extends BaseError {
+  name = 'InvalidArrayError'
+  constructor(value: unknown) {
+    super([`Value "${value}" is not a valid array.`].join('\n'))
+  }
+}
+
+export class InvalidDefinitionTypeError extends BaseError {
+  name = 'InvalidDefinitionTypeError'
+  constructor(type: string) {
+    super(
+      [
+        `"${type}" is not a valid definition type.`,
+        'Valid types: "function", "event", "error"',
+      ].join('\n'),
+    )
+  }
+}

package/src/errors/address.test.ts

@@ -0,0 +1,14 @@
+import { expect, test } from 'vitest'
+import { InvalidAddressError } from './address'
+
+test('InvalidAddressError', () => {
+  expect(
+    new InvalidAddressError({
+      address: '0xa5cc3c03994db5b0d9a5eEdD10Cabab0813678az',
+    }),
+  ).toMatchInlineSnapshot(`
+    [InvalidAddressError: Address "0xa5cc3c03994db5b0d9a5eEdD10Cabab0813678az" is invalid.
+
+    Version: viem@1.0.2]
+  `)
+})

package/src/errors/address.ts

@@ -0,0 +1,9 @@
+import { Address } from '../types'
+import { BaseError } from './base'
+
+export class InvalidAddressError extends BaseError {
+  name = 'InvalidAddressError'
+  constructor({ address }: { address: Address }) {
+    super(`Address "${address}" is invalid.`)
+  }
+}

package/src/errors/base.test.ts

@@ -0,0 +1,72 @@
+import { expect, test } from 'vitest'
+
+import { BaseError } from './base'
+
+test('BaseError', () => {
+  expect(new BaseError('An error occurred.')).toMatchInlineSnapshot(`
+    [ViemError: An error occurred.
+
+    Version: viem@1.0.2]
+  `)
+
+  expect(
+    new BaseError('An error occurred.', { details: 'details' }),
+  ).toMatchInlineSnapshot(`
+    [ViemError: An error occurred.
+
+    Details: details
+    Version: viem@1.0.2]
+  `)
+})
+
+test('BaseError (w/ docsPath)', () => {
+  expect(
+    new BaseError('An error occurred.', {
+      details: 'details',
+      docsPath: '/lol',
+    }),
+  ).toMatchInlineSnapshot(`
+    [ViemError: An error occurred.
+
+    Docs: https://viem.sh/lol
+
+    Details: details
+    Version: viem@1.0.2]
+  `)
+})
+
+test('inherited BaseError', () => {
+  const err = new BaseError('An error occurred.', {
+    details: 'details',
+    docsPath: '/lol',
+  })
+  expect(
+    new BaseError('An internal error occurred.', {
+      cause: err,
+    }),
+  ).toMatchInlineSnapshot(`
+    [ViemError: An internal error occurred.
+
+    Docs: https://viem.sh/lol
+
+    Details: details
+    Version: viem@1.0.2]
+  `)
+})
+
+test('inherited Error', () => {
+  const err = new Error('details')
+  expect(
+    new BaseError('An internal error occurred.', {
+      cause: err,
+      docsPath: '/lol',
+    }),
+  ).toMatchInlineSnapshot(`
+    [ViemError: An internal error occurred.
+
+    Docs: https://viem.sh/lol
+
+    Details: details
+    Version: viem@1.0.2]
+  `)
+})

package/src/errors/base.ts

@@ -0,0 +1,57 @@
+// @ts-ignore
+import pkg from '../../package.json'
+import { stringify } from '../utils/stringify'
+
+/* c8 ignore next */
+const version = process.env.TEST ? '1.0.2' : pkg.version
+
+type BaseErrorArgs = { docsPath?: string } & (
+  | {
+      cause?: never
+      details?: string
+    }
+  | {
+      cause: BaseError | Error
+      details?: never
+    }
+)
+
+export class BaseError extends Error {
+  humanMessage: string
+  details: string
+  docsPath?: string
+
+  name = 'ViemError'
+
+  constructor(humanMessage: string, args: BaseErrorArgs = {}) {
+    const details =
+      args.cause instanceof BaseError
+        ? args.cause.details
+        : args.cause?.message
+        ? args.cause.message
+        : args.details!
+    const docsPath =
+      args.cause instanceof BaseError
+        ? args.cause.docsPath || args.docsPath
+        : args.docsPath
+    const message = [
+      humanMessage,
+      ...(docsPath ? ['', `Docs: https://viem.sh${docsPath}`] : []),
+      '',
+      ...(details ? [`Details: ${details}`] : []),
+      `Version: viem@${version}`,
+      ...(args.cause &&
+      !(args.cause instanceof BaseError) &&
+      Object.keys(args.cause).length > 0
+        ? [`Internal Error: ${stringify(args.cause)}`]
+        : []),
+    ].join('\n')
+
+    super(message)
+
+    if (args.cause) this.cause = args.cause
+    this.details = details
+    this.docsPath = docsPath
+    this.humanMessage = humanMessage
+  }
+}

package/src/errors/block.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from 'vitest'
+import { BlockNotFoundError } from './block'
+
+test('BlockNotFoundError', () => {
+  expect(
+    new BlockNotFoundError({ blockNumber: 69420n }),
+  ).toMatchInlineSnapshot(`
+      [BlockNotFoundError: Block at number "69420" could not be found.
+
+      Version: viem@1.0.2]
+    `)
+  expect(
+    new BlockNotFoundError({ blockHash: '0x69420' }),
+  ).toMatchInlineSnapshot(`
+      [BlockNotFoundError: Block at hash "0x69420" could not be found.
+
+      Version: viem@1.0.2]
+    `)
+  expect(new BlockNotFoundError({})).toMatchInlineSnapshot(`
+    [BlockNotFoundError: Block could not be found.
+
+    Version: viem@1.0.2]
+  `)
+})

package/src/errors/block.ts

@@ -0,0 +1,18 @@
+import { Hash } from '../types'
+import { BaseError } from './base'
+
+export class BlockNotFoundError extends BaseError {
+  name = 'BlockNotFoundError'
+  constructor({
+    blockHash,
+    blockNumber,
+  }: {
+    blockHash?: Hash
+    blockNumber?: bigint
+  }) {
+    let identifier = 'Block'
+    if (blockHash) identifier = `Block at hash "${blockHash}"`
+    if (blockNumber) identifier = `Block at number "${blockNumber}"`
+    super(`${identifier} could not be found.`)
+  }
+}