Interface IDs and roles
Detect ENS contract types with ERC-165 interface IDs, and check the ENSv2 roles an account holds on a registry or resolver.
This guide covers two sets of constants. Interface IDs tell you what a contract is. Role bitmaps tell you what an account may do on an ENSv2 registry or resolver. By the end you will have detected a resolver type and checked a role.
Prerequisites
@ensforge/contractsandvieminstalled. See Installation.- A public client. See Use ABIs with viem.
Detect a contract with an interface ID
An ERC-165 interface ID is a four-byte value a contract reports through supportsInterface. InterfaceIds groups them:
| Group | Holds |
|---|---|
InterfaceIds.registry | ENSv2 registry interfaces, such as permissionedRegistry and wrapperRegistry. |
InterfaceIds.wrapperRegistryInitializable | The two IWrapperRegistryInitializable IDs, explicit and fuseDerived, one per wrapperRegistryInitializer flag value. |
InterfaceIds.resolver | ENSv2 resolver interfaces, such as permissionedResolver. |
InterfaceIds.resolverProfiles | Resolver profile interfaces: addr, text, contenthash, abi, pubkey, extended and others. |
InterfaceIds.erc165 | The ERC-165 interface ID itself. |
Example (Detecting a PermissionedResolver)
import { Abis, InterfaceIds } from "@ensforge/contracts";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const resolver = "0x0000000000000000000000000000000000000001"; // placeholder: the resolver to inspect
const isPermissioned = await publicClient.readContract({
address: resolver,
abi: Abis.shared.erc165,
functionName: "supportsInterface",
args: [InterfaceIds.resolver.permissionedResolver],
});A resolver that does not support the ID returns false. Use InterfaceIds.resolverProfiles.text the same way to ask whether a resolver can store text records.
Read how roles are encoded
In ENSv2, a registry or resolver grants roles to accounts through EnhancedAccessControl. A role is one bit of a 256-bit number, and a set of roles is a bitmap you combine with |. Each role sits in its own nybble, and its admin role, which may grant that role, sits 128 bits higher.
| Constant | Holds |
|---|---|
Roles.registry | Registry roles, such as renew, setResolver and setSubregistry. Every role except wasReserved has an …Admin twin. |
Roles.resolver | PermissionedResolver roles, such as setAddr, setText and setContenthash, each with an …Admin twin. |
Roles.registryBitmaps | Role sets: unemancipated, regeneration and registration. |
Roles.enhancedAccessControl | Masks for allRoles and adminRoles. |
Roles.registryBitmaps.registration is the set the .eth registrar grants a new owner: changing the resolver and subregistry, their admin roles, and the admin role of transfers. Use it as a default for any new name an owner should control.
Check a role
Ask the registry for the account's roles on a name, then test the bit with &.
Example (Checking the Renew Role)
import { Abis, Deployments, Roles } from "@ensforge/contracts";
import { createPublicClient, hexToBigInt, http } from "viem";
import { labelhash } from "viem/ens";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const account = "0x0000000000000000000000000000000000000001"; // placeholder: the account to check
const bitmap = await publicClient.readContract({
address: Deployments.mainnet.v2.contracts.ethRegistry,
abi: Abis.v2.permissionedRegistry,
functionName: "roles",
args: [hexToBigInt(labelhash("vitalik")), account],
});
const canRenew = (bitmap & Roles.registry.renew) !== 0n;rolestakes the label hash as a number and the account.- To grant several roles, combine them:
Roles.registry.setResolver | Roles.registry.renew.
For a resolver, Roles.resolver.setText and its siblings apply to a resource: one record key, or the root. permissionedResolverResource({ text: "url" }) from @ensforge/contracts/v2 computes the resource for a record.
Which role bitmaps change a name's token
Roles.registryBitmaps.regeneration lists the roles whose change regenerates a name's token ID. Roles.registryBitmaps.unemancipated lists the roles that, held by anyone but the sole owner, mean the name is not emancipated. It leaves out the renew and upgrade roles. Mainnet WrapperRegistry follows these sets; the Sepolia WrapperRegistry build predates them.
Roles are ENSv2 only
Role bitmaps apply to ENSv2 registries and resolvers. ENSv1 names use owners, managers and Name Wrapper fuses instead. See Roles and permissions.
Troubleshooting
supportsInterface reverts
The address may not implement ERC-165. Check that it is a contract and that you pass the interface ID as a four-byte hex value.
See the roles reference and the interface IDs reference.
Was this page helpful?