Users are individuals (or machines) who interact with the custody platform. Roles define what actions each user can perform.
- Every user has a cryptographic key pair for authentication and signing.
- Roles determine maker capabilities (propose changes) and checker capabilities (approve changes).
- Genesis users are defined at platform initialization and cannot be deleted.
- Segregation of duties is enforced. No user can both propose and fully approve their own change.
Your user and role design is the foundation of operational security. Properly configured roles prevent unauthorized transactions, enforce multi-party approval for high-risk operations, and create a clear audit trail of who did what. Poorly designed roles can create single points of failure (one person can move funds) or operational bottlenecks (too many approvals required).
For architects and operators: Define your role hierarchy during genesis planning. Consider how many approval tiers you need, what spending limits each role should have, and how you'll handle role changes after go-live (role changes require governance approval).
A user in Ripple Custody represents an individual who can:
- Create intents: Propose changes to the system
- Approve intents: Provide approvals for pending changes
- Reject intents: Block changes they disagree with
Each user has:
- A unique identifier
- One or more assigned roles
- A cryptographic key pair for signing
- Assignment to a specific domain
A role defines a set of capabilities that can be assigned to users. Roles determine:
| Capability | Description |
|---|---|
| Maker capabilities | Which intent types the user can create |
| Checker capabilities | Which intent types the user can approve |
| Domain scope | Which domains the user can operate in |
| Role | Typical Capabilities |
|---|---|
| Operator | Create and approve transfers, manage accounts |
| Supervisor | Approve high-value transfers, manage operators |
| Compliance | Approve regulatory-sensitive operations |
| Admin | Manage users, policies, and domains |
| Auditor | Read-only access for compliance review |
Roles are customizable — you define roles that match your organization's structure.
Genesis users are special users defined in the genesis block when the platform is first initialized. (For more information about the genesis block, see The Genesis block.)
| Characteristic | Description |
|---|---|
| Created at initialization | Defined in the genesis block before the platform starts |
| Bootstrap the system | Enable initial setup before normal governance applies |
| Cannot be deleted | Remain in the system permanently (can be locked) |
| Highest trust level | Represent the initial root of trust |
| Aspect | Genesis Users | Regular Users |
|---|---|---|
| Creation | In genesis block | Via v0_CreateUser intent |
| Governance | Pre-governance | Subject to policies |
| Deletion | Cannot be deleted | Can be deleted via intent |
| Purpose | Bootstrap system | Normal operations |
Genesis users should be carefully selected and their credentials securely managed. They represent the foundation of your system's trust model.
Ripple Custody enforces segregation of duties through the maker-checker model:
No single user should be able to both propose and fully approve a change. This prevents:
- Unauthorized actions by compromised accounts
- Mistakes from going unchecked
- Fraud by malicious insiders
| Rule | Description |
|---|---|
| Maker ≠Checker | The user who creates an intent cannot be the sole approver |
| Role separation | Different roles for different responsibilities |
| Quorum requirements | Multiple approvals required for sensitive operations |
| Domain boundaries | Users can only operate within their assigned domain |
Users progress through several states:
| State | Description |
|---|---|
| Active | User can create and approve intents |
| Locked | User cannot perform any actions (temporary suspension) |
| Deleted | User is removed from the system (regular users only) |
Locking is useful for:
- Temporary suspension during investigations
- Employee leave or role transitions
- Security incidents
Locked users cannot create or approve intents until unlocked.
Users can have multiple roles, and roles can be assigned to multiple users:
This flexibility allows you to model complex organizational structures.