Intro
This is a thought experiment in several parts in what it would take to turn a blockchain Constitution like the EOS proposal into a full Ricardian Contract. Which isn’t as difficult as it sounds, and could lead to some surprising benefits.
For the quick intro, a Ricardian contract is a prose or legal contract that includes computer-parsable markup. In that order: it is first and foremost a human-readable document, and only secondly is it a machine readable document.
The humans come first because they (we?) are the hard cases. For a contract to be a contract, there must be intent, which means the humans not only have to know about it, they have to understand it, so as to be able to legally enter into agreement in a manner that will be accepted by any (human-staffed) court as a legal contract. Establishing that exact intent is so important that we often turn it into a ceremony that is as well known to people as it is to courts - signing.
All this human stuff turns out to be a very hard problem to do digitally, whereas making a computer understand a document is easy - just shove some markup in there. Remember that ordering - humans first, computers second - as you’re reading through this odd construction.
Part 1 - A Ricardian Layout
Let’s try it then! Let’s take a prose constitution, and shove some markup in it. By way of an example, here is a clause from an example version of a Constitution that might or might not be useful for EOS:
ARTICLE 3 - Currency
The Community hereby creates a currency known as EXAMPLE, possession of which is evidence of a contribution to the community. The quantity of EXAMPLE shall increase no more than 5% per year after the first 1 billion EXAMPLE are distributed.
Note how the author of this clause (@dantheman) expects others to use this example, even to the extent of a hint to change EXAMPLE into MyCoin or YourCoin or BobCoin or somesuch. It’s a bit laborious but necessary to make this clause adaptable for different contexts - and this is where we get to the nub of the argument: we want to keep the precision of a proper contract, but we’d like the computer to do some of the editing & presentation work of taking the above template and turning it into a finalised contract for us, when we use it in the specific context of the blockchain.
And we want to enable the humans (and the computer) to easily interpret the results, as well.
Contract Cake
In order to get our contract cake and eat it too, let’s add some markup and some parameters to those parts to that may be different from context to context. We already saw that the name of the coin is one such parameter, to which we can add the initial total issue amount, and the rate of inflation rate after the initial issue is done; all of these depend heavily on the context in which the contract is being issued:
Article 3 - Currency
COINNAME = IangBux
INFLATION = 5%
INITIALISSUE = 1,000,000,000The Community hereby creates a currency known as COINNAME, possession of which is evidence of a contribution to the community. The quantity of COINNAME shall increase no more than INFLATION per year after the first INITIALISSUE of COINNAME are distributed.
With a graphical contracts editor, we can process the above dry document to display the prose contract derived from the above.
You can imagine a hover-over on those colour-highlighted parts that reveal the original name that has been substituted. Or, we could have a mode to track the variables by colours and highlighting, as within a programmer’s IDE (integrated development environment):
Hours of fun!
Now, it’s important to realise something here. We don’t want too much fun. The reason for this is that those that have too much fun with graphics and tricks and toolkits and FLASH and popups and special offers and other abominations make it harder and harder for those who are the primary users of this system - the users. As Einstein put it, this system needs to be made as simple as possible, but no simpler!
Declare your variables, for the contract win!
In the above, we have separated out the parameters from the prose. Interestingly, this is a winning idea in both legal writing and in computer coding. For the legal profession, this is known as contract templating, which allows one contract template to be used across many contracting parties - a great saving in legal fees. You can find more on templating over at Common Accord.
For you coders, declaring your variables in advance forces the programmer to be clear and precise about what is intended. And allows the compiler to help you to follow that intent, e.g., by identifying that all parameters are correctly assigned. For both disciplines, it makes the product easier to read by other professionals, which makes it easier and cheaper to maintain.
A slightly more advanced Markup
The above however is a little hard to code - what happens if we actually want to write in an acronym such as COINNAME or ARTICLE ? What happens when we want a bolded (upper case) warning about inflation, because,you know, central banks & lawyers!?
For this reason we would typically advise a simple markup within the prose. Here’s an example that uses a JSON-like format to set the parameters, and a hybrid to allocate the values.
Article 3 - Currency
{
“COINNAME”: “IangBux”,
“INFLATION”: “5%”,
“INITIALISSUE”: “1,000,000,000”
“SYMBOL”: “$”
“DECIMALS”: “2”
}The Community hereby creates a currency known as {COINNAME}, possession of which is evidence of a contribution to the community. The quantity of {COINNAME} shall increase no more than {INFLATION} per year after the first {INITIALISSUE} of {COINNAME} are distributed.
That is the raw text, with some extra bits needed below. Now, your parser for this is quite simple:
- scan through and pull out all the JSON parts to set some internal variables. In short, JSON blocks are signalled by a curly braces, each opening and closing alone on a line alone, as normal.
- What is left is prose, which needs to be checked for pairs of curly braces, holding parameters to be substituted. Curly braces are safe in this context because a prose legal contract wouldn’t need to use them (I hope!) so they are available for simple parsing.
- Feel free to add some colour or mild formatting to accentuate the slightly smart activity that is going on.
This is simple, but not too simple like the earlier arrangements. JSON is good for parameters but lousy at readable text; prose is hopeless for parameters, but claims great readability.
As simple as possible, but no simpler
Mixing prose & params together in a hybrid creates a simple, computer-readable and human-readable contract that can now be varied and used in different contexts. Our primary goal is still intact - the contract remains no more difficult for a human to read than the original prose; any unreadability that is left over is probably due to the original text, but lawyers have to help us there with plain language contracts (please!).
We could of course use any number of formats. I’ve used INI format in the past. You could use LaTeX or XML, but I won’t be so rude as to inflict those abominations on you in this post! The point here to remember is (a) the purpose of this is first, foremost and always to make the text readable by humans, especially those who don’t spend their life deep in code and technics, and (b) keep it as simple as possible, but no simpler ;-)
Having laid down the basic idea of how, my next post will be a brief discussion on why getting the document nailed down matters in the hard-core digital transaction sense, before returning to the Constitution.
End notes: for further reading, see the original paper Ricardian contract. The Clack et al paper Smart Contract Templates: foundations, design landscape and research directions presents current thinking. The most advanced thinking on a clause editor I have seen is at Common Accord. For smart contracts and objectification of blockchain contracts see The Sum of all Chains and in video but that takes us chasing Alice down the rabbithole.
