No Batteries Required

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 and 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:

$ bin/build_all -D -b

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 entities

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

In order to demonstrate the exchange-tp it is necessary to leverage the hashblock-exchange asset and unit transaction families which are responsible for the proposal of and voting acceptance of new types on the chain. In addition to the genesis block creation, where we pre-populate unit and asset entities, there is a sample file to seed a few more of each onto the chain. Open a new terminal window on your machine and shell into the hashblock-admin container to run the batch loader:

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

5. Confirm batch 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/assets' endpoint and expand by clicking on it
3. Click the 'Try it out!' button

This may take a few seconds for the listing to be produced.

Confirm the units-of-measure have been loaded by using the 'GET /hashblock/units' endpoint as well. 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 bag of peanuts?". (Where 5 is a quantity value, bag is a unit-of-measure and peanuts are the assets respectively).

To which Turing responds by telling Church: "That will be 10 $ USD!" 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/utxq-create' endpoint
2. In the 'payload' text entry control paste in the following:

{
  "operation": "demo.ask",
  "plus": "church",
  "minus": "turing",
  "quantity": {
    "value": "5",
    "unit": {
      "key": "bag",
      "system": "purchasing"
    },
    "asset": {
      "key": "peanuts",
      "system": "food"
    }
  }
}

3. Click the 'Try it out!' button
4. Then verify the transaction was successful by clicking on the 'GET /hashblock/utxqs' endpoint. For the agreement name type in standard.
5. Copy the long hex address portion 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/mtxq-create' endpoint
2. Paste the following into the payload window:

{
  "operation": "demo.tell",
  "plus": "turing",
  "minus": "church",
  "quantity": {
    "value": "10",
    "unit": {
      "system": "currency",
      "key": "$"
    },
    "asset": {
      "system": "iso4217",
      "key": "USD"
    }
  },
  "utxq_address": "957682cc7a07c026596ee64308dd45761c38fe190484a8703b10950fa881e873eed2ac",
  "ratio": {
    "numerator": {
      "value": "2",
      "unit": {
        "system": "currency",
        "key": "$"
      },
      "asset": {
        "system": "iso4217",
        "key": "USD"
      }
    },
    "denominator": {
      "value": "1",
      "unit": {
        "system": "purchasing",
        "key": "bag"
      },
      "asset": {
        "system": "food",
        "key": "peanuts"
      }
    }
  }
}

4. Overwrite the "utxq_address" value with the address you copied from step #5 in the asks results on your system
5. Click the 'Try it out!' button

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

Enjoy!