Update Getting Started guide (#24357)

This makes the text easier to follow for beginners.

Co-authored-by: Felix Lange <fjl@twurst.com>

Gemfile.lock

@@ -0,0 +1,309 @@
+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

docs/_getting-started/index.md

@@ -4,197 +4,440 @@ permalink: docs/getting-started
 sort_key: A
 ---
 
-To use Geth, you need to install it first. You can install Geth in a variety
-of ways that you can find in the "[Install and Build](install-and-build/installing-geth)" section.
-These include installing it via your favorite package manager, downloading a
-standalone pre-built binary, running it as a docker container or building it yourself.
 
-For this guide, we assume you have Geth installed and are ready to find out how to use it.
-The guide shows you how to create accounts, sync to a network, and then send transactions
-between accounts.
+To use Geth, you need to install it first. You can install Geth in various ways that you
+can find in the “[Install and Build](install-and-build/installing-geth)” section. These
+include installing it via your favorite package manager, downloading a standalone
+pre-built binary, running it as a docker container, or building it yourself.
 
-This guide uses [Clef](clef/tutorial), which is our preferred tool for signing transactions with Geth,
-and will replace Geth's account management.
+We assume you have Geth installed for this guide and are ready to find out how to use it.
+The guide shows you how to create accounts, sync to a network, and send transactions
+between accounts. This guide also uses [Clef](clef/tutorial), our preferred tool for
+signing transactions with Geth.
 
-## Initialize Clef
+#### Networks
 
-First, initialize Clef with a random master seed, which is also encrypted with the password you define.
-The password must be at least 10 characters.
+You can connect a Geth node to several different networks using the network name as an
+argument. These include the main Ethereum network, [a private network](getting-started/private-net) you create,
+and three test networks:
 
-```shell
-clef init
-```
+- **Ropsten:** Proof-of-work test network
+- **Rinkeby:** Proof-of-authority test network
+- **Görli:** Proof-of-authority test network
 
-![Clef init command](../../static/images/clef-init.gif)
+#### Sync modes
 
-## Create accounts
+You can start Geth in one of three different sync modes using the `--syncmode "<mode>"`
+argument that determines what sort of node it is in the network. These are:
 
-Create two accounts with the `clef newaccount` command,
-set a password for each of them, and note the public address for each.
+- **Full:** Downloads all blocks (including headers, transactions, and receipts) and
+  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.
 
-![Create new account command](../../static/images/clef-account-new.gif)
+For this guide, we will use `light` sync.
 
-Clef outputs a debug message about `Failed to reload keystore contents`, we fix that in a later step.
+### Requirements for following this guide
 
-## Start Geth
+- Experience using the command line
+- Basic knowledge about Ethereum and testnets
+- Basic knowledge about HTTP and JavaScript
 
-### Networks
+## Step 1: Generate accounts
 
-You can connect a Geth node to several different networks using the network name as an argument.
-These include the main Ethereum network, [a private network](getting-started/private-net) you create,
-and three test networks that use different consensus algorithms:
+Use the command below to generate an account. When you create a new account with Clef, it
+will generate a new private key, encrypt it according to the [web3 keystore spec](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition),
+and store it in the keystore directory.
 
--   **Ropsten**: Proof-of-work test network
--   **Rinkeby**: Proof-of-authority test network
--   **Görli**: Proof-of-authority test network
+```shell
+clef newaccount --keystore geth-tutorial/keystore
+```
 
-For this guide, we use the Görli network. The default port is 30303, so you need to enable at least
-outgoing access from your node to that port.
+It will give you the result below:
 
-### Sync modes
+```terminal
+WARNING!
 
-You can start Geth in one of three different sync modes using the `--syncmode "<mode>"`
-argument that determines what sort of node it is in the network.
+Clef is an account management tool. It may, like any software, contain bugs.
+
+Please take care to
+- backup your keystore files,
+- verify that the keystore(s) can be opened with your password.
 
-These are:
+Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See the GNU General Public License for more details.
 
-- **Full**: Downloads all blocks (including headers, transactions, and receipts) and
-generates the state of the blockchain incrementally by executing every block.
-- **Snap** (Default): Same functionality as fast, but with a faster algorithm.   
-- **Light**: Downloads all block headers, block data, and verifies some randomly.
+Enter 'ok' to proceed:
+>
+```
 
-For this tutorial, we use a `light` sync:
+Type “ok” and press the enter key. Next, the Clef will prompt for a password. Enter your
+desired password and hit the enter key to get the result below:
 
+```terminal
+-----------------------
+DEBUG[02-10|13:46:46.436] FS scan times                            list="92.081µs" set="12.629µs" diff="2.129µs"
+INFO [02-10|13:46:46.592] Your new key was generated               address=0xCe8dBA5e4157c2B284d8853afEEea259344C1653
+WARN [02-10|13:46:46.595] Please backup your key file!             path=keystore:///.../geth-tutorial/keystore/UTC--2022-02-07T17-19-56.517538000Z--ca57f3b40b42fcce3c37b8d18adbca5260ca72ec
+WARN [02-10|13:46:46.595] Please remember your password!
+Generated account 0xCe8dBA5e4157c2B284d8853afEEea259344C1653
+```
 
-## Start Clef
+Save your password and the generated account address because you will need them later in
+this tutorial.
 
-Start Clef, setting the keystore and chain id (goerli is 5) for the network we want to connect to:
+**In the remainder of this guide, we will use this account as the main account for
+testing:**
 
 ```shell
-clef --keystore <GETH_DATA_DIR>/keystore --chainid 5
+0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC
 ```
 
-To begin with, you see errors about a missing keystore, and we fix that soon.
+When you follow the tutorial locally, your account address will be different and you will
+need to supply your own account address in all command invocations.
+
+**Please generate a second account by repeating this step one more time.**
+
+## Step 2:  Start Clef
+
+To start clef, open a new terminal and run the command below. Keeping clef running is
+required for the other steps because it signs transactions.
+
+```shell
+clef --keystore geth-tutorial/keystore --configdir geth-tutorial/clef --chainid 5
+```
 
-Under Linux the default Geth data directory is `~/.ethereum`
+> Note: geth-tutorial is the directory holding your keystore.
+
+After running the command above, clef will request you to type “ok” to proceed.
+
+A successful call will give you the result below:
+
+```terminal
+INFO [02-10|13:55:30.812] Using CLI as UI-channel
+INFO [02-10|13:55:30.946] Loaded 4byte database                    embeds=146,841 locals=0 local=./4byte-custom.json
+WARN [02-10|13:55:30.947] Failed to open master, rules disabled    err="failed stat on geth-tutorial/clef/masterseed.json: stat geth-tutorial/clef/masterseed.json: no such file or directory"
+INFO [02-10|13:55:30.947] Starting signer                          chainid=5 keystore=geth-tutorial/keystore light-kdf=false advanced=false
+DEBUG[02-10|13:55:30.948] FS scan times                            list="133.35µs" set="5.692µs" diff="3.262µs"
+DEBUG[02-10|13:55:30.970] Ledger support enabled
+DEBUG[02-10|13:55:30.973] Trezor support enabled via HID
+DEBUG[02-10|13:55:30.976] Trezor support enabled via WebUSB
+INFO [02-10|13:55:30.978] Audit logs configured                    file=audit.log
+DEBUG[02-10|13:55:30.981] IPCs registered                          namespaces=account
+INFO [02-10|13:55:30.984] IPC endpoint opened                      url=geth-tutorial/clef/clef.ipc
+------- Signer info -------
+* intapi_version : 7.0.1
+* extapi_version : 6.1.0
+* extapi_http : n/a
+* extapi_ipc : geth-tutorial/clef/clef.ipc
+```
 
-## Start Geth
+## Step 3:  Start Geth
 
-Open another command line window and run command below, which also enables the 
-[Geth RPC interface](clef/tutorial) (see below), and sets Clef as the transaction signer.
+To start geth, open a new terminal and run the command brlow. Keeping geth running is
+required for the other steps because the command below starts the HTTP server that we will
+be interacting with.
 
 ```shell
-geth --goerli --syncmode "light" --http --signer=<CLEF_LOCATION>/clef.ipc
+geth --datadir geth-tutorial --signer=geth-tutorial/clef/clef.ipc --goerli --syncmode light --http
+```
+
+A successful call will print log messages like the following:
+
+```terminal
+INFO [02-10|13:59:06.649] Starting Geth on Görli testnet...
+INFO [02-10|13:59:06.649] Dropping default light client cache      provided=1024 updated=128
+INFO [02-10|13:59:06.652] Maximum peer count                       ETH=0 LES=10 total=50
+INFO [02-10|13:59:06.655] Using external signer                    url=geth-tutorial/clef/clef.ipc
+INFO [02-10|13:59:06.660] Set global gas cap                       cap=50,000,000
+INFO [02-10|13:59:06.661] Allocated cache and file handles         database=/.../geth-tutorial/geth/lightchaindata cache=64.00MiB handles=5120
+INFO [02-10|13:59:06.794] Allocated cache and file handles         database=/.../geth-tutorial/geth/les.client cache=16.00MiB handles=16
+INFO [02-10|13:59:06.855] Persisted trie from memory database      nodes=361 size=51.17KiB time="643.54µs" gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B
+INFO [02-10|13:59:06.855] Initialised chain configuration          config="{ChainID: 5 Homestead: 0 DAO: <nil> DAOSupport: true EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0 Constantinople: 0 Petersburg: 0 Istanbul: 1561651, Muir Glacier: <nil>, Berlin: 4460644, London: 5062605, Arrow Glacier: <nil>, MergeFork: <nil>, Engine: clique}"
+INFO [02-10|13:59:06.862] Added trusted checkpoint                 block=5,799,935 hash=2de018..c32427
+INFO [02-10|13:59:06.863] Loaded most recent local header          number=6,340,934 hash=483cf5..858315 td=9,321,576 age=2d9h29m
+INFO [02-10|13:59:06.867] Configured checkpoint oracle             address=0x18CA0E045F0D772a851BC7e48357Bcaab0a0795D signers=5 threshold=2
+INFO [02-10|13:59:06.867] Gasprice oracle is ignoring threshold set threshold=2
+WARN [02-10|13:59:06.869] Unclean shutdown detected                booted=2022-02-08T04:25:08+0100 age=2d9h33m
+INFO [02-10|13:59:06.870] Starting peer-to-peer node               instance=Geth/v1.10.15-stable/darwin-amd64/go1.17.5
+INFO [02-10|13:59:06.995] New local node record                    seq=1,644,272,735,880 id=d4ffcd252d322a89 ip=127.0.0.1 udp=30303 tcp=30303
+INFO [02-10|13:59:06.996] Started P2P networking                   self=enode://4b80ebd341b5308f7a6b61d91aa0ea31bd5fc9e0a6a5483e59fd4ea84e0646b13ecd289e31e00821ccedece0bf4b9189c474371af7393093138f546ac23ef93e@127.0.0.1:30303
+INFO [02-10|13:59:06.997] IPC endpoint opened                      url=/.../geth-tutorial/geth.ipc
+INFO [02-10|13:59:06.998] HTTP server started                      endpoint=127.0.0.1:8545 prefix= cors= vhosts=localhost
+WARN [02-10|13:59:06.998] Light client mode is an experimental feature
+WARN [02-10|13:59:06.999] Failed to open wallet                    url=extapi://geth-tutorial/clef/cle.. err="operation not supported on external signers"
+INFO [02-10|13:59:08.793] Block synchronisation started
 ```
 
-By default Clef's location under Linux is `~/.clef`, but the signer's location cannot
-include a `~` so replace it with your home directory.
+> **Note:** keep this terminal window open.
 
-## Get ETH
+## Step 4:  Get Goerli Testnet Ether
 
-Unless you have Ether in another account on the Görli network, you can use a
-[faucet](https://goerli-faucet.slock.it/) to send ETH to one of your new account addresses to use for this guide.
+We will now top up the test account ether balance, so that it can send transactions. You
+can get Goerli testnet ether at several faucet sites. We recommend you try one of these
+faucets:
 
-## Connect to Geth with IPC or RPC
+- <https://faucets.chain.link/goerli>
+- <https://fauceth.komputing.org/?chain=5>
 
-You can interact with Geth in two ways: Directly with the node using the JavaScript
-console over IPC, or connecting to the node remotely over HTTP using RPC.
+Just enter your address on one of those sites and follow the instructions provided.
 
-IPC allows you to do more, especially when it comes to creating and interacting
-with accounts, but you need direct access to the node.
+## Step 5: Interact with Geth via IPC or RPC
 
-RPC allows remote applications to access your node but has limitations and security
-considerations, and by default only allows access to methods in the `eth` and `shh`
-namespaces. Find out how to override this setting [in the RPC docs](rpc/server#http-server).
+For interacting with the blockchain, Geth provides JSON-RPC APIs. A good way to get
+started with the API is by using the Geth JavaScript console. The console gives you a
+JavaScript environment similar to node.js and comes with Geth.
 
-## Using IPC
+You can connect to the Geth node using HTTP or IPC.
 
-### Connect to console
+- IPC (Inter-Process Communication): This provides unrestricted access to all APIs,
+  but only works when you are running the console on the same host as the geth node.
+- HTTP: This connection method provides access to the `eth`, `web3` and `net` method
+  namespaces. We will be using HTTP for this guide.
 
-Connect to the IPC console on a node from another terminal window:
+To connect to Geth using the console, open a new terminal and run this command:
 
 ```shell
-geth attach <IPC_LOCATION>
+geth attach http://127.0.0.1:8545
+```
+
+The `attach` subcommand starts the console and should print a welcome message similar to
+the text shown below:
+
+```terminal
+Welcome to the Geth JavaScript console!
+
+instance: Geth/v1.10.15-stable/darwin-amd64/go1.17.5
+at block: 6354736 (Thu Feb 10 2022 14:01:46 GMT+0100 (WAT))
+ modules: eth:1.0 net:1.0 rpc:1.0 web3:1.0
+
+To exit, press ctrl-d or type exit
 ```
 
-You can see the IPC location in the output of the network node `geth` process. By default, when using
-Görli, it is `~/.ethereum/goerli/geth.ipc`.
+### Checking your test account balance.
 
-### Check account balance
+Run this command in the JavaScript console to check the ether balance of the test account:
 
 ```javascript
-web3.fromWei(eth.getBalance("<ADDRESS_1>"),"ether")
+web3.fromWei(eth.getBalance("0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC"), "ether")
+```
+
+**Result:**
+
+```terminal
+> 0.1
+```
+
+### Getting the list of accounts
+
+Run the command below to get the list of accounts in your keystore.
+
+ ```javascript
+ eth.accounts
+ ```
+
+**Note: Since the accounts are provided by Clef in this tutorial, you must accept the
+account list request in the terminal window running Clef:***
+
+```terminal
+-------- List Account request--------------
+A request has been made to list all accounts.
+You can select which accounts the caller can see
+  [x] 0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC
+    URL: keystore:///.../geth-tutorial/keystore/UTC--2022-02-07T17-19-56.517538000Z--ca57f3b40b42fcce3c37b8d18adbca5260ca72ec
+  [x] 0xCe8dBA5e4157c2B284d8853afEEea259344C1653
+    URL: keystore:///.../geth-tutorial/keystore/UTC--2022-02-10T12-46-45.265592000Z--ce8dba5e4157c2b284d8853afeeea259344c1653
+-------------------------------------------
+Request context:
+        NA -> ipc -> NA
+
+Additional HTTP header data, provided by the external caller:
+        User-Agent: ""
+        Origin: ""
+Approve? [y/N]:
+> y
+
 ```
 
-Getting the balance of an account does not require a signed transaction,
-so Clef does not ask for approval, and Geth returns the value.
+Now you should get a result in the JavaScript console.
+
+**Result:**
 
-Note that this step requires the initial synchronization to end. If you get an error message, return to the 
-console with the network node Geth and wait until it is synchronized. You
-know that your Geth is synchronized when it is only importing a small number of blocks (one or two, usually)
-at a time.
+```terminal
+["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", "0xce8dba5e4157c2b284d8853afeeea259344c1653"]
+```
+
+If you didn't get a result (e.g. an exception was raised), it may be because the account
+listing request timed out while you were entering the password. Just try again in this
+case.
 
-### Send ETH to account
+### Send ether to another account
 
-Send 0.01 ETH from the account that you added ETH to with the Görli faucet,
-to the second account you created:
+Run the command below to transfer 0.01 ether to the other account you created.
 
 ```javascript
-eth.sendTransaction({from:"<ADDRESS_1>",to:"<ADDRESS_2>", value: web3.toWei(0.01,"ether")})
+eth.sendTransaction({
+    from: "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec",
+    to: "0xce8dba5e4157c2b284d8853afeeea259344c1653",
+    value: web3.toWei(0.01, "ether")
+})
+```
+
+**Again, since the test account is stored by Clef, you must confirm the request in the Clef
+terminal window.**
+
+Clef will prompt you to approve the transaction, and when you do, it will ask you for the
+password for the account you are sending the ether from. If the password is correct, Geth
+proceeds with the transaction.
+
+```terminal
+--------- Transaction request-------------
+to:    0xCe8dBA5e4157c2B284d8853afEEea259344C1653
+from:               0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC [chksum ok]
+value:              10000000000000000 wei
+gas:                0x5208 (21000)
+maxFeePerGas:          2425000057 wei
+maxPriorityFeePerGas:  2424999967 wei
+nonce:    0x3 (3)
+chainid:  0x5
+Accesslist
+
+Request context:
+        NA -> ipc -> NA
+
+Additional HTTP header data, provided by the external caller:
+        User-Agent: ""
+        Origin: ""
+-------------------------------------------
+Approve? [y/N]:
+> y
+## Account password
+
+Please enter the password for account 0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC
+>
+```
+
+After approving the transaction, you will see the below screen in the Clef terminal.
+
+```terminal
+-----------------------
+Transaction signed:
+ {
+    "type": "0x2",
+    "nonce": "0x3",
+    "gasPrice": null,
+    "maxPriorityFeePerGas": "0x908a901f",
+    "maxFeePerGas": "0x908a9079",
+    "gas": "0x5208",
+    "value": "0x2386f26fc10000",
+    "input": "0x",
+    "v": "0x0",
+    "r": "0x66e5d23ad156e04363e68b986d3a09e879f7fe6c84993cef800bc3b7ba8af072",
+    "s": "0x647ff82be943ea4738600c831c4a19879f212eb77e32896c05055174045da1bc",
+    "to": "0xce8dba5e4157c2b284d8853afeeea259344c1653",
+    "chainId": "0x5",
+    "accessList": [],
+    "hash": "0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb"
+  }
+
 ```
 
-This action does require signing the transaction, so go to the command line window with Clef running 
-to see that Clef prompts you to approve it, and when you do, asks you for the password for the account you are 
-sending the ETH from. If the password is correct, Geth proceeds with the transaction.
+**Result:**
 
-To check, get the account balance of the second account:
+You will get the transaction hash response in the Geth JavaScript console after approving
+the transaction in Clef.
+
+```terminal
+"0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb"
+```
+
+### Checking the transaction hash
+
+To get the transaction hash, Run the command below.
 
 ```javascript
-web3.fromWei(eth.getBalance("<ADDRESS_2>"),"ether")
+eth.getTransaction("0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb")
 ```
 
-## Using RPC
+If successful, you will get a response like the one below:
+
+```terminal
+{
+  accessList: [],
+  blockHash: "0x1c5d3f8dd997b302935391b57dc3e4fffd1fa2088ef2836d51f844f993eb39c4",
+  blockNumber: 6355150,
+  chainId: "0x5",
+  from: "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec",
+  gas: 21000,
+  gasPrice: 2425000023,
+  hash: "0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb",
+  input: "0x",
+  maxFeePerGas: 2425000057,
+  maxPriorityFeePerGas: 2424999967,
+  nonce: 3,
+  r: "0x66e5d23ad156e04363e68b986d3a09e879f7fe6c84993cef800bc3b7ba8af072",
+  s: "0x647ff82be943ea4738600c831c4a19879f212eb77e32896c05055174045da1bc",
+  to: "0xce8dba5e4157c2b284d8853afeeea259344c1653",
+  transactionIndex: 630,
+  type: "0x2",
+  v: "0x0",
+  value: 10000000000000000
+}
+```
+
+## Access using low-level HTTP
+
+In this part of the tutorial, we will show how to access the JSON-RPC API using curl.
 
-### Connect to RPC
+### Checking account balance
 
-You can use standard HTTP requests to connect to a Geth node using the RPC APIs, using
-this syntax:
+To check account balance, use the command below.
 
 ```shell
-curl -X POST http://<GETH_IP_ADDRESS>:8545 \
-    -H "Content-Type: application/json" \
-   --data'{"jsonrpc":"2.0", "method":"<API_METHOD>", "params":[], "id":1}'
+curl -X POST http://127.0.0.1:8545 \
+  -H "Content-Type: application/json" \
+  --data '{"jsonrpc":"2.0", "method":"eth_getBalance", "params":["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec","latest"], "id":1}'
 ```
 
-### Check account balance
+A successful call will return a response like the one below:
 
-```shell
-curl -X POST http://<GETH_IP_ADDRESS>:8545 \
-    -H "Content-Type: application/json" \
-   --data '{"jsonrpc":"2.0", "method":"eth_getBalance", "params":["<ADDRESS_1>","latest"], "id":1}'
+```terminal
+{"jsonrpc":"2.0","id":1,"result":"0xcc445d3d4b89390"}
 ```
 
-Getting the balance of an account does not require a signed transaction, so Geth returns the value without invoking
-Clef. Note that the value returned is in hexadecimal and WEI. To get the ETH value, convert to decimal and divide by 10^18.
+Note that the value returned is in hexadecimal and WEI. To get the balance in ether,
+convert to decimal and divide by 10^18.
 
-### Send ETH to accounts
+### Checking the account list
 
-Send 0.01 ETH from the account that you added ETH to with the Görli faucet, to the second account you created:
+Run the command below to get the list of all accounts.
 
 ```shell
-curl -X POST http://<GETH_IP_ADDRESS>:8545 \
-    -H "Content-Type: application/json" \
-   --data '{"jsonrpc":"2.0", "method":"eth_sendTransaction", "params":[{"from": "<ADDRESS_1>","to": "<ADDRESS_2>","value": "0x9184e72a"}], "id":1}'
+curl -X POST http://127.0.0.1:8545 \
+    -H "Content-Type: application/json" \
+   --data '{"jsonrpc":"2.0", "method":"eth_accounts","params":[], "id":1}'
 ```
 
-This action does require signing, so Clef prompts you to approve it, and if you do,
-asks you for the password of the account from which you are sending the ETH. If the password is correct,
-Geth proceeds with the transaction.
+Note: you will need to confirm this request in the Clef terminal window.a
+
+**Response:**
+
+```terminal
+{"jsonrpc":"2.0","id":1,"result":["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec"]}
+```
 
-To check, get the account balance of the second account:
+### Sending Transactions
 
 ```shell
-curl -X POST http://<GETH_IP_ADDRESS>:8545 \
-    -H "Content-Type: application/json" \
-    --data '{"jsonrpc":"2.0", "method":"eth_getBalance", "params":["<ADDRESS_2>","latest"], "id":1}'
+curl -X POST http://127.0.0.1:8545 \
+    -H "Content-Type: application/json" \
+   --data '{"jsonrpc":"2.0", "method":"eth_sendTransaction", "params":[{"from": "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec","to": "0xce8dba5e4157c2b284d8853afeeea259344c1653","value": "0x2386F26FC10000"}], "id":1}'
+```
+
+A successful call will return a response containing the transaction hash.
+
+```terminal
+{"jsonrpc":"2.0","id":5,"result":"0xac8b347d70a82805edb85fc136fc2c4e77d31677c2f9e4e7950e0342f0dc7e7c"}
 ```

static/styles/custom/vss.css

@@ -35,4 +35,5 @@
 .highlight .sx { color: #a31515 } /* Literal.String.Other */
 .highlight .sr { color: #a31515 } /* Literal.String.Regex */
 .highlight .s1 { color: #a31515 } /* Literal.String.Single */
-.highlight .ss { color: #a31515 } /* Literal.String.Symbol */
+.highlight .ss { color: #a31515 } /* Literal.String.Symbol */
+.language-terminal .highlight{background: #030303; color: #ffffff;}