> 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/validator-management/wallet-gateway.md).

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

<table><thead><tr><th width="250">Approach</th><th>Keys held by</th><th>Suits</th></tr></thead><tbody><tr><td>Participant-managed party</td><td>The participant node</td><td>Parties the operator legitimately acts for.</td></tr><tr><td><a href="/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties.md">External party</a></td><td>The party's owner, directly</td><td>Counterparties who hold their own keys and sign for themselves.</td></tr><tr><td><strong>Wallet Gateway</strong></td><td>An external custody provider</td><td>Parties that need custodial key management with institutional controls, without either side running key infrastructure.</td></tr></tbody></table>

{% 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.md) 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-<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](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/summary.md) tab and on the [Applications](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/applications.md) 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: <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.

<table><thead><tr><th width="330">Requirement</th><th>Why</th></tr></thead><tbody><tr><td><code>walletGateway.version</code></td><td>Required when enabled; it does not fall back to <code>spliceVersion</code>.</td></tr><tr><td><code>auth.enabled: true</code></td><td>The Wallet Gateway cannot run without authentication.</td></tr><tr><td><code>auth.targetAudience</code> and <code>auth.ledgerApiUserManagementScope</code></td><td>Needed for both browser and machine-to-machine flows.</td></tr><tr><td>An auth URL, a backend client ID, and a Wallet Gateway client ID</td><td>Provisioned for you under managed authentication; supplied by you with an external identity provider.</td></tr><tr><td><code>database.walletGatewayStoreDatabase</code> and <code>walletGatewaySigningDatabase</code></td><td>Both are required — supplying only one fails.</td></tr><tr><td><code>database.credentialsSecretRef</code></td><td>The databases are provisioned with these credentials.</td></tr></tbody></table>

### Provider credentials

```bash
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`.

{% 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.

<table><thead><tr><th width="90">Method</th><th width="420">Path</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>/api/v1/validators/{name}/wallet-gateway/providers/dfns</code></td><td>Reads the current settings. Never returns credentials.</td></tr><tr><td>PUT</td><td><code>/api/v1/validators/{name}/wallet-gateway/providers/dfns</code></td><td>Updates the settings. Each field is optional per call, so rotating just a credential doesn't require resending the rest.</td></tr></tbody></table>

{% 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.md) 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.md) — 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.md) — protecting the *participant's* keys, a separate concern


---

# 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/validator-management/wallet-gateway.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.