gaspersic/go-ethereum
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update Getting Started guide (#24357)

Browse Source 
This makes the text easier to follow for beginners.

Co-authored-by: Felix Lange <fjl@twurst.com>
This commit is contained in:
Nwokocha wisdom maduabuchi
2022-02-17 19:21:28 +01:00
committed by GitHub
parent 6cde301e53
commit 58cd25b166
3 changed files with 681 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

497
docs/_getting-started/index.md
View File

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