EIP-1193 Ethereum Provider JavaScript API

Final · Other · EIP status Final · created 2018-06-30

Standardizes the API of the provider, the JavaScript object a web app uses to talk to Ethereum through a wallet. With just one method (request) and five events, every wallet behaves the same way.

Why it is needed

Ethereum apps (dapps) running on the web talk to the blockchain through the provider, a JavaScript object that the wallet injects into the web page. Before this standard existed, though, each wallet had its own provider interface and behavior. Some wallets used sendAsync, others used send, and event names differed as well. App developers had to write separate code for each wallet, and apps that only worked with a specific wallet appeared. EIP-1193 cleans up this confusion by defining a minimal common API that every wallet must implement identically. It defines only one method for sending requests (request) and five events, and does not concern itself with the transport mechanism or the type of RPC protocol, so it can be used in any environment. Functionality can easily be extended by adding new RPC methods and message event types.

What changes

Today

After EIP-1193

Who is affected

In depth

The request method

The provider accepts all RPC requests through a single request(args) method. The argument follows the RequestArguments interface, where method is a string identifying the RPC method to call, and params is an optional, read-only array or object. The return value is a Promise. On success it MUST resolve with the result value defined by that RPC method's specification, and unless the method's return type is defined that way, it must not resolve with an RPC-protocol-specific response object. Rejections MUST use a ProviderRpcError. If an RPC request comes back with an error, or if the provider fails to process the request for any reason, it MUST reject, and SHOULD reject with code 4900 if the provider is disconnected from all chains, or code 4901 if the request targets a specific chain that alone is not connected. The authors recommend rejecting authorization failures with a 4100 error.

Error standard and provider error codes

All errors follow the ProviderRpcError interface, which extends Error. message MUST be a human-readable string, code MUST be an integer, and data SHOULD hold other useful information. For codes and messages, it is recommended to follow, in order of priority, first the provider error table, second the errors defined by the RPC method specification that produced the error, and third CloseEvent status codes. The provider error table has five entries: 4001 User Rejected Request (the user rejected the request), 4100 Unauthorized (the requested method or account is not authorized for the user), 4200 Unsupported Method (a method the provider does not support), 4900 Disconnected (disconnected from all chains), and 4901 Chain Disconnected (not connected to the requested chain specifically). 4901 also implies that the provider is connected to other chains. If an RPC method defined in a finalized EIP is not supported, it is recommended to reject with a 4200 error or with the error defined by that method's specification.

Definition of connection state and the connect/disconnect events

A provider is defined as 'connected' if it can process RPC requests for at least one chain, and as 'disconnected' if it cannot process requests for any chain. Processing a request means successfully sending the request to a remote endpoint and receiving a response, so if network issues prevent communication with the client, the provider is disconnected. The provider MUST emit a connect event when it first connects to a chain after initialization, or when it reconnects after a disconnect event, and in that case the chainId field of the ProviderConnectInfo object must hold the connected chain's integer ID as an eth_chainId-style hexadecimal string. If it disconnects from all chains, it MUST emit a disconnect event together with a ProviderRpcError value, and that error's code must follow CloseEvent status codes.

State-change events: chainChanged and accountsChanged

The provider MUST implement the two event-handling methods on and removeListener according to the Node.js EventEmitter API. Implementers are advised to consider bundling by extending the EventEmitter class. If the connected chain changes, it MUST emit a chainChanged event together with chainId, a hexadecimal string holding the new chain's integer ID. If the accounts available to the provider change, it MUST emit an accountsChanged event together with an array of account addresses in the eth_accounts format. A change in 'available accounts' is defined as a change in the return value of eth_accounts. Since every Ethereum operation targets a specific chain, the spec states that it is also important for security that eth_chainId's return value be accurate and that chainChanged fire every time that value changes.

The message event and subscription notifications

The message event is a channel for arbitrary notifications not covered by other events. When it fires, it MUST pass a ProviderMessage object with a type string and data. If the provider supports Ethereum RPC subscriptions such as eth_subscribe, it MUST emit a message event every time a subscription notification arrives. In this case the object takes the EthSubscription shape, where type is the string 'eth_subscription' and data holds a subscription string and a result. The original example shows subscribing to newHeads via eth_subscribe, then checking the type and subscription ID in the message event to receive new blocks.

Design rationale: one method and five events

A provider's purpose is to give consumers access to Ethereum, and a web app only needs to be able to do two things: send Ethereum RPC requests and react to state changes in the chain, client, or wallet. The spec consists of one method and five events, but in fact a complete provider can be implemented with just the request method and the message event, since they are designed to handle arbitrary RPC requests and arbitrary message delivery respectively. The remaining four events fall into two categories: connect and disconnect, which signal changes in RPC request capability, and chainChanged and accountsChanged, which are common client/wallet state changes that any app needs to handle. These events were included because the related patterns were already in wide use in production at the time of writing.

Backwards compatibility and the legacy API

Many providers first adopted pre-finalization draft versions. The current API is designed as a strict superset of the legacy version and is in that sense fully backwards compatible. However, a provider implementing only this spec is not compatible with existing web apps built against the legacy API. In the legacy API, the sendAsync and send methods are replaced by request, the close event is replaced by disconnect, the networkChanged event is replaced by chainChanged, and the notification event is replaced by message. The legacy API was never fully standardized and varies widely across implementations, so the authors recommend against implementing it unless the goal is supporting legacy apps.

Security considerations: the provider operates in an adversarial environment

A provider only relays RPC messages and emits events between an Ethereum client and an app; it is not responsible for private keys or account management. Account security and user privacy must be implemented in the layer between the provider and the client, that is, the wallet. Because a provider is a JavaScript object exposed in an untrusted environment controlled by a third party such as a website, consumers can read and overwrite every property on it. It is therefore best to treat it as an attacker-controlled object. Implementers should avoid putting private user data in the provider, isolate the provider from the wallet program, rate-limit requests on the wallet or client side, and validate all data. For user privacy, implementations should also avoid exposing accounts by default and instead support RPC methods that explicitly request account access, such as eth_requestAccounts (EIP-1102) or wallet_requestPermissions (EIP-2255).

Original EIP · ← EIPs