mirror of
https://github.com/status-im/EIPs.git
synced 2025-02-24 04:38:29 +00:00
15f61ed0fd
I have gone through and updated all existing EIPs to match this rule, including EIP-1. In some cases, people were using markdown citations, I suspect because the long-form was a bit verbose to inline. Since the relative path is quite short, I moved these to inline but I wouldn't be opposed to putting them back to citation format if that is desired by the authors. In doing the migration/cleanup, I found some EIP references to EIPs that don't actually exist. In these cases I tried to excise the reference from the EIP as best I could. It is worth noting that the Readme actually already had this rule, it just wasn't expressed properly in EIP-1 and the "Citation Format" section of the readme I think caused people a bit of confusion (when citing externally, you should use the citation format).
72 lines
2.8 KiB
Markdown
72 lines
2.8 KiB
Markdown
---
|
||
eip: 2786
|
||
title: Ethereum Provider Connect/Disconnect Events
|
||
author: Micah Zoltu (@MicahZoltu), Erik Marks (@rekmarks)
|
||
discussions-to: https://github.com/ethereum/EIPs/issues/2787
|
||
status: Last Call
|
||
review-period-end: 2020-07-31
|
||
type: Standards Track
|
||
category: Interface
|
||
created: 2020-07-15
|
||
requires: 2700
|
||
---
|
||
|
||
## Simple Summary
|
||
|
||
When an Ethereum Provider becomes connected or disconnected, it will emit a `connect`/`disconnect` event.
|
||
|
||
## Abstract
|
||
|
||
The Provider is said to be “connected” when it can service RPC requests to at least one chain.
|
||
The Provider is said to be “disconnected” when it cannot service RPC requests to any chain at all.
|
||
When the Provider switches from a "connected" state to a "disconnected" state, it will emit a `connect` event.
|
||
When the Provider switches from a "disconnected" state to a "connected" state, it will emit a `disconnect` event.
|
||
|
||
## Motivation
|
||
|
||
When an application is hooked up to an Ethereum provider, there is value in having the application be alerted of connect/disconnect events that may occur so the application can appropriately inform the user of the situation.
|
||
It is left up to the application to decide whether to listen in on these events, and how to handle them.
|
||
|
||
## Specification
|
||
|
||
### Definitions
|
||
|
||
#### Connected
|
||
|
||
The Provider is considered `connected` when it is able to service RPC requests to at least one chain.
|
||
|
||
#### Disconnected
|
||
|
||
The Provider is considered `disconnected` when it is unable to service RPC requests to any chain.
|
||
|
||
### Events
|
||
|
||
#### `connect`
|
||
|
||
The Provider **MUST** emit a `connect` event to all attached [EIP-2700](./eip-2700.md) listeners if it transitions from a `disconnected` state to a `connected` state.
|
||
All attached listeners **MUST** be called with the parameter `{ chainId }`.
|
||
`chainId` **MUST** specify the integer ID of the connected chain encoded as a hexadecimal string.
|
||
If the Provider supports the `eth_chainId` JSON-RPC method or a derivation of it, then the `chainId` **MUST** match the return value of `eth_chainId`.
|
||
The Provider **MAY** call the attached listeners in any order.
|
||
|
||
## 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 having a connect/disconnect event per chain.
|
||
|
||
## 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](https://creativecommons.org/publicdomain/zero/1.0/).
|
||
|
||
## Appendix I: Examples
|
||
|
||
```javascript
|
||
// connect
|
||
provider.on('connect', ({ chainId }) => {
|
||
console.log(`Provider connected to: ${chainId}`);
|
||
});
|
||
```
|