EOSIO Software Release: Ricardian Contract Specifications and the Ricardian Template Toolkit

Cultivating User Understanding with Richly Rendered Ricardian Contracts

A critical component of user security is preventing phishing attacks or bait and switch attacks which trick users into agreeing to something that isn’t actually going to happen as a result of their agreement. In blockchain, this can occur when a website or application indicates to a user that they are approving one action, but present a different transaction to the key management application (i.e. Authenticator or wallet). The website says one thing, but issues something else to the blockchain. For example, a user may be led to believe they are sending a small number of tokens to an exchange, but in actuality, they are sending all of their tokens to a thief.

A pillar of EOSIO’s usability since its dawn has been support for defining Ricardian Contracts that are paired with Smart Contracts to serve as human readable representations of an action’s intent in plain english for any user (not developer) to understand. The intent of code being transparent and auditable comes into play as blockchain actions are often irreversible. We’ve published on the power of this concept before in Dan Larimer’s past articles on the intent of code as law and the effect this has on user experience and security. Before Ricardian Contracts, it was near impossible for an average user to understand or be expected to understand exactly what actions they were signing in a Smart Contract. Existing Authenticators (wallets) that present transactions to users for signing with their private keys are often not equipped to render Ricardian Contracts in a way that cultivates understanding, so, current solutions rely on applications to explain to the user what a smart contract says on the front end without any auditable association to the actions taking place on the blockchain.

Ricardian Contract Releases

Today’s release introduces two new features for Ricardian Contracts to create consistency and transparency in how Ricardian Contract data is presented to users in Authenticators which ask them to sign transactions. The Ricardian Contract Specification defines a template language based on JSON for adding metadata, a subset of Markdown/CommonMark for formatting, and Handlebars for variable substitution. Smart Contract developers can follow the specification to richly format Ricardian Contracts to cultivate understanding for their users.

In addition, we built the Ricardian Template Toolkit, an implementation of a renderer for the Ricardian Contract Specification that demonstrates how Ricardian Contracts built to the new specification can be displayed. This Template Toolkit can be used by Authenticator developers to consistently render Ricardian Contracts and by Smart Contract developers as an authoring and testing tool.

As an illustrative analogy, one could think of the Ricardian Contract Specification like the HTML specification and the Ricardian Template Toolkit like a browser that can render documents that follow the HTML specification.

For EOSIO Blockchain Users, the Ricardian Contract Specification and the Ricardian Template Toolkit projects enable a clear understanding of the agreements to which they are consenting. We encourage Smart Contract Developers to enhance their Smart Contracts by following the Ricardian Contract Specification, and Authenticator developers to adopt the Ricardian Template Toolkit to provide a much clearer rendering to users of what will happen when they approve a blockchain action.

Stay Connected

If you are interested in providing feedback and working more closely with our team to improve the EOSIO for developers, you can send our developer relations team an email at developers@block.one.

You can also keep up to date with future updates by subscribing to our mailing list on the EOSIO Developer Portal. We are excited to be continually improving the usability of the software for EOSIO developers as we continue laying a foundation for the mass adoption of blockchain technology.


All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Disclaimer: Block.one makes its contribution on a voluntary basis as a member of the EOSIO community and is not responsible for ensuring the overall performance of the software or any related applications. We make no representation, warranty, guarantee or undertaking in respect of the releases described here, the related GitHub release, the EOSIO software or any related documentation, whether expressed or implied, including but not limited to the warranties or merchantability, fitness for a particular purpose and noninfringement. In no event shall we be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or documentation or the use or other dealings in the software or documentation. Any test results or performance figures are indicative and will not reflect performance under all conditions. Any reference to any third party or third-party product, resource or service is not an endorsement or recommendation by Block.one. We are not responsible, and disclaim any and all responsibility and liability, for your use of or reliance on any of these resources. Third-party resources may be updated, changed or terminated at any time, so the information here may be out of date or inaccurate. Any person using or offering this software in connection with providing software, goods or services to third parties shall advise such third parties of these license terms, disclaimers and exclusions of liability.