EIP-2069: Recommendation for using YAML ABI in ERCs/EIPs


  Ethereum Improvement Proposals
        
        
          
            
              
            
          
        

        AllCoreNetworkingInterfaceERCMetaInformational

      



      
        
  
    

  
    
      🚧 Stagnant
    
    
    
    
    
      Informational
    
  
  
    
      EIP-2069: Recommendation for using YAML ABI in ERCs/EIPs
    
    
      
        
      
    
    
      
        
      
    
  

  

  	Authors	Alex Beregszaszi (@axic)
	Created	2017-02-11
	Discussion Link	https://ethereum-magicians.org/t/eip-2069-recommendation-for-using-yaml-abi-in-specifications/3347


  


  

  
    Table of Contents

    	Simple Summary
	Motivation
	Specification
	Rationale
	Backwards Compatibility
	Test Cases
	Implementation
	Copyright



  


  
      
      
         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
      
      
    


Copyright and related rights waived via CC0.


  Citation

  Please cite this document as:

  
  Alex Beregszaszi (@axic), "EIP-2069: Recommendation for using YAML ABI in ERCs/EIPs [DRAFT]," Ethereum Improvement Proposals, no. 2069, February 2017. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-2069.






      
    
  

  

    Ethereum Improvement Proposals


    
      
        	Ethereum Improvement Proposals


      


      	 ethereum/EIPs





      
        Ethereum Improvement Proposals (EIPs) describe standards for the Ethereum platform, including core protocol specifications, client APIs, and contract standards.