Documentation

Documentation »API »Providers »JSON-RPC Provider

JSON-RPC Provider

One of the most common ways to interact with the blockchain is by a node running a JSON-RPC interface which can be connected to, based on the transport, using:

HTTP or HTTPS - JsonRpcProvider
WebSocket - WebSocketProvider
IPC - IpcSocketProvider

TYPES

<src>DebugEventJsonRpcApiProvider⇒ { action: "sendRpcPayload" , payload: JsonRpcPayload | Array< JsonRpcPayload > } | { action: "receiveRpcResult" , result: Array< JsonRpcResult | JsonRpcError > } | { action: "receiveRpcError" , error: Error }

When subscribing to the "debug" event, the Listener will receive this object as the first parameter.

<src>JsonRpcApiProviderOptions⇒ { batchMaxCount?: number , batchMaxSize?: number , batchStallTime?: number , cacheTimeout?: number , polling?: boolean , pollingInterval?: number , staticNetwork?: null | boolean | Network }

Options for configuring a JsonRpcApiProvider. Much of this is targetted towards sub-classes, which often will not expose any of these options to their consumers.

polling - use the polling strategy is used immediately for events; otherwise, attempt to use filters and fall back onto polling (default: false)

staticNetwork - do not request chain ID on requests to validate the underlying chain has not changed (default: null)

This should ONLY be used if it is certain that the network cannot change, such as when using INFURA (since the URL dictates the network). If the network is assumed static and it does change, this can have tragic consequences. For example, this CANNOT be used with MetaMask, since the user can select a new network from the drop-down at any time.

batchStallTime - how long (ms) to aggregate requests into a single batch. 0 indicates batching will only encompass the current event loop. If batchMaxCount = 1, this is ignored. (default: 10)

batchMaxSize - target maximum size (bytes) to allow per batch request (default: 1Mb)

batchMaxCount - maximum number of requests to allow in a batch. If batchMaxCount = 1, then batching is disabled. (default: 100)

cacheTimeout - passed as AbstractProviderOptions.

<src>JsonRpcError⇒ { error: { code: number , data?: any , message?: string } , id: number }

A JSON-RPC error, which are returned on failure from a JSON-RPC server.

<src>JsonRpcPayload⇒ { id: number , jsonrpc: "2.0" , method: string , params: Array< any > | Record< string, any > }

A JSON-RPC payload, which are sent to a JSON-RPC server.

<src>JsonRpcResult⇒ { id: number , result: any }

A JSON-RPC result, which are returned on success from a JSON-RPC server.

abstract class JsonRpcApiProvider

inherits from AbstractProvider, Provider

The JsonRpcApiProvider is an abstract class and MUST be sub-classed.

It provides the base for all JSON-RPC-based Provider interaction.

Sub-classing Notes:

a sub-class MUST override _send
a sub-class MUST call the `_start()` method once connected

PROPERTIES

<src>jsonRpcApiProvider._network⇒ Networkread-only

Gets the Network this provider has committed to. On each call, the network is detected, and if it has changed, the call will reject.

<src>jsonRpcApiProvider.ready⇒ booleanread-only

Returns true only if the _start has been called.

CREATING INSTANCES

<src>new JsonRpcApiProvider(network?: Networkish, options?: JsonRpcApiProviderOptions)

METHODS

<src>jsonRpcApiProvider._detectNetwork()⇒ Promise< Network >

Sub-classes may override this; it detects the *actual* network that we are currently connected to.

Keep in mind that send may only be used once ready, otherwise the _send primitive must be used instead.

<src>jsonRpcApiProvider._getOption(key: K)⇒ TODO(A3B[object Object][[object Object]])

Returns the value associated with the option key.

Sub-classes can use this to inquire about configuration options.

<src>jsonRpcApiProvider._getSubscriber(sub: Subscription)⇒ Subscriber

Return a Subscriber that will manage the sub.

Sub-classes may override this to modify the behavior of subscription management.

<src>jsonRpcApiProvider._perform(req: PerformActionRequest)⇒ Promise< any >

Resolves to the non-normalized value by performing req.

Sub-classes may override this to modify behavior of actions, and should generally call super._perform as a fallback.

<src>jsonRpcApiProvider._send(payload: JsonRpcPayload | Array< JsonRpcPayload >)⇒ Promise< Array< JsonRpcResult | JsonRpcError > >abstract

Sends a JSON-RPC payload (or a batch) to the underlying channel.

Sub-classes MUST override this.

<src>jsonRpcApiProvider._start()⇒ void

Sub-classes MUST call this. Until _start has been called, no calls will be passed to _send from send. If it is overridden, then super._start() MUST be called.

Calling it multiple times is safe and has no effect.

