Core Concepts

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.

Core Concepts

Essential building blocks of Canton Network: parties, validators, synchronizers, and smart contracts

Understanding Canton requires grasping four fundamental concepts: parties, validator node, synchronizers, and templates (smart contracts). This page introduces each and explains how they work together.

Parties

A party is an on-ledger identity in Canton—analogous to an address or account on other blockchains, but with explicit authorization semantics.

Party Identifier Format

alice::1220f2fe29866fd6a0009ecc8a64ccdc09f1958bd0f801166baaee469d1251b2eb72
└┬┘  └─────────────────────────────────────────┘
name                                fingerprint (hash of public key)

What Parties Do

Local vs. External Parties

Party Roles in Contracts

Parties interact with contracts in three roles:

template Asset
  with
    issuer : Party   -- Will be signatory
    owner : Party    -- Will be observer and controller
    auditor : Party  -- Will be observer
  where
    signatory issuer        -- Must authorize creation; always sees contract
    observer owner, auditor -- Can see contract

    choice Transfer : ContractId Asset
      with newOwner : Party
      controller owner      -- Only owner can exercise this choice
      do create this with owner = newOwner

Validators (Participant Nodes)

A validator hosts parties, stores their contract data, and participates in the Canton protocol. A validator contains a participant node (the Daml execution engine) plus a validator process.

What Validators Do

Validator Architecture

flowchart TB
    subgraph Validator[Validator Node]
        PART[Participant<br>Daml execution engine]
        DB[(Ledger Store<br>Party contracts)]
        API[Ledger API<br>gRPC / JSON]
    end

    App[Your Application] --> API
    API --> PART
    PART --> DB
    PART <--> SYNC[Synchronizer]

Key Characteristics

• Each validator maintains a localized, private view of the ledger (called the Active Contract Set)
• Validators only store contracts where their hosted parties are stakeholders
• Multiple parties can be hosted on a single validator
• Validators can connect to multiple synchronizers
• A party can be hosted on multiple validators

Synchronizers

A synchronizer coordinates transaction ordering and consensus without seeing transaction content. It consists of two components:

Sequencer

The sequencer orders and distributes messages:

The sequencer does not:

• Decrypt messages
• See transaction content
• Permanently store transaction data (though it may cache it)
• Know which end users are involved (though it routes based on party information)

Mediator

The mediator facilitates the consensus protocol that confirms the transaction:

The mediator does not:

• See transaction content
• Know what’s being confirmed
• Store confirmation details

The Global Synchronizer

The Global Synchronizer is the public synchronizer for Canton Network:

flowchart TB
    subgraph GS[Global Synchronizer]
        subgraph SVs[Super Validators]
            SV1[SV 1]
            SV2[SV 2]
            SV3[SV N]
        end
        SEQ[Distributed Sequencer]
        MED[Distributed Mediator]
    end

    V1[Validator A] <--> SEQ
    V2[Validator B] <--> SEQ
    V3[Validator C] <--> SEQ
    SEQ <--> MED

• Operated by Super Validators (major institutions)
• Decentralized—no single operator controls it
• Uses Canton Coin (CC) to purchase traffic to pay transaction fees
• Governed by the Global Synchronizer Foundation

Smart Contracts (Templates)

Smart contracts in Canton are defined using Daml, a purpose-built language for multi-party workflows. A Daml template typically defines:

• Data: What information the contract holds
• Parties: Who can see and act on the contract
• Choices: What actions are possible

Template Structure

template Token
  with
    -- Data fields
    owner : Party
    issuer : Party
    amount : Decimal
  where
    -- Authorization
    signatory issuer
    observer owner

    -- Actions
    choice Transfer : ContractId Token
      with
        newOwner : Party
      controller owner
      do
        create this with owner = newOwner

Contracts Are Immutable

Unlike Solidity contracts with mutable state, Daml contracts (template instances) are immutable. They can only be created or archived.

This immutability is key to Canton’s privacy and integrity guarantees.

Choices: Consuming vs. Non-Consuming

-- Consuming: archives the contract
choice Transfer : ContractId Token
  controller owner
  do create this with owner = newOwner

-- Non-consuming: contract stays active
nonconsuming choice GetBalance : Decimal
  controller owner
  do return amount

How Components Work Together

A complete transaction flow involves all four concepts:

sequenceDiagram
    participant App as Application
    participant VA as Validator A<br>(hosts Alice)
    participant Sync as Synchronizer
    participant VB as Validator B<br>(hosts Bob)

    Note over App,VB: 1. Alice transfers token to Bob

    App->>VA: Submit command
    VA->>VA: Execute Daml, create views
    VA->>Sync: Submit encrypted transaction
    Sync->>Sync: Order, timestamp
    Sync->>VA: Deliver Alice's view
    Sync->>VB: Deliver Bob's view
    VA->>Sync: Confirmation
    VB->>Sync: Confirmation
    Sync->>VA: Commit
    Sync->>VB: Commit

Summary Table

Next Steps

Mirrored from Canton Network official documentation (CC-BY-4.0) by CC Privacy Club for learning purposes.