Skip to content
Smart contracts and high level API powering the Agreements Network
Branch: develop
Clone or download
j-h-scheufen Merge pull request #214 from ommish/hotfix/expose-addDataDefinitionsT…
…oModel-function

Export addDataDefinitionsToModel in bpm-controller.js
Latest commit 8f1bca1 Mar 15, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
api
contracts
docs
scripts
test
.eslintignore
.gitignore
CHANGELOG.md
Dockerfile
LICENSE
Makefile
README.md
docker-compose.yml

README.md

/$$       /$$                     /$$                   /$$
| $$      | $$                    | $$                  | $$
| $$$$$$$ | $$  /$$$$$$   /$$$$$$$| $$   /$$  /$$$$$$$ /$$$$$$    /$$$$$$  /$$$$$$$   /$$$$$$
| $$__  $$| $$ |____  $$ /$$_____/| $$  /$$/ /$$_____/|_  $$_/   /$$__  $$| $$__  $$ /$$__  $$
| $$  \ $$| $$  /$$$$$$$| $$      | $$$$$$/ |  $$$$$$   | $$    | $$  \ $$| $$  \ $$| $$$$$$$$
| $$  | $$| $$ /$$__  $$| $$      | $$_  $$  \____  $$  | $$ /$$| $$  | $$| $$  | $$| $$_____/
| $$$$$$$/| $$|  $$$$$$$|  $$$$$$$| $$ \  $$ /$$$$$$$/  |  $$$$/|  $$$$$$/| $$  | $$|  $$$$$$$
|_______/ |__/ \_______/ \_______/|__/  \__/|_______/    \___/   \______/ |__/  |__/ \_______/
The Blackstone codebase is a collection of smart contracts and RESTful APIs which together form the basis for the Agreements Network.

It is named after Sir William Blackstone, an English jurist, judge, and politician of the eighteenth century.

This collection includes a full-feature business process execution engine, and high-level translator from BPMN standard to smart contract based process graphs. It also include an object management suite utilized by the Agreements Network.

Preliminary Note

While the code in this repository is geared towards its use in the Agreements Network, the lower-level functions and smart contracts are highly reusable and suited to build any blockchain-based ecosystem application. If you would like to learn more about the interfaces used in this system please visit the documentation site for the network.

To ask questions or to learn more feel free to join the Agreements Network mailing list to ask questions or to join the community.

Table of Contents

  1. Quick Start
  2. First Steps
  3. Tutorials
  4. Develop & Test

Quick Start

It's highly recommended to use docker-compose as described below to run all of the commands. This saves installation problems and environment problems between developers. (All commands should be run from the root of this repo.)

Prerequisites

Install make, docker, and docker-compose. Now you're ready to go.

Go VROOM!

The following commands will start a Burrow Blockchain, compile, deploy and wire all smart contracts and boot the Node.js API.

To start from a completely clean repo (includes npm install):

make run_all

To start from a repo that already has node_modules:

make run

Now, the API is available at http://localhost:3080.

First Steps

The following serious of steps outlines basic interactions with the Blackstone API:

Create a user

POST http://localhost:3080/users

Body (application/json):

{
	"user": "john.smith",
	"email": "john.smith@example.com",
	"password": "298yefh028"
}

Response:

{
    "address": "AB3399395E9CAB5434022D1992D31BB3ACC2E3F1",
    "id": "john.smith"
}

Login

PUT http://localhost:3080/users/login

Body (application/json):

{
	"user": "john.smith",
	"password": "298yefh028"
}

A successful login creates a Json Web Token access_token that can be used for any subsequent requests using this user's session.

Deploy a BPMN process model

Use the BPMN model here as application/xml body to the endpoint:

POST http://localhost:3080/bpm/process-models

Part of the application/json response gives you the information about the deployed processes Agreement Formation and Agreement Execution. Note the address fields of the two created processes:

