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 with the `pg_trgm` extension	Omnibus structure metadata, virtual accounts, deposit wallets, reservations, quarantined balances, operations, transfers, and event-processing state. If the extension isn't available, the service fails its schema migration and doesn't start.
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. The HMZ_FEATURE_OMNIBUS deployment flag controls whether the console displays the omnibus pages, including omnibus account creation. 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. The target database requires the `pg_trgm` extension.	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. You can also manage thresholds per domain at runtime with the sweep thresholds API.	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:

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 context.submitter.subject or context.submitter.custodyRoles.

For activation details, see System-signed intent configuration. For the Omnibus policy shape, see Setup and governance.

Topic	Documentation
Omnibus concepts	Omnibus
Setup and governance	Setup and governance
Gas Station	Gas Station reference
PostgreSQL	PostgreSQL configuration
Telemetry	Telemetry configuration