Canton 2.6.0

Canton 2.6.0 has been released on March 16, 2023. 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 announce Canton 2.6 with major improvements to deal with malicious participants and operational improvements around rate limiting and health checks.

Please follow the steps outlined in our upgrading manual

What’s New

Breaking: Protocol version 2 support removal

Protocol version 2, which was marked as deprecated in Canton 2.3.0 (released on July 2022), is not supported anymore. If your domain is still running protocol version 2, you first need to upgrade the domain to a more recent protocol version (3 or 4) using a 2.5 version of Canton and then upgrade the binary to the current version.

Upgrading instructions can be found in the documentation: upgrading manual

Breaking: Development version support configuration

The following configuration options enable the development/experimental Canton protocol and Daml LF versions.

NOTE: They are not to be used for production, because we do not provide support nor data continuity guarantees for the experimental versions!

The flag will-corrupt-your-system-dev-version-support under canton.domains.<domain>.init.domain-parameters has been removed. Now setting protocol-version to an unstable version (i.e. dev) requires you to explicitly enable canton.parameters.non-standard-config = yes.

The flags will-corrupt-your-system-dev-version-support and unsafe-enable-daml-lf-dev-version under canton.participants.<participant>.parameters have been removed. Now use the new flag canton.participants.<participant>.parameters.dev-version-support to both enable participant connectivity to unstable protocol version domains and to turn on support for unsafe Daml-LF dev versions. Using this option requires you to explicitly enable canton.parameters.non-standard-config = yes.

Refer to the documentation.

Ledger Authorization Security Checks

We have implemented all remaining security checks to ensure that a ledger is well-authorized according to the ledger model's authorization.

Rate Limitation with Bursts

Background

We have improved the rate limiter algorithm that is used by the participant and the sequencer by introducing a new parameter named maxBurstFactor. As a result, the steady-state rate limitation is enforced whenever the burst exceeds maxBurstFactor * maxRate commands above the maxRate. This will reduce the likeliness of undesired backpressure rejects caused by small and temporary bursts.

Impact and Migration

On the participant node, this factor is part of the normal resource management console commands: resources.set_resource_limits.

** Breaking ** This causes a small breaking change for console scripts that use Scala type unpacking of variables, because it now contains a new parameter maxBurstFactor: val ResourceLimits(dirty, rate[, new parameter maxBurstFactor]) = participant.resources.resource_limits()

On the sequencer node, this factor can be configured using the configuration parameter sequencer.parameters.max-burst-factor = 0.5 (default).

Health Checks

Activeness health check on all nodes

The health server's active check is now supported on all nodes.

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.

gRPC Health Checking Service (Preview)

A gRPC health checking service is now available in preview to be configured on each node. This health checking service can be used in Kubernetes deployments for readiness and liveness probes.

Refer to the documentation gRPC Health Check.

Ledger API streaming related configuration changes

The following backwards-compatible configuration changes apply to a participant node's ledger API server. The old configuration fields are still accepted, but they are deprecated.

# Old
canton.participants.<participant>.ledger-api.events-page-size=1000
# New
canton.participants.<participant>.ledger-api.active-contracts-service.max-payloads-per-payloads-page=1000
canton.participants.<participant>.ledger-api.transaction-flat-streams.max-payloads-per-payloads-page=1000
canton.participants.<participant>.ledger-api.transaction-tree-streams.max-payloads-per-payloads-page=1000

# Old
canton.participants.<participant>.ledger-api.active-contracts-service.acs-global-parallelism=10
# New
canton.participants.<participant>.ledger-api.global-max-event-payload-queries=10

# Old
canton.participants.<participant>.ledger-api.events-processing-parallelism=8
# New
canton.participants.<participant>.ledger-api.buffered-events-processing-parallelism=8
canton.participants.<participant>.ledger-api.active-contracts-service.contract-processing-parallelism=8

canton.participants.<participant>.ledger-api.active-contracts-service {
  # Old
  acs-id-page-size=20000
  # New
  max-ids-per-id-page=20000

  # Old
  acs-id-page-buffer-size=1
  # New
  max-pages-per-id-pages-buffer=1

  # Old
  acs-id-fetching-parallelism=2
  # New
  max-parallel-id-create-queries=2

  # Old
  acs-contract-fetching-parallelism=2
  # New
  max-parallel-payload-create-queries=2
}