"model": {
    "id": "1537809995472_Gc4N66ORqT",
    "address": "81420B0BD90FBDA9765207569DA0FF6D4A429F65"
},
"processes": [
    {
        "processDefinitionId": "Process_104nkeu",
        "interfaceId": "Agreement Formation",
        "processName": "Sale Formation",
        "modelAddress": "81420B0BD90FBDA9765207569DA0FF6D4A429F65",
        "address": "09F5727636788958DAEF32500830F0AD4EB34901",
        "private": false,
        "author": "AB3399395E9CAB5434022D1992D31BB3ACC2E3F1"
    },
    {
        "processDefinitionId": "Process_0gzkjfe",
        "interfaceId": "Agreement Execution",
        "processName": "Sale Execution",
        "modelAddress": "81420B0BD90FBDA9765207569DA0FF6D4A429F65",
        "address": "E6534E45E2B26AF4FBB64E42CE7FC66688696483",
        "private": false,
        "author": "AB3399395E9CAB5434022D1992D31BB3ACC2E3F1"
    }
],

Create an Agreement Archetype

Now we can make an archetype for new agreements by calling

POST http://localhost:3080/archetypes

Body (application/json):

{
    "name": "My Sales Archetype",
    "description": "A template agreement for the sale of goods between a Buyer and a Seller",
    "price": "5.99",
    "isPrivate": false,
    "active": true,
    "parameters": [
        { "type": 8, "name": "Buyer", "signatory": true },
        { "type": 8, "name": "Seller", "signatory": true },
        { "type": 1, "name": "Item Description" },
        { "type": 5, "name": "Price" }
    ],
    "documents": [],
    "jurisdictions": [
        {
        "country": "US",
        "regions": []
        }
    ],
    "formationProcessDefinition": "09F5727636788958DAEF32500830F0AD4EB34901",
    "executionProcessDefinition": "E6534E45E2B26AF4FBB64E42CE7FC66688696483"
}

This will return the address of the new archetype for reference:

{
    "address": "4EF5DAB8CE089AD7F2CE7A04A7CB5DB1C58DB707"
}

Instantiate an Agreemeent

Now we can go ahead and create an actual legal agreement based on the information we've configured in the system so far. Note that we're using the currently logged-in user as both the "Buyer" and "Seller" for demo purposes only; in a real-world legal context that would not be a valid.

POST http://localhost:3080/agreements

Body (application/json):

{
  "name": "Sale No. 7364",
  "archetype": "4EF5DAB8CE089AD7F2CE7A04A7CB5DB1C58DB707",
  "isPrivate": false,
  "maxNumberOfEvents": "10",
  "parameters": [{
      "name": "Buyer",
      "type": 8,
      "value": "AB3399395E9CAB5434022D1992D31BB3ACC2E3F1"
    },
    {
      "name": "Seller",
      "type": 8,
      "value": "AB3399395E9CAB5434022D1992D31BB3ACC2E3F1"
    },
    {
      "name": "Item Description",
      "value": "Lamborghine (red, 2016)"
    },
    {
      "name": "Price",
      "value": "160000.00"
    }
  ]
}

This will return the address of the new archetype for reference:

{
    "address": "B3AEAD4717EFF80BDDF5E22110521029A8460FFB"
}

You can use the returned address to show the status and information about your agreement:

GET http://localhost:3080/agreements/B3AEAD4717EFF80BDDF5E22110521029A8460FFB

Participate in the agreement workflow

According to the Process Definition covering the formation of this sales agreement, both parties have to complete the "Sign Agreement" task by signing the agreement. Since we used the same user for demo purposes, the user's task list will show two items:

GET http://localhost:3080/tasks

[
    {
        "state": 4,
        "processAddress": "A2927604F47D45CC518557A9C31E5EACB9EF8AC5",
        "activityInstanceId": "4C5381C1AB820779B897DAA64378C20D2475EC7535691B805AC02C0346E339B6",
        "activityId": "Task_0ky8n9d",
        "created": 1537813661000,
        "performer": "AB3399395E9CAB5434022D1992D31BB3ACC2E3F1",
        "modelAddress": "81420B0BD90FBDA9765207569DA0FF6D4A429F65",
        "modelId": "1537809995472_Gc4N66ORqT",
        "processDefinitionAddress": "09F5727636788958DAEF32500830F0AD4EB34901",
        "processDefinitionId": "Process_104nkeu",
        "agreementAddress": "B3AEAD4717EFF80BDDF5E22110521029A8460FFB",
        "agreementName": "Sale No. 7364",
        "name": "Sign Agreement",
        "processName": "Sale Formation"
    },
    {
        "state": 4,
        "processAddress": "A2927604F47D45CC518557A9C31E5EACB9EF8AC5",
        "activityInstanceId": "42B546051E099604F7AEAD7A3447C646E7EFF9ACFAB90B71CC89408023124F75",
        "activityId": "Task_0ky8n9d",
        "created": 1537813661000,
        "performer": "AB3399395E9CAB5434022D1992D31BB3ACC2E3F1",
        "modelAddress": "81420B0BD90FBDA9765207569DA0FF6D4A429F65",
        "modelId": "1537809995472_Gc4N66ORqT",
        "processDefinitionAddress": "09F5727636788958DAEF32500830F0AD4EB34901",
        "processDefinitionId": "Process_104nkeu",
        "agreementAddress": "B3AEAD4717EFF80BDDF5E22110521029A8460FFB",
        "agreementName": "Sale No. 7364",
        "name": "Sign Agreement",
        "processName": "Sale Formation"
    }
]

