diff --git a/README.md b/README.md index be3af09..b7c6ef9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# The Erigon 3 Book +# Erigon 3 Docs This is the official Erigon 3 documentation, hosted at . diff --git a/book.toml b/book.toml index c328597..70c93ed 100644 --- a/book.toml +++ b/book.toml @@ -1,5 +1,5 @@ [book] -title = "The Erigon 3 Book" +title = "Erigon 3 Docs" authors = ["Erigon"] description = "Erigon 3 documentation!" language = "en" @@ -8,3 +8,8 @@ src = "src" [output.html] git-repository-url = "https://github.com/erigontech/docs" +[output.html.fold] +enable = true # whether or not to enable section folding +level = 0 # the depth to start folding +theme = "my-theme" +default-theme = "Ayu" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 09dbde3..eeecede 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -21,6 +21,7 @@ - [Optimizing Storage](basic/optimizing-storage.md) - [Supported Networks](basic/networks.md) - [Default Ports and Firewalls](basic/ports.md) + - [YAML/TOML Config](basic/yaml.md) - [Web3 Wallet](basic/wallet) - [Quick nodes](quick_nodes.md) @@ -57,10 +58,9 @@ - [Browser Interface](tools/user_interface.md) - [Otterscan](tools/otterscan.md) -- [Frequently Asked Questions](faq.md) - - [About](about.md) - [License](about/license.md) - [Contributing](about/contributing.md) + - [Disclaimer](about/disclaimer.md) - [Donate](about/donate.md) - [How to reach us](about/reachus.md) diff --git a/src/_introduction.md b/src/_introduction.md index 1cff457..e211c9e 100644 --- a/src/_introduction.md +++ b/src/_introduction.md @@ -1,53 +1,27 @@ # Introduction - - ########b oo d####b. - ## '## - ##aaaa ##d###b. dP .d####b. .d####b. ##d###b. aaad#' - ## ##' '## ## ##' '## ##' '## ##' '## '## - ## ## ## ##. .## ##. .## ## ## .## - ########P dP dP '####P## '#####P' dP dP d#####P - .## - d####P -> 📖 **Contributing** -> -> You can contribute to this book on [GitHub](https://github.com/erigontech/docs). -> -> For instructions regarding Erigon 2 please refer to . +Erigon 3 -Erigon is an efficient Ethereum implementation designed for speed, modularity, and optimization. By default, it functions as an archive node, utilizing technologies like staged sync, efficient state storage, and database compression. +Erigon is an efficient Ethereum implementation designed for speed, modularity, and optimization. By default, it functions as a full node, utilizing technologies like staged sync, efficient state storage, and database compression. -With Erigon 3 the default configuration shifts from archive node to full node, enhancing efficiency, accessibility, and versatility for a wider range of users. Archive nodes remain available for developers and researchers needing full historical data, while the full node offers faster sync times and lower resource usage for everyday operations. More info [here](https://erigon.tech/announcing-erigon-v3-alpha-6-focus-on-staking-and-full-node-performance/). +With Erigon 3 the default configuration shifts from archive node to full node, enhancing efficiency, accessibility, and versatility for a wider range of users. Archive nodes remain available for developers and researchers needing full historical data, while the full node offers faster sync times and lower resource usage for everyday operations. -
+# Topics -**Information** +- Review the hardware and software requirements [get started](getting_started.md). +- Follow the [installation guide](installation.md) to set up Erigon. +- Learn the [basic usage](basic-usage.md) of Erigon. +- Quickly deploy your own Ethereum, Gnosis, or Polygon [node](quick_nodes.md). +- Explore Erigon's [advanced features](advanced.md). +- Discover the capabilities of the [RPC Daemon](advanced/JSONRPC-daemon.md). +- Utilize integrated [tools](tools.md) like Diagnostic Tools and Otterscan. -If you wanto to test Erigon without reading all the documentation, go straight to the [quick nodes](quick_nodes.md) section. +# Additional Resources and Information -
- -> **DISCLAIMER** -> -> Erigon 3 is in alpha phase and it is not recommended to be used in production environments. The Erigon team does not take any responsibility for losses or damages occurred through the use of Erigon. While we employ a seasoned in-house security team, we have not subjected our systems to independent third-party security assessments, leaving potential vulnerabilities to bugs or malicious activity unaddressed. It is essential for validators to be aware that unforeseen events, including software glitches, may result in lost rewards. - -# Features - -Erigon offers several features that make it a good option for a node application such as efficient state storage through the use of a key-value database and faster initial synchronisation. - -Built with modularity in mind, it also offers separate components such as the JSON RPC daemon, that can connect to both local and remote databases. For read-only calls, this RPC daemon does not need to run on the same system as the main Erigon binary, and can even run from a database snapshot. - -Erigon 3 is a major update that introduces several significant changes, improvements, and optimizations. Some of the key features and differences include: - -The main changes from Erigon 2 are listed [here](https://github.com/erigontech/erigon?tab=readme-ov-file#erigon3-changes-from-erigon2). - -# Release Process - -Erigon 3 also introduces changes to the release process, including: -* New Docker Image Repository: Erigon images are now available on Dockerhub repository "erigontech/erigon". -* Multi-Platform Support: The docker image is built for linux/amd64/v2 and linux/arm64 platforms using Alpine 3.20.2. -* Release Workflow Changes: Build flags are now passed to the release workflow, allowing users to view previously missed build information in released binaries. - -# Known Issues - -See . \ No newline at end of file +- **Releases**: see . +- **Docker image releases**: + - New Docker Image Repository: Erigon images are now available on Dockerhub repository [erigontech/erigon](https://hub.docker.com/r/erigontech/erigon). + - Multi-Platform Support: The docker image is built for linux/amd64/v2 and linux/arm64 platforms using Alpine. +- **Frequently Asked Questions**: see . +- **Known Issues**: See . +- **Changes from Erigon 2**: The main changes from Erigon 2 are listed [here](https://github.com/erigontech/erigon?tab=readme-ov-file#erigon3-changes-from-erigon2). \ No newline at end of file diff --git a/src/about/disclaimer.md b/src/about/disclaimer.md new file mode 100644 index 0000000..6c1c0e4 --- /dev/null +++ b/src/about/disclaimer.md @@ -0,0 +1,3 @@ +# Disclaimer + +The Erigon team does not take any responsibility for losses or damages occurred through the use of Erigon. While we employ a seasoned in-house security team, we have not subjected our systems to independent third-party security assessments. \ No newline at end of file diff --git a/src/advanced/JSONRPC-daemon.md b/src/advanced/JSONRPC-daemon.md index f3ba34b..ccb5f83 100644 --- a/src/advanced/JSONRPC-daemon.md +++ b/src/advanced/JSONRPC-daemon.md @@ -29,7 +29,7 @@ This document provides guidelines for understanding and using the various RPC me ## More info -For a comprehensive understanding of the RPC daemon's functionality, configuration, and usage, please refer to *** (also contained in your locally compiled Erigon folder at `/cmd/rpcdaemon`) which covers the following key topics: +For a comprehensive understanding of the RPC daemon's functionality, configuration, and usage, please refer to (also contained in your locally compiled Erigon folder at `/cmd/rpcdaemon`) which covers the following key topics: 1. **Introduction**: An overview of the RPC daemon, its benefits, and how it integrates with Erigon. 2. **Getting Started**: Step-by-step guides for running the RPC daemon locally and remotely, including configuration options and command-line flags. diff --git a/src/advanced/bp-caplin.md b/src/advanced/bp-caplin.md index e36afc7..5676f1a 100644 --- a/src/advanced/bp-caplin.md +++ b/src/advanced/bp-caplin.md @@ -7,13 +7,11 @@ This guide explains how to use Erigon with its embedded Caplin consensus layer a ## 1. Start Erigon with Caplin -Run the following command to start Erigon with the embedded Caplin consensus layer with the beacon API on: +The following command starts Erigon with the embedded Caplin consensus layer with the beacon API on: ```bash erigon \ --datadir=/data/erigon \ - --chain=mainnet \ - --prune.mode=full \ --http \ --http.addr=0.0.0.0 \ --http.port=8545 \ @@ -24,13 +22,12 @@ erigon \ --caplin.discovery.addr=0.0.0.0 \ --caplin.discovery.port=4000 \ --caplin.discovery.tcpport=4001 \ - --chain= --beacon.api=beacon,validator,builder,config,debug,events,node,lighthouse ``` **Flags Explanation**: -- Execution Layer: +- Execution Layer (Erigon): - `--http.api=engine,eth,net,web3`: enables the necessary APIs for external clients and Caplin. - `--ws`: enables WebSocket-based communication (optional). - Consensus Layer (Caplin): @@ -41,15 +38,7 @@ erigon \ ### 2.1 Install Lighthouse -Download the latest Lighthouse binary: - -``` -curl -LO https://github.com/sigp/lighthouse/releases/latest/download/lighthouse -chmod +x lighthouse -sudo mv lighthouse /usr/local/bin/ -``` - -Or, use Docker: +Install and run Lighthouse by following the official guide at or use Docker: ```bash docker pull sigp/lighthouse:latest @@ -63,7 +52,7 @@ mkdir -p ~/.lighthouse/validators ### 2.3. Run Lighthouse Validator Client -Start the validator client and connect it to the Caplin consensus layer: +Start the validator client and connect it to the Caplin CL: ```bash lighthouse vc \ diff --git a/src/advanced/bp-ext.md b/src/advanced/bp-ext.md index 0ba948e..ce512a7 100644 --- a/src/advanced/bp-ext.md +++ b/src/advanced/bp-ext.md @@ -1,3 +1,54 @@ # Using an external consensus client as validator +To use an external Consensus Layer (CL) it is necessary to add to Erigon the flag `--externalcl`. Here are a couple of examples on how to configure Lighhouse and Prysm to run along with Erigon: + +- [Ethereum](/nodes/ethereum.md#erigon-with-prysm-as-the-external-consensus-layer) +- [Gnosis Chain](/nodes/gnosis.md#erigon-with-lighthouse) + +Once you have Erigon and a CL client up and running, you can proceed to set up a Validator Client (VC). The VC is responsible for managing your keys and signing valid blocks. + +## Getting Started with a Validator Client + +To set up a VC, follow the instructions provided in the official documentation, such as: + +. + +This guide will walk you through the process of setting up a VC, including: + +- Generating and managing your keys +- Configuring the Validator Client +- Signing valid blocks + +Make sure to follow the instructions carefully and thoroughly to ensure that your VC is set up correctly. It is always recommended to start staking with a testnet. + +## Example of configuration + +The following example demonstrates how to configure Erigon to run with an external Consensus Layer: + +```bash +erigon \ + --externalcl \ + --datadir=/data/erigon \ + --chain=sepolia \ + --authrpc.jwtsecret=/jwt + --authrpc.addr=0.0.0.0 \ + --http \ + --http.addr=0.0.0.0 \ + --http.port=8545 \ + --http.api=engine,eth,net,web3 \ + --ws \ + --ws.port=8546 \ +``` + +## Flags explanation: + +- `--externalcl`: Enables the use of an external CL. +- `--datadir=/data/erigon`: Defines the directory to be used for databases. +- `--chain=sepolia`: Specifies the Sepolia chain. +- `--authrpc.jwtsecret=/jwt`: Sets the location of the JWT authentication code in hex encoding. This is used by Erigon (the EL) and the CL (in this case Lighthouse) to authenticate communication. +- `--authrpc.addr=0.0.0.0`: Allows the engine API to be accessed from any address. +- `--http.api=engine,eth,net,web3`: Enables the necessary APIs for external clients and Caplin. +- `--ws`: enables WebSocket-based communication, which is optional. + +> Note that many pre-merge flags, such as `--miner.etherbase`, are no longer useful, as block rewards and other validator-related configurations are now controlled by the Consensus Layer (CL). diff --git a/src/advanced/consensus_layer.md b/src/advanced/consensus_layer.md index 18b97f5..484688e 100644 --- a/src/advanced/consensus_layer.md +++ b/src/advanced/consensus_layer.md @@ -12,13 +12,16 @@ The consensus client, also known as the *Beacon Node* or *CL client*, implements **Information** -By default, Erigon is configured to run with [Caplin](/advanced/bp-caplin.md), the embedded Consensus Layer. +By default, Erigon is configured to run with [Caplin](/advanced/caplin.md), the embedded Consensus Layer. ## Choosing the Consensus Layer client -A Consensus Layer (CL) client needs to run alongside Erigon to run a full Ethereum node, a Gnosis Chain node and a Polygon node and its respective testnets. Basically, without a CL client the EL will never get in sync. See below which Beacon node for which chain you can run along with Erigon +A Consensus Layer (CL) client needs to run alongside Erigon to run a full Ethereum node, a Gnosis Chain node and a Polygon node and its respective testnets. Basically, without a CL client the EL will never get in sync. -- [Ethereum](./src/nodes/ethereum.md) -- [Gnosis Chain](/nodes/gnosis.md) -- [Polygon](/nodes/polygon.md) +Below are the links to examples on how to configure Lighhouse and Prysm to run along with Erigon: + +- [Ethereum](/nodes/ethereum.md#erigon-with-prysm-as-the-external-consensus-layer) +- [Gnosis Chain](/nodes/gnosis.md#erigon-with-lighthouse) + +> **important Note**: When configuring a CL client, always refer to the official CL documentation for the most up-to-date and accurate configuration instructions. This will ensure that you set up your CL client correctly and avoid any potential issues. \ No newline at end of file diff --git a/src/advanced/op-node.md b/src/advanced/op-node.md index 434dbc7..55aa3e6 100644 --- a/src/advanced/op-node.md +++ b/src/advanced/op-node.md @@ -1,4 +1,4 @@ -# Running an Op-Node Alongside Erigon +# Running an Op-Node alongside Erigon To run an op-node alongside Erigon, follow these steps: diff --git a/src/advanced/options.md b/src/advanced/options.md index 9ec1cc4..4091877 100644 --- a/src/advanced/options.md +++ b/src/advanced/options.md @@ -23,7 +23,7 @@ USAGE: erigon [command] [flags] VERSION: - 3.00.0-beta2-9da58c0b + 3.00.0-57625b40 COMMANDS: init Bootstrap and initialize a new genesis block @@ -33,7 +33,7 @@ COMMANDS: help, h Shows a list of commands or help for one command GLOBAL OPTIONS: - --datadir value Data directory for the databases (default: /home/bloxster/.local/share/erigon) + --datadir value Data directory for the databases (default: /home/user/.local/share/erigon) --ethash.dagdir value Directory to store the ethash mining DAGs (default: /home/bloxster/.local/share/erigon-ethash) --externalcl Enables the external consensus layer (default: false) --txpool.disable Experimental external pool and block producer, see ./cmd/txpool/readme.md for more info. Disabling internal txpool and block producer. (default: false) @@ -196,10 +196,10 @@ GLOBAL OPTIONS: --caplin.discovery.tcpport value TCP Port for Caplin DISCV5 protocol (default: 4001) --caplin.checkpoint-sync-url value [ --caplin.checkpoint-sync-url value ] checkpoint sync endpoint --caplin.subscribe-all-topics Subscribe to all gossip topics (default: false) - --caplin.max-peer-count value Max number of peers to connect (default: 80) + --caplin.max-peer-count value Max number of peers to connect (default: 128) --caplin.enable-upnp Enable NAT porting for Caplin (default: false) - --caplin.max-inbound-traffic-per-peer value Max inbound traffic per second per peer (default: "256KB") - --caplin.max-outbound-traffic-per-peer value Max outbound traffic per second per peer (default: "256KB") + --caplin.max-inbound-traffic-per-peer value Max inbound traffic per second per peer (default: "1MB") + --caplin.max-outbound-traffic-per-peer value Max outbound traffic per second per peer (default: "1MB") --caplin.adaptable-maximum-traffic-requirements Make the node adaptable to the maximum traffic requirement based on how many validators are being ran (default: true) --sentinel.addr value Address for sentinel (default: "localhost") --sentinel.port value Port for sentinel (default: 7777) @@ -275,3 +275,5 @@ GLOBAL OPTIONS: --config value Sets erigon flags from YAML/TOML file --help, -h show help --version, -v print the version +``` + diff --git a/src/advanced/sentry.md b/src/advanced/sentry.md index 6bbe775..f163fda 100644 --- a/src/advanced/sentry.md +++ b/src/advanced/sentry.md @@ -20,9 +20,10 @@ The ETH core interacts with the Ethereum p2p network through the Sentry componen It is possible to have multiple Sentry to increase connectivity to the network or to obscure the location of the core computer. In this case it is necessary to define address and port of each Sentry that should be connected to the Core. -Before using the Sentry component the executable must be built. Head over to /erigon directory and type: +Before using the Sentry component the executable must be built: ```bash +cd erigon make sentry ``` @@ -39,13 +40,13 @@ In this example we will run an instance of Erigon and Sentry on the same machine Following is the Sentry client running separately: ```bash -screen ./build/bin/sentry --datadir=~/.local/share/erigon +./build/bin/sentry --datadir=~/.local/share/erigon ``` -And here is Erigon attaching to it +And Erigon attaching to it: ```bash -./build/bin/erigon --internalcl --snapshots=true --sentry.api.addr=127.0.0.1:9091 +./build/bin/erigon --sentry.api.addr=127.0.0.1:9091 ``` Erigon might be attached to several Sentry instances running across different machines. As per Erigon help: @@ -53,7 +54,7 @@ Erigon might be attached to several Sentry instances running across different ma ```bash --sentry.api.addr value ``` -Where `value` is comma separated sentry addresses ':,:'. +Where `value` is comma separated sentry addresses `:,:`. ## More info @@ -76,7 +77,7 @@ Usage: sentry [flags] Flags: - --datadir string Data directory for the databases (default "/home/bloxster/.local/share/erigon") + --datadir string Data directory for the databases (default "/home/user/.local/share/erigon") --diagnostics.disabled Disable diagnostics --diagnostics.endpoint.addr string Diagnostics HTTP server listening interface (default "127.0.0.1") --diagnostics.endpoint.port uint Diagnostics HTTP server listening port (default 6062) diff --git a/src/advanced/txpool.md b/src/advanced/txpool.md index 870311b..42a180a 100644 --- a/src/advanced/txpool.md +++ b/src/advanced/txpool.md @@ -1,38 +1,76 @@ -# TxPool -*Memory pool management* +# Txpool -In Erigon, `txpool` is a specific API namespace that keeps pending and queued transactions in the local memory pool. It is used to store transactions that are waiting to be processed by miners. Default is `4096` pending and `1024` queued transactions. However, the number of pending transactions can be much higher than this default value. +The transaction pool, also known as the mempool, is a dynamic storage area where pending transactions are held before being confirmed and added to the blockchain. Each node on the Ethereum network maintains its own local transaction pool, which is combined with others to form the global pool. -The transaction pool (txpool or mempool) is the dynamic in-memory area where pending transactions reside before they are included in a block and thus become static. Each node on the Ethereum mainnet has its own pool of transactions and, combined, they all form the global pool. +In Erigon, the txpool is a dedicated API namespace that stores pending and queued transactions in local memory. Its primary function is to manage transactions waiting to be processed by miners. -The thousands of pending transactions that enter the global pool by being broadcast on the network and before being included in a block are an always changing data set that’s holding millions of dollars at any given second. There are many ways to use txpool such as yield farming, liquidity providing, arbitrage, front running and MEV . +The TxPool component is typically run as an internal Erigon component, but it can also be operated as a separate process, providing flexibility in transaction management. -WHile Txpool component is run by default as an internal Erigon component, it can also be run as a separate process. +## Txpool as an internal Erigon component -## Running with TX pool as a separate process +Txpool is run as an internal Erigon component by default. -Before using a separate TxPool process the executable must be built: +## Txpool as a separate process (experimental) + +Running an external txpool can provide a more secure, scalable, and flexible transaction management solution, which can be particularly beneficial in high-performance or high-availability Ethereum node deployments. + +1) Before TxPool can be using as a separate process the executable must be built: ```bash cd erigon make txpool ``` -If Erigon is on a different device, add the flag `--pprof.addr 0.0.0.0` or TxPool will listen on localhost by default. +2) Together with external TxPool also [Sentry](sentry.md) and [RPCDaemon](JSONRPC-daemon.md) must be compiled and run separately. ```bash -./build/bin/txpool --pprof.addr 0.0.0.0 +make sentry ``` -Erigon must be launched with options to listen to external TxPool - ```bash -./build/bin/erigon --pprof --pprof.addr 123.123.123.123 +make rpcdaemon +``` + +3) Now Erigon and other services can be started as separate processes + + +```sh +./build/bin/erigon --txpool.disable --private.api.addr=localhost:9090 --datadir= --http=false +``` + +If Erigon is on a different device, add the flags `--pprof --pprof.addr 0.0.0.0` or TxPool will listen on localhost by default. + + +```sh +./build/bin/sentry --sentry.api.addr=localhost:9091 --datadir= +``` + +```sh +./build/bin/txpool --private.api.addr=localhost:9090 --sentry.api.addr=localhost:9091 --txpool.api.addr=localhost:9094 --datadir= +``` + +```sh +./build/bin/rpcdaemon --private.api.addr=localhost:9090 --datadir= --txpool.api.addr=localhost:9094 ``` -## More info +## Flags explanation + +- `--txpool.disable`: This flag disables the internal transaction pool (txpool) and block producer (default: `false`). When running the txpool as a separate process, this flag is used to prevent the internal txpool from interfering with the external one. + +- `--private.api.addr=localhost:9090`: This flag sets the address and port for the private API. The private API is used for internal communication between Erigon components (default: `127.0.0.1:9090`). + +- `--datadir=`: This flag specifies the data directory for Erigon. This is where Erigon stores its databases and other data. + +- `--http=false`: This flag disables the HTTP API server in Erigon (default: `true)`. When running the txpool as a separate process, this flag is used to prevent the internal HTTP server from interfering with the external txpool. + +- `--sentry.api.addr=localhost:9091`: This flag sets the address and port for the sentry API. The sentry API is used for communication between the txpool and the sentry. + +- `--txpool.api.addr=localhost:9094`: This flag sets the address and port for the txpool API (default: use value of `--private.api.addr`). The txpool API is used for communication between the txpool and other Erigon components. + +- `--pprof`: Enable the pprof HTTP server (default: `false`) + +- `--pprof.addr 0.0.0.0`: This flag sets the address for the pprof HTTP server (default: `127.0.0.1`). The pprof server is used for profiling and debugging Erigon. By setting this flag to `0.0.0.0`, the pprof server is made accessible from outside the local machine. -For other information regardin Txpool functionality, configuration, and usage, please refer to the embedded file you can find in your compiled Erigon folder at `./cmd/txpool/README.md`. ## Command Line Options @@ -45,13 +83,14 @@ To display available options for Txpool digit: The `--help` flag listing is reproduced below for your convenience. ``` +./build/bin/txpool --help Launch external Transaction Pool instance - same as built-into Erigon, but as independent Process Usage: txpool [flags] Flags: - --datadir string Data directory for the databases (default "/home/bloxster/.local/share/erigon") + --datadir string Data directory for the databases (default "/home/user/.local/share/erigon") --db.writemap Enable WRITE_MAP feature for fast database writes and fast commit times (default true) --diagnostics.disabled Disable diagnostics --diagnostics.endpoint.addr string Diagnostics HTTP server listening interface (default "127.0.0.1") diff --git a/src/basic/disk-space.md b/src/basic/disk-space.md index 31eaa04..9f50c6f 100644 --- a/src/basic/disk-space.md +++ b/src/basic/disk-space.md @@ -3,12 +3,13 @@ # Mainnets +Below is the size of the `--datadir` used by Erigon. ## Erigon with Caplin | Network | Archive Node | Full Node | Minimal Node | |----------|--------------|-----------|--------------| -| Ethereum | 1.7 TB | 900 GB | 310 GB | +| Ethereum | 1.7 TB | 1000 GB | 310 GB | | Gnosis | 535 GB | 365 GB | 210 GB | | Polygon | 4.3 TB | 2 TB | 873 GB | @@ -16,7 +17,6 @@ See also [sync times](https://github.com/erigontech/erigon?tab=readme-ov-file#sy