Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ERC: Human-Readable Transaction Requests #1138

Open
coinfork opened this Issue Jun 7, 2018 · 8 comments

Comments

Projects
None yet
6 participants
@coinfork
Copy link
Contributor

coinfork commented Jun 7, 2018

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

Copyright

Copyright and related rights waived via CC0.

@jeluard

This comment has been minimized.

Copy link

jeluard commented Jun 8, 2018

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

@coinfork

This comment has been minimized.

Copy link
Contributor Author

coinfork commented Jun 9, 2018

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 coinfork changed the title ERC: URI Format for Calling Functions ERC: Human-Readable Transaction Requests Jun 16, 2018

@coinfork

This comment has been minimized.

Copy link
Contributor Author

coinfork commented Jun 16, 2018

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

This comment has been minimized.

Copy link
Member

ligi commented Jun 18, 2018

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

This comment has been minimized.

Copy link
Contributor

pedrouid commented Jun 18, 2018

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

@alexvandesande

This comment has been minimized.

Copy link
Contributor

alexvandesande commented Jun 19, 2018

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

This comment has been minimized.

Copy link
Contributor

MicahZoltu commented Jun 20, 2018

@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

This comment has been minimized.

Copy link
Contributor Author

coinfork commented Jun 20, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.