# ensdomains/ens-contracts architecture

> Architecture diagram of the GitHub repository ensdomains/ens-contracts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ensdomains/ens-contracts
- Repository: https://github.com/ensdomains/ens-contracts

## Overview

##### Main Components
- Contracts Layer:
- ENS Registry Components: Include ENS.sol (the core interface), ENSRegistry, and ENSRegistryWithFallback, which serve as the backbone of domain resolution.
- Registrar Contracts: Represent the EthRegistrar suite (BaseRegistrar, ETHRegistrarController, BulkRenewal, FIFSRegistrar, TestRegistrar) that manage domain registration and renewals for .eth and test domains.
- Resolver Components: Capture both the PublicResolver and underlying general Resolver contracts (with components for ABI, address, content hash, public keys, text records, etc.). Also include specialized resolvers like ExtendedDNSResolver and legacy resolvers.
- Additional Contracts: Incorporate DNS-related sub-components such as DNSSEC Oracle contracts (algorithms, digests), DNS registrar components, reverse registrar and the name wrapper module.

- Deployment and Artifacts:
- “deployments” directory that stores JSON artifacts for various networks (mainnet, goerli, ropsten, sepolia, holesky). These represent the on-chain deployment artifacts for each network, showing that the system is designed for a multi-network environment.

- Build and Development Tools:
- Additional directories such as “scripts” and “tasks” which handle various ancillary functions (e.g., deployment orchestration, fixing ESM issues, running pre-commit hooks).

- Integration Points:
- Npm package usage (how developers import these contracts in their applications) and the dual nature of the repo as both source code and a compiled artifact provider.
- How external services (like price oracles or DNS off-chain services for DNSSEC) interface with the deployed contracts.

