Note
This page is a work in progress. It may contain incomplete or incorrect information.
Protocols on One Synchronizer¶
Note
This page focuses on a single Synchronizer deployment. Multi-synchronizer support is discussed separately.
The execution of Canton protocols involves users and nodes (see diagram below):
Daml parties represent business entities that are involved in transactions.
A Daml party is hosted on one or more Participant Nodes.
Participant Nodes connect to Sequencers to submit transactions (either Daml transactions or reassignments) and receive messages from other members (participants, sequencers, and mediators).
Consensus is achieved by a two-phase commit protocol whose coordinators are Mediator Nodes.
The term member denotes a sequencer, a mediator, or a participant node.
Note
Participant and mediator nodes connect only to sequencer nodes. In particular, they do not exchange messages directly.
Participant Nodes can connect to one or several sequencers.
To illustrate the above description, consider the following example:
Alice, Bob and Charlie are Daml parties.
Participant Nodes are P1, P2 and P3. Alice is hosted on P1 and P3 (in other words, Alice is a multi-hosted party), Bob is hosted on P1 and Charlie on P2.
P1 is connected to a single sequencer, while P2 and P3 are connected to several sequencers.
Synchronizer Functionality¶
Sequencer Nodes¶
Sequencer Nodes allow members of the Synchronizer to send messages to each other. More precisely, they allow for secure multi-cast with privacy:
Secure
Endpoints of the sequencer service to send messages and subscribe to streams of events are authenticated (see security of Synchronizer APIs).
Traffic management can be used to protect against DDoS attacks.
Maximum rate of confirmation requests can be enforced (see dynamic Synchronizer parameters).
Sequencers forward opaque messages. Protocols using the sequencer can therefore encrypt the payloads so that the Sequencers do not see the payload of exchanged messages, only their metadata.
Multi-cast
The sender can send a batch of messages and each message can have different recipients.
The Sequencers assign a timestamp to each batch of messages (see section about Sequencers) and deliver the messages to each recipient in the order of the timestamps.
Privacy preserving
Recipients of a message don’t learn the identity of the sender.
Mediator Nodes¶
Mediator Nodes are coordinators of the two-phase commit protocol. They ensure that a transaction is committed only if all required confirmers send their confirmation before the decision deadline.
Participant Node Functionality¶
Daml parties are hosted on Participant Nodes on one or several Synchronizers. If Participant Node P hosts party Alice, then:
P maintains the set of active contracts (equivalent to unspent transaction outputs, or UTXOs, in some models) for Alice. In particular, Alice can subscribe to the stream of events for her contracts (creations, archivals and exercises) and request a snapshot of her active contract set (ACS).
P maintains the transaction history for Alice and offers querying capabilities.
P confirms transaction on behalf of Alice if she is hosted with at least confirmation permission.
P submits transactions authorized by Alice if she is hosted with at least submission permission.
Protocol types¶
In this section, we present the different kind of protocols supported by Canton:
Channel broadcast to broadcast a message to some or all members of a Synchronizer.
Two-phase commit to coordinate changes on state (for example, Daml transactions to change the state of a contract, or reassignments to change assignation of a contract).
Point-to-point to enable pairs of member to exchange messages (note that members always exchange messages through Sequencers).
Channel broadcast¶
- Definition: channel
A channel is a well-defined group of recipients.
Channel broadcast ensures that all members of the channel receive the same set of messages. Because of the ordering guarantees offered by the Sequencers, channel members can use state machine replication for updating the state managed by the group.
Examples:
Topology state is broadcasted to all members of the synchronizer.
Traffic management uses broadcasts to all sequencers of the synchronizer.
Two-phase commit¶
Required properties¶
Point-to-point¶
Point-to-point protocols allow a member of the Synchronizer to send messages to another member of the same Synchronizer. Since Sequencers are used as gateways, such messages are ordered with respect to other messages of the other protocols. One use case of point-to-point communication is ACS commitments.
Running example¶
We illustrate the different aspects of Canton two-phase commit protocol using a simple DvP example. Alice and Bob want to exchange an IOU given to Alice by a bank for some shares that Bob owns. Ingredients of the example are the following:
Four parties: Alice (A), Bob (B), a Bank and a share registry (SR).
Each party is hosted on a participant with the same name.
- Three types of contracts:
an Iou contract, always with Bank as the backer
a Share contract, always with SR as the registry
a DvP contract between Alice and Bob.
The Daml transaction consists of Alice exercising choice Swap on her IOU, leading to the following transaction:
