https://github.com/gnosisguild/permissions-starter-kit
Out of the box starting point for managing Zodiac Roles permissions
https://github.com/gnosisguild/permissions-starter-kit
blockchain evm permissions zodiac
Last synced: 8 months ago
JSON representation
Out of the box starting point for managing Zodiac Roles permissions
- Host: GitHub
- URL: https://github.com/gnosisguild/permissions-starter-kit
- Owner: gnosisguild
- License: mit
- Created: 2024-04-17T10:56:48.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-10T17:14:20.000Z (over 1 year ago)
- Last Synced: 2025-01-10T18:25:56.607Z (over 1 year ago)
- Topics: blockchain, evm, permissions, zodiac
- Language: TypeScript
- Homepage: https://roles.gnosisguild.org
- Size: 445 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# permissions-starter-kit
Out of the box starting point for managing [Zodiac Roles](https://roles.gnosisguild.org) permissions
Keep the configuration of your Zodiac Roles Modifier as declarative statements in code.
The provided tooling automatically applies updates in a consistent and efficient way.
Learn more about the motivation behind this approach in our blog ["Permissions as Code"](https://engineering.gnosisguild.org/posts/permissions-as-code).
## Getting Started
[Use this template](https://github.com/new?template_name=permissions-starter-kit&template_owner=gnosisguild) to create a repository for your roles configuration.
### Initial Setup
After creating your own repository, clone it to work locally and open the project in a code editor such as [VSCode](https://code.visualstudio.com).
To initialize the project, open a terminal window and run the following command in the project root directory:
`yarn` _(If you encounter a 'command not found' error, ensure that you have [installed Yarn](https://classic.yarnpkg.com/lang/en/docs/install/) and try again.)_
### Creating a New Role
Roles are defined as folders in the [roles/](./roles) directory.
Folder names correspond to [role keys](#role-keys).
The template includes two example roles: `eth_wrapping` and `position_management`.
You can either rename these folders or create new ones for your role.
Inside the role folder, create or edit the _permissions.ts_ file with the following boilerplate content:
```typescript
export default [
// <- define your permissions here
] satisfies Permissions;
```
Also create or edit the _members.ts_ file, keeping the list of role member addresses:
```typescript
export default [
// <- list all role member addresses here
] satisfies `0x${string}`[];
```
### Configuring Allowed Target Contracts
As a preparatory step before actually defining the role permissions, configure the addresses of all contracts you want to allow calling to.
Then, you can run a command that fetches the ABIs of these contracts.
This will provide automatic suggestions and correctness checks while authoring permissions.
Open [contracts.ts](./contracts.ts) in the editor and add labels and addresses of any contracts you plan to use as targets in your permissions.
At the top level of the exported object, define the host blockchain.
The following values are supported:
`mainnet`, `gnosis`, `polygon`, `arbitrumOne`, `avalanche`, `base`, `bsc`, `sepolia`
Then, insert all target contract addresses as records using recognizable labels:
```typescript
import type { Contracts } from "./.lib/types";
export default {
mainnet: {
// : "",
weth: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
// Optionally, group contracts in labeled categories:
uniswap: {
positions_nft: "0xC36442b4a4522E871399CD717aBDD847Ab11FE88",
},
},
} satisfies Contracts;
```
The following values are supported:
1. Save your changes in the contracts.ts file and run the following command in the terminal window:
`yarn setup`
2. Open the VSCode command palette:
Mac: `Cmd` + `Shift` + `P`
Windows: `Ctrl` + `Shift` + `P`
3. Type `restart` and select the option `TypeScript: Restart TS server` from the suggestions list
### Edit Permissions
In the _permissions.ts_ file for your role, type `allow.`.
You will see suggestions appearing next to your cursor.
Select the path to the target contract as previously defined in [contracts.ts](./contracts.ts).
If the suggestions you see in the editor do not match the structure of your [contracts.ts](./contracts.ts) records, ensure you have followed the [three steps described above](#sdk-setup-steps).
#### Set Conditions on Parameters
To limit allowed values for individual function parameters, you can use the Roles Modifier's conditions system.
Condition functions are available under the global `c` variable.
Read more about conditions in the [documentation](https://docs.roles.gnosisguild.org/sdk/conditions).
### Edit Members
In the _members.ts_ file for your role, specify the list of addresses you want to assign the role to.
### Apply Updates
Once you have defined all members and permissions for the role, you can apply the update to your Roles mod.
If you need to set up a new Roles mod from scratch, refer to [this tutorial](https://www.zodiac.wiki/documentation/roles-modifier/roles-modifier-operator-tutorial).
In your terminal, run the following command:
```
yarn apply
```
For example, to apply the role `eth_wrapping` to a mainnet Roles mod at address `0x1234123412341234123412341234123412341234`:
```
yarn apply eth_wrapping eth:0x1234123412341234123412341234123412341234
```
This will direct you to the Roles app, where you can review the updates that will be made to your role and confirm them by signing the apply transaction.
Applying permissions for the first time will create a new role.
Subsequent applications will update the existing role, efficiently removing, updating, and adding permissions so that the role configuration on chain accurately reflects the permissions defined in code.
### Use New Role 🚀
Once applied, start using your role through [Zodiac Pilot](https://pilot.gnosisguild.org), our browser extension for streamlined Safe execution with support for roles and more complex account setups.
## Folder Structure and Conventions
- [contracts.ts](./contracts.ts) – Lists all contracts that are used as targets in permissions
- [roles/](./roles) – Host directory for role configurations
- [`role_key`/](./roles/eth_wrapping) – Each subfolder represents a distinct role. The folder name will be used as the [role key](#role-keys).
- [members.ts](./roles/eth_wrapping/members.ts) – Assigns the role to the listed member addresses
- [permissions.ts](./roles/eth_wrapping/permissions.ts) – Defines all permissions for this role
There are some additional files and folders in the template repository, which you won't usually need to edit.
They contain the necessary wiring for automatically applying the permissions.
##### Role Keys
In the Zodiac Roles Modifier, every role is identified by a `bytes32` string.
Choose a role key that accurately describes the purpose of the role.
We recommend using only the following characters for role keys: `a...z`, `0...9`, `_`
The length must be less than 32 characters.
##### Prefixed Addresses
The Roles tooling adopts [EIP-3770](https://eips.ethereum.org/EIPS/eip-3770) chain-specific addresses for identifying a contract on a specific chain in a compact way:
```
eth:0x1234123412341234123412341234123412341234
```
Chain prefixes for the supported chains are as follows:
- Mainnet: `eth`
- Gnosis Chain: `gno`
- Optimism: `oeth`
- Polygon: `matic`
- Polygon zkEVM: `zkevm`
- Arbitrum One: `arb1`
- Avalanche: `avax`
- Base: `base`
- BSC: `bnb`
- Base Sepolia: `basesep`
- Sepolia Testnet: `sep`