From 8c31a9b78b5017a51957a2bfd3459f5d175080fc Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Sun, 3 Mar 2019 14:14:33 +0100 Subject: [PATCH] Automatically merged updates to draft EIP(s) 1193 Hi, I'm a bot! This change was automatically merged because: - It only modifies existing Draft or Last Call EIP(s) - The PR was approved or written by at least one author of each modified EIP - The build is passing --- EIPS/eip-1193.md | 46 +++++++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/EIPS/eip-1193.md b/EIPS/eip-1193.md index 4302426f..26fd23fb 100644 --- a/EIPS/eip-1193.md +++ b/EIPS/eip-1193.md @@ -1,13 +1,12 @@ --- eip: 1193 title: Ethereum Provider JavaScript API -author: Ryan Ghods (@ryanio), Marc Garreau (@marcgarreau), Fabian Vogelsteller (@frozeman), Victor Maia (@MaiaVictor) +author: Fabian Vogelsteller (@frozeman), Ryan Ghods (@ryanio), Marc Garreau (@marcgarreau), Victor Maia (@MaiaVictor) discussions-to: https://ethereum-magicians.org/t/eip-1193-ethereum-provider-javascript-api/640 status: Draft type: Standards Track category: Interface created: 2018-06-30 -requires: 1102 --- ## Summary @@ -42,13 +41,22 @@ Events are emitted using [EventEmitter](https://nodejs.org/api/events.html). #### notification -All subscriptions from the node emit on `notification`. Attach listeners with: +All subscriptions from the node emit on "subscription type" (e.g. `eth_subscription`, or `ssh_subscription`). Attach listeners with: ```js -ethereum.on('notification', listener: (result: any) => void): this; +ethereum.on('eth_subscription', listener: (result: any) => void): this; ``` -To create a subscription, call `ethereum.send('eth_subscribe')` or `ethereum.send('shh_subscribe')`. The subscription `result` object will emit through `notification`. +To create a subscription, call `ethereum.send('eth_subscribe')` or `ethereum.send('shh_subscribe')`. The subscription object will emit through the specifc subscription type. + +The result object will look as follows: + +```js +{ + "subscription":"0xc3b33aa549fb9a60e95d21862596617c", + "result": {...} +} +``` See the [eth subscription methods](https://github.com/ethereum/go-ethereum/wiki/RPC-PUB-SUB#supported-subscriptions) and [shh subscription methods](https://github.com/ethereum/go-ethereum/wiki/Whisper-v6-RPC-API#shh_subscribe). @@ -102,10 +110,11 @@ The event emits with `accounts`, an array of the accounts' addresses. ```js const ethereum = window.ethereum; -// A) Primary use case - set provider in web3.js -web3.setProvider(ethereum); +// A) Set provider in web3.js +var web3 = new Web3(ethereum); -// B) Secondary use case - use provider object directly + +// B) Use provider object directly // Example 1: Log last block ethereum .send('eth_getBlockByNumber', ['latest', 'true']) @@ -119,6 +128,7 @@ ethereum ); }); + // Example 2: Request accounts ethereum .send('eth_requestAccounts') @@ -136,6 +146,7 @@ ethereum ); }); + // Example 3: Log available accounts ethereum .send('eth_accounts') @@ -149,13 +160,14 @@ ethereum ); }); + // Example 4: Log new blocks let subId; ethereum .send('eth_subscribe', ['newHeads']) .then(subscriptionId => { subId = subscriptionId; - ethereum.on('notification', result => { + ethereum.on('eth_subscription', result => { if (result.subscription === subscriptionId) { if (result.result instanceof Error) { const error = result.result; @@ -176,6 +188,7 @@ ethereum Code: ${error.code}. Data: ${error.data}` ); }); + // to unsubscribe ethereum .send('eth_unsubscribe', [subId]) @@ -189,6 +202,7 @@ ethereum ); }); + // Example 5: Log when accounts change const logAccounts = accounts => { console.log(`Accounts:\n${accounts.join('\n')}`); @@ -205,19 +219,13 @@ ethereum.on('close', (code, reason) => { ## Specification -### Send +### Errors -The `send` method **MUST** send a properly formatted [JSON-RPC request](https://www.jsonrpc.org/specification#request_object). - -If the Ethereum JSON-RPC API returns a response object with no error, then the Promise **MUST** resolve with the `response.result` object untouched by the implementing Ethereum Provider. - -If the Ethereum JSON-RPC API returns response object that contains an error property then the Promise **MUST** reject with an Error object containing the `response.error.message` as the Error message, `response.error.code` as a code property on the error and `response.error.data` as a data property on the error. +If the Ethereum Provider request returns an error property then the Promise **MUST** reject with an Error object containing the `error.message` as the Error message, `error.code` as a code property on the error and `error.data` as a data property on the error. If an error occurs during processing, such as an HTTP error or internal parsing error, then the Promise **MUST** reject with an `Error` object. -If the implementing Ethereum Provider is not talking to an external Ethereum JSON-RPC API provider then it **MUST** resolve with an object that matches the JSON-RPC API object as specified in the [Ethereum JSON-RPC documentation](https://github.com/ethereum/wiki/wiki/JSON-RPC). - -If the JSON-RPC request requires an account that is not yet authenticated, the Promise **MUST** reject with Error code 4100. +If the request requires an account that is not yet authenticated, the Promise **MUST** reject with Error code 4100. #### eth_requestAccounts @@ -237,7 +245,7 @@ The provider **SHOULD** extend from `EventEmitter` to provide dapps flexibility #### notification -All subscriptions received from the node **MUST** emit the `message.params` to the eventName `notification` without modification. +All subscriptions received from the node **MUST** emit the `subscription` property with the subscription ID and a `results` property. #### connect