ENS Contracts: The On-Chain Core of Ethereum Name Service

The Problem: Name Resolution Needs a Trusted Root

ENS solves the problem of human-readable addresses on Ethereum. Without it, users must handle long hex strings for wallets and contracts. The ENS registry is the single source of truth: it maps a domain name to an owner, a resolver, and a TTL. That registry is what this repository implements. The target audience is not end users but developers who build on ENS: wallet makers, dapp developers, registrar operators, and anyone who needs to integrate name resolution into a smart contract. The contracts are the foundation, not the user-facing service. The README makes this clear by listing the package as a source of compiled JSON contracts and Solidity imports for direct use in other projects.

Registry Architecture: One Contract to Rule Them All

At the core sits the ENSRegistry, the implementation of the ENS interface. It keeps a mapping of each domain to its owner, resolver, and TTL. All lookups start here. The registry allows the owner to change that data. There is also ENSRegistryWithFallback, which is the new implementation after the 2020 migration. The difference is that the fallback version can delegate to the old registry during the transition, so existing names keep working. That design choice shows a careful migration path: you do not break old records overnight. The FIFSRegistrar issues subdomains on a first-come-first-served basis, which is simple but vulnerable to squatting. The ReverseRegistrar handles .addr.reverse, enabling reverse resolution from an address back to a name. The TestRegistrar for .test domains is deployed on Ropsten and lets anyone claim a domain instantly, but it expires after 28 days. That is a practical way to test without buying a real name.

The .eth Registrar: Controllers and Commit-Reveal

The EthRegistrar is a set of contracts that manage the .eth TLD. The BaseRegistrar owns the TLD in the registry and has a minimal role: it can add or remove controllers, and controllers can register and renew names, but they cannot change ownership or reduce expiration. Name owners can transfer ownership and reclaim names in the registry. This separation gives name owners strong guarantees while allowing the registration logic to evolve. The EthRegistrarController is the first such controller. It uses a price oracle to set costs and a commit-reveal process to prevent frontrunning. The README explains the two-step flow: first, a user commits to a hash of the name and a secret; after a minimum delay, they call register with the secret. This prevents miners from stealing a name before the transaction lands. It is a standard pattern, but it adds friction: users must wait for the delay, which is a trade-off between security and UX.

Price Oracles: Fixed and Stable

Pricing is handled by two oracle contracts. SimplePriceOracle always returns a fixed price per year, set by the owner. That is trivial and useful for testing or private networks. StablePriceOracle is more interesting: it lets the owner set prices based on name length, and it uses a fiat currency oracle to convert a fixed fiat price into ETH. That means the cost of a .eth name can stay stable in dollar terms even as ETH price fluctuates. The README does not specify how the fiat oracle is implemented or which one to use, so you must check the contract source for details. The trade-off is that the oracle is a point of trust: if it is compromised, registration prices can change. The owner can withdraw collected funds, so there is a central authority. This is not a fully decentralized pricing mechanism; it is a pragmatic one.

Resolvers: Multiple EIPs, One Contract

The PublicResolver implements several EIPs in one contract. It supports ABI (EIP-205), address (EIP-137 and EIP-2304 for multicoin), content hash (EIP-1577), arbitrary data (ENSIP-24), interface detection (EIP-165), reverse resolution (EIP-181), public keys (EIP-619), and text records (EIP-634). That is a wide surface. The advantage is that you only need one resolver contract for most use cases. The downside is that the contract becomes large and complex, which increases gas costs for deployments and updates. Each resolver profile is a separate Solidity interface, so you can implement a custom resolver with only the functions you need. But the PublicResolver is the default for many integrations. The README lists these profiles as part of the package, so you can import them directly.

DNSResolver: Experimental and Not Ready for Production

The DNSResolver is marked as experimental. It allows hosting DNS domains on Ethereum, meaning you can store DNS records like A and AAAA in ENS and use them for resolution. The README points to an old ENS doc for details, which is a red flag: the documentation is outdated. The code is in the repository, but the README does not describe its limitations or security considerations. This is a case where the project is honest about the maturity: experimental means you should not use it for critical infrastructure without thorough testing. If you need DNS integration, you would be better off using a traditional DNS provider or a different approach, because this resolver has not been audited to the same standard as the EthRegistrar. The audit report mentioned in the README covers the EthRegistrar, not the DNSResolver.

Getting Started: Imports, Artifacts, and Setup

You can use this package in two ways. First, import the compiled JSON contracts from npm: the README shows importing BaseRegistrar, ENSRegistry, PublicResolver, and others directly. Second, import the Solidity source files into your own contracts, like `import '@ensdomains/ens-contracts/contracts/registry/ENS.sol';`. If you do not have a Solidity compiler, you can access the raw Hardhat artifacts at `node_modules/@ensdomains/ens-contracts/artifacts/contracts/${modName}/${contractName}.sol/${contractName}.json`. To set up the repo for development, you clone it and run the setup script, which is truncated in the README, but it likely involves `npm install` and `npx hardhat compile`. The repo uses a pre-commit hook with Prettier to keep contract files consistent, and you can add tasks to `.husky/pre-commit`. The default branch is `staging`, which means the latest code may not be production-ready. The releases are tagged, so you should pin to a specific version like v1.7.0.

Maintenance and Upgrades

The repository is actively maintained, with the last push in March 2026 and a v1.7.0 release on the same day. That suggests a regular release cadence. Upgrading is a matter of updating the npm package or the git submodule, but you must be careful: the registry and registrar contracts are deployed on-chain, and you cannot change them without a migration. The ENSRegistryWithFallback exists to handle such migrations, but any change to the core registry requires a coordinated effort. The README mentions the 2020 migration, so this is a known process. The license is MIT, which is permissive, but it does not grant you any rights to the ENS name or the deployed contracts; you are only using the code. For production, you should verify that the deployed addresses match the package version you use, because a mismatch could cause your integration to interact with the wrong contracts.

Editorial conclusion

Adopt this package if you are building on ENS: dapps resolving names, registrars, or tools that manage .eth domains. You need the compiled artifacts or Solidity imports to integrate. Skip it if you only need off-chain resolution; you can query the deployed registry directly. Before using, verify the exact contract versions deployed on your target network, as the package tracks the staging branch and may not match mainnet addresses. Also check the audit report from ConsenSys Diligence for the EthRegistrar contracts, and note that DNSResolver is experimental and not production-ready.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes