ERC: URL Format for Transaction Receipts

[3esmit]

Simple Summary

A standardized URI for transaction receipt with complete information about transaction.

A standard way of representing a submitted transaction.

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 it's details, such as chainId, method signature called and events signatures emitted.

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 ERC-681 transaction request;
• In crypto vending machines, a QRCode can be displayed when transactions are submitted;
• Anywhere transaction receipts are presented to users.

Motivation

Interoperability for web3: wallets, browsers and messengers.

Specification

Syntax

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

receipt                 = erc831_part transaction_hash [ "@" chain_id ] [ "?" parameters ]
erc831_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 and "transaction not found" error should be shown. 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 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 a "method validation error" should 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 should occur at least once in the transaction receipt event logs, otherwise and "event validation error" should be shown instead of the transaction, showing details of the missing events.

Examples

Simple ETH transfer:
ethereum:tx-0x1143b5e38fe3cf585fb026fb9b5ce35c85a691786397dc8a23a07a62796d8172@1

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 should 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, as specified by ERC-831.

References

• ERC-831
• ERC-681

Copyright

Copyright and related rights waived via CC0.

[3esmit]

@ligi @nagydani @alexvandesande Your comments are appreciated because you are authors of related EIPs.

[ligi]

@ligi @nagydani @alexvandesande Your comments are appreciated because you are authors of related EIPs.

LGTM

perhaps some more info on use-cases could be nice here.

[axic]

Let me know when you think this is ready to be merged as a draft.

[3esmit]

I feel like It certainly still have room for improvement, let's wait a few more days and then we can merge it, otherwise a new PR to change this draft would come too early.

I will try to squeeze out more of it ASAP so we can move forward on this. Thanks for the help.

[3esmit]

Added directions on how to deal with transaction live cycle and validation errors.

[3esmit]

This can be merged. Any further discussion can happen in https://ethereum-magicians.org/t/eip-2400-transaction-receipt-uri/3805

[3esmit]

This EIP is ready to go to Last Call.