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

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.

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

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.

---

Supported versions

Component	Version
Canton Protocol	v2.10 or higher
Daml	v2.10 or higher