> 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

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

The Wallet Gateway is an optional validator component that provides a remote wallet whose signing keys are held by an external Wallet-as-a-Service (WaaS) provider rather than by the participant or by the end user.

<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="/pages/Rv7ESflF3JDlSKmxVVTb">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>

## Why use it

* **Private keys never touch application code or platform infrastructure.** All signing is delegated to the provider.
* **Institutional custody controls** — the provider's access policies, approval workflows, and audit trail apply to every signing operation.
* **HSM backing and compliance** — where the provider offers it, key storage can satisfy FIPS 140-2 and comparable requirements.
* **One provisioning path** — validators and their parties are managed through the same provider API.

***

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

***

## 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 catalyx-system
```

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 %}

***

## 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 are written into a ConfigMap.** The generated configuration file contains the PostgreSQL username and password in cleartext, and it is delivered as a Kubernetes ConfigMap in the validator's namespace. Anyone who can read ConfigMaps in that namespace can read those credentials. Restrict `get configmap` in the namespace 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
* [Security & Privacy](/catalyx-blockchain-manager/canton-network/version-2.0/architecture/security-and-privacy.md) — the platform's WaaS integration model


---

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