Aragon Nest Proposal: Radspec, a tool for making Ethereum transactions readable

[mariapao]

Abstract

In Aragon we envision a decentralized future where technical and non-technical people, alike, are able to enjoy and be empowered by the decentralized web. Thus, user experience is key. We must provide the end-user with a friendly interface and a unified and intuitive experience of dealing with a DApp, abstracting the complexity of the technology away.

When a user is interacting with a DApp it should be easy for them to have a clear understanding of everything that is happening. A user shouldn’t be left guessing what will happen after they do X or Y action that sends a transaction or what the consequences of such actions will be. Or as the current status quo, in which users are signing transactions without any certainty of what is actually going on.

One thing that will make DApps more user friendly is to present the transaction data in a human readable language. For this reason, we have created radspec. With radspec you will be able to describe what your code does and tell the user what he/she is about to perform. Current Radspec features are:

• It can perform calls from external contracts via web3. Useful for fetching and displaying information such as token symbols or decimals

• It is safe. It doesn’t have access to the DOM.

• It is simple. It has a very familiar syntax.

• It is compatible. Most natspec comments that already exist are compatible with radspec. Adding radspec expressions to current contracts will allow to provide more context on the actions.

Examples of how radspec is currently being used can be found in all the Aragon developed apps: https://github.com/aragon/aragon-apps. The descriptions shown in Aragon Core are all being computed from the radspec comments in the contract files.

Even though Radspec is integrated into our DApp, we don’t want each DApp having their own human-readable descriptions, their own signer view, their own solution. This would be a waste of time for developers. Radspec should be moved out of the DApp level and have it as an external and independent tool located at the wallet or signer provider level. This way we would have one standard solution that everybody can use.

Radspec is not a finished product yet, its development and maintenance should actively continue as an independent tool. We would love to see a team from the community taking care of this.

Deliverables

1. Improve the grammar and parser of radspec. Some preliminary work was already started migrating the grammar to Nearley

2. Produce documentation on the syntax and how to write good radspec descriptions

3. Make a standalone tool for extracting radspec strings from Solidity contracts. At the moment, the Aragon CLI is using an ad-hoc solution (https://github.com/aragon/aragon-cli/blob/master/src/helpers/solidity-extractor.js) for parsing contract files and extracting the notice comments from functions. This tool should should resolve contract dependency imports

4. Make radspec a standard for describing transactions, making it impossible for DApp devs to deceive users when performing actions. We have thought of two ways to achieve this that aren’t mutually exclusive, as they solve the problem from different angles and can (and should) coexist (feel free to apply with a new solution):

   • Using a curated list of function/action descriptions, a repository could be composed with accurate descriptions of what the smart contract code does for each of its functions. This solution is compatible with currently deployed contracts without an upgrade, but a governance process over the curation of the list of contracts is needed (a TCR or a council of developers/smart contract auditors could be interesting models).

   • Allowing smart contracts to claim their own interface using ERC780 (or another standard for making claims). Signers can check whether the target contract has defined an interface (descriptions). Interfaces should live off-chain using a content addressable file storing protocol like IPFS or Swarm. With this solution each contract is responsible of claiming its own interface, therefore contract developers need to add logic to signal where the interface can be found.

5. Develop a JS library that can be used by signers and wallets (Frame, Status, Metamask...) to easily fetch and display radspec descriptions. We believe action descriptions have to be displayed to users by the signer right before signing a transaction (as opposed to being shown by DApps that can later send a different transaction payload to the signer).

Similar efforts

Given the importance of the problem, there have been other initiatives tackling the problem that can be a source of inspiration:

• https://github.com/ethereum/natspec.js

• https://ethereum-magicians.org/t/eip-1138-human-readable-transaction-requests/565/8

• Trustless Signing UI Protocol ethereum/EIPs#719

Grant size

Funding: from $50k up to $100k in ETH, split into chunks paid out over achieved deliverables.

Success reward: Up to $50k in ANT, given out when all deliverables are ready.

Application requirements

• Proof of concept implementation or well thought out technical design document detailing how project will be accomplished

• Details of the team members, alongside with their willingness in terms of implication
  Estimated average burn rate for completing the deliverables

• Legal structure to be adopted, if any

Development timeline

To be discussed or to be proposed by the team requesting funds.

[Latrasis]

The https://github.com/aragon/radspec-nearley repo is not available, were can it be found?

[mariapao]

Hi @Latrasis that repo is not longer relevant. I have modified the proposal accordingly.

[rperez89]

@mariapao hi! , probably this is not the right place to ask but I wanted to know how can I know which proposals are from aragon and which ones are from other people? what happen if two or three teams are working on the same? And where can i ask that kind of things? :P

[mariapao]

Hi @rperez89 when you see that one of the authors/creators of the issue is a member of one of the teams of the Aragon project that is a proposal coming from Aragon. Sometimes we like to have several teams working on the same proposal from different approach. So this depends on the proposal (problem) and on how teams are solving that problem.

Are you in the Aragon chat? That's the best place for you to ask this type of questions

[MicahZoltu]

EIP 719 needs a champion. If you all plan on building something along these lines, I would encourage you to become the champion for EIP719 rather than designing something separate. As the champion, you would have control over the final route the EIP took. The advantage to the community is that we don't end up with conflicting standards.

[luisivan]

Hey @MicahZoltu! Radspec is already built and Aragon users have been enjoying it for almost a year already. We have been also working on a WIP for a DAO that would aggregate Radspec transactions, and could be governed by the community or reputable actors in the space (e.g. signing providers or wallets) https://github.com/aragonone/metadata-dao

[yeqbfgxjiq]

Closing as this no longer requires attention. Please re-open if that is not the case.