v2 to v3 Migration Guide

This guide covers the key function changes when migrating from zodiac-roles-sdk v2 to v3.

Role Management Functions

Consolidated Planning Functions

In v3, the separate role management functions have been consolidated into unified planning functions:

v2:

import { applyMembers, applyTargets, applyAnnotations } from "zodiac-roles-sdk";
 
// Separate operations for different aspects
await applyMembers(members, options);
await applyTargets(targets, options);
await applyAnnotations(annotations, options);

v3:

import { planApplyRole, planExtendRole } from "zodiac-roles-sdk";
 
// Unified role operations
await planApplyRole(fragment, options); // fragment can include members, targets, annotations
await planExtendRole(fragment, options); // fragment can include members, targets, annotations

In v2 the mode option was used to specify how the update should be applied. v3 offer two dedicated functions instead:

• planApplyRole: Updates a role to match the exact configuration provided (replaces existing permissions)
• planExtendRole: Extends an existing role with new permissions without removing existing ones

See the Role Planning & Management section for complete details.

Setup Functions

Role Setup

v2:

import { setUpRoles } from "zodiac-roles-sdk";
 
await setUpRoles(configuration, options);

v3:

import { planApply } from "zodiac-roles-sdk";
 
await planApply(configuration, options);

The planApply function handles complete Roles Modifier state updates including both roles and allowances.

See the Role Planning & Management section for details.

Function Renames

The following functions have been renamed for clarity and consistency:

• checkIntegrity → targetIntegrity
• encodeRoleKey → encodeKey
• decodeRoleKey → decodeKey

The functionality of these functions remains unchanged.

Summary