[!IMPORTANT]
This repository hosts Roles v3, which is not yet released for production. The contracts, the zodiac-roles-sdk in packages/sdk and the docs here may change in breaking ways.
Roles v2, the version in production today, and its tooling (including the zodiac-roles-sdk 4.x releases on npm) live at zodiaceco/zodiac-modifier-roles-v2.
Zodiac Roles Modifier v3
The Roles Modifier belongs to the Zodiac collection of tools, which can be accessed through the Zodiac App available on Safe.
If you have any questions about Zodiac, join the Gnosis Guild Discord. Follow @GnosisGuild on Twitter for updates.
About the Roles Modifier
This modifier allows avatars to enforce granular, role-based, permissions for attached modules.
Modules that have been granted a role are able to unilaterally make calls to any approved addresses, approved functions, and using approved parameters.
The interface mirrors the relevant parts of the Safe's interface, so this contract can be placed between Safe modules and the Safe itself to enforce role-based permissions.
The contracts have been developed with Solidity 0.8.37 targeting evm version cancun.
Features
- Create multiple roles
- Assign roles to addresses
- Allow roles access to call, delegate call, and/or send to address
- Scope which functions a role can call on given address
- Define conditions on function parameters
Flow
- Define a role by setting targets, functions, and parameters that it can call
- Assign the role to an address with
assignRoles()
- Address can now trigger the safe to call those targets, functions, and parameters via
execTransactionWithRole()
Deployments
Roles v3 is not yet deployed for production. The first release targets Ethereum, Optimism, Gnosis, Arbitrum, Base and Sepolia; Zodiac deploys it to further chains.
The production Roles v2 contracts, their addresses and the chains they are deployed on are listed at zodiaceco/zodiac-modifier-roles-v2.
Development environment setup
- For each package where a
.env.sample file is present (packages/evm), copy it to a .env file at the same location and fill in your keys.
- From the repo root run
yarn
- From the repo root run
yarn build
After that, you can start working on the different packages.
Packages
This monorepo uses yarn workspaces and is comprised of:
- evm: the Roles v3 smart contracts, with tests and the formal verification (
packages/evm/formal)
- sdk: a TypeScript SDK for managing roles,
zodiac-roles-sdk (the v3 version is unreleased; the published 4.x releases come from zodiac-modifier-roles-v2)
- app: a webapp for viewing roles, https://roles.gnosisguild.org (uses the published
zodiac-roles-sdk 4.x)
- docs: the documentation page, https://docs.roles.gnosisguild.org
- integration-tests: tests of the contracts together with the SDK, currently for message signing (
personal_sign, EIP-712)
Audits
Roles v3 has been audited by Côme du Crest (October 2026): report.
Security and Liability
All contracts are WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
License
This repository is dual-licensed as follows:
Contracts and App
All smart contracts and the web app in this repository are licensed under the Business Source License 1.1 (BUSL-1.1).
- Production use is restricted until March 1, 2030.
- On that date, these components will automatically convert to LGPL-3.0-or-later.
See LICENSE.md for full terms.
SDK and Developer Tooling
The SDK included in this repository is licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later) and is available under open-source terms immediately.
These components are not subject to the BUSL restrictions.
The SDK package includes its own LICENSE file.
Summary
| Component Type | License Now | License After 2030-03-01 |
|---|
| Contracts | BUSL-1.1 | LGPL-3.0-or-later |
| App | BUSL-1.1 | LGPL-3.0-or-later |
| SDK | LGPL-3.0-or-later | LGPL-3.0-or-later |
