Crypto 2.0 Musings – Combining Ricardian and Smart Contracts


Nick Szabo proposed the idea of smart contracts back in 1997

  • Many kinds of contractual clauses (such as collateral, bonding, delineation of property rights, etc.) can be embedded in the hardware and software we deal with, in such a way as to make breach of contract expensive (if desired, sometimes prohibitively so) for the breacher.
  • A canonical real-life example, which we might consider to be the primitive ancestor of smart contracts, is the humble vending machine. Within a limited amount of potential loss (the amount in the till should be less than the cost of breaching the mechanism), the machine takes in coins, and via a simple mechanism, which makes a freshman computer science problem in design with finite automata, dispense change and product according to the displayed price. The vending machine is a contract with bearer: anybody with coins can participate in an exchange with the vendor. The lockbox and other security mechanisms protect the stored coins and contents from attackers, sufficiently to allow profitable deployment of vending machines in a wide variety of areas.
  • Smart contracts go beyond the vending machine in proposing to embed contracts in all sorts of property that is valuable and controlled by digital means.

Satoshi Nakamoto incorporated the idea of a smart contract in his : A Peer-to-Peer Electronic Cash System whitepaper. Instead of a vending machine safe keeping snacks and cash, and dispensing snacks plus change in exchange for cash, a distributed ledger, controlled by smart contract code, keeps account of how many bitcoins are held by which account and determines if new coins can be issued or existing ones transferred.

So what happens when the vending machine fails to give you back the right change? Most likely you look for a sticker on the vending machine with a phone number to call. You call the number, tell the operator the machine number, they pull up the instructions on what to do in case of failure, based on clauses of the vending machine legal contract, and hopefully proceed to solve the issue.

Wait, hold on, the operator follows instructions based on legal contract clauses! So there is an overall legal contract, some of contract clauses are performed by the vending machine’s smart contract code, others are performed by people. Bitcoin’s design deliberately focused on a pure digital asset exclusively controlled by distributed-consensus-seeking smart contract code, which means that all legal clauses are covered by smart contract code, and hence there is no need for an encompassing legal contract, but for most real world use cases, including vending machines, you do need an overarching legal contract, and autonomous agents – be they humans, organisations or smart contracts, distributed or centrally operated, to ensure performance of one or more legal clauses.

Traditional legal contracts are unstructured paper or electronic documents that are not machine-readable, not surprising given they were only designed for human consumption. They also tend to be declarative, not procedural in nature i.e. they specify what should happen, not how. That is why often there are operating instructions and procedures that describe how humans should do what things in order to comply with legal clauses. It is therefore useful to think of smart contracts as procedural code that is executed by a centralised or distributed-consensus-seeking platform in order to enforce performance of one or more declarative legal contract clauses, but in order to do that, the legal contract’s automation salient details must be machine readable.

This is where Ian Grigg’s idea of Ricardian Contract comes in

  • Our innovation is to express an issued instrument as a contract, and to link that contract into every aspect of the payment system.
  • By this process, a document of some broad utility (readable by user and program) is drafted and digitally signed by the issuer of the instrument. This document, the Ricardian Contract, forms the basis for understanding an issue and every transaction within that issue.
  • By extension, all issues of value, such as currencies, shares, derivatives, loyalty systems and vouchers, can benefit from this approach.
  • A Ricardian Contract can be defined as a single document that is a) a contract offered by an issuer to holders, b) for a valuable right held by holders, and managed by the issuer, c) easily readable by people (like a contract on paper), d) readable by programs (parsable like a database), e) digitally signed, f) carries the keys and server information, and g) allied with a unique and secure identifier (content hash).

Whilst the focus of a Ricardian Contract is in recognising that financial instruments e.g. currencies, bonds, shares should be issued as human and machine readable contracts, same principles can be in my opinion applied more broadly to any kind of legal contract, so as to be fully or partially enforced by both human and smart contract autonomous agents.

This is by no means a new idea. Primavera de Filippi published an excellent Legal Framework For Crypto-Ledger Transactions post about integrating legal and smart contracts. She cites CommmonAccord, a global legal contract template system, as a means to create Ricardian Contracts.

Eris propose an alternative eris:legal system, based on legal_markdown templates and CommonForm renderer, for what they call cryptographically-certain duel integration process:

  • Deploy a smart contract
  • Reference the chainId and contractAddress of the deployed smart contract in the final draft of the real world contract.
  • Finalize the real world contract and find its digital fingerprint.
  • Send a transaction logging the checksum of the real world contract into the storage of the smart contract.

