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
- There is no common standard for the shape of the object a provider exposes to an app
- Communication between apps and blockchains mainly uses JSON-RPC, but the way it is invoked inside JavaScript can vary
- The shape and meaning of errors when a request fails are not unified
After EIP-2696
- Every provider implements an EthereumProvider object with a single request method
- Request arguments (method, params) are passed as-is as a JavaScript object rather than a JSON string
- On failure, the error follows the common ProviderRpcError specification with message, code, and data
Who is affected
- App (dapp) developers: Whatever provider is injected, requests can be sent using the same request call, reducing provider-specific branching code.
- Wallet and provider implementers: Implementing the request method and the ProviderRpcError error specification is mandatory, and since it aligns with existing JSON-RPC conventions, migration is easy.
- Library developers: web3-family libraries can handle providers against a single common interface.
- Users: There is no directly noticeable change, but standardizing the integration between wallets and apps reduces compatibility problems.
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.