tornadocontrib/go-ethereum
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update md formatting

Browse Source
This commit is contained in:
Joe 2022-08-19 16:03:25 +01:00
parent f3026eacf3
commit ecff17c740
4 changed files with 112 additions and 438 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
content/docs/fundamentals/security.md
View File

@ -21,7 +21,7 @@ Account security comes down to keeping private keys and account passwords backed
Geth has built-in account management tools that are sufficiently secure for most purposes. However, Clef is recommended as an external account management and signing tool. It can be run decoupled from Geth and can even be run on dedicated secure external hardware such as a VM or a secure USB drive. This is considered best practise because the user is required to manually review all actions that touch sensitive data, except where specific predefined rules are implemented. Signing is done locally to Clef rather than giving key access to a node. Geth has built-in account management tools that are sufficiently secure for most purposes. However, Clef is recommended as an external account management and signing tool. It can be run decoupled from Geth and can even be run on dedicated secure external hardware such as a VM or a secure USB drive. This is considered best practise because the user is required to manually review all actions that touch sensitive data, except where specific predefined rules are implemented. Signing is done locally to Clef rather than giving key access to a node.
Geth allows account unlocking by passing account passwords at startup. This unlocks the account all the while that Geth is running. This is not allowed when `http` traffic is enabled, even with appropriate firewall setings. The combination of `http` and `-unlock` poses too much of a security risk because an attacker able to access the node over the exposed HTTP port would be able to make JSON-RPC requests to the node from the unlocked account, including sending funds to other addresses. Geth allows account unlocking by passing account passwords at startup. This unlocks the account all the while that Geth is running. This is not allowed when `http` traffic is enabled, even with appropriate firewall settings. The combination of `http` and `-unlock` poses too much of a security risk because an attacker able to access the node over the exposed HTTP port would be able to make JSON-RPC requests to the node from the unlocked account, including sending funds to other addresses.
**back up your keystore and passwords safely and securely!** **back up your keystore and passwords safely and securely!**

48
content/docs/getting_started/Installing-Geth.md
View File

