Canton 2.4.0

Canton 2.4.0 has been released on September 28, 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 excited to share our new 2.4 release with you. We have increased the reliability, correctness and experience of the system, and added some very early access features.

What’s New

Remote health dump

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

Participant Latency Improvements

We have improved the latency of the system. A Ledger Api client will see a reduction in latency of ~50 milliseconds for end-to-end requests due to better buffering, caching and removal of the database polling step in the participant. The extent of the latency reduction depends on the transaction and deployment. For a simple participant.health.ping (which includes three consecutive transactions), the latency went down from ~ 350ms to 70ms (as compared to the 2.2.0 release).

These optimizations significantly speed up integration testing during development and allow a better user-experience in production due to a swifter reaction to the ledger.

Participant, sequencer and mediator node replication enabled by default

Enterprise: For storage that supports it (Oracle, Postgres), replication is now enabled by default for participant, sequencer and mediator nodes. Replication is used for HA when multiple nodes share the same database. Enabling it by default avoids corruption of the shared database in case enabling it has been forgotten. This has no performance impact even when running a single node. See the performance section on instructions to disable it.

Sequencer client fail-over based on health

Enterprise: Each sequencer now defines internally its health status by the ability to connect to the underlying ledger or database. Sequencer clients connecting to multiple sequencers monitor this health status and will now round-robin requests to healthy sequencers only. Fabric and Ethereum sequencers check and update their health periodically at an interval configured by canton.sequencers.<sequencer>.health.backend-check-period, which defaults to 5 seconds.

Resource Limits

Background

So far, command processing resource limits have been disabled by default. As a result, participants may get overloaded if an application submits commands at an excessive rate. To avoid that, resource limits are now enabled by default.

Specific Changes

If you have already configured command processing resource limits (i.e., using myParticipant.resources.set_resource_limits(...)), the configured limits remain in place. If you have not yet configured resource limits, the limits will change from "no limit" to a maximum rate of 200 commands per second and a maximum of 500 in-flight requests.

Impact and Migration

If you have not yet configured command processing resource limits, double-check whether the new defaults make sense for your system. See the documentation for further information on how to tune resource limits.

Init Configuration

Node name

It is now possible to set an explicit node name during initialization, or have canton generate a random one. See the Default Initialization section for more information.

Changes

Some configuration values have been moved to the init section (Init Configuration) of the configuration. Find below their new location. Note that this change is backwards compatible, but the deprecated config paths will be removed eventually.

All nodes

Deprecated value	New value
init.generate-legal-identity-certificate	init.identity.generate-legal-identity-certificate
init.startup-fail-fast	storage.fail-fast-on-startup

Participant

Deprecated value	New value
ledger-api.max-deduplication-duration	init.ledger-api.max-deduplication-duration
parameters.unique-contract-keys	init.parameters.unique-contract-keys
parameters.enable-causality-tracking	init.parameters.unsafe-enable-causality-tracking

enable-causality-tracking has been renamed to unsafe-enable-causality-tracking due to its experimental state.

Domain

Deprecated value	New value
domain-parameters.*	init.domain-parameters.*

Remote Node Crypto Config Removed

We removed crypto: CryptoConfig = CryptoConfig() from RemoteParticipantConfig since it was not having any effect.

Minor Improvements

• Logging to stdout will now include thread and datetime unless you are running the console interactively. This will improve the logging experience with containers.
• We've discontinued the overly specific error codes MEDIATOR_SAYS_INFORMEES_NOT_HOSTED_ON_ACTIVE_PARTICIPANTS and MEDIATOR_SAYS_INVALID_ROOT_HASH_MESSAGES. Instead, MEDIATOR_INVALID_MESSAGE will be reported.
• New repair commands repair.identity.download and repair.identity.upload 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.
• Improved resilience of ethereum sequencer to network failures.

Security and Bugfixes

• A number of participant metrics were not exposed through the configured reporters. Among others, the metrics pertaining to the indexer such as daml_indexer_ledger_end_sequential_id were missing.
• We have fixed the propagation of JDBC properties from the configuration file to support Postgres SSL connections, and we've updated our documentation on how to configure SSL with Postgres
• Fixed a bug where a command sent through the admin console client fails, if the result exceeds 4MB. The new limit is 2GB, which is also the maximum size of a GRPC message.
• We have fixed a typo in one of the error-ids: PACKAGE_NOT_VETTED_BY_RECIPIENTS was missing the "T" of NOT.

Console Command Changes

This section explains the changes to console commands. Most of the changes are small, but are explained here extensively such that any compilation issues can quickly be resolved.

Timeout Changes in the Console

