Brokerage Engine - aegisbigdata/documentation GitHub Wiki

The blockchain for the Brokerage Engine of AEGIS was developed using Hyperledger Fabric v1.0 and Hyperledger Composer. The network consists of an Orderer, a CA authority, a peer and a CouchDB database for queries. Additional organizations, peers and orderers will be added in future versions.

Installation

Detailed installation steps can be found at the AEGIS Network Repository.

Usage

Along with the network, a REST API server is installed, allowing to interact with it. The following endpoints are available:

User Management

  1. Create new user - Creates a user with user id (uid in the code snippet below) [email protected] , having an initial balance of 1000 tokens:

     curl -XPOST https://localhost:3000/api/User -H 'Accept: application/json' -d '{ "$class": "eu.aegis.User", "uid": "[email protected]", "balance": "1000.0" }'

  2. Get all users

     curl -XGET https://localhost:3000/api/User

  3. Get specific userʼs details - To get a specific userʼs information, add the uid at the end of the url. i.e.:

     curl -XGET https://localhost:3000/api/User/[email protected]

  4. Load tokens to a userʼs account - To load 200 tokens to (user with uid) [email protected] :

     curl -XGET https://localhost:3000/api/LoadBalance -H 'Accept: application/json' -d '{ "user": "resource:eu.aegis.User#[email protected]", "amount": 200 }'

Asset Management

  1. Create a new asset To create an asset, you need to provide an asset id (aid below), its type (can be any of: Dataset , Microservice , Algorithm , Analysis , Visualization , Other ), the cost of the asset, its status (can be Free , Paid , Subscription or Private - i.e. not for sale) and its owner (the uid of the user that owns the dataset).

     curl -XPOST https://localhost:3000/api/AEGISAsset -H 'Accept: application/json' -d '{ "$class": "eu.aegis.AEGISAsset", "aid": "1", "assetType": "Dataset", "cost": 100, "status": "Paid", "owner": "[email protected]" }'

  2. Get all assets

     curl -XGET https://localhost:3000/api/AEGISAsset

  3. Get details on a specific asset - As with user, we use the aid as a parameter

     curl -XGET https://localhost:3000/api/AEGISAsset/1

  4. Change the status of an asset - To change the status of asset with aid=1 to Private , use:

     curl -XPOST https://localhost:3000/api/ChangeAssetStatus -H 'Accept: application/json' -d '{

"relatedAsset": "eu.aegis.AEGISAsset#1", "newStatus": "Private" }'

  1. Change the cost of an asset - To change the status of asset with aid=1 to Private , use:

     curl -XPOST https://localhost:3000/api/ChangeAssetCost -H 'Accept: application/json' d '{"relatedAsset": "eu.aegis.AEGISAsset#1", "newCost": "200" }'

Building Contracts

  1. Create a new (draft) contract - To create a contract, you need to provide a transaction id (tid), the desired exclusivity (can be None , Subscription or Lifetime ), the amount (to be) paid, the status of the contract (always use Draft at this stage), a text containing the terms of the contract (optional), the buyer and the seller (using their uid s) and the asset to be sold (use its aid ).

     curl -XPOST https://localhost:3000/api/Contract -H 'Accept: application/json' -d '{ "$class": "eu.aegis.Contract", "tid": "123", "exclusivity": "None", "amountPaid": "100.0", "status": "Draft", "text": "string", "seller": "[email protected]", "buyer": "[email protected]", "relatedAsset": "eu.aegis.AEGISAsset#1" }'

  2. Get all contracts

     curl -XGET https://localhost:3000/api/Contract

  3. Get all contracts involving assets bought/sold by someone - To get all contracts with a specific buyer/seller we need to filter the contracts. This is done by appending a (url encoded) filter in the url. For example, to get all contracts involving [email protected] as a buyer, the filter should be:

{"where": {"buyer": {"eq":"resource:eu.aegis.User#[email protected]"}}}

As a seller:

{"where": {"seller": {"eq":"resource:eu.aegis.User#[email protected]"}}}

    curl -XGET https://localhost:3000/api/Contract?filter={...}

The url encoded example of contracts with assets bought by [email protected] is

    curl -XGET https://localhost:3000/api/Contract?filter=%7B%22where%22%3A%20%7B%22buyer%22%3A%20%7B%22eq%22%3A%22resource%3Aeu.aegis.User%23john.doe%40example.com%22%7D%7D%7D

  1. Validate a contract - To validate (switch it from Draft it Active):

     curl -XPOST https://localhost:3000/api/ValidateContract -H 'Accept: application/json' -d '{ "contract": "eu.aegis.Contract#123" }'

where 123 is the tid (as set in the draft contract creation).