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.

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.

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.

Approach	Keys held by	Suits
Participant-managed party	The participant node	Parties the operator legitimately acts for.
External party	The party's owner, directly	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.

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 still applies even for a party custodied here. See What's not yet available.

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-<validator-name>.<baseHostname>, 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 tab and on the 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 below.

---

Enabling it

spec:
  auth:
    enabled: true
    managedKeycloak: true
    targetAudience: https://canton.network.global
    ledgerApiUserManagementScope: daml_ledger_api

  walletGateway:
    enabled: true
    version: "v1.7.0"
    dfns:
      orgId: <organisation-id>
      apiUrl: <provider-api-url>
      credentialId: <credential-id>
      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

kubectl create secret generic my-validator-waas-credentials \
  --from-literal=private-key=<provider-private-key> \
  --from-literal=auth-token=<provider-auth-token> \
  -n <namespace>

The key names default to private-key and auth-token, and can be overridden on the credentialsSecretRef.

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.

---

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.

Method	Path	Purpose
GET	/api/v1/validators/{name}/wallet-gateway/providers/dfns	Reads the current settings. Never returns credentials.
PUT	/api/v1/validators/{name}/wallet-gateway/providers/dfns	Updates the settings. Each field is optional per call, so rotating just a credential doesn't require resending the rest.

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.

---

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.

Wallets the validator signs for itself — i.e. not custodied externally — are not shown here. Those already appear on the Parties tab.

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.

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

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

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.

---

Security considerations

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.

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 — the alternative, where the party holds its own keys

• Key Management Service (KMS) — protecting the participant's keys, a separate concern