Verify delivery conditions with the Accord Project and Amazon Quantum Ledger Database – Part 2

This is part two of the two-part series of blog posts discussing how to apply smart legal contracts technology to verify delivery conditions with open-source Accord Project and Amazon Quantum Ledger Database service. In the first part we introduced the smart legal contract technology, a sample delivery process, and reviewed the solution to run smart legal contracts on AWS with Accord Project. In this part of the series, we will dive deeper into how the solution works. To set up and try the whole demo yourself, clone the code of this solution from the GitHub repo and follow the instructions in the project’s README.md file.

The following diagram exhibits all the key actions we do to manage and use our smart legal contract.

Let’s review the key processes:

1.1 Upload the contract template.
1.2 Trigger deployment of a new contract based on the contract template.
1.3 Retrieve the contract template.
1.4 Initialize and publish the state of the contract.
2.1 Trigger the clause of the contract.
2.2 Retrieve the state of the contract.
2.3 Retrieve the contract template and verify its integrity with a ledger-stored hash.
2.4 Run the clause of the contract and store the state of the contract and the result of run.
2.5 Emit a contract obligation accompanied by the ledger metadata to verify its integrity.
2.6 Retrieve the contract obligation event and ledger metadata.
3.1 Retrieve the receipt of the latest transaction with the details of the clause triggered and its output.
3.2 Retrieve ledger-generated metadata for the most recent document revision with the contract’s clause run results.
3.3 Verify the receipt for the contract run result.
3.4 Retrieve the proof for the specified document and run the verification logic.
A. Store the .cta files.
B. Store a hash of the version of a contract template used during initialization, an contract state, and a history of runs of the clauses of an contract.

After all components are deployed to your AWS account, we need to instantiate a new smart legal contract between our coffee shop and the wholesaler. To do that, we need to download an Accord Project’s .cta file with the contract template from the catalog of open-source contract template files in the Accord Project Templates Library. Then we upload the .cta file to our S3 bucket (see Step 1.1 on the diagram).

If you want to build your own contract template, follow this tutorial for an in-browser Template Studio.

After the file is uploaded, we trigger a DeployContract Lambda function and, along with other parameters, we provide a JSON object holding initialization data (Step 1.2). The DeployContract function downloads the required template from the S3 path we specified in our parameters (Step 1.3), and uses the Accord Project’s Ergo engine to trigger the initialization logic of the template with the initialization data we provided. As a result, we get another JSON object with a state of our smart legal contract that is used in subsequent runs of its logic. The DeployContract function stores that object and a hash of the template in Amazon QLDB (Step 1.4).

It’s now easy to see that the smart legal contract, which legally binds the relationships of the coffee shop and the wholesaler, is a combination of the contract template file and the data initializing it. Therefore, it’s important to guarantee that any changes to the initialization data are fully tracible and the integrity of both the template file and the data are verifiable through hashes we keep in the ledger. To further guarantee their integrity, our DeployContract function keeps the hash of the Accord Project’s .cta file and the full initialization data object in Amazon QLDB. Similarly, we capture the results of all runs of our smart legal contract’s logic, making all contract transactions fully tracible as well. Let’s dive deeper into how that works.

After the smart legal contract is instantiated and all related data is stored in Amazon QLDB, the manager of the coffee shop can start using it to check in deliveries from the wholesaler. Every check-in action triggers the RunContract Lambda function (Step 2.1), which does the following:

1. Gets the contract template from Amazon S3 and the state from Amazon QLDB (Steps 2.2 and 2.3).
2. Verifies the integrity of the template by re-calculating its hash and comparing with the one captured in Amazon QLDB during initialization.
3. With the help of the Cicero templating system, it assembles a runnable instance of a complete smart legal contract and triggers a function (a clause in the Accord Project’s terms), written in Ergo language, that processes the delivery check-in information.
4. Based on the check-in data and the current state, it calculates penalties and checks the conditions for delivery termination.
5. Finally, the Lambda function puts a JSON object with the clause run results to Amazon QLDB (Step 2.4) and sends the penalty obligation event to Amazon SQS (Step 2.5) to notify, for example, an accounting system (Step 2.6).

After that, the run is complete and the state of our contract is updated. From the ledger perspective, you can imagine the state changes as per the following diagram.

With such data model, the history function in Amazon QLDB makes it easy to traverse through the history of all runs and any changes made to the state of our contract.

Now let’s see how we can verify that the smart legal contract data we store in Amazon QLDB hasn’t been tampered with.

We start with retrieving a digital receipt (Steps 3.1 and 3.2) for a required version of our contract’s state. The receipt is a JSON object that contains the cryptographic information necessary for verifying the integrity of the contract’s state data. That information includes:

• The Amazon QLDB ledger and table names
• The addressing information of the block in the Amazon QLDB journal that contains our document revision
• A hash and an identifier of the document holding our contract data
• The ledger digest, which is a cryptographic hash value that uniquely represents the ledger’s entire history of document versions (revisions in Amazon QLDB terminology) as of a point in time identified by a digest tip address

The following diagram depicts the artifacts from the Amazon QLDB ledger that are included in the receipt.

After either the coffee shop manager or the wholesaler gets the receipt, they can keep it in a safe place, like their own file storage, and use it later to verify that neither the document with the contract state, nor the whole Amazon QLDB ledger, were modified. To do that, they can call a Verify Lambda function that does the following (Steps 3.3 and 3.4):

1. Retrieves the document revision with the contract transaction data from Amazon QLDB and checks that its hash is the same as in their receipt.
2. Gets the proof for the document revision.
3. Concatenates the document hash from the receipt to the first proof hash and calculates a hash of the result. It concatenates the resulting hash to the next proof hash in the list and calculates the hash of the result. The function repeats this process with every hash in the proof until a final hash is calculated.
4. Compares the final hash with the ledger digest from the receipt. If both are the same, that proves that no modifications occurred either in the document nor in the whole ledger up to the point the ledger digest was generated.
5. Based on the result, the function returns a positive or negative response.

Because both parties can retrieve and keep a copy of the receipt independently, either of them can use it to verify the integrity of the contract data through their own copy of the Verify Lambda function and calling the API of Amazon QLDB service directly. With this mechanism, both the coffee shop manager and the wholesaler supervisor can trust in the integrity of their contract.

Summary

In this series, we introduced the concept of smart legal contracts and how to use them to automate well-established contractual relationships. We discussed the serverless architecture of the solution, which allows parties to run smart legal contracts on AWS using the open-source Accord Project, Lambda, Amazon QLDB, and other AWS services. Finally, we walked through the process of deploying and running smart legal contracts using the proposed architecture and we reviewed how to verify the integrity of the contract’s state using cryptographic features of Amazon QLDB.

As mentioned before, the smart legal technology can be applied in many domains and we hope that this series gave you an inspiration to try it in your own interesting ways.

Happy building on AWS!

About the author

Nikolay Vlasov is a Senior Blockchain Architect with AWS Professional Services. Being part of a Global Speciality Practice team, he helps clients worldwide to turn their ideas into Pilots, Minimally Viable Products, and Production-ready systems based on blockchain technology.