Canton 2.5.0

Canton 2.5.0 has been released on December 15, 2022. You can download the Daml Open Source edition from the Daml Connect Github Release Section. The Enterprise edition is available on Artifactory. Please also consult the full documentation of this release.

Summary

We are quite excited to share our recent improved Canton version, featuring a new protocol version supporting Daml interfaces, KMS support, improved operability and party migration.

Please note that older Canton networks can be upgraded to the new protocol version. Please follow the upgrading manual on how to upgrade binary and protocol version.

What’s New

New protocol version 4 and domain parameters improvements

The new protocol version 4 brings new features.

Impact and Migration

New deployments will use the protocol version 4 by default. Existing deployments can be upgraded to the new protocol version using the documented upgrading procedures.

Please read the migration guide carefully and follow the instructions therein before attempting to upgrade.

New dynamic domain parameters

The following domain parameters are now dynamic:

• Reconciliation interval
• Max inbound message size (renamed to max request size)
• Max rate per participant

These parameters can now be changed while the domain is running. See the documentation for more information. Also, the protocol version consists now of a single integer (or dev for the development version) rather than following semantic versioning scheme.

Migration

Specifying the value of a dynamic domain parameter in the static configuration is not allowed and doing so will cause the node to fail during config parsing. As a result, values for the three new dynamic domain parameters need to be removed from the static configuration and set via console commands, either interactively, or through a bootstrap script.

For example, suppose that the max rate per participant was set using the following config:

