# Home
CatalyX by IntellectEU is a product suite designed to streamline how enterprises deploy, manage, and operate blockchain infrastructure and applications.
## CatalyX Product Docs
Explore the dedicated documentation for each CatalyX product. Additional products are in development and will be documented here as they become available.
Cover image
CatalyX Blockchain Manager
Infrastructure management for enterprise-ready blockchain applications.
***
## CatalyX Support Center
Need help with a CatalyX product? Raise a ticket through the Service Desk, browse the documentation, or reach the team directly via Slack or email.
***
# CatalyX Blockchain Manager
CatalyX Blockchain Manager (CAT-BM) is an infrastructure management and application deployment platform for enterprise DLT and digital assets.
CAT-BM enables enterprises to **build, deploy, manage, and scale** blockchain infrastructure and applications with high automation and guaranteed uptime:
* **Build**: choose your protocol, launch applications, and onboard participants.
* **Deploy**: automate setups rapidly through a UI and API that abstracts away technical complexity.
* **Manage**: highly responsive support, auto-recovery, and observability to resolve issues quickly.
* **Scale**: cloud-agnostic deployment with enterprise-grade HA, monitoring, and security.
***
### CatalyX Blockchain Manager Overview
Key Features
1. **Self-Service Management Console**
Manage networks, validator nodes, and other components of your infrastructure through an intuitive self-service console.
2. **Enterprise-Grade Security**
Integrated secrets management (HashiCorp Vault, Kubernetes Secrets), custody provider connectivity, and KMS-enabled key infrastructure — with SOC 2 certification in progress.
3. **High-Availability & Monitoring**\
Benefit from built-in failover, disaster recovery, and multi-site high availability, supported by comprehensive monitoring.
4. **Cloud-Agnostic Deployment**
Deploy across any cloud provider, hybrid environment, or on-premises infrastructure — without vendor lock-in.
5. **Intuitive UI & API**\
CAT-BM streamlines access to all functionality, including CI/CD hooks.
6. **Expert Operational Support**\
Access highly qualified, responsive support from a DevOps team with 11+ years of enterprise-grade blockchain expertise.
Commercial Models
| Tier | Positioning | Operational responsibility |
| -------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
| **Basic** | Validator setup & platform access | Self-managed |
| **Managed** | Fully managed operations | Self-managed *or* managed by IntellectEU |
| **Enterprise** | Enterprise-grade managed infrastructure with custom SLAs | Self-managed *or* managed by IntellectEU, custom deployment |
Visit Website
{% embed url="" %}
***
### Supported Protocols
Catalyst Blockchain Manager supports a range of different protocols. More details and dedicated documentation can be found for each. Dive into each protocol-specific docs to get started.
***
# Canton Network
# Version 2.0
# Getting Started
This section covers how to get started with CatalyX Blockchain Manager (CAT-BM) 2.0 for the Canton Network.
CatalyX Blockchain Manager (CAT-BM) 2.0 is a Kubernetes-native platform for deploying and operating Canton Network validator nodes, with GitOps-driven operations and full lifecycle automation for Canton Network components.
{% hint style="info" %}
CAT-BM 2.0 is a complete rewrite succeeding the 1.x line: a new operator, a new REST API, and a rebuilt web platform. You declare a validator as a single Kubernetes custom resource, and the platform provisions the entire stack (i.e. the Canton participant node, the validator app, the Wallet and CNS UIs, and the authentication behind them). It then gives you a management plane and an API to operate it without direct cluster access.
{% endhint %}
## Documentation Overview
***
## Where to start
{% stepper %}
{% step %}
**Understand the shape of the system**
Read [Architecture](/catalyx-blockchain-manager/canton-network/version-2.0/architecture) to see how the operator, API, UI, and Canton nodes fit together.
{% endstep %}
{% step %}
**Install the platform**
Follow [Installation Instructions](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton) to check prerequisites and install the Helm chart into your cluster.
{% hint style="warning" %}
2.0 is **not an in-place upgrade** from 1.10 or 1.11. It installs fresh alongside or in place of an existing deployment. Contact IntellectEU support before planning a migration.
{% endhint %}
{% endstep %}
{% step %}
**Create your first validator**
Apply a `Validator` resource as described in [Create a Validator](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/create-a-validator).
{% endstep %}
{% step %}
**Operate it from the platform**
Open the [User Guide](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton) to learn what each screen shows and which operations it supports.
{% endstep %}
{% endstepper %}
# Introduction to Canton Network
This section covers the introduction to the Canton Network, including its core components, architecture, and key concepts relevant to operating nodes with CatalyX Blockchain Manager.
## What is Canton Network?
Canton Network is a public layer 1 blockchain designed for privacy-preserving transactions. Unlike traditional blockchains where all transactions are visible to all participants, Canton enables selective disclosure - parties see only the data they’re entitled to see.
{% embed url="" %}
## Core Concepts
Please refer to the Canton Network documentation to learn more about the core concepts of the Canton Network.
{% embed url="" %}
***
## Glossary
This section defines the key business and technical terms used throughout CatalyX Blockchain Manager and the Canton integration. Use it as the first reference when encountering unfamiliar terminology.
Business Concepts
| **Term** | **Definition** |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Party** | A **party** is an on-ledger identity in Canton—analogous to an address or account on other blockchains, but with explicit authorization semantics. |
| **Validator** | A **validator** hosts parties, stores their contract data, and participates in the Canton protocol. A validator contains a participant node (the Daml execution engine) plus a validator process. |
| **Super Validator** | A special Canton participant node that participates in network governance, permissioning, and topology management on the global sync domain. |
| **Splice** | The open-source governance and reward infrastructure for the Canton Network. |
| **CatalyX** | IntellectEU's suite of blockchain infrastructure products built on Canton and other protocols. |
| **CAT-BM** | CatalyX Blockchain Manager, IntellectEU's platform for deploying and operating Canton and other DLT infrastructure. |
| **CPM** | CatalyX Package Manager, the application registry for discovering, publishing, and downloading Canton applications. |
| **GSF / Canton Foundation** | Global Synchronizer Foundation, which governs the Global Sync Domain on Canton. |
Technical Concepts
| **Term** | **Definition** |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Ledger API** | The gRPC API exposed by Canton participant nodes for submitting and reading transactions. |
| **Admin API** | The API for managing participant configuration, parties, and packages. |
| **Topology** | The configuration of domains, participants, parties, and their relationships on the network. |
| **PartyToParticipant mapping** | The topology record that says which participants host a party, with what permission and confirmation threshold. |
| **Confirmation threshold** | How many confirming hosts must confirm each of a party's transactions. |
| **PQS (Participant Query Store)** | A queryable off-ledger store for Canton contract data. |
| **KMS driver** | Canton integration module that delegates key operations to an external KMS or HSM. |
| **WaaS** | Wallet-as-a-Service — an external key custody and signing service supported by CAT-BM. |
| **ArgoCD** | GitOps continuous-delivery tool used to synchronise desired state from Git into the Kubernetes cluster. |
| **Helm chart** | Kubernetes packaging format used to deploy Canton components. |
| **CRD (Custom Resource Definition)** | Kubernetes extension used by the CAT-BM Canton Operator to manage node lifecycle. |
| **CAT-BM Canton Operator** | Custom Kubernetes operator that watches CRDs and reconciles Canton component state. |
| **Round** | 10-minute cycle on Canton Network governing minting and distribution of Canton Coin. |
***
## Learn More
| **Resource** | **Purpose** |
| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [Canton Network Website](https://canton.network/) | Official Canton Network site |
| [Canton Network Docs](https://docs.canton.network/) | Official Canton Network documentation |
| [Canton Network Github](https://github.com/canton-network) | Canton Network repositories, including Splice |
| [Canton Network Whitepaper](https://www.digitalasset.com/hubfs/Canton/Canton%20Network%20-%20White%20Paper.pdf) | Official Canton Network whitepaper |
| [Digital Asset / Daml Documentation](https://docs.digitalasset.com/) | Canton and Daml technical documentation from Digital Asset |
| [Canton Foundation Website](https://canton.foundation/) | GSF governance, committees, and network information |
| [CIPs](https://github.com/canton-foundation/cips) | Canton Improvement Proposals |
***
# Technical Architecture
System context, high-level architecture, and design principles of CatalyX Blockchain Manager version 2.0 for the Canton Network.
CAT-BM is a Kubernetes-native solution designed to manage Canton's distributed ledger infrastructure with enterprise-grade security and operational automation. It uses a custom Kubernetes operator and custom resource definitions (CRDs) to manage Canton components across environments. While the reference setup runs on Amazon EKS, it is fully portable to Microsoft Azure (AKS), Google Cloud (GKE), or on-premises Kubernetes / OpenShift.
Beyond infrastructure management, CAT-BM provides operational capabilities at the Canton and Daml application level, including managing parties and users, deploying DARs, configuring identity providers, performing backup and restore operations, monitoring, integration with wallet providers, and handling upgrades.
## System Context
CAT-BM sits between the operators who run Canton infrastructure and the Canton nodes and applications themselves. It is the control plane: it deploys, operates, and monitors Canton DLT, while the nodes and applications remain standard Canton components.
Software system
Functional responsibilities
Interfaces
CatalyX Blockchain Manager
Canton and Daml infrastructure provisioning, application deployment, and operations.
CatalyX UI, HTTP API, Kubernetes custom resources
Identity provider
User management, RBAC.
Web UI, API (OAuth / OIDC)
Canton nodes
Distributed ledger.
REST API, gRPC API, TCP
Canton applications
End-user Daml applications.
Web UI, HTTP API
CAT-BM runs on any conformant Kubernetes distribution, including managed Kubernetes services and OpenShift, on AWS, GCP, Azure, or on-premises.
## High-Level Architecture
CAT-BM separates a management plane (i.e. the components CatalyX ships) from the Canton stack those components create and operate.
High Level Architecture
### CatalyX Components
Component
Functional responsibilities
Interfaces
CAT-BM Canton UI
User interface for the Canton infrastructure and application operator.
Web UI
CAT-BM Canton API
Backend API for the user interface and third-party integrations.
REST API
CAT-BM Canton Operator
Kubernetes operator for Canton deployment operations.
Kubernetes custom resource definitions for Canton infrastructure
Canton Nodes
Canton DLT infrastructure.
gRPC API, REST API
Identity Provider
Authenticates and authorises every CatalyX component and validator UI. Either managed automatically (Keycloak, provisioned by the operator) or supplied externally as any OIDC-compliant provider (Okta, Microsoft Entra ID, Auth0, Ping Identity, and others).
Web UI, API (OAuth / OIDC)
***
### CatalyX management plane
Three components make up the CatalyX management plane. They are installed together by a single Helm chart.
Catalyx-operator
The operator watches `Validator` resources and reconciles each one into the workloads that make up a working validator. For a single `Validator` it will:
1. Provision the OIDC clients, scopes, and wallet user in the identity provider (when managed authentication is enabled).
2. Create the participant and validator-app databases and schemas.
3. Create one child `Application` resource per component.
Each `Application` is then reconciled into a Kubernetes `Deployment`, a `Service`, and — for components that are externally reachable — a Traefik `IngressRoute`.
```
Validator user-managed entry point
└─ Application × 4–6 operator-managed, one per component
└─ Deployment + Service + IngressRoute
```
{% hint style="warning" %}
`Application` resources are an operator implementation detail. Never create, edit, or delete them by hand — the operator owns them and will revert manual changes on the next reconcile. All configuration flows through the `Validator` resource.
{% endhint %}
The components created for a validator are:
| Component | Always created | Purpose |
| ---------------- | ----------------- | ---------------------------------------- |
| `participant` | Yes | The Canton participant node |
| `validator` | Yes | The validator app (Splice backend) |
| `wallet-ui` | Yes | Canton Wallet web UI |
| `cns-ui` | Yes | Canton Name Service web UI |
| `pqs` | Only when enabled | Participant Query Store |
| `wallet-gateway` | Only when enabled | Wallet Gateway, for external key custody |
Catalyx-api
The API is a stateless service that does two jobs:
* **Reads** validator and application state from the Kubernetes custom resources. It never writes them.
* **Proxies** privileged Canton operations — the Ledger API, the participant Admin API, the Scan API, and the validator app's admin API — so operators and integrations do not need direct network access to the nodes.
It also hosts the WebSocket endpoint that backs the interactive Canton console, and publishes an OpenAPI description of itself.
Catalyx-ui
The CatalyX UI is a single-page application that talks only to the API. It never talks to Kubernetes or to Canton directly, which means the permissions a UI user needs are API permissions, not cluster permissions.
***
### The Canton stack
Everything the operator creates for a validator sits in the Canton stack:
* **`participant`** — the Canton participant node. Owns its own PostgreSQL database. Exposes the Ledger API, the Admin API, a JSON API, and a metrics endpoint.
* **`validator`** — the validator app. Owns its own PostgreSQL database and connects to the network's sequencer, sponsoring Super Validator, and Scan services.
* **`wallet-ui`** and **`cns-ui`** — static web applications served behind the ingress, authenticating against the identity provider.
* **`pqs`** — optional. Streams the ledger into a queryable PostgreSQL store.
* **`wallet-gateway`** — optional. Delegates party signing to an external Wallet-as-a-Service provider.
All external traffic enters through Traefik over HTTPS. The UI, the API, and each externally reachable validator component are exposed on their own hostnames or path prefixes derived from the base hostname configured at install time.
***
## Design principles
The platform is built around the following capabilities.
Enterprise-grade security
* Encrypted persistent storage and encrypted communication channels (TLS / mTLS).
* Secure secret management via cloud secret managers or Kubernetes Secrets.
* Integration with enterprise Key Management Services (AWS KMS, Azure Key Vault) for encryption key lifecycle management.
* Support for integration with external Wallet-as-a-Service providers for secure signing and transaction management.
* Support for OIDC-compliant identity providers (Keycloak, Okta, Microsoft Entra ID, Auth0, Ping Identity, and others) for authentication and authorisation.
* Fine-grained access control using scope and claim mapping from the identity provider.
* Role-based access control (RBAC).
* Network-level security: IP allowlisting, VPN, and firewall / WAF integration options.
* Security audit logging with integration into SIEM platforms.
* Regular security patching and vulnerability scanning of container images and dependencies.
GitOps-driven operations
* All infrastructure and deployment configuration is defined declaratively using Helm charts and managed through GitOps practices.
* ArgoCD can be used to synchronise desired state from Git repositories to the Kubernetes cluster, enabling traceable, auditable, and consistent deployment pipelines across development, test, staging, and production environments.
Infrastructure-as-Code
* Cloud infrastructure is defined declaratively (for example with Terraform) and provisioned through the same GitOps pipelines described above, so changes stay traceable and reproducible across environments.
Automated lifecycle management
* CAT-BM automates node provisioning, dependency management, certificate distribution, and topology orchestration.
* Built-in support for scaling, patching, and configuration updates through CRDs.
Monitoring and observability
* Integrated with Prometheus and Grafana for metrics collection, visualisation, and alerting.
* Logs are aggregated and forwarded to a centralised log store such as Loki.
* Health checks, liveness and readiness probes, and custom metrics are exposed for proactive monitoring and incident response.
Scalability and extensibility
* Horizontal and vertical pod autoscaling based on resource usage.
* Support for multi-tenant deployments and workload isolation via Kubernetes namespaces and network policies.
***
## CatalyX validator hosting reference document
{% hint style="info" %}
For a worked example of a full production deployment on AWS — networking, compute sizing, and the managed services used — see the [CatalyX Canton Validator Hosting reference document](https://docs.google.com/document/d/1B2NQxLI4dqTpHY16DS1_wf6ddpKiaiq9/edit).
{% endhint %}
***
## Supported versions
| Component | Version |
| --------------- | --------------- |
| Canton Protocol | v2.10 or higher |
| Daml | v2.10 or higher |
# Installation Instructions
How to install CatalyX Blockchain Manager 2.0 for the Canton Network.
One Helm chart installs the operator, the API, and the ui into your cluster. You do this once.
Each validator is a `Validator` custom resource that you apply to the cluster. The operator does the rest. This is a separate, ongoing task once the platform is installed — see [Create a Validator](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/create-a-validator) in [Validator Management](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management).
{% hint style="warning" %}
CAT-BM 2.0 is not an in-place upgrade from 1.10 or 1.11. Install it fresh. Contact IntellectEU support before planning a migration from a 1.x deployment.
{% endhint %}
## In this section
Prerequisites
Cluster, tooling, and access you need before you start.
Reachable from the cluster. In-cluster or managed (for example Amazon RDS).
{% hint style="warning" %}
Traefik must be configured with entry points named exactly **`web`** (HTTP) and **`websecure`** (HTTPS). CAT-BM references these names when creating ingress routes; a Traefik installation using different entry point names will not route traffic to the platform.
{% endhint %}
## Optional cluster components
Each of these unlocks an optional feature. The corresponding CRDs must already be installed in the cluster.
Sourcing the platform's Keycloak secrets from an external secret store instead of creating Kubernetes Secrets by hand.
## Database access
CAT-BM provisions validator databases for you. The credentials you give it must therefore be able to create databases and schemas.
* The credentials referenced by `spec.database.credentialsSecretRef` need `CREATEDB` privileges.
* The operator connects to the `postgres` maintenance database on the host you specify, so that database must be reachable.
Each validator uses at least two databases — one for the participant node and one for the validator app — plus one more when the Participant Query Store is enabled, and two more when the Wallet Gateway is enabled.
## Identity provider
An OIDC-compliant identity provider must be reachable from the cluster before you install.
{% hint style="danger" %}
**The realm must already exist.** CAT-BM never creates a realm. When managed authentication is enabled, the operator creates clients, client scopes, protocol mappers, and users *inside* an existing realm.
{% endhint %}
You need:
* An existing realm for the validators.
* An **admin client** in that realm, with a service account holding realm-management permissions. The operator authenticates as this client to provision per-validator objects.
{% hint style="warning" %}
The admin client must live **in the target realm**, not in the `master` realm. The operator authenticates against the realm you configure as `operator.keycloak.realm` using the client credentials grant.
{% endhint %}
* Two clients for the management plane itself:
* a **confidential client** used by the API to mint per-validator Ledger API tokens — `catalyx-api` by default;
* a **public client** used by the ui for browser login (authorization code with PKCE) — `catalyx-canton-ui` by default.
## Network access
From
To
Cluster workloads
Your identity provider
Cluster workloads
PostgreSQL
Validator components
The Canton Network sequencer, sponsoring Super Validator, and Scan endpoints for your target network
Operators / users
The platform hostname, over HTTPS
Participant node
Your KMS endpoint, if KMS is enabled
For the global Canton Network, your egress IP addresses must be allowlisted by the network governance body and Super Validators. Start this process early — it requires a two-thirds approval threshold and is usually the longest lead-time item in an onboarding.
## Container images
Platform images are published to the IntellectEU Artifactory registry at `intellecteu-catbp-docker.jfrog.io`, built for `linux/amd64` and `linux/arm64`:
| Component | Repository |
| --------- | --------------------------------- |
| Operator | `catalyx/canton/catalyx-operator` |
| API | `catalyx/canton/catalyx-console` |
| UI | `catalyx/canton/catalyx-ui` |
You need an image pull secret with credentials for that registry. Contact IntellectEU support to obtain access.
{% hint style="info" %}
Pin `image.tag` to the release you intend to run — for example `v2.0.0`. The chart default is `latest`, which is convenient for evaluation but not appropriate for production.
{% endhint %}
## Onboarding secret
To join a validator to a network you need a one-time onboarding secret from a sponsoring Super Validator.
* Request it against the **Super Validator** URL (`sv.…`), not the Scan URL.
* Onboarding secrets are single-use and short-lived — typically valid for **48 hours**, and only **1 hour** for DevNet self-service tokens.
* Request the secret shortly before you apply the `Validator` resource, not days in advance.
# Keycloak Realm Setup
Create the realm, clients, and login user the platform needs before you install — with the commands to do it by hand.
Before you run [Platform Installation](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation), a Keycloak realm has to exist with three clients and a login user already in it. The operator only *provisions into* an existing realm (see [Managed Keycloak](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-provider-configuration/managed-keycloak)) — it never creates the realm itself, so this is a one-time manual step.
## One realm, shared by the platform and every validator
Everything below goes into one realm. That's the same realm you point the operator at with `operator.keycloak.realm` in [Platform Installation](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation), and the same realm [Managed Keycloak](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-provider-configuration/managed-keycloak) later provisions per-validator clients into. There's no separate "platform realm" and "validator realm" — one realm serves both.
## Placeholders used below
Placeholder
Example
Is
$REALM
validator-intellecteu-devnet
The realm you create — becomes operator.keycloak.realm.
$BASE_HOSTNAME
validators.example.com
Should match operatorRuntime.baseHostname — used in the UI client's redirect URI.
$UI_USERNAME / $UI_EMAIL
catalyx-ui-admin / catalyx-ui-admin@example.com
The browser login user you create for catalyx-canton-ui.
{% hint style="danger" %}
Pick your own values — don't reuse the examples above, and don't leave any password as a placeholder like `admin` in anything beyond a local minikube run.
{% endhint %}
## What to create
Object
Realm
Configuration
Realm
—
$REALM, enabled, display name "CatalyX Canton Validator" (or your own).
Client — catalyx-operator-admin
$REALM
Confidential, service accounts enabled, standard flow disabled (service account only — never used for browser login). Its secret is what you store as admin-client-secret in the catalyx-operator-keycloak secret in Platform Installation, and is referenced by operator.keycloak.adminClientId.
Client — catalyx-api
$REALM
Confidential, service accounts enabled, standard flow enabled, direct access grants disabled, redirectUris: ["/*"], webOrigins: ["/*"]. Its secret is what you store as client-secret in the catalyx-api-credentials secret.
Client — catalyx-canton-ui
$REALM
Public, standard flow enabled (browser OIDC with PKCE), direct access grants disabled, redirect URI https://$BASE_HOSTNAME/*, web origin https://$BASE_HOSTNAME. Matches ui.oidc.clientId (default catalyx-canton-ui).
User — $UI_USERNAME
$REALM
Enabled, email verified, password set. Used to sign in to the CatalyX UI in a browser via catalyx-canton-ui. Carries no realm roles — it's a plain login, not an admin account.
## Permission to grant
There is one role assignment to make: the `catalyx-operator-admin` service account (`service-account-catalyx-operator-admin`) gets the **`realm-admin`** client role of **`$REALM`**'s own **`realm-management`** client — not `master`'s. That scopes the operator to administering just `$REALM`, and is what lets its client-credentials login create and update the per-validator clients, scopes, and users described in [Managed Keycloak](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-provider-configuration/managed-keycloak).
## Commands
Everything below can equally be done by hand in the Keycloak Admin Console (**Realm settings → Create realm**, **Clients → Create client**, **Users → Add user**, and the role assignment under a user's **Role mapping** tab).
Run these with `kcadm.sh` against your Keycloak — from a shell with `kcadm.sh` on the path (for example `kubectl exec` into the Keycloak pod), or adapt them to the [Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/index.html) if you're not using the CLI.
{% stepper %}
{% step %}
**Authenticate**
```bash
kcadm.sh config credentials \
--server "$KEYCLOAK_URL" \
--realm master \
--user admin \
--password
```
{% endstep %}
{% step %}
**Create the realm**
```bash
kcadm.sh create realms \
-s realm="$REALM" \
-s enabled=true \
-s displayName="CatalyX Canton Validator"
```
{% endstep %}
{% step %}
**Create `catalyx-operator-admin` in `$REALM` and grant it `realm-admin`**
```bash
kcadm.sh create clients -r "$REALM" \
-s clientId=catalyx-operator-admin \
-s enabled=true \
-s publicClient=false \
-s serviceAccountsEnabled=true \
-s standardFlowEnabled=false
kcadm.sh add-roles -r "$REALM" \
--uusername service-account-catalyx-operator-admin \
--cclientid realm-management \
--rolename realm-admin
```
{% endstep %}
{% step %}
**Create `catalyx-api` in `$REALM`**
```bash
kcadm.sh create clients -r "$REALM" \
-s clientId=catalyx-api \
-s enabled=true \
-s publicClient=false \
-s serviceAccountsEnabled=true \
-s standardFlowEnabled=true \
-s directAccessGrantsEnabled=false \
-s 'redirectUris=["/*"]' \
-s 'webOrigins=["/*"]'
```
{% endstep %}
{% step %}
**Create `catalyx-canton-ui` in `$REALM`**
```bash
kcadm.sh create clients -r "$REALM" \
-s clientId=catalyx-canton-ui \
-s enabled=true \
-s publicClient=true \
-s serviceAccountsEnabled=false \
-s standardFlowEnabled=true \
-s directAccessGrantsEnabled=false \
-s "redirectUris=[\"https://$BASE_HOSTNAME/*\"]" \
-s "webOrigins=[\"https://$BASE_HOSTNAME\"]"
```
{% endstep %}
{% step %}
**Create the UI login user**
```bash
kcadm.sh create users -r "$REALM" \
-s username="$UI_USERNAME" \
-s email="$UI_EMAIL" \
-s enabled=true \
-s emailVerified=true
kcadm.sh set-password -r "$REALM" \
--username "$UI_USERNAME" \
--new-password
```
{% endstep %}
{% step %}
**Retrieve the `catalyx-operator-admin` secret**
```bash
CLIENT_ID=$(kcadm.sh get clients -r "$REALM" \
-q clientId=catalyx-operator-admin --fields id --format csv --noquotes)
kcadm.sh get "clients/$CLIENT_ID/client-secret" -r "$REALM"
```
Store the printed `value` as `admin-client-secret` in the `catalyx-operator-keycloak` secret — see step 2 of [Platform Installation](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation).
{% endstep %}
{% step %}
**Retrieve the `catalyx-api` secret**
```bash
CLIENT_ID=$(kcadm.sh get clients -r "$REALM" \
-q clientId=catalyx-api --fields id --format csv --noquotes)
kcadm.sh get "clients/$CLIENT_ID/client-secret" -r "$REALM"
```
Store the printed `value` as `client-secret` in the `catalyx-api-credentials` secret — also step 2 of [Platform Installation](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation).
{% endstep %}
{% endstepper %}
***
## Next step
With the realm, its three clients, and the UI login user in place, continue to [Platform Installation](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation) to create the Kubernetes secrets from the two client secrets above and install the Helm chart.
# Platform Installation
Install the CAT-BM operator, API, and UI with Helm.
The `catalyx-canton` Helm chart installs three components — the operator, the API, and the CatalyX UI component — plus the two custom resource definitions they depend on.
## Before you install
{% stepper %}
{% step %}
**Create the namespace**
Create a namespace for the platform — any name works. This guide uses `` as a placeholder throughout; substitute your own choice everywhere you see it.
```bash
kubectl create namespace
```
{% endstep %}
{% step %}
**Create the identity provider secrets**
Two secrets are required, both live in the release namespace, and both hold client secrets from an existing Keycloak realm — see [Keycloak Realm Setup](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/keycloak-realm-setup) if that realm and its clients don't exist yet.
```bash
# The operator's Keycloak admin client secret
kubectl create secret generic catalyx-operator-keycloak \
--from-literal=admin-client-secret= \
-n
# The API's Keycloak confidential client secret
kubectl create secret generic catalyx-api-credentials \
--from-literal=client-secret= \
-n
```
{% hint style="danger" %}
`catalyx-api-credentials` is **not optional**. The API pod will not start without it — it fails with `CreateContainerConfigError`.
{% endhint %}
{% endstep %}
{% step %}
**Create the TLS secret**
The chart does not create a TLS certificate unless you enable cert-manager. The default name is `catalyx-app-tls`.
```bash
kubectl create secret tls catalyx-app-tls \
--cert= --key= \
-n
```
{% hint style="warning" %}
This secret name is used by **every ingress route the operator creates for validators**, not just by the UI and API. If it does not exist, validator UIs will fail to serve over HTTPS even if you never set `ingress.tls.secretName` yourself.
{% endhint %}
{% endstep %}
{% step %}
**Create the image pull secret**
```bash
kubectl create secret docker-registry intellecteu-jfrog-access \
--docker-server=intellecteu-catbp-docker.jfrog.io \
--docker-username= --docker-password= \
-n
```
{% endstep %}
{% endstepper %}
***
## Install
```bash
helm install catalyx-canton catalyx/catalyx-canton \
-n \
--set image.tag=v2.0.0 \
--set 'image.pullSecrets[0].name=intellecteu-jfrog-access' \
--set operator.keycloak.serverUrl=https://keycloak.example.com \
--set operator.keycloak.realm=my-realm \
--set operator.keycloak.adminClientId=catalyx-operator-admin \
--set operator.keycloak.adminClientSecretRef.name=catalyx-operator-keycloak \
--set api.auth.jwksUri=https://keycloak.example.com/realms/my-realm/protocol/openid-connect/certs \
--set ui.oidc.authority=https://keycloak.example.com/realms/my-realm \
--set ui.oidc.redirectUri=https://validators.example.com \
--set operatorRuntime.baseHostname=validators.example.com \
--set ingress.host=validators.example.com \
--set ingress.tls.secretName=catalyx-app-tls
```
Contact IntellectEU support for the Helm repository URL and credentials.
Verify the rollout:
```bash
kubectl -n get deploy
kubectl -n wait --for=condition=Available deployment \
-l app.kubernetes.io/instance=catalyx-canton --timeout=180s
```
The UI is then available at `https:///`, and the API at `https:///api`.
***
## Values you must set
These have defaults that are only suitable for local development. Every production install should override all of them.
Value
Purpose
ingress.host
Hostname the UI and API are served on. When empty, ingress routes match on path only, with no host clause.
ingress.tls.secretName
TLS secret for the UI and API routes.
operatorRuntime.baseHostname
Base hostname for every per-validator hostname the operator generates, and for the identity provider redirect URIs it registers. Changing it later rewrites those redirect URIs on the next reconcile.
operatorRuntime.tlsSecretName
TLS secret used by every ingress route the operator creates. Default catalyx-app-tls.
api.auth.jwksUri
JWKS endpoint the API validates UI tokens against.
ui.oidc.authority
OIDC issuer the UI redirects browser logins to.
ui.oidc.clientId
Public OIDC client for the UI. Default catalyx-canton-ui.
ui.oidc.redirectUri
Where the identity provider returns the browser after login. Must match a redirect URI registered on the client.
image.tag
Pin to a release tag. Default is latest.
image.pullSecrets
Pull secret for the IntellectEU registry.
## Managed authentication values
Required only if you intend to use `managedKeycloak: true` on any validator.
Value
Purpose
operator.keycloak.serverUrl
Identity provider base URL.
operator.keycloak.realm
Realm the operator provisions into. Must already exist.
operator.keycloak.adminClientId
Admin client the operator authenticates as. Must exist in that realm.
Secret holding the admin client secret. Key defaults to admin-client-secret.
operator.keycloak.apiClientId
The client that per-validator Ledger API scopes are attached to. Default catalyx-api.
## Component values
Value
Default
Notes
operator.replicaCount
1
Must remain 1. The operator has no leader election; a second replica double-reconciles every resource.
api.replicaCount
1
Must remain 1. Canton console sessions are held in process, so they do not survive being load-balanced across replicas.
ui.replicaCount
2
The UI is stateless and runs highly available by default, with a pod disruption budget and topology spread.
api.namespace
release namespace
Namespace the API reads validators from. The API's RBAC is namespaced to the release namespace, so pointing this elsewhere produces authorisation errors.
operator.rbac.clusterAdmin
false
Leave false. When true, the operator service account is bound to cluster-admin instead of the chart's least-privilege role.
ui.grafana.baseUrl
—
Base URL for the Grafana deep links in the UI. See Grafana Links.
monitoring.serviceMonitor.enabled
false
Set true to have Prometheus scrape validator component metrics. Requires the Prometheus Operator CRDs.
certManager.enabled
false
Set true, with certManager.certificate.create and certManager.certificate.dnsNames, to have cert-manager issue the platform certificate.
{% hint style="warning" %}
**Harden the OpenAPI endpoints before exposing the platform publicly.** The chart publishes `/swagger-ui` and `/v3/api-docs` on the same hostname as the API, and both are served without authentication. If that is not acceptable in your environment, restrict them with a Traefik middleware via `api.ingress.middlewares`, or block them at your edge.
{% endhint %}
***
## Upgrading
```bash
helm upgrade catalyx-canton catalyx/catalyx-canton -n -f my-values.yaml
```
{% hint style="danger" %}
**Helm does not upgrade CRDs.** `helm upgrade` never touches the chart's `crds/` directory. When a release changes the `Validator` or `Application` schema, apply the CRDs explicitly before upgrading:
```bash
kubectl apply -f /crds
```
{% endhint %}
Existing validators are re-reconciled after an upgrade. The operator applies rolling updates to component deployments, so a component with more than one replica is updated without downtime.
# Validator CRD Reference
Every field on the Validator custom resource, with types and defaults.
## How to read this reference
Two different kinds of default appear in the tables, and the distinction is load-bearing.
Kind
Behaviour
Schema default
Applied by the Kubernetes API server when you omit the field. It is written into the stored resource, so kubectl get -o yaml shows it.
Operator default
Applied by the operator at reconcile time. The field stays absent from the stored resource — the value appears only in the resulting workload.
Similarly, two kinds of "required":
Kind
Behaviour
Schema required
The API server rejects the resource at kubectl apply. Fast, obvious failure.
Reconcile required
Accepted at apply, then fails during reconciliation. Surfaces as the Ready condition with reason InvalidSpec and a message naming the field.
{% hint style="danger" %}
**Unknown fields are silently pruned.** The API server drops any field not in the schema, without an error. A misspelled field name has no effect and produces no warning. After applying, confirm your fields survived:
```bash
kubectl -n get validator my-validator -o yaml
```
{% endhint %}
***
## Top level
Three blocks are schema-required: `auth`, `database`, and `network`.
Field
Required
Purpose
spec.auth
Schema
Authentication for every component.
spec.database
Schema
PostgreSQL connection and database names.
spec.network
Schema
Canton network connectivity.
spec.participant
No
Canton participant node configuration.
spec.validator
No
Validator app configuration.
spec.ui
No
Wallet UI and CNS UI configuration and branding.
spec.pqs
No
Participant Query Store.
spec.walletGateway
No
Wallet Gateway.
spec.kms
No
External key management.
spec.overrides
No
Extra environment variables per component.
***
## `spec.auth`
Field
Type
Default
Purpose
enabled
boolean
true
Master authentication switch. false disables authentication on the participant.
managedKeycloak
boolean
false
true → the operator provisions the OIDC objects and reads configuration from status.managedAuth.
authUrl
string
—
OIDC issuer or token endpoint.
jwksUrl
string
—
JWKS endpoint for token verification.
targetAudience
string
—
Audience every token must carry.
ledgerApiUserManagementScope
string
—
OAuth scope granting Ledger API user management.
ledgerApiUser
string
—
Participant admin user name.
walletUserName
string
—
Wallet owner user name.
ledgerApiClientId
string
—
Confidential backend client ID.
walletUiClientId
string
—
Public client ID for the Wallet UI.
cnsUiClientId
string
—
Public client ID for the CNS UI.
walletGatewayClientId
string
—
Public client ID for the Wallet Gateway.
ledgerApiClientSecretRef.name
string
—
Secret holding the backend client secret.
ledgerApiClientSecretRef.key
string
client-secret
Key within that secret.
{% hint style="info" %}
With `managedKeycloak: false`, the fields the components need are **reconcile-required**, not schema-required. A `Validator` missing them applies successfully and then reports `InvalidSpec`. See [External Identity Provider](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-provider-configuration/external-identity-provider).
{% endhint %}
***
## `spec.database`
Schema-required inside: `host`, `participantDb`, `validatorDb`, `credentialsSecretRef.name`.
Field
Type
Default
Purpose
host
string
—
PostgreSQL host. Schema required.
port
integer
5432
PostgreSQL port. Must be 1–65535.
participantDb
string
—
Participant database name. Schema required.
participantSchema
string
participant
Participant schema.
validatorDb
string
—
Validator app database name. Schema required.
validatorSchema
string
validator
Validator app schema.
pqsDatabase
string
—
PQS database name. Reconcile required when pqs.enabled.
pqsSchema
string
pqs
PQS schema.
walletGatewayStoreDatabase
string
—
Wallet Gateway store database. Reconcile required when walletGateway.enabled.
walletGatewaySigningDatabase
string
—
Wallet Gateway signing database. Reconcile required when walletGateway.enabled.
credentialsSecretRef.name
string
—
Secret with the database credentials. Schema required.
credentialsSecretRef.usernameKey
string
username
Key holding the username.
credentialsSecretRef.passwordKey
string
password
Key holding the password.
{% hint style="info" %}
The operator creates the databases and schemas for you, so these credentials need `CREATEDB` privileges and access to the `postgres` maintenance database.
{% endhint %}
***
## `spec.network`
Schema-required inside: `partyHint`.
Field
Type
Default
Purpose
partyHint
string
—
Party ID hint, and the wallet username under managed authentication. Schema required, and pattern-validated — see below.
spliceVersion
string
—
Single image tag for the participant, validator app, and both UIs, used when a component has no version of its own.
migrationId
string
"1"
Canton domain migration ID. A string, not an integer.
onboardingSecretName
string
—
Secret holding the Super Validator onboarding token, under the key secret.
sponsorSvUrl
string
—
Sponsoring Super Validator URL.
contactPoint
string
—
Operator contact point published to the network.
scan.address
string
—
Scan service address.
scan.type
string
—
Scan mode. Use bft with seedUrls, or trust-single with a single address.
scan.seedUrls
string[]
—
BFT scan seed URLs.
synchronizer.connectionType
string
—
Sequencer connection mode: bft or trust-single.
synchronizer.url
string
—
Sequencer URL. Used with trust-single.
{% hint style="danger" %}
**`partyHint` is pattern-validated** as `^[a-zA-Z0-9]+-[a-zA-Z0-9]+-[0-9]+$` — two alphanumeric segments and a numeric segment, hyphen-separated. `catalyx-devnet-001` is valid; `myvalidator` and `my_validator_1` are rejected at apply time.
{% endhint %}
{% hint style="warning" %}
**`scan` and `synchronizer` are effectively required**, even though the schema does not mark them so. A validator without them fails to reconcile.
**`scan.type` and `synchronizer.connectionType` are not enum-validated.** Only `trust-single` is treated specially; every other value — including a typo — takes the BFT path. Check the spelling.
{% endhint %}
***
## `spec.participant` and `spec.validator`
Both blocks are optional and take operator defaults. `spec.participant` additionally has `nodeIdentifier`; `spec.validator` additionally has `dumpPath`.
Field
Operator default
Purpose
version
spec.network.spliceVersion
Image tag. Reconcile required if spliceVersion is also unset.
participant.nodeIdentifier
spec.network.partyHint
Canton participant node identifier.
validator.dumpPath
—
Path to a domain migration dump.
resources.requests.cpu / .memory
2 / 3Gi
CPU and memory requests.
resources.limits.cpu / .memory
3 / 6Gi
CPU and memory limits.
jvm.minHeap / .maxHeap
2048m / 4096m
JVM heap bounds.
jvm.logbackConfigFile
/app/logback.xml
Logback configuration path.
participant.service.jsonApiPort
7575
JSON API port.
participant.service.ledgerApiPort
5001
Ledger API port.
participant.service.adminApiPort
5002
Admin API port.
validator.service.apiPort
5003
Validator app HTTP API port.
service.metricsPort
10013
Metrics port.
{% hint style="danger" %}
**Heap and memory limit are validated together.** The operator rejects the validator if `jvm.maxHeap` would not fit inside `resources.limits.memory` — the container would otherwise be OOM-killed. The limit must also leave headroom for JVM non-heap memory.
Heap values use **JVM units** with an optional `k`, `m`, or `g` suffix — `2048m`, `2g`. Kubernetes-style units such as `Mi` and `Gi` are rejected.
{% endhint %}
{% hint style="warning" %}
If you supply a `requests` or `limits` block, **both `cpu` and `memory` are required inside it**. A partial block is rejected at apply time.
{% endhint %}
***
## `spec.ui`
`wallet` and `cns` take the same fields.
Field
Default
Purpose
wallet.enabled / cns.enabled
true (schema)
Whether the UI runs.
wallet.version / cns.version
spliceVersion (operator)
Image tag. Reconcile required if spliceVersion is also unset — even when the UI is disabled.
resources.requests.cpu / .memory
100m / 128Mi (operator)
Requests.
resources.limits.cpu / .memory
3 / 128Mi (operator)
Limits.
branding.networkName
Canton Network
Network display name.
branding.networkFaviconUrl
Canton Network favicon
Favicon URL.
branding.amuletName
Canton Coin
Coin display name.
branding.amuletNameAcronym
CC
Coin acronym.
branding.nameServiceName
Amulet Name Service
Name service display name.
branding.nameServiceNameAcronym
ANS
Name service acronym.
{% hint style="info" %}
Setting `enabled: false` scales the UI to zero replicas rather than removing it. It still appears as a component in the UI and still requires a resolvable version.
{% endhint %}
***
## `spec.pqs`
Field
Default
Purpose
enabled
false (schema)
Deploy the Participant Query Store.
version
—
Image tag. Required when enabled, and does not fall back to spliceVersion.
ledgerStart
Latest (schema)
Where the pipeline starts reading.
resources.requests.cpu / .memory
500m / 1Gi
Requests.
resources.limits.cpu / .memory
3 / 2Gi
Limits.
jvm.minHeap / .maxHeap
512m / 1536m
JVM heap bounds.
Also requires `spec.database.pqsDatabase`. See [Participant Query Store](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/participant-query-store).
***
## `spec.walletGateway`
Field
Default
Purpose
enabled
false (schema)
Deploy the Wallet Gateway.
version
—
Image tag. Required when enabled, enforced by the schema.
resources.requests.cpu / .memory
250m / 512Mi
Requests.
resources.limits.cpu / .memory
1 / 1Gi
Limits.
dfns.orgId
—
Provider organisation ID.
dfns.apiUrl
—
Provider API base URL.
dfns.credentialId
—
Provider credential ID.
dfns.credentialsSecretRef.name
—
Secret with the provider credentials. Schema required when the block is present.
dfns.credentialsSecretRef.privateKeyKey
private-key
Key holding the private key.
dfns.credentialsSecretRef.authTokenKey
auth-token
Key holding the auth token.
Also requires `spec.auth.enabled: true`, an auth URL, a backend client ID, a Wallet Gateway client ID, a target audience, a user-management scope, and both Wallet Gateway databases. See [Wallet Gateway](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/wallet-gateway).
***
## `spec.kms`
Field
Default
Purpose
enabled
false
Hold Canton keys in an external KMS.
provider
—
azure or aws. Case-sensitive, and required when enabled.
{% hint style="info" %}
Fields marked *driver default* have **no default in the CRD**. Omitting one emits no configuration at all, and the KMS driver's own default applies. Set a value explicitly if you need to depend on it.
{% endhint %}
### `spec.kms.aws`
Schema-required inside: `region`.
Field
Default
Purpose
region
—
AWS region. Schema required.
serviceAccountName
—
Pre-created service account for IRSA. CAT-BM does not create it.
credentialsSecretRef.name
—
Static credentials secret. Schema required when the block is present.
credentialsSecretRef.accessKeyIdKey
access-key-id
Applied by the operator, not the schema.
credentialsSecretRef.secretAccessKeyKey
secret-access-key
Applied by the operator, not the schema.
credentialsSecretRef.sessionTokenKey
—
For temporary or assumed-role credentials.
multiRegionKey
—
Use a multi-region key.
auditLogging
—
Log KMS operations.
There is no `preBuiltImage` for AWS — the standard participant image is used.
***
## `spec.overrides`
Appends environment variables to a component's container. Each block takes an `extraEnv` array using the standard Kubernetes `EnvVar` schema, so `value`, `secretKeyRef`, `configMapKeyRef`, and the other reference forms are all available.
```yaml
spec:
overrides:
participant:
extraEnv:
- name: MY_SETTING
value: "value"
```
Available for `participant`, `validator`, `walletUi`, and `cnsUi`.
{% hint style="info" %}
There is no `overrides` block for PQS or the Wallet Gateway. Those components are configured only through their own fields.
{% endhint %}
***
## Status
The status subresource is written by the operator. It is read-only.
Field
Meaning
status.observedGeneration
The resource generation the operator last reconciled. Compare against metadata.generation to see whether your change has been picked up.
status.conditions[]
A single Ready condition, with status, reason, message, and lastTransitionTime.
status.databaseProvisioned
Participant and validator databases created.
status.pqsDatabaseProvisioned
PQS database created. Present only when PQS is enabled.
status.walletGatewayDatabaseProvisioned
Wallet Gateway databases created. Present only when enabled.
status.applications.<component>
Per-component summary — name, ready, reason, message, lastTransitionTime. Components: participant, validatorBackend, walletUi, cnsUi, and pqs / walletGateway when enabled.
status.managedAuth
The result of managed authentication provisioning. See Managed Keycloak.
### `Ready` condition reasons
| Reason | Meaning |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `AllApplicationsReady` | Healthy |
| `ApplicationNotReady` | A component has not come up. Check `status.applications` |
| `InvalidSpec` | Configuration error. The message names the field |
| `ReconcileError` | A non-configuration failure — often the database or identity provider being unreachable |
### Printer columns
```bash
kubectl -n get validators # NAME, READY, AGE
kubectl -n get validators -o wide # adds REASON
```
***
## The `Application` resource
The operator creates one `Application` per component, as a child of the `Validator`.
{% hint style="danger" %}
**Never create, edit, or delete `Application` resources.** They are an operator implementation detail. A hand-created one is unowned and unmanaged; an edited one is reverted on the next reconcile. All configuration flows through the `Validator`.
{% endhint %}
`Application` resources are useful to *read*, though — they show exactly what the operator generated:
```bash
kubectl -n get applications
kubectl -n get application my-validator-participant -o yaml
```
Their status carries the generated `deployment`, `service`, and `ingress` names, the internal and external `endpoints`, and a `Ready` condition whose reason is one of `DeploymentNotFound`, `DeploymentAvailable`, or `DeploymentUnavailable`. The UI surfaces all of it on the [Applications](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/applications) pages.
***
## Schema stability
{% hint style="info" %}
The served version is `catalyx.manager.canton/v1alpha1`. **Field-level changes may still occur in a future minor release.** Keep your `Validator` resources under version control, and read the [Release Notes](/catalyx-blockchain-manager/canton-network/version-2.0/release-notes) before upgrading the platform.
{% endhint %}
# User Guide
The CatalyX UI is a web application for operating Canton validators without direct cluster access. It talks only to the CatalyX API, never to Kubernetes or to the Canton nodes directly.
***
## Navigation
The sidebar has three primary destinations:
| | |
| ---------------- | ----------------------------------------------------- |
| **Dashboard** | Fleet-wide summary and the Canton console |
| **Validators** | The validator list, and every validator's detail view |
| **Applications** | Every component deployed for every validator |
Below them, **Help** opens this documentation. The sidebar can be collapsed with **Cmd/Ctrl + `\`**.
### Environment badge
The sidebar shows which environment you are looking at, derived from the hostname you are on:
| Badge | Shown when |
| ------------ | ------------------------------------------------------ |
| `Local` | The hostname is `localhost`, `127.0.0.1`, or `0.0.0.0` |
| `Dev` | The hostname contains a `dev` or `staging` segment |
| `Production` | Anything else |
{% hint style="warning" %}
`Production` is the fallback, not a positive detection. Any hostname that does not look local or dev is labelled `Production`.
{% endhint %}
***
## How to read the UI
### Everything refreshes itself
There is no refresh button on most screens, and no "last updated" indicator — the UI polls continuously:
| Data | Interval |
| ------------------------------------------------------- | --------- |
| Validator status, applications list, application status | 3 seconds |
| Resource metrics | 5 seconds |
The Parties tab is the exception: its lists have an explicit **Refresh** button, because reading the synchronizer topology store is comparatively expensive.
### Status vocabulary
The UI uses a small, consistent set of status words. Two of them are worth learning precisely, because they mean different things in different places.
**Validator readiness**
| Value | Meaning |
| ---------- | ------------------------------------------------------ |
| `Ready` | Every component the validator owns is ready |
| `Degraded` | At least one is not (shown on the lists and Dashboard) |
On the validator detail header, a validator that is not ready shows the underlying **reason** instead of the word `Degraded` — which is more specific and worth reading.
**Participant connection**
| List page | Detail page | Meaning |
| -------------- | -------------- | --------------------------------------------------------------------------------------------- |
| `Live` | `Connected` | The participant is initialised and its synchronizer connection is healthy |
| `Disconnected` | `Disconnected` | Initialised, but the synchronizer connection is unhealthy |
| `Initializing` | `Initializing` | The participant is still starting up |
| `Not live` | *(no badge)* | No participant status was returned — usually still loading, or the participant is unreachable |
**Health values** on participant components and synchronizers are the raw values Canton reports, colour-coded: `ok` and `healthy` are good, `degraded` is a warning, `failed`, `fatal`, and `unhealthy` are errors, and anything else is treated as unknown.
**Kubernetes conditions** appear as `True`, `False`, or `Unknown`.
### Copying identifiers
Party IDs, package IDs, endpoints, and other long values are truncated for display, with the full value in a tooltip. A copy button beside each one copies the **complete** value, never the truncated form, and confirms with a brief toast.
### Tables
All tables in the UI behave the same way:
* Columns can be resized, and your widths are remembered per table.
* Rows that lead somewhere are clickable, and respond to Enter or Space.
* Some rows expand to reveal detail, via a chevron on the left.
* Narrow screens fall back to a card layout instead of a horizontal scroll.
* Tables with many rows paginate at 10 rows, with a page size selector offering 10, 25, 50, or 100.
***
## What the UI does not do
Being clear about this up front saves time hunting for a button that is not there.
Not exposed in 2.0. The Balances and Traffic tabs are read-only
Generating, rotating, or importing participant keys
Not exposed in 2.0. The Keys tab is read-only
Full-text search across validators
Search exists within the DAR packages list and the Parties tab only
## Permissions
The UI requires a valid OIDC token from the identity provider configured at install time. Any user who can authenticate can reach every screen, including the operations that change ledger state.
{% hint style="danger" %}
There is no per-validator or per-screen authorisation inside the UI in 2.0. Restrict who can obtain a token for the UI client in your identity provider, and treat UI access as privileged — the [Canton console](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/canton-console) in particular grants full administrative access to the participant.
{% endhint %}
# Dashboard
Fleet-wide validator and application health.
The Dashboard is the CatalyX UI's landing page. It answers one question — *is anything wrong?* — and gives you the Canton console.
## Summary cards
Four cards across the top aggregate every validator the UI can see.
Card
Value
Badge
Validators
Total number of validators.
View all → links to the Validators list.
Ready
ready / total.
All healthy when every validator is ready.
Issues
Number of validators that are not ready.
Degraded when the count is above zero.
Applications
ready / total across every component of every validator.
View all → links to the Applications list.
A validator counts as ready when its `Ready` condition is `True`. **Issues** is simply the remainder.
{% hint style="info" %}
The Applications count comes from each validator's reported component status, so it includes components that have not yet produced a workload. The [Applications](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/applications) list is the authoritative view of what is actually deployed.
{% endhint %}
## Canton Console panel
Below the cards sits the [Canton Console](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/canton-console) — an interactive Canton console session in the browser. It is collapsed by default and this is the only place in the UI where it appears.
## Where to go next
The Dashboard deliberately does not try to tell you *what* is wrong. When the **Issues** card is non-zero:
{% stepper %}
{% step %}
**Open the Validators list**
The [Validators list](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators-list) shows per-validator status, plus the participant connection state, which is usually the fastest signal.
{% endstep %}
{% step %}
**Open the affected validator**
Its [Summary](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/summary) tab breaks readiness down per component.
{% endstep %}
{% step %}
**Read the conditions**
The [Status](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/status-and-specification) tab shows the reason and message the operator posted, which names the specific problem.
{% endstep %}
{% endstepper %}
# Validator Overview
The Validators list is the main working view for an operator running more than one validator. Every row is live — status, participant connection, and balance all refresh on their own.
## Validator Overview
Above the table: **`n` total**, **`n` ready**, **`n` issues**. The issues figure turns amber when it is above zero.
Column
Contents
Name
The validator's name.
Network
DevNet, TestNet, or MainNet, inferred from the Canton endpoints configured on the validator.
Party ID
The validator's primary party, truncated, with a copy button.
Version
The validator app version — the component's own version, or the validator's spliceVersion.
Balance
The validator's Canton Coin balance, to two decimal places. Shows Loading… until the Scan endpoint responds.
Participant
Connection state: Live, Disconnected, Initializing, or Not live.
Status
Ready or Degraded.
Metrics
Opens the participant dashboard in Grafana, in a new tab.
Logs
Opens the participant's logs in Grafana, in a new tab.
{% hint style="info" %}
**`Status` and `Participant` answer different questions.** `Status` is about Kubernetes: are all the workloads running? `Participant` is about Canton: is the node initialised and talking to the synchronizer? A validator can show `Ready` and `Disconnected` at the same time — every pod is healthy, but the node has lost its synchronizer connection. That combination is the one worth looking into first.
{% endhint %}
## Actions
* **Click a row** to open that validator's detail view.
* **Metrics** and **Logs** open Grafana without navigating away from the UI. See [Grafana Links](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/grafana-dashboards).
## Empty and error states
| Situation | What you see |
| ---------------------------- | ------------------------------------------------------------------------------ |
| No validators exist | **No validators found** — *No Canton validators are deployed in this cluster.* |
| The list could not be loaded | **Failed to load validators**, with the error message |
{% hint style="warning" %}
The UI only sees validators in the namespace the API is configured to watch. A validator applied to a different namespace will not appear here, and is not being reconciled by the platform either.
{% endhint %}
# Validator Details
Opening a validator opens the validator details, and a left-hand navigation of thirteen tabs grouped into four sections.
## Header Details
Element
Contents
Breadcrumb
Back to validators.
Title
The validator's name.
Network badge
DevNet, TestNet, or MainNet.
Readiness badge
Ready, or the reason the validator is not ready — for example ApplicationNotReady or InvalidSpec.
Connection badge
Connected, Disconnected, or Initializing. No badge is shown when no participant status has been returned.
Party ID row
The validator's primary party, with a copy button.
## Tab Details
### Overview
Summary
Component-by-component health, resources, and restarts.
## Which tabs can change something
Most of the detail view is read-only. Nine of the thirteen tabs only display information. Four support operations:
Tab
Operations
Parties
Allocate a party, onboard an external party, approve a hosting proposal, amend a party's hosting.
DARs
Upload a .dar package.
Users
Create a ledger user, edit a user and its rights.
Wallet Users
Onboard and offboard wallet users.
Plus **Identity**, which lets you download an identity dump — a read operation, but one that produces a highly sensitive file.
{% hint style="danger" %}
These operations act on the live ledger and take effect immediately. Only wallet user removal asks for confirmation; DAR upload, party allocation, user changes, and hosting approval do not.
{% endhint %}
# Summary
The Summary tab is where you start when a validator is not behaving. It shows the participant node's health and then every component the validator owns, in one table.
## Metric cards
| Card | Value |
| ----------- | --------------------------------------------------------------------------------------- |
| **Status** | `Ready` or `Degraded`, with a badge showing the percentage of components that are ready |
| **Network** | `DevNet`, `TestNet`, or `MainNet` |
| **Balance** | Canton Coin balance, to two decimal places |
## Participant
Shown once the participant has reported status. The badge is `Connected`, `Disconnected`, or `Initializing`.
Row
Meaning
Initialized
Whether the node has completed initialisation.
Active
Whether the node is the active instance.
Components
healthy / total of the participant's internal health components. Turns amber when any is unhealthy.
Version
The Canton participant version.
UID
The participant's unique identifier.
Waiting for
What the node is blocked on, when it is still initialising.
Below that, **Health components** lists each internal component with its status and description. The same table appears in more depth on the [Participant](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/participant-and-keys) tab.
## Applications
One row per component, always in this order:
`Participant` · `Validator Backend` · `Wallet UI` · `CNS UI` · `PQS` · `Wallet Gateway`
PQS and Wallet Gateway rows only appear when those components are enabled.
Column
Contents
Application
The component name.
CPU
Current usage against the limit, as a bar and a percentage, with the raw used / limit beneath.
Memory
Same, in bytes.
Restarts
Container restart count. Amber when above zero.
Since
When the component last changed readiness.
Status
Ready or Pending.
—
Grafana metrics link (participant only) and Grafana logs link.
{% hint style="info" %}
This tab uses `Pending` rather than `Degraded` for a component that is not ready — the same underlying state, a different word. The [Applications](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/applications) list shows the operator's specific reason instead.
{% endhint %}
### Expanding a row
Each row expands to show what the operator created and what Kubernetes reports back:
Field
Meaning
Deployment
Name of the generated Deployment.
Replicas
ready / desired.
Service
Name of the generated Service.
Ingress
Name of the generated IngressRoute, for externally reachable components.
Observed Generation
The generation of the resource the operator last reconciled.
Internal URL / External URL
In-cluster and public addresses.
Then **Resources by replica**, a per-pod table of phase, restarts, and CPU and memory usage against requests and limits; and finally the component's Kubernetes conditions, with type, status, reason, message, and last transition time.
{% hint style="warning" %}
If live usage figures are missing and a note says the cluster metrics API is not reachable, the `metrics-server` component is not installed or not healthy in your cluster. Requests and limits still display; only actual usage is unavailable.
{% endhint %}
## Restart notifications
While you have a validator open, the UI watches container restart counts. If a component restarts, a toast appears naming it and the number of new restarts. This is the fastest way to notice a crash-looping component without watching the table.
{% hint style="info" %}
Toasts are only shown in the desktop layout. On a narrow screen you will not see restart notifications — check the **Restarts** column instead.
{% endhint %}
## Empty state
**No application status** — *The validator has not reported any application status yet.* Normal for the first few seconds after applying a `Validator`; persistent otherwise, check the operator logs.
# Status & Specification
The conditions the operator posted, and the validator's configuration as applied. Status is what the operator reports, Specification is what you asked for.
## Status
### Metric cards
Each card appears only when the underlying value has been reported.
Card
Values
Database
Provisioned or Pending — whether the participant and validator databases have been created.
Auth Provisioned
Yes or No — whether managed authentication has completed. Only meaningful when managedKeycloak is enabled.
Observed Generation
The generation of the Validator resource the operator last reconciled.
{% hint style="info" %}
**Observed Generation is the field to check after editing a validator.** If it lags behind the resource's current generation, your change has not been reconciled yet — or the reconcile is failing, in which case the conditions table below will say why.
{% endhint %}
### Conditions
| Column | Contents |
| ------------------- | ------------------------------------------------ |
| **Type** | The condition type. In practice, always `Ready`. |
| **Status** | `True`, `False`, or `Unknown`. |
| **Reason** | A short machine-readable cause. |
| **Message** | A human-readable explanation. |
| **Last transition** | When the status last changed. |
The reasons you will see:
Reason
What to do
AllApplicationsReady
Nothing — the validator is healthy.
ApplicationNotReady
Go to Summary and find which component is Pending.
InvalidSpec
A configuration error. The message names the exact field. Fix the Validator resource and re-apply.
ReconcileError
Something outside the configuration failed — often the database or identity provider being unreachable. Check the operator logs.
Empty state: **No conditions reported** — *The controller has not posted any conditions for this validator.*
***
## Specification
The validator's configuration, as it exists in the cluster, grouped by section: **Network**, **Participant**, **Validator**, **UI**, **Overrides**, then anything else alphabetically. Each group header shows how many fields it contains, and all groups are expanded by default.
* Booleans display as `Yes` / `No`.
* Long identifiers are truncated with a **Copy** button that copies the full value.
* Empty values show as `-`.
### What is deliberately hidden
{% hint style="warning" %}
This tab is **not** a faithful dump of the resource. Several things are filtered out by design:
* Any field whose path contains `secret`, `password`, `token`, `credential`, `privateKey`, `clientSecret`, or `apiKey`, plus the onboarding secret name — these are never displayed.
* Fields that are set to their default of `enabled: true`. Only `enabled: false` is shown, so an absent `enabled` row means the component is enabled.
For the complete resource, use `kubectl get validator -o yaml`.
{% endhint %}
This is also the fastest way to confirm that a field you set actually took effect. Unknown fields are silently pruned by the Kubernetes API server, so a misspelled field name disappears without an error — if a setting seems to be ignored, look for it here first.
Empty state: **No spec fields** — *No specification fields available.*
# Balances & Traffic
Two read-only tabs covering the validator's economic position on the network: Canton Coin holdings and synchronizer traffic counters.
{% hint style="info" %}
Both tabs are **read-only in 2.0**. There is no top-up, purchase, mint, or transfer action in the UI in this release. Traffic purchases and Canton Coin transfers are performed through the Wallet UI or the Canton console.
{% endhint %}
## Balances
Canton Coin holdings, read from the network's Scan service.
### Metric cards
| Card | Meaning |
| ------------------ | ------------------------------------------------------ |
| **Total holdings** | The validator's total Canton Coin balance |
| **Unlocked** | The portion available to spend |
| **Locked** | The portion locked in contracts. Amber when above zero |
### Snapshot
Row
Meaning
Owner party
The party the balance belongs to.
Available coin
Spendable amount at the time of the snapshot.
Record time
Ledger time the snapshot was taken.
Migration ID
The Canton migration this balance is recorded against.
Computed as of round
The mining round the figures were computed for.
### Holding Fees
**Total**, **Unlocked**, and **Locked** holding fees — the ongoing cost of holding Canton Coin.
All amounts are formatted to exactly two decimal places, with thousands separators. A missing value shows as `—`.
### States
| Situation | What you see |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Scan has no balance for this validator yet | **No balance returned** — *Scan endpoint reported no balance for this validator yet.* Normal for a newly onboarded validator |
| The request failed | **Failed to load balances**, with the error |
***
## Traffic
Synchronizer traffic counters, read from the participant.
Canton meters the data a participant sends through the synchronizer. Each participant gets a base allowance that refills over time, and can purchase extra traffic beyond it. This tab shows where the validator stands against both.
### Metric cards
All three are byte-formatted (`B`, `KB`, `MB`, `GB`).
| Card | Meaning |
| ------------------ | --------------------------------- |
| **Extra consumed** | Purchased traffic consumed so far |
| **Extra limit** | Total purchased traffic allowance |
| **Base remaining** | Remaining base allowance |
{% hint style="warning" %}
When **Base remaining** is near zero and **Extra consumed** is approaching **Extra limit**, the participant is close to being throttled by the synchronizer, and command submission will start failing. Purchase additional traffic through the Wallet UI before that happens.
{% endhint %}
### Routing
**Domain ID**, **Participant ID**, and **Endpoint**, each with a copy button. Shown when the synchronizer reports them.
### Counters
**Last consumed cost**, plus any additional counters the synchronizer returns, with humanised labels. The set of counters depends on the Canton protocol version, so this section is deliberately open-ended.
### States
| Situation | What you see |
| ------------------ | ----------------------------------------------------------------------- |
| Loading | *Loading traffic status…* |
| No counters yet | **No traffic data** — *The synchronizer has not reported counters yet.* |
| The request failed | **Failed to load traffic**, with the error |
# Parties
The Parties tab shows the parties this participant hosts, the hosting proposals waiting on it, and a lookup for any party on the synchronizer — and it is where all party operations start.
{% hint style="info" %}
This page describes the screens. For the concepts — what an external party is, what multi-hosting means, and the complete onboarding and approval workflow — see [External & Multi-Host Parties](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties).
{% endhint %}
## Header actions
| Button | Opens |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Onboard External Party** | The four-step external party onboarding wizard. For what each step does and why, see [Onboarding an external party](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties#onboarding-an-external-party). |
| **Allocate Party** | The Allocate Party modal |
## Sub-tabs
Sub-tab
Shows
Hosted Parties
Parties currently hosted by this participant.
Hosting Proposals
Hosting proposals naming this participant that are not yet fully authorized. Badged with a count when there are any.
Browse Parties
Lookup for any party known to this participant, including parties hosted elsewhere.
***
## Hosted Parties
*Parties currently hosted by this participant.*
Column
Contents
Party ID
The party's full identifier, truncated, with a copy button.
Permission
One badge per distinct permission across the party's hosts: submission, confirmation, or observation.
Threshold / Hosts
A row of dots — one per host that can confirm, filled up to the confirmation threshold. Hover for "N of M confirming participant(s) must confirm". Falls back to a plain ratio when there are more than eight.
Rows are sorted by permission strength — submission, then confirmation, then observation — and then by party ID.
**Permission filter.** A button group above the table filters to **All**, **Submission**, **Confirmation**, or **Observation**. A party matches if any of its hosts holds that permission.
**Refresh.** Reading the topology mapping is comparatively slow, so this list has an explicit refresh button rather than polling. While it loads you will see *Loading topology mapping, this may take a while…*
### Expanding a row
An expanded row shows **Hosted on (`n`)** — every participant hosting the party, with its permission, sorted by permission strength. A participant still being onboarded carries an `onboarding` badge.
For a party whose keys are held externally, the expanded row also offers **Edit hosting**, which opens the hosting amendment flow. See [External & Multi-Host Parties](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties#changing-a-partys-hosting).
{% hint style="info" %}
**Edit hosting only appears for externally-signed parties.** A party managed by the participant itself has no external key holder to sign a hosting change, so its hosting cannot be amended this way.
{% endhint %}
### States
| Situation | What you see |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| No hosted parties | **No hosted parties** — *This participant has not authorized any PartyToParticipant mappings yet.* |
| Filter matches nothing | **No matching parties** — *No hosted party has a participant with `` permission.* |
| Load failed | **Failed to load hosted parties**, with the error |
***
## Hosting Proposals
*Hosting proposals naming this participant that are not yet authorized by everyone involved. These parties cannot be used until each named host approves. Approving makes this participant co-host the party — it replicates that party's data and takes part in confirming its transactions.*
Only proposals that name **this** participant are listed. The synchronizer's topology store is shared across the whole network and can hold hundreds of proposals; the rest are filtered out.
Column
Contents
Party ID
The party being proposed.
Hosting Participants
Every named host. Your own participant is tagged this participant.
Threshold
The proposed confirmation threshold.
—
The action, or the current waiting state.
The action cell shows one of:
| | Meaning |
| ------------------------------ | ---------------------------------------------------------- |
| **Approve** | This participant is required to authorize, and has not yet |
| *Approved — updating topology* | You approved just now; the change is still propagating |
| *Waiting on other hosts* | This participant has already authorized; others have not |
### Approving
Clicking **Approve** authorizes immediately — **there is no confirmation dialog.** The result appears as a toast:
| Toast | Meaning |
| ------------------------------------------------- | ------------------------------------------------------------- |
| *Hosting approved — the party is now active* | Every named host has now authorized |
| *Hosting approved — still waiting on other hosts* | Your authorization is recorded; the party is still not usable |
| *Approval failed* | With the reason |
After approving, the row's button disappears and the list polls for up to 30 seconds until the synchronizer agrees, so you do not need to refresh manually.
{% hint style="warning" %}
Approving is a real commitment. This participant will store that party's data and take part in confirming its transactions. Only approve proposals you recognise.
{% endhint %}
Empty state: **Nothing pending** — *Every party hosting involving this participant is fully authorized.*
***
## Browse Parties
*Search any party known to this participant by ID prefix, including parties hosted elsewhere on the synchronizer.*
Type at least **two characters** of a party ID prefix and press Enter or **Search**.
| Column | Contents |
| --------------------- | --------------------------------------------------------- |
| **Party ID** | The party's identifier |
| **Identity Provider** | The identity provider ID, or `default` |
| **Scope** | `Local` if hosted on this participant, `Remote` otherwise |
{% hint style="info" %}
This is a **prefix search, not a full listing.** On a production network a participant may know of hundreds of thousands of parties, so there is deliberately no "list all" — you must know roughly what you are looking for. Use **Hosted Parties** for the complete list of parties this participant hosts.
{% endhint %}
If nothing matches, the UI offers **Allocate "``"**, which opens the Allocate Party modal pre-filled with the term.
***
## Allocate Party
*Provision a new party on this validator. The hint is incorporated into the generated party ID.*
| Field | |
| ----------------- | -------------------------------------------------------------------------------------- |
| **Party ID hint** | *Choose a short, human-readable hint. Backend appends a hash for uniqueness.* Required |
Buttons: **Cancel** and **Allocate**. On success a toast reports *Party allocated* with the resulting party ID, and both lists refresh.
{% hint style="info" %}
This allocates a **participant-managed** party — the participant holds its keys and can submit on its behalf. To create a party whose keys are held outside the participant, use **Onboard External Party** instead.
{% endhint %}
# DARs
The DARs tab lists every Daml package the participant knows about, and lets you upload new ones.
## Columns
Column
Contents
Name
The package name.
Version
The package version.
Package ID
The full package hash, truncated, with a copy button.
Size
Package size.
Known since
When the participant first saw the package.
## Searching
The search box matches on **name, version, or package ID**, and is forgiving: it matches substrings and in-order character sequences, so partial or approximate terms work. Search results replace the table; clear the box to return to the full list.
## Uploading a DAR
{% stepper %}
{% step %}
**Click `Upload .dar`**
A file picker opens, filtered to `.dar` files.
{% endstep %}
{% step %}
**Choose the file**
An upload strip appears below the toolbar showing the file name, its size, a progress bar, and the status **Ready to upload**.
{% endstep %}
{% step %}
**Click the upload button**
The status changes to **Uploading…** and the progress bar advances.
{% endstep %}
{% step %}
**Check the result**
On success the status becomes **Uploaded ``** and the package list refreshes. On failure the error message from the participant is shown in place of the status.
{% endstep %}
{% endstepper %}
Use the dismiss button to clear the strip and pick a different file.
{% hint style="danger" %}
**There is no confirmation step.** Clicking upload sends the DAR to the participant immediately. Uploading a Daml package cannot be undone — packages are permanent on the ledger — so check you have the right file and the right validator first.
{% endhint %}
{% hint style="warning" %}
The file picker will accept a file that is not really a DAR. Validation happens on the participant, so an invalid file produces an upload error rather than being rejected in the browser.
{% endhint %}
{% hint style="info" %}
Very large DARs may be rejected before reaching the participant, by the request size limit on the API. If a large upload fails with a size-related error rather than a Daml error, raise it with IntellectEU support — the limit is a platform setting, not something you can change from the UI.
{% endhint %}
## States
| Situation | What you see |
| ---------------------- | ------------------------------------------------------------------------------------- |
| No packages | **No DAR packages yet** — *Upload a .dar file to deploy contracts to this validator.* |
| Search with no matches | **No packages match** — *Try a different search term.* |
| Load failed | **Failed to load DAR packages**, with the error |
# Participant & Keys
Two read-only tabs that expose what the Canton participant node itself reports: Participant node health, synchronizer connections, identity, and keys.
## Participant
The deepest health view in the UI. When something is wrong at the Canton level rather than the Kubernetes level, this is the tab that tells you. The heading carries the participant **Version** beside it.
### While initialising
If the node has not finished initialising, the tab shows only:
* **Initialized** — `false`
* **Active** — `Yes` / `No`
* **Waiting for** — what the node is blocked on
{% hint style="info" %}
**Waiting for** is the single most useful field during onboarding. A participant that sits here for a long time is usually waiting on the synchronizer or on network onboarding to complete, not failing.
{% endhint %}
### Once initialised
| Card | Meaning |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Active** | Whether this is the active instance |
| **Uptime** | Live-ticking, formatted `1d 2h 3m 4s` |
| **Connected Synchronizers** | One row per synchronizer, with its ID (copyable) and health. This is where a lost synchronizer connection shows up first. |
| **Topology Queues** | The depth of the **Manager**, **Dispatcher**, and **Clients** queues. Sustained non-zero values mean topology changes are backing up. |
| **Identity** | The participant's **UID**, its **Endpoint**, and the **Protocol Versions** it supports. |
| **Ports** | The ports the node exposes. |
| **Components** | The participant's internal health components, each with a status and description. Component names are truncated after the `::` separator, with the full name in the tooltip. |
### Health values
The status values are Canton's own, colour-coded by the UI:
| Value | Reading |
| ------------------------------ | -------- |
| `ok`, `healthy` | Healthy |
| `degraded` | Degraded |
| `failed`, `fatal`, `unhealthy` | Failed |
| anything else | Unknown |
### States
| Situation | What you see |
| -------------- | ------------------------------------------------------------------------ |
| Loading | *Loading participant status…* |
| No status | **No participant data** — *The participant has not reported status yet.* |
| Request failed | **Failed to load participant status**, with the error |
{% hint style="info" %}
This tab is entirely read-only. There is no restart, reconnect-synchronizer, or pruning action. For participant-level administration, use the [Canton console](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/canton-console).
{% endhint %}
***
## Keys
The public keys held in the participant's key vault.
| Column | Contents |
| ------------ | ------------------------------------- |
| **Name** | The key's name, or `—` |
| **Purpose** | `signing` or `encryption` |
| **Key Spec** | The cryptographic algorithm and curve |
| **Usage** | One badge per declared usage |
| **Format** | The key's encoding |
### What this tab tells you
It is the quickest way to confirm that KMS integration is working. With a KMS configured, the participant's operational keys are created and held in the key vault rather than in the participant database — and they appear here either way, so use the **Key Spec** and your KMS provider's own console to confirm where the private material actually lives.
### States
| Situation | What you see |
| -------------- | -------------------------------------------------------------- |
| No keys | **No keys** — *The participant vault returned no public keys.* |
| Request failed | **Failed to load keys**, with the error |
{% hint style="info" %}
Read-only. Key generation, rotation, import, and export are not exposed in the UI — they are participant and KMS operations. See [Key Management Service (KMS)](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/kms-integration).
{% endhint %}
# Users & Wallet Users
Two tabs covering two different kinds of user: Ledger users with their rights, and users onboarded to the Wallet UI.
## Overview
Tab
Manages
Users
Ledger users on the Canton participant. A ledger user has rights over specific parties, and is what an application authenticates as when it talks to the Ledger API.
Wallet Users
Wallet UI users registered with the validator app, so a person can sign in to the Canton Wallet.
Neither creates an account in your identity provider. Both assume the identity already exists there.
***
## Users
The heading shows the count: *`n` users provisioned on this validator.*
### Columns
| Column | Contents |
| --------------------- | -------------------------------------- |
| **Username** | The ledger user ID |
| **Primary party** | The party the user acts as by default |
| **Identity provider** | The identity provider ID, or `default` |
| **Active** | `Active` or `Deactivated` |
| — | Edit action |
### Viewing rights
Clicking a row opens a read-only drawer showing the user's rights, grouped by kind:
Right
Grants
Participant admin
Full administrative control of the participant.
Identity provider admin
Administration of identity provider configuration.
Can read as any party
Read access to every party's data on this participant.
Can execute as any party
Execution on behalf of any party.
Can act as
Submitting commands on behalf of the listed parties.
Can read as
Reading the listed parties' data.
Can execute as
Executing on behalf of the listed parties.
The drawer's **Edit Rights** button moves you into the editor.
{% hint style="danger" %}
The first four are **participant-wide** rights, not party-scoped. `Participant admin` and `Can read as any party` in particular give access to every party's data on the node. Grant them sparingly, and prefer the party-scoped rights below them.
{% endhint %}
### Creating a user
{% stepper %}
{% step %}
**Click `Create User`**
*Provision a new participant user with a primary party and rights.*
{% endstep %}
{% step %}
**Fill in Basic info**
**User ID** is required — for example `analyst-01`. **Primary party** is optional.
{% endstep %}
{% step %}
**Grant rights**
Under **Rights**, add parties to **Can act as**, **Can read as**, and **Can execute as**. Type a party and press Enter — each becomes a removable chip. Under **Global flags**, tick any participant-wide rights.
{% endstep %}
{% step %}
**Click `Create`**
The modal closes on success.
{% endstep %}
{% endstepper %}
### Editing a user
The pencil icon on a row, or **Edit Rights** in the drawer, opens the same modal in edit mode: *User ID is read-only. Primary party, status, annotations and rights can be changed.*
Edit mode adds:
* a **Deactivated** checkbox — *user cannot authenticate to the ledger*;
* an **Annotations** section for arbitrary key/value metadata on the user.
{% hint style="warning" %}
**Saving rights replaces them wholesale.** The editor is not additive — the rights shown when you save become the user's complete set, and anything you removed is revoked. Always open the editor from the row or drawer so it is pre-populated with the current rights, rather than reconstructing them from memory.
{% endhint %}
{% hint style="info" %}
There is no success toast for user create or edit. The modal simply closes. Confirm the change landed by reopening the user's rights drawer.
{% endhint %}
### States
| Situation | What you see |
| ----------- | ------------------------------------------------------------------ |
| No users | **No users yet** — *Create the first user to grant ledger access.* |
| Load failed | **Failed to load users**, with the error |
***
## Wallet Users
The heading shows the count: *`n` users registered with the wallet UI.*
| Column | Contents |
| ------------ | --------------------------------------- |
| **Username** | The wallet username, with a copy button |
| **Status** | Always `Active` |
| — | Remove action |
{% hint style="info" %}
**Status is always `Active`.** The validator app only returns usernames, so there is no other state to show. Treat the column as informational.
{% endhint %}
### Adding a wallet user
**Add Wallet User** — *Enter a username to onboard someone to the wallet UI.* Enter the **Username** and click **Add user**. A toast confirms *Wallet user added*.
The UI checks for duplicates before submitting and warns *Username already exists* rather than sending the request.
{% hint style="warning" %}
The username must match the user's identity in your identity provider. Onboarding a username that does not exist there creates a wallet user nobody can sign in as.
{% endhint %}
### Removing a wallet user
The trash icon opens a confirmation: *Offboard "``" from the wallet UI. This cannot be undone.* Confirm with **Remove**.
{% hint style="danger" %}
This is the **only destructive action in the UI that asks for confirmation**, and it cannot be undone. The validator refuses to offboard its own wallet user, so that request will fail with a conflict rather than breaking the validator.
{% endhint %}
### States
| Situation | What you see |
| --------------- | ----------------------------------------------------------------------------------- |
| No wallet users | **No wallet users yet** — *Add a username to give someone access to the wallet UI.* |
| Load failed | **Failed to load wallet users**, with the error |
# Identity & Endpoints
OIDC configuration and the identity dump download, plus the URLs each component exposes.
## Identity
*Managed Keycloak realm and OIDC client configuration for this validator.*
The fastest way to confirm that a validator's authentication is wired up as you intended.
### Metric cards
| Card | Values |
| -------------------- | ----------------------- |
| **Auth enabled** | `Yes` / `No` |
| **Managed Keycloak** | `Managed` or `External` |
| **Provisioned** | `Yes` / `No` |
### Realm
Each row appears only when the value is set, and each is copyable:
**Auth URL** · **Target Audience** · **Ledger API client ID** · **Ledger API user** · **CNS UI client ID** · **Wallet UI client ID** · **Wallet user** · **Management Scope**
With managed authentication these are the values the operator provisioned. With an external identity provider they are the values you supplied on the `Validator` resource — so if a component is failing to authenticate, check them here first against what actually exists in your identity provider.
### Authenticated user
| Row | Meaning |
| --------------------- | -------------------------------------------- |
| **User ID** | The ledger user the API is authenticating as |
| **Primary party** | That user's default party |
| **Identity provider** | The identity provider ID, or `default` |
| **Status** | `Active` or `Deactivated` |
{% hint style="info" %}
If this section fails to load, the API could not authenticate against the participant. That usually means the OIDC client secret, the audience, or the scope is wrong — the values above are where to look.
{% endhint %}
### Identity dump
The **Identity Dump** button downloads the participant's identity export as `-identities.json`.
{% hint style="danger" %}
**An identity dump is the validator's cryptographic identity.** Anyone holding it can reconstruct the node's identity on the network. Treat it exactly as you would a private key:
* store it in a secrets manager, not in a shared drive, ticket, or chat;
* never commit it to a repository;
* transfer it only over encrypted channels.
There is no confirmation step — clicking the button downloads the file immediately.
{% endhint %}
You need this file if the participant's database is ever lost or corrupted beyond recovery. See [Identity Dumps & Database Backups](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-dumps).
### States
| Situation | What you see |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| No managed authentication section | **No identity payload** — *No managedAuth section returned for this validator.* Expected when using an external identity provider |
| User lookup failed | **Failed to load user**, with the error |
***
## Endpoints
*Network endpoints exposed by this validator and its applications.*
Endpoints are grouped by the component that owns them, and each group lists:
| Label | Meaning |
| ------------ | ------------------------------------------------------ |
| **Internal** | The in-cluster address, reachable from other workloads |
| **External** | The public address through the ingress |
Every URL has a copy button. `https://` URLs render as links you can open directly.
### What you use these for
* **External** URLs are what you give to people — the Wallet UI and CNS UI addresses for end users, and the Wallet Gateway address where enabled.
* **Internal** URLs are what you give to applications running in the same cluster — a Daml application connecting to the Ledger API, for instance, should use the internal participant address rather than going out through the ingress.
{% hint style="info" %}
Only components with an ingress route have an **External** URL. The participant and the validator app are deliberately not exposed publicly; to reach the Ledger API from outside the cluster, front it yourself with appropriate authentication and network controls.
{% endhint %}
### States
| Situation | What you see |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| Loading | *Loading endpoints…* |
| None reported | **No endpoints exposed** — *The validator and its applications have not reported any addressable endpoints.* |
| Load failed | **Failed to load endpoints**, with the error |
# Applications
Application component-level health and resource usage across every validator.
Where the Validators list is organised by validator, the Applications list is organised by **component**. It is the view to use when you are chasing a resource problem, a crash loop, or a configuration question about one specific workload.
{% hint style="info" %}
Applications are created and owned by the operator. Nothing on these screens changes them — to change a component, change the `Validator` resource that owns it.
{% endhint %}
## Overview
### Columns
Column
Contents
Name
The application resource name, <validator>-<component>.
Type
Participant, Validator, Wallet UI, CNS UI, PQS, or Wallet Gateway.
Validator
Link to the owning validator.
Replicas
ready / desired.
Restarts
Container restart count.
CPU
Utilisation bar and percentage, with used / limit beneath.
Memory
Same, in bytes.
Status
Ready, or the operator's reason for not being ready, or Unknown.
### States
| Situation | What you see |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| No applications | **No applications found** — *No Canton applications are deployed in this cluster.* |
| Filtered, none match | **No applications for this validator** — *No Canton applications are deployed for validator "``".* |
| Load failed | **Failed to load applications**, with the error |
***
## Application details
Clicking a row opens a single scrolling page.
### Overview Cards
| Column | Contents |
| -------- | ------------------------------------------------------------------------------ |
| Status | `Ready`, or the operator's reason for not being ready, or `Unknown`. |
| Replicas | `ready / desired`. |
| Restarts | Container restart count. |
| Type | `Participant`, `Validator`, `Wallet UI`, `CNS UI`, `PQS`, or `Wallet Gateway`. |
| Port | The port the component's service listens on. |
| CPU | Utilisation bar and percentage, with `used / limit` beneath. |
| Memory | Same, in bytes. |
### Resources by replica
| Column | Contents |
| --------------------------------------- | ---------------------------------------------- |
| **Replica** | The pod name |
| **Phase** | The Kubernetes pod phase. `Running` is healthy |
| **Restarts** | Restart count for that pod |
| **CPU (used / limit)** · **CPU req** | CPU usage against limit, and the request |
| **Memory (used / limit)** · **Mem req** | Memory usage against limit, and the request |
{% hint style="warning" %}
If a note says the cluster metrics API is not reachable, `metrics-server` is missing or unhealthy. Requests and limits still show; live usage does not.
{% endhint %}
### Endpoints
**Internal** and **External** URLs, plus **Metrics** and **Logs**, which render as **Open in Grafana** links.
### Conditions
The component's Kubernetes conditions — **Type**, **Status**, **Reason**, **Message**, **Last transition**. `DeploymentNotFound` means the workload has not been created yet; `DeploymentUnavailable` means it exists but has too few available replicas.
### Environment variables
Every variable the operator set on the container, sorted by name, with a **Copy all** button that copies them as `NAME=value` lines.
{% hint style="info" %}
Values sourced from a Kubernetes Secret or another reference show a **`from secret`** or **`from ref`** badge instead of the value. Secret values are never displayed in the UI.
{% endhint %}
This is the most direct way to confirm how the operator configured a component — which auth URL the participant is using, which database it connects to, which network endpoints it was given.
### Specification
The application resource's fields as **Field** / **Value** pairs, excluding the environment variables, which have their own section.
# Canton Console
The Canton Console panel gives you a live, interactive Canton console attached to a participant node, from the UI, without cluster or shell access.
{% hint style="danger" %}
**This is full administrative access to the participant node.** A Canton console session can read any party's data, change topology, and alter ledger state. It is the most privileged surface in the platform, and there is no read-only mode and no confirmation on anything you type.
Restrict who can obtain a console token in your identity provider, and treat access to the CatalyX UI as equivalent to participant administrator access.
{% endhint %}
## Where to find it
The panel sits on the [Dashboard](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/dashboard), directly below the summary cards. It is the only place in the UI where it appears — there is no separate page and no per-validator console.
It starts collapsed. Click the bar labelled **Canton Console** to expand it; the terminal and its connection are created the first time you do.
## Using the Canton Console
Once expanded, a status indicator appears beside the title:
| Status | Meaning |
| ----------- | --------------------- |
| `idle` | Not connected |
| `connected` | Session established |
| `error` | The connection failed |
Type commands directly into the terminal, exactly as you would in a Canton console attached to the node. Output is streamed back live. The terminal keeps 5,000 lines of scrollback.
**Reconnect** clears the terminal and opens a fresh session — useful if the connection has dropped or the session has become unresponsive.
Two messages come from the console itself rather than from Canton:
| Message | Meaning |
| ------------------------ | ---------------------------------------------------- |
| `[Connection error]` | The connection could not be established or was lost |
| `[Disconnected: ]` | The session closed unexpectedly, with the close code |
## What to use it for
The console exists to cover what the graphical UI deliberately does not:
Task
Why here
Topology inspection and changes
Beyond the read-only views and the external-party flows on the Parties tab.
Diagnostics
health.status and similar commands, when the Participant tab does not give enough detail.
One-off administrative operations
Anything Canton supports that has no CatalyX equivalent.
### Canton console command reference
The commands themselves — what you type into the terminal — are Canton's, not CatalyX's, so they are documented upstream rather than duplicated here.
{% hint style="info" %}
See the official Canton Network documentation for the full [**Canton console command reference**](https://docs.canton.network/global-synchronizer/reference/canton-console-commands#canton-console-commands) — the admin console commands for participant, mediator, sequencer, and topology nodes.
{% endhint %}
## Session behaviour
**Collapsing does not disconnect.** The panel hides the terminal but keeps the session alive, so you can collapse it, navigate around the UI, and come back to the same session with its history intact.
**Sessions are per user and reused.** Reconnecting typically reattaches you to your existing session rather than starting a new one, and recent output is replayed.
**Idle sessions are reclaimed** after roughly ten minutes with nothing attached.
{% hint style="info" %}
The session attaches to a running participant pod. If no participant pod is running, the console reports that instead of connecting — check the validator's [Summary](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/summary) tab first.
{% endhint %}
## Security notes for operators
{% hint style="warning" %}
Two properties of the current implementation are worth knowing when you assess this feature:
* **The session's access token is passed in the connection URL.** It may therefore be recorded in proxy and load-balancer access logs. Review your log retention accordingly.
* **The token is validated once, when the session is established.** An attached session is not re-checked afterwards, so it can outlive the token's expiry. Sessions are reclaimed on idle timeout rather than on token expiry.
If either is unacceptable in your environment, block the console's WebSocket path at your ingress and use a Canton console attached out-of-band instead.
{% endhint %}
# Grafana Dashboards
The CatalyX UI does not embed dashboards. Instead it links out to your Grafana instance, pre-filtered to the component you were looking at — so you land on the right data rather than a blank dashboard
## Where the links are
All of them open in a new tab, so you keep your place in the UI.
## What each link opens
**Logs** opens Grafana's Loki log explorer, filtered to the component's service name, over the **last 24 hours**, newest first.
**Metrics** opens the Canton participant dashboard, filtered to that participant, over the **last hour**, refreshing every five minutes.
{% hint style="info" %}
**Metrics links only appear for participant components.** The participant is the component with a Canton-specific dashboard; other components expose standard Kubernetes workload metrics, which you can reach through your own dashboards. Logs are available for every component.
{% endhint %}
## Configuration
Set at install time, in the Helm values:
Value
Purpose
ui.grafana.baseUrl
Base URL of your Grafana instance.
ui.grafana.dataSource
Optional. The UID of the Loki data source to query, when Grafana has more than one.
{% hint style="warning" %}
**The Grafana buttons are always rendered**, whether or not `ui.grafana.baseUrl` points at a reachable Grafana. If you have not configured it, the links will open a broken page rather than being hidden. Set `ui.grafana.baseUrl` as part of every install.
{% endhint %}
## Prerequisites
For these links to resolve to real data you need:
* **Grafana**, reachable by the people using the UI.
* **Loki**, receiving logs from the cluster, for the log links.
* **Prometheus**, scraping validator component metrics, for the metrics links. Enable `monitoring.serviceMonitor.enabled` in the Helm values if you use the Prometheus Operator.
* **The Canton participant dashboard** installed in your Grafana. Contact IntellectEU support for the dashboard definition.
{% hint style="info" %}
The resource figures shown *inside* the UI — the CPU and memory bars on the lists and detail pages — do not come from Prometheus. They come from the Kubernetes metrics API, which requires `metrics-server` in the cluster. Prometheus and Grafana are only needed for the deep links.
{% endhint %}
# Validator Management
This section covers creating a validator, and the operational tasks that go beyond viewing its health: managing parties, protecting keys, adding optional components, & keeping a validator upgradable &
{% hint style="info" %}
Editing a `Validator` is a normal Kubernetes update — `kubectl apply`, `kubectl edit`, or a GitOps commit. Watch the **Observed Generation** on the validator's [Status](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/status-and-specification) tab to confirm your change was picked up.
{% endhint %}
# Create a Validator
A validator is declared as a single Validator custom resource. You apply it, and the operator provisions everything else to create the validator.
Validators are created, changed, and deleted through custom resources — not through the UI. This keeps validator configuration reviewable and GitOps-friendly. The UI is where you *operate* a validator once it exists.
## What the operator does
{% stepper %}
{% step %}
**Provisions authentication**
When `spec.auth.managedKeycloak` is `true`, the operator creates the OIDC clients, client scopes, protocol mappers, and wallet user for this validator, then writes the generated backend client secret to a Kubernetes Secret and records the result in `status.managedAuth`.
{% endstep %}
{% step %}
**Provisions databases**
The participant and validator-app databases and schemas are created, plus the PQS and Wallet Gateway databases when those components are enabled.
{% endstep %}
{% step %}
**Creates the component applications**
One child `Application` resource per component: `participant`, `validator`, `wallet-ui`, `cns-ui`, and optionally `pqs` and `wallet-gateway`.
{% endstep %}
{% step %}
**Creates the workloads**
Each `Application` becomes a `Deployment`, a `Service`, and — for externally reachable components — a Traefik `IngressRoute`.
{% endstep %}
{% endstepper %}
The validator reports `Ready` once every component it owns is ready.
***
## Prepare the secrets
Two secrets are needed in the validator's namespace before you apply.
```bash
# Database credentials — must be able to CREATE DATABASE
kubectl create secret generic my-validator-db-credentials \
--from-literal=username= \
--from-literal=password= \
-n
# One-time onboarding secret from the sponsoring Super Validator
kubectl create secret generic my-validator-onboarding \
--from-literal=secret= \
-n
```
{% hint style="danger" %}
The onboarding secret's key **must be `secret`**. The operator reads that exact key name.
{% endhint %}
If you are using an external identity provider rather than managed authentication, you also need a secret holding the backend OIDC client secret — see [External Identity Provider](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-provider-configuration/external-identity-provider).
***
## A minimal Validator
This example relies on managed authentication and on operator defaults for every component. It is the shortest useful `Validator`.
{% code title="my-validator.yaml" %}
```yaml
apiVersion: catalyx.manager.canton/v1alpha1
kind: Validator
metadata:
name: my-validator
namespace:
spec:
auth:
managedKeycloak: true
targetAudience: https://canton.network.global
ledgerApiUserManagementScope: daml_ledger_api
network:
spliceVersion: "0.6.4"
partyHint: catalyx-devnet-001
onboardingSecretName: my-validator-onboarding
sponsorSvUrl: https://sv.sv-1.dev.global.canton.network.sync.global
scan:
address: https://scan.sv-1.dev.global.canton.network.sync.global
type: bft
seedUrls:
- https://scan.sv-1.dev.global.canton.network.sync.global
synchronizer:
connectionType: bft
url: https://sequencer.sv-1.dev.global.canton.network.sync.global
database:
host: postgres.default.svc.cluster.local
participantDb: participant_my_validator
validatorDb: validator_my_validator
credentialsSecretRef:
name: my-validator-db-credentials
```
{% endcode %}
```bash
kubectl apply -f my-validator.yaml
```
{% hint style="warning" %}
**`spec.network.partyHint` is pattern-validated.** It must match `^[a-zA-Z0-9]+-[a-zA-Z0-9]+-[0-9]+$` — that is, two alphanumeric segments and a numeric segment, separated by hyphens. `catalyx-devnet-001` is valid; `myvalidator` and `my_validator_1` are rejected at apply time.
{% endhint %}
{% hint style="info" %}
`spec.network.spliceVersion` sets one version for the participant, validator app, and both UIs. You can still pin any component individually with its own `version` field. Either the component `version` or `spliceVersion` must be set, or the validator is rejected.
{% endhint %}
## Required fields
Only three top-level blocks are mandatory, and the API server rejects the resource at apply time if any is missing:
Block
Mandatory fields inside
spec.auth
None individually, but the block itself is required.
{% hint style="warning" %}
`spec.network.scan` and `spec.network.synchronizer` are not marked mandatory in the schema, but the validator cannot reconcile without them. Always supply both.
{% endhint %}
For the complete field list, see the [Validator CRD Reference](/catalyx-blockchain-manager/canton-network/version-2.0/validator-crd).
***
## Watch it come up
```bash
kubectl -n get validators
kubectl -n get validators my-validator -o wide
```
The `Validator` resource prints a `READY` column, and `-o wide` adds the `REASON` for a validator that is not ready.
```bash
# Per-component detail
kubectl -n get validators my-validator -o jsonpath='{.status.applications}' | jq
# The child applications and their workloads
kubectl -n get applications
kubectl -n get pods -l app.kubernetes.io/instance=my-validator
```
Or open the UI and watch the validator's [Summary](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/summary) and [Status](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/status-and-specification) tabs, which refresh automatically.
## If it does not become ready
The `Ready` condition carries a reason that tells you which kind of problem you have:
Reason
Meaning
InvalidSpec
A configuration problem the operator detected. The condition message names the exact field. Fix the Validator and re-apply.
ReconcileError
Something went wrong that is not a configuration error — for example the database or identity provider was unreachable. Check the operator logs.
ApplicationNotReady
The configuration is accepted but a component has not come up. Look at status.applications to see which one, then at that component's pods.
```bash
kubectl -n logs deploy/catalyx-canton-operator
```
{% hint style="info" %}
Unknown fields are **silently pruned** by the Kubernetes API server. A misspelled field name is dropped without an error, and the setting simply has no effect. If a value seems to be ignored, check the spelling against the [CRD reference](/catalyx-blockchain-manager/canton-network/version-2.0/validator-crd) and confirm it survived with `kubectl get validator -o yaml`.
{% endhint %}
***
## Deleting a validator
```bash
kubectl -n delete validator my-validator
```
Kubernetes garbage-collects the child `Application` resources and their workloads.
{% hint style="danger" %}
Deleting a `Validator` does **not** remove:
* the **databases** — participant, validator, PQS, and Wallet Gateway data all remain;
* the **identity provider objects** created by managed authentication — clients, scopes, and users stay in the realm;
* the **managed authentication secret** `-managed-ledger-api-auth`.
Clean these up yourself if you are decommissioning a validator permanently. Retaining them is what makes it possible to recreate a validator against its existing state.
{% endhint %}
# External & Multi-Host Parties
Onboard parties whose signing keys live outside the participant, and host a single party across several participants.
Canton parties normally have their keys held by the participant that hosts them. Two capabilities change that, and they compose:
1. **External parties:** The party's signing key lives *outside* the participant — with the party's owner. The participant cannot act on the party's behalf; the owner signs its own transactions.
2. **Multi-hosting:** A single party is hosted on *several* participants, which may belong to different organisations. The party survives the loss of any one of them.
### External parties and how they work
For the concept of external parties and the difference with local parties, please refer to the Canton documentation:
{% embed url="" %}
### Why multi-host and how it works
For the concept and Canton's own guidance on resilience and disaster-recovery use cases, see Multi-Hosting and Resilience in the Canton documentation:
{% embed url="" %}
***
## Onboarding an external party
Start from **Parties → Onboard External Party** on the validator.
{% stepper %}
{% step %}
**Identity — the party's key**
*Provide the party's public key. The participant will generate topology transactions for you to sign.*
| Field | Notes |
| --------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Party hint** | 2–64 characters, letters, digits, hyphens, and underscores only. Incorporated into the generated party ID |
| **Key algorithm** | **Ed25519 (recommended)** or **ECDSA P-256** |
| **Public key (DER Base64)** | X.509 SubjectPublicKeyInfo, DER encoded, then Base64 |
The wizard shows the commands to produce a key pair:
```bash
openssl genpkey -algorithm ed25519 -out key.pem
openssl pkey -in key.pem -pubout -outform DER | base64 -w 0
```
Nothing is sent to the participant at this step. Click **Next: Hosting →**.
{% hint style="warning" %}
`key.pem` is the party's private key. Whoever holds it controls the party. Generate it on the party owner's own machine wherever possible, and store it in a secrets manager or hardware token — not alongside your platform configuration.
{% endhint %}
{% endstep %}
{% step %}
**Hosting — choose the host set**
*Choose which participants host this party. This cannot be changed later — the host set is covered by the signature.*
Leave this step untouched to host the party on your validator alone. Otherwise:
* **Add participant** adds a row. Enter the participant UID in `alias::fingerprint` form, and choose **Confirming** or **Observing**.
* Tick **This validator observes only (does not confirm)** if confirmation should rest entirely on the other hosts.
* Set the **Confirmation threshold**. The hint below it tells you how many confirming participants you currently have.
Participant UIDs are entered as free text rather than chosen from a list — a production synchronizer carries hundreds of participants, and the useful ones are usually on other clusters. A participant UID is a public identifier; naming one needs no credentials for that node.
**The advisory lookup.** When you leave a UID field, CatalyX checks it against the synchronizer and reports:
| Chip | Meaning |
| -------------------------------------------------------------------------------------------------- | ------------------------------ |
| *Checking synchronizer…* | Lookup in flight |
| *Known on this synchronizer* | The participant exists |
| *This is this validator — remove it, it is already a host* | You named your own participant |
| *Not found on this synchronizer… You can continue, but allocation will fail unless it joins first* | No match |
{% hint style="warning" %}
**The lookup warns; it never blocks.** Naming a participant that has not yet joined the synchronizer is legitimate — but the party's signature is spent at the next step, so a genuine typo costs you the whole onboarding. Resolve every warning before continuing.
All hosts must be on the **same synchronizer**. A participant that is absent from your local topology store — including one whose validator has been offline long enough to fall behind — will not resolve, and allocation will fail.
{% endhint %}
Click **Generate Transactions →**.
{% endstep %}
{% step %}
**Sign the multi-hash**
*Sign the hash below with your private key and paste the Base64 signature.*
The participant has generated the party ID and a **multi-hash** covering the topology transactions. When you named co-hosts, a **Co-hosts** line reports how many additional participants must authorize.
Give the multi-hash to the party's key holder to sign. The wizard shows the command for the chosen algorithm:
```bash
echo "" | base64 --decode > hash.bin
openssl pkeyutl -sign -inkey key.pem -rawin -in hash.bin | base64
```
Paste the Base64 signature into **Signature (Base64)** and click **Complete Onboarding**.
{% hint style="danger" %}
This is the point of no return for the host set. If allocation fails because a named participant does not exist, the signature is consumed — you cannot retry with a corrected host list. Start again with a **fresh party hint**.
{% endhint %}
{% endstep %}
{% step %}
**Distribute — wait for the co-hosts**
Single-hosted, the wizard reports **External Party Onboarded** — *Hosted on this validator alone. The party is ready to use.*
Multi-hosted, it reports **Awaiting Other Hosts** and lists each participant still owing approval:
> The party is **not usable yet**. Each participant above must approve hosting it. The request is already visible to them — it appears under Hosting Proposals on their own Parties tab, whether they are in this cluster or another one. Nothing needs to be sent to them.
Click **Done**.
{% endstep %}
{% endstepper %}
***
## Approving a hosting proposal
This is the other half of the workflow, performed by each co-host's operator.
{% stepper %}
{% step %}
**Open Parties → Hosting Proposals**
The proposal is already there. Nothing was sent to you and there is nothing to import — the synchronizer's topology store is shared, and the proposal already carries the party's signature.
{% endstep %}
{% step %}
**Check what you are agreeing to**
The row shows the party ID, every named host with your own participant tagged **this participant**, and the confirmation threshold.
{% hint style="warning" %}
Approving means this participant will store that party's data and take part in confirming its transactions. Only approve proposals you recognise.
{% endhint %}
{% endstep %}
{% step %}
**Click Approve**
There is no confirmation dialog. A toast reports either *Hosting approved — the party is now active* or *Hosting approved — still waiting on other hosts*.
Rows where this participant has already authorized show *Waiting on other hosts* instead of a button.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
**Approval is safe to repeat.** Re-submitting an identical approval succeeds rather than erroring, so retrying after a network failure is harmless.
**A participant is only asked to approve when it takes on more responsibility** — when it is being added as a host, or when its permission is being strengthened. If you are named in a proposal but see no **Approve** button, nothing is required of you.
{% endhint %}
***
## Changing a party's hosting
{% hint style="info" %}
**Version note.** Hosting amendments were added after 2.0.0 and are newer than the onboarding flow above. Exercise them in a non-production environment first.
{% endhint %}
Hosting on an existing party can be changed: add a host, remove one, change a permission, or change the threshold. All four are the same operation — the party's hosting mapping is replaced at the next serial.
Open **Parties → Hosted Parties**, expand the party, and click **Edit hosting**.
{% stepper %}
{% step %}
**Edit Hosting**
*Replace the full set of participants hosting this party. Anything removed here stops hosting it.*
The current host set and threshold are pre-filled. Edit them, then click **Prepare Change →**.
{% hint style="danger" %}
**This is a replacement, not a delta.** What you leave in the list becomes the party's complete new host set — anything you remove stops hosting the party. At least one host must remain.
{% endhint %}
{% endstep %}
{% step %}
**Sign the Change**
*Sign the transaction hash with the party's private key and paste the Base64 signature.*
The modal shows the serial transition — `current → next` — and a transaction hash to sign, with the matching `openssl` command. Paste the signature and click **Submit Change**.
{% hint style="warning" %}
Check the **Key algorithm** selector matches the party's actual key. It defaults to Ed25519 and does not detect the party's algorithm, so an ECDSA P-256 party needs the selector changed or the signature will be rejected.
{% endhint %}
{% endstep %}
{% step %}
**Wait for approvals**
A toast confirms *Hosting change submitted at serial `n` — awaiting approval from affected participants*.
As with onboarding, every participant taking on more responsibility must approve from its own **Hosting Proposals** tab before the change takes effect.
{% endstep %}
{% endstepper %}
### Not supported
{% hint style="warning" %}
**Multi-hosting a participant-managed party.** A party allocated with **Allocate Party** is managed by the participant, which holds its keys. There is no external key holder to sign a hosting change, so its hosting cannot be amended through this flow — which is why **Edit hosting** only appears for externally-signed parties.
If you need a party hosted on more than one participant, onboard it as an external party from the start.
{% endhint %}
***
## Things to know
Behaviour established by testing against a live network:
Question
Answer
Does generating the topology validate that a named participant exists?
No. It succeeds for an unknown UID; allocation then fails — after the party has signed.
Is a multi-hosted mapping effective before all hosts authorize?
No. It exists as a proposal and is absent from effective state. The party is unusable until the last host approves.
Is approval idempotent?
Yes. Replaying an identical approval succeeds. Re-approving is safe.
Can the onboarding flow amend an existing party?
No. It always creates a party at the first serial. Use Edit hosting instead.
Is a proposal visible to participants that did not submit it?
Yes. The synchronizer's topology store is fully shared — a single query returns hundreds of proposals, nearly all naming participants the querying node has no relationship with.
Do stored proposals carry the party's signature?
Yes. Which is why nothing has to be transferred between operators.
Additional notes:
* **Topology propagation is not instant.** Immediately after an approval, a party may still read as pending. The UI polls for up to 30 seconds; if in doubt, refresh the Hosted Parties list.
* **A blank permission in the advisory lookup is normal.** Per-participant synchronizer terms are optional in Canton; whether the participant is *on* the synchronizer is the signal that matters.
* **Naming your own validator as a co-host is not blocked.** The lookup warns you, but nothing prevents it — remove the row.
## Related
* [Parties tab](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/parties) — the UI screens in detail
* [Wallet Gateway](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/wallet-gateway) — custodial key holding for a party, intended to eventually replace the manual signing step above
# Users & Rights
The two kinds of users in a CAT-BM deployment, and how ledger rights work.
CAT-BM distinguishes between two different kinds of users: ledger users and wallet users
* A ledger user has rights over specific parties, and is what an application authenticates as when it talks to the Ledger API.
* A wallet user is an off-ledger entity (e.g., a wallet login) that gets associated with one or more parties and is registered with the validator app, so a person can sign in to the Canton Wallet.
For more depth on the party/user model, refer the the Canton docs: [Manage Daml parties](https://docs.canton.network/appdev/deep-dives/manage-daml-parties) and [Validator Users and Wallets](https://docs.canton.network/global-synchronizer/deployment/validator-users).
***
## Onboarding a user end to end
{% stepper %}
{% step %}
**Create the user in your identity provider**
Create the user in the realm your validator authenticates against, and give them a credential. Note the username exactly — you will reuse it.
{% endstep %}
{% step %}
**Allocate a party, if they need one**
On the validator's **Parties** tab, use **Allocate Party** with a short hint. The participant generates the full party ID.
If the person should hold their own signing key rather than trusting the participant, onboard them as an [external party](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties) instead.
{% endstep %}
{% step %}
**Create the ledger user**
On the **Users** tab, **Create User**. Set the **User ID** to match the identity provider username, set the **Primary party** to the party from the previous step, and grant **Can act as** that party.
{% endstep %}
{% step %}
**Onboard the wallet user, if they need the Wallet UI**
On the **Wallet Users** tab, **Add Wallet User** with the same username.
{% endstep %}
{% step %}
**Hand over the URL**
Give them the Wallet UI address from the validator's **Endpoints** tab.
{% endstep %}
{% endstepper %}
***
## Ledger rights
A ledger user's rights fall into two groups, and the distinction matters a great deal.
### Party-scoped rights
These name specific parties, and are what you should be using in almost every case.
Right
Grants
Can act as
Submitting commands on behalf of the named parties — creating and exercising contracts as them.
Can read as
Reading the named parties' contracts and transaction history.
Can execute as
Executing on behalf of the named parties.
### Participant-wide rights
These are not scoped to any party.
Right
Grants
Participant admin
Full administrative control of the participant node.
Identity provider admin
Administration of the participant's identity provider configuration.
Can read as any party
Read access to every party's data on the node.
Can execute as any party
Execution on behalf of any party on the node.
{% hint style="danger" %}
`Can read as any party` defeats Canton's per-party data privacy on that participant, and `Participant admin` grants everything. Reserve both for platform service accounts, never for individual users or per-tenant applications.
{% endhint %}
### Editing rights is a replacement
{% hint style="warning" %}
Saving the rights editor sets the user's **complete** rights — anything you removed is revoked. Always open the editor from the user's row or rights drawer, so it starts pre-populated with the current rights.
{% endhint %}
## Deactivating a user
In edit mode, tick **Deactivated** — *user cannot authenticate to the ledger*. This is preferable to deleting rights: it blocks access immediately while preserving the user's configuration, so it is reversible and leaves an audit trail.
## Annotations
Edit mode also allows arbitrary key/value **annotations** on a ledger user. These are metadata for your own use — a tenant ID, an owning team, a ticket reference. They are not interpreted by CatalyX or Canton.
## Related
* [Users & Wallet Users](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/users-and-wallet-users) — the UI screens
* [Identity Provider Configuration](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-provider-configuration) — how a validator authenticates
# Identity Dumps & Database Backups
Identity dumps, database backups, and what each one recovers.
A validator has two kinds of state, and they need different protection.
State
Where it lives
Protected by
Node identity — the cryptographic identity the network knows this participant by
The participant's key store, or your KMS
An identity dump
Ledger state — contracts, transaction history, topology
The participant and validator PostgreSQL databases
Database backups
You need both. A database backup without the identity cannot be restored onto a node the network recognises; an identity without a database gives you a recognised node with no history.
***
## Identity dumps
An identity dump exports the participant's identity so the node can be reconstructed if its database is lost beyond recovery.
### Downloading an identity dump
Open the validator's [Identity](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/identity-and-endpoints) tab and click **Identity Dump**. The file downloads as `-identities.json`.
{% hint style="danger" %}
**An identity dump is equivalent to the validator's private key material.** Anyone holding it can reconstruct your node's identity on the network.
* Store it in a secrets manager or an encrypted vault — never in a shared drive, a ticket, a wiki page, or a chat message.
* Never commit it to a repository.
* Transfer it only over encrypted channels.
* Keep access to it as tightly held as your production credentials.
There is no confirmation dialog. Clicking the button downloads the file immediately.
{% endhint %}
### When to take one
* **After onboarding**, once the validator is initialised and connected. This is the dump you cannot do without.
* **Before any migration or major upgrade.**
* **Periodically**, on whatever cadence your change-management process requires.
{% hint style="info" %}
An identity dump reflects the identity at the moment it was taken. It does not need to be refreshed as ledger state changes — but retake it if the node's identity or keys change.
{% endhint %}
***
## Database backups
Each validator has at least two databases, and more when optional components are enabled:
| Database | Contains |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Participant | The ledger — contracts, transaction history, topology state, and the key store unless a KMS holds the keys |
| Validator app | Validator app state, including wallet and onboarding data |
| PQS | A rebuildable projection of the ledger. See [Participant Query Store](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/participant-query-store) |
| Wallet Gateway store and signing | Wallet Gateway state. See [Wallet Gateway](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/wallet-gateway) |
Back these up with your standard PostgreSQL tooling — managed service snapshots, or your own `pg_basebackup` and WAL archiving. CAT-BM does not manage database backups, deliberately: this is the layer where your organisation's existing backup, retention, and testing policy should apply.
For more details on database backups, please refer the Canton guidelines:
{% embed url="" %}
{% hint style="warning" %}
**Deleting a `Validator` resource does not delete its databases.** That is what makes it possible to recreate a validator against its existing state — but it also means decommissioning is a two-step job: delete the resource, then drop the databases.
{% endhint %}
***
## Recovery paths
In order of preference.
{% stepper %}
{% step %}
**Restore from a database backup**
The normal path. Restore the participant and validator databases, and the node resumes with the state in the backup. Some transaction loss is possible, bounded by your backup frequency.
{% endstep %}
{% step %}
**Fail over to a standby region**
Where a multi-region deployment is configured, workloads move to the secondary region. See [Canton's own documentation](https://docs.canton.network/) for high-availability and disaster-recovery guidance for validators.
{% endstep %}
{% step %}
**Reinitialise from an identity dump**
The last resort, for when database backups are unavailable or corrupted. The node is recreated with its original network identity, but without its ledger history. Coordinate this with IntellectEU support and with your sponsoring Super Validator.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
Recovery objectives are defined per engagement in the applicable service agreement. Contact IntellectEU for the objectives that apply to your deployment.
{% endhint %}
***
## What else to keep alongside the backups
A restore also needs the surrounding configuration. Keep these under version control or in your secrets manager:
* The **`Validator` resource** for each validator — ideally in Git, which is the main argument for managing them through GitOps.
* The **Helm values** used to install the platform.
* The **database credentials secret** for each validator.
* The **identity provider configuration** — realm, clients, and scopes. With managed authentication the operator can recreate the clients, but the realm and the admin client are yours.
* For an external identity provider, the **backend client secret**.
* For KMS-backed validators, access to the **key vault** itself. Without it the keys are unrecoverable, whatever else you have.
{% hint style="danger" %}
If you use a KMS, the KMS becomes part of your recovery path. Losing access to the key vault is unrecoverable — an identity dump will not substitute for keys the node no longer has permission to use. Make sure your KMS has its own backup, replication, and access-recovery plan.
{% endhint %}
# Key Management Service (KMS)
Hold the Canton participant's operational keys in an external key management service.
By default a Canton participant generates its operational keys and stores them in its own PostgreSQL database. For deployments that require stronger key-protection guarantees, CAT-BM can configure the participant to hold those keys in an external KMS instead.
Without KMS
With KMS
Keys are generated by the node and stored in the participant database.
Keys are generated and held in the KMS. Private key material never enters the node.
Protecting the keys means protecting the database.
Keys are customer-managed, with the KMS's own access control and audit trail.
Sufficient for many deployments; it is Canton's out-of-the-box model.
Supports FIPS 140-2 validated modules and HSM backing where the provider offers them.
{% hint style="info" %}
KMS protects the **participant node's operational keys**. It is a different concern from external party keys, which are held by the party's owner — see [External & Multi-Host Parties](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties) — and from the Wallet Gateway, which delegates *party* signing to a custody provider.
{% endhint %}
***
## Azure Key Vault
### Prerequisites
{% stepper %}
{% step %}
**A key vault**
An Azure Key Vault the participant can reach, with the identity CAT-BM will use granted permission to create keys and to sign and decrypt with them.
For HSM-backed keys you need a Premium vault or Managed HSM.
{% endstep %}
{% step %}
**A KMS-enabled participant image**
Azure Key Vault support requires a purpose-built participant image containing the KMS driver. Contact IntellectEU support to obtain it, together with the pull secret for the registry it is published to.
{% endstep %}
{% step %}
**Credentials**
Either a workload identity, or a service principal whose client secret you store in a Kubernetes Secret.
```bash
kubectl create secret generic azure-kms-credentials \
--from-literal=client-secret= \
-n
```
{% endstep %}
{% endstepper %}
### Configuration
```yaml
spec:
kms:
enabled: true
provider: azure
azure:
vaultUrl: https://my-vault.vault.azure.net/
keyNamePrefix: my-validator
preBuiltImage:
imagePullSecret: azure-kms-registry-credentials
tenantId:
clientId:
clientSecretRef:
name: azure-kms-credentials
key: client-secret
```
Field
Purpose
vaultUrl
Required. The key vault URL.
preBuiltImage
Required. The KMS-enabled participant image.
keyNamePrefix
Prefixes generated key names, so several nodes can share one vault without colliding.
credentialType
How the driver authenticates: default, environment, or managedIdentity. Omit it to use a service principal from the secret.
tenantId, clientId, clientSecretRef
Service principal credentials. Not needed with default or managedIdentity.
hardwareBackedKeys
Create HSM-protected keys. Needs a Premium vault or Managed HSM.
imagePullSecret
Pull secret for the participant image's registry.
{% hint style="danger" %}
**With Azure KMS enabled, `preBuiltImage` replaces the participant image entirely.** `spec.participant.version` and `spec.network.spliceVersion` are ignored for the participant. That means the KMS image's Canton version is what runs — coordinate its version with the rest of your deployment, and re-check it at every upgrade.
{% endhint %}
{% hint style="warning" %}
`spec.kms.provider` is matched **case-sensitively**. `Azure` or `AZURE` will not enable KMS — and because the validator otherwise reconciles normally, it will silently come up with keys in the database. Use lowercase `azure`.
{% endhint %}
### Hardening options
The driver exposes a set of strict-mode checks — pinned key versions, key spec validation, key operation validation, rejection of exportable keys, hardened generated keys, and a minimum key-encryption-key strength. Leave them at their defaults unless you have a specific reason to relax one; they are there to fail closed.
Sizing and connection tunables — cache size and idle window, AES and RSA key sizes, I/O threads, and HTTP timeouts and pool limits — are also available. Omit them to use the driver's defaults. See the [Validator CRD Reference](/catalyx-blockchain-manager/canton-network/version-2.0/validator-crd) for the full list.
{% hint style="info" %}
Two driver defaults changed after the initial 2.0.0 release: audit logging is now enabled by default, and the default AES key size changed. If you depend on either, set the value explicitly rather than relying on the default.
{% endhint %}
***
## AWS KMS
{% hint style="warning" %}
**Confirm availability before relying on this.** An AWS KMS provider is present in the current 2.0 line, but it postdates the 2.0.0 release and is less exercised than the Azure integration. Check with IntellectEU support before adopting it in production.
{% endhint %}
Unlike Azure, AWS KMS does not require a special participant image — it uses Canton's native AWS KMS support, so the standard participant image applies.
```yaml
spec:
kms:
enabled: true
provider: aws
aws:
region: eu-central-1
auditLogging: true
# Either IRSA:
serviceAccountName: catalyx-kms-sa
# or static credentials:
# credentialsSecretRef:
# name: aws-kms-credentials
```
Field
Purpose
region
Required. The AWS region holding the keys.
serviceAccountName
A pre-created Kubernetes service account annotated for IAM Roles for Service Accounts. CAT-BM does not create it — you do.
credentialsSecretRef
Static credentials, as an alternative to IRSA. Keys default to access-key-id and secret-access-key, with an optional session-token for assumed roles.
multiRegionKey
Use a multi-region key.
auditLogging
Log KMS operations.
IRSA is preferable to static credentials: it avoids long-lived secrets in the cluster entirely.
***
## Verifying it works
{% stepper %}
{% step %}
**Check the validator reconciled**
The [Status](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/status-and-specification) tab should show `Ready`. A misconfiguration reports `InvalidSpec` with the exact field named in the message.
{% endstep %}
{% step %}
**Check the participant image**
On the participant's [Application](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/applications) detail page, confirm the **Image** is the KMS-enabled one when using Azure.
{% endstep %}
{% step %}
**Check the keys**
The validator's [Keys](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/participant-and-keys) tab lists the participant's public keys. Cross-check them against your key vault — the vault is the authority on where the private material lives.
{% endstep %}
{% endstepper %}
***
## Operational consequences
{% hint style="danger" %}
Enabling KMS makes the KMS part of your validator's critical path and its recovery path.
* **Availability** — if the participant cannot reach the KMS, it cannot sign, and it cannot operate.
* **Permissions** — revoking or rotating the identity's access stops the node.
* **Recovery** — losing access to the key vault is unrecoverable. An identity dump does not substitute for keys the node can no longer use.
Give the key vault the same backup, replication, and access-recovery treatment as the databases. See [Identity Dumps & Database Backups](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-dumps).
{% endhint %}
Enable KMS **before** onboarding a validator where you can. Moving an existing validator's keys into a KMS is a Canton-level key migration, not a configuration change — plan it with IntellectEU support.
# Participant Query Store
The Participant Query Store (PQS) streams the ledger from the participant into a PostgreSQL database, so applications can query contract state with SQL instead of walking the Ledger API.
Use PQS when
Skip it when
Applications need to query current contract state by attribute, not just by contract ID.
Applications only stream transactions and maintain their own state.
You want reporting or analytics over ledger data.
You have no read-heavy consumers.
Read load would otherwise fall on the participant.
The extra database and workload are not worth the benefit.
{% hint style="info" %}
PQS is a **projection**, not a source of truth. The participant's own database remains authoritative — PQS can be rebuilt from the ledger at any time.
{% endhint %}
## Enabling it
Two things are needed on the `Validator`: the component, and a database for it.
```yaml
spec:
pqs:
enabled: true
version: "3.4.1"
ledgerStart: Latest
database:
host: postgres.default.svc.cluster.local
participantDb: participant_my_validator
validatorDb: validator_my_validator
pqsDatabase: pqs_my_validator
pqsSchema: pqs
credentialsSecretRef:
name: my-validator-db-credentials
```
Field
Notes
pqs.enabled
Defaults to false.
pqs.version
Required when enabled. It does not fall back to spliceVersion — PQS is versioned independently of the Splice components.
pqs.ledgerStart
Where the pipeline begins reading. Defaults to Latest.
database.pqsDatabase
Required when enabled. The operator creates the database for you.
{% hint style="warning" %}
`ledgerStart: Latest` means PQS begins from the current ledger end and does **not** backfill history. If you need historical contracts in the store, set the start point when you first enable PQS — changing it later requires rebuilding the store.
{% endhint %}
## What gets created
Enabling PQS adds a sixth component to the validator: a `pqs` application with its own deployment and service, plus the PQS database and schema.
It appears as a `PQS` row on the validator's [Summary](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/summary) tab and as an entry on the [Applications](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/applications) list, with the same health, resource, and log surface as every other component. The validator's overall readiness includes it.
{% hint style="info" %}
There is no PQS-specific screen in the UI — no query browser and no pipeline status view. PQS is monitored like any other component. Query the store directly with your own SQL tooling.
{% endhint %}
## Connecting to it
The store is an ordinary PostgreSQL database. Connect with the credentials from the validator's database credentials secret, at the host, database, and schema you configured.
For the schema itself and the query patterns it supports, see Canton's [Participant Query Store documentation](https://docs.canton.network/sdks-tools/development-tools/pqs#pqs-participant-query-store).
## Operating it
**Sizing.** PQS holds a projection of contract state, so its size tracks your active contract set and retention rather than the full transaction history. Start from the defaults and measure.
**Backups.** PQS can be rebuilt from the ledger, so it does not strictly need backing up — but rebuilding a large store takes time. Back it up if your recovery time matters more than the storage cost.
**Restarts.** PQS resumes from where it left off. A restart causes a lag in the projection, not data loss.
{% hint style="warning" %}
If PQS is not ready, the whole validator reports `Degraded` — its readiness is included in the validator's. A PQS pipeline problem will therefore show up as a validator-level alert. Check the `PQS` row on the Summary tab to distinguish it from a participant problem.
{% endhint %}
**Extra environment variables.** Unlike the participant, validator app, and UIs, PQS does not support `spec.overrides` environment variables. Configuration is limited to the fields above.
# Wallet Gateway
Deploy a custodial key-holding service for a validator's parties, and manage wallets from the CatalyX UI or the API — without holding private keys yourself.
{% hint style="info" %}
**Version note.** The Wallet Gateway was added after the 2.0.0 release. It is not part of the 2.0.0 artifact set. Contact IntellectEU support to confirm availability and supported versions for your deployment.
{% endhint %}
Wallet Gateway is a third-party product, built by Digital Asset (the company behind Canton), that sits next to a validator and holds a party's private key with an external custodian — currently **DFNS**. CatalyX deploys and configures a Wallet Gateway instance per validator, and provides a UI screen and API for creating and browsing the wallets it manages.
Counterparties who hold their own keys and sign for themselves.
Wallet Gateway
An external custody provider
Parties that need custodial key management with institutional controls, without either side running key infrastructure.
{% hint style="warning" %}
**Wallet Gateway holds keys; it does not yet sign anything for CatalyX.** Today it can create and hold a wallet, but nothing in CatalyX asks it to sign a transaction — the manual `openssl` signing step in [External & Multi-Host Parties](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties) still applies even for a party custodied here. See [What's not yet available](#whats-not-yet-available).
{% endhint %}
## Why use it
* **Private keys never touch application code or platform infrastructure.** DFNS holds and can sign with them; CatalyX only ever talks to Wallet Gateway's API, never to a key.
* **Institutional custody controls** — the provider's access policies, approval workflows, and audit trail apply to every signing operation the provider itself performs.
* **HSM backing and compliance** — where the provider offers it, key storage can satisfy FIPS 140-2 and comparable requirements.
* **One integrated workflow** — create and browse wallets from the CatalyX UI or API, without needing DFNS's own dashboard for day-to-day operator tasks.
***
## What gets created
Enabling the Wallet Gateway adds a component to the validator with:
* its own deployment and service;
* its own public hostname, `https://wallet-gateway-.`, so it is reachable from a browser;
* two dedicated PostgreSQL databases — a store and a signing store;
* a public OIDC client, provisioned automatically under managed authentication;
* a generated configuration file, delivered as a Kubernetes Secret, mounted into the container.
It appears as a `Wallet Gateway` row on the validator's [Summary](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/summary) tab and on the [Applications](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/applications) list, and its readiness is included in the validator's. It also gets its own **Wallet Gateway** tab on the validator detail page — see [Managing wallets](#managing-wallets) below.
***
## Enabling it
```yaml
spec:
auth:
enabled: true
managedKeycloak: true
targetAudience: https://canton.network.global
ledgerApiUserManagementScope: daml_ledger_api
walletGateway:
enabled: true
version: "v1.7.0"
dfns:
orgId:
apiUrl:
credentialId:
credentialsSecretRef:
name: my-validator-waas-credentials
database:
host: postgres.default.svc.cluster.local
participantDb: participant_my_validator
validatorDb: validator_my_validator
walletGatewayStoreDatabase: wg_store_my_validator
walletGatewaySigningDatabase: wg_signing_my_validator
credentialsSecretRef:
name: my-validator-db-credentials
```
### Requirements
The Wallet Gateway has more prerequisites than any other optional component, and the validator will report `InvalidSpec` naming the exact missing field if any are absent.
Requirement
Why
walletGateway.version
Required when enabled; it does not fall back to spliceVersion.
auth.enabled: true
The Wallet Gateway cannot run without authentication.
auth.targetAudience and auth.ledgerApiUserManagementScope
Needed for both browser and machine-to-machine flows.
An auth URL, a backend client ID, and a Wallet Gateway client ID
Provisioned for you under managed authentication; supplied by you with an external identity provider.
database.walletGatewayStoreDatabase and walletGatewaySigningDatabase
Both are required — supplying only one fails.
database.credentialsSecretRef
The databases are provisioned with these credentials.
### Provider credentials
```bash
kubectl create secret generic my-validator-waas-credentials \
--from-literal=private-key= \
--from-literal=auth-token= \
-n
```
The key names default to `private-key` and `auth-token`, and can be overridden on the `credentialsSecretRef`.
{% hint style="info" %}
With **managed authentication**, the Wallet Gateway's OIDC client is created automatically when the validator is provisioned, so no extra identity provider work is needed.
With an **external identity provider** you must create the client yourself and set `spec.auth.walletGatewayClientId`. Note that this field cannot currently be set through the `catalyx-canton-validator` Helm chart — apply the `Validator` resource directly instead.
{% endhint %}
***
## Updating provider settings without a redeploy
Once a validator has Wallet Gateway enabled, its DFNS connection details — the enabled flag, connection details, and credentials — can be viewed and updated live through the API, without editing the `Validator` resource or restarting anything.
Updates the settings. Each field is optional per call, so rotating just a credential doesn't require resending the rest.
{% hint style="info" %}
**The `Validator` resource's `dfns` fields are fallback defaults only.** Once you call the settings API, the live enabled flag and connection details live in a ConfigMap instead and take precedence over the CR, field by field. Credentials are never put in that ConfigMap — they always go straight to the Secret named by `credentialsSecretRef`. This is what lets the UI's Create Wallet screen know whether a provider is actually usable before offering it.
{% endhint %}
***
## Managing wallets
On a validator's detail page, alongside Parties, DARs, Participant, and Keys, there is a **Wallet Gateway** tab. This is separate from the Summary tab, which only shows whether the Wallet Gateway *service* is deployed and healthy — the tab is where wallet management happens.
### Browsing wallets
The tab lists every wallet held by that validator's Wallet Gateway, refreshing automatically every 30 seconds (and immediately after creating one). Each row shows:
* the wallet's name and its Canton party ID;
* which provider holds its key (`dfns` today);
* its status — `initialized`, `allocated`, `removed`, or `disabled`;
* whether it's marked primary.
Expanding a row shows more detail: namespace, network, and public key. If more than one provider is ever configured, the list can be filtered by provider.
{% hint style="info" %}
Wallets the validator signs for itself — i.e. not custodied externally — are **not** shown here. Those already appear on the [Parties](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/parties) tab.
{% endhint %}
### Creating a wallet
Fill in a short, human-readable name for the party (for example `treasury` or `my-bank`) and pick a signing provider — DFNS is pre-selected when it's the only one configured. You can optionally mark the new wallet as the party's primary. CatalyX then asks Wallet Gateway to allocate a new Canton party and have DFNS generate and hold its key; the wallet appears in the list once allocation completes.
{% hint style="warning" %}
**"Make primary" is a shared setting, not a personal one.** CatalyX calls Wallet Gateway with one shared service identity rather than a per-user login, so marking a wallet primary affects everyone using the UI for this validator. The UI calls this out when the box is checked.
{% endhint %}
If Wallet Gateway isn't enabled for the validator, or no signing provider is configured yet, the screen explains what's missing rather than failing silently.
***
## Startup behaviour
{% hint style="info" %}
On a brand-new validator using managed authentication, the Wallet Gateway does **not** appear on the first reconcile. It waits until identity provider provisioning has completed, then starts. A validator that briefly shows no Wallet Gateway component, or shows it with zero replicas, is behaving correctly — give it a reconcile cycle.
{% endhint %}
***
## Security considerations
{% hint style="danger" %}
Review these before enabling the Wallet Gateway in a production namespace.
**Database credentials reach the pod as a Kubernetes Secret.** The generated configuration file — and the DFNS/OAuth secrets injected alongside it — is delivered via a Secret rather than a ConfigMap (tightened after the initial rollout). Anyone who can read Secrets in the validator's namespace can still read it, so restrict `get secret` there with RBAC, and consider a dedicated database user with access limited to the two Wallet Gateway databases.
**The service accepts requests from any origin**, and does not verify the TLS certificate of its database connection. Neither is configurable. Deploy it behind your own network controls and treat its hostname as a sensitive endpoint.
{% endhint %}
Access to the provider credentials secret should be as tightly held as any signing credential — it is what authorises the platform to request signatures.
***
## Related
* [External & Multi-Host Parties](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties) — the alternative, where the party holds its own keys
* [Key Management Service (KMS)](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/kms-integration) — protecting the *participant's* keys, a separate concern
# Upgrades
Upgrading the platform, and upgrading validator components.
There are two independent upgrade tracks, and it helps to keep them separate.
Track
Changes
Mechanism
Platform
The operator, API, and UI
helm upgrade
Validator components
The Canton participant, validator app, UIs, PQS, Wallet Gateway
Edit the Validator resource
You can upgrade either without the other, within a compatible range.
***
## Upgrading the platform
```bash
helm upgrade catalyx-canton catalyx/catalyx-canton \
-n -f my-values.yaml
```
{% hint style="danger" %}
**Apply the CRDs first.** Helm never upgrades the resources in a chart's `crds/` directory. If a release changes the `Validator` or `Application` schema and you skip this, new fields will be silently pruned from resources you apply.
```bash
kubectl apply -f /crds
```
{% endhint %}
### What happens
The operator, API, and UI deployments are rolled. The UI runs multiple replicas by default and has a pod disruption budget, so it stays available. The operator and API run a single replica each — expect a brief interruption while they restart.
Once the new operator starts, it re-reconciles every existing validator. Validators are not restarted unless something they depend on has changed.
### Rolling back
```bash
helm rollback catalyx-canton -n
```
{% hint style="warning" %}
Rolling back the chart does **not** roll back the CRDs, because Helm never managed them. If the upgrade introduced schema changes and you roll back the release, the newer CRDs remain in place. The older operator will ignore fields it does not understand.
{% endhint %}
***
## Upgrading validator components
Canton networks upgrade on a schedule, and validators are expected to keep pace with the network's supported protocol versions.
### The simple case
If the validator uses `spec.network.spliceVersion`, one change upgrades the participant, validator app, and both UIs together:
```yaml
spec:
network:
spliceVersion: "0.6.13"
```
```bash
kubectl apply -f my-validator.yaml
```
The operator rolls each component in turn. Watch the validator's [Summary](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/summary) tab as components return to `Ready`.
### Pinned components
A component with its own `version` ignores `spliceVersion`. Check for pinned versions before upgrading:
```bash
kubectl -n get validator my-validator \
-o jsonpath='{.spec.participant.version} {.spec.validator.version} {.spec.ui.wallet.version} {.spec.ui.cns.version}'
```
Independently versioned components — PQS and the Wallet Gateway — always need their own `version` set, and never follow `spliceVersion`.
{% hint style="warning" %}
**Azure KMS bypasses this entirely.** When Azure KMS is enabled, the participant runs the KMS-enabled image from `spec.kms.azure.preBuiltImage`, and both `spec.participant.version` and `spliceVersion` are ignored for the participant. Upgrading such a validator means obtaining an updated KMS image. Factor that into your upgrade lead time.
{% endhint %}
***
## Before you upgrade
{% stepper %}
{% step %}
**Confirm the target version is supported by the network**
Your validator's protocol version must remain compatible with the synchronizer. Check the network's published schedule; for the global Canton Network this is governed by the Global Synchronizer Foundation.
{% endstep %}
{% step %}
**Take an identity dump and confirm your database backups**
See [Identity Dumps & Database Backups](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-dumps). Do this before every version change, not just major ones.
{% endstep %}
{% step %}
**Upgrade a non-production validator first**
Component versions are per validator, so a lower environment can run the new version while production stays put.
{% endstep %}
{% step %}
**Check the release notes**
See [Release Notes](/catalyx-blockchain-manager/canton-network/version-2.0/release-notes) for behaviour changes in the CatalyX release, and the Canton release notes for protocol changes.
{% endstep %}
{% endstepper %}
***
## Domain migrations
When a network performs a domain migration, the migration is coordinated by the network, not by CAT-BM. Two fields participate:
Field
Purpose
spec.network.migrationId
The migration the validator is operating against.
spec.validator.dumpPath
Path to a migration dump, when the migration requires one.
{% hint style="warning" %}
Domain migrations are network-wide events with their own timing and procedure. Coordinate them with IntellectEU support and your sponsoring Super Validator — do not change `migrationId` speculatively.
{% endhint %}
***
## Version compatibility
{% hint style="info" %}
The `Validator` and `Application` custom resources are served at `catalyx.manager.canton/v1alpha1`.
**Field-level changes may still occur in a future minor release.** Treat the CRD schema as stable in shape but not frozen in detail, and read the release notes before upgrading the platform. Keep your `Validator` resources under version control so a schema change is a reviewable diff rather than a surprise.
{% endhint %}
## Getting help
Upgrade paths, supported version combinations, and migration procedures for a specific deployment are provided by IntellectEU support. See [Contact Support](/catalyx-blockchain-manager/canton-network/version-2.0/support-and-resources).
# Identity Provider Configuration
Choose between letting CAT-BM provision authentication for a validator, or supplying your own OIDC configuration.
Every validator authenticates its users and components through an OIDC identity provider. CAT-BM supports two modes, chosen per validator with a single field.
Managed Keycloak
managedKeycloak: true — CAT-BM creates the clients, scopes, and users for you.
You run Keycloak and are happy for CAT-BM to hold an admin client in the validator realm.
Your identity provider is not Keycloak — for example Okta, Microsoft Entra ID, Auth0, or Ping Identity.
You want to add validators without a manual identity provider change for each one.
Client creation is centrally governed and cannot be automated by a platform component.
You want per-validator client isolation without designing the naming yourself.
You already have OIDC clients you must reuse.
{% hint style="info" %}
The mode is per validator, so you can mix both in one cluster.
{% endhint %}
## Two separate identity concerns
It is worth being precise about this, because the two are easy to conflate.
Concern
Configured where
The management plane — who can log in to the CatalyX UI and call the CatalyX API.
Helm values at install time: ui.oidc.* and api.auth.jwksUri. Not per validator.
The validator — how the participant, validator app, Wallet UI, and CNS UI authenticate.
spec.auth on each Validator resource.
This page and its children cover the second. For the first, see [Platform Installation](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation).
# Managed Keycloak
Let CAT-BM provision the OIDC clients, scopes, and users a validator needs.
With `spec.auth.managedKeycloak: true`, the operator provisions everything the validator's components need inside an existing Keycloak realm, on the validator's first reconcile.
## Configuration
At the platform level, set the operator's Keycloak values at install time — see [Platform Installation](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation).
On the validator, the whole `spec.auth` block reduces to four fields:
```yaml
spec:
auth:
managedKeycloak: true
targetAudience: https://canton.network.global
ledgerApiUserManagementScope: daml_ledger_api
```
`spec.network.partyHint` must also be set — it becomes the wallet user's username.
{% hint style="danger" %}
The realm must already exist, and the operator's admin client must exist **inside that realm** with realm-management permissions. The operator authenticates with the client credentials grant against the realm named in `operator.keycloak.realm`.
{% endhint %}
***
## What gets created
For a validator named `my-validator`, in the realm you configured:
Object
Name
Notes
Public client — CNS UI
my-validator-cns-ui
Redirect URI and web origin derived from operatorRuntime.baseHostname. Gets an audience mapper for targetAudience.
Public client — Wallet UI
my-validator-wallet-ui
As above.
Public client — Wallet Gateway
my-validator-wallet-gateway
Created whether or not the Wallet Gateway is enabled. Gets an audience mapper, a hardcoded sub claim mapper, and a 30-minute access token lifespan. The profile and email default scopes are removed.
Confidential client — backend
my-validator-validator-backend
Service accounts enabled. Its generated secret is written to a Kubernetes Secret.
Client scope — Ledger API
the value of ledgerApiUserManagementScope
Created once per realm, with an audience mapper for targetAudience.
Client scope — per validator
my-validator-ledger-api
Attached as an optional scope to the platform's API client. Carries the audience, the user-management scope claim, and the backend service account's subject.
User — wallet
the value of spec.network.partyHint
Enabled, email verified, no password and no roles.
## The generated secret
The operator writes an `Opaque` Kubernetes Secret in the validator's namespace:
| | |
| ----- | ------------------------------------------------------------ |
| Name | `-managed-ledger-api-auth` |
| Key | `client-secret` |
| Value | The generated secret of `-validator-backend` |
{% hint style="warning" %}
This secret has no owner reference, so it is **not** deleted when the validator is deleted. That is deliberate — it lets you recreate a validator without re-provisioning — but it means you must remove it yourself when decommissioning permanently.
{% endhint %}
## Checking the result
Provisioning results are recorded on the validator's status and shown on the UI's [Identity](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/identity-and-endpoints) tab.
```bash
kubectl -n get validator my-validator -o jsonpath='{.status.managedAuth}' | jq
```
Status field
Meaning
provisioned
true once provisioning has completed successfully.
Internal Keycloak user identifiers for the backend service account and the wallet user. These are IDs, not usernames.
{% hint style="info" %}
Once `provisioned` is `true`, the operator stops contacting Keycloak on subsequent reconciles and reads all authentication configuration from `status.managedAuth`.
{% endhint %}
***
## Things to know before you rely on it
**Provisioning is idempotent, but not fully self-correcting.** Clients that already exist have their redirect URIs and web origins overwritten to match the current `operatorRuntime.baseHostname`. **Client scopes are not updated** — a scope created with the wrong `targetAudience` must be corrected by hand in Keycloak.
**Changing the base hostname rewrites redirect URIs.** If you change `operatorRuntime.baseHostname` after validators exist, their public clients are updated on the next provisioning cycle.
**The platform API client is optional but recommended.** If the client named by `operator.keycloak.apiClientId` (default `catalyx-api`) does not exist in the realm, the operator logs a warning and continues — but the UI will not be able to perform Ledger API operations for that validator.
**Nothing is cleaned up on delete.** Clients, scopes, and users created for a validator remain in the realm after the validator is deleted.
# External Identity Provider
Configure a validator against OIDC clients you create yourself, in any OIDC-compliant identity provider.
With `spec.auth.managedKeycloak: false` — the default — you create the OIDC objects yourself and reference them from the `Validator` resource. This works with any OIDC-compliant identity provider, including Okta, Microsoft Entra ID, Auth0, and Ping Identity.
## What to create in your identity provider
Object
Type
Used by
Wallet UI client
Public
The Canton Wallet web UI. Needs a redirect URI of https://wallet-<validator-name>.<baseHostname>/* and the matching web origin.
CNS UI client
Public
The Canton Name Service web UI. Redirect URI https://cns-<validator-name>.<baseHostname>/*.
Backend client
Confidential
The validator app, PQS, and the Wallet Gateway, for machine-to-machine access to the Ledger API. Needs the client credentials grant enabled.
Wallet Gateway client
Public
Only when the Wallet Gateway is enabled. Redirect URI https://wallet-gateway-<validator-name>.<baseHostname>/*.
Participant admin user
User
The Canton participant's admin user identity.
Wallet user
User
The user the validator app treats as the wallet owner.
Every token issued to these clients must carry the audience you configure as `spec.auth.targetAudience`. Add an audience mapper or equivalent to each client.
## Store the backend client secret
```bash
kubectl create secret generic my-validator-ledger-api-auth \
--from-literal=client-secret= \
-n
```
***
## Configuration
```yaml
spec:
auth:
enabled: true
managedKeycloak: false
authUrl: https://idp.example.com/realms/canton
jwksUrl: https://idp.example.com/realms/canton/protocol/openid-connect/certs
targetAudience: https://canton.network.global
ledgerApiUserManagementScope: daml_ledger_api
ledgerApiUser: participant-admin
walletUserName: wallet-user
ledgerApiClientId: my-validator-backend
walletUiClientId: my-validator-wallet-ui
cnsUiClientId: my-validator-cns-ui
ledgerApiClientSecretRef:
name: my-validator-ledger-api-auth
key: client-secret
```
### Field reference
Field
Purpose
authUrl
OIDC issuer URL. Used by the UIs, and by the validator app, PQS, and Wallet Gateway to obtain tokens. Either an issuer URL or a token endpoint is accepted — an issuer URL is discovered via .well-known/openid-configuration.
jwksUrl
JWKS endpoint the participant and validator app verify tokens against.
targetAudience
The audience every token must carry.
ledgerApiUserManagementScope
The OAuth scope that grants Ledger API user-management rights.
ledgerApiUser
The participant's admin user name.
walletUserName
The wallet owner's user name.
ledgerApiClientId
The confidential backend client ID.
walletUiClientId / cnsUiClientId
The public client IDs for the two web UIs.
walletGatewayClientId
The public client ID for the Wallet Gateway. Required only when the Wallet Gateway is enabled.
ledgerApiClientSecretRef
Secret holding the backend client secret. key defaults to client-secret.
{% hint style="warning" %}
None of these fields is marked required in the CRD schema, so a `Validator` missing them will be **accepted** by the API server and then fail during reconciliation. The `Ready` condition will report `InvalidSpec` with the name of the missing field. Check the condition after applying.
{% endhint %}
{% hint style="info" %}
The `walletGatewayClientId` field cannot currently be set through the `catalyx-canton-validator` Helm chart. If you use that chart and need the Wallet Gateway with an external identity provider, apply the `Validator` resource directly instead.
{% endhint %}
***
## Verifying
Open the validator's [Identity](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/identity-and-endpoints) tab in the UI. It shows `Managed Keycloak: External`, the resolved auth URL, the target audience, and each client ID — a quick way to confirm the values reached the components.
If tokens are being rejected, the usual causes are:
* the audience mapper is missing on one of the clients, so `targetAudience` does not match;
* the redirect URI registered on a public client does not match the hostname the operator generated from `operatorRuntime.baseHostname`;
* the client credentials grant is not enabled on the backend client.
***
## Disabling authentication
`spec.auth.enabled: false` disables authentication on the participant entirely.
{% hint style="danger" %}
Never do this outside a local development cluster. It leaves the Ledger API open to anyone who can reach it.
{% endhint %}
# Release Notes
Product updates and release notes for CAT-BM 2.0 for Canton.
## Version 2.0.0
**Released 31 July 2026**
CAT-BM 2.0 is a **complete rewrite succeeding the 1.x line**: a new operator, a new REST API, and a rebuilt web UI.
{% hint style="danger" %}
**2.0 is not an in-place upgrade from 1.x.** Install it fresh. Contact IntellectEU support before planning a migration from an existing 1.10 or 1.11 deployment.
{% endhint %}
### Operator
Apply a single `Validator` custom resource and the operator provisions the full stack — the identity provider realm objects and OIDC clients, the Canton participant node, the validator app, the Wallet UI, and the CNS UI, plus an optional Participant Query Store. Components are managed as child `Application` resources with per-component readiness and reconciliation status. Traefik ingress, and PostgreSQL-backed participant and validator databases provisioned automatically.
### REST API
Read-only against the Kubernetes custom resources, read/write through the Canton Ledger API proxy: balances, traffic status, participant health, DAR packages, ledger users and wallet users, parties — local, external, and onboarding — and participant public keys. Stateless OAuth 2.0 resource server with per-validator scoped tokens. An interactive Canton console over WebSocket. OpenAPI description published at `/v3/api-docs`.
### Web UI
A React single-page application for operating validators without cluster access: a Dashboard, a Validators list, and a 13-tab validator detail view — Summary, Specification, Status, Balances, Traffic, Identity, DARs, Users, Wallet Users, Parties, Endpoints, Participant, and Keys. Application health and resource metrics, with optional Grafana deep links. External party onboarding, and the Canton console.
### Artifacts
| Artifact | Version |
| ------------------------------------------------------------------ | -------- |
| `catalyx-console` image (multi-arch `linux/amd64`, `linux/arm64`) | `v2.0.0` |
| `catalyx-operator` image (multi-arch `linux/amd64`, `linux/arm64`) | `v2.0.0` |
| `catalyx-ui` image (multi-arch `linux/amd64`, `linux/arm64`) | `v2.0.0` |
| `catalyx-canton` Helm chart | 2.0.0 |
| `catalyx-canton-validator` Helm chart | 2.0.0 |
### Upgrading from 1.x
2.0 is a fresh installation. Contact IntellectEU support for the migration procedure that applies to your deployment.
### Known limitations
* The CRD served version is `catalyx.manager.canton/v1alpha1`. **Field-level changes may still occur in a future minor release.**
* Ledger pruning is not exposed in the UI. Use the [Canton console](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/canton-console).
* Traffic purchases and balance top-ups are not exposed in the UI. The Balances and Traffic tabs are read-only.
* Participant key generation, rotation, and import are not exposed in the UI.
* The UI has no per-validator or per-screen authorisation. Restrict access at token issuance in your identity provider.
***
## Later 2.0 updates
The following landed after the 2.0.0 release and are available in the current 2.0 line. Confirm the exact version that carries each with IntellectEU support before planning around them.
{% hint style="info" %}
Each feature page carries a version note where the behaviour differs from 2.0.0, so you can tell what your build supports.
{% endhint %}
### Multi-host external parties
A party can now be hosted on **several participants**, including participants operated by other organisations, so it survives the loss of any single validator.
* The external party onboarding wizard gained a **Hosting** step: name additional hosting participants as confirming or observing, set the confirmation threshold, and optionally make the local validator observation-only.
* A new **Hosting Proposals** sub-tab on the Parties tab lists proposals naming this participant, with an **Approve** action. Local and remote co-hosts follow the identical path — nothing is transferred between operators.
* An advisory participant lookup warns when a named participant UID is not present on the synchronizer.
* The **Hosted Parties** sub-tab shows each party's hosts, their permissions, and its confirmation threshold, with a permission filter.
See [External & Multi-Host Parties](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties).
### Hosting amendments
An existing externally-signed party's hosting can be changed — add a host, remove one, change a permission, or change the threshold — via **Edit hosting** on the Hosted Parties sub-tab. The party's key holder signs the change, and every participant taking on more responsibility approves it from its own Hosting Proposals tab.
### Wallet Gateway
A new optional validator component providing a remote wallet whose signing keys are held by an external Wallet-as-a-Service provider. See [Wallet Gateway](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/wallet-gateway).
### AWS KMS
An AWS KMS provider alongside Azure Key Vault, using Canton's native AWS KMS support with either IAM Roles for Service Accounts or static credentials. Unlike Azure, it does not require a purpose-built participant image. See [Key Management Service (KMS)](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/kms-integration).
### Azure KMS hardening
New Azure Key Vault options: a `credentialType` selector supporting workload and managed identity, a configurable key-encryption-key size, an audit node identifier, and six strict-mode security checks — pinned key versions, key spec validation, key operation validation, rejection of exportable keys, hardened generated keys, and a minimum key-encryption-key strength.
{% hint style="warning" %}
**Two Azure KMS defaults changed.** Audit logging is now enabled by default, and the default AES key size changed. If you depend on either value, set it explicitly rather than relying on the default.
{% endhint %}
### Availability hardening
Pod disruption budgets for the operator, API, and UI deployments, so voluntary node disruptions do not take the management plane offline.
***
## Earlier versions
Release notes for the 1.x line are published under their own versions in this space.
## Getting help
For support requests, see the [Support Center](/support-center) — it covers the service desk, contact details, and how to stay up to date with releases.
## External documentation
CAT-BM operates Canton; it does not replace Canton's own documentation. For protocol-level detail, go to the source:
| Resource | Covers |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [Canton Network documentation](https://docs.canton.network/) | Canton Network documentation and resources. |
| [Digital Asset documentation](https://docs.digitalasset.com/) | Daml documentation and resources, including topology, party hosting, KMS drivers, and the Participant Query Store |
| [Global Synchronizer Foundation](https://sync.global/) | Network governance, upgrade schedules, and validator operator guidance |
| [Splice](https://github.com/hyperledger-labs/splice) | The open-source validator app, Wallet UI, and CNS UI |
| [Canton Improvement Proposals](https://github.com/canton-foundation/cips) | Proposed and accepted protocol and network changes |
# FAQ
Frequently asked questions about CAT-BM 2.0 for Canton.
## Getting started
Can I upgrade a 1.10 or 1.11 deployment in place?
No. 2.0 is a complete rewrite with a new operator, a new API, and new custom resources. It installs fresh. Contact IntellectEU support before planning a migration — the procedure depends on your deployment.
Why can't I create a validator from the UI?
By design. A validator is a `Validator` custom resource, so creating one is a Kubernetes apply — which makes it reviewable, diffable, and GitOps-friendly. The UI is for operating validators once they exist.
See [Create a Validator](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/create-a-validator).
Do I have to use Keycloak?
No. Any OIDC-compliant identity provider works — Okta, Microsoft Entra ID, Auth0, Ping Identity, and others. Set `managedKeycloak: false` and supply the client IDs yourself.
Managed provisioning, where CAT-BM creates the clients for you, is Keycloak-specific. See [Identity Provider Configuration](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-provider-configuration).
Do I need to create the validator databases first?
No. The operator creates them, provided the credentials you give it can `CREATEDB` and can reach the `postgres` maintenance database.
***
## Operating
My validator says Ready but the participant says Disconnected. Which is right?
Both. They measure different things.
* **Ready** is about Kubernetes — every workload the validator owns is running.
* **Disconnected** is about Canton — the participant node has lost its synchronizer connection.
A healthy set of pods with an unhealthy network connection is exactly this combination. Start on the validator's [Participant](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/participant-and-keys) tab, under **Connected Synchronizers**.
I changed the Validator resource and nothing happened.
Check three things, in order:
1. **Observed Generation** on the [Status](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/status-and-specification) tab. If it lags behind, the change has not been reconciled.
2. **The `Ready` condition.** A reason of `InvalidSpec` means the operator rejected your change and the message names the field.
3. **Whether the field survived.** Unknown fields are silently pruned by the Kubernetes API server, so a typo disappears without an error. Run `kubectl get validator -o yaml` and look for it.
Where is ledger pruning?
It is not exposed in the CatalyX UI in 2.0. Prune through the [Canton console](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/canton-console), which gives you the participant's full administrative command set.
Where do I buy traffic or top up a balance?
Not in the CatalyX UI — the Balances and Traffic tabs are read-only monitoring. Use the Wallet UI, or the Canton console.
Watch **Base remaining** and **Extra consumed** on the [Traffic](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/balances-and-traffic) tab: a participant that exhausts both is throttled by the synchronizer and command submission starts failing.
The CPU and Memory columns are empty.
Live usage comes from the Kubernetes metrics API, which needs `metrics-server` installed and healthy in the cluster. Requests and limits still display without it; only actual usage is missing.
Why do the Grafana links go nowhere?
The buttons are always rendered, whether or not Grafana is configured. Set `ui.grafana.baseUrl` in the Helm values. See [Grafana Links](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/grafana-dashboards).
***
## Parties and users
What is the difference between a party, a ledger user, and a wallet user?
* A **party** is an on-ledger identity that can hold contracts.
* A **ledger user** is an account on the participant that has rights over one or more parties, and is what an application authenticates as.
* A **wallet user** is a registration with the validator app so a person can sign in to the Wallet UI.
None of them is an account in your identity provider — that has to exist already. See [Users & Rights](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/users-and-rights).
Why can't I see all the parties on the network?
Because a production participant may know of hundreds of thousands of parties, so a full listing is impractical. **Browse Parties** is a prefix search requiring at least two characters. For the parties this participant hosts, use **Hosted Parties**, which is a complete list.
When should I use an external party instead of allocating one?
Allocate a party when your participant should legitimately act on its behalf. Onboard an **external party** when the party's owner should hold its own signing key — the participant then cannot submit for it.
External parties are also the prerequisite for multi-hosting. See [External & Multi-Host Parties](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties).
I onboarded a multi-hosted party and it doesn't work.
A multi-hosted party is not usable until **every** named host has authorized it. Until then it exists as a proposal, not as effective state.
Check the Distribute step's host list, or ask each co-host's operator to look at their own **Hosting Proposals** tab. Note that approval propagation takes a few seconds.
I mistyped a participant UID and onboarding failed. Can I retry?
Not with the same party. The party's signature covers the host set, so it is consumed by the failed attempt. Start again with a **fresh party hint**.
This is why the wizard runs an advisory lookup on every UID — resolve any warning before you reach the signing step.
Can I multi-host a party I allocated with Allocate Party?
No. A participant-managed party has no external key holder to sign a hosting change. If you need a party on more than one participant, onboard it as an external party from the start.
Does the confirmation threshold control how many participants must approve the hosting?
No — that is the most common misreading of the field. Hosting authorization is **all-of-N**: every named host must authorize, regardless of the threshold.
The threshold governs how many *confirming* hosts must confirm each of the party's **ledger transactions**, once it is live.
***
## Security
Who can do what in the UI?
In 2.0 there is no per-validator or per-screen authorisation. Any user who can obtain a token for the UI client can reach every screen, including the operations that change ledger state and the Canton console.
Enforce access control at token issuance in your identity provider, and treat UI access as platform administrator access.
Are secrets visible in the UI?
No. The Specification tab filters out any field whose path looks like a secret, and application environment variables sourced from a Kubernetes Secret show a `from secret` badge instead of the value.
How sensitive is an identity dump?
Extremely. It is the validator's cryptographic identity — treat it as private key material. Store it in a secrets manager, never in a repository, ticket, or chat, and transfer it only over encrypted channels. See [Identity Dumps & Database Backups](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-dumps).
Are the OpenAPI endpoints public?
Yes — `/v3/api-docs` and `/swagger-ui.html` are served without authentication on the platform hostname. If that is unacceptable in your environment, restrict them with a Traefik middleware or block them at your edge. See [Platform Installation](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation).
***
## Backups and recovery
Does CAT-BM back up my databases?
No. Database backups are yours to run, with your existing PostgreSQL tooling and retention policy. CAT-BM provides the identity dump, which is the other half of a recoverable validator.
See [Identity Dumps & Database Backups](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-dumps).
What happens when I delete a Validator resource?
The child applications and their workloads are removed. **Not** removed: the databases, the identity provider clients and users created by managed authentication, and the managed authentication secret.
That is deliberate — it lets you recreate a validator against its existing state. It also means decommissioning permanently is a two-step job.
If I use a KMS, is an identity dump still enough to recover?
No. With a KMS, the keys live in the key vault, and an identity dump does not substitute for keys the node can no longer reach. Losing access to the vault is unrecoverable — give it the same backup and access-recovery treatment as your databases.
# API Reference
The CatalyX REST API — endpoints, authentication, and error handling.
The CatalyX API is the integration surface for the platform. The UI is built entirely on it, so anything you can do in the UI you can automate.
It does two things:
* **Reads** validator and application state from the Kubernetes custom resources. It never writes them.
* **Proxies** privileged Canton operations — the Ledger API, the participant Admin API, the network Scan API, and the validator app's admin API — so callers do not need direct network access to the nodes.
{% hint style="warning" %}
The API is **not** read-only overall. Reading CRDs is read-only, but the proxy operations create parties and users, upload DAR packages, onboard and offboard wallet users, and authorize topology changes. Treat it as a privileged administrative API.
{% endhint %}
## Base URL and discovery
Endpoints are served under `/api/v1` on the platform hostname, for example `https://validators.example.com/api/v1/validators`.
The API publishes its own OpenAPI description:
| | |
| ---------------- | ---------------------- |
| OpenAPI document | `GET /v3/api-docs` |
| Swagger UI | `GET /swagger-ui.html` |
{% hint style="danger" %}
Both are served **without authentication**, so anyone who can reach the hostname can enumerate the API surface. If that is unacceptable in your environment, restrict them with a Traefik middleware via `api.ingress.middlewares`, or block the paths at your edge. See [Platform Installation](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation).
The published document also declares no security scheme, so Swagger UI has no *Authorize* control and generated clients get no authentication wiring. Add the bearer token yourself.
{% endhint %}
## Authentication
Send an OIDC bearer token on every `/api/v1` request:
```
Authorization: Bearer
```
Tokens are validated against the JWKS endpoint configured at install time (`api.auth.jwksUri`). Signature and expiry are checked.
{% hint style="warning" %}
**In 2.0 there is no scope, audience, or per-validator authorisation.** Any token the configured issuer signs can call every endpoint, including the mutating ones. Access control must therefore be enforced at token issuance: restrict who can obtain a token for the UI client in your identity provider, and treat API access as equivalent to platform administrator access.
{% endhint %}
Unauthenticated requests return `401` with an empty body and a `WWW-Authenticate: Bearer` header.
## Namespace scoping
Every endpoint operates on the single namespace the API is configured to watch (`api.namespace` in the Helm values — see [Platform Installation](/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation)). There is no namespace parameter, and resources elsewhere return `404`.
***
## Validators
Method
Path
Returns
GET
/api/v1/validators
Every Validator resource, sorted by namespace and name.
GET
/api/v1/validators/{name}
One Validator resource.
GET
/api/v1/validators/{name}/status
Just the resource's status.
GET
/api/v1/validators/{name}/details
Aggregate view: the validator, its Ledger API endpoint, the authenticated user, all ledger users, and all DAR packages.
GET
/api/v1/validators/{name}/balances
Canton Coin balance from the Scan service.
GET
/api/v1/validators/{name}/traffic-status
Synchronizer traffic counters.
GET
/api/v1/validators/{name}/participant-status
Participant node health.
GET
/api/v1/validators/{name}/keys
Public keys in the participant's key vault.
GET
/api/v1/validators/{name}/identity-dump
The participant identity export, as a file download.
{% hint style="info" %}
`/details` degrades rather than failing. If one of its sections cannot be fetched, the response still returns `200` with that section replaced by a corresponding `*Error` field. Check for those fields rather than relying on the status code alone.
`/balances` behaves similarly: a balance lookup failure returns `200` with an `error` field in the body.
{% endhint %}
{% hint style="danger" %}
`/identity-dump` returns the validator's cryptographic identity. Protect calls to it as you would a private key export, and never log the response body. See [Identity Dumps & Database Backups](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-dumps).
{% endhint %}
## Applications
Method
Path
Returns
GET
/api/v1/applications
Every Application resource.
GET
/api/v1/applications/{name}
One Application resource.
GET
/api/v1/applications/{name}/status
Just the resource's status.
GET
/api/v1/applications/metrics
Resource metrics for every application.
GET
/api/v1/applications/{name}/metrics
Resource metrics for one application.
Metrics report **CPU in millicores and memory in bytes**. Any usage, request, or limit value may be `null`. A `metricsAvailable: false` response means the cluster metrics API was unreachable — usually a missing `metrics-server`.
## Parties
Method
Path
Purpose
GET
/api/v1/validators/{name}/parties
Look up parties by ID prefix. Optional partyId query parameter.
POST
/api/v1/validators/{name}/parties
Allocate a participant-managed party. Requires the partyIdHint query parameter.
GET
/api/v1/validators/{name}/local-parties
Parties hosted by this participant, with their hosts, permissions, and threshold.
GET
/api/v1/validators/{name}/external-parties
Externally-signed parties onboarded here.
GET
/api/v1/validators/{name}/topology-proposals
Hosting proposals on the synchronizer, each flagged with whether this participant must act.
GET
/api/v1/validators/{name}/participant-lookup
Advisory check of a participant UID. Requires participantUid.
## External parties
The onboarding and hosting flow. See [External & Multi-Host Parties](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties) for the concepts.
X.509 SubjectPublicKeyInfo, DER encoded, then Base64.
keySpec
No
Defaults to Ed25519.
hosts
No
Array of { participantUid, permission }. permission is CONFIRMING or OBSERVING; participantUid must be alias::fingerprint. Omit for a single-hosted party.
confirmationThreshold
No
Defaults to 1. Must not exceed the number of confirming participants.
localParticipantObservationOnly
No
Defaults to false. When true, this validator observes but does not confirm.
Returns the generated `partyId`, the `multiHash` to sign, the `topologyTransactions`, the `synchronizerId`, and `otherHostingParticipantUids`.
{% hint style="danger" %}
**This call does not verify that the participant UIDs you name exist.** It succeeds for an unknown UID; `allocate` then fails — after the party has already signed the multi-hash, which consumes it. Use `participant-lookup` to check every UID first.
{% endhint %}
### `allocate`
Requires `synchronizerId`, `topologyTransactions`, `signature`, and `publicKeyFingerprint`. `signatureFormat` and `signingAlgorithmSpec` default to the Ed25519 pair and must match the key you used.
Returns `partyId`, the `hosts` still owing approval, and `complete` — which is `false` until every named host has authorized.
{% hint style="warning" %}
`allocate` affects **this participant only**. It does not fan out to co-hosts. Each co-host authorizes independently via `approve-pending`.
{% endhint %}
### `amend-hosting`
`prepare` takes `partyId`, the complete new `hosts` array, and `confirmationThreshold`, and returns the current and next serial plus a `transactionHash` to sign. `submit` takes the signed transaction back.
{% hint style="warning" %}
`hosts` is a **complete replacement**, not a delta. Any host you omit stops hosting the party. At least one must remain.
{% endhint %}
## Ledger users
Method
Path
Purpose
POST
/api/v1/validators/{name}/users
Create a ledger user.
POST
/api/v1/validators/{name}/users/{userId}
Update a user's primary party, deactivation state, and annotations.
GET
/api/v1/validators/{name}/users/{userId}/rights
List a user's rights.
POST
/api/v1/validators/{name}/users/{userId}/rights
Replace a user's rights.
User creation and rights take **query or form parameters**, not a JSON body: `userId`, `primaryParty`, the boolean flags `participantAdmin`, `identityProviderAdmin`, `canReadAsAnyParty`, `canExecuteAsAnyParty`, and the repeatable party lists `canActAs`, `canReadAs`, `canExecuteAs`.
{% hint style="danger" %}
Updating rights **revokes and re-grants** — the rights you send become the user's complete set. Read the current rights first and send them back with your change applied, or you will silently remove access.
{% endhint %}
There is no endpoint that lists users directly. The user list is the `allUsers` field of `/details`.
## Wallet users
Method
Path
Purpose
GET
/api/v1/validators/{name}/wallet-users
List wallet usernames.
POST
/api/v1/validators/{name}/wallet-users
Onboard a wallet user. Body { "name": "<username>" }.
DELETE
/api/v1/validators/{name}/wallet-users/{username}
Offboard a wallet user.
The validator refuses to offboard its own wallet user, returning `409`.
## Wallet Gateway
Method
Path
Purpose
GET
/api/v1/validators/{name}/wallet-gateway/wallets
Lists the wallets Wallet Gateway manages for this validator.
POST
/api/v1/validators/{name}/wallet-gateway/wallets
Creates a wallet for a party. Requires a party hint and a signing provider (dfns today); optionally a primary flag and a DFNS vault.
Updates the enabled flag, connection details, and/or credentials for the DFNS provider. Each field is optional per call. Takes effect immediately, without editing the Validator resource or restarting anything.
{% hint style="info" %}
These calls only manage wallet *custody* — creating a wallet and reading its state. Nothing here asks Wallet Gateway to sign a transaction; that flow does not exist yet. See [Wallet Gateway](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/wallet-gateway#whats-not-yet-available).
{% endhint %}
***
## DAR packages
Method
Path
Purpose
POST
/api/v1/validators/{name}/dars/upload
Upload a DAR. multipart/form-data, part name file.
The package list is the `dars` field of `/details`.
## Health
Method
Path
Auth
GET
/actuator/health
Public
GET
/actuator/info
Public
These are the platform's own health endpoints, used by Kubernetes probes. Validator component metrics are exposed by the components themselves, not here.
## Canton console
`GET /api/ws/canton-console` upgrades to a WebSocket carrying a raw terminal stream. It is not a REST endpoint and is intended for the console UI. See [Canton Console](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/canton-console), including its security notes.
***
## Conventions
Aspect
Behaviour in 2.0
Status codes
Success is always 200 — including creates, which do not return 201, and deletes, which return 200 with a body.
Pagination
None. Collection endpoints return complete lists. A nextPageToken may appear in passthrough payloads but cannot be used — there is no corresponding request parameter.
Filtering
Only partyId on party lookup and participantUid on participant lookup. Both are prefix filters.
Sorting
Validators and applications are sorted by namespace and name. Not client-controllable.
Rate limiting
None.
Timeouts
Upstream calls have their own timeouts; an upstream that is slow or unavailable surfaces as 502.
***
# Introduction to Canton Network
This section covers the introduction to the Canton Network, including its core components, architecture, and key concepts relevant to operating nodes with CatalyX Blockchain Manager.
## Canton Network Overview
The [Canton Network](https://www.canton.network/) is the first privacy-enabled interoperable blockchain network, designed for regulated, real-world assets. Blockchain applications in the Canton Network can use the Global Synchronizer to enable atomic transactions across sovereign blockchains, without sacrificing privacy or control.
The Canton network is composed of nodes known as **Validators** that achieve consensus through **Synchronizers**. Validator nodes are responsible for storing contract data and executing smart contract code. The synchronizers, in turn, distribute encrypted messages and facilitate transaction coordination.
Transaction data is only distributed on a **need-to-know basis** to maintain confidentiality. This is the key delta to other chains: In most other chains, all state and transactions get replicated to all nodes/validators. In Canton, state and transactions get distributed only to nodes/validators that are specified in the smart contracts.
## Core Components of the Canton Network
The Global Synchronizer
The [Global Synchronizer](https://www.canton.network/global-synchronizer) is a decentralized and transparently governed interoperability service for the Canton Network.
The Global Synchronizer is a decentrally operated service, using a 2/3 majority Byzantine Fault Tolerant ([BFT](https://docs.sync.global/glossary.html#term-BFT)) consensus protocol for message ordering and confirmation, and BFT majority voting on governance changes.
Its infrastructure is operated by independently acting organizations, called Super Validators, that run components of the decentralized infrastructure, and coordinate activities via an on-chain governance application. Its open source code is maintained in [Splice](https://github.com/hyperledger-labs/splice).
The [Global Synchronizer Foundation (“GSF”)](https://sync.global/) has been created in partnership with the Linux Foundation to coordinate the governance of the Global Synchronizer and lead efforts to grow the Global Synchronizer ecosystem. The GSF provides transparency into Super Validator governance and operations. The GSF also operates a Super Validator node, and takes part in governance votes on behalf of its members.
Synchronizers (previously Domains)
Canton is a network composed of multiple [synchronizers](https://docs.digitalasset.com/overview/3.4/explanations/canton/synchronizers.html), each operating under its own rules, governance, and set of participants. Each synchronizer functions as an independent sub-network that participates in the wider Canton Network.
In a composed solution, each synchronizer is a sub-network. A [Validator Node](https://docs.sync.global/validator_operator/index.html) (previously Participant nodes) connects to one or more synchronizers, enabling transactions that span domains.
A Canton Domain consists of three entities: Sequencers, Mediators, and a Topology Manager. These are collectively called the **domain entities**.
In general, every domain entity can run in a separate trust domain (i.e., can be operated by an independent organization). In practice, all domain entities are typically run by a single organization. Each participant node runs in its own trust domain.
The generic term **member** refers to either a domain entity or a participant node.
Super Validators
[Super Validators](https://www.canton.network/blog/what-is-a-validator-on-the-canton-network) form the backbone of the [Global Synchronizer](https://www.canton.network/global-synchronizer)’s decentralized interoperability and synchronization infrastructure. They ensure the integrity, security, and operational reliability of the Global Synchronizer by:
* Running the core infrastructure of the Global Synchronizer
* Sequencing transactions across the network
* Validating Canton Coin transactions
* Participating in network governance and decision-making
Validators (previously Participants)
[Validators](https://docs.sync.global/validator_operator/index.html) work within the broader Canton Network—a “network of networks” where each node stores only the data it needs, and interacts with other Validators via [synchronizers](https://docs.digitalasset.com/overview/3.4/explanations/canton/synchronizers.html). Validators typically connect to one or more synchronizers (which might be run as centralized or decentralized services) to receive and confirm encrypted messages.
The primary roles of a Validator in the Global Synchronizer ecosystem are to:
* Validate transactions
* Record activity
* Facilitate network connectivity for users and applications
* Coordinate upgrades and migrations
Parties
In Canton, [parties](https://docs.digitalasset.com/integrate/devnet/canton-network-overview/index.html#parties) are the core on-ledger identities, and are the wallet addresses, similar to an address or Externally Owned Account (EOA) on other blockchains. They are central to how permissions and privacy are managed within the network.
Parties come in two forms, internal and external. An [internal party](https://docs.digitalasset.com/overview/3.4/explanations/canton/external-party.html) is created on the validator node, it gives a validator node submission rights and therefore holds its key on the validator node. Transactions are signed using the Validators own internal keys for signing (and thereby the validator operator has full control of everything that happens on the party).
[External parties](https://docs.digitalasset.com/overview/3.4/explanations/canton/external-party.html) are similar to how node interactions happens on other networks and therefore Externally Owned Accounts. In this case the signing key can be held externally and a signature is required alongside the transaction to authorize the action.
Canton Coin
Canton Network’s native token, [Canton Coin](https://www.digitalasset.com/hubfs/Canton%20Network%20Files/Documents%20\(whitepapers%2c%20etc...\)/Canton%20Coin_%20A%20Canton-Network-native%20payment%20application.pdf), is a utility token launched as part of the Global Synchronizer. It facilitate the transfer of value, provide incentives, and serve as payment for infrastructure costs.
The Canton Coin application employs a burn-mint equilibrium mechanism, aiming to stabilize the conversion rate of Canton Coin around the intrinsic value it provides to network users:
* Fee Burning: Users pay fees (denominated in USD but paid by burning Canton Coin) when they initiate Canton Coin transfers or when they create a traffic balance. Instead of paying these fees to a central authority, the coins are burned—i.e., removed from circulation.
* Minting Rewards: Validators (as well as Super Validators and application providers) can mint new Canton Coins in return for their “utility” contributions:
* Infrastructure Operation: Super Validators operating synchronizer nodes earn minting rights by contributing to the synchronization service.
* Application Services: Application providers can earn rewards any time they facilitate a transaction.
* Usage: When a Validator uses the network, that Validator earns “minting rights” proportional to the fees they burn, which the network treats as a proxy for the activity generated by that node.
* Liveness Incentives: Validators are rewarded for uptime and for being ready to serve transaction traffic. If a Validator does not use all its minting allowance via direct activity, a portion is allocated as a “liveness” bonus.
* Dynamic Equilibrium: The system is designed so that, over the long term, the total amount of coins burned (which reflects actual network utility) roughly balances the coins minted (subject to a predetermined maximum allowed minting curve). When usage is high, more coins are burned, tending to increase the token’s conversion rate; when usage is lower, supply increases until balance is restored.
Please refer to [Digital Assets' documentation](https://docs.digitalasset.com/overview/3.5/overview/index.html) to learn more about the core elements of the Canton Network.
***
## Concepts & Glossary
This section defines the key business and technical terms used throughout the CatalyX Blockchain Manager and Canton integration. Use it as the first reference when encountering unfamiliar terminology.
Business Concepts
| **Term** | **Definition** |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Canton Network** | A privacy-first blockchain network built on Daml, designed for regulated financial applications. |
| **Participant** | An organisation connected to the Canton network that can host parties and submit transactions. |
| **Domain** | The synchronisation layer of Canton — mediates transactions between participants. |
| **Sync Domain** | Coordinates transaction sequencing. A **Private Sync Domain** is isolated within an organisation; the **Global Sync Domain** is publicly reachable. |
| **Party** | A logical entity within Canton that can own contracts and be a signatory or observer. |
| **DAR file** | Daml Archive — a compiled package of Daml smart contract code, uploaded to a participant. |
| **Validator** | A Canton node that validates and sequences transactions. A **Bridge Validator** is connected to both a private sync domain and the global sync domain. |
| **Super Validator** | A special Canton participant node that participates in network governance, permissioning, and topology management on the global sync domain. |
| **Splice** | The open-source governance and reward infrastructure for the Canton Network. |
| **CatalyX** | IntellectEU's suite of blockchain infrastructure products built on Canton and other protocols. |
| **CAT-BM** | CatalyX Blockchain Manager, IntellectEU’s platform for deploying and operating Canton and other DLT infrastructure. |
| **CPM** | CatalyX Package Manager, the application registry ("Canton App Store") for discovering, publishing, and downloading Canton applications. |
| **GSF /** **Canton Foundation** | Global Synchronizer Foundation that governs the Global Sync Domain on Canton. |
Technical Concepts
| **Term** | **Definition** |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| **Ledger API** | The gRPC API exposed by Canton participant nodes for submitting and reading transactions. |
| **Admin API** | The API for managing participant configuration, parties, and packages. |
| **Topology** | The configuration of domains, participants, and their relationships on the network. |
| **PQS (Participant Query Store)** | A queryable off-ledger store for Canton contract data. |
| **KMS driver** | Canton integration module that delegates key operations to external KMS/HSM (AWS KMS, GCP KMS, HashiCorp Vault). |
| **WaaS** | Wallet-as-a-Service (e.g. Dfns), external key custody and signing service supported by CAT-BM. |
| **ArgoCD** | GitOps continuous-delivery tool used to synchronise desired state from Git into the Kubernetes cluster. |
| **Helm chart** | Kubernetes packaging format used to deploy Canton components. |
| **CRD (Custom Resource Definition)** | Kubernetes extension used by the CAT-BM Canton Operator to manage node lifecycle. |
| **CAT-BM Canton Operator** | Custom Kubernetes Operator that watches CRDs and reconciles Canton component state. |
| **Round** | 10-minute cycle on Canton Network governing minting and distribution of Canton Coins. |
***
## Learn more about Canton Network
| **Resource** | **Purpose** |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| [Canton Network](https://canton.network/) | Official Canton Network site |
| [Canton Network Whitepaper](https://www.digitalasset.com/hubfs/Canton/Canton%20Network%20-%20White%20Paper.pdf) | Official Canton Network Whitepaper |
| [Global Synchronizer Foundation](https://sync.global/) | GSF governance, committees, and network information |
| [Digital Asset docs](https://docs.digitalasset.com/) | Canton / Daml technical documentation from Digital Asset |
| [Daml documentation](https://docs.daml.com/) | Daml language and SDK reference |
| [Splice on GitHub](https://github.com/hyperledger-labs/splice) | Open-source Splice repository |
| [CIPs](https://github.com/canton-foundation/cips) | Canton Improvement Proposals |
***
# Installation Instructions
This section provides an overview of the steps necessary to launch CAT-BM for the Canton Network.
## Installation Instructions Overview
{% stepper %}
{% step %}
**Prerequisites**
{% content-ref url="/pages/yhlhY7K0tXIMkZgEdUvU" %}
[Prerequisites](/catalyx-blockchain-manager/canton-network/version-1.11/installation-instructions-canton/prerequisites)
{% endcontent-ref %}
{% endstep %}
{% step %}
**Setup**
{% content-ref url="/pages/G7ey5zeAvPIAdBfWtOZ6" %}
[Setup](/catalyx-blockchain-manager/canton-network/version-1.11/installation-instructions-canton/set-up)
{% endcontent-ref %}
{% endstep %}
{% step %}
**CAT-BM Canton Service Installation**
{% content-ref url="/pages/McIbiyvFWD8xpqCFdphN" %}
[CAT-BM Canton Service Installation](/catalyx-blockchain-manager/canton-network/version-1.11/installation-instructions-canton/cat-bm-canton-service-installation)
{% endcontent-ref %}
{% endstep %}
{% step %}
**External Identity Provider Configuration (optional)**
{% content-ref url="/pages/u0ylfiYfGRM6KXWYoz7z" %}
[External Identity Provider Configuration (optional)](/catalyx-blockchain-manager/canton-network/version-1.11/installation-instructions-canton/external-identity-provider-configuration-optional)
{% endcontent-ref %}
{% endstep %}
{% endstepper %}
# Prerequisites
System, infrastructure, and access requirements to prepare for a CatalyX Blockchain Manager installation on Canton Network.
{% stepper %}
{% step %}
**Setup Kubernetes or OpenShift cluster**
{% hint style="info" %}
Supported version of **Kubernetes**: 1.21 and later.\
\
We recommend AWS (EKS) or Google Cloud (GKE), but you can install it on a standalone cluster as well.
{% endhint %}
**Define your cluster size considering the following minimum requirements and your business needs:**
1. Minimal requirements for the Catalyst Blockchain Manager Canton service for 1 instance with:
* 2 core CPU
* 4GB RAM
* 10GB disk space
2. Each node (Domain, participant, or application) that will be deployed consumes additional resources. Minimal requirements for one node:
| Node | CPUe | Memory, Gi | Storage, Gi |
| ----------- | ---- | ---------- | ----------- |
| Domain | 1 | 1 | 1 |
| Participant | 1 | 1 | 1 |
| Application | 1 | 1 | 1 |
{% hint style="info" %}
Deciding on the size of the cluster, please consider the expected load of the nodes and increase these values accordingly.
{% endhint %}
{% endstep %}
{% step %}
**Install Helm to your workstation**
Helm can be installed either from source, or from pre-built binary releases.
**Follow the installation manual below:**
{% embed url="" %}
{% hint style="info" %}
Supported version of **Helm**: 3.X.\
\
No customisation is needed.
{% endhint %}
{% endstep %}
{% step %}
**Install Traefik ingress**
The ingress-controller is needed for traffic routing to expose nodes (domains & applications).\
\
The Catalyst Blockchain Manager Canton service creates a CRD resource (IngressRoute in case of using Traefik), that is automatically started and deleted along with each application (and on demand for domains).
**Follow the installation manual below:**
{% embed url="" %}
{% hint style="info" %}
Supported version of **Traefik**: 2.3.
No customisation is needed, the default port ( :443 ) for HTTPS traffic will be used.
We recommend installing Traefik to a separate namespace from the application (creation of a namespace for the CatalyX Blockchain Manager Canton service is described in step 6).
{% endhint %}
{% endstep %}
{% step %}
**Install cert-manager to create TLS certificate**
TLS certificate is needed for secured communication between a User and the СatalyX Blockchain Manager Canton service components.
**Follow the installation manual below:**
{% embed url="" %}
We recommend using the last release of the official helm chart.
{% hint style="info" %}
You can skip this step and specify your TLS certificate and key as a Kubernetes secret in Helm chart values instead later (Helm chart values are described in the Setup section).\
You can find the manual on how to create a Kubernetes secret here:
[kubernetes.io/docs/concepts/configuration/secret/#tls-secrets](https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets)
{% endhint %}
{% endstep %}
{% step %}
**Create an A-record in a zone in your domain’s DNS management panel and assign it to the load balancer created upon Traefik or OpenShift installation**
CatalyX Blockchain Manager Canton service needs a wildcard record *`*.`* to expose nodes. All created nodes (domains, participants, applications) will have a *`.`* address.
**For example, in case you are using AWS, follow these steps:**
1. Go to the Route53 service.
2. Create a new domain or choose the existing domain.
3. Create an A record.
4. Switch “alias” to ON.
5. In the “Route traffic to” field select “Alias to application and classic load balancer.”
6. Select your region (where the cluster is installed).
7. Select an ELB balancer from the drop-down list.\*
{% hint style="warning" %}
Choose the ELB balancer, which was automatically configured upon the Traefik chart installation as described in step 3 (or upon OpenShift installation in case of using OpenShift).\
You can check the ELB by the following command:
```bash
kubectl get svc -n ${ingress-namespace}
```
* where:
* *`${ingress-namespace}`* is the name of the namespace, where the ingress was installed.
* ELB is displayed in the *`EXTERNAL-IP`* field.
{% endhint %}
{% endstep %}
{% step %}
**Create a namespace for the CatalyX Blockchain Manager Canton service application**
```bash
kubectl create ns ${ns_name}
```
where *`${ns_name}`* — name of namespace (can be any).
{% endstep %}
{% step %}
**Get the credentials to the Helm repository in the JFrog artifactory provided by the IntellectEU admin team**
Add the repo to Helm with the username and password provided:
```bash
helm repo add catbp --username ${ARTIFACTORY_USERNAME} --password ${ARTIFACTORY_PASSWORD}
```
As a result: *`"catbp" has been added to your repositories`*
{% endstep %}
{% step %}
**Create an ImagePullSecret to access the Catalyst Blockchain Manager Canton service deployable images**
For example, create this Secret, naming it *`intellecteu-jfrog-access:`*
```bash
kubectl create secret intellecteu-jfrog-access regcred --docker-server=intellecteu-catbp-docker.jfrog.io --docker-username=${your-name} --docker-password=${your-password} --docker-email=${your-email} -n ${ns_name}
```
where:
* `${your-name}+` — your Docker username.
* `${your-password}` — your Docker password.
* `${your-email}` — your Docker email.
* `${ns_name}` — the namespace created for the Catalyst Blockchain Manager Canton service on the previous step.
{% hint style="warning" %}
In case you want to use a readiness check and use a private repository for the image, you should create a “secret” file with your credentials in Kubernetes for further specifying it in the Helm chart upon Catalyst Blockchain Manager installation.\
\
Please refer to the official Kubernetes documentation: [kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/)\
\
Helm chart configuration instructions you will find [here.](#helmChartVals)
{% endhint %}
{% endstep %}
{% step %}
**Setup Keycloak realm or Auth0 tenant**
**For Keycloak**
Download [the realm.json](https://docs.catalyx.solutions/canton/_attachments/realm-v1.8.json) file and import it to create necessary clients, scopes & users in your keycloak realm.
{% hint style="info" %}
User roles `canton_viewer` & `canton_writer` will be evaluated by the Catalyst Blockchain Manager Canton service
{% endhint %}
{% hint style="info" %}
After creating realm, set url and realm name in [helm values.](#helmChartVals)
{% endhint %}
#### Role-Based Access Control (RBAC)
{% hint style="info" %}
Console UI enforcement of these roles was added in **v1.11.15**. In earlier versions the roles existed on the backend but the Console UI did not adapt to them.
{% endhint %}
Two roles are supported:
* **`canton_viewer`** — can view all resources (domains, participants, applications, validators), but cannot create, edit, or delete anything.
* **`canton_writer`** — can create, edit, and delete any resource, in addition to viewing.
Enforcement is gated by the `AUTH_ROLES` flag, which must be set **consistently on both the API and the UI**:
{% code title="helm-values.yaml" %}
```yaml
api:
extraEnv:
AUTH_ROLES: "true"
ui:
extraEnv:
AUTH_ROLES: "true"
```
{% endcode %}
{% hint style="warning" %}
If `AUTH_ROLES` differs between the `api` and `ui` sections, a viewer can end up seeing create/edit/delete controls that the backend then rejects with HTTP 403 — the API is the source of truth for enforcement, but the UI must match it to hide those controls in the first place. Set the same value in both places.
{% endhint %}
**For Keycloak Auth0 tenant**
If you want to enable Auth0 as an option for ledger authentication, set up a tenant.
{% hint style="info" %}
After creating tenant, make sure set 'enabled', domain, api id, client id and client secret in [helm values.](#helmChartVals)
{% endhint %}
{% endstep %}
{% step %}
**(Optional) Setup Monitoring & Dashboard**
The installation of the CatalyX Blockchain Manager Canton service includes templates to assist monitoring. If you use Graphana, to observe the metrics of all nodes, install the [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) on your cluster.
Once installed, configure Keycloak OAuth2 authentication on Grafana following the detailed steps provided in the [Grafana documentation](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/keycloak/)
[This file](https://docs.catalyx.solutions/canton/_attachments/dashboard-v1.5.json) is a default dashboard that can be [imported in Grafana](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/import-dashboards/).
{% hint style="info" %}
After configuring Grafana, make sure set 'url' & 'clusterDashboard' in the Grafana section in [helm values.](#helmChartVals)
{% endhint %}
{% endstep %}
{% step %}
**Enter License Key**
Request a license key and set it in [helm values.](#helmChartVals)
{% endstep %}
{% endstepper %}
# Setup
Full Helm chart values reference for configuring the CatalyX Blockchain Manager Canton service prior to installation.
Before installing the CatalyX Blockchain Manager Canton Service, you must configure the Helm chart values file. This page documents every available configuration option and explains how to prepare your `values.yaml` file for deployment.
{% hint style="info" %}
You will need values from the previous steps, including your domain name, identity provider credentials, JFrog credentials, and license key, before filling in this file.
{% endhint %}
### Required Configuration
At a minimum, the following fields must be set before installation:
| Field | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `domainName` | The domain where CAT-BM will be hosted (wildcard DNS must be configured). |
| `auth.keycloakUrl` | The base URL of your Keycloak instance. **Only required when using integrated Keycloak** (`auth.keycloak.enabled: true`). |
| `auth.keycloakRealm` | The name of the Keycloak realm created in the prerequisites step. **Only required when using integrated Keycloak.** |
| `api.licenseKey.key` | Your CAT-BM license key (or configure via Kubernetes secret — see below). |
| `api.imagePullSecrets` | The name of the `ImagePullSecret` created in the prerequisites step. |
| `operator.imagePullSecrets` | Same `ImagePullSecret` for the operator component. |
{% hint style="info" %}
If you are using an external Identity Provider (Okta, Microsoft Entra ID, Auth0, or other OIDC-compatible provider) instead of integrated Keycloak, set `auth.keycloak.enabled: false` and configure `auth.url`, `auth.client.idApiOperator`, `auth.client.idUI`, and `auth.client.secret` instead. See the [External Identity Provider Configuration](/catalyx-blockchain-manager/canton-network/version-1.11/installation-instructions-canton/external-identity-provider-configuration-optional) page for full setup instructions.
{% endhint %}
### Configure helm chart values
```yaml
# -- address where application will be hosted.
domainName: ""
auth:
enabled: true
## -- Keycloak is enabled by default. Set keycloakUrl and keycloakRealm when using integrated Keycloak.
## -- To use an external IdP (Okta, Entra ID, Auth0, etc.), set keycloak.enabled=false and configure auth.url and auth.client below instead.
keycloak:
enabled: true
keycloakUrl: ""
keycloakRealm: ""
## -- Configure values below when keycloak.enabled=false (external IdP)
## -- OpenID provider endpoint for obtaining an access token
url: ""
## - OpenID client IDs and secret
client:
idApiOperator: "" # client_id for api and operator components
idUI: "" #client_id for ui component
secret: ""
externalSecret:
enabled: false # If enabled, will be used instead of 'secret' field
remoteSecretRef: "" # Name of the remote secret
secretStoreRef:
name: "" # SecretStore Name
kind: "SecretStore" # Type of SecretStore ("SecretStore" or "ClusterSecretStore")
rbac:
# -- Whether to create RBAC Resourses (Role, SA, RoleBinding)
enabled: true
# -- Service Account Name to use for api, ui, operator
serviceAccountName: canton-console
# -- Automount API credentials for a Service Account.
automountServiceAccountToken: false
# operator component values
operator:
# -- number of operator pods to run
replicaCount: 1
# -- operator image settings
image:
repository: intellecteu-catbp-docker.jfrog.io/catbp/canton/canton-operator
pullPolicy: IfNotPresent
# defaults to appVersion
tag: ""
# -- operator image pull secrets
imagePullSecrets: []
# - name: ""
# -- extra env variables for operator pods
extraEnv: {}
# -- labels for operator pods
labels: {}
# -- annotations for operator pods
podAnnotations: {}
# -- Automount API credentials for a Service Account.
automountServiceAccountToken: true
# -- security context on a pod level
podSecurityContext:
# runAsNonRoot: true
# runAsUser: 4444
# runAsGroup: 5555
# fsGroup: 4444
# -- security context on a container level
securityContext: {}
# Define update strategy for Operator pods
updateStrategy: {}
# -- CPU and Memory requests and limits
# TO TEST
resources: {}
# requests:
# cpu: "200m"
# memory: "500Mi"
# limits:
# cpu: "500m"
# memory: "700Mi"
# -- Specify Node Labels to place operator pods on
nodeSelector: {}
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/
tolerations: []
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity
affinity: {}
# -- keycloak client secret is used to get token from keycloak
# -- Can be fetched from ExternalSecret or provided directly in the 'secret' field
keycloakClient:
secret: "" # Keycloak client secret
externalSecret:
enabled: false # If enabled, will be used instead of 'secret' field
remoteSecretRef: "" # Name of the remote secret
secretStoreRef:
name: "" # SecretStore Name
kind: "SecretStore" # Type of SecretStore ("SecretStore" or "ClusterSecretStore")
## Readiness and Liveness probes for Operator component
## Ref: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/
probes:
# -- Enable Kubernetes Liveness and Readiness probes
enabled: true
# -- Liveness probe for Operator container
livenessProbe:
# -- Number of seconds after the container has started before probe is initiated
initialDelaySeconds: 60
# -- How often (in seconds) to perform the probe
periodSeconds: 10
# -- Number of seconds after which the probe times out
timeoutSeconds: 1
# -- Minimum consecutive successes for the probe to be considered successful after having failed
successThreshold: 1
# -- Minimum consecutive failures for the probe to be considered failed after having succeeded
failureThreshold: 3
# -- Readiness probe for Operator container
readinessProbe:
# -- Number of seconds after the container has started before probe is initiated
initialDelaySeconds: 40
# -- How often (in seconds) to perform the probe
periodSeconds: 10
# -- Number of seconds after which the probe times out
timeoutSeconds: 1
# -- Minimum consecutive successes for the probe to be considered successful after having failed
successThreshold: 1
# -- Minimum consecutive failures for the probe to be considered failed after having succeeded
failureThreshold: 5
# API component values
api:
# -- the persistence volume claim for DARs
darsPvc:
enabled: true
size: 5Gi
mountPath: /dars-storage
# If defined, storageClassName:
# If undefined, no storageClassName spec is set, choosing the default provisioner. (gp2 on AWS, standard on GKE, AWS & OpenStack)
storageClass: ""
# Annotations for darsPvc
# Example:
# annotations:
# example.io/disk-volume-type: SSD
annotations: {}
# -- environment for api pods
environment: "dev"
# -- gateway configuration for channel subscription gateway
gateway:
events:
heartbeat:
enabled: false
interval: 60 # interval in seconds
# -- number of api pods to run
replicaCount: 1
# -- api image settings
image:
repository: intellecteu-catbp-docker.jfrog.io/catbp/canton/canton-console
pullPolicy: IfNotPresent
# defaults to appVersion
tag: ""
# -- api image pull secrets
imagePullSecrets: []
# - name: ""
# -- extra env variables for api pods
extraEnv: {}
# -- labels for api pods
labels: {}
# -- api service port and name
service:
port: 8080
portName: http
# -- annotations for api pods
podAnnotations: {}
# -- Automount API credentials for a Service Account.
automountServiceAccountToken: true
# -- securtiry context on a pod level
podSecurityContext:
# runAsNonRoot: true
# runAsUser: 4444
# runAsGroup: 5555
# fsGroup: 4444
# -- security context on a container level
securityContext: {}
# Define update strategy for API pods
updateStrategy: {}
# type: RollingUpdate
# rollingUpdate:
# maxUnavailable: 0
# maxSurge: 1
# -- CPU and Memory requests and limits
# TO TEST
resources: {}
# requests:
# cpu: "200m"
# memory: "900Mi"
# limits:
# cpu: "500m"
# memory: "1000Mi"
# -- Specify Node Labels to place api pods on
nodeSelector: {}
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/
tolerations: []
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity
affinity: {}
# -- keycloak client secret is used to get token from keycloak
# -- Can be fetched from ExternalSecret or provided directly in the 'secret' field
keycloakClient:
secret: "" # Keycloak client secret
externalSecret:
enabled: false # If enabled, will be used instead of 'secret' field
remoteSecretRef: "" # Name of the external secret
secretStoreRef:
name: "" # SecretStore Name
kind: "SecretStore" # Type of SecretStore ("SecretStore" or "ClusterSecretStore")
## Readiness and Liveness probes for API component
## Ref: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/
probes:
# -- Enable Kubernetes Liveness and Readiness probes
enabled: true
# -- Liveness probe for API container
livenessProbe:
# -- Number of seconds after the container has started before probe is initiated
initialDelaySeconds: 90
# -- How often (in seconds) to perform the probe
periodSeconds: 10
# -- Number of seconds after which the probe times out
timeoutSeconds: 3
# -- Minimum consecutive successes for the probe to be considered successful after having failed
successThreshold: 1
# -- Minimum consecutive failures for the probe to be considered failed after having succeeded
failureThreshold: 3
# -- Readiness probe for API container
readinessProbe:
# -- Number of seconds after the container has started before probe is initiated
initialDelaySeconds: 60
# -- How often (in seconds) to perform the probe
periodSeconds: 10
# -- Number of seconds after which the probe times out
timeoutSeconds: 10
# -- Minimum consecutive successes for the probe to be considered successful after having failed
successThreshold: 1
# -- Minimum consecutive failures for the probe to be considered failed after having succeeded
failureThreshold: 5
# -- License Key for canton console
licenseKey:
key: "" # Set licenseKey if NOT using a Kubernetes secret
secret:
enabled: false # Set to 'true' to use a Kubernetes Secret
name: "" # Name of the Kubernetes secret
key: "" # Key inside the secret that contains licenseKey
# -- Auth providers configuration for ledger
ledgerAuth:
auth0:
enabled: false
domain: ""
apiIdentifier: ""
clientId: ""
clientSecret: ""
# UI component values
ui:
# -- gateway configuration for channel subscription gateway
gateway:
events:
heartbeat:
enabled: false
interval: 60 # interval in seconds
# -- ui autoscaling settings
autoscaling:
enabled: false
minReplicas: 1
maxReplicas: 5
targetCPUUtilizationPercentage: 80
# targetMemoryUtilizationPercentage: 80
# -- number of ui pods to run
replicaCount: 1
# -- api image settings
image:
repository: intellecteu-catbp-docker.jfrog.io/catbp/canton/canton-console-ui
pullPolicy: IfNotPresent
# defaults to appVersion
tag: ""
# -- api image pull secrets
imagePullSecrets: []
# - name: ""
# -- extra env variables for ui pods
extraEnv: {}
# -- labels for ui pods
labels: {}
# -- api service port and name
service:
port: 80
portName: http
# -- annotations for api pods
podAnnotations: {}
# -- Automount API credentials for a Service Account.
automountServiceAccountToken: true
# -- securtiry context on a pod level
podSecurityContext:
# runAsNonRoot: true
# runAsUser: 4444
# runAsGroup: 5555
# fsGroup: 4444
# -- security context on a container level
securityContext: {}
# Define update strategy for UI pods
updateStrategy: {}
# -- CPU and Memory requests and limits
# TO TEST
resources: {}
# requests:
# cpu: "100m"
# memory: "50Mi"
# limits:
# cpu: "200m"
# memory: "200Mi"
# -- Specify Node Labels to place api pods on
nodeSelector: {}
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/
tolerations: []
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity
affinity: {}
# -- metrics server and Prometheus Operator configuration
# -- keycloak client secret is used to get token from keycloak (set in env-specific values)
keycloakClient:
id: ""
# -- Ingress for any ingress controller.
ingressConfig:
provider:
# -- #Currently supported: [traefik, traefikCRD]
name: traefikCRD
traefik:
ingressClass: ""
traefikCRD:
tlsStore:
enabled: false
name: default
# -- specify whether to create Ingres resources for API and UI
enabled: false
tls:
enabled: false
# -- Certificate and Issuer will be created with Cert-Manager. Names will be autogenerated.
# if `certManager.enabled` `ingressConfig.tls.secretName` will be ignored
certManager:
enabled: false
email: ""
server: "https://acme-staging-v02.api.letsencrypt.org/directory"
# -- secret name with own tls certificate to use with ingress
secretName: ""
# Strip Application prefix middleware configuration
stripApplicationPrefix:
enabled: true
regex:
- "/.*(/api)?/"
# -- Whether to parse and send logs to centralised storage
# FluentD Output Configuration. Fluentd aggregates and parses logs
# FluentD is a part of Logging Operator. CRs `Output` and `Flow`s will be created
logOutput:
# Configuration specific to ElasticSearch logging
elasticSearch:
enabled: false
# -- The hostname of your Elasticsearch node
host: ""
# -- The port number of your Elasticsearch node
port: 443
# -- The index name to write events
index_name: ""
# -- Data stream configuration
data_stream:
enabled: false
name: ""
data_stream_template_name: ""
# -- The login username to connect to the Elasticsearch node
user: ""
# -- Specify secure password with Kubernetes secret
secret:
create: false
password: ""
annotations: {}
# Buffer configuration for handling logs
buffer:
chunk_limit_size: 4M
total_limit_size: 512MB
flush_mode: interval
flush_interval: 10s
flush_thread_count: 2
overflow_action: block
# Configuration specific to Loki logging
loki:
enabled: false
# URL of the Loki instance to send logs to
url: ""
# Labels to attach to log streams sent to Loki
# Format: label_name: log_field_name
labels: {}
# Format to use when flattening the record to a log line: key_value, json
line_format: ""
# Buffer configuration for handling logs
buffer:
chunk_limit_size: 4m
timekey: 1m
timekey_wait: 30s
timekey_use_utc: true
# Configuration specific to Logz.io logging
logzIo:
enabled: false
# Logz.io endpoint configuration
endpoint:
url: ""
port: 8071
# Logz.io secret configuration
secret:
create: false
token: ""
annotations: {}
# Include tags in the log output
output_include_tags: true
# Include timestamp in the log output
output_include_time: true
# Buffer configuration for handling logs
buffer:
type: file
flush_mode: interval
flush_thread_count: 4
flush_interval: 5s
chunk_limit_size: 16m
queue_limit_length: 4096
monitoring:
# -- Enable integration with a prometheus-operator. The module fetches metrics from the canton nodes in the system.
# Prometheus operator and grafana need to be installed beforehand
enabled: false
url:
# -- Configuration for ServiceMonitor resource
serviceMonitor:
# -- How often to pull metrics from resources
interval: 30s
# -- Configuration for prometheusRules resource
prometheusRules:
enabled: false
# Additional prometheusRules labels
labels: {}
grafana:
enabled: false
# -- grafana default admin username and email. Grafana is authenticated through default API authentication automatically.
# -- grafana normal URL
url: ""
user: admin
email: admin@domain.com
# -- grafana default path to dashboard
clusterDashboard: ""
# -- grafana service and port for ingress
service:
name: grafana
namespace: monitoring
port: 80
```
# CAT-BM Canton Service Installation
Instructions for deploying the CatalyX Blockchain Manager Canton Service using Helm.
## Install the Catalyst Blockchain Manager Canton Service
Use the following command:
```bash
helm upgrade --install ${canton_release_name} catbp/canton-console --values values.yaml -n ${ns_name}
```
where:
* ${`canton_release_name`} — name of the Catalyst Blockchain Manager Canton service release.\
You can choose any name/alias.\
It is used to address for updating, deleting the Helm chart.
* *`catbp/canton-console`* — chart name, where “catbp” is a repository name, “canton-console” is the chart name.
* *`values.yaml`* — a values file.
* ${`ns_name`} — name of the namespace you’ve created before
You can check the status of the installation by using these commands:
* *`helm ls`* — check the "status" field of the installed chart.
{% hint style="info" %}
Status “deployed” should be shown.
{% endhint %}
* *`kubectl get pods`* — get the status of applications separately.
{% hint style="info" %}
All pods statuses must be “running.”
{% endhint %}
* *`kubectl describe pod $pod_name`* — get detailed information about pods.
# External Identity Provider Configuration (optional)
This section outlines the requirements for configuring an external Identity Provider (IdP) instead of the default integrated Keycloak.
When using an external IdP, CatalyX does not create users or OAuth clients for you; all required OIDC clients and users must be set up in your IdP before creating a validator, in accordance with the Canton Validator OIDC requirements.
{% hint style="info" %}
This page covers the technical configuration requirements for external identity providers, including external IDP setup guides. For more details on the supported identity providers, see the Security & Privacy Implementation page.
{% endhint %}
{% content-ref url="/pages/bvHLoRkGDY6yVqcoe4i9" %}
[Broken mention](broken://pages/bvHLoRkGDY6yVqcoe4i9)
{% endcontent-ref %}
The Identity Provider must be configured before launching a Canton Validator Node. This section provides a brief overview of configuring Clients and Users in your Identity Provider before setting up the Validator. For a full description of requirements, consult the Canton Validator OICD Requirements:
{% embed url="" %}
## 1. Identity Requirements
In this section, we describe the Identity requirements for the Catalyst platform and Canton Validator.
### 1.1. Catalyst Blockchain Manager
Catalyst integrates seamlessly with any OICD OAuth provider. The following information is expected from the Identity Provider:
* OICD Discovery
* Authorize Endpoint
* Token Endpoint
* Refresh Token endpoint
* JWKS endpoint
#### 1.1.1. Clients
The clients required to set up a Canton validator with an IdP are explained below.
**CNS Client ID (Public)**
The requirements for the client are:
* Client ID.
* The client needs to support authorization code flow + token refresh.
* Configure redirect URIs based on the environment. Please request them from your Catalyst admin.
**Client Catalyst API (Private)**
This client is used by the Catalyst API. The main requirements are:
* Client ID.
* Client secret.
* The client needs to support authorization code flow + token refresh
* The requirement for an authorization code depends on the IdP and will be verified during the integration test.
* This client is used only for server-to-server interactions and does not require redirect URIs.
#### 1.1.2. Users
To start using Catalyst, you must create a user for the administrator of the instance.
### 1.2. Canton Validator
The requirements for the OICD Provider are explained through the following docs:
{% embed url="" %}
#### 1.2.1. Clients
Based on the documentation, the required clients for the Canton Validator are:
* **CNS Client**
* Client ID
* Redirect URI: Please request them from your Catalyst Admin.
* **Wallet Client**
* Client ID
* Redirect URI: Please request them from your Catalyst Admin.
* **Ledger Client**
* Client ID
* Ledger Client Secret
* Ledger API User: The token needs a sub field. In most of the IdPs, the Client ID is the sub, but in others, it is required to create a service account logic to fill in this field correctly.
#### 1.2.2. Users
The validator requires a wallet user account. This user is required to log in to the wallet application.
## 2. Canton JWT Requirements
From a security perspective, the components that comprise the Validator node must be able to authenticate with one another and with external UI and API users. Canton uses JTW access tokens for authentication and expects them to be issued by an external OpenID Connect (OIDC) provider.
Canton follows the OAuth 2.0 Authorization Framework, as defined in RFC 6749 and RFC 6750.
The Ledger API enforces some JWT dependencies that are described in the following documentation:
{% embed url="" %}
Based on our experience, the changes should be the following:
* The configuration time-to-live for the client JWT tokens should be set to > 5 minutes.
* JWT Header Claim
* The typ claim should be “JWT”.
* JWT Payload Mandatory fields
* iss
* sub
* aud
* exp
* iat
* Scope: should be a list of strings separated by one space.
***
# Okta Setup Guide
CatalyX Blockchain Manager supports Okta as an external Identity Provider. This section walks through the steps required to configure Okta before creating a validator in CAT-BM.
### Catalyst Client Setup
Two clients must be created in Okta under **Applications → Applications**.
**UI Client**
The UI client is used by the CAT-BM console. When creating it, select the following options:
* Sign-in method: **OIDC - OpenID Connect**
* Application type: **Single-Page Application**
* Grant type: **Authorization Code** and **Refresh Token**
Once created, navigate to **LOGIN → Sign-in redirect URIs** and add the following URLs:
* ``
* `/domains`
* `/participants`
Add the same URLs to the **Sign-out redirect URIs**.
**API Client**
This client is used by the CAT-BM API and other backend components. When creating it, select:
* Sign-in method: **OIDC - OpenID Connect**
* Application type: **Web Application**
* Grant type: **Client Credentials**, **Authorization Code**, and **Refresh Token**
| Client | Sign-in Method | Application Type | Grant Types | Has Client Secret |
| ------ | --------------------- | ----------------------- | ----------------------------------------------------- | ----------------- |
| UI | OIDC - OpenID Connect | Single-Page Application | Authorization Code; Refresh Token | No |
| API | OIDC - OpenID Connect | Web Application | Client Credentials; Authorization Code; Refresh Token | Yes |
### User Access Setup
CAT-BM enforces role-based access using two roles: `canton_viewer` (read-only) and `canton_writer` (full operational access). These roles must be added to the Okta token.
**Step 1 — Add the roles attribute to the user profile:**
Go to **Profile Editor → User (default)**:
* Select **Add Attribute** and choose **String Array**
* Set Display name to `roles`
* Set Variable name to `roles`
**Step 2 — Add the roles claim to the token:**
Go to **Security → API → \[your auth server] → Claims** and select **Add Claim**:
* Name: `roles` (must be this exact name)
* Include in token type: **Access Token**
* Value: `user.roles` (or `appuser.roles` if added to the application user profile)
Repeat with **Include in token type** set to **ID Token**.
{% hint style="info" %}
You can verify the token in **Security → API → Token Preview**. The token should contain a `roles` claim with `canton_viewer` and `canton_writer` values in both the `id_token` and `token`.
{% endhint %}
### Helm Chart Configuration
{% hint style="info" %}
**GitOps transition note:** CatalyX Blockchain Manager is moving toward a GitOps-driven deployment model using Helm charts managed via ArgoCD. The Helm chart field references below reflect the current configuration approach. These may change as the GitOps model matures — confirm with the engineering team for the latest guidance on your deployment.
{% endhint %}
Fill in the following fields in your Helm chart values:
```yaml
auth:
url: “”
client:
idApiOperator: “”
idUI: “”
secret: “”
```
* **auth.url** — The Issuer URI from **Security → API → \[your auth server]** (the Issuer URI field on the default server)
* **auth.client.idApiOperator** — Client ID of the API client, found under **Applications → Applications**
* **auth.client.idUI** — Client ID of the UI client, found under **Applications → Applications**
* **auth.client.secret** — Client Secret of the API client, found on the client's page
### Validator Client Setup
Before creating a validator in CAT-BM, three additional clients must be created in Okta.
**CNS and Wallet Clients**
Create two separate clients with the following options:
* Sign-in method: **OIDC - OpenID Connect**
* Application type: **Single-Page Application**
* Grant type: **Authorization Code** and **Refresh Token**
After creating the validator, retrieve the Wallet URL from the Wallet page and add it to **LOGIN → Sign-in redirect URIs** on the Wallet client.
**Ledger Client**
* Sign-in method: **API Services**
#### Adding the `daml_ledger_api` Scope
After creating the Ledger client, you need to define and assign the `daml_ledger_api` scope so the client can request it in token exchanges.
**Step 1 — Add the scope to your authorization server:**
Go to **Security → API → \[your auth server] → Scopes** and select **Add Scope**:
* Name: `daml_ledger_api`
* Display phrase: `Daml Ledger API` (or any descriptive label)
* Default scope: unchecked (unless required by your setup)
**Step 2 — Grant the scope to the Ledger client:**
Go to **Applications → Applications → Ledger client → Okta API Scopes**, locate `daml_ledger_api`, and click **Grant**.
**Step 3 — Verify the scope is returned in tokens:**
Go to **Security → API → Token Preview**, select the Ledger client and **Client Credentials** grant type, then confirm `daml_ledger_api` appears in the `scp` claim of the resulting access token.
| Client | Sign-in Method | Application Type | Grant Types | Has Client Secret |
| ------ | --------------------- | ----------------------- | --------------------------------- | ----------------- |
| Wallet | OIDC - OpenID Connect | Single-Page Application | Authorization Code; Refresh Token | No |
| CNS | OIDC - OpenID Connect | Single-Page Application | Authorization Code; Refresh Token | No |
| Ledger | API Services | — | — | Yes |
Assign at least one user to both the Wallet and CNS clients — this will be the main wallet user when creating the validator.
### Obtaining Fields for Validator Creation
When creating a validator in CAT-BM with Okta as the IdP, the following fields are required:
| Field | Where to find it in Okta |
| ------------------------ | ---------------------------------------------------------------- |
| CNS Client ID | Applications → Applications → CNS client → Client ID |
| Wallet Client ID | Applications → Applications → Wallet client → Client ID |
| Ledger API Client ID | Applications → Applications → Ledger client → Client ID |
| Ledger API Client Secret | Applications → Applications → Ledger client → Client Secrets tab |
| Ledger API User | Same as the Ledger API Client ID by default in Okta |
| Wallet User | Username of the main wallet user account |
| Audience | Security → API → \[your auth server] → Audience field |
# Microsoft EntraID Setup Guide
CatalyX Blockchain Manager supports Microsoft Entra ID (formerly Azure Active Directory) as an external Identity Provider.
## 1 — Catalyst Client Setup
### 1.1 — UI Client
Create a new App Registration for the UI:
* **Name:** `canton-ui`
* **Supported account types:** Single tenant (My organization only)
* **Platform:** Single-Page Application (SPA)
After creation, go to **Authentication → Add Redirect URI** and add the following URLs:
* ``
* `/domains`
* `/participants`
* `/validators`
**CORS origins:**
* ``
**Front-channel logout URL:**
* ``
{% hint style="info" %}
Redirect URIs, CORS origins, and the logout URL will be known after installation on a fresh environment.
{% endhint %}
### 1.2 — API Client
Create a second App Registration for the API:
* **Name:** `catalyst-api`
* **Supported account types:** Single tenant
After creation:
{% stepper %}
{% step %}
#### Create a Client Secret
Go to **Certificates & Secrets → New client secret** and save the secret **value** immediately — it will not be shown again. Do not save the secret ID.
{% endstep %}
{% step %}
#### Expose an API
Go to **Expose an API → Add** next to Application ID URI and accept the default value `api://`.
{% endstep %}
{% step %}
#### Add a Scope
Click **Add a scope** and fill in:
* **Scope name:** `access`
* **Who can consent:** Admins and users
* **Admin consent display name:** `Catalyst API access`
* **Admin consent description:** `Catalyst API access`
{% endstep %}
{% step %}
#### Grant API Permissions
Go to the **UI App Registration → API permissions → Add a permission → My APIs → catalyst-api**, select the `access` scope, and click **Add permissions**.
Then click **Grant admin consent for \[tenant]**.
{% endstep %}
{% endstepper %}
| Client | Platform Type | Grant Types | Has Client Secret |
| -------------------- | ----------------------- | ------------------------------------------------------- | ----------------- |
| UI (`canton-ui`) | Single-Page Application | Authorization Code (PKCE) + Refresh Token | No |
| API (`catalyst-api`) | Web | Client Credentials + Authorization Code + Refresh Token | Yes |
### 1.3 — User Setup
Create a new user in **Entra ID → Users → New user → Create new user**:
* **Username:** e.g. `canton-admin@.onmicrosoft.com`
* **Display name:** e.g. `Canton Admin`
* **Password:** set a temporary password — the user will be prompted to change it on first login
Assign the user to both Enterprise Applications:
* **Entra ID → Enterprise Applications → `canton-ui` → Users and Groups → Add user/group**
* **Entra ID → Enterprise Applications → `catalyst-api` → Users and Groups → Add user/group**
### 1.4 — Fields Required by IntellectEU
After completing the Entra ID setup, provide the following values to IntellectEU:
| Field | Where to find it |
| ----------------- | ----------------------------------------------------------------------------------------- |
| UI Client ID | App Registrations → `canton-ui` → Overview → Application (client) ID |
| API Client ID | App Registrations → `catalyst-api` → Overview → Application (client) ID |
| API Client Secret | App Registrations → `catalyst-api` → Certificates & Secrets → value saved during creation |
| Tenant ID | Entra ID → Overview → Tenant ID |
| Auth URL | `https://login.microsoftonline.com//v2.0` |
| User Username | Entra ID → Users → \[user] → User principal name |
| User Password | Set during user creation in step 1.3 |
# Auth0 Setup Guide
## Configuring Auth0 for CatalyX
### 1. CatalyX API (Resource Server)
Navigate to **Applications → APIs → Create API** and configure:
* **Name:** CatalyX
* **Identifier (Audience):** ``
### 2. UI Client
Create a new application with type **Single Page Application** and configure:
* **Grant types:** Authorization Code, Refresh Token
* **Allowed Callback URLs:** ``, `/domains`, `/participants`
* **Allowed Logout URLs:** same three URLs as above
The UI client requests the `` on login.
### 3. API Client
Create a new application with type **Regular Web Application** and configure:
* **Grant types:** Client Credentials, Authorization Code, Refresh Token
### 4. Connect Both Clients to the CatalyX API
Go to **APIs → CatalyX → Machine to Machine Applications**, enable both the UI and API clients, and grant their respective scopes.
| Client | Application Type | Grant Types | Has Client Secret |
| ------ | ----------------------- | ----------------------------------------------------- | ----------------- |
| UI | Single Page Application | Authorization Code; Refresh Token | No |
| API | Regular Web Application | Client Credentials; Authorization Code; Refresh Token | Yes |
### Example Helm Value Overrides
{% code title="helm-values.yaml" %}
```yaml
api:
extraEnv:
AUTH_ROLES: "false"
AUTH_AUDIENCE: "" # Comes from identifier of Auth0 API
ui:
extraEnv:
AUTH_ROLES: "false"
AUTH_AUDIENCE: "" # Comes from identifier of Auth0 API
auth:
enabled: true
keycloak:
enabled: false
url: "https://dev-2bsf8p5hbjadzwh4.us.auth0.com/" # Example URL
client:
idApiOperator: ""
idUI: ""
secret: ""
```
{% endcode %}
{% hint style="info" %}
`AUTH_ROLES` must be set to the same value under both `api.extraEnv` and `ui.extraEnv` — see [Role-Based Access Control (RBAC)](/catalyx-blockchain-manager/canton-network/version-1.11/installation-instructions-canton/prerequisites#role-based-access-control-rbac) for what `canton_viewer`/`canton_writer` enforcement does when this flag is `"true"`.
{% endhint %}
## Configuring Auth0 for Validator
To configure Auth0 resources for a validator, follow the [Kubernetes Validator Deployment](https://docs.canton.network) guide. Resources should be created under the CatalyX API.
{% hint style="info" %}
Callback URLs and Logout URLs can be added after CatalyX deploys Wallet and CNS resources and generates the URLs.
{% endhint %}
# Network & Node Management
# Domains
This page introduces Domains (or Synchronizers) in Canton and explains how they are created and configured in Catalyst. Canton is a network composed of multiple domains, each operating under its own rules, governance, and set of participants. Each domain functions as an independent sub-network that participates in the wider Canton Network.
### What is a Domain/ Synchronizer?
In a composed solution, each domain is a sub-network. A Participant Node connects to one or more Domains, enabling transactions that span Domains.
{% hint style="info" %}
For more information about Participant nodes, see [Participants](broken://pages/27a5b9a93b16fb5fe81a9e6ff2aa908021e0156b).
{% endhint %}
### How Do I Create a Domain?
To create a Domain, go to the **Domains** tab and click the **Create** button to open a side window.
{% stepper %}
{% step %}
**Provide a Domain name**
Enter a unique Domain name (required).
{% endstep %}
{% step %}
**Fill in the main settings**
{% hint style="info" %}
Using a predefined image is recommended for compatibility. However, you can select your own image if needed. If you want to use an image from a private repository, specify an `imagePullSecret`. You can create an `imagePullSecret` in your Kubernetes cluster and reference it by name here.
{% endhint %}
* Choose domain image
* Enable **Daemon** if required
* Enable **Ingress** if required
* **Resources allocation:**
* **Requested CPU** — Guaranteed CPU resources that will be allocated
* **CPU limit** — Maximum CPU resources that will be allocated
* **Requested memory (MB)** — Guaranteed amount of RAM that will be allocated
* **Memory limit (MB)** — Maximum amount of RAM that can be allocated
* **Storage size**
* You can add custom environment variables if needed
{% endstep %}
{% step %}
**Fill in Topology**
* Enable **Embedded Topology** if needed
* **Topology:**
* Choose between form or raw view topology
* Choose **Admin Port**
* Choose **Public port**
* Choose **Storage type:**
{% tabs %}
{% tab title="Memory" %}
No additional configuration required.
{% endtab %}
{% tab title="PostgreSQL" %}
A PostgreSQL database will be provisioned in the cluster.
* Choose User
* Choose Password
* Choose Storage size
{% hint style="info" %}
When selecting PostgreSQL as storage type, a postgres database will be provisioned in the cluster.
{% endhint %}
{% hint style="info" %}
For production deployments, consider using the **External** option below instead. See [Validator Backups and Identity Dumps](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/identity-backup-and-recovery#use-an-external-database-for-production) for recommendations on database hosting and safe pod operations.
{% endhint %}
{% endtab %}
{% tab title="External" %}
A database is expected to be hosted at the given hostname and port, with the same name as the domain and a user with the provided credentials.
* Choose User
* Choose Password
* Choose Hostname
* Choose Port
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
**Bootstrap (optional)**
Provide bootstrap commands if needed.
{% endstep %}
{% endstepper %}
***
# Participants
This page introduces Participants in Canton and explains how they are created, configured, and managed using Catalyst. In Canton's execution model, each application party is hosted on a Participant Node, which maintains the party's private state and history and synchronizes with other participants using the Canton protocol via domains.
### What is a Participant?
Each party of the application is hosted on a **Participant Node**. The Participant Node stores the party's unique projection and history of the shared system of record. Participant Nodes synchronize by running a consensus protocol (the Canton Protocol) between them, sending encrypted messages through Domains that provide guaranteed delivery and order consistency.
{% hint style="info" %}
For more information about Domains, see [Domains](broken://pages/df6fa4e1fbdb4023b904163cd1981d66ba03e3e1).
{% endhint %}
### How Do I Create a Participant?
To create a Participant, go to the **Participants** tab and click the **Create** button to open a side window.
{% stepper %}
{% step %}
**Provide a Participant name**
Enter a unique Participant name (required).
{% endstep %}
{% step %}
**Fill in the main settings**
{% hint style="info" %}
Using a predefined image is recommended for compatibility. If you want to use an image from a private repository, specify an `imagePullSecret`.
{% endhint %}
* Choose participant image
* Choose DAR files to upload
* Enable **Navigator** if required
* Enable **Daemon** if required
* **Resources allocation:**
* **Requested CPU** — Guaranteed CPU resources that will be allocated
* **CPU limit** — Maximum CPU resources that will be allocated
* **Requested memory (MB)** — Guaranteed amount of RAM that will be allocated
* **Memory limit (MB)** — Maximum amount of RAM that can be allocated
* **Storage size**
* You can add custom environment variables if needed
{% hint style="info" %}
To prevent pod evictions, you can choose to disable CPU limits for the resource allocation.
{% endhint %}
{% endstep %}
{% step %}
**Fill in Topology**
* Enable **Embedded Topology** if needed
* **Topology:**
* Choose between form or raw view topology
* Choose **Admin Port**
* Choose **Public port**
* Choose **Storage type:**
{% tabs %}
{% tab title="Memory" %}
No additional configuration required.
{% endtab %}
{% tab title="PostgreSQL" %}
A postgres database will be provisioned in the cluster.
* Choose User
* Choose Password
* Choose Storage size
{% hint style="info" %}
For production deployments, consider using the **External** option below instead. See [Validator Backups and Identity Dumps](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/identity-backup-and-recovery#use-an-external-database-for-production) for recommendations on database hosting and safe pod operations.
{% endhint %}
{% endtab %}
{% tab title="External" %}
A database is expected to be hosted at the given hostname and port with the same name as the participant and a user with the provided credentials.
* Choose User
* Choose Password
* Choose Hostname
* Choose Port
{% endtab %}
{% endtabs %}
* Enable **Authorization Service** if needed
{% endstep %}
{% step %}
**Bootstrap (optional)**
Provide bootstrap commands if needed.
{% endstep %}
{% endstepper %}
### How Do I Connect a Participant to a Domain?
After the participant is created, click the **Connect to domain** button to open a side window.
{% hint style="info" %}
Select either a domain available in this Catalyst Canton console, or connect to any external domain by providing the full domain URL.
{% endhint %}
### How Do I Upload DAR Files to a Participant?
After the participant is created, click the **Upload DAR** button to open a side window.
{% hint style="info" %}
Select one or multiple DAR files to upload to the participant. DAR files can be added to the console through the [Collections](broken://pages/70b986760b8e86303857f0b72acf6a4f5adf5e8d) tab.
{% endhint %}
### Parties & Users
A party represents an entity capable of creating and interacting with contracts on the ledger. Each party is hosted on one or more Participant Nodes.
A Party is created by default once a Participant is connected to a Domain. However, Catalyst Blockchain Manager allows users to add additional parties on a participant node.
#### Local Parties vs. Parties
The Participant Details page includes the following tabs: **Local Parties**, **Parties**, **Users**, **Dar Files**, and **Logs**.
* **Local Parties** — Allows users to trigger an explicit fetch of all parties registered to this participant on the ledger.
* **Parties** — Shows parties across the entire ledger (the full network), not just those local to this participant.
{% hint style="info" %}
If you create a party outside of Catalyst, it will not appear in the list automatically. Click **Fetch Local Parties** again to pick up that change.
{% endhint %}
{% hint style="info" %}
The Local Parties tab is only shown for validator participants. It does not appear for standalone participants (non-validator nodes).
{% endhint %}
{% hint style="warning" %}
For networks with a large number of parties (e.g., MainNet with \~500,000 parties), the fetch process can take a considerable amount of time.
{% endhint %}
For detailed Party and User Management, head to the Parties and Users section:
{% content-ref url="/pages/f15e7603f08b261b9e85b489ea62cbaefac624f8" %}
[Parties & Users](/catalyx-blockchain-manager/canton-network/version-1.11/network-and-node-management/parties-and-users)
{% endcontent-ref %}
# Parties & Users
## Overview
This section explains how to:
* View and manage parties on a participant.
* Create a User in Keycloak.
* Create a User in CatalyX.
* Assign user permissions and roles.
* Link a User to a Party.
* Access the Wallet UI.
This process is commonly used when onboarding a new customer, validator user, or application participant.
## Prerequisites
Before starting, ensure you have:
* Access to CatalyX Blockchain Manager
* Access to the Keycloak Admin Console
* Permissions to manage Participants and Users
* A deployed validator or participant
***
## Part 1 — View and Manage Parties
### What is a Party?
A Party represents an entity capable of creating contracts, interacting with contracts, and participating on the ledger. Each Party is hosted on one or more Participant Nodes.
### The Parties Tab
The **Parties** tab on the Participant details page allows you to look up any party — local or remote — by ID prefix. Enter at least two characters of a party ID to search. This tab is suitable for looking up a specific known party.
{% hint style="info" %}
The Parties tab does not load all parties automatically. In production environments a participant may be aware of hundreds of thousands of parties (the Canton Network MainNet has \~500,000+), making a full listing impractical.
{% endhint %}
### The Local Parties Tab
The **Local Parties** tab shows parties that are hosted on this participant node. Unlike the Parties tab, local parties can be fetched in bulk.
Local parties are **not** loaded automatically on page load. To retrieve them, click **Fetch Local Parties**. While fetching is in progress, the existing list continues to be displayed and the fetch button is disabled. Once complete, the list updates to show all local parties.
{% hint style="info" %}
Only parties created through CatalyX are guaranteed to appear in the local parties list. Parties created directly via the Ledger API or gRPC may not be included.
{% endhint %}
### Create a Party
To allocate a new party on this participant, open the **Parties** tab and click **Add Party**. Provide a party name and any optional display information, then click **Save**.
After creation, the party becomes available on the ledger. Example party identifier:
```
alice::participant1::domain
```
***
## Part 2 — Create a User in Keycloak
{% stepper %}
{% step %}
**Open Keycloak**
Log in to the **Keycloak Admin Console** and select the appropriate Realm.
{% endstep %}
{% step %}
**Create a User**
Navigate to **Users** and click **Add User**. Enter a username.
{% hint style="info" %}
Recommended naming convention: `cpm-${client}`
{% endhint %}
{% endstep %}
{% step %}
**Configure Credentials**
Open the **Credentials** tab, set a password, and save your changes.
{% endstep %}
{% endstepper %}
***
## Part 3 — Create a User in CatalyX
{% stepper %}
{% step %}
**Open Participant Users**
Navigate to **Participants**, open the target Participant, open the **Users** tab, and click **Create User**.
{% endstep %}
{% step %}
**Configure the User**
Provide a username.
{% hint style="warning" %}
The username must match the Keycloak username exactly. Example: `cpm-client`
{% endhint %}
{% endstep %}
{% step %}
**Assign the Primary Party**
Paste the full party ID of the party created in Part 1 directly into the **Primary Party** field. Do not use a party name — the field requires the full party address.
{% hint style="info" %}
You can copy the full party ID from the **Local Parties** or **Parties** tab on the Participant details page.
{% endhint %}
{% hint style="warning" %}
If the party ID entered does not exist on this participant, CatalyX will display an error. Verify the party ID is correct and that the party is hosted on this participant before proceeding.
{% endhint %}
{% endstep %}
{% endstepper %}
***
## Part 4 — Grant User Rights and Roles
### Available Rights
{% tabs %}
{% tab title="CanActAs" %}
Allows the user to act on behalf of the Party, submit transactions, and interact with contracts.
**Recommended for:** operational users, wallet users, application users.
{% endtab %}
{% tab title="CanReadAs" %}
Allows the user to view ledger data and read contracts. Does **not** allow submitting transactions or acting on behalf of the Party.
**Recommended for:** auditors, monitoring users, read-only access.
{% endtab %}
{% tab title="ParticipantAdmin" %}
Provides administrative access to the Participant. Use carefully.
**Recommended only for:** platform administrators, DevOps operators.
{% endtab %}
{% endtabs %}
### Recommended Rights by User Type
| User Type | Recommended Rights |
| ----------- | ------------------ |
| Wallet user | CanActAs |
| Auditor | CanReadAs |
| Admin | ParticipantAdmin |
### Assign Rights
Under **User Rights**, choose the appropriate role and select the target Party, then click **Save**.
{% hint style="info" %}
Grant the minimum required permissions. Avoid assigning `ParticipantAdmin` unless necessary.
{% endhint %}
***
## Part 5 — Access the Wallet UI
{% stepper %}
{% step %}
**Open the Wallet UI**
Open the Wallet UI URL for your validator. Example: `https://wallet-${validator-name}.${domain}`
{% endstep %}
{% step %}
**Log in**
Log in using the Keycloak credentials created in Part 2.
{% endstep %}
{% endstepper %}
After login, verify that the wallet opens successfully, balances are visible, and Party permissions work correctly.
{% hint style="warning" %}
Use an incognito browser window to avoid Keycloak session conflicts.
{% endhint %}
***
## Validation Checklist
| Validation | Expected Result |
| --------------------- | ------------------------------ |
| Party created | Party visible in CatalyX |
| Keycloak user created | User can authenticate |
| CatalyX user created | User visible under Participant |
| Rights assigned | User has correct access |
| Wallet login works | User can access wallet |
## Troubleshooting
| Issue | Cause | Resolution |
| ---------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| User cannot log in | Incorrect Keycloak credentials | Reset password |
| Wallet access denied | Missing CanActAs role | Grant correct rights |
| User not linked to Party | Primary Party not assigned | Update user configuration |
| Primary Party field shows an error | Party ID does not exist on this participant | Verify the full party ID from the Local Parties tab |
| User visible in Keycloak but not CatalyX | CatalyX user not created | Create user in Participant Users tab |
| Session conflicts during login | Existing Keycloak session | Use incognito browser |
| Local Parties list is empty after fetch | No parties created through CatalyX yet, or startup fetch is disabled | Click Fetch Local Parties manually; check `CANTON_CONSOLE_PARTIES_FETCH_ALL` setting |
## Best Practices
* Use consistent naming conventions across Keycloak and CatalyX
* Match Keycloak and CatalyX usernames exactly
* Copy party IDs directly from the Local Parties tab to avoid typos
* Grant minimum required permissions
* Avoid assigning `ParticipantAdmin` unless necessary
* Use separate users for admin and operational activities
# Applications
This page explains how custom applications can be deployed and managed in Catalyst through the Applications tab. Applications can be backend or frontend types, including DAML-based applications.
### How Do I Create an Application?
To create an application, go to the **Applications** tab and click the **Create** button to open a side window.
{% stepper %}
{% step %}
**Provide an Application name**
Enter a unique Application name (required).
{% endstep %}
{% step %}
**Fill in the main settings**
Applications can have a **UI** or **Backend** type.
{% tabs %}
{% tab title="UI Application" %}
When deploying a UI application, choose between providing an image for the application or selecting one of the previously uploaded UI files (uploaded through the [Collections](broken://pages/70b986760b8e86303857f0b72acf6a4f5adf5e8d) tab).
{% hint style="info" %}
When selecting a UI file to deploy, the image field will be ignored. The UI application will be served by a nginx server.
{% endhint %}
{% endtab %}
{% tab title="Backend Application" %}
Provide a Docker image for the backend application.
{% endtab %}
{% endtabs %}
* Choose **Application Type**
* Choose **application image** (or file if UI app and not using an image)
* Choose **Port**
* Choose **Subdomain:**
* Select subdomain from existing participants
* Choose custom subdomain
* **Resources allocation:**
* **Requested CPU** — Guaranteed CPU resources that will be allocated
* **CPU limit** — Maximum CPU resources that will be allocated
* **Requested memory (MB)** — Guaranteed amount of RAM that will be allocated
* **Memory limit (MB)** — Maximum amount of RAM that can be allocated
* You can add custom environment variables if needed
{% endstep %}
{% endstepper %}
***
# Collections
This page explains how Collections in Catalyst are used to manage reusable artifacts such as DAML archive (DAR) packages and UI packages. Items uploaded to Collections can later be uploaded to participants or deployed as applications.
{% hint style="info" %}
For a step-by-step guide on uploading DAR files — including direct participant uploads, application-specific deployments (CPM, billing, Tradecraft), and Canton console commands — see [Upload DARs](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/dar-management).
{% endhint %}
### My Collection
In the **My Collection** tab, DAR packages and UI packages can be uploaded to the console. These can then be uploaded to participants or deployed as applications respectively.
#### DAR Collections
When a Daml project is compiled, the compiler produces a Daml archive. These are platform-independent packages of compiled Daml code that can be uploaded to a Daml ledger or imported in other Daml projects. Daml archives have a `.dar` file ending.
{% hint style="info" %}
DAR files can be uploaded from the user's local computer, or obtained from the Catalyst Package Manager (CPM).
To read about CPM, see the [Canton Package Manager](/catalyx-package-manager) section of this guide.
{% endhint %}
**Upload a DAR file**
To upload a DAR file, go to the **Collections** tab and click **Upload DAR File** to open a side window.
#### UI Collections
The UI Collections feature of Catalyst allows you to provide a frontend for your app by publishing files exposed by HTTPS over a ledger-specific subdomain.
{% hint style="warning" %}
UI Collections must be uploaded to the console and deployed in the form of `.zip` files. The `.zip` should contain a single root directory, and the contents of that directory should contain an `index.html` along with the rest of the resources for your UI.
{% endhint %}
To upload a UI file, go to the **Collections** tab and click **Upload UI File** to open a side window.
***
# Networking
This page describes how network communication works in Catalyst for participants, domains, and applications. Components running inside the cluster communicate using Kubernetes internal DNS names, while selected services and APIs can also be exposed externally through ingress routes.
### Participants
For every participant running on Catalyst, the following (internal) endpoints are available:
| Endpoint | Address |
| ---------------------------- | ---------------------------------------------------------------------- |
| **Ledger API** | `..svc.cluster.local:5011` |
| **Admin API** | `..svc.cluster.local:5019` |
| **HTTP JSON API (internal)** | `jsonapi-..svc.cluster.local:7011` |
| **HTTP JSON API (external)** | `http(s)://.` |
{% hint style="info" %}
Default ports are shown above. If you set custom ports when creating a participant, the values will differ.
{% endhint %}
### Domains
For every domain running on Catalyst, the following (internal) endpoints are available:
| Endpoint | Address |
| ------------------------ | --------------------------------------------------------- |
| **Public API** | `..svc.cluster.local:5018` |
| **Admin API** | `..svc.cluster.local:5019` |
| **Ingress (if enabled)** | `http(s)://.` |
{% hint style="info" %}
Default ports are shown above. If you set custom ports when creating a domain, the values will differ.
{% endhint %}
### Applications
For every application running on Catalyst, the following endpoints are available:
| Type | Address |
| ---------------- | ------------------------------------------------------------ |
| **Internal** | `..svc.cluster.local:80` |
| **Backend app** | `http(s)://.//api` |
| **Frontend app** | `http(s)://./` |
{% hint style="info" %}
The default port (80) is used above. If you set a custom port when creating an application, the value will differ.
{% endhint %}
***
# Validator Management
# Validator Management with Integrated Keycloak
This page explains how to use Catalyst to create and deploy Validators on the Canton network with Integrated Keycloak. In this mode, Catalyst provisions and configures Keycloak automatically as part of the validator deployment, you don't need to bring or manage your own identity provider.
Keycloak is a login and user-management system: it verifies who you are, lets you sign in securely, and controls what you're allowed to access. When you create a validator with integrated Keycloak, Catalyst uses Keycloak as the security gate for all validator services, automatically creating the required users and connecting components such as the Wallet UI and APIs.
{% hint style="info" %}
This guide is for the **Default** authentication option with integrated Keycloak. To set up a validator with a custom identity provider, see [Create Validator with Custom Identity Provider](broken://pages/1d459ba5d7a4cfbd01fe511c1d03b5a8a26223cd).
{% endhint %}
### Validator Management
Validators can be deployed on Catalyst and seamlessly connected to the Canton Network.
#### Set Up a Validator
To set up a Validator, go to the **Validators** tab and click the **Set up validator** button to open a side window.
{% stepper %}
{% step %}
**Main Settings Configuration**
Provide the following information:
* Sponsor SV Name
* Name
* Onboard secret
* Image tag
* Image repo
* Image pull secret
* Scan address
* SV sponsor address
* Party hint
* Migration id
More info about these fields
| Field | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sponsor SV Name** | The name of the Super Validator that sponsored you to join the network |
| **Name** | The identifier or label for the validator node |
| **Onboard secret** | Passphrase obtained from the super validator in order to join the network |
| **Image tag** | The specific version or tag of the container image to be used |
| **Image repo** | The repository where the container image is stored |
| **Image pull secret** | Credentials required to pull the container image from a private registry (`secret docker-registry`) |
| **Scan address** | The address used for scanning and retrieving validator-related data |
| **SV Sponsor Address** | URL of the SV app of the super validator sponsoring you. Typically starts with `https://sv.sv-N` |
| **Party hint** | Used as a prefix for the Party ID of your validator's administrator. Format: `--`, e.g., `myCompany-myWallet-1` |
| **Migration id** | Used to track database migrations. Starts at `0` for the initial deployment and increments by 1 with each migration |
{% hint style="info" %}
An onboarding secret should be requested from your sponsoring SV in order to join the network.
{% endhint %}
{% hint style="warning" %}
Only turn on the **Restore participant identities** toggle if you want to restore a validator from an Identity Dump.
{% endhint %}
{% endstep %}
{% step %}
**Cluster Configuration**
Provide the following information:
**2.1 — Enable or disable:**
* Disable wallet
* Fail on app version mismatch
* Disable probes
**2.2 — Fill in the remaining fields:**
* Default JVM Options
* Top up:
* Enable
* Min Top up interval
* Target throughput
* Contact point
More info about these fields
| Field | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Disable wallet** | Turn on to not deploy a wallet UI with your validator |
| **Fail on app version mismatch** | If enabled, the deployment will fail if there is a mismatch between the validator and network application versions |
| **Disable probes** | Probes test the health of a deployment. It is recommended to not disable them in standard scenarios |
| **Default JVM Options** | Default configuration options for the Java Virtual Machine (JVM) running the validator |
| **Top up** | Enables or disables the validator's automatic traffic purchase mechanism |
| **Min Top up interval** | Minimum amount of time that must pass between two automatic top-ups |
| **Target throughput** | Desired average traffic rate in bytes per second |
| **Contact point** | Where the validator can be reached for operational or administrative communication |
{% hint style="danger" %}
Do **not** set the Custom Authentication flag on — these instructions are for integrated Keycloak configuration. To use a custom identity provider instead, see [Create Validator with Custom Identity Provider](broken://pages/1d459ba5d7a4cfbd01fe511c1d03b5a8a26223cd).
{% endhint %}
{% endstep %}
{% step %}
**Cluster Participant Configuration**
Provide the following information:
* Node Identifier
* Enable or disable:
* Expose Ledger API
* Private JSON API
* Default JVM Options
More info about these fields
| Field | Description |
| ----------------------- | --------------------------------------------------------------- |
| **Node identifier** | A unique identifier for the validator node within the network |
| **Expose ledger API** | Opens up GRPC Ledger API to the outside |
| **Private JSON API** | Closes JSON Ledger API (open by default) |
| **Default JVM Options** | Default configuration options for the JVM running the validator |
**3.1 — Database Type**
{% tabs %}
{% tab title="PostgreSQL" %}
A PostgreSQL database will be created automatically.
* Database User
* Database Password
{% endtab %}
{% tab title="External Database" %}
Connect to an external database of your choice.
* Database User
* Database Password
* Host/IP address
* Port number
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
**Configure Resources**
Configure the necessary resources:
* Requested CPU
* CPU limit
* Requested memory
* Memory limit
* Replicas
More info about these fields
| Field | Description |
| -------------------- | -------------------------------------------------------------------- |
| **Requested CPU** | Minimum amount of CPU resources requested for the validator node |
| **CPU limit** | Maximum amount of CPU resources the validator node is allowed to use |
| **Requested memory** | Minimum amount of memory requested for the validator node |
| **Memory limit** | Maximum amount of memory the validator node is allowed to use |
| **Replicas** | Number of instances of the validator node to run |
{% hint style="info" %}
The pre-filled figures for resource configuration are a standard recommendation. Please adapt to your unique scenario if needed.
{% endhint %}
{% endstep %}
{% step %}
**Configure Environment Variables**
Override the values of the environment variables for the following components:
* Participant node
* Validator backend
* Canton Name Service UI
* Wallet UI
More info about these components
| Component | Description |
| -------------------------- | ----------------------------------------------------------------------------- |
| **Participant node** | The node that interacts with the Canton ledger on behalf of participants |
| **Validator backend** | The backend service responsible for validating and processing transactions |
| **Canton Name Service UI** | The UI for managing and viewing Canton network names and identifiers |
| **Wallet UI** | User interface for interacting with the wallet associated with your validator |
{% hint style="danger" %}
This is a very specific configuration. If you are not sure about this step, please contact IntellectEU.
{% endhint %}
{% endstep %}
{% step %}
**Summary**
Review your Validator configuration. Once you have confirmed the settings, click the **Confirm** button to finalize and proceed with the deployment.
{% endstep %}
{% step %}
**Create a Permanent Password in Keycloak**
To access the wallet UI, you must first define a new password in Keycloak.
1. Save the credentials displayed in the pop-up window.
2. Once your node is up and running, click on the last link containing the text `wallet-web-ui`, then click the link at the top left part of the screen.
3. A pop-up will ask you to re-authenticate. Close your session by clicking the **Log out** button.
4. Insert the temporary credentials saved in the previous step to authenticate yourself.
5. Define a new password and click **Submit**. You will be forwarded to the wallet UI console of your new Validator.
{% endstep %}
{% endstepper %}
***
### Identity and Access Management
As part of the validator provisioning process, Keycloak is set as the identity provider for authentication and authorization across the validator infrastructure. Each validator is assigned a dedicated user (`$VALIDATOR_NAME_walletuser`) within a specific realm (`validator`) for secure access to services.
{% hint style="danger" %}
We strongly recommend updating the password for this user after the initial setup to maintain security and reduce risks associated with default credentials.
{% endhint %}
#### Resetting the Wallet User Password in Keycloak
{% stepper %}
{% step %}
**Log in to the Keycloak admin console**
* **URL:** `https:///auth/admin/`
* Use an account with administrative access.
{% endstep %}
{% step %}
**Navigate to the validator realm**
From the top-left dropdown menu, select **validator**.
{% endstep %}
{% step %}
**Locate the wallet user**
In the left sidebar, click on **Users** and use the search field to find `$VALIDATOR_NAME_walletuser`.
{% endstep %}
{% step %}
**Access the user's credentials**
Click on the user to open their settings, then navigate to the **Credentials** tab.
{% endstep %}
{% step %}
**Reset the password**
* Enter a new password and confirm it.
* Toggle **Temporary** to **OFF** if you do not want the user to be forced to reset the password upon next login.
* Click **Reset Password**.
{% endstep %}
{% step %}
**Verify the changes**
Test the new password by authenticating the service or using the Keycloak test login page (if enabled).
{% hint style="warning" %}
Make sure to store the new password securely and update any dependent services or configuration files if needed.
{% endhint %}
{% endstep %}
{% endstepper %}
Additional Keycloak documentation resources
* [Keycloak Documentation – Managing Users](https://www.keycloak.org/docs/latest/server_admin/#admin-cli)
* [Keycloak Admin Console Guide](https://www.keycloak.org/docs/latest/server_admin/#admin-console)
* [Resetting Passwords via Admin Console](https://www.keycloak.org/docs/latest/server_admin/#resetting-passwords)
***
# Validator Management with Custom Identity Provider
This page explains how to create a Canton Validator using an external Identity Provider (IdP) instead of Catalyst's integrated Keycloak. In this mode, Catalyst does not create users or OAuth clients for you — all required OIDC clients and users must be set up in your IdP before creating the validator.
{% hint style="info" %}
The alternative to this approach is using an Integrated Keycloak that automates the process, as detailed in [Create Validator with Integrated Keycloak](broken://pages/09ab7fd8546b1d9c108768741af3810b3c02d11f).
{% endhint %}
### Prerequisites: Configure Your Identity Provider
Below you can find a brief overview of how to set up Clients and Users in your Identity Provider before setting up the Validator. For a full description of requirements, consult the [Canton Validator OIDC requirements](https://network.canton.global/validator_operator/validator_helm.html#oidc-provider-requirements) and navigate to the [External Identity Provider Configuration](/catalyx-blockchain-manager/canton-network/version-1.11/installation-instructions-canton/external-identity-provider-configuration-optional) page in the installation instructions:
{% content-ref url="/pages/u0ylfiYfGRM6KXWYoz7z" %}
[External Identity Provider Configuration (optional)](/catalyx-blockchain-manager/canton-network/version-1.11/installation-instructions-canton/external-identity-provider-configuration-optional)
{% endcontent-ref %}
{% hint style="info" %}
The sections on secrets and other Kubernetes configuration can be ignored — Catalyst creates them. You only need to set up clients and users beforehand.
{% endhint %}
#### Setting up Clients and Users in your Identity Provider
The following clients are used by a Validator node and must be configured with the proper flows in your Identity Provider:
| Validator Component | OpenID Flow | Fields required by Catalyst |
| ------------------- | ------------------------ | --------------------------- |
| Validator | Client Credentials Grant | Client Id, Client secret |
| Canton Name Service | Authorization Code | Client Id |
| Wallet | Authorization Code | Client Id |
{% hint style="warning" %}
It is recommended to allow all audiences for the clients during validator creation. These can be restricted later, once Catalyst has generated the required URLs.
{% endhint %}
Before setting up the validator, create a user in your Identity Provider and ensure this user has permission to use the OIDC clients created for the validator.
{% hint style="info" %}
This user will be mapped to the main Validator party and will receive rewards, which can be viewed from the Wallet.
{% endhint %}
Microsoft Entra ID — Creating Clients and Users for a New Validator
**Wallet Client**
Create an App Registration for the Wallet:
* **Platform:** Single-Page Application
* No client secret needed
After creating the validator, obtain the Wallet URL and add it to the Wallet App Registration under **Authentication**:
* **Redirect URI:** `https://wallet-validator-.`
* **CORS origin:** `https://wallet-validator-.`
* **Front-channel logout URL:** `https://wallet-validator-.`
Under **Expose an API**:
* Accept the default Application ID URI: `api://`
* Add a scope named `access`, who can consent: Admins and users
{% hint style="info" %}
Redirect URIs, CORS origins, and the logout URL must be added after validator creation — the URLs are only known at that point.
{% endhint %}
**Ledger Client**
Create an App Registration for the ledger:
* **Name:** e.g. `canton-ledger`
* No platform or redirect URI needed
* Go to **Certificates & Secrets → New client secret** — save the value immediately
* Go to **Expose an API → Add** Application ID URI — accept the default `api://`
* Click **Add a scope**:
* **Scope name:** `access`
* **Who can consent:** Admins and users
* **Admin consent display name:** `Ledger API access`
* **Admin consent description:** `Ledger API access`
Then grant the Wallet registration access to the Ledger API:
**Wallet App Registration → API permissions → Add a permission → My APIs → \[ledger app] → access → Add permissions → Grant admin consent**
| Client | Platform Type | Grant Types | Has Client Secret |
| ------ | ------------------------------ | ---------------------------------- | ----------------- |
| Wallet | Single-Page Application | Authorization Code + Refresh Token | No |
| Ledger | None (Client Credentials only) | Client Credentials | Yes |
**User Setup**
Create a new user in **Entra ID → Users → New user → Create new user**.
Assign the user to both the Wallet and CNS Enterprise Applications via **Enterprise Applications → \[app] → Users and Groups → Add user/group**.
**Fields Required by IntellectEU**
After completing the setup, provide the following values to IntellectEU:
| Field | Where to find it |
| ---------------------------- | ------------------------------------------------------------------------------------------ |
| Ledger Client Application ID | App Registrations → `canton-ledger` → Overview → Application (client) ID |
| Ledger Client Object ID | App Registrations → `canton-ledger` → Overview → Object ID |
| Ledger Client Secret | App Registrations → `canton-ledger` → Certificates & Secrets → value saved during creation |
| Wallet UI Client ID | App Registrations → \[wallet app] → Overview → Application (client) ID |
| Wallet User Username | Entra ID → Users → \[wallet user] → User principal name |
| Wallet User Password | Set during user creation above |
***
### Set Up a Validator
To set up a Validator, go to the **Validators** tab and click the **Set up validator** button.
{% stepper %}
{% step %}
**Main Settings Configuration**
Provide the following information:
* Sponsor SV Name
* Name
* Onboard secret
* Image tag
* Image repo
* Image pull secret
* Scan address
* SV sponsor address
* Party hint
* Migration id
More info about these fields
| Field | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Sponsor SV Name** | The name of the Super Validator that sponsored you to join the network |
| **Name** | The identifier or label for the validator node |
| **Onboard secret** | Passphrase obtained from the super validator in order to join the network |
| **Image tag** | The specific version or tag of the container image to be used |
| **Image repo** | The repository where the container image is stored |
| **Image pull secret** | Credentials required to pull the container image from a private registry |
| **Scan address** | The address used for scanning and retrieving validator-related data |
| **SV Sponsor Address** | URL of the SV app of the super validator sponsoring you (starts with `https://sv.sv-N`) |
| **Party hint** | Used as a prefix for the Party ID. Format: `--`, e.g., `myCompany-myWallet-1` |
| **Migration id** | Used to track database migrations. Starts at `0` and increments by 1 with each migration |
{% hint style="info" %}
An onboarding secret should be requested from your sponsoring SV in order to join the network.
{% endhint %}
{% hint style="warning" %}
Only turn on the **Restore participant identities** toggle if you want to restore a validator from an Identity Dump.
{% endhint %}
{% endstep %}
{% step %}
**Cluster Configuration**
**2.1 — Enable or disable:**
* Disable wallet
* Fail on app version mismatch
* Disable probes
**2.2 — Fill in the fields:**
* Default JVM Options
* Top up: Enable, Min Top up interval, Target throughput, Contact point
{% hint style="danger" %}
Make sure to set the **Custom Authentication** flag **ON**.
{% endhint %}
**2.3 — Fill in the custom authentication fields:**
* CNS Client Id
* Wallet Client Id
* Ledger API Client Id
* Ledger API Client Secret
* Ledger API User
* Wallet User
* Audience
More info about custom authentication fields
| Field | Description |
| ---------------------------- | ------------------------------------------------------------------------- |
| **CNS Client Id** | Client for the Canton Name Service |
| **Wallet Client Id** | Client for the Wallet application |
| **Ledger API Client Id** | Client for the Validator |
| **Ledger API Client Secret** | Secret part of the Client Credentials Grant Flow for the Validator client |
| **Ledger API User** | User of the components described above |
| **Wallet User** | User that will access the wallet application and receive rewards |
| **Audience** | Audience claim expected by the clients |
{% endstep %}
{% step %}
**Cluster Participant Configuration**
Provide the following information:
* Node Identifier
* Enable or disable: Expose Ledger API, Private JSON API
* Default JVM Options
**3.1 — Database Type**
{% tabs %}
{% tab title="PostgreSQL" %}
A PostgreSQL database will be created automatically.
* Database User
* Database Password
{% endtab %}
{% tab title="External Database" %}
Connect to an external database.
* Database User
* Database Password
* Host/IP address
* Port number
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
**Configure Resources**
* Requested CPU
* CPU limit
* Requested memory
* Memory limit
* Replicas
{% hint style="info" %}
The pre-filled figures for resource configuration are a standard recommendation. Please adapt to your unique scenario if needed.
{% endhint %}
{% endstep %}
{% step %}
**Configure Environment Variables**
Override the values of the environment variables for:
* Participant node
* Validator backend
* Canton Name Service UI
* Wallet UI
{% hint style="danger" %}
This is a very specific configuration. If you are not sure about this step, please contact IntellectEU.
{% endhint %}
{% endstep %}
{% step %}
**Summary**
Review your Validator configuration. Once confirmed, click the **Confirm** button to finalize and proceed with the deployment.
{% endstep %}
{% endstepper %}
***
### Identity and Access Management
In deployments where an external Identity Provider is used, your organization is responsible for managing user credentials and access controls for the validator infrastructure.
{% hint style="danger" %}
We strongly recommend updating the password for this user account after the initial setup to ensure that access remains secure and unique.
{% endhint %}
#### Resetting the Wallet User Password in Your Identity Provider
To change the password for the wallet user, refer to the official documentation for your IdP. Typical steps include:
1. Log into your Identity Provider's admin portal.
2. Locate the user account associated with the validator (e.g., `$VALIDATOR_NAME_walletuser`).
3. Initiate a password reset or manual update from the user management section.
4. Disable any temporary password flags if you want to use the new password directly.
5. Update any validator configuration files or services that use this credential.
{% hint style="danger" %}
Always ensure that the new credentials are stored securely and are reflected across all dependent components.
{% endhint %}
{% hint style="warning" %}
If your IdP integrates with federation or SSO, ensure that policies and password propagation are correctly applied.
{% endhint %}
Common IdP documentation resources
* [Azure AD User Management](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/)
* [Okta Admin Guide](https://help.okta.com/)
* [Auth0 Password Reset](https://auth0.com/docs/authenticate/login/password-reset)
***
# Validator Backups and Identity Dumps
How to configure scheduled backups and identity dumps for validator nodes in CatalyX Blockchain Manager.
## Overview
This guide explains how to configure scheduled backups and identity dumps for validator nodes in CatalyX Blockchain Manager.
Scheduled backups help ensure:
* Faster recovery after failures
* Protection against data loss
* Disaster recovery readiness
* Validator identity preservation
This document covers: validator database backups, validator identity dumps (IDDumps), restore procedures, and backup strategy recommendations.
***
## Backup Types Overview
| Backup Type | Includes | Does NOT Include | Recommended Usage |
| ------------- | -------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------- |
| IDDump | Cryptographic keys and validator identity material | Database contents, ledger state, transaction history | Identity recovery and validator restoration |
| PVC/PV Backup | Validator and participant database state | Cryptographic keys and secrets | Stateful workload recovery |
| S3 Backup | Database dumps and snapshots stored externally | Runtime state and identities unless explicitly exported | Long-term disaster recovery |
{% hint style="warning" %}
IDDumps alone cannot restore ledger/database state. Database backups alone cannot restore validator identity. Full disaster recovery requires **both** backup types.
{% endhint %}
***
## Part 1 — Schedule Validator Backups
### Prerequisites
Before enabling scheduled backups:
* Ensure sufficient cluster storage is available
* Verify backup retention requirements
* Confirm the validator is operational
{% hint style="info" %}
If IntellectEU manages the cluster, backup snapshotting may already be enabled. Verify available resources before configuring additional scheduled backups.
{% endhint %}
### Create a Backup Schedule
{% stepper %}
{% step %}
#### Open Validator Backups
Navigate to the **Validators** page, open the target validator, locate the **Backups** section, and click **Schedule**.
{% endstep %}
{% step %}
#### Configure the Schedule
Provide the following settings:
**Cron Expression** — defines how often backups run using standard Unix cron syntax.
| Schedule | Cron |
| --------------------- | ------------- |
| Every day at midnight | `0 0 * * *` |
| Every 6 hours | `0 */6 * * *` |
| Every Sunday at 02:00 | `0 2 * * 0` |
**Max Backup Number** — defines how many backups are retained. When the limit is exceeded, older backups are automatically deleted.
* Development: 3–5 backups
* Production: 7–30 backups
{% endstep %}
{% step %}
#### Confirm the Schedule
Click **Confirm** to activate the backup schedule. Once configured, backups will run automatically and the retention policy will be enforced.
{% endstep %}
{% endstepper %}
### View Existing Backups
To view backup history, navigate to **Validators → Backups → Show history**. The history page displays backup timestamps, status, and available restore actions.
***
## 1.1 Restore Validator from Backup
{% stepper %}
{% step %}
#### Open Backup History
Navigate to **Validators → Backups → Show history**.
{% endstep %}
{% step %}
#### Start the Restore
Open the **Actions** menu for the desired backup and select **Restore**. A restore status indicator will appear showing start time, current progress, and restore status.
{% endstep %}
{% step %}
#### Wait for Completion
When complete, the restore status changes to **Completed**.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
Restoring from a database backup restores database state only. Validator identities and cryptographic material are **not** restored by database backups.
{% endhint %}
***
## Part 2 — Schedule Validator Identity Dumps (IDDumps)
### What is an Identity Dump?
An Identity Dump (IDDump) contains the validator's cryptographic keys, identity material, and validator access credentials.
IDDumps are required to recover validator ownership, restore wallet access, rejoin the network after failures, and recover balances. They do **not** contain database contents, transaction history, or ledger state.
### Configure an Identity Dump Schedule
{% stepper %}
{% step %}
#### Open Identity Backup Settings
Navigate to the **Validator details** page, open the **Management** section, locate **Identity dumps**, and click **Schedule**.
{% endstep %}
{% step %}
#### Configure the Schedule
**Cron Expression** — defines how frequently IDDumps are created. Recommended: daily for production validators, weekly for development environments.
**Max Dump Number** — defines how many IDDumps are retained. Older dumps are automatically removed after reaching the configured limit.
* Production: minimum 14 dumps
* Critical infrastructure: 30+ dumps
{% endstep %}
{% step %}
#### Activate the Schedule
Click **Confirm**. After configuration, the next scheduled execution time is displayed along with schedule management options.
{% endstep %}
{% endstepper %}
### View Existing Identity Dumps
To list available IDDumps, open **Validator details → Identity Backups → Show list**. The list displays dump names, creation timestamps, and available actions.
***
## 2.1 Restore Validator from Identity Dump
### Important Notes
When restoring a validator:
* Reuse the same validator configuration values
* Keep Keycloak users and clients
* Preserve onboarding secrets
* Use the same party hint and node identifier
The restored validator receives a new participant hash, reuses existing cryptographic keys, and regains access to balances and network identity.
### Restore Procedure
{% stepper %}
{% step %}
#### Create an Identity Dump
Create an IDDump from the existing validator before deletion.
{% endstep %}
{% step %}
#### Delete the Validator Resource
Delete the validator resource only. Do **not** remove Keycloak users, Keycloak clients, or Kubernetes secrets.
{% endstep %}
{% step %}
#### Recreate the Validator
Create the validator again using the same onboarding secret, party hint, node identifier, and migration configuration. Include the following restore configuration:
```json
"participantIdentitiesDumpImport": {
"identitiesSecretName": "",
"newParticipantIdentifier": ""
},
"migrateValidatorParty": true
```
{% hint style="warning" %}
Disable auto-init during restore and choose a new participant identifier.
{% endhint %}
{% endstep %}
{% endstepper %}
### Verify Successful Restore
After restore, open the validator wallet UI and log in using the existing Keycloak wallet user. Confirm that wallet access works, balances are visible, and the validator is operational.
{% hint style="info" %}
Use an incognito browser session to avoid Keycloak session conflicts with the CatalyX UI.
{% endhint %}
***
## Best Practices
Use **both** scheduled database backups and scheduled identity dumps to ensure complete disaster recovery coverage.
### Recommended Backup Frequency
| Environment | Database Backup | IDDump |
| ----------- | --------------- | ------ |
| Development | Daily | Weekly |
| Staging | Every 12h | Daily |
| Production | Every 6h | Daily |
### Storage Recommendations
As of **v1.11.7**, backup volume sizing is automatic. The CAT-BM Operator calculates the required backup volume size using the formula:
```
backup volume size = number of backups × database storage size
```
The volume is automatically resized on the next scheduled backup run when the database storage size increases. Note that Kubernetes PVCs can only increase in size — reducing the **Max Backup Number** setting does not shrink the backup volume.
{% hint style="info" %}
If IntellectEU manages your cluster, snapshot-based backup may already be enabled. Verify available storage capacity before configuring additional scheduled backups alongside existing snapshots.
{% endhint %}
Additional recommendations:
* Backup retention should align with your compliance requirements
* Configure off-cluster backup export for disaster recovery
* For production environments, allocate headroom beyond the calculated minimum to account for database growth between backup runs
### Never Force-Delete a Database Pod
Domain, participant, and validator databases run as stateful Kubernetes workloads, each backed by its own storage. Deleting a database pod is sometimes necessary — for maintenance, node draining, or troubleshooting — but how it's done matters.
{% hint style="danger" %}
Never force-delete a database pod (`kubectl delete pod --force --grace-period=0`). A force-delete does not wait for the pod to fully terminate, and a replacement can be scheduled while the original is still shutting down — leaving two processes writing to the same database storage at once. This can corrupt the database, and the damage isn't always visible right away: it can go undetected until the affected data is read.
{% endhint %}
If a pod needs to be removed, delete it normally and allow it to terminate gracefully. If a pod is stuck terminating, contact CatalyX support before forcing removal.
{% content-ref url="/pages/n4QmocInDV7pxmDuH8fz" %}
[Support Center](/support-center)
{% endcontent-ref %}
***
### Reduce Restart-Related Corruption Risk (v1.11.17+)
As of **v1.11.17**, validator, participant, and domain databases can additionally run in a way that guards against the failure mode described above, preventing data corruption during pod restarts or configuration changes — even when a pod isn't cleanly terminated.
This is gated by the `CANTON_OPERATOR_POSTGRES_USESTATEFULSET` environment variable, set under `spec.envVars` (see [Environment Variables](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/validator-custom-resource-definition#environment-variables)).
{% hint style="warning" %}
Enabling this variable triggers a database server restart, incurring roughly 1 minute of downtime.
{% endhint %}
***
### Use an External Database for Production
For production domains, participants, and validators, we recommend configuring an **External** database (see the storage type options on the [Domains](/catalyx-blockchain-manager/canton-network/version-1.11/network-and-node-management/domains) and [Participants](/catalyx-blockchain-manager/canton-network/version-1.11/network-and-node-management/participants) pages) instead of the in-cluster provisioned PostgreSQL option. An externally managed database service (e.g. AWS RDS) moves durability, backup, and failover responsibility to a managed service, reducing the operational risk of running the database as an in-cluster workload.
***
## Troubleshooting
| Issue | Cause | Resolution |
| ----------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Restore completes but wallet inaccessible | Missing IDDump | Restore identities separately |
| Validator cannot rejoin network | Wrong participant identifier | Use correct migration settings |
| Login fails after restore | Keycloak users removed | Preserve original users and clients |
| Backup creation fails | Insufficient storage on initial setup, or automatic volume resize not yet triggered | On v1.11.7+, the Operator resizes the backup volume automatically on the next scheduled run. If the issue persists on first setup, ensure sufficient cluster storage is available for the initial volume allocation. |
| Database pod stuck terminating | Pod not fully released before a replacement is scheduled | Do not force-delete (`--force --grace-period=0`) — this risks two processes writing to the same storage. Wait for graceful termination, or contact CatalyX support. |
# Data Retention & Pruning Policy
How CatalyX Blockchain Manager handles data retention, ledger pruning, and backup strategy for validator and participant infrastructure.
## Overview
CatalyX Blockchain Manager provides automated backup, recovery, data retention, and pruning capabilities to help organizations protect their blockchain infrastructure, optimize storage usage, and meet operational and regulatory requirements.
These capabilities are designed to:
* Protect validator and participant data through scheduled backups
* Preserve validator identities and cryptographic material
* Enable disaster recovery
* Optimize storage by removing obsolete data
* Maintain security and audit logs
* Support enterprise data lifecycle management
Although these concepts are closely related, they serve different purposes:
| Feature | Purpose |
| ------------------ | ---------------------------------------------------------------------- |
| **Data Retention** | Defines how long operational logs and audit information are preserved. |
| **Backups** | Protect validator and ledger data for recovery. |
| **Identity Dumps** | Preserve validator identities and cryptographic material. |
| **Pruning** | Removes obsolete ledger data that is no longer required. |
{% hint style="warning" %}
A complete disaster recovery strategy requires **both** scheduled database backups and scheduled Identity Dumps (IDDumps). These backup types protect different components of a validator and cannot replace one another.
{% endhint %}
***
## Data Retention
### Security and Audit Logging
CatalyX Blockchain Manager centralizes security and operational logs using Azure Log Analytics.
Default log retention periods:
| Environment | Log Retention |
| -------------------- | ------------- |
| Mainnet (Production) | 30 days |
| Devnet / Testnet | 7 days |
These logs support:
* Security investigations
* Operational troubleshooting
* Compliance audits
* Incident response
* Infrastructure monitoring
The centralized logging solution includes:
* Azure Activity Logs
* Kubernetes audit logs
* Kubernetes API server logs
* PostgreSQL audit logs (pgaudit)
* Network flow logs
* Microsoft Sentinel integration
* Microsoft Defender integration
### Infrastructure Audit Trail
CatalyX Blockchain Manager maintains an audit trail for infrastructure and operational activities, including:
* Resource creation and deletion
* Infrastructure configuration changes
* Azure role assignments
* Policy modifications
* Kubernetes API activity
* Database authentication
* Database query execution
This information supports operational monitoring, forensic investigations, and compliance reporting.
***
## Backup Strategy
Scheduled backups and Identity Dumps are the foundation of CatalyX's disaster recovery approach for validator infrastructure.
| Backup Type | Includes | Does Not Include | Recommended Usage |
| ------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------- |
| Identity Dump (IDDump) | Validator cryptographic keys, validator identity, wallet credentials | Database contents, ledger state, transaction history | Validator identity recovery |
| Database Backup (PVC/PV Backup) | Validator database, participant database, ledger state | Validator identities and cryptographic keys | Operational recovery |
| External Storage Backup (S3 or other supported storage) | Database dumps and snapshots | Runtime state and identities unless explicitly exported | Long-term disaster recovery |
{% hint style="info" %}
For scheduling database backups and Identity Dumps, viewing backup history, and restoring a validator, see [Validator Backups and Identity Dumps](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/identity-backup-and-recovery). That page covers the full configuration and restore workflow — this page focuses on retention strategy, pruning, and compliance considerations.
{% endhint %}
### Recommended Backup Schedule
| Environment | Database Backup | Identity Dump |
| ----------- | --------------- | ------------- |
| Development | Daily | Weekly |
| Staging | Every 12 hours | Daily |
| Production | Every 6 hours | Daily |
Recommended retention values are documented in [Validator Backups and Identity Dumps](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/identity-backup-and-recovery#best-practices). Organizations should ultimately configure retention according to their own operational and compliance requirements.
***
## Pruning
### What is Pruning?
Pruning permanently removes obsolete ledger data that is no longer required for normal ledger operation.
Unlike backups, pruning is intended to optimize storage rather than provide recovery.
Pruning helps:
* Reduce database size
* Improve storage efficiency
* Remove obsolete ledger history
* Support organizational data lifecycle policies
* Assist with regulatory requirements such as GDPR "right to erasure," where applicable
{% hint style="info" %}
Pruning does not affect active ledger state.
{% endhint %}
### Supported Pruning Types
CatalyX Blockchain Manager supports scheduled pruning for:
* Domain nodes
* Participant nodes
{% hint style="warning" %}
Pruning is supported only for Enterprise deployments using PostgreSQL.
{% endhint %}
### Configuring Pruning
Pruning schedules are configured directly from the **Domain** or **Participant** management pages (see [Domains](/catalyx-blockchain-manager/canton-network/version-1.11/network-and-node-management/domains) and [Participants](/catalyx-blockchain-manager/canton-network/version-1.11/network-and-node-management/participants)).
| Parameter | Description |
| ---------------- | ------------------------------------------------------------------------ |
| Cron Expression | Defines how frequently pruning is executed |
| Retention Time | Specifies how long data is retained before becoming eligible for pruning |
| Maximum Duration | Maximum execution time allowed for a pruning operation |
Example configuration (for demonstration purposes only — production environments should set retention according to operational and regulatory requirements):
| Setting | Example Value |
| ---------------- | ------------- |
| Cron Expression | `*/1 * * * *` |
| Retention Time | `1 second` |
| Maximum Duration | `20 seconds` |
The same schedule can also be set at the CRD level. See [Validator CRD User Guide](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/validator-crd-user-guide) for the `scheduledPrune` spec fields.
### Monitoring Pruning
After configuring a pruning schedule:
1. Wait for the scheduled execution.
2. Refresh the Pruning Schedule page.
3. Verify that pruning completed successfully.
The UI displays:
* Last execution
* Pruning status
* Pruned records
### Backup Pruning vs. Ledger Pruning
These are different operations and should not be confused.
| Backup Pruning | Ledger Pruning |
| -------------------------------------- | -------------------------------- |
| Removes old backup files | Removes obsolete ledger data |
| Controlled by backup retention setting | Controlled by pruning schedule |
| Frees backup storage | Reduces database size |
| Does not affect ledger state | Does not affect active contracts |
***
## Best Practices
For production deployments, IntellectEU recommends:
* Schedule regular automated database backups.
* Schedule regular Identity Dumps.
* Store backups in external storage whenever possible.
* Periodically validate restore procedures.
* Configure pruning only after defining a suitable retention policy.
* Monitor scheduled backup and pruning jobs.
* Review backup retention periodically to balance recovery objectives and storage utilization.
***
## Compliance Considerations
CatalyX Blockchain Manager provides capabilities that support organizational compliance requirements through:
* Configurable backup retention
* Scheduled pruning
* Security logging
* Infrastructure audit trails
* Validator identity preservation
* Disaster recovery mechanisms
{% hint style="warning" %}
Organizations remain responsible for defining retention policies that satisfy their own regulatory and business requirements.
{% endhint %}
***
## Frequently Asked Questions
What is the difference between a Database Backup and an Identity Dump?
A Database Backup protects the validator database and ledger state. An Identity Dump protects validator identity, cryptographic keys, and wallet credentials. Both are required for complete disaster recovery.
How long are security logs retained?
Mainnet (Production): 30 days. Devnet/Testnet: 7 days.
Can I configure pruning schedules?
Yes. Pruning schedules allow administrators to define the execution schedule, retention period, and maximum execution duration, either from the Domain/Participant management pages or via the CRD.
Does pruning delete active ledger data?
No. Pruning removes only obsolete ledger data that is no longer required for normal ledger operation.
Does pruning affect backups?
No. Ledger pruning and backup retention are independent features.
Can I restore a validator using only an Identity Dump, or only a database backup?
No, in either case. Identity Dumps restore validator identity only — database state must be restored separately. Database backups restore ledger state but do not restore validator identity, cryptographic keys, or wallet credentials. See [Validator Backups and Identity Dumps](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/identity-backup-and-recovery) for the full restore procedure.
Does pruning require downtime?
Pruning is designed as a scheduled maintenance operation and does not require planned validator downtime under normal operating conditions.
# DAR management
How to upload and deploy DAR files in CatalyX Blockchain Manager.
## Overview
DAR (DAML Archive) files contain compiled DAML application packages. They must be uploaded to a participant before any DAML templates or ledger workflows from that package can be used.
DAR files are required to:
* deploy DAML applications
* enable ledger workflows
* install application templates on participants
* support CPM, billing, Tradecraft, and other Canton applications
DAR files use the `.dar` extension. Examples: `cpm-.dar`, `ieu-billing-.dar`, `canton-swap-.dar`.
***
## Upload Flow Overview
Uploading a DAR in CatalyX is typically a two-step process:
| Step | Description |
| ---------- | ------------------------------------------------ |
| **Step 1** | Upload the DAR to Collections |
| **Step 2** | Deploy the DAR from Collections to a Participant |
Storing DARs in Collections first allows packages to be reused across multiple participants and environments without re-uploading the source file each time.
{% hint style="info" %}
You can also upload a DAR directly to a participant without going through Collections. See [Part 2](#part-2--upload-dar-directly-to-a-participant) below.
{% endhint %}
***
## Part 1 — Upload DAR to Collections
Collections are reusable artifact repositories inside CatalyX. They support both DAR packages and UI packages. Once uploaded, a DAR in Collections can be deployed to any participant or referenced by applications.
{% hint style="info" %}
For a full overview of Collections, see the [Collections](/catalyx-blockchain-manager/canton-network/version-1.11/network-and-node-management/collections) page.
{% endhint %}
{% stepper %}
{% step %}
**Navigate to Collections**
Open CatalyX Blockchain Manager and navigate to **Collections** from the left navigation menu. The page contains two sections: **DAR Collections** and **UI Collections**.
{% endstep %}
{% step %}
**Open the Upload Dialog**
In the **DAR Collections** section, click **Upload DAR File**.
{% endstep %}
{% step %}
**Select the DAR File**
Choose the `.dar` file from your local machine (e.g. `cpm-0.2.1.dar`, `ieu-billing-1.0.0.dar`).
{% endstep %}
{% step %}
**Confirm the Upload**
After upload, the DAR appears in the DAR Collections table with the following details:
* Package name
* File size
* Available actions: **Deploy**, **Download**, **Remove**
The package is now available for deployment to any participant.
{% endstep %}
{% endstepper %}
***
## Part 2 — Upload DAR to a Participant
{% stepper %}
{% step %}
**Navigate to the Participant**
Open **Participants** from the left navigation and select the target participant.
{% endstep %}
{% step %}
**Open the DARs Tab**
Inside the participant details page, open the **DARs** tab and click **Upload DAR**.
{% endstep %}
{% step %}
**Select DAR Files**
Choose one or multiple `.dar` files. Multi-file upload is supported.
After upload:
* The package appears in the participant DARs list
* The package hash becomes visible
* DAML templates from the package become available on the ledger
{% endstep %}
{% endstepper %}
***
## UI Package Uploads
UI packages provide frontend applications exposed through HTTPS. They are uploaded to **Collections → UI Collections** separately from DAR files.
UI packages must:
* be uploaded as `.zip` files
* contain a single root directory
* include an `index.html` at the root
{% stepper %}
{% step %}
**Navigate to UI Collections**
Go to **Collections → UI Collections**.
{% endstep %}
{% step %}
**Upload the UI File**
Click **Upload UI File** and select the `.zip` package.
After upload, the package appears in UI Collections and becomes available for deployment.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
For a full overview of UI Collections and how to deploy UI packages as applications, see the [Collections](/catalyx-blockchain-manager/canton-network/version-1.11/network-and-node-management/collections) page.
{% endhint %}
***
## Application-Specific DAR Deployments
### CPM
{% stepper %}
{% step %}
Download `cpm-${version}.dar`
{% endstep %}
{% step %}
Upload the DAR to the target participant
{% endstep %}
{% step %}
Verify the DAR is visible in the participant DAR list
{% endstep %}
{% endstepper %}
### Billing Subscriber
{% stepper %}
{% step %}
Download `ieu-billing-${version}.dar`
{% endstep %}
{% step %}
Upload the DAR to the target participant
{% endstep %}
{% step %}
Confirm deployment completed successfully
{% endstep %}
{% endstepper %}
### Tradecraft (CantonSwap)
{% stepper %}
{% step %}
Download `canton-swap-${version}.dar`
{% endstep %}
{% step %}
Upload the DAR to the participant
{% endstep %}
{% step %}
Verify the package is visible in the DAR list
{% endstep %}
{% endstepper %}
***
## Verification Checklist
| Validation | Expected Result |
| ------------------------------- | ---------------------------------------- |
| DAR visible in Collections | Package appears in DAR Collections table |
| DAR uploaded to participant | Package visible under Participant DARs |
| Package hash generated | Hash visible in DAR list |
| Application templates available | DAML workflows accessible on the ledger |
| No upload errors | Upload completed without errors |
***
## Troubleshooting
| Issue | Cause | Resolution |
| ---------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
| DAR upload fails | Invalid file format | Verify the file uses the `.dar` extension |
| DAR not visible on participant | Upload incomplete or failed | Re-upload the package |
| Templates unavailable after upload | Package uploaded to Collections but not deployed to participant | Upload the DAR to the participant (Part 2) |
| UI deployment fails | Invalid ZIP structure | Ensure the ZIP contains a single root folder with `index.html` |
| Upload button disabled | Insufficient permissions | Verify your user has the required access rights |
***
## Best Practices
* Store reusable DARs in Collections so they can be deployed to multiple participants without re-uploading
* Use versioned naming conventions (e.g. `cpm-0.2.1.dar`) to distinguish package versions
* Keep older package versions in Collections for rollback purposes
* Verify package hashes after deployment
* Upload all required DARs before deploying dependent applications
* Keep production and development packages separate
# Validator Custom Resource Definition
This page provides an overview of the Validator Custom Resource Definition (CRD) used by Catalyst Blockchain Manager to deploy and manage Canton validators using Kubernetes. It describes the structure of the CRD and explains how each validator component is defined and configured.
{% hint style="info" %}
A Custom Resource Definition (CRD) in Kubernetes is a way to extend the Kubernetes API by defining new, custom object types, allowing you to manage application-specific data.
{% endhint %}
### Structure of the Specification
The CRD specification defines each validator component separately.
| Component | CRD Location |
| -------------------- | --------------------------------------- |
| **Validator** (core) | Top level of the specification |
| **ANS/CNS UI** | `spec.applicationCantonNameServer.spec` |
| **Wallet UI** | `spec.walletUI.spec` |
| **Participant Node** | `spec.participant.spec` |
#### Provisioned Postgres Database
The PostgreSQL database provisioned for the validator is not explicitly represented in the CRD specification. To increase the database storage size (decreases are ignored), use:
```
spec.storageSize
```
### Modifying Component Specifications
#### Environment Variables
For all components, environment variables are defined under `spec.envVars`. They follow the same structure and format used in Kubernetes Pods and Deployments.
#### Resources
Each component has a resource specification:
```yaml
resources:
cpuLimit: '2'
cpuRequested: '1'
imagePullSecret: intellecteu-gitlab-access
memoryLimit: 2Gi
memoryRequested: 1Gi
replicas: 1
```
| Field | Description |
| ----------------- | ---------------------------------------------- |
| `cpuLimit` | Maximum CPU allocation |
| `cpuRequested` | Minimum CPU allocation |
| `memoryLimit` | Maximum memory allocation |
| `memoryRequested` | Minimum memory allocation |
| `replicas` | Number of instances (can be set to `0` or `1`) |
To scale down a validator, set the `replicas` field to `0` for all components.
### Example CRD
Full example Validator CRD YAML
```yaml
apiVersion: catalyst.manager.canton/v1
kind: Validator
metadata:
name: validator1st
namespace: canton-dev
spec:
application:
spec:
domain: participant-validator1st
resources:
cpuLimit: '2'
cpuRequested: '1'
imagePullSecret: intellecteu-gitlab-access
memoryLimit: 2Gi
memoryRequested: 1Gi
replicas: 1
type: backend
validatorParent: validator1st
applicationCantonNameServer:
spec:
domain: cns-validator1st
image: >-
digitalasset-canton-network-docker.jfrog.io/digitalasset/ans-web-ui:0.3.15
resources:
cpuLimit: '1'
cpuRequested: '0.1'
imagePullSecret: intellecteu-gitlab-access
memoryLimit: 1536Mi
memoryRequested: 240Mi
replicas: 1
type: ui
applicationWallet:
spec:
domain: wallet-validator1st
image: >-
digitalasset-canton-network-docker.jfrog.io/digitalasset/wallet-web-ui:0.3.15
resources:
cpuLimit: '1'
cpuRequested: '0.1'
imagePullSecret: intellecteu-gitlab-access
memoryLimit: 1536Mi
memoryRequested: 240Mi
replicas: 1
type: ui
customAuth: false
disabledWallet: false
enableKms: false # master flag for KMS; the KMS fields live under participant.spec
image: digitalasset-canton-network-docker.jfrog.io/digitalasset/validator-app:0.3.15
imageRepo: digitalasset-canton-network-docker.jfrog.io/digitalasset
imageTag: 0.3.15
migrationId: '0'
migrationMigrating: false
participant:
spec:
adminPort: '5002'
auth: true
authProvider: keycloak
image: >-
digitalasset-canton-network-docker.jfrog.io/digitalasset/canton-participant:0.3.15
jsonapi: false
ledgerPort: '5001'
# --- KMS (only applied when spec.enableKms is true) ---
serviceAccount: catbm-aws-kms # AWS/GCP: K8s ServiceAccount (IRSA / workload identity)
kmsValue: '{ type = "aws", region = "eu-west-1", audit-logging = true }' # HOCON provider config
kmsAzureVaultSecretName: '' # Azure only: K8s Secret with tenant-id, client-id, client-secret
overrideImage: '' # Azure only: Azure-KMS driver participant image (matches splice image)
logLevel: INFO
resources:
cpuLimit: '2'
cpuRequested: '1'
imagePullSecret: intellecteu-gitlab-access # Azure KMS: set to pull secret for the override (driver) image
memoryLimit: 2Gi
memoryRequested: 1Gi
replicas: 1
storageType: Shared Postgres
resources:
cpuLimit: '2'
cpuRequested: '1'
imagePullSecret: intellecteu-gitlab-access
memoryLimit: 2Gi
memoryRequested: 1Gi
replicas: 1
storageSize: 20Gi
```
### KMS Fields
The following fields control KMS for a validator. `enableKms` is immutable after creation; all other KMS fields are also immutable **except `overrideImage`**, which remains editable.
| Field | Location | Notes |
| -------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------- |
| `enableKms` | `spec` | Master flag; immutable after creation |
| `participant.spec.kmsValue` | `spec.participant.spec` | HOCON provider config (AWS / GCP / Azure) |
| `participant.spec.serviceAccount` | `spec.participant.spec` | AWS/GCP ServiceAccount; not used for Azure |
| `participant.spec.kmsAzureVaultSecretName` | `spec.participant.spec` | Azure only; Secret with `tenant-id` / `client-id` / `client-secret` |
| `participant.spec.overrideImage` | `spec.participant.spec` | Azure driver image; the only KMS-adjacent field editable post-creation |
| `participant.spec.resources.imagePullSecret` | `spec.participant.spec.resources` | Azure only; pull secret for the override (driver) image |
When `enableKms` is `true`: `kmsValue` is required, plus either `serviceAccount` (AWS/GCP) or `kmsAzureVaultSecretName` (Azure).
***
# Validator CRD User Guide
Catalyst uses the operator pattern with Custom Resource Definitions. The same operations available in the Catalyst GUI can also be performed directly on Kubernetes with access to the cluster.
### Creating a Validator
Full creation example (Kubernetes YAML)
```yaml
apiVersion: v1
kind: Secret
metadata:
namespace: canton-dev
name: database-validator-dev-foo
data:
user: "YWRtaW4="
password: "YWRtaW4="
---
apiVersion: v1
kind: Secret
metadata:
namespace: canton-dev
name: cn-app-validator-dev-foo-onboarding-validator
data:
secret: ""
---
apiVersion: v1
kind: Secret
metadata:
namespace: canton-dev
name: cn-app-validator-dev-foo-cns-ui-auth
data:
url: ""
clientId: ""
---
apiVersion: v1
kind: Secret
metadata:
namespace: canton-dev
name: cn-app-validator-dev-foo-wallet-ui-auth
data:
url: ""
clientId: ""
username: ""
---
apiVersion: v1
kind: Secret
metadata:
namespace: canton-dev
name: cn-app-validator-dev-foo-ledger-api-auth
data:
client-id: ""
client-secret: ""
ledger-api-user: ""
url: ""
---
apiVersion: catalyst.manager.canton/v1
kind: Validator
metadata:
name: validator-dev-foo
namespace: canton-dev
spec:
config:
scanAddress: "https://scan.sv-1.dev.global.canton.network.sync.global"
svSponsorAddress: "https://sv.sv-1.dev.global.canton.network.sync.global"
defaultJvmOptions: "-Xms1152M -Xmx1152M -Dscala.concurrent.context.minThreads=4"
partyHint: ieu-foo-001
failOnAppVersionMismatch: true
database:
port: 5432
pwdField: password
schema: validator
secretName: database-validator-dev-foo
userField: user
participant:
nodeIdentifier: IEUDevFoo001
customAuth: true
imageRepo: ghcr.io/digital-asset/decentralized-canton-sync/docker
imageTag: 0.4.16
migrationId: "0"
migrationMigrating: false
onboardingSecretName: cn-app-validator-dev-foo-onboarding-validator
storageSize: 20Gi
```
{% hint style="info" %}
**Key notes when creating a validator:**
* The onboarding secret is one-time use.
* The validator name, participant identifier, and party hint should be changed when deploying a new validator.
* Secrets (names and fields) are referenced inside the Validator definition itself — keep them in-sync.
* Some data is provided as part of the reference itself (e.g., `port`, `schema`), not as a secret field.
{% endhint %}
### Validator Operations
#### Migration
The following fields are used in migration:
```yaml
spec:
migrationId: "2"
migrationMigrating: false
```
To migrate, set the values as follows:
```yaml
spec:
migrationId: "new mig id"
migrationMigrating: true
```
Once the migration is complete, set `migrationMigrating` back to `false`.
#### Recovery from Identity Dump
To recover Canton Coin balances using an Identities Backup, create a Kubernetes secret in the following format:
```yaml
apiVersion: v1
data:
content:
kind: Secret
metadata:
labels:
validator:
name: id-backup-secret-example
namespace: namespace-of-val
type: Opaque
```
Then create a validator (removing the old one if on the same cluster) with the following fields added to `spec`:
```yaml
spec:
config:
partyHint: "oldParty"
participant:
nodeIdentifier: "validator-foooooooo"
identitiesImport:
newParticipantIdentifier: "validator-foooooooo"
secretName: "secret-with-identity-dump-party"
isMigrateValidatorParty: true
```
{% hint style="warning" %}
The participant should have the same node identifier as the `newParticipantIdentifier` field, which must differ from the previous validator.
{% endhint %}
### Configuring the Validator
#### Environment Variable Overrides
To add extra environment variables:
```yaml
spec:
config:
validatorOverrides:
- name: OVERRIDE_EXAMPLE
value: "5432"
participantOverrides: []
walletOverrides:
- name: OVERRIDE_WITH_SECRET
valueFrom:
secretKeyRef:
key: password
name: secret
cnsOverrides: []
```
{% hint style="info" %}
These overrides will **override** any variables generated by the `spec.config`. In older versions, environment variables were defined directly in `application.spec.envVars`, `applicationWallet.spec.envVars`, etc. On upgrade to v1.10, a script generates the `spec.config` fields from these. The `.spec.envVars` format will be removed in a future release.
{% endhint %}
#### Resource Customization
```yaml
spec:
application:
spec:
resources:
cpuLimit: "4"
cpuRequested: "2"
memoryLimit: 8Gi
memoryRequested: 4Gi
replicas: 1
applicationCantonNameServer:
spec:
resources:
cpuLimit: "2"
cpuRequested: "0.5"
memoryLimit: 2Gi
memoryRequested: 512Mi
replicas: 1
applicationWallet:
spec:
resources:
cpuLimit: "2"
cpuRequested: "0.5"
memoryLimit: 2Gi
memoryRequested: 512Mi
replicas: 1
participant:
spec:
resources:
cpuLimit: "4"
cpuRequested: "2"
memoryLimit: 8Gi
memoryRequested: 4Gi
replicas: 1
storageSize: 50Gi
```
#### Other Configuration Examples
Enable top-up
```yaml
spec:
config:
topUp:
enabled: true
minInterval: 2m
targetThroughput: 80000
```
Enable scheduled pruning
```yaml
spec:
config:
scheduledPrune:
retention: "2m"
cron: "* * * * *"
maxDuration: "30d"
```
Provide additional config
```yaml
spec:
config:
additionalConfigOther: |
canton.validator-apps.validator_backend.participant-bootstrapping-dump {
type = file
file = /participant-bootstrapping-dump/content
new-participant-identifier = "validator-fooooooo"
}
```
Set contact point
```yaml
spec:
config:
contactPoint: "mycompany@mail.com"
```
***
## KMS
KMS is set at creation via `spec.enableKms` plus fields on the participant spec. It cannot be toggled on or off after creation.
### AWS / GCP
{% tabs %}
{% tab title="AWS" %}
```yaml
spec:
enableKms: true
participant:
spec:
serviceAccount: catbm-aws-kms
kmsValue: '{ type = "aws", region = "eu-west-1", audit-logging = true }'
```
{% endtab %}
{% tab title="GCP" %}
```yaml
spec:
enableKms: true
participant:
spec:
serviceAccount: catbm-gcp-kms
kmsValue: '{ type = "gcp", project-id = "my-project" }'
```
{% endtab %}
{% endtabs %}
### Azure
```yaml
spec:
enableKms: true
participant:
spec:
overrideImage:
resources:
imagePullSecret: azure-kms-registry-credentials
kmsValue: '{ type = driver, name = "azure-kms", config { vault-url = "...", credential { type = environment } } }'
kmsAzureVaultSecretName: azure-kms-credentials
```
The secret named by `kmsAzureVaultSecretName` must contain: `tenant-id`, `client-id`, `client-secret`.
### API-to-CRD field mapping
The REST API nests these under `clusterParticipantConfig`:
| API field | CRD path |
| --------------------------------------- | ------------------------------------------------- |
| `enableKms` | `spec.enableKms` |
| `kmsValue` | `spec.participant.spec.kmsValue` |
| `kmsServiceAccount` | `spec.participant.spec.serviceAccount` |
| `kmsAzureVaultSecretName` | `spec.participant.spec.kmsAzureVaultSecretName` |
| `overrideImage` | `spec.participant.spec.overrideImage` |
| `participant.resources.imagePullSecret` | `spec.participant.spec.resources.imagePullSecret` |
***
# Key Management Service (KMS)
How to enable KMS-backed key management for Canton Validator Participant nodes using IRSA (IAM Roles for Service Accounts).
CatalyX Blockchain Manager supports External Key Management Services (KMS) for storing Canton Validator Participant cryptographic keys. When KMS is enabled, participant keys are stored and managed in an external KMS rather than locally on the node, improving key security and enabling compliance with enterprise key management policies.
For background on why KMS matters, the two Canton key storage modes (encrypted vs. external), and the broader key management and wallet strategy for CAT-BM, see the Security & Privacy Implementation page:
{% content-ref url="/pages/bvHLoRkGDY6yVqcoe4i9" %}
[Broken mention](broken://pages/bvHLoRkGDY6yVqcoe4i9)
{% endcontent-ref %}
{% hint style="info" %}
KMS integration was introduced in **v1.11.8** as a Phase 1, environment-level toggle. As of **v1.11.11**, KMS is configured **per validator** — each validator can be created with its own KMS provider configuration and ServiceAccount, independently of other validators in the same environment. The Azure KMS driver was added in **v1.11.13**, and Azure authentication via AKS Workload Identity (cross-tenant) was added in **v1.11.15**.
{% endhint %}
{% hint style="warning" %}
KMS is now selected at **validator creation time** in the console (or via the API). It cannot be toggled on or off for an existing validator through the edit wizard. The environment-level Operator settings still exist, but they are no longer a master switch — they now only support migration of pre-v1.11.11 validators. See [Operator Settings (Legacy Migration Only)](#operator-settings-legacy-migration-only) below.
{% endhint %}
***
## What Changed in v1.11.11
| Aspect | Phase 1 (v1.11.8) | Per-validator (v1.11.11) |
| ------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Scope | Environment-wide — applied to **all** newly created validators | **Per validator** — chosen individually at creation time |
| How it is enabled | `CANTON_TOPOLOGY_KMS_ENABLED=true` on the Operator | `enableKms` flag in the validator create request / console create flow |
| KMS provider config | Single global `CANTON_TOPOLOGY_KMS_VALUE` for everyone | Per-validator `kmsValue` (falls back to the Operator default if omitted) |
| ServiceAccount | Single global `CANTON_TOPOLOGY_KMS_SERVICE_ACCOUNT` | Per-validator `kmsServiceAccount` (falls back to the Operator default if omitted) |
| Changing the toggle | Required redeploying the Operator | No redeploy — set per validator at create time |
| Existing validators | Retained their original config | Legacy KMS validators are auto-migrated on first reconcile (see [Backward Compatibility](#backward-compatibility-with-legacy-validators)) |
The Phase 1 global auto-enable flag (`CANTON_TOPOLOGY_KMS_ENABLED`) has been **retired**. KMS is no longer turned on by an environment variable; it is driven entirely by the per-validator request.
***
## How It Works
When a validator is created with KMS enabled, the CAT-BM Operator injects additional Canton crypto configuration into that validator's Participant pod at provisioning time. The Participant authenticates with the external KMS using IRSA — an IAM Role is associated with a Kubernetes ServiceAccount, and that ServiceAccount is assigned to the Participant pod.
The ServiceAccount is **externally managed**. It must be created and maintained outside of CAT-BM, and its name is provided per validator (or via the Operator default).
Each validator carries its own KMS settings on its spec:
* `enableKms` — whether this validator uses KMS
* `kmsValue` — the Canton KMS provider configuration fragment for this validator
* `kmsServiceAccount` — the externally managed ServiceAccount this validator's Participant pod runs under
Validators created without KMS are unaffected and continue to run under the `default` ServiceAccount with no KMS crypto config injected.
***
## Prerequisites
Before enabling KMS for a validator, ensure the following are in place:
* An external KMS key created in the appropriate region/project (e.g. AWS KMS, GCP KMS)
* An IAM Role configured with permissions to use the KMS key
* A Kubernetes ServiceAccount created in the validator namespace with the IAM Role ARN annotated via IRSA:
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: catalyst-canton-kms
namespace:
annotations:
eks.amazonaws.com/role-arn:
```
* The ServiceAccount name and the KMS provider configuration available to supply in the create request
***
## Enabling KMS for a Validator
KMS is enabled per validator at creation time. In the **Create Validator** flow, the participant configuration accepts three fields:
| Field | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `enableKms` | Set to `true` to store this validator's participant keys in an external KMS. Default: `false`. |
| `kmsValue` | The KMS provider configuration in Canton config format (see below). Required when `enableKms` is true. |
| `kmsServiceAccount` | The externally managed Kubernetes ServiceAccount used for IRSA authentication. Required when `enableKms` is true. |
### Request body (API)
These fields live under `clusterParticipantConfig` in the create-validator request. There are two modes, distinguished by which field you supply:
* **AWS / GCP** — use `kmsServiceAccount`
* **Azure (vault secret)** — use `kmsAzureVaultSecretName` (plus `overrideImage`)
* **Azure (AKS Workload Identity, cross-tenant)** — use `kmsAzureWorkloadIdentity: true` with `kmsServiceAccount` instead of a vault secret (see [AKS Workload Identity (Cross-Tenant)](#aks-workload-identity-cross-tenant) below)
`clusterParticipantConfig` KMS fields:
| Field | Type | Description |
| -------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `enableKms` | boolean | Master flag — turns KMS on for this validator |
| `kmsValue` | string | HOCON provider config (see Provider Examples below) |
| `kmsServiceAccount` | string | K8s ServiceAccount — for AWS/GCP IRSA, or for Azure when using Workload Identity |
| `kmsAzureVaultSecretName` | string | K8s Secret holding Azure credentials (Azure vault-secret mode only) |
| `kmsAzureWorkloadIdentity` | boolean | Use AKS Workload Identity instead of a vault secret for Azure KMS auth (cross-tenant) |
| `overrideImage` | string | Participant image override (required for Azure driver image) |
Azure also needs a pull secret for `overrideImage`, set elsewhere in the request body:
| Field | Description |
| --------------------------------------- | ----------------------------------------------- |
| `participant.resources.imagePullSecret` | Pull secret for the override image (Azure only) |
AWS example:
```json
{
"clusterParticipantConfig": {
"nodeIdentifier": "my-validator-01",
"enableKms": true,
"kmsValue": "{ type = \"aws\", region = \"eu-west-1\", audit-logging = true }",
"kmsServiceAccount": "catalyst-canton-kms"
}
}
```
### `kmsValue` format
`kmsValue` takes a Canton configuration fragment. Because it is passed through verbatim, any Canton-supported KMS provider can be used.
AWS KMS:
```
{ type = "aws", region = "eu-west-1", audit-logging = true }
```
GCP KMS:
```
{ type = "gcp", project-id = "my-project" }
```
Azure KMS (driver-based):
```
{ type = driver, name = "azure-kms", config { vault-url = "https://.vault.azure.net", credential { type = environment } } }
```
Azure additionally requires:
* `kmsAzureVaultSecretName`: a K8s Secret containing fields `tenant-id`, `client-id`, `client-secret`
* `overrideImage`: an Azure-KMS-enabled participant image that matches the splice image used by the validator's other apps
* A pull secret for that image, set under `participant.resources.imagePullSecret`
Azure example request:
```json
{
"clusterParticipantConfig": {
"nodeIdentifier": "my-validator-01",
"enableKms": true,
"kmsValue": "{ type = driver, name = \"azure-kms\", config { vault-url = \"https://my-vault.vault.azure.net\", credential { type = environment } } }",
"kmsAzureVaultSecretName": "azure-kms-credentials",
"overrideImage": "registry.gitlab.com/.../canton-azure-kms-driver:latest"
},
"participant": {
"resources": {
"imagePullSecret": "azure-kms-registry-credentials"
}
}
}
```
Adjust the provider settings to match your KMS key. For AWS, set `audit-logging = true` to enable KMS API audit logs (recommended for production).
### AKS Workload Identity (Cross-Tenant)
{% hint style="info" %}
Introduced in **v1.11.15**. This is an alternative to the vault-secret Azure flow above — it removes the need for a `client-secret` stored in a Kubernetes Secret.
{% endhint %}
AKS supports [cross-tenant Workload Identity](https://learn.microsoft.com/en-us/azure/aks/workload-identity-cross-tenant), which lets a validator authenticate to an Azure Key Vault that lives in a **different tenant** than the AKS cluster:
* The AKS cluster runs in **Tenant A** (the CAT-BM cluster).
* The Azure Key Vault and managed identity live in **Tenant B** (the customer's tenant).
* A Kubernetes `ServiceAccount` annotated with `azure.workload.identity/client-id` binds the Participant pod to a managed identity in Tenant B via a federated OIDC credential — no `client-secret` required.
* The Participant pod (not the Deployment) must carry the label `azure.workload.identity/use: "true"` so the AKS Workload Identity mutating webhook fires.
* The webhook automatically injects `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_FEDERATED_TOKEN_FILE`, and `AZURE_AUTHORITY_HOST` into the pod from the ServiceAccount's annotations.
* The Azure KMS driver picks these up automatically via `credential { type = default }` (`DefaultAzureCredential`) — no driver changes are needed.
To use this mode, set `kmsAzureWorkloadIdentity: true` and supply `kmsServiceAccount` (the externally managed ServiceAccount bound to the Tenant B identity) instead of `kmsAzureVaultSecretName`:
```json
{
"clusterParticipantConfig": {
"nodeIdentifier": "my-validator-01",
"enableKms": true,
"kmsValue": "{ type = driver, name = \"azure-kms\", config { vault-url = \"https://my-vault.vault.azure.net\", credential { type = default } } }",
"kmsAzureWorkloadIdentity": true,
"kmsServiceAccount": "catalyst-azure-workload-identity",
"overrideImage": "registry.gitlab.com/.../canton-azure-kms-driver:latest"
},
"participant": {
"resources": {
"imagePullSecret": "azure-kms-registry-credentials"
}
}
}
```
Note the `credential` type in `kmsValue` changes from `environment` (vault-secret mode) to `default` (Workload Identity mode).
The existing vault-secret-based Azure KMS flow continues to work unchanged — `kmsAzureWorkloadIdentity` and `kmsAzureVaultSecretName` are mutually exclusive ways of authenticating the same Azure KMS driver.
### Validation
When `enableKms` is `true`, `kmsValue` must be non-blank, and at least one of `kmsServiceAccount` (AWS/GCP, or Azure Workload Identity), or `kmsAzureVaultSecretName` (Azure vault-secret mode) must be non-blank. Creating an Azure KMS validator without providing either a vault secret or a Workload Identity ServiceAccount is rejected. If a required field is missing, empty, or whitespace-only, the API rejects the request with **HTTP 400** and a `fieldErrors` map identifying the offending field(s):
```json
{
"fieldErrors": {
"clusterParticipantConfig.kmsValue": "kmsValue must not be empty when enableKms is true",
"clusterParticipantConfig.kmsServiceAccount": "kmsServiceAccount must not be empty when enableKms is true"
},
"globalErrors": {}
}
```
When `enableKms` is `false`, these fields are ignored and no validation is applied.
***
## Operator Settings (Legacy Migration Only)
The Operator still reads two environment-level KMS settings, but in v1.11.11 they are **not** a general-purpose configuration knob. Because the API requires both `kmsValue` and `kmsServiceAccount` whenever `enableKms=true` (see [Validation](#validation)), every validator created through the CAT-BM API or console already carries explicit values — so the Operator defaults are **never consulted for new validators**.
If `enableKms=true` but a per-validator KMS field is left blank, the Operator falls back to its configured defaults. This happens both as a one-time backfill onto pre-v1.11.11 validators on first reconcile, and at render time for any validator.
| Variable | Role in v1.11.11 |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `CANTON_TOPOLOGY_KMS_ENABLED` | **Retired** — no longer used to auto-enable KMS. KMS is enabled per validator via `enableKms`. |
| `CANTON_TOPOLOGY_KMS_VALUE` | Default fallback for `kmsValue` when blank. |
| `CANTON_TOPOLOGY_KMS_SERVICE_ACCOUNT` | Default fallback for `kmsServiceAccount` when blank. |
| `CANTON_TOPOLOGY_KMS_AZURE_IMAGE` | Default fallback for `overrideImage` (Azure) when blank. |
| `CANTON_TOPOLOGY_KMS_AZURE_IMAGE_PULL_SECRET` | Default fallback for `participant.resources.imagePullSecret` (Azure) when blank. |
| `CANTON_TOPOLOGY_KMS_AZURE_VAULT_SECRET` | Default fallback for `kmsAzureVaultSecretName` (Azure) when blank. |
{% hint style="warning" %}
To prevent a validator with blank KMS fields from silently inheriting these defaults, set the relevant variables to `""` on the Operator.
{% endhint %}
{% hint style="info" %}
If your environment has no legacy (pre-v1.11.11) KMS validators, these Operator settings have no effect and can be ignored. They only matter while un-migrated Phase 1 validators still exist — see [Backward Compatibility](#backward-compatibility-with-legacy-validators).
{% endhint %}
***
## What the Operator Configures
When a validator is provisioned with KMS enabled, the Operator makes the following changes to that validator's Participant pod:
**ServiceAccount reference** — the resolved ServiceAccount (per-validator value, or the Operator default) is set on the Participant/Canton spec:
```yaml
spec:
serviceAccountName: catalyst-canton-kms
```
**KMS crypto config injection** — the following environment variable is injected into the Participant pod, built from the resolved `kmsValue`:
```
ADDITIONAL_CONFIG_SPLICE_PARTICIPANT_CRYPTO_KMS =
"canton.participants.participant.crypto.provider = kms
canton.participants.participant.crypto.kms { type = "aws", region = "eu-west-1", audit-logging = true }"
```
***
## Backward Compatibility with Legacy Validators
Validators that were created under the Phase 1 environment-level model (with `enableKms=true` but no per-validator `kmsValue` / `kmsServiceAccount` on their spec) are automatically migrated. On the next reconcile, the Operator **backfills** the global topology values (`CANTON_TOPOLOGY_KMS_VALUE` / `CANTON_TOPOLOGY_KMS_SERVICE_ACCOUNT`) onto the validator CR.
This makes the validator's KMS configuration fully explicit on its own spec, so that API reads (GET) and Operator writes (reconcile) share a single source of truth. The backfill:
* Runs only for validators that already have `enableKms=true`.
* Only fills fields that are currently **blank** — it never overwrites an explicit per-validator value.
* Runs regardless of the `disableUserEdit` flag, because it is a system migration rather than a user edit (it executes before the user-edit guard in the reconcile loop).
* Is **idempotent and self-terminating** — once both `kmsValue` and `kmsServiceAccount` are populated, it short-circuits and patches nothing on subsequent reconciles. After this one-time migration the validator no longer depends on the global Operator defaults.
{% hint style="warning" %}
For the legacy backfill to work, the Operator's `CANTON_TOPOLOGY_KMS_VALUE` and `CANTON_TOPOLOGY_KMS_SERVICE_ACCOUNT` defaults must still match what those validators were originally provisioned with, **until every legacy validator has reconciled at least once**. Removing them before legacy validators have been migrated would leave those validators without a resolvable KMS configuration.
{% endhint %}
***
## Verifying KMS Is Active
After provisioning a validator with KMS enabled, verify that:
1. The API echoes the KMS fields back on the participant — a GET on the participant returns `enableKms=true` and the `kmsValue` / `kmsServiceAccount` you submitted.
2. The Participant pod references the correct ServiceAccount — check with `kubectl get pod -o yaml | grep serviceAccountName`
3. The `ADDITIONAL_CONFIG_SPLICE_PARTICIPANT_CRYPTO_KMS` environment variable is present on the Participant pod
4. The Participant starts successfully and reaches a Ready state — check the [Status](https://gitlab.com/intellecteu/products/catalyst/cat-bp/catbp-docu/catalyx-gitbook/-/blob/staging/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validator-detail/status.md) page in the console
{% hint style="info" %}
KMS key usage will appear in your provider's audit log (e.g. AWS CloudTrail) if audit logging is enabled on your KMS key. This can be used to confirm the Participant is actively using KMS for cryptographic operations.
{% endhint %}
***
## Scope and Limitations
| Capability | v1.11.11 |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Per-validator KMS toggle (at create time) | ✅ Supported |
| Per-validator KMS provider config & ServiceAccount | ✅ Supported |
| Multiple KMS providers (AWS, GCP, …) | ✅ Supported via the `kmsValue` Canton config fragment |
| Azure KMS via AKS Workload Identity (cross-tenant) | ✅ Supported since **v1.11.15** — `kmsAzureWorkloadIdentity` as an alternative to `kmsAzureVaultSecretName` |
| Legacy validator migration | ✅ Supported — Operator KMS settings backfilled onto the CR on reconcile |
| Environment-level KMS defaults for new validators | ❌ Not applicable — validation requires explicit values, so Operator defaults are never used for new validators |
| Toggling KMS on an existing validator (edit) | ❌ Not supported — KMS is fixed at creation time; the edit wizard guards these fields. All KMS fields are immutable after creation **except `overrideImage`**, which remains editable. |
| Retroactive KMS enablement for non-KMS validators | ❌ Not supported — only validators created with `enableKms=true` use KMS |
| Operator-managed ServiceAccount lifecycle | ❌ Not yet supported — SA must be externally managed |
| KMS key rotation | ❌ Not yet supported |
# Logging
This page explains how Catalyst provides access to logs for all running participant and validator components directly from the user interface. Logs are retrieved from the Kubernetes API and displayed per component, with each entry including a Kubernetes-provided timestamp.
### Component Logs
Catalyst displays logs for all running components on the Participant or Validator detail page. Logs are fetched from the Kubernetes API.
### Navigating Logs
Scroll up and down through the log output. Scroll **down** to see newer entries, scroll **up** to see older ones.
### Log Formatting
Your logs can use any format. However, to enable level filtering, format your logs as JSON with a `level` field:
```json
{"level": "error", "message": "Connection failed"}
{"level": "info", "message": "Service started"}
```
When your logs follow this format, you can filter by severity level (info, warning, error, etc.).
### Searching Logs
Use the search field to find specific text within your loaded logs. The search works on logs currently displayed in your view. To search older logs, scroll up to load them first.
***
# Wallet Sweeps
This page explains how to configure wallet sweeps on a validator. A wallet sweep monitors the balance of a specific party (the sender). When the sender's balance exceeds a configured maximum threshold, the validator automatically initiates a transfer to another party (the receiver), ensuring only a defined minimum balance remains.
### Configure a Wallet Sweep
{% stepper %}
{% step %}
**Navigate to the Sweep section**
Go to the Validator's details page and locate the **Sweep** section.
{% endstep %}
{% step %}
**Add a new sweep**
Click the **+** icon to configure a new sweep.
{% endstep %}
{% step %}
**Provide sweep configuration**
Fill in the following information:
* **Primary party ID (sender)**
* **Secondary party ID (receiver)**
* **Maximum balance threshold (USD)**
* **Minimum balance to retain (USD)**
* **Toggle on/off: Use Transfer Preapproval**
More info about these fields
| Field | Description |
| ----------------------------------- | -------------------------------------------------------------------- |
| **Primary party ID (sender)** | The hosted party whose wallet balance will be monitored and swept |
| **Secondary party ID (receiver)** | The party that will receive the swept funds |
| **Maximum balance threshold (USD)** | When the sender's balance exceeds this amount, the sweep is executed |
| **Minimum balance to retain (USD)** | The amount that will remain in the sender's wallet after the sweep |
| **Use Transfer Preapproval** | See below |
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
**Use Transfer Preapproval toggle behavior:**
* **Enabled (true):** Performs a direct automatic transfer. No acceptance by the receiver is required.
* **Disabled (false):** Creates a transfer offer that must be accepted by the receiver (manually or via auto-accept).
{% endhint %}
### Alternative Sweep Configuration Method
Wallet sweeps can also be configured during:
* Initial validator setup
* Editing an existing validator setup
This is done through the standard validator configuration flow.
***
# Expose Ledger API
How to expose and access the Ledger API for a participant or validator in CatalyX Blockchain Manager.
## Overview
This guide explains how to:
* expose the Ledger API for a participant or validator
* configure authentication and authorization
* configure Keycloak integration
* access the JSON Ledger API and gRPC Ledger API
* validate access tokens
* troubleshoot common Ledger API access issues
The Ledger API allows external applications to submit commands, query contracts, consume ledger events, and integrate with Canton applications.
{% hint style="info" %}
Enabling the Ledger API exposes the participant API externally but does **not** cause ledger downtime or interrupt validator operations.
{% endhint %}
## What is the Ledger API?
The Ledger API exposes services that allow applications to interact with the Canton ledger. It supports command submission, transaction streaming, active contract queries, and event subscriptions.
There are two primary API types:
| API Type | Purpose |
| --------------- | ------------------------------------------ |
| gRPC Ledger API | Native high-performance Canton integration |
| JSON Ledger API | REST/WebSocket-based integration |
### Architecture
The Ledger API uses OpenID Connect (OIDC), JWT access tokens, Keycloak authentication, and Canton authorization checks. Authorization is performed for every request.
Required token claims:
* `aud` — audience
* `sub` — subject
* `scope` — must include `daml_ledger_api`
***
## Part 1 — Enable Ledger API Exposure
{% stepper %}
{% step %}
#### Open Validator Details
Navigate to **Validators**, select the target validator, and open **Edit configuration**.
{% endstep %}
{% step %}
#### Enable Ledger API Exposure
Locate the **Ledger API** or **API Exposure** settings and enable:
* JSON Ledger API exposure
* External API access
Save the configuration. After deployment, the participant exposes Ledger API endpoints externally.
{% endstep %}
{% step %}
#### Access the Ledger API URL
After enabling the API, the Ledger API URL becomes visible in the validator details page. Typical URL formats:
```
https://participant-${validator-name}.${domain}
```
```
https://json-api-${validator-name}.${domain}
```
Credentials are authenticated using Keycloak.
{% endstep %}
{% endstepper %}
***
## Part 2 — Configure Keycloak Authentication
Keycloak acts as the Identity Provider (IdP), OAuth Provider, and token issuer. Applications authenticate against Keycloak and receive JWT access tokens used by Canton.
### Create a Realm
{% stepper %}
{% step %}
#### Open Keycloak
Log in to the Keycloak Admin Console and click **Add Realm**.
{% endstep %}
{% step %}
#### Configure the Realm
Provide a **Realm Name** and **Display Name**, then click **Create**.
Use separate realms per environment, for example: `sandbox`, `production`.
{% endstep %}
{% endstepper %}
### Create an OpenID Client
{% stepper %}
{% step %}
#### Open Clients
Navigate to **Clients → Create**.
{% endstep %}
{% step %}
#### Configure the Client
Provide:
* **Client ID** — recommended: `canton-participants`
* **Protocol** — `openid-connect`
{% endstep %}
{% step %}
#### Configure Access Type
Set **Access Type** to `confidential` and enable:
* Standard Flow
* Direct Access Grants
* Service Accounts
Save the configuration.
{% endstep %}
{% step %}
#### Configure Redirect URLs
Add the participant JSON API URL:
```
https://json-api-${participant}.${domain}/*
```
Save changes.
{% endstep %}
{% endstepper %}
### Create the `daml_ledger_api` Scope
{% stepper %}
{% step %}
#### Open Client Scopes
Navigate to **Client Scopes → Create**.
{% endstep %}
{% step %}
#### Configure the Scope
Create a scope named `daml_ledger_api`, enable **Include In Token Scope**, and save.
{% endstep %}
{% step %}
#### Assign the Scope to the Client
Navigate to **Client → Client Scopes** and add `daml_ledger_api` to **Assigned Default Client Scopes**.
{% endstep %}
{% endstepper %}
### Configure the Audience Mapper
The Ledger API validates the token audience against the participant identifier. Navigate to **Client Scopes → daml\_ledger\_api → Mappers** and create a mapper:
| Field | Value |
| ------------------------ | ----------------------------- |
| Name | `audience-participant-mapper` |
| Mapper Type | Audience |
| Included Custom Audience | participant ID |
Enable **Add to ID token** and **Add to access token**.
Example audience value:
```
sandbox::12205d66c5f04ee07...
```
***
## Part 3 — Configure Roles and Users
Navigate to **Client → Roles → Add Role** and create the required roles. Recommended roles:
* `Participant_Admin`
* `Party`
* `Broker`
* `Borrower`
* `Lender`
To create a user, navigate to **Users → Add User**, provide a username, email, and password, then navigate to **User → Role Mappings** and assign the appropriate client role (e.g. `Participant_Admin`).
***
## Part 4 — Configure Canton Authorization
Configure the participant to validate JWT tokens against Keycloak:
```
ledger-api {
address = localhost
port = 6865
auth-services = [{
type = jwt-rs-256-jwks
url = "http://localhost:8080/auth/realms/company/protocol/openid-connect/certs"
}]
}
```
***
## Part 5 — Generate an Access Token
Request a token from Keycloak:
```bash
curl -X POST \
https://${keycloak}/auth/realms/${realm}/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id=canton-participants" \
-d "client_secret=${CLIENT_SECRET}" \
-d "scope=daml_ledger_api" \
-d "username=participant_admin" \
-d "password=${PASSWORD}"
```
The response contains an access token, expiration, and token type.
### Validate the JWT Token
The JWT token must contain:
```json
{
"aud": "participantId",
"sub": "userId",
"scope": "daml_ledger_api",
"exp": 1300819380
}
```
* The `aud` audience must match the participant ID
* The `scope` must include `daml_ledger_api`
***
## Part 6 — Access the Ledger API
### JSON Ledger API
Used for REST integrations, WebSocket event streaming, frontend applications, and lightweight integrations. Include the JWT token in every request:
```
Authorization: Bearer
```
Common endpoints:
| Endpoint | Purpose |
| ------------------- | ----------------------- |
| `/v2/updates/flats` | Flat event stream |
| `/v2/updates/trees` | Transaction tree stream |
| `/docs/openapi` | OpenAPI documentation |
| `/docs/asyncapi` | AsyncAPI documentation |
### gRPC Ledger API
Used for backend services, high-performance integrations, and native Canton clients. Main services: Command Submission Service, Command Completion Service, Command Service.
### Ledger Events
The Ledger API emits the following event types:
* Created Events
* Exercised Events
* Archived Events
* Transaction Tree Events
Applications consume events asynchronously.
***
## Troubleshooting
### Common Issues
| Issue | Cause | Resolution |
| ------------------------------ | ------------------------------ | ------------------------------------ |
| Unauthorized client | Incorrect client configuration | Verify confidential client settings |
| Invalid audience | Wrong participant audience | Update audience mapper |
| Missing scope | `daml_ledger_api` not assigned | Add default client scope |
| 401 Unauthorized | Invalid token | Regenerate token |
| Ledger API inaccessible | API not exposed | Enable Ledger API exposure |
| Create Party button greyed out | Parties not yet loaded | Wait for synchronization to complete |
### Validation Checklist
| Check | Expected Result |
| ---------------------------------- | --------------------------- |
| Ledger API enabled | External endpoint available |
| Keycloak client created | OAuth authentication works |
| `daml_ledger_api` scope configured | Tokens include scope |
| Audience mapper configured | Token audience valid |
| User roles assigned | API access granted |
| JWT token valid | Requests authorized |
***
## Best Practices
* Use confidential clients in production
* Separate environments by realm
* Use short-lived access tokens
* Restrict `Participant_Admin` role usage
* Always validate token scopes
* Use HTTPS-only endpoints
* Configure CORS for JSON API access
***
## Additional References
* [JSON Ledger API](https://docs.digitalasset.com/build/3.4/explanations/json-api/index.html)
* [Ledger API Services](https://docs.digitalasset.com/build/3.4/explanations/ledger-api-services.html)
* [Ledger API Proto Docs](https://docs.digitalasset.com/build/3.4/reference/lapi-proto-docs.html)
* [JSON API Reference](https://docs.digitalasset.com/build/3.4/reference/json-api/json-api.html)
# Disaster Recovery from a Failure on Global Synchronizer
This flow is adapted from the [Canton official guide](https://dev.network.canton.global/validator_operator/validator_backups.html#disaster-recovery-from-loss-of-the-cometbft-storage-layer-of-the-global-synchronizer), with additional instructions for Catalyst validator installations.
{% hint style="warning" %}
Follow these steps only when instructed to by your super validator sponsor or the IntellectEU team during a network recovery event.
{% endhint %}
{% stepper %}
{% step %}
**Set environment variables**
```bash
export NAME=
export PASSWORD=
export KEYCLOAK_URL=
export REALM=
```
{% endstep %}
{% step %}
**Log in to Keycloak and obtain a token**
```bash
curl --location "${KEYCLOAK_URL}/auth/realms/${REALM}/protocol/openid-connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=password" \
--data-urlencode "client_id=${NAME}-wallet-ui" \
--data-urlencode "username=${NAME}_walletuser" \
--data-urlencode "password=${PASSWORD}" > token.json
```
{% endstep %}
{% step %}
**Extract the access token**
```bash
export TOKEN=$(jq -r .access_token token.json)
```
{% endstep %}
{% step %}
**Obtain the snapshot from the wallet**
{% hint style="info" %}
* The wallet URL can be obtained from the UI page of the wallet application.
* The super validators on network recovery will provide the timestamp in the `#validators-ops` channel.
* The timestamp format is the same as the logs for the validator.
{% endhint %}
```bash
export WALLET_URL=
export TIMESTAMP=
curl -sSLf "${WALLET_URL}/api/validator/v0/admin/domain/data-snapshot?timestamp=${TIMESTAMP}&force=true" \
-X GET \
-H "authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" > dump_response.json
```
{% endstep %}
{% step %}
**Extract the data snapshot**
```bash
jq '.data_snapshot' dump_response.json > data_snapshot.json
```
{% endstep %}
{% step %}
**Copy the snapshot to the validator pod**
{% hint style="info" %}
The validator pod will have the name of the validator plus suffixes added by Kubernetes.
{% endhint %}
```bash
export NAMESPACE=
export PODNAME=
kubectl cp data_snapshot.json ${NAMESPACE}/${PODNAME}:/domain-upgrade-dump/domain_migration_dump.json
```
{% endstep %}
{% step %}
**Verify the file integrity (MD5 checksum)**
```bash
export LOCAL_DUMP_MD5SUM=$(md5sum data_snapshot.json)
export PODS_DUMP_MD5SUM=$(kubectl -n "${NAMESPACE}" exec -it ${PODNAME} -- md5sum /domain-upgrade-dump/domain_migration_dump.json)
if [ "$(echo $LOCAL_DUMP_MD5SUM | awk '{print $1}')" = "$(echo $PODS_DUMP_MD5SUM | awk '{print $1}')" ]; then
echo 'MD5SUM checksums are equal.'
else
echo 'MD5SUM checksums are not equal! Check the file copied is correct.'
fi
```
{% endstep %}
{% step %}
**Trigger the migration**
In the Catalyst UI validator page, **edit the validator**, set `migrationID` to a new migration ID, and toggle **migrating** to `true`.
Confirm and wait for the update to complete.
{% endstep %}
{% endstepper %}
***
# Validator Upgrade Policy and Release Schedule
CatalyX's policy and process for validator node upgrades, release validation, and version compatibility on the Canton Network.
## Overview
CatalyX follows the official Canton Foundation release lifecycle for validator upgrades. New Canton releases are continuously monitored, evaluated, and validated by IntellectEU before being recommended for customer environments.
The objective of the upgrade process is to maintain compatibility with the Canton Network while minimizing operational risk and service disruption.
{% hint style="info" %}
CatalyX does not automatically upgrade validator nodes. Upgrades are performed in a controlled manner following internal validation, customer communication, and agreed maintenance windows where applicable.
{% endhint %}
***
## Upgrade Policy
Validator upgrades are performed according to the release schedule published by the Canton Foundation.
When a new supported version becomes available, IntellectEU:
* Reviews the Canton Foundation release notes.
* Evaluates compatibility with supported CatalyX components.
* Performs internal validation and testing.
* Reviews migration requirements and known issues.
* Updates internal and customer documentation where necessary.
* Recommends the validated release to customers.
* Assists customers with upgrade planning and execution.
This process ensures that validator nodes remain compatible with the Canton Network while reducing the risk of introducing regressions into production environments.
***
## Release Validation Process
Before a validator version is recommended for customer use, IntellectEU follows an internal release validation process:
1. Reviewing the new Canton Foundation release.
2. Validating compatibility with supported CatalyX services.
3. Testing validator deployment and upgrade procedures.
4. Verifying database migrations (if applicable).
5. Validating package compatibility.
6. Reviewing known issues and workarounds.
7. Updating operational documentation.
8. Recommending the validated release for customer deployment.
{% hint style="info" %}
Only validated releases are recommended for production environments.
{% endhint %}
***
## Release Schedule
CatalyX does not maintain its own fixed release calendar for Canton validator versions. Validator upgrades follow the availability of new Canton Foundation releases.
Customers can monitor upcoming and released versions through:
* Canton Foundation release announcements
* CatalyX Blockchain Manager [Release Notes](/catalyx-blockchain-manager/canton-network/version-1.11/release-notes)
* CatalyX Product Roadmap
After a new Canton release becomes available, IntellectEU performs validation before recommending customer upgrades.
***
## Typical Upgrade Process
A validator upgrade generally consists of four stages.
{% stepper %}
{% step %}
#### Preparation
Before performing an upgrade, it is recommended to:
* Schedule an appropriate maintenance window.
* Review the release notes for the target version.
* Verify that recent database backups are available.
* Verify that a recent Validator Identity Dump (IDDump) exists.
* Review any migration requirements.
{% hint style="info" %}
See [Validator Backups and Identity Dumps](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/identity-backup-and-recovery) for how to schedule and verify backups and IDDumps.
{% endhint %}
{% endstep %}
{% step %}
#### Upgrade the Validator Version
The validator application version is upgraded by updating the validator image.
Using the CatalyX UI:
* Open the validator.
* Edit the validator configuration.
* Select the new Image Tag.
* Save the configuration.
Using the [Validator CRD](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/validator-custom-resource-definition):
```yaml
spec:
imageTag: 0.6.x
```
The operator deploys the updated validator version.
{% endstep %}
{% step %}
#### Execute Migration (When Required)
Some validator releases require an application or data migration.
When migration is required:
1. Increment the Migration ID.
2. Set **Migrating** to **true**.
3. Wait for the migration to complete.
4. Set **Migrating** back to **false**.
Example:
```yaml
spec:
migrationId: "3"
migrationMigrating: true
```
After successful completion:
```yaml
spec:
migrationMigrating: false
```
{% hint style="warning" %}
Migration should only be executed once for each required upgrade.
{% endhint %}
{% endstep %}
{% step %}
#### Post-Upgrade Validation
After the upgrade completes, verify that the validator is operating normally:
* Validator status is **Running**.
* Participant successfully joins and synchronizes with the network.
* Wallet login succeeds.
* Applications start successfully.
* No startup errors are present in the logs.
* Scan API responds successfully.
* Health status is normal.
{% endstep %}
{% endstepper %}
***
## Backup Recommendations Before Upgrading
Before every upgrade, IntellectEU recommends creating both a database backup and a Validator Identity Dump (IDDump). See [Validator Backups and Identity Dumps](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/identity-backup-and-recovery) for scheduling and restore procedures.
| Backup Type | Preserves | Does Not Preserve |
| ---------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------- |
| Database Backup | Validator database, participant database, ledger state, transaction history | Validator identities and cryptographic keys |
| Identity Dump (IDDump) | Validator identity, cryptographic keys, wallet identity, participant identity | Database contents, ledger state, transaction history |
{% hint style="warning" %}
For complete disaster recovery, both database backups and Identity Dumps should be available before performing an upgrade.
{% endhint %}
***
## Upgrade Best Practices
To minimize operational risk, IntellectEU recommends:
* Test upgrades in DevNet or TestNet before Production.
* Create a database backup.
* Create an Identity Dump.
* Review release notes.
* Perform upgrades during planned maintenance windows.
* Verify validator health immediately after the upgrade.
* Monitor logs until validator initialization completes successfully.
***
## Version Compatibility
Validator nodes should remain on a supported Canton version validated by IntellectEU.
Although older versions may continue operating for a period of time, remaining significantly behind the supported version increases operational risk and may eventually lead to incompatibility with newer network components.
Customers are encouraged to upgrade after IntellectEU validates and recommends a new release.
### Consequences of Running an Outdated Validator
If a validator remains on an older version after the Canton Network has moved forward, the following issues may occur:
* Application initialization failures.
* Package compatibility conflicts.
* Migration failures.
* Validator remaining in **Pending** state.
* Failure to join or synchronize with the network.
* Inability to deploy newer applications or packages.
* Reduced compatibility with newer Canton protocol features.
* Unsupported configuration for future incident resolution.
{% hint style="danger" %}
In some cases, the validator must be upgraded before normal operation can resume.
{% endhint %}
***
## Customer Communication Process
When a new supported validator version becomes available, IntellectEU typically follows this process:
1. Review the official Canton Foundation release.
2. Perform internal compatibility testing.
3. Validate upgrade and migration procedures.
4. Update operational documentation if required.
5. Notify customers of the recommended upgrade.
6. Schedule or assist with the upgrade.
7. Verify validator health after deployment.
***
## Frequently Asked Questions
How often should validator nodes be upgraded?
Validator nodes should be upgraded after IntellectEU has validated and recommended the corresponding Canton Foundation release. There is no fixed calendar for upgrades, as they depend on the Canton Foundation release schedule and the validation process performed by IntellectEU.
Does every upgrade require a migration?
No. Some releases only require updating the validator application version, while others introduce schema or application changes that require a migration. Migration requirements are documented as part of each supported release.
Can upgrades be rolled back?
Application versions can generally be reverted if necessary. However, migrations may introduce irreversible data changes. Always create a database backup and Identity Dump before upgrading to ensure recovery options are available.
How long does an upgrade take?
Upgrade duration depends on validator size, database size, whether migrations are required, and infrastructure performance. Most routine upgrades complete within a planned maintenance window.
# Release Notes
## Version 1.11
**What's New**
* **Validator Backup and restore** — Configure a database backups schedule through Catalyst and restore validators.
* **Identity backups scheduling** — Configure the identity backup flow through a schedule; these backups are now also visible in the Catalyst UI.
* **Configure External DB** — Create Validators configured for an external Database service (e.g. RDS).
* **User roles added to match new DAML versions** — Added Roles for Participant users in the new DAML versions on the Edit User UI.
**Patches Summary**
| Patch | Description |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v1.11.1 | Validator deployment fix: resolved an error thrown when deploying Validators without a wallet configured. |
| v1.11.2 | Validator wallet configuration fix: resolved a bug where wallet username configuration was missing for some Validators. |
| v1.11.3 | Client heap dump & parties cache: added client heap dump support and an initial attempt at parties cache improvements. |
| v1.11.6 | Disabled party cache. |
| v1.11.7 | Local parties tab & dynamic backup sizing: added a local parties view on the participant details page, improved party fetching performance, and introduced automatic backup volume sizing based on database size and retention settings. |
| v1.11.8 | **I**ntroduced environment-level AWS KMS support for Canton Validator Participant key management via IRSA (IAM Roles for Service Accounts). When enabled, participant keys are stored in KMS rather than locally. Configured via `CANTON_TOPOLOGY_KMS_ENABLED`, `CANTON_TOPOLOGY_KMS_VALUE`, and `CANTON_TOPOLOGY_KMS_SERVICE_ACCOUNT` environment variables. Existing validators are not affected when KMS is enabled at the environment level. |
| v1.11.9 | KMS integration patch |
| v1.11.10 | Added support for Microsoft EntraID as an external Identity Provider. EntraID requires explicit OAuth scope logic on Ledger API and Validator API requests (`/.default` and `api:///.default` respectively). All previously supported IdP configurations remain unaffected. |
| v1.11.11 | Support was introduced for per-participant KMS configuration, allowing validators to be deployed with individual KMS settings that override the global default. The release also addresses several frontend bugs around session handling and form behavior, fixes a validator identity-dump CronJob failure, and includes several security upgrades. |
| v1.11.12 | Fixed a JVM race condition on Operator startup where the Postgres JDBC driver was not reliably registered with `DriverManager`, intermittently causing "No suitable driver found" errors when checking validator/participant database availability and suspending deployment as a result. |
| v1.11.13 | Added support for the Azure KMS driver alongside AWS/GCP, including a participant image override (`overrideImage`) that can be changed and updated independently of other validator components, and an `imagePullSecret` field for the override image. Validator components can now be scaled to 0 replicas. Also fixes env-var validation on the validator edit dialog, a broken Canton Helm chart version, incorrect `targetThroughtput`/`kmsValue` config when disabled/set, the Azure KMS create-wizard's required-field gating, the KMS Value display on validator/participant details pages, the Validator API route being unavailable when the wallet is disabled, validator creation incorrectly rejecting `replicas=0`, and adds HOCON format validation for the Azure KMS value field in the UI. |
| v1.11.14 | Security fixes: bumped the base Docker images used across cat-bm-canton components. |
| v1.11.15 | Added role-based access control to the Console UI — `canton_viewer` and `canton_writer` roles now determine which create/edit/delete controls a user sees, gated by the `AUTH_ROLES` flag on both the API and UI. Added support for configuring Azure KMS authentication via AKS Workload Identity (cross-tenant), letting a validator authenticate to an Azure Key Vault in another tenant via a federated ServiceAccount instead of a vault secret. Also fixes a mismatch between the UI and backend `AUTH_ROLES` defaults that let viewers see write controls the backend would reject, removes a stray health-dump "Create a file" control from the viewer role, and fixes a `POST /api/files` 400 error that was blocking DAR/package uploads. |
| v1.11.16 | Reworked the Console UI **Dashboard** page, now renamed **Monitoring**. Grafana is no longer embedded in the UI — the Monitoring page now links out to the configured Grafana dashboard, opening it in a new tab. Added a Noves section linking to the Noves Data App; when Noves is not configured, clicking the button opens a message prompting the user to install it or contact CatalyX support. Set the `CLUSTER_NOVES_URL` variable on the UI to configure the link. Also includes security fixes for critical dependency and Dockerfile vulnerabilities. |
| v1.11.17 | Improved database reliability: validator, participant, and domain databases now run in a way that prevents a rare failure mode that could corrupt data during pod restarts or configuration changes. This is gated by the `CANTON_OPERATOR_POSTGRES_USESTATEFULSET` environment variable; enabling it triggers a database server restart, incurring roughly 1 minute of downtime. |
***
Version 1.10
**What’s new**
* **Custom Resource Definition changes for Git Ops** - Changes to the main Validator CRD specification to make Git Ops integration easier
* **Custom Annotations for On-Prem Deployments** - Introduced custom Kubernetes annotations for services and deployments, targeted at on-premises customers.
* **Participant Communication API Upgrade** - CatalyX now uses the V2 API for participant communication.
* **Ledger API Egress Support** - Added the ability to configure Ledger API egress.
* **Validator Creation Prefill** - Validator provisioning now automatically queries the network to prefill configuration values, reducing manual input and setup errors.
* **Security Enhancements** - Upgraded dependencies to address known vulnerabilities.
* **Multi-DAR Upload** - Users can now upload multiple DAR files in a single operation.
{% hint style="warning" %}
**Breaking change:** API endpoint /api/files now expects 'files' param instead of 'file'
{% endhint %}
**Bug Fixes**
* **Optimized the validator listing call** - reducing cold start times reported at >1 minute for some customers.
* **Resolved Liveness Probe Creation Issue** - Solved limitations when being created for certain components.
* **Resolved a logging issue** - some runtime logs were not visible in the UI.
**Patches Summary**
* **v1.10.1** - Fixed bug where logs could be truncated - json formatted logs are now returned fully instead of only returning the message field
* **v1.10.2** - Fixed scan API forwarding regression errors in cross environment Identity Dump recovery introduced in 1.10
* **v1.10.3** - Fixed to handle change on validator images where the default user was changed
* **v1.10.4** - Fixed logs formatted in json, so they could get truncated in CatalyX UI
* **v1.10.5** - Changed DAR upload through CatalyX to match the new DAML Ledger API
Version 1.9
**What’s new**
* **Secure JSON API Communication** – CatalyX now establishes direct HTTPS connections with the DAML JSON API, removing the prior reliance on Traefik HTTP-to-HTTPS redirection. This improves compatibility with different cluster environments
* **Dedicated Metrics Port Exposure** – Participants and validators now expose an explicit metrics port, enhancing observability and integration with monitoring tools.
* **Client-Focused Enhancements** – Participants and validators now expose a dedicated Prometheus-compatible metrics port, enabling tighter integration with observability stacks and more granular performance monitoring.
* **UI Redesign** – Modernized frontend for improved UX and streamlined workflows.
* **Flexible Deployment Options** – Additional deployment flags and configurations to support heterogeneous client environments and infrastructure.
* **Stability Improvements** – Multiple backend fixes and improvements to ensure more consistent runtime behavior.
**Patches Summary**
* **v1.9.0 / v1.9.1-** Internal-only builds for penetration testing and internal QA cycles.
* **v1.9.2-** Major client release featuring UI overhaul and modular deployment support for varied infrastructure requirements.
* **v1.9.3-** Resolved an issue introduced in v1.9 where validator pods failed to restart correctly during migration operations
* **…**
* **v1.9.5-** Introduced dedicated metrics port bindings for both participants and validators.
* **v1.9.6-** Modified CatalyX’s DAML JSON API integration to initiate direct HTTPS requests, eliminating dependency on Traefik-level HTTPS redirection.
* **v1.9.7-** Added the ability to disable wallet creation during validator provisioning. Improved identity dump behavior by removing wallet password requirements and avoiding field duplication.
Version 1.8
**What’s new**
* **Extended Identity Provider Integration** - CatalyX now supports integration with additional identity providers beyond Keycloak, enabling broader compatibility with enterprise authentication systems such as Auth0 and Okta.
* **Custom Authorization Controls** - Introduced a configurable authorization mechanism that allows manual definition of clients and users to enhance flexibility for custom access control and tighter security policies.
**Improvements**
* **Validator Provisioning Flow Enhancements** - Streamlined the creation and configuration process for validators with improved component orchestration and resource management, reducing setup time and potential misconfigurations.
* **Bug Fixes.** - Includes various UI and backend corrections to improve stability and consistency.
**Patches**
* **v1.8.1 -** Fixed application creation issue with custom Identity Providers.
* **v1.8.2 -** Resolved volume sizing bug affecting Operator stability.
* **v1.8.3 -** Updated Helm charts and removed deprecated replicated labels; internal CI/CD improvements.
* **v1.8.4 -** Enabled license key injection via Kubernetes secrets.
* **v1.8.5 -** Fixed port conflict in validator UI Docker images for versions >0.3.15.
* **v1.8.6 -** Corrected Canton Name Server image reference from `cns-web-ui` to `ans-web-ui` for version 0.3.17.
* **v1.8.7 -** Added option to disable Role-Based Access Control and use a single Admin role.
* **…**
* **v1.8.10 -** Resolved a regression introduced in build v1.8.7.
* **v1.8.11 -** Introduced ability to define default images (e.g., Postgres, NGINX).
* **v1.8.12 -** Added configuration option to disable `typ` header verification.
* **v1.8.13 -** Enabled Postgres deployment customization via the Validator CRD.
* **v1.8.14 -** Updated Postgres deployment strategy to support rolling updates.
{% hint style="warning" %}
Since **v1.8.4** the license key can be passed as a secret, please update your values.yaml with the respective values.
{% endhint %}
```yaml
licenseKey:
key: "" # Set licenseKey if NOT using a Kubernetes secret
secret:
enabled: false # Set to 'true' to use a Kubernetes Secret
name: "" # Name of the Kubernetes secret
key: "" # Key inside the secret that contains licenseKey
```
Version 1.7
**What’s new**
* **Validator Identity Dump Management** - CatalyX now allows users to generate identity dumps for validator nodes directly from the UI. These dumps are stored as Kubernetes secrets within the cluster, enabling secure and persistent identity management.
* **Validator Recreation from Identity Dumps** - Validators can now be safely deleted and later recreated using their previously stored identity dumps, preserving node identity across lifecycle operations and reducing redeployment overhead.
**Improvements**
* **Stability & Maintenance Fixes** - Includes minor backend and UI fixes to enhance system reliability and user experience. Version 1.6
**What’s new**
* **Validator Lifecycle Management** - CatalyX now supports the deployment and operational management of Canton validator nodes directly from the UI, enabling users to provision, monitor, and maintain validator infrastructure with minimal manual intervention.
* **Wallet Operations Interface** - Introduced a dedicated interface for Canton wallet management, allowing users to operate their wallets more securely and efficiently.
**Improvements**
* **One-Click Health Data Export** - Users can now generate and download comprehensive health dumps for both participants and domains in a single action, simplifying diagnostics and support workflows.
* **Stability & Usability Enhancements** - Includes various minor fixes and refinements to improve overall stability and user experience.
Version 1.5
**What’s new**
* **Scheduled Backup Support** CatalyX now enables automated scheduling of backups for both domains and participants. This ensures regular state snapshots and enhances disaster recovery readiness with minimal manual oversight.
* **Embedded Cluster Monitoring Dashboard** A built-in dashboard has been introduced for real-time observability of cluster health. This provides a consolidated view of node status, resource usage, and system metrics directly within the CatalyX interface.
* **Direct Node Health Dump Downloads** Users can now download health dump files directly from individual nodes, streamlining diagnostics and enabling faster support workflows.
**Improvements**
* **Runtime Log Level Management** It is now possible to dynamically adjust the log level of running nodes without requiring restarts, providing enhanced control during debugging or incident analysis.
* **Topology Update API** A new API has been added to allow live updates to node topology configurations, simplifying the process of managing participant and domain relationships at runtime.
Version 1.4
**What’s new**
* Support for Auth0 as ledger authentication provider
**Improvements**
* Minor security improvements
* Minor UX improvements
Version 1.3
**What’s new**
* Full remote administration of participant and domain nodes
**Improvements**
* See when the next run of the pruning schedule will take place
* Improved node health feedback
Version 1.2
**What’s new**
* Option to enable a PostgreSQL backend for the HTTP JSON API server, for more efficient data caching and improved query performance
* IAM integration for parties created outside of CAT-BM
**Improvements**
* Improved feedback for pruning schedule: Status of last runs, including number of pruned records
* Increased configurability for already running nodes
* UI/UX improvements on Collections and input validation
Version 1.1
**What’s new**
* Role-based access control
* A Web UI for the Daml REPL console
* Pruning: CatalyX now supports pruning leveraging the Canton protocol
**Improvements**
* Improvements for Dars/package management
Version 1.0
**What’s new**
* Intuitive UI for Canton/DAML deployment & operations
* Simplified Canton nodes configuration & bootstrap
* Integrated off-ledger Identity Access Management
* Party & User management
* DAR package management
* Query active contract
* Deploy DAML client applications
***
# Support & Resources
Contact our Support Center or explore the additional resources below to answer any questions you may have about CatalyX Blockchain Manager.
***
# FAQ
This section covers answers to frequently asked questions about CatalyX Blockchain Manager and Canton Network operations.
{% hint style="info" %}
This page is a work in progress. More questions will be added over time.
{% endhint %}
## Backups, Identity Dumps & Retention
What's the difference between a database backup and an Identity Dump (IDDump)?
Database backups protect ledger and database state. Identity Dumps (IDDumps) protect validator identity and cryptographic keys. Both are required for full disaster recovery — neither can substitute for the other.
Learn more: [Validator Backups and Identity Dumps](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/identity-backup-and-recovery)
How long are security and audit logs retained?
30 days on Mainnet (Production), and 7 days on Devnet/Testnet.
Learn more: [Data Retention & Pruning Policy](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/data-retention-and-pruning-policy)
Does ledger pruning delete active data, and does it require downtime?
No to both. Pruning only removes obsolete ledger data that's no longer required for normal operation, and it runs as a scheduled maintenance task without requiring planned validator downtime.
Learn more: [Data Retention & Pruning Policy](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/data-retention-and-pruning-policy)
## Validator Upgrades
How often should I upgrade my validator, and does CatalyX auto-upgrade it?
CatalyX does not automatically upgrade validator nodes. Upgrades follow IntellectEU's validation of each Canton Foundation release before it's recommended for customer environments.
Learn more: [Validator Upgrade Policy and Release Schedule](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/validator-upgrade-policy-and-release-schedule)
Does every upgrade require a migration?
No. Only releases that introduce schema or application changes require a migration; others only update the validator application version.
Learn more: [Validator Upgrade Policy and Release Schedule](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/validator-upgrade-policy-and-release-schedule)
## KMS & Security
Can I use an external KMS (AWS, GCP, Azure) instead of storing validator keys directly?
Yes. Per-validator KMS is supported for storing participant keys with an external key management service.
Learn more: [KMS Integration](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/kms-integration)
## Networking & API
How do I expose the Ledger API for a validator?
Covers enabling gRPC vs. JSON Ledger API access and configuring Keycloak-based token authentication.
Learn more: [Expose Ledger API](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/expose-ledger-api)
Is there a REST API for triggering backups, restores, or pruning instead of using the UI?
Yes. 128 documented endpoints are available, including validator backup, restore, and prune operations.
Learn more: [API Reference](/catalyx-blockchain-manager/canton-network/version-1.11/support-and-resources/api-reference)
## Troubleshooting
Why can't I log into the wallet UI, or why is the Primary Party field showing an error?
See the troubleshooting table for common causes and resolutions.
Learn more: [Parties & Users](/catalyx-blockchain-manager/canton-network/version-1.11/network-and-node-management/parties-and-users)
Why did my DAR upload fail, or why don't templates appear after upload?
See the troubleshooting table for common causes and resolutions.
Learn more: [Upload DARs](/catalyx-blockchain-manager/canton-network/version-1.11/validator-management/dar-management)
# API Reference
REST API reference for the CatalyX Blockchain Manager Canton Console v1.11, covering all 128 endpoints across validators, participants, domains, and more.
## List validators
> Returns Splice validators visible to this CBM, optionally filtered by name substring and/or lifecycle phase, paginated via \`from\` (offset) and \`limit\`. The response also includes the total count of matching validators.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-controller","description":"Create, list, edit and remove Splice validator deployments, and read their configuration and status."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ValidatorFilterResponseDto":{"type":"object","description":"Paginated list of `ValidatorResponseDto` entries plus the total count of validators matching the filter.","properties":{"validators":{"type":"array","items":{"$ref":"#/components/schemas/ValidatorResponseDto"}},"totalCount":{"type":"integer","format":"int64"}}},"ValidatorResponseDto":{"type":"object","description":"Full validator details returned by GET / list endpoints: cluster and participant configuration, app info for validator / wallet / CNS, contact point and optional Keycloak credentials created on first provisioning.","properties":{"appInfoCantonNameService":{"$ref":"#/components/schemas/AppInfoDto"},"appInfoValidator":{"$ref":"#/components/schemas/AppInfoDto"},"appInfoWallet":{"$ref":"#/components/schemas/AppInfoDto"},"application":{"type":"string"},"applicationCantonNameServer":{"type":"string"},"applicationWallet":{"type":"string"},"contactPoint":{"type":"string"},"createdUser":{"$ref":"#/components/schemas/CreatedUserDto"},"customAuth":{"type":"boolean"},"databaseStorage":{"type":"string"},"disabledWallet":{"type":"boolean"},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"exposeLedgerApi":{"type":"boolean"},"imageRepo":{"type":"string"},"imageTag":{"type":"string"},"immutable":{"type":"boolean"},"jsonApiAddress":{"type":"string"},"ledgerApiAddress":{"type":"string"},"validatorApiAddress":{"type":"string"},"migrationId":{"type":"string"},"migrationMigrating":{"type":"boolean"},"name":{"type":"string"},"onboardingSecretName":{"type":"string"},"participant":{"type":"string"},"participantIdentitiesDumpSecretName":{"type":"string"},"participantInfo":{"$ref":"#/components/schemas/AppInfoDto"},"partyId":{"type":"string"},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"postgresPassword":{"type":"string","deprecated":true},"postgresUser":{"type":"string","deprecated":true},"privateJsonApi":{"type":"boolean"},"scanAddress":{"type":"string"},"storageSize":{"type":"string"},"disableProbes":{"type":"boolean"},"topUp":{"$ref":"#/components/schemas/TopUpDto"},"databaseConfig":{"$ref":"#/components/schemas/ValidatorDbConfigDto"},"postgresConfig":{"$ref":"#/components/schemas/PostgresConfigDto"},"walletSweeps":{"type":"array","items":{"$ref":"#/components/schemas/WalletSweepDto"}}}},"AppInfoDto":{"type":"object","description":"Application deployment metadata: container environment variables and resource requirements declared for an individual Canton/Splice application component.","properties":{"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"resources":{"$ref":"#/components/schemas/ResourcesDto"}},"required":["envVars"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}},"CreatedUserDto":{"type":"object","properties":{"id":{"type":"string"},"temporaryPassword":{"type":"string"},"username":{"type":"string"}}},"TopUpDto":{"type":"object","properties":{"enable":{"type":"boolean"},"minTopupInterval":{"type":"string"},"targetThroughput":{"type":"integer","format":"int32"}}},"ValidatorDbConfigDto":{"type":"object","description":"Database configuration for a Splice validator: whether an external Postgres is used and, if so, its connection credentials.","properties":{"external":{"type":"boolean"},"username":{"type":"string"},"password":{"type":"string"},"hostname":{"type":"string"},"port":{"type":"string"}}},"PostgresConfigDto":{"type":"object","description":"Postgres deployment configuration consumed by a participant or domain: container image, JVM args, resources and any extra volumes / volume mounts.","properties":{"args":{"type":"array","items":{"type":"string"}},"image":{"type":"string"},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"volumes":{"type":"array","items":{"$ref":"#/components/schemas/Volume"}},"volumeMounts":{"type":"array","items":{"$ref":"#/components/schemas/VolumeMount"}}}},"Volume":{"type":"object","properties":{"name":{"type":"string"},"emptyDir":{"$ref":"#/components/schemas/EmptyDirVolumeSource"},"configMap":{"$ref":"#/components/schemas/ConfigMapVolumeSource"},"persistentVolumeClaim":{"$ref":"#/components/schemas/PersistentVolumeClaimVolumeSource"},"secret":{"$ref":"#/components/schemas/SecretVolumeSource"},"hostPath":{"$ref":"#/components/schemas/HostPathVolumeSource"}}},"EmptyDirVolumeSource":{"type":"object","properties":{"medium":{"type":"string"},"sizeLimit":{"$ref":"#/components/schemas/Quantity"}}},"Quantity":{"type":"object","properties":{"amount":{"type":"string"},"format":{"type":"string"}}},"ConfigMapVolumeSource":{"type":"object","properties":{"defaultMode":{"type":"integer","format":"int32"},"items":{"type":"array","items":{"$ref":"#/components/schemas/KeyToPath"}},"name":{"type":"string"},"optional":{"type":"boolean"}}},"KeyToPath":{"type":"object","properties":{"key":{"type":"string"},"mode":{"type":"integer","format":"int32"},"path":{"type":"string"}}},"PersistentVolumeClaimVolumeSource":{"type":"object","properties":{"claimName":{"type":"string"},"readOnly":{"type":"boolean"}}},"SecretVolumeSource":{"type":"object","properties":{"defaultMode":{"type":"integer","format":"int32"},"items":{"type":"array","items":{"$ref":"#/components/schemas/KeyToPath"}},"optional":{"type":"boolean"},"secretName":{"type":"string"}}},"HostPathVolumeSource":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"}}},"VolumeMount":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"},"subPath":{"type":"string"},"readOnly":{"type":"boolean"}}},"WalletSweepDto":{"type":"object","properties":{"senderPartyId":{"type":"string","minLength":1},"receiverPartyId":{"type":"string","minLength":1},"maxBalanceUSD":{"type":"string","minLength":1},"minBalanceUSD":{"type":"string","minLength":1},"useTransferPreapproval":{"type":"boolean"}},"required":["maxBalanceUSD","minBalanceUSD","receiverPartyId","senderPartyId","useTransferPreapproval"]}}},"paths":{"/validators":{"get":{"tags":["validator-controller"],"summary":"List validators","description":"Returns Splice validators visible to this CBM, optionally filtered by name substring and/or lifecycle phase, paginated via `from` (offset) and `limit`. The response also includes the total count of matching validators.","operationId":"listValidators","parameters":[{"name":"from","in":"query","description":"Zero-based offset of the first result to return.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"status","in":"query","description":"Filter by validator lifecycle phase.","required":false,"schema":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]}},{"name":"limit","in":"query","description":"Maximum number of results to return.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"name","in":"query","description":"Substring matched against the validator name.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ValidatorFilterResponseDto"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create validator
> Provisions a new Splice validator (participant, validator app, wallet, CNS) and optionally creates the associated Keycloak user when custom auth is not used. The returned payload includes the initial Keycloak credentials for non-custom-auth validators.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-controller","description":"Create, list, edit and remove Splice validator deployments, and read their configuration and status."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ValidatorDto":{"type":"object","description":"Splice validator definition: cluster and participant configuration, container image, auth and database settings used to provision a new validator deployment and convert it to the underlying CRD.","properties":{"auth":{"$ref":"#/components/schemas/ValidatorAuthDto"},"clusterConfig":{"$ref":"#/components/schemas/ClusterConfigDto"},"clusterParticipantConfig":{"$ref":"#/components/schemas/ClusterParticipantConfigDto"},"customAuth":{"type":"boolean"},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"imageRepo":{"type":"string","minLength":1},"imageTag":{"type":"string","minLength":1},"name":{"type":"string","maxLength":33,"minLength":1},"onboardingSecret":{"type":"string"},"participant":{"$ref":"#/components/schemas/AppInfoDto"},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"postgresPassword":{"type":"string","deprecated":true},"postgresUser":{"type":"string","deprecated":true},"databaseConfig":{"$ref":"#/components/schemas/ValidatorDbConfigDto"},"postgresConfig":{"$ref":"#/components/schemas/PostgresConfigDto"}},"required":["clusterConfig","clusterParticipantConfig","imageRepo","imageTag","name","participant"]},"ValidatorAuthDto":{"type":"object","description":"Auth configuration for a Splice validator: per-application OIDC client ids / secrets and the OAuth2 issuer / audience to use.","properties":{"cnsClientId":{"type":"string","description":"Client for the Canton Name Service","minLength":1},"walletClientId":{"type":"string","description":"Client for Wallet application","minLength":1},"ledgerApiClientId":{"type":"string","description":"Client for Validator","minLength":1},"ledgerApiClientSecret":{"type":"string","description":"Secret part of Client Credentials Grant Flow for the Validator client","minLength":1},"walletUser":{"type":"string","description":"User that will access the wallet application and receive rewards","minLength":1},"ledgerApiUser":{"type":"string","description":"Subject of the Validator client","minLength":1},"audience":{"type":"string","description":"Audience claim expected by the clients\n","minLength":1},"oidcAuthorityUrl":{"type":"string"},"oidcConfigUrl":{"type":"string"},"jwksUrl":{"type":"string"}},"required":["audience","cnsClientId","ledgerApiClientId","ledgerApiClientSecret","ledgerApiUser","walletClientId","walletUser"]},"ClusterConfigDto":{"type":"object","description":"Cluster-wide Splice / Canton configuration for a validator: shared DARs, application metadata for validator / wallet / CNS, decentralized synchronizer URL, dev-net flags and JVM options.","properties":{"additionalConfigOther":{"type":"string"},"additionalUsersEnvVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"appDars":{"type":"string"},"appInfoValidator":{"$ref":"#/components/schemas/AppInfoDto"},"appInfoCantonNameService":{"$ref":"#/components/schemas/AppInfoDto"},"appInfoWallet":{"$ref":"#/components/schemas/AppInfoDto"},"contactPoint":{"type":"string"},"decentralizedSynchronizerUrl":{"type":"string"},"defaultJvmOptions":{"type":"string","minLength":1},"devNet":{"type":"boolean"},"disabledWallet":{"type":"boolean"},"extraDomains":{"type":"array","items":{"$ref":"#/components/schemas/ExtraDomainDto"}},"failOnAppVersionMismatch":{"type":"boolean"},"fixedTokens":{"type":"boolean"},"metrics":{"$ref":"#/components/schemas/MetricsDto"},"migrateValidatorParty":{"type":"boolean"},"migration":{"$ref":"#/components/schemas/MigrationDto"},"participantIdentitiesDumpBackup":{"$ref":"#/components/schemas/IdentitiesDumpPeriodicBackupDto"},"participantIdentitiesDumpImport":{"$ref":"#/components/schemas/ParticipantIdentitiesImportDto"},"partyHint":{"type":"string","minLength":1},"pvcVolumeStorageClass":{"type":"string"},"scanAddress":{"type":"string","minLength":1},"svSponsorAddress":{"type":"string","minLength":1},"svValidator":{"type":"boolean"},"topUp":{"$ref":"#/components/schemas/TopUpDto"},"useSequencerConnectionsFromScan":{"type":"boolean"},"walletUserName":{"type":"string"},"scheduledPrune":{"$ref":"#/components/schemas/ScheduledValidatorPruneDto"},"disableProbes":{"type":"boolean"}},"required":["appInfoCantonNameService","appInfoValidator","defaultJvmOptions","migration","partyHint","scanAddress","svSponsorAddress"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"AppInfoDto":{"type":"object","description":"Application deployment metadata: container environment variables and resource requirements declared for an individual Canton/Splice application component.","properties":{"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"resources":{"$ref":"#/components/schemas/ResourcesDto"}},"required":["envVars"]},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}},"ExtraDomainDto":{"type":"object","properties":{"alias":{"type":"string"},"url":{"type":"string"}}},"MetricsDto":{"type":"object","properties":{"enable":{"type":"boolean"},"interval":{"type":"string"},"release":{"type":"string"}}},"MigrationDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32","minimum":0},"migrating":{"type":"boolean"}},"required":["id"]},"IdentitiesDumpPeriodicBackupDto":{"type":"object","properties":{"backupInterval":{"type":"string","minLength":1},"locationBucketName":{"type":"string","minLength":1},"locationBucketProjectId":{"type":"string","minLength":1},"locationBucketSecretName":{"type":"string","minLength":1},"locationPrefix":{"type":"string"}},"required":["backupInterval","locationBucketName","locationBucketProjectId","locationBucketSecretName","locationPrefix"]},"ParticipantIdentitiesImportDto":{"type":"object","properties":{"identitiesSecretName":{"type":"string","description":"The name of the secret participant identities backup file dump.","minLength":1},"newParticipantIdentifier":{"type":"string","minLength":1}},"required":["identitiesSecretName","newParticipantIdentifier"]},"TopUpDto":{"type":"object","properties":{"enable":{"type":"boolean"},"minTopupInterval":{"type":"string"},"targetThroughput":{"type":"integer","format":"int32"}}},"ScheduledValidatorPruneDto":{"type":"object","properties":{"cron":{"type":"string"},"maxDuration":{"type":"string"},"retention":{"type":"string"},"nextRun":{"type":"string"}},"required":["cron","maxDuration","retention"]},"ClusterParticipantConfigDto":{"type":"object","description":"Participant-side cluster configuration: JVM options, KMS settings, exposure of the ledger / JSON API and node identifier.","properties":{"defaultJvmOptions":{"type":"string","deprecated":true},"enableHealthProbes":{"type":"boolean","deprecated":true},"nodeIdentifier":{"type":"string"},"exposeLedgerApi":{"type":"boolean"},"privateJsonApi":{"type":"boolean"},"enableKms":{"type":"boolean"},"kmsValue":{"type":"string"},"kmsServiceAccount":{"type":"string"}}},"ValidatorDbConfigDto":{"type":"object","description":"Database configuration for a Splice validator: whether an external Postgres is used and, if so, its connection credentials.","properties":{"external":{"type":"boolean"},"username":{"type":"string"},"password":{"type":"string"},"hostname":{"type":"string"},"port":{"type":"string"}}},"PostgresConfigDto":{"type":"object","description":"Postgres deployment configuration consumed by a participant or domain: container image, JVM args, resources and any extra volumes / volume mounts.","properties":{"args":{"type":"array","items":{"type":"string"}},"image":{"type":"string"},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"volumes":{"type":"array","items":{"$ref":"#/components/schemas/Volume"}},"volumeMounts":{"type":"array","items":{"$ref":"#/components/schemas/VolumeMount"}}}},"Volume":{"type":"object","properties":{"name":{"type":"string"},"emptyDir":{"$ref":"#/components/schemas/EmptyDirVolumeSource"},"configMap":{"$ref":"#/components/schemas/ConfigMapVolumeSource"},"persistentVolumeClaim":{"$ref":"#/components/schemas/PersistentVolumeClaimVolumeSource"},"secret":{"$ref":"#/components/schemas/SecretVolumeSource"},"hostPath":{"$ref":"#/components/schemas/HostPathVolumeSource"}}},"EmptyDirVolumeSource":{"type":"object","properties":{"medium":{"type":"string"},"sizeLimit":{"$ref":"#/components/schemas/Quantity"}}},"Quantity":{"type":"object","properties":{"amount":{"type":"string"},"format":{"type":"string"}}},"ConfigMapVolumeSource":{"type":"object","properties":{"defaultMode":{"type":"integer","format":"int32"},"items":{"type":"array","items":{"$ref":"#/components/schemas/KeyToPath"}},"name":{"type":"string"},"optional":{"type":"boolean"}}},"KeyToPath":{"type":"object","properties":{"key":{"type":"string"},"mode":{"type":"integer","format":"int32"},"path":{"type":"string"}}},"PersistentVolumeClaimVolumeSource":{"type":"object","properties":{"claimName":{"type":"string"},"readOnly":{"type":"boolean"}}},"SecretVolumeSource":{"type":"object","properties":{"defaultMode":{"type":"integer","format":"int32"},"items":{"type":"array","items":{"$ref":"#/components/schemas/KeyToPath"}},"optional":{"type":"boolean"},"secretName":{"type":"string"}}},"HostPathVolumeSource":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"}}},"VolumeMount":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"},"subPath":{"type":"string"},"readOnly":{"type":"boolean"}}},"ValidatorResponseDto":{"type":"object","description":"Full validator details returned by GET / list endpoints: cluster and participant configuration, app info for validator / wallet / CNS, contact point and optional Keycloak credentials created on first provisioning.","properties":{"appInfoCantonNameService":{"$ref":"#/components/schemas/AppInfoDto"},"appInfoValidator":{"$ref":"#/components/schemas/AppInfoDto"},"appInfoWallet":{"$ref":"#/components/schemas/AppInfoDto"},"application":{"type":"string"},"applicationCantonNameServer":{"type":"string"},"applicationWallet":{"type":"string"},"contactPoint":{"type":"string"},"createdUser":{"$ref":"#/components/schemas/CreatedUserDto"},"customAuth":{"type":"boolean"},"databaseStorage":{"type":"string"},"disabledWallet":{"type":"boolean"},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"exposeLedgerApi":{"type":"boolean"},"imageRepo":{"type":"string"},"imageTag":{"type":"string"},"immutable":{"type":"boolean"},"jsonApiAddress":{"type":"string"},"ledgerApiAddress":{"type":"string"},"validatorApiAddress":{"type":"string"},"migrationId":{"type":"string"},"migrationMigrating":{"type":"boolean"},"name":{"type":"string"},"onboardingSecretName":{"type":"string"},"participant":{"type":"string"},"participantIdentitiesDumpSecretName":{"type":"string"},"participantInfo":{"$ref":"#/components/schemas/AppInfoDto"},"partyId":{"type":"string"},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"postgresPassword":{"type":"string","deprecated":true},"postgresUser":{"type":"string","deprecated":true},"privateJsonApi":{"type":"boolean"},"scanAddress":{"type":"string"},"storageSize":{"type":"string"},"disableProbes":{"type":"boolean"},"topUp":{"$ref":"#/components/schemas/TopUpDto"},"databaseConfig":{"$ref":"#/components/schemas/ValidatorDbConfigDto"},"postgresConfig":{"$ref":"#/components/schemas/PostgresConfigDto"},"walletSweeps":{"type":"array","items":{"$ref":"#/components/schemas/WalletSweepDto"}}}},"CreatedUserDto":{"type":"object","properties":{"id":{"type":"string"},"temporaryPassword":{"type":"string"},"username":{"type":"string"}}},"WalletSweepDto":{"type":"object","properties":{"senderPartyId":{"type":"string","minLength":1},"receiverPartyId":{"type":"string","minLength":1},"maxBalanceUSD":{"type":"string","minLength":1},"minBalanceUSD":{"type":"string","minLength":1},"useTransferPreapproval":{"type":"boolean"}},"required":["maxBalanceUSD","minBalanceUSD","receiverPartyId","senderPartyId","useTransferPreapproval"]}}},"paths":{"/validators":{"post":{"tags":["validator-controller"],"summary":"Create validator","description":"Provisions a new Splice validator (participant, validator app, wallet, CNS) and optionally creates the associated Keycloak user when custom auth is not used. The returned payload includes the initial Keycloak credentials for non-custom-auth validators.","operationId":"createValidator","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ValidatorResponseDto"}}}},"400":{"description":"Validator payload is invalid or references unknown resources.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"409":{"description":"A validator with the same name already exists.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ValidatorResponseDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Update validator
> Applies an in-place edit to an existing validator (image, env vars, overrides, database/wallet settings, etc.). Immutable fields cannot be changed and validators marked as \`disableUserEdit\` reject updates.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-controller","description":"Create, list, edit and remove Splice validator deployments, and read their configuration and status."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ValidatorEditDto":{"type":"object","description":"Partial update payload for a Splice validator. Non-null fields replace the corresponding section of the existing validator; null fields are left unchanged. Includes a `cleanRestoreData` flag and toggles for ledger-API exposure.","properties":{"clusterConfig":{"$ref":"#/components/schemas/ClusterConfigEditDto"},"imageRepo":{"type":"string"},"imageTag":{"type":"string"},"name":{"type":"string"},"databaseStorage":{"type":"string"},"participant":{"$ref":"#/components/schemas/AppInfoEditDto"},"cleanRestoreData":{"type":"boolean"},"exposeLedgerApi":{"type":"boolean"},"privateJsonApi":{"type":"boolean"},"databaseConfig":{"$ref":"#/components/schemas/ValidatorDbConfigDto"},"postgresConfig":{"$ref":"#/components/schemas/PostgresConfigDto"}}},"ClusterConfigEditDto":{"type":"object","properties":{"scanAddress":{"type":"string"},"contactPoint":{"type":"string"},"migration":{"$ref":"#/components/schemas/MigrationDto"},"topUp":{"$ref":"#/components/schemas/TopUpDto"},"appInfoValidator":{"$ref":"#/components/schemas/AppInfoEditDto"},"appInfoCantonNameService":{"$ref":"#/components/schemas/AppInfoEditDto"},"appInfoWallet":{"$ref":"#/components/schemas/AppInfoEditDto"},"disableProbes":{"type":"boolean"},"walletSweeps":{"type":"array","items":{"$ref":"#/components/schemas/WalletSweepDto"}}},"required":["migration"]},"MigrationDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32","minimum":0},"migrating":{"type":"boolean"}},"required":["id"]},"TopUpDto":{"type":"object","properties":{"enable":{"type":"boolean"},"minTopupInterval":{"type":"string"},"targetThroughput":{"type":"integer","format":"int32"}}},"AppInfoEditDto":{"type":"object","description":"Partial update payload for an application component's deployment metadata; non-null fields replace the existing values and `envVarsDelete` removes specific variables.","properties":{"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"envVarsDelete":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"resources":{"$ref":"#/components/schemas/ResourcesDto"}}},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}},"WalletSweepDto":{"type":"object","properties":{"senderPartyId":{"type":"string","minLength":1},"receiverPartyId":{"type":"string","minLength":1},"maxBalanceUSD":{"type":"string","minLength":1},"minBalanceUSD":{"type":"string","minLength":1},"useTransferPreapproval":{"type":"boolean"}},"required":["maxBalanceUSD","minBalanceUSD","receiverPartyId","senderPartyId","useTransferPreapproval"]},"ValidatorDbConfigDto":{"type":"object","description":"Database configuration for a Splice validator: whether an external Postgres is used and, if so, its connection credentials.","properties":{"external":{"type":"boolean"},"username":{"type":"string"},"password":{"type":"string"},"hostname":{"type":"string"},"port":{"type":"string"}}},"PostgresConfigDto":{"type":"object","description":"Postgres deployment configuration consumed by a participant or domain: container image, JVM args, resources and any extra volumes / volume mounts.","properties":{"args":{"type":"array","items":{"type":"string"}},"image":{"type":"string"},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"volumes":{"type":"array","items":{"$ref":"#/components/schemas/Volume"}},"volumeMounts":{"type":"array","items":{"$ref":"#/components/schemas/VolumeMount"}}}},"Volume":{"type":"object","properties":{"name":{"type":"string"},"emptyDir":{"$ref":"#/components/schemas/EmptyDirVolumeSource"},"configMap":{"$ref":"#/components/schemas/ConfigMapVolumeSource"},"persistentVolumeClaim":{"$ref":"#/components/schemas/PersistentVolumeClaimVolumeSource"},"secret":{"$ref":"#/components/schemas/SecretVolumeSource"},"hostPath":{"$ref":"#/components/schemas/HostPathVolumeSource"}}},"EmptyDirVolumeSource":{"type":"object","properties":{"medium":{"type":"string"},"sizeLimit":{"$ref":"#/components/schemas/Quantity"}}},"Quantity":{"type":"object","properties":{"amount":{"type":"string"},"format":{"type":"string"}}},"ConfigMapVolumeSource":{"type":"object","properties":{"defaultMode":{"type":"integer","format":"int32"},"items":{"type":"array","items":{"$ref":"#/components/schemas/KeyToPath"}},"name":{"type":"string"},"optional":{"type":"boolean"}}},"KeyToPath":{"type":"object","properties":{"key":{"type":"string"},"mode":{"type":"integer","format":"int32"},"path":{"type":"string"}}},"PersistentVolumeClaimVolumeSource":{"type":"object","properties":{"claimName":{"type":"string"},"readOnly":{"type":"boolean"}}},"SecretVolumeSource":{"type":"object","properties":{"defaultMode":{"type":"integer","format":"int32"},"items":{"type":"array","items":{"$ref":"#/components/schemas/KeyToPath"}},"optional":{"type":"boolean"},"secretName":{"type":"string"}}},"HostPathVolumeSource":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"}}},"VolumeMount":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"},"subPath":{"type":"string"},"readOnly":{"type":"boolean"}}}}},"paths":{"/validators":{"put":{"tags":["validator-controller"],"summary":"Update validator","description":"Applies an in-place edit to an existing validator (image, env vars, overrides, database/wallet settings, etc.). Immutable fields cannot be changed and validators marked as `disableUserEdit` reject updates.","operationId":"updateValidator","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorEditDto"}}},"required":true},"responses":{"200":{"description":"OK"},"400":{"description":"The validator edit payload is invalid or attempts to change immutable fields.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No validator exists with the name referenced in the payload."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Get validator pruning schedule
> Returns the validator's current pruning configuration (cron, retention, max duration) and the computed next run timestamp. Returns an empty DTO when no schedule is set.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-prune-controller","description":"Run pruning on a validator and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledValidatorPruneDto":{"type":"object","properties":{"cron":{"type":"string"},"maxDuration":{"type":"string"},"retention":{"type":"string"},"nextRun":{"type":"string"}},"required":["cron","maxDuration","retention"]}}},"paths":{"/validators/{name}/prune":{"get":{"tags":["validator-prune-controller"],"summary":"Get validator pruning schedule","description":"Returns the validator's current pruning configuration (cron, retention, max duration) and the computed next run timestamp. Returns an empty DTO when no schedule is set.","operationId":"getValidatorPruningSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorPruneDto"}}}},"400":{"description":"The supplied validator name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No validator exists with the given name.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorPruneDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create validator pruning schedule
> Enables a cron-based ledger pruning schedule on the validator. Fails if a pruning schedule is already configured; use PUT to modify an existing one.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-prune-controller","description":"Run pruning on a validator and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledValidatorPruneDto":{"type":"object","properties":{"cron":{"type":"string"},"maxDuration":{"type":"string"},"retention":{"type":"string"},"nextRun":{"type":"string"}},"required":["cron","maxDuration","retention"]}}},"paths":{"/validators/{name}/prune":{"post":{"tags":["validator-prune-controller"],"summary":"Create validator pruning schedule","description":"Enables a cron-based ledger pruning schedule on the validator. Fails if a pruning schedule is already configured; use PUT to modify an existing one.","operationId":"createValidatorPruningSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorPruneDto"}}},"required":true},"responses":{"201":{"description":"Created"},"400":{"description":"The pruning schedule payload is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No validator exists with the given name."},"409":{"description":"A pruning schedule already exists for this validator."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Update validator pruning schedule
> Replaces the cron expression, retention and max-duration of the validator's existing pruning schedule. Fails if no schedule has been configured yet.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-prune-controller","description":"Run pruning on a validator and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledValidatorPruneDto":{"type":"object","properties":{"cron":{"type":"string"},"maxDuration":{"type":"string"},"retention":{"type":"string"},"nextRun":{"type":"string"}},"required":["cron","maxDuration","retention"]}}},"paths":{"/validators/{name}/prune":{"put":{"tags":["validator-prune-controller"],"summary":"Update validator pruning schedule","description":"Replaces the cron expression, retention and max-duration of the validator's existing pruning schedule. Fails if no schedule has been configured yet.","operationId":"updateValidatorPruningSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorPruneDto"}}},"required":true},"responses":{"204":{"description":"No Content"},"400":{"description":"The pruning schedule payload is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"The validator does not exist or has no pruning schedule configured."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Delete validator pruning schedule
> Removes the configured pruning schedule from the validator. Idempotent: succeeds with no-op if no schedule is currently set.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-prune-controller","description":"Run pruning on a validator and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/validators/{name}/prune":{"delete":{"tags":["validator-prune-controller"],"summary":"Delete validator pruning schedule","description":"Removes the configured pruning schedule from the validator. Idempotent: succeeds with no-op if no schedule is currently set.","operationId":"deleteValidatorPruningSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"The supplied validator name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No validator exists with the given name."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create validator backup schedule
> Creates a scheduled (cron-based) database backup job for the validator's internal Postgres. Reactivates the schedule if it was previously soft-deleted. Not supported for validators backed by an external database.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-backup-controller","description":"Trigger validator backups, browse backup history and manage scheduled validator backups."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ValidatorBackupDto":{"type":"object","description":"Request body to trigger or schedule a Splice validator backup: cron expression and retention limit.","properties":{"cron":{"type":"string"},"maxBackups":{"type":"integer","format":"int32","maximum":84,"minimum":2}},"required":["maxBackups"]},"ScheduledValidatorBackupDto":{"type":"object","description":"Persisted backup schedule for a Splice validator: cron expression, retention limit and next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxBackups":{"type":"integer","format":"int32"},"nextRun":{"type":"string"}},"required":["cron"]}}},"paths":{"/validators/{name}/backup":{"post":{"tags":["validator-backup-controller"],"summary":"Create validator backup schedule","description":"Creates a scheduled (cron-based) database backup job for the validator's internal Postgres. Reactivates the schedule if it was previously soft-deleted. Not supported for validators backed by an external database.","operationId":"createBackupSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorBackupDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorBackupDto"}}}},"400":{"description":"The backup schedule payload is invalid or the validator uses an external database.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No validator exists with the given name.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorBackupDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}},"503":{"description":"Validator database is not running so a backup cannot be scheduled.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorBackupDto"}}}}}}}}}
```
## Get validator backup schedule
> Returns the current backup schedule for the validator, including the cron expression and the computed unix timestamp of the next planned run.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-backup-controller","description":"Trigger validator backups, browse backup history and manage scheduled validator backups."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledValidatorBackupDto":{"type":"object","description":"Persisted backup schedule for a Splice validator: cron expression, retention limit and next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxBackups":{"type":"integer","format":"int32"},"nextRun":{"type":"string"}},"required":["cron"]}}},"paths":{"/validators/{name}/backup":{"get":{"tags":["validator-backup-controller"],"summary":"Get validator backup schedule","description":"Returns the current backup schedule for the validator, including the cron expression and the computed unix timestamp of the next planned run.","operationId":"getBackupSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorBackupDto"}}}},"400":{"description":"The supplied validator name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No validator or backup schedule exists for the given name.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorBackupDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Update validator backup schedule
> Replaces the cron expression and retention settings on the validator's backup schedule. Also clears the soft-deleted flag, effectively reactivating a paused schedule.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-backup-controller","description":"Trigger validator backups, browse backup history and manage scheduled validator backups."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ValidatorBackupDto":{"type":"object","description":"Request body to trigger or schedule a Splice validator backup: cron expression and retention limit.","properties":{"cron":{"type":"string"},"maxBackups":{"type":"integer","format":"int32","maximum":84,"minimum":2}},"required":["maxBackups"]},"ScheduledValidatorBackupDto":{"type":"object","description":"Persisted backup schedule for a Splice validator: cron expression, retention limit and next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxBackups":{"type":"integer","format":"int32"},"nextRun":{"type":"string"}},"required":["cron"]}}},"paths":{"/validators/{name}/backup":{"put":{"tags":["validator-backup-controller"],"summary":"Update validator backup schedule","description":"Replaces the cron expression and retention settings on the validator's backup schedule. Also clears the soft-deleted flag, effectively reactivating a paused schedule.","operationId":"updateBackupSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorBackupDto"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorBackupDto"}}}},"400":{"description":"The backup schedule payload is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No backup schedule exists for the given validator.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorBackupDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Delete validator backup schedule
> Soft-deletes the validator's backup schedule so that no further backups run. The schedule resource is retained and can be reactivated by re-issuing a POST.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-backup-controller","description":"Trigger validator backups, browse backup history and manage scheduled validator backups."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/validators/{name}/backup":{"delete":{"tags":["validator-backup-controller"],"summary":"Delete validator backup schedule","description":"Soft-deletes the validator's backup schedule so that no further backups run. The schedule resource is retained and can be reactivated by re-issuing a POST.","operationId":"deleteBackupSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"The supplied validator name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No backup schedule exists for the given validator."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## List remote participants with filters
> Returns a paginated list of CBM-side remote participant registrations, optionally filtered by health status, lifecycle phase, or name substring. The result also includes the total count of registrations matching the filters.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-controller","description":"Register and manage externally-hosted Canton participants reachable from this CBM instance."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RemoteParticipantFilterResponseDto":{"type":"object","description":"Paginated list of `RemoteParticipantDto` entries plus the total count.","properties":{"participants":{"type":"array","items":{"$ref":"#/components/schemas/RemoteParticipantDto"}},"totalCount":{"type":"integer","format":"int64"}}},"RemoteParticipantDto":{"type":"object","description":"Externally-hosted Canton participant registered in CBM: admin / ledger / JSON-API endpoints, auth provider and identifying metadata.","properties":{"adminAddress":{"type":"string","minLength":1},"adminPort":{"type":"string","minLength":1},"authProvider":{"type":"string","enum":["keycloak","auth0","custom"]},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"jsonApiUrl":{"type":"string","minLength":1},"ledgerAddress":{"type":"string","minLength":1},"ledgerId":{"type":"string","minLength":1},"ledgerPort":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"v3":{"type":"boolean"}},"required":["adminAddress","adminPort","authProvider","image","jsonApiUrl","ledgerAddress","ledgerId","ledgerPort","name"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}}}},"paths":{"/remote-participants":{"get":{"tags":["remote-participant-controller"],"summary":"List remote participants with filters","description":"Returns a paginated list of CBM-side remote participant registrations, optionally filtered by health status, lifecycle phase, or name substring. The result also includes the total count of registrations matching the filters.","operationId":"listRemoteParticipants","parameters":[{"name":"healthStatus","in":"query","description":"If set, only return participants whose last known health check matches this value.","required":false,"schema":{"type":"boolean"}},{"name":"from","in":"query","description":"Zero-based index of the first registration to return.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"status","in":"query","description":"Lifecycle phase to filter by (e.g. RUNNING, FAILED).","required":false,"schema":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]}},{"name":"limit","in":"query","description":"Maximum number of registrations to return.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"name","in":"query","description":"Case-sensitive substring matched against the registration name.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RemoteParticipantFilterResponseDto"}}}},"400":{"description":"Pagination or filter parameters are invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Register a remote participant
> Creates a CBM-side registration for a Canton participant node that runs outside the cluster. Only configuration metadata (endpoints, auth provider, resources) is stored; the remote workload itself is not provisioned by CBM.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-controller","description":"Register and manage externally-hosted Canton participants reachable from this CBM instance."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RemoteParticipantDto":{"type":"object","description":"Externally-hosted Canton participant registered in CBM: admin / ledger / JSON-API endpoints, auth provider and identifying metadata.","properties":{"adminAddress":{"type":"string","minLength":1},"adminPort":{"type":"string","minLength":1},"authProvider":{"type":"string","enum":["keycloak","auth0","custom"]},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"jsonApiUrl":{"type":"string","minLength":1},"ledgerAddress":{"type":"string","minLength":1},"ledgerId":{"type":"string","minLength":1},"ledgerPort":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"v3":{"type":"boolean"}},"required":["adminAddress","adminPort","authProvider","image","jsonApiUrl","ledgerAddress","ledgerId","ledgerPort","name"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}}}},"paths":{"/remote-participants":{"post":{"tags":["remote-participant-controller"],"summary":"Register a remote participant","description":"Creates a CBM-side registration for a Canton participant node that runs outside the cluster. Only configuration metadata (endpoints, auth provider, resources) is stored; the remote workload itself is not provisioned by CBM.","operationId":"createRemoteParticipant","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoteParticipantDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RemoteParticipantDto"}}}},"400":{"description":"The request payload failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"409":{"description":"A remote participant with the same name is already registered in CBM.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RemoteParticipantDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Update a remote participant registration
> Updates the CBM-side configuration (endpoints, auth provider, resources) for an existing remote participant. The remote Canton node is not reconfigured by this call.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-controller","description":"Register and manage externally-hosted Canton participants reachable from this CBM instance."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RemoteParticipantDto":{"type":"object","description":"Externally-hosted Canton participant registered in CBM: admin / ledger / JSON-API endpoints, auth provider and identifying metadata.","properties":{"adminAddress":{"type":"string","minLength":1},"adminPort":{"type":"string","minLength":1},"authProvider":{"type":"string","enum":["keycloak","auth0","custom"]},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"jsonApiUrl":{"type":"string","minLength":1},"ledgerAddress":{"type":"string","minLength":1},"ledgerId":{"type":"string","minLength":1},"ledgerPort":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"v3":{"type":"boolean"}},"required":["adminAddress","adminPort","authProvider","image","jsonApiUrl","ledgerAddress","ledgerId","ledgerPort","name"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}}}},"paths":{"/remote-participants":{"put":{"tags":["remote-participant-controller"],"summary":"Update a remote participant registration","description":"Updates the CBM-side configuration (endpoints, auth provider, resources) for an existing remote participant. The remote Canton node is not reconfigured by this call.","operationId":"updateRemoteParticipant","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoteParticipantDto"}}},"required":true},"responses":{"200":{"description":"OK"},"400":{"description":"The request payload failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote participant is registered under the given name."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Connects/Disconnects an already registered domain to a participant
> Proxies an admin-API call to the remote participant to toggle the connection state of a previously registered domain. Use the connect query flag to choose between connect and disconnect.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-connection-controller","description":"Configure, register, connect and disconnect a remote Canton participant against one of its sync domains."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/remote-participants/{name}/connections/{domainAlias}":{"put":{"tags":["remote-participant-connection-controller"],"summary":"Connects/Disconnects an already registered domain to a participant","description":"Proxies an admin-API call to the remote participant to toggle the connection state of a previously registered domain. Use the connect query flag to choose between connect and disconnect.","operationId":"updateRemoteParticipantConnection","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"domainAlias","in":"path","description":"Alias of the domain connection already registered on the participant.","required":true,"schema":{"type":"string"}},{"name":"connect","in":"query","description":"true to connect, false to disconnect","required":true,"schema":{"type":"boolean","description":"true to connect, false to disconnect"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"The participant name or domain alias is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"Either the participant is not registered in CBM or the domain alias is unknown on the remote node."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## List remote domains with filtering and pagination
> Returns the CBM-registered remote domains, optionally filtered by health status, lifecycle phase or name. Pagination is controlled via the from/limit query parameters. This call reads local registration metadata and does not query the remote nodes.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-domain-controller","description":"Register and manage externally-hosted Canton sync domains reachable from this CBM instance."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RemoteDomainFilterResponseDto":{"type":"object","description":"Paginated list of `RemoteDomainDto` entries plus the total count.","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/RemoteDomainDto"}},"totalCount":{"type":"integer","format":"int64"}}},"RemoteDomainDto":{"type":"object","description":"Externally-hosted sync domain registered in CBM: admin / public endpoints, image metadata and lifecycle phase.","properties":{"adminAddress":{"type":"string","minLength":1},"adminPort":{"type":"string","minLength":1},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"publicAddress":{"type":"string","minLength":1},"publicPort":{"type":"string","minLength":1},"resources":{"$ref":"#/components/schemas/ResourcesDto"}},"required":["adminAddress","adminPort","image","name","publicAddress","publicPort"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}}}},"paths":{"/remote-domains":{"get":{"tags":["remote-domain-controller"],"summary":"List remote domains with filtering and pagination","description":"Returns the CBM-registered remote domains, optionally filtered by health status, lifecycle phase or name. Pagination is controlled via the from/limit query parameters. This call reads local registration metadata and does not query the remote nodes.","operationId":"listRemoteDomains","parameters":[{"name":"healthStatus","in":"query","description":"If set, returns only remote domains whose last observed health matches this value.","required":false,"schema":{"type":"boolean"}},{"name":"from","in":"query","description":"Zero-based offset of the first remote domain to return.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"status","in":"query","description":"Lifecycle phase to filter by (e.g. running, failed).","required":false,"schema":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]}},{"name":"limit","in":"query","description":"Maximum number of remote domains to return.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"name","in":"query","description":"Case-insensitive substring filter on the remote domain registration name.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RemoteDomainFilterResponseDto"}}}},"400":{"description":"One of the query parameters has an invalid value.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Register a remote domain
> Stores CBM-side registration metadata for a Canton sync domain that runs outside this cluster. The remote domain workload itself is not created here; CBM only tracks the connection details so subsequent operations can be proxied to it.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-domain-controller","description":"Register and manage externally-hosted Canton sync domains reachable from this CBM instance."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RemoteDomainDto":{"type":"object","description":"Externally-hosted sync domain registered in CBM: admin / public endpoints, image metadata and lifecycle phase.","properties":{"adminAddress":{"type":"string","minLength":1},"adminPort":{"type":"string","minLength":1},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"publicAddress":{"type":"string","minLength":1},"publicPort":{"type":"string","minLength":1},"resources":{"$ref":"#/components/schemas/ResourcesDto"}},"required":["adminAddress","adminPort","image","name","publicAddress","publicPort"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}}}},"paths":{"/remote-domains":{"post":{"tags":["remote-domain-controller"],"summary":"Register a remote domain","description":"Stores CBM-side registration metadata for a Canton sync domain that runs outside this cluster. The remote domain workload itself is not created here; CBM only tracks the connection details so subsequent operations can be proxied to it.","operationId":"createRemoteDomain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoteDomainDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RemoteDomainDto"}}}},"400":{"description":"Invalid registration payload.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"409":{"description":"A node with the same name is already registered or running in the cluster.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RemoteDomainDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Update a remote domain registration
> Updates the CBM-side connection metadata (addresses, ports, image, resources) for a previously registered remote domain. The remote node itself is not modified by this call.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-domain-controller","description":"Register and manage externally-hosted Canton sync domains reachable from this CBM instance."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RemoteDomainDto":{"type":"object","description":"Externally-hosted sync domain registered in CBM: admin / public endpoints, image metadata and lifecycle phase.","properties":{"adminAddress":{"type":"string","minLength":1},"adminPort":{"type":"string","minLength":1},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"publicAddress":{"type":"string","minLength":1},"publicPort":{"type":"string","minLength":1},"resources":{"$ref":"#/components/schemas/ResourcesDto"}},"required":["adminAddress","adminPort","image","name","publicAddress","publicPort"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}}}},"paths":{"/remote-domains":{"put":{"tags":["remote-domain-controller"],"summary":"Update a remote domain registration","description":"Updates the CBM-side connection metadata (addresses, ports, image, resources) for a previously registered remote domain. The remote node itself is not modified by this call.","operationId":"updateRemoteDomain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoteDomainDto"}}},"required":true},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid update payload.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote domain is registered under the given name."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## List participants
> Returns the paginated list of participants matching the given filters along with the total count of matches (ignoring pagination). All filter parameters are optional and combined with AND semantics.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-controller","description":"Create, list, edit and remove Canton participant deployments, and read their configuration."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ParticipantFilterResponseDto":{"type":"object","description":"Paginated list of `ParticipantDto` entries plus the total count of participants matching the filter.","properties":{"participants":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantDto"}},"totalCount":{"type":"integer","format":"int64"}}},"ParticipantDto":{"type":"object","description":"Canton participant definition: container image, admin / ledger endpoints, authentication, postgres storage and Canton-specific settings used to provision a new participant deployment.","properties":{"adminAddress":{"type":"string"},"adminPort":{"type":"string","minLength":1},"auth":{"type":"boolean"},"authProvider":{"type":"string","enum":["keycloak","auth0","custom"]},"authorization":{"$ref":"#/components/schemas/AuthorizationDto"},"bootstrap":{"type":"string"},"daemon":{"type":"boolean"},"enterprise":{"type":"boolean","description":"Whether the canton image is enterprise or not"},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"jsonapi":{"type":"boolean"},"jsonapiImage":{"type":"string"},"privateJsonapi":{"type":"boolean"},"jsonapiQueryStore":{"type":"boolean"},"exposeLedgerApi":{"type":"boolean"},"ledgerAddress":{"type":"string"},"ledgerPort":{"type":"string","minLength":1},"logLevel":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR"]},"name":{"type":"string","minLength":1},"navigator":{"type":"boolean"},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"storage":{"$ref":"#/components/schemas/StorageDto"},"topology":{"type":"string"},"validatorParent":{"type":"string"},"enableKms":{"type":"boolean"},"kmsValue":{"type":"string"},"kmsServiceAccount":{"type":"string"}},"required":["adminPort","authProvider","image","ledgerPort","name"]},"AuthorizationDto":{"type":"object","description":"Credential and OIDC client descriptor used to obtain tokens for a Canton participant: client id / secret, username / password and JWKS URL.","properties":{"clientId":{"type":"string"},"clientSecret":{"type":"string"},"jwksUrl":{"type":"string"},"password":{"type":"string"},"username":{"type":"string"},"audience":{"type":"string"}}},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}},"StorageDto":{"type":"object","description":"Persistent storage configuration: type (in-cluster or external Postgres), size, backup size and connection credentials when external.","properties":{"backupSize":{"type":"string"},"hostname":{"type":"string"},"password":{"type":"string"},"port":{"type":"string"},"size":{"type":"string"},"type":{"type":"string","enum":["Memory","Postgres","Shared Postgres","External"]},"user":{"type":"string"}}}}},"paths":{"/participants":{"get":{"tags":["participant-controller"],"summary":"List participants","description":"Returns the paginated list of participants matching the given filters along with the total count of matches (ignoring pagination). All filter parameters are optional and combined with AND semantics.","operationId":"listParticipants","parameters":[{"name":"healthStatus","in":"query","description":"If true, returns only participants reported as healthy; if false, only unhealthy ones.","required":false,"schema":{"type":"boolean"}},{"name":"from","in":"query","description":"Zero-based offset of the first participant to return.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"status","in":"query","description":"Lifecycle phase to filter by (e.g. RUNNING, PENDING, FAILED).","required":false,"schema":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]}},{"name":"limit","in":"query","description":"Maximum number of participants to return.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"name","in":"query","description":"Substring match on the participant Kubernetes resource name.","required":false,"schema":{"type":"string"}},{"name":"storageType","in":"query","description":"Storage backend to filter by (e.g. POSTGRES, EXTERNAL, MEMORY).","required":false,"schema":{"type":"string","enum":["Memory","Postgres","Shared Postgres","External"]}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ParticipantFilterResponseDto"}}}},"400":{"description":"One or more query parameters failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create participant
> Provisions a new Canton participant in this CBM by creating the underlying Kubernetes Custom Resource. When the storage type is EXTERNAL or POSTGRES, a database secret is recreated with the provided credentials. The operation is asynchronous: a 201 response means the resource has been accepted; lifecycle status must be polled via the GET endpoint.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-controller","description":"Create, list, edit and remove Canton participant deployments, and read their configuration."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ParticipantDto":{"type":"object","description":"Canton participant definition: container image, admin / ledger endpoints, authentication, postgres storage and Canton-specific settings used to provision a new participant deployment.","properties":{"adminAddress":{"type":"string"},"adminPort":{"type":"string","minLength":1},"auth":{"type":"boolean"},"authProvider":{"type":"string","enum":["keycloak","auth0","custom"]},"authorization":{"$ref":"#/components/schemas/AuthorizationDto"},"bootstrap":{"type":"string"},"daemon":{"type":"boolean"},"enterprise":{"type":"boolean","description":"Whether the canton image is enterprise or not"},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"jsonapi":{"type":"boolean"},"jsonapiImage":{"type":"string"},"privateJsonapi":{"type":"boolean"},"jsonapiQueryStore":{"type":"boolean"},"exposeLedgerApi":{"type":"boolean"},"ledgerAddress":{"type":"string"},"ledgerPort":{"type":"string","minLength":1},"logLevel":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR"]},"name":{"type":"string","minLength":1},"navigator":{"type":"boolean"},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"storage":{"$ref":"#/components/schemas/StorageDto"},"topology":{"type":"string"},"validatorParent":{"type":"string"},"enableKms":{"type":"boolean"},"kmsValue":{"type":"string"},"kmsServiceAccount":{"type":"string"}},"required":["adminPort","authProvider","image","ledgerPort","name"]},"AuthorizationDto":{"type":"object","description":"Credential and OIDC client descriptor used to obtain tokens for a Canton participant: client id / secret, username / password and JWKS URL.","properties":{"clientId":{"type":"string"},"clientSecret":{"type":"string"},"jwksUrl":{"type":"string"},"password":{"type":"string"},"username":{"type":"string"},"audience":{"type":"string"}}},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}},"StorageDto":{"type":"object","description":"Persistent storage configuration: type (in-cluster or external Postgres), size, backup size and connection credentials when external.","properties":{"backupSize":{"type":"string"},"hostname":{"type":"string"},"password":{"type":"string"},"port":{"type":"string"},"size":{"type":"string"},"type":{"type":"string","enum":["Memory","Postgres","Shared Postgres","External"]},"user":{"type":"string"}}}}},"paths":{"/participants":{"post":{"tags":["participant-controller"],"summary":"Create participant","description":"Provisions a new Canton participant in this CBM by creating the underlying Kubernetes Custom Resource. When the storage type is EXTERNAL or POSTGRES, a database secret is recreated with the provided credentials. The operation is asynchronous: a 201 response means the resource has been accepted; lifecycle status must be polled via the GET endpoint.","operationId":"createParticipant","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ParticipantDto"}}}},"400":{"description":"The participant payload failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"409":{"description":"A participant or backing workload with the same name already exists.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ParticipantDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Update participant
> Applies the supplied configuration to the existing participant Custom Resource. The participant is identified by the name field of the body. The operator picks up the change and rolls the workload asynchronously; this endpoint only acknowledges that the CR has been updated.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-controller","description":"Create, list, edit and remove Canton participant deployments, and read their configuration."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ParticipantDto":{"type":"object","description":"Canton participant definition: container image, admin / ledger endpoints, authentication, postgres storage and Canton-specific settings used to provision a new participant deployment.","properties":{"adminAddress":{"type":"string"},"adminPort":{"type":"string","minLength":1},"auth":{"type":"boolean"},"authProvider":{"type":"string","enum":["keycloak","auth0","custom"]},"authorization":{"$ref":"#/components/schemas/AuthorizationDto"},"bootstrap":{"type":"string"},"daemon":{"type":"boolean"},"enterprise":{"type":"boolean","description":"Whether the canton image is enterprise or not"},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"jsonapi":{"type":"boolean"},"jsonapiImage":{"type":"string"},"privateJsonapi":{"type":"boolean"},"jsonapiQueryStore":{"type":"boolean"},"exposeLedgerApi":{"type":"boolean"},"ledgerAddress":{"type":"string"},"ledgerPort":{"type":"string","minLength":1},"logLevel":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR"]},"name":{"type":"string","minLength":1},"navigator":{"type":"boolean"},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"storage":{"$ref":"#/components/schemas/StorageDto"},"topology":{"type":"string"},"validatorParent":{"type":"string"},"enableKms":{"type":"boolean"},"kmsValue":{"type":"string"},"kmsServiceAccount":{"type":"string"}},"required":["adminPort","authProvider","image","ledgerPort","name"]},"AuthorizationDto":{"type":"object","description":"Credential and OIDC client descriptor used to obtain tokens for a Canton participant: client id / secret, username / password and JWKS URL.","properties":{"clientId":{"type":"string"},"clientSecret":{"type":"string"},"jwksUrl":{"type":"string"},"password":{"type":"string"},"username":{"type":"string"},"audience":{"type":"string"}}},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}},"StorageDto":{"type":"object","description":"Persistent storage configuration: type (in-cluster or external Postgres), size, backup size and connection credentials when external.","properties":{"backupSize":{"type":"string"},"hostname":{"type":"string"},"password":{"type":"string"},"port":{"type":"string"},"size":{"type":"string"},"type":{"type":"string","enum":["Memory","Postgres","Shared Postgres","External"]},"user":{"type":"string"}}}}},"paths":{"/participants":{"put":{"tags":["participant-controller"],"summary":"Update participant","description":"Applies the supplied configuration to the existing participant Custom Resource. The participant is identified by the name field of the body. The operator picks up the change and rolls the workload asynchronously; this endpoint only acknowledges that the CR has been updated.","operationId":"updateParticipant","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantDto"}}},"required":true},"responses":{"200":{"description":"OK"},"400":{"description":"The participant payload failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Connects/Disconnects an already registered domain to a participant
> Toggles the connection state of an existing sync-domain registration on the participant. The domain must already be registered via POST; this endpoint does not modify the connection configuration, only its connected/disconnected state.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"connection-controller","description":"Configure, register, connect and disconnect a Canton participant against one of its sync domains."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/participants/{name}/connections/{domainAlias}":{"put":{"tags":["connection-controller"],"summary":"Connects/Disconnects an already registered domain to a participant","description":"Toggles the connection state of an existing sync-domain registration on the participant. The domain must already be registered via POST; this endpoint does not modify the connection configuration, only its connected/disconnected state.","operationId":"updateParticipantConnection","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant holding the connection.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"domainAlias","in":"path","description":"Alias of the previously registered sync domain to (dis)connect.","required":true,"schema":{"type":"string"}},{"name":"connect","in":"query","description":"true to connect, false to disconnect","required":true,"schema":{"type":"boolean","description":"true to connect, false to disconnect"}},{"name":"port","in":"query","description":"Admin gRPC port on which to contact the participant.","required":false,"schema":{"type":"integer","format":"int32","default":5019}}],"responses":{"204":{"description":"No Content"},"400":{"description":"The participant name, domain alias or port failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No such participant exists or the domain alias is not registered."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Set the runtime log level for a node
> Adjusts the log level used by the Canton node at runtime without restarting the pod. Takes effect immediately for subsequent log output.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"log-controller","description":"Stream pod logs and adjust log levels at runtime for the managed workloads."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/logs/{name}/{level}":{"put":{"tags":["log-controller"],"summary":"Set the runtime log level for a node","description":"Adjusts the log level used by the Canton node at runtime without restarting the pod. Takes effect immediately for subsequent log output.","operationId":"updateLogLevel","parameters":[{"name":"name","in":"path","description":"Name of the Canton node whose log level should be updated","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"level","in":"path","description":"New log level to apply","required":true,"schema":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR"]}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid node name or log level","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"Node or its pod not found"},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Get identity dump schedule
> Returns the current identity dump schedule for the validator along with the computed unix timestamp of the next planned run.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-id-dumps-controller","description":"Trigger and schedule validator identity dump jobs and download their artifacts."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledValidatorIdDumpDto":{"type":"object","description":"Persisted identity-dump schedule for a Splice validator: cron expression, retention limit and next-run timestamp.","properties":{"validatorName":{"type":"string"},"cron":{"type":"string"},"nextRun":{"type":"string"},"maxDumps":{"type":"integer","format":"int32"}}}}},"paths":{"/id-dumps/{validatorName}/schedule":{"get":{"tags":["validator-id-dumps-controller"],"summary":"Get identity dump schedule","description":"Returns the current identity dump schedule for the validator along with the computed unix timestamp of the next planned run.","operationId":"getSchedule","parameters":[{"name":"validatorName","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorIdDumpDto"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No validator or identity dump schedule exists for the given name.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorIdDumpDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create identity dump schedule
> Creates a cron-based schedule that periodically produces identity dumps for the validator, retaining at most \`maxDumps\` of them. Reactivates a soft-deleted schedule if one exists.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-id-dumps-controller","description":"Trigger and schedule validator identity dump jobs and download their artifacts."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ValidatorIdDumpScheduleDto":{"type":"object","description":"Request body to schedule recurring identity dumps for a Splice validator (cron expression plus retention limit); converts to the underlying CRD.","properties":{"cron":{"type":"string"},"maxDumps":{"type":"integer","format":"int32","minimum":1}}},"ScheduledValidatorIdDumpDto":{"type":"object","description":"Persisted identity-dump schedule for a Splice validator: cron expression, retention limit and next-run timestamp.","properties":{"validatorName":{"type":"string"},"cron":{"type":"string"},"nextRun":{"type":"string"},"maxDumps":{"type":"integer","format":"int32"}}}}},"paths":{"/id-dumps/{validatorName}/schedule":{"post":{"tags":["validator-id-dumps-controller"],"summary":"Create identity dump schedule","description":"Creates a cron-based schedule that periodically produces identity dumps for the validator, retaining at most `maxDumps` of them. Reactivates a soft-deleted schedule if one exists.","operationId":"createSchedule","parameters":[{"name":"validatorName","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorIdDumpScheduleDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorIdDumpDto"}}}},"400":{"description":"The schedule payload is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No validator exists with the given name.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorIdDumpDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Update identity dump schedule
> Replaces the cron expression and retention (\`maxDumps\`) of the validator's identity dump schedule. Also clears the soft-deleted flag, reactivating a paused schedule.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-id-dumps-controller","description":"Trigger and schedule validator identity dump jobs and download their artifacts."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ValidatorIdDumpScheduleDto":{"type":"object","description":"Request body to schedule recurring identity dumps for a Splice validator (cron expression plus retention limit); converts to the underlying CRD.","properties":{"cron":{"type":"string"},"maxDumps":{"type":"integer","format":"int32","minimum":1}}},"ScheduledValidatorIdDumpDto":{"type":"object","description":"Persisted identity-dump schedule for a Splice validator: cron expression, retention limit and next-run timestamp.","properties":{"validatorName":{"type":"string"},"cron":{"type":"string"},"nextRun":{"type":"string"},"maxDumps":{"type":"integer","format":"int32"}}}}},"paths":{"/id-dumps/{validatorName}/schedule":{"put":{"tags":["validator-id-dumps-controller"],"summary":"Update identity dump schedule","description":"Replaces the cron expression and retention (`maxDumps`) of the validator's identity dump schedule. Also clears the soft-deleted flag, reactivating a paused schedule.","operationId":"updateSchedule","parameters":[{"name":"validatorName","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorIdDumpScheduleDto"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorIdDumpDto"}}}},"400":{"description":"The schedule payload is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No identity dump schedule exists for the given validator.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledValidatorIdDumpDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Delete identity dump schedule
> Soft-deletes the validator's identity dump schedule so that no further dumps run. The resource is preserved and can be reactivated via POST.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-id-dumps-controller","description":"Trigger and schedule validator identity dump jobs and download their artifacts."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/id-dumps/{validatorName}/schedule":{"delete":{"tags":["validator-id-dumps-controller"],"summary":"Delete identity dump schedule","description":"Soft-deletes the validator's identity dump schedule so that no further dumps run. The resource is preserved and can be reactivated via POST.","operationId":"deleteSchedule","parameters":[{"name":"validatorName","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"The supplied validator name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No identity dump schedule exists for the given validator."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## List sync domains with filtering
> Returns a paginated list of sync domains matching the supplied filters together with the total count of matches. All filter parameters are optional and combined with AND.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"domain-controller","description":"Create, list, edit and remove Canton sync domains, and read their configuration."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DomainFilterResponseDto":{"type":"object","description":"Paginated list of `DomainDto` entries plus the total count of sync domains matching the filter.","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/DomainDto"}},"totalCount":{"type":"integer","format":"int64"}}},"DomainDto":{"type":"object","description":"Canton sync domain definition: name, container image, log level, admin / public endpoints and Canton-specific bootstrap settings used to provision a single-replica sync domain.","properties":{"adminAddress":{"type":"string"},"adminPort":{"type":"string","minLength":1},"bootstrap":{"type":"string"},"daemon":{"type":"boolean"},"enterprise":{"type":"boolean","description":"Whether the canton image is enterprise or not"},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"ingress":{"type":"boolean"},"logLevel":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR"]},"name":{"type":"string","minLength":1},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"publicAddress":{"type":"string"},"publicPort":{"type":"string","minLength":1},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"storage":{"$ref":"#/components/schemas/StorageDto"},"topology":{"type":"string"}},"required":["adminPort","image","name","publicPort"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}},"StorageDto":{"type":"object","description":"Persistent storage configuration: type (in-cluster or external Postgres), size, backup size and connection credentials when external.","properties":{"backupSize":{"type":"string"},"hostname":{"type":"string"},"password":{"type":"string"},"port":{"type":"string"},"size":{"type":"string"},"type":{"type":"string","enum":["Memory","Postgres","Shared Postgres","External"]},"user":{"type":"string"}}}}},"paths":{"/domains":{"get":{"tags":["domain-controller"],"summary":"List sync domains with filtering","description":"Returns a paginated list of sync domains matching the supplied filters together with the total count of matches. All filter parameters are optional and combined with AND.","operationId":"listDomains","parameters":[{"name":"healthStatus","in":"query","description":"Filter by health status; true returns only healthy domains, false only unhealthy.","required":false,"schema":{"type":"boolean"}},{"name":"from","in":"query","description":"Zero-based index of the first domain to return for pagination.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"status","in":"query","description":"Filter by the lifecycle phase of the domain.","required":false,"schema":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]}},{"name":"limit","in":"query","description":"Maximum number of domains to return.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"name","in":"query","description":"Filter by domain name (substring match).","required":false,"schema":{"type":"string"}},{"name":"storageType","in":"query","description":"Filter by the configured storage type of the domain.","required":false,"schema":{"type":"string","enum":["Memory","Postgres","Shared Postgres","External"]}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DomainFilterResponseDto"}}}},"400":{"description":"One or more query parameters are invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create a new sync domain
> Provisions a new Canton sync domain as a Kubernetes resource. For external or Postgres storage, the database credentials are stored in a dedicated secret and injected as environment variables. The created domain is returned in its initial state.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"domain-controller","description":"Create, list, edit and remove Canton sync domains, and read their configuration."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DomainDto":{"type":"object","description":"Canton sync domain definition: name, container image, log level, admin / public endpoints and Canton-specific bootstrap settings used to provision a single-replica sync domain.","properties":{"adminAddress":{"type":"string"},"adminPort":{"type":"string","minLength":1},"bootstrap":{"type":"string"},"daemon":{"type":"boolean"},"enterprise":{"type":"boolean","description":"Whether the canton image is enterprise or not"},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"ingress":{"type":"boolean"},"logLevel":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR"]},"name":{"type":"string","minLength":1},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"publicAddress":{"type":"string"},"publicPort":{"type":"string","minLength":1},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"storage":{"$ref":"#/components/schemas/StorageDto"},"topology":{"type":"string"}},"required":["adminPort","image","name","publicPort"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}},"StorageDto":{"type":"object","description":"Persistent storage configuration: type (in-cluster or external Postgres), size, backup size and connection credentials when external.","properties":{"backupSize":{"type":"string"},"hostname":{"type":"string"},"password":{"type":"string"},"port":{"type":"string"},"size":{"type":"string"},"type":{"type":"string","enum":["Memory","Postgres","Shared Postgres","External"]},"user":{"type":"string"}}}}},"paths":{"/domains":{"post":{"tags":["domain-controller"],"summary":"Create a new sync domain","description":"Provisions a new Canton sync domain as a Kubernetes resource. For external or Postgres storage, the database credentials are stored in a dedicated secret and injected as environment variables. The created domain is returned in its initial state.","operationId":"createDomain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DomainDto"}}}},"400":{"description":"The request payload is invalid or fails validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"409":{"description":"A domain with the same name already exists.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DomainDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Update an existing sync domain
> Applies the supplied spec changes to the existing sync domain resource. The domain is identified by the name field in the request body.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"domain-controller","description":"Create, list, edit and remove Canton sync domains, and read their configuration."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DomainDto":{"type":"object","description":"Canton sync domain definition: name, container image, log level, admin / public endpoints and Canton-specific bootstrap settings used to provision a single-replica sync domain.","properties":{"adminAddress":{"type":"string"},"adminPort":{"type":"string","minLength":1},"bootstrap":{"type":"string"},"daemon":{"type":"boolean"},"enterprise":{"type":"boolean","description":"Whether the canton image is enterprise or not"},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string","minLength":1},"ingress":{"type":"boolean"},"logLevel":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR"]},"name":{"type":"string","minLength":1},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"publicAddress":{"type":"string"},"publicPort":{"type":"string","minLength":1},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"storage":{"$ref":"#/components/schemas/StorageDto"},"topology":{"type":"string"}},"required":["adminPort","image","name","publicPort"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}},"StorageDto":{"type":"object","description":"Persistent storage configuration: type (in-cluster or external Postgres), size, backup size and connection credentials when external.","properties":{"backupSize":{"type":"string"},"hostname":{"type":"string"},"password":{"type":"string"},"port":{"type":"string"},"size":{"type":"string"},"type":{"type":"string","enum":["Memory","Postgres","Shared Postgres","External"]},"user":{"type":"string"}}}}},"paths":{"/domains":{"put":{"tags":["domain-controller"],"summary":"Update an existing sync domain","description":"Applies the supplied spec changes to the existing sync domain resource. The domain is identified by the name field in the request body.","operationId":"updateDomain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDto"}}},"required":true},"responses":{"200":{"description":"OK"},"400":{"description":"The request payload is invalid or fails validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No sync domain exists with the given name."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## List HA sync domains with filtering
> Returns a paginated list of HA sync domains matching the supplied filters together with the total count. All filter parameters are optional.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"domain-ha-controller","description":"Configure and inspect high-availability settings of a Canton sync domain."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DomainHAResponseDto":{"type":"object","description":"Paginated list of HA sync domain entries plus the total count.","properties":{"domainHAs":{"type":"array","items":{"$ref":"#/components/schemas/DomainHAEntry"}},"totalCount":{"type":"integer","format":"int64"}}},"DomainHAEntry":{"type":"object","properties":{"name":{"type":"string","minLength":1},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"status":{"$ref":"#/components/schemas/DomainHAStatusDto"}},"required":["name","status"]},"DomainHAStatusDto":{"type":"object","description":"Runtime status of an HA sync domain split per component (mediator, topology manager, sequencer, in-cluster database, bootstrap).","properties":{"mediator":{"$ref":"#/components/schemas/MediatorStatusDto"},"topologyManager":{"$ref":"#/components/schemas/TopologyManagerStatusDto"},"sequencer":{"$ref":"#/components/schemas/SequencerStatusDto"},"inClusterDatabase":{"$ref":"#/components/schemas/InClusterDatabaseStatusDto"},"bootstrap":{"$ref":"#/components/schemas/BootstrapStatusDto"}}},"MediatorStatusDto":{"type":"object","properties":{"ready":{"type":"boolean"}}},"TopologyManagerStatusDto":{"type":"object","properties":{"ready":{"type":"boolean"}}},"SequencerStatusDto":{"type":"object","properties":{"ready":{"type":"boolean"}}},"InClusterDatabaseStatusDto":{"type":"object","properties":{"ready":{"type":"boolean"}}},"BootstrapStatusDto":{"type":"object","properties":{"started":{"type":"boolean"},"completed":{"type":"boolean"},"error":{"type":"string"},"ready":{"type":"boolean"}}}}},"paths":{"/domainha":{"get":{"tags":["domain-ha-controller"],"summary":"List HA sync domains with filtering","description":"Returns a paginated list of HA sync domains matching the supplied filters together with the total count. All filter parameters are optional.","operationId":"list","parameters":[{"name":"from","in":"query","description":"Zero-based index of the first HA domain to return for pagination.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"limit","in":"query","description":"Maximum number of HA domains to return.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"name","in":"query","description":"Filter by HA domain name (substring match).","required":false,"schema":{"type":"string"}},{"name":"phase","in":"query","description":"Filter by the lifecycle phase of the HA domain.","required":false,"schema":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DomainHAResponseDto"}}}},"400":{"description":"One or more query parameters are invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create a highly available sync domain
> Provisions a new sync domain with replicated mediator and sequencer components to support failover. Fails if a HA domain with the same name already exists.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"domain-ha-controller","description":"Configure and inspect high-availability settings of a Canton sync domain."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DomainHADto":{"type":"object","description":"High-availability sync domain definition: per-component (sequencer, mediator, topology manager) specifications plus in-cluster or external storage settings.","properties":{"name":{"type":"string","maxLength":15,"minLength":2},"defaults":{"$ref":"#/components/schemas/DefaultsDto"},"sequencer":{"$ref":"#/components/schemas/SequencerSpecDto"},"mediator":{"$ref":"#/components/schemas/MediatorSpecDto"},"topologyManager":{"$ref":"#/components/schemas/TopologyManagerSpecDto"},"externalStorage":{"$ref":"#/components/schemas/ExternalStorageSpecDto"},"inClusterStorage":{"$ref":"#/components/schemas/InClusterStorageSpecDto"},"validStorage":{"type":"boolean"}},"required":["defaults","mediator","name","sequencer","topologyManager"]},"DefaultsDto":{"type":"object","properties":{"image":{"$ref":"#/components/schemas/ImageDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"}},"required":["image"]},"ImageDto":{"type":"object","description":"Container image reference: registry, repository, tag and the Kubernetes pull secret used to fetch it.","properties":{"registry":{"type":"string","minLength":1},"repository":{"type":"string","minLength":1},"tag":{"type":"string","minLength":1},"pullSecretName":{"type":"string"}},"required":["registry","repository","tag"]},"CantonFlagsDto":{"type":"object","description":"Runtime log-level flags for a Canton workload (root, Canton-specific and stdout log levels).","properties":{"logLevelRoot":{"type":"string"},"logLevelCanton":{"type":"string"},"logLevelStdout":{"type":"string"}}},"SequencerSpecDto":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"ingress":{"$ref":"#/components/schemas/SequencerIngressConfigDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"storageOverrides":{"$ref":"#/components/schemas/ExternalStorageOverridesDto"}},"required":["resources"]},"ResourceRequirementsDto":{"type":"object","description":"Kubernetes container resource requirements: limits and requests, each composed of CPU and memory values.","properties":{"limits":{"$ref":"#/components/schemas/ContainerResourcesDto"},"requests":{"$ref":"#/components/schemas/ContainerResourcesDto"}},"required":["limits","requests"]},"ContainerResourcesDto":{"type":"object","description":"Kubernetes container CPU and memory values (used as either limits or requests).","properties":{"cpu":{"type":"string","minLength":1},"memory":{"type":"string","minLength":1}},"required":["cpu","memory"]},"SequencerIngressConfigDto":{"type":"object","description":"Per-sequencer ingress flags toggling exposure of the admin and public APIs.","properties":{"adminAPIEnabled":{"type":"boolean"},"publicAPIEnabled":{"type":"boolean"}}},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ExternalStorageOverridesDto":{"type":"object","properties":{"schemaName":{"type":"string"},"dbName":{"type":"string"},"userUsername":{"type":"string"},"userPassword":{"type":"string"}}},"MediatorSpecDto":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"storageOverrides":{"$ref":"#/components/schemas/ExternalStorageOverridesDto"}},"required":["resources"]},"TopologyManagerSpecDto":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"storageOverrides":{"$ref":"#/components/schemas/ExternalStorageOverridesDto"}},"required":["resources"]},"ExternalStorageSpecDto":{"type":"object","properties":{"hostname":{"type":"string","minLength":1},"port":{"type":"integer","format":"int32"},"adminUsername":{"type":"string","minLength":1},"adminPassword":{"type":"string","minLength":1},"ssl":{"type":"boolean"},"maxConnections":{"type":"integer","format":"int32"},"schemaName":{"type":"string"}},"required":["adminPassword","adminUsername","hostname","port"]},"InClusterStorageSpecDto":{"type":"object","properties":{"storageSize":{"type":"string","minLength":1},"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"validStorageSize":{"type":"boolean"}},"required":["resources","storageSize"]}}},"paths":{"/domainha":{"post":{"tags":["domain-ha-controller"],"summary":"Create a highly available sync domain","description":"Provisions a new sync domain with replicated mediator and sequencer components to support failover. Fails if a HA domain with the same name already exists.","operationId":"create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainHADto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DomainHADto"}}}},"400":{"description":"The request payload is invalid or fails validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"409":{"description":"A HA sync domain with the same name already exists.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DomainHADto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Update an existing HA sync domain
> Applies the supplied editable changes to the HA sync domain resource and returns the updated DTO. The HA domain is identified by the name in the request body.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"domain-ha-controller","description":"Configure and inspect high-availability settings of a Canton sync domain."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DomainHAEditDto":{"type":"object","description":"Partial update payload for an HA sync domain; non-null sections replace the corresponding configuration on the existing deployment.","properties":{"name":{"type":"string"},"defaults":{"$ref":"#/components/schemas/DefaultsEditDto"},"sequencer":{"$ref":"#/components/schemas/SequencerEditDto"},"mediator":{"$ref":"#/components/schemas/MediatorEditDto"},"topologyManager":{"$ref":"#/components/schemas/TopologyManagerEditDto"},"inClusterStorage":{"$ref":"#/components/schemas/InClusterStorageEditDto"}},"required":["defaults","mediator","name","sequencer","topologyManager"]},"DefaultsEditDto":{"type":"object","properties":{"image":{"$ref":"#/components/schemas/ImageDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"}},"required":["image"]},"ImageDto":{"type":"object","description":"Container image reference: registry, repository, tag and the Kubernetes pull secret used to fetch it.","properties":{"registry":{"type":"string","minLength":1},"repository":{"type":"string","minLength":1},"tag":{"type":"string","minLength":1},"pullSecretName":{"type":"string"}},"required":["registry","repository","tag"]},"CantonFlagsDto":{"type":"object","description":"Runtime log-level flags for a Canton workload (root, Canton-specific and stdout log levels).","properties":{"logLevelRoot":{"type":"string"},"logLevelCanton":{"type":"string"},"logLevelStdout":{"type":"string"}}},"SequencerEditDto":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}}},"required":["resources"]},"ResourceRequirementsDto":{"type":"object","description":"Kubernetes container resource requirements: limits and requests, each composed of CPU and memory values.","properties":{"limits":{"$ref":"#/components/schemas/ContainerResourcesDto"},"requests":{"$ref":"#/components/schemas/ContainerResourcesDto"}},"required":["limits","requests"]},"ContainerResourcesDto":{"type":"object","description":"Kubernetes container CPU and memory values (used as either limits or requests).","properties":{"cpu":{"type":"string","minLength":1},"memory":{"type":"string","minLength":1}},"required":["cpu","memory"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"MediatorEditDto":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}}},"required":["resources"]},"TopologyManagerEditDto":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}}},"required":["resources"]},"InClusterStorageEditDto":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"storageSize":{"type":"string"},"validStorageSize":{"type":"boolean"}},"required":["resources"]},"DomainHADto":{"type":"object","description":"High-availability sync domain definition: per-component (sequencer, mediator, topology manager) specifications plus in-cluster or external storage settings.","properties":{"name":{"type":"string","maxLength":15,"minLength":2},"defaults":{"$ref":"#/components/schemas/DefaultsDto"},"sequencer":{"$ref":"#/components/schemas/SequencerSpecDto"},"mediator":{"$ref":"#/components/schemas/MediatorSpecDto"},"topologyManager":{"$ref":"#/components/schemas/TopologyManagerSpecDto"},"externalStorage":{"$ref":"#/components/schemas/ExternalStorageSpecDto"},"inClusterStorage":{"$ref":"#/components/schemas/InClusterStorageSpecDto"},"validStorage":{"type":"boolean"}},"required":["defaults","mediator","name","sequencer","topologyManager"]},"DefaultsDto":{"type":"object","properties":{"image":{"$ref":"#/components/schemas/ImageDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"}},"required":["image"]},"SequencerSpecDto":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"ingress":{"$ref":"#/components/schemas/SequencerIngressConfigDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"storageOverrides":{"$ref":"#/components/schemas/ExternalStorageOverridesDto"}},"required":["resources"]},"SequencerIngressConfigDto":{"type":"object","description":"Per-sequencer ingress flags toggling exposure of the admin and public APIs.","properties":{"adminAPIEnabled":{"type":"boolean"},"publicAPIEnabled":{"type":"boolean"}}},"ExternalStorageOverridesDto":{"type":"object","properties":{"schemaName":{"type":"string"},"dbName":{"type":"string"},"userUsername":{"type":"string"},"userPassword":{"type":"string"}}},"MediatorSpecDto":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"storageOverrides":{"$ref":"#/components/schemas/ExternalStorageOverridesDto"}},"required":["resources"]},"TopologyManagerSpecDto":{"type":"object","properties":{"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"cantonFlags":{"$ref":"#/components/schemas/CantonFlagsDto"},"env":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"storageOverrides":{"$ref":"#/components/schemas/ExternalStorageOverridesDto"}},"required":["resources"]},"ExternalStorageSpecDto":{"type":"object","properties":{"hostname":{"type":"string","minLength":1},"port":{"type":"integer","format":"int32"},"adminUsername":{"type":"string","minLength":1},"adminPassword":{"type":"string","minLength":1},"ssl":{"type":"boolean"},"maxConnections":{"type":"integer","format":"int32"},"schemaName":{"type":"string"}},"required":["adminPassword","adminUsername","hostname","port"]},"InClusterStorageSpecDto":{"type":"object","properties":{"storageSize":{"type":"string","minLength":1},"resources":{"$ref":"#/components/schemas/ResourceRequirementsDto"},"validStorageSize":{"type":"boolean"}},"required":["resources","storageSize"]}}},"paths":{"/domainha":{"put":{"tags":["domain-ha-controller"],"summary":"Update an existing HA sync domain","description":"Applies the supplied editable changes to the HA sync domain resource and returns the updated DTO. The HA domain is identified by the name in the request body.","operationId":"update","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainHAEditDto"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DomainHADto"}}}},"400":{"description":"The request payload is invalid or fails validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No HA sync domain exists with the given name.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DomainHADto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## List applications with filtering and pagination
> Returns a page of deployed applications optionally filtered by status, name and type. Supports offset/limit pagination via the from and limit query parameters.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"application-controller","description":"Manage generic CBM-deployed applications and their lifecycle."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ApplicationFilterResponseDto":{"type":"object","description":"Paginated list of `ApplicationDto` entries plus the total count of applications matching the filter.","properties":{"applications":{"type":"array","items":{"$ref":"#/components/schemas/ApplicationDto"}},"totalCount":{"type":"integer","format":"int64"}}},"ApplicationDto":{"type":"object","description":"Generic CBM-deployed application: name, container image, port, package, parent validator and Kubernetes resource requirements; used both as a request and a response body on the applications endpoints.","properties":{"domain":{"type":"string","minLength":1},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string"},"name":{"type":"string","minLength":1},"packageName":{"type":"string"},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"port":{"type":"integer","format":"int32"},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"type":{"type":"string","enum":["BACKEND","UI"]},"validatorParent":{"type":"string"}},"required":["domain","name","type"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}}}},"paths":{"/applications":{"get":{"tags":["application-controller"],"summary":"List applications with filtering and pagination","description":"Returns a page of deployed applications optionally filtered by status, name and type. Supports offset/limit pagination via the from and limit query parameters.","operationId":"listApplications","parameters":[{"name":"from","in":"query","description":"Zero-based index of the first application to return","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"status","in":"query","description":"Filter by current lifecycle phase of the application","required":false,"schema":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]}},{"name":"limit","in":"query","description":"Maximum number of applications to return","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"name","in":"query","description":"Filter by application name (substring match)","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","description":"Filter by application type","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApplicationFilterResponseDto"}}}},"400":{"description":"Invalid filter or pagination parameters","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create a new application
> Deploys a new CBM application CRD onto the Kubernetes cluster. When the target participant uses an OIDC auth provider (e.g. Keycloak), the corresponding auth client and environment variables are provisioned automatically. Fails if a resource with the same name already exists.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"application-controller","description":"Manage generic CBM-deployed applications and their lifecycle."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ApplicationDto":{"type":"object","description":"Generic CBM-deployed application: name, container image, port, package, parent validator and Kubernetes resource requirements; used both as a request and a response body on the applications endpoints.","properties":{"domain":{"type":"string","minLength":1},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string"},"name":{"type":"string","minLength":1},"packageName":{"type":"string"},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"port":{"type":"integer","format":"int32"},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"type":{"type":"string","enum":["BACKEND","UI"]},"validatorParent":{"type":"string"}},"required":["domain","name","type"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}}}},"paths":{"/applications":{"post":{"tags":["application-controller"],"summary":"Create a new application","description":"Deploys a new CBM application CRD onto the Kubernetes cluster. When the target participant uses an OIDC auth provider (e.g. Keycloak), the corresponding auth client and environment variables are provisioned automatically. Fails if a resource with the same name already exists.","operationId":"createApplication","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApplicationDto"}}}},"400":{"description":"Invalid application payload","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"409":{"description":"An application or resource with the same name already exists","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApplicationDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Update an existing application
> Applies the provided application spec to the existing CRD, updating image, env vars, resources and other mutable fields.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"application-controller","description":"Manage generic CBM-deployed applications and their lifecycle."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ApplicationDto":{"type":"object","description":"Generic CBM-deployed application: name, container image, port, package, parent validator and Kubernetes resource requirements; used both as a request and a response body on the applications endpoints.","properties":{"domain":{"type":"string","minLength":1},"envVars":{"type":"array","items":{"$ref":"#/components/schemas/EnvVar"}},"image":{"type":"string"},"name":{"type":"string","minLength":1},"packageName":{"type":"string"},"phase":{"type":"string","enum":["COMPLETED","PENDING","RUNNING"]},"port":{"type":"integer","format":"int32"},"resources":{"$ref":"#/components/schemas/ResourcesDto"},"type":{"type":"string","enum":["BACKEND","UI"]},"validatorParent":{"type":"string"}},"required":["domain","name","type"]},"EnvVar":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"},"valueFrom":{"$ref":"#/components/schemas/EnvVarSource"}}},"EnvVarSource":{"type":"object","properties":{"secretKeyRef":{"$ref":"#/components/schemas/SecretKeySelector"}}},"SecretKeySelector":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"optional":{"type":"boolean"}}},"ResourcesDto":{"type":"object","description":"Container/Pod related fields.","properties":{"cpuLimit":{"type":"string","description":"The maximum amount of CPU allowed for a container. The value is a string with a suffix of milliCPU, e.g. 500m. The value can also be given in CPU units, e.g. 0.5. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu"},"cpuRequested":{"type":"string","description":"The requested amount of CPU for a container. See cpuLimit for details."},"imagePullSecret":{"type":"string","description":"The name of the image pull secret to use for the container. The secret must be present in the same namespace as the pod."},"memoryLimit":{"type":"string","description":"The maximum amount of memory allowed for a container. The value is a string with a quantity suffix, e.g. 123Mi. The value can also be given in bytes, e.g. 128974848. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory"},"memoryRequested":{"type":"string","description":"The requested amount of memory for a container. See memoryLimit for details."},"replicas":{"type":"integer","format":"int32","description":"The requested replicas for a container."}}}}},"paths":{"/applications":{"put":{"tags":["application-controller"],"summary":"Update an existing application","description":"Applies the provided application spec to the existing CRD, updating image, env vars, resources and other mutable fields.","operationId":"updateApplication","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationDto"}}},"required":true},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid application payload","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"Application not found"},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Get validator restore job
> Returns the current status and metadata of the validator's most recent restore job. Use this to poll the progress of a previously triggered restore.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-restore-controller","description":"Restore a Splice validator from a previously created backup (database, identity, wallet)."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ValidatorRestoreResponseDto":{"type":"object","description":"Single entry in the validator restore history: filenames restored from, overall status and capture timestamp.","properties":{"filenames":{"type":"array","items":{"type":"string"},"maxItems":2,"minItems":2},"status":{"type":"string"},"timestamp":{"type":"string"}}}}},"paths":{"/validators/{name}/restore":{"get":{"tags":["validator-restore-controller"],"summary":"Get validator restore job","description":"Returns the current status and metadata of the validator's most recent restore job. Use this to poll the progress of a previously triggered restore.","operationId":"getRestoreJob","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ValidatorRestoreResponseDto"}}}},"400":{"description":"The supplied validator name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No restore job exists for the given validator.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ValidatorRestoreResponseDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Trigger validator restore
> Starts a long-running restore job that recreates the validator's state from the referenced backup files. Returns immediately with the created job descriptor; poll the GET endpoint for status. Any previous completed restore job for this validator is deleted first.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-restore-controller","description":"Restore a Splice validator from a previously created backup (database, identity, wallet)."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ValidatorRestoreDto":{"type":"object","description":"Request body to start a Splice validator restore from one or more previously captured backup files.","properties":{"filenames":{"type":"array","items":{"type":"string"},"maxItems":2,"minItems":2}}},"ValidatorRestoreResponseDto":{"type":"object","description":"Single entry in the validator restore history: filenames restored from, overall status and capture timestamp.","properties":{"filenames":{"type":"array","items":{"type":"string"},"maxItems":2,"minItems":2},"status":{"type":"string"},"timestamp":{"type":"string"}}}}},"paths":{"/validators/{name}/restore":{"post":{"tags":["validator-restore-controller"],"summary":"Trigger validator restore","description":"Starts a long-running restore job that recreates the validator's state from the referenced backup files. Returns immediately with the created job descriptor; poll the GET endpoint for status. Any previous completed restore job for this validator is deleted first.","operationId":"createRestoreJob","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the validator to restore.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorRestoreDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ValidatorRestoreResponseDto"}}}},"400":{"description":"The restore payload references missing or invalid backup files.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No validator exists with the given name.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ValidatorRestoreResponseDto"}}}},"409":{"description":"A restore job is already running for this validator.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ValidatorRestoreResponseDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Check sponsor scan quorum
> Verifies that the supplied sponsor scan address can reach a quorum of Super Validators on the network. Used as a pre-flight check before launching a prefill.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-prefill-controller","description":"Prefill a Splice validator, check quorum status and perform top-up operations."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CheckQuorumRequest":{"type":"object","description":"Request body for the Splice prefill quorum check; references the sponsor scan address used during validator on-boarding.","properties":{"sponsorScanAddress":{"type":"string"}}}}},"paths":{"/validators/prefill/check-quorum":{"post":{"tags":["validator-prefill-controller"],"summary":"Check sponsor scan quorum","description":"Verifies that the supplied sponsor scan address can reach a quorum of Super Validators on the network. Used as a pre-flight check before launching a prefill.","operationId":"checkQuorum","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckQuorumRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"boolean"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Get the pruning schedule of a participant
> Reads the current pruning schedule from the remote enterprise participant and enriches it with the Unix timestamp of the next scheduled cron run, computed in CBM.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-prune-controller","description":"Run pruning on a remote participant and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledPruneDto":{"type":"object","description":"Persisted pruning schedule for a Canton workload: cron expression, retention window, max duration and next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxDurationInSec":{"type":"integer","format":"int64","minimum":1},"nextRun":{"type":"string"},"retentionInSec":{"type":"integer","format":"int64","minimum":1}},"required":["cron","maxDurationInSec","retentionInSec"]}}},"paths":{"/remote-participants/{name}/prune":{"get":{"tags":["remote-participant-prune-controller"],"summary":"Get the pruning schedule of a participant","description":"Reads the current pruning schedule from the remote enterprise participant and enriches it with the Unix timestamp of the next scheduled cron run, computed in CBM.","operationId":"getRemoteParticipantPruningSchedule","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledPruneDto"}}}},"400":{"description":"The supplied participant name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote participant is registered under the given name or no schedule is configured.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledPruneDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create a pruning schedule on a participant
> Validates the cron expression and sends it to the remote enterprise participant's admin API, which will then prune old ledger data on the configured cadence.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-prune-controller","description":"Run pruning on a remote participant and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledPruneDto":{"type":"object","description":"Persisted pruning schedule for a Canton workload: cron expression, retention window, max duration and next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxDurationInSec":{"type":"integer","format":"int64","minimum":1},"nextRun":{"type":"string"},"retentionInSec":{"type":"integer","format":"int64","minimum":1}},"required":["cron","maxDurationInSec","retentionInSec"]}}},"paths":{"/remote-participants/{name}/prune":{"post":{"tags":["remote-participant-prune-controller"],"summary":"Create a pruning schedule on a participant","description":"Validates the cron expression and sends it to the remote enterprise participant's admin API, which will then prune old ledger data on the configured cadence.","operationId":"createRemoteParticipantPruningSchedule","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledPruneDto"}}},"required":true},"responses":{"201":{"description":"Created"},"400":{"description":"The participant name, cron expression, or retention payload is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote participant is registered under the given name."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Clear the pruning schedule on a participant
> Proxies a clear-schedule call to the remote enterprise participant so that no further automatic pruning runs are triggered. Previously pruned data is not restored.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-prune-controller","description":"Run pruning on a remote participant and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/remote-participants/{name}/prune":{"delete":{"tags":["remote-participant-prune-controller"],"summary":"Clear the pruning schedule on a participant","description":"Proxies a clear-schedule call to the remote enterprise participant so that no further automatic pruning runs are triggered. Previously pruned data is not restored.","operationId":"deleteRemoteParticipantPruningSchedule","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"The supplied participant name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote participant is registered under the given name."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Proxy a GET request to the participant JSON Ledger API
> Forwards the incoming GET request (path beyond /jsonapi, query string, headers) to the configured JSON Ledger API endpoint of the remote participant and streams the response back.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-json-api-controller","description":"Proxy requests to the JSON Ledger API of a remote Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/remote-participants/{name}/jsonapi/**":{"get":{"tags":["remote-participant-json-api-controller"],"summary":"Proxy a GET request to the participant JSON Ledger API","description":"Forwards the incoming GET request (path beyond /jsonapi, query string, headers) to the configured JSON Ledger API endpoint of the remote participant and streams the response back.","operationId":"getRemoteParticipantRequest","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote participant is registered under the given name.","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Proxy a POST request to the participant JSON Ledger API
> Forwards the incoming POST request body and path/query to the configured JSON Ledger API endpoint of the remote participant. Used for command submission and similar mutating ledger operations.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-json-api-controller","description":"Proxy requests to the JSON Ledger API of a remote Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/remote-participants/{name}/jsonapi/**":{"post":{"tags":["remote-participant-json-api-controller"],"summary":"Proxy a POST request to the participant JSON Ledger API","description":"Forwards the incoming POST request body and path/query to the configured JSON Ledger API endpoint of the remote participant. Used for command submission and similar mutating ledger operations.","operationId":"postRemoteParticipantRequest","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote participant is registered under the given name.","content":{"*/*":{"schema":{"type":"object"}}}},"409":{"description":"The remote JSON Ledger API rejected the request due to a state conflict (e.g. duplicate command id).","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Proxy a DELETE request to the participant JSON Ledger API
> Forwards the incoming DELETE request to the configured JSON Ledger API endpoint of the remote participant, typically used to cancel or release ledger resources.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-json-api-controller","description":"Proxy requests to the JSON Ledger API of a remote Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/remote-participants/{name}/jsonapi/**":{"delete":{"tags":["remote-participant-json-api-controller"],"summary":"Proxy a DELETE request to the participant JSON Ledger API","description":"Forwards the incoming DELETE request to the configured JSON Ledger API endpoint of the remote participant, typically used to cancel or release ledger resources.","operationId":"deleteRemoteParticipantRequest","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote participant is registered under the given name.","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Lists all configured dars of a participant
> Queries the remote participant's admin API and returns the DARs currently installed on the node, including their hashes and package metadata.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-dar-controller","description":"List, upload and remove DAR packages on a remote Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DarDto":{"type":"object","description":"Reference to a DAR package uploaded to a Canton participant: identifying hash, package name and version.","properties":{"hash":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"}}}}},"paths":{"/remote-participants/{name}/dars":{"get":{"tags":["remote-participant-dar-controller"],"summary":"Lists all configured dars of a participant","description":"Queries the remote participant's admin API and returns the DARs currently installed on the node, including their hashes and package metadata.","operationId":"listRemoteParticipantDars","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DarDto"}}}}},"400":{"description":"The supplied participant name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote participant is registered under the given name.","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DarDto"}}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Upload dar file to a participant
> Reads each requested DAR from CBM file storage and uploads it to the remote participant via its admin API. Between 1 and 15 DAR names may be uploaded in a single call.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-dar-controller","description":"List, upload and remove DAR packages on a remote Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/remote-participants/{name}/dars":{"post":{"tags":["remote-participant-dar-controller"],"summary":"Upload dar file to a participant","description":"Reads each requested DAR from CBM file storage and uploads it to the remote participant via its admin API. Between 1 and 15 DAR names may be uploaded in a single call.","operationId":"uploadRemoteParticipantDar","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"darName","in":"query","description":"Names of DAR files (already stored in CBM file storage) to upload to the participant.","required":true,"schema":{"type":"array","items":{"type":"string"},"maxItems":15,"minItems":1}}],"responses":{"200":{"description":"OK"},"400":{"description":"The participant name or the supplied list of DAR names is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"The participant is not registered in CBM or a referenced DAR is missing from CBM file storage."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Remove a dar from a participant
> Proxies an admin-API call to the remote participant to uninstall the DAR identified by its hash. The DAR is only removed from the remote node; CBM file storage is untouched.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-dar-controller","description":"List, upload and remove DAR packages on a remote Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/remote-participants/{name}/dars":{"delete":{"tags":["remote-participant-dar-controller"],"summary":"Remove a dar from a participant","description":"Proxies an admin-API call to the remote participant to uninstall the DAR identified by its hash. The DAR is only removed from the remote node; CBM file storage is untouched.","operationId":"removeRemoteParticipantDar","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"darHash","in":"query","description":"Hash of the DAR to remove, as reported by the participant.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"The participant name or DAR hash is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"Either the participant is not registered in CBM or the DAR hash is unknown on the remote node."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Lists all configured domain connections of a participant
> Calls the remote participant's admin API to retrieve every domain connection it has been configured with, regardless of current connectivity state.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-connection-controller","description":"Configure, register, connect and disconnect a remote Canton participant against one of its sync domains."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ConnectionDto":{"type":"object","description":"The DTO representing a connection to a domain.","properties":{"connected":{"type":"boolean","description":"It represents the connection status. It is true when the connection is established, false otherwise."},"custom":{"type":"boolean","description":"It represents a custom domain. When it is true the domainUrl should be used, use domainName and port otherwise "},"domainAlias":{"type":"string","description":"This is the alias of the domain to connect to. It does not have to be the same as the actual domain name.","minLength":1},"domainName":{"type":"string","description":"This is name of the domain to connect to. "},"isHADomain":{"type":"boolean","description":"Defines whether the domain name belongs to the HA Domain entity"},"domainUrl":{"type":"string","description":"This is the URL of the domain to connect to. It must be accessible from the participant node. Usage: https://..svc.cluster.local:"},"publicPort":{"type":"string","description":"This is public port of the domain to connect to. "}},"required":["domainAlias"]}}},"paths":{"/remote-participants/{name}/connections":{"get":{"tags":["remote-participant-connection-controller"],"summary":"Lists all configured domain connections of a participant","description":"Calls the remote participant's admin API to retrieve every domain connection it has been configured with, regardless of current connectivity state.","operationId":"listRemoteParticipantConnections","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionDto"}}}}},"400":{"description":"The supplied participant name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote participant is registered under the given name.","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionDto"}}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Configures, registers and connects a domain to a participant
> Proxies an admin-API call to the remote participant to register a new domain connection and immediately connect it. The exact RPC is selected based on the remote node's Canton major version (V0 vs V3).
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-participant-connection-controller","description":"Configure, register, connect and disconnect a remote Canton participant against one of its sync domains."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ConnectionDto":{"type":"object","description":"The DTO representing a connection to a domain.","properties":{"connected":{"type":"boolean","description":"It represents the connection status. It is true when the connection is established, false otherwise."},"custom":{"type":"boolean","description":"It represents a custom domain. When it is true the domainUrl should be used, use domainName and port otherwise "},"domainAlias":{"type":"string","description":"This is the alias of the domain to connect to. It does not have to be the same as the actual domain name.","minLength":1},"domainName":{"type":"string","description":"This is name of the domain to connect to. "},"isHADomain":{"type":"boolean","description":"Defines whether the domain name belongs to the HA Domain entity"},"domainUrl":{"type":"string","description":"This is the URL of the domain to connect to. It must be accessible from the participant node. Usage: https://..svc.cluster.local:"},"publicPort":{"type":"string","description":"This is public port of the domain to connect to. "}},"required":["domainAlias"]}}},"paths":{"/remote-participants/{name}/connections":{"post":{"tags":["remote-participant-connection-controller"],"summary":"Configures, registers and connects a domain to a participant","description":"Proxies an admin-API call to the remote participant to register a new domain connection and immediately connect it. The exact RPC is selected based on the remote node's Canton major version (V0 vs V3).","operationId":"createRemoteParticipantConnection","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the remote participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionDto"}}},"required":true},"responses":{"201":{"description":"Created"},"400":{"description":"The connection payload or participant name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote participant is registered under the given name."},"409":{"description":"A domain connection with the same alias is already registered on the remote participant."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Get the current pruning schedule of a remote domain component
> Fetches the cron-based pruning schedule currently configured on the mediator or sequencer of the remote sync domain, together with the next computed run timestamp. The schedule is read from the remote node via its admin API.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-domain-prune-controller","description":"Run pruning on a remote sync domain and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledPruneDto":{"type":"object","description":"Persisted pruning schedule for a Canton workload: cron expression, retention window, max duration and next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxDurationInSec":{"type":"integer","format":"int64","minimum":1},"nextRun":{"type":"string"},"retentionInSec":{"type":"integer","format":"int64","minimum":1}},"required":["cron","maxDurationInSec","retentionInSec"]}}},"paths":{"/remote-domains/{name}/prune":{"get":{"tags":["remote-domain-prune-controller"],"summary":"Get the current pruning schedule of a remote domain component","description":"Fetches the cron-based pruning schedule currently configured on the mediator or sequencer of the remote sync domain, together with the next computed run timestamp. The schedule is read from the remote node via its admin API.","operationId":"getRemoteDomainPruningSchedule","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the target remote domain.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"component","in":"query","description":"Remote domain component to inspect (mediator or sequencer).","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledPruneDto"}}}},"400":{"description":"Invalid component value.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote domain is registered under the given name, or no schedule is configured.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledPruneDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create a pruning schedule on a remote domain component
> Sends a pruning schedule (cron-based ledger data retention) to the mediator or sequencer of a remote sync domain. The schedule is applied on the remote node via its admin API; CBM only resolves the connection details from its local registration.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-domain-prune-controller","description":"Run pruning on a remote sync domain and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledPruneDto":{"type":"object","description":"Persisted pruning schedule for a Canton workload: cron expression, retention window, max duration and next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxDurationInSec":{"type":"integer","format":"int64","minimum":1},"nextRun":{"type":"string"},"retentionInSec":{"type":"integer","format":"int64","minimum":1}},"required":["cron","maxDurationInSec","retentionInSec"]}}},"paths":{"/remote-domains/{name}/prune":{"post":{"tags":["remote-domain-prune-controller"],"summary":"Create a pruning schedule on a remote domain component","description":"Sends a pruning schedule (cron-based ledger data retention) to the mediator or sequencer of a remote sync domain. The schedule is applied on the remote node via its admin API; CBM only resolves the connection details from its local registration.","operationId":"createRemoteDomainPruningSchedule","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the target remote domain.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"component","in":"query","description":"Remote domain component the schedule applies to (mediator or sequencer).","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledPruneDto"}}},"required":true},"responses":{"201":{"description":"Created"},"400":{"description":"Invalid cron expression, component, or schedule payload.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote domain is registered under the given name."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Clear the pruning schedule on a remote domain component
> Instructs the mediator or sequencer of the remote sync domain to drop its current pruning schedule. The clear command is proxied to the remote node's admin API.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"remote-domain-prune-controller","description":"Run pruning on a remote sync domain and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/remote-domains/{name}/prune":{"delete":{"tags":["remote-domain-prune-controller"],"summary":"Clear the pruning schedule on a remote domain component","description":"Instructs the mediator or sequencer of the remote sync domain to drop its current pruning schedule. The clear command is proxied to the remote node's admin API.","operationId":"deleteRemoteDomainPruningSchedule","parameters":[{"name":"name","in":"path","description":"CBM-side registration name of the target remote domain.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"component","in":"query","description":"Remote domain component whose schedule should be cleared (mediator or sequencer).","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"Invalid component value.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No remote domain is registered under the given name, or no schedule exists to clear."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Get participant restore job
> Returns the descriptor of the current restore job for the participant, including the source backup file and the job's runtime status. Used to poll the progress of a long-running restore initiated via POST.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-restore-controller","description":"Restore a Canton participant from a previously created backup."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RestoreDto":{"type":"object","description":"Request body to start a participant or domain restore from a previously captured backup file.","properties":{"fileName":{"type":"string","minLength":1}},"required":["fileName"]}}},"paths":{"/participants/{name}/restore":{"get":{"tags":["participant-restore-controller"],"summary":"Get participant restore job","description":"Returns the descriptor of the current restore job for the participant, including the source backup file and the job's runtime status. Used to poll the progress of a long-running restore initiated via POST.","operationId":"getParticipantRestoreSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant whose restore job to fetch.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RestoreDto"}}}},"400":{"description":"The participant name failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No restore job exists for the given participant.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RestoreDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create participant restore job
> Launches a one-shot restore job that recreates the participant's storage from the specified backup file. Any previous restore job for this participant is removed first. This is a long-running operation: the response is a job descriptor whose progress can be polled via the GET endpoint.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-restore-controller","description":"Restore a Canton participant from a previously created backup."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RestoreDto":{"type":"object","description":"Request body to start a participant or domain restore from a previously captured backup file.","properties":{"fileName":{"type":"string","minLength":1}},"required":["fileName"]}}},"paths":{"/participants/{name}/restore":{"post":{"tags":["participant-restore-controller"],"summary":"Create participant restore job","description":"Launches a one-shot restore job that recreates the participant's storage from the specified backup file. Any previous restore job for this participant is removed first. This is a long-running operation: the response is a job descriptor whose progress can be polled via the GET endpoint.","operationId":"createParticipantRestoreSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant to restore.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RestoreDto"}}}},"400":{"description":"The body, participant name, or backup file failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists or the referenced backup file is missing.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RestoreDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Delete participant restore job
> Removes the restore job descriptor for the participant. If a restore is currently running it will be cancelled. Restored data already written to the participant's storage is not rolled back.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-restore-controller","description":"Restore a Canton participant from a previously created backup."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/participants/{name}/restore":{"delete":{"tags":["participant-restore-controller"],"summary":"Delete participant restore job","description":"Removes the restore job descriptor for the participant. If a restore is currently running it will be cancelled. Restored data already written to the participant's storage is not rolled back.","operationId":"deleteParticipantRestoreSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant whose restore job should be removed.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"The participant name failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No restore job exists for the given participant."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Get participant pruning schedule
> Returns the current pruning schedule configured on the participant, including the cron expression, retention and the predicted Unix timestamp of the next run.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-prune-controller","description":"Run pruning on a participant and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledPruneDto":{"type":"object","description":"Persisted pruning schedule for a Canton workload: cron expression, retention window, max duration and next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxDurationInSec":{"type":"integer","format":"int64","minimum":1},"nextRun":{"type":"string"},"retentionInSec":{"type":"integer","format":"int64","minimum":1}},"required":["cron","maxDurationInSec","retentionInSec"]}}},"paths":{"/participants/{name}/prune":{"get":{"tags":["participant-prune-controller"],"summary":"Get participant pruning schedule","description":"Returns the current pruning schedule configured on the participant, including the cron expression, retention and the predicted Unix timestamp of the next run.","operationId":"getParticipantPruningSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant whose pruning schedule to fetch.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"port","in":"query","description":"Admin gRPC port on which to contact the participant.","required":false,"schema":{"type":"integer","format":"int32","default":5019}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledPruneDto"}}}},"400":{"description":"The participant name or port failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledPruneDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create participant pruning schedule
> Configures a recurring pruning schedule on the participant via its admin API. Pruning deletes ledger data older than the configured retention. This endpoint is only supported on enterprise participants; a 400 is returned otherwise.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-prune-controller","description":"Run pruning on a participant and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledPruneDto":{"type":"object","description":"Persisted pruning schedule for a Canton workload: cron expression, retention window, max duration and next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxDurationInSec":{"type":"integer","format":"int64","minimum":1},"nextRun":{"type":"string"},"retentionInSec":{"type":"integer","format":"int64","minimum":1}},"required":["cron","maxDurationInSec","retentionInSec"]}}},"paths":{"/participants/{name}/prune":{"post":{"tags":["participant-prune-controller"],"summary":"Create participant pruning schedule","description":"Configures a recurring pruning schedule on the participant via its admin API. Pruning deletes ledger data older than the configured retention. This endpoint is only supported on enterprise participants; a 400 is returned otherwise.","operationId":"createParticipantPruningSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the enterprise participant to schedule pruning on.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"port","in":"query","description":"Admin gRPC port on which to contact the participant.","required":false,"schema":{"type":"integer","format":"int32","default":5019}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledPruneDto"}}},"required":true},"responses":{"201":{"description":"Created"},"400":{"description":"The body, cron expression, or participant is non-enterprise.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Delete participant pruning schedule
> Clears the pruning schedule on the participant via its admin API. Already pruned ledger data cannot be recovered; this only stops future scheduled runs.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-prune-controller","description":"Run pruning on a participant and manage its pruning schedule."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/participants/{name}/prune":{"delete":{"tags":["participant-prune-controller"],"summary":"Delete participant pruning schedule","description":"Clears the pruning schedule on the participant via its admin API. Already pruned ledger data cannot be recovered; this only stops future scheduled runs.","operationId":"deleteParticipantPruningSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant whose pruning schedule to clear.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"port","in":"query","description":"Admin gRPC port on which to contact the participant.","required":false,"schema":{"type":"integer","format":"int32","default":5019}}],"responses":{"204":{"description":"No Content"},"400":{"description":"The participant name or port failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Refresh and list local parties
> Triggers an asynchronous refresh of the cached local-parties view from the participant's ledger API and immediately returns the current view together with the refresh status. Subsequent calls to the GET endpoint will reflect the refreshed data once the background fetch completes.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"local-party-controller","description":"Fetch and synchronise local parties hosted on a Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"LocalPartyListingDTO":{"type":"object","description":"Local-party listing for a participant: the in-progress fetch flag and the currently-known list of party identifiers.","properties":{"fetching":{"type":"boolean"},"parties":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/participants/{name}/parties/local/fetch":{"post":{"tags":["local-party-controller"],"summary":"Refresh and list local parties","description":"Triggers an asynchronous refresh of the cached local-parties view from the participant's ledger API and immediately returns the current view together with the refresh status. Subsequent calls to the GET endpoint will reflect the refreshed data once the background fetch completes.","operationId":"fetchParties","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant whose local parties to refresh.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/LocalPartyListingDTO"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Proxy GET to participant JSON Ledger API
> Forwards a GET request to the participant's JSON Ledger API endpoint, preserving the path suffix, query string and body. CBM authenticates the request with a freshly minted ledger token chosen according to the participant's auth provider (Keycloak, Auth0 or validator).
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"json-api-controller","description":"Proxy requests to the JSON Ledger API of a local Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/participants/{name}/jsonapi/**":{"get":{"tags":["json-api-controller"],"summary":"Proxy GET to participant JSON Ledger API","description":"Forwards a GET request to the participant's JSON Ledger API endpoint, preserving the path suffix, query string and body. CBM authenticates the request with a freshly minted ledger token chosen according to the participant's auth provider (Keycloak, Auth0 or validator).","operationId":"getParticipantRequest","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant to proxy the call to.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists.","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Proxy POST to participant JSON Ledger API
> Forwards a POST request (JSON or octet-stream) to the participant's JSON Ledger API. When the call is a party-allocation request (POST /v2/parties) and succeeds, the newly allocated party is added to CBM's local-party cache for the participant.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"json-api-controller","description":"Proxy requests to the JSON Ledger API of a local Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/participants/{name}/jsonapi/**":{"post":{"tags":["json-api-controller"],"summary":"Proxy POST to participant JSON Ledger API","description":"Forwards a POST request (JSON or octet-stream) to the participant's JSON Ledger API. When the call is a party-allocation request (POST /v2/parties) and succeeds, the newly allocated party is added to CBM's local-party cache for the participant.","operationId":"postParticipantRequest","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant to proxy the call to.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists.","content":{"*/*":{"schema":{"type":"object"}}}},"409":{"description":"The participant rejected the request as conflicting (for example party already exists).","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Proxy DELETE to participant JSON Ledger API
> Forwards a DELETE request to the participant's JSON Ledger API. The path suffix and query string after /jsonapi are passed through unchanged.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"json-api-controller","description":"Proxy requests to the JSON Ledger API of a local Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/participants/{name}/jsonapi/**":{"delete":{"tags":["json-api-controller"],"summary":"Proxy DELETE to participant JSON Ledger API","description":"Forwards a DELETE request to the participant's JSON Ledger API. The path suffix and query string after /jsonapi are passed through unchanged.","operationId":"deleteParticipantRequest","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant to proxy the call to.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists.","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Proxy PATCH to participant JSON Ledger API
> Forwards a PATCH request (JSON or octet-stream) to the participant's JSON Ledger API, preserving path, query string and body.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"json-api-controller","description":"Proxy requests to the JSON Ledger API of a local Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/participants/{name}/jsonapi/**":{"patch":{"tags":["json-api-controller"],"summary":"Proxy PATCH to participant JSON Ledger API","description":"Forwards a PATCH request (JSON or octet-stream) to the participant's JSON Ledger API, preserving path, query string and body.","operationId":"patchParticipantRequest","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant to proxy the call to.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists.","content":{"*/*":{"schema":{"type":"object"}}}},"409":{"description":"The participant rejected the request as conflicting.","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Lists all configured dars of a participant
> Returns the list of Daml Archive (DAR) packages currently uploaded to the given participant by calling its admin API. The package service is dispatched based on the participant's Canton/validator version.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-dar-controller","description":"List, upload and remove DAR packages on a Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DarDto":{"type":"object","description":"Reference to a DAR package uploaded to a Canton participant: identifying hash, package name and version.","properties":{"hash":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"}}}}},"paths":{"/participants/{name}/dars":{"get":{"tags":["participant-dar-controller"],"summary":"Lists all configured dars of a participant","description":"Returns the list of Daml Archive (DAR) packages currently uploaded to the given participant by calling its admin API. The package service is dispatched based on the participant's Canton/validator version.","operationId":"listParticipantDars","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the target participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DarDto"}}}}},"400":{"description":"The participant name failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists.","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DarDto"}}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Upload dar file to a participant
> Uploads one or more DAR packages already stored in the CBM file store to the target participant. Between 1 and 15 DAR names can be uploaded in a single request; uploads are performed in order and the call returns when all are accepted by the admin API.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-dar-controller","description":"List, upload and remove DAR packages on a Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/participants/{name}/dars":{"post":{"tags":["participant-dar-controller"],"summary":"Upload dar file to a participant","description":"Uploads one or more DAR packages already stored in the CBM file store to the target participant. Between 1 and 15 DAR names can be uploaded in a single request; uploads are performed in order and the call returns when all are accepted by the admin API.","operationId":"uploadParticipantDar","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the target participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"darName","in":"query","description":"Names of DAR files in the CBM file store to upload (1 to 15 entries).","required":true,"schema":{"type":"array","items":{"type":"string"},"maxItems":15,"minItems":1}}],"responses":{"200":{"description":"OK"},"400":{"description":"Validation failed (participant name, DAR list size, or unknown DAR).","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Remove a dar from a participant
> Unregisters the DAR identified by its content hash from the given participant. The package contents themselves are not deleted from the ledger; only the registration is removed. The operation is idempotent on success.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-dar-controller","description":"List, upload and remove DAR packages on a Canton participant."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/participants/{name}/dars":{"delete":{"tags":["participant-dar-controller"],"summary":"Remove a dar from a participant","description":"Unregisters the DAR identified by its content hash from the given participant. The package contents themselves are not deleted from the ledger; only the registration is removed. The operation is idempotent on success.","operationId":"removeParticipantDar","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the target participant.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"darHash","in":"query","description":"Content hash of the DAR to remove, as reported by the list endpoint.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"The participant name or DAR hash failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists or the DAR is not registered."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Lists all configured domain connections of a participant
> Returns the list of sync-domain connections registered on the participant, including each domain's alias, URL, parameters and current connection state.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"connection-controller","description":"Configure, register, connect and disconnect a Canton participant against one of its sync domains."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ConnectionDto":{"type":"object","description":"The DTO representing a connection to a domain.","properties":{"connected":{"type":"boolean","description":"It represents the connection status. It is true when the connection is established, false otherwise."},"custom":{"type":"boolean","description":"It represents a custom domain. When it is true the domainUrl should be used, use domainName and port otherwise "},"domainAlias":{"type":"string","description":"This is the alias of the domain to connect to. It does not have to be the same as the actual domain name.","minLength":1},"domainName":{"type":"string","description":"This is name of the domain to connect to. "},"isHADomain":{"type":"boolean","description":"Defines whether the domain name belongs to the HA Domain entity"},"domainUrl":{"type":"string","description":"This is the URL of the domain to connect to. It must be accessible from the participant node. Usage: https://..svc.cluster.local:"},"publicPort":{"type":"string","description":"This is public port of the domain to connect to. "}},"required":["domainAlias"]}}},"paths":{"/participants/{name}/connections":{"get":{"tags":["connection-controller"],"summary":"Lists all configured domain connections of a participant","description":"Returns the list of sync-domain connections registered on the participant, including each domain's alias, URL, parameters and current connection state.","operationId":"listParticipantConnections","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant whose connections to list.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"port","in":"query","description":"Admin gRPC port on which to contact the participant.","required":false,"schema":{"type":"integer","format":"int32","default":5019}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionDto"}}}}},"400":{"description":"The participant name or port failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists.","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionDto"}}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Configures, registers and connects a domain to a participant
> Registers a new sync-domain connection on the participant and immediately connects to it via the participant's admin API. The combination of domain alias and URL must be unique for the participant; a 409 is returned if the participant is already connected to another incompatible domain.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"connection-controller","description":"Configure, register, connect and disconnect a Canton participant against one of its sync domains."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ConnectionDto":{"type":"object","description":"The DTO representing a connection to a domain.","properties":{"connected":{"type":"boolean","description":"It represents the connection status. It is true when the connection is established, false otherwise."},"custom":{"type":"boolean","description":"It represents a custom domain. When it is true the domainUrl should be used, use domainName and port otherwise "},"domainAlias":{"type":"string","description":"This is the alias of the domain to connect to. It does not have to be the same as the actual domain name.","minLength":1},"domainName":{"type":"string","description":"This is name of the domain to connect to. "},"isHADomain":{"type":"boolean","description":"Defines whether the domain name belongs to the HA Domain entity"},"domainUrl":{"type":"string","description":"This is the URL of the domain to connect to. It must be accessible from the participant node. Usage: https://..svc.cluster.local:"},"publicPort":{"type":"string","description":"This is public port of the domain to connect to. "}},"required":["domainAlias"]}}},"paths":{"/participants/{name}/connections":{"post":{"tags":["connection-controller"],"summary":"Configures, registers and connects a domain to a participant","description":"Registers a new sync-domain connection on the participant and immediately connects to it via the participant's admin API. The combination of domain alias and URL must be unique for the participant; a 409 is returned if the participant is already connected to another incompatible domain.","operationId":"createParticipantConnection","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant on which to register the connection.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}},{"name":"port","in":"query","description":"Admin gRPC port on which to contact the participant.","required":false,"schema":{"type":"integer","format":"int32","default":5019}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionDto"}}},"required":true},"responses":{"201":{"description":"Created"},"400":{"description":"The connection payload or participant name failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists."},"409":{"description":"The participant is already connected to another incompatible domain."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Get participant backup schedule
> Returns the current scheduled backup configuration for the participant, including the cron expression and the predicted Unix timestamp of the next run.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-backup-controller","description":"Trigger participant backups, browse backup history and manage scheduled participant backups."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ScheduledBackupDto":{"type":"object","description":"Persisted backup schedule for a Canton workload: cron expression, retention limit and the resolved next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxBackups":{"type":"integer","format":"int32"},"nextRun":{"type":"string"}},"required":["cron"]}}},"paths":{"/participants/{name}/backup":{"get":{"tags":["participant-backup-controller"],"summary":"Get participant backup schedule","description":"Returns the current scheduled backup configuration for the participant, including the cron expression and the predicted Unix timestamp of the next run.","operationId":"getParticipantBackupSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant whose schedule to fetch.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledBackupDto"}}}},"400":{"description":"The participant name failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No backup schedule exists for the given participant.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledBackupDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create participant backup schedule
> Creates a recurring backup schedule (Kubernetes CronJob owned by the participant) that periodically dumps the participant's storage to the configured backup location. The cron expression is validated against the platform's non-enterprise allowed schedule.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-backup-controller","description":"Trigger participant backups, browse backup history and manage scheduled participant backups."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"BackupDto":{"type":"object","description":"Schedule definition used to configure a recurring backup job on a Canton workload (participant or domain). Carries the cron expression that drives the schedule and the maximum number of backups to retain.","properties":{"cron":{"type":"string","minLength":1},"maxBackups":{"type":"integer","format":"int32","minimum":1}},"required":["cron","maxBackups"]},"ScheduledBackupDto":{"type":"object","description":"Persisted backup schedule for a Canton workload: cron expression, retention limit and the resolved next-run timestamp.","properties":{"cron":{"type":"string","minLength":1},"maxBackups":{"type":"integer","format":"int32"},"nextRun":{"type":"string"}},"required":["cron"]}}},"paths":{"/participants/{name}/backup":{"post":{"tags":["participant-backup-controller"],"summary":"Create participant backup schedule","description":"Creates a recurring backup schedule (Kubernetes CronJob owned by the participant) that periodically dumps the participant's storage to the configured backup location. The cron expression is validated against the platform's non-enterprise allowed schedule.","operationId":"createParticipantBackupSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant to back up.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackupDto"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledBackupDto"}}}},"400":{"description":"The body, cron expression, or participant name failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No participant with the given name exists.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ScheduledBackupDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Delete participant backup schedule
> Removes the scheduled backup CronJob for the participant. Existing backup files already produced in the backup location are not deleted.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"participant-backup-controller","description":"Trigger participant backups, browse backup history and manage scheduled participant backups."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/participants/{name}/backup":{"delete":{"tags":["participant-backup-controller"],"summary":"Delete participant backup schedule","description":"Removes the scheduled backup CronJob for the participant. Existing backup files already produced in the backup location are not deleted.","operationId":"deleteParticipantBackupSchedule","parameters":[{"name":"name","in":"path","description":"Kubernetes resource name of the participant whose schedule should be removed.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"The participant name failed validation.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No backup schedule exists for the given participant."},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## List validator identity dumps
> Returns the identity dump secrets currently stored for a single validator, ordered by creation time.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-id-dumps-controller","description":"Trigger and schedule validator identity dump jobs and download their artifacts."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"IdDumpDto":{"type":"object","description":"Identity-dump artifact metadata: name of the Kubernetes secret holding the dump, the owning validator name and the timestamp at which it was captured.","properties":{"secretName":{"type":"string"},"validatorName":{"type":"string"},"timestamp":{"type":"integer","format":"int64"},"createdAt":{"type":"string"}}}}},"paths":{"/id-dumps/{validatorName}":{"get":{"tags":["validator-id-dumps-controller"],"summary":"List validator identity dumps","description":"Returns the identity dump secrets currently stored for a single validator, ordered by creation time.","operationId":"listParticipantIdentityDumps","parameters":[{"name":"validatorName","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IdDumpDto"}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Create validator identity dump
> Synchronously requests an identity dump from the validator's wallet and stores it as a Kubernetes secret. The dump can later be used to recover or transfer the validator's identity.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"validator-id-dumps-controller","description":"Trigger and schedule validator identity dump jobs and download their artifacts."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"IdDumpDto":{"type":"object","description":"Identity-dump artifact metadata: name of the Kubernetes secret holding the dump, the owning validator name and the timestamp at which it was captured.","properties":{"secretName":{"type":"string"},"validatorName":{"type":"string"},"timestamp":{"type":"integer","format":"int64"},"createdAt":{"type":"string"}}}}},"paths":{"/id-dumps/{validatorName}":{"post":{"tags":["validator-id-dumps-controller"],"summary":"Create validator identity dump","description":"Synchronously requests an identity dump from the validator's wallet and stores it as a Kubernetes secret. The dump can later be used to recover or transfer the validator's identity.","operationId":"createIdentityDump","parameters":[{"name":"validatorName","in":"path","description":"Kubernetes resource name of the validator.","required":true,"schema":{"type":"string","maxLength":47,"minLength":1,"pattern":"[a-z]([-a-z0-9]*[a-z0-9])?([a-z0-9]([-a-z0-9]*[a-z0-9])?)*"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/IdDumpDto"}}}},"400":{"description":"The supplied validator name is invalid.","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"404":{"description":"No validator exists with the given name.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/IdDumpDto"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Proxy an HTTP request to an internal service
> Forwards the provided HTTP method, URL, headers and body to an internal Canton or Splice service that is not directly exposed outside the cluster, and returns the upstream response. Timestamps in the URL are normalized to ISO-8601 with millisecond precision and a 'Z' suffix.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"proxy-controller","description":"HTTP proxy endpoints used to forward requests to internal Canton / Splice services (including validator API access-token retrieval)."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ProxyRequestDto":{"type":"object","description":"Generic HTTP proxy request: target URL, method, custom headers and body forwarded by the proxy controller.","properties":{"url":{"type":"string"},"method":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"body":{"type":"string"}}}}},"paths":{"/http-proxy":{"post":{"tags":["proxy-controller"],"summary":"Proxy an HTTP request to an internal service","description":"Forwards the provided HTTP method, URL, headers and body to an internal Canton or Splice service that is not directly exposed outside the cluster, and returns the upstream response. Timestamps in the URL are normalized to ISO-8601 with millisecond precision and a 'Z' suffix.","operationId":"proxyRequest","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyRequestDto"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Retrieve an access token for the validator API
> Performs an OAuth login against the validator wallet using stored credentials combined with the supplied password, and returns a bearer token usable for validator API calls.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"proxy-controller","description":"HTTP proxy endpoints used to forward requests to internal Canton / Splice services (including validator API access-token retrieval)."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PasswordDto":{"type":"object","description":"Wrapper around a single password value; used by endpoints that update credentials in isolation.","properties":{"password":{"type":"string","minLength":1}},"required":["password"]},"OauthLoginResponse":{"type":"object","description":"Token response returned by the OAuth2 login flow (access token).","properties":{"access_token":{"type":"string"}}}}},"paths":{"/http-proxy/validator-api-access-token":{"post":{"tags":["proxy-controller"],"summary":"Retrieve an access token for the validator API","description":"Performs an OAuth login against the validator wallet using stored credentials combined with the supplied password, and returns a bearer token usable for validator API calls.","operationId":"getValidatorApiAccessToken","parameters":[{"name":"validator","in":"query","description":"Name of the validator whose wallet credentials should be used","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordDto"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/OauthLoginResponse"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## List stored files with filtering and pagination
> Returns a page of files in the CBM file storage, optionally filtered by type and name. Supports offset/limit pagination via the from and limit query parameters.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"file-storage-controller","description":"Upload, list and remove files used by validators, participants and domains (DAR packages, identity dumps, configuration archives, …)."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer `.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"FileFilterResponseDto":{"type":"object","description":"Paginated list of `FileDto` entries plus the total count of stored files matching the filter.","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/FileDto"}},"totalCount":{"type":"integer","format":"int64"}}},"FileDto":{"type":"object","description":"File DTO","properties":{"name":{"type":"string","description":"Name of the file"},"sizeInBytes":{"type":"integer","format":"int64","description":"Size of the file in bytes"}}}}},"paths":{"/files":{"get":{"tags":["file-storage-controller"],"summary":"List stored files with filtering and pagination","description":"Returns a page of files in the CBM file storage, optionally filtered by type and name. Supports offset/limit pagination via the from and limit query parameters.","operationId":"listFiles","parameters":[{"name":"fileType","in":"query","description":"Filter by file type/category","required":false,"schema":{"type":"string","enum":["DAR","UI_PACKAGE"]}},{"name":"from","in":"query","description":"Zero-based index of the first file to return","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"limit","in":"query","description":"Maximum number of files to return","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"name","in":"query","description":"Filter by file name (substring match)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FileFilterResponseDto"}}}},"400":{"description":"Invalid filter or pagination parameters","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"type":"object"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"type":"object"}}}}}}}}}
```
## Upload files to server-side storage
> Uploads one or more files of the given type (DAR, identity dump, config, etc.) into the CBM-managed file storage so they can later be consumed by Canton workloads. File extensions are validated against the declared file type.
```json
{"openapi":"3.1.0","info":{"title":"Catalyst Blockchain Manager: Canton Console API","version":"1.0.0-local"},"tags":[{"name":"file-storage-controller","description":"Upload, list and remove files used by validators, participants and domains (DAR packages, identity dumps, configuration archives, …)."}],"servers":[{"url":"http://localhost:8080/api","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Bearer JWT issued by the configured OAuth2 / OIDC provider (typically Keycloak or Auth0). Pass as `Authorization: Bearer
.png?alt=media){kind=link}
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
