A policy defines the approval rules for a specific type of action: who must approve, how many approvals are needed, and under what conditions.
- Policies match intents by type (e.g., transfers, user creation) and conditions (e.g., amount > $10,000).
- Workflows specify multi-step approval chains with role requirements and quorum counts.
- Scope controls where the policy applies in your domain hierarchy.
- Rank determines priority when multiple policies could match the same intent.
Policies are your primary control mechanism for custody operations—they are what distinguish institutional-grade custody from a simple wallet. Well-designed policies enable you to enforce spending limits, require multi-party approval for high-value transactions, and implement compliance controls (like geographic restrictions or time-based rules). This is a key differentiator for Ripple Custody: you can encode arbitrarily complex business rules that would require manual processes with other custodians.
For architects and operators: Start with restrictive policies and loosen as needed. Use conditions with JavaScript expressions for dynamic rules. Test policies thoroughly in non-production environments — a missing policy results in rejected intents, and overly broad policies can create security gaps.
A policy is a rule that specifies:
- What: Which intent types the policy governs
- When: Conditions that determine if the policy applies
- Who: Which roles must approve and how many approvals are needed
- Where: The scope of domains where the policy applies
When a user submits an intent, the system finds the matching policy and enforces its approval requirements.
Every policy consists of these elements:
| Component | Description | Example |
|---|---|---|
| Intent types | Operations this policy governs | ["v0_CreateTransferOrder"] |
| Condition | JavaScript expression filtering when policy applies | amount > 1000000 |
| Workflow | Approval steps with roles and quorum counts | 2 operators, then 1 CFO |
| Scope | Where the policy applies in the domain hierarchy | SelfAndDescendants |
| Rank | Priority when multiple policies match (0-999) | 500 |
When an intent is submitted, the system selects the applicable policy through the following steps:
The system identifies policies that could apply:
- Intent type matches (or policy applies to all types).
- Scope includes the target domain.
- Policy is not locked.
For each matching policy, the JavaScript condition is evaluated:
- Conditions have access to intent data and referenced entities.
- Only policies where the condition evaluates to
trueproceed. - Policies without conditions automatically pass.
If multiple policies remain, the highest-ranked policy is selected:
- Higher rank = higher priority (range: 0-999).
- If ranks are equal, the older policy wins.
- One policy selected: Intent follows that policy's workflow.
- No policy matches: Intent fails (no applicable governance rule).
The scope setting determines where a policy applies relative to its domain:
| Scope | Applies To |
|---|---|
Self | Only intents targeting this domain |
Descendants | Only intents targeting subdomains |
SelfAndDescendants | Both this domain and all subdomains |
Scope works together with the domain's governing strategy to determine which policies apply.
Policies use a quorum model for approvals, requiring multiple signatures for sensitive operations.
| Benefit | Description |
|---|---|
| No single point of failure | Compromising one user's credentials isn't enough |
| Distributed trust | Critical decisions require consensus |
| Regulatory compliance | Many regulations require multi-party approval |
| Operational safety | Reduces risk of mistakes or unauthorized actions |
A workflow step specifies:
- Role: Which role can provide approvals
- Quorum: How many approvals from that role are required
| Pattern | Description | Use Case |
|---|---|---|
| Single approver | 1 approval from 1 role | Low-risk operations |
| Dual control | 2 approvals from same role | Standard operations |
| Multi-role | Approvals from different roles | High-risk operations |
| Sequential | Approval steps in order | Escalation workflows |
In a domain hierarchy, multiple policies may apply to a single intent:
- Target domain policy: Policy in the domain where the intent executes
- Ancestor domain policies: Policies from parent domains with scope that includes descendants
The domain's governing strategy determines how these interact:
ConsiderDescendants: Both parent and child policies applyCoerceDescendants: Parent policies override child policies
For details, see Governing strategies.
A breakglass policy provides emergency override capability:
- Created in a parent domain (often root)
- Has
CoerceDescendantsgoverning strategy - Requires high quorum from senior roles
- Can override child domain policies in emergencies
Use cases:
- Court orders requiring account freezes
- Recovery from misconfigured policies
- Lost user keys preventing normal approval
For implementation, see Breakglass policies.
| Term | Definition |
|---|---|
| Policy | A rule that defines who can approve specific types of intents and how many approvals are required |
| Intent type | The category of action a policy governs (e.g., CreateTransfer, CreateUser, UpdatePolicy) |
| Condition | Optional criteria that must be met for a policy to apply (e.g., amount thresholds, asset types) |
| Workflow | The sequence of approval steps required by a policy, defining roles and quorum for each step |
| Quorum | The number of approvals required from a specific role to complete a workflow step |
| Scope | Defines where a policy applies: Self (this domain only), Descendants (subdomains only), or SelfAndDescendants (both) |
| Rank | A numeric priority (0-999) used to select between multiple matching policies; higher rank wins |
| Governing strategy | A domain setting that determines how parent policies interact with child policies: ConsiderDescendants (additive) or CoerceDescendants (override) |
| Breakglass policy | An emergency policy that bypasses normal approval workflows, typically requiring elevated authorization |
| Maker-checker | A control pattern where the user who creates an intent (maker) cannot be the sole approver (checker) |
| Dual control | A quorum pattern requiring two approvals from the same role |
| Multi-role approval | A workflow pattern requiring approvals from users with different roles |
- Governance framework: Return to the governance overview
- Domains: Learn about domain hierarchy and governing strategies
- Intents: Understand intent lifecycle
- Users and roles: Learn how users and roles work
- Policy design: Start implementing policies