​

Release of Canton 3.7.0

​

Summary

• Multi-synchronizer: no feature flag needed on protocol version 37, and Ledger API changes for multi-synchronizer applications (see Breaking changes).
• Party replication: new v31 topology transactions that track the hosting state of each participant of a party, to enable Hybrid Party Replication (HyPR). Applications that decode PartyToParticipant transactions may need to act (see the migration guide).
• CantonBFT: lower ordering latency and faster catch-up and onboarding.
• Traffic management: traffic can be purchased for participants before they register with the sequencer, and cost estimation covers reassignments.
• Hardening and scalability: protocol version 37 bounds more protocol, topology, and ACS commitment collections, and sequencer and topology states larger than 2 GB can be exported and imported.

• Ledger API:
  • StateService excludes incomplete reassignments unless includeIncompleteReassignments is set, and rejects continuation and page tokens of previous versions.
  • GenerateExternalPartyTopology returns v31 topology transactions on protocol version 37, unless explicitly requested for protocol version 36.
  • Contracts with a non-zero reassignment counter that repair commands import, add or purge appear as Assigned and Unassigned events.
• Node APIs and console:
  • Sequencers and mediators no longer store their onboarding transactions. Use generate_onboarding_transactions instead of identity_transactions.
  • propose_delta no longer moves an Active participant back to Onboarding.
• Protocol:
  • (*) Synchronizers on protocol version 36 are not affected. Protocol version 37 will be rolled out as a new protocol version.
• Configuration: changed default values for safety.
  • The participant repair service is disabled by default (canton.features.enable-repair-commands = false).
  • Key export is disabled by default (canton.parameters.enable-key-download = false).
  • The Docker images no longer set canton.parameters.non-standard-config = true by default.

​

What’s New

​

Protocol version 37

​

Multi-synchronizer without feature flag

• The EnableMultiSynchronizer feature flag is not needed to enable multi-synchronizer.
• Any stakeholder can submit the assignment as soon as the unassignment is completed. The assignment_exclusivity field of unassigned events is not set, and the synchronizer parameter assignmentExclusivityTimeout has no effect.
• New participant configuration canton.participants.<participant>.parameters.reassignments-config.enable-automatic-assignment (default true). When set to true, the participant tries to complete the reassignments initiated by other participants by submitting their assignment, and upon reconnection to a synchronizer it tries to complete its pending reassignments.
• New participant configuration canton.participants.<participant>.parameters.reassignments-config.automatic-assignment-delay (default 60s). The automatic assignment is submitted after a delay drawn between this value and twice this value, counted from the sequencing time of the unassignment on the local clock.

​

New collection size limits

• daml.participant.transaction-node.acting-parties
• daml.participant.transaction-node.choice-authorizers
• daml.participant.transaction-node.choice-observers
• daml.participant.transaction-node.external-call-result-size
• daml.participant.transaction-node.external-call-results
• daml.participant.transaction-node.input-contract-count
• daml.participant.transaction-node.key-maintainers
• daml.participant.transaction-node.lf-value
• daml.participant.transaction-node.node-children-size
• daml.participant.transaction-node.node-count
• daml.participant.transaction-node.root-node-count
• daml.participant.transaction-node.signatories
• daml.participant.transaction-node.stakeholders
• daml.participant.transaction-node.total-informees

• daml.participant.sync.protocol-messages.transaction-view.sub-views
• daml.participant.sync.protocol-messages.transaction-view.tree-depth

​

New v31 topology transactions: action may be required for decoders

• On protocol version 37, moving a hosting entry backward, e.g. from Active to Onboarding, is rejected. A v30 transaction may still set the onboarding flag of an Active entry if the current mapping is v30 too.
• Ledger API topology events: ParticipantAuthorizationOnboarding when an entry becomes Onboarding, ParticipantAuthorizationAdded when it becomes Active, and ParticipantAuthorizationRevoked when an Onboarding or Active entry is removed.
• A node skips a PartyToParticipant mapping with a Nominated or Freezing entry when it pushes its authorized store to a synchronizer on protocol version 36, which cannot express these states, and logs a warning. Propose such mappings in the synchronizer’s store.

​

Migration guide for external signers of PartyToParticipant transactions

Decode v31

• from GenerateExternalPartyTopology unless you request v30,
• from the topology admin API GenerateTransactions always,
• from changes that participants make themselves, and
• as stored proposals to co-sign.