<src>jsonRpcApiProvider._waitUntilReady()⇒ Promise< void >

Resolves once the _start has been called. This can be used in sub-classes to defer sending data until the connection has been established.

<src>jsonRpcApiProvider.getRpcError(payload: JsonRpcPayload, error: JsonRpcError)⇒ Error

Returns an ethers-style Error for the given JSON-RPC error payload, coalescing the various strings and error shapes that different nodes return, coercing them into a machine-readable standardized error.

<src>jsonRpcApiProvider.getRpcRequest(req: PerformActionRequest)⇒ null | { args: Array< any > , method: string }

Returns the request method and arguments required to perform req.

<src>jsonRpcApiProvider.getRpcTransaction(tx: TransactionRequest)⇒ JsonRpcTransactionRequest

Returns tx as a normalized JSON-RPC transaction request, which has all values hexlified and any numeric values converted to Quantity values.

<src>jsonRpcApiProvider.getSigner(address?: number | string)⇒ Promise< JsonRpcSigner >

Resolves to the Signer account for address managed by the client.

If the address is a number, it is used as an index in the the accounts from listAccounts.

This can only be used on clients which manage accounts (such as Geth with imported account or MetaMask).

Throws if the account doesn't exist.

<src>jsonRpcApiProvider.listAccounts()⇒ Promise< Array< JsonRpcSigner > >

<src>jsonRpcApiProvider.send(method: string, params: Array< any > | Record< string, any >)⇒ Promise< any >

Requests the method with params via the JSON-RPC protocol over the underlying channel. This can be used to call methods on the backend that do not have a high-level API within the Provider API.

This method queues requests according to the batch constraints in the options, assigns the request a unique ID.

Do NOT override this method in sub-classes; instead override _send or force the options values in the call to the constructor to modify this method's behavior.

class JsonRpcProvider

The JsonRpcProvider is one of the most common Providers, which performs all operations over HTTP (or HTTPS) requests.

Events are processed by polling the backend for the current block number; when it advances, all block-base events are then checked for updates.

CREATING INSTANCES

<src>new JsonRpcProvider(url?: string | FetchRequest, network?: Networkish, options?: JsonRpcApiProviderOptions)

METHODS

<src>jsonRpcProvider._getConnection()⇒ FetchRequest

<src>jsonRpcProvider._send(payload: JsonRpcPayload | Array< JsonRpcPayload >)⇒ Promise< Array< JsonRpcResult > >

<src>jsonRpcProvider.send(method: string, params: Array< any > | Record< string, any >)⇒ Promise< any >

class JsonRpcSigner

inherits from AbstractSigner, Signer

PROPERTIES

<src>jsonRpcSigner.address⇒ string

CREATING INSTANCES

<src>new JsonRpcSigner(provider: JsonRpcApiProvider, address: string)

METHODS

<src>jsonRpcSigner._legacySignMessage(message: string | Uint8Array)⇒ Promise< string >

<src>jsonRpcSigner.sendUncheckedTransaction(tx: TransactionRequest)⇒ Promise< string >

<src>jsonRpcSigner.unlock(password: string)⇒ Promise< boolean >

interface JsonRpcTransactionRequest

A JsonRpcTransactionRequest is formatted as needed by the JSON-RPC Ethereum API specification.

PROPERTIES

<src>jsonRpcTransactionRequest.accessList⇒ Array< { address: string , storageKeys: Array< string > } >

The transaction access list.

<src>jsonRpcTransactionRequest.chainId⇒ string

The chain ID the transaction is valid on.

<src>jsonRpcTransactionRequest.data⇒ string

The transaction data.

<src>jsonRpcTransactionRequest.from⇒ string

The sender address to use when signing.

<src>jsonRpcTransactionRequest.gas⇒ string

The maximum amount of gas to allow a transaction to consume.

In most other places in ethers, this is called gasLimit which differs from the JSON-RPC Ethereum API specification.

<src>jsonRpcTransactionRequest.gasPrice⇒ string

The gas price per wei for transactions prior to EIP-1559.

<src>jsonRpcTransactionRequest.maxFeePerGas⇒ string

The maximum fee per gas for EIP-1559 transactions.

<src>jsonRpcTransactionRequest.maxPriorityFeePerGas⇒ string

The maximum priority fee per gas for EIP-1559 transactions.

<src>jsonRpcTransactionRequest.nonce⇒ string

The nonce for the transaction.

<src>jsonRpcTransactionRequest.to⇒ string

The target address.

<src>jsonRpcTransactionRequest.type⇒ string

The EIP-2718 transaction type.

<src>jsonRpcTransactionRequest.value⇒ string

The transaction value (in wei).