• Stars
    star
    576
  • Rank 77,502 (Top 2 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 3 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The core contracts of the ENS protocol

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:

  • The owner of the registrar may add and remove controllers.
  • Controllers may register new domains and extend the expiry of (renew) existing domains. They can not change the ownership or reduce the expiration time of existing domains.
  • Name owners may transfer ownership to another address.
  • Name owners may reclaim ownership in the ENS registry if they have lost it.
  • Owners of names in the interim registrar may transfer them to the new registrar, during the 1 year transition period. When they do so, their deposit is returned to them in its entirety.

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 owner of the registrar may set a price oracle contract, which determines the cost of registrations and renewals based on the name and the desired registration or renewal duration.
  • The owner of the registrar may withdraw any collected funds to their account.
  • Users can register new names using a commit/reveal process and by paying the appropriate registration fee.
  • Users can renew a name by paying the appropriate fee. Any user may renew a domain, not just the name's owner.

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.

  • ABIResolver = EIP 205 - ABI support (ABI()).
  • AddrResolver = EIP 137 - Contract address interface. EIP 2304 - Multicoin support (addr()).
  • ContentHashResolver = EIP 1577 - Content hash support (contenthash()).
  • InterfaceResolver = EIP 165 - Interface Detection (supportsInterface()).
  • NameResolver = EIP 181 - Reverse resolution (name()).
  • PubkeyResolver = EIP 619 - SECP256k1 public keys (pubkey()).
  • TextResolver = EIP 634 - Text records (text()).
  • DNSResolver = Experimental support is available for hosting DNS domains on the Ethereum blockchain via ENS. The more detail is on the old ENS doc.

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
yarn

How to run tests

yarn test

How to publish

yarn pub

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. Commit build artifacts to feature branch. You now MUST merge this branch into staging branch.
  9. Create GitHub release of the form v1.2.3-testnet from the commit that has the new deployment artifacts.
  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 Deployment to mainnet from staging. Commit build artifacts. You now MUST merge this branch into main.
  12. Create GitHub release of the form v1.2.3-mainnet from the commit that has the new deployment artifacts.

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

  • staging branch and main branch should start off in sync
  • staging is intended to be a practice main. Only code that is intended to be released to main can be merged to staging. Consequently:
    • Feature branches will be long-lived
    • Feature branches must be kept in sync with staging
    • Audits are conducted on feature branches
  • All code that is on staging and main should be deployed to testnet and mainnet respectively i.e. these branches should not have any undeployed code
  • It is preferable to not edit the same file on different feature branches.
  • Code on staging and main will always be a subset of what is deployed, as smart contracts cannot be undeployed.
  • Release candidates, staging and main branch are subject to our bug bounty
  • Releases follow semantic versioning and should contain a description of changes with developers being the intended audience

More Repositories

1

ens

Implementations for ENS core functionality: The registry, registrars, and public resolvers.
JavaScript
1,159
star
2

ens-app

Legacy ENS manager app
JavaScript
223
star
3

ensjs-v2

Javascript bindings for the Ethereum Name Service
JavaScript
206
star
4

subdomain-registrar

A registrar that sells subdomains to users on behalf of their owners
CSS
185
star
5

governance-contracts

Governance contracts for the ENS DAO
JavaScript
160
star
6

address-encoder

Encodes and decodes address formats for various cryptocurrencies
TypeScript
148
star
7

offchain-resolver

TypeScript
142
star
8

docs

Main documentation site for the ENS protocol
TypeScript
136
star
9

evmgateway

This repository implements a generic CCIP-Read gateway for fetching state proofs of data on other EVM chains. The intended use is for contracts on L1 to be able to fetch and verify data from contracts on L2 in a read context.
TypeScript
132
star
10

ens-app-v3

The official ENS manager app. Register and manage your ENS names here.
TypeScript
126
star
11

ensjs

ENS javascript library for contract interaction
TypeScript
123
star
12

ensdomains-landing

ENS Homepage V2, the main homepage of the ENS protocol.
TypeScript
105
star
13

ethregistrar

Solidity
92
star
14

thorin

A web3 native design system.
TypeScript
81
star
15

ens-metadata-service

TypeScript
71
star
16

resolvers

A collection of resolvers for ENS domains
JavaScript
69
star
17

dnssec-oracle

A DNSSEC oracle for Ethereum
Solidity
57
star
18

react-ens-address

React Component to resolve ENS names or reverse resolve addresses
JavaScript
57
star
19

ui

UI components and reusable functions
JavaScript
55
star
20

l2gateway-demo

A simple demonstration of a proposed L2 gateway specification
JavaScript
52
star
21

name-wrapper

JavaScript
45
star
22

ens-avatar

ENS Avatar resolver library for both nodejs and browser.
TypeScript
40
star
23

solsha1

Pure-solidity implementation of the SHA1 hash function.
Solidity
39
star
24

ens.domains

JavaScript
31
star
25

reverse-records

JavaScript
27
star
26

dnsprovejs

A tool to convince an Ethereum DNSSEC oracle of the contents of DNS records
TypeScript
25
star
27

buffer

A library for working with mutable byte buffers in Solidity.
Solidity
25
star
28

governance-web-react

JavaScript
23
star
29

governance-docs

Governance documentation for the ENS DAO
22
star
30

offchain-resolver-example

CCIP Offchain ENS Resolver example implementation
TypeScript
21
star
31

dnsregistrar

DNS registrar for ENS
Solidity
21
star
32

ens-manager

JavaScript
19
star
33

ethers-ccip-read

Ethers-rs CCIP-Read Middleware
Rust
19
star
34

media-kit

ens media kit resources
CSS
17
star
35

ens-validation

TypeScript
17
star
36

root

New ENS root contract
JavaScript
16
star
37

op-resolver

JavaScript
15
star
38

ens-twitter-api

TypeScript
14
star
39

ens-avatar-worker

Cloudflare worker that facilitates gasless avatar record updates via the ENS manager app
TypeScript
13
star
40

dnssecoraclejs

TypeScript/JavaScript library for generating DNSSEC proofs for the ENS DNSSEC oracle contract
TypeScript
11
star
41

court

Basic smart contracts for the arbitration processes.
Solidity
11
star
42

docs-v2

The Ethereum Name Service (ENS) is a distributed, open, and extensible naming system based on the Ethereum blockchain. This repository contains documentation, examples, and much more.
HTML
11
star
43

blacklist

Blacklisting tools for ENS
Solidity
10
star
44

optimistic-dnssec

Optimistic Implementation of the DNSSEC Registrar
Solidity
10
star
45

ens-archived-contracts

Collection of compiled ENS smart contracts
Solidity
10
star
46

hackathon-registrar

A simple ENS registrar for Hackathons
Solidity
9
star
47

gas-estimate-worker

Cloudflare worker for estimating registration gas costs with tenderly
TypeScript
9
star
48

name-reservations

Repository for 3-6 character name reservations in .eth.
CSS
9
star
49

enschain

Solidity
9
star
50

frontend-template

Starter web app for web3 developers
TypeScript
8
star
51

offchain-gateway-rs

Offchain CCIP Gateway Resolver implementation in Rust
Rust
7
star
52

learn-docs

Documentation for learning about ENS domains
7
star
53

renewal-widget

ENS Renewal widget displays a popup window if there are any expiring ENS names.
JavaScript
7
star
54

arb-resolver

JavaScript
7
star
55

ensips

ENS Improvement Proposals
TypeScript
7
star
56

hack.ens.domains

JavaScript
7
star
57

k-ens

ENS formally verified
6
star
58

auction

An auction contract for a one-off vickery style auction of 3-6 character names
JavaScript
6
star
59

my-ens-app

HTML
6
star
60

ccip-read-dns-gateway

ENS CCIP-Read DNSSEC Gateway
TypeScript
5
star
61

dnssectool

JavaScript
5
star
62

short-name-claims-app

A webapp for submitting claims for ENS short names (3-6 characters)
TypeScript
5
star
63

blog

Official Ethereum Name Service Blog
TypeScript
5
star
64

hack2018

5
star
65

research

ENS relevant research.
5
star
66

ccip-tools

CCIP Multitool for testing your offchain resolver!
TypeScript
5
star
67

ens-support-docs

ENS Support Docs
CSS
4
star
68

ens-reclaim-deposit-subgraph

TypeScript
4
star
69

hackathon-registrar-app

JavaScript
4
star
70

renewal

JavaScript
4
star
71

ens-print

Micro App for printing ENS stickers
JavaScript
4
star
72

ethlink-request

It fetches newly created subdomain and send request to eth.link to add to the DoH proxy
TypeScript
4
star
73

mock

Module for mocking ENS locally
JavaScript
4
star
74

integrations

List of integrations for ENS
TypeScript
4
star
75

reclaim

TypeScript
3
star
76

moonpay-worker

JavaScript
3
star
77

normalise-refund

JavaScript
3
star
78

test-utils

ENS test utilities
JavaScript
3
star
79

tldclaims

JavaScript
3
star
80

verify-ratification

Code to verify the votes ratifying the ENS constitution
JavaScript
3
star
81

usd-oracle

USD oracle research
3
star
82

batch-gateway

3
star
83

short-name-claims-subgraph

A subgraph for indexing ENS .eth short name claims
TypeScript
3
star
84

migration-scripts

Python
3
star
85

ens-faucet-worker

Cloudflare worker to help distribute testnet ETH to ENS manager app users
TypeScript
3
star
86

ens-bigquery-udf

JavaScript
3
star
87

ens-evmgateway

TypeScript
3
star
88

crypto-addr-serialize

Encode/Decode various cryptocurrency addresses
JavaScript
3
star
89

ens-og-image

TypeScript
2
star
90

enscluster

Config files for the ensdomains Kubernetes clusters
Python
2
star
91

dnssec-oracle-anchors

JavaScript
2
star
92

dao-pm

Project management repository for the ENS DAO
2
star
93

context-resolver

TypeScript
2
star
94

constitution-book-claim

ENS DAO constitution book claim site
TypeScript
2
star
95

ens-avatar-fallback

JavaScript
2
star
96

arbitrum-resolver

JavaScript
1
star
97

pm

an place to hold ENS project issues which cannot be assigned to any existing repos
1
star
98

ens-cfw

TypeScript
1
star
99

rasterize-gcp

ENS NFT Rasterization Service
JavaScript
1
star
100

punycode

Solidity
1
star