• Decode the data of the UntypedVersionedMessage by its version: 30 as v30.TopologyTransaction, 31 as v31.TopologyTransaction, and reject others. Never decode v31 with the v30 schema: it parses, but drops the party signing keys and the hosting states.
• v31.PartyToParticipant replaces the onboarding flag with a hosting state per participant, and moves party_signing_keys from field number 6 to 4. All other mappings are unchanged.
• Show each participant’s hosting state: Nominated and Freezing participants do not host the party yet.
• Hashing and signing are unchanged.
• ListPartyToParticipant returns v30 items unless the client sends a client_version of 3.7 or later, as long as no entry is Nominated or Freezing.

Or keep using v30 for now

• Request v30 with protocol version 36: protocol_version in GenerateExternalPartyTopology (protocolVersion in the JSON Ledger API) and the topology admin API Authorize, protocolVersion in the console commands party_to_participant_mappings.propose and propose_delta, and --protocol-version in the topology scripts. GenerateTransactions always returns v31. AllocateExternalParty accepts both versions.
• To co-sign, sign the transaction that you received. Do not rebuild it as v30: a v30 and a v31 proposal of the same change never combine.
• While a party has a Nominated or Freezing entry, v30 PTP transactions for it are rejected with TOPOLOGY_HOSTING_STATES_NOT_EXPRESSIBLE, as v30 cannot express these states.

​

Protocol version downgrades via LSU are forbidden

​

For application developers

​

Synchronizer record time to offset conversion

​

Traffic cost estimation for reassignments

​

Source and target validation packages can be overridden

• The following console commands now take optional overrideSourceValidationPackageIds and overrideTargetValidationPackageIds arguments:
  • submit_unassign
  • submit_unassign_with_format
  • submit_reassign
  • submit_unassign_async
• The UnassignCommand Java binding also supports these additional fields.

​

Synchronizer operators

​

CantonBFT

• Improved configuration defaults for better ordering latency.
• Request pre-prepare via retransmissions if a weak quorum of prepares is reached without having the pre-prepare. This is an important performance improvement when there is high latency between some nodes and pre-prepares are often delayed or lost.
• Starting with PV37, state transfer responses can carry multiple commit certificates. This allows for more efficient catch-up and onboarding.
• Patience-based dissemination retries (availability-dissemination-patience) are now disabled by default. When enabled, they also apply to batches that have reached the minimum dissemination threshold but have neither been disseminated to all nodes nor become part of a block proposal.
• Observability:
  • Logs of the dissemination stage of the ordering protocol have been improved for easier troubleshooting.
  • Improved logging about oversized gRPC messages.
  • Improved metrics about P2P connection status and ISS consensus segment leadership.
  • P2P: TCP- and HTTP2-level metrics.
  • Added metrics for the time ordered blocks wait before delivery while lower-numbered blocks are still pending.
  • Added metrics for pre-prepares accepted coming from retransmissions.
• Fixed: the P2P connection direction was incorrectly reported in metrics and console/admin endpoints in some circumstances.

​

Initialization changes for sequencers and mediators

​

File-based console commands for sequencer initialization and topology snapshots

• node.topology.transactions.export_genesis_state
• node.topology.transactions.export_topology_snapshot_to_file
• sequencer.setup.export_onboarding_state_for_sequencer
• sequencer.setup.export_onboarding_state_at_timestamp
• sequencer.setup.import_genesis_state
• sequencer.setup.import_onboarding_state

​

Traffic purchase for members that are not registered yet

​

Participant node operators

​

Traffic enforcement app: pruning of submission correlations

​

Traffic enforcement app: traffic top-ups from the ledger (experimental)

​

All node operators

​

Key management operations are bound to a synchronizer

• node.topology.owner_to_key_mappings.add_key
• node.topology.owner_to_key_mappings.add_keys
• node.topology.owner_to_key_mappings.remove_key
• node.topology.owner_to_key_mappings.rotate_key
• node.keys.secret.rotate_kms_node_key
• node.keys.secret.rotate_node_key
• node.keys.secret.rotate_node_keys

​

Breaking changes

​

Ledger API (application developers)

​

