# openzeppelin/openzeppelin-contracts architecture

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

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

## Overview

OpenZeppelin Contracts is a Solidity library for secure smart-contract development; its README highlights token standards, access control, and reusable utilities. The principal user workflow is to import a library contract into an application, then compile and use that application. The provided tree and source excerpts mainly expose supporting Hardhat integrations rather than the Solidity library itself, so this map focuses on those visible integrations. Edges are limited to relationships shown in excerpts, the source index, or README; the library’s Solidity modules are not represented because their paths are absent.

Main entry points: [`hardhat.config.ts`](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat.config.ts) (Hardhat Config), [`hardhat/hardhat-oz-contracts-helpers/hook-handlers/network.ts`](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/hook-handlers/network.ts) (Connection Helpers), [`hardhat/hardhat-exposed/tasks/generate-exposed-contracts.ts`](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-exposed/tasks/generate-exposed-contracts.ts) (Generate Exposed), [`hardhat/hardhat-exposed/plugin.ts`](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-exposed/plugin.ts) (Exposed Plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_exposed["Exposed Contracts"]
  node_exposed_plugin["Exposed Plugin<br/>[plugin.ts]"]
  node_exposed_task["Generate Exposed"]
  node_expose["Contract Exposure<br/>[expose.ts]"]
  node_manifest["Generation Manifest<br/>[manifest.ts]"]
end

subgraph group_helpers["Network Helpers"]
  node_network_plugin["Helpers Plugin<br/>[plugin.ts]"]
  node_network_hook["Connection Helpers<br/>[network.ts]"]
  node_account["Account Helpers<br/>[account.ts]"]
  node_chains["Chain Formatting<br/>[chains.ts]"]
  node_time["Time Helpers<br/>[time.ts]"]
  node_storage["Storage Helpers<br/>[storage.ts]"]
end

subgraph group_docs["Solidity Documentation"]
  node_docgen_plugin["Docgen Plugin<br/>[plugin.ts]"]
  node_docgen_task["Docgen Task<br/>[docgen.ts]"]
  node_docgen_main["Site Generator<br/>[main.ts]"]
  node_site["Site Builder<br/>[site.ts]"]
  node_natspec["NatSpec Parser<br/>[natspec.ts]"]
end

subgraph group_compile["Compilation Tools"]
  node_transpiler["Transpiler Task<br/>[transpile.ts]"]
  node_yul_hook["Yul Build Hook<br/>[solidity.ts]"]
  node_yul_compile["Yul Compiler<br/>[compile.ts]"]
end

node_developer(("Contract Developer"))
node_hardhat["Hardhat Config<br/>[hardhat.config.ts]"]

node_developer -->|"configures"| node_hardhat
node_hardhat -->|"loads"| node_exposed_plugin
node_hardhat -->|"loads"| node_network_plugin
node_hardhat -->|"loads"| node_docgen_plugin
node_hardhat -->|"loads"| node_yul_compile
node_exposed_plugin -->|"registers"| node_exposed_task
node_exposed_task -->|"calls"| node_expose
node_exposed_task -->|"updates"| node_manifest
node_network_plugin -->|"registers"| node_network_hook
node_network_hook -->|"uses"| node_account
node_network_hook -->|"uses"| node_chains
node_network_hook -->|"uses"| node_time
node_network_hook -->|"uses"| node_storage
node_docgen_plugin -->|"registers"| node_docgen_task
node_docgen_task -->|"calls"| node_docgen_main
node_docgen_main -->|"builds"| node_site
node_natspec -->|"reads context"| node_site
node_transpiler -->|"runs build"| node_hardhat
node_yul_hook -->|"calls"| node_yul_compile

click node_hardhat "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat.config.ts"
click node_exposed_plugin "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-exposed/plugin.ts"
click node_exposed_task "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-exposed/tasks/generate-exposed-contracts.ts"
click node_expose "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-exposed/internal/expose.ts"
click node_manifest "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-exposed/internal/manifest.ts"
click node_network_plugin "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/plugin.ts"
click node_network_hook "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/hook-handlers/network.ts"
click node_account "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/internal/account.ts"
click node_chains "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/internal/chains.ts"
click node_time "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/internal/time.ts"
click node_storage "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/internal/storage.ts"
click node_docgen_plugin "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-solidity-docgen/plugin.ts"
click node_docgen_task "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-solidity-docgen/tasks/docgen.ts"
click node_docgen_main "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-solidity-docgen/internal/main.ts"
click node_site "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-solidity-docgen/internal/site.ts"
click node_natspec "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-solidity-docgen/internal/utils/natspec.ts"
click node_transpiler "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-transpiler/tasks/transpile.ts"
click node_yul_hook "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-yul/hook-handlers/solidity.ts"
click node_yul_compile "https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-yul/internal/compile.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_exposed_plugin,node_exposed_task,node_expose,node_manifest toneBlue
class node_network_plugin,node_network_hook,node_account,node_chains,node_time,node_storage toneAmber
class node_docgen_plugin,node_docgen_task,node_docgen_main,node_site,node_natspec toneMint
class node_transpiler,node_yul_hook,node_yul_compile toneRose
class node_developer toneIndigo
class node_hardhat toneTeal
```

## Components

### Exposed Contracts

- [Exposed Plugin](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-exposed/plugin.ts): `hardhat/hardhat-exposed/plugin.ts`
- [Generate Exposed](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-exposed/tasks/generate-exposed-contracts.ts): `hardhat/hardhat-exposed/tasks/generate-exposed-contracts.ts`
- [Contract Exposure](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-exposed/internal/expose.ts): `hardhat/hardhat-exposed/internal/expose.ts`
- [Generation Manifest](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-exposed/internal/manifest.ts): `hardhat/hardhat-exposed/internal/manifest.ts`

### Network Helpers

- [Helpers Plugin](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/plugin.ts): `hardhat/hardhat-oz-contracts-helpers/plugin.ts`
- [Connection Helpers](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/hook-handlers/network.ts): `hardhat/hardhat-oz-contracts-helpers/hook-handlers/network.ts`
- [Account Helpers](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/internal/account.ts): `hardhat/hardhat-oz-contracts-helpers/internal/account.ts`
- [Chain Formatting](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/internal/chains.ts): `hardhat/hardhat-oz-contracts-helpers/internal/chains.ts`
- [Time Helpers](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/internal/time.ts): `hardhat/hardhat-oz-contracts-helpers/internal/time.ts`
- [Storage Helpers](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-oz-contracts-helpers/internal/storage.ts): `hardhat/hardhat-oz-contracts-helpers/internal/storage.ts`

### Solidity Documentation

- [Docgen Plugin](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-solidity-docgen/plugin.ts): `hardhat/hardhat-solidity-docgen/plugin.ts`
- [Docgen Task](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-solidity-docgen/tasks/docgen.ts): `hardhat/hardhat-solidity-docgen/tasks/docgen.ts`
- [Site Generator](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-solidity-docgen/internal/main.ts): `hardhat/hardhat-solidity-docgen/internal/main.ts`
- [Site Builder](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-solidity-docgen/internal/site.ts): `hardhat/hardhat-solidity-docgen/internal/site.ts`
- [NatSpec Parser](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-solidity-docgen/internal/utils/natspec.ts): `hardhat/hardhat-solidity-docgen/internal/utils/natspec.ts`

### Compilation Tools

- [Transpiler Task](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-transpiler/tasks/transpile.ts): `hardhat/hardhat-transpiler/tasks/transpile.ts`
- [Yul Build Hook](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-yul/hook-handlers/solidity.ts): `hardhat/hardhat-yul/hook-handlers/solidity.ts`
- [Yul Compiler](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat/hardhat-yul/internal/compile.ts): `hardhat/hardhat-yul/internal/compile.ts`

### Other components

- **Contract Developer**
- [Hardhat Config](https://github.com/openzeppelin/openzeppelin-contracts/blob/master/hardhat.config.ts): `hardhat.config.ts`

## Connections

- Contract Developer → Hardhat Config: configures (evidence: `hardhat.config.ts`)
- Hardhat Config → Exposed Plugin: loads (evidence: `hardhat.config.ts`)
- Hardhat Config → Helpers Plugin: loads (evidence: `hardhat.config.ts`)
- Hardhat Config → Docgen Plugin: loads (evidence: `hardhat.config.ts`)
- Hardhat Config → Yul Compiler: loads (evidence: `hardhat.config.ts`)
- Exposed Plugin → Generate Exposed: registers (evidence: `hardhat/hardhat-exposed/plugin.ts`)
- Generate Exposed → Contract Exposure: calls (evidence: `hardhat/hardhat-exposed/tasks/generate-exposed-contracts.ts`)
- Generate Exposed → Generation Manifest: updates (evidence: `hardhat/hardhat-exposed/tasks/generate-exposed-contracts.ts`)
- Helpers Plugin → Connection Helpers: registers (evidence: `hardhat/hardhat-oz-contracts-helpers/plugin.ts`)
- Connection Helpers → Account Helpers: uses (evidence: `hardhat/hardhat-oz-contracts-helpers/hook-handlers/network.ts`)
- Connection Helpers → Chain Formatting: uses (evidence: `hardhat/hardhat-oz-contracts-helpers/hook-handlers/network.ts`)
- Connection Helpers → Time Helpers: uses (evidence: `hardhat/hardhat-oz-contracts-helpers/hook-handlers/network.ts`)
- Connection Helpers → Storage Helpers: uses (evidence: `hardhat/hardhat-oz-contracts-helpers/hook-handlers/network.ts`)
- Docgen Plugin → Docgen Task: registers (evidence: `hardhat/hardhat-solidity-docgen/plugin.ts`)
- Docgen Task → Site Generator: calls (evidence: `hardhat/hardhat-solidity-docgen/tasks/docgen.ts`)
- Site Generator → Site Builder: builds (evidence: `hardhat/hardhat-solidity-docgen/internal/main.ts`)
- NatSpec Parser → Site Builder: reads context (evidence: `hardhat/hardhat-solidity-docgen/internal/utils/natspec.ts`)
- Transpiler Task → Hardhat Config: runs build (evidence: `hardhat/hardhat-transpiler/tasks/transpile.ts`)
- Yul Build Hook → Yul Compiler: calls (evidence: `hardhat/hardhat-yul/hook-handlers/solidity.ts`)
