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.
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_REGENERATEDwarning.
Gotchas
renewgranted 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
| Option | Type | Default | Description |
|---|---|---|---|
grantee (required) | string | Account that gets the roles. | |
roles (required) | readonly Role.Name[] | bigint | Roles by name, e.g. ["setResolver"], or as a bitmap. | |
target (required) | "registry" | "resolver" | Registry or PermissionedResolver roles (resolvers: root only). | |
name | string | ENS name whose registry or resolver to use. Normalized automatically. | |
contract | string | Registry or resolver address, instead of the name's. | |
root | boolean | Root 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.
| Field | Type | Description |
|---|---|---|
hash | Hex | Hash of the last transaction. |
hashes | readonly Hex[] | Every submitted transaction, in order. |
id | string | EIP-5792 bundle id when the calls were sent as one batch. |
plan | Plan | The plan the write executed: its steps, in order, as they were submitted. |
Errors
| Error | Codes | When |
|---|---|---|
InvalidInputError | INVALID_NAME, INVALID_ADDRESS, INVALID_ROLES, INVALID_RECORD_VALUE | invalid input or targets. |
UnsupportedError | UNSUPPORTED_PROTOCOL | ENSv1 names. |
UnauthorizedError | CANNOT_GRANT_ROLES | without the admin roles. |
InvalidInputError | INVALID_ROLES | a role already has the maximum of 15 holders. |
UserRejectedError | USER_REJECTED | the user rejects the request. |
WalletError | CHAIN_MISMATCH, ACCOUNT_NOT_FOUND | the wallet is on another chain or has no account to sign with. |
UnsupportedError | WALLET_BATCH_UNSUPPORTED | with 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
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.
| Method | Description |
|---|---|
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.
const { receipt } = await ens.role.grantSync({ name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" })See also
role.getto read roles
Was this page helpful?