# Domains

Executive summary
**A domain is an organizational boundary that groups accounts, users, and policies under a single governance structure.**

- Domains form a hierarchy (parent → child) mirroring your business structure.
- Data is isolated. Users can only access their assigned domain and its subdomains.
- Policies can cascade down the hierarchy or be enforced at specific levels.
- Governing strategies control whether child domains can override parent policies.


Why this matters
Domains are your primary tool for segregating assets, users, and governance rules. Proper domain design directly impacts your ability to meet regulatory requirements (client asset segregation), enforce operational controls (regional policies), and scale your custody operations (adding new business units or clients). Misconfigured domain hierarchies can lead to unintended policy bypasses or access violations.

**For architects and operators**: Your domain structure is defined in the genesis block and is foundational — plan carefully before deployment. Consider how governing strategies (`ConsiderDescendants` vs. `CoerceDescendants`) will affect policy inheritance as you add subdomains.

## What are domains?

A domain is a logical container that:

- **Segregates data**: Users, accounts, vaults, and other entities belong to specific domains
- **Defines governance boundaries**: Policies are defined at the domain level and control actions within that domain
- **Establishes user access**: Users can only operate within their assigned domain (and potentially its subdomains)


Think of domains as organizational units that mirror your business structure — headquarters, regional offices, business units, or client segregation.

## Domain hierarchy

Domains form a tree structure with a single **root domain** at the top and **subdomains** beneath it.


```mermaid
flowchart TB
    Root["Root Domain<br/>(Company HQ)"]
    A["Subdomain A<br/>(APAC Region)"]
    A1["Subdomain A1<br/>(Japan Office)"]
    A2["Subdomain A2<br/>(Singapore Office)"]
    B["Subdomain B<br/>(EMEA Region)"]
    B1["Subdomain B1<br/>(London Office)"]
    C["Subdomain C<br/>(Americas Region)"]

    Root --> A
    Root --> B
    Root --> C
    A --> A1
    A --> A2
    B --> B1
```

### Key hierarchy rules

| Rule | Description |
|  --- | --- |
| **Single root** | Every environment has exactly one root domain |
| **Parent-child relationships** | Each subdomain has exactly one parent domain |
| **No upward access** | Users cannot submit intents to parent domains, only to their own domain or its subdomains |
| **Inheritance** | Subdomains can inherit policies from parent domains (depending on configuration) |


### Compliance domains

A **compliance domain** is a specialized domain that manages transaction screening and Travel Rule compliance. When you enable compliance features, you create a compliance domain as a child of the root domain. Transaction screening then applies to all accounts in the compliance domain's child domains.

This pattern uses the domain hierarchy to scope compliance:

- The compliance domain contains compliance-specific users (compliance managers, supervisor agents)
- Child domains inherit the compliance policies from the compliance domain
- You can use [domain injection](#domain-injection) to insert a compliance domain between the root and existing child domains


For setup instructions, see [Create a compliance domain](/products/custody/v1.34/ui/transaction-screening-and-risk-management#create-a-compliance-domain).

## Multi-tenancy

The domain hierarchy enables multi-tenancy patterns:

- **Business unit segregation**: Separate domains for different parts of your organization
- **Client segregation**: Each client in its own subdomain with isolated data
- **Regulatory boundaries**: Domains aligned with jurisdictional requirements
- **Environment separation**: Development, staging, and production as separate domain trees


Data entities (accounts, vaults, users) belong to exactly one domain and cannot be directly accessed from other domains.

## Governing strategies

A domain's **governing strategy** determines how its policies interact with subdomain policies.

### ConsiderDescendants

The parent domain's policies are **considered alongside** subdomain policies. Both the parent and child policies may apply to intents in the subdomain.


```mermaid
flowchart TB
    subgraph Parent["Parent Domain"]
        PP["Parent policy:<br/>All transfers need 1 approval"]
    end
    subgraph Child["Child Domain"]
        CP["Child policy:<br/>High-value transfers need CFO approval"]
    end
    Parent --> Child
    Result["Result: Both policies apply<br/>to high-value transfers"]
    Child --> Result
```

**Use case**: Establishing baseline rules while allowing subdomains to add their own requirements.

### CoerceDescendants

The parent domain's policies **override** subdomain policies for matching intents. The subdomain's own policies are ignored when the parent has a matching policy.


```mermaid
flowchart TB
    subgraph Parent["Parent Domain"]
        PP["Parent policy:<br/>All transfers need 3 approvals"]
    end
    subgraph Child["Child Domain"]
        CP["Child policy:<br/>Transfers need 1 approval<br/>(IGNORED)"]
    end
    Parent --> Child
    Result["Result: Only parent policy applies<br/>3 approvals required"]
    Child --> Result
```

**Use case**: Enforcing organization-wide rules that cannot be weakened by subdomains. Essential for [breakglass policies](/products/custody/v1.34/concepts/governance/policies#breakglass-policies)—emergency override mechanisms that allow senior management to bypass normal approval workflows in exceptional circumstances (e.g., court orders, lost keys, misconfigured policies).

## Policy scope

Policies use **scope** settings to define where they apply:

| Scope | Description |
|  --- | --- |
| `Self` | Policy applies only to intents targeting this domain |
| `Descendants` | Policy applies only to intents targeting subdomains |
| `SelfAndDescendants` | Policy applies to both this domain and all subdomains |


The combination of governing strategy (on domains) and scope (on policies) determines the complete policy application behavior.

For detailed examples, see [Policy scope](/products/custody/v1.34/concepts/governance/policies#policy-scope).

## Domain lifecycle

Domains progress through several states:

| State | Description |
|  --- | --- |
| **Created** | Domain exists and is operational |
| **Locked** | Domain is disabled; no intents can be executed within it |
| **Unlocked** | Domain is re-enabled after being locked |


Locking a domain is useful for:

- Suspending a business unit
- Freezing operations during an investigation
- Decommissioning an organizational unit


## Domain injection

Ripple Custody supports **domain injection** — inserting a new domain between an existing parent and its children. This allows you to:

- Add a new governance layer without restructuring
- Apply new policies to a subset of existing subdomains
- Reorganize hierarchy as your business evolves


For implementation details, see [Domain injection](/products/custody/v1.34/api/environment/domain).

## Next steps

- [Governance framework](/products/custody/v1.34/overview/governance): Return to the governance overview
- [Intents](/products/custody/v1.34/concepts/governance/intents): Learn about the intent lifecycle
- [Policies](/products/custody/v1.34/concepts/governance/policies): Understand how policies control actions
- [Domain management](/products/custody/v1.34/api/environment/domain): Learn how to manage domains