ERC-2400: Transaction Receipt URI

URI format for submitted transactions with complete information for transaction decoding

Abstract

A transaction hash is not very meaningful on its own, because it looks just like any other hash, and it might lack important information for reading a transaction.

This standard includes all needed information for displaying a transaction and its details, such as chainId, method signature called, and events signatures emitted.

Motivation

Interoperability between ethereum clients, allowing different systems to agree on a standard way of representing submitted transactions hashes, optionally with necessary information for decoding transaction details.

Use-cases

Transaction Receipt URIs embedded in QR-codes, hyperlinks in web-pages, emails or chat messages provide for robust cross-application signaling between very loosely coupled applications. A standardized URI format allows for instant invocation of the user’s preferred transaction explorer application. Such as:

• In web3 (dapps, mining pools, exchanges), links would automatically open user’s preferred transaction explorer;
• In wallets, for users sharing transaction receipts easier;
• In chat applications, as a reply to an EIP-681 transaction request;
• In crypto vending machines, a QRCode can be displayed when transactions are submitted;
• Anywhere transaction receipts are presented to users.

Specification

Syntax

Transaction receipt URLs contain “ethereum” in their schema (protocol) part and are constructed as follows:

receipt                 = schema_part transaction_hash [ "@" chain_id ] [ "?" parameters ]
schema_part             = "ethereum:tx-" 
transaction_hash        = "0x" 64*HEXDIG 
chain_id                = 1*DIGIT
parameters              = parameter *( "&" parameter )
parameter               = key "=" value
key                     = "method" / "events"
value                   = function_signature / event_list
function_signature      = function_name "(" TYPE *( "," TYPE) ")"
function_name           = STRING
event_list              = event_signature *( ";" event_signature )
event_signature         = event_name "(" event_type *( "," event_type) ")"
event_name              = STRING
event_type              = ["!"] TYPE

Where TYPE is a standard ABI type name, as defined in Ethereum Contract ABI specification. STRING is a URL-encoded unicode string of arbitrary length.

The exclamation symbol (!), in event_type, is used to identify indexed event parameters.

Semantics

transaction_hash is mandatory. The hash must be looked up in the corresponding chain_id transaction history, if not found it should be looked into the pending transaction queue and rechecked until is found. If not found anequivalent error as “transaction not found error” should be shown instead of the transaction. When the transaction is pending, it should keep checking until the transaction is included in a block and becomes “unrevertable” (usually 12 blocks after transaction is included).

chain_id is specified by EIP-155 optional and contains the decimal chain ID, such that transactions on various test and private networks can be represented as well. If no chain_id is present, the $ETH/mainnet (1) is considered.

If method is not present, this means that the transaction receipt URI does not specify details, or that it was a transaction with no calldata. When present it needs to be validated by comparing the first 4 bytes of transaction calldata with the first 4 bytes of the keccak256 hash of method, if invalid, an equivalent error as “method validation error” must be shown instead of the transaction.

If events is not present, this means that the transaction receipt URI does not specify details, or that the transaction did not raised any events. Pending and failed transactions don’t validate events, however, when transaction is successful (or changes from pending to success) and events are present in URI, each event in the event_list must occur at least once in the transaction receipt event logs, otherwise an equivalent error as “event validation error: {event(s) [$event_signature, …] not found}” should be shown instead of the transaction. A URI might contain the event signature for all, some or none of the raised events.

Examples

Simple ETH transfer:

ethereum:tx-0x1143b5e38fe3cf585fb026fb9b5ce35c85a691786397dc8a23a07a62796d8172@1

Standard Token transfer:

ethereum:tx-0x5375e805b0c6afa20daab8d37352bf09a533efb03129ba56dee869e2ce4f2f92@1?method="transfer(address,uint256)"&events="Transfer(!address,!address,uint256)"

Complex contract transaction:

ethereum:tx-0x4465e7cce3c784f264301bfe26fc17609855305213ec74c716c7561154b76fec@1?method="issueAndActivateBounty(address,uint256,string,uint256,address,bool,address,uint256)"&events="Transfer(!address,!address,uint256);BountyIssued(uint256);ContributionAdded(uint256,!address,uint256);BountyActivated(uint256,address)"

Rationale

The goal of this standard envolves only the transport of submitted transactions, and therefore transaction data must be loaded from blockchain or pending transaction queue, which also serves as a validation of the transaction existence.

Transaction hash not found is normal in fresh transactions, but can also mean that effectively a transaction was never submitted or have been replaced (through “higher gasPrice” nonce override or through an uncle/fork).

In order to decode transaction parameters and events, a part of the ABI is required. The transaction signer have to know the ABI to sign a transaction, and is also who is creating a transaction receipt, so the transaction receipt can optionally be shared with the information needed to decode the transaction call data and it’s events.

Backwards Compatibility

Future upgrades that are partially or fully incompatible with this proposal must use a prefix other than tx- that is separated by a dash (-) character from whatever follows it.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Ricardo Guilherme Schmidt (@3esmit), Eric Dvorsak (@yenda), "ERC-2400: Transaction Receipt URI [DRAFT]," Ethereum Improvement Proposals, no. 2400, November 2019. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-2400.