Smart Legal Agreements on AWS

This sample serverless application helps to run Smart Legal Agreements developed with the tool set from Accord Project on Amazon Web Services. It uses AWS Lambda for runtime, Amazon Quantum Ledger Database (Amazon QLDB) for immutable ledger, Amazon Simple Storage Service (Amazon S3) for storing files, and Amazon Simple Queue Service (Amazon SQS) for sending contract obligation events. With this solution you can:

1. Initialize and deploy Smart Legal Agreements developed with Accord Project tool set using only the serverless services on AWS.
2. Run deployed Smart Legal Agreements, persist run results to Amazon QLDB, and emit contract events to trigger external systems with Ledger Metadata information for contract state integrity verification.
3. Retrieve a history of a specific contract run results to track all contract events.
4. Verify integrity of the contract data using Ledger Metadata generated by Amazon QLDB service.

The following diagram illustrates this serverless application, deployed for a single AWS account.

Setup

Pre-requisites

1. An existing AWS account
2. Mac or Linux machine to run "build" and "deploy" bash scripts. You may use AWS Cloud9 development environment to build and deploy this application or install and setup the following tools on your own machine:
   • git tool for your platform to clone this repository: Getting Started - Installing Git.
   • AWS CLI: Installing, updating, and uninstalling the AWS CLI version 1
   • SAM CLI: Installing the AWS SAM CLI
   • Node.js version 12.x and later (if using Amazon Elastic Compute Cloud service (Amazon EC2), it is recommended to install it with nvm: Tutorial: Setting Up Node.js on an Amazon EC2 Instance)

Setup instructions

1. Clone this repository to your build and deployment machine: git clone https://github.com/accordproject/aws-qldb-lambda.git

2. Review and edit the values of the environment variables in ./devops/deploy.sh

3. Run the build script

   cd ./devops
   ./build.sh
   

4. Run the setup script

   cd ./devops
   ./deploy.sh
   

Usage

1. Deploy a new smart legal agreement
   • Download the "Mini-Late Delivery and Penalty Payment" contract template archive from Accord Project Template Library: [email protected]
   • Open your Amazon S3 service console and upload the contract template archive (.cta) file to the root of an S3 bucket that you specified in the ACCORD_S3_CONTRACTS_REPO_NAME parameter of ./devops/deploy.sh file (default name is accord-contracts-${AWSRegion}-${AWSAccountId}).
   • Open your AWS Lambda console
   • Search for a function with name accord-contracts-accord-deploy
   • Invoke a new test event with contract initialization data. For example:

 {
    "contractSourceS3BucketObjectPath": "[email protected]",
    "ledgerDataPath": "Accord",
    "eventsQueue": "accord-contracts-output",
    "contractId": "minilatedeliveryandpenalty-payment-best-latte-1",
    "contractData": "{\"$class\":\"org.accordproject.minilatedeliveryandpenalty.MiniLateDeliveryContract\",\"buyer\":\"resource:org.accordproject.party.Party#Best%20Latte\",\"seller\":\"resource:org.accordproject.party.Party#Dairy%20Co\",\"penaltyDuration\":{\"$class\":\"org.accordproject.time.Duration\",\"amount\":2,\"unit\":\"days\"},\"penaltyPercentage\":10.5,\"capPercentage\":52,\"maximumDelay\":{\"$class\":\"org.accordproject.time.Duration\",\"amount\":15,\"unit\":\"days\"},\"contractId\":\"d095f9fb-e9a1-42d3-927a-4dc15cc24c0f\",\"$identifier\":\"d095f9fb-e9a1-42d3-927a-4dc15cc24c0f\"}"
 }

• You should receive a response as the following:

   "{\"response\":null}"

2. Executing a late delivery clause of the agreement

   • Open your AWS Lambda console
   • Search for a function with name accord-contracts-accord-run
   • Invoke a new test event with delivery invocation data. For example:

      {
         "ledgerDataPath": "Accord",
         "contractId": "minilatedeliveryandpenalty-payment-best-latte-1",
         "requestString": "{\"$class\":\"org.accordproject.minilatedeliveryandpenalty.LateRequest\",\"agreedDelivery\":\"2021-03-01T12:00:00-05:00\",\"deliveredAt\":\"2021-03-10T03:24:00-05:00\",\"goodsValue\":200}"
      }

   • You should get a response similar to the following:

      "{\"response\":{\"$class\":\"org.accordproject.minilatedeliveryandpenalty.LateResponse\",\"penalty\":84,\"buyerMayTerminate\":false,\"$timestamp\":\"2021-05-17T03:56:39.595Z\"}}"

   • Check the Amazon SQS queue with the name specified in a ACCORD_EVENTS_SQS_QUEUE_NAME parameter of ./devops/deploy.sh file (default is accord-contracts-output). It should contain a PaymentObligation event with accompanying Ledger Metadata of a QLDB document with contract run results. It also includes the metadata of the version of document holding contract run results to use for verification.

