# Governance model

Executive summary
**Ripple Custody governance controls who can change the environment, which approvals are required, and where those controls apply.**

- **Domains** define the organizational boundaries for users, accounts, policies, endpoints, requests, and events.
- **Policies** define approval rules for governed actions, including who must approve, how many approvals are needed, and where the rule applies.
- **Intents** are governed proposals to change system state. They execute only when the selected policy workflow is satisfied.
- **Genesis** creates the first governed state: the root domain, launch domains, first users, roles, and initial policies.
- **Approvals** make governance enforceable and auditable by recording who proposed, approved, rejected, or executed a change.


Why this matters
Governance is the operating control layer for custody. It is how you separate clients or business units, enforce multi-party approval, route high-risk activity to compliance or senior reviewers, and govern changes to the governance model itself.

**For architects and operators**: Domain, user, and policy design should be treated as launch architecture. A weak model can create unexpected access paths or approval gaps. An over-complicated model can make legitimate operations hard to approve, audit, or recover.

Prerequisites
Before reading this page, you should understand:

- [Security model](/products/custody/v1.36/overview/security-model) - The zero-trust model and trusted state concepts.
- [Users and roles](/products/custody/v1.36/governance/users) - How users receive operational authority.
- [Data integrity and governance](/products/custody/v1.36/overview/security/data-integrity-and-audit-trail) - How trusted entities and state changes are signed and audited.


Governance connects organizational authority to cryptographic enforcement. A user proposes a signed intent in a target domain, or an API service caller submits a system-signed proposal that is signed by the platform before policy evaluation. The system selects the policy that applies to that intent and domain. The policy workflow determines who must approve. After the workflow is satisfied, the change can execute and becomes part of the auditable system state.


```mermaid
flowchart LR
    Genesis["Genesis<br/>first governed state"]
    Domains["Domains<br/>operating boundaries"]
    Users["Users and roles<br/>authority"]
    Policies["Policies<br/>approval rules"]
    Intents["Intents<br/>proposed changes"]
    Approvals["Approvals<br/>maker-checker workflow"]
    State["Executed change<br/>auditable state"]

    Genesis --> Domains
    Genesis --> Users
    Genesis --> Policies
    Users --> Intents
    Domains --> Intents
    Policies --> Approvals
    Intents --> Approvals
    Approvals --> State
```

## Domains define where governance applies

A domain is an organizational boundary. It groups domain-owned records such as users, accounts, vaults, policies, endpoints, requests, and events under one governance structure.

Every environment has a root domain. Subdomains form a tree below it. Users can target their own domain and, where governance permits, descendant domains. Users cannot submit intents to parent or sibling domains directly.


```mermaid
flowchart TB
    Root["Root domain<br/>platform governance"]
    Operations["Operations domain<br/>shared controls"]
    Compliance["Compliance domain<br/>oversight"]
    ClientA["Client A domain<br/>isolated operations"]
    ClientB["Client B domain<br/>isolated operations"]

    Root --> Operations
    Root --> Compliance
    Operations --> ClientA
    Operations --> ClientB
```

Domain design controls:

| Design area | What it controls |
|  --- | --- |
| Hierarchy | How client, regional, treasury, compliance, or business-unit boundaries are represented. |
| Read access | Which roles can view domains, users, accounts, transactions, policies, endpoints, requests, and events. |
| Policy inheritance | Whether policies in parent domains can affect intents in child domains. |
| Lock state | Whether activity is enabled. A locked domain prevents users from submitting intents in that domain or its subdomains. |
| Domain injection | Whether a new parent domain can be inserted above existing child domains after launch. |


Parent and child policies interact through policy scope and the domain governing strategy:

| Strategy | Behavior |
|  --- | --- |
| `ConsiderDescendants` | Parent and child policies can both be considered. The highest-ranked eligible policy wins. |
| `CoerceDescendants` | Matching parent-domain policies override matching child-domain policies. Use this only when the override is intentional. |


## Policies define how changes are approved

A policy defines the approval rule for a governed action. It answers five questions:

| Question | Policy field | Example |
|  --- | --- | --- |
| What action? | `intentTypes` | `v0_CreateTransactionOrder`, `v0_CreatePolicy`, or `v0_CreateDomain`. |
| Which origin? | `intentOrigin` | User-signed proposals or API-only system-signed proposals. |
| When? | `condition` | Amount threshold, endpoint trust score, author role, target role, or another payload condition. |
| Who approves? | `workflow` | Two operators, then one compliance reviewer. |
| Where? | `scope` | `Self`, `Descendants`, or `SelfAndDescendants`. |
| Which policy wins? | `rank` | Higher rank wins among matching policies. |


When an intent is submitted, the notary evaluates the applicable policies and applies the selected workflow.


```mermaid
flowchart LR
    Intent["Intent"] --> Scope["Scope and<br/>governing strategy"]
    Scope --> Type["Intent type<br/>matches"]
    Type --> Condition["Condition<br/>evaluates true"]
    Condition --> Rank["Highest rank<br/>selected"]
    Rank --> Workflow["Workflow<br/>enforced"]
    Workflow --> Result["Approve, reject,<br/>expire, or execute"]
```

If no policy matches, the intent cannot execute. If a matching policy omits `workflow` or sets it to `null`, the intent is auto-approved. If `workflow` is an empty array, matching intents are rejected. Use those behaviors deliberately.

Policy workflows can require:

