Canton Network Validator Setup Guide

This guide deploys a Canton validator with the official Splice Docker Compose bundle. The main flow registers on TestNet; DevNet differences are called out explicitly so you do not mix network-specific values.

info

The versions and parameters below were checked against the official Sync Global validator operator docs on 2026-05-20:

TestNet docs: docs.test.sync.global, Splice node 0.6.3
DevNet docs: docs.dev.sync.global, Splice node 0.6.4

DevNet vs TestNet

Setting	TestNet	DevNet
Network value	`testnet`	`devnet`
Bundle version	`0.6.3`	`0.6.4`
Migration ID	`3`	`7`
Sponsor SV URL	`https://sv.sv-2.test.global.canton.network.com`	`https://sv.sv-2.dev.global.canton.network.com`
Onboarding secret	Request from your sponsoring SV after approval	Fetch from the DevNet sponsor API
Environment stability	Longer-lived test environment	Fast-moving environment, may reset more often

warning

TestNet onboarding is not the same as DevNet onboarding. For TestNet, contact the Canton Network team or your sponsoring SV, complete the MainNet readiness approval process, provide your egress IP address for allowlisting, and obtain a one-time onboarding secret.

Prerequisites

System Requirements

Component	Recommended
OS	Ubuntu 22.04/24.04 LTS
CPU	4+ vCPU
Memory	16GB+ RAM for testing, 32GB+ preferred
Storage	200GB+ SSD
Network	Stable public egress IP, HTTPS outbound access

Required Information

Prepare these values before starting:

Variable	Description
`NETWORK`	`testnet` for this guide, or `devnet` when following the DevNet section
`MIGRATION_ID`	Network migration ID from the matching official docs
`SPONSOR_SV_URL`	Sponsor super validator URL for the selected network
`ONBOARDING_SECRET`	One-time validator onboarding secret
`VALIDATOR_PARTY_HINT`	Human-readable party hint for your validator
`VALIDATOR_USER_NAME`	Wallet/admin user name
`VALIDATOR_AUTH_AUDIENCE`	OIDC audience when enabling authenticated wallet/scan access
`VALIDATOR_AUTH_JWKS_URL`	OIDC JWKS URL when enabling authenticated wallet/scan access

Step 1: Install Docker

sudo -i

apt-get update
apt-get install -y ca-certificates curl gnupg lsb-release jq wget tar

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${VERSION_CODENAME}") stable" \
  > /etc/apt/sources.list.d/docker.list

apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

systemctl enable --now docker
docker --version
docker compose version

Step 2: Prepare TestNet Variables

Replace the placeholders with values from your sponsoring SV or Canton Network contact.

export CANTON_DIR=/data/canton-validator
export SPLICE_VERSION=0.6.3
export NETWORK=testnet
export MIGRATION_ID=3
export SPONSOR_SV_URL=https://sv.sv-2.test.global.canton.network.com

export ONBOARDING_SECRET=PASTE_TESTNET_ONBOARDING_SECRET_HERE
export VALIDATOR_PARTY_HINT=your-validator-party
export VALIDATOR_USER_NAME=your-wallet-user

mkdir -pv ${CANTON_DIR}
cd ${CANTON_DIR}

tip

Keep ONBOARDING_SECRET out of shell history on shared systems. It is intended for first-time onboarding and should be treated like a credential.

Step 3: Download the Official Compose Bundle

wget -O splice-node.tar.gz \
  https://github.com/hyperledger-labs/splice/releases/download/splice-node-${SPLICE_VERSION}/${SPLICE_VERSION}_splice-node.tar.gz

tar xzvf splice-node.tar.gz
cd compose

The extracted compose directory contains the official docker-compose.yml, helper scripts, and configuration templates used by Sync Global's validator operator guide.

Step 4: Configure Authentication

The official startup command supports authenticated wallet and scan access through OIDC. For production-like TestNet operations, configure an identity provider such as Auth0, Okta, or Keycloak and set:

export VALIDATOR_AUTH_AUDIENCE=YOUR_OIDC_AUDIENCE
export VALIDATOR_AUTH_JWKS_URL=https://YOUR_ISSUER/.well-known/jwks.json

For a private lab deployment, you can bind the UI to localhost or restrict access with a reverse proxy while you finish OIDC setup. Do not expose unauthenticated wallet or validator admin endpoints to the public internet.

Step 5: Start the TestNet Validator

Run the official startup helper from the extracted compose directory:

