search

ensdomains / ens-contracts

The core contracts of the ENS protocol
https://ens.domains/
MIT License
565 stars 384 forks source link
ethereum solidity

readme

ENS

Build Status

For documentation of the ENS system, see docs.ens.domains.

npm package

This repo doubles as an npm package with the compiled JSON contracts

import {
  BaseRegistrar,
  BaseRegistrarImplementation,
  BulkRenewal,
  ENS,
  ENSRegistry,
  ENSRegistryWithFallback,
  ETHRegistrarController,
  FIFSRegistrar,
  LinearPremiumPriceOracle,
  PriceOracle,
  PublicResolver,
  Resolver,
  ReverseRegistrar,
  StablePriceOracle,
  TestRegistrar,
} from '@ensdomains/ens-contracts'

Importing from solidity

// Registry
import '@ensdomains/ens-contracts/contracts/registry/ENS.sol';
import '@ensdomains/ens-contracts/contracts/registry/ENSRegistry.sol';
import '@ensdomains/ens-contracts/contracts/registry/ENSRegistryWithFallback.sol';
import '@ensdomains/ens-contracts/contracts/registry/ReverseRegistrar.sol';
import '@ensdomains/ens-contracts/contracts/registry/TestRegistrar.sol';
// EthRegistrar
import '@ensdomains/ens-contracts/contracts/ethregistrar/BaseRegistrar.sol';
import '@ensdomains/ens-contracts/contracts/ethregistrar/BaseRegistrarImplementation.sol';
import '@ensdomains/ens-contracts/contracts/ethregistrar/BulkRenewal.sol';
import '@ensdomains/ens-contracts/contracts/ethregistrar/ETHRegistrarController.sol';
import '@ensdomains/ens-contracts/contracts/ethregistrar/LinearPremiumPriceOracle.sol';
import '@ensdomains/ens-contracts/contracts/ethregistrar/PriceOracle.sol';
import '@ensdomains/ens-contracts/contracts/ethregistrar/StablePriceOracle.sol';
// Resolvers
import '@ensdomains/ens-contracts/contracts/resolvers/PublicResolver.sol';
import '@ensdomains/ens-contracts/contracts/resolvers/Resolver.sol';

Accessing to binary file.

If your environment does not have compiler, you can access to the raw hardhat artifacts files at node_modules/@ensdomains/ens-contracts/artifacts/contracts/${modName}/${contractName}.sol/${contractName}.json

Contracts

Registry

The ENS registry is the core contract that lies at the heart of ENS resolution. All ENS lookups start by querying the registry. The registry maintains a list of domains, recording the owner, resolver, and TTL for each, and allows the owner of a domain to make changes to that data. It also includes some generic registrars.

ENS.sol

Interface of the ENS Registry.

ENSRegistry

Implementation of the ENS Registry, the central contract used to look up resolvers and owners for domains.

ENSRegistryWithFallback

The new implementation of the ENS Registry after the 2020 ENS Registry Migration.

FIFSRegistrar

Implementation of a simple first-in-first-served registrar, which issues (sub-)domains to the first account to request them.

ReverseRegistrar

Implementation of the reverse registrar responsible for managing reverse resolution via the .addr.reverse special-purpose TLD.

TestRegistrar

Implementation of the .test registrar facilitates easy testing of ENS on the Ethereum test networks. Currently deployed on Ropsten network, it provides functionality to instantly claim a domain for test purposes, which expires 28 days after it was claimed.

EthRegistrar

Implements an ENS registrar intended for the .eth TLD.

These contracts were audited by ConsenSys Diligence; the audit report is available here.

BaseRegistrar

BaseRegistrar is the contract that owns the TLD in the ENS registry. This contract implements a minimal set of functionality:

This separation of concerns provides name owners strong guarantees over continued ownership of their existing names, while still permitting innovation and change in the way names are registered and renewed via the controller mechanism.

EthRegistrarController

EthRegistrarController is the first implementation of a registration controller for the new registrar. This contract implements the following functionality:

The commit/reveal process is used to avoid frontrunning, and operates as follows:

  1. A user commits to a hash, the preimage of which contains the name to be registered and a secret value.
  2. After a minimum delay period and before the commitment expires, the user calls the register function with the name to register and the secret value from the commitment. If a valid commitment is found and the other preconditions are met, the name is registered.

The minimum delay and expiry for commitments exist to prevent miners or other users from effectively frontrunning registrations.

SimplePriceOracle

SimplePriceOracle is a trivial implementation of the pricing oracle for the EthRegistrarController that always returns a fixed price per domain per year, determined by the contract owner.

StablePriceOracle

StablePriceOracle is a price oracle implementation that allows the contract owner to specify pricing based on the length of a name, and uses a fiat currency oracle to set a fixed price in fiat per name.

Resolvers

Resolver implements a general-purpose ENS resolver that is suitable for most standard ENS use cases. The public resolver permits updates to ENS records by the owner of the corresponding name.

PublicResolver includes the following profiles that implements different EIPs.

Developer guide

Prettier pre-commit hook

This repo runs a husky precommit to prettify all contract files to keep them consistent. Add new folder/files to prettier format script in package.json. If you need to add other tasks to the pre-commit script, add them to .husky/pre-commit

How to setup

git clone https://github.com/ensdomains/ens-contracts
cd ens-contracts
bun i

How to run tests

bun run test

How to publish

bun run pub

Deployment

NODE_OPTIONS='--experimental-loader ts-node/esm/transpile-only' bun run hardhat --network <network_name> deploy

Full list of available networks for deployment is here.

Release flow

  1. Create a feature branch from staging branch
  2. Make code updates
  3. Ensure you are synced up with staging
  4. Code should now be in a state where you think it can be deployed to production
  5. Create a "Release Candidate" release on GitHub. This will be of the form v1.2.3-RC0. This tagged commit is now subject to our bug bounty.
  6. Have the tagged commit audited if necessary
  7. If changes are required, make the changes and then once ready for review create another GitHub release with an incremented RC value v1.2.3-RC0 -> v.1.2.3-RC1. Repeat as necessary.
  8. Deploy to testnet. Open a pull request to merge the deploy artifacts into the feature branch. Create GitHub release of the form v1.2.3-testnet from the commit that has the new deployment artifacts.
  9. Get someone to review and approve the deployment and then merge. You now MUST merge this branch into staging branch.
  10. If any further changes are needed, you can either make them on the existing feature branch that is in sync or create a new branch, and follow steps 1 -> 9. Repeat as necessary.
  11. Make a deployment to ethereum mainnet from staging. Create a GitHub release of the form v1.2.3 from the commit that has the new deployment artifacts.
  12. Open a PR to merge into main. Have it reviewed and merged.

Cherry-picked release flow

Certain changes can be released in isolation via cherry-picking, although ideally we would always release from staging.

  1. Create a new branch from mainnet.
  2. Cherry-pick from staging into new branch.
  3. Deploy to ethereum mainnet, tag the commit that has deployment artifacts and create a release.
  4. Merge into mainnet.

Emergency release process

  1. Branch from main, make fixes, deploy to testnet (can skip), deploy to mainnet
  2. Merge changes back into main and staging immediately after deploy
  3. Create GitHub releases, if you didn't deploy to testnet in step 1, do it now

Notes