ERC: Descriptions for Smart Contracts and Functions

toliuyi commented 6 years ago

eip: title: Descriptions for Smart Contracts and Functions author: Yi Liu (@toliuyi) discussions-to: lum.wang@gmail.com rivers.yang@icloud.com hayeah@gmail.com status: WIP type: Standards Track category: ERC created: 2018-06-15

Simple Summary

A standard for dApp developers to register descriptions of their smart contracts, then wallet apps could display those descriptions to users when signing transactions, providing better user experience.

Abstract

This EIP specifies a registry for human-readable contract descriptions, permitting contracts owners to register descriptions for contract functions and then wallet apps(such as MetaMask, ImToken, Status, Toshi etc.) could query and display those descriptions to users when users are about to sign Ethereum transactions.

Motivation

When users interact with dApps, they often need to confirm transactions. But the confirmation UI presented by installed wallet(such as MetaMask, Imtoken, Status, Toshi etc.) does NOT show proper information of what the transaction is about. This situation often made user confused and hesitated to confirm. Considered that there is EIP-926, address metadata registry could be used to associate description messages with contract address, a simple and consistent standard could fix this issue far more efficiently. Then the overall Ethereum dApp user experience would be improved.

Specification

Interface

pragma solidity ^0.4.20;

/**
   @title Owned, a standard interface to check smart contract owner

   Any contract implementing ERC*** should support this interface, having public ower() function to return contract owner's address

 */
interface Owned {
  /**
   * @dev Return contract owner address. 
   * @return owner address
   */
  function owner() external view returns (address);
}

/**
   @title ContractDescRegistry Human readable contract description registry. Implementation of ERC***.

   Allow contract owners register human-readable descriptions to contract functions. Wallets such as
   MetaMask, Imtoken, Status, Toshi etc. could display those descriptions to users when they about to sign
   Ethereum transactions.

 */
contract ContractDescRegistry {

  //inforamtion storage, contract address => function selector => language code => description
  mapping (address => mapping( bytes4 =>mapping (bytes5 => string))) public desc_store;

  //event emitted after a contract description registered
  event DescRegistered(address indexed contractAddr, bytes4 selector, bytes5 lang, string desc);

  /**
   * @dev Throws if called by any account other than contract owner.
   */
  modifier onlyContractOwner(address contractAddr){
    require(Owned(contractAddr).owner() == msg.sender);
    _;
  }

  /**
   * @dev Allows the contract owner to register human-readable description of contract and it's functions.
   * @param contractAddr The address of the contract which description associated with.
   * @param selector The selector of function which description associated with, use empty bytes to associate description to the whole contract.
   * @param lang ISO 639 language code of the description. Every contract should at least register description in English which language code is "en".
   * @param desc Description string in UTF8 encoding which supports argument injection, such as "Deposite $(_value)[18]$ Ether".
   */
  function attachDesc(address contractAddr, bytes4 selector, bytes5 lang, string desc) external onlyContractOwner(contractAddr){
    desc_store[contractAddr][selector][lang] = desc;
    emit DescRegistered(contractAddr, selector, lang, desc);
  }

  /**
   * @dev Allows anyone query contract description messages from this registry.
   * @param contractAddr The address of the contract to query.
   * @param selector The selector of function to query, use contract name's selector to query description of the whole contract.
   * @param lang ISO 639 language code of the description. If there is no description in specified language, "en" used as default.
   * @return Description string in UTF8 encoding which supports argument injection,such as "Deposite $(_value)[18]$ Ether".
   */
  function getDesc(address contractAddr, bytes4 selector, bytes5 lang) view external returns (string) {
    if(bytes(desc_store[contractAddr][selector][lang]).length != 0) return desc_store[contractAddr][selector][lang];
    else return desc_store[contractAddr][selector]["en"];
  }

}

attachDesc() submit a description to be associated with contract address, function selector and specified language, while getDesc() returns the description of supplied contract address, function select and language. Any contract utilizes this registry should have public owner() function for the registry to check description submitter is contract owner.

Parameters

contractAddr, The address of the contract which descriptions are assciatated with.
selector, The selector of function which description is associated with. Use empty bytes to associate description to the whole contract. Since user doesn't interact with constructor function, so no description is needed.
lang, ISO 639 language code of the description, such as en/de/ru/zh_CN. Default language is en.
desc, Description message in UTF8 encoding which supports argument injection, such as "Deposit $(_value)[18]$ Ether".

Argument Injection

Description messages can be added by client software with transaction parameters. 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 variables can be parsed and displayed automatically by client software by simply looking at the parameter name and type defined in the ABI.

This part draw lessons from ERC: URI Format for Calling Functions #1138

Rationale

Self-contained or central registry

Human readable descriptions could be embedded in the contract and exposed by a standard interface. But since there is no commonly accepted standard for this purpose and so many contracts had already published onto Ethererum, set up a central registry would allow both existing and upcoming contracts to use the same mechanism.

Store hash or message

An alternative design is to store hash rather than description message itself. This approach would surely cost less gas to submit descriptions than the current one, but it will bring other issues such as:

Description consumers (most likely wallet software) have to resort to off-chain web service to retrieve messages, make the architecture more complex and vulnerable to censorship and network outrage.
Contract owners may intend to introduce their contract in detail, which makes the messages too long to read. If message stored on Ethereum blockchain, the cost and gas limit may lead more refined message which is easy to read by users.

Backwards Compatibility

There are no backwards compatibility concerns.

Test Cases and Reference Implementation

Test cases and a reference implementation are available at https://github.com/toliuyi/contract-description/

Copyright

Copyright and related rights waived via CC0.

github-actions[bot] commented 2 years ago

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[bot] commented 2 years ago

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.

ethereum / EIPs