Skip to content
Renderer for the Ricardian Contract specification
Branch: master
Clone or download
Latest commit 5a43eff Apr 15, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github adds pull request template Mar 26, 2019
.images
bin EOSIO Ricardian Template Toolkit Initial Render Mar 12, 2019
docs
examples Add the `bin` dir to the npm release Apr 12, 2019
src Small spelling fixes in README and rc.ts Apr 15, 2019
.eslintrc.json EOSIO Ricardian Template Toolkit Initial Render Mar 12, 2019
.gitignore EOSIO Ricardian Template Toolkit Initial Render Mar 12, 2019
.npmignore
.nvmrc EOSIO Ricardian Template Toolkit Initial Render Mar 12, 2019
CONTRIBUTING.MD Update CONTRIBUTING.MD Mar 21, 2019
LICENSE
README.md Small spelling fixes in README and rc.ts Apr 15, 2019
index-complex.js EOSIO Ricardian Template Toolkit Initial Render Mar 12, 2019
index-simple.js EOSIO Ricardian Template Toolkit Initial Render Mar 12, 2019
index.js
jest.config.js EOSIO Ricardian Template Toolkit Initial Render Mar 12, 2019
package.json
tsconfig.json
tsconfig.webpack.json
tslint.json EOSIO Ricardian Template Toolkit Initial Render Mar 12, 2019
webpack.jscore.config.js EOSIO Ricardian Template Toolkit Initial Render Mar 12, 2019
webpack.web.config.js EOSIO Ricardian Template Toolkit Initial Render Mar 12, 2019
yarn.lock

README.md

EOSIO.CDT Ricardian Template Toolkit EOSIO Alpha

This library is a new tool in the suite of tools from EOSIO.CDT (Contract Development Toolkit), and should allow for a more robust and rich environment for writing Ricardian contracts for your EOSIO 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:

Installation

yarn add ricardian-template-toolkit

Running Locally

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/EOSIO/ricardian-spec.

Usage

Usage is very straightforward:

import RicardianContractFactory from '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 EOS.IO Blockchain Block Producers.</div><br />
  </body>
</html>

Rendered Styled HTML Styled HTML Example

Contributing

Contributing Guide

Code of Conduct

License

MIT

Important

See LICENSE for copyright and license terms. 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 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, service or other resource 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.

Wallets and related components are complex software that require the highest levels of security. If incorrectly built or used, they may compromise users’ private keys and digital assets. Wallet applications and related components should undergo thorough security evaluations before being used. Only experienced developers should work with this software.

You can’t perform that action at this time.