[DOCS] Update the main getting started guide (#20753)
* In progress * Final first draft * Edits * Final first draft * Update images and post * Remove rogue comment * Respond to comments * Update speed of gifs * Whitespace fixes * Say what's signed by clef * Flip content-type header and JSON-RPC message in examples Co-authored-by: Felix Lange <fjl@twurst.com>
This commit is contained in:
Chris Chinchilla
GitHub
parent
12be83b71c
commit
cfd3e7189b
|
|
@ -4,95 +4,183 @@ permalink: docs/getting-started
|
|||
sort_key: A
|
||||
---
|
||||
|
||||
To use Geth, you need to install it first. You can install the geth software in a variety
|
||||
of ways. These include installing it via your favorite package manager; downloading a
|
||||
standalone pre-built binary; running as a docker container; or building it yourself.
|
||||
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 tutorial, we'll assume you are comfortable with downloading a pre-built binary.
|
||||
Head over to the [install and build](./install-and-build/installing-geth) section and
|
||||
follow the instructions for your operating system if you wish to use a different
|
||||
installation method.
|
||||
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.
|
||||
|
||||
### Downloading Geth
|
||||
This guide uses [Clef](clef/tutorial), which is our preferred tool for signing transactions with Geth,
|
||||
and will replace Geth's account management.
|
||||
|
||||
We distribute all our stable releases and development builds as standalone binaries. These
|
||||
are useful for scenarios where you'd like to: a) install a specific version of our code
|
||||
(e.g., for reproducible environments); b) install on machines without internet access
|
||||
(e.g., air gapped computers); or c) do not like automatic updates and would rather
|
||||
manually install software.
|
||||
## Initialize Clef
|
||||
|
||||
To download Geth, go to the [Downloads page](https://geth.ethereum.org/downloads) and
|
||||
select the latest stable release matching your platform.
|
||||
|
||||
We create the following archives:
|
||||
|
||||
- 32bit, 64bit, ARMv5, ARMv6, ARMv7 and ARM64 archives (`.tar.gz`) on Linux
|
||||
- 64bit archives (`.tar.gz`) on macOS
|
||||
- 32bit and 64bit archives (`.zip`) and installers (`.exe`) on Windows
|
||||
|
||||
For all binaries we provide two options, one containing only Geth, and another containing
|
||||
Geth along with all the developer tools from our repository (`abigen`, `bootnode`,
|
||||
`disasm`, `evm`, `rlpdump`). Read our
|
||||
[`README`](https://github.com/ethereum/go-ethereum#executables) for more information about
|
||||
these executables.
|
||||
|
||||
### Creating an account
|
||||
|
||||
Before starting Geth you first need to create an account that represents a key pair. Use
|
||||
the following command to create a new account and set a password for that account:
|
||||
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.
|
||||
|
||||
```shell
|
||||
geth account new
|
||||
clef init
|
||||
```
|
||||
|
||||
_[Read this guide](./interface/managing-your-accounts) for more details on importing
|
||||
existing Ethereum accounts and other uses of the `account` command._
|
||||
|
||||
|
||||
## Create accounts
|
||||
|
||||
Create two accounts with the `clef newaccount` command,
|
||||
set a password for each of them, and note the public address for each.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
### Sync modes
|
||||
|
||||
Running Geth starts an Ethereum node that can join any existing network, or create a new
|
||||
one. You can start Geth in one of three different sync modes using the `--syncmode "{mode}"`
|
||||
You can start Geth in one of three different sync modes using the `--syncmode "<mode>"`
|
||||
argument that determines what sort of node it is in the network.
|
||||
|
||||
These are:
|
||||
|
||||
- **Full**: Downloads all blocks (including headers, transactions and receipts) and
|
||||
- **Full**: Downloads all blocks (including headers, transactions, and receipts) and
|
||||
generates the state of the blockchain incrementally by executing every block.
|
||||
- **Fast** (Default): Downloads all blocks (including headers, transactions and
|
||||
receipts), verifies all headers, and downloads the state and verifies it against the
|
||||
headers.
|
||||
- **Light**: Downloads all block headers, block data, and verifies some randomly.
|
||||
|
||||
For example:
|
||||
For this tutorial, we use a `light` sync:
|
||||
|
||||
## Start Clef
|
||||
|
||||
Start Clef, setting the keystore and chain id (goerli is 5) for the network we want to connect to:
|
||||
|
||||
```shell
|
||||
geth --syncmode "light"
|
||||
clef --keystore <GETH_LOCATION>/keystore --chainid 5
|
||||
```
|
||||
|
||||
### Javascript Console
|
||||
To begin with, you see errors about a missing keystore, and we fix that soon.
|
||||
|
||||
Once you have an account and Geth is running, you can interact with it by opening another
|
||||
terminal and using the following command to open a JavaScript console:
|
||||
## Start Geth
|
||||
|
||||
The command below also enables the [Geth RPC interface](clef/tutorial)
|
||||
(which we cover below), and sets Clef as the transaction signer.
|
||||
|
||||
```shell
|
||||
geth attach
|
||||
geth --goerli --syncmode "light" --rpc --signer=<CLEF_LOCATION>/clef.ipc
|
||||
```
|
||||
|
||||
If you get the error 'unable to attach to remote geth', try connecting via HTTP as shown below:
|
||||
## Get ETH
|
||||
|
||||
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.
|
||||
|
||||
## 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:
|
||||
|
||||
```shell
|
||||
geth attach http://127.0.0.1:8545
|
||||
geth attach <IPC_LOCATION>
|
||||
```
|
||||
|
||||
In the console you can issue any of the Geth commands, for example, to list all the
|
||||
accounts on the node, use:
|
||||
### Check account balance
|
||||
|
||||
```js
|
||||
> eth.accounts
|
||||
```javascript
|
||||
web3.fromWei(eth.getBalance("<ADDRESS_1>"),"ether")
|
||||
```
|
||||
|
||||
You can also enter the console directly when you start the node with the `console` command:
|
||||
Getting the balance of an account does not require a signed transaction,
|
||||
so Clef does not ask for approval, and Geth returns the value.
|
||||
|
||||
### Send ETH to account
|
||||
|
||||
Send 0.01 ETH from the account that you added ETH to with the Görli faucet,
|
||||
to the second account you created:
|
||||
|
||||
```javascript
|
||||
eth.sendTransaction({from:"<ADDRESS_0>",to:"<ADDRESS_1>", value: web3.toWei(0.01,"ether")})
|
||||
```
|
||||
|
||||
This action does require signing the transaction, so Clef prompts you to approve it, and
|
||||
if you do, asks you for the password you are sending the ETH from. If the password is
|
||||
correct, Geth proceeds with the transaction.
|
||||
|
||||
To check, get the account balance of the second account:
|
||||
|
||||
```javascript
|
||||
web3.fromWei(eth.getBalance("<ADDRESS_1>"),"ether")
|
||||
```
|
||||
|
||||
## Using RPC
|
||||
|
||||
### Connect to RPC
|
||||
|
||||
You can use standard HTTP requests to connect to a Geth node using the RPC APIs, for example:
|
||||
|
||||
```shell
|
||||
geth console --syncmode "light"
|
||||
curl -X POST http://<GETH_IP_ADDRESS>:8545 --data \
|
||||
-H "Content-Type: application/json" \
|
||||
'{"jsonrpc":"2.0", "method":"<API_METHOD>", "params":[], "id":1}'
|
||||
```
|
||||
|
||||
### Check account balance
|
||||
|
||||
```shell
|
||||
curl -X POST http://<GETH_IP_ADDRESS>:8545 --data \
|
||||
-H "Content-Type: application/json" \
|
||||
'{"jsonrpc":"2.0", "method":"eth_getBalance", "params":["<ADDRESS_1>","latest"], "id":1}'
|
||||
```
|
||||
|
||||
Getting the balance of an account does not require a signed transaction,
|
||||
so Clef does not ask for approval, and Geth returns the value.
|
||||
|
||||
### Send ETH to accounts
|
||||
|
||||
Send 0.01 ETH from the account that you added ETH to with the Görli faucet, to the second account you created:
|
||||
|
||||
```shell
|
||||
curl -X POST http://<GETH_IP_ADDRESS>:8545 --data \
|
||||
-H "Content-Type: application/json" \
|
||||
'{"jsonrpc":"2.0", "method":"eth_sendTransaction", "params":[{"from": "<ADDRESS_0>","to": "<ADDRESS_1>","value": "0x9184e72a"}], "id":1}'
|
||||
```
|
||||
|
||||
This action does require signing, so Clef prompts you to approve it, and if you do,
|
||||
asks you for the password you are sending the ETH from. If the password is correct,
|
||||
Geth proceeds with the transaction.
|
||||
|
||||
To check, get the account balance of the second account:
|
||||
|
||||
```shell
|
||||
curl -X POST http://<GETH_IP_ADDRESS>:8545 --data \
|
||||
-H "Content-Type: application/json" \
|
||||
'{"jsonrpc":"2.0", "method":"eth_getBalance", "params":["<ADDRESS_1>","latest"], "id":1}'
|
||||
```
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 136 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 109 KiB |
Loading…
Reference in New Issue