DAML on Fabric
Ledger implementation enabling DAML applications to run on Hyperledger Fabric 2.x
Quick Start Guide
Prerequisites
These are the minimal requirements that this flow was tested with. Docker and Docker-Compose are required to run a Hyperledger Fabric network, and greater versions of docker generally can be used. Note: running Docker as root is not recommended.
- docker-compose version 1.24.0 or greater
- docker CE version 18.09.6 or greater
- Java / JDK version 1.8.0.x
- DAML SDK version 1.7.0
- Hyperledger Fabric Tools version 2.0.0 or greater
You can get the latest Hyperledger Fabric Tools by running the following command, and binaries will be downloaded to <download_directory>/bin
cd <download_directory>
curl -sSL https://raw.githubusercontent.com/hyperledger/fabric/master/scripts/bootstrap.sh | bash -s -- 2.1.0 -s
Now add the <download_directory>/bin to your PATH so that the fabric tools are available for use
export PATH=<download_directory>/bin:$PATH
Full instructions on Fabric Tools can be found at https://hyperledger-fabric.readthedocs.io/en/release-2.0/install.html
Cloning DAML-on-Fabric
For the sake of cleanliness, we are using the directory ~/daml-on-fabric
as the root for the repository.
cd
git clone https://github.com/digital-asset/daml-on-fabric.git
Running a local Hyperledger Fabric network
This is achieved by running a Docker-Compose network which is a typical way to set up Fabric for development environments. Our particular example sets up a network of 2 endorsing peers.
cd ~/daml-on-fabric/src/test/fixture/
./gen.sh
./restart_fabric.sh
The script used is a shortcut for ./fabric.sh down && ./fabric.sh up
that will erase all current data and start a fresh network.
Deploying a DAML Application to Fabric
Check out the deployment guide for a demonstration on deploying a full E2E application.
DAML-on-Fabric command line and Services
The basic command to run the ledger right from the repository is like this:
sbt "run --role <roles> [--port NNNN] [DAMLArchive.dar DAMLArchive2.dar ...]"
Important: the ledger will connect to a Fabric network specified in config-local.yaml file.
If you want to run the ledger against something other than the local Fabric test network, you should specify the configuration of the network by providing the additional fabricConfigFile
argument, as shown below:
sbt "run ..." -J-DfabricConfigFile=<configuration file>
By default, it will use "config-local.yaml", which you can use for reference.
Services, or "Roles"
You may have noticed that the required argument for DAML-on-Fabric is "role".
There are several roles that define which parts of the service are going to be executed:
provision
- will connect to Fabric and prepare it to be used as storage for a DAML ledger.
ledger
- will run a DAML Ledger API endpoint at a port specified with
--port
argument.
- will run a DAML Ledger API endpoint at a port specified with
time
- will run a DAML time service, which writes heartbeats to the ledger. There should be exactly one time service per ledger.
explorer
- will run a block explorer service that exposes a REST API to view the content of blocks and transactions inside the Fabric network for debugging or demonstration purposes. The explorer will run at a port specified in config-local.yaml file. It provides REST API that responds at endpoints
/blocks[?id=...]
and/transactions[?id=...]
- will run a block explorer service that exposes a REST API to view the content of blocks and transactions inside the Fabric network for debugging or demonstration purposes. The explorer will run at a port specified in config-local.yaml file. It provides REST API that responds at endpoints
One ledger may perform multiple roles at the same time, in which case roles are comma-separated.
Running Java Quick Start against DAML-on-Fabric
Step 1. Start Hyperledger Fabric
cd ~/daml-on-fabric/src/test/fixture/
./gen.sh
./restart_fabric.sh
Step 2. Extract and build Quick Start project
cd
daml new quickstart quickstart-java
Created a new project in "quickstart" based on the template "quickstart-java".
cd quickstart
daml build
Compiling daml/Main.daml to a DAR Created .daml/dist/quickstart-0.0.1.dar
Step 3. Run the Ledger with Quick Start DAR archive
cd ~/daml-on-fabric/
sbt "run --port 6865 --role provision,time,ledger,explorer ../quickstart/.daml/dist/quickstart-0.0.1.dar"
Step 4. Allocate parties on the ledger
There's no automatic mapping of DAML parties to parties on the Fabric ledger. We'll need to create the parties on Fabric that match the party names in DAML:
cd ~/quickstart/
daml ledger allocate-parties --host localhost --port 6865 Alice Bob Carol USD_Bank EUR_Bank
Step 5. Run DAML Navigator
cd ~/quickstart/
daml navigator server localhost 6865 --port 4000
Step 6. Conclusion
Now you can explore your freshly setup DAML ledger.
You should have the following services running:
- DAML Navigator at http://localhost:4000/
- Hyperledger Fabric block explorer at http://localhost:8080/blocks and http://localhost:8080/transactions
- DAML Ledger API endpoint at localhost:6865
- Fabric Orderer and Peers running at ports as defined in docker compose file
More information on Quick Start example and DAML in general can be found here:
https://docs.daml.com/getting-started/quickstart.html
Step 7. Upload own dar files
To upload custom dars run the following command where the custom dar is located:
daml ledger upload-dar <dar-file-location> --host localhost --port 6865
Step 8. Run Ledger API Test Tool
For testing purposes, the Ledger API provides a tool to execute some tests against the deployed network. You can find the ledger-api-test-tool.jar in the src/test/fixture folder. This JAR is generated when the make it command
cd ~/daml-on-fabric/src/test/fixture
./download_test_tool_extract_dars.sh
ls *.dar | xargs -I {} daml ledger upload-dar {} --host localhost --port 6865
java -jar ledger-api-test-tool.jar --all-tests localhost:6865 --timeout-scale-factor=10
NOTE: The localhost and port can be changed to accommodate the projects needs
Step 9. Run with authentication
We can also run the Ledger API with authentication enabled. The ledger API uses JWT for authentication. There are a few methods that are supported: * rsa256 * esda256 * esda512 * hs256 (this is unsafe) * rsa256 jwks
To enable authentication, follow one of the examples below.
To run with rsa256 jwt authentication enabled:
sbt "run --port 6865 --role provision,time,ledger,explorer ./quickstart/.daml/dist/quickstart-0.0.1.dar --auth-jwt-rs256-crt=<path-to-crt-file>"
To run with esda256 jwt authentication enabled:
sbt "run --port 6865 --role provision,time,ledger,explorer ./quickstart/.daml/dist/quickstart-0.0.1.dar --auth-jwt-es256-crt=<path-to-crt-file>"
To run with esda512 jwt authentication enabled:
sbt "run --port 6865 --role provision,time,ledger,explorer ./quickstart/.daml/dist/quickstart-0.0.1.dar --auth-jwt-es512-crt=<path-to-crt-file>
To run with hs256 jwt authentication enabled:
sbt "run --port 6865 --role provision,time,ledger,explorer ./quickstart/.daml/dist/quickstart-0.0.1.dar --auth-jwt-hs256-unsafe=<path-to-crt-file>"
To run with rsa256 jwks jwt authentication enabled:
sbt "run --port 6865 --role provision,time,ledger,explorer ./quickstart/.daml/dist/quickstart-0.0.1.dar --auth-jwt-rs256-jwkse=<URI-to-jwks-service>"
If authentication is enabled, then all the calls to the Ledger API will need to be authenticated. Given the the authentication, please use the following:
To run daml commands for Legder API with any jwt authentication enabled
daml ledger allocate-parties --host localhost --port 6865 Alice Bob Carol USD_Bank EUR_Bank --access-token-file=<path-to-token>
A few examples for this type of authentication can be found in src/test/fixture/data/ledger_certs and src/test/fixture/data/ledger_tokens
For more information, regarding authentication on the Ledger API and token generation, can be found here and here , respectively.
Step 10. Running with CI
This project has its own CI environment that builds, spins up the network, and runs the ledger tests and the authentication tests. To replicate the same steps as are run in CI locally, you can run this command:
$ make it
This will clean, compile, build and package the code, deploy the network and run all the necessary tests.
Step 11. Running a Multi-node Setup
Start Fabric Network
cd src/test/fixture && ./restart_fabric.sh
Output DAR from test tool
cd src/test/fixture && ./download_test_tool_extract_dars.sh
First Participant Node
sbt "run --role ledger,time,provision --port 11111" -J-DfabricConfigFile=config-local.yaml
Second Participant Node
sbt "run --role ledger --port 12222" -J-DfabricConfigFile=config-local.yaml
Third Participant Node
sbt "run --role ledger --port 13333 src/test/fixture/SemanticTests.dar src/test/fixture/Test-stable.dar" -J-DfabricConfigFile=config-local.yaml
Run Ledger Test Tool against all nodes
java -jar ledger-api-test-tool.jar localhost:11111 --include=SemanticTests --timeout-scale-factor 2.0
java -jar ledger-api-test-tool.jar localhost:12222 --include=SemanticTests --timeout-scale-factor 2.0
java -jar ledger-api-test-tool.jar localhost:13333 --include=SemanticTests --timeout-scale-factor 2.0
Technical README
If there is a need for further customization, there are a few options that can be changed. Please refer to this README for further information.
Architecture Guide
A more detailed description of the technical architecture can be found in Architecture Guide