smart contracts are by no means the only way to enforce Ricardian Contract clauses. Open-Transactions project, see whitepaper, implements financial instruments as Ricardian Contracts, processed by a transaction server based on cryptographic proof instead of trust, allowing any willing parties who wish to contract with each other to enjoy the benefits of a server without needing to trust it – a solution that demotes transaction servers to mere notaries, only able to counter-sign contracts that have first been signed by their clients. Barclays’ Dr Lee Braine recently presented yet another alternative vision when he demonstrated an ISDA Master Agreement proof of concept on R3’s Corda – a blockchain inspired platform lead by Richard Gendal Brown – R3’s CTO.

One of the issues I foresee with the emergence of many different template and markup standards is the very plurality of standards. How do you know that the term in contract A is same or different in contract B. How can you create a nice looking document, yet mark it up in such a way as to make it machine readable. Turns out most of these questions have already been solved by the Semantic Web project in the form of RDFa standard that embeds Linked Data in HTML, an extension to HTML5 that helps you markup things like People, Places, Events, Recipes and Reviews.

It builds upon standard Web technologies such as HTML, HTTP, RDF (allows creation of unambiguous structured data taxonomies) and URIs, but rather than using them to serve web pages for human readers, it extends them to share information in a way that can be read automatically by computers. RDFa was originally designed for Search Engines and Web Services to use this markup to generate better search listings and give users better visibility on the Web, so that people can find websites more easily, but in my opinion can be applied without alteration to Ricardian Contracts.

Let’s provide a simple example – a Ricardian Contract for weather insurance. Here is what a user would see in their web-browser:


Example Weather Insurance Ricardian Contract

I, Alex Batlin, authorise the transfer from address ‘abcdwerr’ to address ’24dsfrg3434′ using smart contract agent address ’24dsfrg3434′ of ’10’ unit(s) of GBP pounds held by smart contract address ‘4854398578934’ on the condition that website ‘‘ confirms that ‘0.5’ cumulative inches of rain did indeed fall between start date ‘9:00AM UTC 10th of March, 2015’ and finish date ‘9:00AM UTC 11th of March, 2015’ in country ‘GB’ and postcode ‘EC2Y 0RT’.


Hopefully pretty much self-explanatory, but on first glance not very useful for machine consumption. Let’s have a look at the underlying HTML:




<title>Example <a href=”″>Weather Insurance</a> Ricardian Contract</title>


<body prefix=”rc:”&gt;

<h1>Example Weather Insurance Ricardian Contract</h1>

<p typeof=”rc:RicardianContract”>

          <span>I, Alex Batlin, authorise the transfer</span>

          <span property=”rc:hasTransferAuthorisation” typeof=”rc:TransferAuthorisation”>

                      from address ‘<span property=”rc:hasFromAddress”>abcdwerr</span>’

                      to address ‘<span property=”rc:hasToAddress”>24dsfrg3434</span>’

                      using smart contract agent address ‘<span property=”rc:“>24dsfrg3434</span>’

                      of ‘<span property=”rc:hasInstrumentUnits”>10</span>’ unit(s)

                      of GBP pounds held by smart contract address ‘<span property=”rc:hasInstrumentAddress”>4854398578934</span>’


          <span property=”rc:hasTransferCondition” typeof=”rc:TransferCondition”>

                      on the condition that

                      website ‘<a href=”; property=”rc:hasOracleUrl”></a>’

                      confirms that ‘<span property=”rc:hasCumulativeInchesOfRainDetected”>0.5</span>’ cumulative inches of rain

                      did indeed fall between start date ‘<span property=”rc:hasStartDate” content=”2016-03-10T09:00:00<“>9:00AM UTC 10th of March, 2015</span>’ and

                      finish date ‘<span property=”rc:hasFinishDate” content=”2016-03-11T09:00:00<“>9:00AM UTC 11th of March, 2015</span>’

                      in country ‘<span property=”rc:hasCountryCode”>GB</span>’

                      and postcode ‘<span property=”rc:hasPostCode”>EC2Y 0RT</span>’.





You will notice that many HTML tags have additional attributes like property and type. When the same document is parsed through an RDFa parser, the following structured data (for this example in Turtle format) is extracted:


@prefix rc: <; .

[] a rc:RicardianContract;

   rc:hasTransferAuthorisation [ a rc:TransferAuthorisation;

           rc:hasAgentAddress “24dsfrg3434”;

           rc:hasFromAddress “abcdwerr”;

           rc:hasInstrumentAddress “4854398578934”;

           rc:hasInstrumentUnits “10”;

           rc:hasToAddress “24dsfrg3434” ];

   rc:hasTransferCondition [ a rc:TransferCondition;

           rc:hasCountryCode “GB”;

           rc:hasCumulativeInchesOfRainDetected “0.5”;

           rc:hasFinishDate “2016-03-11T09:00:00<“;

           rc:hasOracleUrl <;;

           rc:hasPostCode “EC2Y 0RT”;

           rc:hasStartDate “2016-03-10T09:00:00<” ] .


