Documentation

Documentation »API »Providers »JSON-RPC Provider

JSON-RPC Provider

About JSON-RPC...

Types
JsonRpcApiPollingProvider
JsonRpcApiProvider
JsonRpcProvider
JsonRpcSigner
JsonRpcTransactionRequest

<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 , polling?: boolean , staticNetwork?: null | 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 used 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)

<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.

<src>abstract class JsonRpcApiPollingProvider

inherits fromJsonRpcApiProvider, AbstractProvider, Provider, ContractRunner, EventEmitterable, NameResolver

<src>jsonRpcApiPollingProvider.pollingInterval⇒ number

The polling interval (default: 4000 ms)

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

<src>abstract class JsonRpcApiProvider

inherits fromAbstractProvider, Provider, ContractRunner, EventEmitterable, NameResolver

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

<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.

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

<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._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.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.

<src>class JsonRpcProvider

inherits fromJsonRpcApiPollingProvider, JsonRpcApiProvider, AbstractProvider, Provider, ContractRunner, EventEmitterable, NameResolver

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.

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

<src>jsonRpcProvider._getConnection()⇒ FetchRequest

<src>class JsonRpcSigner

inherits fromAbstractSigner, Signer, Addressable, ContractRunner, NameResolver

<src>jsonRpcSigner.address⇒ string

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

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

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

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

<src>interface JsonRpcTransactionRequest

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

<src>jsonRpcTransactionRequest.chainId⇒ string

<src>jsonRpcTransactionRequest.data⇒ string

<src>jsonRpcTransactionRequest.from⇒ string

<src>jsonRpcTransactionRequest.gas⇒ string

<src>jsonRpcTransactionRequest.gasPrice⇒ string

<src>jsonRpcTransactionRequest.maxFeePerGas⇒ string

<src>jsonRpcTransactionRequest.maxPriorityFeePerGas⇒ string

<src>jsonRpcTransactionRequest.nonce⇒ string

<src>jsonRpcTransactionRequest.to⇒ string

<src>jsonRpcTransactionRequest.type⇒ string

<src>jsonRpcTransactionRequest.value⇒ string