Client
Look up the options of Ensforge.create, the action groups, and the read, write and plan option types that every @ensforge/sdk action shares.
The client, its options and the option and result types every action shares. See Create a client.
Create a client
Ensforge.create
Creates an ensforge client from viem clients.
function create(options: CreateOptions): ClientUse once per chain, at app start, then add action groups with extend.
- The deployment is chosen by chain ID (mainnet, Sepolia); other chains need
deployment. walletClientcan be a getter, so a wallet that connects later works.chainsadds clients for other chains, for the writes ENS makes there: primary names on L2s (primaryName.setwithcoin: { chainId }).- The client and its
configare frozen.
import { Ensforge, ensActions } from "@ensforge/sdk"
const ens = Ensforge.create({ publicClient, walletClient }).extend(ensActions())import { Deployments } from "@ensforge/contracts"
import { Ensforge } from "@ensforge/sdk"
const ens = Ensforge.create({
publicClient: anvil,
deployment: Deployments.define({ name: "devnet", chainId: 31337, v2: devnetV2 }),
})import { Ensforge, ensActions } from "@ensforge/sdk"
const ens = Ensforge.create({
publicClient,
walletClient,
chains: { 10: { publicClient: optimismClient, walletClient: optimismWallet } },
}).extend(ensActions())
await ens.primaryName.set({ name: "alice.eth", coin: { chainId: 10 } })Errors:
ConfigError(UNKNOWN_CHAIN) when the chain has no built-in deployment and none is given.ConfigError(INVALID_DEPLOYMENT) whendeploymentis invalid or for another chain.ConfigError(CHAIN_NOT_CONFIGURED) when an entry ofchainsholds clients of another chain.
Ensforge.from
Returns client when it is an ensforge client, otherwise an ensforge client for the viem
client, created once and reused.
function from(client: Like): ClientUse in your own helpers that accept either client. Every action already does this.
Errors:
ConfigError(UNKNOWN_CHAIN) when a bare viem client is on a chain without a built-in deployment.
Ensforge.is
Whether value is an ensforge client.
function is(value: unknown): value is ClientEnsforge.fromWagmi
Creates an ensforge client from a wagmi config: reads use wagmi's client for the ENS chain, and writes use whichever wallet is connected when they run.
function fromWagmi(config: WagmiConfig, options: fromWagmi.Options = {}): ClientUse in apps that already have a wagmi config (RainbowKit, ConnectKit, Dynamic, Privy, Reown
AppKit), instead of passing viem clients to Ensforge.create.
-
Works with wagmi 2 and 3.
-
The ENS chain is
chainId, else mainnet when the config has it, else the first configured chain ensforge has a deployment for. Its transport must be in the wagmi config. -
The wallet is looked up on every write, so account and connector changes are followed. With no wallet connected, writes fail with
WALLET_NOT_CONFIGURED. -
A wallet on another chain is asked to switch first, as wagmi's own
writeContractdoes. -
Every other chain of the wagmi config becomes one of the client's
chains, so writes ENS makes there (an L2 primary name) use wagmi's clients and wallet;chainsadds or overrides. -
fromWagmilives on theEnsforgefrom@ensforge/sdk/wagmi, so apps without wagmi never load it. The client it returns works with everything in@ensforge/sdk.
import { ensActions } from "@ensforge/sdk"
import { Ensforge } from "@ensforge/sdk/wagmi"
const ens = Ensforge.fromWagmi(wagmiConfig).extend(ensActions())
await ens.record.set({ name: "alice.eth", texts: { url: "https://alice.xyz" } })import { Ensforge } from "@ensforge/sdk/wagmi"
const ens = Ensforge.fromWagmi(wagmiConfig, { chainId: 11155111, switchChain: false })Errors:
ConfigError(UNKNOWN_CHAIN) when no ENS chain can be chosen or the wagmi config has no transport for it.ConfigError(INVALID_DEPLOYMENT) whendeploymentis invalid or for another chain.ConfigError(CHAIN_NOT_CONFIGURED) when an entry ofchainsholds clients of another chain.
Ensforge.layer
A layer that creates the client with Ensforge.create.
function layer(options: CreateOptions): Layer.Layer<Ensforge, ConfigError>Ensforge.ChainClients
viem clients for a chain other than the ENS chain, e.g. an L2 where an address sets its primary name for that chain.
type ChainClients| Field | Type | Description |
|---|---|---|
publicClient | ViemClient | viem client for reads and simulation on the chain. |
walletClient (optional) | ViemWalletClient | (() => ViemWalletClient | undefined | Promise<ViemWalletClient | undefined>) | viem client for writes on the chain, or a getter for wallets that change (wagmi connectors). |
Ensforge.Client
The ensforge client. Its top level holds what app code reads day to day and extend; action
groups added by extend sit beside them.
type Client<actions extends object = {}> = actions & ClientBase<actions>;| Field | Type | Description |
|---|---|---|
chain | { readonly id: number; readonly name: string } | The chain the client reads and writes ENS on. |
account | Address | Default signer address, or undefined without a wallet. |
deployment | Deployments.Profile | ENS deployments on this chain (addresses, capabilities, provenance). |
publicClient | ViemClient | The viem client used for reads, as an escape hatch. |
config | Config | The configuration the client was created with. |
extend | <const added extends object>( decorator: (client: Client<object>) => added, ) => Client<object & added> | Adds action groups; returns a new client. |
Ensforge.ClientBase
Members every ensforge client has, whatever action groups it carries.
interface ClientBase<actions extends object = {}>| Field | Type | Description |
|---|---|---|
chain | { readonly id: number; readonly name: string } | The chain the client reads and writes ENS on. |
account | Address | Default signer address, or undefined without a wallet. |
deployment | Deployments.Profile | ENS deployments on this chain (addresses, capabilities, provenance). |
publicClient | ViemClient | The viem client used for reads, as an escape hatch. |
config | Config | The configuration the client was created with. |
extend | <const added extends object>( decorator: (client: Client<object>) => added, ) => Client<object & added> | Adds action groups; returns a new client. |
Ensforge.Config
Behaviour settings, set once in Ensforge.create and rarely read back.
type Config| Option | Type | Default | Description |
|---|---|---|---|
ccipRead (required) | { readonly gatewayUrls: readonly string[] } | false | Off-chain resolution (CCIP-Read) through the Universal Resolver's batch gateways. false disables it. | |
batch (required) | { readonly multicall: false | { readonly batchSize: number; readonly wait: number }; } | Coalescing of concurrent contract reads into multicall. | |
blockTag (required) | BlockTag | Default block tag for reads. | |
storage (required) | Plan.Storage | Where multi-step plans save their progress. | |
simulate (required) | boolean | Whether writes are simulated before the wallet prompt. | |
indexer (required) | Indexer | Indexer for indexer.* actions and migration discovery, when configured. | |
gateways (required) | { readonly [protocol in keyof Gateways]-?: string } | Storage gateways for avatars and content-hash URLs, defaults filled in. |
Ensforge.CreateOptions
Options for Ensforge.create.
type CreateOptions| Option | Type | Default | Description |
|---|---|---|---|
publicClient (required) | ViemClient | viem client for reads. Its chain selects the deployment. | |
walletClient | ViemWalletClient | (() => ViemWalletClient | undefined | Promise<ViemWalletClient | undefined>) | publicClient when it has an account | viem client for writes, or a getter for wallets that change (wagmi connectors). |
chains | Readonly<Record<number, ChainClients>> | none; writes for another chain fail with CHAIN_NOT_CONFIGURED | Clients for other chains, by chain ID: writes ENS makes there (an L2 primary name) run on them, and plans for them resume on them. The signer is the same account on every chain. |
account | Account | Address | the wallet client's account | Default signer for writes. |
deployment | Deployments.Profile | Deployments.get({ chainId }) | ENS deployments. Required for chains ensforge does not ship (devnets, forks, other chains). |
ccipRead | { readonly gatewayUrls?: readonly string[] | undefined } | false | the Universal Resolver's own batch gateway | Off-chain resolution. false disables CCIP-Read. gatewayUrls are the Universal Resolver's batch gateways and replace its default, not the gateways of individual resolvers. |
batch | { readonly multicall?: | boolean | { readonly batchSize?: number; readonly wait?: number } | undefined; } | { multicall: true } | Coalesce concurrent reads into multicall. wait is in milliseconds. |
blockTag | BlockTag | "latest" | Default block tag for reads. |
storage | Plan.Storage | Plan.memoryStorage() | Where multi-step plans save their progress. |
simulate | boolean | true | Simulate writes before the wallet prompt. |
indexer | Indexer | none; indexer actions fail with INDEXER_NOT_CONFIGURED | Indexer for indexer.* actions and for discovering records and subnames during migration: bigname(), goldsky(), fallback([...]) or defineIndexer({...}) from @ensforge/sdk/indexer. |
gateways | Gateways | https://ipfs.io, https://arweave.net and https://api.gateway.ethswarm.org | Storage gateways for avatars (record.getAvatar) and content-hash URLs (ContentHash.toGatewayUrl(uri, ens.config.gateways)). A call's own gateways override them. |
Ensforge.Gateways
HTTP gateways that turn decentralized-storage URIs (avatars, content hashes) into URLs a
browser can load. Each is an origin, such as https://ipfs.io.
type Gateways| Field | Type | Description |
|---|---|---|
ipfs (optional) | string | IPFS gateway, for ipfs://, ipns:// and bare CIDs. The public ipfs.io is rate limited: use a dedicated gateway in production. |
arweave (optional) | string | Arweave gateway, for ar://. |
swarm (optional) | string | Swarm gateway, for bzz:// content hashes. |
Ensforge.Like
Anything an action accepts: an ensforge client or a bare viem client.
type Like = Client<object> | ViemClient;Ensforge.ViemClient
A viem client used for reads. viem's base client type keeps type checking fast; any
PublicClient or WalletClient fits.
type ViemClient = ViemBaseClient<Transport, Chain | undefined>;Ensforge.ViemWalletClient
A viem client that can sign: any WalletClient, or a client created with an account.
type ViemWalletClient = ViemBaseClient<Transport, Chain | undefined, Account | undefined>;Ensforge.fromWagmi.Options
Options for fromWagmi: those of Ensforge.create, without the viem clients.
type Options = Omit<CreateOptions, "publicClient" | "walletClient"> & { /** * The ENS chain. * * @default mainnet when configured, else the first configured chain with a built-in deployment */ chainId?: number | undefined; /** * Ask the wallet to switch to the ENS chain before a write. With `false`, a wallet on another * chain fails with `WalletError` (`CHAIN_MISMATCH`). * * @default true */ switchChain?: boolean | undefined; };| Option | Type | Default | Description |
|---|---|---|---|
chains | Readonly<Record<number, ChainClients>> | none; writes for another chain fail with CHAIN_NOT_CONFIGURED | Clients for other chains, by chain ID: writes ENS makes there (an L2 primary name) run on them, and plans for them resume on them. The signer is the same account on every chain. |
account | Account | Address | the wallet client's account | Default signer for writes. |
deployment | Deployments.Profile | Deployments.get({ chainId }) | ENS deployments. Required for chains ensforge does not ship (devnets, forks, other chains). |
ccipRead | { readonly gatewayUrls?: readonly string[] | undefined } | false | the Universal Resolver's own batch gateway | Off-chain resolution. false disables CCIP-Read. gatewayUrls are the Universal Resolver's batch gateways and replace its default, not the gateways of individual resolvers. |
batch | { readonly multicall?: | boolean | { readonly batchSize?: number; readonly wait?: number } | undefined; } | { multicall: true } | Coalesce concurrent reads into multicall. wait is in milliseconds. |
blockTag | BlockTag | "latest" | Default block tag for reads. |
storage | Plan.Storage | Plan.memoryStorage() | Where multi-step plans save their progress. |
simulate | boolean | true | Simulate writes before the wallet prompt. |
indexer | Indexer | none; indexer actions fail with INDEXER_NOT_CONFIGURED | Indexer for indexer.* actions and for discovering records and subnames during migration: bigname(), goldsky(), fallback([...]) or defineIndexer({...}) from @ensforge/sdk/indexer. |
gateways | Gateways | https://ipfs.io, https://arweave.net and https://api.gateway.ethswarm.org | Storage gateways for avatars (record.getAvatar) and content-hash URLs (ContentHash.toGatewayUrl(uri, ens.config.gateways)). A call's own gateways override them. |
chainId | number | mainnet when configured, else the first configured chain with a built-in deployment | The ENS chain. |
switchChain | boolean | true | Ask the wallet to switch to the ENS chain before a write. With false, a wallet on another chain fails with WalletError (CHAIN_MISMATCH). |
Ensforge.Ensforge
The ensforge client as an Effect service.
class Ensforgeimport { Effect } from "effect"
import { Actions, Ensforge } from "@ensforge/sdk/effect"
const program = Effect.gen(function* () {
const ens = yield* Ensforge.Ensforge
return yield* Actions.record.getText(ens, { name: "nick.eth", key: "url" })
})
await Effect.runPromise(program.pipe(Effect.provide(Ensforge.layer({ publicClient }))))Action groups
Decorators add action groups to a client: Ensforge.create(options).extend(ensActions()).
approvalActions
Adds the approval actions to a client.
function approvalActions()batchActions
Adds batch to a client.
function batchActions()dnsActions
Adds the dns actions to a client.
function dnsActions()ensActions
Adds every ENS action group to a client.
function ensActions()import { Ensforge, ensActions } from "@ensforge/sdk"
const ens = Ensforge.create({ publicClient, walletClient }).extend(ensActions())eventActions
Adds the event actions to a client.
function eventActions()indexerActions
Adds the indexer actions to a client.
function indexerActions()migrationActions
Adds the migration actions to a client.
function migrationActions()nameActions
Adds the name actions to a client.
function nameActions()permissionActions
Adds the permission actions to a client.
function permissionActions()planActions
Adds the plan actions to a client.
function planActions()primaryNameActions
Adds the primaryName actions to a client.
function primaryNameActions()recordActions
Adds the record actions to a client.
function recordActions()registrationActions
Adds the registration actions to a client.
function registrationActions()registryActions
Adds the registry actions to a client.
function registryActions()resolverActions
Adds the resolver actions to a client.
function resolverActions()roleActions
Adds the role actions to a client.
function roleActions()subnameActions
Adds the subname actions to a client.
function subnameActions()wrapperActions
Adds the wrapper actions to a client.
function wrapperActions()ApprovalActions
approval actions bound to a client.
type ApprovalActions| Field | Type | Description |
|---|---|---|
approval | { /** Checks whether a delegate may edit a name's records on its public resolver (`isApprovedFor`). */ readonly getDelegate: Bound<typeof approval.getDelegate>; /** Checks whether an operator may manage everything an owner holds on an ENS contract (`isApprovedForAll`). */ readonly getOperator: Bound<typeof approval.getOperator>; /** Reads the address approved to transfer one ENSv1 name token (`getApproved`). */ readonly getToken: Bound<typeof approval.getToken>; /** Approves or revokes a delegate who may edit a name's records on its public resolver. Resolves once the transaction is submitted. */ readonly setDelegate: BoundWrite<typeof approval.setDelegate>; /** Approves or revokes a delegate who may edit a name's records on its public resolver. Resolves once the receipt is in. */ readonly setDelegateSync: Bound<typeof approval.setDelegateSync>; /** Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). Resolves once the transaction is submitted. */ readonly setOperator: BoundWrite<typeof approval.setOperator>; /** Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). Resolves once the receipt is in. */ readonly setOperatorSync: Bound<typeof approval.setOperatorSync>; /** Approves one address to transfer one ENSv1 name token, or clears the approval. Resolves once the transaction is submitted. */ readonly setToken: BoundWrite<typeof approval.setToken>; /** Approves one address to transfer one ENSv1 name token, or clears the approval. Resolves once the receipt is in. */ readonly setTokenSync: Bound<typeof approval.setTokenSync>; } |
BatchActions
batch bound to a client.
type BatchActions| Field | Type | Description |
|---|---|---|
batch | batch.Bound |
DnsActions
dns actions bound to a client.
type DnsActions| Field | Type | Description |
|---|---|---|
dns | { /** Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. Resolves once the transaction is submitted. */ readonly claim: BoundWrite<typeof dns.claim>; /** Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. Resolves once the receipt is in. */ readonly claimSync: Bound<typeof dns.claimSync>; /** Reads the gasless DNS resolver a DNS name sets in an `ENS1` TXT record. */ readonly getOffchainResolver: Bound<typeof dns.getOffchainResolver>; /** Fetches the DNSSEC proof of a DNS name's `_ens` TXT record. */ readonly getProof: Bound<typeof dns.getProof>; /** Reads DNS records and the zonehash a name stores on its resolver. */ readonly getRecords: Bound<typeof dns.getRecords>; /** Reads whether a DNS name is imported into ENS, and what it needs to be. */ readonly getStatus: Bound<typeof dns.getStatus>; /** Sets DNS records or the zonehash of a name on its public resolver. Resolves once the transaction is submitted. */ readonly setRecords: BoundWrite<typeof dns.setRecords>; /** Sets DNS records or the zonehash of a name on its public resolver. Resolves once the receipt is in. */ readonly setRecordsSync: Bound<typeof dns.setRecordsSync>; } |
EnsActions
Every action group bound to a client.
type EnsActions = ApprovalActions & DnsActions & EventActions & MigrationActions & NameActions & PermissionActions & PlanActions & PrimaryNameActions & RecordActions & RegistrationActions & RegistryActions & ResolverActions & RoleActions & SubnameActions & WrapperActions & BatchActions;| Field | Type | Description |
|---|---|---|
approval | { /** Checks whether a delegate may edit a name's records on its public resolver (`isApprovedFor`). */ readonly getDelegate: Bound<typeof approval.getDelegate>; /** Checks whether an operator may manage everything an owner holds on an ENS contract (`isApprovedForAll`). */ readonly getOperator: Bound<typeof approval.getOperator>; /** Reads the address approved to transfer one ENSv1 name token (`getApproved`). */ readonly getToken: Bound<typeof approval.getToken>; /** Approves or revokes a delegate who may edit a name's records on its public resolver. Resolves once the transaction is submitted. */ readonly setDelegate: BoundWrite<typeof approval.setDelegate>; /** Approves or revokes a delegate who may edit a name's records on its public resolver. Resolves once the receipt is in. */ readonly setDelegateSync: Bound<typeof approval.setDelegateSync>; /** Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). Resolves once the transaction is submitted. */ readonly setOperator: BoundWrite<typeof approval.setOperator>; /** Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). Resolves once the receipt is in. */ readonly setOperatorSync: Bound<typeof approval.setOperatorSync>; /** Approves one address to transfer one ENSv1 name token, or clears the approval. Resolves once the transaction is submitted. */ readonly setToken: BoundWrite<typeof approval.setToken>; /** Approves one address to transfer one ENSv1 name token, or clears the approval. Resolves once the receipt is in. */ readonly setTokenSync: Bound<typeof approval.setTokenSync>; } | |
dns | { /** Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. Resolves once the transaction is submitted. */ readonly claim: BoundWrite<typeof dns.claim>; /** Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. Resolves once the receipt is in. */ readonly claimSync: Bound<typeof dns.claimSync>; /** Reads the gasless DNS resolver a DNS name sets in an `ENS1` TXT record. */ readonly getOffchainResolver: Bound<typeof dns.getOffchainResolver>; /** Fetches the DNSSEC proof of a DNS name's `_ens` TXT record. */ readonly getProof: Bound<typeof dns.getProof>; /** Reads DNS records and the zonehash a name stores on its resolver. */ readonly getRecords: Bound<typeof dns.getRecords>; /** Reads whether a DNS name is imported into ENS, and what it needs to be. */ readonly getStatus: Bound<typeof dns.getStatus>; /** Sets DNS records or the zonehash of a name on its public resolver. Resolves once the transaction is submitted. */ readonly setRecords: BoundWrite<typeof dns.setRecords>; /** Sets DNS records or the zonehash of a name on its public resolver. Resolves once the receipt is in. */ readonly setRecordsSync: Bound<typeof dns.setRecordsSync>; } | |
event | { /** Normalizes the ENS events in logs or transaction receipts. */ readonly decode: Bound<typeof event.decode>; /** Reads the ENS events of one name over a block range, across ENSv1 and ENSv2. */ readonly get: Bound<typeof event.get>; /** Watches one name's ENS events as new blocks arrive. Resolves to a function that stops watching. */ readonly watch: Bound<typeof event.watch>; } | |
migration | { /** Reads whether an ENSv1 name can migrate to ENSv2, how, and what it becomes. */ readonly get: Bound<typeof migration.get>; /** Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the transaction is submitted. */ readonly migrate: BoundWrite<typeof migration.migrate>; /** Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the receipt is in. */ readonly migrateSync: Bound<typeof migration.migrateSync>; } | |
name | { /** Reads the full state of a name across ENSv1 and ENSv2: where it lives, who owns it, its resolver, expiry and whether it can be registered or renewed. */ readonly get: Bound<typeof name.get>; /** Recovers a label from its labelhash through the ENSv2 LabelStore. */ readonly getLabel: Bound<typeof name.getLabel>; /** Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. Resolves once the transaction is submitted. */ readonly reclaim: BoundWrite<typeof name.reclaim>; /** Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. Resolves once the receipt is in. */ readonly reclaimSync: Bound<typeof name.reclaimSync>; /** Sets the ENSv1 manager (registry owner) of a name. Resolves once the transaction is submitted. */ readonly setManager: BoundWrite<typeof name.setManager>; /** Sets the ENSv1 manager (registry owner) of a name. Resolves once the receipt is in. */ readonly setManagerSync: Bound<typeof name.setManagerSync>; /** Sets the ENSv1 registry TTL of a name. Resolves once the transaction is submitted. */ readonly setTtl: BoundWrite<typeof name.setTtl>; /** Sets the ENSv1 registry TTL of a name. Resolves once the receipt is in. */ readonly setTtlSync: Bound<typeof name.setTtlSync>; /** Sends a name to another account and resolves once the transaction is submitted. */ readonly transfer: BoundWrite<typeof name.transfer>; /** Sends a name to another account and resolves once the receipt is in. */ readonly transferSync: Bound<typeof name.transferSync>; } | |
permission | { /** Checks whether an account may perform one operation on an ENS name, and lists exactly what it lacks when it may not. */ readonly check: Bound<typeof permission.check>; /** Reads what an account may do with an ENS name: transfer it, change its resolver, edit records, create subnames and more, across ENSv1 ownership and ENSv2 roles. */ readonly get: Bound<typeof permission.get>; /** Lets another account edit a name's records, or takes that access back. Resolves once the transaction is submitted. */ readonly setRecordAccess: BoundWrite<typeof permission.setRecordAccess>; /** Lets another account edit a name's records, or takes that access back. Resolves once the receipt is in. */ readonly setRecordAccessSync: Bound<typeof permission.setRecordAccessSync>; } | |
plan | { /** Reads a saved plan and its progress. */ readonly get: Bound<typeof plan.get>; /** Lists the saved plans of this client's chain and of its `chains`, newest first. */ readonly list: Bound<typeof plan.list>; /** Records a transaction sent outside ensforge as a plan step's submission. */ readonly reconcile: Bound<typeof plan.reconcile>; /** Continues a saved plan after a failure or a reload. Resolves once the remaining transactions are submitted. */ readonly resume: Bound<typeof plan.resume>; /** Continues a saved plan and resolves once every receipt is in. */ readonly resumeSync: Bound<typeof plan.resumeSync>; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the transaction is submitted. */ readonly send: BoundWrite<typeof plan.send>; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the receipt is in. */ readonly sendSync: Bound<typeof plan.sendSync>; } | |
primaryName | { /** Reads the primary name of an address (ENSIP-19 reverse resolution), verified against the name's address record. */ readonly get: Bound<typeof primaryName.get>; /** Sets or clears the primary name (reverse record) of an address. Resolves once the transaction is submitted. */ readonly set: BoundWrite<typeof primaryName.set>; /** Sets or clears the primary name (reverse record) of an address. Resolves once the receipt is in. */ readonly setSync: Bound<typeof primaryName.setSync>; /** Signs a claim to a primary name on one or more L2s, with one signature and no transaction. Anyone can then submit it on each chain with `primaryName.set`, so the account needs no gas or wallet connection there. */ readonly signClaim: Bound<typeof primaryName.signClaim>; } | |
record | { /** Reads any mix of a name's records in one request: texts, addresses, content hash, ABI, public key, name record, interface implementers and data records. */ readonly get: record.get.Bound; /** Reads one address record of an ENS name, for Ethereum by default or any coin (ENSIP-9, ENSIP-11). */ readonly getAddress: record.getAddress.Bound; /** Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12). */ readonly getAvatar: Bound<typeof record.getAvatar>; /** Reads the content hash of an ENS name (ENSIP-7), decoded into its protocol, value and URI. */ readonly getContentHash: Bound<typeof record.getContentHash>; /** Reads one text record of an ENS name, such as `url`, `avatar` or `com.twitter`. */ readonly getText: Bound<typeof record.getText>; /** Writes records of an ENS name and resolves once the transaction is submitted. */ readonly set: BoundWrite<typeof record.set>; /** Writes records of an ENS name and resolves once the receipt is in. */ readonly setSync: Bound<typeof record.setSync>; } | |
registration | { /** Commits to registering `.eth` names, the first half of a registration. Resolves once the transaction is submitted. */ readonly commit: BoundWrite<typeof registration.commit>; /** Commits to registering `.eth` names, the first half of a registration. Resolves once the receipt is in. */ readonly commitSync: Bound<typeof registration.commitSync>; /** Reads where a registration commitment is in its window. */ readonly getCommitmentStatus: Bound<typeof registration.getCommitmentStatus>; /** Reads the `.eth` registration settings: contracts, commitment window, minimum duration, grace period and accepted payment tokens. */ readonly getParameters: Bound<typeof registration.getParameters>; /** Quotes the price of registering a `.eth` name, in an ERC-20 payment token. */ readonly getPrice: Bound<typeof registration.getPrice>; /** Quotes renewing one or more `.eth` names, in an ERC-20 payment token. */ readonly getRenewalPrice: Bound<typeof registration.getRenewalPrice>; /** Checks whether a `.eth` name can be registered now. */ readonly isAvailable: Bound<typeof registration.isAvailable>; /** Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the transaction is submitted. */ readonly register: BoundWrite<typeof registration.register>; /** Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the receipt is in. */ readonly registerSync: Bound<typeof registration.registerSync>; /** Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. Resolves once the transaction is submitted. */ readonly renew: BoundWrite<typeof registration.renew>; /** Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. Resolves once the receipt is in. */ readonly renewSync: Bound<typeof registration.renewSync>; } | |
registry | { /** Sets or removes the subregistry of an ENSv2 name. Resolves once the transaction is submitted. */ readonly attach: BoundWrite<typeof registry.attach>; /** Sets or removes the subregistry of an ENSv2 name. Resolves once the receipt is in. */ readonly attachSync: Bound<typeof registry.attachSync>; /** Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Resolves once the transaction is submitted. */ readonly deploy: BoundWrite<typeof registry.deploy>; /** Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Resolves once the receipt is in. */ readonly deploySync: Bound<typeof registry.deploySync>; /** Reads an ENSv2 registry: its kind, implementation, parent, canonical name, URI, whether it is emancipated, and whether it can be upgraded. */ readonly get: Bound<typeof registry.get>; /** Sets the metadata URI of an ENSv2 registry. Resolves once the transaction is submitted. */ readonly setUri: BoundWrite<typeof registry.setUri>; /** Sets the metadata URI of an ENSv2 registry. Resolves once the receipt is in. */ readonly setUriSync: Bound<typeof registry.setUriSync>; /** Upgrades an ENSv2 registry to the deployment's latest implementation. Resolves once the transaction is submitted. */ readonly upgrade: BoundWrite<typeof registry.upgrade>; /** Upgrades an ENSv2 registry to the deployment's latest implementation. Resolves once the receipt is in. */ readonly upgradeSync: Bound<typeof registry.upgradeSync>; } | |
resolver | { /** Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Resolves once the transaction is submitted. */ readonly create: BoundWrite<typeof resolver.create>; /** Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Resolves once the receipt is in. */ readonly createSync: Bound<typeof resolver.createSync>; /** Reads the resolver of an ENS name: its address, what kind of resolver it is, who may write to it and which record profiles it supports. */ readonly get: Bound<typeof resolver.get>; /** Reads which record set an ENS name uses on its PermissionedResolver. */ readonly getLink: Bound<typeof resolver.getLink>; /** Links an ENS name to the records of another name on the same PermissionedResolver. Resolves once the transaction is submitted. */ readonly link: BoundWrite<typeof resolver.link>; /** Links an ENS name to the records of another name on the same PermissionedResolver. Resolves once the receipt is in. */ readonly linkSync: Bound<typeof resolver.linkSync>; /** Calls the resolver of an ENS name with raw calldata through the Universal Resolver (ENSIP-10). */ readonly resolve: Bound<typeof resolver.resolve>; /** Points an ENS name at a resolver. Resolves once the transaction is submitted. */ readonly set: BoundWrite<typeof resolver.set>; /** Points an ENS name at a resolver. Resolves once the receipt is in. */ readonly setSync: Bound<typeof resolver.setSync>; /** Upgrades the PermissionedResolver of an ENS name to a newer implementation. Resolves once the transaction is submitted. */ readonly upgrade: BoundWrite<typeof resolver.upgrade>; /** Upgrades the PermissionedResolver of an ENS name to a newer implementation. Resolves once the receipt is in. */ readonly upgradeSync: Bound<typeof resolver.upgradeSync>; } | |
role | { /** Reads the ENSv2 roles an account holds on a name, or at the root of a registry or resolver. */ readonly get: Bound<typeof role.get>; /** Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted. */ readonly grant: BoundWrite<typeof role.grant>; /** Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in. */ readonly grantSync: Bound<typeof role.grantSync>; /** Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted. */ readonly revoke: BoundWrite<typeof role.revoke>; /** Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in. */ readonly revokeSync: Bound<typeof role.revokeSync>; } | |
subname | { /** Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the transaction is submitted. */ readonly create: BoundWrite<typeof subname.create>; /** Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the receipt is in. */ readonly createSync: Bound<typeof subname.createSync>; /** Removes a subname. Resolves once the transaction is submitted. */ readonly remove: BoundWrite<typeof subname.remove>; /** Removes a subname. Resolves once the receipt is in. */ readonly removeSync: Bound<typeof subname.removeSync>; /** Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the transaction is submitted. */ readonly update: BoundWrite<typeof subname.update>; /** Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the receipt is in. */ readonly updateSync: Bound<typeof subname.updateSync>; } | |
wrapper | { /** Reads the NameWrapper owner, fuses and expiry of an ENSv1 name. */ readonly getFuses: Bound<typeof wrapper.getFuses>; /** Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Resolves once the transaction is submitted. */ readonly setChildFuses: BoundWrite<typeof wrapper.setChildFuses>; /** Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Resolves once the receipt is in. */ readonly setChildFusesSync: Bound<typeof wrapper.setChildFusesSync>; /** Burns owner-controlled fuses on a wrapped ENSv1 name. Resolves once the transaction is submitted. */ readonly setFuses: BoundWrite<typeof wrapper.setFuses>; /** Burns owner-controlled fuses on a wrapped ENSv1 name. Resolves once the receipt is in. */ readonly setFusesSync: Bound<typeof wrapper.setFusesSync>; /** Unwraps an ENSv1 name from the NameWrapper. Resolves once the transaction is submitted. */ readonly unwrap: BoundWrite<typeof wrapper.unwrap>; /** Unwraps an ENSv1 name from the NameWrapper. Resolves once the receipt is in. */ readonly unwrapSync: Bound<typeof wrapper.unwrapSync>; /** Wraps an ENSv1 name in the NameWrapper. Resolves once the transaction is submitted. */ readonly wrap: BoundWrite<typeof wrapper.wrap>; /** Wraps an ENSv1 name in the NameWrapper. Resolves once the receipt is in. */ readonly wrapSync: Bound<typeof wrapper.wrapSync>; } | |
batch | batch.Bound |
EventActions
event actions bound to a client.
type EventActions| Field | Type | Description |
|---|---|---|
event | { /** Normalizes the ENS events in logs or transaction receipts. */ readonly decode: Bound<typeof event.decode>; /** Reads the ENS events of one name over a block range, across ENSv1 and ENSv2. */ readonly get: Bound<typeof event.get>; /** Watches one name's ENS events as new blocks arrive. Resolves to a function that stops watching. */ readonly watch: Bound<typeof event.watch>; } |
IndexerActions
indexer actions bound to a client.
type IndexerActions| Field | Type | Description |
|---|---|---|
indexer | { /** Searches indexed ENS events by name, address, resolver, contract or block range. */ readonly getEvents: Bound<typeof indexer.getEvents>; /** Reads the full history of a name, or of every name an address is related to. */ readonly getHistory: Bound<typeof indexer.getHistory>; /** Reads one name from the indexer: owner, manager, expiry, resolver, records and protocol. */ readonly getName: Bound<typeof indexer.getName>; /** Lists names by when they expire or leave their grace period. */ readonly getNamesByExpiry: Bound<typeof indexer.getNamesByExpiry>; /** Lists the names an address owns, manages, holds roles on, resolves to, or used to own. */ readonly getNamesForAddress: Bound<typeof indexer.getNamesForAddress>; /** Reads what the indexer serves for a namespace: its networks and which features are complete. */ readonly getNamespace: Bound<typeof indexer.getNamespace>; /** Lists who can do what over a name, a registration, an account or an ENSv2 registry. */ readonly getPermissions: Bound<typeof indexer.getPermissions>; /** Reads an address's primary name from the indexer, verified on-chain when the indexer can. */ readonly getPrimaryName: Bound<typeof indexer.getPrimaryName>; /** Reads a name's records and its record inventory from the indexer. */ readonly getRecords: Bound<typeof indexer.getRecords>; /** Reads an ENSv2 registry: the name it serves, its parent registry, when it was created and its counts. */ readonly getRegistry: Bound<typeof indexer.getRegistry>; /** Lists the labels of an ENSv2 registry, optionally only those an address holds or does not hold. */ readonly getRegistryLabels: Bound<typeof indexer.getRegistryLabels>; /** Reads a resolver and one page of the names bound to it. */ readonly getResolver: Bound<typeof indexer.getResolver>; /** Lists the names linked to record sets on an ENSv2 resolver. */ readonly getResolverLinks: Bound<typeof indexer.getResolverLinks>; /** Lists the role grants on an ENSv2 resolver. */ readonly getResolverRoles: Bound<typeof indexer.getResolverRoles>; /** Lists the ENSv2 resolvers on which an address holds roles. */ readonly getResolvers: Bound<typeof indexer.getResolvers>; /** Reads the indexer's health and how far each chain is indexed. */ readonly getStatus: Bound<typeof indexer.getStatus>; /** Lists the direct subnames of a name. */ readonly getSubnames: Bound<typeof indexer.getSubnames>; /** Reads up to 1,000 names and addresses in one request. */ readonly lookup: Bound<typeof indexer.lookup>; /** Searches names by text. */ readonly search: Bound<typeof indexer.search>; } |
MigrationActions
migration actions bound to a client.
type MigrationActions| Field | Type | Description |
|---|---|---|
migration | { /** Reads whether an ENSv1 name can migrate to ENSv2, how, and what it becomes. */ readonly get: Bound<typeof migration.get>; /** Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the transaction is submitted. */ readonly migrate: BoundWrite<typeof migration.migrate>; /** Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the receipt is in. */ readonly migrateSync: Bound<typeof migration.migrateSync>; } |
NameActions
name actions bound to a client.
type NameActions| Field | Type | Description |
|---|---|---|
name | { /** Reads the full state of a name across ENSv1 and ENSv2: where it lives, who owns it, its resolver, expiry and whether it can be registered or renewed. */ readonly get: Bound<typeof name.get>; /** Recovers a label from its labelhash through the ENSv2 LabelStore. */ readonly getLabel: Bound<typeof name.getLabel>; /** Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. Resolves once the transaction is submitted. */ readonly reclaim: BoundWrite<typeof name.reclaim>; /** Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. Resolves once the receipt is in. */ readonly reclaimSync: Bound<typeof name.reclaimSync>; /** Sets the ENSv1 manager (registry owner) of a name. Resolves once the transaction is submitted. */ readonly setManager: BoundWrite<typeof name.setManager>; /** Sets the ENSv1 manager (registry owner) of a name. Resolves once the receipt is in. */ readonly setManagerSync: Bound<typeof name.setManagerSync>; /** Sets the ENSv1 registry TTL of a name. Resolves once the transaction is submitted. */ readonly setTtl: BoundWrite<typeof name.setTtl>; /** Sets the ENSv1 registry TTL of a name. Resolves once the receipt is in. */ readonly setTtlSync: Bound<typeof name.setTtlSync>; /** Sends a name to another account and resolves once the transaction is submitted. */ readonly transfer: BoundWrite<typeof name.transfer>; /** Sends a name to another account and resolves once the receipt is in. */ readonly transferSync: Bound<typeof name.transferSync>; } |
PermissionActions
permission actions bound to a client.
type PermissionActions| Field | Type | Description |
|---|---|---|
permission | { /** Checks whether an account may perform one operation on an ENS name, and lists exactly what it lacks when it may not. */ readonly check: Bound<typeof permission.check>; /** Reads what an account may do with an ENS name: transfer it, change its resolver, edit records, create subnames and more, across ENSv1 ownership and ENSv2 roles. */ readonly get: Bound<typeof permission.get>; /** Lets another account edit a name's records, or takes that access back. Resolves once the transaction is submitted. */ readonly setRecordAccess: BoundWrite<typeof permission.setRecordAccess>; /** Lets another account edit a name's records, or takes that access back. Resolves once the receipt is in. */ readonly setRecordAccessSync: Bound<typeof permission.setRecordAccessSync>; } |
PlanActions
plan actions bound to a client.
type PlanActions| Field | Type | Description |
|---|---|---|
plan | { /** Reads a saved plan and its progress. */ readonly get: Bound<typeof plan.get>; /** Lists the saved plans of this client's chain and of its `chains`, newest first. */ readonly list: Bound<typeof plan.list>; /** Records a transaction sent outside ensforge as a plan step's submission. */ readonly reconcile: Bound<typeof plan.reconcile>; /** Continues a saved plan after a failure or a reload. Resolves once the remaining transactions are submitted. */ readonly resume: Bound<typeof plan.resume>; /** Continues a saved plan and resolves once every receipt is in. */ readonly resumeSync: Bound<typeof plan.resumeSync>; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the transaction is submitted. */ readonly send: BoundWrite<typeof plan.send>; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the receipt is in. */ readonly sendSync: Bound<typeof plan.sendSync>; } |
PrimaryNameActions
primaryName actions bound to a client.
type PrimaryNameActions| Field | Type | Description |
|---|---|---|
primaryName | { /** Reads the primary name of an address (ENSIP-19 reverse resolution), verified against the name's address record. */ readonly get: Bound<typeof primaryName.get>; /** Sets or clears the primary name (reverse record) of an address. Resolves once the transaction is submitted. */ readonly set: BoundWrite<typeof primaryName.set>; /** Sets or clears the primary name (reverse record) of an address. Resolves once the receipt is in. */ readonly setSync: Bound<typeof primaryName.setSync>; /** Signs a claim to a primary name on one or more L2s, with one signature and no transaction. Anyone can then submit it on each chain with `primaryName.set`, so the account needs no gas or wallet connection there. */ readonly signClaim: Bound<typeof primaryName.signClaim>; } |
RecordActions
record actions bound to a client.
type RecordActions| Field | Type | Description |
|---|---|---|
record | { /** Reads any mix of a name's records in one request: texts, addresses, content hash, ABI, public key, name record, interface implementers and data records. */ readonly get: record.get.Bound; /** Reads one address record of an ENS name, for Ethereum by default or any coin (ENSIP-9, ENSIP-11). */ readonly getAddress: record.getAddress.Bound; /** Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12). */ readonly getAvatar: Bound<typeof record.getAvatar>; /** Reads the content hash of an ENS name (ENSIP-7), decoded into its protocol, value and URI. */ readonly getContentHash: Bound<typeof record.getContentHash>; /** Reads one text record of an ENS name, such as `url`, `avatar` or `com.twitter`. */ readonly getText: Bound<typeof record.getText>; /** Writes records of an ENS name and resolves once the transaction is submitted. */ readonly set: BoundWrite<typeof record.set>; /** Writes records of an ENS name and resolves once the receipt is in. */ readonly setSync: Bound<typeof record.setSync>; } |
RegistrationActions
registration actions bound to a client.
type RegistrationActions| Field | Type | Description |
|---|---|---|
registration | { /** Commits to registering `.eth` names, the first half of a registration. Resolves once the transaction is submitted. */ readonly commit: BoundWrite<typeof registration.commit>; /** Commits to registering `.eth` names, the first half of a registration. Resolves once the receipt is in. */ readonly commitSync: Bound<typeof registration.commitSync>; /** Reads where a registration commitment is in its window. */ readonly getCommitmentStatus: Bound<typeof registration.getCommitmentStatus>; /** Reads the `.eth` registration settings: contracts, commitment window, minimum duration, grace period and accepted payment tokens. */ readonly getParameters: Bound<typeof registration.getParameters>; /** Quotes the price of registering a `.eth` name, in an ERC-20 payment token. */ readonly getPrice: Bound<typeof registration.getPrice>; /** Quotes renewing one or more `.eth` names, in an ERC-20 payment token. */ readonly getRenewalPrice: Bound<typeof registration.getRenewalPrice>; /** Checks whether a `.eth` name can be registered now. */ readonly isAvailable: Bound<typeof registration.isAvailable>; /** Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the transaction is submitted. */ readonly register: BoundWrite<typeof registration.register>; /** Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the receipt is in. */ readonly registerSync: Bound<typeof registration.registerSync>; /** Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. Resolves once the transaction is submitted. */ readonly renew: BoundWrite<typeof registration.renew>; /** Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. Resolves once the receipt is in. */ readonly renewSync: Bound<typeof registration.renewSync>; } |
RegistryActions
registry actions bound to a client.
type RegistryActions| Field | Type | Description |
|---|---|---|
registry | { /** Sets or removes the subregistry of an ENSv2 name. Resolves once the transaction is submitted. */ readonly attach: BoundWrite<typeof registry.attach>; /** Sets or removes the subregistry of an ENSv2 name. Resolves once the receipt is in. */ readonly attachSync: Bound<typeof registry.attachSync>; /** Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Resolves once the transaction is submitted. */ readonly deploy: BoundWrite<typeof registry.deploy>; /** Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Resolves once the receipt is in. */ readonly deploySync: Bound<typeof registry.deploySync>; /** Reads an ENSv2 registry: its kind, implementation, parent, canonical name, URI, whether it is emancipated, and whether it can be upgraded. */ readonly get: Bound<typeof registry.get>; /** Sets the metadata URI of an ENSv2 registry. Resolves once the transaction is submitted. */ readonly setUri: BoundWrite<typeof registry.setUri>; /** Sets the metadata URI of an ENSv2 registry. Resolves once the receipt is in. */ readonly setUriSync: Bound<typeof registry.setUriSync>; /** Upgrades an ENSv2 registry to the deployment's latest implementation. Resolves once the transaction is submitted. */ readonly upgrade: BoundWrite<typeof registry.upgrade>; /** Upgrades an ENSv2 registry to the deployment's latest implementation. Resolves once the receipt is in. */ readonly upgradeSync: Bound<typeof registry.upgradeSync>; } |
ResolverActions
resolver actions bound to a client.
type ResolverActions| Field | Type | Description |
|---|---|---|
resolver | { /** Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Resolves once the transaction is submitted. */ readonly create: BoundWrite<typeof resolver.create>; /** Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Resolves once the receipt is in. */ readonly createSync: Bound<typeof resolver.createSync>; /** Reads the resolver of an ENS name: its address, what kind of resolver it is, who may write to it and which record profiles it supports. */ readonly get: Bound<typeof resolver.get>; /** Reads which record set an ENS name uses on its PermissionedResolver. */ readonly getLink: Bound<typeof resolver.getLink>; /** Links an ENS name to the records of another name on the same PermissionedResolver. Resolves once the transaction is submitted. */ readonly link: BoundWrite<typeof resolver.link>; /** Links an ENS name to the records of another name on the same PermissionedResolver. Resolves once the receipt is in. */ readonly linkSync: Bound<typeof resolver.linkSync>; /** Calls the resolver of an ENS name with raw calldata through the Universal Resolver (ENSIP-10). */ readonly resolve: Bound<typeof resolver.resolve>; /** Points an ENS name at a resolver. Resolves once the transaction is submitted. */ readonly set: BoundWrite<typeof resolver.set>; /** Points an ENS name at a resolver. Resolves once the receipt is in. */ readonly setSync: Bound<typeof resolver.setSync>; /** Upgrades the PermissionedResolver of an ENS name to a newer implementation. Resolves once the transaction is submitted. */ readonly upgrade: BoundWrite<typeof resolver.upgrade>; /** Upgrades the PermissionedResolver of an ENS name to a newer implementation. Resolves once the receipt is in. */ readonly upgradeSync: Bound<typeof resolver.upgradeSync>; } |
RoleActions
role actions bound to a client.
type RoleActions| Field | Type | Description |
|---|---|---|
role | { /** Reads the ENSv2 roles an account holds on a name, or at the root of a registry or resolver. */ readonly get: Bound<typeof role.get>; /** Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted. */ readonly grant: BoundWrite<typeof role.grant>; /** Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in. */ readonly grantSync: Bound<typeof role.grantSync>; /** Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted. */ readonly revoke: BoundWrite<typeof role.revoke>; /** Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in. */ readonly revokeSync: Bound<typeof role.revokeSync>; } |
SubnameActions
subname actions bound to a client.
type SubnameActions| Field | Type | Description |
|---|---|---|
subname | { /** Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the transaction is submitted. */ readonly create: BoundWrite<typeof subname.create>; /** Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the receipt is in. */ readonly createSync: Bound<typeof subname.createSync>; /** Removes a subname. Resolves once the transaction is submitted. */ readonly remove: BoundWrite<typeof subname.remove>; /** Removes a subname. Resolves once the receipt is in. */ readonly removeSync: Bound<typeof subname.removeSync>; /** Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the transaction is submitted. */ readonly update: BoundWrite<typeof subname.update>; /** Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the receipt is in. */ readonly updateSync: Bound<typeof subname.updateSync>; } |
WrapperActions
wrapper actions bound to a client.
type WrapperActions| Field | Type | Description |
|---|---|---|
wrapper | { /** Reads the NameWrapper owner, fuses and expiry of an ENSv1 name. */ readonly getFuses: Bound<typeof wrapper.getFuses>; /** Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Resolves once the transaction is submitted. */ readonly setChildFuses: BoundWrite<typeof wrapper.setChildFuses>; /** Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Resolves once the receipt is in. */ readonly setChildFusesSync: Bound<typeof wrapper.setChildFusesSync>; /** Burns owner-controlled fuses on a wrapped ENSv1 name. Resolves once the transaction is submitted. */ readonly setFuses: BoundWrite<typeof wrapper.setFuses>; /** Burns owner-controlled fuses on a wrapped ENSv1 name. Resolves once the receipt is in. */ readonly setFusesSync: Bound<typeof wrapper.setFusesSync>; /** Unwraps an ENSv1 name from the NameWrapper. Resolves once the transaction is submitted. */ readonly unwrap: BoundWrite<typeof wrapper.unwrap>; /** Unwraps an ENSv1 name from the NameWrapper. Resolves once the receipt is in. */ readonly unwrapSync: Bound<typeof wrapper.unwrapSync>; /** Wraps an ENSv1 name in the NameWrapper. Resolves once the transaction is submitted. */ readonly wrap: BoundWrite<typeof wrapper.wrap>; /** Wraps an ENSv1 name in the NameWrapper. Resolves once the receipt is in. */ readonly wrapSync: Bound<typeof wrapper.wrapSync>; } |
Read options
Read.BlockOptions
Read at one block, by number or by tag, never both.
type BlockOptions = | { /** Block number to read at. */ blockNumber?: bigint | undefined; blockTag?: undefined; } | { blockNumber?: undefined; /** * Block tag to read at. * * @default the client's `config.blockTag` */ blockTag?: BlockTag | undefined; };Read.Options
Options every read action takes.
type Options = { /** Cancels the call; the Promise rejects with `signal.reason`. */ signal?: AbortSignal | undefined; /** * Throw `NotFoundError` instead of returning `null` for missing data. * * @default false */ strict?: boolean | undefined; /** CCIP-Read gateways for this call, overriding the client's. */ gatewayUrls?: readonly string[] | undefined; } & BlockOptions;| Option | Type | Default | Description |
|---|---|---|---|
signal | AbortSignal | Cancels the call; the Promise rejects with signal.reason. | |
strict | boolean | false | Throw NotFoundError instead of returning null for missing data. |
gatewayUrls | readonly string[] | CCIP-Read gateways for this call, overriding the client's. | |
blockNumber | bigint | Block number to read at. | |
blockTag | undefined |
Write options
Write.Method
A write's .prepare, .simulate or .estimateGas: options plus account and via.
type Method<options, value> = (( client: Like, options: options & Pick<Options, "account" | "via">, ) => Promise<value>) & { /** Path of the method, e.g. `record.set.prepare`. */ readonly path: string; };| Field | Type | Description |
|---|---|---|
path | string | Path of the method, e.g. record.set.prepare. |
Write.Mode
How a plan's calls are sent: batch uses one EIP-5792 wallet call, sequential sends one
transaction per call, each once the previous one is mined and with a fifth more gas than
estimated, auto batches when the wallet supports atomic batches.
type Mode = "auto" | "batch" | "sequential";Write.Options
Options every write action takes.
type Options| Option | Type | Default | Description |
|---|---|---|---|
account | Account | Address | the client's account | Signer for this write. |
simulate | boolean | the client's config.simulate | Simulate every call before the wallet prompt, so reverts become typed errors first. |
signal | AbortSignal | Cancels before the next wallet prompt; already submitted transactions are not undone. | |
mode | Mode | "auto" | How calls are sent. |
maxBundleCalls | number | 10 | Most calls per wallet bundle. Consecutive steps share a bundle when the wallet supports atomic batches, up to this many calls and never across a chain-time wait. |
onStep | ((event: Plan.Event) => void) | Called as each step waits, is submitted, confirmed or fails. | |
via | Via | Send the write another way than the signer's own transactions, e.g. through a smart account (hca() from @ensforge/hca). Also applies to .prepare, .simulate and .estimateGas. | |
paymaster | { readonly url: string; readonly context?: Readonly<Record<string, unknown>> } | EIP-5792 paymaster service for wallets that support it (paymasterService capability), so the wallet's calls are sponsored. Sends through wallet_sendCalls even for one call. |
Write.Via.Context
What a route knows about the write it carries.
type Context| Field | Type | Description |
|---|---|---|
client | Client<object> | The ensforge client the write runs on (deployment, reads). |
chainId | number | |
account | Address | Signer of the write. |
publicClient | ViemClient | |
walletClient | ViemWalletClient | The signer's wallet, when one is configured. |
Write.Via.Status
Where a sent step is: still pending, mined (with its transactions), or failed.
type Status = | { readonly status: "pending" } | { readonly status: "success"; readonly hashes: readonly Hex[] } | { readonly status: "failed"; readonly reason: string; readonly hashes?: readonly Hex[] };Write results
Write.Result
Returned by every write: resolves once every call is submitted.
type Result| 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. |
Sync options
Write.SyncOptions
Options of a write's …Sync form, which waits for receipts.
type SyncOptions = Options & { /** * Confirmations to wait for per transaction. * * @default 1 */ confirmations?: number | undefined; /** Milliseconds to wait for each receipt before failing with `RECEIPT_TIMEOUT`. */ timeout?: number | undefined; };| Option | Type | Default | Description |
|---|---|---|---|
account | Account | Address | the client's account | Signer for this write. |
simulate | boolean | the client's config.simulate | Simulate every call before the wallet prompt, so reverts become typed errors first. |
signal | AbortSignal | Cancels before the next wallet prompt; already submitted transactions are not undone. | |
mode | Mode | "auto" | How calls are sent. |
maxBundleCalls | number | 10 | Most calls per wallet bundle. Consecutive steps share a bundle when the wallet supports atomic batches, up to this many calls and never across a chain-time wait. |
onStep | ((event: Plan.Event) => void) | Called as each step waits, is submitted, confirmed or fails. | |
via | Via | Send the write another way than the signer's own transactions, e.g. through a smart account (hca() from @ensforge/hca). Also applies to .prepare, .simulate and .estimateGas. | |
paymaster | { readonly url: string; readonly context?: Readonly<Record<string, unknown>> } | EIP-5792 paymaster service for wallets that support it (paymasterService capability), so the wallet's calls are sponsored. Sends through wallet_sendCalls even for one call. | |
confirmations | number | 1 | Confirmations to wait for per transaction. |
timeout | number | Milliseconds to wait for each receipt before failing with RECEIPT_TIMEOUT. |
Write.SyncResult
Returned by every …Sync write: resolves once every receipt is in.
type SyncResult = Result & { /** Receipt of the last transaction. */ readonly receipt: TransactionReceipt; readonly receipts: readonly TransactionReceipt[]; };| 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. |
receipt | TransactionReceipt | Receipt of the last transaction. |
receipts | readonly TransactionReceipt[] |
Requests
Request
A deferred read built with action.request(options), run later by Actions.batch.
Plain data; the type parameters only carry the result types.
interface Request<value = unknown, error = unknown>| Field | Type | Description |
|---|---|---|
path | string | Action path, e.g. record.getText. |
options | unknown |
Plans
Plan
A write, fully planned but not sent: the calls to make, in which order, and what they need. Plans are plain data, so they can be inspected, serialized, merged or handed to viem.
interface Planconst plan = await ens.record.set.prepare({ name: "alice.eth", texts: { url: "https://alice.dev" } })
plan.calls // send with ensforge, or with viem's sendCallsPlan.Call
One contract call.
type Call| Field | Type | Description |
|---|---|---|
to | Address | |
data | Hex | |
value | bigint |
Plan.Deployment
A contract the plan deploys. The address is known before sending (CREATE2).
type Deployment| Field | Type | Description |
|---|---|---|
contract | "resolver" | "registry" | |
address | Address |
Plan.Estimate
Gas and ETH a plan needs.
type Estimate| Field | Type | Description |
|---|---|---|
plan | Plan | |
gas | bigint | Total gas limit across all calls: each call's estimate and the fifth more it is sent with. |
value | bigint | Total ETH sent across all calls. |
Plan.Event
Progress of a plan being sent: waiting for chain time before a step, submitted once its
transactions are sent, confirmed once their receipts are in, failed with the error.
type Event| Field | Type | Description |
|---|---|---|
step | Step | |
status | "waiting" | "submitted" | "confirmed" | "failed" | |
hashes (optional) | readonly Hex[] | Transactions of the step, once submitted. |
bundleId (optional) | string | EIP-5792 bundle the step was sent in. |
reference (optional) | string | Reference of a step sent through a route (via), e.g. a UserOperation hash. |
error (optional) | AnyError |
Plan.Fee
A fee a route charges, in a token or in native currency.
type Fee| Field | Type | Description |
|---|---|---|
kind | "gas" | "execution" | "bridge" | |
token | Address | "native" | Token address, or native. |
amount | bigint | Expected amount, in the token's smallest unit. |
maximum | bigint | Most the route may charge. |
sponsored | boolean | Paid by the route's sponsor instead of the account. |
Plan.Record
A saved plan and its progress, for resuming after a failure or a reload.
type Record| Field | Type | Description |
|---|---|---|
plan | Plan | |
status | "pending" | "completed" | "failed" | pending while steps remain, completed once every step is submitted. |
submitted | Readonly<globalThis.Record<string, readonly Hex[]>> | Transaction hashes per submitted step id. |
bundles | Readonly<globalThis.Record<string, string>> | EIP-5792 bundle id per step sent in a bundle. |
references (optional) | Readonly<globalThis.Record<string, string>> | Route references per step sent through via (e.g. UserOperation hashes). |
error (optional) | string | Message of the last failure. |
updatedAt | number | Unix time in milliseconds. |
Plan.Requirement
Something the account must have before the plan can succeed.
type Requirement = | { readonly kind: "balance"; readonly amount: bigint; readonly token?: Address | undefined } | { readonly kind: "approval"; readonly token: Address; readonly spender: Address; readonly amount: bigint; };Plan.Simulation
Result of simulating every call.
type Simulation| Field | Type | Description |
|---|---|---|
ok | boolean | |
plan | Plan | |
steps | readonly { readonly id: string; readonly ok: boolean; readonly error?: AnyError | undefined; }[] |
Plan.Step
A group of calls sent together, optionally after a wait.
type Step| Field | Type | Description |
|---|---|---|
id | string | |
description | string | Short description for progress UIs, e.g. "Set records". |
calls | readonly Call[] | |
waitFor (optional) | { readonly seconds: bigint } | Chain time to wait after the previous step is confirmed before sending this one, e.g. the registration commitment age. |
from (optional) | "signer" | signer: the signer must send it itself, even through a route (e.g. a token approval). |
Plan.Storage
Where saved plans live.
type Storage| Field | Type | Description |
|---|---|---|
get | (id: string) => Promise<Record | undefined> | |
set | (record: Record) => Promise<void> | |
delete | (id: string) => Promise<void> | |
list | () => Promise<readonly Record[]> |
Plan.Warning
A non-blocking note about the plan.
type Warning| Field | Type | Description |
|---|---|---|
code | string | |
message | string |
PlanActions
plan actions bound to a client.
type PlanActions| Field | Type | Description |
|---|---|---|
plan | { /** Reads a saved plan and its progress. */ readonly get: Bound<typeof plan.get>; /** Lists the saved plans of this client's chain and of its `chains`, newest first. */ readonly list: Bound<typeof plan.list>; /** Records a transaction sent outside ensforge as a plan step's submission. */ readonly reconcile: Bound<typeof plan.reconcile>; /** Continues a saved plan after a failure or a reload. Resolves once the remaining transactions are submitted. */ readonly resume: Bound<typeof plan.resume>; /** Continues a saved plan and resolves once every receipt is in. */ readonly resumeSync: Bound<typeof plan.resumeSync>; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the transaction is submitted. */ readonly send: BoundWrite<typeof plan.send>; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the receipt is in. */ readonly sendSync: Bound<typeof plan.sendSync>; } |
Was this page helpful?