Skip to content

No Batteries Required

Jump to bottom
Frank V. Castellucci edited this page Jun 18, 2018 · 24 revisions

The hashblock-exchange repo is equiped with batteries for a quick start and demonstration of value.

Note: If you are a Windows user, see Windows Docker Users

1. Download the hashblock-exchange Github repository:

$ git clone https://github.com/hashblock/hashblock-exchange.git

2. Build the hashblock-exchange system

Build the hashblock administrative, REST and hashblock TP family docker images. The build will also generates the necessary python protobuf files. We then generate the sawtooth genesis.block for hashblock setup. To begin, change to the root of the hashblock-exchange repo root directory on your machine and enter the following commands:

$ bin/build_all
$ bin/blockgen

3. Starting hashblock-exchange

While still in the hashblock-exchange root folder:

$ docker-compose -f docker/compose/hashblock-local.yaml up

The first execution may take a bit to start up due to the download of the hyperledger/sawtooth services from DockerHub. Subsequent executions should not take as long.

4. Seed hashblock assets

The hashblock-exchange match transaction family (match-tp) uses Unmatched Transaction Quantity (UTXQ) and Matched Transaction Quantity (MTXQ) transactions to record the dual initiating and reciprocating events that comprise an asset exchange.

In order to demonstrate the match-tp it is necessary to leverage the hashblock-exchange asset transaction family (asset-tp), which is responsible for the proposal of and voting acceptance of new asset types (units-of-measure and resources) on the chain. There is a sample file to seed a few assets onto the chain. Open a new terminal window on your machine and shell into the hashblock-admin container to run the asset batch loader:

$ docker exec -it hashblock-admin bash
root@c03622398ff5:/path# hbadm batch asset --file /project/hashblock-exchange/sampledata/asset_batch.json

5. Confirm assets load

hashblock-exchange includes a RESTful application called hashblock-rest (ingenious, right?) supporting the viewing of existing assets and exchanges. From your browser window, load the generic hashblock-rest UI by entering either localhost:8000, http://localhost:8000 or http://127.0.0.1:8000and:

  1. Click on the 'List Operations' option on the right side of the screen. This will expand all the entry points to hashblock-rest
  2. Find the 'GET /hashblock/resources' endpoint and expand by clicking on it
  3. Click the 'Try it out!' button

You should see something similar to this:

{
  "dimension": "resource",
  "family": "asset",
  "data": [
    {
      "link": "http://localhost:8000/hashblock/resource/95768292a8fd5bb58965ec1c84240392786f6c8903c835db341bf83ef9c99ef8166486",
      "name": "USD",
      "system": "currency",
      "value": "7"
    },
    {
      "link": "http://localhost:8000/hashblock/resource/95768292a8fd5bb589c235540af534e2566045444a5cf702da28a024de63e9e484cbb3",
      "name": "peanuts",
      "system": "food",
      "value": "3"
    },
    {
      "link": "http://localhost:8000/hashblock/resource/95768292a8fd5bb589c235546700f676551a0094ce8741fc30495c12d06cd25873ad28",
      "name": "hay",
      "system": "food",
      "value": "13"
    }
  ]
}

Confirm the units-of-measure assets have been loaded by using the 'GET /hashblock/units' endpoint. You should see results that resemble:

{
  "dimension": "unit",
  "family": "asset",
  "data": [
    {
      "link": "http://localhost:8000/hashblock/unit/95768292a8fd95638293ece52b2922cf0b61dec428945a2c082d8a541c8430c6c83e79",
      "name": "bale",
      "system": "purchasing",
      "value": "11"
    },
    {
      "link": "http://localhost:8000/hashblock/unit/95768292a8fd95638293ece57f71442842b94b05eb073f6262fbbe99719872add283e5",
      "name": "bag",
      "system": "purchasing",
      "value": "2"
    },
    {
      "link": "http://localhost:8000/hashblock/unit/95768292a8fd95638293ece5840cfc6285878464c36c9aa819d8373729eda14c3e701f",
      "name": "$",
      "system": "imperial",
      "value": "5"
    },
    {
      "link": "http://localhost:8000/hashblock/unit/95768292a8fd95638293ece5a6c9aeaa1994d59a6cbd6c1447b91c74da5a9d1f969939",
      "name": "unity",
      "system": "imperial",
      "value": "1"
    }
  ]
}

For more information regarding assets see Assets

6. Create an exchange

As noted, the core value proposition of hashblock-exchange is recording of the initiating and reciprocating events (UTXQ and MTXQ duality) that comprise a value exchange. To exemplify this, we will use the 'ask'/'tell' duality.

An example would be:

Church asks Turing: "How much for 5 bags of peanuts?". (Where 5 is a quantity value, bags is a unit-of-measure and peanuts are the resource assets respectively).

To which Turing responds by telling Church: "That will be 10 $ USD!" and which is based on the ratio of "2 $ USD for 1 bags of peanuts".

Going back to the browser window:

  1. Click on the 'POST /hashblock/ask' endpoint
  2. In the 'payload' text entry control paste in the following:
{
  "plus": "church",
  "minus": "turing",
  "quantity": {
    "value": "5",
    "unit": {
      "key": "bag",
      "system": "purchasing"
    },
    "resource": {
      "key": "peanuts",
      "system": "food"
    }
  }
}
  1. Click the 'Try it out!' button
  2. Then verify the transaction was successful by clicking on the 'GET /hashblock/asks' endpoint. You should see results similar to:
{
  "data": [
    {
      "plus": "church",
      "text": "5 bag of peanuts",
      "link": "http://localhost:8000/hashblock/ask/957682cc7a07c026596ee64308dd45761c38fe190484a8703b10950fa881e873eed2ac",
      "minus": "turing"
    }
  ],
  "dimension": "utxq",
  "family": "match",
  "operation": "ask"
}
  1. Copy the long hex address portion from the 'link' key as you will need it for Turing's response

In the system, what we've created is considered an unmatched transaction or UTXQ. Let's remedy that.

  1. Click on the 'POST /hashblock/tell' endpoint
  2. Paste the following into the payload window:
{
  "plus": "turing",
  "minus": "church",
  "quantity": {
    "value": "10",
    "unit": {
      "system": "imperial",
      "key": "$"
    },
    "resource": {
      "system": "currency",
      "key": "USD"
    }
  },
  "utxq_address": "957682cc7a07c026596ee64308dd45761c38fe190484a8703b10950fa881e873eed2ac",
  "ratio": {
    "numerator": {
      "value": "2",
      "unit": {
        "system": "imperial",
        "key": "$"
      },
      "resource": {
        "system": "currency",
        "key": "USD"
      }
    },
    "denominator": {
      "value": "1",
      "unit": {
        "system": "purchasing",
        "key": "bag"
      },
      "resource": {
        "system": "food",
        "key": "peanuts"
      }
    }
  }
}
  1. Overwrite the "utxq_address" value with the address you copied from step #5 in the asks results on your system
  2. Click the 'Try it out!' button
  3. Verify the transaction was successful by clicking on the 'GET /hashblock/tells' endpoint. You should see resuts similar to:
{
  "data": [
    {
      "plus": "turing",
      "text": "10 $ of USD for 5 bag of peanuts",
      "link": "http://localhost:8000/hashblock/tell/957682cc7a0702d3e289251608dd45761c38fe190484a8703b10950fa881e873eed2ac",
      "minus": "church"
    }
  ],
  "dimension": "mtxq",
  "family": "match",
  "operation": "tell"
}

To explore the deeper aspects of the topics demonstrated, visit the Theory of Operations page.

Enjoy!

Clone this wiki locally