Static Configuration

Canton differentiates between static and dynamic configuration. Static configuration is immutable and therefore has to be known from the beginning of the process start. An example for a static configuration are the connectivity parameters to the local persistence store or the port the admin-apis should bind to. On the other hand, connecting to a domain or adding parties however is not a static configuration and therefore is not set via the config file but through the adminstration APIs or the console.

initialization of Canton nodes.

The configuration files themselves are written in HOCON format.

Canton does not run one node, but any number of nodes, be it domain or participant nodes in the same process. Therefore, the root configuration allows to define several instances of committer and participant nodes together with a set of general process parameters.

A sample configuration file for two participant nodes and a single domain can be seen below.

canton {

  participants {

    participant1 {
      storage {
        type = memory
      }

      admin-api {
        port= 5012
      }

      ledger-api {
        port = 5011
      }
    }

    participant2 {
      storage {
        type = memory
      }

      admin-api {
        port= 5022
      }

      ledger-api {
        port = 5021
      }
    }
  }

  domains {
   mydomain {
      storage {
        type = memory
      }

      server {
        public.port = 5018
        admin.port = 5019
      }
    }
  }

}

Mixing Configuration Files

Configuration files can be nested and combined together. First, using the include directive (with relative paths), a configuration file can include other configuration files.

canton {
    domains {
        include "domain1.conf"
    }
}

Second, by providing several configuration files, we can override configuration settings using explicit configuration option paths:

canton.participants.myparticipant.admin-api.port = 11234

Those defined first will have precedence if the same key is included in multiple configurations.

Monitoring

The canton process can optionally expose an HTTP endpoint indicating if the process believes it is healthy. This is intended for use in uptime checks and liveness probes. If enabled, the /health endpoint will respond to a GET http request with a 200 HTTP status code if healthy or 500 if unhealthy (with a plain text description of why it is unhealthy).

To enable this health endpoint add a monitoring section to the canton configuration. As this health check is for the whole process, it is added directly to the canton configuration rather than for a specific node.

canton {
  monitoring.health {
   server {
      port = 7000
   }

   check {
     type = ping
     participant = participant1
     interval = 30s
   }
}

This health check will have participant1 “ledger ping” itself every 30 seconds. The process will be considered healthy if the ping is successful.

Cryptography

All crypto-graphic routines used in Canton are represented through an abstract API for asymmetric and symmetric cryptographic operations. Currently, there are two implementations available, a convenient one for development and testing and one for serious and secure use.

Tink

The real cryptographic module is based on Tink and can be activated using

canton.domains.<mydomain>.crypto.type = tink
canton.domains.<myparticipant>.crypto.type = tink

Symbolic

The symbolic cryptography module will not encrypt anything but just wrap the content in a clear-text container together with the information of what was encrypted by whom.

canton.domains.<mydomain>.crypto.type = symbolic

Reference

Canton configuration file for static properties is based on Pureconfig. Pureconfig maps Scala case classes into appropriate configuration options. Therefore, the ultimate source of truth for all available configuration options is given by the appropriate scaladocs of the CantonConfig classes.

In order to map the Scala names into the HOCON format, we need to map the names from CamelCase to lowercase_with_underscores, i.e. domainParameters becomes domain-parameters (dash, not underscore).