This is a distributed application to help you trace the provenance and other contextual information of any asset. It can be used as-is or customized for different use cases. This distributed application runs on top of Hyperledger Sawtooth, an enterprise blockchain. To learn more about Hyperledger Sawtooth please see its sawtooth-core repo or its published docs.
Running alongside the core components from Hyperledger Sawtooth, BBR Chain includes a number of elements customizing the blockchain and user interaction with it:
- a transaction processor which handles BBR Chain transaction logic
- a server which provides an HTTP/JSON API for BBR Chain actions
- a ledger sync which syncs blockchain data to a local database
- the AssetTrack example client for tracking generic assets
- a shell container with the dependencies to run any commands and scripts
This project utilizes Docker to simplify
dependencies and deployment. After cloning this repo, follow the instructions
specific to your OS to install and run whatever components are required to use
docker and docker-compose from your command line. This is only dependency
required to run BBR Chain components.
Once Docker is installed and you've cloned this repo, navigate to the root project directory and run:
docker-compose upThis will take awhile the first time it runs, but when complete will be running all required components in separate containers. Many of the components will be available through HTTP endpoints, including:
- The BBR Chain REST API will be at http://localhost:8020
- AssetTrack will be at http://localhost:8021
- RethinkDB's admin panel will be available at http://localhost:8023
- Sawtooth's blockchain REST API will be available at http://localhost:8024
In bash you can shutdown these components with the key combination: ctrl-C.
You can shutdown and remove the containers (destroying their data), with the
command:
docker-compose downRunning docker-compose up, will automatically run all scripts necessary to
use all BBR Chain components. However if you want to run any additional
scripts, such as scripts to automatically update sample blockchain data, a shell
container is provided with all necessary dependencies installed. To enter the
shell, simply open a terminal window and run:
docker exec -it bbr-shell bashOnce inside the shell, you might try running the one of the update scripts to see live updates populate in an example web app. First navigate to the server directory:
cd server/Then run one of the two provided npm scripts:
npm run update-sample-assetsYou can customize how many updates are submitted per minute with the RATE
environment variable (default 6), and use LIMIT to stop the updates after a
certain number are submitted (default 25):
RATE=3 LIMIT=10 npm run update-sample-assetsIf you just want to exit the shell, you can simply run:
exitWhile the Server runs out of the box with sensible defaults, there are a number of secrets and API keys which will not be secure unless set explicitly. While this is fine for demo purposes, any actual deployment set the following properties:
- JWT_SECRET: can be any random string
- PRIVATE_KEY: must be 64 random hexadecimal characters
- MAPS_API_KEY: provided by Google Maps
These properties can be set one of two ways, through an environment variable,
or (preferably) by creating a file named config.json file in the server/
directory. A file named config.json.example is provided which should provide
a template to follow.
The default Docker containers use the volumes command to link directly to the
source code on your host machine. As a result any changes you make will
immediately be reflected in BBR Chain components without having to rebuild
them. However, typically you will have to restart a component before it can
take advantage of any changes. Rather than restarting every container, you can
restart a single component from separate terminal using the container name. For
example:
docker restart bbr-serverThe available container names include:
- bbr-shell
- bbr-processor
- bbr-server
- bbr-asset-client
- bbr-rethink
- bbr-validator
- bbr-settings-tp
- bbr-rest-api
The example clients are based on static files generated by build scripts. Any
time changes are made to their source code they will need to be rebuilt. This
is done automatically on up, but if you make changes to these files and wish
to rebuild the generated files immediately, you can do so from within the
BBR Chain Shell:
docker exec -it bbr-shell bashOnce in the shell, you can generate the necessary JS files by navigating to a client's directory and running its build script:
cd asset_client/
npm run buildUnlike other components, the clients do not typically need to be restarted in order to reflect changes, just rebuild the static files and refresh your browser (the browser cache may have to be emptied).
Files in the protos/ directory are used to generate classes for all of the
other components. If any changes are made in this directory, these classes will
need to be rebuilt for all components. While this can be done manually, the
necessary commands are included in docker-compose.yaml, so simply stop all
containers with ctrl-C and then docker-compose up again.
The latest documentation for Sawtooth BBR Chain is available within this repo in the docs subdirectory.
This software is licensed under the Apache License Version 2.0 software license.
Sawtooth BBR Chain documentation in the docs subdirectory is licensed under a Creative Commons Attribution 4.0 International License. You may obtain a copy of the license at: http://creativecommons.org/licenses/by/4.0/.
Original fork: hyperledger/sawtooth-supply-chain