interesting
/
go-ethereum
mirror of https://github.com/ethereum/go-ethereum.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

more markdown formatting

This commit is contained in:
Joe 2022-08-19 15:19:46 +01:00
parent 0bb421adc5
commit f3026eacf3
8 changed files with 81 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
content/docs/fundamentals/Backup--restore.md
View File

@ -1,30 +1,23 @@
---
title: Backup & Restore
description: How to backup and restore keyfiles and blockchain data
---
**Keep secure backups of your keystore and password!**
## Data Directory
All data relating to a specific Geth instance gets written inside a data directory.
The default data directory locations are platform specific:
All data relating to a specific Geth instance gets written inside a data directory. The default data directory locations are platform specific:
* Mac: `~/Library/Ethereum`
* Linux: `~/.ethereum`
* Windows: `%LOCALAPPDATA%\Ethereum`
Accounts are stored in the `keystore` subdirectory. The contents of this directories
should be transportable between nodes, platforms, and client implementations.
Accounts are stored in the `keystore` subdirectory. The contents of this directories should be transportable between nodes, platforms, and client implementations.
To configure the location of the data directory, the `--datadir` parameter can be
specified. See [CLI Options](../interface/command-line-options) for more details.
There may exist multiple data directories for multiple networks (e.g. a separate directory
for Ethereum Mainnet and the Goerli testnet). Each would have subdirectories for their
blockchain data and keystore.
To configure the location of the data directory, the `--datadir` parameter can be specified. See [CLI Options](../interface/command-line-options) for more details. There may exist multiple data directories for multiple networks (e.g. a separate directory for Ethereum Mainnet and the Goerli testnet). Each would have subdirectories for their blockchain data and keystore.
It is important to backup the files in the keystore securely. These files are encrypted
using an account password. This needs to be securely backed up too. There is no way to
decrypt the keys without the password!
It is important to backup the files in the keystore securely. These files are encrypted using an account password. This needs to be securely backed up too. There is no way to decrypt the keys without the password!
## Cleanup
@ -34,8 +27,7 @@ Geth's blockchain and state databases can be removed with:
geth removedb
```
This is useful for deleting an old chain and sync'ing to a new one. It only affects data
directories that can be re-created on synchronisation and does not touch the keystore.
This is useful for deleting an old chain and sync'ing to a new one. It only affects data directories that can be re-created on synchronisation and does not touch the keystore.
## Blockchain Import/Export
@ -45,15 +37,13 @@ Export the blockchain in binary format with:
geth export <filename>
```
Or if you want to back up portions of the chain over time, a first and last block can be
specified. For example, to back up the first epoch:
Or if you want to back up portions of the chain over time, a first and last block can be specified. For example, to back up the first epoch:
```sh
geth export <filename> 0 29999
```
Note that when backing up a partial chain, the file will be appended rather than
truncated.
Note that when backing up a partial chain, the file will be appended rather than truncated.
Import binary-format blockchain exports with:

8
content/docs/fundamentals/Command-Line-Options.md
View File

