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

Use a DNS name

Import a DNS name such as example.com into ENS with a DNSSEC proof, claim it for an owner, and then manage its records on ENS.

You will import a DNS name you own into ENS, so it can have an owner, a resolver and records like any other name. You prove ownership with a DNSSEC proof of a TXT record in your DNS zone, and ensforge fetches and sends the proof for you.

DNS names are imported into ENSv1. ENSv2 resolves them through the ENSv1 registry, so you do not choose a version.

Prerequisites

  • A DNS name whose zone uses DNSSEC.
  • A wallet client. Anyone can send the claim: the name goes to the address in the TXT record. See Create a client.
  • A chain with a DNSSEC gateway in its deployment, or your own gatewayUrls. The mainnet and Sepolia deployments list their gateways on-chain. Without either, the DNS actions fail with UNSUPPORTED_ON_DEPLOYMENT.

DNS claims fail since the root key rollover

Since the DNSSEC root KSK rollover in October 2026, the on-chain DNSSEC oracle on mainnet and Sepolia cannot verify any proof: it lacks the new root key. dns.getStatus reports proof-invalid and dns.claim fails with DNSSEC_PROOF_FAILED until ENS adds the trust anchor. ensforge has no client-side workaround. See DNSSEC_PROOF_FAILED.

1. Check what the name needs

dns.getStatus compares the ENSv1 registry owner with the address in the _ens TXT record, and verifies the record's proof against the on-chain DNSSEC oracle.

Example (Checking a DNS Name)

dns-status.ts
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
}).extend(ensActions());

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

status.action is the next step:

actionWhat to do
set-txt-recordAdd the TXT record in step 2.
claimImport the name (step 3), or re-import it to move it to the address in its TXT record.
proof-invalidThe TXT record exists, but its proof does not verify on-chain. Do not send a claim yet.
noneThe name is imported and owned by the address in its TXT record.

status also has imported, owner (the ENSv1 registry owner), dnsOwner (the address in the TXT record) and proofValid.

2. Add the TXT record

In your DNS zone, add a TXT record at _ens.<name> with the value a=<address>. The address becomes the owner. For example.com it is the record _ens.example.com.

DNS record
_ens.example.com.  TXT  "a=0xB0b0000000000000000000000000000000000000"

3. Claim the name

dns.claim fetches the proof from the deployment's DNSSEC gateway and sends it. dns.claimSync also waits for the receipt.

Example (Claiming a DNS Name)

dns-claim.ts
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const transport = http(process.env.SEPOLIA_RPC_URL);

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport }),
  walletClient: createWalletClient({ account, chain: sepolia, transport }),
}).extend(ensActions());

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

if (status.action === "claim") {
  await ens.dns.claimSync({ name: "example.com" });
}
OptionTypeDescription
namestringThe DNS name. Normalised automatically.
proofProofA proof from dns.getProof, instead of fetching one.
resolverstringA resolver to set while claiming. Only the DNS owner may send a claim with a resolver.
gatewayUrlsstring[]DNSSEC gateways to fetch the proof from, instead of the deployment's.

dns.getProof fetches a proof without sending anything. It does not verify the proof: dns.getStatus does.

dns.claim cannot set an address record while claiming. Set records afterwards with record.set.

Use a gasless DNS name

A gasless DNS name resolves without being imported, as an off-chain name. Its owner adds a TXT record ENS1 <resolver> [context] on the name itself. dns.getOffchainResolver reads it and returns { resolver, context }, or null when there is none.

Example (Reading a Gasless DNS Setup)

dns-offchain.ts
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
}).extend(ensActions());

const offchain = await ens.dns.getOffchainResolver({ name: "example.com" });

The record is read through the DNSSEC gateway without on-chain verification. See Look up off-chain names.

Host DNS records in ENS

dns.setRecords stores resource records, or a zonehash, on an ENS name's public resolver, for DNS servers that read them from ENS. Records are in DNS wire format. zonehash: null clears the zonehash. Only the ENS public resolvers store DNS records.

Check the result

Call dns.getStatus again. action is none and imported is true when the claim worked. Then read the name with name.get.

Troubleshooting

DNS_RECORD_MISSING

The _ens TXT record is missing, or its value does not parse as a=<address>. Add it and wait for DNS to update. See DNS_RECORD_MISSING.

PROOF_STALE

The proof is older than the one already on-chain. Fetch a fresh proof and retry. See PROOF_STALE.

DNSSEC_PROOF_FAILED

The proof could not be built or verified. Check that DNSSEC is enabled for the domain, and see the warning at the top of this page. See DNSSEC_PROOF_FAILED.

TLD_NOT_PUBLIC

The name's top-level domain is not a public suffix, so it cannot be imported. See TLD_NOT_PUBLIC.

GATEWAY_REQUEST_FAILED or GATEWAY_RESPONSE_INVALID

The DNSSEC gateway failed or answered with data that does not parse. Retry, or pass another gatewayUrls. See GATEWAY_REQUEST_FAILED and GATEWAY_RESPONSE_INVALID.

NOT_OWNER

You passed resolver, but the sender is not the DNS owner. Claim without resolver, or send from the address in the TXT record. See NOT_OWNER.

Was this page helpful?