Simple Summary

A standard mechanism for JavaScript Ethereum Providers to notify clients about chain state changes when both are able to interface with each other via a shared JavaScript object.

Abstract

This standard provides the description of an object that is made available to JavaScript applications which they can use to receive notifications from an Ethereum Provider. This standard only describes the notification mechanism, it does not specify the payloads that are valid nor does it specify how the client or the provider will discover or agree on payload content.

How/where this Ethereum Provider object is exposed is left to future standards.

Motivation

When working within a JavaScript runtime (such as NodeJS, Electron, Browser, etc.) it may be possible for the runtime or a runtime plugin to inject objects into the runtime. Someone authoring a runtime or a runtime plugin may choose to expose an Ethereum Provider to any JavaScript apps or scripts running within that runtime in order to provide notifications of blockchain state changes. In order to achieve maximum compatibility between the provider and the client, a standard is necessary for what the shape of that object is.

Specification

RFC-2119

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119.

Interface

interface EthereumProvider {
	on(eventName: string, listener: (...params: unknown[]) => void): void
	removeListener(eventName: string, listener: (...params: unknown[]) => void): void
}

The specific events that can be listened to and the shape of their listener callback functions is left to be defined in separate standards.

If on is called with an eventName that the provider is familiar with then the provider MUST call the provided listener when the named event occurs. If the same listener is added multiple times to the same event via on, the provider MAY choose to either callback the listener one time or one time per call to on.

If removeListener is called with an eventName and listener that was previously added via on then the provider MUST decrease the number of times it calls the listener per event by one.

Rationale

This EIP is mostly a retrospective EIP meaning it codifies an already existing specification so there isn't a lot of room for improving things such as by using a discriminated union object for listener parameters or having a tighter definition of on. The specific events are intentionally left out of this specification as that set will be an ever-evolving collection and having the first few listed here doesn't add value to this specification (especially if, over time, the first few end up deprecated or unused).

Security Considerations

The relationship between Ethereum Provider and client is a trusted one, where it is assumed that the user implicitly trusts the Ethereum Provider which is how it managed to get injected into the client, or the client expressly pulled in a connection to it.

Copyright

Copyright and related rights waived via CC0.