CCPEDIAby Unity Nodes
Documentation/DamlView on Daml ↗

Covalidating Partner Onboarding

​
1. Configure your Validator Node

Ensure you are running the same splice version on your node as is run on the primary validator and other covalidating node(s), keeping up to date with the Canton Foundation schedule.
Create / configure the validator node which you will use as your covalidating node. If creating a new node, follow the Canton Network Validator Onboarding Process.

​
2. Create GitHub App for Reading DAR Repository

Before deploying the service, first a GitHub App must be created within your organization’s GitHub account in order to access the shared DAR repository.
Creating a GitHub App requires GitHub Organization Owner permissions.A single GitHub App can be reused for multiple Covalidation Service deployments within the same organization.
The GitHub App setup process entails:

​
Create a GitHub App in your organization

Navigate to:
Organization Settings → Developer Settings → GitHub Apps
Select New GitHub App.

​
Configure the application

Use the following settings.
SettingValue
Name<Company Name> Covalidation
DescriptionA description such as Used by the Covalidation Service to synchronize DARs
Homepage URLYour organization’s website
Expire user authorization tokensDisabled
WebhooksDisabled

​
Repository Permissions

Configure the following permissions.
PermissionAccess
ContentsRead-only
WebhooksRead & Write

​
Installation Scope

Select:
Any account
Then create the application.

​
Record Required Information

After the application has been created, save the following values.
ItemRequired For
Public LinkPrimary validator GitHub App
App IDHelm configuration
Private KeyKubernetes Secret

​
Generate Private Key

Generate a Private Key and store it as a Kubernetes Secret in the namespace where the chart will be installed. Example: 
kubectl create secret generic github-app-private-key \
  --from-file=private-key.pem

​
Share Your GitHub App Details with Primary Validator

After creating the GitHub App:
  1. Send the Public Link to the primary validator.
  2. Ask them to install the application into the DAR repository.
  3. Request the Installation ID from the primary validator.

​
Primary Validator installs GitHub App into Organization of DAR repository and Provides Installation ID

Once installed, the primary validator will provide you the Installation ID, which is required when configuring the Helm chart.

​
3. Exchange Details and Configure and Install Your Covalidation Service

  • Gather details from the Primary Validator and Covalidating operator on DAR repository, GitHub App installation ID and participant IDs so that each co-validator can be configured correctly.
  • Configure and Install the Covalidation Service Helm Chart

​
Install the Covalidation Service Helm Chart

​
Setup

Before installing Covalidation Service, ensure you have:

Prerequisites

  • Access to your GitHub organization
  • A primary validator willing to share DARs
  • A Kubernetes cluster
  • A Kubernetes namespace for the deployment
  • Helm 3.x (> 3.17.0)
  • Kubernetes Secrets containing:
  • GitHub App private key
  • Participant OIDC client secret
Deploy the service using Helm. 
helm upgrade --install \
  covalidation-service \
  -n some-namespace \
  -f values.yaml \
  oci://europe-docker.pkg.dev/da-images/public/charts/covalidation-service:latest

​
Configuration

A minimal configuration looks like the following. 
covalidator:
  dars:
    github:
      appID: <GitHub App ID>
      installID: <GitHub Installation ID>

      privateKey:
        secretKeyRef:
          name: github-app-private-key
          key: private-key.pem

    repo:
      owner: <Primary validator GitHub organization>
      repo: <DAR repository>
      # Optional: The branch and directory containing the dars
      # branch: <`main` by default>
      # dir: <path/to/some/dir>

  participant:
    id: <Participant ID>

    oidc:
      oauthDomain: <OIDC issuer URL (e.g., https://issuer.example.com)>
      clientID: <Client ID>
      clientSecret:
        secretKeyRef:
          name: participant-oidc-secret
          key: client-secret
      # Optional: audience
      # audience: <Your validator audience>

      # Optional: scopes
      # scopes:
      #     - <some scope>

    endpoints:
      ledgerApi: participant.namespace:5001
      adminApi: participant.namespace:5002

  replication:
    participants:
      primary: <Primary participant ID>

      # List other covalidator nodes (if any)
      covalidators:
        - <Other covalidator's participant ID>
  monitoring:
    otel:
      endpointURL: <OTEL Monitoring URL>

  # OPTIONAL: sync interval
  # syncInterval:
  #   # Optional: frequency with which party topology events are synchronized
  #   partyTopologyPolling: 30s
  #
  #   # Optional: frequency with which package upload and vetting are synchronized
  #   packagePolling: 5m

  # OPTIONAL: log level
  # log:
  #   format: auto
  #   level: debug

​
Configuration Reference

GitHub
FieldDescription
appIDGitHub App ID
installIDInstallation ID provided by the primary validator
privateKey.secretKeyRefKubernetes Secret containing the GitHub App private key
DAR Repository
FieldDescription
ownerGitHub organization containing the DAR repository
repoRepository name
branchOptional branch (defaults to main)
dirOptional directory containing DAR files
Participant
FieldDescription
idParticipant identifier
oauthDomainOIDC issuer URI
audienceOIDC audience
scopesOIDC scopes
clientIDOIDC client ID
clientSecretKubernetes Secret containing the OIDC client secret
ledgerApiLedger API endpoint
adminApiAdmin API endpoint
Replication
FieldDescription
primaryPrimary validator participant ID
covalidatorsAdditional covalidator participant IDs
Monitoring
FieldDescription
endpointURLOTEL monitoring URL and port
Log
FieldDescription
formatFormat of the logger (text, json, auto)
levelLevel of logger (debug, info, warning, error)
Sync Interval
FieldDescription
partyTopologyPollingInterval for party topology sync
packagePollingInterval for package upload and vetting sync
Kubernetes Secrets
The chart expects existing Kubernetes Secrets.
GitHub Private Key
privateKey:
  secretKeyRef:
    name: github-app-private-key
    key: private-key.pem
Participant Client Secret
clientSecret:
  secretKeyRef:
    name: participant-oidc-secret
    key: client-secret

​
Deployment Flow

​
Uninstall

Remove the deployment with Helm. 
helm uninstall covalidation-service -n some-namespace
This removes the Kubernetes resources created by the chart but does not delete Kubernetes Secrets or the GitHub App.

​
Release Notes

Notable changes to the Helm chart are documented below.

​
2026-08-13

​
0.8.1

  • Party Topology Polling Change party topology polling default to 30s, and make it configurable through syncInterval configuration in helm chart.
  • Party Topology Acceptance Only auto-accept new party topology onboardings, but do not accept topology changes for existing parties.
  • Multi-platform Docker Image Support The produced image is now multi-platform and can run on either ARM or AMD Linux platforms.