IMAGE_REPO=ghcr.io/hyperledger-labs/splice \
IMAGE_VERSION=${SPLICE_VERSION} \
NETWORK=${NETWORK} \
MIGRATION_ID=${MIGRATION_ID} \
SPONSOR_SV_URL=${SPONSOR_SV_URL} \
ONBOARDING_SECRET=${ONBOARDING_SECRET} \
VALIDATOR_AUTH_AUDIENCE=${VALIDATOR_AUTH_AUDIENCE} \
VALIDATOR_AUTH_JWKS_URL=${VALIDATOR_AUTH_JWKS_URL} \
./start.sh -w -s -p ${VALIDATOR_PARTY_HINT} -u ${VALIDATOR_USER_NAME} -a

Expected result:

Docker Compose pulls the official images from ghcr.io/hyperledger-labs/splice.
PostgreSQL and validator services start locally.
The validator uses the onboarding secret to join TestNet through the sponsor SV.
Wallet and scan-related services become available through the configured local endpoints.

Step 6: Verify Operation

docker compose ps
docker compose logs -f validator-app
docker compose logs --tail=100

Check that:

Containers are running or healthy.
Logs do not show repeated authentication, migration ID, sponsor URL, or onboarding failures.
The validator appears in the expected TestNet view after the sponsor onboarding completes.

DevNet Deployment Differences

Use DevNet only when you intentionally want the faster-moving developer network. Start from a separate directory:

export CANTON_DIR=/data/canton-validator-devnet
export SPLICE_VERSION=0.6.4
export NETWORK=devnet
export MIGRATION_ID=7
export SPONSOR_SV_URL=https://sv.sv-2.dev.global.canton.network.com

mkdir -pv ${CANTON_DIR}
cd ${CANTON_DIR}

export ONBOARDING_SECRET=$(
  curl -sS ${SPONSOR_SV_URL}/api/sv/v0/devnet/onboard/validator/prepare -X POST
)

Then download splice-node-${SPLICE_VERSION} and run the same ./start.sh command with the DevNet values.

warning

DevNet versions can move ahead of TestNet. At the time checked, DevNet used 0.6.4 while TestNet used 0.6.3. Do not upgrade a TestNet validator to the DevNet bundle unless the TestNet docs announce that version.

Maintenance

Stop and Restart

cd /data/canton-validator/compose

docker compose ps
docker compose restart
docker compose logs -f

Upgrade

Confirm the new bundle version in the matching official docs.
Back up the validator data and PostgreSQL volumes.
Download the new splice-node bundle.
Re-run ./start.sh with the updated IMAGE_VERSION, NETWORK, and MIGRATION_ID.

cd /data/canton-validator/compose
docker compose down

# After downloading and extracting the new bundle:
IMAGE_REPO=ghcr.io/hyperledger-labs/splice \
IMAGE_VERSION=NEW_VERSION \
NETWORK=testnet \
MIGRATION_ID=NEW_MIGRATION_ID \
SPONSOR_SV_URL=${SPONSOR_SV_URL} \
VALIDATOR_AUTH_AUDIENCE=${VALIDATOR_AUTH_AUDIENCE} \
VALIDATOR_AUTH_JWKS_URL=${VALIDATOR_AUTH_JWKS_URL} \
./start.sh -w -s -p ${VALIDATOR_PARTY_HINT} -u ${VALIDATOR_USER_NAME} -a

Do not reuse ONBOARDING_SECRET during a normal restart or upgrade unless the official guide or your sponsoring SV tells you to re-onboard.

Backups

Back up the validator's Compose directory, .env or exported deployment variables, and Docker volumes before upgrades:

cd /data/canton-validator
docker compose -f compose/docker-compose.yml ps
docker volume ls | grep -i splice

For production-like TestNet operations, use a scheduled PostgreSQL backup and store secrets outside the repository.

Troubleshooting

Symptom	What to Check
Onboarding fails	Confirm `ONBOARDING_SECRET`, `SPONSOR_SV_URL`, approval status, and egress IP allowlisting
Migration error	Ensure `MIGRATION_ID` matches the selected network docs
Images fail to pull	Confirm `IMAGE_REPO`, `IMAGE_VERSION`, and GitHub Container Registry access
Wallet or scan login fails	Verify `VALIDATOR_AUTH_AUDIENCE`, `VALIDATOR_AUTH_JWKS_URL`, issuer configuration, and token audience
Containers restart repeatedly	Inspect `docker compose logs --tail=200` and confirm memory/disk capacity

DevNet vs TestNet​

Prerequisites​

System Requirements​

Required Information​

Step 1: Install Docker​

Step 2: Prepare TestNet Variables​

Step 3: Download the Official Compose Bundle​

Step 4: Configure Authentication​

Step 5: Start the TestNet Validator​

Step 6: Verify Operation​

DevNet Deployment Differences​

Maintenance​

Stop and Restart​

Upgrade​

Backups​

Troubleshooting​

Official References​