forked from DecentralizedClimateFoundation/DCIPs
101 lines
6.3 KiB
Markdown
101 lines
6.3 KiB
Markdown
---
|
||
eip: 2400
|
||
title: Transaction Receipt URI
|
||
description: URI format for submitted transactions with complete information for transaction decoding
|
||
author: Ricardo Guilherme Schmidt (@3esmit), Eric Dvorsak (@yenda)
|
||
discussions-to: https://ethereum-magicians.org/t/eip-2400-transaction-receipt-uri/
|
||
status: Stagnant
|
||
type: Standards Track
|
||
category: ERC
|
||
created: 2019-11-05
|
||
requires: 155, 681
|
||
---
|
||
## 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](../LICENSE.md).
|
||
|
||
[EIP-155]: ./eip-155.md
|
||
[EIP-681]: ./eip-681.md
|