Important

This feature is only available in Canton Enterprise

Fabric Domain

The Canton-on-Fabric integration runs a Canton domain where events are sequenced using the Hyperledger Fabric ledger.

The Demo Deployment

To run the demo Canton Fabric deployment, you will need access to the following:

Also make sure to have docker and docker-compose installed.

Basic Demo

The demo can be found inside the examples directory of the Canton Enterprise release. Unpack the Canton Enterprise release and then cd into examples/e01-fabric-domain/canton-on-fabric.

Run the script ./run.sh single.

The script will start the following:

  1. A Fabric ledger with 2 peers and one orderer node.
  2. A Canton Sequencer node that interacts with the Fabric ledger.
  3. A Canton process running a single Canton domain and 2 participants. The configuration for this Canton process is in config/canton/demo.conf

Once the script has finished setting up (you should see the canton service print “Successfully initialized Canton-on-Fabric” together with the Canton console startup message), you will be able to interact with the two participants using the config at config/remote/demo.conf.

You can start an instance of the Canton console to connect to the two remote participants (provided you have also installed Canton):

<<canton-release>>/examples/e01-fabric-domain/canton-on-fabric$ ../../../bin/canton -c config/remote/demo.conf

You can then perform various commands in the Canton console:

@ remoteParticipant1.id
res1: ParticipantId = PAR::participant1::012c7af9...

@ remoteParticipant1.domains.list_connected
res2: Seq[(com.digitalasset.canton.DomainAlias, com.digitalasset.canton.DomainId)] = List((Domain 'myDomain', myDomain::01dafa04...))

@ remoteParticipant1.health.ping(remoteParticipant2)
res3: concurrent.duration.Duration = 946 milliseconds

Troubleshooting

Some Mac users may report docker issues during the chaincode installation steps, which has been linked to this issue and can be easily fixed by doing the following:

“Preferences…” -> “Experimental Features” -> Turn off “Use gRPC FUSE for file sharing”

Run the Example Deployment

The example files located at examples/e01-fabric-domain/canton-on-fabric provide you with more flexibility than to run the basic demo just shown. There you will find config files, docker-compose files and scripts to set up all of or a subset of the following:

  • a Fabric ledger with 2 organizations (with one peer each) and one orderer node
  • a Fabric block explorer UI
  • one Canton domain and 2 participants
  • 2 sequencers backed by the Fabric ledger

You will find in this directory our main script called run.sh. If you run the script, it will show you the help instructions with all the options that you can choose to run the deployment with.

The demo deployment will by default use the Canton version from the release. However, if you wish to use a different version, you can specify it with the CANTON_VERSION environment variable. For example, export CANTON_VERSION=0.19.0 to use Canton v0.19.0. You can choose dev for the latest main build of Canton.

Depending on which options you choose, it will run a docker-compose command using a different subset of the following docker-compose files below:

  • docker-compose-ledger.yaml: Sets up the Fabric ledger. You can see that there is a service in it called ledger-setup that is a service responsible for creating the crypto materials, setting up the channel and deploying the chaincode. It uses a customized and simplified version of the test-network from fabric-samples inside a docker container.
  • docker-compose-blockchain-explorer.yaml: Runs a blockchain explorer that allows visualizing the Fabric ledger on the browser.
  • docker-compose-sequencer-1.yaml: Runs a canton-enterprise node with a Fabric sequencer in it backed by a Postgres cache.
  • docker-compose-sequencer-2.yaml: Runs a second Fabric sequencer inside the same canton node. This shows that multiple sequencers operating on top of the same Fabric ledgers are supported.
  • docker-compose-canton.yaml: Runs a canton domain and 2 participants using the Fabric sequencer(s).

Single Sequencer

To run Canton with a single Fabric Sequencer, run ./run.sh single.

If you just want to run the sequencer, without starting Canton, you can run the same command with the -only-sequencer flag. Alternatively, you can run the following docker-compose command:

<<canton-release>>/examples/e01-fabric-domain/canton-on-fabric$ COMPOSE_PROJECT_NAME="fabric-sequencer-demo" docker-compose -f docker-compose-ledger.yaml -f docker-compose-sequencer-1.yaml up

The Fabric Sequencer will be available on localhost:3000.

Multiple Sequencers

