From e32c01579fa8e0a6e50bbb1785e6990b4d573f4a Mon Sep 17 00:00:00 2001 From: Joe Date: Fri, 29 Jul 2022 09:48:04 +0100 Subject: [PATCH] content updates --- .../geth-developer/built-in-tracers.md | 112 ++++++++++++++++++ .../docs/getting_started/consensus-clients.md | 17 +-- .../getting-started-with-clef.md | 63 +++++----- .../docs/getting_started/getting_started.md | 47 +++++--- .../interacting_with_geth/RPC/ns-debug.md | 3 +- .../interacting_with_geth/RPC/ns-personal.md | 3 +- content/homepage.md | 3 + 7 files changed, 194 insertions(+), 54 deletions(-) create mode 100644 content/docs/developers/geth-developer/built-in-tracers.md diff --git a/content/docs/developers/geth-developer/built-in-tracers.md b/content/docs/developers/geth-developer/built-in-tracers.md new file mode 100644 index 0000000000..08ae63b3a9 --- /dev/null +++ b/content/docs/developers/geth-developer/built-in-tracers.md @@ -0,0 +1,112 @@ +--- +title: Built-in tracers +sort_key: C +--- + +Geth comes bundled with a choice of tracers ready for usage through the [tracing API](/docs/rpc/ns-debug). Some of them are implemented natively in Go, and others in JS. In this page a summary of each of these will be outlined. They have to be specified by name when sending a request. The only exception is the opcode logger (otherwise known as struct logger) which is the default tracer for all the methods and cannot be specified by name. + +* TOC +{:toc} + +## Struct logger + +Struct logger or opcode logger is a native Go tracer which executes a transaction and emits the opcode and execution context at every step. This is the tracer that will be used when no name is passed to the API, e.g. `debug.traceTransaction()`. The following information is emitted at each step: + +| field | type | description | +|------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------| +| pc | uint64 | program counter | +| op | byte | opcode to be executed | +| gas | uint64 | remaining gas | +| gasCost | uint64 | cost for executing op | +| memory | []byte | EVM memory. Enabled via `enableMemory` | +| memSize | int | Size of memory | +| stack | []uint256 | EVM stack. Disabled via `disableStack` | +| returnData | []byte | Last call's return data. Enabled via `enableReturnData` | +| storage | map[hash]hash | Storage slots of current contract read from and written to. Only emitted for `SLOAD` and `SSTORE`. Disabled via `disableStorage` | +| depth | int | Current call depth | +| refund | uint64 | Refund counter | +| error | string | Error message if any | + +Note that the fields `memory`, `stack`, `returnData`, and `storage` have dynamic size and depending on the exact transaction they could grow large in size. This is specially true for `memory` which could blow up the trace size. It is recommended to keep them disabled unless they are explicitly required for a given use-case. + +## Native tracers + +The following tracers are implement in Go and as such have offer good performance. They are selected by their name when invoking a tracing API method, e.g. `debug.traceTransaction(, { tracer: 'callTracer' })`. + +### 4byteTracer + +Solidity contract functions are [addressed](https://docs.soliditylang.org/en/develop/abi-spec.html#function-selector) by the first four four byte of the Keccak-256 hash of their signature. Therefore when calling the function of a contract, the caller must send this function selector as well as the ABI-encoded arguments as call data. + +The `4byteTracer` collects the function selectors of every function executed in the lifetime of a transaction, along with the size of the supplied call data. The result is a `map[string]int` where the keys are `SELECTOR-CALLDATASIZE` and the values are number of occurances of this key. E.g.: + +```terminal +> debug.traceTransaction( "0x214e597e35da083692f5386141e69f47e973b2c56e7a8073b1ea08fd7571e9de", {tracer: "4byteTracer"}) +{ + "0x27dc297e-128": 1, + "0x38cc4831-0": 2, + "0x524f3889-96": 1, + "0xadf59f99-288": 1, + "0xc281d19e-0": 1 +} +``` + +### callTracer + +The `callTracer` tracks all the call frames executed during a transaction, including depth 0. The result will be a nested list of call frames, resembling how EVM works. They form a tree with the top-level call at root and sub-calls as children of the higher levels. Each call frame has the following fields: + +| field | type | description | +|---------|-------------|-------------------------------------------| +| type | string | CALL or CREATE | +| from | string | address | +| to | string | address | +| value | string | hex-encoded amount of value transfer | +| gas | string | hex-encoded gas provided for call | +| gasUsed | string | hex-encoded gas used during call | +| input | string | call data | +| output | string | return data | +| error | string | error, if any | +| calls | []callframe | list of sub-calls | + +Things to note about the call tracer: + +- Calls to precompiles are also included in the result +- In case a frame reverts, the field `output` will contain the raw return data, unlike [revertReasonTracer](#revertreasontracer) which parses the data and returns the revert message + +### noopTracer + +This tracer is noop. It returns an empty object and is only meant for testing the setup. + +### prestateTracer + +Executing a transaction requires the prior state, including account of sender and recipient, contracts that are called during execution, etc. The `prestateTracer` replays the tx and tracks every part of state that is touched. This is similar to the concept of a [stateless witness](https://ethresear.ch/t/the-stateless-client-concept/172), the difference being this tracer doesn't return any cryptographic proof, rather only the trie leaves. The result is an object. The keys are addresses of accounts. The value is an object with the following fields: + +| field | type | description | +|---------|-------------------|-------------------------------| +| balance | string | balance in Wei | +| nonce | uint64 | nonce | +| code | string | hex-encoded bytecode | +| storage | map[string]string | storage slots of the contract | + +### revertReasonTracer + +The `revertReasonTracer` is useful for analyzing failed transactions. The return value is: + +- In case the transaction reverted: reason of the revert as returned by the Solidity contract +- Error message for any other failure + +Example: + +```terminal +> debug.traceTransaction('0x97695ffb034be7e1faeb372a564bb951ba4ebf4fee4caff2f9d1702497bb2b8b', { tracer: 'revertReasonTracer' }) +"execution reverted: tokensMintedPerAddress exceed MAX_TOKENS_MINTED_PER_ADDRESS" +``` + +## JS tracers + +The following are a list of tracers written in JS that come as part of Geth: + +- `bigramTracer`: Counts the opcode bigrams, i.e. how many times 2 opcodes were executed one after the other +- `evmdisTracer`: Returns sufficient information from a trace to perform [evmdis](https://github.com/Arachnid/evmdis)-style disassembly +- `opcountTracer` Counts the total number of opcodes executed +- `trigramTracer`: Counts the opcode trigrams +- `unigramTracer`: Counts the occurances of each opcode diff --git a/content/docs/getting_started/consensus-clients.md b/content/docs/getting_started/consensus-clients.md index 17cb109d0f..f57bc4e26f 100644 --- a/content/docs/getting_started/consensus-clients.md +++ b/content/docs/getting_started/consensus-clients.md @@ -8,8 +8,8 @@ run a full Ethereum node. However, ever since Ethereum swapped from [proof-of-wo [proof-of-stake][pos-link] (PoS) based consensus, Geth has needed to be coupled to another piece of software called a ["consensus client"][con-client-link]. -There are four consensus clients available, all of which connect to Geth in the same way. This page will -outline how Geth can be set up with a consensus client. +There are five consensus clients available, all of which connect to Geth in the same way. +This page will outline how Geth can be set up with a consensus client to form a complete Ethereum node. ## Configuring Geth @@ -45,6 +45,8 @@ There are currently four consensus clients that can be run alongside Geth. These [Prysm](https://docs.prylabs.network/docs/getting-started/): written in Go [Teku](https://pegasys.tech/teku): written in Java + +[Lodestar](https://lodestar.chainsafe.io/): written in Typescript It is recommended to consider [client diversity][client-div-link] when choosing a consensus client. Instructions for installing each client are provided in the documentation linked in the list above. @@ -59,8 +61,8 @@ Each consensus client has a command similar to `--jwt-secret` that takes the fil be consistent with the `--authrpc.jwtsecret` path provided to Geth. The consensus clients all expose a [Beacon API][beacon-api-link] that can be used to check the status -of the Beacon client or download blocks and consensus data by sending requests using tools such as [Curl](https://curl.se). -More information on this can be found in the documentation for each consensus client. +of the Beacon client or download blocks and consensus data by sending requests using tools such as +[Curl](https://curl.se). More information on this can be found in the documentation for each consensus client. ## Validators @@ -84,10 +86,9 @@ geth attach datadir/geth.ipc ## Summary -As The Merge approaches it is important for Geth users to prepare by installing and running a consensus client. Otherwise, Geth will stop -following the head of the chain immediately after The Merge. There are five consensus clients to choose from. This page provided an overview -of how to choose a consensus client and configure Geth to connect to it. This pre-emptive action will protect against disruption to users as a -result of The Merge. +Now that Ethereum has implemented proof-of-stake, Geth users are required to install and run a consensus client. +Otherwise, Geth will not be able to track the head of the chain. There are five consensus clients to choose from. +This page provided an overview of how to choose a consensus client and configure Geth to connect to it. [pow-link]:https://ethereum.org/en/developers/docs/consensus-mechanisms/pow diff --git a/content/docs/getting_started/getting-started-with-clef.md b/content/docs/getting_started/getting-started-with-clef.md index 684996f7ed..37078b7a2e 100644 --- a/content/docs/getting_started/getting-started-with-clef.md +++ b/content/docs/getting_started/getting-started-with-clef.md @@ -6,10 +6,13 @@ sort_key: B 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. +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. Geth +also needs to be connected to a consensus client in order to function as an Ethereum node. +The tutorial on this page assumes Geth and a consensus client have been installed successfully and +that a firewall has been configured to block external traffic to the JSON-RPC port `8545` see +[Security](/content/docs/fundamentals/security.md). 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 @@ -19,40 +22,46 @@ the Geth team and is intended to eventually replace the account management tool ## Prerequisites -In order to get the most value from the tutorials on this page, the following skills are necessary: +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 +- Basic knowledge of node architecture and consensus clients -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). +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). Information on node architecture can be found +[here](/content/docs/fundamentals/node-architecture.md) and our guide for configuring Geth to connect to a +consensus client is [here](/content/docs/getting_started/consensus-clients.md). -{% 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." %} +{% 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. +managed by a central server. Every 12 seconds one node is randomly selected to generate a new block +containing a list of transactions that nodes receiving the block should execute. This "block proposer" node +sends the new block to its peers. 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 and the data stored by each smart contract. 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/). diff --git a/content/docs/getting_started/getting_started.md b/content/docs/getting_started/getting_started.md index 448e8eb5aa..7f9c8f6647 100644 --- a/content/docs/getting_started/getting_started.md +++ b/content/docs/getting_started/getting_started.md @@ -8,14 +8,22 @@ This page explains how to set up Geth and execute some basic tasks using the com 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. +Geth can be found on the ["Install and Build"](install-and-build/installing-geth) pages. Geth +also needs to be connected to a consensus client in order to function as an Ethereum node. +The tutorial on this page assumes Geth and a consensus client have been installed successfully and +that a firewall has been configured to block external traffic to the JSON-RPC port `8545` see +[Security](/content/docs/fundamentals/security.md). 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. +This page uses Geth's built in account management tool. This is the simplest method for creating and accessing +accounts in Geth, is sufficiently secure for many purposes and provides a good entry point for undersatanding +some of the basic Geth workflows. However, Geth also comes bundled with an external signer and account management +tool called [Clef](/tools/Clef/introduction). It is best practise to use Clef instead of Geth's built-in account +management tools because Clef is decoupled from Geth and can be run in a separate, secure environment. +This page should be used as an initial entry point into basic Geth and readers should plan to advance from this +page to [Getting started with Geth and Clef](/content/docs/getting_started/getting-started-with-clef.md). +Eventually, Clef is intended to replace Geth's built-in account management tools. {:toc} - this will be removed by the toc @@ -28,11 +36,14 @@ necessary: - Experience using the command line - Basic knowledge about Ethereum and testnets - Basic knowledge about HTTP and JavaScript +- Basic knowledge of node architecture and consensus clients 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). +Javascript [here](https://www.javascript.com/learn). Information on node architecture can be found +[here](/content/docs/fundamentals/node-architecture.md) and our guide for configuring Geth to connect to a +consensus client is [here](/content/docs/getting_started/consensus-clients.md). {% 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 @@ -46,17 +57,19 @@ or provide their path (e.g. `./build/bin/geth`). These instructions can be ignor 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. +managed by a central server. Every 12 seconds one node is randomly selected to generate a new block +containing a list of transactions that nodes receiving the block should execute. This "block proposer" node +sends the new block to its peers. 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 and the data stored by each smart contract. 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/). diff --git a/content/docs/interacting_with_geth/RPC/ns-debug.md b/content/docs/interacting_with_geth/RPC/ns-debug.md index 57640283d0..2fed88c96b 100644 --- a/content/docs/interacting_with_geth/RPC/ns-debug.md +++ b/content/docs/interacting_with_geth/RPC/ns-debug.md @@ -753,7 +753,7 @@ Specifying the `tracer` option in the second argument enables JavaScript-based t `log` has the following fields: - `op`: Object, an OpCode object representing the current opcode - - `stack`: array[big.Int], the EVM execution stack + - `stack`: Object, a structure representing the EVM execution stack - `memory`: Object, a structure representing the contract's memory space - `contract`: Object, an object representing the account executing the current operation @@ -945,3 +945,4 @@ Writes a goroutine blocking profile to the given file. |:--------|-----------------------------------------------------------| | Console | `debug.writeMutexProfile(file)` | | RPC | `{"method": "debug_writeMutexProfile", "params": [file]}` | + diff --git a/content/docs/interacting_with_geth/RPC/ns-personal.md b/content/docs/interacting_with_geth/RPC/ns-personal.md index c3086ccb50..436471b773 100644 --- a/content/docs/interacting_with_geth/RPC/ns-personal.md +++ b/content/docs/interacting_with_geth/RPC/ns-personal.md @@ -207,7 +207,7 @@ undefined ### personal_sign The sign method calculates an Ethereum specific signature with: -`sign(keccak256("\x19Ethereum Signed Message:\n" + len(message) + message)))`. +`sign(keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))`. By adding a prefix to the message makes the calculated signature recognisable as an Ethereum specific signature. This prevents misuse where a malicious DApp can sign arbitrary data (e.g. transaction) and use the signature to impersonate the victim. @@ -253,3 +253,4 @@ SignTransaction will create a transaction from the given arguments and tries to > personal.ecRecover("0xdeadbeaf", "0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b") "0x9b2055d370f73ec7d8a03e965129118dc8f5bf83" ``` + diff --git a/content/homepage.md b/content/homepage.md index eb6ec09174..eb2254aa34 100644 --- a/content/homepage.md +++ b/content/homepage.md @@ -16,6 +16,8 @@ of smart contracts and contains an embedded computer known as the *Ethereum Virt Running Geth alongside a consensus client turns a computer into an Ethereum node. + + ## What is Ethereum? Ethereum is a technology for building apps and organizations, holding assets, transacting and @@ -37,3 +39,4 @@ using your Geth instance. +