Each of these tasks can be completed using the following endpoint. Note: This URL is a shortcut for signing the agreement and completing the workflow task in one call.

PUT http://localhost:3080/tasks/4C5381C1AB820779B897DAA64378C20D2475EC7535691B805AC02C0346E339B6/complete/B3AEAD4717EFF80BDDF5E22110521029A8460FFB/sign

PUT http://localhost:3080/tasks/42B546051E099604F7AEAD7A3447C646E7EFF9ACFAB90B71CC89408023124F75/complete/B3AEAD4717EFF80BDDF5E22110521029A8460FFB/sign

Signing and completing both these tasks also completes the Formation of the agreement. If you retrieve the details about the agreement, you'll see that the legal state has switched to Executed (legalState: 2).

GET http://localhost:3080/agreements/B3AEAD4717EFF80BDDF5E22110521029A8460FFB

Tutorials

Tools (coming soon)

Provides an overview of the tools, specifically how the Agreements Network leverages burrow deploy. This will help users understand how to deploy and wire smart contracts utilizing burrow.

Smart Contract Framework (coming soon)

Delivers an introduction to the smart contracts in this project and walks through the concepts to deploy a basic framework of upgradeable packages of smart contracts wired together as micro-services in order to build applications.

My Application (coming soon)

Build a web app to interact with your archetypes and active agreements.

Develop & Test

The following sections provide an overview over commands helpful for developing and testing Blackstone smart contracts and API functions.

Test All

To run the entire test suite run the following. N.B. -- this will take forever.

make test

Test Bundles

To run the test step for a single bundle of contracts run the following. N.B. in the following command no spaces are entered between the target bundles. To only run one bundle do not enter a comma.

make test_contracts tgt=agreements,bpm-runtime

To run the test step for all the bundles of contracts run the following:

make test_contracts

Work with the API

To run the npm install for the API run the following:

make install_api

To run the API test suite (without installing NPM or the bundles) run the following:

make test_api

To restart the API but leave the chain running follow this sequence:

  1. make run -> this operation is non-blocking and will return you to your terminal. It will background processes that will follow the logs.
  2. To turn everything off (including the chain) from here run make clean.
  3. To only reboot the API but leave the chain running from here run make restart_api. This is a blocking call and will not return you to your terminal.
  4. To reboot the API (again): ctrl+c then make restart_api. Rinse and repeat as needed.
  5. To turn everything off or reset the chain or whatever: ctrl+c then make clean.

Cleanup

To run the clean step in docker (useful for clearing caches and reseting defaults) run the following:

make clean

To clean the entire system (including node_modules and bundle_cache) run the following:

make clean_all

Work Inside the Containers

Finally, if you'd like to run commands inside the containers, e.g. to execute additional .yaml scripts manually, you can go into the bash of the docker container with the following commands:

Start up the docker containers and the system:

make run_all
docker ps

From the docker output find out the container ID for the blackstone_api container

docker exec -it <blackstone-api-container-ID> bash

Examples of commands that can be run inside the container

Run pending migrations

cd api
npm run db:migrate:up

You can also run the tests, e.g.

cd api
ps -ef | grep node
kill -9 <pid>
npm run test

Run a yaml script, e.g. a manual upgrade.

cd contracts/src
burrow deploy --chain-url=chain:10997 --mempool-signing --address <deployment-address> --file ../upgrades/NewServiceUpgrade-1.2.7.yaml
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.