Ricardian contracts

The documents known as Ricardian contracts are the essential method to describe "value" in financial cryptography. The Ricardian contract is both a document that presents a form for a legal contract, and a design pattern to incorporate that document securely into an accounting system. When used properly, they are pervasive, being found in some sense from the client GUI layer down to the secure Internet protocol level.

Note, graphics 2,4,5,6 to the right are my annotations over a superb schema done by the OpenBazaar project, which is described a little in the Implementations page.


"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 valuable thing, such as the issuance of an asset over the Internet.

Our implementation 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 cleartext form by the Legal Issuer's contract signing key. The appropriate keys are included to verify the chain of integrity. Hence, the Ricardian contract is generally self-verifying.

A unique identifier is formed by a canonical message digest (hash) which provides a secure (unforgeable) identifier. This identifier is then placed in every transaction as the descriptor to the issuance or instrument, thus forming a secure link from the written contract to every transaction in the accounting system.


"Ignorance, the root and stem of all evil."
-- Plato

The original mission of the Ricardian contract was 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.

Note that other implementations have found other missions for the design pattern.


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. There are some additional writings on Requirements which were culled from the original paper.

  2. Some or many Implementations of Ricardian contracts are described, but this is more my notes than an accurate index.
  3. On the intersection of Ricardian and Smart contracts is a WIP that describes the cross-over. In another moment, I develop that relationship with The Sum of All Chains - Let's Converge! in which Iang brings together the various contract ideas and personalities into a single unifying architecture. See the triangle diagram at right for a hint!
  4. The g3 definition of formats describes in detail the WebFunds g3 version of of contracts. Note that these are somewhat out of date in detail, as they relate to versions of contracts used with an older version of the software, but they do still present the big picture of what WebFunds implementations look like.
  5. issuance documentation describes the business role of a contract within an issued instrument such as a currency, as deployed by Systemics.
  6. Wikipedia has an entry on contracts in law which forms the backdrop of what we are trying to express. See also the direct page on the Ricardian contract.
  7. FC in 7 layers is the broad, sweeping architectural model that in one tiny section, discusses how contracts fit into the whole FC context. Skim the full paper and the 7 layers quickly, then concentrate on the Example's Value section and the next Static Governance subsection, about half way down.

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
  15. Permissionless -- a contract can be created and used by anyone without requiring allocations in controlled spaces.

As a brief list. There doesn't appear to be a document that defines the Ricardian contract formally. There are some older requirements and many other 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. Classical signing packages are too expensive to maintain, secure and modify. x.509 especially stands out as very expensive to maintain for a reward of constriction. The signature form of OpenPGP is far more flexible and cost-effective in software and administration terms than x.509, but a custom library is even cheaper and can be modelled in modern OO terms and integrated more easily into protocols. (From actual experience, our Ricardian contracts used

Substantial steps were done in Kenya to remodel Ricardo to use a more layered signing model over people. However, the model used was a hybrid of CAcert.org Assurance and local savings groups.

Alternate Implementations

(This section moved to Ricardian Implementations.)


Some miscellaneous resources:

Back to Ricardian Page and Guide Index.