diff --git a/EIPS/eip-1193.md b/EIPS/eip-1193.md index 628e2c9e945234..3556d1a53b21ae 100644 --- a/EIPS/eip-1193.md +++ b/EIPS/eip-1193.md @@ -30,8 +30,7 @@ Makes an Ethereum RPC method call. ```typescript interface RequestArguments { method: string; - params?: unknown; - [key: string]: unknown; + params?: unknown[] | object; } Provider.request(args: RequestArguments): Promise; @@ -299,7 +298,7 @@ In practice, this convention does not handle some situations, including: - Multiple Providers being injected into the same page, e.g. when the user has multiple wallets installed - Asynchronously injected Providers, whether by choice or due to platform limitations -Provider implementers are encouraged to work with each other and with dapp developers to solve these problems until standards emerge. +The authors encourage Provider implementers to work with each other and with dapp developers to solve these problems until standards emerge. ### Connectivity @@ -312,9 +311,10 @@ The Provider is said to be "disconnected" when it cannot service RPC requests to ### API -The Provider **MUST** expose the API defined in this section. All API entities **MUST** adhere to the types and interfaces defined in this section. +> The Provider API is specified using TypeScript. +> The authors encourage implementers to declare their own types and interfaces, using the ones in this section as a basis. -The Provider **MAY** expose methods and properties not specified in this document. +The Provider **MUST** implement and expose the API defined in this section. All API entities **MUST** adhere to the types and interfaces defined in this section. #### request @@ -323,21 +323,19 @@ The Provider **MAY** expose methods and properties not specified in this documen ```typescript interface RequestArguments { method: string; - params?: unknown; - [key: string]: unknown; + params?: unknown[] | object; } Provider.request(args: RequestArguments): Promise; ``` -The `request` method **MUST** send a properly formatted request to the Provider's Ethereum client. -Requests **MUST** be handled such that, for a given set of arguments, the returned Promise either resolves with a value per the RPC method's specification, or rejects with an error. +The Provider **MUST** identify the requested RPC method by the value of `RequestArguments.method`. -The `args` object **MAY** include properties not mentioned in this specification. +If the requested RPC method takes any parameters, the Provider **MUST** accept them as the value of `RequestArguments.params`. -If resolved, the Promise **MUST NOT** resolve with any RPC protocol-specific response objects, unless the RPC method's return type is so defined by its specification. +RPC requests **MUST** be handled such that the returned Promise either resolves with a value per the requested RPC method's specification, or rejects with an error. -If resolved, the Promise **MUST** resolve with a result per the RPC method's specification. +If resolved, the Promise **MUST** resolve with a result per the RPC method's specification. The Promise **MUST NOT** resolve with any RPC protocol-specific response objects, unless the RPC method's return type is so defined. If the returned Promise rejects, it **MUST** reject with a `ProviderRpcError` as specified in the [RPC Errors](#rpc-errors) section below. @@ -366,8 +364,6 @@ All supported RPC methods **MUST** be identified by unique strings. Providers **MAY** support whatever RPC methods required to fulfill their purpose, standardized or otherwise. -If a Provider supports a method defined in a finalized EIP, the Provider's implementation of this method **MUST** adhere to the method's specification. - If an RPC method defined in a finalized EIP is not supported, it **SHOULD** be rejected with a `4200` error per the [Provider Errors](#provider-errors) section below, or an appropriate error per the RPC method's specification. #### RPC Errors @@ -407,20 +403,20 @@ interface ProviderRpcError extends Error { | 4100 | Unauthorized | The requested method and/or account has not been authorized by the user. | | 4200 | Unsupported Method | The Provider does not support the requested method. | | 4900 | Disconnected | The Provider is disconnected from all chains. | -| 4901 | Chain Disconnected | The Provider is not connected to the requested chain. | +| 4901 | Chain Disconnected | The Provider is not connected to the requested chain. | > `4900` is intended to indicate that the Provider is disconnected from all chains, while `4901` is intended to indicate that the Provider is disconnected from a specific chain only. > In other words, `4901` implies that the Provider is connected to other chains, just not the requested one. ### Events -The Provider **SHOULD** extend the [Node.js `EventEmitter`](https://nodejs.org/api/events.html) to provide dapps flexibility in listening to events. In place of full `EventEmitter` functionality, the Provider **MAY** provide as many methods as it can reasonably provide, but **MUST** provide at least `on`, `emit`, and `removeListener`. +The Provider **SHOULD** extend the [Node.js `EventEmitter`](https://nodejs.org/api/events.html) to provide dapps flexibility in listening to events. -#### message +The Provider **MUST** implement at least the following methods `EventEmitter` methods: `on`, `emit`, and `removeListener` -The Provider **MAY** emit the event named `message`, for any reason. +#### message -If the Provider supports Ethereum RPC subscriptions, e.g. [`eth_subscribe`](https://geth.ethereum.org/docs/rpc/pubsub), the Provider **MUST** emit the `message` event when it receives a subscription notification. +> The `message` event is intended for arbitrary notifications not covered by other events. When emitted, the `message` event **MUST** be emitted with an object argument of the following form: @@ -431,6 +427,8 @@ interface ProviderMessage { } ``` +If the Provider supports Ethereum RPC subscriptions, e.g. [`eth_subscribe`](https://geth.ethereum.org/docs/rpc/pubsub), the Provider **MUST** emit the `message` event when it receives a subscription notification. + ##### Converting a Subscription Message to a ProviderMessage If the Provider receives a subscription message from e.g. an `eth_subscribe` subscription, the Provider **MUST** emit a `message` event with a `ProviderMessage` object of the following form: @@ -461,14 +459,11 @@ This event **MUST** be emitted with an object of the following form: ```typescript interface ProviderConnectInfo { chainId: string; - [key: string]: unknown; } ``` `chainId` **MUST** specify the integer ID of the connected chain as a hexadecimal string, per the [`eth_chainId`](https://eips.ethereum.org/EIPS/eip-695) Ethereum RPC method. -The `ProviderConnectInfo` object **MAY** contain any other `string` properties with values of any type. - #### disconnect See the section [Connectivity](#connectivity) for the definition of "disconnected".