3. Retrieving the metadata of the latest agreement logic run result (the receipt)

   • Open your AWS Lambda console
   • Search for a function with name accord-contracts-qldb-get-document-metadata
   • Invoke a new test event with results document id. For example:

      {
         "ledgerName": "accord-contracts",
         "tableName": "Accord",
         "documentKey": "minilatedeliveryandpenalty-payment-best-latte-1.result"
      }

   • IMPORTANT To prepare the receipt for verification, you need to:
     • Copy the value of "ledgerMetadata" property from the output of accord-contracts-qldb-get-document-metadata function

4. Verifying Ledger Metadata

   • Open Lambda console: https://console.aws.amazon.com/lambda/home
   • Search for a function with name accord-contracts-qldb-verify
   • Invoke a new test event with the "receipt" data. For example you can paste the value of "ledgerMetadata" from the previous step a string:

 {
    "ledgerMetadata":"{\"LedgerName\":\"accord-contracts\",\"TableName\":\"Accord\",\"BlockAddress\":{\"IonText\":\"{strandId: \\\"4Y7QCHBmOxm85uX3izwGJR\\\", sequenceNo: 19}\"},\"DocumentId\":\"0QcF9OkXRfQ2mDx9OzUTtn\",\"RevisionHash\":\"E7LeTyBqlwfMTCIQjxi+ertTU3V9IOHc5l8ETYIMwj8=\",\"LedgerDigest\":{\"Digest\":\"vTzOW9bJdgsombIYHmRDN7v0WO/xn0TPckp/YPOnplU=\",\"DigestTipAddress\":{\"IonText\":\"{strandId:\\\"4Y7QCHBmOxm85uX3izwGJR\\\",sequenceNo:38}\"}}}"
 }

• or, you may parse it into a JSON object like this:

   {
    "ledgerMetadata":{
       "LedgerName": "accord-contracts",
       "TableName": "Accord",
       "BlockAddress": {
          "IonText": "{strandId: \"4Y7QCHBmOxm85uX3izwGJR\", sequenceNo: 19}"
       },
       "DocumentId": "0QcF9OkXRfQ2mDx9OzUTtn",
       "RevisionHash": "E7LeTyBqlwfMTCIQjxi+ertTU3V9IOHc5l8ETYIMwj8=",
       "LedgerDigest": {
          "Digest": "vTzOW9bJdgsombIYHmRDN7v0WO/xn0TPckp/YPOnplU=",
          "DigestTipAddress": {
                "IonText": "{strandId:\"4Y7QCHBmOxm85uX3izwGJR\",sequenceNo:38}"
          }
       }
    }
 }

- You should get a response like the following:

 "{\"response\":true}"

5. Retrieve full history of the logic run results for your agreement:
   • Open your AWS Lambda console
   • Search for a function with name accord-contracts-qldb-get-document-history
   • Invoke a new test event with results document id. For example:

 {
    "ledgerName": "accord-contracts",
    "tableName": "Accord",
    "documentKey": "minilatedeliveryandpenalty-payment-best-latte-1.result"
 }

• Your response will include at least two records: one with initialization results and another with the results of running the contract on step two.

Cleaning up

To remove this serverless application from your account, do the following:

1. Open your AWS console and navigate to the Amazon QLDB service console
2. From the list of ledgers choose the ledger name you specified in the ACCORD_QLDB_LEDGER_NAME parameter of ./devops/deploy.sh file (default name is accord-contracts).
3. Click Edit button and uncheck the box Enable deletion protection. Click the Confirm changes button.
4. Navigate to Amazon S3 service console.
5. From the list of buckets choose the one you specified in the ACCORD_S3_CONTRACTS_REPO_NAME parameter of ./devops/deploy.sh file (default name is accord-contracts-${AWSRegion}-${AWSAccountId}).
6. Click Empty button to delete all contract templates.
7. Go back to the list of all buckets and choose the one you specified in the ACCORD_DEPLOY_SAM_S3_BUCKET parameter of ./devops/deploy.sh file (default name is accord-sam-${AWSRegion}-${AWSAccountId}).
8. Click Empty button to delete all packaged AWS Lambda resources.
9. Navigate to AWS CloudFormation service console (Please double check your region if you used this link).
10. Choose the CloudFormation stack named as per value of ACCORD_STACK_NAME parameter of ./devops/deploy.sh file (default name is accord-contracts).
11. Click Delete button.
12. Choose the CloudFormation stack with named staring with the value of ACCORD_STACK_NAME parameter of ./devops/deploy.sh file (default name is accord-contracts-s3).
13. Click Delete button.
14. Navigate to the Amazon CloudWatch service console.
15. From the left hand menu choose Logs > Log groups.
16. In the Filter field enter the value of ACCORD_STACK_NAME parameter of ./devops/deploy.sh file (default name is accord-contracts).
17. Choose all log groups under /aws/lambda/${ACCORD_STACK_NAME}- and select Actions > Delete log group(s).

After that all the resources of this application are removed from your account.