StateService excludes incomplete reassignments by default

  POST http://localhost:6865/v2/state/active-contracts-page
  Content-Type: application/json
  {
    "activeAtOffset": 1000000,
    "eventFormat": {...},
    "maxPageSize": 100,
    "pageToken": "",
    "includeIncompleteReassignments": false
  }

​

GenerateExternalPartyTopology returns v31 topology transactions on protocol version 37

​

Repair commands represent contracts depending on their reassignment counter

• true: unchanged, all contracts are represented as Assigned (import, add) or Unassigned (purge) events.
• false (default): contracts with a zero reassignment counter are represented as Created (import, add) or Archive (purge) events, contracts with a non-zero reassignment counter are represented as Assigned (import, add) or Unassigned (purge) events, preserving the reassignment counter. Previously, all contracts were represented as Created/Archive events and the import of contracts with a non-zero reassignment counter was rejected.

​

Submission ids of automatic reassignments

​

Synchronizer operators

​

Sequencer and mediator onboarding transactions

​

Participant node operators

​

The participant repair service requires enable-repair-commands

​

Topology: propose_delta no longer moves an Active participant back to Onboarding

​

All node operators

​

Key export requires enable-key-download

​

Docker images no longer set non-standard-config

​

Deprecations

• The traffic enforcement Ledger API endpoint TrafficService.PruneEvents, the JSON endpoint POST /v2/traffic/events/prune and the console command ledger_api.traffic.prune_events are deprecated. Use TrafficService.Prune (POST /v2/traffic/prune, console ledger_api.traffic.prune) instead. They will be disabled by default in 3.8 and removed in 3.9. Setting canton.participants.<participant>.features.deprecated.enable-deprecated-endpoints-37 = false (default true) disables them earlier, and calls then fail with DEPRECATED_API_DISABLED.
• The sequencer configuration canton.sequencers.<sequencer>.parameters.produce-post-ordering-topology-ticks is deprecated and ignored with a warning: post-ordering topology ticks are always produced.

​

Minor Improvements

​

Ledger API

• Manual pruning over the Ledger API is iterative, like scheduled pruning, with the maximum offset range of one iteration set by canton.participants.<participant>.parameters.batching.max-pruning-batch-size. Contract pruning is iterative as well, with at most canton.participants.<participant>.ledger-api.index-service.contract-pruning-batch-size contracts per iteration (default 10000).
• Improved the performance of Ledger API pruning. The query plan change behind it can be turned off with canton.participants.<participant>.ledger-api.index-service.disable-merge-and-hash-joins = false (default true).
• Improved the performance of Ledger API update and active contract streams, and of the paged updates endpoint (GetUpdatesPage).
• Improved the performance of Ledger API party queries, and party listings now reflect changes to the hosting of multi-hosted parties faithfully.
• Unassignments and assignments are rejected with ContractSerializationVersionNotSupported if a contract requires a higher LF serialization version than the target synchronizer’s protocol version supports.
• Increased the log level of Ledger API indexer initialization and termination errors to WARN, except known transient failures that stay on INFO.
• Fixed an internal error when calling JoseService.GetJwks for Ed25519 keys.
• When the last locally hosted stakeholder of an unassigned contract is offboarded from the participant, the reassignment no longer counts as incomplete from that offset on, so the StateService with includeIncompleteReassignments and the check for stuck assignments no longer report it.

​

Synchronizer operators

• Sequencer acknowledgements are now rejected synchronously whenever the sequencer cannot accept them.
• The sequencer reports malformed submission requests with the new error codes SEQUENCER_SUBMISSION_REQUEST_MALFORMED_REJECTED on protocol version 37 and SEQUENCER_SUBMISSION_REQUEST_MALFORMED on protocol version 36. The alarm codes INVALID_ENVELOPE_SIGNATURE and MULTIPLE_MEDIATOR_RECIPIENTS have been removed: update alerts that match on them.

​

Participant node operators

