diff --git a/docs/_getting-started/index.md b/docs/_getting-started/index.md index 9def1587e..3600e2041 100644 --- a/docs/_getting-started/index.md +++ b/docs/_getting-started/index.md @@ -4,95 +4,183 @@ permalink: docs/getting-started sort_key: A --- -To use Geth, you need to install it first. You can install the geth software in a variety -of ways. These include installing it via your favorite package manager; downloading a -standalone pre-built binary; running as a docker container; or building it yourself. +To use Geth, you need to install it first. You can install Geth in a variety +of ways that you can find in the "[Install and Build](install-and-build/installing-geth)" section. +These include installing it via your favorite package manager, downloading a +standalone pre-built binary, running it as a docker container or building it yourself. -For this tutorial, we'll assume you are comfortable with downloading a pre-built binary. -Head over to the [install and build](./install-and-build/installing-geth) section and -follow the instructions for your operating system if you wish to use a different -installation method. +For this guide, we assume you have Geth installed and are ready to find out how to use it. +The guide shows you how to create accounts, sync to a network, and then send transactions +between accounts. -### Downloading Geth +This guide uses [Clef](clef/tutorial), which is our preferred tool for signing transactions with Geth, +and will replace Geth's account management. -We distribute all our stable releases and development builds as standalone binaries. These -are useful for scenarios where you'd like to: a) install a specific version of our code -(e.g., for reproducible environments); b) install on machines without internet access -(e.g., air gapped computers); or c) do not like automatic updates and would rather -manually install software. +## Initialize Clef -To download Geth, go to the [Downloads page](https://geth.ethereum.org/downloads) and -select the latest stable release matching your platform. +First, initialize Clef with a random master seed, which is also encrypted with the password you define. +The password must be at least 10 characters. -We create the following archives: +```shell +clef init +``` -- 32bit, 64bit, ARMv5, ARMv6, ARMv7 and ARM64 archives (`.tar.gz`) on Linux -- 64bit archives (`.tar.gz`) on macOS -- 32bit and 64bit archives (`.zip`) and installers (`.exe`) on Windows +![Clef init command](../../static/images/clef-init.gif) -For all binaries we provide two options, one containing only Geth, and another containing -Geth along with all the developer tools from our repository (`abigen`, `bootnode`, -`disasm`, `evm`, `rlpdump`). Read our -[`README`](https://github.com/ethereum/go-ethereum#executables) for more information about -these executables. +## Create accounts -### Creating an account +Create two accounts with the `clef newaccount` command, +set a password for each of them, and note the public address for each. -Before starting Geth you first need to create an account that represents a key pair. Use -the following command to create a new account and set a password for that account: +![Create new account command](../../static/images/clef-account-new.gif) -```shell -geth account new -``` +Clef outputs a debug message about `Failed to reload keystore contents`, we fix that in a later step. + +## Start Geth + +### Networks -_[Read this guide](./interface/managing-your-accounts) for more details on importing -existing Ethereum accounts and other uses of the `account` command._ +You can connect a Geth node to several different networks using the network name as an argument. +These include the main Ethereum network, [a private network](getting-started/private-net) you create, +and three test networks that use different consensus algorithms: + +- **Ropsten**: Proof-of-work test network +- **Rinkeby**: Proof-of-authority test network +- **Görli**: Proof-of-authority test network + +For this guide, we use the Görli network. ### Sync modes -Running Geth starts an Ethereum node that can join any existing network, or create a new -one. You can start Geth in one of three different sync modes using the `--syncmode "{mode}"` +You can start Geth in one of three different sync modes using the `--syncmode ""` argument that determines what sort of node it is in the network. These are: -- **Full**: Downloads all blocks (including headers, transactions and receipts) and +- **Full**: Downloads all blocks (including headers, transactions, and receipts) and generates the state of the blockchain incrementally by executing every block. - **Fast** (Default): Downloads all blocks (including headers, transactions and receipts), verifies all headers, and downloads the state and verifies it against the headers. - **Light**: Downloads all block headers, block data, and verifies some randomly. -For example: +For this tutorial, we use a `light` sync: + +## Start Clef + +Start Clef, setting the keystore and chain id (goerli is 5) for the network we want to connect to: ```shell -geth --syncmode "light" +clef --keystore /keystore --chainid 5 ``` -### Javascript Console +To begin with, you see errors about a missing keystore, and we fix that soon. + +## Start Geth -Once you have an account and Geth is running, you can interact with it by opening another -terminal and using the following command to open a JavaScript console: +The command below also enables the [Geth RPC interface](clef/tutorial) +(which we cover below), and sets Clef as the transaction signer. ```shell -geth attach +geth --goerli --syncmode "light" --rpc --signer=/clef.ipc ``` -If you get the error 'unable to attach to remote geth', try connecting via HTTP as shown below: +## Get ETH + +Unless you have Ether in another account on the Görli network, you can use a +[faucet](https://goerli-faucet.slock.it/) to send ETH to one of your new account addresses to use for this guide. + +## Connect to Geth with IPC or RPC + +You can interact with Geth in two ways: Directly with the node using the JavaScript +console over IPC, or connecting to the node remotely over HTTP using RPC. + +IPC allows you to do more, especially when it comes to creating and interacting +with accounts, but you need direct access to the node. + +RPC allows remote applications to access your node but has limitations and security +considerations, and by default only allows access to methods in the `eth` and `shh` +namespaces. Find out how to override this setting [in the RPC docs](rpc/server#http-server). + +## Using IPC + +### Connect to console + +Connect to the IPC console on a node from another terminal window: ```shell -geth attach http://127.0.0.1:8545 +geth attach ``` -In the console you can issue any of the Geth commands, for example, to list all the -accounts on the node, use: +### Check account balance -```js -> eth.accounts +```javascript +web3.fromWei(eth.getBalance(""),"ether") ``` -You can also enter the console directly when you start the node with the `console` command: +Getting the balance of an account does not require a signed transaction, +so Clef does not ask for approval, and Geth returns the value. + +### Send ETH to account + +Send 0.01 ETH from the account that you added ETH to with the Görli faucet, +to the second account you created: + +```javascript +eth.sendTransaction({from:"",to:"", value: web3.toWei(0.01,"ether")}) +``` + +This action does require signing the transaction, so Clef prompts you to approve it, and +if you do, asks you for the password you are sending the ETH from. If the password is +correct, Geth proceeds with the transaction. + +To check, get the account balance of the second account: + +```javascript +web3.fromWei(eth.getBalance(""),"ether") +``` + +## Using RPC + +### Connect to RPC + +You can use standard HTTP requests to connect to a Geth node using the RPC APIs, for example: + +```shell +curl -X POST http://:8545 --data \ + -H "Content-Type: application/json" \ + '{"jsonrpc":"2.0", "method":"", "params":[], "id":1}' +``` + +### Check account balance + +```shell +curl -X POST http://:8545 --data \ + -H "Content-Type: application/json" \ + '{"jsonrpc":"2.0", "method":"eth_getBalance", "params":["","latest"], "id":1}' +``` + +Getting the balance of an account does not require a signed transaction, +so Clef does not ask for approval, and Geth returns the value. + +### Send ETH to accounts + +Send 0.01 ETH from the account that you added ETH to with the Görli faucet, to the second account you created: + +```shell +curl -X POST http://:8545 --data \ + -H "Content-Type: application/json" \ + '{"jsonrpc":"2.0", "method":"eth_sendTransaction", "params":[{"from": "","to": "","value": "0x9184e72a"}], "id":1}' +``` + +This action does require signing, so Clef prompts you to approve it, and if you do, +asks you for the password you are sending the ETH from. If the password is correct, +Geth proceeds with the transaction. + +To check, get the account balance of the second account: ```shell -geth console --syncmode "light" +curl -X POST http://:8545 --data \ + -H "Content-Type: application/json" \ + '{"jsonrpc":"2.0", "method":"eth_getBalance", "params":["","latest"], "id":1}' ``` diff --git a/static/images/clef-account-new.gif b/static/images/clef-account-new.gif new file mode 100644 index 000000000..2bbe8053a Binary files /dev/null and b/static/images/clef-account-new.gif differ diff --git a/static/images/clef-init.gif b/static/images/clef-init.gif new file mode 100644 index 000000000..b9771f17e Binary files /dev/null and b/static/images/clef-init.gif differ