Ricardian Contracts

These contracts are the core idea behind the "value" axis managed by WebFunds. They are pervasive, being at the client level, as well as the SOX level.

In WebFunds G3, Ricardian Contracts are not at the Value Manager level, and this architectural position was a strong statement as to their suitability to describe value even within value managers that were yet to be seen or incorporated.


"O ye who believe! When ye deal with each other, in transactions involving future obligations in a fixed period of time, reduce them to writing."
-- Holy Quran, 2:282

In the simplest possible terms, a Ricardian Contract is a document defining a type of value for issuance over the Internet.

It is an Ini-formatted text file that is both human readable and program parsable. It identifies a Legal Issuer and includes all the clauses the Issuer sees fit to add in to make the document stand as a contract.

The document is signed in OpenPGP cleartext form by the Legal Issuer's contract signing key. The appropriate OpenPGP keys are included to verify the chain of integrity.

A unique identifier is formed by a canonical message digest (hash) which provides a secure (unforgeable) link to the accounting system.


The mission of the Ricardian Contract is to provide a document that can be a primary contract for the issuance of a digital asset.

The ultimate test of our mission is if the legal profession can take a Ricardian contract and unambiguously decide points of dispute.


Documentation is a little scattered. Here's some from the various sources:

  1. Mark Miller kindly presented the paper " The Ricardian Contract" to IEEE's Workshop on Electronic Contracting for me in my absence.

  2. definition of formats describes in detail the WebFunds g3 version of of contracts.
  3. issuance documentation describes the role of a contract within an issued instrument such as a currency. Read that section, but also skim the rest of the document.
  4. Wikipedia now has an entry on Contracts which serves as a backdrop in law for what we are trying to express in the Ricardian Contract.
  5. FC in 7 layers is a broad, sweeping architectural model that in one tiny section, discusses how contracts fit into the whole FC context. Read the full paper quickly, and concentrate on the Example's Value section and the next Static Governance subsection, about half way down.
  6. Implementations of Ricardian Contracts records some notes on those other uses I have found out in the wild.

You can find some examples of Ricardian Contracts on our site. WebFunds.org does not endorse these, so don't put your money where our mouth is.


The characteristics for a Ricardian Contract can be listed loosely as

  1. Human parsable
  2. Document is printable
  3. Program parsable
  4. All forms (displayed, printed, parsed) are manifestly equivalent
  5. Signed by Issuer
  6. All pertinant information in one single document, including signature and parties. This, along with the manifestly equivalent characteristic above, result in the Rule of One Contract.
  7. Represents a legal contract
  8. Can be identified securely, where security means any attempt to pervert the linkage between a reference and the contract is impractical.
  9. Supported by financially capable PKI (such as OpenPGP)
  10. Extensible - can interpret bonds, shares, loyalty, etc
  11. Identifies Legal Issuer (signer of contract)
  12. Identifies Issuance Server (accounter of contract)
  13. Unchangeable by Legal Issuer or other parties
  14. Supports content verifiability

As a brief list. There doesn't appear to be a document that defines the Ricardian Contract, just documents on how to use them (above).


Ricardian contracts are identified by a canonical hash. This hash results in a secure, distributed name space. In the framework of Zooko's Triangle, this makes Ricardian Contract namespace a Type 3 (SOX nyms are also a Type 3 within that system).

However each name is non-understandable to humans, and thus the client software includes facilities to attach names to each contract, or to derive standard names from within the contract. This takes the client into Type 4 of Zooko's Triangle. (Server software does not have this facility because it does not talk to humans.) WebFunds-3G and XML-based clients likely have a fixed name system derived from the contract itself. Lucaya adds petnames to its management of naming.


Within the Ricardo world, there are several terms that are often used interchangeably:

So, a given Ricardian Contract might be referred to as an instrument, a contract, and an item, depending on the context...

As a Signed Document

