From 58cd25b166a1bbbcea0cbf67fb542e977a6b09ee Mon Sep 17 00:00:00 2001 From: Nwokocha wisdom maduabuchi Date: Thu, 17 Feb 2022 19:21:28 +0100 Subject: [PATCH] Update Getting Started guide (#24357) This makes the text easier to follow for beginners. Co-authored-by: Felix Lange --- Gemfile.lock | 309 ++++++++++++++++++++ docs/_getting-started/index.md | 497 ++++++++++++++++++++++++--------- static/styles/custom/vss.css | 3 +- 3 files changed, 681 insertions(+), 128 deletions(-) create mode 100644 Gemfile.lock diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 0000000000..7abfafa8a8 --- /dev/null +++ b/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 diff --git a/docs/_getting-started/index.md b/docs/_getting-started/index.md index d5a48d16b0..016f12a879 100644 --- a/docs/_getting-started/index.md +++ b/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) - -## Create accounts - -Create two accounts with the `clef newaccount` command, -set a password for each of them, and note the public address for each. - -![Create new account command](../../static/images/clef-account-new.gif) - -Clef outputs a debug message about `Failed to reload keystore contents`, we fix that in a later step. - -## Start Geth - -### Networks - -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: - --   **Ropsten**: Proof-of-work test network --   **Rinkeby**: Proof-of-authority test network --   **Görli**: Proof-of-authority test network - -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. - -### Sync modes +#### Sync modes You can start Geth in one of three different sync modes using the `--syncmode ""` -argument that determines what sort of node it is in the network. +argument that determines what sort of node it is in the network. These are: -These are: +- **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. -- **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. +For this guide, we will use `light` sync. -For this tutorial, we use a `light` sync: +### Requirements for following this guide +- Experience using the command line +- Basic knowledge about Ethereum and testnets +- Basic knowledge about HTTP and JavaScript -## Start Clef +## Step 1: Generate accounts -Start Clef, setting the keystore and chain id (goerli is 5) for the network we want to connect to: +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. ```shell -clef --keystore /keystore --chainid 5 +clef newaccount --keystore geth-tutorial/keystore ``` -To begin with, you see errors about a missing keystore, and we fix that soon. +It will give you the result below: -Under Linux the default Geth data directory is `~/.ethereum` +```terminal +WARNING! -## Start Geth +Clef is an account management tool. It may, like any software, contain bugs. -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. +Please take care to +- backup your keystore files, +- verify that the keystore(s) can be opened with your password. + +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. + +Enter 'ok' to proceed: +> +``` + +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 +``` + +Save your password and the generated account address because you will need them later in +this tutorial. + +**In the remainder of this guide, we will use this account as the main account for +testing:** ```shell -geth --goerli --syncmode "light" --http --signer=/clef.ipc +0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC ``` -By default Clef's location under Linux is `~/.clef`, but the signer's location cannot -include a `~` so replace it with your home directory. +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. -## Get ETH +**Please generate a second account by repeating this step one more time.** -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. +## Step 2: Start Clef -## Connect to Geth with IPC or RPC - -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. - -IPC allows you to do more, especially when it comes to creating and interacting -with accounts, but you need direct access to the node. - -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). - -## Using IPC - -### Connect to console - -Connect to the IPC console on a node from another terminal window: +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 -geth attach +clef --keystore geth-tutorial/keystore --configdir geth-tutorial/clef --chainid 5 ``` -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`. +> Note: geth-tutorial is the directory holding your keystore. -### Check account balance +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 +``` + +## Step 3: Start Geth + +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 --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: DAOSupport: true EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0 Constantinople: 0 Petersburg: 0 Istanbul: 1561651, Muir Glacier: , Berlin: 4460644, London: 5062605, Arrow Glacier: , MergeFork: , 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 +``` + +> **Note:** keep this terminal window open. + +## Step 4: Get Goerli Testnet Ether + +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: + +- +- + +Just enter your address on one of those sites and follow the instructions provided. + +## Step 5: Interact with Geth via IPC or RPC + +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. + +You can connect to the Geth node using HTTP or IPC. + +- 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. + +To connect to Geth using the console, open a new terminal and run this command: + +```shell +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 +``` + +### Checking your test account balance. + +Run this command in the JavaScript console to check the ether balance of the test account: ```javascript -web3.fromWei(eth.getBalance(""),"ether") +web3.fromWei(eth.getBalance("0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC"), "ether") ``` -Getting the balance of an account does not require a signed transaction, -so Clef does not ask for approval, and Geth returns the value. +**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 +> 0.1 +``` -### Send ETH to account +### Getting the list of accounts -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 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 + +``` + +Now you should get a result in the JavaScript console. + +**Result:** + +```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 ether to another account + +Run the command below to transfer 0.01 ether to the other account you created. ```javascript -eth.sendTransaction({from:"",to:"", value: web3.toWei(0.01,"ether")}) +eth.sendTransaction({ + from: "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", + to: "0xce8dba5e4157c2b284d8853afeeea259344c1653", + value: web3.toWei(0.01, "ether") +}) ``` -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. +**Again, since the test account is stored by Clef, you must confirm the request in the Clef +terminal window.** -To check, get the account balance of the second account: +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" + } + +``` + +**Result:** + +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(""),"ether") +eth.getTransaction("0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb") ``` -## Using RPC +If successful, you will get a response like the one below: -### Connect to RPC +```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 +} +``` -You can use standard HTTP requests to connect to a Geth node using the RPC APIs, using -this syntax: +## Access using low-level HTTP + +In this part of the tutorial, we will show how to access the JSON-RPC API using curl. + +### Checking account balance + +To check account balance, use the command below. ```shell -curl -X POST http://:8545 \ -    -H "Content-Type: application/json" \ -   --data'{"jsonrpc":"2.0", "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: + +```terminal +{"jsonrpc":"2.0","id":1,"result":"0xcc445d3d4b89390"} +``` + +Note that the value returned is in hexadecimal and WEI. To get the balance in ether, +convert to decimal and divide by 10^18. + +### Checking the account list + +Run the command below to get the list of all accounts. ```shell -curl -X POST http://:8545 \ -    -H "Content-Type: application/json" \ -   --data '{"jsonrpc":"2.0", "method":"eth_getBalance", "params":["","latest"], "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}' ``` -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: you will need to confirm this request in the Clef terminal window.a -### Send ETH to accounts +**Response:** -Send 0.01 ETH from the account that you added ETH to with the Görli faucet, to the second account you created: +```terminal +{"jsonrpc":"2.0","id":1,"result":["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec"]} +``` + +### Sending Transactions ```shell -curl -X POST http://:8545 \ -    -H "Content-Type: application/json" \ -   --data '{"jsonrpc":"2.0", "method":"eth_sendTransaction", "params":[{"from": "","to": "","value": "0x9184e72a"}], "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}' ``` -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. +A successful call will return a response containing the transaction hash. -To check, get the account balance of the second account: - -```shell -curl -X POST http://:8545 \ -    -H "Content-Type: application/json" \ -    --data '{"jsonrpc":"2.0", "method":"eth_getBalance", "params":["","latest"], "id":1}' +```terminal +{"jsonrpc":"2.0","id":5,"result":"0xac8b347d70a82805edb85fc136fc2c4e77d31677c2f9e4e7950e0342f0dc7e7c"} ``` diff --git a/static/styles/custom/vss.css b/static/styles/custom/vss.css index af4b2a094f..adf48227da 100644 --- a/static/styles/custom/vss.css +++ b/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 */ \ No newline at end of file +.highlight .ss { color: #a31515 } /* Literal.String.Symbol */ +.language-terminal .highlight{background: #030303; color: #ffffff;}