Getting started

This quick 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. For adding 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 npm:

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 first step is to create a config file listing all contracts that we want to allow calling to. 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 the entry for each chain you can define arbitrary object structures with addresses stored at the leave values.

Custom chain configuration

TODO

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 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 this 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 full 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 permissions currently 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:

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

Or batch them as a multi-send:

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