Types around durations were slightly reworked. The generic TimeoutDuration was dropped and additional types were introduced:

• NonNegativeDuration A duration which is non-negative and possibly infinite.
• NonNegativeFiniteDuration A duration which is non-negative and finite.
• PositiveSeconds A duration which is strictly positive and rounded to the seconds.

Impact and Migration

In most of the cases, changes should be transparent. However, there are a few console commands that need to be changed. For these, a simple rename is sufficient.

Dynamic domain parameters

If you have commands to update the dynamic domain parameters, you should change them and use NonNegativeFiniteDuration instead of TimeoutDuration. However, because new automatic conversions are available, use can use the syntax that is alloweed for Scala concurrent durations.

paint.service.update_dynamic_domain_parameters(
  _.update(transferExclusivityTimeout = TimeoutDuration.ofSeconds(2))
)

should be rewritten

paint.service.update_dynamic_domain_parameters(
  _.update(transferExclusivityTimeout = NonNegativeFiniteDuration.ofSeconds(2))
)

or simply

paint.service.update_dynamic_domain_parameters(
  _.update(transferExclusivityTimeout = 2.seconds)
)

Other console commands and macros

If you use the following commands, you should change some parameters from TimeoutDuration to NonNegativeDuration:

• utils.retry_until_true
• utils.synchronize_topology
• console.set_command_timeout

Domain (nodes):

• domain.set_state
• domain.topology.synchronisation.await_idle
• mediator.fetch_domain_time
• mediator.await_domain_time

Participant:

• participants.all.domains.connect_local
• participants.all.domains.connect_multi
• participants.all.domains.reconnect
• participants.all.domains.reconnect_all
• participant.ledger_api.commands.submit
• participant.ledger_api.commands.submit_flat
• participant.ledger_api.commands.await
• participant.ledger_api.commands.await_active_contract
• participant.ledger_api.commands.find_generic
• participant.ledger_api.completions.list
• participant.ledger_api.completions.list_with_checkpoint
• participant.ledger_api.configuration.list
• participant.ledger_api.transactions.flat
• participant.ledger_api.transactions.trees
• participant.parties.await_topology_observed
• participant.testing.bong
• participant.testing.maybe_bong
• participant.testing.fetch_domain_time
• participant.testing.fetch_domain_times
• participant.testing.await_domain_time
• participant.topology.*.authorize
• participant.packages.synchronize_vetting

Sequencer Connectivity Commands

There are two breaking clean-up changes to the sequencer connection commands, both for participant and domain members.

First, the recently added overloaded version of connect_ha was renamed to connect_multi to disambiguate the two. The overloading of the created UX issues. Therefore, please change your script accordingly.

Second, the <node>.sequencer_connection.modify() function was changed to not require a function returning Either, but rather a plain mapping function (Config => Config) to remove the use of advanced Scala capabilities. At the same time, SequencerConnection.addConnection return type was changed from Either[String, SequencerConnection] to SequencerConnection. As a result, Canton scripts should work mostly unchanged.

Additionally, we improved the documentation on how to manipulate sequencer connections.

Additional Command to Update Domain Parameters

We have added a command myDomain.service.set_ledger_time_record_time_tolerance to conveniently update DynamicDomainParameters.ledgerTimeRecordTimeTolerance. If you use a different method (e.g. myDomain.service.update_domain_parameters) to increase this parameter, you need to pass force = true. Further information can be found in the reference documentation of the methods used to update the domain parameters.

Changes to Daml Script Utilities

The method utils.generate_daml_script_participants_conf outputs now by default a json file without the default participant and uses participant alias instead of Canton style unique identifiers. This allows you to use allocateOn with actual participant references when Daml script with the generated configuration file.

Changes to Transfer Commands

(Preview): We improved naming consistency around transfers commands. Some command parameters have been renamed from origin to source:

• ParticipantCommands.transfer.out: originDomain -> sourceDomain
• ParticipantCommands.transfer.execute: originDomain -> sourceDomain
• ParticipantCommands.transfer.search: filterOriginDomain -> filterSourceDomain

Changes to Limit Arguments

We have reworked the limit arguments in the console. Now, every argument that exposes a limit argument will default to the configuration value canton.parameters.console.default-limit, which is 1000 by default. All the argument types have been changed to PositiveInt, which means that by default, all arguments will return a limited set of items.

In your commands, you can just use integers, as they will be automatically converted to the correct types.

Compatibility

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

Dependency	Version
Canton protocol versions	2, 3
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.5 (Debian 14.5-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.
• adding support for daml interfaces.
• providing higher levels of topology management privacy and scalability.
• production ready support of multiple domains per participant.
• improving our documentation with many explicit operational procedures.