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.
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.
Before reading this page, you should understand:
- Security model - The zero-trust model and trusted state concepts.
- Users and roles - How users receive operational authority.
- Data integrity and governance - 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.
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.
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. |
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.
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.
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".
The basic maker-checker flow is:
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 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.
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.
| 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. |
| 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. |
| Topic | Description |
|---|---|
| Governance overview | Entry point for the governance section. |
| Domains | Domain hierarchy, isolation, governing strategies, lifecycle, and injection. |
| Policies | Policy matching, workflows, scope, rank, and breakglass patterns. |
| Intents and approvals | Intent lifecycle, maker-checker approvals, targeting, expiry, and dry runs. |
| Design your genesis governance model | Launch planning for domains, first users, roles, and initial policies. |
| Manage governance | Day-to-day intent submission, review, approval, rejection, and state checks. |