> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/architecture.md).

# 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.

<table><thead><tr><th width="220">Software system</th><th>Functional responsibilities</th><th width="220">Interfaces</th></tr></thead><tbody><tr><td>CatalyX Blockchain Manager</td><td>Canton and Daml infrastructure provisioning, application deployment, and operations.</td><td>CatalyX UI, HTTP API, Kubernetes custom resources</td></tr><tr><td>Identity provider</td><td>User management, RBAC.</td><td>Web UI, API (OAuth / OIDC)</td></tr><tr><td>Canton nodes</td><td>Distributed ledger.</td><td>REST API, gRPC API, TCP</td></tr><tr><td>Canton applications</td><td>End-user Daml applications.</td><td>Web UI, HTTP API</td></tr></tbody></table>

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.

<div data-with-frame="true"><figure><img src="https://2680825251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUGPGTcyMu8FXsdY8XQY%2Fuploads%2Fgit-blob-0abee83c4741504b219f4623e7afb8cd1c431abb%2FCatalyx2-Architecture.png?alt=media" alt=""><figcaption><p>High Level Architecture</p></figcaption></figure></div>

### CatalyX Components

<table><thead><tr><th width="230">Component</th><th>Functional responsibilities</th><th width="180">Interfaces</th></tr></thead><tbody><tr><td>CAT-BM Canton UI</td><td>User interface for the Canton infrastructure and application operator.</td><td>Web UI</td></tr><tr><td>CAT-BM Canton API</td><td>Backend API for the user interface and third-party integrations.</td><td>REST API</td></tr><tr><td>CAT-BM Canton Operator</td><td>Kubernetes operator for Canton deployment operations.</td><td>Kubernetes custom resource definitions for Canton infrastructure</td></tr><tr><td>Canton Nodes</td><td>Canton DLT infrastructure.</td><td>gRPC API, REST API</td></tr><tr><td>Identity Provider</td><td>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).</td><td>Web UI, API (OAuth / OIDC)</td></tr></tbody></table>

***

### CatalyX management plane

Three components make up the CatalyX management plane. They are installed together by a single Helm chart.

<details>

<summary>Catalyx-operator</summary>

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 |

</details>

<details>

<summary>Catalyx-api</summary>

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.

</details>

<details>

<summary>Catalyx-ui</summary>

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.

</details>

***

### 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.

<details>

<summary>Enterprise-grade security</summary>

* 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.

</details>

<details>

<summary>GitOps-driven operations</summary>

* 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.

</details>

<details>

<summary>Infrastructure-as-Code</summary>

* 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.

</details>

<details>

<summary>Automated lifecycle management</summary>

* CAT-BM automates node provisioning, dependency management, certificate distribution, and topology orchestration.
* Built-in support for scaling, patching, and configuration updates through CRDs.

</details>

<details>

<summary>Monitoring and observability</summary>

* 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.

</details>

<details>

<summary>Scalability and extensibility</summary>

* Horizontal and vertical pod autoscaling based on resource usage.
* Support for multi-tenant deployments and workload isolation via Kubernetes namespaces and network policies.

</details>

***

## 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 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.