Deploying a Private Synchronizer

Step-by-step guide to configure, start, bootstrap, and verify a private Canton synchronizer

This tutorial walks you through deploying a private synchronizer (also called an extension synchronizer): configure sequencer and mediator nodes, start them, bootstrap topology, connect validators, and verify the deployment.

It is for operators who run their own synchronizer alongside — or instead of relying solely on — the Global Synchronizer. It is not the Super Validator / Global Synchronizer operator guide.

For concepts first, see Private Synchronizers. For deep reference (all bootstrap variants, HA, pruning, and so on), use Synchronizer Operations — this page is the end-to-end walkthrough; that page is the reference.

Setup order

1. Configure — APIs, sequencer backend, TLS, and storage
2. Start — Deploy and start sequencer and mediator
3. Bootstrap — Initialize synchronizer topology
4. Connect — Attach validators / participants
5. Verify — Health, topology, and a test transaction
6. Harden (optional) — HA, monitoring, backups, and related ops

Who this guide is for

Use this guide when:

• You need a dedicated synchronizer for privacy, performance, governance, or cost reasons
• A single organization will own and operate the sequencer and mediator (the default path below)
• You may later connect the same validators to the Global Synchronizer (hybrid pattern)

If you only need Canton Network public connectivity and Canton Coin, deploy a validator on the Global Synchronizer instead of standing up your own synchronizer.

Choose your topology

Choose…	When…	Then follow…
Centralized, single-operator (default)	One org owns sequencer and mediator	This tutorial
Decentralized / multi-owner	Distinct operators must co-sign topology	Decentralized bootstrap
HA / multi-sequencer	Production redundancy	Finish this tutorial, then High Availability
Hybrid (private + Global Synchronizer)	Need CN connectivity as well	This tutorial, then hybrid pattern and linking validators

Default path for this guide: one sequencer + one mediator, single owner, BFT sequencer backend (minimal single-node network). Background on the orderer is in BFT Orderer Architecture. API, backend, and TLS details are in Synchronizer Operations — configure.

The database sequencer backend is unsupported. Use the BFT sequencer backend for new private synchronizers. Multi-node BFT peer networks and advanced backend options are covered under Configure Sequencer Backend.

Prerequisites

Before you begin:

• Familiarity with Canton’s synchronizer architecture
• PostgreSQL 14+ — separate databases for sequencer and mediator; for production, a managed service with automated backups, at least 4 vCPUs / 16 GB memory, and SSD-backed storage
• TLS certificates for the sequencer public API (validators connect here)
• Canton release artifacts (container images or JARs) for sequencer and mediator
• Access to the Canton Console for the sequencer (and mediator if it runs separately)

Kubernetes / Helm (typical production path): Kubernetes 1.27+ and Helm 3.

Local / non-Helm (dev and test): You can run sequencer and mediator as Canton processes with config files instead of Helm. The configure and bootstrap steps are the same; only how you start the processes changes. See Deploy and start for a short non-Helm note.

1. Configure APIs, backend, and TLS

Write configuration before starting nodes. At minimum you need:

1. Sequencer and mediator APIs — public and admin ports/addresses (Configure Synchronizer APIs)
2. Sequencer backend — sequencer.type = BFT for the default path (Configure Sequencer Backend)
3. TLS on the sequencer public API (Secure Synchronizer APIs)
4. Storage — Postgres for each node (next section)

Minimal Canton-style shape (illustrative; map the same settings into Helm values below):

sequencers {
  sequencer1 {
    storage.type = postgres
    // ... postgres connection ...
    public-api {
      port = 5001
      // TLS: see Secure Synchronizer APIs
    }
    admin-api.port = 5002
    sequencer.type = BFT
  }
}

mediators {
  mediator1 {
    storage.type = postgres
    // ... postgres connection ...
    admin-api.port = 5202
  }
}

For peers, endpoint authentication, dedicated BFT storage, external sequencers, and client authentication, use the operations reference — do not expand this tutorial into those variants.

2. Set up databases

Create separate PostgreSQL databases and dedicated users, for example sequencer_db / sequencer_user and mediator_db / mediator_user. Each node stores its own state independently.

Point the sequencer and mediator storage configuration at those databases before you start the nodes.

3. Deploy and start sequencer and mediator

The Helm examples below are illustrative packaging of the same settings. Adjust chart names, value keys, and image repositories to match the Canton / CN release artifacts you use.

Sequencer (Helm)

