Important

This feature is only available in Canton Enterprise

Ethereum Domain

The Canton Enterprise Ethereum integration runs on an external Ethereum network. It is currently tested with Hyperledger Besu.

The Demo Deployment

To run the demo Canton Ethereum deployment, you will need access to a Canton Enterprise release, the Canton Enterprise docker repository , as well as having docker, docker-compose, and Hyperledger Besu (instructions here) installed.

Run the Demo Deployment

The demo Ethereum deployment can be found inside the examples directory of the Canton Enterprise release. Unpack the Canton Enterprise release and then cd into examples/e03-ethereum-sequencer.

The script ./ethereum-docker-compose/run.sh from the folder examples will create a new Besu testnet for the demo deployment and then start the demo. In particular, the script will start several dockerised services:

  • An ethereum testnet, using 4 Besu nodes with the IBFT consensus protocol.

  • An instance of Canton. This includes two Participants and a Canton Enterprise Domain with two Ethereum sequencers. The configuration for the canton instance is in ethereum-docker-compose/conf/config-example.conf.

The environment variable CANTON_VERSION is used to select the version of Canton to use for the demo deployment. This should normally be set to the version of the Canton Enterprise release being used, but can alternatively be set to a different version or dev for the latest master build of Canton.

Start the demo deployment as follows:

<<canton-release>>/examples/e03-ethereum-sequencer$ CANTON_VERSION=<your version> ./ethereum-docker-compose/run.sh

A new Besu testnet will be created and then the demo will begin running with the created testnet. Once the demo is initialized and running, you will be able to interact with the two participants via their ledger APIs, running on ports 5011 and 5021.

For example, you can start an instance of the Canton console to connect to the two remote participants. You can find the Canton binary in bin/canton of the Canton Enterprise release artifact.

<<canton-release>>/examples/e03-ethereum-sequencer$ ../../bin/canton -c ethereum-docker-compose/conf/remote.conf

You can then perform various commands in the Canton console:

@ remoteParticipant1.id
res5: ParticipantId = ParticipantId(
  UniqueIdentifier(Identifier("participant1"), Namespace(Fingerprint("01e69a39e2c821fc98eaeb22994b47084162122a01ebcb16dfb2514ccafcedd43d")))
)

@ remoteParticipant2.id
res6: ParticipantId = ParticipantId(
  UniqueIdentifier(Identifier("participant2"), Namespace(Fingerprint("014aeb29dddff83678bc6f1194c363c6f0d18d3a6c9655927a7fb5adc84ec0532c")))
)

@ remoteParticipant1.domains.list_connected
res7: Seq[(com.digitalasset.canton.DomainAlias, com.digitalasset.canton.DomainId)] = List(
  (Domain 'mydomain', mydomain::01537eb8...)
)

@ remoteParticipant1.health.ping(remoteParticipant2)
res8: concurrent.duration.Duration = 968 milliseconds

Generating a Clean Testnet

The directory examples/e03-ethereum-sequencer/ibft-testnet contains the script generate-testnet.sh. This automatically generates a clean Besu network, including creating new randomised private keys. This is automatically called by run.sh but you may want to understand and edit this script to create your own custom Besu deployment.

When generate-testnet.sh is run:

  • A genesis file and a set of keys for four Besu nodes are automatically generated. These can be found in the folder generated.

  • The four Besu nodes are started.

  • The state from any previous runs of generate-testnet.sh is deleted.

The generated testnet includes an instance of Canton’s Ethereum Sequencer contract pre-deployed from genesis. This contract has the address 0x0ffd23af8eebc60b3cfdeed6f814988757237314 and is defined by the binary file sequencer-binary.

The generated Besu testnet has been configured largely following these tutorials:

The parameters of the generated testnet can be changed by modifying the genesis.json file defined inline in generate-testnet.sh.

Customization of the Demo Configuration

You can also modify the Canton configuration and bootstrap script for the demo. The Canton configuration is found in ethereum-docker-compose/conf/config-demo.conf and the bootstrap script is ethereum-docker-compose/demo.canton. Note that if you change port mappings in the Canton config file then you may also need to update ethereum-docker-compose/docker-compose.yaml.

Requirements for the Ethereum Network

The Canton Ethereum integration is currently tested with a Hyperledger Besu free gas network, running with the IBFT 2.0 consensus protocol. However, the integration only interfaces with the Ethereum Node via web3j so most popular Ethereum clients (eg Geth and Parity) should be supported. There are, however, some requirements for the Ethereum Network irrespective of the Ethereum Node you choose to use:

  • Blocks must be mined frequently. It is recommended to mine at least once block every second. More frequent mining will improve performance.

  • Currently, a free gas network is required. This means setting the gas price to zero.

  • The block size limit (often measured in gas, and sometimes referred to as the ‘gas limit’) must be larger than any message to be sequenced. It is recommended to set this parameter as high as possible.

  • The contract size limit must be big enough for the Canton Ethereum Domain to store all required state for sequencing messages. It is recommended to set this parameter as high as possible.

  • Proof of authority protocols are recommended over proof of work.

  • Currently, consensus protocols must have immediate finality. This means that ledger forks should not occur with the chosen consensus protocol.

Trust Properties of the Ethereum Sequencer Integration

The demo integration uses two participants and two different Ethereum Sequencer nodes. Each participant chooses its preferred Ethereum Sequencer node, and this node performs reads and writes on behalf of the participant. Therefore, each participant must trust its chosen Ethereum Sequencer node. Additionally, each participant must trust some proportion of the nodes in the Ethereum network as determined by the consensus protocol.