Documentation Index

Fetch the complete documentation index at: https://docs.canton.network/llms.txt

Use this file to discover all available pages before exploring further.

​

Contracts and synchronizer assignment

​

Unassignment and reassignment

1. Unassignment — The contract is removed from its current synchronizer. During this brief period, the contract cannot be used in transactions.
2. Reassignment — The contract is assigned to the target synchronizer and becomes usable again.

​

The Global Synchronizer

​

When to use multiple synchronizers

• Isolation — Keep certain transaction flows entirely separate from the public network
• Performance — Reduce contention by spreading high-throughput workflows across synchronizers
• Regulatory compliance — Ensure certain transactions are processed only by specific validators in specific jurisdictions

​

Multiple Synchronizers

​

Motivation

• Regulations Some regulated environments require you to have control of the core infrastructure. Alternatively, data domicile laws may forbid you from connecting to Synchronizers that are not deployed in your zone of operations.
• Performance Different Synchronizers have different performance characteristics: some might favor high throughput, while others might target low latency. You must pick the Synchronizer which fits your non-functional requirements.
• Governance The governance of a Synchronizer might be centralized or decentralized.
• Cost For a high throughput use case, the fees of the Global Synchronizer might be too high and you might favor another Synchronizer.
• Application restrictions As an application provider, you might decide to restrict the use of your application to a specific Synchronizer.

​

Transactions with Multiple Synchronizers

1. Find a suitable Synchronizer for the transaction, let’s call it S The conditions that S should fulfill are made more precise below in reassignment-validations. At minimum, all the stakeholders should be hosted on S, and every package of every input contract should be vetted on S.
2. Change the assignation of all input contracts to S (that is, reassign all the input contracts to S).
3. Execute the transaction on S.
4. If desired, change the assignation of output contracts to another Synchronizer.

• Automatically When a user submits the transaction, Canton’s Synchronizer router tries to identify the best Synchronizer which can be used to submit the transaction. Then, it submits reassignment confirmation requests so that the transaction’s inputs contracts are reassigned to the selected Synchronizer. Once all the reassignments have been completed, the Synchronizer router submits the Daml transaction to the selected Synchronizer. Note that in that case, the user does not have to worry about choosing a Synchronizer and performing reassignments. This allows applications to be designed without taking Synchronizers into account. However, an application can influence the routing using inhomogeneous topologies (per-synchronizer package vetting or party hosting) as well as explicitly disclosed contracts.
• Explicitly Users can control the Synchronizer routing precisely as follows:
  • Ledger API accepts commands to submit reassignments.
  • When submitting a Daml transaction, the user can prescribe which Synchronizer to use. If the prescribed Synchronizer is not suited for the transaction, the submission fails.

​

Automatic selection of the Synchronizer

• The reassignment of c``i from S``i to S is valid.
• The submitting participant is a reassigning participant for the submitting party for each c``i.

• has the highest priority,
• minimize the number of reassignments,
• has the lowest Synchronizer id.

​

Importance of the Global Synchronizer

​

Reassignment protocol

​

Overview

• Unassignment A stakeholder of the contract submits the command to unassign the contract from the source Synchronizer. Once the unassignment is committed, c is inactive on the source Synchronizer and cannot be used anymore. The unassignment goes though the same phases as the transaction protocol.
• Assignment A stakeholder of the contract (not necessarily the same one who submitted the unassignment) submits the command to assign the contract on the target Synchronizer. Once the assignment is committed, c becomes active on the target Synchronizer and can be used again. The assignment goes though the same phases as the transaction protocol.

​

Reassignment from Ledger API and application point of view

• contracts to be reassigned (all contracts in the batch must have same set of signatories and same set of stakeholders),
• source Synchronizer (current assignation),
• target Synchronizer.

• unassign id: Opaque identifier which uniquely identifies the reassignment and is used to submit the assignment.
• reassignment counter: Number of times the contract was reassigned.
• assignment exclusivity: Before this time (measured on the target Synchronizer), only the submitter of the unassignment can initiate the assignment.

• unassign id,
• source Synchronizer (previous assignation),
• target Synchronizer.

• unassign id: Can be used to correlate unassigned and assigned events.
• reassignment counter: The value is the same as in the unassigned event.
• created event: Contract data (see entering-leaving-visibility to learn about the purpose).

​

Running example

• Five participants P1, …, P3 and two Synchronizers S1 and S2.
• Hosting relationships as shown in the picture below. The letter in parenthesis indicates the permission (Submission, Confirmation, Observation).

​

Main definitions around reassignments

​

Target timestamp

​

Reassigning participant

1. S is a stakeholder of c.
2. S is hosted by P on the target Synchronizer at the target timestamp.
3. S is hosted by P on the source Synchronizer.

​

Signatory unassigning participant

1. S is a signatory of c.
2. P is a reassigning participant for S.
3. S is hosted on P with at least confirmation rights on the source Synchronizer.

​

Signatory assigning participant

1. S is a signatory of c.
2. P is a reassigning participant for S.
3. S is hosted on P with at least confirmation rights on the target Synchronizer.

• P1 does not host a signatory of the contract.
• P3 hosts a signatory but only with observation rights.

​

Confirmation policies

​

Validation of unassignment and assignment requests

• Reassigning a contract should not deprive a stakeholder from being able to use a contract.
• The risk that a contract cannot be assigned after it has been unassigned should be reduced to the bare minimum (recall that a reassignment is non-atomic).

