Getting started

This guide walks you through the basic steps of using the Roles SDK, showing how to define permissions and apply them to a role.

The Roles SDK is focused on authoring permissions. Reading on-chain state and pushing configuration updates is handled by the Zodiac SDK , which talks to the Zodiac API. The two SDKs are designed to be used together: you compose Permissions with the Roles SDK and ship them with the Zodiac SDK’s push().

For getting started quickly using a pre-configured default setup, check out the Zodiac Constellation Template . It provides a complete project template for managing your Roles Modifier instance using the Roles SDK and the Zodiac SDK together.

Installation

Install the Roles SDK alongside the Zodiac SDK:


npm i --save zodiac-roles-sdk @zodiac-os/sdk


yarn add zodiac-roles-sdk @zodiac-os/sdk


pnpm add zodiac-roles-sdk @zodiac-os/sdk

Authorize the Zodiac SDK

Run zodiac init from your project root. This opens a browser tab so you can sign in, pick the Zodiac org you want to use, and approve a project-scoped API key. The key is written to a .env file in your project root.


npx zodiac init

⚠️

Make sure .env is in your .gitignore — it contains your API key.

Configuration

Create a zodiac.config.ts in your project root listing the contracts you want to permit calling:


import { defineConfig } from "@zodiac-os/sdk/cli/config";
 
export default defineConfig({
  contracts: {
    mainnet: {
      dai: "0x6b175474e89094c44da98b954eedeac495271d0f",
    },
  },
});

This example lists the DAI contract on Ethereum mainnet. The object under the contracts field should list the identifiers of all chains you plan to target. For each chain entry, you can define arbitrary object structures with addresses stored at the leaf values.

Pull org and contract data

Run zodiac pull to fetch contract ABIs and your org’s accounts. The command generates typed references under .zodiac/ at your project root.


npx zodiac pull

Add .zodiac/ to your .gitignore. Re-run zodiac pull after any change to zodiac.config.ts or to refresh your org data. The VSCode TypeScript server may not pick up the new types automatically — press CMD+SHIFT+P and select “TypeScript: Restart TS Server” if needed.

Define permissions

You now have a typed allow kit at your disposal. Access it by importing from "@zodiac-os/sdk/allow":


import { allow } from "@zodiac-os/sdk/allow";
 
const CURVE_3POOL = "0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7";
 
const permissions = [allow.mainnet.dai.approve(CURVE_3POOL)];

Apply permissions

Describe the role using the constellation() factory and ship it with push():


import { constellation, push } from "@zodiac-os/sdk";
import { allow } from "@zodiac-os/sdk/allow";
 
const eth = constellation({
  workspace: "Production",
  label: "Roles Setup",
  chain: 1,
});
 
const CURVE_3POOL = "0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7";
 
// Reference an existing Roles mod from your workspace
const rolesMod = eth.roles["My Roles"]({
  roles: {
    manager: {
      members: ["0xAlice…"],
      permissions: [allow.mainnet.dai.approve(CURVE_3POOL)],
    },
  },
});
 
await push({ rolesMod });

push() sends the desired state to the Zodiac API, which diffs against the current on-chain configuration and applies the necessary calls. Mentioned roles are replaced; omitted roles are left untouched; pass null for a role key to clear it.

Using `eth-sdk` instead

The legacy eth-sdk workflow is still supported. If you already have an eth-sdk/config.ts and prefer to keep using yarn eth-sdk to generate ABIs, you can import the kit from "zodiac-roles-sdk/kit" and pass the resulting permissions to push() exactly the same way:


import { allow } from "zodiac-roles-sdk/kit";
 
const permissions = [allow.mainnet.dai.approve(CURVE_3POOL)];

See the eth-sdk docs for setup details. New projects should prefer the Zodiac SDK workflow above.