Setting Up a Canton Network Validator Node: A Complete Guide

A step-by-step walkthrough covering everything from prerequisites and network sponsorship, to Docker Compose deployment, authentication, and post-launch health checks everything you need to go from zero to a live Canton validator.

Table of Contents

1. What Is the Canton Network?
2. Validator vs. Super Validator: Know the Difference
3. Prerequisites
4. Step 1: Get a Sponsor & Join the Allowlist
5. Step 2: Set Up Your Infrastructure
6. Step 3: Configure OIDC Authentication
7. Step 4: Obtain Your Onboarding Secret
8. Step 5: Deploy via Docker Compose (DevNet)
9. Step 6: Kubernetes Deployment (Production)
10. Step 7: Verify Connectivity
11. Step 8: Access Your Wallet UI
12. Step 9: Promote to TestNet & MainNet
13. Rewards, Traffic & Canton Coin
14. Backups & Disaster Recovery
15. Monitoring & Observability
16. Common Errors & Troubleshooting
17. Summary
18. About Us
19. FAQ

What Is the Canton Network?

Canton is an enterprise-grade blockchain network built by Digital Asset on top of the Daml smart contract language. Unlike traditional public blockchains that broadcast all data to all nodes, Canton uses a privacy-by-default architecture: your validator node only receives and stores data belonging to transactions you are a party to. Every other participant's data remains invisible to you by design.

The network's backbone is the Global Synchronizer a decentralized coordination layer operated by a set of Super Validator (SV) nodes. Validators connect to this synchronizer to participate in the network, submit transactions, and interact with applications such as tokenization platforms, payment rails, and settlement systems.

The native utility token is Canton Coin (CC), used to pay for network traffic fees and earned as liveness rewards for running an active validator node.

Validator vs. Super Validator

Before we start, it's important to understand the two node tiers on Canton:

This guide covers validator nodes only. Super Validator setup is a separate, invite-only process.

Prerequisites

Before you touch any config file, make sure you have the following in place.

Software Requirements

Hardware Requirements (Minimum for DevNet/TestNet)

Network Requirements

• A static egress IP address is mandatory. The Canton network uses IP allowlisting at the firewall level; dynamic or NAT'd IPs will not work unless tunneled through a VPN that has been whitelisted.
• Alternatively, you can connect your validator through a VPN operated by your sponsor SV.
• Outbound HTTPS (port 443) to Super Validator sequencer and Scan endpoints.
• Inbound ports for the wallet and CNS UIs (typically 80/443 behind a reverse proxy).

Account Requirements

• An OIDC-compatible Identity Provider (Auth0, Keycloak, Azure AD, Okta, or similar)
• An existing Super Validator sponsor to whitelist your IP and issue an onboarding secret
• Access to the Splice release bundle (open-source, hosted on GitHub)

Step 1: Get a Sponsor & Join the Allowlist

Canton MainNet operates in an invite-only model. To join, you must be sponsored by an existing Super Validator (SV), an existing validator, an application provider, or the Canton Foundation itself.

How to Find a Sponsor

• Request access through the Canton Foundation form at sync.global/validator-request
• Reach out directly to a listed Super Validator operator (Digital Asset, Tradeweb, Cumberland, etc.)
• For DevNet, any SV can sponsor you and the process is largely self-service

Submit Your Egress IP for Whitelisting

Once you have a sponsor, provide them with the static egress IP of the machine or cluster that will run your validator. Each network (DevNet, TestNet, MainNet) requires a distinct IP address you cannot reuse the same IP across networks.

Your sponsor will submit your IP to the Super Validators for inclusion in their firewall allowlist. This covers both the Scan endpoint and the sequencer endpoint connectivity your validator needs.

01# Confirm your egress IP before sending it to your sponsor02curl -s https://api.ipify.org

⚠️ Important: Run this command from the exact machine or cluster that will host your validator. If you run it from your laptop, you will send the wrong IP.

Step 2: Set Up Your Infrastructure

Docker Compose Path (DevNet / Small Production)

Provision a Linux VM (on AWS, GCP, Azure, or bare metal) meeting the hardware specs above. Install Docker and Docker Compose:

