Wire CDT Ricardian Template Toolkit

This library is a new tool in the suite of tools from Wire CDT (Contract Development Toolkit), and should allow for a more robust and rich environment for writing Ricardian contracts for your Wire smart contracts.

Overview

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

Together, the Ricardian Template Toolkit and Ricardian Contract Specification projects enable a clear understanding of the agreements to which users are consenting in Authenticators which ask them to sign transactions.

This library contains a factory that takes an ABI object, a transaction object, and an action index (along with some developer-oriented flags). It then:

1. Selects an appropriate processor based on the spec_version field in the contract metadata
2. Validates the Ricardian Contracts and metadata associated with the transaction actions
3. Validates all other spec requirements, including image sizes and hashes
4. Interpolates all variables with data from the transaction or ricardian_clauses
5. On success, returns an object with metadata and Contract Markup Language (CML, a subset of HTML)
6. On error or validation failure, returns a descriptive error, along with any data it was able to successfully parse and render

Foundational Inspiration for Metadata:

• https://hiltmon.com/blog/2012/06/18/markdown-metadata/
• https://blog.github.com/2013-09-27-viewing-yaml-metadata-in-your-documents/
• https://stackoverflow.com/questions/44215896/markdown-metadata-format#answer-44222826

Installation

npm i @wireio/ricardian-template-toolkit yarn add @wireio/ricardian-template-toolkit

Command Line Tool

The toolkit includes a simple command line wrapper around the library for local testing of HTML generation. If you install the package globally, the rc command will be available on the command line. If running locally, use (within the project root) ./bin/rc. Given an ABI, transaction data (fully deserialized), and optionally the transaction index (default 0) the rc command will output the generated HTML fragment.

Example:

rc -a myabi.json -t mytxn.json -i 1

The metadata is also available with the --only-metadata option.

Example:

rc -a myabi.json -t mytxn.json -i 1 --only-metadata

Help is available with rc --help.

Running Locally

npm run install
npm run build
npm run example

yarn install
yarn build
yarn example

Other Commands

• yarn lint
• yarn test

Ricardian Specification

The Ricardian Specification and an example of a compliant Ricardian contract can now be found at https://github.com/Wire-Network/ricardian-spec.

Usage

Usage is very straightforward:

import { RicardianContractFactory} from '@wireio/ricardian-template-toolkit'

...

// Create the factory instance.
const factory = new RicardianContractFactory()

// Construct a RicardianContractConfig object
const config = {
  abi: myAbi,
  transaction: myTransaction,
  actionIndex: 0,
  // Optional - defaults to 3
  maxPasses: 3,
  // Optional - developer flag - if true ignore errors if a variable
  // is specified in the contract but no value is found to substitute
  allowUnusedVariables: false
}

const ricardianContract = factory.create(config)

const metadata = ricardianContract.getMetadata()
const html = ricardianContract.getHtml()

Backward Compatibility Note

Be aware that for backward compatibility with contract specifications prior to 0.1.0, any contracts lacking a spec_version in the metadata are treated as following spec version 0.0.0.

Example

The following is based on the example from the Ricardian Contract Specification

Raw HTML Output

I, <div class="variable data">bobsmith</div>, author of the blog post "<div class="variable data">An Example Post</div>", certify that I am the original author of the contents of this blog post and have attributed all external sources appropriately.<br />
<div class="variable clauses">WARRANTY. The invoker of the contract action shall uphold its Obligations under this Contract in a timely and workmanlike manner, using knowledge and recommendations for performing the services which meet generally acceptable standards set forth by EOS.IO Blockchain Block Producers.</div><br  />

Styled HTML

<html>
  <head>
    <style>
      * {
        font-family: serif;
      }
      body {
        margin: 1rem 2rem;
      }
      .variable {
        display: inline;
        color: DarkRed;
        font-style: italic;
        font-weight: bold;
      }
    </style>
  </head>

  <body>
    I, <div class="variable data">bobsmith</div>, author of the blog post "<div class="variable data">An Example Post</div>", certify that I am the original author of the contents of this blog post and have attributed all external sources appropriately.<br />
    <div class="variable clauses">WARRANTY. The invoker of the contract action shall uphold its Obligations under this Contract in a timely and workmanlike manner, using knowledge and recommendations for performing the services which meet generally acceptable standards set forth by Wire Network.</div><br />
  </body>
</html>

Rendered Styled HTML

License

MIT