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.

Setting	Value
Name	`<Company Name> Covalidation`
Description	A description such as `Used by the Covalidation Service to synchronize DARs`
Homepage URL	Your organization’s website
Expire user authorization tokens	Disabled
Webhooks	Disabled

Repository Permissions

Configure the following permissions.

Permission	Access
Contents	Read-only
Webhooks	Read & Write

Installation Scope

Select:

Any account

Then create the application.

Record Required Information

After the application has been created, save the following values.

Item	Required For
Public Link	Primary validator GitHub App
App ID	Helm configuration
Private Key	Kubernetes 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

After creating the GitHub App:

Send the Public Link to the primary validator.
Ask them to install the application into the DAR repository.
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 confirmation nodes (if any)
      covalidators:
        - <Other covalidator's participant ID>

      # List observation nodes (if any) -
      # Available from version 0.9.0+
      observers:
        - <Other observer'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

Field	Description
`appID`	GitHub App ID
`installID`	Installation ID provided by the primary validator
`privateKey.secretKeyRef`	Kubernetes Secret containing the GitHub App private key

DAR Repository

Field	Description
`owner`	GitHub organization containing the DAR repository
`repo`	Repository name
`branch`	Optional branch (defaults to `main`)
`dir`	Optional directory containing DAR files

Participant

Field	Description
`id`	Participant identifier
`oauthDomain`	OIDC issuer URI
`audience`	OIDC audience
`scopes`	OIDC scopes
`clientID`	OIDC client ID
`clientSecret`	Kubernetes Secret containing the OIDC client secret
`ledgerApi`	Ledger API endpoint
`adminApi`	Admin API endpoint

Replication

Field	Description
`primary`	Primary validator participant ID
`covalidators`	Additional covalidator participant IDs
`observers`	Additional observer participant IDs (available from version 0.9.0+)

Monitoring

Field	Description
`endpointURL`	OTEL monitoring URL and port

Log

Field	Description
`format`	Format of the logger (text, json, auto)
`level`	Level of logger (debug, info, warning, error)

Sync Interval

Field	Description
`partyTopologyPolling`	Interval for party topology sync
`packagePolling`	Interval 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.

​1. Configure your Validator Node

​2. Create GitHub App for Reading DAR Repository

​Create a GitHub App in your organization

​Configure the application

​Repository Permissions

​Installation Scope

​Record Required Information

​Generate Private Key

​Share Your GitHub App Details with Primary Validator

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

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

​Install the Covalidation Service Helm Chart

​Setup

Prerequisites

​Configuration

​Configuration Reference

GitHub

DAR Repository

Participant

Replication

Monitoring

Log

Sync Interval

Kubernetes Secrets

GitHub Private Key

Participant Client Secret

​Deployment Flow

​Uninstall

1. Configure your Validator Node

2. Create GitHub App for Reading DAR Repository

Create a GitHub App in your organization

Configure the application

Repository Permissions

Installation Scope

Record Required Information

Generate Private Key

Share Your GitHub App Details with Primary Validator

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

3. Exchange Details and Configure and Install Your Covalidation Service

Install the Covalidation Service Helm Chart

Setup

Configuration

Configuration Reference

Deployment Flow

Uninstall