You will notice that at the top there is a link to the taxonomy definition file, which means every single property, is completely unambiguous. In fact you can define many different taxonomies or use many shared ones within the same document, which promotes re-use and efficiency, and you can use your client to also pull-in descriptions, labels, additional facts and any rules associated with a property. See if you can read the extract below, from the taxonomy file:


<rdf:Description rdf:about=””&gt;

   <rdfs:label xml:lang=”en”>Agent Address</rdfs:label>

   <rdfs:comment xml:lang=”en”>Address of the smart contract responsible for doing the actual condition transfer.</rdfs:comment>



Pretty powerful stuff! It’s worth pointing out that many financial vocabularies or taxonomies like ISO20022 are already expressed in XML Schemas, which can be easily converted to RDF schemas. In another words you do not need to re-invent how create your legal documents, just write them in HTML, which even MS Word supports, you don’t need to re-invent structured data serialisation – use RDF, you can use RDFa to mark-up HTML with RDF, and you can reuse existing taxonomies like ISO20022 either by converting them from XML Schema or writing them native in RDF Schema or OWL.

So ok, you have defined your Ricardian Contract as RDFa marked-up HTML document that grants someone the right to withdraw some money from someone’s account based on a pre-specified condition, now what?

This is where I get inspired by Bitcoin – it defines a distributed ledger that safe keeps bitcoins and defines in a smart contract the generic transfer and issuance rules e.g. only allow someone who possesses the correct private key to spend only the ones what they own etc. If I try and create a more generic pattern, lets say on Ethereum, I end up with what I called the Instrument Smart Contract (ISC) – something that defines the procedural rules linked to one or more contractual clauses of a financial instrument Ricardian Contract and keeps ledger of ownership.

Bitcoin actually specifies some of it’s transfer rules via scripts attached to transactions – default one being that a specific key is required to spend the transactions, whilst double spend prevent etc. rules are hardwired into the protocol code. Scripts can support more advanced conditions like multisig. To create a more generic and re-usable pattern, I propose the idea of an Agent Smart Contract (ASC)– something that encapsulates more user specific conditions in procedural code to achieve the declarative end state, again linked to legal clauses.

In effect, the Weather Insurance ASC is granted permission to transfer value held in the GBP ISC from issuer to beneficiary if it is presented with sufficient evidence by the beneficiary. In this example, proof-of-contract and proof-of-weather (a form of proof-of-condition) will be required as evidence. Proof-of-contract is the digitally signed Ricardian Contract expressed as RDFa marked-up HTML document. Proof-of-weather is in this case a digitally signed JSON response from a RESTful API service by with contract matching parameters. It could as easily be a smart contract controlled by a smart oracle – if on-chain notary is an advantage.

Here is a, not at all well thought out, process to claim your insurance and get paid:

  • Beneficiary buys the weather insurance from an insurer and receives from them by email or other means the digitally signed Ricardian Contract, which is stored in beneficiary’s digital wallet.
  • Beneficiary’s wallet will inspect the contract and decide when it should query the weather service to determine if a claim can proceed.
  • Assuming a claim can proceed, the wallet sends a transaction that primarily includes the Ricardian Contract to the ISC to register the ASC as a trusted third party able to act as a value transfer delegate on behalf of the issuer.
  • The wallet then sends a transaction to the ASC, primarily including the Ricardian Contract and JSON response.
  • The ASC validates the contract and JSON response, and if all ok sends a transaction to the ISC, instructing transfer of GBP in this case from issuer to beneficiary.

Note, the ASC may itself be an ISC – meaning that for instance if you buy a bond, the bond gives you the right to get paid coupons from the issuer’s money smart contract. In this way you can implement complex atomic swaps spanning multiple instruments e.g. Delivery vs. Payment, Payment vs. Payment. In fact the ASC may be a good place to implement Interledger’s notary services, as long as the ISC supports ledger-provided escrow. Interledger is a protocol for payments across payment systems. It enables secure transfers between ledgers and allows anyone with accounts on two ledgers to create a connection between them. Ledger-provided escrow removes the need to trust these connectors. Connections can be composed to enable payments between any ledgers, creating a global graph of liquidity or Interledger.

The ASC can also be a good place to implement state (micropayment) channels and off-chain oracles. Many contracts never get exercised e.g. options, insurance – so recording them on-chain is a waste of resource – good enough security can be achieved without use of on-chain smart oracles or storage of contract instance if proof-of-contract and proof-of-condition (in this case weather) is submitted to ASC when the claim needs to be made. Another advantage of this approach versus bundling all logic into the instrument code is flexibility – code can be kept tight and implement core logic, and allow many claim conditions e.g. if the holder of a bond fails to collect coupon payments, but has a credit default swap, this can be activated and money collected from underwriter.

That’s about it, would love some feedback!

This post express the opinion of the author: Alex Batlin that originally posted it on linkedin