01# Install Docker Engine02curl -fsSL https://get.docker.com -o get-docker.sh03sudo sh get-docker.sh04 05# Add your user to the docker group06sudo usermod -aG docker $USER07newgrp docker08 09# Verify10docker --version11docker compose version

Both AMD64 and ARM64 architectures are supported. The output should show Docker Compose 2.26.0 or newer; older versions will fail silently on certain config features.

Kubernetes Path (Production)

For production deployments, a Kubernetes-based setup using Helm charts is strongly recommended. It provides better scalability, built-in health probes, and supports Grafana-based monitoring out of the box.

Requirements:

• A running Kubernetes cluster with admin access to create and manage namespaces
• kubectl (v1.26.1+) and helm (v3.x) installed on your workstation
• An external PostgreSQL database (RDS, Cloud SQL, or self-managed)
• An ingress controller (nginx-ingress recommended) with TLS termination

Download the Helm chart bundle from the official Splice release page and extract it:

01# Download and extract the release bundle02curl -L https://github.com/hyperledger-labs/splice/releases/latest/download/splice-node.tar.gz \03  -o splice-node.tar.gz04tar -xzf splice-node.tar.gz05cd splice-node/

Step 3: Configure OIDC Authentication

This is the step that trips up most new operators. Canton validator nodes use OAuth 2.0 / OIDC for two distinct authentication flows, and both need to be configured before you start the node.

Flow 1: Machine-to-Machine (Client Credentials Grant)

Used internally: the validator app backend authenticates to the Canton participant node. Your OIDC provider must support the OAuth 2.0 Client Credentials flow, and you need to create a (CLIENT_ID, CLIENT_SECRET) pair for this.

The sub field of JWTs issued through this flow must match the ledger-api-user you configure later. Most providers (Auth0, Keycloak) form this as CLIENT_ID@clients by default.

Flow 2: User-Facing (Authorization Code Grant)

Used by humans accessing the Wallet UI and Canton Name Service (CNS) UI. Your OIDC provider must support the Authorization Code Grant flow and expose sub as a stable, unique user identifier.

Required Configuration Values

Export these variables you will need them during deployment:

01# OIDC Provider configuration02export OIDC_AUTHORITY="https://YOUR_TENANT.auth0.com/"03export OIDC_CLIENT_ID="your-validator-client-id"04export OIDC_CLIENT_SECRET="your-validator-client-secret"05export VALIDATOR_WALLET_ADMIN_USER="auth0|your-admin-user-sub"06 07# JWT Audience start with this default, harden later08export LEDGER_API_AUTH_AUDIENCE="https://canton.network.global"09export VALIDATOR_AUTH_AUDIENCE="https://canton.network.global"

💡 Tip: When starting out, setting both audiences to https://canton.network.global is fine and simplifies debugging. Once your node is running, configure dedicated per-deployment audience values to prevent tokens from one network being usable on another.

Callback URLs to Register in Your OIDC Provider

01http://wallet.localhost      ← Wallet UI02http://ans.localhost         ← Canton Name Service UI

