eth-rpc-errors

What is eth-rpc-errors?

The eth-rpc-errors package provides utilities for creating and managing Ethereum JSON-RPC errors. It helps standardize error handling in Ethereum-related applications by providing predefined error codes and messages.

What are eth-rpc-errors's main functionalities?

Creating Custom Errors

This feature allows you to create custom errors with specific codes, messages, and additional data. It is useful for defining application-specific error conditions.

const { ethErrors } = require('eth-rpc-errors');

const customError = ethErrors.rpc.custom({
  code: 1234,
  message: 'Custom error message',
  data: { additional: 'info' }
});

console.log(customError);

Predefined Errors

The package provides predefined errors for common JSON-RPC error conditions, such as invalid parameters, method not found, and internal errors. This helps standardize error responses across different applications.

const { ethErrors } = require('eth-rpc-errors');

const invalidParamsError = ethErrors.rpc.invalidParams('Invalid parameters provided');

console.log(invalidParamsError);

Error Serialization

This feature allows you to serialize JavaScript errors into a format that can be easily transmitted over JSON-RPC. It ensures that error information is consistently formatted.

const { serializeError } = require('eth-rpc-errors');

const error = new Error('Something went wrong');
const serializedError = serializeError(error);

console.log(serializedError);

Other packages similar to eth-rpc-errors

json-rpc-error

The json-rpc-error package provides utilities for creating and managing JSON-RPC errors. It offers similar functionality to eth-rpc-errors but is not specific to Ethereum. It can be used in any JSON-RPC based application.

jsonrpc-lite

The jsonrpc-lite package is a lightweight JSON-RPC 2.0 and 1.0 implementation. It includes error handling utilities similar to eth-rpc-errors but also provides full JSON-RPC request and response handling capabilities.

json-rpc-protocol

The json-rpc-protocol package provides a complete implementation of the JSON-RPC 2.0 protocol, including error handling. It offers a more comprehensive solution compared to eth-rpc-errors, which focuses solely on error management.

README

eth-rpc-errors

Ethereum RPC errors, including for Ethereum JSON RPC and Ethereum Provider, and making unknown errors compliant with either spec.

Basic Usage

import { ethErrors } from 'eth-rpc-errors'

throw ethErrors.provider.unauthorized()
// or
throw ethErrors.provider.unauthorized('my custom message')

Supported Errors

• Ethereum JSON RPC
  • Per EIP-1474
    • This includes all JSON RPC 2.0 errors
• Ethereum Provider errors
  • Per EIP-1193
    • Does not yet support CloseEvent errors or status codes.

Usage

Installation: npm install eth-rpc-errors or yarn add eth-rpc-errors

import or require as normal (no default export).

Errors API

import { ethErrors } from 'eth-rpc-errors'

// Ethereum RPC errors are namespaced under "ethErrors.rpc"
response.error = ethErrors.rpc.methodNotFound({
  message: optionalCustomMessage, data: optionalData
})

// Provider errors namespaced under ethErrors.provider
response.error = ethErrors.provider.unauthorized({
  message: optionalCustomMessage, data: optionalData
})

// each error getter takes a single "opts" argument
// for most errors, this can be replaced with a single string, which becomes
// the error message
response.error = ethErrors.provider.unauthorized(customMessage)

// if an error getter accepts a single string, all arguments can be omitted
response.error = ethErrors.provider.unauthorized()
response.error = ethErrors.provider.unauthorized({})

// omitting the message will produce an error with a default message per
// the relevant spec

// omitting the data argument will produce an error without a
// "data" property

// the JSON RPC 2.0 server error requires a valid code
response.error = ethErrors.rpc.server({
  code: -32031
})

// custom Ethereum Provider errors require a valid code and message
// valid codes are integers i such that: 1000 <= i <= 4999
response.error = ethErrors.provider.custom({
  code: 1001, message: 'foo'
})

Parsing Unknown Errors

// this is useful for ensuring your errors are standardized
import { serializeError } from 'eth-rpc-errors'

// if the argument is not a valid error per any supported spec,
// it will be added as error.data.originalError
response.error = serializeError(maybeAnError)

// you can add a custom fallback error code and message if desired
const fallbackError = { code: 4999, message: 'My custom error.' }
response.error = serializeError(maybeAnError, fallbackError)

// Note: if the original error has a "message" property, it will take
// precedence over the fallback error's message

// the default fallback is:
{
  code: -32603,
  message: 'Internal JSON-RPC error.'
}

Other Exports

/**
 * TypeScript interfaces
 */
import {
  // these describe to the corresponding exports from index.js
  IEthErrors, IEthereumRpcError, IEthereumProviderError, ISerializeError,
  // these describe the options argument to error getters in ethErrors
  IErrorOptions, IRpcServerErrorOptions, IProviderCustomErrorOptions
} from 'eth-rpc-errors/@types'

/**
 * Classes
 */
import { EthereumRpcError, EthereumProviderError } from 'eth-rpc-errors'

/**
 * getMessageFromCode and errorCodes
 */
import { getMessageFromCode, errorCodes } from 'eth-rpc-errors'

// get the default message string for the given code, or a fallback message if
// no message exists for the given code
const message1 = getMessageFromCode(someCode)

// you can specify your own fallback message
const message2 = getMessageFromCode(someCode, myFallback)
// it can be anything, use at your own peril
const message3 = getMessageFromCode(someCode, null)

// {
//   rpc: { [errorName]: code, ... },
//   provider: { [errorName]: code, ... },
// }
const code1 = errorCodes.rpc.parse
const code2 = errorCodes.provider.userRejectedRequest

// all codes in errorCodes have default messages
const message4 = getMessageFromCode(code1)
const message5 = getMessageFromCode(code2)

License

MIT

Changelog

[4.0.0] - 2020-11-02

Changed

• BREAKING: ERROR_CODES export renamed to errorCodes (#28)
• BREAKING: ethErrors getters will now throw an error if passed a truthy, non-string message (#28)
• Updated TypeScript types for all exports (#28)