> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-generated-references-canton-protobuf-histo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> Visual understanding of how Canton Network components work together

Canton's architecture differs fundamentally from traditional blockchains. Understanding these components is essential for designing and debugging Canton applications.

## The Big Picture

Canton separates **coordination** from **storage**. Synchronizers coordinate transaction ordering; participant nodes (validators) store data for their hosted parties.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TB
    subgraph CN[Canton Network]
        subgraph GS[Global Synchronizer]
            SEQ[Sequencer] <--> MED[Mediator]
        end

        subgraph VA[Validator A]
            PNA[Participant Node]
            LSA[(Ledger Shard)]
            PAA[Party: Alice]
        end

        subgraph VB[Validator B]
            PNB[Participant Node]
            LSB[(Ledger Shard)]
            PBB[Party: Bob]
            PCB[Party: Charlie]
        end

        PNA <--> SEQ
        PNB <--> SEQ
    end

    AppA[Application A] --> PNA
    AppB[Application B] --> PNB
```

Unlike Ethereum where every node stores all state, Canton nodes store only their parties' data. The synchronizer coordinates but never stores transaction content.

## Core Components

### Validators

Validators are the workhorses of Canton. They:

| Function | Description |
| - | - |
| **Host parties** | Store contract data for their hosted parties |
| **Execute Daml logic** | Run smart contract code when transactions affect their parties |
| **Validate transactions** | Verify authorization and correctness for their shard |
| **Expose the Ledger API** | Provide gRPC/JSON APIs for applications |

A validator is the Canton Network role that operates a participant node. The participant node, often shortened to "participant", is the private, self-sovereign computational and storage unit for an entity within Canton Network.

**Key characteristics:**

* Each participant node maintains a **localized, private view** of the ledger
* Participant nodes only store contracts where their hosted parties are stakeholders
* Multiple parties can be hosted on a single participant node
* Participant nodes can connect to multiple synchronizers

### Synchronizers

Synchronizers coordinate transaction ordering and consensus **without seeing transaction content**. They consist of two components:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    subgraph Sync[Synchronizer]
        subgraph SEQs[Sequencers]
            SEQ1[Sequencer 1]
            SEQ2[Sequencer 2]
            SEQ3[Sequencer N]
        end
        subgraph MEDs[Mediators]
            MED1[Mediator 1]
            MED2[Mediator 2]
            MED3[Mediator N]
        end
        SEQs <--> MEDs
    end

    P1[Participant 1] <--> SEQs
    P2[Participant 2] <--> SEQs
    P3[Participant N] <--> SEQs
```

**Sequencer**

* Orders and distributes encrypted messages between participants
* Provides total ordering for transactions for that synchronizer
* **Does not see** decrypted transaction content
* Ensures all participants receive messages from that synchronizer in the same order

**Mediator**

* Facilitates the consensus protocol
* Collects confirmation verdicts from participants
* Declares transaction verdicts (committed or rejected)
* **Does not see** decrypted transaction content

<Note>
  The synchronizer is a coordination layer, not a state storage layer. It never stores or has access to transaction data, only encrypted messages and confirmation results.
</Note>

### Parties

Parties are Canton's on-ledger identities, analogous to addresses or externally owned accounts (EOAs) on other blockchains.

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

**Party Capabilities:**

| Capability | Description |
| - | - |
| **Validate** | Confirm transactions affecting their contracts |
| **Control** | Initiate specific actions (choices) |
| **Observe** | See specific state and transactions |

**Local vs External Parties:**

| Type | Key Storage | Control | Use Case |
| - | - | - | - |
| **Local Party** | Held by validator | Validator signs on behalf | Simpler; validator has full control |
| **External Party** | Held externally | Requires explicit signatures | More control; wallet-like experience |

<Warning>
  Unlike Ethereum addresses, parties have costs associated with creation and create state on validators. They're not ephemeral, design your party structure deliberately.
</Warning>

## How Transactions Work

### Transaction Flow

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant App as Application
    participant P1 as Participant 1<br>(hosts Alice)
    participant Sync as Synchronizer
    participant P2 as Participant 2<br>(hosts Bob)

    App->>P1: 1. Submit command<br>(Alice transfers to Bob)
    P1->>P1: 2. Interpret Daml,<br>create transaction views
    P1->>Sync: 3. Submit encrypted views
    Sync->>Sync: 4. Sequence & order
    Sync->>P1: 5. Deliver view for Alice
    Sync->>P2: 5. Deliver view for Bob
    P1->>P1: 6. Validate Alice's view
    P2->>P2: 6. Validate Bob's view
    P1->>Sync: 7. Confirmation
    P2->>Sync: 7. Confirmation
    Sync->>Sync: 8. Mediator collects confirmations
    Sync->>P1: 9. Commit notification
    Sync->>P2: 9. Commit notification
