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.
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.
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 tab, under Connected Synchronizers.
I changed the Validator resource and nothing happened.
Check three things, in order:
Observed Generation on the Status tab. If it lags behind, the change has not been reconciled.
The
Readycondition. A reason ofInvalidSpecmeans the operator rejected your change and the message names the field.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 <name> -o yamland look for it.
Where is ledger pruning?
It is not exposed in the CatalyX UI in 2.0. Prune through the 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 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.
I click a Grafana link and get "Forbidden".
The link resolved and you're authenticated, but your account hasn't been granted access to that dashboard. Access is provisioned by IntellectEU, separately per customer. See Access and permissions.
Validator and Canton Network Upgrades
What is the difference between a version upgrade and a protocol upgrade?
A version upgrade updates the validator software independently on each node — this is what spliceVersion covers. A protocol upgrade changes the Canton Network protocol itself and is coordinated across the network, using the Logical Synchronizer Upgrade (LSU) mechanism in modern releases. See Platform and Canton Upgrades.
Where can I find the upgrade schedules?
Upgrade calendar and schedules can be found at https://sv-cal.canton.foundation
Does every upgrade require downtime?
Not necessarily. Validator component upgrades typically require a brief rolling restart. Protocol upgrades using LSU are designed to minimize service interruption and let applications keep operating during the transition.
Can validators be upgraded independently?
Yes, for version upgrades — each validator operator upgrades independently, within a compatible range of the platform. Protocol upgrades are coordinated across the Canton Network on a scheduled activation time.
Should upgrades be tested before Production?
Yes. Component versions are set per validator, so IntellectEU recommends upgrading a non-production validator first. See Before you upgrade.
What happens if I delay upgrading?
Running an outdated validator version may eventually lead to:
package compatibility issues;
inability to participate in newer protocol versions;
application compatibility issues;
unsupported configurations;
reduced compatibility with newer Canton features.
Customers are encouraged to remain on supported versions and follow upgrade recommendations published by the Canton Foundation and validated by IntellectEU.
Does every version upgrade require a migration?
No. Many upgrades only require updating the validator software. Some releases introduce application or database changes that require a migration. Always review the release notes for the target version.
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.
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 last?
Upgrade duration depends on:
validator size,
database size,
whether migrations are required,
infrastructure performance.
Most routine upgrades complete within a planned maintenance window.
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.
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.
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.
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.
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.
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.
Last updated
Was this helpful?