diff --git a/LICENSE.txt b/LICENSE.txt index a1e0302..d2b5550 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,3 +1,3 @@ The Erigon 3 documentation © 2025 by Erigon contributors is licensed under CC BY 4.0. -To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/ +To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/. diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3a02fb8..09dbde3 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -50,10 +50,11 @@ - [Caplin](advanced/bp-caplin.md) - [Tools](tools.md) - - [Dagnostic Tools](tools/introduction.md) + - [Diagnostics Tool](tools/introduction.md) - [Installation](tools/installation.md) - [Setup](tools/setup.md) - - [User Interface](tools/user_interface.md) + - [Options](tools/options.md) + - [Browser Interface](tools/user_interface.md) - [Otterscan](tools/otterscan.md) - [Frequently Asked Questions](faq.md) diff --git a/src/about/contributing.md b/src/about/contributing.md index 59e132f..340e2b5 100644 --- a/src/about/contributing.md +++ b/src/about/contributing.md @@ -1,6 +1,13 @@ -# Contributing to Erigon 3 +# Contributing -## Development + +- [Contributing to Erigon 3](#contributing-to-erigon-3) +- [Contributing to Documentation](#contributing-to-documentation) + + +## Contributing to Erigon 3 + +### Development Erigon is an open-source project that welcomes contributions from developers worldwide who are passionate about advancing the Ethereum ecosystem. Bounties may be offered for noteworthy contributions, as the team is committed to continuously enhancing the tool to better serve the Erigon community. @@ -39,6 +46,6 @@ Visit also Erigon's **[Wiki](https://github.com/ledgerwatch/erigon/wiki)** to ga - Transaction Pool Design - Using Postman to test RPC. -# Documentation +# Contributing to Documentation -To contribute to this documentation, commit your change to the development branch on **[Github](https://github.com/erigontech/docs/tree/development)**. You might want to run it locally to verify the output before committing, see how MdBook works [here](https://rust-lang.github.io/mdBook/index.html). +To contribute to the Erigon 3 book, commit your change to the development branch on **[Github](https://github.com/erigontech/docs/tree/development)**. You might want to run it locally to verify the output before committing, see how MdBook works [here](https://rust-lang.github.io/mdBook/index.html). diff --git a/src/about/license.md b/src/about/license.md index 548afd3..d8d229e 100644 --- a/src/about/license.md +++ b/src/about/license.md @@ -1,3 +1,7 @@ # License -The Erigon 3 Book © 2024 by Erigon contributors is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). \ No newline at end of file +Copyright 2025 Erigon Technologies AG. + +Licensed under the [LGPL-3.0](https://github.com/erigontech/erigon/blob/release/2.60/COPYING.LESSER), [GPL-3.0](https://github.com/erigontech/erigon/blob/release/2.60/COPYING). + +*Permissions of this copyleft license are conditioned on making available complete source code of licensed works and modifications under the same license or the GNU GPLv3. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work through interfaces provided by the licensed work may be distributed under different terms and without source code for the larger work.* \ No newline at end of file diff --git a/src/about/reachus.md b/src/about/reachus.md index f9f8ee1..39e3b69 100644 --- a/src/about/reachus.md +++ b/src/about/reachus.md @@ -2,14 +2,15 @@ The Erigon Technologies AG office is located in the CV Labs in Zug: - ``` -Erigon Technologies AG +Erigon Technologies AG Damstrasse 16 6300 Zug Switzerland ``` +**[erigon.tech](https://erigon.tech)** + ## Erigon Discord Server The most important discussions take place on the Discord server where also some support is provided. To get an invite, send an email to bloxster [at] proton.me with your name, profession, a short explanation why you want to join the Discord server and how you heard about Erigon. diff --git a/src/advanced/bp-ext.md b/src/advanced/bp-ext.md index 4f5c065..0ba948e 100644 --- a/src/advanced/bp-ext.md +++ b/src/advanced/bp-ext.md @@ -1,24 +1,3 @@ # Using an external consensus client as validator -To enable external consensus clients, add the flags: -```bash ---mine --miner.etherbase=... -``` -or - -```bash ---mine --miner.miner.sigkey=... -``` - -Other supported options are: -- `--miner.notify`: Comma separated HTTP URL list to notify of new work packages -- `--miner.gaslimit`: Target gas limit for mined blocks (default: `36000000`) -- `--miner.etherbase`: Public address for block mining rewards (default: "`0`") -- `--miner.extradata`: Block extra data set by the miner (default: `client version`) -- `--miner.noverify`: Disable remote sealing verification (default: `false`) -- `--miner.noverify`: Disable remote sealing verification (default: `false`) -- `--miner.sigfile`: Private key to sign blocks with -- `--miner.recommit`: Time interval to recreate the block being mined (default: `3s`) -- `--miner.gasprice`: This option sets the minimum gas price for mined transactions -- `--miner.gastarget`: This option sets the maximum amount of gas that could be spent during a transaction. diff --git a/src/advanced/caplin.md b/src/advanced/caplin.md index b1bc3bf..37fd226 100644 --- a/src/advanced/caplin.md +++ b/src/advanced/caplin.md @@ -22,4 +22,4 @@ In addition, Caplin can backfill recent blobs for an op-node or other uses with - `--caplin.blobs-immediate-backfill`: Backfills the last 18 days' worth of blobs to quickly populate historical blob data for operational needs or analytics. -Caplin can also be used for [block production](/advanced/block-prod.md#using-caplin-as-validator), aka **staking**. \ No newline at end of file +Caplin can also be used for [block production](/advanced/bp-caplin.md), aka **staking**. \ No newline at end of file diff --git a/src/advanced/options.md b/src/advanced/options.md index dad7c77..9ec1cc4 100644 --- a/src/advanced/options.md +++ b/src/advanced/options.md @@ -23,7 +23,7 @@ USAGE: erigon [command] [flags] VERSION: - 3.00.0-beta1-0b94461f + 3.00.0-beta2-9da58c0b COMMANDS: init Bootstrap and initialize a new genesis block @@ -191,7 +191,7 @@ GLOBAL OPTIONS: --polygon.sync.stage Enabling syncing with a stage that uses the polygon sync component (default: false) --ethstats value Reporting URL of a ethstats service (nodename:secret@host:port) --override.prague value Manually specify the Prague fork time, overriding the bundled setting (default: 0) - --caplin.discovery.addr value Address for Caplin DISCV5 protocol (default: "127.0.0.1") + --caplin.discovery.addr value Address for Caplin DISCV5 protocol (default: "0.0.0.0") --caplin.discovery.port value Port for Caplin DISCV5 protocol (default: 4000) --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 @@ -248,6 +248,8 @@ GLOBAL OPTIONS: --shutter Enable the Shutter encrypted transactions mempool (defaults to false) (default: false) --shutter.p2p.bootstrap.nodes value [ --shutter.p2p.bootstrap.nodes value ] Use to override the default p2p bootstrap nodes (defaults to using the values in the embedded config) --shutter.p2p.listen.port value Use to override the default p2p listen port (defaults to 23102) (default: 0) + --polygon.pos.ssf Enabling Polygon PoS Single Slot Finality (default: false) + --polygon.pos.ssf.block value Enabling Polygon PoS Single Slot Finality since block (default: 0) --pprof Enable the pprof HTTP server (default: false) --pprof.addr value pprof HTTP server listening interface (default: "127.0.0.1") --pprof.port value pprof HTTP server listening port (default: 6060) @@ -273,4 +275,3 @@ GLOBAL OPTIONS: --config value Sets erigon flags from YAML/TOML file --help, -h show help --version, -v print the version -``` \ No newline at end of file diff --git a/src/images/diag_create_session_1.png b/src/images/diag_create_session_1.png new file mode 100644 index 0000000..c5339f9 Binary files /dev/null and b/src/images/diag_create_session_1.png differ diff --git a/src/images/diag_create_session_2.png b/src/images/diag_create_session_2.png new file mode 100644 index 0000000..59841d8 Binary files /dev/null and b/src/images/diag_create_session_2.png differ diff --git a/src/images/diag_create_session_3.png b/src/images/diag_create_session_3.png new file mode 100644 index 0000000..86c3a7f Binary files /dev/null and b/src/images/diag_create_session_3.png differ diff --git a/src/images/diag_create_session_4.png b/src/images/diag_create_session_4.png new file mode 100644 index 0000000..0f011c3 Binary files /dev/null and b/src/images/diag_create_session_4.png differ diff --git a/src/images/logoDEF-07.png b/src/images/logoDEF-07.png new file mode 100644 index 0000000..36c4c7d Binary files /dev/null and b/src/images/logoDEF-07.png differ diff --git a/src/installation/build_exec_win.md b/src/installation/build_exec_win.md index 4e6c219..90ecf45 100644 --- a/src/installation/build_exec_win.md +++ b/src/installation/build_exec_win.md @@ -55,7 +55,7 @@ Then click on the "**New**" button and paste the following path: Open the Command Prompt and type the following: ```bash -git clone --branch v3.0.0-beta1 --single-branch https://github.com/erigontech/erigon.git +git clone --branch v3.0.0-beta2 --single-branch https://github.com/erigontech/erigon.git ``` You might need to change the `ExecutionPolicy` to allow scripts created locally or signed by a trusted publisher to run: diff --git a/src/installation/docker.md b/src/installation/docker.md index 186c3b6..288903c 100644 --- a/src/installation/docker.md +++ b/src/installation/docker.md @@ -24,7 +24,7 @@ Here are the steps to download and start Erigon 3 in Docker: 3. Download the latest version: ```bash -docker pull erigontech/erigon:v3.0.0-beta1 +docker pull erigontech/erigon:v3.0.0-beta2 ``` * List the downloaded images to get the IMAGE ID: diff --git a/src/installation/linux.md b/src/installation/linux.md index 229cff1..c3c7b20 100644 --- a/src/installation/linux.md +++ b/src/installation/linux.md @@ -4,7 +4,7 @@ The basic Erigon configuration is suitable for most users just wanting to run a node. For building the latest stable release use the following command: ```bash -git clone --branch v3.0.0-beta1 --single-branch https://github.com/erigontech/erigon.git +git clone --branch v3.0.0-beta2 --single-branch https://github.com/erigontech/erigon.git cd erigon make erigon ``` diff --git a/src/installation/upgrading-md b/src/installation/upgrading-md index 16d7b54..8ffc3e6 100644 --- a/src/installation/upgrading-md +++ b/src/installation/upgrading-md @@ -23,7 +23,7 @@ To upgrade Erigon to a newer version when you've originally installed it via Git Replace `` with the version tag of the new release, for example: ```bash - git checkout v3.0.0-beta1 + git checkout v3.0.0-beta2 ``` * **Rebuild Erigon**: Since the codebase has changed, you need to compile the new version. Run: @@ -46,7 +46,7 @@ If you're using Docker to run Erigon, the process to upgrade to a newer version Replace `` with the actual version tag you wish to use. For example: ```bash - docker pull erigontech/erigon:v3.0.0-beta1 + docker pull erigontech/erigon:v3.0.0-beta2 ``` diff --git a/src/nodes/ethereum.md b/src/nodes/ethereum.md index cb7524e..b0072f5 100644 --- a/src/nodes/ethereum.md +++ b/src/nodes/ethereum.md @@ -18,7 +18,7 @@ Check which [type of node](/basic/node.md) you might want to run and the [disk s For MacOS and Linux, run the following commands to build from source the latest Erigon version: ```bash -git clone --branch v3.0.0-beta1 --single-branch https://github.com/erigontech/erigon.git +git clone --branch v3.0.0-beta2 --single-branch https://github.com/erigontech/erigon.git cd erigon make erigon ``` diff --git a/src/nodes/gnosis.md b/src/nodes/gnosis.md index d7337d1..95bef41 100644 --- a/src/nodes/gnosis.md +++ b/src/nodes/gnosis.md @@ -18,7 +18,7 @@ Check which [type of node](/basic/node.md) you might want to run and the [disk s For MacOS and Linux, run the following commands to build from source the latest Erigon version: ```bash -git clone --branch v3.0.0-beta1 --single-branch https://github.com/erigontech/erigon.git +git clone --branch v3.0.0-beta2 --single-branch https://github.com/erigontech/erigon.git cd erigon make erigon ``` diff --git a/src/nodes/polygon.md b/src/nodes/polygon.md index 7ec2db2..526c85a 100644 --- a/src/nodes/polygon.md +++ b/src/nodes/polygon.md @@ -18,7 +18,7 @@ Check which [type of node](/basic/node.md) you might want to run and the [disk s For MacOS and Linux, run the following commands to build from source the latest Erigon version: ```bash -git clone --branch v3.0.0-beta1 --single-branch https://github.com/erigontech/erigon.git +git clone --branch v3.0.0-beta2 --single-branch https://github.com/erigontech/erigon.git cd erigon make erigon ``` diff --git a/src/tools.md b/src/tools.md index e9924b0..663b3fd 100644 --- a/src/tools.md +++ b/src/tools.md @@ -1,3 +1,8 @@ # Tools - \ No newline at end of file +Erigon offers a range of tools to enhance your experience and provide valuable assistance when: + +1. Troubleshooting issues with your local or remote Erigon node using our [Diagnostics Tool](/tools/introduction.md), which helps you identify and resolve problems efficiently. +2. Exploring the blockchain with [Otterscan](/tools/otterscan.md), a feature-rich EVM block explorer that allows you to browse and analyze blockchain data with ease. + +Both tools are developed internally and are fully supported for our users. \ No newline at end of file diff --git a/src/tools/installation.md b/src/tools/installation.md index 25267fe..3371a0a 100644 --- a/src/tools/installation.md +++ b/src/tools/installation.md @@ -1 +1,16 @@ # Installation + +## Pre-requisites + +- Erigon Node running locally; +- Ngrok, in case you are planning to monitor a remote node, see installation at . + +## Diagnostics Tool Set Up + +```bash +git clone https://github.com/erigontech/diagnostics.git +cd diagnostics +make build +``` + +You are now ready to run the Diagnostic Tool. \ No newline at end of file diff --git a/src/tools/introduction.md b/src/tools/introduction.md index 931ebe1..6509cf8 100644 --- a/src/tools/introduction.md +++ b/src/tools/introduction.md @@ -1,7 +1,8 @@ -# Diagnostic Tool +# Diagnostics Tool -As the Erigon ecosystem expands, the demand for an effective system to diagnose and resolve user issues grows. The Erigon Diagnostics Tool is designed to offer a simplified approach to pinpointing the underlying reasons for problems faced by Erigon users, be they individuals, companies utilizing Erigon internally, or enterprises granting Erigon node access to others. -Key Features +As the Erigon ecosystem expands, the demand for an effective system to diagnose and resolve user issues grows. The Erigon Diagnostics Tool is designed to offer a simplified approach to pinpointing the underlying reasons for problems faced by Erigon users. + +## Key Features The Erigon Diagnostics tool offers the following features: @@ -9,4 +10,4 @@ The Erigon Diagnostics tool offers the following features: - **Interactive Diagnostics**: When additional data is needed to pinpoint the issue, the tool facilitates an interactive process, guiding the user through targeted data collection to optimize the troubleshooting process. -- **Diagnostic Reporting**: The tool generates comprehensive diagnostic reports, making it easier for the Erigon development team to analyze the issues and provide effective solutions. \ No newline at end of file +- **Diagnostic Reporting**: The tool generates comprehensive diagnostic reports, making it easier to analyze the issues. \ No newline at end of file diff --git a/src/tools/options.md b/src/tools/options.md new file mode 100644 index 0000000..32d517c --- /dev/null +++ b/src/tools/options.md @@ -0,0 +1,49 @@ +# Options + +The following flags can be used to configure various parameters of the Diagnostics Tool. + +## Configuration File: + +- `--config` : Specify a configuration file (default is `$HOME/.cobra.yaml`). + +## Network Settings: + +- `--addr` : Network interface to listen on (default is `localhost`). +- `--port` : Port to listen on (default is `8080`). + +## Session Management: + +- `--node.sessions` : Maximum number of node sessions to allow (default is `5000`). +- `--ui.sessions` : Maximum number of UI sessions to allow (default is `5000`). + +## Logging Configuration: + +- `--log.dir.path` : Directory path to store log data (default is `./logs`). +- `--log.file.name` : Name of the log file (default is `diagnostics.log`). +- `--log.file.size.max` : Maximum size of log file in megabytes (default is `100`). +- `--log.file.age.max` : Maximum age in days a log file can persist in the system (default is `28`). +- `--log.max.backup` : Maximum number of log files that can persist (default is `5`). +- `--log.compress` : Whether to compress historical log files (default is `false`). + + +# Other options + +To display other available options for Diagnostics Tool digit: + +```bash +cd erigon +./build/bin/erigon support --help +``` + +The `--help` flag listing is reproduced below for your convenience. + +- `--diagnostics.addr [value]`: By default, the diagnostics address is `localhost:8080`. You may tunnel it to connect to a remote node, you must specify it for this flag. +- `--debug.addrs [value]`: Comma separated list of URLs to the debug endpoints thats are being diagnosed [`15sk` ] (default: "localhost:6062") +- `--diagnostics.addr [value]`: Address of the diagnostics system provided by the support team, include unique session PIN (default: "`localhost:8080`") +- `--diagnostics.sessions [value]`: Comma separated list of session PINs to connect to +- `--pprof`: Enable the pprof HTTP server (default: false) +- `--pprof.addr [value]`: pprof HTTP server listening interface (default: "`127.0.0.1`") +- `--pprof.port [value]`: pprof HTTP server listening port (default: `6060`) +- `--pprof.cpuprofile [value]`: Write CPU profile to the given file +- `--trace [value]`: Write execution trace to the given file +- `--help`, `-h`: show help \ No newline at end of file diff --git a/src/tools/setup.md b/src/tools/setup.md index feae8cb..7da3046 100644 --- a/src/tools/setup.md +++ b/src/tools/setup.md @@ -1 +1,112 @@ # Setup +*How to connect the Diagnostics Tool to your Erigon node* + +To monitor your node using the Diagnostic Tool, you must first establish a connection. The necessary steps to connect are: + +1. Run your Erigon node +2. Run the Diagnostic Tool +3. Create a new session in the Diagnostic Tool +4. Connect the Diagnostic Tool to your node +5. Refresh the Diagnostic Tool + +## 1. Run your Erigon node + +If you are not sure what to run, start from a testnet with Caplin as the Consensus Engine. + +``` +./build/bin/erigon --chain=holesky +``` + +## 2. Run the Diagnostics Tool + +Run the Diagnostic Tool application from the machine where you intend to monitor your node. + +```bash +cd diagnostics +make run-self-signed +``` + +The Diagnostics Tool page will automatically be available in your browser at the address . + +> Leaving the terminal session will close the Diagnostics Tool interface. + +## 3. Create a new session in the Diagnostics Tool + +The Diagnostics Tool is now operational, but to access the data, it must be connected to the Erigon node. Proceed to the **Admin** section in the left navigation menu and select **Create Session**. + + + +Assign a name to your session and click **Create** to proceed. + + + +Upon successful creation of a new session, a unique 8-digit code, referred to as `YOUR SESSION PIN`, will be generated. You can find this PIN displayed next to the session name in the list of created sessions. + +To copy the Session PIN or the support command, click on the copy button next to it. This will copy the information to your clipboard for easy reference or use. + + + +In this example, we created a session named "Holesky", and it was assigned the PIN 34424089. The corresponding support command is displayed beside the PIN: + +```bash +./build/bin/erigon support --Diagnostics.sessions 34424089. +``` + +## 4. Connect the Diagnosticss Tool to your node + +### 4.1 Local Node + +If your Erigon node is running on your local machine, open a new console window in the Erigon folder and run the following command: + +```bash +cd erigon +./build/bin/erigon support --diagnostics.sessions YOUR_SESSION_PIN +``` +Replace `YOUR_SESSION_PIN` with the 8-digit PIN allocated to your session during the previous step, or use the suggested support command: + +```bash +./build/bin/erigon support --diagnostics.sessions 34424089 +``` + +This will attach the Diagnostics Tool to the Erigon node using the provided session PIN. + +See also other [options](/tools/options.md). + +### 4.2 Remote Node + +If your Erigon node is running on a Virtual Private Server (VPS) such as Amazon AWS, you can connect the Diagnostics Tool on your local machine with [ngrok](https://ngrok.com/docs/getting-started/) utility. + +> **ngrok** was chosen because of its easy of use and because the free version is useful for our scope. It is possible to use any other similar tool. + +You can run ngrok on your local machine in order to tunnel `localhost:8080`: + +```bash +ngrok http http://localhost:8080 +``` + +The ngrok utility will start and return a page similar to the below example: + + + +Your diagnostic address is in the Forwarding field. Copy only the part of the address after the URL prefix https://, in this case `8ac3-79-56-45-3.ngrok-free.app`. + +In the machine hosting your Erigon node, go to the Erigon directory and run this command to attach the Diagnostics Tool to the Erigon node: + +```bash +./build/bin/erigon support --diagnostics.addr YOUR_DIAGNOSTIC_ADDRESS --diagnostics.sessions YOUR_SESSION_PIN +``` + +Replace `YOUR_DIAGNOSTIC_ADDRESS` with the address obtained with ngrok amd `YOUR_SESSION_PIN` with your session PIN from point 3. For example: + +```bash +./build/bin/erigon support --diagnostics.addr 8ac3-79-56-45-3.ngrok-free.app --diagnostics.sessions 34424089 +``` + +By following these steps, you can establish a connection between the Diagnostic Tool on your local machine and the Erigon node running on the VPS, enabling you to monitor and diagnose the node's performance. + +More information about the Erigon support command can be find here. + +## 5. Refresh the Diagnostic Tool + +Once the Diagnostics Tool is successfully connected to the Erigon node, return to your web browser and reload the page. +This step is necessary to query data from the connected node. \ No newline at end of file diff --git a/src/tools/user_interface.md b/src/tools/user_interface.md index 924b948..c0bef78 100644 --- a/src/tools/user_interface.md +++ b/src/tools/user_interface.md @@ -1 +1,20 @@ -# User Interface +# Browser Interface + +By navigating to in your browser, you can access the Diagnostics Tool and explore its various sections. These sections provide a comprehensive overview of your Erigon node's status and activity, covering aspects such as session details, node configuration, network interactions, download status, log files, and more. + +1. **Status Bar**: Displays essential information about the current session and operating Erigon node. +2. **Process Tab**: + * **Command**: Inspect the command line arguments used to launch the Erigon node. + * **Flags**: Examine the flags set in the CLI context by the user when launching the node. + * **Node info**: Contains detailed information about the Erigon node. +3. **Network Tab**: + * **Peers Data**: Collect and view information about network peers, including active peers, static peers, and total seen peers. + * **Downloader**: Provides detailed information about the progress, download status, estimated time, and resource allocation for "Snapshots" download. +4. **Logs Tab**: View and download logs from the Erigon node, with log rotation and filtering capabilities. +5. **Data Tab**: Inspect databases and their tables. +6. **Admin Tab**: + * **Session Management**: View active sessions, create new sessions, and obtain session PINs for connections. + * **Data Management**: Clear all sessions and data . +7. **Available Flags**: Configure various parameters of the diagnostics UI, including network settings, session management, logging configuration, and more. + +See currently implemented diagnostics [here](https://github.com/erigontech/diagnostics/blob/main/README.md#currently-implemented-diagnostics). \ No newline at end of file