Implementations of Ricardian Contracts

Implementations of Ricardian Contracts

Ricardian contracts have seen many implementations. This page documents some of those, where I've bumped into them and had the time to record and say something. There is no particular order. This description is part of the WebFunds Guide and Ricardian Page within that.

The evolution of Ricardian Contracts has been slow. The concept was announced as far back as 1996, and source code was made available in Feb of 1997 (?), serious and deep interest in how to describe real assets did not arise until Bitcoin.

KSI blockchain

Guardtime have built a hash notary server concept into a signing infrastructure and then into a distributed ledger using Ricardian contracts: "Assets: can be defined by any permissioned user, they are textual Ricardian Contracts and are represented by the hash value."

Superficially, the KSI blockchain looks like a SOX (or Ricardo) system without the public key cryptography (they use KSI signing which is server-mediated hash-based signing), and without the receipts (they use balances instead). But, more meat required.


CommonAccord is a project by James Hazard and Primavera de Filippi to "create a global template system of codified legal texts" that integrates with smartcontracts. As written by Primavera de Filippi in "Legal Framework For Crypto-Ledger Transactions," the base legal contract element is of the Ricardian form, each of which is matched to a smart contract element, and then the pairs are composed into wider contacts.


This Bitcoin-era system called OpenBazaar expands the more static notion of Ricardian Contracts and creates a protocol of bids and offers to form trades:

OpenBazaar uses Ricardian contracts for managing trade and arbitration in a decentralised pseudonymous marketplace. Ricardian contracts enable tamper-proof and authenticated consensus between buyers and sellers, which can be easily audited by the contracted parties and an external 3rd party.

They choose JSON to express the contract writings. They create a series of embedded contracts, reminiscent of the russian dolls of OT. See schema at right, which I borrowed and annotated elsewhere, and this description from @drwasho on how the Ricardian Contracts relate to their identity and reputation system:

OpenBazaar extends the utility of the Ricardian contract, originally designed by the eminent Ian Grigg, to act as a ledger of the transaction or trade flow between the contracting parties. The final version of the Ricardian contract, with a completed and digitally signed record of the execution of the contract, is called a trade receipt. The data within the contract is signed with the GUID keys of the participants.


OpenAssets project has added (?) a capability to issue Ricardian Contracts. Also see Bitcoin talk post .

This is work by Flavien Charlon and/or Nicolas Dorier.

FreiMarkets by Jorge and Mark

Must write on ... "Freimarkets: extending bitcoin protocol with user-specified bearer instruments, peer-to-peer exchange, off-chain accounting, auctions, derivatives and transitive transactions" paper by Mark Friedenbach and Jorge Timón.

Askemos by Jörg F. Wittenberger

Askemos consists of a set of notaries, being cooperating nodes that securely exchange information. Each notary is instantiated on a 'notary device' being the combined user platform of hardware, software and data. A set of notaries can run an autonomous 'agent' being an operation run by each of them in consensus using byzantine fault tolerance ( Paxos).

A user's personal notary can sign off on her information, which is presented to her as a signed web page, and can then be signed by the user's personal notary for distribution to others for consensual agreement.

In Askemos the presentation of the information can be seen as a Ricardian Contract that can be expressed as an issuance of an asset such as an IPR to photo, although that probably cuts the capabilities of Askemos short.

Open Transactions by FellowTraveller

OpenTransactions uses the Ricardian Contract. Its chosen form is XML, as below.

More curiously, the author makes the following claim:

While these contracts are simply signed-XML files, they can be nested like russian dolls, and they have turned out to become the critical building block of the entire Open Transactions library. Most objects in the library are derived, somehow, from OTContract. The messages are contracts. The datafiles are contracts. The ledgers are contracts. The payment plans are contracts. The markets and trades are all contracts. Etc.

I originally implemented contracts solely for the issuing, but they have really turned out to have become central to everything else in the library.

That's a sandwich that demands some meat!

XML by WebFunds

In a presentation at EFCE 01 WebFunds programmer Erwin van der Koogh talked about how to map Ricardian Contracts to the XML format.

In brief, the summary was that the equality requirement of the Rule of One Contract was not met. XML is so blase as to the whitespace and layout that there are enough simple tricks there to break the real contract requirement.

It is simply not clear that we can make a contract out of XML that will satisfy initially, a lawyer, and ultimately, a judge. More work required on this front. Note that the example presented here is quite readable and familiar, and may satisfy.

Voucher Trading


One alternate development is the FlexTicket from NTT.

It was recently described in an Internet Drafts, Voucher definition published by Ko Fujimura <> and Masayuki Terada (both from NTT, Japan):

        Title           : XML Voucher: Generic Voucher Language
        Author(s)       : K. Fujimura
        Filename        : draft-ietf-trade-voucher-lang-00.txt
        Pages           : 8
        Date            : 21-Feb-01

    This document specifies rules for defining voucher properties in
    XML syntax. A voucher is a logical entity that represents a right
    to claim goods or services. A voucher can be used to transfer a
    wide-range of electronic-values, including coupons, tickets,
    loyalty points, and gift certificates, which are often necessary to
    process in the course of payment and/or delivery transactions.

    A URL for this Internet-Draft is:

This is part of a "generic value circulation system" that is further described in a set of requirements for Generic Voucher Trading:

        Title           : Requirements for Generic Voucher Trading
        Author(s)       : K. Fujimura
        Filename        : draft-ietf-trade-drt-requirements-02.txt
        Pages           : 11
        Date            : 15-Feb-01

    In purchase and other trading transactions, it is often required to
    credit loyalty points, collect digital coupons or gift certificates,
    and so on.  These activities can be generalized using the concept of
    a 'voucher', which is a digital representation of the right to claim
    goods or services.

    A URL for this Internet-Draft is:

