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