Skip to main content

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.

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

CapabilityDescription
SignAuthorize contract creation (as signatory)
ActExecute choices on contracts (as controller)
SeeObserve contracts and transactions (as stakeholder)
ValidateConfirm transactions affecting their contracts

​
Local vs. External Parties

TypeKeys Held ByUse Case
Local PartyValidatorSimpler; validator signs on party’s behalf. Good for automation.
External PartyExternal systemUser wallets; requires explicit signing workflow
Unlike Ethereum addresses, parties create state on validators and have costs associated with creation. Design your party structure deliberately—don’t create parties unnecessarily.

​
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
RoleCan CreateCan SeeCan Act
SignatoryMust authorizeAlwaysIf also controller
ObserverNoYesIf also controller
ControllerNoWhen exercisingYes (specific choice)
Stakeholder = signatories + observers. Stakeholders are all parties who can see a contract. Validators store contracts for their hosted parties when those parties are stakeholders.

​
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

FunctionDescription
Host partiesStore contracts for their hosted parties
Execute DamlRun smart contract logic
Validate transactionsVerify authorization and correctness
Expose APIsProvide Ledger API for applications

​
Validator Architecture

​
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
Your hosting validator sees all your data. Choose your validator carefully—this is a trust relationship.

​
Synchronizers

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

​
Sequencer

The sequencer orders and distributes messages:
FunctionDescription
OrderAssign timestamps and total ordering
DistributeRoute encrypted messages to recipients
ConsistencyEnsure all participants see same order
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:
FunctionDescription
CollectGather confirmations from participants
AggregateDetermine if consensus threshold is met
DeclareAnnounce transaction outcome (commit/reject)
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:
  • 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.
SolidityDaml
Modify state in placeArchive old contract, create new one
balances[addr] = newValuecreate Token with owner = newOwner
State history implicitState history explicit via contracts
This immutability is key to Canton’s privacy and integrity guarantees.

​
Choices: Consuming vs. Non-Consuming

TypeEffectUse Case
ConsumingArchives the contractState transitions, transfers
Non-consumingContract remains activeQueries, read operations, events for listening clients
-- 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:
StepComponentAction
1ApplicationSubmits command via Ledger API
2Validator AExecutes Daml, creates transaction views
3SynchronizerOrders, distributes encrypted views
4ValidatorsValidate their respective views
5SynchronizerCollects confirmations, declares commit
6ValidatorsStore committed contracts

​
Summary Table

ConceptWhat It IsKey Property
PartyOn-ledger identityHas explicit authorization roles
ValidatorNode hosting partiesStores only hosted parties’ data
SynchronizerCoordination layerOrders without seeing content
TemplateSmart contract definitionDefines data, parties, and choices
ContractTemplate instanceImmutable; changes create new contracts

​
Next Steps

Architecture Deep Dive

See how components work together technically.

Global Synchronizer

Learn about the public coordination layer.

Privacy Model

Understand sub-transaction privacy in detail.

Start Building

Begin developing on Canton.