EIP-2696 JavaScript request RPC transport (JavaScript `request` method RPC transport)

Final · Other · EIP status Final · created 2020-06-04

In JavaScript environments, this defines a standard transport method in which an app sends a request through a single request method on the Ethereum provider object and receives the result as a promise.

Why it is needed

In JavaScript runtime environments (NodeJS, Electron, browsers, etc.), the runtime or a plugin can inject an object into an app. Tools such as wallets use this method to expose an Ethereum Provider object to the app, giving the app indirect access to a blockchain like Ethereum and to signing tools. However, if the shape of this object is not standardized, each provider ends up using a different approach, forcing apps to write separate code for each provider. This EIP standardizes the shape of that object so that providers and clients are as compatible as possible. The core idea is sending a request through a single request method and receiving the result or error as a Promise. However, this standard does not cover what request content (payload) is valid or how and where this object should be exposed, leaving those to other standards.

What changes

Today

After EIP-2696

Who is affected

In depth

The EthereumProvider interface

A provider MUST implement a request method on its exposed EthereumProvider object. request must be callable with a single argument of type RequestArguments. RequestArguments consists of a required method field (string) and an optional params field (readonly unknown[] or object). The return type is Promise<unknown>. This standard follows the interpretation of keywords such as MUST and SHOULD as defined in RFC-2119.

Correspondence rules with JSON-RPC requests

If a provider supports a JSON-RPC request defined in another standard, it MUST accept a request call for that JSON-RPC method. In this case, RequestArguments.method must match the JSON-RPC method string, and RequestArguments.params must match the JSON-RPC params object. params must be encoded as a JavaScript object conforming to the specified JSON-RPC type, not as a JSON string. For example, if the JSON-RPC payload is { "jsonrpc": "2.0", "id": 1, "method": "do_work", "params": [ 5, "hello" ] }, the app calls request with a single object containing only method and params. Transport-level fields such as the jsonrpc version or id are not handled by the app.

Result return format

If a provider supports a given JSON-RPC request, it MUST return an object matching the result defined for that request. That is, it returns only the value corresponding to result, not the entire JSON-RPC response ({ "jsonrpc": "2.0", "id": 1, "result": ... }). In the source's example, if the result field of the response payload is { "color": "red", "value": 5 }, the response to request is the object { color: 'red', value: 5 }.

ProviderRpcError and error codes

If a request cannot be processed for any reason, the provider must reject the promise with an error that should, as far as possible, be in the form of ProviderRpcError. ProviderRpcError extends Error and has message (string), code (number), and an optional data (unknown). The codes defined by the standard are 4001 User Rejected Request (the user rejected the request), 4100 Unauthorized (the requested method or account has not been authorized by the user), 4200 Unsupported Method (a method not supported by the provider), 4900 Disconnected (disconnected from all chains), and 4901 Chain Disconnected (not connected to the requested chain). When using a code defined in this table, the JSON-RPC specification, or the relevant request standard, the error's cause must match that code's established meaning, and the message must match the defined message. The data field MAY contain any data that helps understand the error or resolve the issue.

What this standard does not cover

This standard only describes the transport mechanism. It does not specify which payloads are valid or how clients and providers discover and agree on payload content. Nor does it dictate where or how this Ethereum object should be exposed; that is left to later standards. Accordingly, the actual list of usable methods and where the object gets injected are defined by separate standards.

Design rationale, security assumptions, and current status

The source text explains that while this approach may not be the best possible means of communication between apps and the blockchain, it closely follows established community practice, making migration from existing systems relatively easy. Since most communication today happens over JSON-RPC, the design aligns with the JSON-RPC standard for fast integration with existing systems. On the security side, the relationship between provider and client is assumed to be one of trust: the fact that a provider could be injected into the client is taken to mean either that the user implicitly trusts that provider, or that the client explicitly pulled in the connection. This EIP's status is Final, meaning it is a finalized standard.

Original EIP · ← EIPs