Roles Modifier
The Roles Modifier gives addresses limited power over a Safe. You define roles. Each role lists the exact calls that its members can make. The Roles Modifier checks every transaction onchain and reverts all other transactions.
Typical uses:
- A DAO lets a service provider manage part of the treasury, within strict rules.
- A team funds daily operations from a shared Safe, with per-token spending limits.
- A bot or an AI agent trades for a Safe, but only on approved venues. See Permission an AI agent.
- A protocol offers its users a safe, scoped integration for their Safes.
Organizations that use the Roles Modifier include Safe, ENS DAO, Balancer, Gnosis DAO, Gnosis Pay, and kpk.
The three components
| Component | What it does | Where |
|---|---|---|
| Contract | Stores roles and checks every call onchain. | Reference, Deployments |
| Zodiac App | Shows any Roles Modifier. Builds, compares, and applies permissions. | app.zodiac.eco |
| Constellation | Your roles as code: members and permissions in TypeScript, applied with push. This is the primary path. | Constellations, Quickstart |
How a role works
A role has a role key (a bytes32 identifier), members, and targets. For each
target, the role either allows all functions or lists allowed functions. A listed function
is either open for all parameters or limited by a condition tree. Conditions can also
consume allowances, which are quotas that refill on a schedule.
The lifecycle has three steps:
- Author the permissions, in your constellation or in the Zodiac App.
- Apply the permissions.
push(or the app) computes the configuration calls, and the owner of the Roles Modifier — normally the Safe — signs and executes them. - Execute. Members send transactions through the Roles Modifier. The contract checks each call and forwards it to the Safe.
Read next: The permission model.
Versions
| Version | State | Mastercopy |
|---|---|---|
| Roles v1 | Legacy. It still runs, but it gets no new features. Source: zodiac-modifier-roles-v1 . | — |
| Roles v2 | Current. This documentation describes v2. | 2.1.1 (0xF2964CE6161ce0e75964Fe7927cE114cb0B283D5) |
| Roles v3 | In development. No deployments exist yet. | — |
Mastercopy 2.1.0 (0x9646fDAD06d3e24444381f44362a3B0eB343D337) has a known
vulnerability. Deploy only 2.1.1. If you run 2.1.0, read
Security now.
The SDK has its own version numbers. The current SDK is zodiac-roles-sdk v4, and it
targets the v2 contracts. When a page says “v2”, it means the contract version.
A preview of Roles v3
Roles v3 is in development in the open, in the
contracts-v3 branch.
The planned features include:
- Slippage protection with a new
WithinRatiooperator. - Allowances denominated in a base asset, for example USD.
- Session keys, expiring roles, and members that can forfeit a role.
- A simpler permission API:
allowFunctionwith an optional condition replacesscopeFunction.
These plans can change. Roles v3 has no release date and no deployed contracts. Follow the pull request for progress.