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

dns.claim

Imports a DNS name into ENS with a DNSSEC proof of its _ens TXT record. Parameters, return value, errors and examples for dns.claim in @ensforge/sdk.

Writestable
Since v1.0.0View source

Imports a DNS name into ENS with a DNSSEC proof of its _ens TXT record. Resolves once the transaction is submitted.

When to use

Use to claim a DNS name after adding the TXT record _ens.<name> = a=<address>. Use claimSync to wait for the receipt.

Details

  • The name goes to the address in the TXT record, whoever sends the claim.
  • The proof comes from the deployment's DNSSEC gateway unless proof is given.
  • With resolver, the claim also sets it; then only the DNS owner may send it. Set records with record.set afterwards.

Gotchas

  • Read dns.getStatus first: a proof that does not verify on-chain fails.

Signature

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

Call it as ens.dns.claim(options) on a client, or Actions.dns.claim(client, options).

Parameters

OptionTypeDefaultDescription
name (required)stringDNS name. Normalized automatically.
proofProofProof from dns.getProof, instead of fetching one.
resolverstringResolver to set while claiming.
gatewayUrlsreadonly string[]DNSSEC gateways to fetch the proof from, instead of the deployment'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_RECORD_VALUEinvalid input.
DnsErrorDNS_RECORD_MISSING, PROOF_STALE, DNSSEC_PROOF_FAILED, TLD_NOT_PUBLICthe name cannot be proven.
GatewayErrorGATEWAY_REQUEST_FAILED, GATEWAY_RESPONSE_INVALIDthe proof cannot be fetched.
UnauthorizedErrorNOT_OWNERsomeone other than the DNS owner claims with a resolver.
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

Claiming a DNS name
const { hash } = await ens.dns.claim({ name: "example.com" })

Plan methods

Each method takes the same options as dns.claim and sends nothing. See Preview before sending.

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

Wait for the receipt with claimSync

Imports a DNS name into ENS with a DNSSEC proof of its _ens TXT record. Resolves once the receipt is in.

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

dns.claimSync takes the same options plus confirmations and timeout.

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

Claiming a DNS name and waiting
const { receipt } = await ens.dns.claimSync({ name: "example.com" })

See also

Was this page helpful?