# Setup and governance

Set up Omnibus in an existing Ripple Custody domain. The domain provides the vault assignment, user roles, account policies, compliance controls, and transaction governance that apply to the omnibus wallet and deposit wallets.

Before you begin
Omnibus automation uses system-signed intents to create deposit wallets, sweep deposits, and propagate ledgers. Before you make an omnibus structure operational, activate system-signed intents in Notary and create a narrowly scoped policy that allows the Omnibus service to submit only the required automation intent types.

## Prerequisites

Before creating an omnibus structure, confirm that you have:

- An existing domain for the omnibus structure.
- A vault assigned to the domain.
- Tickers and ledgers configured for the assets you intend to support.
- System-signed intents activated for the deployment.
- A system-signed policy that gives the Omnibus service access to required automated operations.
- Gas Station configured for just-in-time fee funding if non-native token sweeps require sponsored gas.
- Monitoring and balance-operations ownership defined.


For domain and policy concepts, see [Domains](/products/custody/v1.36/governance/domains) and [Policies](/products/custody/v1.36/governance/policies). For the system-signed intent activation sequence, see [System-signed intent configuration](/products/custody/v1.36/deployment/reference/system-signed-intents).

## Domain model

Omnibus supports one omnibus structure per domain. Create all related custody accounts in that domain:

- The omnibus wallet.
- Virtual accounts, including the host virtual account.
- Deposit wallets created for virtual accounts.


Using a dedicated domain for each omnibus structure keeps policy scope, audit, monitoring, and support boundaries clearer.

## System-signed automation

Omnibus uses system-signed intents for automated operations that do not require a user to sign each request. The Omnibus service still authenticates as a service caller, and policy conditions should identify that service caller with `submitter.subject` or `submitter.custodyRoles`.

Before Omnibus submits system-signed automation intents:

1. Gateway must be configured for system-signed intents.
2. The active Gateway system signing public key must be registered in Notary with `purpose: "SystemSignatures"`.
3. `NOTARY_SYSTEM_SIGNED_INTENTS_ENABLED` must be set to `enabled: true`.
4. A matching policy with `intentOrigin: "SystemSigned"` must allow the Omnibus service to submit the required intent types.


System-signed intent configuration is enabled by default at deployment level in current release packages, but system-signed traffic remains disabled until the Notary key registration, system property, and policy are in place.

For the full deployment and activation sequence, see [System-signed intent configuration](/products/custody/v1.36/deployment/reference/system-signed-intents).

## Required policy

The Omnibus service needs a manually created policy that matches its system-signed automation intents:

| Automated operation | Intent type | Policy condition guidance |
|  --- | --- | --- |
| Create deposit wallets | `v0_CreateAccount` | Match the Omnibus service submitter and scope the policy to the omnibus domain. |
| Sweep deposits | `v0_CreateTransactionOrder` | Match the Omnibus service submitter and constrain the destination to the omnibus wallet where possible. |
| Propagate ledgers | `v0_AddAccountLedgers` | Match the Omnibus service submitter and constrain target accounts to Omnibus deposit wallets where possible. |


Use `intentOrigin: "SystemSigned"` and specify only the required intent types:


```json
{
  "intentTypes": [
    "v0_CreateAccount",
    "v0_CreateTransactionOrder",
    "v0_AddAccountLedgers"
  ],
  "intentOrigin": "SystemSigned",
  "condition": {
    "expression": "submitter.type === 'Service' && submitter.custodyRoles.includes('omnibus')",
    "type": "Expression"
  }
}
```

Use the service role or subject value that your deployment issues to the Omnibus service. If the policy includes an approval workflow, user-signed approvers must satisfy it; the service submitter does not count as a user approval.

Policy governance
Do not give Omnibus automation unrestricted permission to create or update policies. Policy creation changes the governance model itself and should remain controlled by independent policy-management approvals.

## Creation flow

Creating an omnibus structure has two phases:

