Reference
What it does
The roles module implements protocol-wide RBAC: named roles with defined capabilities, assignable to accounts, checked by other modules before privileged operations execute. Auditor rights, administrative operations, and specialized marketplace capabilities all resolve through role checks.
Centralizing authorization means access decisions are consistent, queryable, and governable — a role grant is a transaction, not a configuration file on someone's server.
Why it exists: Two dozen modules each inventing its own permission model would be unauditable. One RBAC module gives the protocol a single, inspectable answer to "who may do what" — and one governance surface to change it.
State
Primary objects
| Concept | Definition |
|---|---|
Role | A named bundle of capabilities assignable to accounts and checked by modules. |
Capability check | The authorization gate a module runs before executing a privileged message. |
Messages
Messages & queries
Message and query surfaces are documented at implementation level in the module docs ↗ and the source ↗. The objects above are the state those messages create and transition.
Connections
Module interactions
-
x/auditAuditor status is a role that authorizes signing provider attributes. -
x/configConfiguration changes require appropriately-roled accounts. -
x/mfaPrivileged roles can be required to carry stronger authentication. -
x/veidregistryRole grants can be conditioned on verified identity.
Flows
Core flow
- Define — Capabilities bundle into roles. Auditor rights, administrative operations, marketplace capabilities — named, bounded, documented.
- Grant — Accounts receive roles. Grants are transactions: public, queryable, and optionally conditioned on verified identity.
- Check — Modules gate on roles. Privileged messages run capability checks before executing — no check, no execution.
- Harden — Identity and factors attach. Sensitive grants can require VEID-verified identity or stronger MFA authentication.
Questions
Asked about x/roles
Why not let each module manage permissions?
Two dozen bespoke permission models would be unauditable. One RBAC module keeps authorization consistent, queryable, and governable across the protocol.
What is a capability check?
The authorization gate a module runs before executing a privileged message — the runtime enforcement of the role model.
Is auditor status a role?
Yes. Auditor status authorizes signing provider attributes, with grants that can carry identity conditions and MFA requirements.
Related