Erigon is an implementation of Ethereum (execution layer with embeddable consensus layer), on the efficiency frontier.

Download | Documentation | Blog

This README is for people working on the repository. Everything about operating a node — install methods, flags, pruning modes, ports, monitoring, staking — is on the documentation site.

The Erigon documentation answers most questions. Useful starting points:

• Installation — binaries, Docker, Linux/macOS, Windows, ARM
• Hardware requirements — disk, RAM, CPU, bandwidth
• Pruning modes — archive, full, blocks, minimal
• CLI reference — every flag, config files, env vars
• Default ports and Security
• Interacting with Erigon — JSON-RPC, GraphQL, gRPC namespaces
• Creating a dashboard — Prometheus and Grafana
• Upgrading — versions and snapshot formats

In-depth links are marked by the microscope sign (🔬)

• Initial sync doesn't re-exec from 0: downloading 99% LatestState and History
• Per-Transaction granularity of history (Erigon2 had per-block). Means:
  • Can execute 1 historical transaction - without executing it's block
  • If account X change V1->V2->V1 within 1 block (different transactions): debug_getModifiedAccountsByNumber return it
  • Erigon3 doesn't store Logs (aka Receipts) - it always re-executing historical txn (but it's cheaper)
• Validator mode: added. --internalcl is enabled by default. to disable use --externalcl.
• Store most of data in immutable files (segments/snapshots):
  • can symlink/mount latest state to fast drive and history to cheap drive
  • chaindata is tens of gb (22gb on an archive mainnet node). It's ok to rm -rf chaindata. (to prevent grow: recommend --batchSize <= 1G)
• --prune flags changed: see --prune.mode (default: full, archive: archive, EIP-4444: minimal)
• Other changes:
  • ExecutionStage included many E2 stages: stage_hash_state, stage_trie, log_index, history_index, trace_index
  • Restart doesn't loose much partial progress: --sync.loop.block.limit=5_000 enabled by default

Log flags, log levels and log files: Logs and the CLI reference.

The torrent client in the Downloader keeps its own file, logs/torrent.log. It is written at whichever is more verbose of --torrent.verbosity and WARN, so warnings and errors always reach it even at the default verbosity. Messages at --torrent.verbosity or above are additionally forwarded to Erigon's own file and console loggers, which emit them only if --log.dir.verbosity and --verbosity are themselves verbose enough.

Block production is fully supported for Ethereum & Gnosis Chain.

Erigon can be used as an Execution Layer for external Consensus Layer clients. See JWT secret and Ethereum with an external CL.

Caplin is Erigon's embedded Consensus Layer, enabled by default. Flags, archival modes and Beacon API configuration: Caplin and Caplin for staking.

Why a new Consensus Layer rather than the Engine API: the Engine API delivers blocks one at a time, which does not suit Erigon's bulk model — Erigon is built to handle many blocks simultaneously and to sort and process data in batches. Owning the consensus layer lets Erigon drive block handling on its own terms instead of being paced by the Engine API.

🔬 Detailed explanation is DEV_CHAIN.

Toolchain: Go >= 1.25, GCC 10+ or Clang, 64-bit architecture. On Linux, kernel > v4.

git clone https://github.com/erigontech/erigon.git
cd erigon
make erigon

Binaries land in ./build/bin. Use -j<n> to parallelise the build. Packaged binaries, Docker images and the per-platform install steps are on the installation page; to build a specific release rather than main, check out its tag.

On Windows, build natively (Chocolatey, MinGW, and the MinGW anti-virus false-positive workaround) or under WSL2: Native compilation and WSL.

make erigon builds the node; make all builds the full suite into ./build/bin. make help lists every target.

caplin, capcli, snapshots, rpctest and pics are also built by make all.

make test-short           # fast unit tests
make test-all             # full test suite
make test-fixtures-cl     # consensus-spec fixtures (also: test-fixtures-eest, test-fixtures-zkevm)
make lint                 # run before opening or updating a PR

docs/TESTING.md covers the release-time incremental-sync verification, which is a separate exercise from the test suite above.

# please use git branch name (or commit hash). don't use git tags
go get github.com/erigontech/erigon@main
go mod tidy

• docs/DEV_CHAIN.md — dev chain / local devnet
• docker-compose.yml — how the services are wired when run as separate processes
• db/etl/README.md — the ETL framework used to preprocess data before DB inserts
• db/downloader/README.md — snapshot downloader internals
• cmd/downloader/readme.md — snapshots overview: what they are, when they are created and pulled
• cmd/rpcdaemon/README.md — RPC daemon, including running it remotely
• cmd/prometheus/Readme.md — metrics and dashboards
• CI-GUIDELINES.md — read before changing workflows

Most of Erigon's components (txpool, rpcdaemon, snapshots downloader, sentry, ...) can run inside Erigon or as independent processes. Deployment modes, flags and remote (Remote DB) setup: RPC Daemon and cmd/rpcdaemon/README.md.

Every default port, the flags that change them, and firewalling guidance: Default ports and Security.

Ports to open and the reserved IPv4 ranges to block: Hetzner firewall note.

Running erigon from build/bin as a separate user requires the binaries to be installed using make DIST=<path> install. You could use $HOME/erigon or /opt/erigon as the installation path, for example:

make DIST=/opt/erigon install

• Get stack trace: kill -SIGUSR1 <pid>, get trace and stop: kill -6 <pid>
• Get CPU profiling: add --pprof flag and run
  go tool pprof -png http://127.0.0.1:6060/debug/pprof/profile\?seconds\=20 > cpu.png
• Get RAM profiling: add --pprof flag and run
  go tool pprof -inuse_space -png http://127.0.0.1:6060/debug/pprof/heap > mem.png

🔬 Detailed explanation is here.

post

Send an email to security [at] torquem.ch.

• Discord for community support and development chat
• GitHub Issues to report a bug — see Grab diagnostic for bug report first
• Release notes for what changed in each version

Erigon is licensed under the GNU Lesser General Public License v3.0.