Getting started

This guide walks you through the basic steps of using the Roles SDK.

Installation

The Roles SDK relies on eth-sdk (opens in a new tab) for generating type-safe APIs from automatically downloaded contract ABIs. To add it to your project, run one of the following commands.

With npm:

npm i --save @dethcrypto/eth-sdk @dethcrypto/eth-sdk-client zodiac-roles-sdk

With yarn:

yarn add @dethcrypto/eth-sdk @dethcrypto/eth-sdk-client zodiac-roles-sdk

With pnpm:

pnpm add @dethcrypto/eth-sdk @dethcrypto/eth-sdk-client zodiac-roles-sdk

Configuration

The next step is to create a config file that lists all the contracts we want to permit calling.

Create a folder named eth-sdk in your project root (where your package.json is located). Inside this folder, create a config.ts file with the following content structure:

import { defineConfig } from "@dethcrypto/eth-sdk";
 
export default defineConfig({
  contracts: {
    mainnet: {
      dai: "0x6b175474e89094c44da98b954eedeac495271d0f",
    },
  },
});

This example lists the DAI contract (opens in a new tab) on Ethereum mainnet. The object under the contracts field should generally 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 leave values.

For custom chain configurations: refer to the eth-sdk docs (opens in a new tab) for a complete overview of the available configuration options.

Generate allow kit

Now, and after any update to the eth-sdk/config.ts file, make sure to run the following command:

yarn eth-sdk

This command will fetch the ABIs of the contracts listed in the config file and generate TypeScript types for them directly into your node_modules. If the ABI of any listed contract cannot be fetched automatically, the command will return an error code. In that case, you need to manually create a JSON file with the ABI at a location inside eth-sdk/abi matching the path of the contract in the eth-sdk/config.ts file.

Define permissions

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

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

Apply permissions

Additional SDK functions allow applying a set of permissions to a role:

import { applyPermissions } from "zodiac-roles-sdk";
 
const calls = applyPermissions(MY_ROLE_KEY, permissions, {
  network: 1,
  address: ROLES_MOD_ADDRESS,
});

This will fetch the current permissions configured for the role identified by MY_ROLE_KEY and compute the set of calls required to patch it to the new set of permissions. You can execute the calls via ethers or batch them as a multi-send.

ethers:

calls.forEach(async (data) => {
  await provider.call({ to: ROLES_MOD_ADDRESS, data }); // signer must be the `owner` of the roles mod
});

multi-send:

import { encodeMulti } from "ethers-multisend";
 
const multiSendTx = encodeMulti(
  calls.map((data) => ({ to: ROLES_MOD_ADDRESS, value: 0, data }))
);