HomeEIPs
EIPsEIP-2700
EIP-2700

JavaScript Provider Event Emitter

FinalStandards Track: Interface
Created: 2020-06-05
Micah Zoltu (@MicahZoltu), Erik Marks (@rekmarks)
DiscussionsOriginal linkEdit
1 min read

EIP-2700 proposes 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. It 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. The specific events that can be listened to and the shape of their listener callback functions is left to be defined in separate standards.

Video
Anyone may contribute to propose contents.
Go propose
Original

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 and related rights waived via CC0.

Further reading
Anyone may contribute to propose contents.
Go propose
Adopted by projects
Anyone may contribute to propose contents.
Go propose

Not miss a beat of EIPs' update?

Subscribe EIPs Fun to receive the latest updates of EIPs Good for Buidlers to follow up.

View all
Serve EIP builders, scale Ethereum.
Resources
GitHub
Supported by