Ricardian Contracts use a public key signature as well as the secure message digest. Both are tools of digital signing, and it is a singular observation that the hash provides more protective power in the technology, while the public key signature provides for more descriptive intent.

The debate over the efficacy of public key signatures continues to simmer. Ricardian Contracts show how to do it in the narrow domain of a fixed, long-term reliable document. These techniques are not necessarily expandable to the wider domain of applying digsigs but we would argue that such a goal is futile anyway. So the Ricardian Contract presents a perfect case study in how to do digital signing correctly - by concentrating on actual local and narrow requirements and avoiding all the digsig hype.

Ricardian Contracts are signed in several components:

Certification and Authority

Ricardian Contracts stand out as an internally-complete solution to authorisation and authentication using cryptography, but they do not depend or use in any form the classical PKI ideas or Certification Authorities. The reasons for this are severalfold:

  1. Financial contracts cannot be bound to hierarchical or permission structure, by their nature;
  2. PKI and/or CAs add no value in this particular application; and
  3. the signature form of OpenPGP is far more flexible and cost-effective in software and administration terms than x.509. (This we know from actual experience, Ricardian Contracts used x.509 cleartext signing around 1998.)

If we were to remodel WebFunds to use a CA, we'd probably have to use CAcert.org or something similar to reduce the first version.

Klima-Rosa attack on OpenPGP signatures

In a paper by Vlastimil Klima and Tomas Rosa an attack were identified on the OpenPGP form of digital signature commonly used in Ricardian Contracts. Do these effect the contract? The short answer is probably not.

[Reference: Vlastimil Klima and Tomas Rosa, " Attack on Private Signature Keys of the OpenPGP Format, PGP(TM) Programs and Other Applications Compatible with OpenPGP" Also see explanation and exploit code].

The slightly longer answer requires understanding the form of the attack:

A modification of the private key file in a certain manner and subsequent capturing of one signed message is sufficient for successful attack. Insufficient protection of the integrity of the public as well as private parts of signature keys in the OpenPGP format is analyzed in DSA and RSA algorithms and on the basis of this, a procedure of attacks is shown on both private signature keys.

So in short the secret key file could be gained by an attacker. (Note the caveats that the attacker has to gain control of the secret key file, and to capture a signed message made with a modified key file. These are unlikely in our scenario, but plausible so we shall assume them.)

What does this mean? It means that someone else could then sign a message under the name of the issuer. There are two possibilities - a contract-updating message which would then change the nature of the current contract. At the moment, no such are employed, so it would be a non-programmatic claim (i.e., a published email on the maillists). Secondly, the attacker could sign a new contract in the name of the issuer.

Both of these are no more than nuisance attacks in the current instance. The issue here is that not only the issuer, but also the server operator, the mint role, and all the users form between them a web of trust. Such a community presents fairly broad and powerful protection against loss of signing keys. (This is no accident. The original design called for the resiliance in the face of complete loss of control of the signing keys - by publication if desired. See Requirements.)

One caveat - if we were to add another role such as an addendum onto an existant contract signed by the contract signing key, then this could evolve into a potential attack.

Note here that the defence is simply repudiation of the signature. This puts the lie to the imfamous non-repudiation myth of PKI - any and all signatures can be repudiated, and it is up to the community and courts to decide whether this was done unfairly or not. No technology can take away the human's ability to repudiate.


Up until recently, the idea of Ricardian Contracts has not been copied or independantly developed as far as we know. Even though the concept was announced as far back as 1996, and source code was made available in Feb of 1997, interest in applied Financial Cryptography of this form, and how to describe real assets, did not arise until about 2001.

Open Transactions by FellowTraveller

Although I haven't looked closely, OpenTransactions claims to use the Ricardian Contract in essence. 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 < fujimura@isl.ntt.co.jp> 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 1995 (?) which dates it before Ricardian Contracts.

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 problem 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 quite 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 Index.

Copyright © 1999 Systemics Ltd. All rights reserved.