# Omnibus reference

Use this page to understand the main deployment settings and runtime relationships for the Omnibus Service. The example shows one possible configuration shape; your release package, database, secrets, and workflow settings can differ.

This page applies to on-premise deployments. Ripple manages Omnibus deployment for SaaS.

## What this config controls

Omnibus is a pooled-custody add-on that uses one custody account as the omnibus wallet and tracks tenant positions in off-chain virtual account records. It stores operational state in PostgreSQL, coordinates long-running workflows, records settled balance movements in the Accounting Service, and uses system-signed intents for automated operations such as deposit wallet creation, deposit sweeps, and ledger propagation.

## Runtime dependencies

Before deploying Omnibus, confirm connectivity to:

| Dependency | Used for |
|  --- | --- |
| Ripple Custody API gateway | Domains, accounts, intents, events, balances, and transaction state. |
| PostgreSQL | Omnibus structure metadata, virtual accounts, deposit wallets, reservations, quarantined balances, operations, transfers, and event-processing state. |
| Temporal | Multi-step workflow orchestration and retries. |
| Accounting Service | Settled virtual account balances, entries, statements, and exports. |
| Notification Server | User-signed operations such as omnibus creation and withdrawals. |
| Gas Station | Native-token sponsorship for non-native token sweeps on supported Solana, XRPL, and EVM networks. |
| System-signed intents | Service-submitted automation intents for deposit wallet creation, deposit sweeps, and ledger propagation. |


## Configuration fields

The exact field names depend on your deployment package. Omnibus commonly needs settings like the following:

| Parameter | Description | Required |
|  --- | --- | --- |
| `CUSTODY_API_URL` | Ripple Custody API gateway URL. | Yes |
| `ACCOUNTING_SERVICE_URL` | Accounting Service URL used for ledger entries, balances, and statements. | Yes |
| `NOTIFICATION_SERVER_URL` | Notification Server URL used for user-signing flows. | Yes |
| `TEMPORAL_ADDRESS` | Temporal cluster address. | Yes |
| `POSTGRES_URL` | PostgreSQL connection string. | Yes |
| Service authentication settings | Deployment-specific settings that let the Omnibus service authenticate to the Ripple Custody API gateway. | Yes |
| `EVENT_POLL_INTERVAL_MS` | Polling interval for custody events. | No |
| `MIN_SWEEP_AMOUNT_*` | Per-ticker dust threshold for deposit sweeps, expressed in the ticker's smallest unit. | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry collector endpoint. | No |


Secrets
Store database credentials and service-authentication secrets in your secret-management system. Do not put secrets directly in values files or source control.

## Deployment values

This example shows one possible Omnibus configuration shape:


```yaml
omnibus:
  enabled: true
  custodyApiUrl: "https://gateway.example.com"
  accountingServiceUrl: "http://accounting-service:8080"
  notificationServerUrl: "http://notification-server:8080"
  temporalAddress: "temporal.example.com:7233"
  eventPollIntervalMs: 5000

  database:
    host: "postgres.example.com"
    port: 5432
    name: "omnibus"
    username: "omnibus_user"
    existingSecret: "omnibus-db-credentials"

  serviceAuthentication:
    existingSecret: "omnibus-service-auth"

  dustThresholds:
    MIN_SWEEP_AMOUNT_USDC: "1000000"

  telemetry:
    enabled: true
    otlpEndpoint: "http://otel-collector:4317"
```

## Database state

Omnibus stores structure metadata, virtual accounts, deposit wallets, local reservations, local quarantined balances, operations, transfers, event processing state, and workflow correlation data.

The Accounting Service remains the source of truth for settled available balances. Omnibus limits local balance data to transient reserved and quarantined states.

## Workflows

Omnibus uses workflow orchestration for multi-step operations such as:

- Omnibus creation.
- Deposit wallet creation.
- Deposit detection, quarantine release tracking, and sweeps.
- Withdrawals.
- Ledger propagation from the omnibus wallet to deposit wallets.
- Incoming direct deposits to the omnibus wallet.


Configure workflow retention, retry, and worker scaling according to your expected event volume.

## Event polling

Omnibus monitors custody events such as:

- `TransactionDetected`
- `TransactionUpdated`
- `TransferUpdated`
- `AccountCreated`
- `AccountUpdated`
- `PolicyCreated`


When multiple Omnibus replicas run, stable workflow IDs and event IDs provide idempotency and duplicate suppression.

## System-signed automation

Omnibus automation uses system-signed intents. Before the service submits automation intents, the deployment must have system-signed intents active and the target domain must have a matching `SystemSigned` policy.

Confirm that:

- Gateway can sign system-signed proposals.
- The active Gateway public signing key is registered in Notary with `purpose: "SystemSignatures"`.
- `NOTARY_SYSTEM_SIGNED_INTENTS_ENABLED` is set to `enabled: true`.
- The Omnibus domain has a policy with `intentOrigin: "SystemSigned"` for `v0_CreateAccount`, `v0_CreateTransactionOrder`, and `v0_AddAccountLedgers`.
- The policy condition matches the Omnibus service submitter, such as `submitter.subject` or `submitter.custodyRoles`.


For activation details, see [System-signed intent configuration](/products/custody/deployment/reference/system-signed-intents). For the Omnibus policy shape, see [Setup and governance](/products/custody/accounts-and-assets/omnibus/setup-and-governance#required-policy).

## Related topics

| Topic | Documentation |
|  --- | --- |
| Omnibus concepts | [Omnibus](/products/custody/accounts-and-assets/omnibus/overview) |
| Setup and governance | [Setup and governance](/products/custody/accounts-and-assets/omnibus/setup-and-governance) |
| Gas Station | [Gas Station reference](/products/custody/deployment/reference/gas-station) |
| PostgreSQL | [PostgreSQL configuration](/products/custody/deployment/reference/postgresql) |
| Telemetry | [Telemetry configuration](/products/custody/deployment/reference/telemetry-configuration) |