v3 to v4 Migration Guide

v4 narrows the scope of zodiac-roles-sdk to authoring permissions. Reading on-chain state and applying configuration updates now live in the Zodiac SDK , which talks to the Zodiac API.

What changed

Removed exports

Removed	Replacement
`planApply`	`push()` from `@zodiac-os/sdk`
`planApplyRole`	`push()` from `@zodiac-os/sdk`
`planExtendRole`	`push()` from `@zodiac-os/sdk`
`callsPlannedForApply`, `callsPlannedForApplyRole`	— (the API plans calls server-side)
`encodeCalls`, `Call`	— (no longer needed at the SDK boundary)
`fetchRole`, `fetchRolesMod`, `fetchRolesModConfig`	— (state is read through the Zodiac API)

`zodiac-roles-deployments` is sunset

All type definitions (ChainId, Role, Target, Condition, Operator enum, etc.) and the chains map have moved into zodiac-roles-sdk. The zodiac-roles-deployments package is no longer published.


- import { Role, Operator, chains } from "zodiac-roles-deployments";
+ import { Role, Operator, chains } from "zodiac-roles-sdk";

`getCowQuote` no longer reads the subgraph

getCowQuote previously fetched avatar and owner from the subgraph. In v4 the caller passes them on the request:


  const quote = await getCowQuote({
    kind: "sell",
    sellToken,
    buyToken,
    sellAmountBeforeFee,
    chainId,
    rolesModifier,
    roleKey,
+   avatar,
+   owner,
  });

Migrating apply flows to the Zodiac SDK

Updates are declarative in v4: you describe the desired state of a Roles modifier (members, permissions, allowances) and call push(). The Zodiac API diffs against the current on-chain state, plans the calls, and applies them.

The Zodiac SDK requires a Zodiac org and a project-scoped API key. Run zodiac init in your project to authorize, then zodiac pull to generate typed account references. See the Zodiac SDK README for the full setup.

Replacing `planApplyRole`

v3:


import { planApplyRole } from "zodiac-roles-sdk";
import { allow } from "zodiac-roles-sdk/kit";
 
const calls = await planApplyRole(
  {
    key: encodeKey("manager"),
    members: ["0xB0b…"],
    targets: processPermissions([allow.mainnet.dai.transfer()]).targets,
  },
  { chainId: 1, address: "0xRolesMod…" },
);
 
// caller is responsible for executing `calls` on-chain

v4:


import { constellation, push } from "@zodiac-os/sdk";
import { allow } from "@zodiac-os/sdk/allow";
import { encodeKey } from "zodiac-roles-sdk";
 
const eth = constellation({
  workspace: "GG",
  label: "Production",
  chain: 1,
});
 
// Reference the existing Roles mod by its workspace label
const rolesMod = eth.roles["GG DAO Roles"]({
  roles: {
    manager: {
      members: ["0xB0b…"],
      permissions: [allow.mainnet.dai.transfer()],
    },
  },
});
 
await push({ rolesMod });

Mentioned roles are replaced (the equivalent of planApplyRole). Roles you omit are left untouched. Pass null for a role key to clear it.

Replacing `planApply`

v3:


import { planApply } from "zodiac-roles-sdk";
 
const calls = await planApply(
  { roles, allowances },
  { chainId: 1, address: "0xRolesMod…" },
);

v4:


import { constellation, push } from "@zodiac-os/sdk";
 
const eth = constellation({
  workspace: "Default",
  label: "Roles Setup",
  chain: 1,
});
 
const rolesMod = eth.roles["My Roles"]({
  address: "0xRolesMod…",
  roles,
  allowances,
});
 
await push({ rolesMod });

push() groups operations by constellation and submits them to the Zodiac API, which returns the planned and applied changes.

Summary

v3	v4
`planApply`, `planApplyRole`, `planExtendRole`	`push()` from `@zodiac-os/sdk`
`callsPlannedForApply*`, `encodeCalls`, `Call`	removed — the API plans server-side
`fetchRole`, `fetchRolesMod`, `fetchRolesModConfig`	removed — read through the Zodiac API
`import … from "zodiac-roles-deployments"`	`import … from "zodiac-roles-sdk"`
`getCowQuote({ … })` reads subgraph	`getCowQuote({ …, avatar, owner })` — caller supplies