EIPs/EIPS/eip-2831.md

eip	title	author	discussions-to	status	type	category	created	requires
2831	Transaction Replacement Message Type	Gregory Markou (@GregTheGreek)	https://ethereum-magicians.org/t/eip-2831-transaction-replacement-message-type/4448	Draft	Standards Track	Interface	2020-07-26	1193

Summary

An extension to the JavaScript Ethereum Provider API (EIP-1193) this creates a new message type in the event a transaction replacement occurs.

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

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 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.

This EIP formalizes a way for both providers and dapp developers to track transaction replacements seamlessly.

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.

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.
• Wallet
  • An end-user application that manages private keys, performs signing operations, and acts as a middleware between the Provider and the 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. Both oldTx and newTx should be encoded hex numbers as strings with the 0x prefixed.

interface TxReplacement extends ProviderMessage {
  readonly type: 'tx_replacement';
  readonly data: {
    readonly oldTx: string;
    readonly newTx: string;
  };
}

Rationale

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

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.

Security Considerations

None at the current time.

References

• Web3.js issue with metamask tx cancel
• Browser doesn't know when a transaction is replace

Copyright

Copyright and related rights waived via CC0.

Appendix I: Examples

These examples assume a web browser environment.

// 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}`);
  });