ContractPen: How to create an Accord Project smart legal clause without computer programming experience
An Accord Project smart legal clause is the basic part of a contract which may be made up of one or many such clauses. For computations to occur there must be calculations which are expressed in some form, for this article it is expected you have basic knowledge of a computer spreadsheet but you do not know how to program a computer. With just knowledge of how to produce a spreadsheet and logical thinking then a smart contract can be defined which generates files which can then run on the Accord Project as a smart legal contract with computations.
Note that at this date (28th of March 2019) there are some limitations as to what can be done with ContractPen and they are described at the end of this document, please read the limitations right at the end of this page to understand what can and cannot be done.
In this article it is shown:
* How to create a smart legal clause with computational elements
* Execute and demonstrate the computations
* How to download the Accord Project source code generated from this process
* Bring this code into Accord Studio and finally import this code to Clause.io as a legal clause
Conceptually ContractPen takes inputs, passes them through spreadsheet(s) and produces outputs where calculations are expressed in the spreadsheet.
ContractPen also allows for data models to be defined when combined with the spreadsheet leads to a smart contract being generated in the Accord Project Ergo language.
Creating a demonstration smart legal contract clause
Visit https://contractpen.com/ and sign-in with your google account or create a new account and sign-in. Press the NEW CONTRACT button on the top left of the screen after login, type in the contract name and press the larger button which says “Click to use the Contract Wizard to guide you through the creation of the smart legal contract”. You must also follow all the instructions of the demonstration steps as documented on the Introduction page, clicking the “feeling lazy” link on each and every page and clicking to the next step.
This process goes through 8 steps of creating a smart legal contract clause, at the end of these steps you should have a basic understanding of how an accord project smart legal clause can work. For this step by step part of the document there are no images given to keep the step descriptions as short as possible. Also when you click the “feeling lazy” link, all this data is entered for you automatically, this is only an explanation here.
Step 1: Entry of the clauses template, this is the text of the contract as a lawyer or human would see it. Go to the next step by clicking Step 2 at the top.
Step 2: Creating a PurchaseClause, a PurchaseClause represents the data fields which will be shown on the legal contract as a person will see it. In this demonstration the two data fields are the purchaserName and supplierName. You can imagine that the data for a purchaser’s name and suppliers name would change from one instance of the contract to another depending on who the purchaser and supplier are. The clause information typically does not change for this contract instance but state data does change.
Step 3: Creating a PurchaseOrderState, this is information about the contract which exists and changes as the contract exists from day to day. It is the clauses state, the word state means the description of its data at a moment in time. In this case the PurchaseOrderState records the part number, name, quantity of parts and unit price of each part in the purchase order. It is assumed for demonstration purposes the contract has changing data about what the price of the items is being purchased and the number of items being purchased.
Step 4: A PurchaseRequest, this is a request which can enter the smart legal contract as it is executing, it may change the data in the PurchaseOrderState and return a response. Here the fields are described as adjustQuantity and unitPrice. What are we doing here? When a PurchaseRequest enters the PurchaseOrderState it updates the state and generates a PurchaseResponse. What are we updating and in what way? This will be explained soon but in short the quantity of items being purchased is added to the PurchaseOrderState’s quantity and updated, also the unitPrice is updated but directly updated.
Step 5: A PurchaseResponse is the response to the request and it contains the total price as calculated and a value which indicates if the price is too expensive. This value of being too expensive is computed by an IF statement which says if the total price is greater than 8 then it istoo expensive.
Step 6: A spreadsheet defines the calculations and updates which will occur when a request comes into the smart clause, the response is generated and the state is updated (PurchaseOrderState).
The cells on the left define the request and response cells, the cells on the right define the state before and after the update. You can change the values in these cells to see what the calculations will produce. For example, click on cell B3 to set the adjust quantity to =4.0 and see what the updated state and generated response will be. You will notice the STATE OUT quantity has updated to 5.0.
Click on the cells of the spreadsheet to inspect the calculations of each cell, this helps to explain what is going on.
Notice on cell B8 there is a IF calculation, this will be discussed later.
Step 7: Input output bindings bind the spreadsheet cells to the data models as you defined earlier in steps 2, 3, 4 and 5. Since data will come into the smart contract in the data models such as in a PurchaseRequest, that data then needs to go as input to the spreadsheet. If you study the relationship between the bindings on this Step 7 and the spreadsheet on step 6 it will become clear how the calculations proceed.
Step 8: If you pressed the feeling lazy link on each and every page you are now on step 8 and you can test the smart contract clause by clicking the Click to Execute button. If you press the Click to Execute button 7 times and look at the data you will notice the Response total price is equal to 8 and the tooExpensive field is set to 0. If you press the Click to Execute button once more then the total price in the response will be equal to 9 and the tooExpensive field is set to 1.
To finish you must click the link “If you wish to finish click here to close this wizard step creation process” on the Step 8 page.
What is the point of all the above steps? You now have smart legal contract computer code written in the Accord Project Ergo computer language which matches the logic of your data models and spreadsheet and you didn’t need to do any computer programming!
Click on the Generated Source Code menu link on the left hand side of the page. The files which should interest you are the model.cto which contains a description of the data models of request, response, clause and state, logic.ergo file contains the computations which you expressed in the spreadsheet as converted to computer code.
If you are a computer programmer you will notice that there is an IF statement in the code generated which was originally in the spreadsheet and the IF statement now has the form of the following in Ergo computer code which will run on Accord Project.
let cellB8 : Double = if ((((inputState_quantity) + (inputRequest_adjustQuantity)) * (inputRequest_unitPrice)) > (8.0)) then (1.0) else (0.0);
If you wish to download this code as a ZIP file or CTA archive click the links above which say for example Download ZIP.
Execute and demonstrate the computations
To continue to change the spreadsheet and models you can do the following. Click on the Calculations link of the menu on the left of the page. Here is the spreadsheet and bindings, you can also click Automatically generated Ergo code to see the code and click Test Execution to test this execution.
To edit the data models and their data note that there are two different things here, there are the data model definitions and there is the data model data. The data model definitions define the fields that the data models have and the types of data allowed in those fields. The data model data is the real data stored in this contract. Clicking on the “Models” link and then clicking on the “Click to edit data model definitions” button allows editing of the data model definitions where-as clicking on the link in the menu for PurchaseRequest allows for editing of the data stored in the PurchaseRequest.
Bring this code into Accord Studio
If you wish to skip this step you can do so and export the cta file and import it directly into clause.io, but for understanding it is useful to follow this step to see what Accord Studio does. Note you could develop your code in Accord Studio without ContractPen but this is suitable for a programmer.
Accord Studio is an open source editor for Accord Project clauses and contracts as developed by the Accord Project team. We are doing a clause of a contract, so in a new browser tab go to the website. https://studio.accordproject.org/
Click on the top where it says “New Template” menu item and click “Empty Clause”, then click on model and copy the text from model.cto from ContractPen’s outputted file into this area. You need to copy also logic.ergo file contents from ContractPen to the logic section of this project, at this step you will have errors.
Now the contract text must be copied in from ContractPen, at this still there will still be an error message so also copy the same text into the “Test Contract” tab.
The “Test Contract” must be filled in with text, where the fields [{supplierName}] and [{purchaserName}] existed you must replace them with quoted strings such as as shown in the following image and at this point there should be no error messages and you can see the text of the contract was converted into a data model containing the typed purchaserName and supplierName, you can see here the binding of what you typed as the supplier and the purchaser binds from the text to the data model. There should be No Errors written on the bottom left of the page finally at the end.
You will wish to give your clause a name on the left where it says “Current Template”.
Import this smart legal clause into Clause.io
Clause.io allows for the importing of clauses from files with the extension “.cta”, you can export the clause from either accord studio or ContractPen as a cta file.
How to import a “.cta” file? first create an account at clause.io and create a new contract. On the top right of the page is a “Templates” tab, click here, go to your “private organizational library” on the left menu and on this page you can upload your “.cta” file exported from the previous step either in Accord Studio or ContractPen then it can be used as a smart clause within the Contract.
Clause provides features which neither ContractPen or Accord Studio provide at this moment such as binding with real life payments, connecting to real life data and signatures between people and many more features. Blockchain oracles are one of the ways in which smart contracts can be linked with real world events.
Clause also makes it easy for you to build parameterized legal contracts and to connect them to external data sources. or example, you may have a Service Level Contract that specifies a percentage reduction in a customer’s monthly bill, based on the availability of a service. The parameters for the contract are defined in a Smart Clause® Template and Clause can be used to automatically generate invoices (or move money!) based on IT monitoring events. See their website and FAQ for more details.
Limitations of ContractPen at the moment (Thursday March 28th 2019)
ContractPen should be seen as beta software at this moment and is undergoing constant change so bear in mind the following warnings!
Stay on the happy path, that when dealing with the creation of data types such as PurchaseRequest or your own data types, for numeric values use the data type of Double, not Money or any other, for strings use the data type of String. If you use other data types it may or may not work within ContractPen as other types are not well tested at this moment. (in the near future all things will get better).
Try to use the wizard generator to generate your accord project clause, if using String and Double data types it is likely to work without problems.
The spreadsheet supported limited typical math operations of + — * / < > <= >= and equals cell assignment = and IF(?,?,?), some other operations may or may not work, or may work but not be converted to Ergo computer code, usually the given operations are sufficient to express calculations and conditional statements. For example if you want to calculate a percentage of something try this in your cell =0.03*B1 where 0.03 expresses 3 percent.
If something doesn’t work you will likely NOT be told why by the ContractPen application at this moment with any warning message, you should consider what you inputted last and try to fix that problem.
This is an new and emerging area of smart legal contracts and new software features are developed constantly from week to week, expect new and exciting changes soon.
