From 4cf3f2d50844593c1d2cbfffb122061bc2162f3e Mon Sep 17 00:00:00 2001 From: Sina M <1591639+s1na@users.noreply.github.com> Date: Mon, 24 Jun 2024 16:39:42 +0200 Subject: [PATCH 1/2] website: remove LES page (#30055) les: remove page --- docs/fundamentals/les.md | 62 ------------------------------- src/data/documentation-links.yaml | 2 - 2 files changed, 64 deletions(-) delete mode 100644 docs/fundamentals/les.md diff --git a/docs/fundamentals/les.md b/docs/fundamentals/les.md deleted file mode 100644 index e2ba98be90..0000000000 --- a/docs/fundamentals/les.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Light client -description: Introduction to Geth's light sync mode ---- - -Running a full node is the most trustless, private, decentralized and censorship resistant way to interact with Ethereum. It is also the best choice for the health of the network, because a decentralized network relies on having many individual nodes that independently verify the head of the chain. In a full node a copy of the blockchain is stored locally enabling users to verify incoming data against a local source of truth. However, running a full node requires a lot of disk space and non-negligible CPU allocation and takes hours (for snap sync) or days (for full sync) to sync the blockchain from genesis. Geth also offers a light mode that overcomes these issues and provides some of the benefits of running a node but requires only a fraction of the resources. - -Read more about the reasons to run nodes on [ethereum.org](https://ethereum.org/en/run-a-node/). - -Geth light clients **do not currently work** on proof-of-stake Ethereum. New light clients that work with the proof-of-stake consensus engine are expected to ship soon! - -## Light node vs full node {#light-node-vs-full-node} - -Running Geth in light mode has the following advantages for users: - -- Syncing takes minutes rather than hours/days -- Light mode uses significantly less storage -- Light mode is lighter on CPU and other resources -- Light mode is suitable for resource-constrained devices -- Light mode can catch up much quicker after having been offline for a while - -However, the cost of this performance increase is that a light Geth node depends heavily on full-node peers that choose, for altruistic reasons, to run light servers. There is no monetary incentive for full nodes to run light servers and it is an opt-in, rather than opt-out function of a Geth full node. For those reasons light servers are rather rare and can quickly become overwhelmed by data requests from light clients. The result of this is that **Geth nodes run in light mode often struggle to find peers**. - -A light client can be used to query data from Ethereum and submit transactions, acting as a locally-hosted Ethereum wallet. However they have different security guarantees than full nodes. Because they don't keep local copies of the Ethereum state, light nodes can't validate the blocks in the same way as the full nodes. Instead they fetch block headers by requesting them from full nodes and check their proof-of-work (PoW), assuming the heaviest chain is valid. This means that it is sensible to wait until a few additional blocks have been confirmed before trusting the validity of a recently-mined transaction. - -### Running a light server {#running-light-server} - -Full node operators that choose to enable light serving altruistically enable other users to run light clients. This is good for Ethereum because it makes it easier for a wider population of users to interact with Ethereum without using trusted intermediaries. However, there is naturally a limit to how much resource a node operator is able and willing to dedicate to serving light clients. Therefore, the command that enables light serving requires arguments that define the upper bound on resource allocation. The value given is in percent of a processing thread, for example `--light.serve 300` enables light-serving and dedicates three processing threads to it. - -Recent versions of Geth (>`1.9.14`) unindex older transactions to save disk space. Indexing is required for looking up transactions in Geth's database. Therefore, unindexing limits the data that can be requested by light clients. This unindexing can be disabled by adding `--tx.txlookuplimit 0` to make the maximum data available to light clients. - -The whole command for starting Geth with a light server could look as follows: - -```sh -geth --light.serve 50 --txlookuplimit 0 -``` - -### Running a light client {#running-light-client} - -Running a light client simply requires Geth to be started in light mode. It is likely that a user would also want to interact with the light node using, for example, RPC. This can be enabled using the `--http` command. - -```sh -geth --syncmode light --http --http.api "eth,debug" -``` - -Data can be requested from this light Geth instance in the same way as for a full node (i.e. using the [JSON-RPC-API](/docs/interacting-with-geth/rpc/) using tools such as [Curl](https://curl.se/) or Geth's [Javascript console](/docs/interacting-with-geth/javascript-console)). Instead of fetching the data from a local database as in a full node, the light Geth instance requests the data from full-node peers. - -It's also possible to send transactions. However, light clients are not connected directly to Ethereum Mainnet but to a network of light servers that connect to Ethereum Mainnet. This means a transaction submitted by a light client is received first by a light server that then propagates it to full-node peers on the light-client's behalf. This reliance on honest light-servers is one of the trust compromises that comes along with running a light node instead of a full node. - -### Ultra light clients {#ultra-light-client} - -Geth has an even lighter sync mode called ultra light client (ULC). The difference between light mode and ultra-light mode is that a ULC doesn't check the PoW in block headers. There is an assumption that the ULC has access to one or more trusted light servers. This option has the greatest trust assumptions but the smallest resource requirement. - -To start an ultra-light client, the enode addresses of the trusted light servers must be passed to the `--ulc.servers` command and the sync mode is `light`: - -```sh -geth --syncmode light --ulc.servers "enode://...,enode://..." --http --http.api "eth,debug" -``` - -## Summary {#summary} - -Running a full node is the most trustless way to interact with Ethereum. However, Geth provides a low-resource "light" mode that can be run on modest computers and requires much less disk space. The trade-offs are additional trust assumptions and a small pool of light-serving peers to connect to. diff --git a/src/data/documentation-links.yaml b/src/data/documentation-links.yaml index b027d0ca0b..ae310df91f 100644 --- a/src/data/documentation-links.yaml +++ b/src/data/documentation-links.yaml @@ -38,8 +38,6 @@ to: /docs/fundamentals/private-network - id: Config files to: /docs/fundamentals/config-files - - id: Light client - to: /docs/fundamentals/les - id: Mining to: /docs/fundamentals/mining - id: Interacting with Geth From 8a47173856e50093cd0d0f5f273ae4c11bfb764e Mon Sep 17 00:00:00 2001 From: Sina M <1591639+s1na@users.noreply.github.com> Date: Tue, 25 Jun 2024 15:16:40 +0200 Subject: [PATCH 2/2] website: add page on blsync (#30057) Co-authored-by: Marius van der Wijden Co-authored-by: Felix Lange --- docs/fundamentals/blsync.md | 70 +++++++++++++++++++++++ docs/getting-started/consensus-clients.md | 2 + src/data/documentation-links.yaml | 2 + 3 files changed, 74 insertions(+) create mode 100644 docs/fundamentals/blsync.md diff --git a/docs/fundamentals/blsync.md b/docs/fundamentals/blsync.md new file mode 100644 index 0000000000..796432f71d --- /dev/null +++ b/docs/fundamentals/blsync.md @@ -0,0 +1,70 @@ +--- +title: Beacon light client +description: Running geth with integrated beacon light client +--- + +`blsync` is a beacon chain light client. Integrated within Geth, blsync eliminates the necessity of running a separate [consensus client](/docs/getting-started/consensus-clients), making it ideal for use-cases that do not require full validation capabilities. It comes with very low resource requirements and can sync the beacon chain within seconds. `blsync` can be run in two modes: integrated or standalone. In standalone mode it is possible to use it for driving other execution clients. + +Important: blsync is not suitable for running a validator. It is also not recommended for nodes handling any amount of money or used in production settings due to its lower security guarantees compared to running a full consensus client. + +## Usage + +### Integrated mode + +To run blsync as part of Geth, you need to specify a public HTTP endpoint and a checkpoint: + +- **Choose an Endpoint**: Select a reliable and available endpoint from the [Light Sync Endpoints](https://s1na.github.io/light-sync-endpoints/) list. These nodes are community-maintained. + +- **Specify the Checkpoint**: Obtain a weak subjectivity checkpoint from a trusted node operator. The checkpoint should be less than 2 weeks old. + +#### Checkpoint + +A checkpoint is the block root of the first proposed slot of a finalized beacon epoch. In this guide we use [beaconcha.in](https://sepolia.beaconcha.in) to find a checkpoint: + +- Visit sepolia.beaconcha.in. +- Navigate to the latest finalized epoch that is ideally 1 hour old. +![Finding a suitable epoch](/images/docs/blsync1.png) +- Open the epoch details and find the first proposed slot at the end of the page. +![Finding the first slot](/images/docs/blsync2.png) +- Copy the block root field. +![Copy the block root](/images/docs/blsync3.png) + +#### Example + +The following command can be used to start Geth with blsync on the Sepolia network. Note that the checkpoint root will be outdated two weeks after the writing of this page and a recent one will have to be picked according to the guide above: + +```terminal +./build/bin/geth --sepolia --beacon.api https://sepolia.lightclient.xyz --beacon.checkpoint 0x0014732c89a02315d2ada0ed2f63b32ecb8d08751c01bea39011b31ad9ecee36 +``` + +### Running `blsync` as a Standalone Tool + +As mentioned before, `blsync` can be run in standalone mode. This will be similar to running a consensus client with low resource requirements and faster sync times. In most cases Geth users can use the integrated mode for convenience. The standalone mode can be used e.g. to drive an execution client other than Geth. + +#### Installing + +Depending on your [installation method](/docs/getting-started/installing-geth) either you have access to the `blsync` binary or you will have to build it from source by: + +```terminal +go build ./cmd/blsync +``` + +#### Running + +Blsync takes the same flags as above to configure the HTTP endpoint as well as checkpoint. It additionally needs flags to connect to the execution client. Specifically `--blsync.engine.api` to configure the Engine API url and `--blsync.jwtsecret` for the JWT authentication token. + +Again to sync the Sepolia network in this mode, first run Geth: + +```terminal +./build/bin/geth --sepolia --datadir light-sepolia-dir +``` + +The logs will indicate the Engine API path which is by default `http://localhost:8551` and the path to the JWT secret created which is in this instance `./light-sepolia-dir/geth/jwtsecret`. Now blsync can be run: + +```terminal +./blsync --sepolia --beacon.api https://sepolia.lightclient.xyz --beacon.checkpoint 0x0014732c89a02315d2ada0ed2f63b32ecb8d08751c01bea39011b31ad9ecee36 --blsync.engine.api http://localhost:8551 --blsync.jwtsecret light-sepolia-dir/geth/jwtsecret + +INFO [06-23|15:06:33.388] Loaded JWT secret file path=light-sepolia-dir/geth/jwtsecret crc32=0x5a92678 +INFO [06-23|15:06:34.130] Successful NewPayload number=6,169,314 hash=d4204e..772e65 status=SYNCING +INFO [06-23|15:06:34.130] Successful ForkchoiceUpdated head=d4204e..772e65 status=SYNCING +``` diff --git a/docs/getting-started/consensus-clients.md b/docs/getting-started/consensus-clients.md index 7e7b1bd0ed..f12b6fba5b 100644 --- a/docs/getting-started/consensus-clients.md +++ b/docs/getting-started/consensus-clients.md @@ -7,6 +7,8 @@ Geth is an [execution client](https://ethereum.org/en/glossary/#execution-client There are five consensus clients available, all of which connect to Geth in the same way. This page will outline how Geth can be set up with a consensus client to form a complete Ethereum node. +As an alternative it is possible to run with an integrated beacon light client for non-production settings. Please refer to [this](/docs/fundamentals/blsync) guide. + ## Configuring Geth {#configuring-geth} Geth can be downloaded and installed according to the instructions on the [Installing Geth](/docs/getting-started/installing-geth) page. In order to connect to a consensus client, Geth must expose a port for the inter-client RPC connection. diff --git a/src/data/documentation-links.yaml b/src/data/documentation-links.yaml index ae310df91f..f190724ec1 100644 --- a/src/data/documentation-links.yaml +++ b/src/data/documentation-links.yaml @@ -20,6 +20,8 @@ to: /docs/fundamentals/security - id: Sync-modes to: /docs/fundamentals/sync-modes + - id: Beacon light sync + to: /docs/fundamentals/blsync - id: Account management to: /docs/fundamentals/account-management - id: Databases