• The participant status report now tracks the health components of all connected synchronizers instead of only the last connected one. Each per-synchronizer component status carries the physical synchronizer id in a new labels field (synchronizer key) of ComponentStatus in the health admin API, and the Components: section of participant.health.status renders node-level components as before, followed by a Synchronizers: section with the component states per connected synchronizer. The status can also be restricted to a single synchronizer via participant.health.status(synchronizerId) (accepting a logical or physical synchronizer id), backed by a new optional synchronizer_id field on ParticipantStatusRequest.
• Participants validate synchronizer connections (connect, register, modify, migrate) through a temporary sequencer connection pool. All validation modes except DISABLED now behave like THRESHOLD_ACTIVE, so All and Active no longer require every configured sequencer to be reachable. Validation failures are reported as FailedToConnectToSequencers or SynchronizerIsNotAvailable.
• New participant reassignment metrics: daml.participant.sync.reassignments.submitted, daml.participant.sync.reassignments.requests, daml.participant.sync.reassignments.finalized, daml.participant.sync.reassignments.batch-size and daml.participant.sync.reassignments.unassignment.local-target-timestamp-lag.
• repair.purge rejects contracts that are reassigned away from the synchronizer, or skips them when ignoreAlreadyPurged is set.
• To maintain ledger consistency when importing repair events, repair events are now rejected if the last persisted event was a topology event. If this happens, reconnect to the synchronizer to move the record time. If you cannot reconnect, use the forceRepairWhenTopologyTransactionAtLedgerEnd flag. Using the force flag can corrupt the data in the system.
• Participants reconnect to a synchronizer faster. On reconnect, the participant looks up its latest request before a given time. This lookup could scan the whole request journal and now uses its index.

​

All node operators

• New cache configuration canton.<node>.parameters.caching.transparency-check-cache (default maximum-size = 10000, expire-after-timeout = 5m) for the results of transparency checks, used if the static synchronizer parameter enable_transparency_checks is set. It previously shared the session key receiver cache configuration.
• Topology:
  • When a topology transaction submission loses the race against a concurrent topology transaction submission for the same serial, a TOPOLOGY_SERIAL_MISMATCH is reported instead of a semantic error related to the content of the transaction.
  • The submitting node now logs an INFO when a topology transaction sent through the queue-based or store-based topology outbox is sequenced but rejected during topology validation.
  • The topology and offline root key scripts can build topology transactions of proto version v31, used from protocol version 37. They take the protocol version of the synchronizer: --protocol-version for prepare-cert.sh, interactive_submission.py, interactive_topology_example.py and interactive_topology_example.sh, an optional last argument for the functions of topology_util.sh, and the keyword argument protocol_version for the Python helpers.
    • The protocol version defaults to 36, i.e. to v30 topology transactions as in earlier releases. Synchronizers on protocol versions 36 and 37 accept them.
    • Pass 37 to build v31 topology transactions for a synchronizer on protocol version 37. Such synchronizers accept v30 only to ease the transition, so switch to 37 once your synchronizers run protocol version 37.
    • prepare-cert.sh: keep 36 while the node connects to any synchronizer running protocol version 36, and switch to 37 once all of them run it. A node can’t convert a certificate signed with the offline root key, so a certificate of the wrong version must be prepared again.
    • An unsupported protocol version fails with an explanation of the choices.
  • prepare-cert.sh rejects --intermediate-delegation combined with --root-delegation or --delegation-restrictions.
• KMS:
  • Added AWS KMS support for Ed25519 signing keys like GCP KMS.
  • Fixed creation of Ed25519 keys in GCP KMS to use only the software protection level, because they are not available with HSM protection level.
• Improved error reporting of various admin API endpoints in case of the server being shut down: ABORTED_DUE_TO_SHUTDOWN is now reported in some cases instead of internal errors.
• gRPC server handler logs now carry the request’s trace id when a client calls with an empty TraceContext, for example the sequencer connection pool’s Authenticate, Subscribe and DownloadTopologyStateForInit. The client interceptor uses a default trace id when the caller supplied none, instead of sending no traceparent.
• Dependency updates to address security vulnerabilities: Bouncy Castle 1.86, gRPC 1.85, jackson 2.22.4, and OpenTelemetry and its instrumentation.
• The sequencer aggregator no longer fails on old messages delivered by a lagging sequencer.
• Fixed a regression where the Canton console printed party IDs, synchronizer IDs and other identifiers as raw case classes (e.g. PartyId(uid = UniqueIdentifier(...))) instead of their compact form.
• The Docker images use da-base-image 1.0.18, whose JDK no longer trusts the eMudhra root CA. TLS certificates that chain to it are rejected.

​

Daml

• Fixed the transaction trace shown for unhandled exceptions: when the exception passed through a try-catch that did not handle it, the trace started at the choice enclosing the try-catch instead of the choice where the exception was thrown.

​

Compatibility