From 688413493500b367d3d6eb2480b60742fd23c297 Mon Sep 17 00:00:00 2001 From: Sina Mahmoodi <1591639+s1na@users.noreply.github.com> Date: Fri, 8 Apr 2022 00:15:47 +0200 Subject: [PATCH] doc: add page on light clients (#24647) * Add light client page * Rm gemfile.lock * add section on ulc * update compose file syntax --- Gemfile.lock | 309 --------------------------------- docker-compose.yml | 15 +- docs/_getting-started/index.md | 2 +- docs/_interface/les.md | 48 +++++ 4 files changed, 57 insertions(+), 317 deletions(-) delete mode 100644 Gemfile.lock create mode 100644 docs/_interface/les.md diff --git a/Gemfile.lock b/Gemfile.lock deleted file mode 100644 index 7abfafa8a8..0000000000 --- a/Gemfile.lock +++ /dev/null @@ -1,309 +0,0 @@ -GEM - remote: https://rubygems.org/ - specs: - activesupport (6.0.4.4) - concurrent-ruby (~> 1.0, >= 1.0.2) - i18n (>= 0.7, < 2) - minitest (~> 5.1) - tzinfo (~> 1.1) - zeitwerk (~> 2.2, >= 2.2.2) - addressable (2.8.0) - public_suffix (>= 2.0.2, < 5.0) - coderay (1.1.3) - coffee-script (2.4.1) - coffee-script-source - execjs - coffee-script-source (1.11.1) - colorator (1.1.0) - commonmarker (0.17.13) - ruby-enum (~> 0.5) - concurrent-ruby (1.1.9) - dnsruby (1.61.9) - simpleidn (~> 0.1) - em-websocket (0.5.3) - eventmachine (>= 0.12.9) - http_parser.rb (~> 0) - ethon (0.15.0) - ffi (>= 1.15.0) - eventmachine (1.2.7) - execjs (2.8.1) - faraday (1.9.3) - faraday-em_http (~> 1.0) - faraday-em_synchrony (~> 1.0) - faraday-excon (~> 1.1) - faraday-httpclient (~> 1.0) - faraday-multipart (~> 1.0) - faraday-net_http (~> 1.0) - faraday-net_http_persistent (~> 1.0) - faraday-patron (~> 1.0) - faraday-rack (~> 1.0) - faraday-retry (~> 1.0) - ruby2_keywords (>= 0.0.4) - faraday-em_http (1.0.0) - faraday-em_synchrony (1.0.0) - faraday-excon (1.1.0) - faraday-httpclient (1.0.1) - faraday-multipart (1.0.3) - multipart-post (>= 1.2, < 3) - faraday-net_http (1.0.1) - faraday-net_http_persistent (1.2.0) - faraday-patron (1.0.0) - faraday-rack (1.0.0) - faraday-retry (1.0.3) - ffi (1.15.5) - forwardable-extended (2.6.0) - gemoji (3.0.1) - github-pages (223) - github-pages-health-check (= 1.17.9) - jekyll (= 3.9.0) - jekyll-avatar (= 0.7.0) - jekyll-coffeescript (= 1.1.1) - jekyll-commonmark-ghpages (= 0.1.6) - jekyll-default-layout (= 0.1.4) - jekyll-feed (= 0.15.1) - jekyll-gist (= 1.5.0) - jekyll-github-metadata (= 2.13.0) - jekyll-include-cache (= 0.2.1) - jekyll-mentions (= 1.6.0) - jekyll-optional-front-matter (= 0.3.2) - jekyll-paginate (= 1.1.0) - jekyll-readme-index (= 0.3.0) - jekyll-redirect-from (= 0.16.0) - jekyll-relative-links (= 0.6.1) - jekyll-remote-theme (= 0.4.3) - jekyll-sass-converter (= 1.5.2) - jekyll-seo-tag (= 2.7.1) - jekyll-sitemap (= 1.4.0) - jekyll-swiss (= 1.0.0) - jekyll-theme-architect (= 0.2.0) - jekyll-theme-cayman (= 0.2.0) - jekyll-theme-dinky (= 0.2.0) - jekyll-theme-hacker (= 0.2.0) - jekyll-theme-leap-day (= 0.2.0) - jekyll-theme-merlot (= 0.2.0) - jekyll-theme-midnight (= 0.2.0) - jekyll-theme-minimal (= 0.2.0) - jekyll-theme-modernist (= 0.2.0) - jekyll-theme-primer (= 0.6.0) - jekyll-theme-slate (= 0.2.0) - jekyll-theme-tactile (= 0.2.0) - jekyll-theme-time-machine (= 0.2.0) - jekyll-titles-from-headings (= 0.5.3) - jemoji (= 0.12.0) - kramdown (= 2.3.1) - kramdown-parser-gfm (= 1.1.0) - liquid (= 4.0.3) - mercenary (~> 0.3) - minima (= 2.5.1) - nokogiri (>= 1.12.5, < 2.0) - rouge (= 3.26.0) - terminal-table (~> 1.4) - github-pages-health-check (1.17.9) - addressable (~> 2.3) - dnsruby (~> 1.60) - octokit (~> 4.0) - public_suffix (>= 3.0, < 5.0) - typhoeus (~> 1.3) - html-pipeline (2.14.0) - activesupport (>= 2) - nokogiri (>= 1.4) - html-proofer (3.19.3) - addressable (~> 2.3) - mercenary (~> 0.3) - nokogiri (~> 1.12) - parallel (~> 1.3) - rainbow (~> 3.0) - typhoeus (~> 1.3) - yell (~> 2.0) - http_parser.rb (0.8.0) - i18n (0.9.5) - concurrent-ruby (~> 1.0) - jekyll (3.9.0) - addressable (~> 2.4) - colorator (~> 1.0) - em-websocket (~> 0.5) - i18n (~> 0.7) - jekyll-sass-converter (~> 1.0) - jekyll-watch (~> 2.0) - kramdown (>= 1.17, < 3) - liquid (~> 4.0) - mercenary (~> 0.3.3) - pathutil (~> 0.9) - rouge (>= 1.7, < 4) - safe_yaml (~> 1.0) - jekyll-avatar (0.7.0) - jekyll (>= 3.0, < 5.0) - jekyll-coffeescript (1.1.1) - coffee-script (~> 2.2) - coffee-script-source (~> 1.11.1) - jekyll-commonmark (1.3.1) - commonmarker (~> 0.14) - jekyll (>= 3.7, < 5.0) - jekyll-commonmark-ghpages (0.1.6) - commonmarker (~> 0.17.6) - jekyll-commonmark (~> 1.2) - rouge (>= 2.0, < 4.0) - jekyll-default-layout (0.1.4) - jekyll (~> 3.0) - jekyll-feed (0.15.1) - jekyll (>= 3.7, < 5.0) - jekyll-gist (1.5.0) - octokit (~> 4.2) - jekyll-github-metadata (2.13.0) - jekyll (>= 3.4, < 5.0) - octokit (~> 4.0, != 4.4.0) - jekyll-include-cache (0.2.1) - jekyll (>= 3.7, < 5.0) - jekyll-mentions (1.6.0) - html-pipeline (~> 2.3) - jekyll (>= 3.7, < 5.0) - jekyll-optional-front-matter (0.3.2) - jekyll (>= 3.0, < 5.0) - jekyll-paginate (1.1.0) - jekyll-readme-index (0.3.0) - jekyll (>= 3.0, < 5.0) - jekyll-redirect-from (0.16.0) - jekyll (>= 3.3, < 5.0) - jekyll-relative-links (0.6.1) - jekyll (>= 3.3, < 5.0) - jekyll-remote-theme (0.4.3) - addressable (~> 2.0) - jekyll (>= 3.5, < 5.0) - jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) - rubyzip (>= 1.3.0, < 3.0) - jekyll-sass-converter (1.5.2) - sass (~> 3.4) - jekyll-seo-tag (2.7.1) - jekyll (>= 3.8, < 5.0) - jekyll-sitemap (1.4.0) - jekyll (>= 3.7, < 5.0) - jekyll-swiss (1.0.0) - jekyll-theme-architect (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-cayman (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-dinky (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-hacker (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-leap-day (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-merlot (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-midnight (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-minimal (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-modernist (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-primer (0.6.0) - jekyll (> 3.5, < 5.0) - jekyll-github-metadata (~> 2.9) - jekyll-seo-tag (~> 2.0) - jekyll-theme-slate (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-tactile (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-time-machine (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-titles-from-headings (0.5.3) - jekyll (>= 3.3, < 5.0) - jekyll-watch (2.2.1) - listen (~> 3.0) - jemoji (0.12.0) - gemoji (~> 3.0) - html-pipeline (~> 2.2) - jekyll (>= 3.0, < 5.0) - kramdown (2.3.1) - rexml - kramdown-parser-gfm (1.1.0) - kramdown (~> 2.0) - liquid (4.0.3) - listen (3.7.1) - rb-fsevent (~> 0.10, >= 0.10.3) - rb-inotify (~> 0.9, >= 0.9.10) - mercenary (0.3.6) - method_source (1.0.0) - mini_portile2 (2.7.1) - minima (2.5.1) - jekyll (>= 3.5, < 5.0) - jekyll-feed (~> 0.9) - jekyll-seo-tag (~> 2.1) - minitest (5.15.0) - multipart-post (2.1.1) - nokogiri (1.13.1) - mini_portile2 (~> 2.7.0) - racc (~> 1.4) - octokit (4.22.0) - faraday (>= 0.9) - sawyer (~> 0.8.0, >= 0.5.3) - parallel (1.21.0) - pathutil (0.16.2) - forwardable-extended (~> 2.6) - pry (0.14.1) - coderay (~> 1.1) - method_source (~> 1.0) - public_suffix (4.0.6) - racc (1.6.0) - rainbow (3.1.1) - rb-fsevent (0.11.1) - rb-inotify (0.10.1) - ffi (~> 1.0) - rexml (3.2.5) - rouge (3.26.0) - ruby-enum (0.9.0) - i18n - ruby2_keywords (0.0.5) - rubyzip (2.3.2) - safe_yaml (1.0.5) - sass (3.7.4) - sass-listen (~> 4.0.0) - sass-listen (4.0.0) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - sawyer (0.8.2) - addressable (>= 2.3.5) - faraday (> 0.8, < 2.0) - simpleidn (0.2.1) - unf (~> 0.1.4) - terminal-table (1.8.0) - unicode-display_width (~> 1.1, >= 1.1.1) - thread_safe (0.3.6) - typhoeus (1.4.0) - ethon (>= 0.9.0) - tzinfo (1.2.9) - thread_safe (~> 0.1) - unf (0.1.4) - unf_ext - unf_ext (0.0.8) - unicode-display_width (1.8.0) - webrick (1.7.0) - yell (2.2.2) - zeitwerk (2.5.4) - -PLATFORMS - ruby - -DEPENDENCIES - github-pages - html-proofer - jekyll-feed (~> 0.6) - minima (~> 2.0) - pry - tzinfo-data - webrick - -BUNDLED WITH - 1.17.2 diff --git a/docker-compose.yml b/docker-compose.yml index 30403fab50..f47f6ebfa4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,7 +1,8 @@ -jekyll: - image: jekyll/jekyll:latest - command: jekyll serve --watch --incremental - ports: - - 4000:4000 - volumes: - - .:/srv/jekyll \ No newline at end of file +services: + jekyll: + image: jekyll/jekyll:latest + command: jekyll serve --watch --incremental + ports: + - 4000:4000 + volumes: + - .:/srv/jekyll diff --git a/docs/_getting-started/index.md b/docs/_getting-started/index.md index 016f12a879..87214bd582 100644 --- a/docs/_getting-started/index.md +++ b/docs/_getting-started/index.md @@ -34,7 +34,7 @@ argument that determines what sort of node it is in the network. These are: generates the state of the blockchain incrementally by executing every block. - **Snap:** (Default): Downloads all blocks and a recent version of the state. - **Light:** The node only downloads a few recent block headers, and downloads - other data on-demand. + other data on-demand. See this [page](../interface/les) for more info. For this guide, we will use `light` sync. diff --git a/docs/_interface/les.md b/docs/_interface/les.md new file mode 100644 index 0000000000..125c7e8bdc --- /dev/null +++ b/docs/_interface/les.md @@ -0,0 +1,48 @@ +--- +title: Light client +sort_key: B +--- + +*Note*: Light client is an experimental feature. Please consider this before using it with large funds. + +In addition to the full client, geth supports a light mode which has several advantages for end users: + +- Syncing takes minutes instead of hours (for snap sync) or days (for full sync) +- It uses significantly less storage, e.g. less than 1Gb for a node light-synced to mainnet +- It is lighter on CPU and possibly other resources +- It is hence suitable for resource-contrained devices +- It can catch up much quicker after having been offline for a while + +What's the catch you might ask? They are heavily dependant on as of now altruistic light servers. These are full nodes that volunteer to serve data to light clients and which can be easily overwhelmed as the number of clients increase. + +They also have slightly different security guarantees. Because they don't keep the Ethereum state, they can't validate the blocks in the same way as the full nodes. Instead they fetch block headers and check their Proof-of-Work, assuming the heaviest chain is valid. What this means for you is that if you want to be on the safe side it's advisable to wait for a few blocks worth of confirmations before trusting the validity of a recently mined transaction. + +#### Light server + +By enabling light serving on your full node you'll help the network and light clients. Naturally you might want to cap the amount of resources you dedicate to serving light clients. That's why the same flag that enables this feature also requires you to specify how much resources to dedicate to serving clients. `--light.serve ` takes a percentage as value. Number bigger than 100 indicate you want to dedicate more than one thread to this feature, e.g. `--light.serve 200` for 2 cores. + +Something else you need to note is that since v1.9.14 geth unindexes old transactions to save space. This limits what clients can request. A node with unindexed transactions also can't serve lesv4 clients due to lack of support. Please keep this in mind and if possible disable unindexing by adding `--txlookuplimit 0`. + +E.g. the whole command could see as follows: + +```sh +geth --light.serve 50 --txlookuplimit 0 +``` + +#### Light client + +To run a light client you specify sync mode to be light. In addition to syncing you probably also want to interact with the node, say through RPC. So Let's enable that too: + +```sh +geth --syncmode light --http --http.api "eth,debug" +``` + +Now you can request data from the RPC endpoint just like as in a full node and the light client will fetch the necessary data from servers in the background. You can also send transactions. But note that light clients do not join the main ethereum network (`eth`) so they can't propagate transactions themselves but rather give this to light servers which propagate it on their behalf. + +##### Ultra light client + +Geth has an even lighter sync mode called ultra light client (ULC). The difference is that an ULC doesn't check the Proof-of-Work in block headers. The assumption is that you have access to one or more light servers you are running yourself or that you trust. The command looks as follows: + +```sh +geth --syncmode light --ulc.servers "enode://...,enode://..." --http --http.api "eth,debug" +```