• The contract c is active on the source Synchronizer.
• Every stakeholder is hosted on a reassigning participant.
• Each signatory S is hosted on sufficiently many signatory assigning participants. More precisely, if the confirmation threshold on the target Synchronizer for S is t, then S needs to have at least t signatory assigning participants. This removes the risk that there are not enough signatory assigning participants, which would mean that the reassignment cannot be completed.
• The package corresponding to the contract has to be vetted on the target Synchronizer.
• If the request contains several contracts, all the contracts in the batch must have the same signatories and stakeholders.

• The assignment corresponds to a reassignment which is not yet completed.
• The package corresponding to the contract is vetted.

• views can be decrypted correctly,
• the recipient list is correct,
• root hash messages is correct,
• etc.

​

Submission policies

• In the running example, Alice loses the ability to exercise choices on the Iou when it is reassigned to S2 as she is not hosted with submission permissions on Synchronizer S2. Because she is allowed to initiate a reassignment back to S1, she has a way to regain the possibility to exercise choices on the Iou.
• Decentralized parties cannot submit Daml transactions but should be able to submit reassignments for composability of applications.

​

Contracts entering and leaving the visibility of the participant

​

Non causality of the updates stream

• The first element is the Created of c (activation).
• When the contract is not active, the last element is either an Archived or an Exercised (deactivation).
• The record time of the activation is strictly smaller then then record time of the deactivation. More generally, the events on the updates stream are ordered by their record time.

• No assumption can be made with respect to ordering of events which happened on different Synchronizers.
• The ordering can be different from one participant to the order.

• Contract c is created on Synchronizer S1.
• c is unassigned from S1 to S2.
• c is assigned to S2.
• c is archived.

• created, unassigned, assigned, archived
• created, assigned, unassigned, archived
• assigned, created, unassigned, archived
• assigned, archived, created, unassigned
• created, assigned, archived, unassigned
• assigned, created, archived, unassigned

• the created always appears before all unassigned or archived, and
• the archived always appears after all the assigned or created,
• there are no consecutive activations or deactivations (and in particular no consecutive assigned or unassigned).

​

Reassignments and contention

​

Multi-Synchronizer Time

​

Traffic management

​

Submission requests

​

Traffic Cost

• Network traffic incurred by recipients reading the event
• Storage cost of the events in the sequencer

• The sender
• The list of envelopes. Each envelope contains:

  • A payload (arbitrary bytes)
  • A list of recipients (members of the synchronizer). Recipients can be addressed either:

    • Individually
    • Via group addressing. Group addressing allows to address a specific set of recipients as a group. For instance, the group address AllMembersOfSynchronizer will send the payload to all members of the synchronizer.

fn calculate_submission_request_traffic_cost:
    envelopes_cost = 0

    for envelope in envelopes:
        storage_cost = envelope.payload
        network_cost = envelope.payload * envelope.recipients.size * read_vs_write_scaling_factor
        submission_request = storage_cost + network_cost
        envelopes_cost = envelopes_cost + submission_request

    return base_event_cost + envelopes_cost

​

Traffic accounting

​

Traffic enforcement

• After step 1 when the sequencer receives the submission request from the sender. At this stage the sequencer decides whether the sender has enough traffic for the request using its local knowledge of the sender’s traffic state. If it determines that the sender does not have enough traffic, it rejects the request at this stage.
• After step 3, every sequencer reads the sequenced event from the BFT ordering layer. At this stage each sequencer runs the same logic as in step 1, except they use the traffic state of the sender at the sequencing time of this event. This enables every sequencer to make the same deterministic decision on whether the sender has enough traffic.

  • If the sender does not have enough traffic, the event is not sent to its recipient, and the sender receives a deliver error indicating the reason. This is called “wasted sequencing” and will be reported as such in metrics.
  • If the sender has enough traffic, traffic is deducted from the sender’s balance. What happens after this depends on whether the event is valid and can be delivered to its recipients. Additional validations beyond traffic control happen in the sequencer before an event can be delivered (such as validating signatures, the existence of recipients, and so on). If those validations pass, the event is delivered, and the sender receives a delivery receipt that includes a TrafficReceipt. The receipt allows the sender to update its traffic state accordingly. If the event is otherwise invalid, the event is not delivered, and the sender receives a delivery error indicating the reason for the failure. This last case is called “wasted traffic” and is reported as such in metrics.

​

Acquiring traffic

​

Base traffic

​

Extra traffic

​

Serial

​

Observing traffic

​

Traffic state

​

Metrics

​

Configuration

// In bytes, the maximum amount of base traffic that can be accumulated
uint64 max_base_traffic_amount = 1;

// Maximum duration over which the base rate can be accumulated
// Consequently, base_traffic_rate = max_base_traffic_amount / max_base_traffic_accumulation_duration
google.protobuf.Duration max_base_traffic_accumulation_duration = 3;

// Read scaling factor to compute the event cost. In parts per 10 000.
uint32 read_vs_write_scaling_factor = 4;

// Window size used to compute the max sequencing time of a submission request
// This impacts how quickly a submission is expected to be accepted before a retry should be attempted by the caller
// Default is 5 minutes
google.protobuf.Duration set_balance_request_submission_window_size = 5;

// If true, submission requests without enough traffic credit will not be delivered
bool enforce_rate_limiting = 6;

// In bytes, base event cost added to all sequenced events.
// Optional
optional uint64 base_event_cost = 7;