Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

Roles and permissions

Read, grant and revoke ENSv2 roles, and check what an account may do with a name before it tries to change anything on it.

This page is about ENSv2 roles. On ENSv1 an owner, a manager and operators control a name, limited by Name Wrapper fuses. ENSv2 replaces that with roles: each account holds specific powers, such as changing the resolver, on a name or at the root of a registry or resolver. The permission reads below answer for both versions, so UIs need no branch.

You will check what an account may do, grant and revoke roles, and give an app access to some records.

Prerequisites

1. Check what an account may do

permission.get answers every operation at once. Use it to show or hide buttons.

Example (Gating a UI)

permission-get.ts
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
}).extend(ensActions());

const { can, fuses } = await ens.permission.get({
  name: "ensforge-docs-demo.eth",
  account: "0xB0b0000000000000000000000000000000000000",
});

if (can.setRecords) console.log("show the edit button");
  • can maps each operation to true, false or null. null means the permission model is unknown, as with a custom resolver.
  • fuses lists burned NameWrapper fuses on wrapped ENSv1 names.
  • Pass records for per-record answers, such as which text keys the account may write.
  • On ENSv2 the answer uses the account's roles on the name and at the root of its registry.

permission.check checks one operation and lists what is missing.

Example (Explaining a Disabled Button)

permission-check.ts
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
}).extend(ensActions());

const { allowed, via, missing } = await ens.permission.check({
  name: "ensforge-docs-demo.eth",
  account: "0xB0b0000000000000000000000000000000000000",
  operation: "setResolver",
});

via says how the account is allowed: owner, operator, approved, delegate, roles or anyone. missing lists the ownership, approvals or roles it lacks, or what blocks the change for everyone, such as a burned fuse.

2. Read an account's roles

role.get reads the roles directly. target is "registry" or "resolver".

Example (Reading Roles on a Name)

role-get.ts
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
}).extend(ensActions());

const { names, admin, rootRoles } = await ens.role.get({
  name: "ensforge-docs-demo.eth",
  account: "0xB0b0000000000000000000000000000000000000",
  target: "registry",
});
  • names lists the roles held, including root roles, which apply to every name.
  • admin lists the roles the account may grant and revoke.
  • rootRoles is the bitmap of the root roles alone.
  • root: true reads root roles alone. contract reads another registry or resolver than the name's.

3. Grant and revoke roles

role.grant and role.revoke take role names or a bitmap. Granting or revoking needs the matching admin roles.

Example (Granting and Revoking a Role)

role-grant.ts
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const transport = http(process.env.SEPOLIA_RPC_URL);

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport }),
  walletClient: createWalletClient({ account, chain: sepolia, transport }),
}).extend(ensActions());

const bob = "0xB0b0000000000000000000000000000000000000";

await ens.role.grantSync({
  name: "ensforge-docs-demo.eth",
  grantee: bob,
  roles: ["setResolver"],
  target: "registry",
});

await ens.role.revokeSync({
  name: "ensforge-docs-demo.eth",
  holder: bob,
  roles: ["setResolver"],
  target: "registry",
});
OptionDescription
grantee / holderThe account that gains or loses the roles.
rolesRole names such as ["setResolver"], or a bitmap.
target"registry" or "resolver". Resolver roles are root only.
nameThe name whose registry or resolver to use.
contractA registry or resolver address, instead of the name's.
rootRoot roles, which apply to every name, instead of the name's.

Each role has an admin role named <role>Admin. Role.admin("setResolver") returns "setResolverAdmin".

Some roles regenerate the name's token ID. The plan then carries a TOKEN_ID_REGENERATED warning, so read the token ID again afterwards.

Registry roles

registrar, registerReserved, setParent, unregister, renew, setSubregistry, setResolver, canTransfer, setUri, canName and upgrade, each with an Admin form. The .eth registrar grants a new owner the roles for the resolver, the subregistry and transfers.

Resolver roles

setAddr, setText, setContenthash, setAbi, setInterface, setName, setData, link, canName and upgrade, each with an Admin form.

Renewal needs no role on .eth

A .eth owner cannot grant renew (CANNOT_GRANT_ROLES). Anyone can renew a .eth name through the registrar. See Renew a name.

4. Let an app edit some records

permission.setRecordAccess gives an account access to the records you list, or to all of them. revoke: true takes it back.

Example (Letting an App Edit One Text Record)

set-record-access.ts
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const transport = http(process.env.SEPOLIA_RPC_URL);

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport }),
  walletClient: createWalletClient({ account, chain: sepolia, transport }),
}).extend(ensActions());

await ens.permission.setRecordAccessSync({
  name: "ensforge-docs-demo.eth",
  grantee: "0xB0b0000000000000000000000000000000000000",
  records: { texts: ["url"] },
});
  • On a PermissionedResolver it grants the exact setter roles for each record. With records: "all" it grants every setter role.
  • On a public resolver it sets a per-name delegate, which can edit every record of the name.
  • Delegates and "all" need allowScopeWidening: true.

Resolver roles cover every name on that resolver

Setter roles are per record kind, not per name. If names share a resolver (resolver: "parent"), the grantee edits the same records on all of them. By default each name has its own resolver. See Resolvers and shared records.

Troubleshooting

MISSING_ROLES

The account lacks a role. The error lists them. See MISSING_ROLES.

CANNOT_GRANT_ROLES

The signer lacks the admin role for what it tries to grant or revoke. See CANNOT_GRANT_ROLES.

INVALID_ROLES

A role name or bitmap is not valid. See INVALID_ROLES.

permission.get returns null for an operation

The resolver is custom, so ensforge cannot know its permission model.

Was this page helpful?