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.getStatus

Reads whether a DNS name is imported into ENS, and what it needs to be. Parameters, return value, errors and examples for dns.getStatus in @ensforge/sdk.

ReadBatchablestable
Since v1.0.0View source

Reads whether a DNS name is imported into ENS, and what it needs to be.

When to use

Use to tell the user which step comes next, before dns.claim.

Details

  • Compares the ENSv1 registry owner with the address in the _ens TXT record, and verifies the record's DNSSEC proof against the on-chain DNSSEC oracle.
  • action is the next step: none, claim, set-txt-record or proof-invalid.
  • Gasless DNS names (ENS1 TXT records) resolve without importing; see dns.getOffchainResolver.

Signature

function getStatus(client: Like, options: getStatus.Options): Promise<getStatus.ReturnType>

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

dns.getStatus.request(options) builds a deferred read for Actions.batch. See Look up many at once.

Parameters

OptionTypeDefaultDescription
name (required)stringDNS name. Normalized automatically.
gatewayUrlsreadonly string[]DNSSEC gateways to use instead of the deployment's.

Also takes the read options.

Returns

Resolves to Status. Import state and the next step.

FieldTypeDescription
namestringNormalized name.
importedbooleanWhether the name is in the ENSv1 registry.
ownerAddress | nullENSv1 registry owner, or null when not imported.
dnsOwnerAddress | nullAddress in the _ens TXT record (a=0x…), or null when there is none.
proofValidbooleanWhether the DNSSEC proof of the TXT record verifies against the on-chain DNSSEC oracle.
importedInceptionnumber | nullInception of the last imported proof, or null when none was imported.
proofInceptionnumberInception of the current DNSSEC proof.
actionImportAction

Errors

ErrorCodesWhen
InvalidInputErrorINVALID_NAMEnames that are not DNS names.
GatewayErrorGATEWAY_REQUEST_FAILED, GATEWAY_RESPONSE_INVALIDthe DNSSEC gateway fails.
UnsupportedErrorUNSUPPORTED_ON_DEPLOYMENTwithout a DNSSEC gateway or gatewayUrls.
NetworkErrorRPC_REQUEST_FAILED, RPC_TIMEOUT, RATE_LIMITEDthe RPC request fails.

It can also fail with the errors every read can (Errors.CommonError: ConfigError, ContractRevertError, InternalError, NetworkError).

See How errors work.

Examples

Checking a DNS name
const status = await ens.dns.getStatus({ name: "example.com" })

Example response

Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does.

await ens.dns.getStatus({ name: "ens.domains" })
{
  "name": "ens.domains",
  "imported": true,
  "owner": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
  "dnsOwner": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
  "proofValid": false,
  "importedInception": null,
  "proofInception": 1794939171,
  "action": "proof-invalid"
}

See also

Was this page helpful?