@ -1,15 +1,11 @@
--- ---
title: Installing Geth title: Installing Geth
sort_key: A description: Guide to installing Geth
--- ---
There are several ways to install Geth, including via a package manager, downloading a pre-built bundle, running as a docker container or building from downloaded source code. On this page the various installation options are explained for several major operating systems. Users prioritizing ease of installation should choose to use a package manager or prebuilt bundle. Users prioritizing customization should build from source. It is important to run the latest version of Geth because each release includes bugfixes and improvement over the previous versions. The stable releases are recommended for most users because they have been fully tested. A list of stable releases can be found [here][geth-releases]. Instructions for updating existing Geth installations are also provided in each section. There are several ways to install Geth, including via a package manager, downloading a pre-built bundle, running as a docker container or building from downloaded source code. On this page the various installation options are explained for several major operating systems. Users prioritizing ease of installation should choose to use a package manager or prebuilt bundle. Users prioritizing customization should build from source. It is important to run the latest version of Geth because each release includes bugfixes and improvement over the previous versions. The stable releases are recommended for most users because they have been fully tested. A list of stable releases can be found [here](https://github.com/ethereum/go-ethereum/releases). Instructions for updating existing Geth installations are also provided in each section.
{:toc}
- this will be removed by the toc
## Package managers ## Package managers
### MacOS via Homebrew ### MacOS via Homebrew
@ -20,7 +16,7 @@ The easiest way to install go-ethereum is to use the Geth Homebrew tap. The firs
brew -v brew -v
``` ```
If a version number is returned, then Homebrew is installed. If not, Homebrew can be installed by following the instructions [here][brew]. With Homebrew installed, the following commands add the Geth tap and install Geth: If a version number is returned, then Homebrew is installed. If not, Homebrew can be installed by following the instructions [here](https://brew.sh/). With Homebrew installed, the following commands add the Geth tap and install Geth:
```shell ```shell
@ -34,7 +30,7 @@ The previous command installs the latest stable release. Developers that wish to
brew install ethereum --devel brew install ethereum --devel
``` ```
These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`. The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`. The full list of command line options can be viewed [here](/content/docs/fundamentals/Command-Line-Options.md) or in the terminal by running `geth --help`.
Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands: Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands:
@ -71,7 +67,7 @@ sudo apt-get update
sudo apt-get install ethereum-unstable sudo apt-get install ethereum-unstable
``` ```
These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`. The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`. The full list of command line options can be viewed [here](/content/docs/fundamentals/Command-Line-Options.md) or in the terminal by running `geth --help`.
Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands: Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands:
@ -87,7 +83,7 @@ When the node is started again, Geth will automatically use all the data from th
### Windows ### Windows
The easiest way to install Geth is to download a pre-compiled binary from the [downloads][geth-dl] page. The page provides an installer as well as a zip file containing the Geth source code. The install wizard offers the user the option to install Geth, or Geth and the developer tools. The installer adds `geth` to the system's `PATH` automatically. The zip file contains the command `.exe` files that can be run from the command prompt. The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. The easiest way to install Geth is to download a pre-compiled binary from the [downloads](/content/downloads.md) page. The page provides an installer as well as a zip file containing the Geth source code. The install wizard offers the user the option to install Geth, or Geth and the developer tools. The installer adds `geth` to the system's `PATH` automatically. The zip file contains the command `.exe` files that can be run from the command prompt. The full list of command line options can be viewed [here](/content/docs/fundamentals/Command-Line-Options.md) or in the terminal by running `geth --help`.
Updating an existing Geth installation can be achieved by stopping the node, downloading and installing the latest version following the instructions above. When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline. Updating an existing Geth installation can be achieved by stopping the node, downloading and installing the latest version following the instructions above. When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline.
@ -101,7 +97,7 @@ pkg install go-ethereum
These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`.
The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. The full list of command line options can be viewed [here](/content/docs/fundamentals/Command-Line-Options.md) or in the terminal by running `geth --help`.
Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands: Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands:
@ -124,7 +120,7 @@ make install
These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`. These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`.
The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. The full list of command line options can be viewed [here](/content/docs/fundamentals/Command-Line-Options.md) or in the terminal by running `geth --help`.
Updating an existing Geth installation can be achieved by stopping the node and running the following command: Updating an existing Geth installation can be achieved by stopping the node and running the following command:
@ -137,7 +133,7 @@ When the node is started again, Geth will automatically use all the data from th
### Arch Linux via pacman ### Arch Linux via pacman
The Geth package is available from the [community repo][geth-archlinux]. It can be installed by running: The Geth package is available from the [community repo](https://www.archlinux.org/packages/community/x86_64/geth/). It can be installed by running:
```shell ```shell
pacman -S geth pacman -S geth
@ -145,7 +141,7 @@ pacman -S geth
These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/bin/`. These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/bin/`.
The full list of command line options can be viewed [here][geth-cl-options] or in the terminal by running `geth --help`. The full list of command line options can be viewed [here](/content/docs/fundamentals/Command-Line-Options.md) or in the terminal by running `geth --help`.
Updating an existing Geth installation can be achieved by stopping the node and running the following command: Updating an existing Geth installation can be achieved by stopping the node and running the following command:
@ -166,9 +162,9 @@ The following standalone bundles are available:
- 32bit and 64bit archives (`.zip`) and installers (`.exe`) on Windows - 32bit and 64bit archives (`.zip`) and installers (`.exe`) on Windows
Some archives contain only Geth, while other archives containing Geth and the various developer tools (`clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`). More information about these executables is available at the [`README`][geth-readme-exe]. Some archives contain only Geth, while other archives containing Geth and the various developer tools (`clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`). More information about these executables is available at the [`README`](https://github.com/ethereum/go-ethereum#executables).
The standalone bundles can be downloaded from the [Geth Downloads][geth-dl] page. To update an existing installation, download and manually install the latest version. The standalone bundles can be downloaded from the [Geth Downloads](content/downloads.md) page. To update an existing installation, download and manually install the latest version.
## Docker container ## Docker container
@ -216,7 +212,7 @@ docker run -it -p 30303:30303 ethereum/client-go
### Most Linux systems and macOS ### Most Linux systems and macOS
Geth is written in [Go][go], so building from source code requires the most recent version of Go to be installed. Instructions for installing Go are available at the [Go installation page][go-install] and necessary bundles can be downloaded from the [Go download page][go-dl]. Geth is written in [Go](https://golang.org/), so building from source code requires the most recent version of Go to be installed. Instructions for installing Go are available at the [Go installation page](https://golang.org/doc/install) and necessary bundles can be downloaded from the [Go download page](https://golang.org/dl/).
With Go installed, Geth can be downloaded into a `GOPATH` workspace via: With Go installed, Geth can be downloaded into a `GOPATH` workspace via:
@ -258,7 +254,7 @@ go get -u github.com/ethereum/go-ethereum
### Windows ### Windows
The Chocolatey package manager provides an easy way to install the required build tools. Chocolatey can be installed by following these [instructions][chocolatey]. Then, to install the build tool the following commands can be run in an Administrator command prompt: The Chocolatey package manager provides an easy way to install the required build tools. Chocolatey can be installed by following these [instructions](https://chocolatey.org). Then, to install the build tool the following commands can be run in an Administrator command prompt:
``` ```
@ -334,23 +330,9 @@ git pull
make geth make geth
``` ```
Additionally all the developer tools provided with Geth (`clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`) can be compiled by running `make all`. More information about these tools can be found [here][geth-readme-exe]. Additionally all the developer tools provided with Geth (`clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`) can be compiled by running `make all`. More information about these tools can be found [here](https://github.com/ethereum/go-ethereum#executables).
Instructions for cross-compiling to another architecture are available in the [cross-compilation guide](./cross-compile).
To build a stable release, e.g. v1.9.21, the command `git checkout v1.9.21` retrieves that specific version. Executing that command before running `make geth` switches Geth to a stable branch. To build a stable release, e.g. v1.9.21, the command `git checkout v1.9.21` retrieves that specific version. Executing that command before running `make geth` switches Geth to a stable branch.
[brew]: https://brew.sh/
[go]: https://golang.org/
[go-dl]: https://golang.org/dl/
[go-install]: https://golang.org/doc/install
[chocolatey]: https://chocolatey.org
[geth-releases]: https://github.com/ethereum/go-ethereum/releases
[geth-readme-exe]: https://github.com/ethereum/go-ethereum#executables
[geth-cl-options]: https://geth.ethereum.org/docs/interface/command-line-options
[geth-archlinux]: https://www.archlinux.org/packages/community/x86_64/geth/
[geth-dl]: ../../downloads/

261
content/docs/getting_started/getting-started-with-clef.md
View File

@ -1,88 +1,47 @@
--- ---
title: Geth and Clef title: Geth and Clef
permalink: docs/getting-started/geth-and-clef description: Guide to getting up and running with Geth using Clef as an external account management and signing tool.
sort_key: B
--- ---
This page explains how to set up Geth and execute some basic tasks using the command line tools. This page explains how to set up Geth and execute some basic tasks using the command line tools. In order to use Geth, the software must first be installed. There are several ways Geth can be installed depending on the operating system and the user's choice of installation method, for example using a package manager, container or building from source. Instructions for installing Geth can be found on the ["Install and Build"](content/docs/getting_started/Installing-Geth.md) pages. Geth also needs to be connected to a consensus client in order to function as an Ethereum node. The tutorial on this page assumes Geth and a consensus client have been installed successfully and that a firewall has been configured to block external traffic to the JSON-RPC port `8545` see [Security](/content/docs/fundamentals/security.md).
In order to use Geth, the software must first be installed. There are several ways Geth can be
installed depending on the operating system and the user's choice of installation method, for
example using a package manager, container or building from source. Instructions for installing
Geth can be found on the ["Install and Build"](install-and-build/installing-geth) pages. Geth
also needs to be connected to a consensus client in order to function as an Ethereum node.
The tutorial on this page assumes Geth and a consensus client have been installed successfully and
that a firewall has been configured to block external traffic to the JSON-RPC port `8545` see
[Security](/content/docs/fundamentals/security.md).
This page provides step-by-step instructions covering the fundamentals of using Geth. This This page provides step-by-step instructions covering the fundamentals of using Geth. This includes generating accounts, joining an Ethereum network, syncing the blockchain and sending ether between accounts. This tutorial also uses [Clef](/content/docs/tools/Clef/Tutorial.md). Clef is an account management tool external to Geth itself that allows users to sign transactions. It is developed and maintained by the Geth team and is intended to eventually replace the account management tool built in to Geth.
includes generating accounts, joining an Ethereum network, syncing the blockchain and sending ether
between accounts. This tutorial also uses [Clef](/docs/clef/tutorial). Clef is an account management tool
external to Geth itself that allows users to sign transactions. It is developed and maintained by
the Geth team and is intended to eventually replace the account management tool built in to Geth.
## Prerequisites ## Prerequisites
In order to get the most value from the tutorials on this page, the following skills are In order to get the most value from the tutorials on this page, the following skills are necessary:
necessary:
- Experience using the command line - Experience using the command line
- Basic knowledge about Ethereum and testnets - Basic knowledge about Ethereum and testnets
- Basic knowledge about HTTP and JavaScript - Basic knowledge about HTTP and JavaScript
- Basic knowledge of node architecture and consensus clients - Basic knowledge of node architecture and consensus clients
Users that need to revisit these fundamentals can find helpful resources relating to the command Users that need to revisit these fundamentals can find helpful resources relating to the command line [here](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line), Ethereum and its testnets [here](https://ethereum.org/en/developers/tutorials/), http [here](https://developer.mozilla.org/en-US/docs/Web/HTTP) and Javascript [here](https://www.javascript.com/learn). Information on node architecture can be found [here](/content/docs/fundamentals/node-architecture.md) and our guide for configuring Geth to connect to a
line [here][cli], Ethereum and its testnets [here](https://ethereum.org/en/developers/tutorials/),
http [here](https://developer.mozilla.org/en-US/docs/Web/HTTP) and
Javascript [here](https://www.javascript.com/learn). Information on node architecture can be found
[here](/content/docs/fundamentals/node-architecture.md) and our guide for configuring Geth to connect to a
consensus client is [here](/content/docs/getting_started/consensus-clients.md). consensus client is [here](/content/docs/getting_started/consensus-clients.md).
{% include note.html content="If Geth was installed from source on Linux, `make` saves the {% include note.html content="If Geth was installed from source on Linux, `make` saves the binaries for Geth and the associated tools in `/build/bin`. To run these programs it is convenient to move them to the top level project directory (e.g. running `mv ./build/bin/* ./`) from `/go-ethereum`. Then `./` must be prepended to the commands in the code snippets in order to execute a particular program, e.g. `./geth` instead of simply `geth`. If the executables are not
binaries for Geth and the associated tools in `/build/bin`. To run these programs it is moved then either navigate to the `bin` directory to run them (e.g. `cd ./build/bin` and `./geth`) or provide their path (e.g. `./build/bin/geth`). These instructions can be ignored for other installations." %}
convenient to move them to the top level project directory (e.g. running `mv ./build/bin/* ./`)
from `/go-ethereum`. Then `./` must be prepended to the commands in the code snippets in order to
execute a particular program, e.g. `./geth` instead of simply `geth`. If the executables are not
moved then either navigate to the `bin` directory to run them (e.g. `cd ./build/bin` and `./geth`)
or provide their path (e.g. `./build/bin/geth`). These instructions can be ignored for other installations." %}
## Background ## Background
Geth is an Ethereum client written in Go. This means running Geth turns a computer into an Ethereum node. Geth is an Ethereum client written in Go. This means running Geth turns a computer into an Ethereum node. Ethereum is a peer-to-peer network where information is shared directly between nodes rather than being managed by a central server. Every 12 seconds one node is randomly selected to generate a new block containing a list of transactions that nodes receiving the block should execute. This "block proposer" node sends the new block to its peers. On receiving a new block, each node checks that it is valid and adds it to their database. The sequence of discrete blocks is called a "blockchain".
Ethereum is a peer-to-peer network where information is shared directly between nodes rather than being
managed by a central server. Every 12 seconds one node is randomly selected to generate a new block
containing a list of transactions that nodes receiving the block should execute. This "block proposer" node
sends the new block to its peers. On receiving a new block, each node checks that it is valid and adds
it to their database. The sequence of discrete blocks is called a "blockchain".
The information provided in each block is used by Geth to update its "state" - the ether The information provided in each block is used by Geth to update its "state" - the ether balance of each account on Ethereum and the data stored by each smart contract. There are two types of account: externally-owned accounts (EOAs) and contract accounts. Contract accounts execute contract code when they receive transactions. EOAs are accounts that users manage locally in order to sign and submit transactions. Each EOA is a public-private key pair, where the public key is used to derive a unique address for the user and the private key is used to protect the account and securely sign messages. Therefore, in order to use Ethereum,
balance of each account on Ethereum and the data stored by each smart contract. There are two types of account: it is first necessary to generate an EOA (hereafter, "account"). This tutorial will guide the user through creating an account, funding it with ether and sending some to another address.
externally-owned accounts (EOAs) and contract accounts. Contract accounts execute contract code when they
receive transactions. EOAs are accounts that users manage locally in order to sign and submit transactions.
Each EOA is a public-private key pair, where the public key is used to derive a unique address for the user and
the private key is used to protect the account and securely sign messages. Therefore, in order to use Ethereum,
it is first necessary to generate an EOA (hereafter, "account"). This tutorial will guide the user through
creating an account, funding it with ether and sending some to another address.
Read more about Ethereum accounts [here](https://ethereum.org/en/developers/docs/accounts/). Read more about Ethereum accounts [here](https://ethereum.org/en/developers/docs/accounts/).
## Step 1: Generating accounts ## Step 1: Generating accounts
There are several methods for generating accounts in Geth. This tutorial demonstrates how to generate accounts There are several methods for generating accounts in Geth. This tutorial demonstrates how to generate accounts using Clef, as this is considered best practice, largely because it decouples the users' key management from Geth, making it more modular and flexible. It can also be run from secure USB sticks or virtual machines, offering security benefits. For convenience, this tutorial will execute Clef on the same computer that will also run Geth, although more secure options are available (see [here](https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/docs/setup.md)).
using Clef, as this is considered best practice, largely because it decouples the users' key management from Geth,
making it more modular and flexible. It can also be run from secure USB sticks or virtual machines, offering
security benefits. For convenience, this tutorial will execute Clef on the same computer that will also run Geth,
although more secure options are available (see [here](https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/docs/setup.md)).
An account is a pair of keys (public and private). Clef needs to know where to save these keys to so that they An account is a pair of keys (public and private). Clef needs to know where to save these keys to so that they can be retrieved later. This information is passed to Clef as an argument. This is achieved using the following command:
can be retrieved later. This information is passed to Clef as an argument. This is achieved using the following command:
```shell ```shell
clef newaccount --keystore geth-tutorial/keystore clef newaccount --keystore geth-tutorial/keystore
``` ```
The specific function from Clef that generates new accounts is `newaccount` and it accepts a The specific function from Clef that generates new accounts is `newaccount` and it accepts a parameter, `--keystore`, that tells it where to store the newly generated keys. In this example the keystore location is a new directory that will be created automatically: `geth-tutorial/keystore`.
parameter, `--keystore`, that tells it where to store the newly generated keys. In this
example the keystore location is a new directory that will be created automatically: `geth-tutorial/keystore`.
Clef will return the following result in the terminal: Clef will return the following result in the terminal:
```terminal ```terminal
@ -102,17 +61,10 @@ Enter 'ok' to proceed:
> >
``` ```
This is important information. The `geth-tutorial/keystore` directory will soon contain a secret This is important information. The `geth-tutorial/keystore` directory will soon contain a secret key that can be used to access any funds held in the new account. If it is compromised, the funds can be stolen. If it is lost, there is no way to retrieve the funds. This tutorial will only use dummy funds with no real world value, but when these steps are repeated on Ethereum mainnet is critical that the keystore is kept secure and backed up.
key that can be used to access any funds held in the new account. If it is compromised, the funds
can be stolen. If it is lost, there is no way to retrieve the funds. This tutorial will only use
dummy funds with no real world value, but when these steps are repeated on Ethereum mainnet is
critical that the keystore is kept secure and backed up.
Typing `ok` into the terminal and pressing `enter` causes Clef to prompt for a password. Typing `ok` into the terminal and pressing `enter` causes Clef to prompt for a password. Clef requires a password that is at least 10 characters long, and best practice would be to use a combination of numbers, characters and special characters. Entering a suitable password and pressing `enter` returns the following result to the terminal:
Clef requires a password that is at least 10 characters long, and best practice would be
to use a combination of numbers, characters and special characters. Entering a suitable
password and pressing `enter` returns the following result to the terminal:
```terminal ```terminal
----------------------- -----------------------
@ -123,27 +75,13 @@ WARN [02-10|13:46:46.595] Please remember your password!
Generated account 0xCe8dBA5e4157c2B284d8853afEEea259344C1653 Generated account 0xCe8dBA5e4157c2B284d8853afEEea259344C1653
``` ```
It is important to save the account address and the password somewhere secure. It is important to save the account address and the password somewhere secure. They will be used again later in this tutorial. Please note that the account address shown in the code snippets above and later in this tutorials are examples - those generated by followers of this tutorial will be different. The account generated above can be used as the main account throughout the remainder of this tutorial. However in order to demonstrate transactions between accounts it is also necessary to have a second account. A second account can be added to the same keystore by precisely repeating the previous steps, providing the same password.
They will be used again later in this tutorial. Please note that the account address shown
in the code snippets above and later in this tutorials are examples - those generated by followers
of this tutorial will be different. The account generated above can be used as the main account
throughout the remainder of this tutorial. However in order to demonstrate transactions between
accounts it is also necessary to have a second account. A second account can be added to the
same keystore by precisely repeating the previous steps, providing the same password.
## Step 2: Start Clef ## Step 2: Start Clef
The previous commands used Clef's `newaccount` function to add new key pairs to the keystore. The previous commands used Clef's `newaccount` function to add new key pairs to the keystore. Clef uses the private key(s) saved in the keystore is used to sign transactions. In order to do this, Clef needs to be started and left running while Geth is running simultaneously, so that the two programs can communicate between one another.
Clef uses the private key(s) saved in the keystore is used to sign transactions. In order to do
this, Clef needs to be started and left running while Geth is running simultaneously, so that the
two programs can communicate between one another.
To start Clef, run the Clef executable passing as arguments the keystore file location, To start Clef, run the Clef executable passing as arguments the keystore file location, config directory location and a chain ID. The config directory was automatically created inside the `geth-tutorial` directory during the previous step. The [chain ID](https://chainlist.org/) is an integer that defines which Ethereum network to connect to. Ethereum mainnet has chain ID 1. In this tutorial Chain ID 5 is used which is that of the Goerli testnet. It is very important that this chain ID parameter is set to 5. The following command starts Clef on Goerli:
config directory location and a chain ID. The config directory was automatically created
inside the `geth-tutorial` directory during the previous step. The [chain ID](https://chainlist.org/)
is an integer that defines which Ethereum network to connect to. Ethereum mainnet has chain ID 1.
In this tutorial Chain ID 5 is used which is that of the Goerli testnet. It is very important that
this chain ID parameter is set to 5. The following command starts Clef on Goerli:
```shell ```shell
@ -172,20 +110,11 @@ INFO [02-10|13:55:30.984] IPC endpoint opened url=geth-tuto
* extapi_ipc : geth-tutorial/clef/clef.ipc * extapi_ipc : geth-tutorial/clef/clef.ipc
``` ```
This result indicates that Clef is running. This terminal should be left running for the duration of this This result indicates that Clef is running. This terminal should be left running for the duration of this tutorial. If the tutorial is stopped and restarted later Clef must also be restarted by running the previous command.
tutorial. If the tutorial is stopped and restarted later Clef must also be restarted by running the previous command.
## Step 3: Start Geth ## Step 3: Start Geth
Geth is the Ethereum client that will connect the computer to the Ethereum network. In this tutorial the Geth is the Ethereum client that will connect the computer to the Ethereum network. In this tutorial the network is Goerli, an Ethereum testnet. Testnets are used to test Ethereum client software and smart contracts in an environment where no real-world value is at risk. To start Geth, run the Geth executable file passing argument that define the data directory (where Geth should save blockchain data), signer (points Geth to Clef), the network ID and the sync mode. For this tutorial, snap sync is recommended (see [here](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/) for reasons why). The final argument passed to Geth is the `--http` flag. This enables the http-rpc server that allows external programs to interact with Geth by sending it http requests. By default the http server is only exposed locally using port 8545: `localhost:8545`.
network is Goerli, an Ethereum testnet. Testnets are used to test Ethereum client software and smart
contracts in an environment where no real-world value is at risk. To start Geth, run the Geth executable
file passing argument that define the data directory (where Geth should save blockchain data),
signer (points Geth to Clef), the network ID and the sync mode. For this tutorial, snap sync is recommended
(see [here](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/) for reasons why). The final argument
passed to Geth is the `--http` flag. This enables the http-rpc server that allows external programs to
interact with Geth by sending it http requests. By default the http server is only exposed locally using
port 8545: `localhost:8545`.
The following command should be run in a new terminal, separate to the one running Clef: The following command should be run in a new terminal, separate to the one running Clef:
@ -219,11 +148,8 @@ WARN [02-10|13:59:06.999] Failed to open wallet url=extapi://
INFO [02-10|13:59:08.793] Block synchronisation started INFO [02-10|13:59:08.793] Block synchronisation started
``` ```
This indicates that Geth has started up and is searching for peers to connect to. Once it finds peers it This indicates that Geth has started up and is searching for peers to connect to. Once it finds peers it can request block headers from them, starting at the genesis block for the Goerli blockchain. Geth continues to download blocks sequentially, saving the data in files in `/go-ethereum/geth-tutorial/geth/chaindata/`.
can request block headers from them, starting at the genesis block for the Goerli blockchain. Geth continues This is confirmed by the logs printed to the terminal. There should be a rapidly-growing sequence of logs in the terminal with the following syntax:
to download blocks sequentially, saving the data in files in `/go-ethereum/geth-tutorial/geth/chaindata/`.
This is confirmed by the logs printed to the terminal. There should be a rapidly-growing sequence of logs in
the terminal with the following syntax:
```terminal ```terminal
INFO [04-29][15:54:09.238] Looking for peers peercount=2 tried=0 static=0 INFO [04-29][15:54:09.238] Looking for peers peercount=2 tried=0 static=0
@ -239,42 +165,22 @@ the following command can be run:
curl http://localhost:8545 curl http://localhost:8545
``` ```
If there is no error message reported to the terminal, everything is OK. Geth must be running in order for If there is no error message reported to the terminal, everything is OK. Geth must be running in order for a user to interact with the Ethereum network. If this terminal is closed down then Geth must be restarted in a new terminal. Geth can be started and stopped easily, but it must be running for any interaction with
a user to interact with the Ethereum network. If this terminal is closed down then Geth must be restarted Ethereum to take place. To shut down Geth, simply press `CTRL+C` in the Geth terminal. To start it again, run the previous command `geth --datadir <other commands>`.
in a new terminal. Geth can be started and stopped easily, but it must be running for any interaction with
Ethereum to take place. To shut down Geth, simply press `CTRL+C` in the Geth terminal. To start it again,
run the previous command `geth --datadir ... ..`.
{% include note.html content="Snap syncing Goerli will take some time and until the sync is finished you {% include note.html content="Snap syncing Goerli will take some time and until the sync is finished you can't use the node to transfer funds. You can also try doing a [light sync](interface/les) which will be much quicker but depends on light servers being available to serve your node the data it needs." %}
can't use the node to transfer funds. You can also try doing a [light sync](interface/les) which will be
much quicker but depends on light servers being available to serve your node the data it needs." %}
## Step 4: Get Testnet Ether ## Step 4: Get Testnet Ether
In order to make some transactions, the user must fund their account with ether. On Ethereum mainnet, In order to make some transactions, the user must fund their account with ether. On Ethereum mainnet, ether can only be obtained in three ways: 1) by receiving it as a reward for mining/validating; 2) receiving it in a transfer from another Ethereum user or contract; 3) receiving it from an exchange, 3) having paid for it with fiat money. On Ethereum testnets, the ether has no real world value so it 4) can be made freely available via faucets. Faucets allow users to request a transfer of testnet ether to their account.
ether can only be obtained in three ways: 1) by receiving it as a reward for mining/validating;
2) receiving it in a transfer from another Ethereum user or contract; 3) receiving it from an exchange,
3) having paid for it with fiat money. On Ethereum testnets, the ether has no real world value so it
4) can be made freely available via faucets. Faucets allow users to request a transfer of testnet ether to their account.
The address generated by Clef in Step 1 can be pasted into the Paradigm Multifaucet faucet The address generated by Clef in Step 1 can be pasted into the Paradigm Multifaucet faucet [here](https://fauceth.komputing.org/?chain=1115511). This requires a Twitter login as proof of personhood. The faucets adds ether to the given address on multiple testnets simultaneously, including Goerli. In the next steps Geth will be used to check that the ether has been sent to the given address and send some of it to the second address created earlier.
[here](https://fauceth.komputing.org/?chain=1115511). This requires a Twitter login as proof of
personhood. The faucets adds ether to the given address on multiple testnets simultaneously,
including Goerli. In the next steps Geth will be used to check that the ether has been sent
to the given address and send some of it to the second address created earlier.
## Step 5: Interact with Geth ## Step 5: Interact with Geth
For interacting with the blockchain, Geth provides JSON-RPC APIs. For interacting with the blockchain, Geth provides JSON-RPC APIs. [JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) is a way to execute specific
[JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) is a way to execute specific tasks by sending instructions to Geth in the form of [JSON](https://www.json.org/json-en.html) objects. RPC stands for "Remote Procedure Call" and it refers to the ability to send these JSON-encoded instructions from locations outside of those managed by Geth. It is possible to interact with Geth by sending these JSON encoded instructions directly over Geth's exposed http port using tools like Curl. However, this is somewhat user-unfriendly and error-prone, especially for more complex instructions. For this reason, there are a set of libraries built on top of JSON-RPC that provide a more user-friendly interface for interacting with Geth. One of the most widely used is Web3.js.
tasks by sending instructions to Geth in the form of [JSON](https://www.json.org/json-en.html) objects.
RPC stands for "Remote Procedure Call" and it refers to the ability to send these JSON-encoded
instructions from locations outside of those managed by Geth. It is possible to interact with Geth
by sending these JSON encoded instructions directly over Geth's exposed http port using tools like Curl.
However, this is somewhat user-unfriendly and error-prone, especially for more complex instructions.
For this reason, there are a set of libraries built on top of JSON-RPC that provide a more user-friendly
interface for interacting with Geth. One of the most widely used is Web3.js.
Geth provides a Javascript console that exposes the Web3.js API. This means that with Geth running in one terminal, a Javascript environment can be opened in another allowing the user to interact with Geth using Web3.js. There are three transport protocols that can be used to connect the Javascript environment to Geth: Geth provides a Javascript console that exposes the Web3.js API. This means that with Geth running in one terminal, a Javascript environment can be opened in another allowing the user to interact with Geth using Web3.js. There are three transport protocols that can be used to connect the Javascript environment to Geth:
@ -284,16 +190,13 @@ Geth provides a Javascript console that exposes the Web3.js API. This means that
- Websocket: By default provides access to the `eth`, `web3` and `net` method namespaces. - Websocket: By default provides access to the `eth`, `web3` and `net` method namespaces.
This tutorial will use the HTTP option. Note that the terminals running Geth and Clef should both still be active. This tutorial will use the HTTP option. Note that the terminals running Geth and Clef should both still be active. In a new (third) terminal, the following command can be run to start the console and connect it to Geth using the exposed http port:
In a new (third) terminal, the following command can be run to start the console and connect it to Geth
using the exposed http port:
```shell ```shell
geth attach http://127.0.0.1:8545 geth attach http://127.0.0.1:8545
``` ```
This command causes the terminal to hang because it is waiting for approval from Clef. Approving the request This command causes the terminal to hang because it is waiting for approval from Clef. Approving the request in the terminal running Clef will lead to the following welcome message being displayed in the Javascript console:
in the terminal running Clef will lead to the following welcome message being displayed in the Javascript console:
```terminal ```terminal
Welcome to the Geth JavaScript console! Welcome to the Geth JavaScript console!
@ -310,17 +213,13 @@ The console is now active and connected to Geth. It can now be used to interact
### List of accounts ### List of accounts
In this tutorial, the accounts are managed using Clef. This means that requesting information about In this tutorial, the accounts are managed using Clef. This means that requesting information about the accounts requires explicit approval in Clef, which should still be running in its own terminal. Earlier in this tutorial, two accounts were created using Clef. The following command will display the addresses of those two accounts and any others that might have been added to the keystore before or since.
the accounts requires explicit approval in Clef, which should still be running in its own terminal.
Earlier in this tutorial, two accounts were created using Clef. The following command will display the
addresses of those two accounts and any others that might have been added to the keystore before or since.
```javascript ```javascript
eth.accounts eth.accounts
``` ```
The console will hang, because Clef is waiting for approval. The following message will be The console will hang, because Clef is waiting for approval. The following message will be displayed in the Clef terminal:
displayed in the Clef terminal:
```terminal ```terminal
-------- List Account request-------------- -------- List Account request--------------
@ -341,35 +240,24 @@ Approve? [y/N]:
``` ```
Entering `y` approves the request from the console. In the terminal running the Javascript console, Entering `y` approves the request from the console. In the terminal running the Javascript console, the account addresses are now displayed:
the account addresses are now displayed:
```terminal ```terminal
["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", "0xce8dba5e4157c2b284d8853afeeea259344c1653"] ["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", "0xce8dba5e4157c2b284d8853afeeea259344c1653"]
``` ```
It is also possible for this request to time out if the Clef approval took too long - It is also possible for this request to time out if the Clef approval took too long - in this case simply repeat the request and approval.
in this case simply repeat the request and approval.
### Checking account balance. ### Checking account balance.
Having confirmed that the two addresses created earlier are indeed in the keystore and accessible Having confirmed that the two addresses created earlier are indeed in the keystore and accessible through the Javascript console, it is possible to retrieve information about how much ether they own. The Goerli faucet should have sent 1 ETH to the address provided, meaning that the balance of one of the accounts should be 1 ether and the other should be 0. The following command displays the account balance in the console:
through the Javascript console, it is possible to retrieve information about how much ether they own.
The Goerli faucet should have sent 1 ETH to the address provided, meaning that the balance of one of
the accounts should be 1 ether and the other should be 0. The following command displays the account
balance in the console:
```javascript ```javascript
web3.fromWei(eth.getBalance("0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC"), "ether") web3.fromWei(eth.getBalance("0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC"), "ether")
``` ```
There are actually two instructions sent in the above command. The inner one is the `getBalance` There are actually two instructions sent in the above command. The inner one is the `getBalance` function from the `eth` namespace. This takes the account address as its only argument. By default, this returns the account balance in units of Wei. There are 10<sup>18</sup> Wei to one ether. To present the result in units of ether, `getBalance` is wrapped in the `fromWei` function from the `web3` namespace. Running this command should provide the following result (for the account that received faucet funds):
function from the `eth` namespace. This takes the account address as its only argument. By default,
this returns the account balance in units of Wei. There are 10<sup>18</sup> Wei to one ether.
To present the result in units of ether, `getBalance` is wrapped in the `fromWei` function from
the `web3` namespace. Running this command should provide the following result
(for the account that received faucet funds):
```terminal ```terminal
1 1
@ -383,15 +271,7 @@ Repeating the command for the other account should yield:
### Send ether to another account ### Send ether to another account
The command `eth.sendTransaction` can be used to send some ether from one address to another. The command `eth.sendTransaction` can be used to send some ether from one address to another. This command takes three arguments: `from`, `to` and `value`. These define the sender and recipient addresses (as strings) and the amount of Wei to transfer. It is far less error prone to enter the transaction value in units of ether rather than Wei, so the value field can take the return value from the `toWei` function. The following command, run in the Javascript console, sends 0.1 ether from one of the accounts in the Clef keystore to the other. Note that the addresses here are examples - the user must replace the address in the `from` field with the address currently owning 1 ether, and the address in the `to` field with the address currently holding 0 ether.
This command takes three arguments: `from`, `to` and `value`. These define the sender and
recipient addresses (as strings) and the amount of Wei to transfer. It is far less error
prone to enter the transaction value in units of ether rather than Wei, so the value field can
take the return value from the `toWei` function. The following command, run in the Javascript
console, sends 0.1 ether from one of the accounts in the Clef keystore to the other. Note that
the addresses here are examples - the user must replace the address in the `from` field with
the address currently owning 1 ether, and the address in the `to` field with the address
currently holding 0 ether.
```javascript ```javascript
eth.sendTransaction({ eth.sendTransaction({
@ -401,11 +281,7 @@ eth.sendTransaction({
}) })
``` ```
Note that submitting this transaction requires approval in Clef. In the Clef terminal, Note that submitting this transaction requires approval in Clef. In the Clef terminal, Clef will prompt for approval and request the account password. If the password is correctly entered, Geth proceeds with the transaction. The transaction request summary is presented by Clef in the Clef terminal. This is an opportunity for the sender to review the details and ensure they are correct.
Clef will prompt for approval and request the account password. If the password is correctly
entered, Geth proceeds with the transaction. The transaction request summary is presented by
Clef in the Clef terminal. This is an opportunity for the sender to review the details and
ensure they are correct.
```terminal ```terminal
--------- Transaction request------------- --------- Transaction request-------------
@ -432,8 +308,7 @@ Please enter the password for account 0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC
``` ```
After approving the transaction, the following confirmation screen in displayed in After approving the transaction, the following confirmation screen in displayed in the Clef terminal:
the Clef terminal:
```terminal ```terminal
----------------------- -----------------------
@ -457,34 +332,24 @@ Transaction signed:
} }
``` ```
In the Javascript console, the transaction hash is displayed. This will be used in the In the Javascript console, the transaction hash is displayed. This will be used in the next section to retrieve the transaction details.
next section to retrieve the transaction details.
```terminal ```terminal
"0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb" "0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb"
``` ```
It is also advised to check the account balances using Geth by repeating the instructions from It is also advised to check the account balances using Geth by repeating the instructions from earlier. At this point in the tutorial, the two accounts in the Clef keystore should have balances just below 0.9 ether (because 0.1 ether has been transferred out and some small amount paid in transaction gas) and 0.1 ether.
earlier. At this point in the tutorial, the two accounts in the Clef keystore should have balances
just below 0.9 ether (because 0.1 ether has been transferred out and some small amount paid in
transaction gas) and 0.1 ether.
### Checking the transaction hash ### Checking the transaction hash
The transaction hash is a unique identifier for this specific transaction that can be used The transaction hash is a unique identifier for this specific transaction that can be used later to retrieve the transaction details. For example, the transaction details can be viewed by pasting this hash into the [Goerli block explorer](https://goerli.etherscan.io/). The same information can also be retrieved directly from the Geth node. The hash returned in the previous step can be provided as an argument to `eth.getTransaction` to return the transaction information:
later to retrieve the transaction details. For example, the transaction details can be
viewed by pasting this hash into the [Goerli block explorer](https://goerli.etherscan.io/).
The same information can also be retrieved directly from the Geth node. The hash returned in
the previous step can be provided as an argument to `eth.getTransaction` to return the
transaction information:
```javascript ```javascript
eth.getTransaction("0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb") eth.getTransaction("0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb")
``` ```
This returns the following response (although the actual values for each field will vary This returns the following response (although the actual values for each field will vary because they are specific to each transaction):
because they are specific to each transaction):
```terminal ```terminal
{ {
@ -512,23 +377,12 @@ because they are specific to each transaction):
## Using Curl ## Using Curl
Up to this point this tutorial has interacted with Geth using the convenience library Web3.js. Up to this point this tutorial has interacted with Geth using the convenience library Web3.js. This library enables the user to send instructions to Geth using a more user-friendly interface compared to sending raw JSON objects. However, it is also possible for the user to send these JSON objects directly to Geth's exposed HTTP port. Curl is a command line tool that sends HTTP requests. This part of the tutorial demonstrates how to check account balances and send a transaction using Curl.
This library enables the user to send instructions to Geth using a more user-friendly interface
compared to sending raw JSON objects. However, it is also possible for the user to send these
JSON objects directly to Geth's exposed HTTP port. Curl is a command line tool that sends HTTP
requests. This part of the tutorial demonstrates how to check account balances and send a
transaction using Curl.
### Checking account balance ### Checking account balance
The command below returns the balance of the given account. This is a HTTP POST request to the The command below returns the balance of the given account. This is a HTTP POST request to the local port 8545. The `-H` flag is for header information. It is used here to define the format of the incoming payload, which is JSON. The `--data` flag defines the content of the payload, which is a JSON object. That JSON object contains four fields: `jsonrpc` defines the spec version for the JSON-RPC API, `method` is the specific function being invoked, `params` are the function
local port 8545. The `-H` flag is for header information. It is used here to define the format arguments, and `id` is used for ordering transactions. The two arguments passed to `eth_getBalance` are the account address whose balance to check and the block to query (here `latest` is used to check the balance in the most recently mined block).
of the incoming payload, which is JSON. The `--data` flag defines the content of the payload,
which is a JSON object. That JSON object contains four fields: `jsonrpc` defines the spec version
for the JSON-RPC API, `method` is the specific function being invoked, `params` are the function
arguments, and `id` is used for ordering transactions. The two arguments passed to `eth_getBalance`
are the account address whose balance to check and the block to query (here `latest` is used to
check the balance in the most recently mined block).
```shell ```shell
curl -X POST http://127.0.0.1:8545 \ curl -X POST http://127.0.0.1:8545 \
@ -542,9 +396,7 @@ A successful call will return a response like the one below:
{"jsonrpc":"2.0","id":1,"result":"0xc7d54951f87f7c0"} {"jsonrpc":"2.0","id":1,"result":"0xc7d54951f87f7c0"}
``` ```
The balance is in the `result` field in the returned JSON object. However, it is denominated in The balance is in the `result` field in the returned JSON object. However, it is denominated in Wei and presented as a hexadecimal string. There are many options for converting this value to a decimal in units of ether, for example by opening a Python console and running:
Wei and presented as a hexadecimal string. There are many options for converting this value to a
decimal in units of ether, for example by opening a Python console and running:
```python ```python
0xc7d54951f87f7c0 / 1e18 0xc7d54951f87f7c0 / 1e18
@ -573,11 +425,7 @@ This requires approval in Clef. Once approved, the following information is retu
### Sending Transactions ### Sending Transactions
Sending a transaction between accounts can also be achieved using Curl. Notice that the value of the Sending a transaction between accounts can also be achieved using Curl. Notice that the value of the transaction is a hexadecimal string in units of Wei. To transfer 0.1 ether, it is first necessary to convert this to Wei by multiplying by 10<sup>18</sup> then converting to hex. 0.1 ether is `"0x16345785d8a0000"` in hex. As before, update the `to` and `from` fields with the addresses in the Clef keystore.
transaction is a hexadecimal string in units of Wei. To transfer 0.1 ether, it is first necessary to
convert this to Wei by multiplying by 10<sup>18</sup> then converting to hex. 0.1 ether is
`"0x16345785d8a0000"` in hex. As before, update the `to` and `from` fields with the addresses in
the Clef keystore.
```shell ```shell
@ -586,9 +434,7 @@ curl -X POST http://127.0.0.1:8545 \
--data '{"jsonrpc":"2.0", "method":"eth_sendTransaction", "params":[{"from": "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec","to": "0xce8dba5e4157c2b284d8853afeeea259344c1653","value": "0x16345785d8a0000"}], "id":1}' --data '{"jsonrpc":"2.0", "method":"eth_sendTransaction", "params":[{"from": "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec","to": "0xce8dba5e4157c2b284d8853afeeea259344c1653","value": "0x16345785d8a0000"}], "id":1}'
``` ```
This requires approval in Clef. Once the password for the sender account has been provided, This requires approval in Clef. Once the password for the sender account has been provided, Clef will return a summary of the transaction details and the terminal that made the Curl request will display a response containing the transaction hash.
Clef will return a summary of the transaction details and the terminal that made the Curl
request will display a response containing the transaction hash.
```terminal ```terminal
{"jsonrpc":"2.0","id":5,"result":"0xac8b347d70a82805edb85fc136fc2c4e77d31677c2f9e4e7950e0342f0dc7e7c"} {"jsonrpc":"2.0","id":5,"result":"0xac8b347d70a82805edb85fc136fc2c4e77d31677c2f9e4e7950e0342f0dc7e7c"}
@ -596,11 +442,6 @@ request will display a response containing the transaction hash.
## Summary ## Summary
This tutorial has demonstrated how to generate accounts using Clef, fund them with testnet ether and use This tutorial has demonstrated how to generate accounts using Clef, fund them with testnet ether and use those accounts to interact with Ethereum (Goerli) through a Geth node. Checking account balances, sending transactions and retrieving transaction details were explained using the web3.js library via the Geth console and using the JSON-RPC directly using Curl. For more detailed information about Clef, please see [the Clef docs](/content/docs/tools/Clef/Tutorial.md).
those accounts to interact with Ethereum (Goerli) through a Geth node. Checking account balances, sending
transactions and retrieving transaction details were explained using the web3.js library via the
Geth console and using the JSON-RPC directly using Curl. For more detailed information about Clef, please see
[the Clef docs](/docs/clef/tutorial).
[cli]: https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line

239
content/docs/getting_started/getting_started.md
View File

@ -1,32 +1,13 @@
--- ---
title: Getting Started with Geth title: Getting Started with Geth
permalink: docs/getting-started description: Instructions for getting up and running with Geth
sort_key: A
--- ---
This page explains how to set up Geth and execute some basic tasks using the command line tools. This page explains how to set up Geth and execute some basic tasks using the command line tools. In order to use Geth, the software must first be installed. There are several ways Geth can be installed depending on the operating system and the user's choice of installation method, for example using a package manager, container or building from source. Instructions for installing Geth can be found on the ["Install and Build"](content/docs/getting_started/Installing-Geth.md) pages. Geth
In order to use Geth, the software must first be installed. There are several ways Geth can be also needs to be connected to a consensus client in order to function as an Ethereum node. The tutorial on this page assumes Geth and a consensus client have been installed successfully and that a firewall has been configured to block external traffic to the JSON-RPC port `8545` see [Security](/content/docs/fundamentals/security.md).
installed depending on the operating system and the user's choice of installation method, for
example using a package manager, container or building from source. Instructions for installing
Geth can be found on the ["Install and Build"](install-and-build/installing-geth) pages. Geth
also needs to be connected to a consensus client in order to function as an Ethereum node.
The tutorial on this page assumes Geth and a consensus client have been installed successfully and
that a firewall has been configured to block external traffic to the JSON-RPC port `8545` see
[Security](/content/docs/fundamentals/security.md).
This page provides step-by-step instructions covering the fundamentals of using Geth. This includes This page provides step-by-step instructions covering the fundamentals of using Geth. This includes generating accounts, joining an Ethereum network, syncing the blockchain and sending ether between accounts. This page uses Geth's built in account management tool. This is the simplest method for creating and accessing
generating accounts, joining an Ethereum network, syncing the blockchain and sending ether between accounts. accounts in Geth, is sufficiently secure for many purposes and provides a good entry point for understanding some of the basic Geth workflows. However, Geth also comes bundled with an external signer and account management tool called [Clef](/tools/Clef/introduction). It is best practise to use Clef instead of Geth's built-in account management tools because Clef is decoupled from Geth and can be run in a separate, secure environment. This page should be used as an initial entry point into basic Geth and readers should plan to advance from this page to [Getting started with Geth and Clef](/content/docs/getting_started/getting-started-with-clef.md). Eventually, Clef is intended to replace Geth's built-in account management tools.
This page uses Geth's built in account management tool. This is the simplest method for creating and accessing
accounts in Geth, is sufficiently secure for many purposes and provides a good entry point for undersatanding
some of the basic Geth workflows. However, Geth also comes bundled with an external signer and account management
tool called [Clef](/tools/Clef/introduction). It is best practise to use Clef instead of Geth's built-in account
management tools because Clef is decoupled from Geth and can be run in a separate, secure environment.
This page should be used as an initial entry point into basic Geth and readers should plan to advance from this
page to [Getting started with Geth and Clef](/content/docs/getting_started/getting-started-with-clef.md).
Eventually, Clef is intended to replace Geth's built-in account management tools.
{:toc}
- this will be removed by the toc
## Prerequisites ## Prerequisites
@ -38,38 +19,19 @@ necessary:
- Basic knowledge about HTTP and JavaScript - Basic knowledge about HTTP and JavaScript
- Basic knowledge of node architecture and consensus clients - Basic knowledge of node architecture and consensus clients
Users that need to revisit these fundamentals can find helpful resources relating to the command Users that need to revisit these fundamentals can find helpful resources relating to the command line [here](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line), Ethereum and its testnets [here](https://ethereum.org/en/developers/tutorials/), http [here](https://developer.mozilla.org/en-US/docs/Web/HTTP) and Javascript [here](https://www.javascript.com/learn). Information on node architecture can be found [here](/content/docs/fundamentals/node-architecture.md) and our guide for configuring Geth to connect to a
line [here][cli], Ethereum and its testnets [here](https://ethereum.org/en/developers/tutorials/),
http [here](https://developer.mozilla.org/en-US/docs/Web/HTTP) and
Javascript [here](https://www.javascript.com/learn). Information on node architecture can be found
[here](/content/docs/fundamentals/node-architecture.md) and our guide for configuring Geth to connect to a
consensus client is [here](/content/docs/getting_started/consensus-clients.md). consensus client is [here](/content/docs/getting_started/consensus-clients.md).
{% include note.html content="If Geth was installed from source on Linux, `make` saves the {% include note.html content="If Geth was installed from source on Linux, `make` saves the binaries for Geth and the associated tools in `/build/bin`. To run these programs it is convenient to move them to the top level project directory (e.g. running `mv ./build/bin/* ./`) from `/go-ethereum`. Then `./` must be prepended to the commands in the code snippets in order to execute a particular program, e.g. `./geth` instead of simply `geth`. If the executables are not
binaries for Geth and the associated tools in `/build/bin`. To run these programs it is moved then either navigate to the `bin` directory to run them (e.g. `cd ./build/bin` and `./geth`) or provide their path (e.g. `./build/bin/geth`). These instructions can be ignored for other installations." %}
convenient to move them to the top level project directory (e.g. running `mv ./build/bin/* ./`)
from `/go-ethereum`. Then `./` must be prepended to the commands in the code snippets in order to
execute a particular program, e.g. `./geth` instead of simply `geth`. If the executables are not
moved then either navigate to the `bin` directory to run them (e.g. `cd ./build/bin` and `./geth`)
or provide their path (e.g. `./build/bin/geth`). These instructions can be ignored for other installations." %}
## Background ## Background
Geth is an Ethereum client written in Go. This means running Geth turns a computer into an Ethereum node. Geth is an Ethereum client written in Go. This means running Geth turns a computer into an Ethereum node. Ethereum is a peer-to-peer network where information is shared directly between nodes rather than being managed by a central server. Every 12 seconds one node is randomly selected to generate a new block
Ethereum is a peer-to-peer network where information is shared directly between nodes rather than being containing a list of transactions that nodes receiving the block should execute. This "block proposer" node sends the new block to its peers. On receiving a new block, each node checks that it is valid and adds it to their database. The sequence of discrete blocks is called a "blockchain".
managed by a central server. Every 12 seconds one node is randomly selected to generate a new block
containing a list of transactions that nodes receiving the block should execute. This "block proposer" node
sends the new block to its peers. On receiving a new block, each node checks that it is valid and adds
it to their database. The sequence of discrete blocks is called a "blockchain".
The information provided in each block is used by Geth to update its "state" - the ether The information provided in each block is used by Geth to update its "state" - the ether balance of each account on Ethereum and the data stored by each smart contract. There are two types of account: externally-owned accounts (EOAs) and contract accounts. Contract accounts execute contract code when they receive transactions. EOAs are accounts that users manage locally in order to sign and submit transactions. Each EOA is a public-private key pair, where the public key is used to derive a unique address for the user and the private key is used to protect the account and securely sign messages. Therefore, in order to use Ethereum,
balance of each account on Ethereum and the data stored by each smart contract. There are two types of account: it is first necessary to generate an EOA (hereafter, "account"). This tutorial will guide the user through creating an account, funding it with ether and sending some to another address.
externally-owned accounts (EOAs) and contract accounts. Contract accounts execute contract code when they
receive transactions. EOAs are accounts that users manage locally in order to sign and submit transactions.
Each EOA is a public-private key pair, where the public key is used to derive a unique address for the user and
the private key is used to protect the account and securely sign messages. Therefore, in order to use Ethereum,
it is first necessary to generate an EOA (hereafter, "account"). This tutorial will guide the user through
creating an account, funding it with ether and sending some to another address.
Read more about Ethereum accounts [here](https://ethereum.org/en/developers/docs/accounts/). Read more about Ethereum accounts [here](https://ethereum.org/en/developers/docs/accounts/).
@ -82,15 +44,12 @@ To generate a new account in Geth:
geth account new geth account new
``` ```
This returns a prompt for a password. Once provided, a new account will be created and added to the This returns a prompt for a password. Once provided, a new account will be created and added to the default keystore (`/datadir/keystore`). A custom keystore can also be provided by passing `--keystore <path>`. In this tutorial the keys will be stored in a new data directory `geth-tutorial`. Create that directory, then run:
default keystore (`/datadir/keystore`). A custom keystore can also be provided by passing `--keystore <path>`.
In this tutorial the keys will be stored in a new data directory `geth-tutorial`. Create that diredctory, then run:
```sh ```sh
geth account new --keystore geth-tutorial/keystore geth account new --keystore geth-tutorial/keystore
``` ```
The following will be returned to the console, confirming the new account has been created and The following will be returned to the console, confirming the new account has been created and added to the keystore.
added to the keystore.
```terminal ```terminal
Your new account is locked with a password. Please give a password. Do not forget this password. Your new account is locked with a password. Please give a password. Do not forget this password.
@ -108,33 +67,15 @@ Path of the secret key file: /home/go-ethereum/geth-tutorial/keystore/UTC--2022-
- You must REMEMBER your password! Without the password, it's impossible to decrypt the key! - You must REMEMBER your password! Without the password, it's impossible to decrypt the key!
``` ```
It is important to save the account address and the password somewhere secure. They will be used It is important to save the account address and the password somewhere secure. They will be used again later in this tutorial. Please note that the account address shown in the code snippets above and later in this tutorials are examples - those generated by followers of this tutorial will be different. The account generated above can be used as the main account throughout the remainder of this tutorial. However in order to demonstrate transactions between accounts it is
again later in this tutorial. Please note that the account address shown in the code snippets also necessary to have a second account. A second account can be added to the same keystore by precisely repeating the previous steps, providing the same password.
above and later in this tutorials are examples - those generated by followers of this tutorial
will be different. The account generated above can be used as the main account throughout the
remainder of this tutorial. However in order to demonstrate transactions between accounts it is
also necessary to have a second account. A second account can be added to the same keystore by
precisely repeating the previous steps, providing the same password.
Notice that the path to the secret key includes a long filename that starts `UTC--`. This is the Notice that the path to the secret key includes a long filename that starts `UTC--`. This is the name of the file that contains the keys for the new account. It is **extremely important** that this file stays secure because it contains the secret key used to control access to any funds associated with the account. The file should be backed up securely along with the password used to encrypt it. If the file or the password is lost, then so is access to the funds in the account. If someone else gains access to the keyfile and password, they have access to any assets in the account.
name of the file that contains the keys for the new account. It is **extremely important** that
this file stays secure because it contains the secret key used to control access to any funds
associated with the account. The file should be backed up securely along with the password
used to encrypt it. If the file or the password is lost, then so is access to the funds in
the account. If someone else gains access to the keyfile and password, they have access to any
assets in the account.
## Step 2: Start Geth ## Step 2: Start Geth
Geth is the Ethereum client that will connect the computer to the Ethereum network. Geth is the Ethereum client that will connect the computer to the Ethereum network. In this tutorial the network is Goerli, an Ethereum testnet. Testnets are used to test Ethereum client software and smart contracts in an environment where no real-world value is at risk. To start Geth, run the Geth executable file passing argument that define the data directory (where Geth should save blockchain data), the network ID and the sync mode. For this tutorial, snap sync is recommended
In this tutorial the network is Goerli, an Ethereum testnet. Testnets are used to test (see [here](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/) for reasons why). The following command should be run in the terminal:
Ethereum client software and smart contracts in an environment where no real-world value
is at risk. To start Geth, run the Geth executable file passing argument that define the
data directory (where Geth should save blockchain data), the network ID and the sync mode.
For this tutorial, snap sync is recommended
(see [here](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/) for reasons why).
The following command should be run in the terminal:
```shell ```shell
geth --datadir geth-tutorial --goerli --syncmode snap geth --datadir geth-tutorial --goerli --syncmode snap
@ -162,76 +103,42 @@ WARN [02-10|13:59:06.998] Light client mode is an experimental feature
INFO [02-10|13:59:08.793] Block synchronisation started INFO [02-10|13:59:08.793] Block synchronisation started
``` ```
This indicates that Geth has started up and is searching for peers to connect to. Once it finds peers This indicates that Geth has started up and is searching for peers to connect to. Once it finds peers it can request block headers from them, starting at the genesis block for the Goerli blockchain. Geth continues to download blocks sequentially, saving the data in files in `/go-ethereum/geth-tutorial/geth/chaindata/`.
it can request block headers from them, starting at the genesis block for the Goerli blockchain. This is confirmed by the logs printed to the terminal. There should be a rapidly-growing sequence of logs in the terminal with the following syntax:
Geth continues to download blocks sequentially, saving the data in files in `/go-ethereum/geth-tutorial/geth/chaindata/`.
This is confirmed by the logs printed to the terminal. There should be a rapidly-growing sequence of logs in the
terminal with the following syntax:
```terminal ```terminal
INFO [04-29][15:54:09.238] Looking for peers peercount=2 tried=0 static=0 INFO [04-29][15:54:09.238] Looking for peers peercount=2 tried=0 static=0
INFO [04-29][15:54:19.393] Imported new block headers count=2 elapsed=1.127ms number=996288 hash=09f1e3..718c47 age=13h9m5s INFO [04-29][15:54:19.393] Imported new block headers count=2 elapsed=1.127ms number=996288 hash=09f1e3..718c47 age=13h9m5s
INFO [04-29][15:54:19:656] Imported new block receipts count=698 elapsed=4.464ms number=994566 hash=56dc44..007c93 age=13h9m9s INFO [04-29][15:54:19:656] Imported new block receipts count=698 elapsed=4.464ms number=994566 hash=56dc44..007c93 age=13h9m9s
``` ```
These logs indicate that Geth is running as expected. These logs indicate that Geth is running as expected.
If there is no error message reported to the terminal, everything is OK. Geth must be running in If there is no error message reported to the terminal, everything is OK. Geth must be running in order for a user to interact with the Ethereum network. If this terminal is closed down then Geth must be restarted again. Geth can be started and stopped easily, but it must be running for any interaction with Ethereum to take place. To shut down Geth, simply press `CTRL+C` in the Geth terminal. To start it again, run the previous command `geth --datadir <other commands>`.
order for a user to interact with the Ethereum network. If this terminal is closed down then Geth
must be restarted again. Geth can be started and stopped easily, but it must be running for any
interaction with Ethereum to take place. To shut down Geth, simply press `CTRL+C` in the Geth terminal.
To start it again, run the previous command `geth --datadir ... ..`.
{% include note.html content="Snap syncing Goerli will take some time and until the sync is finished {% include note.html content="Snap syncing Goerli will take some time and until the sync is finished you can't use the node to transfer funds. You can also try doing a [light sync](interface/les) which will be much quicker but depends on light servers being available to serve your node the data it needs." %}
you can't use the node to transfer funds. You can also try doing a [light sync](interface/les)
which will be much quicker but depends on light servers being available to serve your node the data it needs." %}
## Step 3: Get Testnet Ether ## Step 3: Get Testnet Ether
In order to make some transactions, the user must fund their account with ether. On Ethereum mainnet, In order to make some transactions, the user must fund their account with ether. On Ethereum mainnet, ether can only be obtained in three ways: 1) by receiving it as a reward for mining/validating; 2) receiving it in a transfer from another Ethereum user or contract; 3) receiving it from an exchange, having paid for it with fiat money. On Ethereum testnets, the ether has no real world value so it can be made freely available via faucets. Faucets allow users to request a transfer of testnet ether to their account.
ether can only be obtained in three ways: 1) by receiving it as a reward for mining/validating; 2)
receiving it in a transfer from another Ethereum user or contract; 3) receiving it from an exchange,
having paid for it with fiat money. On Ethereum testnets, the ether has no real world value so it
can be made freely available via faucets. Faucets allow users to request a transfer of testnet ether
to their account.
The address generated by `geth account new` can be pasted into the Paradigm Multifaucet faucet The address generated by `geth account new` can be pasted into the Paradigm Multifaucet faucet [here](https://fauceth.komputing.org/?chain=1115511). This requires a Twitter login as proof of personhood. The faucets adds ether to the given address on multiple testnets simultaneously, including Goerli. In the next steps Geth will be used to check that the ether has been sent to the given address and send some of it to the second address created earlier.
[here](https://fauceth.komputing.org/?chain=1115511). This requires a Twitter login as proof of
personhood. The faucets adds ether to the given address on multiple testnets simultaneously,
including Goerli. In the next steps Geth will be used to check that the ether has been sent to
the given address and send some of it to the second address created earlier.
## Step 4: Interact with Geth ## Step 4: Interact with Geth
For interacting with the blockchain, Geth provides JSON-RPC APIs. For interacting with the blockchain, Geth provides JSON-RPC APIs.
[JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) is a way to execute specific tasks [JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) is a way to execute specific tasks by sending instructions to Geth in the form of [JSON](https://www.json.org/json-en.html) objects. RPC stands for "Remote Procedure Call" and it refers to the ability to send these JSON-encoded instructions from locations outside of those managed by Geth. It is possible to interact with Geth by sending these JSON encoded instructions directly to Geth using tools such as Curl. However, this is somewhat user-unfriendly and error-prone, especially for more complex instructions. For this reason, there are a set of libraries built on top of JSON-RPC that provide a more user-friendly interface for interacting with Geth. One of the most widely used is Web3.js.
by sending instructions to Geth in the form of [JSON](https://www.json.org/json-en.html) objects.
RPC stands for "Remote Procedure Call" and it refers to the ability to send these JSON-encoded
instructions from locations outside of those managed by Geth. It is possible to interact with Geth
by sending these JSON encoded instructions directly to Geth using tools such as Curl. However,
this is somewhat user-unfriendly and error-prone, especially for more complex instructions. For this
reason, there are a set of libraries built on top of JSON-RPC that provide a more user-friendly
interface for interacting with Geth. One of the most widely used is Web3.js.
Geth provides a Javascript console that exposes the Web3.js API. This means that with Geth running in Geth provides a Javascript console that exposes the Web3.js API. This means that with Geth running in one terminal, a Javascript environment can be opened in another allowing the user to interact with Geth using Web3.js. There are three transport protocols that can be used to connect the Javascript environment to Geth:
one terminal, a Javascript environment can be opened in another allowing the user to interact with
Geth using Web3.js. There are three transport protocols that can be used to connect the Javascript
environment to Geth:
- IPC (Inter-Process Communication): Provides unrestricted access to all APIs, but only works when the - IPC (Inter-Process Communication): Provides unrestricted access to all APIs, but only works when the console is run on the same host as the Geth node.
- console is run on the same host as the Geth node.
- HTTP: By default provides access to the `eth`, `web3` and `net` method namespaces. - HTTP: By default provides access to the `eth`, `web3` and `net` method namespaces.
- Websocket: By default provides access to the `eth`, `web3` and `net` method namespaces. - Websocket: By default provides access to the `eth`, `web3` and `net` method namespaces.
This tutorial will use the IPC option. To do this, the path to Geth's `ipc` file must be known. This tutorial will use the IPC option. To do this, the path to Geth's `ipc` file must be known. By default, this is the `datadir`, in this case `geth-tutorial`. In a new terminal, the following command can be run to start the Javascript console and connect it to Geth using the `geth.ipc` file from the datadir:
By default, this is the `datadir`, in this case `geth-tutorial`. In a new terminal, the following
command can be run to start the Javascript console and connect it to Geth using the `geth.ipc`
file from the datadir:
```shell ```shell
geth attach geth-tutorial/geth.ipc geth attach geth-tutorial/geth.ipc
@ -252,12 +159,9 @@ To exit, press ctrl-d or type exit
The console is now active and connected to Geth. It can now be used to interact with the Ethereum (Goerli) network. The console is now active and connected to Geth. It can now be used to interact with the Ethereum (Goerli) network.
### List of accounts ### List of accounts
Earlier in this tutorial, at least one account was created using `geth account new`. The following Earlier in this tutorial, at least one account was created using `geth account new`. The following command will display the addresses of those two accounts and any others that might have been added to the keystore before or since.
command will display the addresses of those two accounts and any others that might have been added
to the keystore before or since.
```javascript ```javascript
eth.accounts eth.accounts
@ -270,21 +174,13 @@ eth.accounts
### Checking account balance. ### Checking account balance.
Having confirmed that the two addresses created earlier are indeed in the keystore and accessible Having confirmed that the two addresses created earlier are indeed in the keystore and accessible through the Javascript console, it is possible to retrieve information about how much ether they own. The Goerli faucet should have sent 1 ETH to the address provided, meaning that the balance of one of the accounts should be 1 ether and the other should be 0. The following command displays the account balance in the console:
through the Javascript console, it is possible to retrieve information about how much ether they
own. The Goerli faucet should have sent 1 ETH to the address provided, meaning that the balance
of one of the accounts should be 1 ether and the other should be 0. The following command displays
the account balance in the console:
```javascript ```javascript
web3.fromWei(eth.getBalance("0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC"), "ether") web3.fromWei(eth.getBalance("0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC"), "ether")
``` ```
There are actually two instructions sent in the above command. The inner one is the `getBalance` There are actually two instructions sent in the above command. The inner one is the `getBalance` function from the `eth` namespace. This takes the account address as its only argument. By default, this returns the account balance in units of Wei. There are 10<sup>18</sup> Wei to one ether. To present the result in units of ether, `getBalance` is wrapped in the `fromWei` function from the `web3` namespace. Running this command should provide the following result (for the account that
function from the `eth` namespace. This takes the account address as its only argument. By default,
this returns the account balance in units of Wei. There are 10<sup>18</sup> Wei to one ether. To
present the result in units of ether, `getBalance` is wrapped in the `fromWei` function from the
`web3` namespace. Running this command should provide the following result (for the account that
received faucet funds): received faucet funds):
```terminal ```terminal
@ -299,14 +195,7 @@ Repeating the command for the other new account that was not funded from the fau
### Send ether to another account ### Send ether to another account
The command `eth.sendTransaction` can be used to send some ether from one address to another. The command `eth.sendTransaction` can be used to send some ether from one address to another. This command takes three arguments: `from`, `to` and `value`. These define the sender and recipient addresses (as strings) and the amount of Wei to transfer. It is far less error prone to enter the transaction value in units of ether rather than Wei, so the value field can take the return value from the `toWei` function. The following command, run in the Javascript console, sends 0.1 ether from one of the accounts in the keystore to the other. Note that the addresses here are examples - the user must replace the address in the `from` field with the address currently owning 1 ether, and the address in the `to` field with the address currently holding 0 ether.
This command takes three arguments: `from`, `to` and `value`. These define the sender and
recipient addresses (as strings) and the amount of Wei to transfer. It is far less error prone
to enter the transaction value in units of ether rather than Wei, so the value field can take the
return value from the `toWei` function. The following command, run in the Javascript console,
sends 0.1 ether from one of the accounts in the keystore to the other. Note that the addresses
here are examples - the user must replace the address in the `from` field with the address
currently owning 1 ether, and the address in the `to` field with the address currently holding 0 ether.
```javascript ```javascript
eth.sendTransaction({ eth.sendTransaction({
@ -316,14 +205,7 @@ eth.sendTransaction({
}) })
``` ```
This command will return an error message indicating that `authentication is needed: password or unlock`. This command will return an error message indicating that `authentication is needed: password or unlock`. This is a security feature that prevents unauthorized access to sensitive account operations. There are two ways to unlock the account. The first is to start Geth with the account permanently unlocked (by passing `--unlock <address>` at startup). This is not recommended because the account remains unlocked all the time Geth is running, creating a security weakness. Instead, it is better to temporarily unlock the account for the specific transaction. This requires using the `sendTransaction` method from the `personal` namespace instead of the `eth` namespace. The password can be provided as a string in the method call as follows:
This is a security feature that prevents unauthorized access to sensitive account operations.
There are two ways to unlock the account. The first is to start Geth with the account permanently
unlocked (by passing `--unlock <address>` at startup). This is not recommended because the account
remains unlocked all the time Geth is running, creating a security weakness. Instead, it is better
to temporarily unlock the account for the specific transaction. This requires using the `sendTransaction`
method from the `personal` namespace instead of the `eth` namespace. The password can be provided as a
string in the method call as follows:
```sh ```sh
personal.sendTransaction({ personal.sendTransaction({
@ -333,31 +215,23 @@ personal.sendTransaction({
}, "password") }, "password")
``` ```
In the Javascript console, the transaction hash is displayed. This will be used in the next section In the Javascript console, the transaction hash is displayed. This will be used in the next section to retrieve the transaction details.
to retrieve the transaction details.
```terminal ```terminal
"0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb" "0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb"
``` ```
It is also advised to check the account balances using Geth by repeating the instructions from earlier. It is also advised to check the account balances using Geth by repeating the instructions from earlier. At this point in the tutorial, the two accounts in the keystore should have balances just below 0.9 ether (because 0.1 ether has been transferred out and some small amount paid in transaction gas) and 0.1 ether.
At this point in the tutorial, the two accounts in the keystore should have balances just below 0.9
ether (because 0.1 ether has been transferred out and some small amount paid in transaction gas) and 0.1 ether.
### Checking the transaction hash ### Checking the transaction hash
The transaction hash is a unique identifier for this specific transaction that can be used later to The transaction hash is a unique identifier for this specific transaction that can be used later to retrieve the transaction details. For example, the transaction details can be viewed by pasting this hash into the [Goerli block explorer](https://goerli.etherscan.io/). The same information can also be retrieved directly from the Geth node. The hash returned in the previous step can be provided as an argument to `eth.getTransaction` to return the transaction information:
retrieve the transaction details. For example, the transaction details can be viewed by pasting this
hash into the [Goerli block explorer](https://goerli.etherscan.io/). The same information can also
be retrieved directly from the Geth node. The hash returned in the previous step can be provided as
an argument to `eth.getTransaction` to return the transaction information:
```javascript ```javascript
eth.getTransaction("0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb") eth.getTransaction("0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb")
``` ```
This returns the following response (although the actual values for each field will vary because they This returns the following response (although the actual values for each field will vary because they are specific to each transaction):
are specific to each transaction):
```terminal ```terminal
{ {
@ -385,24 +259,11 @@ are specific to each transaction):
## Using Curl ## Using Curl
Up to this point this tutorial has interacted with Geth using the convenience library Web3.js. Up to this point this tutorial has interacted with Geth using the convenience library Web3.js. This library enables the user to send instructions to Geth using a more user-friendly interface compared to sending raw JSON objects. However, it is also possible for the user to send these JSON objects directly to Geth's exposed HTTP port. Curl is a command line tool that sends HTTP requests. This part of the tutorial demonstrates how to check account balances and send a transaction using Curl. This requires Geth to expose an HTTP port to listen for requests. This can be configured at startup by passing the `--http` flag. If no other commands are passed with it, `--http` will expose the default `localhost:8545` port.
This library enables the user to send instructions to Geth using a more user-friendly interface
compared to sending raw JSON objects. However, it is also possible for the user to send these JSON
objects directly to Geth's exposed HTTP port. Curl is a command line tool that sends HTTP requests.
This part of the tutorial demonstrates how to check account balances and send a transaction using Curl.
This requires Geth to expose an HTTP port to listen for requests. This can be configured at startup
by passing the `--http` flag. If no other commands are passed with it, `--http` will expose the
default `localhost:8545` port.
### Checking account balance ### Checking account balance
The command below returns the balance of the given account. This is a HTTP POST request to the local The command below returns the balance of the given account. This is a HTTP POST request to the local port 8545. The `-H` flag is for header information. It is used here to define the format of the incoming payload, which is JSON. The `--data` flag defines the content of the payload, which is a JSON object. That JSON object contains four fields: `jsonrpc` defines the spec version for the JSON-RPC API, `method` is the specific function being invoked, `params` are the function arguments, and `id` is used for ordering transactions. The two arguments passed to `eth_getBalance` are the account address whose balance to check and the block to query (here `latest` is used to check the balance in the most recently mined block).
port 8545. The `-H` flag is for header information. It is used here to define the format of the incoming
payload, which is JSON. The `--data` flag defines the content of the payload, which is a JSON object.
That JSON object contains four fields: `jsonrpc` defines the spec version for the JSON-RPC API, `method`
is the specific function being invoked, `params` are the function arguments, and `id` is used for ordering
transactions. The two arguments passed to `eth_getBalance` are the account address whose balance to check
and the block to query (here `latest` is used to check the balance in the most recently mined block).
```shell ```shell
curl -X POST http://127.0.0.1:8545 \ curl -X POST http://127.0.0.1:8545 \
@ -416,9 +277,7 @@ A successful call will return a response like the one below:
{"jsonrpc":"2.0","id":1,"result":"0xc7d54951f87f7c0"} {"jsonrpc":"2.0","id":1,"result":"0xc7d54951f87f7c0"}
``` ```
The balance is in the `result` field in the returned JSON object. However, it is denominated in Wei and The balance is in the `result` field in the returned JSON object. However, it is denominated in Wei and presented as a hexadecimal string. There are many options for converting this value to a decimal in units of ether, for example by opening a Python console and running:
presented as a hexadecimal string. There are many options for converting this value to a decimal in units
of ether, for example by opening a Python console and running:
```python ```python
0xc7d54951f87f7c0 / 1e18 0xc7d54951f87f7c0 / 1e18
@ -447,19 +306,11 @@ The following information is returned to the terminal:
### Sending Transactions ### Sending Transactions
It is possible to send transactions using raw curl requests too, but this requires unlocking the sender It is possible to send transactions using raw curl requests too, but this requires unlocking the sender account. It is recommended to do this using Clef to manage access to accounts or to use `ipc` instead. The combination of HTTP and unlocked accounts pose a security risk.
account. It is recommended to do this using Clef to manage access to accounts or to use `ipc` instead. The
combination of HTTP and unlocked accounts pose a security risk.
## Summary ## Summary
This tutorial has demonstrated how to generate accounts using Geth's built-in account management tool, This tutorial has demonstrated how to generate accounts using Geth's built-in account management tool, fund them with testnet ether and use those accounts to interact with Ethereum (Goerli) through a Geth node. Checking account balances, sending transactions and retrieving transaction details were explained using
fund them with testnet ether and use those accounts to interact with Ethereum (Goerli) through a Geth the web3.js library via the Geth console and using the JSON-RPC directly using Curl. Note that this is an entry-level tutorial designed to help users get familiar with basic Geth processes, we strongly recommend following this with the [Geth with Clef](/content/docs/getting-started/geth_with_clef) tutorial which will help to
node. Checking account balances, sending transactions and retrieving transaction details were explained using
the web3.js library via the Geth console and using the JSON-RPC directly using Curl. Note that this is an
entry-level tutorial designed to help users get familiar with basic Geth processes, we strongly recommend
following this with the [Geth with Clef](/docs/getting-started/geth_with_clef) tutorial which will help to
adopt more secure account management practices than those outlined here. adopt more secure account management practices than those outlined here.
[cli]: https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line