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 addoptions.chainId
- Network chain IDoptions.address
- Roles Modifier contract addressoptions.current
- Optional current Role stateoptions.log
- Optional logging function ortrue
to log withconsole.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 configurationsnext.allowances
- Array of Allowance configurationsoptions
- Same asplanExtendRole
Returns: Promise<TransactionRequest[]>
Permission Processing
processPermissions(permissions)
Converts an array of permissions into targets for role configuration.
Parameters:
permissions
- Array of Permission objects
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 addressespermission
- 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 objectspresets
- 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 addressesconfig.buy
- Array of buyable token addressesconfig.receiver
- Optional custom receiver address
Returns: Permission[]
Order Placement
getCowQuote(request, options?)
Gets a quote for a COW Protocol swap.
Parameters:
request
- QuoteRequest configurationoptions
- Optional AdvancedOptions
Returns: Promise<Quote>
signCowOrder(quote)
Generates transaction to sign a COW Protocol order.
Parameters:
quote
- Quote object fromgetCowQuote
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
}