The notion seems to have been introduced as far back as this 1998 Usenix paper, "General-purpose Digital Ticket Framework".


Their higher level requirements document for a voucher trading system is pretty much met by Ricardo already. As far as voucher trading goes, the requirements need not be as stringent as for money or asset systems, but the effective nature of the system is equivalent. Indeed, the Voucher ID mentions stocks and bonds at one place, so maybe the system is headed there.


Do other ideas meet the requirements if the Ricardian Contract? In terms of the contrast between Ricardian Contracts and Fujimura/Terada Vouchers (what this page is more properly about), there appear to be these :

Feature Ricardian Contracts Vouchers Comments
Signature OpenPGP cleartext (external) suggests XMLDSIG
PKI OpenPGP (external) no requirements
Format Ini/custom XML XML is much better
Identifies parties yes yes Legal Issuer, Issuance Server
Extensible yes yes Allows other types of instruments
Separates value from contract yes yes Units are accounted for in parent Payment System
Provides Unique Identifier yes no how to identify the document with no ambiguity and no change
program-parsable yes yes  
human-parsable yes maybe can humans read the document without confusion?
Contractual yes no lacks defined signature & PKI, human parsability, unique id
Implementation yes no  

As a contract in the terms that the Ricardian Contract attempts to meet, the Voucher might not succeed. That is somewhat unjust as there is no indication that the requirements of the Voucher are intended to be of a contractual form, merely that they are suitable for describing loyalty systems and ticketing and the like.

However, it may be that we can use the Voucher ID as the starting point for the future XML format for the Ricardian Contract.

Smart Contracts

One idea that has been around for a long time is smart contracts. These dynamic, coded agents were theorised by Nick Szabo as far back as 1994 which dates it before Ricardian Contracts.

I define a smart contract as a computerized transaction protocol that executes terms of a contract. The general objectives of smart contract design are to satisfy common contractual conditions (such as payment terms, liens, confidentiality, and even enforcement), minimize exceptions both malicious and accidental, and minimize the need for trusted intermediaries. Related economic goals include lowering fraud loss, arbitration and enforcement costs, and other transaction costs.

In a nutshell, smart contracts are pieces of code that are run to interpret and play agent in a protocol that instantiates a contract in action. A vending machine is a smart contract; you put in your coin, and you get your soft drink.


Documentation resources on Smart Contracts include


From our present perspective, the biggest question with smart contracts is whether they are contracts at all. That is, do they meet the legal definition of a contract? Can a participating party be made aware of the terms? Or does she need to be a programmer to read the code? Can she enter into a dispute?

It was based on these consideration that the original designers of the Ricardian Contract deliberately eschewed complex notations (such as formal languages) and formats that were only readable by programmers.

In Ricardian Contracts, the most complex extant aspect, and the one that gets closest to smart contracts, is the calculation of the decimalisation of issues. That is, how many cents make up a dollar. As contracts must describe or imply decimalisation to be complete, and clients must interpret this to get basic value calculations correct, this is thought to be a necessary evil.

It's also pertinant to point at the "One Contract" rule. Smart contracts don't really follow this notion. With a smart contract, the emphasis is on the performance, via the code, rather than the dispute, and thus the documentation.

But, it's important to put it in context: Smart Contracts are a much more theoretical construct, heading towards an interesting future. Ricardian Contracts are nowhere near as sci-fi as smart contracts, they represent a half-way house between dumb paper and smart code. They are also here and now, and have been working reality since mid 1996.


A consortium has defined an eCheck format written in SGML (not quite XML) for the purposes of transmitting cheques between parties. These are definately banking cheques, not SOX cheques.

The Document Formatting Rules in the standard may be of interest. It describes characters, tags, lines, and whitespace, all pretty much as we do things.

The rest of the document is not so useful, it includes too many assumptions about cheques and protocols. It's also locked up in PDF and can't easily be worked with.


NeuClear is worth a look:

"A NeuClear transaction is a piece of xml defining a contract that is signed by some one and processed by an independent third party."

The easiest description starts with a blog entry called How does a NeuClear Transaction Work?.

This appears to follow a User-generates model. Each contract is a piece of XML text that a merchant generates. If the user signs it, it can then go to a payment processor for settlement.

This seems quite like the SAXAS model where everyone is a contract writer.

Ontology based designs

An obvious alternate to Ricardian Contracts is to construct an ontology or dewey decimal style hierarchy of information. This approach is criticised in The Ricardian Contract. But, for what it is worth, here are some efforts in that direction.

Open Fortress Signing Policy Project

OpenFortress is embarking on a signing policy project that promises to investigate the whole space of documents signed in human terms.

What seems odd is that the work makes no mention of Ricardian contracts at all. It even talks about XML signing, and we've been there done that!


A new project offers contracts on the web. Tractis. To be reviewed.

John Boyer

This post references a 1999 paper that suggests 'what you see is what you sign'. That goes some way to meeting our needs. Need to find and read the paper.

Secure Layer

Philipp G writes (paraphrased):

SecurityLayer solved questions like "how to sign the Presentation layer." They defined secure document format subsets, so that its possible to formally verify that a document/image/... can be signed securely. The security capsule formally validates that the document actually matches the definitions of a secure document, before it can be signed, and refuses to sign documents, that do not guarantee a secure display with the presentation layer. And luckily they did that with several document formats (HTML, Plaintext, Images, ...)

Here are some english documentation links about SecurityLayer:


Some miscellaneous resources:

Back to Guide Index and Ricardian Page