canton {
  domains {
    mydomain {
      domain-parameters {
        max-rate-per-participant = 10000
        reconciliation-interval = 30
        max-inbound-message-size = 10485700
      }
    }
  }

This config entry should be removed and the value can be set using the following console command:

mydomain.service.set_max_rate_per_participant(10000)
mydomain.service.set_reconciliation_interval(30.seconds)

mydomain.service.set_max_request_size(10485700)
// equivalently, one case use `mydomain.service.set_max_inbound_message_size(10485700)`

The other two parameters can bet set using similar console commands (set_reconciliation_interval and set_max_request_size). More examples can be found in the documentation.

Changing max request size (previously max inbound message size)

When increasing max request size, the sequencer nodes need to be restarted for the new value to be taken into account. If the domain is not distributed, restart can be done as follows

participants.all.domains.disconnect(mydomain.name)
nodes.local.stop()
nodes.local.start()
participants.all.domains.reconnect_all()

If the domain is distributed, then restart can be done as follows:

participants.all.domains.disconnect(sequencer1.name)
nodes.local.stop()
nodes.local.start()
participants.all.domains.reconnect_all()

Other changes around dynamic domain parameters

Compared to Canton 2.3.0, several changes impact how dynamic domain parameters are updated:

• Command update_dynamic_domain_parameters should be preferred over update_dynamic_parameters.
• The copy method on dynamic domain parameters was renamed to update
• Durations are specified using NonNegativeFiniteDuration rather than with TimeoutDuration. Implicit conversions allow to write these in a human-readable form.

Migration from 2.3.0 to 2.5.0

Updating dynamic domain parameters in Canton 2.3.0 was done as follows:

mydomain.service.update_dynamic_parameters(
  _.copy(
    participantResponseTimeout = TimeoutDuration.ofMinutes(3),
    ledgerTimeRecordTimeTolerance = TimeoutDuration.ofMinutes(1),
    mediatorReactionTimeout = TimeoutDuration.ofMinutes(1),
    transferExclusivityTimeout = TimeoutDuration.ofSeconds(2),
    topologyChangeDelay = TimeoutDuration.ofSeconds(1),
  )
)

With Canton 2.5.0, this needs to be rewritten as follows:

mydomain.service.update_dynamic_domain_parameters(
  _.update(
    participantResponseTimeout = 3.minutes,
    ledgerTimeRecordTimeTolerance = 1.minute,
    mediatorReactionTimeout = 1.minute,
    transferExclusivityTimeout = 2.seconds,
    topologyChangeDelay = 1.second,
  )
)

Daml Interfaces support

Daml Interfaces (see the documentation), that were marked as preview in Canton 2.4.0, are now officially supported.

Capture encryption schemes used in EncryptedViewMessage and avoid lifting in protocol messages

In protocol version 2 we did not specify which encryption scheme was used to symmetrically encrypt the view tree as well as the hybrid/asymmetric scheme that was used to encrypt the secure randomness for each participant. In addition, the fingerprint of the public key that was used to encrypt the secure randomness is now captured to avoid ambiguity and to define the used hybrid/asymmetric encryption scheme.

Optimization of messages between participants and domains

Starting with protocol version 4, the size of messages exchanged between participants and domains has decreased. More specifically, the subviews of transaction views are now stored in balanced binary Merkle trees, similarly to the way root views are stored. This provides a significant size reduction when many subviews are blinded, as complete subtrees can be reduced to single hashes.

Authenticated contract ids

Starting with protocol version 4, the Canton participant authenticates a transaction's input contracts as part of the phase 3 Transaction protocol processor. This is a necessary preparation in order to introduce a new and exciting feature that will allow using off-ledger shared contracts on the ledger.

KMS Support

The newly added support for key management services allows to encrypt the Canton keys with a securely stored envelope key. Please check the documentation for more information.

Domain Manager High Availability

The domain manager can now be deployed with an active / passive setup (similarly to the mediator) to achieve high-availability. See the documentation for more information.

Remote health dump

Health dumps can now be gathered through a remote console. See the documentation for more information.

Infrastructure transactions excluded from participant metering report

Infrastructure transactions are no longer metered by default and will not show up in the participant metering report. To override this there is a new participant node parameter config setting (canton.<participant>.parameters.exclude-infrastructure-transactions) that can be used to meter infrastructure transactions. For more information on participant metering see the Participant Metering documentation. Infrastructure transactions include:

• Ping transactions, used by the Ping health check
• Dar Distribution transactions

Console Command Changes

Party Migration

We have added a set of console macros to the Enterprise version that allow you to migrate a party together with its contracts from one participant node to another. See the documentation for more information.

Key Store Commands

BREAKING: The signature for console commands download and upload for crypto key pairs (keys.secret) and public keys (keys.public.). upload now expects as input a ByteString and not a reference to the object. download has been split in two different commands: (1) download expects a key fingerprint and returns the serialized public key or key pair (ByteString) and; (2) download_to also expects a filename and stores the ByteString directly into a file. Both methods have as optional input the protocol version to use for serialization (by default it's the latest protocol version supported by the release).

BREAKING: The return type of keys.secret.list has been renamed from PublicKeyWithName to PrivateKeyMetadata to return additional information related to the stored private keys, such as which wrapper key was used to encrypt the stored private key. The fields on the previous result type are the same as on the new result type for backwards compatibility.

Repair Commands

We have extended the set of repair commands available for recovering broken nodes. First, we added a new repair.download command that allows downloading an entire active contract set of a set of parties.

Second, two new repair commands repair.identity.download and repair.identity.upload allow for downloading and uploading the identity and keys of a node. They can be used to preserve a node's identity and keys when its storage is reset.

Configuration Changes

Moved all parameters from canton...storage.* to canton...storage.parameters.* This separates now the parameters canton is using to control the db layer from the genuine db layer parameters

Additionally, we've added canton.monitoring.deadlock-detection.warn-interval to control how often a warning should be repeated. The (undocumented) configuration variable num-reports has been removed.

We made socket timeouts for ethereum sequencers configurable (see canton.mySequencer.sequencer.config.web3jConfig.(read|write|connect)Timeout). Increase these parameters if you observe socket timeouts on the link between Canton and Ethereum.

Active health check configuration field was renamed from canton.monitoring.health.check.participant to canton.monitoring.health.check.node. This is a backwards compatible change.

Leeway parameters for JWT token-based authorization

The JWT token authorization checking now supports leeway parameters. This allows you to work around authentication failures due to clock-skew by defining a leeway window in which the tokens should still be considered valid.

See the documentation for more information.

All nodes

The following configuration variables have been migrated. Fallbacks are in-place, but we recommend to upgrade your configuration files and not rely on the fallbacks.

Deprecated value	New value
storage.max-connections	storage.parameters.max-connections
storage.ledger-api-jdbc-url	storage.parameters.ledger-api-jdbc-url
storage.fail-fast-on-startup	storage.parameters.fail-fast-on-startup
storage.connection-timeout	storage.parameters.connection-timeout

Minor Improvements

• The error category "MaliciousOrFaultyBehaviour" was renamed to "SecurityAlert". The integer code remained unchanged.
• The error category for INVALID_TOPOLOGY_TX_SIGNATURE_ERROR and UNAUTHORIZED_TOPOLOGY_TRANSACTION has changed to SecurityAlert.
• To support users for tuning resource limits, the metric dirty-requests has been added. The "number of dirty requests" is also logged periodically (at DEBUG level).
• An index was added to the database schema to improve pruning performance for large datasets.
• Participants produce ACS commitments when they receive commitments from their counterparticipants. This avoids that idle participants cause active participants to pile up outstanding commitments when they are shared active contracts.
• Better logging and supervision around Fabric sequencer operations that may get stuck.

Security and Bugfixes

• Fabric sequencer: when sending transaction to orderer, do not wait on all peers receiving transaction to complete send. This avoids getting stuck if some peers are down.
• Fixed a deadlock that may occur - with very low probability - if a command is rejected for the first time.
• Health server endpoint active check now supports all nodes

Compatibility

The following Canton protocol and Ethereum sequencer contract versions are supported:

Dependency	Version
Canton protocol versions	2, 3, 4
Ethereum contract versions	1.0.0, 1.0.1

Canton has been tested against the following versions of its dependencies:

Dependency	Version
Java Runtime	OpenJDK 64-Bit Server VM 18.9 (build 11.0.16+8, mixed mode, sharing)
Postgres	postgres (PostgreSQL) 14.6 (Debian 14.6-1.pgdg110+1)
Oracle	19.15.0
Besu	besu/v21.10.9/linux-x86_64/openjdk-java-11
Fabric	2.2.2

What's Coming

We are currently working on

• ongoing security hardening of the Canton protocol and application.
• HSM / KSM support.
• read-delegation / explicit disclosure.
• production ready support of multiple domains per participant.
• improving our documentation with many explicit operational procedures.