rm mining.md, update account and CLI pages
This commit is contained in:
Joe
parent
67892d6c84
commit
45550ace2c
@ -3,8 +3,18 @@ title: Command-line Options
|
||||
sort_key: A
|
||||
---
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
```
|
||||
$ geth --help
|
||||
NAME:
|
||||
geth - the go-ethereum command line interface
|
||||
|
||||
|
||||
@ -1,258 +0,0 @@
|
||||
---
|
||||
title: Account Management
|
||||
sort_key: C
|
||||
---
|
||||
|
||||
It is recommended to use the external key manager Clef for interacting with Geth because it can be run from secure external devices and has additional security benefits such as the ability to sign transactions according to custom rules. Instructions for setting up and using Clef can be found on the [Clef page](../clef/tutorial). However, Geth also has its own built-in account management tools that are more convenient and secure enough for many use-cases. This page will describe how to manage accounts using Geth's built in tools. The command line is considered first and then managing accounts from the Javascript console is considered in a [separate section](#accounts-in-the-javascript-console).
|
||||
|
||||
|
||||
## Account command
|
||||
|
||||
Interacting with accounts is achieved using Geth's `account` command:
|
||||
|
||||
```
|
||||
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` subcommands are:
|
||||
|
||||
```
|
||||
COMMANDS:
|
||||
list Print summary of existing accounts
|
||||
new Create a new account
|
||||
update Update an existing account
|
||||
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:
|
||||
|
||||
```
|
||||
$ geth account list --help
|
||||
list [command options] [arguments...]
|
||||
|
||||
Print a short summary of all accounts
|
||||
|
||||
OPTIONS:
|
||||
--datadir "/home/.ethereum" Data directory for the databases and keystore
|
||||
--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 create a new account in the default data directory:
|
||||
|
||||
|
||||
```shell
|
||||
$ geth account new
|
||||
```
|
||||
|
||||
This returns the following to the terminal:
|
||||
|
||||
```terminal
|
||||
Your new account is locked with a password. Please give a password. Do not forget this password.
|
||||
Passphrase:
|
||||
Repeat Passphrase:
|
||||
Address: {168bc315a2ee09042d83d7c5811b533620531f67}
|
||||
```
|
||||
|
||||
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! **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:
|
||||
|
||||
`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`:
|
||||
|
||||
```shell
|
||||
geth account list --keystore some-dir/keystore
|
||||
```
|
||||
|
||||
This command returns the following to the terminal for a keystore with two files:
|
||||
|
||||
```terminal
|
||||
Account 0: {5afdd78bdacb56ab1dad28741ea2a0e47fe41331} keystore:///tmp/mykeystore/UTC--2017-04-28T08-46-27.437847599Z--5afdd78bdacb56ab1dad28741ea2a0e47fe41331
|
||||
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.
|
||||
|
||||
|
||||
## 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!
|
||||
|
||||
```shell
|
||||
$ geth account import --datadir /some-dir ./keyfile
|
||||
```
|
||||
|
||||
The following information will be displayed in the terminal, indicating a successful import:
|
||||
|
||||
```terminal
|
||||
Please enter a passphrase now.
|
||||
Passphrase:
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
chmod 700 /path/to/password
|
||||
cat > /path/to/password
|
||||
<type password here>
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
```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:
|
||||
|
||||
```shell
|
||||
geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b
|
||||
```
|
||||
|
||||
The following will be returned to the terminal:
|
||||
|
||||
```terminal
|
||||
Unlocking account a94f5374fce5edbc8e2a8697c15331677e6ebf0b | Attempt 1/3
|
||||
Passphrase:
|
||||
0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b
|
||||
Account 'a94f5374fce5edbc8e2a8697c15331677e6ebf0b' unlocked.
|
||||
Please give a new password. Do not forget this password.
|
||||
Passphrase:
|
||||
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:
|
||||
|
||||
```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.
|
||||
|
||||
|
||||
## 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 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`:
|
||||
|
||||
```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**" %}
|
||||
|
||||
|
||||
## 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:
|
||||
|
||||
```shell
|
||||
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.
|
||||
|
||||
```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.
|
||||
|
||||
```shell
|
||||
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.:
|
||||
|
||||
```
|
||||
eth.accounts
|
||||
```
|
||||
|
||||
or alternatively the same is achieved using:
|
||||
|
||||
```
|
||||
personal.listAccounts
|
||||
```
|
||||
|
||||
This returns an array of account addresses to the terminal.
|
||||
|
||||
|
||||
### Unlocking accounts
|
||||
|
||||
To unlock an account, the `personal.unlockAccount` function can be used:
|
||||
|
||||
```
|
||||
personal.unlockAccount(eth.accounts[1])
|
||||
```
|
||||
|
||||
The account passphrase is requested:
|
||||
|
||||
```terminal
|
||||
Unlock account 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b
|
||||
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:
|
||||
|
||||
```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.
|
||||
|
||||
|
||||
### 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 immediately afterwards. For example, to send 5 ether between two accounts in the keystore:
|
||||
|
||||
```shell
|
||||
var tx = {from: eth.accounts[1], to: eth.accounts[2], value: web3.toWei(5, "ether")}
|
||||
|
||||
# this requires global account unlock for eth.accounts[1]
|
||||
eth.sendTransaction(tx)
|
||||
|
||||
# this unlocks eth.accounts[1] temporarily just to send the transaction
|
||||
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.
|
||||
340
content/docs/fundamentals/account-management.md
Normal file
340
content/docs/fundamentals/account-management.md
Normal file
@ -0,0 +1,340 @@
|
||||
---
|
||||
title: Account Management
|
||||
sort_key: C
|
||||
---
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
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` subcommands are:
|
||||
|
||||
```
|
||||
COMMANDS:
|
||||
list Print summary of existing accounts
|
||||
new Create a new account
|
||||
update Update an existing account
|
||||
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:
|
||||
|
||||
```
|
||||
$ geth account list --help
|
||||
list [command options] [arguments...]
|
||||
|
||||
Print a short summary of all accounts
|
||||
|
||||
OPTIONS:
|
||||
--datadir "/home/.ethereum" Data directory for the databases and keystore
|
||||
--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
|
||||
create a new account in the default data directory:
|
||||
|
||||
|
||||
```shell
|
||||
$ geth account new
|
||||
```
|
||||
|
||||
This returns the following to the terminal:
|
||||
|
||||
```terminal
|
||||
Your new account is locked with a password. Please give a password. Do not forget this password.
|
||||
Passphrase:
|
||||
Repeat Passphrase:
|
||||
Address: {168bc315a2ee09042d83d7c5811b533620531f67}
|
||||
```
|
||||
|
||||
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!
|
||||
**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:
|
||||
|
||||
`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`:
|
||||
|
||||
```shell
|
||||
geth account list --keystore some-dir/keystore
|
||||
```
|
||||
|
||||
This command returns the following to the terminal for a keystore with two files:
|
||||
|
||||
```terminal
|
||||
Account 0: {5afdd78bdacb56ab1dad28741ea2a0e47fe41331} keystore:///tmp/mykeystore/UTC--2017-04-28T08-46-27.437847599Z--5afdd78bdacb56ab1dad28741ea2a0e47fe41331
|
||||
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.
|
||||
|
||||
|
||||
## 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!
|
||||
|
||||
```shell
|
||||
$ geth account import --datadir /some-dir ./keyfile
|
||||
```
|
||||
|
||||
The following information will be displayed in the terminal, indicating a successful import:
|
||||
|
||||
```terminal
|
||||
Please enter a passphrase now.
|
||||
Passphrase:
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
chmod 700 /path/to/password
|
||||
cat > /path/to/password
|
||||
<type password here>
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
```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:
|
||||
|
||||
```shell
|
||||
geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b
|
||||
```
|
||||
|
||||
The following will be returned to the terminal:
|
||||
|
||||
```terminal
|
||||
Unlocking account a94f5374fce5edbc8e2a8697c15331677e6ebf0b | Attempt 1/3
|
||||
Passphrase:
|
||||
0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b
|
||||
Account 'a94f5374fce5edbc8e2a8697c15331677e6ebf0b' unlocked.
|
||||
Please give a new password. Do not forget this password.
|
||||
Passphrase:
|
||||
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:
|
||||
|
||||
```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.
|
||||
|
||||
|
||||
## 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 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`:
|
||||
|
||||
```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**" %}
|
||||
|
||||
|
||||
## 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:
|
||||
|
||||
```shell
|
||||
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.
|
||||
|
||||
```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.
|
||||
|
||||
```shell
|
||||
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.:
|
||||
|
||||
```
|
||||
eth.accounts
|
||||
```
|
||||
or alternatively the same is achieved using:
|
||||
|
||||
```
|
||||
personal.listAccounts
|
||||
```
|
||||
This returns an array of account addresses to the terminal.
|
||||
|
||||
### Unlocking accounts
|
||||
|
||||
To unlock an account, the `personal.unlockAccount` function can be used:
|
||||
|
||||
```
|
||||
personal.unlockAccount(eth.accounts[1])
|
||||
```
|
||||
|
||||
The account passphrase is requested:
|
||||
|
||||
```terminal
|
||||
Unlock account 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b
|
||||
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:
|
||||
|
||||
```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.
|
||||
|
||||
|
||||
### 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
|
||||
immediately afterwards. For example, to send 5 ether between two accounts in the keystore:
|
||||
|
||||
```shell
|
||||
var tx = {from: eth.accounts[1], to: eth.accounts[2], value: web3.toWei(5, "ether")}
|
||||
|
||||
# this requires global account unlock for eth.accounts[1]
|
||||
eth.sendTransaction(tx)
|
||||
|
||||
# this unlocks eth.accounts[1] temporarily just to send the transaction
|
||||
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.
|
||||
@ -1,208 +0,0 @@
|
||||
---
|
||||
title: Mining
|
||||
sort_key: F
|
||||
---
|
||||
|
||||
|
||||
The Ethereum blockchain grows when nodes add blocks and distribute them to their peers. Nodes
|
||||
that add blocks are rewarded with ether payouts. This creates competition for the right to add
|
||||
blocks to the blockchain. This means some mechanism must exist to select a single block for each
|
||||
position in the blockchain that all nodes can agree upon. The mechanism that currently achieves
|
||||
this for Ethereum is "proof-of-work" (PoW). This involved computing a certain value that can
|
||||
only be calculated using repeated random guesses. Only if a node can demonstrate that they have
|
||||
calculated this value, and therefore expended energy, will their block be accepted by other nodes.
|
||||
This secures the network. This process of creating blocks and securing them using proof-of-work
|
||||
is known as "mining".
|
||||
|
||||
Much more information about mining, including details about the specific algorithm ("Ethash") used by
|
||||
Ethereum nodes is available on
|
||||
[ethereum.org](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining).
|
||||
|
||||
|
||||
## Mining and the Merge
|
||||
|
||||
[The Merge](https://ethereum.org/en/upgrades/merge) is an upcoming upgrade to Ethereum that
|
||||
will swap the existing PoW for a [proof-of-stake (PoS)](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos) consensus mechanism. This marks the end of mining on Ethereum. Instead, nodes can [stake ether](https://ethereum.org/en/staking/solo/#get-started-on-the-staking-launchpad) directly and earn ether rewards by running [validators](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/#validators). The merge is expected to happen in the second half of 2022. Until then, Ethereum will continue to be secured by PoW miners. It is no longer recommended to purchase new hardware to participate in Ethereum mining because the chances of returning a profit before The Merge are low.
|
||||
|
||||
|
||||
## CPU vs GPU
|
||||
|
||||
Participating in Ethereum's PoW mining requires running an algorithm called
|
||||
["Ethash"](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining-algorithms/ethash). Geth includes
|
||||
a CPU miner which runs Ethash within the Geth process. This might be useful for mining on some testnets. However, this is CPU mining is not viable on Ethereum Mainnet because CPU miners are easily out-competed by more efficient GPU miners. GPU mining is the recommended method for mining real ether on Ethereum Mainnet, but it is not part of the standard Geth installation. To mine using GPUs an additional piece of third-paty software is required. The recommended GPU mining software is [Ethminer](https://github.com/ethereum-mining/ethminer).
|
||||
|
||||
Regardless of the mining method, the blockchain must be fully synced before mining is started, otherwise the miner will build on an incorrect chain, invalidating the block rewards.
|
||||
|
||||
|
||||
## GPU Mining
|
||||
|
||||
### Installing Ethminer
|
||||
|
||||
The Ethminer software can be installed from a downloaded binary or built from source. The relevant downloads
|
||||
and installation instructions are available from the [Ethminer Github](https://github.com/ethereum-mining/ethminer/#build). Standalone executables are available for Linux, macOS and Windows.
|
||||
|
||||
### Using Ethminer with Geth
|
||||
|
||||
|
||||
An account to receive block rewards must first be defined. The address of the account is all that is required to start mining - the mining rewards will be credited to that address. This can be an existing address or one that is newly created by Geth. More detailed instructions on creating and importing accounts are available on the [Account Management](/docs/interface/managing-your-accounts) page.
|
||||
|
||||
The account address can be provided to `--mining.etherbase` when Geth is started. This instructs Geth to direct any block rewards to this address. Once started, Geth will sync the blockchain. If Geth has not connected to this network before, or if the data directory has been deleted, this can take several days. Also, enable HTTP traffic with the `--http` command.
|
||||
|
||||
```shell
|
||||
geth --http --miner.etherbase 0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10
|
||||
```
|
||||
|
||||
The progress of the blockchain syncing can be monitored by attaching a JavaScript console in another terminal. More detailed information about the console can be found on the [Javascript Console](/docs/interface/javascript-console) page. To attach and open a console:
|
||||
|
||||
```shell
|
||||
geth attach http://127.0.0.1:8545
|
||||
```
|
||||
|
||||
Then in the console, to check the sync progress:
|
||||
|
||||
```shell
|
||||
eth.syncing
|
||||
```
|
||||
|
||||
If the sync is progressing correctly the output will look similar to the following:
|
||||
|
||||
```terminal
|
||||
{
|
||||
currentBlock: 13891665,
|
||||
healedBytecodeBytes: 0,
|
||||
healedBytecodes: 0,
|
||||
healedTrienodeBytes: 0,
|
||||
healedTrienodes: 0,
|
||||
healingBytecode: 0,
|
||||
healingTrienodes: 0,
|
||||
highestBlock: 14640000,
|
||||
startingBlock: 13891665,
|
||||
syncedAccountBytes: 0,
|
||||
syncedAccounts: 0,
|
||||
syncedBytecodeBytes: 0,
|
||||
syncedBytecodes: 0,
|
||||
syncedStorage: 0,
|
||||
syncedStorageBytes: 0
|
||||
}
|
||||
```
|
||||
|
||||
Once the blockchain is sync'd, mining can begin. In order to begin mining, Ethminer must be run and connected to Geth in a new terminal. OpenCL can be used for a wide range of GPUs, CUDA can be used specifically for Nvidia GPUs:
|
||||
|
||||
```shell
|
||||
#OpenCL
|
||||
ethminer -v 9 -G -P http://127.0.0.1:8545
|
||||
```
|
||||
|
||||
```shell
|
||||
#CUDA
|
||||
ethminer -v -U -P http://127.0.0.1:8545
|
||||
```
|
||||
|
||||
Ethminer communicates with Geth on port 8545 (Geth's default RPC port) but this can be changed by providing a custom
|
||||
port to the `http.port` command. The corresponding port must also be configured in Ethminer by providing
|
||||
`-P http://127.0.0.1:<port-number>`. This is necessary when multiple instances of Geth/Ethminer will coexist on the same machine.
|
||||
|
||||
If using OpenCL and the default for `ethminer` does not work, specifying the device using the `--opencl--device X` command is a common fix. `X` is an integer `1`, `2`, `3` etc. The Ethminer `-M` (benchmark) command should display something that looks like:
|
||||
|
||||
```terminal
|
||||
Benchmarking on platform: { "platform": "NVIDIA CUDA", "device": "GeForce GTX 750 Ti", "version": "OpenCL 1.1 CUDA" }
|
||||
|
||||
Benchmarking on platform: { "platform": "Apple", "device": "Intel(R) Xeon(R) CPU E5-1620 v2 @ 3.70GHz", "version": "OpenCL 1.2 " }
|
||||
```
|
||||
|
||||
Note that the Geth command `miner.hashrate` only works for CPU mining - it always reports zero for GPU mining. To check the GPU mining hashrate, check the logs `ethminer` displays to its terminal. More verbose logs can be configured using `-v` and a value between 0-9.
|
||||
|
||||
The Ethash algorithm is [memory-hard](https://crypto.stackexchange.com/questions/84002/memory-hard-vs-memory-bound-functions) and requires a large dataset to be loaded into memory. Each GPU requires 4-5 GB of RAM. The error message `Error GPU mining. GPU memory fragmentation?` indicates that there is insufficient memory available.
|
||||
|
||||
|
||||
## CPU Mining with Geth
|
||||
|
||||
When Geth is started is is not mining by default. Unless it is specifically instructed to mine, it acts only as a node, not a miner. Geth starts as a (CPU) miner if the `--mine` flag is provided. The `--miner.threads` parameter can
|
||||
be used to set the number parallel mining threads (defaulting to the total number of processor cores).
|
||||
|
||||
```shell
|
||||
geth --mine --miner.threads=4
|
||||
```
|
||||
|
||||
CPU mining can also be started and stopped at runtime using the [console](/docs/interface/javascript-console). The command `miner.start` takes an optional parameter for the number of miner threads.
|
||||
|
||||
```js
|
||||
miner.start(8)
|
||||
true
|
||||
miner.stop()
|
||||
true
|
||||
```
|
||||
|
||||
Note that mining for real ether only makes sense if you are in sync with the network (since you mine on top of the consensus block). Therefore the Ethereum blockchain downloader/synchroniser will delay mining until syncing is complete, and after that mining automatically starts unless you cancel your intention with `miner.stop()`.
|
||||
|
||||
Like with GPU mining, an etherbase account must be set. This defaults to the primary account in the keystore but can be set to an alternative address using the `--miner.etherbase` command:
|
||||
|
||||
```shell
|
||||
geth --miner.etherbase '0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10' --mine
|
||||
```
|
||||
If there is no account available the miner will not start. The Javascript console can also be used to reset the etherbase account at runtime:
|
||||
|
||||
```shell
|
||||
miner.setEtherbase(eth.accounts[2])
|
||||
```
|
||||
|
||||
Note that your etherbase does not need to be an address of a local account, it just has to be set to an existing one.
|
||||
|
||||
There is an option to add extra data (32 bytes only) to the mined blocks. By convention this is interpreted as a unicode string, so it can be used to add a short vanity tag using `miner.setExtra` in the Javascript console.
|
||||
|
||||
```shell
|
||||
miner.setExtra("ΞTHΞЯSPHΞЯΞ")
|
||||
```
|
||||
|
||||
The console can also be used to check the current hashrate in units H/s (Hash operations per second):
|
||||
|
||||
```shell
|
||||
eth.hashrate
|
||||
712000
|
||||
```
|
||||
|
||||
After some blocks have been mined, the etherbase account balance with be >0. Assuming the etherbase is a local account:
|
||||
|
||||
```shell
|
||||
eth.getBalance(eth.coinbase).toNumber();
|
||||
'34698870000000'
|
||||
```
|
||||
|
||||
It is also possible to check which blocks were mined by a particular miner (address) using the following code snippet in the Javascript console:
|
||||
|
||||
```js
|
||||
function minedBlocks(lastn, addr) {
|
||||
addrs = [];
|
||||
if (!addr) {
|
||||
addr = eth.coinbase
|
||||
}
|
||||
limit = eth.blockNumber - lastn
|
||||
for (i = eth.blockNumber; i >= limit; i--) {
|
||||
if (eth.getBlock(i).miner == addr) {
|
||||
addrs.push(i)
|
||||
}
|
||||
}
|
||||
return addrs
|
||||
}
|
||||
|
||||
// scans the last 1000 blocks and returns the blocknumbers of blocks mined by your coinbase
|
||||
// (more precisely blocks the mining reward for which is sent to your coinbase).
|
||||
minedBlocks(1000, eth.coinbase)
|
||||
[352708, 352655, 352559]
|
||||
|
||||
```
|
||||
|
||||
The etherbase balance will fluctuate because quite often a mined block may be re-org'd out
|
||||
of the canonical chain. This means that when the local Geth node includes the mined block
|
||||
in its own local blockchain the account balance appears higher because the block rewards are
|
||||
applied. When the node switches to another version of the chain due to information received
|
||||
from peers, that block may not be included and the block rewards are not applied.
|
||||
|
||||
The logs show locally mined blocks confirmed after 5 blocks.
|
||||
|
||||
|
||||
## Summary
|
||||
|
||||
The page describes how to start Geth as a mining node. Mining can be done on CPUs - in which case Geth's built-in
|
||||
miner can be used - or on GPUs which requires third party software. GPUs are required to mine real ether on Ethereum
|
||||
Mainnet. It is important to note that Ethereum will swap its consensus mechanism from PoW to PoS in the second half of 2022. This swap, known as "The Merge" will end mining on Ethereum.
|
||||
@ -1,452 +0,0 @@
|
||||
---
|
||||
title: Getting Started with Geth
|
||||
permalink: docs/getting-started
|
||||
sort_key: A
|
||||
---
|
||||
|
||||
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"](install-and-build/installing-geth) pages.
|
||||
The tutorial on this page assumes Geth and the associated developer tools have been installed successfully.
|
||||
|
||||
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.
|
||||
It is considered best-practice to use [Clef](/docs/clef/Introduction) for account management - this
|
||||
is explained in the [Geth with Clef](/docs/getting-started/geth_with_clef) tutorial. In this
|
||||
introductory tutorial, Geth's built-in account management tools are used instead.
|
||||
|
||||
{:toc}
|
||||
- this will be removed by the toc
|
||||
|
||||
## Prerequisites
|
||||
|
||||
In order to get the most value from the tutorials on this page, the following skills are
|
||||
necessary:
|
||||
|
||||
- Experience using the command line
|
||||
- Basic knowledge about Ethereum and testnets
|
||||
- Basic knowledge about HTTP and JavaScript
|
||||
|
||||
Users that need to revisit these fundamentals can find helpful resources relating to the command
|
||||
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).
|
||||
|
||||
{% 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
|
||||
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
|
||||
|
||||
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. Nodes compete to generate new blocks of transactions to send to its peers
|
||||
because they are rewarded for doing so in Ethereum's native token, ether (ETH). 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
|
||||
balance of each account on Ethereum. 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, 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/).
|
||||
|
||||
|
||||
## Step 1: Generating accounts
|
||||
|
||||
To generate a new account in Geth:
|
||||
|
||||
```sh
|
||||
geth account new
|
||||
```
|
||||
|
||||
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 diredctory, then run:
|
||||
|
||||
```sh
|
||||
geth account new --keystore geth-tutorial/keystore
|
||||
```
|
||||
The following will be returned to the console, confirming the new account has been created and
|
||||
added to the keystore.
|
||||
|
||||
```terminal
|
||||
Your new account is locked with a password. Please give a password. Do not forget this password.
|
||||
Password:
|
||||
Repeat password:
|
||||
|
||||
Your new key was generated
|
||||
|
||||
Public address of the key: 0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC
|
||||
Path of the secret key file: /home/go-ethereum/geth-tutorial/keystore/UTC--2022-07-25T08-27-59.433905560Z--ca57F3b40B42FCce3c37B8D18aDBca5260ca72EC
|
||||
|
||||
- You can share your public address with anyone. Others need it to interact with you.
|
||||
- You must NEVER share the secret key with anyone! The key controls access to your funds!
|
||||
- You must BACKUP your key file! Without the key, it's impossible to access account funds!
|
||||
- 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
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Step 2: Start Geth
|
||||
|
||||
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
|
||||
(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
|
||||
geth --datadir geth-tutorial --goerli --syncmode snap
|
||||
```
|
||||
Running the above command starts Geth. The terminal should rapidly fill with status updates that look like the following:
|
||||
|
||||
```terminal
|
||||
INFO [02-10|13:59:06.649] Starting Geth on goerli 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=50 LES=0 total=50
|
||||
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/chaindata cache=64.00MiB handles=5120
|
||||
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
|
||||
WARN [02-10|13:59:06.998] Light client mode is an experimental feature
|
||||
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 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/`.
|
||||
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
|
||||
|
||||
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: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.
|
||||
|
||||
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 ... ..`.
|
||||
|
||||
{% 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." %}
|
||||
|
||||
## Step 3: Get Testnet Ether
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Step 4: Interact with Geth
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
- console is run on the same host as the Geth node.
|
||||
|
||||
- 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.
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
geth attach geth-tutorial/geth.ipc
|
||||
```
|
||||
|
||||
The following welcome message will be displayed in the Javascript console:
|
||||
|
||||
```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))
|
||||
datadir: /home/go-ethereum/geth-tutorial
|
||||
modules: admin:1.0 clique:1.0 debug:1.0 eth:1.0 miner:1.0 net:1.0 personal:1.0 rpc:1.0 txpool:1.0 web3:1.0
|
||||
|
||||
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.
|
||||
|
||||
|
||||
### List of accounts
|
||||
|
||||
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.
|
||||
|
||||
```javascript
|
||||
eth.accounts
|
||||
```
|
||||
|
||||
```terminal
|
||||
["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", "0xce8dba5e4157c2b284d8853afeeea259344c1653"]
|
||||
```
|
||||
|
||||
|
||||
### Checking account balance.
|
||||
|
||||
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:
|
||||
|
||||
```javascript
|
||||
web3.fromWei(eth.getBalance("0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC"), "ether")
|
||||
```
|
||||
|
||||
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):
|
||||
|
||||
```terminal
|
||||
1
|
||||
```
|
||||
|
||||
Repeating the command for the other new account that was not funded from the faucet should yield:
|
||||
|
||||
```terminal
|
||||
0
|
||||
```
|
||||
|
||||
### Send ether to another account
|
||||
|
||||
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.
|
||||
|
||||
```javascript
|
||||
eth.sendTransaction({
|
||||
from: "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec",
|
||||
to: "0xce8dba5e4157c2b284d8853afeeea259344c1653",
|
||||
value: web3.toWei(0.1, "ether")
|
||||
})
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
personal.sendTransaction({
|
||||
from: "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec",
|
||||
to: "0xce8dba5e4157c2b284d8853afeeea259344c1653",
|
||||
value: web3.toWei(0.1, "ether")
|
||||
}, "password")
|
||||
```
|
||||
|
||||
In the Javascript console, the transaction hash is displayed. This will be used in the next section
|
||||
to retrieve the transaction details.
|
||||
|
||||
```terminal
|
||||
"0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb"
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### Checking the transaction hash
|
||||
|
||||
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:
|
||||
|
||||
```javascript
|
||||
eth.getTransaction("0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb")
|
||||
```
|
||||
|
||||
This returns the following response (although the actual values for each field will vary because they
|
||||
are specific to each transaction):
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
## Using Curl
|
||||
|
||||
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.
|
||||
|
||||
### Checking account balance
|
||||
|
||||
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).
|
||||
|
||||
```shell
|
||||
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}'
|
||||
```
|
||||
|
||||
A successful call will return a response like the one below:
|
||||
|
||||
```terminal
|
||||
{"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
|
||||
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
|
||||
0xc7d54951f87f7c0 / 1e18
|
||||
```
|
||||
This returns the balance in ether:
|
||||
|
||||
```terminal
|
||||
0.8999684999998321
|
||||
```
|
||||
|
||||
### Checking the account list
|
||||
|
||||
The curl command below returns the list of all accounts.
|
||||
|
||||
```shell
|
||||
curl -X POST http://127.0.0.1:8545 \
|
||||
-H "Content-Type: application/json" \
|
||||
--data '{"jsonrpc":"2.0", "method":"eth_accounts","params":[], "id":1}'
|
||||
```
|
||||
|
||||
The following information is returned to the terminal:
|
||||
|
||||
```terminal
|
||||
{"jsonrpc":"2.0","id":1,"result":["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec"]}
|
||||
```
|
||||
|
||||
### Sending Transactions
|
||||
|
||||
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.
|
||||
|
||||
## Summary
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
|
||||
[cli]: https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line
|
||||
Loading…
Reference in New Issue
Block a user