Skip to Content
SDKAPI Reference

API Reference

Complete reference for the Zodiac Roles SDK functions and types.

zodiac-roles-sdk

The main entrypoint for core role management functionality.

Role Planning & Management

planExtendRole(fragment, options)

Extends an existing role with new permissions without removing existing ones.

Parameters:

  • fragment - RoleFragment with permissions to add
  • options.chainId - Network chain ID
  • options.address - Roles Modifier contract address
  • options.current - Optional current Role state
  • options.log - Optional logging function or true to log with console.log

Returns: Promise<TransactionRequest[]>

planApplyRole(fragment, options)

Updates a role to match the exact configuration provided.

Parameters: Same as planExtendRole

Returns: Promise<TransactionRequest[]>

planApply(next, options)

Plans transactions to update complete rolesMod state (roles + allowances).

Parameters:

  • next.roles - Array of Role configurations
  • next.allowances - Array of Allowance configurations
  • options - Same as planExtendRole

Returns: Promise<TransactionRequest[]>

Permission Processing

processPermissions(permissions)

Converts an array of permissions into targets for role configuration.

Parameters:

Returns: { targets: Target[] }

reconstructPermissions(targets)

Converts targets back into permission objects (inverse of processPermissions).

Parameters:

  • targets - Array of Target objects

Returns: Permission[]

Condition Authoring

c

Condition helper functions for defining permission constraints. See Conditions for more details.

forAll(addresses, permission)

Creates permissions for multiple target addresses.

Parameters:

  • addresses - Array of target contract addresses
  • permission - Permission template to apply

Returns: Permission[]

Utilities

encodeKey(roleKey)

Converts string role key to hex-encoded bytes32.

Parameters:

  • roleKey - Human-readable role identifier

Returns: 0x${string}

decodeKey(encodedKey)

Converts hex-encoded bytes32 back to string.

Parameters:

  • encodedKey - Hex-encoded role key

Returns: string

postRole(config)

Posts role configuration to backend service.

Parameters:

  • config - Role posting configuration

Returns: Promise<void>

Validation

targetIntegrity(target)

Validates and optimizes target configuration integrity.

Parameters:

  • target - Target configuration to validate

Returns: Target

validatePresets(permissions, presets)

Validates permissions against preset configurations.

Parameters:

  • permissions - Array of Permission objects
  • presets - Preset validation rules

Returns: Validation results

zodiac-roles-sdk/kit

Type-safe permission builders generated from contract ABIs.

Permission Builders

allow

Type-safe permission builder from eth-sdk generated contracts.

Usage:

import { allow } from "zodiac-roles-sdk/kit";
 
// Access by network and contract name
allow.mainnet.dai.approve(spender);
allow.gnosis.gno.transfer(recipient, amount);

Structure:

  • allow[network][contract][function](...conditions, options)
  • Contracts: Defined in your eth-sdk/config.ts
  • Conditions: Each function parameters can be scoped using a condition expression in the respective position
  • Options: Define execution options (delegate call, send value) or Ether allowances

EVERYTHING

Wildcard permission that allows all operations.

Usage:

import { EVERYTHING } from "zodiac-roles-sdk/kit";
 
// Allow all functions on a target
allow.mainnet.dai[EVERYTHING]();

zodiac-roles-sdk/swaps

CowSwap integration for MEV-protected trading through roles.

Permission Generation

allowCowOrderSigning(config)

Generates permissions for COW Protocol order signing.

Parameters:

  • config.sell - Array of sellable token addresses
  • config.buy - Array of buyable token addresses
  • config.receiver - Optional custom receiver address

Returns: Permission[]

Order Placement

getCowQuote(request, options?)

Gets a quote for a COW Protocol swap.

Parameters:

Returns: Promise<Quote>

signCowOrder(quote)

Generates transaction to sign a COW Protocol order.

Parameters:

  • quote - Quote object from getCowQuote

Returns: TransactionRequest

postCowOrder(quote)

Posts a signed order to COW Protocol orderbook.

Parameters:

  • quote - Signed Quote object

Returns: Promise<string> (order ID)

zodiac-roles-sdk/annotations

Annotation processing for enhanced role documentation.

Annotation Processing

processAnnotations(annotations)

Processes annotation configurations into structured format.

Parameters:

  • annotations - Array of annotation objects

Returns: Processed annotation data

Preset (type)

Type definition for preset annotation configurations.

Core Types

Role

Complete role configuration including members, targets, and metadata.

interface Role {
  key: `0x${string}`; // Unique role identifier
  members: `0x${string}`[]; // Array of member addresses
  targets: Target[]; // Array of target permissions
  annotations: Annotation[]; // Array of role annotations
  lastUpdate: number; // Timestamp of last update
}

RoleFragment

Partial role configuration for updates (all fields optional except key).

interface RoleFragment {
  key: `0x${string}`;
  members?: `0x${string}`[];
  targets?: Target[];
  annotations?: Annotation[];
}

Target

Permission configuration for a target contract.

interface Target {
  address: `0x${string}`; // Target contract address
  clearance: Clearance; // Permission level
  executionOptions?: ExecutionOptions; // Execution constraints
  functions?: Function[]; // Function-specific permissions
}

Permission

High-level permission definition for function calls.

interface Permission {
  targetAddress: `0x${string}`; // Target contract address
  signature?: string; // Function signature (optional)
  condition?: Condition; // Parameter constraints
  executionOptions?: ExecutionOptions; // Execution options
}

Allowance

Spending limit configuration for roles.

interface Allowance {
  refill: bigint; // Amount refilled per period
  maxRefill: bigint; // Maximum accruable amount
  period: number; // Refill period in seconds
  balance: bigint; // Current available balance
  timestamp: number; // Last refill timestamp
}
Last updated on
Swapsv2 to v3 Migration