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

role.grant

Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Options, result, errors and examples for role.grant.

Writestable
Since v1.0.0View source

Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted.

When to use

Use to delegate specific powers, such as renewing or changing the resolver, without transferring a name. Use grantSync to wait for the receipt.

Details

  • Name roles go to the name's resource in the registry holding it; root roles apply to every name in that registry or on that resolver.
  • Granting needs the matching admin roles.
  • Some roles regenerate the name's token ID; the plan carries a TOKEN_ID_REGENERATED warning.

Gotchas

  • renew granted on a name lets its holder renew it only in registries that predate contracts-v2 #505; the deployment's current UserRegistry checks it at the root (root: true).

Signature

function grant(
  client: Like,
  options: grant.Options & Write.Options,
): Promise<grant.ReturnType>

Call it as ens.role.grant(options) on a client, or Actions.role.grant(client, options).

Parameters

OptionTypeDefaultDescription
grantee (required)stringAccount that gets the roles.
roles (required)readonly Role.Name[] | bigintRoles by name, e.g. ["setResolver"], or as a bitmap.
target (required)"registry" | "resolver"Registry or PermissionedResolver roles (resolvers: root only).
namestringENS name whose registry or resolver to use. Normalized automatically.
contractstringRegistry or resolver address, instead of the name's.
rootbooleanRoot roles, applying to every name, instead of the name's.

Also takes the write options.

Returns

Resolves to Write.Result. Submitted transaction hashes and the plan that produced them.

FieldTypeDescription
hashHexHash of the last transaction.
hashesreadonly Hex[]Every submitted transaction, in order.
idstringEIP-5792 bundle id when the calls were sent as one batch.
planPlanThe plan the write executed: its steps, in order, as they were submitted.

Errors

ErrorCodesWhen
InvalidInputErrorINVALID_NAME, INVALID_ADDRESS, INVALID_ROLES, INVALID_RECORD_VALUEinvalid input or targets.
UnsupportedErrorUNSUPPORTED_PROTOCOLENSv1 names.
UnauthorizedErrorCANNOT_GRANT_ROLESwithout the admin roles.
InvalidInputErrorINVALID_ROLESa role already has the maximum of 15 holders.
UserRejectedErrorUSER_REJECTEDthe user rejects the request.
WalletErrorCHAIN_MISMATCH, ACCOUNT_NOT_FOUNDthe wallet is on another chain or has no account to sign with.
UnsupportedErrorWALLET_BATCH_UNSUPPORTEDwith mode: "batch" or a paymaster when the wallet cannot send calls as one batch.

It can also fail with the errors every write can (Errors.WriteError: the common errors plus InsufficientFundsError, TransactionError, UnsupportedError, UserRejectedError, WalletError).

See How errors work.

Examples

Granting a role
const { hash } = await ens.role.grant({ name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" })

Plan methods

Each method takes the same options as role.grant and sends nothing. See Preview before sending.

MethodDescription
role.grant.prepare(options)Builds the plan without sending anything.
role.grant.simulate(options)Simulates the plan with eth_call, reporting each step.
role.grant.estimateGas(options)Estimates the gas and ETH the plan needs.

Wait for the receipt with grantSync

Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in.

Use when the next step depends on the change being on-chain.

role.grantSync takes the same options plus confirmations and timeout.

Resolves to Write.SyncResult. Receipts plus the submitted hashes and plan.

Granting a role and waiting
const { receipt } = await ens.role.grantSync({ name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" })

See also

Was this page helpful?