# sequencer-values.yaml
sequencer:
  storage:
    type: postgres
    config:
      dataSourceClass: "org.postgresql.ds.PGSimpleDataSource"
      properties:
        serverName: "<postgres-host>"
        portNumber: 5432
        databaseName: "sequencer_db"
        user: "sequencer_user"
        password: "<password>"
  publicApi:
    port: 5001
    tls:
      certChainFile: "/certs/tls.crt"
      privateKeyFile: "/certs/tls.key"
  adminApi:
    port: 5002
  sequencer:
    type: BFT
  parameters:
    synchronizerName: "my-private-sync"

helm install sequencer canton/canton-sequencer \
  -f sequencer-values.yaml \
  --namespace canton-sync

Mediator (Helm)

# mediator-values.yaml
mediator:
  storage:
    type: postgres
    config:
      dataSourceClass: "org.postgresql.ds.PGSimpleDataSource"
      properties:
        serverName: "<postgres-host>"
        portNumber: 5432
        databaseName: "mediator_db"
        user: "mediator_user"
        password: "<password>"
  adminApi:
    port: 5202
  sequencerConnection:
    address: "https://sequencer.canton-sync.svc.cluster.local"

helm install mediator canton/canton-mediator \
  -f mediator-values.yaml \
  --namespace canton-sync

Confirm nodes are healthy

Before bootstrap:

• Sequencer and mediator processes/pods are running
• Sequencer health endpoint returns HTTP 200 (when exposed)
• You can open a Canton Console against the sequencer admin API

Non-Helm starts

Start the sequencer and mediator with your Canton distribution and the config files from Configure, then continue with bootstrap. Console commands are the same.

4. Bootstrap (initialize) the synchronizer

Nodes must be fresh (not previously initialized), started, and already configured with backend, APIs, TLS, and storage.

Using the Canton Console connected to the sequencer (default centralized bootstrap — single owner, threshold 1):

@ bootstrap.synchronizer(synchronizerName = "my-private-sync", sequencers = Seq(sequencer1), mediators = Seq(mediator1), synchronizerOwners = Seq(sequencer1), synchronizerThreshold = PositiveInt.one, staticSynchronizerParameters = StaticSynchronizerParameters.defaultsWithoutKMS(ProtocolVersion.forSynchronizer))
    res1: PhysicalSynchronizerId = my-private-sync::122032922613...::35-0

This creates the synchronizer identity and registers the sequencer and mediator in the synchronizer topology. You should see a physical synchronizer id for my-private-sync (or the name you chose).

Other bootstrap flows (do not inline here):

• Decentralized synchronizer
• Decentralized with a subset of sequencers as owners
• Permissioned synchronizer

Full bootstrap reference: Bootstrap a Synchronizer.

5. Connect validators

Once the synchronizer is initialized, connect each validator (participant). On the Canton Console:

@ participant1.synchronizers.connect_local(sequencer1, "my-private-sync")

Or configure the connection in the validator’s Helm values:

participant:
  additionalSynchronizerConnections:
    - alias: "my-private-sync"
      sequencerConnection: "https://sequencer.private-sync.example.com"

Use a stable alias (here my-private-sync) consistently in console and Helm. After changing connection config at runtime, disconnect and reconnect the synchronizer on the participant so the update takes effect.

For validators that also stay on the Global Synchronizer, see linking a validator to multiple synchronizers.

6. Verify the deployment

Work through this checklist:

1. Sequencer health — HTTP health endpoint returns 200
2. Mediator in topology — Mediator is registered on the synchronizer
3. Participant connected — participant.synchronizers.list_connected() shows your alias
4. Ping — Participant can ping across the synchronizer (see bootstrap examples in Synchronizer Operations)
5. Optional smoke test — Allocate a test party and create a contract assigned to the private synchronizer

Production hardening and next steps

• TLS everywhere — Validators to sequencer public API; prefer TLS for peer and admin paths in production (Secure Synchronizer APIs)
• Network policies — Restrict sequencer endpoint access to known validator networks
• Monitoring — Synchronizer monitoring; reuse your validator metrics stack where possible
• Backups — Back up sequencer and mediator databases regularly (Backup and Restore)
• HA — High Availability in Synchronizer
• Traffic management — If you enable traffic controls on a private synchronizer, see Sequencer Traffic Management
• Pruning — Synchronizer Pruning

Related reference

• Private Synchronizers — Why and when to use them
• Hybrid Synchronizer Pattern — Private + Global Synchronizer
• Linking Validators — Multi-synchronizer participants
• Synchronizer Operations — Configure, bootstrap variants, HA, traffic, pruning, backup
• BFT Orderer Architecture — Ordering backend background
• Synchronizer Monitoring — Observability