To run Canton with 2 Fabric Sequencers in a multi-sequencer setup, run ./run.sh multiple. If you just want to run the sequencers, without starting Canton, you can run the same command with the -only-sequencer flag. Alternatively, you can run the following docker-compose command:

<<canton-release>>/examples/e01-fabric-domain/canton-on-fabric$ COMPOSE_PROJECT_NAME="fabric-sequencer-demo" docker-compose -f docker-compose-ledger.yaml -f docker-compose-sequencer-1.yaml -f docker-compose-sequencer-2.yaml up

This will start 2 sequencers, one on localhost:3000 and the second one on localhost:3001.

Blockchain Explorer

If you wish to start the Hyperledger Fabric Blockchain Explorer, you can do so by running one of the ./run.sh commands shown above but also adding the -e flag. Alternatively you can use one of the docker-compose commands and add -f docker-compose-blockchain-explorer.yaml flag to them. You will then be able to see the explorer web UI in your browser if you go to http://localhost:8080.

Alternatively, you can start the explorer separately after the ledger has been started by simply running the following command:

<<canton-release>>/examples/e01-fabric-domain/canton-on-fabric$ COMPOSE_PROJECT_NAME="fabric-sequencer-demo" docker-compose -f docker-compose-blockchain-explorer.yaml up

Note that even when the explorer is working perfectly, it might output some error messages like the following that can be safely ignored:

[ERROR] FabricGateway - Failed to get block 0 from channel undefined :  TypeError: Cannot read property 'toString' of undefined

Cleanup

When you’re done running the sequencer, make sure to run ./run.sh down.

Using the Canton Binary instead of docker

If you wish to run the domain and participants separately (with the canton binary or jar), you can do so as follows:

Single sequencer:

<<canton-release>>/examples/e01-fabric-domain/canton-on-fabric$ ./run.sh single -only-sequencer

<<canton-release>>/examples/e01-fabric-domain/canton-on-fabric$ ../../../bin/canton -c "config/canton/demo.conf" --bootstrap "config/canton/demo.canton"

Multiple sequencers:

<<canton-release>>/examples/e01-fabric-domain/canton-on-fabric$ ./run.sh multiple -only-sequencer

<<canton-release>>/examples/e01-fabric-domain/canton-on-fabric$ ../../../bin/canton -c "config/canton/demo.conf" --bootstrap "config/canton/demo.canton"

The -only-sequencer flag makes sure that the script does not start the domain and participants, allowing us to run it ourselves with the canton binary or the jar.

If you wish to run the jar file instead of the canton binary, simply replace ../../../bin/canton above with java -jar ../../../lib/canton-enterprise-*.jar.

Fabric Setup

The Fabric Sequencer operates on top of the Fabric Ledger and uses it as the source of truth for the state of the sequencer (all the messages and the order of them).

In order for The Fabric Sequencer to work, all it needs is access to a Fabric Ledger that has been setup with at least one channel where the Canton Sequencer chaincode has been installed.

In order to configure access to the ledger, please follow the notes and example show in examples/e01-fabric-domain/canton-on-fabric/config/fabric/fabric-config-1.conf. You’ll need to provide the necessary urls and files as described in the sample config.

Regarding the chaincode setup, the Fabric Sequencer expects that the chaincode is initialized by calling the function init (no arguments needed) and with the --isInit flag turned on. You can find the chaincode source at /ledger-setup/chaincode/src/github.com/digital-asset/sequencer.

Block Cutting Parameters and Performance

It is possible to configure the block cutting parameters of the ledger by changing the file at ledger-setup/configtx/configtx.yaml.

The relevant parameters are the following:

  • Orderer.BatchTimeout: The amount of time to wait before creating a block.
  • Orderer.BatchSize.MaxMessageCount: The maximum number of transactions to permit in a block (block size).

If your use case operates under high traffic, you may benefit from increasing the block size in order to increase your throughput at the expense of latency. If you care more about latency and don’t need to support high traffic, then decreasing block size will be of help.

Currently, we have set the values of 200ms for batch timeout and 50 for block size as it has empirically shown to be a good tradeoff after some rounds of long running tests, but feel free to pick parameters that fit your use-case best.

Note: See slide 17 of http://www.mscs.mu.edu/~mascots/Papers/blockchain.pdf for a discussion on block size influence on throughput and latency.