For Kubernetes deployments using real domain names, replace localhost with your actual domain (e.g., https://wallet.mycompany.com).

Step 4: Obtain Your Onboarding Secret

Your onboarding secret is a one-time-use token provided by your sponsor SV that authorizes your node to join the network. On MainNet and TestNet, your sponsor must generate this for you manually. On DevNet, you can self-generate it.

Self-Generate on DevNet

01# Replace SPONSOR_SV_URL with your sponsor's SV app URL02# Example for GSF (Global Synchronizer Foundation):03SPONSOR_SV_URL="https://sv.sv-1.dev.global.canton.network.sync.global"04 05curl -X POST "${SPONSOR_SV_URL}/api/sv/v0/devnet/onboard/validator/prepare"

The response contains your onboardingSecret. Copy it immediately it is only valid for 1 hour on DevNet (48 hours for manually issued secrets on TestNet/MainNet).

⚠️ Secrets are single-use and time-limited. If your deployment fails and you need to retry, request a new secret from your sponsor.

Step 5: Deploy via Docker Compose (DevNet)

This is the fastest path to a running validator. The Docker Compose setup bundles the participant node, validator backend, wallet UI, and CNS UI into a single orchestrated deployment.

Download and Extract the Bundle

01# Download the latest Splice release bundle02curl -L https://github.com/hyperledger-labs/splice/releases/latest/download/splice-node.tar.gz \03  -o splice-node.tar.gz04tar -xzf splice-node.tar.gz05cd splice-node/docker-compose/

Configure Your Environment

Create your .env file from the provided template and populate it:

01cp .env.example .env

Edit .env with the values prepared in the previous steps:

01# .env file key variables02 03# Network04MIGRATION_ID=9                            # Get current value from your sponsor or docs05SPONSOR_SV_URL=https://sv.sv-1.dev.global.canton.network.sync.global06 07# Validator Identity08PARTY_HINT=myOrg-myValidator-1            # Format: <org>-<function>-<enumerator>09 10# OIDC Auth (for production skip for unauthenticated DevNet quickstart)11AUTH_OIDC_AUTHORITY=https://YOUR_TENANT.auth0.com/12AUTH_OIDC_CLIENT_ID=your-client-id13AUTH_OIDC_CLIENT_SECRET=your-client-secret14WALLET_ADMIN_USER=auth0|your-admin-sub

Start the Validator Node

01./start.sh \02  -s "<SPONSOR_SV_URL>" \03  -o "<ONBOARDING_SECRET>" \04  -p "<PARTY_HINT>" \05  -m "<MIGRATION_ID>"

A real example for DevNet:

01./start.sh \02  -s "https://sv.sv-1.dev.global.canton.network.sync.global" \03  -o "abc123...your-secret..." \04  -p "acmeCorp-primaryValidator-1" \05  -m "9"

The node will pull Docker images, initialize its PostgreSQL database, connect to the Global Synchronizer, and complete onboarding. This typically takes 3-10 minutes on first boot. Subsequent restarts are much faster.

Stop and Restart

01# Stop the node (data is preserved in Docker volumes)02./stop.sh03 04# Restart using the same parameters05# The -o flag is still required but the secret value can be empty after initial onboarding06./start.sh -s "<SPONSOR_SV_URL>" -o "" -p "<PARTY_HINT>" -m "<MIGRATION_ID>"

Systemd Integration (Optional)

If you want the validator to survive reboots automatically:

01# /etc/systemd/system/canton-validator.service02[Unit]03Description=Canton Validator Node04After=docker.service05Requires=docker.service06 07[Service]08Type=oneshot09RemainAfterExit=true10WorkingDirectory=/home/ubuntu/splice-node/docker-compose11ExecStart=/bin/bash start.sh -s "SPONSOR_URL" -o "" -p "PARTY_HINT" -m "MIGRATION_ID"12ExecStop=/bin/bash stop.sh13 14[Install]15WantedBy=multi-user.target

01sudo systemctl daemon-reload02sudo systemctl enable canton-validator03sudo systemctl start canton-validator

Step 6: Kubernetes Deployment (Production)

For operators running on Kubernetes, the official Helm charts deploy the validator node along with wallet and CNS UIs and wire up all the service interconnects automatically.

Prerequisites Check

01kubectl version --client02helm version

Create a Dedicated Namespace

01kubectl create namespace canton-validator02kubectl config set-context --current --namespace=canton-validator

Create Kubernetes Secrets

01# OIDC credentials02kubectl create secret generic oidc-credentials \03  --from-literal=clientId="YOUR_CLIENT_ID" \04  --from-literal=clientSecret="YOUR_CLIENT_SECRET" \05  -n canton-validator06 07# Docker registry credentials (for pulling private images)08kubectl create secret docker-registry canton-registry \09  --docker-server=ghcr.io \10  --docker-username=YOUR_GITHUB_USER \11  --docker-password=YOUR_GITHUB_PAT \12  -n canton-validator

Configure Your Helm Values File

Create a validator-values.yaml with your deployment-specific config:

01# validator-values.yaml02 03validator:04  name: "acmeCorp-primaryValidator-1"05  onboardingSecret: "YOUR_ONBOARDING_SECRET"06  migrationId: 907  sponsorSvUrl: "https://sv.sv-1.dev.global.canton.network.sync.global"08 09  auth:10    oidcAuthority: "https://YOUR_TENANT.auth0.com/"11    clientId: "YOUR_CLIENT_ID"12    ledgerApiAudience: "https://canton.network.global"13    validatorApiAudience: "https://canton.network.global"14    walletAdminUser: "auth0|your-admin-user-sub"15 16  participant:17    adminApiPort: 500218    ledgerApiPort: 500119 20  topUp:21    enabled: true22    targetThroughput: 2048       # bytes/sec; adjust based on expected traffic23    minTopupIntervalSeconds: 6024 25  healthProbes:26    enabled: true27 28postgresql:29  host: "your-postgres-host.rds.amazonaws.com"30  port: 543231  database: "canton_validator"32  username: "canton_user"33  existingSecret: "postgres-credentials"34 35ingress:36  enabled: true37  className: "nginx"38  walletHostname: "wallet.mycompany.com"39  cnsHostname: "cns.mycompany.com"40  tls: true

Deploy the Helm Chart

01helm upgrade --install canton-validator ./helm/validator \02  -f validator-values.yaml \03  -n canton-validator \04  --wait \05  --timeout 10m

Check Pod Status

01kubectl get pods -n canton-validator02 03# Expected output (all pods should be Running):04# NAME                                     READY   STATUS    RESTARTS   AGE05# participant-xxxxxxxxx-xxxxx              1/1     Running   0          5m06# validator-backend-xxxxxxxxx-xxxxx        1/1     Running   0          5m07# wallet-web-ui-xxxxxxxxx-xxxxx            1/1     Running   0          5m08# cns-web-ui-xxxxxxxxx-xxxxx               1/1     Running   0          5m09# postgres-xxxxxxxxx-xxxxx                 1/1     Running   0          5m

Step 7: Verify Connectivity

Before declaring your node live, verify it can actually reach the Global Synchronizer.

Check Your Egress IP

01# Run this from your validator machine/cluster02curl -s https://api.ipify.org

Confirm this IP matches what you submitted to your sponsor for whitelisting.

Test Scan Connectivity

01# Install jq if not present02sudo apt-get install -y jq03 04# Test connectivity to SV Scan endpoints05(set -o pipefail06CURL='curl -fsS -m 5 --connect-timeout 5'07for url in $($CURL https://scan.sv-1.dev.global.canton.network.sync.global/api/scan/v0/scans \08  | jq -r '.scans[].scans[].publicUrl'); do09  echo -n "$url: "10  $CURL "$url/api/scan/version" | jq -r '.version'11done)

A healthy output looks like:

01https://scan.sv-2.dev.global.canton.network.digitalasset.com: 0.3.602https://scan.sv.dev.global.canton.network.tradeweb.com: 0.3.603https://scan.sv-1.dev.global.canton.network.cumberland.io: 0.3.604https://scan.sv-1.dev.global.canton.network.sync.global: 0.3.6

If lines return errors where version numbers should appear, your IP has not been added to the allowlist yet, or the SV you're checking is momentarily unreachable. You need at least 2/3 of SVs reachable for your validator to function.

Test Sequencer Connectivity

01# Check that SV sequencer endpoints are reachable02curl -s https://sequencer-1.sv-1.dev.global.canton.network.sync.global/health03# Expected: { "status": "SERVING" }

Get Console Access

For Docker Compose deployments, you can drop into the Canton Admin Console:

01# Create a console config02cat > console.conf <<EOF03canton {04  remote-participants {05    participant {06      admin-api { port = 5002; address = participant }07      ledger-api { port = 5001; address = participant }08    }09  }10  features.enable-preview-commands = yes11  features.enable-testing-commands = yes12  features.enable-repair-commands = yes13}14EOF15 16# Launch the console17docker run -it --rm \18  --network splice-validator \19  -v $(pwd)/console.conf:/app/app.conf \20  ghcr.io/digital-asset/decentralized-canton-sync/docker/canton:latest \21  --console

For Kubernetes, use a debug pod:

01POD_NAME=$(kubectl get pods -n canton-validator -l app=participant -o name | head -1)02kubectl debug "${POD_NAME}" \03  --image "$(kubectl get pod "${POD_NAME}" -o json | jq -re '.spec.containers[0].image')" \04  -i -t -- bash

Step 8: Access Your Wallet UI

Once the node is running and connected, the wallet UI is your primary interface for managing parties, canton coin balances, and validator operations.

Docker Compose: Navigate to http://wallet.localhost in your browser.

Kubernetes: Navigate to https://wallet.mycompany.com (or whatever hostname you configured in Helm values).

First Login

On first access, you will be prompted to set a password via Keycloak. Save these credentials they are your validator operator credentials.

If you need to update the wallet user password later via Keycloak:

1. Log into the Keycloak admin console
2. Switch to the validator realm from the top-left dropdown
3. Navigate to Users → search for <VALIDATOR_NAME>_walletuser
4. Open Credentials tab → set new password → toggle Temporary to OFF
5. Click Reset Password

Self-Feature on DevNet

On DevNet, you can self-feature your validator operator party to start receiving liveness rewards:

1. Log into the Wallet UI as the validator operator user
2. Tap to airdrop yourself 20 CC (DevNet test coins)
3. In the validator settings, feature your operator party as the exchange party

On TestNet/MainNet, featuring requires SV approval contact your sponsor.

Step 9: Promote to TestNet & MainNet

Once your validator is stable on DevNet, you can apply to connect to TestNet and eventually MainNet.

TestNet Requirements

• Your validator must have been approved for MainNet by the Tokenomics Committee of the Global Synchronizer Foundation first TestNet approval is bundled with MainNet approval.
• Submit your application at sync.global/validator-request
• Provide a separate static egress IP for TestNet (distinct from your DevNet IP)
• Your sponsor will submit the IP whitelisting request to the SV operators

MainNet

MainNet access is granted after the Tokenomics Committee review, which typically takes around two weeks. Once approved:

1. Your sponsor submits the MainNet IP to the SV operators for whitelisting
2. You receive a MainNet onboarding secret from your sponsor
3. Deploy a separate validator instance (do not reuse your DevNet/TestNet deployment) using the MainNet bundle and secret
4. Your node connects to the MainNet Global Synchronizer and begins earning live Canton Coin rewards

🔑 Never reuse the same PostgreSQL database or Docker volumes across networks. Each network (DevNet, TestNet, MainNet) must be a fully isolated deployment with its own persistent storage.

Rewards, Traffic & Canton Coin

Understanding Canton Coin economics helps you configure your node correctly from day one.

Liveness Rewards

Validators earn CC for simply keeping their nodes online and connected to the Global Synchronizer. There is no staking, no slashing, and no minimum uptime threshold but significant downtime means you miss out on rewards and may need to catch up on ledger state.

Traffic Fees

Every transaction you submit to the Global Synchronizer consumes network traffic, which must be paid for in CC. The recommended starting configuration is:

01topUp:02  enabled: true03  targetThroughput: 2048     # 2 kB/s sufficient for ~1 tx/10 seconds04  minTopupIntervalSeconds: 60

This tells the validator backend to automatically purchase traffic using your operator party's CC balance when it falls below the calculated threshold. Adjust targetThroughput based on your actual transaction volume.

Recommended Setup for Self-Funding Traffic

Use your validator operator party as both the exchange party and the traffic funding source. This creates a self-sustaining loop:

1. Node earns liveness rewards in CC → deposited to operator party
2. Auto-topup purchases traffic using that CC balance
3. Traffic is consumed by your transactions
4. More transactions → more usage → more rewards over time

Backups & Disaster Recovery

Regular backups are optional for day-to-day operation and needed to recover your Canton Coin after a catastrophic failure.

What to Back Up

Identities Backup (Most Important)

Super Validators retain enough information to help you recover your Canton Coin from an identities backup. They do not retain transaction details from non-SV applications. If you run third-party apps on your validator, only your own backups can recover that data.

For Docker Compose deployments:

01# Trigger an identities dump via the wallet UI02# Settings → Backup → Create Dump → enter wallet user password03 04# Or via API05curl -X POST http://localhost:5003/api/validator/v0/admin/backup/identity \06  -H "Authorization: Bearer <ADMIN_TOKEN>" \07  -o identities-backup-$(date +%Y%m%d).json

Back up your PostgreSQL data with standard pg_dump:

01docker exec canton-postgres pg_dump -U splice splice_validator \02  > backup-$(date +%Y%m%d-%H%M%S).sql

Store backups in a separate location from your validator host an S3 bucket, GCS bucket, or off-site storage.

Monitoring & Observability

Docker Compose (Basic)

The Docker Compose deployment does not include a monitoring stack. For basic health checks, use:

01# Check all container health02docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"03 04# Follow validator backend logs05docker logs -f validator-backend06 07# Follow participant logs08docker logs -f participant

Kubernetes (Full Stack)

The Kubernetes Helm deployment supports Grafana dashboards out of the box. Key metrics available:

• Traffic usage per party and per transaction type
• CC balances for local parties (operator party, exchange party, treasury party)
• Ledger offset lag how far behind the validator is from the tip of the chain
• Container health and resource utilization

Enable monitoring in your Helm values:

01monitoring:02  enabled: true03  grafana:04    enabled: true05    adminPassword: "your-grafana-password"06  prometheus:07    enabled: true

Health Check Endpoints

01# Validator backend health02curl http://localhost:5003/api/validator/v0/readyz03 04# Participant node health05curl http://localhost:5002/health06 07# Expected: HTTP 200 with {"status":"SERVING"} or similar

Common Errors & Troubleshooting

Node fails to connect to sequencer

Symptom: Logs show repeated connection failures to SV sequencer endpoints.

Cause: Your egress IP has not been added to the SV firewall allowlist, or you are running the check from a different IP than what you submitted.

Fix: Confirm your egress IP with curl -s https://api.ipify.org from the validator host, then ask your sponsor to verify whitelisting.

Onboarding secret expired or already used

Symptom: Start script fails with invalid onboarding secret or secret already consumed.

Cause: Onboarding secrets are one-time use and expire after 48 hours (1 hour for self-generated DevNet secrets).

Fix: Request a new secret from your sponsor. On DevNet, re-run the curl -X POST .../devnet/onboard/validator/prepare call.

Wallet UI shows "Unauthorized"

Symptom: Accessing http://wallet.localhost redirects to a login error.

Cause: OIDC configuration mismatch the sub in the issued JWT does not match the WALLET_ADMIN_USER configured in .env.

Fix: Check the sub field of the JWT your OIDC provider is issuing (you can decode it at jwt.io), and set WALLET_ADMIN_USER to exactly that value.

Docker Compose containers keep restarting

Symptom: docker ps shows containers in a restart loop.

Cause: Usually a PostgreSQL initialization failure or a misconfigured environment variable.

Fix:

01# Check logs for the specific failing container02docker logs participant --tail 10003docker logs validator-backend --tail 10004 05# Most common fix: wipe and re-initialize the database06./stop.sh07docker volume rm compose_postgres-splice08./start.sh -s "..." -o "NEW_SECRET" -p "..." -m "..."

⚠️ Wiping the volume means losing all existing data. Only do this on a fresh install or if you have a backup.

Less than 2/3 of Scan endpoints reachable

Symptom: Connectivity check shows only 1-2 out of 10 SVs responding.

Cause: Your IP may be partially whitelisted, or some SVs are temporarily down.

Fix: Wait 10-15 minutes and re-run the connectivity check. If it persists, contact your sponsor to confirm full whitelisting across all SV operators.

Summary

Setting up a Canton validator node follows a clear sequence: secure a sponsor, set a static egress IP, configure OIDC authentication, obtain an onboarding secret, deploy via Docker Compose or Kubernetes, verify sequencer connectivity, and access the wallet UI. From there you can apply to graduate to TestNet and MainNet, where your node becomes eligible to earn live Canton Coin liveness rewards.

The key operational principles are: keep your identities backed up, use a dedicated IP per network, never share database volumes across networks, and configure auto-topup so your traffic costs are funded automatically by your own rewards.

The software is fully open-source under the Splice project on GitHub. There is no slashing, no minimum stake, and no penalty for downtime though staying online maximizes your reward accrual and keeps your ledger state current.

Canton Network Docs: docs.dev.sync.global

Splice Source Code: github.com/hyperledger-labs/splice

Validator Application Form: sync.global/validator-request

Canton Foundation: canton.foundation/validators

About Us

At SC Audit Studio, we specialize in protocols security assessments. Our team of experts has worked with companies like Aave, 1Inch and several more to conduct security assessments. Partner with us to enhance your project's security and gain peace of mind.

Reach out to us for queries and security assessments!