@ -1,12 +1,10 @@
---
title: Command-line Options
sort_key: A
description: A list of commands for Geth
---
Geth is primarily controlled using the command line. Geth is started using the `geth` command.
Geth is stopped by pressing `ctrl-c`. There are then many combinations of commands that configure
precisely how geth will run. These commands are displayed below. The same information can be
obtained at any time from your Geth instance by running
Geth is primarily controlled using the command line. Geth is started using the `geth` command. Geth is stopped by pressing `ctrl-c`. There are then many combinations of commands that configure precisely how geth will run. These commands are displayed below. The same information can be
obtained at any time from your Geth instance by running:
```sh
geth --help

142
content/docs/fundamentals/account-management.md
View File

@ -1,18 +1,14 @@
---
title: Account Management
sort_key: C
description: Guide to basic account management using Geth's built-in tools
---
The recommended practise for managing accounts in Geth is to use Clef. However, Geth also has its own, convenient
account management tools. Eventually, these built in tools will be deprecated in favour of using Clef as the
default account manager. This page describes account management using Geth's built-in tools. It is recommended to
also visit the following pages that explain how to use Clef.
The recommended practise for managing accounts in Geth is to use Clef. However, Geth also has its own, convenient account management tools. Eventually, these built in tools will be deprecated in favour of using Clef as the default account manager. This page describes account management using Geth's built-in tools. It is recommended to also visit the following pages that explain how to use Clef.
- [Getting started with Clef](/content/docs/getting_started/getting-started-with-clef.md)
- [Introduction to Clef](/content/docs/tools/Clef/Introduction.md)
- [Clef tutorial](/content/docs/tools/Clef/Tutorial.md)
## Account command
Geth's `account` command is used to interact with accounts:
@ -21,13 +17,7 @@ Geth's `account` command is used to interact with accounts:
geth account <command> [options...] [arguments...]
```
The account command enables the user to create new accounts, list existing
accounts, import private keys into a new account, update key formats and update
the passwords that lock each account. In interactive mode, the user is prompted
for passwords in the console when the `account` functions are invoked, whereas
in non-interactive mode passwords to unlock accounts are saved to text files
whose path is passed to Geth at startup. Non-interactive mode is only intended
for use on private networks or known safe environments.
The account command enables the user to create new accounts, list existing accounts, import private keys into a new account, update key formats and update the passwords that lock each account. In interactive mode, the user is prompted for passwords in the console when the `account` functions are invoked, whereas in non-interactive mode passwords to unlock accounts are saved to text files whose path is passed to Geth at startup. Non-interactive mode is only intended for use on private networks or known safe environments.
The `account` subcommands are:
@ -39,8 +29,7 @@ COMMANDS:
import Import a private key into a new account
```
Information about the subcommands can be displayed in the terminal using
`geth account <command> --help`. For example, for the `list` subcommand:
Information about the subcommands can be displayed in the terminal using `geth account <command> --help`. For example, for the `list` subcommand:
```
$ geth account list --help
@ -53,14 +42,11 @@ OPTIONS:
--keystore Directory for the keystore (default = inside the datadir)
```
## Creating new accounts
New accounts can be created using `account new`. This generates a new key
pair and adds them to the `keystore` directory in the `datadir`. To
New accounts can be created using `account new`. This generates a new key pair and adds them to the `keystore` directory in the `datadir`. To
create a new account in the default data directory:
```shell
$ geth account new
```
@ -74,28 +60,19 @@ Repeat Passphrase:
Address: {168bc315a2ee09042d83d7c5811b533620531f67}
```
It is critical to backup the account password safely and securely as it cannot
be retrieved or reset.
It is critical to backup the account password safely and securely as it cannot be retrieved or reset.
{% include note.html content=" If the password provided on account creation is lost
or forgotten, there is no way to retrive it and the account will simply stay locked
forever. The password MUST be backed up safely and securely!
{% include note.html content=" If the password provided on account creation is lost or forgotten, there is no way to retrive it and the account will simply stay locked forever. The password MUST be backed up safely and securely!
**IT IS CRITICAL TO BACKUP THE KEYSTORE AND REMEMBER PASSWORDS**" %}
The newly generated key files can be viewed in `<datadir>/keystore/`. The file naming
format is `UTC--<date>--<address>` where `date` is the date and time of key creation
formatted according to [UTC 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
with zero time offset and seconds precise to eight decimal places. `address` is the 40
hexadecimal characters that make up the account address without a leading `0x`, for example:
The newly generated key files can be viewed in `<datadir>/keystore/`. The file naming format is `UTC--<date>--<address>` where `date` is the date and time of key creation formatted according to [UTC 8601](https://www.iso.org/iso-8601-date-and-time-format.html) with zero time offset and seconds precise to eight decimal places. `address` is the 40 hexadecimal characters that make up the account address without a leading `0x`, for example:
`UTC--2022-05-19T12-34-36.47413510Z--0b85e5a13e118466159b1e1b6a4234e5f9f784bb`
## Listing Accounts
Listing all existing accounts is achieved using the `account list` command. If the
keystore is located anywhere other than the default location its path should be
included with the `keystore` flag. For example, if the datadir is `some-dir`:
Listing all existing accounts is achieved using the `account list` command. If the keystore is located anywhere other than the default location its path should be included with the `keystore` flag. For example, if the datadir is `some-dir`:
```shell
geth account list --keystore some-dir/keystore
@ -108,27 +85,15 @@ Account 0: {5afdd78bdacb56ab1dad28741ea2a0e47fe41331} keystore:///tmp/mykeystore
Account 1: {9acb9ff906641a434803efb474c96a837756287f} keystore:///tmp/mykeystore/UTC--2017-04-28T08-46-52.180688336Z--9acb9ff906641a434803efb474c96a837756287f
```
The ordering of accounts when they are listed is lexicographic, but is effectively
chronological based on time of creation due to the timestamp in the file name. It is
safe to transfer the entire `keystore` directory or individual key files between
Ethereum nodes. This is important because when accounts are added from other nodes
the order of accounts in the keystore may change. It is therefore important not to
rely on account indexes in scripts or code snippets.
The ordering of accounts when they are listed is lexicographic, but is effectively chronological based on time of creation due to the timestamp in the file name. It is safe to transfer the entire `keystore` directory or individual key files between Ethereum nodes. This is important because when accounts are added from other nodes the order of accounts in the keystore may change. It is therefore important not to rely on account indexes in scripts or code snippets.
## Importing accounts
### Import a keyfile
It is also possible to create a new account by importing a private key. For example,
a user might already have some ether at an address they created using a browser wallet
and now wish to use a new Geth node to interact with their funds. In this case, the
private key can be exported from the browser wallet and imported into Geth. Geth requires
the private key to be stored as a file which contains the private key as unencrypted
canonical elliptic curve bytes encoded into hex (i.e. plain text key without leading 0x).
The new account is then saved in encrypted format, protected by a passphrase the user
provides on request. As always, this passphrase must be securely and safely backed
up - there is no way to retrieve or reset it if it is forgotten!
It is also possible to create a new account by importing a private key. For example, a user might already have some ether at an address they created using a browser wallet and now wish to use a new Geth node to interact with their funds. In this case, the private key can be exported from the browser wallet and imported into Geth. Geth requires the private key to be stored as a file which contains the private key as unencrypted
canonical elliptic curve bytes encoded into hex (i.e. plain text key without leading 0x). The new account is then saved in encrypted format, protected by a passphrase the user provides on request. As always, this passphrase must be securely and safely backed up - there is no way to retrieve or reset it if it is forgotten!
```shell
$ geth account import --datadir /some-dir ./keyfile
@ -143,19 +108,14 @@ Repeat Passphrase:
Address: {7f444580bfef4b9bc7e14eb7fb2a029336b07c9d}
```
This import/export process is not necessary for transferring accounts between Geth
instances because the key files can simply be copied directly from one keystore to another.
This import/export process is not necessary for transferring accounts between Geth instances because the key files can simply be copied directly from one keystore to another.
It is also possible to import an account in non-interactive mode by saving the account
password as plaintext in a `.txt` file and passing its path with the `--password` flag
on startup.
It is also possible to import an account in non-interactive mode by saving the account password as plaintext in a `.txt` file and passing its path with the `--password` flag on startup.
```shell
geth account import --password path/password.txt path/keyfile
```
In this case, it is important to ensure the password file is not readable by anyone but
the intended user. This can be achieved by changing the file permissions. On Linux, the
following commands update the file permissions so only the current user has access:
In this case, it is important to ensure the password file is not readable by anyone but the intended user. This can be achieved by changing the file permissions. On Linux, the following commands update the file permissions so only the current user has access:
```shell
chmod 700 /path/to/password
@ -165,20 +125,15 @@ cat > /path/to/password
### Import a presale wallet
Assuming the password is known, importing a presale wallet is very easy. The `wallet import`
commands are used, passing the path to the wallet.
Assuming the password is known, importing a presale wallet is very easy. The `wallet import` commands are used, passing the path to the wallet.
```shell
geth wallet import /path/presale.wallet
```
## Updating accounts
The `account update` subcommand is used to unlock an account and migrate it to the newest
format. This is useful for accounts that may have been created in a format that has since
been deprecated. The same command can be used to update the account password. The current
password and account address are needed in order to update the account, as follows:
The `account update` subcommand is used to unlock an account and migrate it to the newest format. This is useful for accounts that may have been created in a format that has since been deprecated. The same command can be used to update the account password. The current password and account address are needed in order to update the account, as follows:
```shell
geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b
@ -197,53 +152,37 @@ Repeat Passphrase:
0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b
```
Alternatively, in non-interactive mode the path to a password file containing the account
password in unencrypted plaintext can be passed with the `--password` flag:
Alternatively, in non-interactive mode the path to a password file containing the account password in unencrypted plaintext can be passed with the `--password` flag:
```shell
geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b --password path/password.txt
```
Updating the account replaces the original file with a new one - this means the original
file is no longer available after it has been updated.
Updating the account replaces the original file with a new one - this means the original file is no longer available after it has been updated.
## Unlocking accounts
In Geth, accounts are locked unless they are explicitly unlocked. If an account is intended
to be used by apps connecting to Geth via RPC then it can be unlocked in non-interactive
mode by passing the `--unlock` flag with a comma-separated list of account addresses
(or keystore indexes) to unlock. This unlocks the accounts for one session only. Including
the `--unlock` flag without any account addresses defaults to unlocking the first account
In Geth, accounts are locked unless they are explicitly unlocked. If an account is intended to be used by apps connecting to Geth via RPC then it can be unlocked in non-interactive mode by passing the `--unlock` flag with a comma-separated list of account addresses (or keystore indexes) to unlock. This unlocks the accounts for one session only. Including the `--unlock` flag without any account addresses defaults to unlocking the first account
in the keystore.
```shell
geth <other commands> --unlock 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b
```
Geth will start and prompt the user to input the account password in the terminal.
Alternatively, the user can provide a password as a text file and pass its path to `--password`:
Geth will start and prompt the user to input the account password in the terminal. Alternatively, the user can provide a password as a text file and pass its path to `--password`:
```shell
geth <other commands> --unlock 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b --password path/password.txt
```
{% include note.html content=" By default,
account **unlocking is forbidden when HTTP or Websocket access is enabled** (i.e. by
passing `--http` or `ws` flag). This is because an attacker that manages to access
the node via the externally-exposed HTTP/WS port can then control the unlocked account.
It is possible to force account unlock by including the `--allow-insecure-unlock`
flag but this is unsafe and **not recommended** except for expert users that completely
understand how it can be used safely. This is not a hypothetical risk:
**there are bots that continually scan for http-enabled Ethereum nodes to attack**" %}
{% include note.html content=" By default, account **unlocking is forbidden when HTTP or Websocket access is enabled** (i.e. by passing `--http` or `ws` flag). This is because an attacker that manages to access the node via the externally-exposed HTTP/WS port can then control the unlocked account.
It is possible to force account unlock by including the `--allow-insecure-unlock` flag but this is unsafe and **not recommended** except for expert users that completely understand how it can be used safely. This is not a hypothetical risk: **there are bots that continually scan for http-enabled Ethereum nodes to attack**" %}
## Accounts in the Javascript console
Account management can also be achieved in the Javascript console attached to a
running Geth instance. Assuming Geth is already running, in a new terminal attach
a Javascript console using the `geth.ipc` file. This file can be found in the data
directory. Assuming the data directory is named `data` the console can be started using:
Account management can also be achieved in the Javascript console attached to a running Geth instance. Assuming Geth is already running, in a new terminal attach a Javascript console using the `geth.ipc` file. This file can be found in the data directory. Assuming the data directory is named `data` the console can be started using:
```shell
geth attach data/geth.ipc
@ -251,18 +190,13 @@ geth attach data/geth.ipc
### New accounts
New accounts can be generated using the Javascript console using `personal.newAccount()`.
A new password is requested in the console and successful account creation is confirmed
by the new account address being displayed.
New accounts can be generated using the Javascript console using `personal.newAccount()`. A new password is requested in the console and successful account creation is confirmed by the new account address being displayed.
```shell
personal.newAccount()
```
Accounts can also be created by importing private keys directly in the Javascript console.
The private key is passed as an unencrypted hex-encoded string to `personal.importRawKey()`
along with a passphrase that will be used to encrypt the key. A new key file will be
generated from the private key and saved to the keystore.
Accounts can also be created by importing private keys directly in the Javascript console. The private key is passed as an unencrypted hex-encoded string to `personal.importRawKey()` along with a passphrase that will be used to encrypt the key. A new key file will be generated from the private key and saved to the keystore.
```shell
personal.importRawKey("hexstringkey", "password")
@ -270,8 +204,7 @@ personal.importRawKey("hexstringkey", "password")
### Listing accounts
The `accounts` function in the `eth` namespace can be used to list the accounts that
currently exist in the keystore.:
The `accounts` function in the `eth` namespace can be used to list the accounts that currently exist in the keystore.:
```
eth.accounts
@ -299,28 +232,19 @@ Passphrase:
true
```
This unlocked account can now be used to sign and send transactions. it is also possible to
pass the passphrase as an argument to `personal.unlockAccount()` along with a duration
after which the accout will automatically re-lock (in seconds), as follows:
This unlocked account can now be used to sign and send transactions. it is also possible to pass the passphrase as an argument to `personal.unlockAccount()` along with a duration after which the accout will automatically re-lock (in seconds), as follows:
```shell
personal.unlockAccount(eth.accounts[1], "passphrase", 60)
```
This unlocks the account for 60 seconds. However, this is not recommended because the
command history is logged by the Javascript console which could compromise the security
of the account. An unlocked account can be manually re-locked using `personal.lockAccount()`,
passing the address as the sole argument.
This unlocks the account for 60 seconds. However, this is not recommended because the command history is logged by the Javascript console which could compromise the security of the account. An unlocked account can be manually re-locked using `personal.lockAccount()`, passing the address as the sole argument.
### Unlocking for transactions
Sending transactions from the Javascript console also requires the sender account to be
unlocked. There are two ways to send transactions: `eth.sendTransaction` and `personal.sendTransaction`.
The difference between these two functions is that `eth.sendTransaction` requires the account to be
unlocked globally, at the node level (i.e., by unlocking it on the command line at the start of
the Geth session). On the other hand, `personal.sendTransaction` takes a passphrase argument
that unlocks the account temporarily in order to sign the transaction, then locks it again
Sending transactions from the Javascript console also requires the sender account to be unlocked. There are two ways to send transactions: `eth.sendTransaction` and `personal.sendTransaction`. The difference between these two functions is that `eth.sendTransaction` requires the account to be
unlocked globally, at the node level (i.e., by unlocking it on the command line at the start of the Geth session). On the other hand, `personal.sendTransaction` takes a passphrase argument that unlocks the account temporarily in order to sign the transaction, then locks it again
immediately afterwards. For example, to send 5 ether between two accounts in the keystore:
```shell
@ -335,6 +259,4 @@ personal.sendTransaction(tx, "password")
## Summary
This page has demonstrated how to use Geth's built-in account management tools, both on the
command line and in the Javascript console. Accounts are stored encrypted by a password.
It is critical that the account passwords and the keystore directory are safely and securely backed up.
This page has demonstrated how to use Geth's built-in account management tools, both on the command line and in the Javascript console. Accounts are stored encrypted by a password. It is critical that the account passwords and the keystore directory are safely and securely backed up.

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

@ -1,6 +1,6 @@
---
title: Light client
sort_key: B
description: Intriduction to Geth's light sync mode
---
Running a full node is the most trustless, private, decentralized and censorship resistant way to interact with Ethereum. It is also the best choice for the health of the network, because a decentralized network relies on having many individual nodes that independently verify the head of the chain. In a full node a copy of the blockchain is stored locally enabling users to verify incoming data against a local source of truth. However, running a full node requires a lot of disk space and non-negligible CPU allocation and takes hours (for snap sync) or days (for full sync) to sync the blockchain from genesis. Geth also offers a light mode that overcomes these issues and provides some of the benefits of running a node but requires only a fraction of the resources.

37
content/docs/fundamentals/node-architecture.md
View File

@ -1,52 +1,29 @@
---
title: Node architecture
root: ..
description: Introduction to how Ethereum nodes are organized and where Geth fits.
---
## Node architecture
Geth is an [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients).
Originally, an execution client alone was enough to run a full Ethereum node.
However, ever since Ethereum turned off [proof-of-work](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/) and implemented [proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/),
Geth has needed to be coupled to another piece of software called a
[“consensus client”](https://ethereum.org/en/developers/docs/nodes-and-clients/#consensus-clients) in order to
keep track of the Ethereum blockchain.
Geth is an [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients). Originally, an execution client alone was enough to run a full Ethereum node. However, ever since Ethereum turned off [proof-of-work](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/) and implemented [proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/), Geth has needed to be coupled to another piece of software called a [“consensus client”](https://ethereum.org/en/developers/docs/nodes-and-clients/#consensus-clients) in order to keep track of the Ethereum blockchain.
The execution client is responsible for transaction handling, transaction gossip, state management and supporting
the Ethereum Virtual Machine ([EVM])(https://ethereum.org/en/developers/docs/evm/). However, Geth is **not**
responsible for block building, block gossiping or handling consensus logic. These are in the remit of the
consensus client.
The execution client is responsible for transaction handling, transaction gossip, state management and supporting the Ethereum Virtual Machine ([EVM])(https://ethereum.org/en/developers/docs/evm/). However, Geth is **not** responsible for block building, block gossiping or handling consensus logic. These are in the remit of the consensus client.
The relationship between the two Ethereum clients is shown in the schematic below. The two clients each
connect to their own respective peer-to-peer (P2P) networks. This is because the execution clients gossip
transactions over their P2P network enabling them to manage their local transaction pool. The consensus clients
gossip blocks over their P2P network, enabling consensus and chain growth.
The relationship between the two Ethereum clients is shown in the schematic below. The two clients each connect to their own respective peer-to-peer (P2P) networks. This is because the execution clients gossip transactions over their P2P network enabling them to manage their local transaction pool. The consensus clients gossip blocks over their P2P network, enabling consensus and chain growth.
![node-architecture](/assets/node_architecture.png)
For this two-client structure to work, consensus clients must be able to pass bundles of transactions to
Geth to be executed. Executing the transactions locally is how the client validates that the transactions
do not violate any Ethereum rules and that the proposed update to Ethereum’s state is correct. Likewise,
when the node is selected to be a block producer the consensus client must be able to request bundles of
transactions from Geth to include in the new block. This inter-client communication is handled by a local
RPC connection using the [engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md)
which is exposed internally over port 8551 by default.
For this two-client structure to work, consensus clients must be able to pass bundles of transactions to Geth to be executed. Executing the transactions locally is how the client validates that the transactions do not violate any Ethereum rules and that the proposed update to Ethereum’s state is correct. Likewise, when the node is selected to be a block producer the consensus client must be able to request bundles of transactions from Geth to include in the new block. This inter-client communication is handled by a local RPC connection using the [engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md) which is exposed internally over port 8551 by default.
## What does Geth do?
As an execution client, Geth is responsible for creating the execution payloads - the bundles of transactions -
that consensus clients include in their blocks. Geth is also responsible for re-executing transactions that arrive
in new blocks to ensure they are valid. Executing transactions is done on Geth's embedded computer, known as the
Ethereum Virtual Machine (EVM).
As an execution client, Geth is responsible for creating the execution payloads - the bundles of transactions - that consensus clients include in their blocks. Geth is also responsible for re-executing transactions that arrive in new blocks to ensure they are valid. Executing transactions is done on Geth's embedded computer, known as the Ethereum Virtual Machine (EVM).
Geth also offers a user-interface to Ethereum by exposing a set of RPC methods that enable users to query the
Ethereum blockchain, submit transactions and deploy smart contracts using the command line, programmatically
using Geth's built-in console, web3 development frameworks such as Hardhat and Truffle or via web-apps and wallets.
Geth also offers a user-interface to Ethereum by exposing a set of RPC methods that enable users to query the Ethereum blockchain, submit transactions and deploy smart contracts using the command line, programmatically using Geth's built-in console, web3 development frameworks such as Hardhat and Truffle or via web-apps and wallets.
In summary, Geth is:
- a user gateway to Ethereum
- home to the Ethereum Virtual Machine, Ethereum's state and transaction pool.
Read more about [proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/).

19
content/docs/fundamentals/peer-to-peer.md
View File

@ -1,9 +1,9 @@
---
title: Connecting To The Network
sort_key: B
description: Guide to connecting Geth to a peer-to-peer network
---
The default behaviour for Geth is to connect to Ethereum Mainnet. However, Geth can also connect to public testnets, [private networks](/docs/getting-started/private-net) and [local testnets](/docs/getting-started/dev-mode). Command line flags are provided for connecting to the popular public testnets:
The default behaviour for Geth is to connect to Ethereum Mainnet. However, Geth can also connect to public testnets, [private networks](/content/docs/developers/geth-developer/Private-Network.md) and [local testnets](/docs/getting-started/dev-mode). Command line flags are provided for connecting to the popular public testnets:
- `--ropsten`, Ropsten proof-of-work test network
- `--rinkeby`, Rinkeby proof-of-authority test network
@ -15,13 +15,11 @@ Providing these flags at startup instructs Geth to connect to the specific publi
**Note:** network selection is not persisted in the config file. To connect to a pre-defined network you must always enable it explicitly, even when using the `--config` flag to load other configuration values. For example:
```shell
# Generate desired config file. You must specify testnet here.
geth --goerli --syncmode "full" ... dumpconfig > goerli.toml
# Start geth with given config file. Here too the testnet must be specified.
geth --goerli --config goerli.toml
```
## Finding peers
@ -31,9 +29,7 @@ Geth continuously attempts to connect to other nodes on the network until it has
A new node entering the network for the first time gets introduced to a set of peers by a bootstrap node ("bootnode") whose sole purpose is to connect new nodes to peers. The endpoints for these bootnodes are hardcoded into Geth, but they can also be specified by providing the `--bootnode` flag along with comma-separated bootnode addresses in the form of [enodes](https://ethereum.org/en/developers/docs/networking-layer/network-addresses/#enode) on startup. For example:
```shell
geth --bootnodes enode://pubkey1@ip1:port1,enode://pubkey2@ip2:port2,enode://pubkey3@ip3:port3
```
There are scenarios where disabling the discovery process is useful, for example for running a local test node or an experimental test network with known, fixed nodes. This can be achieved by passing the `--nodiscover` flag to Geth at startup.
@ -47,24 +43,22 @@ There are occasions when Geth simply fails to connect to peers. The common reaso
- Some firewall configurations can prohibit UDP traffic. The static nodes feature or `admin.addPeer()` on the console can be used to configure connections manually.
- Running Geth in [light mode](/docs/interface/les) often leads to connectivity issues because there are few nodes running light servers. There is no easy fix for this except to switch Geth out of light mode.
- Running Geth in [light mode](/content/docs/fundamentals/les.md) often leads to connectivity issues because there are few nodes running light servers. There is no easy fix for this except to switch Geth out of light mode.
- The public test network Geth is connecting to might be deprecated or have a low number of active nodes that are hard to find. In this case, the best action is to switch to an alternative test network.
## Checking Connectivity
The `net` module has two attributes that enable checking node connectivity from the [interactive Javascript console](/docs/interface/javascript-console). These are `net.listening` which reports whether the Geth node is listening for inbound requests, and `peerCount` which returns the number of active peers the node is connected to.
The `net` module has two attributes that enable checking node connectivity from the [interactive Javascript console](/content/docs/interacting_with_geth/JavaScript-Console.md). These are `net.listening` which reports whether the Geth node is listening for inbound requests, and `peerCount` which returns the number of active peers the node is connected to.
```javascript
> net.listening
true
> net.peerCount
4
```
Functions in the `admin` module provide more information about the connected peers, including their IP address, port number, supported protocols etc. Calling `admin.peers` returns this information for all connected peers.
@ -117,7 +111,7 @@ The `admin` module also includes functions for gathering information about the l
## Custom Networks
It is often useful for developers to connect to private test networks rather than public testnets or Etheruem mainnet. These sandbox environments allow block creation without competing against other miners, easy minting of test ether and give freedom to break things without real-world consequences. A private network is started by providing a value to `--networkid` that is not used by any other existing public network ([Chainlist](https://chainlist.org)) and creating a custom `genesis.json` file. Detailed instructions for this are available on the [Private Networks page](/docs/interface/private-network).
It is often useful for developers to connect to private test networks rather than public testnets or Etheruem mainnet. These sandbox environments allow block creation without competing against other miners, easy minting of test ether and give freedom to break things without real-world consequences. A private network is started by providing a value to `--networkid` that is not used by any other existing public network ([Chainlist](https://chainlist.org)) and creating a custom `genesis.json` file. Detailed instructions for this are available on the [Private Networks page](content/docs/developers/geth-developer/Private-Network.md).
## Static nodes
@ -134,9 +128,7 @@ Geth also supports static nodes. Static nodes are specific peers that are always
Static nodes can also be added at runtime in the Javascript console by passing an enode address to `admin.addPeer()`:
```javascript
admin.addPeer("enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303")
```
## Peer limit
@ -159,7 +151,6 @@ Nodes can be added using the `admin.addTrustedPeer()` call in the Javascript con
admin.addTrustedPeer("enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303")
```
## Summary
Geth connects to Ethereum Mainnet by default. However, this behaviour can be changed using combinations of command line flags and files. This page has described the various options available for connecting a Geth node to Ethereum, public testnets and private networks.

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

@ -1,14 +1,11 @@
---
title: Security
root: ..
description: A primer on Geth security best practice.
---
## Downloading Geth
Download Geth using the links on our [Downloads](/downloads) page. The SHA256 hashes of the downloaded files
can be compared to ours to ensure precise consistency with our releases. This protects against malicious code being
inadvertently downloaded from an adversarial source. The same measures should also be taken to download trusted
consensus client software.
Download Geth using the links on our [Downloads](/downloads) page. The SHA256 hashes of the downloaded files can be compared to ours to ensure precise consistency with our releases. This protects against malicious code being inadvertently downloaded from an adversarial source. The same measures should also be taken to download trusted consensus client software.
## Networking security

44
content/docs/tools/Clef/CliqueSigning.md
View File

@ -16,7 +16,7 @@ It is useful to have basic knowledge of private networks and Clef. These topics
## Prepping a Clique network
First of all, set up a rudimentary testnet to have something to sign. Create a new keystore (password `testtesttest`):
First of all, set up a rudimentary testnet to have something to sign. Create a new keystore (password `testtesttest`)
```terminal
$ geth account new --datadir ./ddir
@ -75,16 +75,16 @@ INFO [06-16|11:14:54.125] Persisted trie from memory database nodes=1 size=
INFO [06-16|11:14:54.125] Successfully wrote genesis state database=lightchaindata hash=187412..4deb98
```
At this point a Clique network exists with blocks that can be signed.
At this point a Geth has been initiated with a genesis configuration.
## Prepping Clef
In order to make use of Clef for signing:
In order to make use of `clef` for signing:
1. Ensure Clef knows the password for the keystore.
2. Ensure Clef auto-approves clique signing requests.
1. Ensure `clef` knows the password for the keystore.
2. Ensure `clef` auto-approves clique signing requests.
These two things are independent of each other. First of all, however, Clef must be initiated (for this example the password is `clefclefclef`)
These two things are independent of each other. First of all, however, `clef` must be initiated (for this example the password is `clefclefclef`)
```
$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15 --suppress-bootwarn init
@ -110,7 +110,7 @@ After this operation, `clef` has it's own vault where it can store secrets and a
## Storing passwords in `clef`
With that done, Clef can be made aware of the password. To do this `setpw <address>` is invoked to store a password for a given address. Clef asks for the password, and it also asks for the Clef master-password, in order to update and store the new secrets inside Clef vault.
With that done, `clef` can be made aware of the password. To do this `setpw <address>` is invoked to store a password for a given address. `clef` asks for the password, and it also asks for the master-password, in order to update and store the new secrets inside the vault.
```
$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15 --suppress-bootwarn setpw 0x9CD932F670F7eDe5dE86F756A6D02548e5899f47
@ -128,7 +128,7 @@ At this point, if Clef is used as a sealer, each block would require manual appr
### Testing stored password
To test that the stored password is correct and being properly handled by Clef, first start Clef:
To test that the stored password is correct and being properly handled by Clef, first start `clef`:
```sh
$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15 --suppress-bootwarn
@ -160,13 +160,13 @@ Approve? [y/N]:
DEBUG[06-16|11:36:42.499] Served account_list reqid=2 duration=3.213768195s
```
After this, Get will start asking Clef to sign things:
After this, Geth will start asking `clef` to sign things:
```
-------- Sign data request--------------
Account: 0x9CD932F670F7eDe5dE86F756A6D02548e5899f47 [chksum ok]
messages:
  Clique header [clique]: "clique header 1 [0x9b08fa3705e8b6e1b327d84f7936c21a3cb11810d9344dc4473f78f8da71e571]"
Clique header [clique]: "clique header 1 [0x9b08fa3705e8b6e1b327d84f7936c21a3cb11810d9344dc4473f78f8da71e571]"
raw data:
"\xf9\x02\x14\xa0\x18t\x12:\x91f\xa2\x90U\b\xf9\xac\xc02i\xffs\x9f\xf4\xc9⮷!\x0f\x16\xaa?#M똠\x1d\xccM\xe8\xde\xc7]z\xab\x85\xb5g\xb6\xcc\xd4\x1a\xd3\x12E\x1b\x94\x8at\x13\xf0\xa1B\xfd@ԓG\x94\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xa0]1%\n\xfc\xee'\xd0e\xce\xc7t\xcc\\?\t4v\x8f\x06\xcb\xf8\xa0P5\xfeN\xea\x0ff\xfe\x9c\xa0V\xe8\x1f\x17\x1b\xccU\xa6\xff\x83E\xe6\x92\xc0\xf8n[H\xe0\x1b\x99l\xad\xc0\x01b/\xb5\xe3c\xb4!\xa0V\xe8\x1f\x17\x1b\xccU\xa6\xff\x83E\xe6\x92\xc0\xf8n[H\xe0\x1b\x99l\xad\xc0\x01b/\xb5\xe3c\xb4!\xb9\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x01\x83z0\x83\x80\x84b\xaa\xf9\xaa\xa0\u0603\x01\n\x14\x84geth\x88go1.18.1\x85linux\x00\x00\x00\x00\x00\x00\x00\xa0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x88\x00\x00\x00\x00\x00\x00\x00\x00"
data hash: 0x9589ed81e959db6330b3d70e5f8e426fb683d03512f203009f7e41fc70662d03
@ -185,7 +185,6 @@ And indeed, after approving with `y`, the password is not required - the signed
```terminal
INFO [06-16|11:36:46.714] Successfully sealed new block number=1 sealhash=9589ed..662d03 hash=bd20b9..af8b87 elapsed=4.214s
```
This mode of operation offers quite a poor UX because each block to be sealed requires manual approval. That is fixed in the following section.
## Using rules to approve blocks
@ -217,13 +216,13 @@ Password:
INFO [06-16|13:49:00.298] Ruleset attestation updated sha256=54aae496c3f0eda063a62c73ee284ca9fae3f43b401da847ef30ea30e85e35d1
```
And Clef can be started, pointing out the `rules.js` file.
And `clef` can be started, pointing out the `rules.js` file.
```sh
$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15 --suppress-bootwarn --rules ./rules.js
```
Once Geth starts asking Clef to seal blocks, the data will be displayed. From that data, rules can be defined that allow signing clique headers but nothing else.
Once Geth starts asking `clef` to seal blocks, the data will be displayed. From that data, rules can be defined that allow signing clique headers but nothing else.
The actual data that gets passed to the js environment (and which the ruleset display in the terminal) looks as follows:
```json
@ -272,7 +271,7 @@ To create an extremely trustless ruleset, the `raw_data` could be verified to en
0000000000000000,
]
```
However, `messages` could also be used. They do not come from the external caller, but are generated from the Clef internals: Clef parsed the incoming request and verified the Clique wellformedness of the content. The following simply checks for such a message:
However, `messages` could also be used. They do not come from the external caller, but are generated inernally: `clef` parsed the incoming request and verified the Clique wellformedness of the content. The following simply checks for such a message:
```js
function OnSignerStartup(info){}
@ -307,7 +306,7 @@ Decrypt master seed of clef
Password:
INFO [06-16|14:18:53.476] Ruleset attestation updated sha256=7d5036d22d1cc66599e7050fb1877f4e48b89453678c38eea06e3525996c2379
```
Run clef:
Run `clef`:
```sh
$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15 --suppress-bootwarn --rules ./rules.js
@ -317,7 +316,7 @@ Run Geth:
```sh
$ geth --datadir ./ddir --signer ./clef/clef.ipc --mine
```
And Clef should now happily sign blocks:
And `clef` should now happily sign blocks:
```terminal
DEBUG[06-16|14:20:02.136] Served account_version reqid=1 duration="131.38µs"
@ -334,7 +333,11 @@ DEBUG[06-16|14:20:33.584] Served account_signData reqid=5 durat
## Refinements
If an attacker finds the Clef "external" interface (which would only happen if you start it with `--http` enabled), they cannot sign arbitrary data or transactions. However, they could still make it sign e.g. 1000 versions of a certain block height, making the chain very unstable.
If an attacker find the Clef "external" interface (which would only happen if you start it with `http` enabled), they
- cannot make it sign arbitrary transactions,
- cannot sign arbitrary data message,
However, they could still make it sign e.g. 1000 versions of a certain block height, making the chain very unstable.
It is possible for rule execution to be stateful (i.e. storing data). In this case, one could, for example, store what block heights have been sealed and reject sealing a particular block height twice. In other words, these rules could be used to build a miniature version of an execution layer slashing-db.
@ -377,13 +380,12 @@ JS:> number 46 latest 45
INFO [06-16|22:26:44.313] Op approved
DEBUG[06-16|22:26:45.317] Served account_signData reqid=4 duration=1.010612774s
```
This might be a bit over-the-top, security-wise, and may cause problems if, for some reason, a clique-deadlock needs to be resolved by rolling back and continuing on a side-chain. It is mainly meant as a demonstration that rules can use Javascript and statefulness to construct very intricate signing logic.
This might be a bit over-the-top security-wise, and may cause problems if, for some reason, a clique-deadlock needs to be resolved by rolling back and continuing on a side-chain. It is mainly meant as a demonstration that rules can use Javascript and statefulness to construct very intricate signing logic.
## TLDR quick-version
Creation and attestation is a one-off event:
```sh
## Create the rules-file
cat << END > rules.js
@ -411,7 +413,7 @@ clef --keystore ./ddir/keystore \
--suppress-bootwarn --signersecret ./clefpw \
attest `sha256sum rules.js | cut -f1`
```
The normal startup command for Clef:
The normal startup command for `clef`:
```sh
clef --keystore ./ddir/keystore \
--configdir ./clef --chainid 15 \
@ -422,4 +424,4 @@ For Geth, the only change is to provide `--signer <path to clef ipc>`.
## Summary
Clef can be used as a signer that automatically seals Clique blocks. This is a much more secure option than unlocking accounts using Geth's built-in account manager.
Clef can be used as a signer that automatically seals Clique blocks. This is a much more secure option than unlocking accounts using Geth's built-in account manager.