EIP-2700 Standard for JavaScript provider event notifications (JavaScript Provider Event Emitter)
Final · Other · EIP status Final · created 2020-06-05
Standardizes the JavaScript event listening methods (on, removeListener) that Ethereum providers, such as browser wallets, use to notify web apps of chain state changes.
Why it is needed
In JavaScript execution environments such as web browsers or NodeJS, plugins like wallet extensions can inject objects into the runtime. This is how wallets expose an Ethereum provider object to web apps and notify them when blockchain state changes occur. However, if the shape of this object differs from wallet to wallet, apps must write wallet-specific code, and a feature that works fine with one wallet can break with another. For providers and apps to be maximally compatible, a standard is needed for what shape this object should take. This EIP codifies the event notification approach that wallets were already using at the time into a standard document, so that any wallet and any app can exchange notifications the same way.
What changes
Today
- Notification mechanisms can differ across providers, forcing apps to adapt to each wallet's specific implementation
- There is no guaranteed rule for how event subscription and unsubscription should behave
After EIP-2700
- The two methods on and removeListener unify how events are subscribed to and unsubscribed from
- It is now guaranteed that a registered listener will be called whenever the corresponding event occurs
- App developers can handle any standard-compliant provider with the same code
Who is affected
- Web app (dapp) developers: They can receive chain state changes through a single standard interface, instead of writing separate notification code for each wallet.
- Wallet/provider developers: The minimal shape and behavioral rules that an object exposed to apps must satisfy become clear.
- Users: A foundation is established for an app's event-driven features (such as reflecting state changes) to behave consistently regardless of which wallet is used.
In depth
The EthereumProvider interface
The standard requires only two methods: on(eventName: string, listener: (...params: unknown[]) => void): void and removeListener(eventName: string, listener: (...params: unknown[]) => void): void. The event name is a string, and the listener is a callback function that accepts any number of arguments of type unknown. This standard does not define which events can be listened for or what shape of arguments the listener callback receives; that is left to separate standards.
Behavior rules for on
When on is called with an eventName that the provider recognizes, the provider MUST call the given listener whenever that event occurs. If the same listener is added multiple times for the same event via on, the provider MAY choose to call the listener only once or to call it as many times as it was added. In other words, how duplicate registrations are handled can vary by implementation, so apps are safer not registering the same listener more than once.
Behavior rules for removeListener
When removeListener is called with the same eventName and listener combination previously added via on, the provider MUST decrease the call count for that listener on that event by 1. This means registration is managed on a per-count basis, so fully removing a listener that was registered multiple times may require calling removeListener the same number of times.
Why only the notification mechanism is defined, leaving the event list empty
This standard only describes the framework for exchanging notifications. It does not define what constitutes a valid payload or how clients and providers discover and agree on payload content. The concrete set of events is considered an ever-changing list, so listing an initial few here was judged not to add value to the standard. It also notes that, over time, some initial events may be deprecated or fall out of use.
A retrospective standard documenting existing practice
The source text describes this EIP as essentially a retrospective standard. Because it codifies a specification that already existed, there was little room for improvements such as using a discriminated union object for listener arguments or tightening the definition of on. It also leaves where and how this provider object is exposed to later standards. Its status is finalized as Final.
Security model: provider and client are in a trust relationship
The source text presupposes that the relationship between provider and client is 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 that connection. Accordingly, this standard does not include separate mechanisms to protect apps from a malicious provider.