---
eip: 2700
title: JavaScript Provider Event Emitter
author: Micah Zoltu (@MicahZoltu), Erik Marks (@rekmarks)
discussions-to: https://github.com/ethereum/EIPs/issues/2701
status: Final
type: Standards Track
category: Interface
created: 2020-06-05
---

## 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](https://www.ietf.org/rfc/rfc2119.txt).

### Interface
```ts
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](../LICENSE.md).