1. **Create the omnibus wallet**: The user initiates the Omnibus creation flow with `alias`, `vaultId`, and `keyStrategy`, plus optional ledger, description, custom-property, ignored-account, and Gas Station settings. Omnibus validates the domain, prepares a custody account creation intent, and returns the omnibus record with an unsigned Custody intent payload. The client signs that payload and submits it to `POST /v1/intents`.
2. **Set up automation**: Omnibus creates the host virtual account, initializes Accounting Service state, validates the required system-signed automation policy state, configures the omnibus wallet to skip quarantine for intra-domain sweeps, and checks Gas Station sponsorship. Review any policy intents your deployment requires through your normal governance process before treating the omnibus structure as operational.



```mermaid
sequenceDiagram
    actor Operator
    participant Omnibus as Omnibus Service
    participant Custody as Custody API
    participant Accounting as Accounting Service

    Operator->>Omnibus: POST create omnibus request
    Omnibus->>Custody: Dry-run create account intent
    Omnibus-->>Operator: Omnibus record and unsignedIntent
    Operator->>Operator: Sign unsignedIntent
    Operator->>Custody: POST /v1/intents with signed request
    Custody-->>Omnibus: AccountCreated event
    Omnibus->>Accounting: Initialize host virtual account
    Omnibus->>Custody: Set skipQuarantineFrom to Domain
    Omnibus->>Omnibus: Validate system-signed automation policy
    Omnibus-->>Operator: Omnibus operational
```

## Gas Station setup

Omnibus can use [Gas Station](/products/custody/v1.36/accounts-and-assets/gas-station/overview) for non-native token sweeps and withdrawals on supported Solana, XRPL, and EVM networks. Gas Station provides native gas to the deposit wallet or omnibus wallet that needs to broadcast the token transaction.

For native asset withdrawals, the host virtual account is responsible for the native network transaction fee in Omnibus accounting. Fee compensation or reimbursement records for Gas Station-funded non-native withdrawal gas depend on the final Omnibus accounting behavior for your release.

Plan the sponsorship model before creating the omnibus structure:

- Domain-wide sponsorship is simpler when all omnibus-related accounts need sponsorship.
- Account-level sponsorship limits sponsorship to selected accounts.
- Use just-in-time sponsorship. Fund the sponsor account, but do not pre-fund each Omnibus deposit wallet.
- Add the Gas Station account ID to the Omnibus ignored-account list at creation so native-token funding transactions are not processed as customer deposits.


When Omnibus configures the omnibus wallet for intra-domain sweeps, it uses the account compliance configuration API to set `skipQuarantineFrom` to `Domain`. This lets sweeps from deposit wallets arrive at the omnibus wallet without a second quarantine cycle. External deposits to deposit wallets still follow the normal confirmation and quarantine-release flow.

For configuration steps, see [Configure gas sponsorship](/products/custody/v1.36/accounts-and-assets/gas-station/configure-sponsorship).

## Locking and unlocks

Omnibus supports lock states at two levels:

| Lock target | Effect |
|  --- | --- |
| Omnibus structure | Blocks new withdrawals, internal transfers, and deposit wallet creation. Deposit detection and sweeps continue. |
| Virtual account | Blocks new operations for the associated tenant. Existing in-flight operations continue. |


Use locks for operational holds, incident response, or customer lifecycle events. Locks are not a replacement for custody policies on on-chain withdrawals.

## Ledger propagation

When an operator adds a ledger to the omnibus wallet, Omnibus propagates that ledger to existing deposit wallets. This lets new deposits use the same ledger coverage as the omnibus wallet.

Ledger propagation is one-way:

- Add ledgers to the omnibus wallet.
- Let Omnibus add missing ledgers to deposit wallets.
- Avoid adding ledgers directly to deposit wallets.


If a deposit wallet has a ledger that the omnibus wallet does not support, sweeps on that ledger can fail until an operator resolves the mismatch.

## Operational responsibilities

| Responsibility | Owner |
|  --- | --- |
| Domain and policy design | Customer operations and governance owners |
| System-signed intent activation | Customer platform/security team for on-premise, Ripple for managed SaaS where applicable |
| Omnibus system-signed policy governance | Customer operations and governance owners |
| Gas Station funding | Customer operations team |
| Sweep failure monitoring | Platform operations |
| Balance monitoring | Backoffice operations |
| Tenant-to-user mapping | Customer integration or business system |