This feature is only available in Canton Enterprise
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:
- a Canton Enterprise release for the example files and the Canton enterprise binary
- Canton Enterprise docker repository access, in order to have access to the docker images
Also make sure to have docker and docker-compose installed.
The demo can be found inside the examples directory of the Canton Enterprise release.
Unpack the Canton Enterprise release and then
Run the script
The script will start the following:
- A Fabric ledger with 2 peers and one orderer node.
- A Canton Sequencer node that interacts with the Fabric ledger.
- A Canton process running a single Canton domain and 2 participants. The configuration for this Canton process is in
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
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
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-setupthat 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-networkfrom 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).
To run Canton with a single Fabric Sequencer, run
If you just want to run the sequencer, without starting Canton, you can run the same command with the
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
To run Canton with 2 Fabric Sequencers in a multi-sequencer setup, run
If you just want to run the sequencers, without starting Canton, you can run the same command with the
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
If you wish to start the Hyperledger Fabric Blockchain Explorer, you can do so by running one of the
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
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
When you’re done running the sequencer, make sure to run
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:
<<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"
<<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"
-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.
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
Block Cutting Parameters and Performance¶
It is possible to configure the block cutting parameters of the ledger by changing the file at
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.