ERC: Human-Readable Transaction Requests

[coinfork]

---
eip: 1138
title: Human-Readable Transaction Requests
author: Witek Radomski <witek@enjin.com>
type: Standards Track
category: ERC
status: WIP
created: 2018-06-06
discussions-to: https://github.com/ethereum/EIPs/issues/1138
requires: 681, 831
---

Simple Summary

A standard format for providing additional human-readable data to smart contract functions using Ethereum function call URIs, as specified in ERC-681.

Abstract

Including standard metadata in Transaction Request URIs will allow wallets to describe the proposed transaction to the end user in a more human-readable format, and also including the function parameter names that correspond to the passed arguments.

By implementing this ERC, a wallet will be able to display:

• The function name
• A table of parameter names, values (argument names) and their respective types
• Context, summary, and description text about the actual transaction
• An image representing the transaction or affected tokens

Motivation

While the URL Format for Transaction Requests supports creating ETH transactions with minimum required data, not enough information is available in both the URI and blockchain to explain what parameters are being passed to the function.

As more wallets and dapps adopt the ERC-681 standard, we need a way for all this software to inform the end-user about the transactions being created. One of the greatest frustrations (and attack vectors) with existing methods and wallets is the difficulty in understanding transaction data. Software supporting these URI standards should be able to clearly tell an end-user about precisely what is being signed.

Applications like WalletConnect and Enjin Wallet are used in conjunction with dapps to provide notifications of transaction requests in a friendly user-interface.

Specification

Syntax

Function call URIs follow the ERC-681 protocol, with the following change:

key    = "value" / "gas" / "gasLimit" / "gasPrice" / "param" / "context" / "summary" / "description" / "action" / "image" / TYPE

Semantics

param are supplied as strings denoting each function parameter name. They must be in the exact same order and number as in the function signature.

context denotes the source or context of transaction being performed. For example, this might be the name of the Dapp. (Supports Argument Injection)

summary is the title of the transaction, for example "Transfer 5 tokens". (Supports Argument Injection)

description is the longer text description of the transaction being requested, for example "This will transfer $(_value)[18]$ ENJ tokens to $(_to)$". (Supports Argument Injection)

action is intended to customize the action button that proceeds to sign and broadcast the transaction. Examples of action text would be "Approve", "Transfer" or "Mint".

image is the HTTP/HTTPS URL of an image or icon that represents the transaction.

Argument Injection

Any arguments passed to the contract can be replaced into the context, summary, and description fields by client software. This would help in showing end-users that the expected values are being passed to the function. To inject a function argument into the text, use the opening and closing pairs: $( and )$ , for example $(ARGUMENT_NAME)$.

An optional helper can be included in this syntax to display numeric values (such as a token's value) with their appropriate decimal places. To do this, square brackets containing the number of decimal places between 0 and 18 can be included before the ending $ character: $(ARGUMENT_NAME)[18]$. All other variables can be parsed and displayed automatically by client software by simply looking at the parameter type defined in the ABI.

Security Considerations

Wallet apps should offer an option to view the details of the function call.

This view should clearly display:

• The function name
• Each parameter's name
• Each parameter's argument value
• Each parameter's type

If the wallet is capable of interpreting the contract address (for example, a known ERC-20 or ERC-721 token), it could display more information about the transaction. For example, if the wallet is able to resolve the name, icon, decimals, and symbol of a non-fungible token, it should do so and display these depending on the specific transaction's context.

Example

ethereum:0xF629cBd94d3791C9250152BD8dfBDF380E2a3B9c/transfer&address=0x1111111111111111111111111111111111111111&uint256=1880000000000000000&param=_to&param=_value&context=Game%20Marketplace&summary=Transfer%205%20tokens&description=This%20will%20transfer%20%24%28_value%29%24%20ENJ%20tokens%20to%20%24%28_to%29%24&action=Send&image=https%3A%2F%2Fenjincoin.io%2Fimages%2Findex%2Fenjin-coin-logo.png

References

ERC-681, https://eips.ethereum.org/EIPS/eip-681
ERC-831, https://eips.ethereum.org/EIPS/eip-831
ERC-67, #67

Implementation

• Enjin Coin (github)

Copyright

Copyright and related rights waived via CC0.

[jeluard]

How does this relate to ERC-681 which already defines a syntax to call functions?

[coinfork]

ERC-681 does not provide a way to include parameter names for additional context, and there is no thought process about making the functionality easy to understand for the end-user. I'll consider this a bit further.

[coinfork]

This ERC is now compatible with the ERC-681 standard protocol.

An open question is verifying that the param names passed in the URI match the function's parameter names in the original ABI. Since this data is not included in the contract bytecode, it's difficult to enforce.

https://eips.ethereum.org/EIPS/eip-712 suggests a method of verifying the parameters, but this comes with its own set of problems.

[ligi]

interesting EIP

image is the HTTP/HTTPS URL of an image or icon that represents the transaction.

wondering if it would not be better to use multihash here - HTTP/HTTPS centralizes again and content addressing would fit better into the ecosystem than the location addressing used here

[pedrouid]

Suggestion by @alexvandesande to verify param names is to simply use radspec

[alexvandesande]

I think this whole EIP has the wrong approach. You should NEVER trust a dapp to tell you what the transaction does. The client/wallet should always be the one trying to show the user the intended action, preferably using rad spec pulled from the contract (a lot of them publish already meta information to swarm, but nobody uses it yet) and if no info is available the client/wallet should provide it.

[MicahZoltu]

@alexvandesande I think you and I agree on this but I want to make sure, you should never trust the dapp without a mechanism for verifying what it says. I think it is fine to have the dapp provide the signer with information, as long as that information can be trustlessly verified with something (like the contract).

[coinfork]

Thank you for the suggestions. It would be very worthwhile for transaction requests to include human-readable data spec along with variable injection of verified params (perhaps radspec). I'll be updating the standard soon to take these ideas into account.

[github-actions]

There has been no activity on this issue for two months. It will be closed in a week if no further activity occurs. If you would like to move this EIP forward, please respond to any outstanding feedback or add a comment indicating that you have addressed all required feedback and are ready for a review.

[github-actions]

This issue was closed due to inactivity. If you are still pursuing it, feel free to reopen it and respond to any feedback or request a review in a comment.