HomeEIPs
EIPsEIP-2069
EIP-2069

Recommendation for using YAML ABI in ERCs/EIPs

StagnantInformational
Created: 2017-02-11
Alex Beregszaszi (@axic)
DiscussionsOriginal linkEdit
1 min read

The summary of EIP-2069 is a recommendation for including contract ABI descriptions in EIPs and ERCs as YAML. This proposal aims to solve issues such as preferring a single language over others and locking the specification to a certain version of the Solidity language. The Standard Contract ABI is usually represented as a JSON object, but YAML is suggested for providing user-readable specifications with comments. The aim was to choose a representation which is well supported by tools and supports comments. The proposal has no effect on backwards compatibility.

Video
Anyone may contribute to propose contents.
Go propose
Original

Simple Summary

Recommendation for including contract ABI descriptions in EIPs and ERCs as YAML.

Motivation

In the past, most ERCs/EIPs included an ABI description purely as a Solidity contract and/or interface. This has several drawbacks:

  • Prefers a single language over others and could hinder the development of new languages.
  • Locks the specification to a certain version of the Solidity language.
  • Allows the use of syntactical elements and features of the Solidity language, which may not be well representable in the ABI. This puts other languages at even more disadvantage.

This proposal aims to solve all these issues.

Specification

The Standard Contract ABI is usually represented as a JSON object. This works well and several tools – including compilers and clients – support it to handle data encoding.

One shortcoming of the JSON description is its inability to contain comments. To counter this, we suggest the use of YAML for providing user readable specifications. Given YAML was designed to be compatible with JSON, several tools exists to convert between the two formats.

The following example contains a single function, transfer with one input and one output in YAML:

# The transfer function. Takes the recipient address # as an input and returns a boolean signaling the result. - name: transfer type: function payable: false constant: false stateMutability: nonpayable inputs: - name: recipient type: address - name: amount type: uint256 outputs: - name: '' type: bool

Specifications are encouraged to include comments in the YAML ABI.

For details on what fields and values are valid in the ABI, please consult the Standard Contract ABI specification.

The same in JSON:

[ { "name": "transfer", "type": "function", "payable": false, "constant": false, "stateMutability": "nonpayable", "inputs": [ { "name": "recipient", "type": "address" }, { "name": "amount", "type": "uint256" } ], "outputs": [ { "name": "", "type": "bool" } ] } ]

Rationale

The aim was to chose a representation which is well supported by tools and supports comments. While inventing a more concise description language seems like a good idea, it felt as an unnecessary layer of complexity.

Backwards Compatibility

This has no effect on backwards compatibility.

Test Cases

TBA

Implementation

yamabi is a Javascript tool to convert between the above YAML and the more widely used JSON format.

Copyright and related rights waived via CC0.

Further reading
Anyone may contribute to propose contents.
Go propose
Adopted by projects
Anyone may contribute to propose contents.
Go propose

Not miss a beat of EIPs' update?

Subscribe EIPs Fun to receive the latest updates of EIPs Good for Buidlers to follow up.

View all
Serve EIP builders, scale Ethereum.
Resources
GitHub
Supported by