Skip to main content

Documentation Index

Fetch the complete documentation index at: https://cantonfoundation-issue-365-details-history.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The Global Synchronizer upgrades frequently. Validators must keep pace with network versions to remain connected. This page describes the upgrade types, procedures, and verification steps.

​
Upgrade types

Canton Network upgrades fall into three categories based on their scope and impact.

​
Type 1: Backward-compatible updates

These are routine releases that do not change the synchronizer protocol or Daml models. They typically include bug fixes, performance improvements, and minor feature additions.
  • Frequency: Weekly to monthly
  • Downtime: None required. Perform a rolling upgrade.
  • Procedure: Update the container image version and restart. For Kubernetes, run helm upgrade with the new chart version. For Docker Compose, update IMAGE_TAG and restart.
  • Deadline: Apply within 2 weeks of release.

​
Type 2: Daml model changes

These releases include updated Daml models (Splice Daml packages). The participant needs to load new packages, but the synchronizer protocol itself does not change.
  • Frequency: Quarterly or as needed
  • Downtime: Brief restart required. No network-wide coordination.
  • Procedure: Same as Type 1, but verify that new Daml packages are loaded after upgrade by checking participant logs.
  • Deadline: Before the date announced in release notes.

​
Type 3: Synchronizer protocol changes (with downtime)

These are major upgrades that change the synchronizer protocol itself. The entire network coordinates a migration window where Super Validators pause the synchronizer, generate migration dumps, and bring up a new synchronizer instance.
  • Frequency: Infrequent (announced well in advance)
  • Downtime: Network-wide coordinated downtime
  • Procedure: Follow the migration procedure described below
  • Deadline: Must complete during the announced migration window

​
Type 1 and Type 2 upgrade procedure

​
Pre-upgrade checklist

  • Review the release notes for breaking changes or new configuration parameters
  • Back up your PostgreSQL database
  • Confirm the new chart version is available

​
Upgrade

# Update to the new version
helm upgrade validator ./splice-node/helm/validator \
  -n validator \
  -f my-validator-values.yaml
Helm performs a rolling restart. Monitor pod status during the rollout:
kubectl rollout status deployment/validator -n validator

​
Post-upgrade verification

# Check pod health
kubectl get pods -n validator

# Review logs for errors
kubectl logs -f deployment/validator -n validator
Verify the Wallet UI is accessible and your validator is connected to the synchronizer.

​
Type 3 upgrade procedure (synchronizer migration)

Type 3 upgrades require coordinated action across the entire network. Super Validators announce the migration window in advance through Slack and mailing lists.

​
How the migration works

  1. Super Validators pause the Global Synchronizer, halting all transaction processing
  2. Each validator’s node generates a migration dump — a snapshot of the active contract set
  3. Super Validators bring up the new synchronizer instance
  4. Validators deploy the new software version, pointing to the new synchronizer
  5. The new synchronizer imports the migration dump and resumes transaction processing

​
Key technical details

  • Identities are preserved. All party IDs, participant identities, and validator identities carry over to the new synchronizer.
  • Active contracts transfer. The migration dump contains the full active contract set.
  • Transaction history does not transfer. The new participant database starts fresh. If you need historical data, archive it before the migration.
  • Traffic balances reset to zero. All traffic purchases on the old synchronizer are lost. If auto-top-up is configured, the validator will automatically purchase traffic on the new synchronizer after migration completes. Purchase traffic incrementally to minimize losses during future migrations.
  • Migration ID increments. Each Type 3 upgrade increments the migration ID by 1.

​
Pre-migration checklist

  • Back up your entire PostgreSQL database
  • Confirm your validator has caught up with the paused synchronizer — check logs for "Ingested transaction" messages. If the most recent message is more than 10 minutes old, catch-up is likely complete.
  • Verify the migration dump was created — search logs for "Wrote domain migration dump"
  • Download the new Splice node bundle

​
Migration procedure

Update your Helm values to enable migration mode:
migration:
  id: <NEW_MIGRATION_ID>  # Previous ID + 1
  migrating: true
Deploy:
helm upgrade validator ./splice-node/helm/validator \
  -n validator \
  -f my-validator-values.yaml
After the validator successfully ingests the migration dump and connects to the new synchronizer, disable migration mode:
migration:
  id: <NEW_MIGRATION_ID>
  migrating: false

helm upgrade validator ./splice-node/helm/validator \
  -n validator \
  -f my-validator-values.yaml

​
Post-migration verification

  • Validator logs show successful ingestion of the migration dump
  • The Wallet UI loads and displays your validator identity
  • The new migration ID is active
  • Traffic purchase works on the new synchronizer
  • Applications can submit transactions through the Ledger API

​
Staying informed about upgrades

  • Slack: #validator-operations for real-time coordination during upgrades
  • Mailing lists: lists.sync.global for advance notice of upcoming upgrades
  • Release notes: Published with each new version on the Splice GitHub releases page
Validators running outdated software versions risk disconnection from the network. Monitor announcements and plan upgrade windows proactively.

​
Next steps

Configuration

Review configuration options for your upgraded node.

Super Validator Setup

SV-specific upgrade considerations.