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 [email protected].

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.

Important Note: All material is provided subject to this important notice and you must familiarize yourself with its terms. The notice contains important information, limitations, and restrictions relating to our software, publications, trademarks, third-party resources and forward-looking statements. By accessing any of our material, you accept and agree to the terms of the notice.