| Workflow object | Use when |
|  --- | --- |
| `RoleQuorum` | A number of users with one role must approve. |
| `And` | Multiple approval groups must approve in the same step. |
| `Or` | Any one of several approval groups can satisfy the step. |
| Sequential array | Approval must happen in ordered stages. |


Policy-management policies should be stricter than routine operational policies because they control how governance can change in the future.

## Intents turn proposals into governed changes

An intent is a governed proposal to change the system. Domain changes, policy changes, user changes, endpoint changes, transactions, and compliance operations all use the intent model.

User-signed intents contain the user author, target domain, expiry time, operation-specific payload, and custom metadata. After submission, the intent is immutable. The maker's signature counts as the first approval, and the maker must have a role that satisfies the first workflow step. The maker cannot provide another approval for the same workflow.

System-signed intents are API-only proposals from service callers. They omit the user `author` and client-side `signature` fields, are signed by the platform internally, and match only policies with `intentOrigin: "SystemSigned"`.


```mermaid
stateDiagram-v2
    [*] --> Proposed: Submit intent
    Proposed --> PendingApproval: Policy workflow applies
    PendingApproval --> Approved: Required approvals received
    PendingApproval --> Rejected: Approver rejects
    PendingApproval --> Expired: Expiry time passes
    Approved --> Executed: System applies change
    Executed --> [*]
    Rejected --> [*]
    Expired --> [*]
```

The basic maker-checker flow is:


```mermaid
sequenceDiagram
    participant Maker
    participant Platform
    participant Notary as Notary / policy evaluation
    participant Checkers
    participant State as System state

    Maker->>Platform: Submit intent
    Platform->>Notary: Select policy for target domain
    Notary-->>Platform: Return workflow
    Checkers->>Platform: Approve or reject
    Platform->>State: Execute approved change
    State-->>Platform: Record auditable outcome
```

Use dry runs before submitting high-risk or complex intents, especially policy changes, domain changes, user and role changes, and payloads where condition or workflow behavior is uncertain.

## Genesis creates the first governed state

Genesis is the first governed state of the environment. It defines what must exist before normal governed changes can happen:

| Genesis element | Why it matters |
|  --- | --- |
| Root domain and launch domains | Establishes the domain tree and launch operating boundaries. |
| First users and roles | Provides enough human or machine users to satisfy launch approval workflows. |
| Initial policies | Controls root administration, user management, policy management, operations, compliance, fallback, and recovery. |
| Breakglass or recovery controls | Gives operators a governed path for exceptional scenarios such as urgent freezes, lost access, or misconfiguration recovery. |
| Deferred changes | Identifies non-critical domains, users, or policy refinements that can be created later through normal governance. |


Do not treat genesis as a payload-filling task. Treat it as the launch design for your operating model.


```mermaid
flowchart LR
    Domains["1. Design domains<br/>tree, strategy, read access"]
    Users["2. Plan first users<br/>roles and quorum coverage"]
    Policies["3. Design policies<br/>coverage, rank, workflows"]
    Checklist["4. Readiness checklist<br/>launch review"]
    GenesisState["Genesis state<br/>ready for setup"]

    Domains --> Users --> Policies --> Checklist --> GenesisState
```

Policies depend on domains and users. If the launch domain tree or first-user model changes, review the policy model again before setup.

Infrastructure configuration belongs outside the governance model. Governance state belongs in genesis.

## How the pieces work together

| Step | Governance behavior |
|  --- | --- |
| 1. Launch | Genesis establishes the root domain, launch subdomains, first users, roles, and initial policies. |
| 2. Propose | A user signs an intent that targets a domain and contains the requested operation. |
| 3. Select policy | The system evaluates scope, governing strategy, intent type, condition, and rank to select the applicable policy. |
| 4. Approve | The selected workflow determines which roles and quorum must approve. Any authorized rejection stops the workflow. |
| 5. Execute | After required approvals, the system applies the change and records the governance outcome. |
| 6. Evolve | Future domain, user, endpoint, policy, and operational changes continue through the same intent workflow. |


## Common design questions

| Question | Start with |
|  --- | --- |
| What needs to be isolated? | Domain hierarchy, read access, and governing strategy. |
| Who can propose and approve changes? | Users, roles, and quorum coverage. |
| Which actions need approval? | Policy intent types, conditions, workflows, scope, and rank. |
| How do high-risk or unusual cases get handled? | Breakglass, fallback, compliance, and recovery policies. |
| What must exist before the environment starts? | Genesis domain, user, role, and policy design. |


## Next steps

| Topic | Description |
|  --- | --- |
| [Governance overview](/products/custody/v1.36/governance) | Entry point for the governance section. |
| [Domains](/products/custody/v1.36/governance/domains) | Domain hierarchy, isolation, governing strategies, lifecycle, and injection. |
| [Policies](/products/custody/v1.36/governance/policies) | Policy matching, workflows, scope, rank, and breakglass patterns. |
| [Intents and approvals](/products/custody/v1.36/governance/intents) | Intent lifecycle, maker-checker approvals, targeting, expiry, and dry runs. |
| [Design your genesis governance model](/products/custody/v1.36/governance/genesis) | Launch planning for domains, first users, roles, and initial policies. |
| [Manage governance](/products/custody/v1.36/governance/intents/manage-intents-and-approvals) | Day-to-day intent submission, review, approval, rejection, and state checks. |