##### Relationships and Interactions
- Domain/Name ownership and resolution flows: The ENS Registry points to resolvers (for translating names to addresses) and to registrar contracts (for managing domain registrations).
- Registrar contracts (both EthRegistrar and FIFSRegistrar) interact with the registry to update domain ownership and expiration data.
- ReverseRegistrar connects back to the registry by handling reverse resolution (mapping addresses to names).
- That deployment scripts (in “deploy”) use tools like Hardhat (with ts-node for ESM support) to connect with the blockchain networks (as depicted in the “deployments” folder) for deploying the various contracts.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Emphasize that each contract set (registry, registrar, resolver) has its own dedicated folder and specific functionality.
- Modularity: The project’s structure (with separate folders for contracts, deploy scripts, tasks, and tests) indicates that individual components are designed to be developed, audited, and deployed independently.
- Extensibility: Highlight the layering between core contracts and additional services (e.g., the DNSSEC or name wrapper contracts) to illustrate how the ENS system can be extended or integrated with other services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Contracts Layer
    subgraph "Contracts Layer"
        subgraph "ENS Registry"
            ENSRegistry["ENSRegistry & Fallback"]:::contract
        end
        subgraph "Registrar Contracts (EthRegistrar suite)"
            EthRegistrar["EthRegistrar Suite"]:::contract
        end
        subgraph "Resolver Components"
            Resolver["Public & General Resolver"]:::contract
        end
        subgraph "Additional Contracts"
            DNSRegistrar["DNSRegistrar"]:::contract
            DNSSECOracle["DNSSEC Oracle"]:::contract
            ReverseRegistrar["Reverse Registrar"]:::contract
            NameWrapper["Name Wrapper"]:::contract
            UniversalResolver["Universal Resolver"]:::contract
        end
    end

    %% Deployment & Operations Layer
    subgraph "Deployment & Operations"
        DeployScripts["Deploy Scripts"]:::deployment
        DeploymentArtifacts["Deployment Artifacts"]:::deployment
    end

    %% Build & Development Tools Layer
    subgraph "Build & Development Tools"
        Hardhat["Hardhat Config (hardhat.config.cts)"]:::devtools
        PackageJson["Package.json"]:::devtools
        EnvFile[".env.org"]:::devtools
        Scripts["Scripts"]:::devtools
        Tasks["Tasks"]:::devtools
        Test["Test Suite"]:::devtools
    end

    %% Integration Points
    subgraph "Integration Points"
        NpmUsage["npm Package Integration"]:::external
        ExternalServices["External Services (Oracles/DNS)"]:::external
        dApp["DApp/User Interfaces"]:::external
    end

    %% Relationships
    dApp -->|"calls"| NpmUsage
    NpmUsage -->|"interacts"| ENSRegistry
    NpmUsage -->|"interacts"| EthRegistrar
    NpmUsage -->|"interacts"| Resolver

    EthRegistrar -->|"updates"| ENSRegistry
    ENSRegistry -->|"resolves-to"| Resolver
    ReverseRegistrar -->|"reverse-maps"| ENSRegistry
    DNSRegistrar -->|"DNS-updates"| ENSRegistry

    DeployScripts ---|"deploys"| ENSRegistry
    DeployScripts ---|"deploys"| EthRegistrar
    DeployScripts ---|"deploys"| Resolver
    DeployScripts ---|"deploys"| DNSRegistrar
    DeployScripts ---|"deploys"| DNSSECOracle
    DeployScripts ---|"deploys"| ReverseRegistrar
    DeployScripts ---|"deploys"| NameWrapper
    DeployScripts ---|"deploys"| UniversalResolver

    DeploymentArtifacts ---|"stores"| ENSRegistry
    DeploymentArtifacts ---|"stores"| EthRegistrar
    DeploymentArtifacts ---|"stores"| Resolver
    DeploymentArtifacts ---|"stores"| DNSRegistrar
    DeploymentArtifacts ---|"stores"| DNSSECOracle
    DeploymentArtifacts ---|"stores"| ReverseRegistrar
    DeploymentArtifacts ---|"stores"| NameWrapper
    DeploymentArtifacts ---|"stores"| UniversalResolver

    Hardhat -->|"configures"| DeployScripts
    PackageJson -->|"manages"| DeployScripts
    EnvFile -->|"configures"| DeployScripts
    Scripts -->|"orchestrates"| DeployScripts
    Tasks -->|"runs"| Test
    Test -->|"validates"| ENSRegistry
    Test -->|"validates"| EthRegistrar
    Test -->|"validates"| Resolver

    ExternalServices -->|"feeds"| Resolver
    ExternalServices -->|"feeds"| ENSRegistry

    %% Click Events
    click ENSRegistry "https://github.com/ensdomains/ens-contracts/tree/staging/contracts/registry"
    click EthRegistrar "https://github.com/ensdomains/ens-contracts/tree/staging/contracts/ethregistrar"
    click Resolver "https://github.com/ensdomains/ens-contracts/tree/staging/contracts/resolvers"
    click DNSRegistrar "https://github.com/ensdomains/ens-contracts/tree/staging/contracts/dnsregistrar"
    click DNSSECOracle "https://github.com/ensdomains/ens-contracts/tree/staging/contracts/dnssec-oracle"
    click ReverseRegistrar "https://github.com/ensdomains/ens-contracts/tree/staging/contracts/reverseRegistrar"
    click NameWrapper "https://github.com/ensdomains/ens-contracts/tree/staging/contracts/wrapper"
    click UniversalResolver "https://github.com/ensdomains/ens-contracts/tree/staging/contracts/universalResolver"
    click DeployScripts "https://github.com/ensdomains/ens-contracts/tree/staging/deploy"
    click DeploymentArtifacts "https://github.com/ensdomains/ens-contracts/tree/staging/deployments"
    click Hardhat "https://github.com/ensdomains/ens-contracts/blob/staging/hardhat.config.cts"
    click PackageJson "https://github.com/ensdomains/ens-contracts/blob/staging/package.json"
    click EnvFile "https://github.com/ensdomains/ens-contracts/blob/staging/.env.org"
    click Scripts "https://github.com/ensdomains/ens-contracts/tree/staging/scripts"
    click Tasks "https://github.com/ensdomains/ens-contracts/tree/staging/tasks"
    click Test "https://github.com/ensdomains/ens-contracts/tree/staging/test"

    %% Styles
    classDef contract fill:#ffdddd,stroke:#990000,stroke-width:2px;
    classDef deployment fill:#ddeeff,stroke:#000099,stroke-width:2px;
    classDef devtools fill:#ddffdd,stroke:#009900,stroke-width:2px;
    classDef external fill:#fff2cc,stroke:#cc9900,stroke-width:2px;
```
