From 46b6bfa2c63b06db15b6242a388e8b64d4a66808 Mon Sep 17 00:00:00 2001 From: Gregory Markou Date: Sun, 26 Jul 2020 15:35:06 -0400 Subject: [PATCH 1/7] eip-2831 --- EIPS/eip-2831.md | 121 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 EIPS/eip-2831.md diff --git a/EIPS/eip-2831.md b/EIPS/eip-2831.md new file mode 100644 index 00000000000000..b635491a71b0b2 --- /dev/null +++ b/EIPS/eip-2831.md @@ -0,0 +1,121 @@ +--- +eip: 2831 +title: Transaction Replacement Message Type +author: Gregory Markou (@GregTheGreek) +discussions-to: [eth magicians](https://ethereum-magicians.org/t/eip-2831-transaction-replacement-message-type/4448) +status: Draft +type: Standards Track +category: Interface +created: 2020-07-26 +requires: 1193 +--- + +## Summary + +An extension to the JavaScript Ethereum Proider API ([EIP-1193](https://eips.ethereum.org/EIPS/eip-1193)) this creates a new message type in the event a transaction replacement occurs. + +## Abstract + +Exert from EIP-1193 +> A common convention in the Ethereum web application ("dapp") ecosystem is for key management software ("wallets") to expose their API via a JavaScript object in the web page. +This object is called "the Provider". + +Many ingenious developments have been made by wallet developers to improve the overall user experience while interacting with the Ethereum blockchain. One specific innovation was the tx replacement, offering users the ability to effectively cancel a previously sent transaction. + +Transaction replacement is not a new concept, but unfortunately causes major user experience problems for dapp developers as the replaced transaction is near impossible to track. + +This EIP formalizes a way for both providers and dapp developers to track transaction replacements seamlessly. + +This specification does not cover how one would utilize the transaction replacement message. + +## Specification + +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). + +> Comments like this are non-normative. + +### Definitions + +_This section is non-normative._ + +- Provider + - A JavaScript object made available to a consumer, that provides access to Ethereum by means of a Client. +- Client + - An endpoint that receives Remote Procedure Call (RPC) requests from the Provider, and returns their results. +- Wallet + - An end-user application that manages private keys, performs signing operations, and acts as a middleware between the Provider and the Client. +- Remote Procedure Call (RPC) + - A Remote Procedure Call (RPC), is any request submitted to a Provider for some procedure that is to be processed by a Provider, its Wallet, or its Client. +- Transaction Replacement + - Submitting a transaction with both: the same nonce and a 10% increase in the gas price, of a previous transaction which a user no longer wishes to send. This must occur before the original transaction is included in the blockchain. + +### Interface + +The `data` parameter contains two values: `oldTx` and `newTx`,the transaction hash that's being superseded and the transaction hash of the successor, respectively. + +```JavaScript +interface TxReplacement extends ProviderMessage { + readonly type: 'tx_replacement'; + readonly data: { + readonly oldTx: string; + readonly newTx: string; + }; +} +``` + +## Rationale + +The purpose of `tx_replacement` is to provide a user experience improvement to both wallet users and dapp developers. It can be implemented without breaking changes and leverages the existing framework set out by EIP-1193. + +## Backwards Compatibility + +Many Providers adopted EIP-1193, as this EIP extends the arbitrary `message` event, there should be no breaking changes. All providers that do not support the new `tx_replacement` message should either I) Ignore the message or II) Provide some error to the user (Out of scope). + +## Implementations + +At the time of writing, no projects have working implementations. + +## References + +- [Web3.js issue with metamask tx cancel](https://github.com/ethereum/web3.js/issues/3585) +- [Browser doesn't know when a transaction is replace](https://github.com/MetaMask/metamask-extension/issues/3347) + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## Appendix I: Consumer-Facing API Documentation + + +## Appendix II: Examples + +These examples assume a web browser environment. + +```javascript +// Most Providers are available as window.ethereum on page load. +// This is only a convention, not a standard, and may not be the case in practice. +// Please consult the Provider implementation's documentation. +const ethereum = window.ethereum; + +ethereum.on('message', (message) => { + if (message.type === 'tx_replacement') { + const { oldTx, newTx } = message.data; + console.log(`Tx ${oldTx} was cancelled, the new hash is ${newTx}`) + } +}); + +const transactionParameters = { ... } // Fill in parameters + +ethereum + .request({ + method: 'eth_sendTransaction', + params: [transactionParameters], + }) + .then((txHash) => { + console.log(`Transaction hash ${txHash}`) + }) + .catch((error) => { + console.error(`Error sending transaction: ${error.code}: ${error.message}`); + }); + +``` From ceeb5e69fd458f0a91974d6a709e093316b20b87 Mon Sep 17 00:00:00 2001 From: Gregory Markou <16929357+GregTheGreek@users.noreply.github.com> Date: Mon, 27 Jul 2020 11:41:29 -0400 Subject: [PATCH 2/7] Update EIPS/eip-2831.md Co-authored-by: Micah Zoltu --- EIPS/eip-2831.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-2831.md b/EIPS/eip-2831.md index b635491a71b0b2..5d6ae0209a86be 100644 --- a/EIPS/eip-2831.md +++ b/EIPS/eip-2831.md @@ -2,7 +2,7 @@ eip: 2831 title: Transaction Replacement Message Type author: Gregory Markou (@GregTheGreek) -discussions-to: [eth magicians](https://ethereum-magicians.org/t/eip-2831-transaction-replacement-message-type/4448) + discussions-to: https://ethereum-magicians.org/t/eip-2831-transaction-replacement-message-type/4448 status: Draft type: Standards Track category: Interface From 56de927ca390415e007f4c8b6fb2bf1635b99ba3 Mon Sep 17 00:00:00 2001 From: Gregory Markou <16929357+GregTheGreek@users.noreply.github.com> Date: Mon, 27 Jul 2020 11:41:48 -0400 Subject: [PATCH 3/7] Update EIPS/eip-2831.md Co-authored-by: Micah Zoltu --- EIPS/eip-2831.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-2831.md b/EIPS/eip-2831.md index 5d6ae0209a86be..9d602927af5139 100644 --- a/EIPS/eip-2831.md +++ b/EIPS/eip-2831.md @@ -12,7 +12,7 @@ requires: 1193 ## Summary -An extension to the JavaScript Ethereum Proider API ([EIP-1193](https://eips.ethereum.org/EIPS/eip-1193)) this creates a new message type in the event a transaction replacement occurs. +An extension to the JavaScript Ethereum Proider API ([EIP-1193](./eip-1193.md)) this creates a new message type in the event a transaction replacement occurs. ## Abstract From 052eed223118a9d0e5c4f39ba1cae39c1aa1b308 Mon Sep 17 00:00:00 2001 From: Gregory Markou <16929357+GregTheGreek@users.noreply.github.com> Date: Mon, 27 Jul 2020 11:42:11 -0400 Subject: [PATCH 4/7] Update EIPS/eip-2831.md Co-authored-by: Micah Zoltu --- EIPS/eip-2831.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-2831.md b/EIPS/eip-2831.md index 9d602927af5139..a550fde389dd9a 100644 --- a/EIPS/eip-2831.md +++ b/EIPS/eip-2831.md @@ -20,7 +20,7 @@ Exert from EIP-1193 > A common convention in the Ethereum web application ("dapp") ecosystem is for key management software ("wallets") to expose their API via a JavaScript object in the web page. This object is called "the Provider". -Many ingenious developments have been made by wallet developers to improve the overall user experience while interacting with the Ethereum blockchain. One specific innovation was the tx replacement, offering users the ability to effectively cancel a previously sent transaction. +Many ingenious developments have been made by wallet developers to improve the overall user experience while interacting with the Ethereum blockchain. One specific innovation was transaction replacement, offering users the ability to effectively cancel a previously sent transaction. Transaction replacement is not a new concept, but unfortunately causes major user experience problems for dapp developers as the replaced transaction is near impossible to track. From 22f088bf6e373e5a2adc78df8aec10681ec4acc5 Mon Sep 17 00:00:00 2001 From: Gregory Markou <16929357+GregTheGreek@users.noreply.github.com> Date: Mon, 27 Jul 2020 13:07:34 -0400 Subject: [PATCH 5/7] Update EIPS/eip-2831.md Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com> --- EIPS/eip-2831.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-2831.md b/EIPS/eip-2831.md index a550fde389dd9a..5187437ed5dda1 100644 --- a/EIPS/eip-2831.md +++ b/EIPS/eip-2831.md @@ -2,7 +2,7 @@ eip: 2831 title: Transaction Replacement Message Type author: Gregory Markou (@GregTheGreek) - discussions-to: https://ethereum-magicians.org/t/eip-2831-transaction-replacement-message-type/4448 +discussions-to: https://ethereum-magicians.org/t/eip-2831-transaction-replacement-message-type/4448 status: Draft type: Standards Track category: Interface From aa658ff9d19f3a04d53f82f366b29b67a6c86957 Mon Sep 17 00:00:00 2001 From: Gregory Markou Date: Wed, 29 Jul 2020 11:11:49 -0400 Subject: [PATCH 6/7] update eip based on comments --- EIPS/eip-2831.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/EIPS/eip-2831.md b/EIPS/eip-2831.md index 5187437ed5dda1..283eb14e4c43b0 100644 --- a/EIPS/eip-2831.md +++ b/EIPS/eip-2831.md @@ -16,6 +16,10 @@ An extension to the JavaScript Ethereum Proider API ([EIP-1193](./eip-1193.md)) ## Abstract + + +## Motivation + Exert from EIP-1193 > A common convention in the Ethereum web application ("dapp") ecosystem is for key management software ("wallets") to expose their API via a JavaScript object in the web page. This object is called "the Provider". @@ -26,32 +30,24 @@ Transaction replacement is not a new concept, but unfortunately causes major use This EIP formalizes a way for both providers and dapp developers to track transaction replacements seamlessly. -This specification does not cover how one would utilize the transaction replacement message. - ## Specification 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). -> Comments like this are non-normative. - ### Definitions _This section is non-normative._ - Provider - A JavaScript object made available to a consumer, that provides access to Ethereum by means of a Client. -- Client - - An endpoint that receives Remote Procedure Call (RPC) requests from the Provider, and returns their results. - Wallet - An end-user application that manages private keys, performs signing operations, and acts as a middleware between the Provider and the Client. -- Remote Procedure Call (RPC) - - A Remote Procedure Call (RPC), is any request submitted to a Provider for some procedure that is to be processed by a Provider, its Wallet, or its Client. - Transaction Replacement - Submitting a transaction with both: the same nonce and a 10% increase in the gas price, of a previous transaction which a user no longer wishes to send. This must occur before the original transaction is included in the blockchain. ### Interface -The `data` parameter contains two values: `oldTx` and `newTx`,the transaction hash that's being superseded and the transaction hash of the successor, respectively. +The `data` parameter contains two values: `oldTx` and `newTx`,the transaction hash that's being superseded and the transaction hash of the successor, respectively. Both `oldTx` and `newTx` should be encoded hex numbers as strings with the `0x` prefixed. ```JavaScript interface TxReplacement extends ProviderMessage { @@ -65,7 +61,7 @@ interface TxReplacement extends ProviderMessage { ## Rationale -The purpose of `tx_replacement` is to provide a user experience improvement to both wallet users and dapp developers. It can be implemented without breaking changes and leverages the existing framework set out by EIP-1193. +The implementation was chosen to help the ease of implementation for both providers and dapp developers. Since `ProviderMessage` is widely used by dapp developers already it means that the implementation path would be as trivial as adding and additional `if` clause to their existing message listener. This also provides a benefit to dapps in the event that a provider has not yet implemented the `tx_replacement` and will not cause the dapp panic with `undefined` should it be implemented natively (eg: `ethereum.txReplacement(txHash, cb())` which would error with `ethereum.txReplacement()` is not a function). ## Backwards Compatibility @@ -75,6 +71,10 @@ Many Providers adopted EIP-1193, as this EIP extends the arbitrary `message` eve At the time of writing, no projects have working implementations. +## Security Considerations + +None at the current time. + ## References - [Web3.js issue with metamask tx cancel](https://github.com/ethereum/web3.js/issues/3585) @@ -84,10 +84,7 @@ At the time of writing, no projects have working implementations. Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). -## Appendix I: Consumer-Facing API Documentation - - -## Appendix II: Examples +## Appendix I: Examples These examples assume a web browser environment. From fb7ae6c84549da34f5080143e826ce8cccf66485 Mon Sep 17 00:00:00 2001 From: Gregory Markou Date: Wed, 29 Jul 2020 11:12:20 -0400 Subject: [PATCH 7/7] add abstract --- EIPS/eip-2831.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-2831.md b/EIPS/eip-2831.md index 283eb14e4c43b0..23445a02e16de9 100644 --- a/EIPS/eip-2831.md +++ b/EIPS/eip-2831.md @@ -16,7 +16,7 @@ An extension to the JavaScript Ethereum Proider API ([EIP-1193](./eip-1193.md)) ## Abstract - +The current communication between providers and consumers of providers are fundamentally broken in the event that a transaction in the mempool has been superseded by a newer transactions. Providers currently have no way of communicating a transaction replacement, and consumers are required to poll block by block for the resulting transaction. ## Motivation