Below you can see the changed and all the new configuration fields:

canton.participants.<participant>.ledger.api {
  ...
  completions-page-size=1000
  global-max-event-id-queries=20
  global-max-event-payload-queries=10
  active-contracts-service {
    max-ids-per-id-page=20000
    max-pages-per-id-pages-buffer=1
    max-parallel-id-create-queries=2
    max-parallel-payload-create-queries=2
    max-payloads-per-payloads-page=1000
    max-working-memory-in-bytes-for-id-pages=104857600
  }
  transaction-flat-streams {
    max-ids-per-id-page=20000
    max-pages-per-id-pages-buffer=1
    max-parallel-id-consuming-queries=4
    max-parallel-id-create-queries=4
    max-parallel-payload-consuming-queries=2
    max-parallel-payload-create-queries=2
    max-parallel-payload-queries=2
    max-payloads-per-payloads-page=1000
    max-working-memory-in-bytes-for-id-pages=104857600
    transactions-processing-parallelism=8
  }
  transaction-tree-streams {
    max-ids-per-id-page=20000
    max-pages-per-id-pages-buffer=1
    max-parallel-id-consuming-queries=8
    max-parallel-id-create-queries=8
    max-parallel-id-non-consuming-queries=4
    max-parallel-payload-consuming-queries=2
    max-parallel-payload-create-queries=2
    max-parallel-payload-non-consuming-queries=2
    max-parallel-payload-queries=2
    max-payloads-per-payloads-page=1000
    max-working-memory-in-bytes-for-id-pages=104857600
    transactions-processing-parallelism=8
  }
}

Required changes to Besu-based Sequencer deployments

Canton now requires the following versions and features enabled on a Besu deployment:

• Besu version supported upgraded from 21.10 to 22.1 and changed from IBFT 2.0 to QBFT.
• In your Besu node configuration, the RPC HTTP API WEB3 now needs to be enabled ("--rpc-http-api=WEB3,...").

Otherwise the Canton version check of Besu will fail with the sequencer node not starting up due to a BESU_VERSION_MISMATCH error.

Minor Improvements

• We added the ability to run pruning automatically according to a configurable schedule and to track pruning progess via the max-event-age metrics. Refer to the ledger pruning documentation for an overview and details.
• The replication.set_passive command is now also supported on a remote participant setup.
• BREAKING: Improved the input validation at the mediator. As a consequence, the mediator may log MEDIATOR_MALICIOUS_MESSAGE in new situations. Additionally, the mediator may log MEDIATOR_MALICIOUS_MESSAGE instead of MEDIATOR_INVALID_MESSAGE or vice versa. Note that the change can only be observed in rare / unsupported situations, e.g., when the domain topology changes concurrently to a request or when the submitting participant sends an invalid request, which is not possible under our current trust assumptions. Therefore, no impact is expected to existing deployments.
• Two new error messages have been added: UNKNOWN_SUBMITTERS and SUBMITTERS_NOT_ACTIVE mimic the already existing UNKNOWN_INFORMEES and INFORMEES_NOT_ACTIVE messages, respectively reporting if any submitter is not known at all and if no domain can be found where all submitters are hosted and active.
• Performance improvement by enabling the use of epoll native transport when running on Linux for x86_64, ARM64 and S390_64. In case you want to avoid using the native transport, configured it with the -Dio.netty.transport.noNative=true system property setting.
• Fixed issues with the KMS integration in replicated node setups.
• Fixed HA fail-over issues for domain manager and mediator.

Bugfix to the Oracle storage backend

Contracts with large number of stakeholders could lead to an Oracle exception (codes ORA-03146 or ORA-01461) while writing the contract metadata. We have modified the storage operation to not trigger the given limitation anymore. As there is no workaround, we advise users of the Oracle storage backend to upgrade in order to avoid this limitation.

Compatibility

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

Dependency	Version
Canton protocol versions	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 Zulu11.62+17-CA (build 11.0.18+10-LTS, mixed mode)
Postgres	postgres (PostgreSQL) 14.7 (Debian 14.7-1.pgdg110+1)
Oracle	19.15.0
Besu	besu/v22.1.3/linux-x86_64/openjdk-java-11
Fabric	2.2.2