```

### Step-by-Step Explanation

| Step | Component | Action |
| - | - | - |
| **1. Submit** | Application | Sends command to participant via Ledger API |
| **2. Interpret** | Submitting Participant | Executes Daml code, creates transaction with views |
| **3. Submit** | Submitting Participant | Sends encrypted views to synchronizer |
| **4. Sequence** | Sequencer | Orders transaction, assigns timestamp |
| **5. Distribute** | Sequencer | Sends each view only to entitled participants |
| **6. Validate** | All Participants | Each validates their view independently |
| **7. Confirm** | All Participants | Send confirmation/rejection verdict to mediator |
| **8. Collect** | Mediator | Aggregates verdicts, determines outcome |
| **9. Commit** | All Participants | Apply transaction to local ledger shard |

**Key points:**

* Transaction is decomposed into **views**, each party sees only their view
* Synchronizer sequences but **never decrypts** content
* Confirmation requires **threshold agreement** from relevant participants
* Each participant stores only their committed view

## Network Topology Options

Canton supports multiple topology configurations:

### Single Synchronizer (Simple)

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TB
    SYNC[Synchronizer]
    P1[Participant 1]
    P2[Participant 2]
    P3[Participant 3]

    P1 <--> SYNC
    P2 <--> SYNC
    P3 <--> SYNC
```

Use case: Simple deployments, testing, single-organization applications.

### Multiple Synchronizers (Federated)

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TB
    SYNC1[Synchronizer A<br>Private]
    SYNC2[Synchronizer B<br>Consortium]

    P1[Participant 1]
    P2[Participant 2]
    P3[Participant 3]

    P1 <--> SYNC1
    P1 <--> SYNC2
    P2 <--> SYNC1
    P3 <--> SYNC2
```

Use case: Different synchronizers for different workflows; regulatory separation; consortium governance.

### Global Synchronizer (Canton Network)

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TB
    subgraph GSD[Global Synchronizer]
        subgraph SVs[Super Validators]
            SV1[SV 1]
            SV2[SV 2]
            SV3[SV N]
        end
        subgraph SEQs[Distributed Sequencer]
            SEQ1[Sequencer Node 1]
            SEQ2[Sequencer Node 2]
            SEQ3[Sequencer Node N]
        end
        subgraph MEDs[Distributed Mediator]
            MED1[Mediator Node 1]
            MED2[Mediator Node 2]
            MED3[Mediator Node N]
        end
    end

    V1[Validator A]
    V2[Validator B]
    V3[Validator C]

    V1 <--> GSD
    V2 <--> GSD
    V3 <--> GSD
```

Use case: Public Canton Network; decentralized applications; cross-organization workflows.

## Where Your Code Runs

| Component | Location | Technology | Responsibility |
| - | - | - | - |
| **Smart Contracts (Templates)** | Participant nodes | Daml | Business logic, authorization, privacy rules |
| **Backend Services** | Your infrastructure | Any language (TypeScript, Java, Python) | Off-ledger automation, integrations |
| **Frontend** | Browser/mobile | Any framework | User interface |
| **Queries** | Participant (Ledger API) or PQS | gRPC, JSON, SQL | Reading ledger state |

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TB
    subgraph YA[Your Application]
        FE[Frontend<br>React, etc.] --> BE[Backend<br>TypeScript, Java]
    end

    subgraph CI[Canton Infrastructure]
        PART[Participant Node<br>Daml execution] <--> SYNC[Synchronizer]
        PART --> PQS[PQS<br>SQL queries]
    end

    BE --> PART
    BE --> PQS
```

### Application Architecture Decisions

| Decision | On-Ledger (Daml) | Off-Ledger (Backend) |
| - | - | - |
| **Multi-party agreements** | ✓ Required | |
| **Authorization enforcement** | ✓ Recommended | Possible but weaker |
| **Complex business logic** | Possible | ✓ Often easier |
| **External API calls** | Not possible | ✓ Required |
| **High-frequency operations** | Consider batching | ✓ Better suited |
| **Audit trail requirements** | ✓ Built-in | Must implement |

## Component Communication

### APIs Overview

| API | Protocol | Use Case |
| - | - | - |
| **Ledger API (gRPC)** | gRPC/Protobuf | High-performance backend integration |
| **Ledger API (JSON)** | HTTP/JSON | Simpler integration, browser-friendly |
| **Admin API** | gRPC/Protobuf | Node administration, party management |
| **PQS SQL API** | PostgreSQL | Complex queries, reporting |

### Ledger API Operations

| Operation | Description |
| - | - |
| **Command Submission** | Submit Daml commands (create contracts, exercise choices) |
| **Transaction Stream** | Subscribe to transaction events for your parties |
| **Active Contract Set** | Query currently active contracts |
| **Completions** | Track command completion status |

## Next Steps

* **[Privacy Model Explained](/overview/learn/privacy-model)** - Deep dive into sub-transaction privacy
* **[The Global Synchronizer](/overview/understand/global-synchronizer)** - Understand the public network infrastructure
* **[Validator Operations](/global-synchronizer/understand/introduction)** - For those deploying and operating validators