Merge remote-tracking branch 'geth-website/master' into origin/new-website

.env.local.example

@@ -0,0 +1,8 @@
+# Algolia
+NEXT_PUBLIC_ALGOLIA_APP_ID=
+NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY=
+NEXT_PUBLIC_ALGOLIA_BASE_SEARCH_INDEX_NAME=
+
+# GitHub API
+# check fine-grained tokens https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#about-personal-access-tokens
+GITHUB_TOKEN_READ_ONLY=

.eslintignore

@@ -0,0 +1,3 @@
+.next
+dist
+node_modules/

.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["next/core-web-vitals", "prettier"]
+}

.gitignore

@@ -0,0 +1,40 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# Sitemaps
+sitemap*.xml

.prettierignore

@@ -0,0 +1,6 @@
+.next
+node_modules
+yarn.lock
+package-lock.json
+public
+build

.prettierrc

@@ -0,0 +1,10 @@
+{
+  "printWidth": 100,
+  "trailingComma": "none",
+  "semi": true,
+  "arrowParens": "avoid",
+  "singleQuote": true,
+  "jsxSingleQuote": true,
+  "tabWidth": 2,
+  "useTabs": false
+}

README.md

@@ -0,0 +1,59 @@
+## Geth website
+
+This repo will act as a shared workspace for the geth website team in developing new content, designs etc
+
+Resources:
+
+- the project management notes: https://www.notion.so/efdn/Build-new-Geth-website-bf35a46cfe5848db83ac3acb5191eb1c
+- some draft figma files for design sketching: https://www.figma.com/file/ekzIgwyeVKLtFSAcnA0Q0D/geth-website?node-id=6%3A31
+- content planning notes: https://www.notion.so/efdn/Content-Strategy-3252234338814a749374fa7f11049083
+- meeting notes: https://www.notion.so/efdn/Call-notes-46aa0202810a402ebfda07b046761cbd
+
+Notes:
+
+**Dev note**: Remember that the fiules in `vulnerabilities` must be served at the same URLs as they are currently to avoid breaking some Geth functions related to security auditing.
+
+---
+
+This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file.
+
+[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.ts`.
+
+The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+
+## Adding a new documentation page
+
+Documentation pages are located in the `/docs` folder in the root directory of the project.
+
+When you want to add a new page, add the new file in the appropriate folder in the `/docs` page. `index.md` files will be the default page for a directory, and `{pagename}.md` will define subpages for a directory.
+
+After adding this page, you will need to add it `/src/data/documentation-links.yaml` which adds documentation structure which you will see on the left sidebar in the documentation pages.

docs/developers/dapp-developer/dev-mode.md

@@ -0,0 +1,298 @@
+---
+title: Developer mode
+description: Instructions for setting up Geth in developer mode
+---
+
+It is often convenient for developers to work in an environment where changes to client or application software can be deployed and tested rapidly and without putting real-world users or assets at risk. For this purpose, Geth has a `--dev` flag that spins up Geth in "developer mode". This creates a single-node Ethereum test network with no connections to any external peers. It exists solely on the local machine. Starting Geth in developer mode does the following:
+
+- Initializes the data directory with a testing genesis block
+- Sets max peers to 0 (meaning Geth does not search for peers)
+- Turns off discovery by other nodes (meaning the node is invisible to other nodes)
+- Sets the gas price to 0 (no cost to send transactions)
+- Uses the Clique proof-of-authority consensus engine which allows blocks to be mined as-needed without excessive CPU and memory consumption
+- Uses on-demand block generation, producing blocks when transactions are waiting to be mined
+
+This configuration enables developers to experiment with Geth's source code or develop new applications without having to sync to a pre-existing public network. Blocks are only mined when there are pending transactions. Developers can break things on this network without affecting other users. This page will demonstrate how to spin up a local Geth testnet and a simple smart contract will be deployed to it using the Remix online integrated development environment (IDE).
+
+## Prerequisites {#prerequisites}
+
+It is assumed that the user has a working Geth installation (see [installation guide](/docs/getting-started/installing-geth)).
+It would also be helpful to have basic knowledge of Geth and the Geth console. See [Getting Started](/docs/getting-started).
+Some basic knowledge of [Solidity](https://docs.soliditylang.org/) and [smart contract deployment](https://ethereum.org/en/developers/tutorials/deploying-your-first-smart-contract/) would be useful.
+
+## Start Geth in Dev Mode {#start-geth-in-dev-mode}
+
+Starting Geth in developer mode is as simple as providing the `--dev` flag. It is also possible to create a realistic block creation frequency by setting `--dev.period 13` instead of creating blocks only when transactions are pending. There are also additional configuration options required to follow this tutorial.
+
+Remix will be used to deploy a smart contract to the node which requires information to be exchanged externally to Geth's own domain. To permit this, enable `http` and the `net` namespace must be enabled and the Remix URL must be provided to `--http.corsdomain`. For this tutorial some other namespaces will also be enabled. The full command is as follows:
+
+```sh
+geth --dev --http --http.api eth,web3,net --http.corsdomain "http://remix.ethereum.org"
+```
+
+The terminal will display the following logs, confirming Geth has started successfully in developer mode:
+
+```terminal
+INFO [05-09|10:49:02.951] Starting Geth in ephemeral dev mode...
+INFO [05-09|10:49:02.952] Maximum peer count                       ETH=50 LES=0 total=50
+INFO [05-09|10:49:02.952] Smartcard socket not found, disabling    err="stat /run/pcscd/pcscd.comm: no such file or directory"
+INFO [05-09|10:49:02.953] Set global gas cap                       cap=50,000,000
+INFO [05-09|10:49:03.133] Using developer account                  address=0x7Aa16266Ba3d309e3cb278B452b1A6307E52Fb62
+INFO [05-09|10:49:03.196] Allocated trie memory caches             clean=154.00MiB dirty=256.00MiB
+INFO [05-09|10:49:03.285] Writing custom genesis block
+INFO [05-09|10:49:03.286] Persisted trie from memory database      nodes=13 size=1.90KiB time="180.524µs" gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B
+INFO [05-09|10:49:03.287] Initialised chain configuration          config="{ ChainID: 1337 Homestead: 0 DAO: nil DAOSupport: false EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0 Constantinople: 0 Petersburg: 0 Istanbul: 0, Muir Glacier: 0, Berlin: 0, London: 0, Arrow Glacier: nil, MergeFork: nil, Terminal TD: nil, Engine: clique}"
+INFO [05-09|10:49:03.288] Initialising Ethereum protocol           network=1337 dbversion= nil
+INFO [05-09|10:49:03.289] Loaded most recent local header          number=0 hash=c9c3de..579bb8 td=1 age=53y1mo1w
+INFO [05-09|10:49:03.289] Loaded most recent local full block      number=0 hash=c9c3de..579bb8 td=1 age=53y1mo1w
+INFO [05-09|10:49:03.289] Loaded most recent local fast block      number=0 hash=c9c3de..579bb8 td=1 age=53y1mo1w
+WARN [05-09|10:49:03.289] Failed to load snapshot, regenerating    err="missing or corrupted snapshot"
+INFO [05-09|10:49:03.289] Rebuilding state snapshot
+INFO [05-09|10:49:03.290] Resuming state snapshot generation       root=ceb850..0662cb accounts=0 slots=0 storage=0.00B elapsed="778.089µs"
+INFO [05-09|10:49:03.290] Regenerated local transaction journal    transactions=0 accounts=0
+INFO [05-09|10:49:03.292] Gasprice oracle is ignoring threshold set threshold=2
+INFO [05-09|10:49:03.292] Generated state snapshot                 accounts=10 slots=0 storage=412.00B elapsed=2.418ms
+WARN [05-09|10:49:03.292] Error reading unclean shutdown markers   error="leveldb: not found"
+INFO [05-09|10:49:03.292] Starting peer-to-peer node               instance=Geth/v1.10.18-unstable-8d84a701-20220503/linux-amd64/go1.18.1
+WARN [05-09|10:49:03.292] P2P server will be useless, neither dialing nor listening
+INFO [05-09|10:49:03.292] Stored checkpoint snapshot to disk       number=0 hash=c9c3de..579bb8
+INFO [05-09|10:49:03.312] New local node record                    seq=1,652,089,743,311 id=bfedca74bea20733 ip=127.0.0.1 udp=0 tcp=0
+INFO [05-09|10:49:03.313] Started P2P networking                   self=enode://0544de6446dd5831daa5a391de8d0375d93ac602a95d6a182d499de31f22f75b6645c3f562932cac8328d51321b676c683471e2cf7b3c338bb6930faf6ead389@127.0.0.1:0
+INFO [05-09|10:49:03.314] IPC endpoint opened                      url=/tmp/geth.ipc
+INFO [05-09|10:49:03.315] HTTP server started                      endpoint=127.0.0.1:8545 auth=false prefix= cors=http:remix.ethereum.org vhosts=localhost
+INFO [05-09|10:49:03.315] Transaction pool price threshold updated price=0
+INFO [05-09|10:49:03.315] Updated mining threads                   threads=0
+INFO [05-09|10:49:03.315] Transaction pool price threshold updated price=1
+INFO [05-09|10:49:03.315] Etherbase automatically configured       address=0x7Aa16266Ba3d309e3cb278B452b1A6307E52Fb62
+INFO [05-09|10:49:03.316] Commit new sealing work                  number=1 sealhash=2372a2..7fb8e7 uncles=0 txs=0 gas=0 fees=0 elapsed="202.366µs"
+WARN [05-09|10:49:03.316] Block sealing failed                     err="sealing paused while waiting for transactions"
+INFO [05-09|10:49:03.316] Commit new sealing work                  number=1 sealhash=2372a2..7fb8e7 uncles=0 txs=0 gas=0 fees=0 elapsed="540.054µs"
+```
+
+This terminal must be left running throughout the entire tutorial. In a second terminal, attach a Javascript console. By default the `ipc` file is saved in the `datadir`:
+
+```sh
+geth attach <datadir>/geth.ipc
+```
+
+The Javascript terminal will open with the following welcome message:
+
+```terminal
+Welcome to the Geth Javascript console!
+
+instance: Geth/v1.10.18-unstable-8d84a701-20220503/linux-amd64/go.1.18.1
+coinbase: 0x540dbaeb2390f2eb005f7a6dbf3436a0959197a9
+at block: 0 (Thu Jan 01 1970 01:00:00 GMT+0100 (BST))
+ modules: eth:1.0 rpc:1.0 web3:1.0
+
+To exit, press ctrl-d or type exit
+>
+```
+
+For simplicity this tutorial uses Geth's built-in account management. First, the existing accounts can be displayed using `eth.accounts`:
+
+```sh
+eth.accounts
+```
+
+An array containing a single address will be displayed in the terminal, despite no accounts having yet been explicitly created. This is the "coinbase" account. The coinbase address is the recipient of the total amount of ether created at the local network genesis. Querying the ether balance of the coinbase account will return a very large number. The coinbase account can be invoked as `eth.accounts[0]` or as `eth.coinbase`:
+
+```terminal
+> eth.coinbase==eth.accounts[0]
+true
+```
+
+The following command can be used to query the balance. The return value is in units of Wei, which is divided by 1<sup>18</sup> to give units of ether. This can be done explicitly or by calling the `web3.FromWei()` function:
+
+```sh
+eth.getBalance(eth.coinbase)/1e18
+
+// or
+
+web3.fromWei(eth.getBalance(eth.coinbase))
+```
+
+Using `web3.fromWei()` is less error prone because the correct multiplier is built in. These commands both return the following:
+
+```terminal
+1.157920892373162e+59
+```
+
+A new account can be created using Clef. Some of the ether from the coinbase can then be transferred across to it. A new account is generated using the `newaccount` function on the command line:
+
+```sh
+clef newaccount --keystore <path-to-keystore>
+```
+
+The terminal will display a request for a password, twice. Once provided, a new account will be created and its address printed to the terminal. The account creation is also logged in the Geth terminal, including the location of the keyfile in the keystore. It is a good idea to back up the password somewhere at this point. If this were an account on a live network, intended to own assets of real-world value, it would be critical to back up the account password and the keystore in a secure manner.
+
+To reconfirm the account creation, running `eth.accounts` in the Javascript console should display an array containing two account addresses, one being the coinbase and the other being the newly generated address. The following command transfers 50 ETH from the coinbase to the new account:
+
+```sh
+eth.sendTransaction({from: eth.coinbase, to: eth.accounts[1], value: web3.toWei(50, "ether")})
+```
+
+A transaction hash will be returned to the console. This transaction hash will also be displayed in the logs in the Geth console, followed by logs confirming that a new block was mined (remember in the local development network blocks are mined when transactions are pending). The transaction details can be displayed in the Javascript console by passing the transaction hash to `eth.getTransaction()`:
+
+```sh
+eth.getTransaction("0x62044d2cab405388891ee6d53747817f34c0f00341cde548c0ce9834e9718f27")
+```
+
+The transaction details are displayed as follows:
+
+```terminal
+{
+  accessList: [],
+  blockHash: "0xdef68762539ebfb247e31d749acc26ab5df3163aabf9d450b6001c200d17da8a",
+  blockNumber: 1,
+  chainId: "0x539",
+  from: "0x540dbaeb2390f2eb005f7a6dbf3436a0959197a9",
+  gas: 21000,
+  gasPrice: 875000001,
+  hash: "0x2326887390dc04483d435a6303dc05bd2648086eab15f24d7dcdf8c26e8af4b8",
+  input: "0x",
+  maxFeePerGas: 2000000001,
+  maxPriorityFeePerGas: 1,
+  nonce: 0,
+  r: "0x3f7b54f095b837ec13480eab5ac7de082465fc79f43b813cca051394dd028d5d",
+  s: "0x167ef271ae8175239dccdd970db85e06a044d5039252d6232d0954d803bb4e3e",
+  to: "0x43e3a14fb8c68caa7eea95a02693759de4513950",
+  transactionIndex: 0,
+  type: "0x2",
+  v: "0x0",
+  value: 50000000000000000000
+}
+```
+
+Now that the user account is funded with ether, a contract can be created ready to deploy to the Geth node.
+
+## A simple smart contract {#simple-smart-contract}
+
+This tutorial will make use of a classic example smart contract, `Storage.sol`. This contract exposes two public functions, one to add a value to the contract storage and one to view the stored value. The contract, written in Solidity, is provided below:
+
+```javascript
+pragma solidity >=0.7.0;
+
+contract Storage{
+
+
+    uint256 number;
+
+    function store(uint256 num) public{
+
+        number = num;
+    }
+
+    function retrieve() public view returns (uint256){
+        return number;
+
+    }
+}
+```
+
+Solidity is a high-level language that makes code executable by the Ethereum virtual machine (EVM) readable to humans. This means that there is an intermediate step between writing code in Solidity and deploying it to Ethereum. This step is called "compilation" and it converts human-readable code into EVM-executable byte-code. This byte-code is then included in a transaction sent from the Geth node during contract deployment. This can all be done directly from the Geth Javascript console; however this tutorial uses an online IDE called Remix to handle the compilation and deployment of the contract to the local Geth node.
+
+## Compile and deploy using Remix {#compile-and-deploy}
+
+In a web browser, open <https://remix.ethereum.org>. This opens an online smart contract development environment. On the left-hand side of the screen there is a side-bar menu that toggles between several toolboxes that are displayed in a vertical panel. On the right hand side of the screen there is an editor and a terminal. This layout is similar to the default layout of many other IDEs such as [VSCode](https://code.visualstudio.com/). The contract defined in the previous section, `Storage.sol` is already available in the `Contracts` directory in Remix. It can be opened and reviewed in the editor.
+
+![Remix](/images/docs/remix.png)
+
+The Solidity logo is present as an icon in the Remix side-bar. Clicking this icon opens the Solidity compiler wizard. This can be used to compile `Storage.sol` ready. With `Solidity.sol` open in the editor window, simply click the `Compile 1_Storage.sol` button. A green tick will appear next to the Solidity icon to confirm that the contract has compiled successfully. This means the contract bytecode is available.
+
+![Remix-compiler](/images/docs/remix-compiler.png)
+
+Below the Solidity icon is a fourth icon that includes the Ethereum logo. Clicking this opens the Deploy menu. In this menu, Remix can be configured to connect to the local Geth node. In the drop-down menu labelled `ENVIRONMENT`, select `Injected Web3`. This will open an information pop-up with instructions for configuring Geth - these can be ignored as they were completed earlier in this tutorial. However, at the bottom of this pop-up is a box labelled `Web3 Provider Endpoint`. This should be set to Geth's 8545 port on `localhost` (`127.0.0.1:8545`). Click OK. The `ACCOUNT` field should automatically populate with the address of the account created earlier using the Geth Javascript console.
+
+![Remix-deploy](/images/docs/remix-deploy.png)
+
+To deploy `Storage.sol`, click `DEPLOY`.
+
+The following logs in the Geth terminal confirm that the contract was successfully deployed.
+
+```terminal
+INFO [05-09|12:27:09.680] Setting new local account                address=0x7Aa16266Ba3d309e3cb278B452b1A6307E52Fb62
+INFO [05-09|12:27:09.680] Submitted contract creation              hash=0xbf2d2d1c393a882ffb6c90e6d1713906fd799651ae683237223b897d4781c4f2 from=0x7Aa16266Ba3d309e3cb278B452b1A6307E52Fb62 nonce=1 contract=0x4aA11DdfD817dD70e9FF2A2bf9c0306e8EC450d3 value=0
+INFO [05-09|12:27:09.681] Commit new sealing work                  number=2 sealhash=845a53..f22818 uncles=0 txs=1 gas=125,677 fees=0.0003141925 elapsed="335.991µs"
+INFO [05-09|12:27:09.681] Successfully sealed new block            number=2 sealhash=845a53..f22818 hash=e927bc..f2c8ed elapsed="703.415µs"
+INFO [05-09|12:27:09.681] 🔨 mined potential block                  number=2 hash=e927bc..f2c8ed
+```
+
+## Interact with contract using Remix {#interact-with-contract}
+
+The contract is now deployed on a local testnet version of the Ethereum blockchain. This means there is a contract address that contains executable bytecode that can be invoked by sending transactions with instructions, also in bytecode, to that address. Again, this can all be achieved by constructing transactions directly in the Geth console or even by making external http requests using tools such as Curl. Here, Remix is used to retrieve the value, then the same action is taken using the Javascript console.
+
+After deploying the contract in Remix, the `Deployed Contracts` tab in the sidebar automatically populates with the public functions exposed by `Storage.sol`. To send a value to the contract storage, type a number in the field adjacent to the `store` button, then click the button.
+
+![Remix-func](/images/docs/remix-func.png)
+
+In the Geth terminal, the following logs confirm that the transaction was successful (the actual values will vary from the example below):
+
+```terminal
+INFO [05-09|13:41:58.644] Submitted transaction                    hash=0xfa3cd8df6841c5d3706d3bacfb881d2b985d0b55bdba440f1fdafa4ed5b5cc31 from=0x7Aa16266Ba3d309e3cb278B452b1A6307E52Fb62 nonce=2 recipient=0x4aA11DdfD817dD70e9FF2A2bf9c0306e8EC450d3 value=0
+INFO [05-09|13:41:58.644] Commit new sealing work                  number=3 sealhash=5442e3..f49739 uncles=0 txs=1 gas=43724   fees=0.00010931   elapsed="334.446µs"
+INFO [05-09|13:41:58.645] Successfully sealed new block            number=3 sealhash=5442e3..f49739 hash=c076c8..eeee77 elapsed="581.374µs"
+INFO [05-09|13:41:58.645] 🔨 mined potential block                  number=3 hash=c076c8..eeee77
+```
+
+The transaction hash can be used to retrieve the transaction details using the Geth Javascript console, which will return the following information:
+
+```terminal
+{
+  accessList: [],
+  blockHash: "0xc076c88200618f4cbbfb4fe7c3eb8d93566724755acc6c4e9a355cc090eeee77",
+  blockNumber: 3,
+  chainId: "0x539",
+  from: "0x7aa16266ba3d309e3cb278b452b1a6307e52fb62",
+  gas: 43724,
+  gasPrice: 3172359839,
+  hash: "0xfa3cd8df6841c5d3706d3bacfb881d2b985d0b55bdba440f1fdafa4ed5b5cc31",
+  input: "0x6057361d0000000000000000000000000000000000000000000000000000000000000038",
+  maxFeePerGas: 4032048134,
+  maxPriorityFeePerGas: 2500000000,
+  nonce: 2,
+  r: "0x859b88062715c5d66b9a188886ad51b68a1e4938d5932ce2dac874c104d2b26",
+  s: "0x61ef6bc454d5e6a76c414f133aeb6321197a61e263a3e270a16bd4a65d94da55",
+  to: "0x4aa11ddfd817dd70e9ff2a2bf9c0306e8ec450d3",
+  transactionIndex: 0,
+  type: "0x2",
+  v: "0x1",
+  value: 0
+}
+```
+
+The `from` address is the account that sent the transaction, the `to` address is the deployment address of the contract. The value entered into Remix is now in storage at that contract address. This can be retrieved using Remix by calling the `retrieve` function - to do this simply click the `retrieve` button. Alternatively, it can be retrieved using `web3.getStorageAt` using the Geth Javascript console. The following command returns the value in the contract storage (replace the given address with the correct one displayed in the Geth logs).
+
+```sh
+web3.eth.getStorageAt("0x407d73d8a49eeb85d32cf465507dd71d507100c1", 0)
+```
+
+This returns a value that looks like the following:
+
+```terminal
+"0x000000000000000000000000000000000000000000000000000000000000000038"
+```
+
+The returned value is a left-padded hexadecimal value. For example, the return value `0x000000000000000000000000000000000000000000000000000000000000000038` corresponds to a value of `56` entered as a uint256 to Remix. After converting from hexadecimal string to decimal number the returned value should be equal to that provided to Remix in the previous step.
+
+## Reusing --datadir {#reusing-datadir}
+
+This tutorial used an ephemeral blockchain that is completely destroyed and started afresh during each dev-mode session. However, it is also possible to create persistent blockchain and account data that can be reused across multiple sessions. This is done by providing the `--datadir` flag and a directory name when starting Geth in dev-mode.
+
+```sh
+geth --datadir dev-chain --dev --http --http.api web3,eth,net --http.corsdomain "remix.ethereum.org"
+```
+
+## Re-using accounts {#reusing-accounts}
+
+Geth will fail to start in dev-mode if keys have been manually created or imported into the keystore in the `--datadir` directory. This is because the account cannot be automatically unlocked. To resolve this issue, the password defined when the account was created can be saved to a text file and its path passed to the `--password` flag on starting Geth, for example if `password.txt` is saved in the top-level `go-ethereum` directory:
+
+```sh
+geth --datadir dev-chain --dev --http --http.api web3,eth,net --http.corsdomain "remix.ethereum.org" --password password.txt
+```
+
+**Note** that this is an edge-case that applies when both the `--datadir` and `--dev` flags are used and a key has been manually created or imported into the keystore.
+
+## Summary {#summary}
+
+This tutorial has demonstrated how to spin up a local developer network using Geth. Having started this development network, a simple contract was deployed to the developer network. Then, Remix was connected to the local Geth node and used to deploy and interact with a contract. Remix was used to add a value to the contract storage and then the value was retrieved using Remix and also using the lower level commands in the Javascript console.

docs/developers/dapp-developer/mobile.md

@@ -0,0 +1,256 @@
+---
+title: Geth for Mobile
+description: Introduction to mobile development with Geth
+---
+
+Embedding clients into mobile devices is an important part of Ethereum's decentralization vision. This is because being able to verify data, follow the chain and submit transactions without relying on centralized intermediaries is critical for censorship resistant access to the network. Doing so on a mobile device is the most convenient route for many users. This relies on Geth running a [light client](/docs/fundamentals/les) on the mobile
+device and exposing an API that developers can use to build mobile apps on top of Geth. This page outlines how to download Geth for mobile and how to get started with managing Ethereum accounts in mobile applications. Ethereum mobile development is relatively nascent, but there is an active developer community. For further information on Geth mobile development visit the #mobile channel in the [Geth discord](https://discord.gg/wQdpS5aA).
+
+## Download and install {#download-and-install}
+
+### Android {#android}
+
+#### Android Studio {#android-studio}
+
+Geth for Mobile bundles can be downloaded directly from [the download page](/downloads) and inserted into a project in Android Studio via `File -> New -> New module... -> Import .JAR/.AAR Package`.
+
+It is also necessary to configure `gradle` to link the mobile library bundle to the application. This can be done by adding a new entry to the `dependencies` section of the `build.gradle` script, pointing it to the module that was just added (named `geth` by default).
+
+```gradle
+dependencies {
+    // All previous dependencies
+    compile project(':geth')
+}
+```
+
+#### Manual build {#manual-build}
+
+Geth can also be built it locally using a `make` command. This will create an Android archive called `geth.aar` in the `build/bin` folder that can be imported into Android Studio as described above.
+
+```shell
+$ make android
+[...]
+Done building.
+Import "build/bin/geth.aar" to use the library.
+```
+
+### iOS {#ios}
+
+Geth must be downloaded and built locally for IoS. Building locally is achieved using the `make` command. This will create an iOS XCode framework called `Geth.framework` in the `build/bin` folder that can be imported into XCode as described above.
+
+```bash
+$ make ios
+[...]
+Done building.
+Import "build/bin/Geth.framework" to use the library.
+```
+
+## Mobile API {#mobile-api}
+
+Similarly to the reusable [Go libraries](/docs/developers/dapp-developer/native-accounts), the mobile wrappers focus on three main usage areas:
+
+- Simplified client side account management
+- Remote node interfacing via different transports
+- Contract interactions through auto-generated bindings
+
+The Geth mobile API is broadly equivalent to the [Go API](/docs/developers/dapp-developer/native-accounts). The source code can be found in the `mobile` section of Geth's
+[GitHub](https://github.com/ethereum/go-ethereum/tree/master/mobile).
+
+## Mobile Account Management {#mobile-account-management}
+
+Best practise for account management is to do it client-side, with all sensitive information self-contained inside the local application. This ensures the developer/user retains fine-grained control over the access permissions for user-data instead of outsourcing security
+to a third party.
+
+To support this, Geth provides an accounts library that includes the tools required for secure account management via encrypted keystores and passphrase protected accounts, similarly to running a full Geth node.
+
+### Encrypted keystores {#encrypted-keystores}
+
+Access keys to Ethereum accounts should never be stored in plain-text. Instead, they should be stored encrypted so that even if the mobile device is accessed by a malicious third party the keys are still hidden under an additional layer of security. Geth provides a keystore that enables developers to store keys securely using the [`secp256k1` elliptic curve](https://www.secg.org/sec2-v2.pdf), implemented using [`libsecp256k`](https://github.com/bitcoin-core/secp256k1) and wrapped by [Geth accounts](https://godoc.org/github.com/ethereum/go-ethereum/accounts).
+
+Accounts are stored on disk in the [Web3 Secret Storage](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) format. Developers should be aware of these implementation details but are not required to deeply understand the cryptographic primitives in order to use the keystore.
+
+One thing that should be understood, though, is that the cryptographic primitives underpinning the keystore can operate in _light_ or _standard_ mode. Light mode is computationally cheaper, while standard mode has extra security. Light mode is appropriate for mobile devices, but developers
+should be aware that there is a security trade-off.
+
+- _standard_ needs 256MB memory and 1 second processing on a modern CPU to access a key
+- _light_ needs 4MB memory and 100 millisecond processing on a modern CPU to access a key
+
+### Keystores on Android (Java) {#keystores-on-android}
+
+The encrypted keystore on Android is implemented by the `KeyStore` class from the `org.ethereum.geth` package. The configuration constants are located in the `Geth` abstract class, similarly from the `org.ethereum.geth` package. Hence to do client side account management on Android, two classes should be imported into the Java code:
+
+```java
+import org.ethereum.geth.Geth;
+import org.ethereum.geth.KeyStore;
+```
+
+Then new encrypted keystore can be created via:
+
+```java
+KeyStore ks = new KeyStore("/path/to/keystore", Geth.LightScryptN, Geth.LightScryptP);
+```
+
+The keystore should be in a location writable by the local mobile application but on-readable for other installed applications such as inside the app's data directory. If the `KeyStore` is created from within a class extending an Android object, access to the `Context.getFilesDir()` method is probably provided via `this.getFilesDir()`, so the keystore path could be set to `this.getFilesDir() + "/keystore"`.
+
+The last two arguments of the `KeyStore` constructor are the crypto parameters defining how resource-intensive the keystore encryption should be. The choices are `Geth.StandardScryptN, Geth.StandardScryptP`, `Geth.LightScryptN, Geth.LightScryptP` or custom numbers. The _light_ version is recommended.
+
+### Keystores on iOS (Swift 3) {#keystores-on-ios}
+
+The encrypted keystore on iOS is implemented by the `GethKeyStore` class from the `Geth` framework. The configuration constants are located in the same namespace as global variables. Hence to do client side account management on iOS, `Geth` framework should be
+imported into the Swift code:
+
+```swift
+import Geth
+```
+
+Then a new encrypted account manager can be created using:
+
+```swift
+let ks = GethNewKeyStore("/path/to/keystore", GethLightScryptN, GethLightScryptP);
+```
+
+The keystore folder needs to be in a location writable by the local mobile application but non-readable for other installed applications such as inside the app's document directory. The document directory shopuld be retrievable using
+`let datadir = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]`, so the keystore path could be `datadir + "/keystore"`.
+
+The last two arguments of the `GethNewKeyStore` factory method are the crypto parameters defining how resource-intensive the keystore encryption should be. The choices are `GethStandardScryptN, GethStandardScryptP`, `GethLightScryptN, GethLightScryptP` or custom numbers. The _light_ version is recommended.
+
+### Account lifecycle {#account-lifecycle}
+
+The encyrpted keystore can be used for the entire account lifecycle requirements of a mobile application. This includes the basic functionality of creating new accounts and deleting existing ones as well as more advanced functions like updating access credentials and account
+import/export.
+
+Although the keystore defines the encryption strength it uses to store accounts, there is no global master password that can grant access to all of them. Rather each account is maintained individually, and stored on disk in its [encrypted format][secstore] individually, ensuring a much cleaner and stricter separation of credentials.
+
+This individuality means that any operation requiring access to an account will need to provide the necessary authentication credentials for that particular account in the form of a passphrase:
+
+- When creating a new account, the caller must supply a passphrase to encrypt the account with. This passphrase will be required for any subsequent access.
+- When deleting an existing account, the caller must supply a passphrase to verify ownership of the account. This isn't cryptographically necessary, rather a protective measure against accidental loss of accounts.
+- When updating an existing account, the caller must supply both current and new passphrases. After completing the operation, the account will not be accessible via the old passphrase.
+- When exporting an existing account, the caller must supply both the current passphrase to decrypt the account, as well as an export passphrase to re-encrypt it with before returning the key-file to the user. This is required to allow moving accounts between devices without sharing original credentials.
+- When importing a new account, the caller must supply both the encryption passphrase of the key-file being imported, as well as a new passphrase with which to store the account. This is required to allow storing account with different credentials than used for moving them around.
+
+_Please note, there is no recovery mechanisms for losing the passphrases. The cryptographic properties of the encrypted keystore (if using the provided parameters) guarantee that account credentials cannot be brute forced in any meaningful time._
+
+### Accounts on Android (Java) {#accounts-on-android}
+
+An Ethereum account on Android is implemented by the `Account` class from the `org.ethereum.geth` package. Assuming an instance of a `KeyStore` called `ks` exists, all of the described lifecycle operations can be executed with a handful of function calls:
+
+```java
+// Create a new account with the specified encryption passphrase.
+Account newAcc = ksm.newAccount("Creation password");
+
+// Export the newly created account with a different passphrase. The returned
+// data from this method invocation is a JSON encoded, encrypted key-file.
+byte[] jsonAcc = ks.exportKey(newAcc, "Creation password", "Export password");
+
+// Update the passphrase on the account created above inside the local keystore.
+ks.updateAccount(newAcc, "Creation password", "Update password");
+
+// Delete the account updated above from the local keystore.
+ks.deleteAccount(newAcc, "Update password");
+
+// Import back the account we've exported (and then deleted) above with yet
+// again a fresh passphrase.
+Account impAcc = ks.importKey(jsonAcc, "Export password", "Import password");
+```
+
+Although instances of `Account` can be used to access various information about specific Ethereum accounts, they do not contain any sensitive data (such as passphrases or private keys), rather they act solely as identifiers for client code and the keystore.
+
+### Accounts on iOS (Swift 3) {#accounts-on-ios}
+
+An Ethereum account on iOS is implemented by the `GethAccount` class from the `Geth` framework. Assuming an instance of a `GethKeyStore` called `ks` exists, all of the described lifecycle operations can be executed with a handful of function calls:
+
+```swift
+// Create a new account with the specified encryption passphrase.
+let newAcc = try! ks?.newAccount("Creation password")
+
+// Export the newly created account with a different passphrase. The returned
+// data from this method invocation is a JSON encoded, encrypted key-file.
+let jsonKey = try! ks?.exportKey(newAcc!, passphrase: "Creation password", newPassphrase: "Export password")
+
+// Update the passphrase on the account created above inside the local keystore.
+try! ks?.update(newAcc, passphrase: "Creation password", newPassphrase: "Update password")
+
+// Delete the account updated above from the local keystore.
+try! ks?.delete(newAcc, passphrase: "Update password")
+
+// Import back the account we've exported (and then deleted) above with yet
+// again a fresh passphrase.
+let impAcc  = try! ks?.importKey(jsonKey, passphrase: "Export password", newPassphrase: "Import password")
+```
+
+Although instances of `GethAccount` can be used to access various information about specific Ethereum accounts, they do not contain any sensitive data (such as passphrases or private keys), rather they act solely as identifiers for client code and the keystore.
+
+## Signing authorization {#signing-authorization}
+
+As mentioned above, account objects do not hold the sensitive private keys of the associated Ethereum accounts - they are merely placeholders to identify the cryptographic keys with. All operations that require authorization (e.g. transaction signing) are performed by the account manager after granting it access to the private keys.
+
+There are a few different ways one can authorize the account manager to execute signing operations. Since the different methods have very different security guarantees, it is essential to be clear on how each works:
+
+- **Single authorization**: The simplest way to sign a transaction via the keystore is to provide the passphrase of the account every time something needs to be signed, which will ephemerally decrypt the private key, execute the signing operation and immediately throw away the decrypted key. The drawbacks are that the passphrase needs to be queried from the user every time, which can become annoying if done frequently; or the application needs to keep the passphrase in memory, which can have security consequences if not done properly; and depending on the keystore's configured strength, constantly decrypting keys can result in non-negligible resource requirements.
+
+- **Multiple authorizations**: A more complex way of signing transactions via the keystore is to unlock the account via its passphrase once, and allow the account manager to cache the decrypted private key, enabling all subsequent signing requests tocomplete without the passphrase. The lifetime of the cached private key may be managed manually (by explicitly locking the account back up) or automatically (by providing a timeout during unlock). This mechanism is useful for scenarios where the user may need to sign many transactions or the application would need to do so without requiring user input. The crucial aspect to remember is that **anyone with access to the account manager can sign transactions while a particular account is unlocked** (e.g. device left unattended; application running untrusted code).
+
+### Signing on Android (Java) {#signing-on-android}
+
+Assuming an instance of a `KeyStore` called `ks` exists, a new account to sign transactions can be created using its `newAccount` method. For this demonstation a hard-coded example transaction is created to sign:
+
+```java
+// Create a new account to sign transactions with
+Account signer = ks.newAccount("Signer password");
+Transaction tx = new Transaction(
+    1, new Address("0x0000000000000000000000000000000000000000"),
+    new BigInt(0), new BigInt(0), new BigInt(1), null); // Random empty transaction
+BigInt chain = new BigInt(1); // Chain identifier of the main net
+```
+
+The transaction `tx` can be signed using the authorization mechanisms described above:
+
+```java
+// Sign a transaction with a single authorization
+Transaction signed = ks.signTxPassphrase(signer, "Signer password", tx, chain);
+
+// Sign a transaction with multiple manually cancelled authorizations
+ks.unlock(signer, "Signer password");
+signed = ks.signTx(signer, tx, chain);
+ks.lock(signer.getAddress());
+
+// Sign a transaction with multiple automatically cancelled authorizations
+ks.timedUnlock(signer, "Signer password", 1000000000);
+signed = ks.signTx(signer, tx, chain);
+```
+
+### Signing on iOS (Swift 3) {#signing-on-ios}
+
+Assuming an instance of a `GethKeyStore` called `ks` exists, a new account can be created to sign transactions with its `newAccount` method. For
+this demonstation a hard-coded example transaction is created to sign:
+
+```swift
+// Create a new account to sign transactions with
+var error: NSError?
+let signer = try! ks?.newAccount("Signer password")
+
+let to    = GethNewAddressFromHex("0x0000000000000000000000000000000000000000", &error)
+let tx    = GethNewTransaction(1, to, GethNewBigInt(0), GethNewBigInt(0), GethNewBigInt(0), nil) // Random empty transaction
+let chain = GethNewBigInt(1) // Chain identifier of the main net
+```
+
+The transaction `tx` can now be signed using the authorization methods described above:
+
+```swift
+// Sign a transaction with a single authorization
+var signed = try! ks?.signTxPassphrase(signer, passphrase: "Signer password", tx: tx, chainID: chain)
+
+// Sign a transaction with multiple manually cancelled authorizations
+try! ks?.unlock(signer, passphrase: "Signer password")
+signed = try! ks?.signTx(signer, tx: tx, chainID: chain)
+try! ks?.lock(signer?.getAddress())
+
+// Sign a transaction with multiple automatically cancelled authorizations
+try! ks?.timedUnlock(signer, passphrase: "Signer password", timeout: 1000000000)
+signed = try! ks?.signTx(signer, tx: tx, chainID: chain)
+```
+
+## Summary {#summary}
+
+This page introduced Geth for mobile. In addition to download and installation instructions, basic account management was demonstrated for mobile applications on iOS and Android.

docs/developers/dapp-developer/native-accounts.md

@@ -0,0 +1,124 @@
+---
+title: Go Account Management
+description: Introduction to account management in Go native applications.
+---
+
+Geth provides a simple, yet thorough accounts package that includes all the tools developers need to leverage all the security of Geth's crypto implementation in a Go native application. The account management is done client side with all sensitive data held inside the application. This gives the user control over access permissions without relying on any third party.
+
+**Note: Geth's built-in account management is convenient and straightforward to use, but best practise is to use the external tool _Clef_ for key management.**
+
+## Encrypted keystores {#encrypted-keystores}
+
+Access keys to Ethereum accounts should never be stored in plain-text. Instead, they should be stored encrypted so that even if the mobile device is accessed by a malicious third party the keys are still hidden under an additional layer of security. Geth provides a keystore that enables developers to store keys securely. The Geth keystore uses [Scrypt](https://pkg.go.dev/golang.org/x/crypto/scrypt) to store keys that are encoded using the [`secp256k1`](https://www.secg.org/sec2-v2.pdf) elliptic curve. Accounts are stored on disk in the [Web3 Secret Storage](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) format. Developers should be aware of these implementation details
+but are not required to deeply understand the cryptographic primitives in order to use the keystore.
+
+One thing that should be understood, though, is that the cryptographic primitives underpinning the keystore can operate in light or standard mode.Light mode is computationally cheaper, while standard mode has extra security. Light mode is appropriate for mobile devices, but developers should be aware that there is a security trade-off.
+
+- standard needs 256MB memory and 1 second processing on a modern CPU to access a key
+- light needs 4MB memory and 100 millisecond processing on a modern CPU to access a key
+
+The encrypted keystore is implemented by the [`accounts.Manager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager) struct from the [`accounts`](https://godoc.org/github.com/ethereum/go-ethereum/accounts) package, which also contains the configuration constants for the _standard_ or _light_ security modes described above. Hence client side account management
+simply requires importing the `accounts` package into the application code.
+
+```go
+import "github.com/ethereum/go-ethereum/accounts"
+import "github.com/ethereum/go-ethereum/accounts/keystore"
+import "github.com/ethereum/go-ethereum/common"
+```
+
+Afterwards a new encrypted account manager can be created via:
+
+```go
+ks := keystore.NewKeyStore("/path/to/keystore", keystore.StandardScryptN, keystore.StandardScryptP)
+am := accounts.NewManager(&accounts.Config{InsecureUnlockAllowed: false}, ks)
+```
+
+The path to the keystore folder needs to be a location that is writable by the local user but non-readable for other system users, such as inside the user's home directory.
+
+The last two arguments of [`keystore.NewKeyStore`](https://godoc.org/github.com/ethereum/go-ethereum/accounts/keystore#NewKeyStore) are the crypto parameters defining how resource-intensive the keystore encryption should be. The options are [`accounts.StandardScryptN, accounts.StandardScryptP`, `accounts.LightScryptN, accounts.LightScryptP`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#pkg-constants) or custom values (requiring understanding of the underlying cryptography). The _standard_ version is recommended.
+
+## Account lifecycle {#account-lifecycle}
+
+Once an encrypted keystore for Ethereum accounts exists it, it can be used to manage accounts for the entire account lifecycle requirements of a Go native application. This includes the basic functionality of creating new accounts and deleting existing ones as well as updating access credentials, exporting existing accounts, and importing them on other devices.
+
+Although the keystore defines the encryption strength it uses to store accounts, there is no global master password that can grant access to all of them. Rather each account is maintained individually, and stored on disk in its [encrypted format](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) individually, ensuring a much cleaner and stricter separation of credentials.
+
+This individuality means that any operation requiring access to an account will need to provide the necessary authentication credentials for that particular account in the form of a passphrase:
+
+- When creating a new account, the caller must supply a passphrase to encrypt the account with. This passphrase will be required for any subsequent access, the lack of which will forever forfeit using the newly created account.
+
+- When deleting an existing account, the caller must supply a passphrase to verify ownership of the account. This isn't cryptographically necessary, rather a protective measure against accidental loss of accounts.
+
+- When updating an existing account, the caller must supply both current and new passphrases. After completing the operation, the account will not be accessible via the old passphrase any more.
+
+- When exporting an existing account, the caller must supply both the current passphrase to decrypt the account, as well as an export passphrase to re-encrypt it with before returning the key-file to the user. This is required to allow moving accounts between machines and applications without sharing original credentials.
+
+- When importing a new account, the caller must supply both the encryption passphrase of the key-file being imported, as well as a new passhprase with which to store the account. This is required to allow storing account with different credentials than used for moving them around.
+
+**_Please note, there are no recovery mechanisms for lost passphrases. The cryptographic properties of the encrypted keystore (using the provided parameters) guarantee that account credentials cannot be brute forced in any meaningful time._**
+
+An Ethereum account is implemented by the [`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) struct from the Geth [accounts](https://godoc.org/github.com/ethereum/go-ethereum/accounts) package. Assuming an instance of an [`accounts.Manager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager) called `am` exists, all of the described lifecycle operations can be executed with a handful of function calls (error handling omitted).
+
+```go
+// Create a new account with the specified encryption passphrase.
+newAcc, _ := ks.NewAccount("Creation password")
+fmt.Println(newAcc)
+
+// Export the newly created account with a different passphrase. The returned
+// data from this method invocation is a JSON encoded, encrypted key-file.
+jsonAcc, _ := ks.Export(newAcc, "Creation password", "Export password")
+
+// Update the passphrase on the account created above inside the local keystore.
+_ = ks.Update(newAcc, "Creation password", "Update password")
+
+// Delete the account updated above from the local keystore.
+_ = ks.Delete(newAcc, "Update password")
+
+// Import back the account we've exported (and then deleted) above with yet
+// again a fresh passphrase.
+impAcc, _ := ks.Import(jsonAcc, "Export password", "Import password")
+```
+
+_Although instances of [`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) can be used to access various information about specific Ethereum accounts, they do not contain any sensitive data (such as passphrases or private keys), rather they act solely as identifiers for client code and the keystore._
+
+## Signing authorization {#signing-authorization}
+
+Account objects do not hold the sensitive private keys of the associated Ethereum accounts. Account objects are placeholders that identify the cryptographic keys. All operations that require authorization (e.g. transaction signing) are performed by the account manager after granting it access to the private keys.
+
+There are a few different ways to authorize the account manager to execute signing operations, each having its advantages and drawbacks. Since the different methods have wildly different security guarantees, it is essential to be clear on how each works:
+
+- **Single authorization**: The simplest way to sign a transaction via the account manager is to provide the passphrase of the account every time something needs to be signed, which will ephemerally decrypt the private key, execute the signing operation and immediately throw away the decrypted key. The drawbacks are that the passphrase needs to be queried from the user every time, which can become annoying if done frequently or the application needs to keep the passphrase in memory, which can have security consequences if not done properly. Depending on the keystore's configured strength, constantly decrypting keys can result in non-negligible resource requirements.
+
+- **Multiple authorizations**: A more complex way of signing transactions via the account manager is to unlock the account via its passphrase once, and allow the account manager to cache the decrypted private key, enabling all subsequent signing requests to complete without the passphrase. The lifetime of the cached private key may be managed manually (by explicitly locking the account back up) or automatically (by providing a timeout during unlock). This mechanism is useful for scenarios where the user may need to sign many transactions or the application would need to do so without requiring user input. The crucial aspect to remember is that **anyone with access to the account manager can sign transactions while a particular account is unlocked** (e.g. application running untrusted code).
+
+Assuming an instance of an [`accounts.Manager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager) called `am` exists, a new account can be created to sign transactions using [`NewAccount`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.NewAccount). Creating transactions is out of scope for this page so instead a random [`common.Hash`](https://godoc.org/github.com/ethereum/go-ethereum/common#Hash) will be signed instead.
+
+For information on creating transactions in Go native applications see the [Go API page](/docs/developers/dapp-developer/native).
+
+```go
+// Create a new account to sign transactions with
+signer, _ := ks.NewAccount("Signer password")
+txHash := common.HexToHash("0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef")
+```
+
+With the boilerplate out of the way, the transaction can be signed using the authorization mechanisms described above:
+
+```go
+// Sign a transaction with a single authorization
+signature, _ := ks.SignHashWithPassphrase(signer, "Signer password", txHash.Bytes())
+
+// Sign a transaction with multiple manually cancelled authorizations
+_ = ks.Unlock(signer, "Signer password")
+signature, _ = ks.SignHash(signer, txHash.Bytes())
+_ = ks.Lock(signer.Address)
+
+// Sign a transaction with multiple automatically cancelled authorizations
+_ = ks.TimedUnlock(signer, "Signer password", time.Second)
+signature, _ = ks.SignHash(signer, txHash.Bytes())
+```
+
+Note that [`SignWithPassphrase`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.SignWithPassphrase) takes an [`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) as the signer, whereas [`Sign`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.Sign) takes only a [`common.Address`](https://godoc.org/github.com/ethereum/go-ethereum/common#Address). The reason for this is that an [`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) object may also contain a custom key-path, allowing [`SignWithPassphrase`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.SignWithPassphrase) to sign using accounts outside of the keystore; however [`Sign`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.Sign) relies on accounts already unlocked within the keystore, so it cannot specify custom paths.
+
+## Summary {#summary}
+
+Account management is a fundamental pillar of Ethereum development. Geth's Go API provides the tools required to integrate best-practise account security into Go native applications using a simple set of Go functions.

docs/developers/dapp-developer/native-bindings.md

@@ -0,0 +1,531 @@
+---
+title: Go Contract Bindings
+description: Introduction to generating bindings for using Geth features in Go native applications
+---
+
+This page introduces the concept of server-side native dapps. Geth provides the tools required to generate [Go](https://github.com/golang/go/wiki#getting-started-with-go) language bindings to any Ethereum contract that is compile-time type safe, highly performant and can be generated completely automatically from a compiled contract.
+
+Interacting with a contract on the Ethereum blockchain from Go is already possible via the RPC interfaces exposed by Ethereum clients. However, writing the boilerplate code that translates Go language constructs into RPC calls and back is time consuming and brittle - implementation bugs can only be detected during runtime and it's almost impossible to evolve a contract as even a tiny change in Solidity is awkward to port over to Go. Therefore, Geth provides tools for easily converting contract code into Go code that can be used directly in Go applications.
+
+This page provides an introduction to generating Go contract bindings and using them in a simple Go application.
+
+## Prerequisites {#prerequisites}
+
+This page is fairly beginner-friendly and designed for people starting out with writing Go native dapps. The core concepts will be introduced gradually as a developer would encounter them. However, some basic familiarity with [Ethereum](https://ethereum.org), [Solidity](https://docs.soliditylang.org/en/v0.8.15/) and [Go](https://go.dev/) is assumed.
+
+## What is an ABI? {#what-is-an-abi}
+
+Ethereum smart contracts have a schema that defines its functions and return types in the form of a JSON file. This JSON file is known as an _Application Binary Interface_, or ABI. The ABI acts as a specification for precisely how to encode data sent to a contract and how to decode the data the contract sends back. The ABI is the only essential piece of information required to generate Go bindings. Go developers can then use the bindings to interact with the contract from their Go application without having to deal directly with data encoding and decoding. An ABI is generated when a contract is compiled.
+
+## Abigen: Go binding generator {#abigen}
+
+Geth includes a source code generator called `abigen` that can convert Ethereum ABI definitions into easy to use, type-safe Go packages. With a valid Go development environment set up and the go-ethereum repository checked out correctly, `abigen` can be built as follows:
+
+```sh
+$ cd $GOPATH/src/github.com/ethereum/go-ethereum
+$ go build ./cmd/abigen
+```
+
+### Generating the bindings {#generating-bindings}
+
+To demonstrate the binding generator a contract is required. The contract `Storage.sol` implements two very simple functions: `store` updates a user-defined `uint256` to the contract's storage, and `retrieve` displays the value stored in the contract to the user. The Solidity code is as follows:
+
+```solidity
+// SPDX-License-Identifier: GPL-3.0
+
+pragma solidity >0.7.0 < 0.9.0;
+/**
+* @title Storage
+* @dev store or retrieve variable value
+*/
+
+contract Storage {
+
+	uint256 value;
+
+	function store(uint256 number) public{
+		value = number;
+	}
+
+	function retrieve() public view returns (uint256){
+		return value;
+	}
+}
+```
+
+This contract can be pasted into a text file and saved as `Storage.sol`.
+
+The following code snippet shows how an ABI can be generated for `Storage.sol` using the Solidity compiler `solc`.
+
+```shell
+solc --abi Storage.sol -o build
+```
+
+The ABI can also be generated in other ways such as using the `compile` commands in development frameworks such as [Truffle](https://trufflesuite.com/docs/truffle/), [Hardhat](https://hardhat.org/) and [Brownie](https://eth-brownie.readthedocs.io/en/stable/) or in the online IDE [Remix](https://remix.ethereum.org/). ABIs for existing verified contracts can be downloaded from [Etherscan](https://etherscan.io/).
+
+The ABI for `Storage.sol` (`Storage.abi`) looks as follows:
+
+```json
+[
+  {
+    "inputs": [],
+    "name": "retrieve",
+    "outputs": [{ "internalType": "uint256", "name": "", "type": "uint256" }],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [{ "internalType": "uint256", "name": "number", "type": "uint256" }],
+    "name": "store",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  }
+]
+```
+
+The contract binding can then be generated by passing the ABI to `abigen` as follows:
+
+```sh
+$ abigen --abi Storage.abi --pkg main --type Storage --out Storage.go
+```
+
+Where the flags are:
+
+- `--abi`: Mandatory path to the contract ABI to bind to
+- `--pkg`: Mandatory Go package name to place the Go code into
+- `--type`: Optional Go type name to assign to the binding struct
+- `--out`: Optional output path for the generated Go source file (not set = stdout)
+
+This will generate a type-safe Go binding for the Storage contract. The generated code will look something like the snippet below, the full version of which can be viewed [here](https://gist.github.com/jmcook1186/a78e59d203bb54b06e1b81f2cda79d93).
+
+```go
+// Code generated - DO NOT EDIT.
+// This file is a generated binding and any manual changes will be lost.
+
+package main
+
+import (
+	"errors"
+	"math/big"
+	"strings"
+
+	ethereum "github.com/ethereum/go-ethereum"
+	"github.com/ethereum/go-ethereum/accounts/abi"
+	"github.com/ethereum/go-ethereum/accounts/abi/bind"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/event"
+)
+
+// Reference imports to suppress errors if they are not otherwise used.
+var (
+	_ = errors.New
+	_ = big.NewInt
+	_ = strings.NewReader
+	_ = ethereum.NotFound
+	_ = bind.Bind
+	_ = common.Big1
+	_ = types.BloomLookup
+	_ = event.NewSubscription
+)
+
+// StorageMetaData contains all meta data concerning the Storage contract.
+var StorageMetaData = &bind.MetaData{
+	ABI: "[{\"inputs\":[],\"name\":\"retrieve\",\"outputs\":[{\"internalType\":\"uint256\",\"name\":\"\",\"type\":\"uint256\"}],\"stateMutability\":\"view\",\"type\":\"function\"},{\"inputs\":[{\"internalType\":\"uint256\",\"name\":\"number\",\"type\":\"uint256\"}],\"name\":\"store\",\"outputs\":[],\"stateMutability\":\"nonpayable\",\"type\":\"function\"}]",
+}
+
+// StorageABI is the input ABI used to generate the binding from.
+// Deprecated: Use StorageMetaData.ABI instead.
+var StorageABI = StorageMetaData.ABI
+
+// Storage is an auto generated Go binding around an Ethereum contract.
+type Storage struct {
+	StorageCaller     // Read-only binding to the contract
+	StorageTransactor // Write-only binding to the contract
+	StorageFilterer   // Log filterer for contract events
+}
+...
+
+```
+
+`Storage.go` contains all the bindings required to interact with `Storage.sol` from a Go application. However, this isn't very useful unless the contract is actually deployed on Ethereum or one of Ethereum's testnets. The following sections will demonstrate how to deploy the contract to
+an Ethereum testnet and interact with it using the Go bindings.
+
+### Deploying contracts to Ethereum {#deploying-contracts}
+
+In the previous section, the contract ABI was sufficient for generating the contract bindings from its ABI. However, deploying the contract requires some additional information in the form of the compiled bytecode.
+
+The bytecode is obtained by running the compiler again but this passing the `--bin` flag, e.g.
+
+```sh
+solc --bin Storage.sol -o Storage.bin
+```
+
+Then `abigen` can be run again, this time passing `Storage.bin`:
+
+```sh
+$ abigen --abi Storage.abi --pkg main --type Storage --out Storage.go --bin Storage.bin
+```
+
+This will generate something similar to the bindings generated in the previous section. However, an additional `DeployStorage` function has been injected:
+
+```go
+// DeployStorage deploys a new Ethereum contract, binding an instance of Storage to it.
+func DeployStorage(auth *bind.TransactOpts, backend bind.ContractBackend) (common.Address, *types.Transaction, *Storage, error) {
+	parsed, err := StorageMetaData.GetAbi()
+	if err != nil {
+		return common.Address{}, nil, nil, err
+	}
+	if parsed == nil {
+		return common.Address{}, nil, nil, errors.New("GetABI returned nil")
+	}
+
+	address, tx, contract, err := bind.DeployContract(auth, *parsed, common.FromHex(StorageBin), backend)
+	if err != nil {
+		return common.Address{}, nil, nil, err
+	}
+	return address, tx, &Storage{StorageCaller: StorageCaller{contract: contract}, StorageTransactor: StorageTransactor{contract: contract}, StorageFilterer: StorageFilterer{contract: contract}}, nil
+}
+```
+
+View the full file [here](https://gist.github.com/jmcook1186/91124cfcbc7f22dcd3bb4f148d2868a8).
+
+The new `DeployStorage()` function can be used to deploy the contract to an Ethereum testnet from a Go application. To do this requires incorporating the bindings into a Go application that also handles account management, authorization and Ethereum backend to deploy the contract through. Specifically, this requires:
+
+1. A running Geth node connected to an Ethereum testnet
+
+2. An account in the keystore prefunded with enough ETH to cover gas costs for deploying and interacting with the contract
+
+Assuming these prerequisites exist, a new `ethclient` can be instantiated with the local Geth node's ipc file, providing access to the testnet from the Go application. The key can be instantiated as a variable in the application by copying the JSON object from the keyfile in the keystore.
+
+Putting it all together would result in:
+
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+	"math/big"
+	"strings"
+	"time"
+
+	"github.com/ethereum/go-ethereum/accounts/abi/bind"
+	"github.com/ethereum/go-ethereum/ethclient"
+
+)
+
+const key = `<<json object from keystore>>`
+
+func main() {
+	// Create an IPC based RPC connection to a remote node and an authorized transactor
+	conn, err := rpc.NewIPCClient("/home/go-ethereum/goerli/geth.ipc")
+	if err != nil {
+		log.Fatalf("Failed to connect to the Ethereum client: %v", err)
+	}
+	auth, err := bind.NewTransactor(strings.NewReader(key), "<<strong_password>>")
+	if err != nil {
+		log.Fatalf("Failed to create authorized transactor: %v", err)
+	}
+	// Deploy the contract passing the newly created `auth` and `conn` vars
+	address, tx, instance, err := DeployStorage(auth, conn), new(big.Int), "Storage contract in Go!", 0, "Go!")
+	if err != nil {
+		log.Fatalf("Failed to deploy new storage contract: %v", err)
+	}
+	fmt.Printf("Contract pending deploy: 0x%x\n", address)
+	fmt.Printf("Transaction waiting to be mined: 0x%x\n\n", tx.Hash())
+
+	time.Sleep(250 * time.Millisecond) // Allow it to be processed by the local node :P
+
+	// function call on `instance`. Retrieves pending name
+	name, err := instance.Name(&bind.CallOpts{Pending: true})
+	if err != nil {
+		log.Fatalf("Failed to retrieve pending name: %v", err)
+	}
+	fmt.Println("Pending name:", name)
+}
+```
+
+Running this code requests the creation of a brand new `Storage` contract on the Goerli blockchain. The contract functions can be called while the contract is waiting to be included in a block.
+
+```sh
+Contract pending deploy: 0x46506d900559ad005feb4645dcbb2dbbf65e19cc
+Transaction waiting to be mined: 0x6a81231874edd2461879b7280ddde1a857162a744e3658ca7ec276984802183b
+
+Pending name: Storage contract in Go!
+```
+
+Once the contract deployment has been included in a validated block, the contract exists permanently at its deployment address and can now be interacted with from other applications without ever needing to be redeployed.
+
+Note that `DeployStorage` returns four variables:
+
+- `address`: the deployment address of the contract
+
+- `tx`: the transaction hash that can be queried using Geth or a service like [Etherscan](https://etherscan.io/)
+
+- `instance`: an instance of the deployed contract whose functions can be called in the Go application
+
+- `err`: a variable that handles errors in case of a deployment failure
+
+### Accessing an Ethereum contract {#accessing-contracts}
+
+To interact with a contract already deployed on the blockchain, the deployment `address` is required and a `backend` through which to access Ethereum must be defined. The binding generator provides an RPC backend out-of-the-box that can be used to attach to an existing Ethereum node via IPC, HTTP or WebSockets.
+
+As in the previous section, a Geth node running on an Ethereum testnet (recommend Goerli) and an account with some test ETH to cover gas is required. The `Storage.sol` deployment address is also needed.
+
+Again, an instance of `ethclient` can be created, passing the path to Geth's ipc file. In the example below this backend is assigned to the variable `conn`.
+
+```go
+// Create an IPC based RPC connection to a remote node
+// NOTE update the path to the ipc file!
+conn, err := ethclient.Dial("/home/go-ethereum/goerli/geth.ipc")
+if err != nil {
+	log.Fatalf("Failed to connect to the Ethereum client: %v", err)
+}
+```
+
+The functions available for interacting with the `Storage` contract are defined in `Storage.go`. To create a new instance of the contract in a Go application, the `NewStorage()` function can be used. The function is defined in `Storage.go` as follows:
+
+```go
+// NewStorage creates a new instance of Storage, bound to a specific deployed contract.
+func NewStorage(address common.Address, backend bind.ContractBackend) (*Storage, error) {
+	contract, err := bindStorage(address, backend, backend, backend)
+	if err != nil {
+		return nil, err
+	}
+	return &Storage{StorageCaller: StorageCaller{contract: contract}, StorageTransactor: StorageTransactor{contract: contract}, StorageFilterer: StorageFilterer{contract: contract}}, nil
+}
+```
+
+`NewStorage()` takes two arguments: the deployment address and a backend (`conn`) and returns an instance of the deployed contract. In the example below, the instance is assigned to `store`.
+
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/ethclient"
+)
+
+func main() {
+	// Create an IPC based RPC connection to a remote node
+	// NOTE update the path to the ipc file!
+	conn, err := ethclient.Dial("/home/go-ethereum/goerli/geth.ipc")
+	if err != nil {
+		log.Fatalf("Failed to connect to the Ethereum client: %v", err)
+	}
+	// Instantiate the contract and display its name
+	// NOTE update the deployment address!
+	store, err := NewStorage(common.HexToAddress("0x21e6fc92f93c8a1bb41e2be64b4e1f88a54d3576"), conn)
+	if err != nil {
+		log.Fatalf("Failed to instantiate Storage contract: %v", err)
+	}
+
+```
+
+The contract instance is then available to interact with in the Go application. To read a value from the blockchain, for example the `value` stored in the contract, the contract's `Retrieve()` function can be called. Again, the function is defined in `Storage.go` as follows:
+
+```go
+// Retrieve is a free data retrieval call binding the contract method 0x2e64cec1.
+//
+// Solidity: function retrieve() view returns(uint256)
+func (_Storage *StorageCaller) Retrieve(opts *bind.CallOpts) (*big.Int, error) {
+	var out []interface{}
+	err := _Storage.contract.Call(opts, &out, "retrieve")
+
+	if err != nil {
+		return *new(*big.Int), err
+	}
+
+	out0 := *abi.ConvertType(out[0], new(*big.Int)).(**big.Int)
+
+	return out0, err
+
+}
+```
+
+Note that the `Retrieve()` function requires a parameter to be passed, even though the original Solidity contract didn't require any at all none. The parameter required is a `*bind.CallOpts` type, which can be used to fine tune the call. If no adjustments to the call are required, pass `nil`. Adjustments to the call include:
+
+- `Pending`: Whether to access pending contract state or the current stable one
+- `GasLimit`: Place a limit on the computing resources the call might consume
+
+So to call the `Retrieve()` function in the Go application:
+
+```go
+value, err := store.Retrieve(nil)
+if err != nil {
+	log.Fatalf("Failed to retrieve value: %v", err)
+}
+fmt.Println("Value: ", value)
+}
+```
+
+The output will be something like:
+
+```terminal
+Value: 56
+```
+
+### Transacting with an Ethereum contract {#transacting-with-contract}
+
+Invoking a method that changes contract state (i.e. transacting) is a bit more involved, as a live transaction needs to be authorized and broadcast into the network. **Go bindings require local signing of transactions and do not delegate this to a remote node.** This is to keep accounts private within dapps, and not shared (by default) between them.
+
+Thus to allow transacting with a contract, your code needs to implement a method that given an input transaction, signs it and returns an authorized output transaction. Since most users have their keys in the [Web3 Secret Storage](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) format, the `bind` package contains a small utility method (`bind.NewTransactor(keyjson, passphrase)`) that can create an authorized transactor from a key file and associated password, without the user needing to implement key signing themselves.
+
+Changing the previous code snippet to update the value stored in the contract:
+
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+	"math/big"
+	"strings"
+
+	"github.com/ethereum/go-ethereum/accounts/abi/bind"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/ethclient"
+)
+
+const key = `json object from keystore`
+
+func main() {
+	// Create an IPC based RPC connection to a remote node and instantiate a contract binding
+	conn, err := ethclient.Dial("/home/go-ethereum/goerli/geth.ipc")
+	if err != nil {
+		log.Fatalf("Failed to connect to the Ethereum client: %v", err)
+	}
+	store, err := NewStorage(common.HexToAddress("0x21e6fc92f93c8a1bb41e2be64b4e1f88a54d3576"), conn)
+	if err != nil {
+		log.Fatalf("Failed to instantiate a Storage contract: %v", err)
+	}
+	// Create an authorized transactor and call the store function
+	auth, err := bind.NewStorageTransactor(strings.NewReader(key), "strong_password")
+	if err != nil {
+		log.Fatalf("Failed to create authorized transactor: %v", err)
+	}
+	// Call the store() function
+	tx, err := store.Store(auth, big.NewInt(420))
+	if err != nil {
+		log.Fatalf("Failed to update value: %v", err)
+	}
+	fmt.Printf("Update pending: 0x%x\n", tx.Hash())
+}
+```
+
+And the output:
+
+```terminal
+Update pending: 0x4f4aaeb29ed48e88dd653a81f0b05d4df64a86c99d4e83b5bfeb0f0006b0e55b
+```
+
+Similar to the method invocations in the previous section which only read contract state, transacting methods also require a mandatory first parameter, a `*bind.TransactOpts` type, which authorizes the transaction and potentially fine tunes it:
+
+- `From`: Address of the account to invoke the method with (mandatory)
+- `Signer`: Method to sign a transaction locally before broadcasting it (mandatory)
+- `Nonce`: Account nonce to use for the transaction ordering (optional)
+- `GasLimit`: Place a limit on the computing resources the call might consume (optional)
+- `GasPrice`: Explicitly set the gas price to run the transaction with (optional)
+- `Value`: Any funds to transfer along with the method call (optional)
+
+The two mandatory fields are automatically set by the `bind` package if the auth options are constructed using `bind.NewTransactor`. The nonce and gas related fields are automatically derived by the binding if they are not set. Unset values are assumed to be zero.
+
+### Pre-configured contract sessions {#preconfigured-sessions}
+
+Reading and state modifying contract-calls require a mandatory first parameter which can authorize and fine tune some of the internal parameters. However, most of the time the same accounts and parameters will be used to issue many transactions, so constructing the call/transact options individually quickly becomes unwieldy.
+
+To avoid this, the generator also creates specialized wrappers that can be pre-configured with tuning and authorization parameters, allowing all the Solidity defined methods to be invoked without needing an extra parameter.
+
+These are named similarly to the original contract type name but suffixed with `Sessions`:
+
+```go
+// Wrap the Storage contract instance into a session
+session := &StorageSession{
+	Contract: store,
+	CallOpts: bind.CallOpts{
+		Pending: true,
+	},
+	TransactOpts: bind.TransactOpts{
+		From:     auth.From,
+		Signer:   auth.Signer,
+		GasLimit: big.NewInt(3141592),
+	},
+}
+// Call the previous methods without the option parameters
+session.Store(big.NewInt(69))
+```
+
+## Bind Solidity directly {#binding-solidity}
+
+In the past, abigen allowed compilation and binding of a Solidity source file directly to a Go package in a single step. This feature has been discontinued from [v1.10.18](https://github.com/ethereum/go-ethereum/releases/tag/v1.10.18) onwards due to maintenance synchronization challenges with the compiler in Geth.
+
+The compilation and binding steps can be joined together into a pipeline, for example:
+
+```sh
+solc Storage.sol --combined-json abi,bin | abigen --pkg main --type storage --out Storage.go --combined-json -
+```
+
+### Project integration (`go generate`) {#project-integration}
+
+The `abigen` command was made in such a way as to integrate easily into existing Go toolchains: instead of having to remember the exact command needed to bind an Ethereum contract into a Go project, `go generate` can handle all the fine details.
+
+Place the binding generation command into a Go source file before the package definition:
+
+```go
+//go:generate abigen --sol Storage.sol --pkg main --out Storage.go
+```
+
+After which whenever the Solidity contract is modified, instead of needing to remember and run the above command, we can simply call `go generate` on the package (or even the entire source tree via `go generate ./...`), and it will correctly generate the new bindings for us.
+
+## Blockchain simulator {#blockchain-simulator}
+
+Being able to deploy and access deployed Ethereum contracts from native Go code is a powerful feature. However, using public testnets as a backend does not lend itself well to _automated unit testing_. Therefore, Geth also implements a _simulated blockchain_ that can be set as a backend to native contracts the same way as a live RPC backend, using the command `backends.NewSimulatedBackend(genesisAccounts)`. The code snippet below shows how this can be used as a backend in a Go application.
+
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+	"math/big"
+
+	"github.com/ethereum/go-ethereum/accounts/abi/bind"
+	"github.com/ethereum/go-ethereum/accounts/abi/bind/backends"
+	"github.com/ethereum/go-ethereum/core"
+	"github.com/ethereum/go-ethereum/crypto"
+)
+
+func main() {
+	// Generate a new random account and a funded simulator
+	key, _ := crypto.GenerateKey()
+	auth := bind.NewKeyedTransactor(key)
+
+	sim := backends.NewSimulatedBackend(core.GenesisAccount{Address: auth.From, Balance: big.NewInt(10000000000)})
+
+	// instantiate contract
+	store, err := NewStorage(common.HexToAddress("0x21e6fc92f93c8a1bb41e2be64b4e1f88a54d3576"), sim)
+	if err != nil {
+		log.Fatalf("Failed to instantiate a Storage contract: %v", err)
+	}
+	// Create an authorized transactor and call the store function
+	auth, err := bind.NewStorageTransactor(strings.NewReader(key), "strong_password")
+	if err != nil {
+		log.Fatalf("Failed to create authorized transactor: %v", err)
+	}
+	// Call the store() function
+	tx, err := store.Store(auth, big.NewInt(420))
+	if err != nil {
+		log.Fatalf("Failed to update value: %v", err)
+	}
+	fmt.Printf("Update pending: 0x%x\n", tx.Hash())
+}
+```
+
+## Summary {#summary}
+
+To make interacting with Ethereum contracts easier for Go developers, Geth provides tools that generate contract bindings automatically. This makes contract functions available in Go native applications.

docs/developers/dapp-developer/native.md

@@ -0,0 +1,196 @@
+---
+title: Go API
+description: Introduction to the Go packages that allow Geth to be used in Go native applications.
+---
+
+Ethereum was originally conceptualized to be the base layer for [Web3](https://ethereum.org/en/web3/), providing the backbone for a new generation of decentralized, permissionless and censorship resistant applications called [dapps](https://ethereum.org/en/glossary/#dapp). The first step towards this vision was the development of clients providing an RPC interface into the peer-to-peer protocols. This allowed users to transact between accounts and interact with smart contracts using command line tools. Geth was one of the original clients to provide this type of gateway to the Ethereum network.
+
+Before long, web-browser-like graphical interfaces (e.g. Mist) were created to extend clients, and client functions were built into websites built using the time-tested HTML/CSS/JS stack. However, to support the most diverse, complex dapps, developers require programmatic access to client functions through an API. This opens up client technologies as re-usable, composable units that can be applied in creative ways by a global community of developers.
+
+To support this, Geth ships official Go packages that can be embedded into third party desktop and server applications. There is also a [mobile API](/docs/developers/dapp-developer/mobile) that can be used to embed Geth into mobile applications.
+
+This page provides a high-level overview of the Go API.
+
+_Note, this guide will assume some familiarity with Go development. It does not cover general topics about Go project layouts, import paths or any other standard methodologies. If you are new to Go, consider reading [Getting Started with Go](https://github.com/golang/go/wiki#getting-started-with-go) first._
+
+## Overview {#overview}
+
+Geth's reusable Go libraries focus on three main usage areas:
+
+- Simplified client side account management
+- Remote node interfacing via different transports
+- Contract interactions through auto-generated bindings
+
+The libraries are updated synchronously with the Geth GitHub repository. The Go libraries can be viewed in full at [Go Packages](https://pkg.go.dev/github.com/ethereum/go-ethereum#section-directories).
+
+Péter Szilágyi (@karalabe) gave a high level overview of the Go libraries in a talk at DevCon2 in Shanghai in 2016. The slides are still a useful resource ([available here](https://ethereum.karalabe.com/talks/2016-devcon.html)) and the talk itself can be viewed by clicking the image below (it is also archived on [IPFS](https://ipfs.io/ipfs/QmQRuKPKWWJAamrMqAp9rytX6Q4NvcXUKkhvu3kuREKqXR)).
+
+[![Peter's Devcon2 talk](/images/docs/devcon2_labelled.webp)](https://www.youtube.com/watch?v=R0Ia1U9Gxjg)
+
+## Go packages {#go-packages}
+
+The `go-ethereum` library is distributed as a collection of standard Go packages straight from go-ethereum's GitHub repository. The packages can be used directly via the official Go toolkit, without needing any third party tools.
+
+The canonical import path for Geth is `github.com/ethereum/go-ethereum`, with all packages residing underneath. Although there are [lots of them](https://pkg.go.dev/github.com/ethereum/go-ethereum/#section-directories) most developers will only care about a limited subset.
+
+All the Geth packages can be downloaded using:
+
+```sh
+$ go get -d github.com/ethereum/go-ethereum/...
+```
+
+More Go API support for dapp developers can be found on the [Go Contract Bindings](/docs/developers/dapp-developer/native-bindings) and [Go Account Management](/docs/developers/dapp-developer/native-accounts) pages.
+
+## Tutorial {#tutorial}
+
+This section includes some basic usage examples for the `ethclient` and `gethclient` packages available as part of the Go API. The `ethclient` package provides a client that implements the full Ethereum JSON-RPC API, whereas `gethclient` offers the Geth-specific API.
+
+### Instantiating a client {#instantiating-a-client}
+
+The client is an instance of the `Client` struct which has associated functions that wrap requests to the Ethereum or Geth RPC API endpoints.
+
+A client is instantiated by passing a raw url or path to an ipc file to the client's `Dial` function. In the following code snippet the path to the ipc file for a local Geth node is provided to `ethclient.Dial()`.
+
+```go
+// create instance of ethclient and assign to cl
+cl, err := ethclient.Dial("/tmp/geth.ipc")
+if err != nil {
+	panic(err)
+}
+_ = cl
+```
+
+### Interacting with the client {#interacting-with-a-client}
+
+The client can now be used to handle requests to the Geth node using the full JSON-RPC API. For example, the function `BlockNumer()` wraps a call to the `eth_blockNumber` endpoint. The function `SendTransaction` wraps a call to `eth_sendTransaction`. The full list of client methods can be found [here](https://pkg.go.dev/github.com/ethereum/go-ethereum/ethclient#Client).
+
+Frequently, the functions take an instance of the `Context` type as their leading argument. This defines context about requests sent from the application such as deadlines, cancellation signals etc. More information on this can be found in the [Go documentation](https://pkg.go.dev/golang.org/x/net/context). An empty context instance can be created using `Context.Background()`.
+
+### Querying client for data {#querying-client-for-data}
+
+A simple starting point is to fetch the chain ID from the client. This e.g. is needed when signing a transaction as is to be seen in the next section.
+
+```go
+chainid, err := cl.ChainID(context.Background())
+if err != nil {
+    return err
+}
+```
+
+Unlike `ChainID`, many functions require arguments other than context. The Go API takes in and returns high-level types which are used in Geth internals as well to simplify programming and remove the need for knowing how data needs to be formatted exactly as per the JSON-RPC API spec. For example to find out the nonce for an account at a given block the address needs to be provided as a `common.Address` type and the block number as a `*big.Int`:
+
+```go
+addr := common.HexToAddress("0xb02A2EdA1b317FBd16760128836B0Ac59B560e9D")
+nonce, err := cl.NonceAt(context.Background(), addr, big.NewInt(14000000))
+```
+
+### Querying past events {#querying-past-events}
+
+Contracts emit events during execution which can be queried from the client. The parameters for the event one is interested in have to be filled out in the `ethereum.FilterQuery` object. This includes which event topics are of interested, from which contracts and during which range of blocks. The example below queries `Transfer` events of all ERC-20 tokens for the last 10 blocks:
+
+```go
+blockNum, err := cl.BlockNumber(context.Background())
+if err != nil {
+    return err
+}
+q := ethereum.FilterQuery{
+    FromBlock: new(big.Int).Sub(blockNum, big.NewInt(10)),
+    ToBlock: blockNum,
+    Topics: [][]common.Hash{common.HexToHash("0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef")},
+}
+logs, err := cl.FilterLogs(context.Background(), q)
+if err != nil {
+    return err
+}
+```
+
+### Sending a transaction {#sending-a-transaction}
+
+Sending a transaction is achieved using the `SendTransaction()` function. `SendTransaction` takes an instance of `context.Context` as its leading argument and a signed transaction as its second argument. The signed transaction must be generated in advance. Building the signed transaction is a multi-stage process that requires first generating a key pair if none exists already, retrieving some chain data and defining sender and recipient
+addresses. Then these data can be collected into a transaction object and signed. The resulting signed transaction can then be passed to `SendTransaction`.
+
+The example below assumes the following key pair has already been generated:
+
+```go
+// SK and ADDR are the secret key and sender address
+SK   = "0xaf5ead4413ff4b78bc94191a2926ae9ccbec86ce099d65aaf469e9eb1a0fa87f"
+ADDR = "0x6177843db3138ae69679A54b95cf345ED759450d"
+```
+
+The secret key and address can be used to send a transaction. In the example below 1 ETH is sent from the address `ADDR` to an arbitrary recipient.
+
+```go
+import (
+	"context"
+	"math/big"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/ethereum/go-ethereum/ethclient"
+	"github.com/ethereum/go-ethereum/params"
+)
+
+// sendTransaction sends a transaction with 1 ETH to a specified address.
+func sendTransaction(cl *ethclient.Client) error {
+	var (
+		sk       = crypto.ToECDSAUnsafe(common.FromHex(SK))
+		to       = common.HexToAddress("0xb02A2EdA1b317FBd16760128836B0Ac59B560e9D")
+		value    = new(big.Int).Mul(big.NewInt(1), big.NewInt(params.Ether))
+		sender   = common.HexToAddress(ADDR)
+		gasLimit = uint64(21000)
+	)
+	// Retrieve the chainid (needed for signer)
+	chainid, err := cl.ChainID(context.Background())
+	if err != nil {
+		return err
+	}
+	// Retrieve the pending nonce
+	nonce, err := cl.PendingNonceAt(context.Background(), sender)
+	if err != nil {
+		return err
+	}
+	// Get suggested gas price
+	tipCap, _ := cl.SuggestGasTipCap(context.Background())
+	feeCap, _ := cl.SuggestGasPrice(context.Background())
+	// Create a new transaction
+	tx := types.NewTx(
+		&types.DynamicFeeTx{
+			ChainID:   chainid,
+			Nonce:     nonce,
+			GasTipCap: tipCap,
+			GasFeeCap: feeCap,
+			Gas:       gasLimit,
+			To:        &to,
+			Value:     value,
+			Data:      nil,
+		})
+	// Sign the transaction using our keys
+	signedTx, _ := types.SignTx(tx, types.NewLondonSigner(chainid), sk)
+	// Send the transaction to our node
+	return cl.SendTransaction(context.Background(), signedTx)
+}
+```
+
+### gethclient {#geth-client}
+
+An instance of `gethclient` can be used in exactly the same way as `ethclient`. However, `gethclient` includes Geth-specific API methods. These additional methods are:
+
+```sh
+CallContract()
+CreatAccessList()
+GCStats()
+GetNodeInfo()
+GetProof()
+MemStats()
+SetHead()
+SubscribePendingTransactions()
+```
+
+_Note that both `ethclient` and `gethclient` have a `CallContract()` function - the difference is that the `gethclient` version includes an `overrides` argument._
+
+Details relating to these endpoints can be found at [pkg.go.dev](https://pkg.go.dev/github.com/ethereum/go-ethereum@v1.10.19/ethclient/gethclient) or the Geth [GitHub](https://github.com/ethereum/go-ethereum/tree/master/ethclient). The code snippets in this tutorial were adapted from a more more in-depth set of examples available on [GitHub](https://github.com/MariusVanDerWijden/web3go).
+
+## Summary {#summary}
+
+There are a wide variety of Go APIs available for dapp developers that abstract away the complexity of interacting with Ethereum using a set of composable, reusable functions provided by Geth.

docs/developers/evm-tracing/basic-traces.md

@@ -0,0 +1,101 @@
+---
+title: Basic traces
+description: Introduction to basic EVM traces
+---
+
+The simplest type of transaction trace that Geth can generate are raw EVM opcode traces. For every VM instruction the transaction executes, a structured log entry is emitted, containing all contextual metadata deemed useful. This includes the _program counter_, _opcode name_, _opcode cost_, _remaining gas_, _execution depth_ and any _occurred error_. The structured logs can optionally also contain the content of the _execution stack_, _execution memory_ and _contract storage_.
+
+The entire output of a raw EVM opcode trace is a JSON object having a few metadata fields: _consumed gas_, _failure status_, _return value_; and a list of _opcode entries_:
+
+```json
+{
+  "gas": 25523,
+  "failed": false,
+  "returnValue": "",
+  "structLogs": []
+}
+```
+
+An example log for a single opcode entry has the following format:
+
+```json
+{
+  "pc": 48,
+  "op": "DIV",
+  "gasCost": 5,
+  "gas": 64532,
+  "depth": 1,
+  "error": null,
+  "stack": [
+    "00000000000000000000000000000000000000000000000000000000ffffffff",
+    "0000000100000000000000000000000000000000000000000000000000000000",
+    "2df07fbaabbe40e3244445af30759352e348ec8bebd4dd75467a9f29ec55d98d"
+  ],
+  "memory": [
+    "0000000000000000000000000000000000000000000000000000000000000000",
+    "0000000000000000000000000000000000000000000000000000000000000000",
+    "0000000000000000000000000000000000000000000000000000000000000060"
+  ],
+  "storage": {}
+}
+```
+
+### Generating basic traces {#generating-basic-traces}
+
+To generate a raw EVM opcode trace, Geth provides a few [RPC API endpoints](/docs/interacting-with-geth/rpc/ns-debug). The most commonly used is [`debug_traceTransaction`](/docs/interacting-with-geth/rpc/ns-debug#debug_tracetransaction).
+
+In its simplest form, `traceTransaction` accepts a transaction hash as its only argument. It then traces the transaction, aggregates all the generated
+data and returns it as a **large** JSON object. A sample invocation from the Geth console would be:
+
+```js
+debug.traceTransaction('0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f');
+```
+
+The same call can also be invoked from outside the node too via HTTP RPC (e.g. using Curl). In this case, the HTTP endpoint must be enabled in Geth using the `--http` command and the `debug` API namespace must be exposed using `--http.api=debug`.
+
+```sh
+$ curl -H "Content-Type: application/json" -d '{"id": 1, "method": "debug_traceTransaction", "params": ["0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f"]}' localhost:8545
+```
+
+To follow along with this tutorial, transaction hashes can be found from a local Geth node (e.g. by attaching a [Javascript console](/docs/interacting-with-geth/javascript-console) and running `eth.getBlock('latest')` then passing a transaction hash from the returned block to `debug.traceTransaction()`) or from a block explorer (for [Mainnet](https://etherscan.io/) or a [testnet](https://goerli.etherscan.io/)).
+
+It is also possible to configure the trace by passing Boolean (true/false) values for four parameters that tweak the verbosity of the trace. By default, the _EVM memory_ and _Return data_ are not reported but the _EVM stack_ and _EVM storage_ are. To report the maximum amount of data:
+
+```sh
+enableMemory: true
+disableStack: false
+disableStorage: false
+enableReturnData: true
+```
+
+An example call, made in the Geth Javascript console, configured to report the maximum amount of data looks as follows:
+
+```js
+debug.traceTransaction('0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f', {
+  enableMemory: true,
+  disableStack: false,
+  disableStorage: false,
+  enableReturnData: true
+});
+```
+
+The above operation was run on the (now-deprecated) Rinkeby network (with a node retaining enough history), resulting in this [trace dump](https://gist.github.com/karalabe/c91f95ac57f5e57f8b950ec65ecc697f).
+
+Alternatively, disabling _EVM Stack_, _EVM Memory_, _Storage_ and _Return data_ (as demonstrated in the Curl request below) results in the following, much shorter, [trace dump](https://gist.github.com/karalabe/d74a7cb33a70f2af75e7824fc772c5b4).
+
+```sh
+$ curl -H "Content-Type: application/json" -d '{"id": 1, "method": "debug_traceTransaction", "params": ["0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f", {"disableStack": true, "disableStorage": true}]}' localhost:8545
+```
+
+### Limits of basic traces {#list-of-basic-traces}
+
+Although the raw opcode traces generated above are useful, having an individual log entry for every single opcode is too low level for most use cases,
+and will require developers to create additional tools to post-process the traces. Additionally, a full opcode trace can easily go into the hundreds of megabytes, making them very resource intensive to get out of the node and process externally.
+
+To avoid those issues, Geth supports running custom JavaScript tracers _within_ the Ethereum node, which have full access to the EVM stack, memory and contract storage. This means developers only have to gather the data they actually need, and do any processing at the source.
+
+## Summary {#summary}
+
+This page described how to do basic traces in Geth. Basic traces are very low level and can generate lots of data that might not all be useful. Therefore, it is also possible to use a set of built-in tracers or write custom ones in Javascript or Go.
+
+Read more about [built-in](/docs/developers/evm-tracing/built-in-tracers) and [custom](/docs/developers/evm-tracing/custom-tracer) traces.

docs/developers/evm-tracing/built-in-tracers.md

@@ -0,0 +1,492 @@
+---
+title: Built-in tracers
+description: Explanation of the tracers that come bundled in Geth as part of the tracing API.
+---
+
+Geth comes bundled with a choice of tracers that can be invoked via the [tracing API](/docs/interacting-with-geth/rpc/ns-debug). Some of these built-in tracers are implemented natively in Go, and others in Javascript. The default tracer is the opcode logger (otherwise known as struct logger) which is the default tracer for all the methods. Other tracers have to be specified by passing their name to the `tracer` parameter in the API call.
+
+## Struct/opcode logger {#struct-opcode-logger}
+
+The struct logger (aka 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(<txhash>)`. 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.
+
+It is also possible to configure the trace by passing Boolean (true/false) values for four parameters that tweak the verbosity of the trace. By default, the _EVM memory_ and _Return data_ are not reported but the _EVM stack_ and _EVM storage_ are. To report the maximum amount of data:
+
+```sh
+enableMemory: true
+disableStack: false
+disableStorage: false
+enableReturnData: true
+```
+
+An example call:
+
+```js
+debug.traceTransaction('0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f', {
+  enableMemory: true,
+  disableStack: false,
+  disableStorage: false,
+  enableReturnData: true
+});
+```
+
+Return:
+
+```terminal
+{
+   "gas":25523,
+   "failed":false,
+   "returnValue":"",
+   "structLogs":[
+      {
+         "pc":0,
+         "op":"PUSH1",
+         "gas":64580,
+         "gasCost":3,
+         "depth":1,
+         "error":null,
+         "stack":[
+
+         ],
+         "memory":null,
+         "storage":{
+
+         }
+      },
+      {
+         "pc":2,
+         "op":"PUSH1",
+         "gas":64577,
+         "gasCost":3,
+         "depth":1,
+         "error":null,
+         "stack":[
+            "0000000000000000000000000000000000000000000000000000000000000060"
+         ],
+         "memory":null,
+         "storage":{
+
+         }
+      },
+
+      ...
+
+```
+
+## Native tracers {#native-tracers}
+
+The following tracers are implement in Go. This means they are much more performant than other tracers that are written in Javascript. The tracers are selected by passing their name to the `tracer` parameter when invoking a tracing API method, e.g. `debug.traceTransaction(<txhash>, { tracer: 'callTracer' })`.
+
+### 4byteTracer {#4byte-tracer}
+
+Solidity contract functions are
+[addressed](https://docs.soliditylang.org/en/develop/abi-spec.html#function-selector) using 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. For example:
+
+Example call:
+
+```sh
+debug.traceTransaction( "0x214e597e35da083692f5386141e69f47e973b2c56e7a8073b1ea08fd7571e9de", {tracer: "4byteTracer"})
+```
+
+Return:
+
+```terminal
+{
+  "0x27dc297e-128": 1,
+  "0x38cc4831-0": 2,
+  "0x524f3889-96": 1,
+  "0xadf59f99-288": 1,
+  "0xc281d19e-0": 1
+}
+```
+
+### callTracer {#call-tracer}
+
+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                        |
+| revertReason | string      | Solidity revert reason, if any       |
+| calls        | []callframe | list of sub-calls                    |
+
+Example Call:
+
+```sh
+> debug.traceTransaction("0x44bed3dc0f584b2a2ab32f5e2948abaaca13917eeae7ae3b959de3371a6e9a95", {tracer: 'callTracer'})
+```
+
+Return:
+
+```terminal
+{
+  calls: [{
+      from: "0xc8ba32cab1757528daf49033e3673fae77dcf05d",
+      gas: "0x18461",
+      gasUsed: "0x60",
+      input: "0x000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a6",
+      output: "0x557904b74478f8810cc02198544a030d1829bb491e14fe1dd0354e933c5e87bd",
+      to: "0x0000000000000000000000000000000000000002",
+      type: "STATICCALL"
+  }, {
+      from: "0xc8ba32cab1757528daf49033e3673fae77dcf05d",
+      gas: "0x181db",
+      gasUsed: "0x48",
+      input: "0x557904b74478f8810cc02198544a030d1829bb491e14fe1dd0354e933c5e87bd",
+      output: "0x5fb393023b12544491a5b8fb057943b4ebf5b1401e88e44a7800000000000000",
+      to: "0x0000000000000000000000000000000000000002",
+      type: "STATICCALL"
+  }],
+  from: "0x35a9f94af726f07b5162df7e828cc9dc8439e7d0",
+  gas: "0x1a310",
+  gasUsed: "0xfcb6",
+  input: "0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000",
+  to: "0xc8ba32cab1757528daf49033e3673fae77dcf05d",
+  type: "CALL",
+  value: "0x0"
+}
+```
+
+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
+
+- In case the top level frame reverts, its `revertReason` field will contain the parsed reason of revert as returned by the Solidity contract
+
+#### Config
+
+`callTracer` accepts two options:
+
+- `onlyTopCall: true` instructs the tracer to only process the main (top-level) call and none of the sub-calls. This avoids extra processing for each call frame if only the top-level call info are required.
+- `withLog: true` instructs the tracer to also collect the logs emitted during each call.
+
+Example invokation with the `onlyTopCall` flag:
+
+```terminal
+> debug.traceTransaction('0xc73e70f6d60e63a71dabf90b9983f2cdd56b0cb7bcf1a205f638d630a95bba73', { tracer: 'callTracer', tracerConfig: { onlyTopCall: true } })
+```
+
+### prestateTracer {#prestate-tracer}
+
+The prestate tracer has two modes: `prestate` and `diff`. The `prestate` mode returns the accounts necessary to execute a given transaction. `diff` mode returns the differences between the transaction's pre and post-state (i.e. what changed because the transaction happened). The `prestateTracer` defaults to `prestate` mode. It reexecutes the given transaction 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 |
+
+To run this tracer in `diff` mode, pass `tracerConfig: {diffMode: true}` in the APi call.
+
+Example:
+
+```js
+debug.traceCall(
+  {
+    from: '0x35a9f94af726f07b5162df7e828cc9dc8439e7d0',
+    to: '0xc8ba32cab1757528daf49033e3673fae77dcf05d',
+    data: '0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000'
+  },
+  'latest',
+  { tracer: 'prestateTracer' }
+);
+```
+
+Return:
+
+```terminal
+{
+  0x0000000000000000000000000000000000000002: {
+    balance: "0x0"
+  },
+  0x008b3b2f992c0e14edaa6e2c662bec549caa8df1: {
+    balance: "0x2638035a26d133809"
+  },
+  0x35a9f94af726f07b5162df7e828cc9dc8439e7d0: {
+    balance: "0x7a48734599f7284",
+    nonce: 1133
+  },
+  0xc8ba32cab1757528daf49033e3673fae77dcf05d: {
+    balance: "0x0",
+    code: "0x608060405234801561001057600080fd5b50600436106100885760003560e01c8063a9c2d...
+    nonce: 1,
+    storage: {
+      0x0000000000000000000000000000000000000000000000000000000000000000: "0x000000000000000000000000000000000000000000000000000000000024aea6",
+      0x59fb7853eb21f604d010b94c123acbeae621f09ce15ee5d7616485b1e78a72e9: "0x00000000000000c42b56a52aedf18667c8ae258a0280a8912641c80c48cd9548",
+      0x8d8ebb65ec00cb973d4fe086a607728fd1b9de14aa48208381eed9592f0dee9a: "0x00000000000000784ae4881e40b1f5ebb4437905fbb8a5914454123b0293b35f",
+      0xff896b09014882056009dedb136458f017fcef9a4729467d0d00b4fd413fb1f1: "0x000000000000000e78ac39cb1c20e9edc753623b153705d0ccc487e31f9d6749"
+    }
+  }
+}
+```
+
+Return (same call with `{diffMode: True}`):
+
+```terminal
+{
+  post: {
+    0x35a9f94af726f07b5162df7e828cc9dc8439e7d0: {
+      nonce: 1135
+    }
+  },
+  pre: {
+    0x35a9f94af726f07b5162df7e828cc9dc8439e7d0: {
+      balance: "0x7a48429e177130a",
+      nonce: 1134
+    }
+  }
+}
+```
+
+### noopTracer {#noop-tracer}
+
+This tracer is noop. It returns an empty object and is only meant for testing the setup.
+
+## Javascript tracers {#js-tracers}
+
+There are also a set of tracers written in Javascript. These are less performant than the Go native tracers because of overheads associated with interpreting the Javascript in Geth's Go environment.
+
+### bigram {#bigram}
+
+`bigramTracer` counts the opcode bigrams, i.e. how many times 2 opcodes were executed one after the other.
+
+Example:
+
+```js
+debug.traceCall(
+  {
+    from: '0x35a9f94af726f07b5162df7e828cc9dc8439e7d0',
+    to: '0xc8ba32cab1757528daf49033e3673fae77dcf05d',
+    data: '0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000'
+  },
+  'latest',
+  { tracer: 'bigramTracer' }
+);
+```
+
+Returns:
+
+```terminal
+{
+  ADD-ADD: 1,
+  ADD-AND: 2,
+  ADD-CALLDATALOAD: 1,
+  ADD-DUP1: 2,
+  ADD-DUP2: 2,
+  ADD-GT: 1,
+  ADD-MLOAD: 1,
+  ADD-MSTORE: 4,
+  ADD-PUSH1: 1,
+  ADD-PUSH2: 4,
+  ADD-SLT: 1,
+  ADD-SWAP1: 10,
+  ADD-SWAP2: 1,
+  ADD-SWAP3: 1,
+  ADD-SWAP4: 3,
+  ADD-SWAP5: 1,
+  AND-DUP3: 2,
+  AND-ISZERO: 4,
+  ...
+  }
+
+```
+
+### evmdis {#evmdis}
+
+`evmdisTracer` returns sufficient information from a trace to perform [evmdis](https://github.com/Arachnid/evmdis)-style disassembly
+
+Example:
+
+```js
+> debug.traceCall({from: "0x35a9f94af726f07b5162df7e828cc9dc8439e7d0", to: "0xc8ba32cab1757528daf49033e3673fae77dcf05d", data: "0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000"}, 'latest', {tracer: 'evmdisTracer'})
+```
+
+Returns:
+
+```terminal
+[{
+    depth: 1,
+    len: 2,
+    op: 96,
+    result: ["80"]
+}, {
+    depth: 1,
+    len: 2,
+    op: 96,
+    result: ["40"]
+}, {
+    depth: 1,
+    op: 82,
+    result: []
+}, {
+    depth: 1,
+    op: 52,
+    result: ["0"]
+}, {
+    depth: 1,
+    op: 128,
+    result: ["0", "0"]
+}, {
+    depth: 1,
+    op: 21,
+    result: ["1"]
+}, {
+    depth: 1,
+    len: 3,
+    op: 97,
+    result: ["10"]
+}, {
+    depth: 1,
+    op: 87,
+    result: []
+}, {
+    depth: 1,
+    op: 91,
+    pc: 16,
+    result: []
+},
+...
+```
+
+### opcount {#opcount}
+
+`opcountTracer` counts the total number of opcodes executed and simply returns the number.
+
+Example:
+
+```js
+debug.traceCall(
+  {
+    from: '0x35a9f94af726f07b5162df7e828cc9dc8439e7d0',
+    to: '0xc8ba32cab1757528daf49033e3673fae77dcf05d',
+    data: '0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000'
+  },
+  'latest',
+  { tracer: 'opcountTracer' }
+);
+```
+
+Returns:
+
+```terminal
+1384
+```
+
+### trigram {#trigram}
+
+`trigramTracer` counts the opcode trigrams. Trigrams are the possible combinations of three opcodes this tracer reports how many times each combination is seen during execution.
+
+Example:
+
+```js
+debug.traceCall(
+  {
+    from: '0x35a9f94af726f07b5162df7e828cc9dc8439e7d0',
+    to: '0xc8ba32cab1757528daf49033e3673fae77dcf05d',
+    data: '0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000'
+  },
+  'latest',
+  { tracer: 'trigramTracer' }
+);
+```
+
+Returns:
+
+```terminal
+{
+  --PUSH1: 1,
+  -PUSH1-MSTORE: 1,
+  ADD-ADD-GT: 1,
+  ADD-AND-DUP3: 2,
+  ADD-CALLDATALOAD-PUSH8: 1,
+  ADD-DUP1-PUSH1: 2,
+  ADD-DUP2-ADD: 1,
+  ADD-DUP2-MSTORE: 1,
+  ADD-GT-ISZERO: 1,
+  ADD-MLOAD-DUP6: 1,
+  ADD-MSTORE-ADD: 1,
+  ADD-MSTORE-PUSH1: 2,
+  ADD-MSTORE-PUSH32: 1,
+  ADD-PUSH1-KECCAK256: 1,
+  ADD-PUSH2-JUMP: 2,
+  ADD-PUSH2-JUMPI: 1,
+  ADD-PUSH2-SWAP2: 1,
+  ADD-SLT-PUSH2: 1,
+...
+}
+```
+
+### unigram {#unigram}
+
+`unigramTracer` counts the frequency of occurrance of each opcode.
+
+Example:
+
+```js
+> debug.traceCall({from: "0x35a9f94af726f07b5162df7e828cc9dc8439e7d0", to: "0xc8ba32cab1757528daf49033e3673fae77dcf05d", data: "0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000"}, 'latest', {tracer: 'unigramTracer'})
+```
+
+Returns:
+
+```terminal
+{
+  ADD: 36,
+  AND: 23,
+  BYTE: 4,
+  CALLDATACOPY: 1,
+  CALLDATALOAD: 6,
+  CALLDATASIZE: 2,
+  CALLVALUE: 1,
+  DIV: 9,
+  DUP1: 29,
+  DUP10: 2,
+  DUP11: 1,
+  DUP12: 3,
+  DUP13: 2,
+  ...
+  }
+```
+
+## State overrides {#state-overrides}
+
+It is possible to give temporary state modifications to Geth in order to simulate the effects of `eth_call`. For example, some new byetcode could be deployed to some address _temporarily just for the duration of the execution_ and then a transaction interacting with that address canm be traced. This can be used for scenario testing or determining the outcome of some hypothetical transaction before executing for real.
+
+To do this, the tracer is written as normal, but the parameter `stateOverrides` is passed an address and some bytecode.
+
+```js
+var code = //contract bytecode
+var tracer = //tracer name
+debug.traceCall({from: , to: , input: }, 'latest', {stateOverrides: {'0x...': {code: code}}, tracer: tracer})
+```
+
+## Summary {#summary}
+
+This page showed how to use the tracers that come bundled with Geth. There are a set written in Go and a set written in Javascript. They are invoked by passing their names when calling an API method. State overrides can be used in combination with tracers to examine precisely what the EVM will do in some hypothetical scenarios.

docs/developers/evm-tracing/custom-tracer.md

@@ -0,0 +1,273 @@
+---
+title: Custom EVM tracer
+description: Introduction to writing custom tracers for Geth
+---
+
+In addition to the default opcode tracer and the built-in tracers, Geth offers the possibility to write custom code that hook to events in the EVM to process and return the data in a consumable format. Custom tracers can be written either in Javascript or Go. JS tracers are good for quick prototyping and experimentation as well as for less intensive applications. Go tracers are performant but require the tracer to be compiled together with the Geth source code.
+
+## Custom Go tracing
+
+Custom tracers can also be made more performant by writing them in Go. The gain in performance mostly comes from the fact that Geth doesn't need to interpret JS code and can execute native functions. Geth comes with several built-in [native tracers](https://github.com/ethereum/go-ethereum/tree/master/eth/tracers/native) which can serve as examples. Please note that unlike JS tracers, Go tracing scripts cannot be simply passed as an argument to the API. They will need to be added to and compiled with the rest of the Geth source code.
+
+In this section a simple native tracer that counts the number of opcodes will be covered. First follow the instructions to [clone and build](/docs/getting-started/installing-geth) Geth from source code. Next save the following snippet as a `.go` file and add it to `eth/tracers/native`:
+
+```go
+package native
+
+import (
+    "encoding/json"
+    "math/big"
+    "sync/atomic"
+    "time"
+
+    "github.com/ethereum/go-ethereum/common"
+    "github.com/ethereum/go-ethereum/core/vm"
+    "github.com/ethereum/go-ethereum/eth/tracers"
+)
+
+func init() {
+    // This is how Geth will become aware of the tracer and register it under a given name
+    register("opcounter", newOpcounter)
+}
+
+type opcounter struct {
+    env       *vm.EVM
+    counts    map[string]int // Store opcode counts
+    interrupt uint32         // Atomic flag to signal execution interruption
+    reason    error          // Textual reason for the interruption
+}
+
+func newOpcounter(ctx *tracers.Context, cfg json.RawMessage) tracers.Tracer {
+    return &opcounter{counts: make(map[string]int)}
+}
+
+// CaptureStart implements the EVMLogger interface to initialize the tracing operation.
+func (t *opcounter) CaptureStart(env *vm.EVM, from common.Address, to common.Address, create bool, input []byte, gas uint64, value *big.Int) {
+        t.env = env
+}
+
+// CaptureState implements the EVMLogger interface to trace a single step of VM execution.
+func (t *opcounter) CaptureState(pc uint64, op vm.OpCode, gas, cost uint64, scope *vm.ScopeContext, rData []byte, depth int, err error) {
+    // Skip if tracing was interrupted
+    if atomic.LoadUint32(&t.interrupt) > 0 {
+        t.env.Cancel()
+        return
+    }
+
+    name := op.String()
+    if _, ok := t.counts[name]; !ok {
+        t.counts[name] = 0
+    }
+    t.counts[name]++
+}
+
+// CaptureEnter is called when EVM enters a new scope (via call, create or selfdestruct).
+func (t *opcounter) CaptureEnter(op vm.OpCode, from common.Address, to common.Address, input []byte, gas uint64, value *big.Int) {}
+
+// CaptureExit is called when EVM exits a scope, even if the scope didn't
+// execute any code.
+func (t *opcounter) CaptureExit(output []byte, gasUsed uint64, err error) {}
+
+// CaptureFault implements the EVMLogger interface to trace an execution fault.
+func (t *opcounter) CaptureFault(pc uint64, op vm.OpCode, gas, cost uint64, scope *vm.ScopeContext, depth int, err error) {}
+
+// CaptureEnd is called after the call finishes to finalize the tracing.
+func (t *opcounter) CaptureEnd(output []byte, gasUsed uint64, _ time.Duration, err error) {}
+
+func (*opcounter) CaptureTxStart(gasLimit uint64) {}
+
+func (*opcounter) CaptureTxEnd(restGas uint64) {}
+
+// GetResult returns the json-encoded nested list of call traces, and any
+// error arising from the encoding or forceful termination (via `Stop`).
+func (t *opcounter) GetResult() (json.RawMessage, error) {
+    res, err := json.Marshal(t.counts)
+    if err != nil {
+        return nil, err
+    }
+    return res, t.reason
+}
+
+// Stop terminates execution of the tracer at the first opportune moment.
+func (t *opcounter) Stop(err error) {
+    t.reason = err
+    atomic.StoreUint32(&t.interrupt, 1)
+}
+```
+
+Every method of the [EVMLogger interface](https://pkg.go.dev/github.com/ethereum/go-ethereum/core/vm#EVMLogger) needs to be implemented (even if empty). Key parts to notice are the `init()` function which registers the tracer in Geth, the `CaptureState` hook where the opcode counts are incremented and `GetResult` where the result is serialized and delivered. Note that the constructor takes in a `cfg json.RawMessage`. This will be filled with a JSON object that user provides to the tracer to pass in optional config fields.
+
+To test out this tracer the source is first compiled with `make geth`. Then in the console it can be invoked through the usual API methods by passing in the name it was registered under:
+
+```sh
+> debug.traceTransaction('0x7ae446a7897c056023a8104d254237a8d97783a92900a7b0f7db668a9432f384', { tracer: 'opcounter' })
+{
+    ADD: 4,
+    AND: 3,
+    CALLDATALOAD: 2,
+    ...
+}
+```
+
+## Custom Javascript tracing
+
+Transaction traces include the complete status of the EVM at every point during the transaction execution, which can be a very large amount of data. Often, users are only interested in a small subset of that data. Javascript trace filters are available to isolate the useful information.
+
+Specifying the `tracer` option in one of the tracing methods (see list in [reference](/docs/interacting-with-geth/rpc/ns-debug)) enables JavaScript-based tracing. In this mode, `tracer` is interpreted as a JavaScript expression that is expected to evaluate to an object which must expose the `result` and `fault` methods. There exist 4 additional methods, namely: `setup`, `step`, `enter`, and `exit`. `enter` and `exit` must be present or omitted together.
+
+### Setup
+
+`setup` is invoked once, in the beginning when the tracer is being constructed by Geth for a given transaction. It takes in one argument `config`. `config` is tracer-specific and allows users to pass in options to the tracer. `config` is to be JSON-decoded for usage and its default value is `"{}"`.
+
+The `config` in the following example is the `onlyTopCall` option available in the `callTracer`:
+
+```js
+debug.traceTransaction('<txhash>, { tracer: 'callTracer', tracerConfig: { onlyTopCall: true } })
+```
+
+The config in the following example is the `diffMode` option available in the `prestateTracer`:
+
+```js
+debug.traceTransaction('<txhash>, { tracer: 'prestateTracer': tracerConfig: { diffMode: true } })
+```
+
+### Step
+
+`step` is a function that takes two arguments, `log` and `db`, and is called for each step of the EVM, or when an error occurs, as the specified transaction is traced.
+
+`log` has the following fields:
+
+- `op`: Object, an OpCode object representing the current opcode
+- `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
+
+and the following methods:
+
+- `getPC()` - returns a Number with the current program counter
+- `getGas()` - returns a Number with the amount of gas remaining
+- `getCost()` - returns the cost of the opcode as a Number
+- `getDepth()` - returns the execution depth as a Number
+- `getRefund()` - returns the amount to be refunded as a Number
+- `getError()` - returns information about the error if one occured, otherwise returns `undefined`
+
+If error is non-empty, all other fields should be ignored.
+
+For efficiency, the same `log` object is reused on each execution step, updated with current values; make sure to copy values you want to preserve beyond the current call. For instance, this step function will not work:
+
+```js
+function(log) {
+  this.logs.append(log);
+}
+```
+
+But this step function will:
+
+```js
+function(log) {
+  this.logs.append({gas: log.getGas(), pc: log.getPC(), ...});
+}
+```
+
+`log.op` has the following methods:
+
+- `isPush()` - returns true if the opcode is a PUSHn
+- `toString()` - returns the string representation of the opcode
+- `toNumber()` - returns the opcode's number
+
+`log.memory` has the following methods:
+
+- `slice(start, stop)` - returns the specified segment of memory as a byte slice
+- `getUint(offset)` - returns the 32 bytes at the given offset
+- `length()` - returns the memory size
+
+`log.stack` has the following methods:
+
+- `peek(idx)` - returns the idx-th element from the top of the stack (0 is the topmost element) as a big.Int
+- `length()` - returns the number of elements in the stack
+
+`log.contract` has the following methods:
+
+- `getCaller()` - returns the address of the caller
+- `getAddress()` - returns the address of the current contract
+- `getValue()` - returns the amount of value sent from caller to contract as a big.Int
+- `getInput()` - returns the input data passed to the contract
+
+`db` has the following methods:
+
+- `getBalance(address)` - returns a `big.Int` with the specified account's balance
+- `getNonce(address)` - returns a Number with the specified account's nonce
+- `getCode(address)` - returns a byte slice with the code for the specified account
+- `getState(address, hash)` - returns the state value for the specified account and the specified hash
+- `exists(address)` - returns true if the specified address exists
+
+If the step function throws an exception or executes an illegal operation at any point, it will not be called on any further VM steps, and the error will be returned to the caller.
+
+### Result
+
+`result` is a function that takes two arguments `ctx` and `db`, and is expected to return a JSON-serializable value to return to the RPC caller.
+
+`ctx` is the context in which the transaction is executing and has the following fields:
+
+- `type` - String, one of the two values `CALL` and `CREATE`
+- `from` - Address, sender of the transaction
+- `to` - Address, target of the transaction
+- `input` - Buffer, input transaction data
+- `gas` - Number, gas budget of the transaction
+- `gasUsed` - Number, amount of gas used in executing the transaction (excludes txdata costs)
+- `gasPrice` - Number, gas price configured in the transaction being executed
+- `intrinsicGas` - Number, intrinsic gas for the transaction being executed
+- `value` - big.Int, amount to be transferred in wei
+- `block` - Number, block number
+- `output` - Buffer, value returned from EVM
+- `time` - String, execution runtime
+
+And these fields are only available for tracing mined transactions (i.e. not available when doing `debug_traceCall`):
+
+- `blockHash` - Buffer, hash of the block that holds the transaction being executed
+- `txIndex` - Number, index of the transaction being executed in the block
+- `txHash` - Buffer, hash of the transaction being executed
+
+### Fault
+
+`fault` is a function that takes two arguments, `log` and `db`, just like `step` and is invoked when an error happens during the execution of an opcode which wasn't reported in `step`. The method `log.getError()` has information about the error.
+
+### Enter & Exit
+
+`enter` and `exit` are respectively invoked on stepping in and out of an internal call. More specifically they are invoked on the `CALL` variants, `CREATE` variants and also for the transfer implied by a `SELFDESTRUCT`.
+
+`enter` takes a `callFrame` object as argument which has the following methods:
+
+- `getType()` - returns a string which has the type of the call frame
+- `getFrom()` - returns the address of the call frame sender
+- `getTo()` - returns the address of the call frame target
+- `getInput()` - returns the input as a buffer
+- `getGas()` - returns a Number which has the amount of gas provided for the frame
+- `getValue()` - returns a `big.Int` with the amount to be transferred only if available, otherwise `undefined`
+
+`exit` takes in a `frameResult` object which has the following methods:
+
+- `getGasUsed()` - returns amount of gas used throughout the frame as a Number
+- `getOutput()` - returns the output as a buffer
+  ` -getError()` - returns an error if one occured during execution and `undefined` otherwise
+
+### Usage
+
+Note that several values are Golang big.Int objects, not JavaScript numbers or JS bigints. As such, they have the same interface as described in the godocs. Their default serialization to JSON is as a Javascript number; to serialize large numbers accurately call `.String()` on them. For convenience, `big.NewInt(x)` is provided, and will convert a uint to a Go BigInt.
+
+Usage example, returns the top element of the stack at each CALL opcode only:
+
+```js
+debug.traceTransaction(txhash, {
+  tracer:
+    '{data: [], fault: function(log) {}, step: function(log) { if(log.op.toString() == "CALL") this.data.push(log.stack.peek(0)); }, result: function() { return this.data; }}'
+});
+```
+
+## Other traces
+
+This tutorial has focused on `debug_traceTransaction()` which reports information about individual transactions. There are also RPC endpoints that provide different information, including tracing the EVM execution within a block, between two blocks, for specific `eth_call`s or rejected blocks. The full list of trace functions can be explored in the [reference documentation](/docs/interacting-with-geth/rpc/ns-debug).
+
+## Summary
+
+This page described how to write custom tracers for Geth. Custom tracers can be written in Javascript or Go.

docs/developers/evm-tracing/index.md

@@ -0,0 +1,68 @@
+---
+title: EVM Tracing
+description: Introduction to tracing EVM transactions using Geth
+---
+
+Tracing allows users to examine precisely what was executed by the EVM during some specific transaction or set of transactions. There are two different types of [transactions](https://ethereum.org/en/developers/docs/transactions) in Ethereum: value transfers and contract executions. A value transfer just moves ETH from one account to another. A contract interaction executes some code stored at a contract address which can include altering stored data and transacting multiple times with other contracts and externally-owned accounts. A contract execution transaction can therefore be a complicated web of interactions that can be difficult to unpick. The transaction receipt contains a status code that shows whether the transaction succeeded or failed, but more detailed information is not readily available, meaning it is very difficult to know what a contract execution actually did, what data was modified and which addresses were touched. This is the problem that EVM tracing solves. Geth traces transactions by re-running them locally and collecting data about precisely what was executed by the EVM.
+
+Also see this [Devcon 2022 talk](https://www.youtube.com/watch?v=b8RdmGsilfU) on tracing in Geth.
+
+## State availability {#state-availability}
+
+In its simplest form, tracing a transaction entails requesting the Ethereum node to reexecute the desired transaction with varying degrees of data collection and have it return an aggregated summary. In order for a Geth node to reexecute a transaction, all historical state accessed by the transaction must be available. This includes:
+
+- Balance, nonce, bytecode and storage of both the recipient as well as all
+  internally invoked contracts.
+- Block metadata referenced during execution of both the outer as well as all
+  internally created transactions.
+- Intermediate state generated by all preceding transactions contained in the
+  same block as the one being traced.
+
+This means there are limits on the transactions that can be traced imposed by the synchronization and pruning configuration of a node:
+
+- An **archive** node retains **all historical data** back to genesis. It can therefore trace arbitrary transactions at any point in the history of the chain. Tracing a single transaction requires reexecuting all preceding transactions in the same block.
+
+- A **node synced from genesis** node only retains the most recent 128 block states in memory. Older states are represented by a sequence of occasional checkpoints that intermediate states can be regenerated from. This means that states within the most recent 128 blocks are immediately available, older states have to be regenerated from snapshots "on-the-fly". If the distance between the requested transaction and the most recent checkpoint is large, rebuilding the state can take a long time. Tracing a single transaction requires reexecuting all preceding transactions in the same block **and** all preceding blocks until the previous stored snapshot.
+
+- A **snap synced** node holds the most recent 128 blocks in memory, so transactions in that range are always accessible. However, snap-sync only starts processing from a relatively recent block (as opposed to genesis for a full node). Between the initial sync block and the 128 most recent blocks, the node stores occasional checkpoints that can be used to rebuild the state on-the-fly. This means transactions can be traced back as far as the block that was used for the initial sync. Tracing a single transaction requires reexecuting all preceding transactions in the same block, **and** all preceding blocks until the previous stored snapshot.
+
+- A **light synced** node retrieving data **on demand** can in theory trace transactions for which all required historical state is readily available in the network. This is because the data required to generate the trace is requested from an les-serving full node. In practice, data availability **cannot** be reasonably assumed.
+
+![state pruning options](/images/docs/state-pruning.png)
+
+_This image shows the state stored by each sync-mode - red indicates stored state. The full width of each line represents origin to present head_
+
+More detailed information about syncing is available on the [sync modes page](/docs/fundamentals/sync-modes).
+
+When a trace of a specific transaction is executed, the state is prepared by fetching the state of the parent block from the database. If it is not available, Geth will crawl backwards in time to find the next available state but only up to a limit defined in the `reexec` parameter which defaults to 128 blocks. If no state is available within the `reexec` window then the trace fails with `Error: required historical state unavailable` and the `reexec` parameter must be increased. If a valid state _is_ found in the `reexec` window, then Geth sequentially re-executes the transcations in each block between the last available state and the target block. The greater the value of `reexec` the longer the tracing will take because more blocks have to be re-executed to regenerate the target state.
+
+The `debug_getAccessibleStates` endpoint is a useful tool for estimating a suitable value for `reexec`. Passing the number of the block that contains the target transaction and a search distance to this endpoint will return the number of blocks behind the current head where the most recent available state exists. This value can be passed to the tracer as `re-exec`.
+
+It is also possible to force Geth to store the state for specific sequences of block by stopping Geth, running again with `--gcmode archive` for some period - this prevents state pruning for blocks that arrive while Geth is running with `--gcmode archive`.
+
+_There are exceptions to the above rules when running batch traces of entire blocks or chain segments. Those will be detailed later._
+
+## Types of trace {#types-of-trace}
+
+### Basic traces {#basic-traces}
+
+The simplest type of transaction trace that Geth can generate are raw EVM opcode traces. For every EVM instruction the transaction executes, a structured log entry is emitted, containing all contextual metadata deemed useful. This includes the _program counter_, _opcode name_, _opcode cost_, _remaining gas_, _execution depth_ and any _occurred error_. The structured logs can optionally also contain the content of the _execution stack_, _execution memory_ and _contract storage_.
+
+Read more about Geth's basic traces on the [basic traces page](/docs/developers/evm-tracing/basic-traces).
+
+### Built-in tracers {#built-in-tracers}
+
+The tracing API accepts an optional `tracer` parameter that defines how the data returned to the API call should be processed. If this parameter is ommitted the default tracer is used. The default is the struct (or 'opcode') logger. These raw opcode traces are sometimes useful, but the returned data is very low level and can be too extensive and awkward to read for many use-cases. A full opcode trace can easily go into the hundreds of megabytes, making them very resource intensive to get out of the node and process externally. For these reasons, there are a set of non-default built-in tracers that can be named in the API call to return different data from the method. Under the hood, these tracers are Go or Javascript
+functions that do some specific preprocessing on the trace data before it is returned.
+
+More information about Geth's built-in tracers is available on the [built-in tracers](/docs/developers/evm-tracing/built-in-tracers) page.
+
+### Custom tracers {#custom-tracers}
+
+In addition to built-in tracers, it is possible to provide custom code that hooks to events in the EVM to process and return data in a consumable format. Custom tracers can be written either in Javascript or Go. JS tracers are good for quick prototyping and experimentation as well as for less intensive applications. Go tracers are performant but require the tracer to be compiled together with the Geth source code. This means developers only have to gather the data they actually need, and do any processing at the source.
+
+More information about custom tracers is available on the [custom tracers](/docs/developers/evm-tracing/custom-tracer) page.
+
+## Summary {#summary}
+
+This page gave an introduction to the concept of tracing and explained issues around state availability. More detailed information on Geth's built-in and custom tracers can be found on their dedicated pages.

docs/developers/evm-tracing/javascript-tutorial.md

@@ -0,0 +1,300 @@
+---
+title: Tutorial for Javascript tracing
+description: Javascript tracing tutorial
+---
+
+Geth supports tracing via [custom Javascript tracers](/docs/developers/evm-tracing/custom-tracer#custom-javascript-tracing). This document provides a tutorial with examples on how to achieve this.
+
+### A simple filter
+
+Filters are Javascript functions that select information from the trace to persist and discard based on some conditions. The following Javascript function returns only the sequence of opcodes executed by the transaction as a comma-separated list. The function could be written directly in the Javascript console, but it is cleaner to write it in a separate re-usable file and load it into the console.
+
+1. Create a file, `filterTrace_1.js`, with this content:
+
+```js
+tracer = function (tx) {
+  return debug.traceTransaction(tx, {
+    tracer:
+      '{' +
+      'retVal: [],' +
+      'step: function(log,db) {this.retVal.push(log.getPC() + ":" + log.op.toString())},' +
+      'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' +
+      'result: function(ctx,db) {return this.retVal}' +
+      '}'
+  }); // return debug.traceTransaction ...
+}; // tracer = function ...
+```
+
+1. Run the [JavaScript console](/docs/interacting-with-geth/javascript-console).
+2. Get the hash of a recent transaction from a node or block explorer.
+
+3. Run this command to run the script:
+
+   ```js
+   loadScript('filterTrace_1.js');
+   ```
+
+4. Run the tracer from the script. Be patient, it could take a long time.
+
+   ```js
+   tracer('<hash of transaction>');
+   ```
+
+   The bottom of the output looks similar to:
+
+   ```sh
+   "3366:POP", "3367:JUMP", "1355:JUMPDEST", "1356:PUSH1", "1358:MLOAD", "1359:DUP1", "1360:DUP3", "1361:ISZERO", "1362:ISZERO",
+   "1363:ISZERO", "1364:ISZERO", "1365:DUP2", "1366:MSTORE", "1367:PUSH1", "1369:ADD", "1370:SWAP2", "1371:POP", "1372:POP", "1373:PUSH1",
+   "1375:MLOAD", "1376:DUP1", "1377:SWAP2", "1378:SUB", "1379:SWAP1", "1380:RETURN"
+   ```
+
+5. Run this line to get a more readable output with each string in its own line.
+
+   ```js
+   console.log(JSON.stringify(tracer('<hash of transaction>'), null, 2));
+   ```
+
+More information about the `JSON.stringify` function is available [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
+
+The commands above worked by calling the same `debug.traceTransaction` function that was previously explained in [basic traces](/docs/developers/evm-tracing/basic-traces), but with a new parameter, `tracer`. This parameter takes the JavaScript object formated as a string. In the case of the trace above, it is:
+
+```js
+{
+   retVal: [],
+   step: function(log,db) {this.retVal.push(log.getPC() + ":" + log.op.toString())},
+   fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},
+   result: function(ctx,db) {return this.retVal}
+}
+```
+
+This object has three member functions:
+
+- `step`, called for each opcode.
+- `fault`, called if there is a problem in the execution.
+- `result`, called to produce the results that are returned by `debug.traceTransaction`
+- after the execution is done.
+
+In this case, `retVal` is used to store the list of strings to return in `result`.
+
+The `step` function adds to `retVal` the program counter and the name of the opcode there. Then, in `result`, this list is returned to be sent to the caller.
+
+### Filtering with conditions
+
+For actual filtered tracing we need an `if` statement to only log relevant information. For example, to isolate the transaction's interaction with storage, the following tracer could be used:
+
+```js
+tracer = function (tx) {
+  return debug.traceTransaction(tx, {
+    tracer:
+      '{' +
+      'retVal: [],' +
+      'step: function(log,db) {' +
+      '   if(log.op.toNumber() == 0x54) ' +
+      '     this.retVal.push(log.getPC() + ": SLOAD");' +
+      '   if(log.op.toNumber() == 0x55) ' +
+      '     this.retVal.push(log.getPC() + ": SSTORE");' +
+      '},' +
+      'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' +
+      'result: function(ctx,db) {return this.retVal}' +
+      '}'
+  }); // return debug.traceTransaction ...
+}; // tracer = function ...
+```
+
+The `step` function here looks at the opcode number of the op, and only pushes an entry if the opcode is `SLOAD` or `SSTORE` ([here is a list of EVM opcodes and their numbers](https://github.com/wolflo/evm-opcodes)). We could have used `log.op.toString()` instead, but it is faster to compare numbers rather than strings.
+
+The output looks similar to this:
+
+```js
+[
+  "5921: SLOAD",
+  .
+  .
+  .
+  "2413: SSTORE",
+  "2420: SLOAD",
+  "2475: SSTORE",
+  "6094: SSTORE"
+]
+```
+
+### Stack Information
+
+The trace above reports the program counter (PC) and whether the program read from storage or wrote to it. That alone isn't particularly useful. To know more, the `log.stack.peek` function can be used to peek into the stack. `log.stack.peek(0)` is the stack top, `log.stack.peek(1)` the entry below it, etc.
+
+The values returned by `log.stack.peek` are Go `big.Int` objects. By default they are converted to JavaScript floating point numbers, so you need `toString(16)` to get them as hexadecimals, which is how 256-bit values such as storage cells and their content are normally represented.
+
+#### Storage Information
+
+The function below provides a trace of all the storage operations and their parameters. This gives a more complete picture of the program's interaction with storage.
+
+```js
+tracer = function (tx) {
+  return debug.traceTransaction(tx, {
+    tracer:
+      '{' +
+      'retVal: [],' +
+      'step: function(log,db) {' +
+      '   if(log.op.toNumber() == 0x54) ' +
+      '     this.retVal.push(log.getPC() + ": SLOAD " + ' +
+      '        log.stack.peek(0).toString(16));' +
+      '   if(log.op.toNumber() == 0x55) ' +
+      '     this.retVal.push(log.getPC() + ": SSTORE " +' +
+      '        log.stack.peek(0).toString(16) + " <- " +' +
+      '        log.stack.peek(1).toString(16));' +
+      '},' +
+      'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' +
+      'result: function(ctx,db) {return this.retVal}' +
+      '}'
+  }); // return debug.traceTransaction ...
+}; // tracer = function ...
+```
+
+The output is similar to:
+
+```js
+[
+  "5921: SLOAD 0",
+  .
+  .
+  .
+  "2413: SSTORE 3f0af0a7a3ed17f5ba6a93e0a2a05e766ed67bf82195d2dd15feead3749a575d <- fb8629ad13d9a12456",
+  "2420: SLOAD cc39b177dd3a7f50d4c09527584048378a692aed24d31d2eabeddb7f3c041870",
+  "2475: SSTORE cc39b177dd3a7f50d4c09527584048378a692aed24d31d2eabeddb7f3c041870 <- 358c3de691bd19",
+  "6094: SSTORE 0 <- 1"
+]
+```
+
+#### Operation Results
+
+One piece of information missing from the function above is the result on an `SLOAD` operation. The state we get inside `log` is the state prior to the execution of the opcode, so that value is not known yet. For more operations we can figure it out for ourselves, but we don't have access to the
+storage, so here we can't.
+
+The solution is to have a flag, `afterSload`, which is only true in the opcode right after an `SLOAD`, when we can see the result at the top of the stack.
+
+```js
+tracer = function (tx) {
+  return debug.traceTransaction(tx, {
+    tracer:
+      '{' +
+      'retVal: [],' +
+      'afterSload: false,' +
+      'step: function(log,db) {' +
+      '   if(this.afterSload) {' +
+      '     this.retVal.push("    Result: " + ' +
+      '          log.stack.peek(0).toString(16)); ' +
+      '     this.afterSload = false; ' +
+      '   } ' +
+      '   if(log.op.toNumber() == 0x54) {' +
+      '     this.retVal.push(log.getPC() + ": SLOAD " + ' +
+      '        log.stack.peek(0).toString(16));' +
+      '        this.afterSload = true; ' +
+      '   } ' +
+      '   if(log.op.toNumber() == 0x55) ' +
+      '     this.retVal.push(log.getPC() + ": SSTORE " +' +
+      '        log.stack.peek(0).toString(16) + " <- " +' +
+      '        log.stack.peek(1).toString(16));' +
+      '},' +
+      'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' +
+      'result: function(ctx,db) {return this.retVal}' +
+      '}'
+  }); // return debug.traceTransaction ...
+}; // tracer = function ...
+```
+
+The output now contains the result in the line that follows the `SLOAD`.
+
+```js
+[
+  "5921: SLOAD 0",
+  "    Result: 1",
+  .
+  .
+  .
+  "2413: SSTORE 3f0af0a7a3ed17f5ba6a93e0a2a05e766ed67bf82195d2dd15feead3749a575d <- fb8629ad13d9a12456",
+  "2420: SLOAD cc39b177dd3a7f50d4c09527584048378a692aed24d31d2eabeddb7f3c041870",
+  "    Result: 0",
+  "2475: SSTORE cc39b177dd3a7f50d4c09527584048378a692aed24d31d2eabeddb7f3c041870 <- 358c3de691bd19",
+  "6094: SSTORE 0 <- 1"
+]
+```
+
+### Dealing With Calls Between Contracts
+
+So the storage has been treated as if there are only 2<sup>256</sup> cells. However, that is not true. Contracts can call other contracts, and then the storage involved is the storage of the other contract. We can see the address of the current contract in `log.contract.getAddress()`. This value is the execution context - the contract whose storage we are using - even when code from another contract is executed (by using
+[`CALLCODE` or `DELEGATECALL`](https://docs.soliditylang.org/en/v0.8.14/introduction-to-smart-contracts.html#delegatecall-callcode-and-libraries)).
+
+However, `log.contract.getAddress()` returns an array of bytes. To convert this to the familiar hexadecimal representation of Ethereum addresses, `this.byteHex()` and `array2Hex()` can be used.
+
+```js
+tracer = function (tx) {
+  return debug.traceTransaction(tx, {
+    tracer:
+      '{' +
+      'retVal: [],' +
+      'afterSload: false,' +
+      'callStack: [],' +
+      'byte2Hex: function(byte) {' +
+      '  if (byte < 0x10) ' +
+      '      return "0" + byte.toString(16); ' +
+      '  return byte.toString(16); ' +
+      '},' +
+      'array2Hex: function(arr) {' +
+      '  var retVal = ""; ' +
+      '  for (var i=0; i<arr.length; i++) ' +
+      '    retVal += this.byte2Hex(arr[i]); ' +
+      '  return retVal; ' +
+      '}, ' +
+      'getAddr: function(log) {' +
+      '  return this.array2Hex(log.contract.getAddress());' +
+      '}, ' +
+      'step: function(log,db) {' +
+      '   var opcode = log.op.toNumber();' +
+      // SLOAD
+      '   if (opcode == 0x54) {' +
+      '     this.retVal.push(log.getPC() + ": SLOAD " + ' +
+      '        this.getAddr(log) + ":" + ' +
+      '        log.stack.peek(0).toString(16));' +
+      '        this.afterSload = true; ' +
+      '   } ' +
+      // SLOAD Result
+      '   if (this.afterSload) {' +
+      '     this.retVal.push("    Result: " + ' +
+      '          log.stack.peek(0).toString(16)); ' +
+      '     this.afterSload = false; ' +
+      '   } ' +
+      // SSTORE
+      '   if (opcode == 0x55) ' +
+      '     this.retVal.push(log.getPC() + ": SSTORE " +' +
+      '        this.getAddr(log) + ":" + ' +
+      '        log.stack.peek(0).toString(16) + " <- " +' +
+      '        log.stack.peek(1).toString(16));' +
+      // End of step
+      '},' +
+      'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' +
+      'result: function(ctx,db) {return this.retVal}' +
+      '}'
+  }); // return debug.traceTransaction ...
+}; // tracer = function ...
+```
+
+The output is similar to:
+
+```js
+[
+  "423: SLOAD 22ff293e14f1ec3a09b137e9e06084afd63addf9:360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc",
+  "    Result: 360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc",
+  "10778: SLOAD 22ff293e14f1ec3a09b137e9e06084afd63addf9:6",
+  "    Result: 6",
+  .
+  .
+  .
+  "13529: SLOAD f2d68898557ccb2cf4c10c3ef2b034b2a69dad00:8328de571f86baa080836c50543c740196dbc109d42041802573ba9a13efa340",
+  "    Result: 8328de571f86baa080836c50543c740196dbc109d42041802573ba9a13efa340",
+  "423: SLOAD f2d68898557ccb2cf4c10c3ef2b034b2a69dad00:360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc",
+  "    Result: 360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc",
+  "13529: SLOAD f2d68898557ccb2cf4c10c3ef2b034b2a69dad00:b38558064d8dd9c883d2a8c80c604667ddb90a324bc70b1bac4e70d90b148ed4",
+  "    Result: b38558064d8dd9c883d2a8c80c604667ddb90a324bc70b1bac4e70d90b148ed4",
+  "11041: SSTORE 22ff293e14f1ec3a09b137e9e06084afd63addf9:6 <- 0"
+]
+```

docs/developers/geth-developer/code-review-guidelines.md

@@ -0,0 +1,69 @@
+---
+title: Code Review Guidelines
+description: Explanation of how code PRs are reviewed
+---
+
+The only way to get code into Geth is to submit a pull request (PR). Those pull requests need to be reviewed by someone. This document is a guide that explains our expectations around PRs for both authors and reviewers.
+
+## Terminology {#terminology}
+
+- The **author** of a pull request is the entity who wrote the diff and submitted it to GitHub.
+- The **team** consists of people with commit rights on the go-ethereum repository.
+- The **reviewer** is the person assigned to review the diff. The reviewer must be a team member.
+- The **code owner** is the person responsible for the subsystem being modified by the PR.
+
+## The Process {#process}
+
+The first decision to make for any PR is whether it's worth including at all. This decision lies primarily with the code owner, but may be negotiated with team members.
+
+To make the decision we must understand what the PR is about. If there isn't enough description content or the diff is too large, request an explanation. Anyone can do this part.
+
+We expect that reviewers check the style and functionality of the PR, providing comments to the author using the GitHub review system. Reviewers should follow up with the PR until it is in good shape, then **approve** the PR. Approved PRs can be merged by any code owner.
+
+When communicating with authors, be polite and respectful.
+
+### Code Style {#code-style}
+
+We expect `gofmt`ed code. For contributions of significant size, we expect authors to understand and use the guidelines in [Effective Go](https://golang.org/doc/effective_go.html). Authors should avoid common mistakes explained in the [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) page.
+
+### Functional Checks {#functional-checks}
+
+For PRs that fix an issue, reviewers should try reproduce the issue and verify that the pull request actually fixes it. Authors can help with this by including a unit test that fails without (and passes with) the change.
+
+For PRs adding new features, reviewers should attempt to use the feature and comment on how it feels to use it. Example: if a PR adds a new command line flag, use the program with the flag and comment on whether the flag feels useful.
+
+We expect appropriate unit test coverage. Reviewers should verify that new code is covered by unit tests.
+
+### CI {#ci}
+
+Code submitted must pass all unit tests and static analysis ("lint") checks. We use Travis CI to test code on Linux, macOS and AppVeyor to test code on Microsoft Windows.
+
+For failing CI builds, the issue may not be related to the PR itself. Such failures are usually related to flakey tests. These failures can be ignored (authors don't need to fix unrelated issues), but please file a GH issue so the test gets fixed eventually.
+
+### Commit Messages {#commit-messages}
+
+Commit messages on the master branch should follow the rule below. PR authors are not required to use any particular style because the message can be modified at merge time. Enforcing commit message style is the responsibility of the person merging the PR.
+
+The commit message style we use is similar to the style used by the Go project:
+
+The first line of the change description is conventionally a one-line summary of the change, prefixed by the primary affected Go package. It should complete the sentence "This change modifies go-ethereum to **\_**." The rest of the description elaborates and should provide context for the change and explain what it does.
+
+Template:
+
+```text
+package/path: change XYZ
+
+Longer explanation of the change in the commit. You can use multiple sentences here. It's usually best to include content from the PR description in the final commit message.
+
+issue notices, e.g. "Fixes #42353".
+```
+
+### Special Situations And How To Deal With Them {#special-situations}
+
+Reviewers may find themselves in one of the sitations below. Here's how to deal with them:
+
+- The author doesn't follow up: ping them after a while (i.e. after a few days). If there is no further response, close the PR or complete the work yourself.
+
+- Author insists on including refactoring changes alongside bug fix: We can tolerate small refactorings alongside any change. If you feel lost in the diff, ask the author to submit the refactoring as an independent PR, or at least as an independent commit in the same PR.
+
+- Author keeps rejecting feedback: reviewers have authority to reject any change for technical reasons. If you're unsure, ask the team for a second opinion. The PR can be closed if no consensus can be reached.

docs/developers/geth-developer/contributing.md

@@ -0,0 +1,34 @@
+---
+title: Contributing
+description: Guidelines for contributing to Geth
+---
+
+We welcome contributions from anyone on the internet, and are grateful for even the smallest of fixes!
+
+## Contributing to the Geth source code {#contributing-to-source-code}
+
+If you'd like to contribute to the Geth source code, please fork the [GitHub repository](https://github.com/ethereum/go-ethereum), fix, commit and send a pull request for the maintainers to review and merge into the main code base. If you wish to submit more complex changes though, please check up with the core devs first on our Discord Server to ensure those changes are in line with the general philosophy of the project and/or get some early feedback which can make both your efforts much lighter as well as our review and merge procedures quick and simple.
+
+Please make sure your contributions adhere to our coding guidelines:
+
+- Code must adhere to the official Go formatting guidelines (i.e. uses gofmt).
+- Code must be documented adhering to the official Go commentary guidelines.
+- Pull requests need to be based on and opened against the master branch.
+- Commit messages should be prefixed with the package(s) they modify.
+  E.g. "eth, rpc: make trace configs optional"
+
+Pull requests generally need to be based on and opened against the `master` branch, unless by explicit agreement because the work is contributing to some more complex feature branch.
+
+All pull requests will be reviewed according to the [Code Review guidelines](/docs/developers/geth-developer/code-review-guidelines).
+
+We encourage an early pull request approach, meaning pull requests are created as early as possible even without the completed fix/feature. This will let core devs and other volunteers know you picked up an issue. These early PRs should indicate 'in progress' status.
+
+## Contributing to the Geth website {#contributing-to-website}
+
+The Geth website is hosted separately from Geth itself. The contribution guidelines are the same. Please check out the [website repository](https://github.com/ethereum/geth-website) and raise pull requests for the maintainers to review and merge.
+
+## License {#license}
+
+The go-ethereum library (i.e. all code outside of the cmd directory) is licensed under the GNU Lesser General Public License v3.0, also included in our repository in the COPYING.LESSER file.
+
+The go-ethereum binaries (i.e. all code inside of the cmd directory) is licensed under the GNU General Public License v3.0, also included in our repository in the COPYING file.

docs/developers/geth-developer/dev-guide.md

@@ -0,0 +1,147 @@
+---
+title: Getting Started
+description: Entry point for developers working on Geth
+---
+
+This document is the entry point for developers who wish to work on Geth. Developers are people who are interested to build, develop, debug, submit
+a bug report or pull request or otherwise contribute to the Geth source code.
+
+Please see [Contributing](/docs/developers/contributing) for the Geth contribution guidelines.
+
+## Building and Testing {#building-and-testing}
+
+Developers should use a recent version of Go for building and testing. We use the go toolchain for development, which you can get from the [Go downloads page](https://golang.org/doc/install). Geth is a Go module, and uses the [Go modules system](https://github.com/golang/go/wiki/Modules) to manage dependencies. Using `GOPATH` is not required to build go-ethereum.
+
+### Building Executables {#building-executables}
+
+Switch to the go-ethereum repository root directory. All code can be built using the go tool, placing the resulting binary in `$GOPATH/bin`.
+
+```sh
+go install -v ./...
+```
+
+go-ethereum exectuables can be built individually. To build just geth, use:
+
+```sh
+go install -v ./cmd/geth
+```
+
+Cross compilation is not recommended, please build Geth for the host architecture.
+
+### Testing {#testing}
+
+Testing a package:
+
+```sh
+go test -v ./eth
+```
+
+Running an individual test:
+
+```sh
+go test -v ./eth -run TestMethod
+```
+
+**Note**: here all tests with prefix _TestMethod_ will be run, so if TestMethod and TestMethod1 both exist then both tests will run.
+
+Running benchmarks, eg.:
+
+```sh
+go test -v -bench . -run BenchmarkJoin
+```
+
+For more information, see the [go test flags](https://golang.org/cmd/go/#hdr-Testing_flags) documentation.
+
+### Getting Stack Traces {#getting-stack-traces}
+
+A stack trace provides a very detailed look into the current state of the geth node. It helps us to debug issues easier as it contains information about what is currently done by the node. Stack traces can be created by running `debug.stacks()` in the Geth console. If the node was started without the console command or with a script in the background, the following command can be used to dump the stack trace into a file.
+
+```sh
+geth attach <path-to-geth.ipc> --exec "debug.stacks()" > stacktrace.txt
+```
+
+Geth logs the location of the IPC endpoint on startup. It is typically under `/home/user/.ethereum/geth.ipc` or `/tmp/geth.ipc`.
+
+`debug.stacks()` also takes an optional `filter` argument. Passing a package name or filepath to `filter` restricts the output to stack traces involcing only that package/file. For example:
+
+```sh
+debug.stacks("enode")
+```
+
+returns data that looks like:
+
+```terminal
+INFO [11-04|16:15:54.486] Expanded filter expression               filter=enode   expanded="`enode` in Value"
+goroutine 121 [chan receive, 3 minutes]:
+github.com/ethereum/go-ethereum/p2p/enode.(*FairMix).nextFromAny(...)
+	github.com/ethereum/go-ethereum/p2p/enode/iter.go:241
+github.com/ethereum/go-ethereum/p2p/enode.(*FairMix).Next(0xc0008c6060)
+	github.com/ethereum/go-ethereum/p2p/enode/iter.go:215 +0x2c5
+github.com/ethereum/go-ethereum/p2p.(*dialScheduler).readNodes(0xc00021c2c0, {0x18149b0, 0xc0008c6060})
+	github.com/ethereum/go-ethereum/p2p/dial.go:321 +0x9f
+created by github.com/ethereum/go-ethereum/p2p.newDialScheduler
+	github.com/ethereum/go-ethereum/p2p/dial.go:179 +0x425
+```
+
+and
+
+```sh
+debug.stacks("consolecmd.go")
+```
+
+returns data that looks like:
+
+```terminal
+INFO [11-04|16:16:47.141] Expanded filter expression               filter=consolecmd.go expanded="`consolecmd.go` in Value"
+goroutine 1 [chan receive]:
+github.com/ethereum/go-ethereum/internal/jsre.(*JSRE).Do(0xc0004223c0, 0xc0003c00f0)
+	github.com/ethereum/go-ethereum/internal/jsre/jsre.go:230 +0xf4
+github.com/ethereum/go-ethereum/internal/jsre.(*JSRE).Evaluate(0xc00033eb60?, {0xc0013c00a0, 0x1e}, {0x180d720?, 0xc000010018})
+	github.com/ethereum/go-ethereum/internal/jsre/jsre.go:289 +0xb3
+github.com/ethereum/go-ethereum/console.(*Console).Evaluate(0xc0005366e0, {0xc0013c00a0?, 0x0?})
+	github.com/ethereum/go-ethereum/console/console.go:353 +0x6d
+github.com/ethereum/go-ethereum/console.(*Console).Interactive(0xc0005366e0)
+	github.com/ethereum/go-ethereum/console/console.go:481 +0x691
+main.localConsole(0xc00026d580?)
+	github.com/ethereum/go-ethereum/cmd/geth/consolecmd.go:109 +0x348
+github.com/ethereum/go-ethereum/internal/flags.MigrateGlobalFlags.func2.1(0x20b52c0?)
+	github.com/ethereum/go-ethereum/internal/flags/helpers.go:91 +0x36
+github.com/urfave/cli/v2.(*Command).Run(0x20b52c0, 0xc000313540)
+	github.com/urfave/cli/v2@v2.17.2-0.20221006022127-8f469abc00aa/command.go:177 +0x719
+github.com/urfave/cli/v2.(*App).RunContext(0xc0005501c0, {0x1816128?, 0xc000040110}, {0xc00003c180, 0x3, 0x3})
+	github.com/urfave/cli/v2@v2.17.2-0.20221006022127-8f469abc00aa/app.go:387 +0x1035
+github.com/urfave/cli/v2.(*App).Run(...)
+	github.com/urfave/cli/v2@v2.17.2-0.20221006022127-8f469abc00aa/app.go:252
+main.main()
+	github.com/ethereum/go-ethereum/cmd/geth/main.go:266 +0x47
+
+goroutine 159 [chan receive, 4 minutes]:
+github.com/ethereum/go-ethereum/node.(*Node).Wait(...)
+	github.com/ethereum/go-ethereum/node/node.go:529
+main.localConsole.func1()
+	github.com/ethereum/go-ethereum/cmd/geth/consolecmd.go:103 +0x2d
+created by main.localConsole
+	github.com/ethereum/go-ethereum/cmd/geth/consolecmd.go:102 +0x32e
+```
+
+If Geth is started with the `--pprof` option, a debugging HTTP server is made available on port 6060. Navigating to <http://localhost:6060/debug/pprof> displays the heap, running routines etc. By clicking "full goroutine stack dump" a trace can be generated that is useful for debugging.
+
+Note that if multiple instances of Geth exist, port `6060` will only work for the first instance that was launched. To generate stacktraces for other instances, they should be started up with alternative pprof ports. Ensure `stderr` is being redirected to a logfile.
+
+```sh
+geth -port=30300 -verbosity 5 --pprof --pprof.port 6060 2>> /tmp/00.glog
+geth -port=30301 -verbosity 5 --pprof --pprof.port 6061 2>> /tmp/01.glog
+geth -port=30302 -verbosity 5 --pprof --pprof.port 6062 2>> /tmp/02.glog
+```
+
+Alternatively to kill the clients (in case they hang or stalled syncing, etc) and have the stacktrace too, use the `-QUIT` signal with `kill`:
+
+```sh
+killall -QUIT geth
+```
+
+This will dump stack traces for each instance to their respective log file.
+
+## Where to go next {#where-next}
+
+Read the remaning pages in the Geth developer section, and get building!

docs/developers/geth-developer/disclosures.md

@@ -0,0 +1,85 @@
+---
+title: Vulnerability disclosure
+description: Instructions for disclosing vulnerabilities to the Geth team
+---
+
+In the software world, it is expected for security vulnerabilities to be immediately announced, thus giving operators an opportunity to take protective measure against attackers.
+
+Vulnerabilies typically take two forms:
+
+1. Vulnerabilies that, if exploited, would harm the software operator. In the case of Geth, examples would be:
+   - A bug that would allow remote reading or writing of OS files, or
+   - Remote command execution, or
+   - Bugs that would leak cryptographic keys
+2. Vulnerabilies that, if exploited, would harm the Ethereum mainnet. In the case of Geth, examples would be:
+   - Consensus vulnerabilities, which would cause a chain split,
+   - Denial-of-service during block processing, whereby a malicious transaction could cause the geth-portion of the network to crash.
+   - Denial-of-service via p2p networking, whereby portions of the network could be made
+     inaccessible due to crashes or resource consumption.
+
+In most cases so far, vulnerabilities in Geth have been of the second type, where the health of the network is a concern, rather than individual node operators. For such issues, Geth reserves the right to silently patch and ship fixes in new releases.
+
+### Why silent patches {#why-slient-patches}
+
+In the case of Ethereum, it takes a lot of time (weeks, months) to get node operators to update even to a scheduled hard fork. If we were to highlight that a release contains important consensus or DoS fixes, there is always a risk of someone trying to beat node operators to the punch, and exploit the vulnerability. Delaying a potential attack sufficiently to make the majority of node operators immune may be worth the temporary loss of transparency.
+
+The primary goal for the Geth team is the health of the Ethereum network as a whole, and the decision whether or not to publish details about a serious vulnerability boils down to minimizing the risk and/or impact of discovery and exploitation.
+
+At certain times, it's better to remain silent. This practice is also followed by other projects such as [Monero](https://www.getmonero.org/2017/05/17/disclosure-of-a-major-bug-in-cryptonote-based-currencies.html), [ZCash](https://electriccoin.co/blog/zcash-counterfeiting-vulnerability-successfully-remediated/) and [Bitcoin](https://www.coindesk.com/the-latest-bitcoin-bug-was-so-bad-developers-kept-its-full-details-a-secret).
+
+### Public transparency {#public-transparency}
+
+As of November 2020, our policy going forward is:
+
+- If we silently fix a vulnerability and include the fix in release `X`, then,
+- After 4-8 weeks, we will disclose that `X` contained a security-fix.
+- After an additional 4-8 weeks, we will publish the details about the vulnerability.
+
+We hope that this provides sufficient balance between transparency versus the need for secrecy, and aids node operators and downstream projects in keeping up to date with what versions to run on their infrastructure.
+
+In keeping with this policy, we have taken inspiration from [Solidity bug disclosure](https://solidity.readthedocs.io/en/develop/bugs.html) - see below.
+
+## Disclosed vulnerabilities {#disclosed-vulnerabilities}
+
+There is a JSON-formatted list ([`vulnerabilities.json`](/public/docs/vulnerabilities/vulnerabilities.json)) of some of the known security-relevant vulnerabilities concerning Geth.
+
+As of version `1.9.25`, Geth has a built-in command to check whether it is affected by any publically disclosed vulnerability, using the command `geth version-check`. This command will fetch the latest json file (and the accompanying [signature-file](/public/docs/vulnerabilities/vulnerabilities.json.minisig), and cross-check the data against it's own version number.
+
+The list of vulnerabilities was started in November 2020, and covers mainly `v1.9.7` and forward.
+
+The JSON file of known vulnerabilities below is a list of objects, one for each vulnerability, with the following keys:
+
+- `name`
+  - Unique name given to the vulnerability.
+- `uid`
+  - Unique identifier of the vulnerability. Format `GETH-<year>-<sequential id>`
+- `summary`
+  - Short description of the vulnerability.
+- `description`
+  - Detailed description of the vulnerability.
+- `links`
+  - List of relevant URLs with more detailed information (optional).
+- `introduced`
+  - The first published Geth version that contained the vulnerability (optional).
+- `fixed`
+  - The first published Geth version that did not contain the vulnerability anymore.
+- `published`
+  - The date at which the vulnerability became known publicly (optional).
+- `severity`
+  - Severity of the vulnerability: `low`, `medium`, `high`, `critical`.
+  - Takes into account the severity of impact and likelihood of exploitation.
+- `check`
+  - This field contains a regular expression, which can be used against the reported `web3_clientVersion` of a node. If the check
+    matches, the node is with a high likelyhood affected by the vulnerability.
+- `CVE`
+  - The assigned `CVE` identifier, if available (optional)
+
+### What about GitHub security advisories {#github-security-advisories}
+
+We prefer to not rely on GitHub as the only/primary publishing protocol for security advisories, but we plan to use the GitHub-advisory process as a second channel for disseminating vulnerability-information.
+
+Advisories published via GitHub can be accessed [here](https://github.com/ethereum/go-ethereum/security/advisories?state=published).
+
+## Bug Bounties {#bug-bounties}
+
+The Ethereum Foundation run a bug bounty program to reward responsible disclosures of bugs in client software and specs. The details are provided on [ethereum.org](https://ethereum.org/en/bug-bounty/).

docs/developers/geth-developer/dns-discovery-setup.md

@@ -0,0 +1,100 @@
+---
+title: DNS Discovery Setup Guide
+description: Instructions for setting up DNS discovery
+---
+
+This document explains how to set up an [EIP 1459](https://eips.ethereum.org/EIPS/eip-1459) node list using the devp2p developer tool. The focus of this guide is creating a public list for the Ethereum mainnet and public testnets, but it may also be helpful for setting up DNS-based discovery for a private network.
+
+DNS-based node lists can serve as a fallback option when connectivity to the discovery DHT is unavailable. In this guide, node lists will be reated by crawling the discovery DHT, then publishing the resulting node sets under chosen DNS names.
+
+## Installing the devp2p command {#installing-devp2p}
+
+`cmd/devp2p` is a developer utility and is not included in the Geth distribution. You can install this command using `go get`:
+
+```sh
+go get github.com/ethereum/go-ethereum/cmd/devp2p
+```
+
+To create a signing key, the `ethkey` utility is needed.
+
+```sh
+go get github.com/ethereum/go-ethereum/cmd/ethkey
+```
+
+## Crawling the v4 DHT {#crawling-v4-dht}
+
+Our first step is to compile a list of all reachable nodes. The DHT crawler in cmd/devp2p is a batch process which runs for a set amount of time. You should should schedule this command to run at a regular interval. To create a node list, run
+
+```sh
+devp2p discv4 crawl -timeout 30m all-nodes.json
+```
+
+This walks the DHT and stores the set of all found nodes in the `all-nodes.json` file.
+Subsequent runs of the same command will revalidate previously discovered node records,
+add newly-found nodes to the set, and remove nodes which are no longer alive. The quality
+of the node set improves with each run because the number of revalidations is tracked
+alongside each node in the set.
+
+## Creating sub-lists through filtering {#creating-sublists}
+
+Once `all-nodes.json` has been created and the set contains a sizeable number of nodes,
+useful sub-sets of nodes can be extracted using the `devp2p nodeset filter` command. This
+command takes a node set file as argument and applies filters given as command-line flags.
+
+To create a filtered node set, first create a new directory to hold the output set. You
+can use any directory name, though it's good practice to use the DNS domain name as the
+name of this directory.
+
+```sh
+mkdir mainnet.nodes.example.org
+```
+
+Then, to create the output set containing Ethereum mainnet nodes only, run
+
+```sh
+devp2p nodeset filter all-nodes.json -eth-network mainnet > mainnet.nodes.example.org/nodes.json
+```
+
+The following filter flags are available:
+
+- `-eth-network ( mainnet | sepolia | goerli )` selects an Ethereum network.
+- `-les-server` selects LES server nodes.
+- `-ip <mask>` restricts nodes to the given IP range.
+- `-min-age <duration>` restricts the result to nodes which have been live for the
+  given duration.
+
+## Creating DNS trees {#creating-dns-trees}
+
+To turn a node list into a DNS node tree, the list needs to be signed. To do this, a key pair is required. To create the key file in the correct format, the cmd/ethkey utility should be used. Choose a strong password to encrypt the key on disk!
+
+```sh
+ethkey generate dnskey.json
+```
+
+Now use `devp2p dns sign` to update the signature of the node list. If the list's directory name differs from the name it will be published at,specify the DNS name the using the `-domain` flag. This command will prompt for the key file password and update the tree signature.
+
+```sh
+devp2p dns sign mainnet.nodes.example.org dnskey.json
+```
+
+The resulting DNS tree metadata is stored in the `mainnet.nodes.example.org/enrtree-info.json` file.
+
+## Publishing DNS trees {#publishing-dns-trees}
+
+Now that the tree is signed, it can be published to a DNS provider. cmd/devp2p currently supports publishing to CloudFlare DNS and Amazon Route53.TXT records can also be exported as a JSON file and published independently.
+
+To publish to CloudFlare, first create an API token in the management console. cmd/devp2p expects the API token in the `CLOUDFLARE_API_TOKEN` environment variable. Now use the following command to upload DNS TXT records via the CloudFlare API:
+
+```sh
+devp2p dns to-cloudflare mainnet.nodes.example.org
+```
+
+Note that this command uses the domain name specified during signing. Any existing records below this name will be erased by cmd/devp2p.
+
+## Using DNS trees with Geth {#using-dns-trees}
+
+Once a tree is available through a DNS name, Geth can use it with the `--discovery.dns` command line flag. Node trees are referenced using the `enrtree://` URL scheme. The URL of the tree can be found in the `enrtree-info.json` file created by `devp2p dns sign`. Pass the URL as an argument to the flag in order to make use of the published tree.
+
+```sh
+geth --discovery.dns "enrtree://AMBMWDM3J6UY3M32TMMROUNLX6Y3YTLVC3DC6HN2AVG5NHNSAXDW6@mainnet.nodes.example.org"
+```

docs/developers/index.md

@@ -0,0 +1,38 @@
+---
+title: Developer docs
+description: Documentation for Geth developers and dapp developers
+---
+
+Welcome to the Geth Developer docs!
+
+This section includes information for builders. If you are building decentralized apps on top of Geth, head to the `dapp-developer` docs. If you are developing Geth itself, explore the `geth-developer` docs.
+
+## Dapp developers {#dapp-developers}
+
+Geth has many features that support dapp developers. There are many built-in tracers implemented in Go or Javascript that allow developers to monitor what is happening in Geth from inside an app, and users can build their own custom tracers too. Geth also includes a suite of tools for interacting with Ethereum smart contracts using Geth functions using Go functions inside Go native applications. There is also information for Geth mobile developers.
+
+- [Developer mode](/docs/developers/dapp-developer/dev-mode)
+- [Developing for mobile](/docs/developers/dapp-developer/mobile)
+- [Geth in Go apps](/docs/developers/dapp-developer/native)
+- [Go contract bindings](/docs/developers/dapp-developer/native-bindings)
+- [Account management in Go apps](/docs/developers/dapp-developer/native-accounts)
+
+## Geth developers {#geth-developers}
+
+Geth developers add/remove features and fix bugs in Geth. The `geth-developer` section includes contribution guidelines and documentation relating to testing and disclosing vulnerabilities that willhep you get started with working on Geth.
+
+- [Code review guidelines](/docs/developers/geth-developer/code-review-guidelines)
+- [Contributing to Geth](/docs/developers/geth-developer/contributing)
+- [Developer guide](/docs/developers/geth-developer/dev-guide)
+- [Disclosures](/docs/developers/geth-developer/disclosures)
+- [DNS discovery setup guide](/docs/developers/geth-developer/dns-discovery-setup)
+
+## EVM tracing
+
+Tracing allows developers to analyze precisely what the EVM has done or will do given a certain set of commands. This section outlines the various ways tracing can be implemented in Geth.
+
+- [Introduction](/docs/developers/evm-tracing/)
+- [Basic tracers](/docs/developers/evm-tracing/basic-traces)
+- [Built-in tracers](/docs/developers/evm-tracing/built-in-tracers)
+- [Custom tracers](/docs/developers/evm-tracing/custom-tracer)
+- [Javascript tracing tutorial](/docs/developers/evm-tracing/javascript-tutorial)

docs/faq.md

@@ -0,0 +1,97 @@
+---
+title: FAQ
+description: Frequently asked questions related to Geth
+---
+
+## Where can I get more information? {#where-can-i-get-more-information}
+
+This page contains answers to common questions about Geth. Source code and README documentation can be found on the Geth [GitHub](https://github.com/ethereum/go-ethereum). You can also ask questions on Geth's [Discord server](https://discord.gg/WHNkYDsAKU) or keep up to date with Geth on [Twitter](https://twitter.com/go_ethereum). Information about Ethereum in general can be found at [ethereum.org](https://ethereum.org).
+
+The Geth team have also recently started to run AMA's on Reddit:
+
+- [Aug 2022 AMA](https://www.reddit.com/r/ethereum/comments/wpqmo1/ama_we_are_the_go_ethereum_geth_team_18_august/)
+
+It is also recommended to search for 'Geth' and 'go-ethereum' on [ethereum.stackexchange.com](https://ethereum.stackexchange.com/).
+
+## What are RPC and IPC? {#what-are-rpc-and-ipc}
+
+IPC stands for Inter-Process Communications. Geth creates a `geth.ipc` file on startup that other processes on the same computer can use to communicate with Geth.
+RPC stands for Remote Procedure Call. RPC is a mode of communication between processes that may be running on different machines. Geth accepts RPC traffic over HTTP or Websockets. Geth functions are invoked by sending requests that are formatted according to the RPC-API to the node via either IPC or RPC.
+
+## What is `jwtsecret`? {#what-is-jwtsecret}
+
+The `jwtsecret` file is required to create an authenticated connection between Geth and a consensus client. JWT stands for JSON Web Token - it is signed using a secret key. The signed token acts as a shared secret used to check that information is sent to and received from the correct peer. Read about how to create `jwt-secret` in Geth on our [consensus clients](/docs/getting-started/consensus-clients) page.
+
+## I noticed my peercount slowly decreasing, and now it is at 0. Restarting doesn't get any peers. {#where-are-my-peers}
+
+This may be because your clock has fallen out of sync with other nodes. You can [force a clock update using ntp](https://askubuntu.com/questions/254826/how-to-force-a-clock-update-using-ntp) like so:
+
+```sh
+sudo ntpdate -s time.nist.gov
+```
+
+## I would like to run multiple Geth instances but got the error "Fatal: blockchain db err: resource temporarily unavailable". {#multiple-geth-instances}
+
+Geth uses a datadir to store the blockchain, accounts and some additional information. This directory cannot be shared between running instances. If you would like to run multiple instances follow [these](/docs/developers/geth-developer/private-network) instructions.
+
+## When I try to use the --password command line flag, I get the error "Could not decrypt key with given passphrase" but the password is correct. Why does this error appear? {#could-not-decrypt-key}
+
+Especially if the password file was created on Windows, it may have a Byte Order Mark or other special encoding that the go-ethereum client doesn't currently recognize. You can change this behavior with a PowerShell command like:
+
+```sh
+echo "mypasswordhere" | out-file test.txt -encoding ASCII
+```
+
+Additional details and/or any updates on more robust handling are at <https://github.com/ethereum/go-ethereum/issues/19905>.
+
+## How does Ethereum syncing work? {#how-does-syncing-work}
+
+The current default syncing mode used by Geth is called [snap sync](https://github.com/ethereum/devp2p/blob/master/caps/snap.md). Instead of starting from the genesis block and processing all the transactions that ever occurred (which could take weeks), snap sync downloads the blocks, and only verifies the associated proof-of-works, assuming state transitions to be correct. Downloading all the blocks is a straightforward and fast procedure and will relatively quickly reassemble the entire chain.
+
+Many people assume that because they have the blocks, they are in sync. Unfortunately this is not the case. Since no transaction was executed, we do not have any account state available (e.g. balances, nonces, smart contract code, and data). These need to be downloaded separately and cross-checked with the latest blocks. This phase is called the state trie download phase. Snap sync tries to expedite this process by downloading contiguous chunks of state data, instead of doing so one-by-one, as in previous synchronization methods. Geth downloads the leaves of the trie without the intermediate nodes that connect the leaves to the root. The full trie is regenerated locally. However, while this is happening, the blockchain is progressing, meaning some of the regenerated state trie becomes invalid. Therefore, there is also a healing phase that corrects any errors in the state trie. The state sync has to progress faster than the chain growth otherwise it will never finish.
+
+Geth can also be synced with `--syncmode full`. In this case, Geth downloads and independently verifies every block since genesis in sequence, including re-executing transactions to verify state transitions. Although Geth verifies every block since genesis, the state of 128 blocks only are stored in memory.
+
+## What's the state trie? {#what-is-the-state-trie}
+
+In the Ethereum mainnet, there are a ton of accounts already, which track the balance, nonce, etc of each user/contract. The accounts themselves are however insufficient to run a node, they need to be cryptographically linked to each block so that nodes can actually verify that the accounts are not tampered with.
+
+This cryptographic linking is done by creating a tree-like data structure, where each leaf corresponds to an account, and each intermediary level aggregates the layer below it into an ever smaller layer, until you reach a single root. This gigantic data structure containing all the accounts and the intermediate cryptographic proofs is called the state trie.
+
+Read more about Merkle Tries in general and the Ethereum state trie specifically on [ethereum.org](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie)
+
+## Why does the state trie download phase require a special syncing mode? {#state-trie-downloading}
+
+The trie data structure is an intricate interlink of hundreds of millions of tiny cryptographic proofs (trie nodes). To truly have a synchronized node, you need to download all the account data, as well as all the tiny cryptographic proofs to verify that no one in the network is trying to cheat you. This itself is already a crazy number of data items.
+
+The part where it gets even messier is that this data is constantly morphing: at every block (roughly 13s), about 1000 nodes are deleted from this trie and about 2000 new ones are added. This means your node needs to synchronize a dataset that is changing more than 200 times per second. Until you actually do gather all the data, your local node is not usable since it cannot cryptographically prove anything about any accounts. But while you're syncing the network is moving forward and most nodes on the network keep the state for only a limited number of recent blocks. Any sync algorithm needs to consider this fact.
+
+## What happened to fast sync? {#fast-sync}
+
+Snap syncing was introduced by version [1.10.0](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/) and was adopted as the default mode in version [1.10.4](https://github.com/ethereum/go-ethereum/releases/tag/v1.10.4). Before that, the default was the "fast" syncing mode, which was dropped in version [1.10.14](https://github.com/ethereum/go-ethereum/releases/tag/v1.10.14). Even though support for fast sync was dropped, Geth still serves the relevant `eth` requests to other client implementations still relying on it. The reason being that snap sync relies on an alternative data structure called the [snapshot](https://blog.ethereum.org/2020/07/17/ask-about-geth-snapshot-acceleration/) which not all clients implement.
+
+You can read more in the article posted above why snap sync replaced fast sync in Geth.
+
+## What is wrong with my light client? {#light-client}
+
+Light sync relies on full nodes that serve data to light clients. Historically, this has been hampered by the fact that serving light clients was turned off by default in geth full nodes and few nodes chose to turn it on. Therefore, light nodes often struggled to find peers. Since Ethereum switched to proof-of-stake, Geth light clients have stopped working altogether. Light clients for proof-of-stake Ethereum are expected to be implemented soon!
+
+## Why do I need another client in addition to Geth? {#consensus-client}
+
+Historically, running Geth was enough to turn a computer into an Ethereum node. However, when Ethereum transitioned to proof-of-stake, responsibility for consensus logic and block gossip was handed over to a separate consensus layer client. However, Geth still handles transactions and state management. When the consensus client is required to create a new block, it requests Geth to gather transactions from the transaction pool, execute them to compute a state transition and pass this information back to the consensus client. When the consensus client receives a new block from a peer, it passes the transactions to Geth to re-execute to verify the proposed state-transition. There is a clear separationm of concerns between the two clients, meaning that both are required for a computer function as an Ethereum node.
+
+## What is staking and how do I participate? {#what-is-staking}
+
+Staking is how node operators participate in proof-of-stake based consensus. Staking requires validators to deposit 32 ETH to a smart contract and run validator software connected to their node. The validator software broadcasts a vote ("attestation") in favour of checkpoint blocks that it determines to be in the canonical blockchain. The corrct chain is then the one with the greatest accumulation of votes, weighted by the validators stake (up to a maximum of 32 ETH). Geth, as an execution client, does not directly handle consensus logic but it does provide the node with the execution and state-management tools required to validate incoming blocks. Validators are also occasionally picked to propose the next block broadcast across the network. In this case Geth's role is to bundle transactions it has received over the execution layer gossip network, pass them to the consensus client to be included in the block and execute them to determine the resulting state change.
+
+It is entirely possible to run a node without staking any ETH. In this case the node runs the execution and consensus clients but not the validator software. In order to participate in consensus and earn ETH rewards, the node must run an execution cleint, consensus client and a validator. The validator software comes bundled with the consensus client.
+
+For step-by-step instruction for staking and spinning up a validating node, see [ethereum.org](https://ethereum.org/en/staking/) or get started on the Ethereum Foundation's [Staking Launchpad](https://launchpad.ethereum.org/).
+
+## How do I set up a consensus client/validator and connect it to Geth? {#how-to-set-up-consensus-client}
+
+These docs mainly cover how to set up Geth, but since the switch to proof-of-stake it is also necessary to run a consensus client in order to track the head of the chain, and a validator in order to participate in proof-of-stake consensus. A validator node is also required to deposit 32 ETH into a specific smart contract. Our [consensus clients page](/docs/getting-started/consensus-clients) includes a general overview of how to connect a consensus client to Geth. For step by step instructions for specific clients, see their documentation and also see these helpful [online guides](https://github.com/SomerEsat/ethereum-staking-guides).
+
+## How do I update Geth? {#how-to-update-geth}
+
+Updating Geth to the latest version simply requires stopping the node, downloading the latest release and restarting the node. Precisely how to download the latest software depends on the installation method - please refer to our [Installation pages](/docs/getting-started/installing-geth).

docs/fundamentals/account-management.md

@@ -0,0 +1,230 @@
+---
+title: Account Management with Clef
+description: Guide to basic account management using Geth's built-in tools
+---
+
+Geth uses an external signer called [Clef](/docs/tools/clef/introduction) to manage accounts. This is a standalone piece of software that runs independently of - but connects to - a Geth instance. Clef handles account creation, key management and signing transactions/data. This page explains how to use Clef to create and manage accounts for use with Geth. More information about Clef, including advanced setup options, are available in our dedicated Clef docs.
+
+## Initialize Clef {#initializing-clef}
+
+The first time Clef is used it needs to be initialized with a master seed that unlocks Clef's secure vault and a path where the vault should be located. Clef will use the vault to store passwords for keystores, javascript auto-signing rules and hashes of rule files. To initialize Clef, pass a vault path to `clef init`, for example to store it in a new directory inside `/home/user/go-ethereum`:
+
+```sh
+clef init /home/user/go-ethereum/clefdata
+```
+
+It is extremely important to remember the master seed and keep it secure. It allows access to the accounts under Clef's management.
+
+## Connecting Geth and Clef {#connecting-geth-and-clef}
+
+Clef and Geth should be started separately but with complementary configurations so that they can communicate. This requires Clef to know the `chain_id` of the network Geth will connect to so that this information can be included in any signatures. Clef also needs to know the location of the keystore where accounts are (or will be) stored. This is usually in a subdirectory inside Geth's data directory. Clef is also given a data directory which is also often placed conveniently inside Geth's data directory. To enable communication with Clef using Curl, `--http` can be passed which will start an HTTP server on `localhost:8550` by default. To start Clef configured for a Geth node connecting to the Sepolia testnet:
+
+```sh
+clef --chainid 11155111 --keystore ~/.go-ethereum/sepolia-data/keystore --configdir ~/go-ethereum/sepolia-data/clef --http
+```
+
+Clef will start running in the terminal, beginning with a disclaimer and a prompt to click "ok":
+
+```terminal
+WARNING!
+
+Clef is an account management tool. It may, like any software, contain bugs.
+
+Please take care to
+- backup your keystore files,
+- verify that the keystore(s) can be opened with your password.
+
+Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See the GNU General Public License for more details.
+
+Enter 'ok' to proceed:
+>
+```
+
+Geth can be started in a separate terminal. To connect to Clef, ensure the data directory is consistent with the path provided to Clef and pass the location of the the Clef IPC file - which Clef saves to the path provided to its `--configdir` flag - in this case we set it to `~/go-ethereum/sepolia-data/clef`:
+
+```sh
+geth --sepolia --datadir sepolia <other flags> --signer=sepolia-data/clef/clef.ipc
+```
+
+Remember that it is also necessary to have a consensus client running too, which requires `--http` and several `authrpc` values to be provided to Geth. A complete set of startup commands for the Geth-Lodestar client combinaton plus Clef is provided as an example in this [Gist](https://gist.github.com/jmcook1186/ea5de9215ecedb1b0105bcfa9c30d44c) - adapt it for different client combinations and configurations.
+
+## Interacting with Clef {#interacting-with-clef}
+
+There are two modes of interaction with Clef. One is direct interaction, which is achieved by passing requests by HTTP or IPC with JSON-RPC data as defined in Clef's external API. This is the way to do things in Clef that don't require Geth, such as creating and listing accounts, or signing data offline. The other way is via Geth. With Geth started with Clef as an external signer, requests made to Geth that touch account data will route via Clef for approval. By default, the user approves or denies interactions manually by typing `y` or `n` into the Clef console when prompted, but custom rules can also be created to automate common tasks.
+
+### Creating accounts {#creating-accounts}
+
+New accounts can be created using Clef's `account new` method. This generates a new key pair and adds them to the given `keystore` directory:
+
+```sh
+clef newaccount --keystore sepolia-data/keystore
+```
+
+Clef will request the new password in the terminal.
+
+The same can be achieved using raw JSON requests (this example send the request to Clef's exposed HTTP port using curl):
+
+```sh
+curl -X POST --data '{"id": 0, "jsonrpc": "2.0", "method": "account_new", "params": []}' http://localhost:8550 -H "Content-Type: application/json"
+```
+
+The console will hang because Clef is waiting for manual approval. Switch to the Clef terminal and approve the action. Clef will prompt for a account password and then confirm the account creation in the terminal logs. A new keyfile has been added to the keystore in `go-ethereum/sepolia-data`. A JSON response is returned to the terminal the request originated from, containing the new account address in the `result` field.
+
+```terminal
+{"jsonrpc": "2.0", "id": 0, "result": "0x168bc315a2ee09042d83d7c5811b533620531f67"}
+```
+
+It is critical to backup the account password safely and securely as it cannot be retrieved or reset.
+
+<Note>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**</Note>
+
+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`
+
+An account can also be created by importing a raw private key (hex string) using `clef importraw` as follows:
+
+```sh
+clef importraw <hexkey>
+```
+
+The terminal will respond with the following message, indicating the account has been created successfully:
+
+```terminal
+## Info
+Key imported:
+  Address 0x9160DC9105f7De5dC5E7f3d97ef11DA47269BdA6
+  Keystore file: /home/user/.ethereum/keystore/UTC--2022-10-28T12-03-13.976383602Z--9160dc9105f7de5dc5e7f3d97ef11da47269bda6
+
+The key is now encrypted; losing the password will result in permanently losing
+access to the key and all associated funds!
+
+Make sure to backup keystore and passwords in a safe location.
+```
+
+### Listing accounts {#listing-accounts}
+
+The accounts in the keystore can be listed to the terminal using a simple CLI command as follows:
+
+```sh
+clef list-accounts --keystore <path-to-keystore>
+```
+
+or using `account_list` in a POST request as follows:
+
+```sh
+curl -X POST --data '{"id": 0, "jsonrpc": "2.0", "method": "account_list", "params": []}' http://localhost:8550 -H "Content-Type: application/json"
+```
+
+This returns a JSON object with the account addresses in an array in the `result` field.
+
+```terminal
+{"jsonrpc": "2.0", "id": 0, "result": ["0x168bc315a2ee09042d83d7c5811b533620531f67", "0x0b85e5a13e118466159b1e1b6a4234e5f9f784bb"]}
+```
+
+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.
+
+Accounts can also be listed in the Javascript console using `eth.accounts`, which will defer to Clef for approval.
+
+As well as individual account, any wallets managed by Clef can be listed (which will also print the wallet status and the address and URl of any accounts they contain. This uses the `list-wallets` CLI command.
+
+```sh
+clef list-wallets --keystore <path-to-keystore>
+```
+
+which returns:
+
+```terminal
+- Wallet 0 at keystore:///home/user/Code/go-ethereum/testdata/keystore/UTC--2022-11-01T17-05-01.517877299Z--4f4094babd1a8c433e0f52a6ee3b6ff32dee6a9c (Locked )
+  - Account 0: 0x4f4094BaBd1A8c433e0f52A6ee3B6ff32dEe6a9c (keystore:///home/user/go-ethereum/testdata/keystore/UTC--2022-11-01T17-05-01.517877299Z--4f4094babd1a8c433e0f52a6ee3b6ff32dee6a9c)
+- Wallet 1 at keystore:///home/user/go-ethereum/testdata/keystore/UTC--2022-11-01T17-05-11.100536003Z--8ef15919f852a8034688a71d8b57ab0187364009 (Locked )
+  - Account 0: 0x8Ef15919F852A8034688a71d8b57Ab0187364009 (keystore:///home/user/go-ethereum/testdata/keystore/UTC--2022-11-01T17-05-11.100536003Z--8ef15919f852a8034688a71d8b57ab0187364009)
+```
+
+### Import a keyfile {#importing-a-keyfile}
+
+It is also possible to create an account by importing an existing 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. It is possible to do this using Clef, but currently the method is not externally exposed and requires implementing a UI. There is a Python UI on the Geth GitHub that could be used as an example or it can be done using the default console UI. However, for now the most straightforward way to import an accoutn from a private key is to use Geth's `account import`.
+
+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!
+
+```sh
+$ 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 users 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.
+
+```sh
+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:
+
+```sh
+chmod 700 /path/to/password
+cat > /path/to/password
+<type password here>
+```
+
+### Import a presale wallet {#import-presale-wallet}
+
+Assuming the password is known, importing a presale wallet is very easy. Geth's `wallet import` commands are used, passing the path to the wallet.
+
+```sh
+geth wallet import /path/presale.wallet
+```
+
+## Updating accounts {#updating-accounts}
+
+Clef can be used to set and remove passwords for an existing keystore file. To set a new password, pass the account address to `setpw`:
+
+```sh
+clef setpw a94f5374fce5edbc8e2a8697c15331677e6ebf0b
+```
+
+This will cause Clef to prompt for a new password, twice, and then the Clef master password to decrypt the keyfile.
+
+Geth's `account update` subcommand can also be used to update the account password:
+
+```sh
+geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b
+```
+
+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:
+
+```sh
+geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b --password path/password.txt
+```
+
+Updating the account using `geth account update` replaces the original file with a new one - this means the original file is no longer available after it has been updated. This can be used to update a key file to the latest format.
+
+## Unlocking accounts {#unlocking-accounts}
+
+With Clef, indiscriminate account unlocking is no longer a feature. Instead, Clef unlocks are locked until actions are explicitly approved manually by a user, unless they conform to some specific scenario that has been encoded in a ruleset. Please refer to our Clef docs for instructions for how to create rulesets.
+
+### Transactions {#transactions}
+
+Transactions can be sent using raw JSON requests to Geth or using `web3js` in the Javascript console. Either way, with Clef acting as the signer the transactions will not get sent until approval is given in Clef. The following code snippet shows how a transaction could be sent between two accounts in the keystore using the Javascript console.
+
+```sh
+var tx = {from: eth.accounts[1], to: eth.accounts[2], value: web3.toWei(5, "ether")}
+
+# this will hang until approval is given in the Clef console
+eth.sendTransaction(tx)
+```
+
+## Summary {#summary}
+
+This page has demonstrated how to manage accounts using Clef and Geth's account management tools. Accounts are stored encrypted by a password. It is critical that the account passwords and the keystore directory are safely and securely backed up.

docs/fundamentals/backup-restore.md

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

docs/fundamentals/command-line-options.md

@@ -0,0 +1,242 @@
+---
+title: Command-line Options
+description: A list of commands for Geth
+---
+
+Geth is primarily controlled using the command line. Geth is started using the `geth` command. Geth is stopped by pressing `ctrl-c`. There are then many combinations of commands that configure precisely how geth will run. These commands are displayed below. The same information can be obtained at any time from your Geth instance by running:
+
+```sh
+geth --help
+```
+
+## Commands {#commands}
+
+```sh
+NAME:
+   geth - the go-ethereum command line interface
+
+   Copyright 2013-2022 The go-ethereum Authors
+
+USAGE:
+   geth [options] [command] [command options] [arguments...]
+
+VERSION:
+   1.10.19-stable-23bee162
+
+COMMANDS:
+   account                            Manage accounts
+   attach                             Start an interactive JavaScript environment (connect to node)
+   console                            Start an interactive JavaScript environment
+   db                                 Low level database operations
+   dump                               Dump a specific block from storage
+   dumpconfig                         Show configuration values
+   dumpgenesis                        Dumps genesis block JSON configuration to stdout
+   export                             Export blockchain into file
+   export-preimages                   Export the preimage database into an RLP stream
+   import                             Import a blockchain file
+   import-preimages                   Import the preimage database from an RLP stream
+   init                               Bootstrap and initialize a new genesis block
+   js                                 Execute the specified JavaScript files
+   license                            Display license information
+   makecache                          Generate ethash verification cache (for testing)
+   makedag                            Generate ethash mining DAG (for testing)
+   removedb                           Remove blockchain and state databases
+   show-deprecated-flags              Show flags that have been deprecated
+   snapshot                           A set of commands based on the snapshot
+   version                            Print version numbers
+   version-check                      Checks (online) whether the current version suffers from any known security vulnerabilities
+   wallet                             Manage Ethereum presale wallets
+   help, h                            Shows a list of commands or help for one command
+
+ETHEREUM OPTIONS:
+  --config value                      TOML configuration file
+  --datadir.minfreedisk value         Minimum free disk space in MB, once reached triggers auto shut down (default = --cache.gc converted to MB, 0 = disabled)
+  --keystore value                    Directory for the keystore (default = inside the datadir)
+  --usb                               Enable monitoring and management of USB hardware wallets
+  --pcscdpath value                   Path to the smartcard daemon (pcscd) socket file
+  --networkid value                   Explicitly set network id (integer)(For testnets: use --sepolia, --goerli instead) (default: 1)
+  --syncmode value                    Blockchain sync mode ("snap", "full" or "light") (default: snap)
+  --exitwhensynced                    Exits after block synchronisation completes
+  --gcmode value                      Blockchain garbage collection mode ("full", "archive") (default: "full")
+  --txlookuplimit value               Number of recent blocks to maintain transactions index for (default = about one year, 0 = entire chain) (default: 2350000)
+  --ethstats value                    Reporting URL of a ethstats service (nodename:secret@host:port)
+  --identity value                    Custom node name
+  --lightkdf                          Reduce key-derivation RAM & CPU usage at some expense of KDF strength
+  --eth.requiredblocks value          Comma separated block number-to-hash mappings to require for peering (<number>=<hash>)
+  --mainnet                           Ethereum mainnet
+  --goerli                            Görli network: pre-configured proof-of-authority test network
+  --sepolia                           Sepolia network: pre-configured proof-of-work test network
+  --datadir value                     Data directory for the databases and keystore (default: "~/.ethereum")
+  --datadir.ancient value             Data directory for ancient chain segments (default = inside chaindata)
+  --remotedb value                    URL for remote database
+
+LIGHT CLIENT OPTIONS:
+  --light.serve value                 Maximum percentage of time allowed for serving LES requests (multi-threaded processing allows values over 100) (default: 0)
+  --light.ingress value               Incoming bandwidth limit for serving light clients (kilobytes/sec, 0 = unlimited) (default: 0)
+  --light.egress value                Outgoing bandwidth limit for serving light clients (kilobytes/sec, 0 = unlimited) (default: 0)
+  --light.maxpeers value              Maximum number of light clients to serve, or light servers to attach to (default: 100)
+  --ulc.servers value                 List of trusted ultra-light servers
+  --ulc.fraction value                Minimum % of trusted ultra-light servers required to announce a new head (default: 75)
+  --ulc.onlyannounce                  Ultra light server sends announcements only
+  --light.nopruning                   Disable ancient light chain data pruning
+  --light.nosyncserve                 Enables serving light clients before syncing
+
+DEVELOPER CHAIN OPTIONS:
+  --dev                               Ephemeral proof-of-authority network with a pre-funded developer account, mining enabled
+  --dev.period value                  Block period to use in developer mode (0 = mine only if transaction pending) (default: 0)
+  --dev.gaslimit value                Initial block gas limit (default: 11500000)
+
+ETHASH OPTIONS:
+  --ethash.cachedir value             Directory to store the ethash verification caches (default = inside the datadir)
+  --ethash.cachesinmem value          Number of recent ethash caches to keep in memory (16MB each) (default: 2)
+  --ethash.cachesondisk value         Number of recent ethash caches to keep on disk (16MB each) (default: 3)
+  --ethash.cacheslockmmap             Lock memory maps of recent ethash caches
+  --ethash.dagdir value               Directory to store the ethash mining DAGs (default: "~/.ethash")
+  --ethash.dagsinmem value            Number of recent ethash mining DAGs to keep in memory (1+GB each) (default: 1)
+  --ethash.dagsondisk value           Number of recent ethash mining DAGs to keep on disk (1+GB each) (default: 2)
+  --ethash.dagslockmmap               Lock memory maps for recent ethash mining DAGs
+
+TRANSACTION POOL OPTIONS:
+  --txpool.locals value               Comma separated accounts to treat as locals (no flush, priority inclusion)
+  --txpool.nolocals                   Disables price exemptions for locally submitted transactions
+  --txpool.journal value              Disk journal for local transaction to survive node restarts (default: "transactions.rlp")
+  --txpool.rejournal value            Time interval to regenerate the local transaction journal (default: 1h0m0s)
+  --txpool.pricelimit value           Minimum gas price limit to enforce for acceptance into the pool (default: 1)
+  --txpool.pricebump value            Price bump percentage to replace an already existing transaction (default: 10)
+  --txpool.accountslots value         Minimum number of executable transaction slots guaranteed per account (default: 16)
+  --txpool.globalslots value          Maximum number of executable transaction slots for all accounts (default: 5120)
+  --txpool.accountqueue value         Maximum number of non-executable transaction slots permitted per account (default: 64)
+  --txpool.globalqueue value          Maximum number of non-executable transaction slots for all accounts (default: 1024)
+  --txpool.lifetime value             Maximum amount of time non-executable transaction are queued (default: 3h0m0s)
+
+PERFORMANCE TUNING OPTIONS:
+  --cache value                       Megabytes of memory allocated to internal caching (default = 4096 mainnet full node, 128 light mode) (default: 1024)
+  --cache.database value              Percentage of cache memory allowance to use for database io (default: 50)
+  --cache.trie value                  Percentage of cache memory allowance to use for trie caching (default = 15% full mode, 30% archive mode) (default: 15)
+  --cache.trie.journal value          Disk journal directory for trie cache to survive node restarts (default: "triecache")
+  --cache.trie.rejournal value        Time interval to regenerate the trie cache journal (default: 1h0m0s)
+  --cache.gc value                    Percentage of cache memory allowance to use for trie pruning (default = 25% full mode, 0% archive mode) (default: 25)
+  --cache.snapshot value              Percentage of cache memory allowance to use for snapshot caching (default = 10% full mode, 20% archive mode) (default: 10)
+  --cache.noprefetch                  Disable heuristic state prefetch during block import (less CPU and disk IO, more time waiting for data)
+  --cache.preimages                   Enable recording the SHA3/keccak preimages of trie keys
+  --fdlimit value                     Raise the open file descriptor resource limit (default = system fd limit) (default: 0)
+
+ACCOUNT OPTIONS:
+  --unlock value                      Comma separated list of accounts to unlock
+  --password value                    Password file to use for non-interactive password input
+  --signer value                      External signer (url or path to ipc file)
+  --allow-insecure-unlock             Allow insecure account unlocking when account-related RPCs are exposed by http
+
+API AND CONSOLE OPTIONS:
+  --ipcdisable                        Disable the IPC-RPC server
+  --ipcpath value                     Filename for IPC socket/pipe within the datadir (explicit paths escape it)
+  --http                              Enable the HTTP-RPC server
+  --http.addr value                   HTTP-RPC server listening interface (default: "localhost")
+  --http.port value                   HTTP-RPC server listening port (default: 8545)
+  --http.api value                    API's offered over the HTTP-RPC interface
+  --http.rpcprefix value              HTTP path path prefix on which JSON-RPC is served. Use '/' to serve on all paths.
+  --http.corsdomain value             Comma separated list of domains from which to accept cross origin requests (browser enforced)
+  --http.vhosts value                 Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default: "localhost")
+  --ws                                Enable the WS-RPC server
+  --ws.addr value                     WS-RPC server listening interface (default: "localhost")
+  --ws.port value                     WS-RPC server listening port (default: 8546)
+  --ws.api value                      API's offered over the WS-RPC interface
+  --ws.rpcprefix value                HTTP path prefix on which JSON-RPC is served. Use '/' to serve on all paths.
+  --ws.origins value                  Origins from which to accept websockets requests
+  --authrpc.jwtsecret value           Path to a JWT secret to use for authenticated RPC endpoints
+  --authrpc.addr value                Listening address for authenticated APIs (default: "localhost")
+  --authrpc.port value                Listening port for authenticated APIs (default: 8551)
+  --authrpc.vhosts value              Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default: "localhost")
+  --graphql                           Enable GraphQL on the HTTP-RPC server. Note that GraphQL can only be started if an HTTP server is started as well.
+  --graphql.corsdomain value          Comma separated list of domains from which to accept cross origin requests (browser enforced)
+  --graphql.vhosts value              Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default: "localhost")
+  --rpc.gascap value                  Sets a cap on gas that can be used in eth_call/estimateGas (0=infinite) (default: 50000000)
+  --rpc.evmtimeout value              Sets a timeout used for eth_call (0=infinite) (default: 5s)
+  --rpc.txfeecap value                Sets a cap on transaction fee (in ether) that can be sent via the RPC APIs (0 = no cap) (default: 1)
+  --rpc.allow-unprotected-txs         Allow for unprotected (non EIP155 signed) transactions to be submitted via RPC
+  --jspath loadScript                 JavaScript root path for loadScript (default: ".")
+  --exec value                        Execute JavaScript statement
+  --preload value                     Comma separated list of JavaScript files to preload into the console
+
+NETWORKING OPTIONS:
+  --bootnodes value                   Comma separated enode URLs for P2P discovery bootstrap
+  --discovery.dns value               Sets DNS discovery entry points (use "" to disable DNS)
+  --port value                        Network listening port (default: 30303)
+  --maxpeers value                    Maximum number of network peers (network disabled if set to 0) (default: 50)
+  --maxpendpeers value                Maximum number of pending connection attempts (defaults used if set to 0) (default: 0)
+  --nat value                         NAT port mapping mechanism (any|none|upnp|pmp|extip:<IP>) (default: "any")
+  --nodiscover                        Disables the peer discovery mechanism (manual peer addition)
+  --v5disc                            Enables the experimental RLPx V5 (Topic Discovery) mechanism
+  --netrestrict value                 Restricts network communication to the given IP networks (CIDR masks)
+  --nodekey value                     P2P node key file
+  --nodekeyhex value                  P2P node key as hex (for testing)
+
+MINER OPTIONS:
+  --mine                              Enable mining
+  --miner.threads value               Number of CPU threads to use for mining (default: 0)
+  --miner.notify value                Comma separated HTTP URL list to notify of new work packages
+  --miner.notify.full                 Notify with pending block headers instead of work packages
+  --miner.gasprice value              Minimum gas price for mining a transaction (default: 1000000000)
+  --miner.gaslimit value              Target gas ceiling for mined blocks (default: 30000000)
+  --miner.etherbase value             Public address for block mining rewards (default = first account) (default: "0")
+  --miner.extradata value             Block extra data set by the miner (default = client version)
+  --miner.recommit value              Time interval to recreate the block being mined (default: 3s)
+  --miner.noverify                    Disable remote sealing verification
+
+GAS PRICE ORACLE OPTIONS:
+  --gpo.blocks value                  Number of recent blocks to check for gas prices (default: 20)
+  --gpo.percentile value              Suggested gas price is the given percentile of a set of recent transaction gas prices (default: 60)
+  --gpo.maxprice value                Maximum transaction priority fee (or gasprice before London fork) to be recommended by gpo (default: 500000000000)
+  --gpo.ignoreprice value             Gas price below which gpo will ignore transactions (default: 2)
+
+VIRTUAL MACHINE OPTIONS:
+  --vmdebug                           Record information useful for VM and contract debugging
+
+LOGGING AND DEBUGGING OPTIONS:
+  --fakepow                           Disables proof-of-work verification
+  --nocompaction                      Disables db compaction after import
+  --verbosity value                   Logging verbosity: 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail (default: 3)
+  --vmodule value                     Per-module verbosity: comma-separated list of <pattern>=<level> (e.g. eth/*=5,p2p=4)
+  --log.json                          Format logs with JSON
+  --log.backtrace value               Request a stack trace at a specific logging statement (e.g. "block.go:271")
+  --log.debug                         Prepends log messages with call-site location (file and line number)
+  --pprof                             Enable the pprof HTTP server
+  --pprof.addr value                  pprof HTTP server listening interface (default: "127.0.0.1")
+  --pprof.port value                  pprof HTTP server listening port (default: 6060)
+  --pprof.memprofilerate value        Turn on memory profiling with the given rate (default: 524288)
+  --pprof.blockprofilerate value      Turn on block profiling with the given rate (default: 0)
+  --pprof.cpuprofile value            Write CPU profile to the given file
+  --trace value                       Write execution trace to the given file
+
+METRICS AND STATS OPTIONS:
+  --metrics                              Enable metrics collection and reporting
+  --metrics.expensive                    Enable expensive metrics collection and reporting
+  --metrics.addr value                   Enable stand-alone metrics HTTP server listening interface (default: "127.0.0.1")
+  --metrics.port value                   Metrics HTTP server listening port (default: 6060)
+  --metrics.influxdb                     Enable metrics export/push to an external InfluxDB database
+  --metrics.influxdb.endpoint value      InfluxDB API endpoint to report metrics to (default: "http://localhost:8086")
+  --metrics.influxdb.database value      InfluxDB database name to push reported metrics to (default: "geth")
+  --metrics.influxdb.username value      Username to authorize access to the database (default: "test")
+  --metrics.influxdb.password value      Password to authorize access to the database (default: "test")
+  --metrics.influxdb.tags value          Comma-separated InfluxDB tags (key/values) attached to all measurements (default: "host=localhost")
+  --metrics.influxdbv2                   Enable metrics export/push to an external InfluxDB v2 database
+  --metrics.influxdb.token value         Token to authorize access to the database (v2 only) (default: "test")
+  --metrics.influxdb.bucket value        InfluxDB bucket name to push reported metrics to (v2 only) (default: "geth")
+  --metrics.influxdb.organization value  InfluxDB organization name (v2 only) (default: "geth")
+
+ALIASED (deprecated) OPTIONS:
+  --nousb                             Disables monitoring for and managing USB hardware wallets (deprecated)
+  --whitelist value                   Comma separated block number-to-hash mappings to enforce (<number>=<hash>) (deprecated in favor of --eth.requiredblocks)
+
+MISC OPTIONS:
+  --snapshot                                Enables snapshot-database mode (default = enable)
+  --bloomfilter.size value                  Megabytes of memory allocated to bloom-filter for pruning (default: 2048)
+  --ignore-legacy-receipts                  Geth will start up even if there are legacy receipts in freezer
+  --help, -h                                show help
+  --override.grayglacier value              Manually specify Gray Glacier fork-block, overriding the bundled setting (default: 0)
+  --override.terminaltotaldifficulty value  Manually specify TerminalTotalDifficulty, overriding the bundled setting (default: <nil>)
+
+
+COPYRIGHT:
+   Copyright 2013-2022 The go-ethereum Authors
+```

docs/fundamentals/index.md

@@ -0,0 +1,27 @@
+---
+title: Geth fundamentals
+description: Documentation for foundational Geth topics
+---
+
+This section includes documentation for foundational topics in Geth. The pages here will help you to understand how Geth works from a user perspective and under the hood.
+
+This is where you will find information about how to manage a Geth node and understand how it functions.
+
+For example, the pages here will help you to understand the underlying architecture of your Geth node, how to start it in different configurations using command line options, how to sync the blockchain and how to manage accounts. There is a page on security practices that will help you to keep your Geth node safe from adversaries.
+
+Note also that there is a page explaining common log messages that are often queried on the Geth discord and GitHub - this will help users to interpret the messages displayed to the console and know what actions to take.
+
+## In this section
+
+- [Node architecture](/docs/fundamentals/node-architecture): learn about the three components of an Ethereum node and how they fit together
+- [Command line options](/docs/fundamentals/command-line-options): see the various command line options that can be used to configure Geth
+- [Security](/docs/fundamentals/security): learn about basic security best-practises for Geth
+- [Sync-modes](/docs/fundamentals/sync-modes): learn about the different ways Geth can sync the blockchain
+- [Account management](/docs/fundamentals/account-management): read about how to manage accounts using Clef and Geth
+- [Backup and restore](/docs/fundamentals/backup-restore): learn how to backup and restore data for a Geth instance
+- [Logs](/docs/fundamentals/logs): learn how to interpret the main log messages Geth displays in the console
+- [Peer-to-peer](/docs/fundamentals/peer-to-peer): learn about Geth's peer-to-peer networking
+- [Pruning](/docs/fundamentals/pruning): read about Geth's data pruning options
+- [Private networks](/docs/fundamentals/private-network): learn hoe to set up a private network of multiple Geth nodes
+- [Light clients](/docs/fundamentals/les): read about Geth's light mode.
+- [Mining](/docs/fundamentals/mining): read about the minign algorithms Geth used to use to secure Ethereum before the network switched to proof-of-stake.

docs/fundamentals/les.md

@@ -0,0 +1,64 @@
+---
+title: Light client
+description: Introduction to Geth's light sync mode
+---
+
+<Note>Light nodes do not currently work on proof-of-stake Ethereum, but new proof-of-stake light clients are expected to ship soon!</Note>
+
+Running a full node is the most trustless, private, decentralized and censorship resistant way to interact with Ethereum. It is also the best choice for the health of the network, because a decentralized network relies on having many individual nodes that independently verify the head of the chain. In a full node a copy of the blockchain is stored locally enabling users to verify incoming data against a local source of truth. However, running a full node requires a lot of disk space and non-negligible CPU allocation and takes hours (for snap sync) or days (for full sync) to sync the blockchain from genesis. Geth also offers a light mode that overcomes these issues and provides some of the benefits of running a node but requires only a fraction of the resources.
+
+Read more about the reasons to run nodes on [ethereum.org](https://ethereum.org/en/run-a-node/).
+
+<Note>Geth light clients **do not currently work** on proof-of-stake Ethereum. New light clients that work with the proof-of-stake consensus engine are expected to ship soon!</Note>
+
+## Light node vs full node {#light-node-vs-full-node}
+
+Running Geth in light mode has the following advantages for users:
+
+- Syncing takes minutes rather than hours/days
+- Light mode uses significantly less storage
+- Light mode is lighter on CPU and other resources
+- Light mode is suitable for resource-constrained devices
+- Light mode can catch up much quicker after having been offline for a while
+
+However, the cost of this performance increase is that a light Geth node depends heavily on full-node peers that choose, for altruistic reasons, to run light servers. There is no monetary incentive for full nodes to run light servers and it is an opt-in, rather than opt-out function of a Geth full node. For those reasons light servers are rather rare and can quickly become overwhelmed by data requests from light clients. The result of this is that **Geth nodes run in light mode often struggle to find peers**.
+
+A light client can be used to query data from Ethereum and submit transactions, acting as a locally-hosted Ethereum wallet. However they have different security guarantees than full nodes. Because they don't keep local copies of the Ethereum state, light nodes can't validate the blocks in the same way as the full nodes. Instead they fetch block headers by requesting them from full nodes and check their proof-of-work (PoW), assuming the heaviest chain is valid. This means that it is sensible to wait until a few additional blocks have been confirmed before trusting the validity of a recently-mined transaction.
+
+### Running a light server {#running-light-server}
+
+Full node operators that choose to enable light serving altruistically enable other users to run light clients. This is good for Ethereum because it makes it easier for a wider population of users to interact with Ethereum without using trusted intermediaries. However, there is naturally a limit to how much resource a node operator is able and willing to dedicate to serving light clients. Therefore, the command that enables light serving requires arguments that define the upper bound on resource allocation. The value given is in percent of a processing thread, for example `--light.serve 300` enables light-serving and dedicates three processing threads to it.
+
+Recent versions of Geth (>`1.9.14`) unindex older transactions to save disk space. Indexing is required for looking up transactions in Geth's database. Therefore, unindexing limits the data that can be requested by light clients. This unindexing can be disabled by adding `--tx.txlookuplimit 0` to make the maximum data available to light clients.
+
+The whole command for starting Geth with a light server could look as follows:
+
+```sh
+geth --light.serve 50 --txlookuplimit 0
+```
+
+### Running a light client {#running-light-client}
+
+Running a light client simply requires Geth to be started in light mode. It is likely that a user would also want to interact with the light node using, for example, RPC. This can be enabled using the `--http` command.
+
+```sh
+geth --syncmode light --http --http.api "eth,debug"
+```
+
+Data can be requested from this light Geth instance in the same way as for a full node (i.e. using the [JSON-RPC-API](/docs/interacting-with-geth/rpc/) using tools such as [Curl](https://curl.se/) or Geth's [Javascript console](/docs/interacting-with-geth/javascript-console)). Instead of fetching the data from a local database as in a full node, the light Geth instance requests the data from full-node peers.
+
+It's also possible to send transactions. However, light clients are not connected directly to Ethereum Mainnet but to a network of light servers that connect to Ethereum Mainnet. This means a transaction submitted by a light client is received first by a light server that then propagates it to full-node peers on the light-client's behalf. This reliance on honest light-servers is one of the trust compromises that comes along with running a light node instead of a full node.
+
+### Ultra light clients {#ultra-light-client}
+
+Geth has an even lighter sync mode called ultra light client (ULC). The difference between light mode and ultra-light mode is that a ULC doesn't check the PoW in block headers. There is an assumption that the ULC has access to one or more trusted light servers. This option has the greatest trust assumptions but the smallest resource requirement.
+
+To start an ultra-light client, the enode addresses of the trusted light servers must be passed to the `--ulc.servers` command and the sync mode is `light`:
+
+```sh
+geth --syncmode light --ulc.servers "enode://...,enode://..." --http --http.api "eth,debug"
+```
+
+## Summary {#summary}
+
+Running a full node is the most trustless way to interact with Ethereum. However, Geth provides a low-resource "light" mode that can be run on modest computers and requires much less disk space. The trade-offs are additional trust assumptions and a small pool of light-serving peers to connect to.

docs/fundamentals/logs.md

@@ -0,0 +1,217 @@
+---
+title: Geth logs
+description: Geth's log messages explained
+---
+
+A Geth node continually reports messages to the console allowing users to monitor Geth's current status in real-time. The logs indicate when Geth is running normally and indicates when some attention is required. However, reading these logs can be difficult for new users. This page will help to interpret the log messages to better understand what Geth is doing.
+
+Note that there are a large number of log messages covering a wide range of possible scenarios for a Geth node. This page will only address a subset of commonly seen messages. For more, see the [Geth GitHub](https://github.com/ethereum/go-ethereum), [Discord](https://discord.gg/WHNkYDsAKU) or search on [ethereum.stackexchange](https://ethereum.stackexchange.com/). Log messages are usually sufficiently self-descrining that they do not require additional explanation.
+
+## Configuring log messages {#configuring-log-messages}
+
+Log messages are displayed to the console by default. The messages can be tuned to be more or less detailed by passing `--verbosity` and a value between 0 and 6 to Geth at startup:
+
+```sh
+0 = silent (no log messages)
+1 = error (error messages only)
+2 = warn (error messages and warnings only)
+3 = info (error messages, warnings and normal activity logs)
+4 = debug (all info plus additional messages for debugging)
+5 = detail (all info plus detailed debugging messages)
+```
+
+The default is `--verbosity 3`.
+
+Log messages can also be redirected so they are saved to a text file instead of being displayed in the console. In Linux the syntax `>> <path> 2>&1` redirects both `stdout` and `stderr` messages to `<path>`. For example:
+
+```sh
+# saves detailed logs to path/eth.log
+geth --verbosity 5 >> /path/eth.log 2>&1
+```
+
+### Startup {#startup}
+
+When Geth starts up it immediately reports a fairly long page of configuration details and status reports that allow the user to confirm Geth is on the right network and operating in its intended modes. The basic structure of a log message is as follows:
+
+```sh
+MESSAGE_TYPE [MONTH-DAY][TIME] MESSAGE VALUE
+```
+
+Where `MESSAGE_TYPE` can be `INFO`, `WARN`, `ERROR` or `DEBUG`. These tags categorize log messages according to their purpose. `INFO` messages inform the user about Geth's current configuration and status. `WARN` messages are for alerting the user to details that affect the way Geth is running. `ERROR` messages are for alerting the user to problems. `DEBUG` is for messages that are relevant to troubleshooting or for developers working on Geth.
+
+The messages displayed on startup break down as follows:
+
+```terminal
+INFO [10-04|10:20:52.028] Starting Geth on Ethereum mainnet...
+INFO [10-04|10:20:52.028] Bumping default cache on mainnet         provided=1024 updated=4096
+INFO [10-04|10:20:52.030] Maximum peer count                       ETH=50 LES=0 total=50
+INFO [10-04|10:20:52.031] Smartcard socket not found, disabling    err="stat /run/pcscd/pcscd.comm: no such file or directory"
+INFO [10-04|10:20:52.034] Set global gas cap                       cap=50,000,000
+INFO [10-04|10:20:52.035] Allocated trie memory caches             clean=614.00MiB dirty=1024.00MiB
+INFO [10-04|10:20:52.035] Allocated cache and file handles         database=/home/go-ethereum/devnet/geth/chaindata cache=2.00GiB handles=524,288
+INFO [10-04|10:20:52.128] Opened ancient database                  database=/home/go-ethereum/devnet/geth/chaindata/ancient/chain readonly=false
+INFO [10-04|10:20:52.129] Disk storage enabled for ethash caches   dir=/home/go-ethereum/devnet/geth/ethash count=3
+INFO [10-04|10:20:52.129] Disk storage enabled for ethash DAGs     dir=/home/.ethash                        count=2
+INFO [10-04|10:20:52.129] Initialising Ethereum protocol           network=1 dbversion=<nil>
+INFO [10-04|10:20:52.129] Writing default main-net genesis block
+INFO [10-04|10:20:52.372] Persisted trie from memory database      nodes=12356 size=1.78MiB time=21.535537ms gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B
+```
+
+The logs above show the user that the node is connecting to Ethereum Mainnet and some low level configuration details. The cache size is bumped to the Mainnet default (4096). The maximum peer count is the highest number of peers this node is allowed to connect to and can be used to control the bandwidth requirements of the node. Logs relating to `ethash` are out of date since Ethereum moved to proof-of-stake based consensus and can safely be ignored.
+
+```terminal
+---------------------------------------------------------------------------------------------------------------------------------------------------------
+INFO [10-04|10:20:52.386] Chain ID:  1 (mainnet)
+INFO [10-04|10:20:52.386] Consensus: Beacon (proof-of-stake), merged from Ethash (proof-of-work)
+INFO [10-04|10:20:52.386]
+INFO [10-04|10:20:52.386] Pre-Merge hard forks:
+INFO [10-04|10:20:52.386]  - Homestead:                   1150000  (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/homestead.md)
+INFO [10-04|10:20:52.386]  - DAO Fork:                    1920000  (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/dao-fork.md)
+INFO [10-04|10:20:52.386]  - Tangerine Whistle (EIP 150): 2463000  (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/tangerine-whistle.md)
+INFO [10-04|10:20:52.386]  - Spurious Dragon/1 (EIP 155): 2675000  (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/spurious-dragon.md)
+INFO [10-04|10:20:52.386]  - Spurious Dragon/2 (EIP 158): 2675000  (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/spurious-dragon.md)
+INFO [10-04|10:20:52.386]  - Byzantium:                   4370000  (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/byzantium.md)
+INFO [10-04|10:20:52.386]  - Constantinople:              7280000  (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/constantinople.md)
+INFO [10-04|10:20:52.386]  - Petersburg:                  7280000  (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/petersburg.md)
+INFO [10-04|10:20:52.386]  - Istanbul:                    9069000  (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/istanbul.md)
+INFO [10-04|10:20:52.387]  - Muir Glacier:                9200000  (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/muir-glacier.md)
+INFO [10-04|10:20:52.387]  - Berlin:                      12244000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/berlin.md)
+INFO [10-04|10:20:52.387]  - London:                      12965000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/london.md)
+INFO [10-04|10:20:52.387]  - Arrow Glacier:               13773000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/arrow-glacier.md)
+INFO [10-04|10:20:52.387]  - Gray Glacier:                15050000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/gray-glacier.md)
+```
+
+The above block of messages are related to past Ethereum hard forks. The names are the names of the hard forks and the numbers are the blocks at which the hard fork occurs. This means that blocks with numbers that exceed these values have the configuration required by that hard fork. The specification of each hard fork is available at the provided links (and more information is available on [ethereum.org](https://ethereum.org/en/history/)). The message `Consensus: Beacon (proof-of-stake), merged from Ethash (proof-of-work)` indicates that the node requires a Beacon node to follow the canonical chain - Geth cannot participate in consensus on its own.
+
+```terminal
+INFO [10-04|10:20:52.387] Merge configured:
+INFO [10-04|10:20:52.387]  - Hard-fork specification:    https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/paris.md
+INFO [10-04|10:20:52.387]  - Network known to be merged: true
+INFO [10-04|10:20:52.387]  - Total terminal difficulty:  58750000000000000000000
+INFO [10-04|10:20:52.387]  - Merge netsplit block:       <nil>
+INFO [10-04|10:20:52.387]
+INFO [10-04|10:20:52.388] Chain post-merge, sync via beacon client
+WARN [10-04|10:20:52.388] Engine API enabled                       protocol=eth
+---------------------------------------------------------------------------------------------------------------------------------------------------------
+```
+
+The messages above relate to [The Merge](https://ethereum.org/en/upgrades/merge/). The Merge was Ethereum's transition from proof-of-work to proof-of-stake based consensus. In Geth, The Merge came in the form of the Paris hard fork which was triggered at a [terminal total difficulty](https://ethereum.org/en/glossary/#terminal-total-difficulty) of 58750000000000000000000 instead of a preconfigured block number like previous hard forks. The hard fork specification is linked in the log message. The message `network known to be merged: true` indicates that the node is following a chain that has passed the terminal total difficulty and undergone the Paris hard fork. Since September 15 2022 this will always be true for nodes on Ethereum Mainnet (and the merged testnets Sepolia and Goerli). The warning `Engine API enabled` informs the user that Geth is exposing the set of API methods required for communication with a consensus client.
+
+```terminal
+INFO [10-04|10:20:52.389] Starting peer-to-peer node               instance=Geth/v1.11.0-unstable-e004e7d2-20220926/linux-amd64/go1.19.1
+INFO [10-04|10:20:52.409] New local node record                    seq=1,664,875,252,408 id=9aa0e5b14ccd75ec ip=127.0.0.1 udp=30303 tcp=30303
+INFO [10-04|10:20:52.409] Started P2P networking                   self=enode://1ef45ab610c2893b70483bf1791b550e5a93763058b0abf7c6d9e6201e07212d61c4896d64de07342c9df734650e3b40812c2dc01f894b6c385acd180ed30fc8@127.0.0.1:30303
+INFO [10-04|10:20:52.410] IPC endpoint opened                      url=/home/go-ethereum/devnet/geth.ipc
+INFO [10-04|10:20:52.410] Generated JWT secret                     path=/home/go-ethereum/devnet/geth/jwtsecret
+INFO [10-04|10:20:52.411] HTTP server started                      endpoint=127.0.0.1:8545 auth=false prefix= cors= vhosts=localhost
+INFO [10-04|10:20:52.411] WebSocket enabled                        url=ws://127.0.0.1:8551
+INFO [10-04|10:20:52.411] HTTP server started                      endpoint=127.0.0.1:8551 auth=true  prefix= cors=localhost vhosts=localhost
+INFO [10-04|10:20:54.785] New local node record                    seq=1,664,875,252,409 id=9aa0e5b14ccd75ec ip=82.11.59.221 udp=30303 tcp=30303
+INFO [10-04|10:20:55.267] Mapped network port                      proto=udp extport=30303 intport=30303 interface="UPNP IGDv1-IP1"
+INFO [10-04|10:20:55.833] Mapped network port                      proto=tcp extport=30303 intport=30303 interface="UPNP IGDv1-IP1"
+INFO [10-04|10:21:03.100] Looking for peers                        peercount=0 tried=20 static=0
+```
+
+The logs above relate to Geth starting up its peer-to-peer components and seeking other nodes to connect to. The long address reported to `Started P2P networking` is the nodes own enode address. The `IPC Endpoint` is the location of the node's IPC file that can be used to connect a Javascript console. There is a log message confirming that a JWT secret was generated and reporting its path. This is required to authenticate communication between Geth and the consensus client. There are also messages here reporting on the HTTP server that can be used to send requests to Geth. There should be two HTTP servers - one for interacting with Geth (defaults to `localhost:8545`) and one for communication with the consensus client (defaults to `localhost:8551`).
+
+### Syncing {#syncing}
+
+The default for Geth is to sync in snap mode. This requires a block header to be provided to Geth by the consensus client. The header is then used as a target to sync to. Geth requests block headers from its peers that are parents of the target until there is a continuous chain of sequential headers of sufficient length. Then, Geth requests block bodies and receipts for each header and simultaneously starts downloading state data. This state data is stored in the form of a [Patricia Merkle Trie](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie/). Only the leaves of the trie are downloaded, the full trie structure is then locally regenerated from the leaves up. Meanwhile, the blockchain continues to progress and the target header is updated. This means some of the regenerated state data needs to be updated. This is known as _healing_.
+
+Assuming Geth has a synced consensus client and some peers it will start importing headers, block bodies and receipts. The log messages for data downloading look as follows:
+
+```terminal
+INFO [07-28|10:29:49.681] Block synchronisation started
+INFO [07-28|10:29:50.427] Imported new block headers               count=1    elapsed=253.434ms number=12,914,945 hash=ee1a08..9ce38a
+INFO [07-28|10:30:00.224] Imported new block receipts              count=64   elapsed=13.703s   number=12,914,881 hash=fef964..d789fc age=18m5s     size=7.69MiB
+INFO [07-28|10:30:18.658] Imported new block headers               count=1    elapsed=46.715ms  number=12,914,946 hash=7b24c8..2d8006
+INFO [07-28|10:30:21.665] Imported new state entries
+```
+
+For state sync, Geth reports when the state heal is in progress. This can take a long time. The log message includes values for the number of `accounts`, `slots`, `codes` and `nodes` that were downloaded in the current healing phase, and the pending field is the number of state entires waiting to be downloaded. The `pending` value is not necessarily the number of state entries remaining until the healing is finished. As the blockchain progresses the state trie is updated and therefore the data that needs to be downloaded to heal the trie can increase as well as decrease over time. Ultimately, the state should heal faster than the blockchain progresses so the node can get in sync. When the state healing is finished there is a post-sync snapshot generation phase. The node is not in sync until the state healing phase is over. If the node is still regularly reporting `State heal in progress` it is not yet in sync - the state healing is still ongoing.
+
+```terminal
+INFO [07-28|10:30:21.965] State heal in progress                   accounts=169,633@7.48MiB  slots=57314@4.17MiB    codes=4895@38.14MiB nodes=43,293,196@11.70GiB pending=112,626
+INFO [09-06|01:31:59.885] Rebuilding state snapshot
+INFO [09-06|01:31:59.910] Resuming state snapshot generation root=bc64d4..fc1edd accounts=0 slots=0 storage=0.00B dangling=0 elapsed=18.838ms
+```
+
+The sync can be confirmed using [`eth.syncing`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_syncing) - it will return `false` if the node is in sync. If `eth.syncing` returns anything other than `false` it has not finished syncing. Generally, if syncing is still ongoing, `eth.syncing` will return block info that looks as follows:
+
+```json
+> eth.sycing
+{
+  currentBlock: 15285946,
+  healedBytecodeBytes: 991164713,
+  healedBytecodes: 130880,
+  healedTrienodeBytes: 489298493475,
+  healedTrienodes: 1752917331,
+  healingBytecode: 0,
+  healingTrienodes: 1745,
+  highestBlock: 16345003,
+  startingBlock: 12218525,
+  syncedAccountBytes: 391561544809,
+  syncedAccounts: 136498212,
+  syncedBytecodeBytes: 2414143936,
+  syncedBytecodes: 420599,
+  syncedStorage: 496503178,
+  syncedStorageBytes: 103368240246
+}
+```
+
+There are other log messages that are commonly seen during syncing. For example:
+
+```sh
+WARN [09-28|11:06:01.363] Snapshot extension registration failed
+```
+
+This warning is nothing to worry about - it is reporting a configuration mismatch between the node and a peer. It does not mean syncing is stalling or failing, it simply results in the peer being dropped and replaced.
+
+```sh
+# consensus client has identified a new head to use as a sync target - account for this in state sync
+INFO [10-03|15:34:01.336] Forkchoice requested sync to new head    number=15,670,037 hash=84d4ec..4c0e2b
+```
+
+The message above indicates that the fork choice algorithm, which is run by the consensus client, has identified a new target Geth should sync up to. This redirects the sync to prevent syncing to an outdated target and is a natural part of syncing a live blockchain.
+
+## Transaction logs {#transaction-logs}
+
+Transactions submitted over local IPC, Websockets or HTTP connections are reported in the console logs. For example, a simple ETH transaction appears in the console logs as follows:
+
+```sh
+INFO [09-06|01:31:59.910] Submitted transaction             hash=0x2893b70483bf1791b550e5a93763058b0abf7c6d9e6201e07212dbc64d4764532 from: 0xFB48587362536C606d6e89f717Fsd229673246e6 nonce: 43 recipient: 0x7C60662d63536e89f717F9673sd22246F6eB4858 value: 100,000,000,000,000,000
+```
+
+Other user actions have similar log messages that are displayed to the console.
+
+## Common warnings {#common-warnings}
+
+There are many warnings that can be emitted by Geth as part of its normal operation. However, some are asked about especially frequently on the [Geth GitHub](https://github.com/ethereum/go-ethereum) and [Discord](https://discord.gg/WHNkYDsAKU) channel.
+
+```sh
+WARN [10-03|18:00:40.413] Unexpected trienode heal packet          peer=9f0e8fbf         reqid=6,915,308,639,612,522,441
+```
+
+The above is often seen and misinterpreted as a problem with snap sync. In reality, it indicates a request timeout that may be because I/O speed is low. It is usually not an issue, but if this message is seen very often over prolonged periods of time it might be rooted in a local connectivity or hardware issue.
+
+```sh
+WARN [10-03|13:10:26.441] Post-merge network, but no beacon client seen. Please launch one to follow the chain!
+```
+
+The above message is emitted when Geth is run without a consensus client on a post-merge proof-of-stake network. Since Ethereum moved to proof-of-stake Geth alone is not enough to follow the chain because the consensus logic is now implemented by a separate piece of software called a consensus client. This log message is displayed when the consensus client is missing. Read more about this on our [consensus clients](/docs/getting-started/consensus-clients) page.
+
+```sh
+WARN [10-03 |13:10:26.499] Beacon client online, but never received consensus updates. Please ensure your beacon client is operational to follow the chain!
+```
+
+The message above indicates that a consensus client is present but not working correctly. The most likely reason for this is that the client is not yet in sync. Waiting for the consensus client to sync should solve the issue.
+
+```sh
+WARN [10-03 | 13:15:56.543] Dropping unsynced node during sync    id = e2fdc0d92d70953 conn = ...
+```
+
+This message indicates that a peer is being dropped because it is not fully synced. This is normal - the necessary data will be requested from an alternative peer instead.
+
+## Summary {#summary}
+
+There are a wide range of log messages that are emitted while Geth is running. The level of detail in the logs can be configured using the `verbosity` flag at startup. This page has outlined some of the common messages users can expect to see when Geth is run with default verbosity, without attempting to be comprehensive. For more, please see the [Geth GitHub](https://github.com/ethereum/go-ethereum) and [Discord](https://discord.gg/WHNkYDsAKU).

docs/fundamentals/mining.md

@@ -0,0 +1,180 @@
+---
+title: Proof-of-work mining with Ethash
+description: Introduction to proof-of-work mining with Geth
+---
+
+<Note>Proof-of-work mining is no longer used to secure Ethereum Mainnet. The information below is included because the Ethash code is still part of Geth and it could be used to create a private proof-of-work network or testnet.</Note>
+
+Blockchains grow when individual nodes create valid blocks and distribute them to their peers who check the blocks and add them to their own local databases.
+Nodes that add blocks are rewarded with ether payouts. On Ethereum Mainnet, the proof-of-stake consensus engine randomly selects a node to produce each block.
+
+Ethereum wasn't always secured this way. Originally, a proof-of-work based consensus mechanism was used instead. Under proof-of-work, block producers are not selected randomly in each slot. Instead they compete for the right to add a block. The node that is fastest to compute a certain value that can only be found using brute force calculations is the one that gets to add a block. 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 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-algorithms/ethash).
+
+## CPU vs GPU {#cpu-vs-gpu}
+
+Ethereum mining used 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. Everything required to mine on a CPU is bundled with Geth. However, to mine using GPUs an additional piece of third-party software is required. The most commonly used 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 outdated side chain,meaning block rewards will not be recognized by the main network.
+
+## GPU Mining {#gpu-mining}
+
+### Installing Ethminer {#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 {#using-ethminer}
+
+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/fundamentals/account-management) 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.
+
+```sh
+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/interacting-with-geth/javascript-console) page. To attach and open a console:
+
+```sh
+geth attach http://127.0.0.1:8545
+```
+
+Then in the console, to check the sync progress:
+
+```sh
+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 synced, 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:
+
+```sh
+#OpenCL
+ethminer -v 9 -G -P http://127.0.0.1:8545
+```
+
+```sh
+#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 {#cpu-mining-with-geth}
+
+When Geth is started it 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).
+
+```sh
+geth --mine --miner.threads=4
+```
+
+CPU mining can also be started and stopped at runtime using the [console](/docs/interacting-with-geth/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 only makes sense if you are in sync with the network (since you mine on top of the consensus block). Therefore the blockchain downloader/synchroniser will delay mining until syncing is complete, and after that mining automatically starts unless you cancel 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:
+
+```sh
+geth --miner.etherbase '0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10' --mine
+```
+
+If there is no account available an account wil be created and automatically configured to be the coinbase. The Javascript console can be used to reset the etherbase account at runtime:
+
+```sh
+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.
+
+```sh
+miner.setExtra("ΞTHΞЯSPHΞЯΞ")
+```
+
+The console can also be used to check the current hashrate in units H/s (Hash operations per second):
+
+```sh
+eth.hashrate
+ 712000
+```
+
+After some blocks have been mined, the etherbase account balance with be >0. Assuming the etherbase is a local account:
+
+```sh
+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 if a mined block is 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 {#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. Mining is **no longer used to secure Ethereum Mainnet**.

docs/fundamentals/node-architecture.md

@@ -0,0 +1,30 @@
+---
+title: Node architecture
+description: Introduction to how Ethereum nodes are organized and where Geth fits.
+---
+
+An Ethereum node is composed of two clients: an [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) and a [consensus client](https://ethereum.org/en/developers/docs/nodes-and-clients/#consensus-clients). Geth is an [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients). Originally, an execution client alone was enough to run a full Ethereum node. However, ever since Ethereum turned off [proof-of-work](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/) and implemented [proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/), Geth has needed to be coupled to another piece of software called a [“consensus client”](https://ethereum.org/en/developers/docs/nodes-and-clients/#consensus-clients) in order to keep track of the Ethereum blockchain.
+
+The execution client (Geth) is responsible for transaction handling, transaction gossip, state management and supporting the Ethereum Virtual Machine [EVM](https://ethereum.org/en/developers/docs/evm/). However, Geth is **not** responsible for block building, block gossiping or handling consensus logic. These are in the remit of the consensus client.
+
+The relationship between the two Ethereum clients is shown in the schematic below. The two clients each connect to their own respective peer-to-peer (P2P) networks. This is because the execution clients gossip transactions over their P2P network enabling them to manage their local transaction pool. The consensus clients gossip blocks over their P2P network, enabling consensus and chain growth.
+
+![node-architecture](/images/docs/node-architecture-text-background.png)
+
+For this two-client structure to work, consensus clients must be able to pass bundles of transactions to Geth to be executed. Executing the transactions locally is how the client validates that the transactions do not violate any Ethereum rules and that the proposed update to Ethereum’s state is correct. Likewise, when the node is selected to be a block producer the consensus client must be able to request bundles of transactions from Geth to include in the new block. This inter-client communication is handled by a local RPC connection using the [engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md).
+
+## What does Geth do? {#what-does-geth-do}
+
+As an execution client, Geth is responsible for creating the execution payloads - the list of transactions, updated state trie plus other execution related data - that consensus clients include in their blocks. Geth is also responsible for re-executing transactions that arrive in new blocks to ensure they are valid. Executing transactions is done on Geth's embedded computer, known as the Ethereum Virtual Machine (EVM).
+
+Geth also offers a user-interface to Ethereum by exposing a set of [RPC methods](/docs/interacting-with-geth/rpc/) that enable users to query the Ethereum blockchain, submit transactions and deploy smart contracts. Often, the RPC calls are abstracted by a library such as [Web3js](https://web3js.readthedocs.io/en/v1.8.0/) or [Web3py](https://web3py.readthedocs.io/en/v5/) for example in Geth's built-in Javascript console, development frameworks or web-apps.
+
+## What does the consensus client do? {#consensus-client}
+
+The consensus client deals with all the logic that enables a node to stay in sync with the Ethereum network. This includes receiving blocks from peers and running a fork choice algorithm to ensure the node always follows the chain with the greatest accumulation of attestations (weighted by validator effective balances). The consensus client has its own peer-to-peer network, separate from the network that connects execution clients to each other. The consensus clients share blocks and attestations over their peer-to-peer network. The consensus client itself does not participate in attesting to or proposing blocks - this is done by a validator which is an optional add-on to a consensus client. A consensus client without a validator only keeps up with the head of the chain, allowing the node to stay synced. This enables a user to transact with Ethereum using their execution client, confident that they are on the right chain.
+
+## Validators {#validators}
+
+Validators can be added to consensus clients if 32 ETH have been sent to the deposit contract. The validator client comes bundled with the consensus client and can be added to a node at any time. The validator handles attestations and block proposals. They enable a node to accrue rewards or lose ETH via penalties or slashing. Running the validator software also makes a node eligible to be selected to propose a new block.
+
+Read more about [proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/).

docs/fundamentals/peer-to-peer.md

@@ -0,0 +1,157 @@
+---
+title: Connecting To The Network
+description: Guide to connecting Geth to a peer-to-peer network
+---
+
+The default behaviour for Geth is to connect to Ethereum Mainnet. However, Geth can also connect to public testnets, [private networks](/docs/developers/geth-developer/private-network) and [local testnets](/docs/developers/geth-developer/dev-mode). For convenience, the two public testnets with long term support, Goerli and Sepolia, have their own command line flag. Geth can connect to these testnets simply by passing:
+
+- `--goerli`, Goerli proof-of-authority test network
+- `--sepolia` Sepolia proof-of-work test network
+
+These testnets started as proof-of-work and proof-of-authority testnets, but they were transitioned to proof-of-stake in 2022 in preparation for doing the same to Ethereum Mainnet. This means that to run a node on Goerli or Sepolia it is now necessary to run a consensus client connected to Geth. This is also true for Ethereum Mainnet. **Geth does not work on proof-of-stake networks without a consensus client**! The remainder of this page will assume that Geth is connected to a consensus client that is synced to the desired network. For instructions on how to set up a consensus client please see the [Consensus Clients](/docs/getting-started/consensus-clients) page.
+
+**Note:** Network selection is not persisted from a config file. To connect to a pre-defined network you must always enable it explicitly, even when using the `--config` flag to load other configuration values. For example:
+
+```sh
+# Generate desired config file. You must specify testnet here.
+geth --goerli --syncmode "full" ... dumpconfig > goerli.toml
+
+# Start geth with given config file. Here too the testnet must be specified.
+geth --goerli --config goerli.toml
+```
+
+## Finding peers {#finding-peers}
+
+Geth continuously attempts to connect to other nodes on the network until it has enough peers. If UPnP (Universal Plug and Play) is enabled at the router or Ethereum is run on an Internet-facing server, it will also accept connections from other nodes. Geth finds peers using the [discovery protocol](https://ethereum.org/en/developers/docs/networking-layer/#discovery). In the discovery protocol, nodes exchange connectivity details and then establish sessions ([RLPx](https://github.com/ethereum/devp2p/blob/master/rlpx.md)). If the nodes support compatible sub-protocols they can start exchanging Ethereum data [on the wire](https://ethereum.org/en/developers/docs/networking-layer/#wire-protocol).
+
+A new node entering the network for the first time gets introduced to a set of peers by a bootstrap node ("bootnode") whose sole purpose is to connect new nodes to peers. The endpoints for these bootnodes are hardcoded into Geth, but they can also be specified by providing the `--bootnode` flag along with comma-separated bootnode addresses in the form of [enodes](https://ethereum.org/en/developers/docs/networking-layer/network-addresses/#enode) on startup. For example:
+
+```sh
+geth --bootnodes enode://pubkey1@ip1:port1,enode://pubkey2@ip2:port2,enode://pubkey3@ip3:port3
+```
+
+There are scenarios where disabling the discovery process is useful, for example for running a local test node or an experimental test network with known, fixed nodes. This can be achieved by passing the `--nodiscover` flag to Geth at startup.
+
+## Connectivity problems {#connectivity-problems}
+
+There are occasions when Geth simply fails to connect to peers. The common reasons for this are:
+
+- Local time might be incorrect. An accurate clock is required to participate in the Ethereum network. The local clock can be resynchronized using commands such as `sudo ntpdate -s time.nist.gov` (this will vary depending on operating system).
+
+- Some firewall configurations can prohibit UDP traffic. The static nodes feature or `admin.addPeer()` on the console can be used to configure connections manually.
+
+- Running Geth in [light mode](/docs/fundamentals/les) often leads to connectivity issues because there are few nodes running light servers. There is no easy fix for this except to switch Geth out of light mode. **Note that light mode does not curently work on proof-of-stake networks**.
+
+- The public test network Geth is connecting to might be deprecated or have a low number of active nodes that are hard to find. In this case, the best action is to switch to an alternative test network.
+
+## Checking Connectivity {#checking-connectivity}
+
+The `net` module has two attributes that enable checking node connectivity from the [interactive Javascript console](/docs/interacting-with-geth/javascript-console). These are `net.listening` which reports whether the Geth node is listening for inbound requests, and `peerCount` which returns the number of active peers the node is connected to.
+
+```js
+> net.listening
+true
+
+> net.peerCount
+4
+```
+
+Functions in the `admin` module provide more information about the connected peers, including their IP address, port number, supported protocols etc. Calling `admin.peers` returns this information for all connected peers.
+
+```sh
+> admin.peers
+[{
+  ID: 'a4de274d3a159e10c2c9a68c326511236381b84c9ec52e72ad732eb0b2b1a2277938f78593cdbe734e6002bf23114d434a085d260514ab336d4acdc312db671b',
+  Name: 'Geth/v0.9.14/linux/go1.4.2',
+  Caps: 'eth/60',
+  RemoteAddress: '5.9.150.40:30301',
+  LocalAddress: '192.168.0.28:39219'
+}, {
+  ID: 'a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c',
+  Name: 'Geth/v0.9.15/linux/go1.4.2',
+  Caps: 'eth/60',
+  RemoteAddress: '52.16.188.185:30303',
+  LocalAddress: '192.168.0.28:50995'
+}, {
+  ID: 'f6ba1f1d9241d48138136ccf5baa6c2c8b008435a1c2bd009ca52fb8edbbc991eba36376beaee9d45f16d5dcbf2ed0bc23006c505d57ffcf70921bd94aa7a172',
+  Name: 'pyethapp_dd52/v0.9.13/linux2/py2.7.9',
+  Caps: 'eth/60, p2p/3',
+  RemoteAddress: '144.76.62.101:30303',
+  LocalAddress: '192.168.0.28:40454'
+}, {
+  ID: 'f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0',
+  Name: '++eth/Zeppelin/Rascal/v0.9.14/Release/Darwin/clang/int',
+  Caps: 'eth/60, shh/2',
+  RemoteAddress: '129.16.191.64:30303',
+  LocalAddress: '192.168.0.28:39705'
+} ]
+
+```
+
+The `admin` module also includes functions for gathering information about the local node rather than its peers. For example, `admin.nodeInfo` returns the name and connectivity details for the local node.
+
+```sh
+> admin.nodeInfo
+{
+  Name: 'Geth/v0.9.14/darwin/go1.4.2',
+  NodeUrl: 'enode://3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694@[::]:30303',
+  NodeID: '3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694',
+  IP: '::',
+  DiscPort: 30303,
+  TCPPort: 30303,
+  Td: '2044952618444',
+  ListenAddr: '[::]:30303'
+}
+```
+
+## Custom Networks {#custom-networks}
+
+It is often useful for developers to connect to private test networks rather than public testnets or Ethereum mainnet. These sandbox environments allow block creation without competing against other miners, easy minting of test ether and give freedom to break things without real-world consequences. A private network is started by providing a value to `--networkid` that is not used by any other existing public network ([Chainlist](https://chainlist.org)) and creating a custom `genesis.json` file. Detailed instructions for this are available on the [Private Networks page](/docs/developers/geth-developer/private-network).
+
+## Static nodes {#static-nodes}
+
+Geth also supports static nodes. Static nodes are specific peers that are always connected to. Geth reconnects to these peers automatically when it is restarted. Specific nodes are defined to be static nodes by adding their enode addresses to a config file. The easiest way to create this config file is to run:
+
+```sh
+geth --datadir <datadir> dumpconfig > config.toml
+```
+
+This will create `config.toml` in the current directory. The enode addresses for static nodes can then be added as a list to the `StaticNodes` field of the `Node.P2P` section in `config.toml`. When Geth is started, pass `--config config.toml`. The relevant line in `config.toml` looks as follows:
+
+```toml
+StaticNodes = ["enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303"]
+```
+
+Ensure the other lines in `config.toml` are also set correctly before starting Geth, as passing `--config` instructs Geth to get its configuration values from this file. An example of a complete `config.toml` file can be found [here](https://gist.github.com/jmcook1186/16db2f0feddb4bd0581ebb9ba867a47a).
+
+Static nodes can also be added at runtime in the Javascript console by passing an enode address to `admin.addPeer()`:
+
+```js
+admin.addPeer(
+  'enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303'
+);
+```
+
+## Peer limit {#peer-limit}
+
+It is sometimes desirable to cap the number of peers Geth will connect to in order to limit on the computational and bandwidth cost associated with running a node. By default, the limit is 50 peers, however, this can be updated by passing a value to `--maxpeers`:
+
+```sh
+geth <otherflags> --maxpeers 15
+```
+
+## Trusted nodes {#trusted-nodes}
+
+Trusted nodes can be added to `config.toml` in the same way as for static nodes. Add the trusted node's enode address to the `TrustedNodes` field in `config.toml` before starting Geth with `--config config.toml`.
+
+Nodes can be added using the `admin.addTrustedPeer()` call in the Javascript console and removed using `admin.removeTrustedPeer()` call.
+
+```js
+admin.addTrustedPeer(
+  'enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303'
+);
+```
+
+## Summary {#summary}
+
+Geth connects to Ethereum Mainnet by default. However, this behaviour can be changed using combinations of command line flags and files. This page has described the various options available for connecting a Geth node to Ethereum, public testnets and private networks. Remember that to connect to a proof-of-stake network (e.g. Ethereum Mainnet, Goerli, Sepolia) a consensus client is also required.

docs/fundamentals/private-network.md

@@ -0,0 +1,459 @@
+---
+title: Private Networks
+description: Tutorial on setting up private Ethereum networks
+---
+
+This guide explains how to set up a private network of multiple Geth nodes. An Ethereum network is private if the nodes are not connected to the main network. In this context private only means reserved or isolated, rather than protected or secure. A fully controlled, private Ethereum network is useful as a backend for core developers working on issues relating to networking/blockchain syncing etc. Private networks are also useful for Dapp developers testing multi-block and multi-user scenarios.
+
+## Prerequisites {#prerequisites}
+
+To follow the tutorial on this page it is necessary to have a working Geth installation (instructions [here](/docs/getting-started/installing-geth)). It is also helpful to understand Geth fundamentals (see [Getting Started](/docs/getting-started)).
+
+## Private Networks {#private-networks}
+
+A private network is composed of multiple Ethereum nodes that can only connect to each other. In order to run multiple nodes locally, each one requires a separate data directory (`--datadir`). The nodes must also know about each other and be able to exchange information, share an initial state and a common consensus algorithm. The remainder of this page will explain how to configure Geth so that these basic requirements are met, enabling a private network to be started.
+
+### Choosing A Network ID {#choosing-network-id}
+
+Ethereum Mainnet has Network ID = 1. There are also many other networks that Geth can connect to by providing alternative Chain IDs, some are testnets and others are alternative networks built from forks of the Geth source code. Providing a network ID that is not already being used by an existing network or testnet means the nodes using that network ID can only connect to each other, creating a private network. A list of current network IDs is available at [Chainlist.org](https://chainlist.org/). The network ID is controlled using the `networkid` flag, e.g.
+
+```sh
+geth --networkid 12345
+```
+
+### Choosing A Consensus Algorithm {#choosing-a-consensus-mechanism}
+
+While the main network uses proof-of-stake (PoS) to secure the blockchain, Geth also supports the the 'Clique' proof-of-authority (PoA) consensus algorithm and the Ethash proof-of-work algorithm as alternatives for private networks. Clique is strongly recommended for private testnets because PoA is far less resource-intensive than PoW. The key differences between the consensus algorithms available in Geth are:
+
+#### Ethash {#ethash}
+
+Geth's PoW algorithm, [Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining-algorithms/ethash), is a system that allows open participation by anyone willing to dedicate resources to mining. While this is a critical property for a public network, the overall security of the blockchain strictly depends on the total amount of resources used to secure it. As such, PoW is a poor choice for private networks with few miners. The Ethash mining 'difficulty' is adjusted automatically so that new blocks are created approximately 12 seconds apart. As more mining resources are deployed on the network, creating a new block becomes harder so that the average block time matches the target block time.
+
+#### Clique {#clique}
+
+Clique consensus is a PoA system where new blocks can be created by authorized 'signers' only. The clique consenus protocol is specified in [EIP-225](https://eips.ethereum.org/EIPS/eip-225). The initial set of authorized signers is configured in the genesis block. Signers can be authorized and de-authorized using a voting mechanism, thus allowing the set of signers to change while the blockchain operates. Clique can be configured to target any block time (within reasonable limits) since it isn't tied to the difficulty adjustment.
+
+### Creating The Genesis Block {#creating-genesis-block}
+
+Every blockchain starts with a genesis block. When Geth is run with default settings for the first time, it commits the Mainnet genesis to the database. For a private network, it is generally preferable to use a different genesis block. The genesis block is configured using a _genesis.json_ file whose path must be provided to Geth on start-up. When creating a genesis block, a few initial parameters for the private blockchain must be defined:
+
+- Ethereum platform features enabled at launch (`config`). Enabling and disabling features once the blockchain is running requires scheduling a [hard fork](https://ethereum.org/en/glossary/#hard-fork).
+
+- Initial block gas limit (`gasLimit`). This impacts how much EVM computation can happen within a single block. Mirroring the main Ethereum network is generally a [good choice](https://etherscan.io/chart/gaslimit). The block gas limit can be adjusted after launch using the `--miner.gastarget` command-line flag.
+
+- Initial allocation of ether (`alloc`). This determines how much ether is available to the addresses listed in the genesis block. Additional ether can be created through mining as the chain progresses.
+
+#### Clique Example {#clique-example}
+
+Below is an example of a `genesis.json` file for a PoA network. The `config` section ensures that all known protocol changes are available and configures the 'clique' engine to be used for consensus. Note that the initial signer set must be configured through the `extradata` field. This field is required for Clique to work.
+
+The signer account keys can be generated using the [geth account](/docs/fundamentals/account-management) command (this command can be run multiple times to create more than one signer key).
+
+```sh
+geth account new --datadir data
+```
+
+The Ethereum address printed by this command should be recorded. To encode the signer addresses in `extradata`, concatenate 32 zero bytes, all signer addresses and 65 further zero bytes. The result of this concatenation is then used as the value accompanying the `extradata` key in `genesis.json`. In the example below, `extradata` contains a single initial signer address, `0x7df9a875a174b3bc565e6424a0050ebc1b2d1d82`.
+
+The `period` configuration option sets the target block time of the chain.
+
+```json
+{
+  "config": {
+    "chainId": 12345,
+    "homesteadBlock": 0,
+    "eip150Block": 0,
+    "eip155Block": 0,
+    "eip158Block": 0,
+    "byzantiumBlock": 0,
+    "constantinopleBlock": 0,
+    "petersburgBlock": 0,
+    "istanbulBlock": 0,
+    "berlinBlock": 0,
+    "clique": {
+      "period": 5,
+      "epoch": 30000
+    }
+  },
+  "difficulty": "1",
+  "gasLimit": "8000000",
+  "extradata": "0x00000000000000000000000000000000000000000000000000000000000000007df9a875a174b3bc565e6424a0050ebc1b2d1d820000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+  "alloc": {
+    "7df9a875a174b3bc565e6424a0050ebc1b2d1d82": { "balance": "300000" },
+    "f41c74c9ae680c1aa78f42e5647a62f353b7bdde": { "balance": "400000" }
+  }
+}
+```
+
+#### Ethash Example {#ethash-example}
+
+Since Ethash is the default consensus algorithm, no additional parameters need to be configured in order to use it. The initial mining difficulty is influenced using the `difficulty` parameter, but note that the difficulty adjustment algorithm will quickly adapt to the amount of mining resources deployed on the chain.
+
+```json
+{
+  "config": {
+    "chainId": 12345,
+    "homesteadBlock": 0,
+    "eip150Block": 0,
+    "eip155Block": 0,
+    "eip158Block": 0,
+    "byzantiumBlock": 0,
+    "constantinopleBlock": 0,
+    "petersburgBlock": 0,
+    "istanbulBlock": 0,
+    "berlinBlock": 0,
+    "ethash": {}
+  },
+  "difficulty": "1",
+  "gasLimit": "8000000",
+  "alloc": {
+    "7df9a875a174b3bc565e6424a0050ebc1b2d1d82": { "balance": "300000" },
+    "f41c74c9ae680c1aa78f42e5647a62f353b7bdde": { "balance": "400000" }
+  }
+}
+```
+
+### Initializing the Geth Database {#initializing-geth-database}
+
+To create a blockchain node that uses this genesis block, first use `geth init` to import and sets the canonical genesis block for the new chain. This requires the path to `genesis.json` to be passed as an argument.
+
+```sh
+geth init --datadir data genesis.json
+```
+
+When Geth is started using `--datadir data` the genesis block defined in `genesis.json` will be used. For example:
+
+```sh
+geth --datadir data --networkid 12345
+```
+
+### Scheduling Hard Forks {#scheduling-hard-forks}
+
+As Ethereum protocol development progresses, new features become available. To enable these features on an existing private network, a hard fork must be scheduled. To do this, a future block number must be chosen which determines precisely when the hard fork will activate. Continuing the `genesis.json` example above and assuming the current block number is 35421, a hard fork might be scheduled for block 40000. This hard fork might upgrade the network to conform to the 'London' specs. First, all the Geth instances on the private network must be recent enough to support the specific hard fork. If so, `genesis.json` can be updated so that the `londonBlock` key gets the value 40000. The Geth instances are then shut down and `geth init` is run to update their configuration. When the nodes are restarted they will pick up where they left off and run normally until block 40000, at which point they will automatically upgrade.
+
+The modification to `genesis.json` is as follows:
+
+```json
+{
+  "config": {
+    "londonBlock": 40000
+  }
+}
+```
+
+The upgrade command is:
+
+```sh
+geth init --datadir data genesis.json
+```
+
+### Setting Up Networking {#setting-up-networking}
+
+With the node configured and initialized, the next step is to set up a peer-to-peer network. This requires a bootstrap node. The bootstrap node is a normal node that is designated to be the entry point that other nodes use to join the network. Any node can be chosen to be the bootstrap node.
+
+To configure a bootstrap node, the IP address of the machine the bootstrap node will run on must be known. The bootsrap node needs to know its own IP address so that it can broadcast it to other nodes. On a local machine this can be found using tools such as `ifconfig` and on cloud instances such as Amazon EC2 the IP address of the virtual machine can be found in the management console. Any firewalls must allow UDP and TCP traffic on port 30303.
+
+The bootstrap node IP is set using the `--nat` flag (the command below contains an example address - replace it with the correct one).
+
+```sh
+geth --datadir data --networkid 15 --nat extip:172.16.254.4
+```
+
+The 'node record' of the bootnode can be extracted using the JS console:
+
+```sh
+geth attach data/geth.ipc --exec admin.nodeInfo.enr
+```
+
+This command should print a base64 string such as the following example. Other nodes will use the information contained in the bootstrap node record to connect to the peer-to-peer network.
+
+```text
+"enr:-Je4QEiMeOxy_h0aweL2DtZmxnUMy-XPQcZllrMt_2V1lzynOwSx7GnjCf1k8BAsZD5dvHOBLuldzLYxpoD5UcqISiwDg2V0aMfGhGlQhqmAgmlkgnY0gmlwhKwQ_gSJc2VjcDI1NmsxoQKX_WLWgDKONsGvxtp9OeSIv2fRoGwu5vMtxfNGdut4cIN0Y3CCdl-DdWRwgnZf"
+```
+
+If the nodes are intended to connect across the Internet, the bootnode and all other nodes must have public IP addresses assigned, and both TCP and UDP traffic can pass their firewalls. If Internet connectivity is not required or all member nodes connect using well-known IPs, Geth should be set up to restrict peer-to-peer connectivity to an IP subnet. Doing so will further isolate the network and prevents cross-connecting with other blockchain networks in case the nodes are reachable from the Internet. Use the
+`--netrestrict` flag to configure a whitelist of IP networks:
+
+```sh
+geth <other-flags> --netrestrict 172.16.254.0/24
+```
+
+With the above setting, Geth will only allow connections from the 172.16.254.0/24 subnet, and will not attempt to connect to other nodes outside of the set IP range.
+
+### Running Member Nodes {#running-member-nodes}
+
+Before running a member node, it must be initialized with the same genesis file as used for the bootstrap node. With the bootnode operational and externally reachable (`telnet <ip> <port>` will confirm that it is indeed reachable), more Geth nodes can be started and connected to them via the bootstrap node using the `--bootnodes` flag. The process is to start Geth on the same machine as the bootnode, with a separate data directory and listening port and the bootnode node record provided as an argument:
+
+For example, using data directory (example: `data2`) and listening port (example: `30305`):
+
+```sh
+geth --datadir data2 --networkid 12345 --port 30305 --bootnodes <bootstrap-node-record>
+```
+
+With the member node running, it is possible to check that it is connected to the bootstrap node or any other node in the network by attaching a console and running `admin.peers`. It may take up to a few seconds for the nodes to get connected.
+
+```sh
+geth attach data2/geth.ipc --exec admin.peers
+```
+
+### Running A Signer (Clique) {#running-a-signer}
+
+To set up Geth for signing blocks in Clique, a signer account must be available. The account must already be available as a keyfile in the keystore. To use it for signing blocks, it must be unlocked. The following command, for address `0x7df9a875a174b3bc565e6424a0050ebc1b2d1d82` will prompt for the account password, then start signing blocks:
+
+```sh
+geth <other-flags> --unlock 0x7df9a875a174b3bc565e6424a0050ebc1b2d1d82 --mine
+```
+
+Mining can be further configured by changing the default gas limit blocks converge to (with `--miner.gastarget`) and the price transactions are accepted at (with `--miner.gasprice`).
+
+### Running A Miner (Ethash) {#running-a-miner}
+
+For PoW in a simple private network, a single CPU miner instance is enough to create a stable stream of blocks at regular intervals. To start a Geth instance for mining, it can be run with all the usual flags plus the following to configure mining:
+
+```sh
+geth <other-flags> --mine --miner.threads=1 --miner.etherbase=0xf41c74c9ae680c1aa78f42e5647a62f353b7bdde
+```
+
+This will start mining bocks and transactions on a single CPU thread, crediting all block rewards to the account specified by `--miner.etherbase`.
+
+## End-to-end example {#end-to-end-example}
+
+This section will run through the commands for setting up a simple private network of two nodes. Both nodes will run on the local machine using the same genesis block and network ID. The data directories for each node will be named `node1` and `node2`.
+
+```sh
+`mkdir node1 node2`
+```
+
+Each node will have an associated account that will receive some ether at launch. The following command creates an account for Node 1:
+
+```sh
+geth --datadir node1 account new
+```
+
+This command returns a request for a password. Once a password has been provided the following information is returned to the terminal:
+
+```terminal
+Your new account is locked with a password. Please give a password. Do not foget this password.
+Password:
+Repeat password:
+
+Your new key was generated
+
+Public address of the key: 0xC1B2c0dFD381e6aC08f34816172d6343Decbb12b
+Path of the secret key file: node1/keystore/UTC--2022-05-13T14-25-49.229126160Z--c1b2c0dfd381e6ac08f34816172d6343decbb12b
+
+- 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!
+```
+
+The keyfile and account password should be backed up securely. These steps can then be repeated for Node 2. These commands create keyfiles that are stored in the `keystore` directory in `node1` and `node2` data directories. In order to unlock the accounts later the passwords for each account should be saved to a text file in each node's data directory.
+
+In each data directory save a copy of the following `genesis.json` to the top level project directory. The account addresses in the `alloc` field should be replaced with those created for each node in the previous step (without the leading `0x`).
+
+```json
+{
+  "config": {
+    "chainId": 12345,
+    "homesteadBlock": 0,
+    "eip150Block": 0,
+    "eip155Block": 0,
+    "eip158Block": 0,
+    "byzantiumBlock": 0,
+    "constantinopleBlock": 0,
+    "petersburgBlock": 0,
+    "istanbulBlock": 0,
+    "muirGlacierBlock": 0,
+    "berlinBlock": 0,
+    "londonBlock": 0,
+    "arrowGlacierBlock": 0,
+    "grayGlacierBlock": 0,
+    "clique": {
+      "period": 5,
+      "epoch": 30000
+    }
+  },
+  "difficulty": "1",
+  "gasLimit": "800000000",
+  "extradata": "0x00000000000000000000000000000000000000000000000000000000000000007df9a875a174b3bc565e6424a0050ebc1b2d1d820000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+  "alloc": {
+    "C1B2c0dFD381e6aC08f34816172d6343Decbb12b": { "balance": "500000" },
+    "c94d95a5106270775351eecfe43f97e8e75e59e8": { "balance": "500000" }
+  }
+}
+```
+
+The nodes can now be set up using `geth init` as follows:
+
+```sh
+geth init --datadir node1 genesis.json
+```
+
+This should be repeated for both nodes. The following will be returned to the terminal:
+
+```terminal
+INFO [05-13|15:41:47.520] Maximum peer count                       ETH=50 LES=0 total=50
+INFO [05-13|15:41:47.520] Smartcard socket not found, disabling    err="stat /run/pcscd/pcscd.comm: no such file or directory"
+INFO [05-13|15:41:47.520] Set global gas cap                       cap=50,000,000
+INFO [05-13|15:41:47.520] Allocated cache and file handles         database=/home/go-ethereum/node2/geth/chaindata cache=16.00MiB handles=16
+INFO [05-13|15:41:47.542] Writing custom genesis block
+INFO [05-13|15:41:47.542] Persisted trie from memory database      nodes=3 size=397.00B time="41.246µs" gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B
+INFO [05-13|15:41:47.543] Successfully wrote genesis state         database=chaindata hash=c9a158..d415a0
+INFO [05-13|15:41:47.543] Allocated cache and file handles         database=/home/go-ethereum/node2/geth/chaindata cache=16.00MiB handles=16
+INFO [05-13|15:41:47.556] Writing custom genesis block
+INFO [05-13|15:41:47.557] Persisted trie from memory database      nodes=3 size=397.00B time="81.801µs" gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B
+INFO [05-13|15:41:47.558] Successfully wrote genesis state         database=chaindata hash=c9a158..d415a0
+```
+
+The next step is to configure a bootnode. This can be any node, but for this tutorial the developer tool `bootnode` will be used to quickly and easily configure a dedicated bootnode. First the bootnode requires a key, which can be created with the following command, which will save a key to `boot.key`:
+
+```sh
+bootnode -genkey boot.key
+```
+
+This key can then be used to generate a bootnode as follows:
+
+```sh
+bootnode -nodekey boot.key -addr :30305
+```
+
+The choice of port passed to `-addr` is arbitrary, but public Ethereum networks use 30303, so this is best avoided. The `bootnode` command returns the following logs to the terminal, confirming that it is running:
+
+```terminal
+enode://f7aba85ba369923bffd3438b4c8fde6b1f02b1c23ea0aac825ed7eac38e6230e5cadcf868e73b0e28710f4c9f685ca71a86a4911461637ae9ab2bd852939b77f@127.0.0.1:0?discport=30305
+Note: you're using cmd/bootnode, a developer tool.
+We recommend using a regular node as bootstrap node for production deployments.
+INFO [05-13|15:50:03.645] New local node record                    seq=1,652,453,403,645 id=a2d37f4a7d515b3a ip=nil udp=0 tcp=0
+```
+
+The two nodes can now be started. Open separate terminals for each node, leaving the bootnode running in the original terminal. In each terminal, run the following command (replacing `node1` with `node2` where appropriate, and giving each node a different port ID. The account address and password file for node 1 must also be provided:
+
+```sh
+./geth --datadir node1 --port 30306 --bootnodes enode://f7aba85ba369923bffd3438b4c8fde6b1f02b1c23ea0aac825ed7eac38e6230e5cadcf868e73b0e28710f4c9f685ca71a86a4911461637ae9ab2bd852939b77f@127.0.0.1:0?discport=30305  --networkid 123454321 --unlock 0xC1B2c0dFD381e6aC08f34816172d6343Decbb12b --password node1/password.txt
+```
+
+This will start the node using the bootnode as an entry point. Repeat the same command with the information appropriate to node 2. In each terminal, the following logs indicate success:
+
+```terminal
+INFO [05-13|16:17:40.061] Maximum peer count                       ETH=50 LES=0 total=50
+INFO [05-13|16:17:40.061] Smartcard socket not found, disabling    err="stat /run/pcscd/pcscd.comm: no such file or directory"
+INFO [05-13|16:17:40.061] Set global gas cap                       cap=50,000,000
+INFO [05-13|16:17:40.061] Allocated trie memory caches             clean=154.00MiB dirty=256.00MiB
+INFO [05-13|16:17:40.061] Allocated cache and file handles         database=/home/go-ethereum/node1/geth/chaindata cache=512.00MiB handles=524,288
+INFO [05-13|16:17:40.094] Opened ancient database                  database=/home/go-ethereum/node1/geth/chaindata/ancient readonly=false
+INFO [05-13|16:17:40.095] Initialised chain configuration          config="{ChainID: 123454321 Homestead: 0 DAO: nil DAOSupport: false EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0 Constantinople: 0 Petersburg: 0 Istanbul: nil, Muir Glacier: nil, Berlin: nil, London: nil, Arrow Glacier: nil, MergeFork: nil, Terminal TD: nil, Engine: clique}"
+INFO [05-13|16:17:40.096] Initialising Ethereum protocol           network=123,454,321 dbversion=8
+INFO [05-13|16:17:40.098] Loaded most recent local header          number=0 hash=c9a158..d415a0 td=1 age=53y1mo2w
+INFO [05-13|16:17:40.098] Loaded most recent local full block      number=0 hash=c9a158..d415a0 td=1 age=53y1mo2w
+INFO [05-13|16:17:40.098] Loaded most recent local fast block      number=0 hash=c9a158..d415a0 td=1 age=53y1mo2w
+INFO [05-13|16:17:40.099] Loaded local transaction journal         transactions=0 dropped=0
+INFO [05-13|16:17:40.100] Regenerated local transaction journal    transactions=0 accounts=0
+INFO [05-13|16:17:40.100] Gasprice oracle is ignoring threshold set threshold=2
+WARN [05-13|16:17:40.100] Unclean shutdown detected                booted=2022-05-13T16:16:46+0100 age=54s
+INFO [05-13|16:17:40.100] Starting peer-to-peer node               instance=Geth/v1.10.18-unstable-8d84a701-20220503/linux-amd64/go1.18.1
+INFO [05-13|16:17:40.130] New local node record                    seq=1,652,454,949,228 id=f1364e6d060c4625 ip=127.0.0.1 udp=30306 tcp=30306
+INFO [05-13|16:17:40.130] Started P2P networking                   self=enode://87606cd0b27c9c47ca33541d4b68cf553ae6765e22800f0df340e9788912b1e3d2759b3d1933b6f739c720701a56ce26f672823084420746d04c25fc7b8c6824@127.0.0.1:30306
+INFO [05-13|16:17:40.133] IPC endpoint opened                      url=/home/go-ethereum/node1/geth.ipc
+INFO [05-13|16:17:40.785] Unlocked account                         address=0xC1B2c0dFD381e6aC08f34816172d6343Decbb12b
+INFO [05-13|16:17:42.636] New local node record                    seq=1,652,454,949,229 id=f1364e6d060c4625 ip=82.11.59.221 udp=30306 tcp=30306
+INFO [05-13|16:17:43.309] Mapped network port                      proto=tcp extport=30306 intport=30306 interface="UPNP IGDv1-IP1"
+INFO [05-13|16:17:43.822] Mapped network port                      proto=udp extport=30306 intport=30306 interface="UPNP IGDv1-IP1"
+[05-13|16:17:50.150] Looking for peers                        peercount=0 tried=0 static=0
+INFO [05-13|16:18:00.164] Looking for peers                        peercount=0 tried=0 static=0
+```
+
+In the first terminal that is currently running the logs resembling the following will be displayed, showing the discovery process in action:
+
+```terminal
+INFO [05-13|15:50:03.645] New local node record                    seq=1,652,453,403,645 id=a2d37f4a7d515b3a ip=nil udp=0 tcp=0
+TRACE[05-13|16:15:49.228]  PING/v4                               id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:49.229]  PONG/v4                               id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:49.229]  PING/v4                               id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:49.230]  PONG/v4                               id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:49.730]  FINDNODE/v4                           id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:49.731]  NEIGHBORS/v4                          id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:50.231]  FINDNODE/v4                           id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:50.231]  NEIGHBORS/v4                          id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:50.561]  FINDNODE/v4                           id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:50.561]  NEIGHBORS/v4                          id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:50.731]  FINDNODE/v4                           id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:50.731]  NEIGHBORS/v4                          id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:51.231]  FINDNODE/v4                           id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:51.232]  NEIGHBORS/v4                          id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:52.591]  FINDNODE/v4                           id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:52.591]  NEIGHBORS/v4                          id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+TRACE[05-13|16:15:57.767]  PING/v4                               id=f1364e6d060c4625 addr=127.0.0.1:30306 err=nil
+```
+
+It is now possible to attach a Javascript console to either node to query the network properties:
+
+```sh
+geth attach node1/geth.ipc
+```
+
+Once the Javascript console is running, check that the node is connected to one other peer (node 2):
+
+```sh
+net.peerCount
+```
+
+The details of this peer can also be queried and used to check that the peer really is Node 2:
+
+```sh
+admin.peers
+```
+
+This should return the following:
+
+```terminal
+[{
+    caps: ["eth/66", "snap/1"],
+    enode: "enode://6a4576fb12004aa13949dbf25de978102483a6521e6d5d87c5b7ccb1944bbf8995dc730303ae891732410b1dd2e684277e9292fc0a17372a789bb4e87bdf366b@127.0.0.1:30307",
+    id: "d300c59ba301abcb5f4a3866aab6f833857c3ddf2f0febb583410b1dc466f175",
+    name: "Geth/v1.10.18-unstable-8d84a701-20220503/linux-amd64/go1.18.1",
+    network: {
+      inbound: false,
+      localAddress: "127.0.0.1:56620",
+      remoteAddress: "127.0.0.1:30307",
+      static: false,
+      trusted: false
+    },
+    protocols: {
+      eth: {
+        difficulty: 1,
+        head: "0xc9a158a687eff8a46128bd5b9aaf6b2f04f10f0683acbd7f031514db9ad415a0",
+        version: 66
+      },
+      snap: {
+        version: 1
+      }
+    }
+}]
+```
+
+The account associated with Node 1 was supposed to be funded with some ether at the chain genesis. This can be checked easily using `eth.getBalance()`:
+
+```sh
+eth.getBalance(eth.accounts[0])
+```
+
+This account can then be unlocked and some ether sent to Node 2, using the following commands:
+
+```js
+// send some Wei
+eth.sendTransaction({
+  to: '0xc94d95a5106270775351eecfe43f97e8e75e59e8',
+  from: eth.accounts[0],
+  value: 25000
+});
+
+//check the transaction was successful by querying Node 2's account balance
+eth.getBalance('0xc94d95a5106270775351eecfe43f97e8e75e59e8');
+```
+
+The same steps can then be repeated to attach a console to Node 2.
+
+## Summary {#summary}
+
+This page explored the various options for configuring a local private network. A step by step guide showed how to set up and launch a private network, unlock the associated accounts, attach a console to check the network status and make some basic interactions.

docs/fundamentals/pruning.md

@@ -0,0 +1,64 @@
+---
+title: Pruning
+description: Instructions for pruning a Geth node
+---
+
+<Note>Offline pruning is only for the hash-based state scheme. Soon, we will have a path-based state scheme which enables the pruning by default. Once the hash-based state scheme is no longer supported, offline pruning will be deprecated.</Note>
+
+A snap-sync'd Geth node currently requires more than 650 GB of disk space to store the historic blockchain data. With default cache size the database grows by about 14 GB/week. This means that Geth users will rapidly run out of space on 1TB hard drives. To solve this problem without needing to purchase additional hardware, Geth can be pruned. Pruning is the process of erasing older data to save disk space. Since Geth `v1.10`, users have been able to trigger a snapshot offline prune to bring the total storage back down to the original ~650 GB in about 4-5 hours. This has to be done periodically to keep the total disk storage
+within the bounds of the local hardware (e.g. every month or so for a 1TB disk).
+
+To prune a Geth node at least 40 GB of free disk space is recommended. This means pruning cannot be used to save a hard drive that has been completely filled. A good rule of thumb is to prune before the node fills ~80% of the available disk space.
+
+## Pruning rules {#pruning-rules}
+
+1. Do not try to prune an archive node. Archive nodes need to maintain ALL historic data by definition.
+2. Ensure there is at least 40 GB of storage space still available on the disk that will be pruned. Failures have been reported with ~25GB of free space.
+3. Geth is at least `v1.10` ideally > `v1.10.3`
+4. Geth is fully sync'd
+5. Geth has finished creating a snapshot that is at least 128 blocks old. This is true when "state snapshot generation" is no longer reported in the logs.
+
+With these rules satisfied, Geth's database can be pruned.
+
+## How pruning works {#how-pruning-works}
+
+Pruning uses snapshots of the state database as an indicator to determine which nodes in the state trie can be kept and which ones are stale and can be discarded. Geth identifies the target state trie based on a stored snapshot layer which has at least 128 block confirmations on top (for surviving reorgs) data that isn't part of the target state trie or genesis state.
+
+Geth prunes the database in three stages:
+
+1. Iterating state snapshot: Geth iterates the bottom-most snapshot layer and constructs a bloom filter set for identifying the target trie nodes.
+2. Pruning state data: Geth deletes stale trie nodes from the database which are not in the bloom filter set.
+3. Compacting database: Geth tidies up the new database to reclaim free space.
+
+There may be a period of >1 hour during the Compacting Database stage with no log messages at all. This is normal, and the pruning should be left to run until finally a log message containing the phrase `State pruning successful` appears (i.e. do not restart Geth yet!). That message indicates that the pruning is complete and Geth can be started.
+
+## Pruning command {#pruning-command}
+
+For a normal Geth node, Geth should be stopped and the following command executed to start a offline state prune:
+
+```sh
+geth snapshot prune-state
+```
+
+For a Geth node run using `systemd`:
+
+```sh
+sudo systemctl stop geth # stop geth, wait >3mins to ensure clean shutdown
+tmux # tmux enables pruning to keep running even if you disconnect
+sudo -u <user> geth --datadir <path> snapshot prune-state # wait for pruning to finish
+sudo systemctl start geth # restart geth
+```
+
+The pruning could take 4-5 hours to complete. Once finished, restart Geth.
+
+## Troubleshooting {#troubleshooting}
+
+Messages about "state snapshot generation" indicate that a snapshot is not fully generated. This suggests either the `--datadir` is not correct or Geth ran out of time to complete the snapshot generation and the pruning began before the snapshot was completed. In either case, the best course of action is to stop Geth, run it normally again (no pruning) until the snapshot is definitely complete and at least 128 blocks exist on top of it, then try pruning again.
+
+## Further Reading {#further-reading}
+
+[Ethereum Foundation blog post for Geth v1.10.0](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/)
+
+[Pruning Geth guide (@yorickdowne)](https://gist.github.com/yorickdowne/3323759b4cbf2022e191ab058a4276b2)
+
+[Pruning Geth in a RocketPool node](https://docs.rocketpool.net/guides/node/geth-pruning.html)

docs/fundamentals/security.md

@@ -0,0 +1,28 @@
+---
+title: Security
+description: A primer on Geth security best practice.
+---
+
+## Downloading Geth {#downloading-geth}
+
+Download Geth using the links on the [Downloads](/downloads) page. The SHA256 hashes of the downloaded files can be used to confirm precise consistency with our releases. This protects against malicious code being inadvertently downloaded from an adversarial source. The same measures should also be taken to download trusted consensus client software.
+
+## Networking security {#networking-security}
+
+The local machine's firewall settings should:
+
+- Block all traffic to `8545`, or whatever custom port has been defined for JSON-RPC requests to the node, except for traffic from explicitly defined trusted machines.
+- Allow traffic on `TCP 30303` or whichever custom port has been defined for peer-to-peer communications. This allows the node to connect to peers.
+- Allow traffic on `UDP 30303` or whichever custom port has been defined for peer-to-peer communications. This allows node discovery.
+
+## Account security {#account-security}
+
+Account security comes down to keeping private keys and account passwords backed up and inaccessible to adversaries. This is something that users take responsibility for. Geth provides an encrypted store for keys that are unlocked using an account password. If the key files or the passwors are lost, the account is impossible to access and the funds are effectively lost forever. If access to the unencrypted keys is obtained by an adversary they gain control of any funds associated with the account.
+
+Geth has built-in account management tools. However, Clef is recommended as an external account management and signing tool. It can be run decoupled from Geth and can even be run on dedicated secure external hardware such as a VM or a secure USB drive. This is considered best practise because the user is required to manually review all actions that touch sensitive data, except where specific predefined rules are implemented. Signing is done locally to Clef rather than giving key access to a node. Geth's built-in management tools are intended to be deprecated in the near future.
+
+**Back up your keystore and passwords safely and securely!**
+
+## Other security considerations {#other-security}
+
+Even with a perfectly secure node, users can still be manipulated by attackers into exposing security weaknesses or inadvertently interact with insecure smart contracts. For an overview, please see the Ethereum [security best practise webpage](https://ethereum.org/en/security) and this introduction to [smart contract security](https://ethereum.org/en/developers/docs/smart-contracts/security).

docs/fundamentals/sync-modes.md

@@ -0,0 +1,73 @@
+---
+title: Sync modes
+description: Introduction to Geth's sync modes
+---
+
+Syncing is the process by which Geth catches up to the latest Ethereum block and current global state. There are several ways to sync a Geth node that differ in their speed, storage requirements and trust assumptions. Now that Ethereum uses proof-of-stake based consensus, a consensus client is required for Geth to sync.
+
+## Full nodes {#full-nodes}
+
+There are two types of full node that use different mechanisms to sync up to the head of the chain:
+
+### Snap (default) {#snap-sync}
+
+Snap sync starts froma relatively recent block and syncs from there to the head of the chain, keeping only the most recent 128 block states in memory. The block header to sync up to is provided by the consensus client. Between the initial sync block and the 128 most recent blocks, the node stores occasional snapshots that can be used to rebuild any intermediate state "on-the-fly". The difference between the snap-synced node and a full block-by-block synced node is that a snap synced node started from an initial checkpoint that was more recent than the genesis block. Snap sync is much faster than a full block-by-block sync from genesis. To start a node with snap sync pass `--syncmode snap` at startup.
+
+![state pruning options](/images/docs/state-pruning.png)
+_This image shows the state stored by each sync-mode - red indicates stored state. The full width of each line represents origin to present head_
+
+Snap sync works by first downloading the headers for a chunk of blocks. Once the headers have been verified, the block bodies and receipts for those blocks are downloaded. In parallel, Geth also sync begins state-sync. In state-sync, Geth first downloads the leaves of the state trie for each block without the intermediate nodes along with a range proof. The state trie is then regenerated locally.
+
+The state download is the part of the snap-sync that takes the most time to complete and the progress can be monitored using the ETA values in the log messages. However, the blockchain is also progressing at the same time and invalidating some of the regenerated state data. This means it is also necessary to have a 'healing' phase where errors in the state are fixed. It is not possible to monitor the progress of the state heal because the extent of the errors cannot be known until the current state has already been regenerated. Geth regularly reports `Syncing, state heal in progress` during state healing - this informs the user that state heal has not finished. It is also possible to confirm this using `eth.syncing` - if this command returns `false` then the node is in sync. If it returns anything other than `false` then syncing is still in progress.
+
+The healing has to outpace the growth of the blockchain, otherwise the node will never catch up to the current state. There are some hardware factors that determine the speed of the state healing (speed of disk read/write and internet connection) and also the total gas used in each block (more gas means more changes to the state that have to be handled).
+
+To summarize, snap sync progresses in the following sequence:
+
+- download and verify headers
+- download block bodies and receipts. In parallel, download raw state data and build state trie
+- heal state trie to account for newly arriving data
+
+**Note** Snap sync is the default behaviour, so if the `--syncmode` value is not passed to Geth at startup, Geth will use snap sync. A node that is started using `snap` will switch to block-by-block sync once it has caught up to the head of the chain.
+
+### Full {#full-sync}
+
+A full blobk-by-block sync generates the current state by executing every block starting from the genesis block. A full sync indendently verifies block provenance as well as all state transitions by re-executing the transactions in the entire historical sequence of blocks. Only the most recent 128 block states are stored in a full node - older block states are pruned periodically and represented as a series of checkpoints from which any previous state can be regenerated on request. 128 blocks is about 25.6 minutes of history with a block time of 12 seconds.
+
+To create a full node pass `--syncmode full` at startup.
+
+## Archive nodes {#archive-nodes}
+
+An archive node is a node that retains all historical data right back to genesis. There is no need to regenerate any data from checkpoints because all data is directly available in the node's own storage. Archive nodes are therefore ideal for making fast queries about historical states. At the time of writing (September 2022) a full archive node that stores all data since genesis occupies nearly 12 TB of disk space (keep up with the current size on [Etherscan](https://etherscan.io/chartsync/chainarchive)). Archive nodes are created by configuring Geth's garbage collection so that old data is never deleted: `geth --syncmode full --gcmode archive`.
+
+It is also possible to create a partial/recent archive node where the node was synced using `snap` but the state is never pruned. This creates an archive node that saves all state data from the point that the node first syncs. This is configured by starting Geth with `--syncmode snap --gcmode archive`.
+
+## Light nodes {#light-nodes}
+
+A light node syncs very quickly and stores the bare minimum of blockchain data. Light nodes only process block headers, not entire blocks. This greatly reduces the computation time, storage and bandwidth required relative to a full node. This means light nodes are suitable for resource-constrained devices and can catch up to the head of the chain much faster when they are new or have been offline for a while. The trade-off is that light nodes rely heavily on data served by altruistic full nodes. A light client can be used to query data from Ethereum and submit transactions, acting as a locally-hosted Ethereum wallet. However, because they don't keep local copies of the Ethereum state, light nodes can't validate blocks in the same way as full nodes - they receive a proof from the full node and verify it against their local header chain. To start a node in light mode, pass `--syncmode light`. Be aware that full nodes serving light data are relative scarce so light nodes can struggle to find peers. **Light nodes are not currently working on proof-of-stake Ethereum**.
+
+Read more about light nodes on our [LES page](/docs/fundamentals/les).
+
+## Consensus layer syncing {#consensus-layer-syncing}
+
+Now that Ethereum has switched to proof-of-stake, all consensus logic and block propagation is handled by consensus clients. This means that syncing the blockchain is a process shared between the consensus and execution clients. Blocks are downloaded by the consensus client and verified by the execution client. In order for Geth to sync, it requires a header from its connected consensus client. Geth does not import any data until it is instructed to by the consensus client. **Geth cannot sync without being connected to a consensus client**. This includes block-by-block syncing from genesis. The consensus client is required to provide a header from the tip of the chain that Geth can sync towards - without it, Geth cannot know that it has followed the right sequence of blocks.
+
+Once a header is available to use as a syncing target, Geth retrieves all headers between that target header and the local header chain in reverse chronological order. These headers show that the sequence of blocks is correct because the parenthashes link one block to the next right up to the target block. Eventually, the sync will reach a block held in the local database, at which point the local data and the target data are considered 'linked' and there is a very high chance the node is syncing the correct chain. The block bodies are then downloaded and then the state data. The consensus client can update the target header - as long as the syncing outpaces the growth of the blockchain then the node will eventually get in sync.
+
+There are two ways for the consensus client to find a block header that Geth can use as a sync target: optimistic syncing and checkpoint syncing:
+
+### Optimistic sync {#optimistic-sync}
+
+Optimistic sync downloads blocks before the execution client has validated them. In optimistic sync the node assumes the data it receives from its peers is correct during the downloading phase but then retroactively verifies each downloaded block. Nodes are not allowed to attest or propose blocks while they are still 'optimistic' because they can't yet guarantee their view of the head of the chain is correct.
+
+Read more in the [optimistic sync specs](https://github.com/ethereum/consensus-specs/blob/dev/sync/optimistic.md).
+
+### Checkpoint sync {#checkpoint-sync}
+
+Alternatively, the consensus client can grab a checkpoint from a trusted source which provides a target state to sync up to, before switching to full sync and verifying each block in turn. In this mode, the node trusts that the checkpoint is correct. There are many possible sources for this checkpoint - the gold standard would be to get it out-of-band from another trusted friend, but it could also come from block explorers or [public APIs/web apps](https://eth-clients.github.io/checkpoint-sync-endpoints/). Checkpoint sync is very fast - a consensus cleint should be able to sync in a few minutes using this method.
+
+For troubleshooting, please see the `Syncing` section on the [console log messages](/docs/fundamentals/logs) page.
+
+## Summary {#summary}
+
+There are several ways to sync a Geth node. The default is to use snap sync to create a full node. Full nodes can be created by syncing block-by-block from genesis (full-sync) or by starting at an intermediate checkpoint block (snap-sync). By default, these modes prune state data older than 128 blocks, keeping only checkpoints that enable on-request regeneration of historical states. For rapid queries of historical data an archive node is required. Archive nodes keep local copies of all historical data right back to genesis - currently about 12 TB and growing. Partial archive nodes can be created by snap-syncign a node and turning off state-pruning to create a node that keeps all states since the initial sync block. Currently, due to the transition to proof-of-stake, light-sync does not work (new light client protocols are being developed).

docs/getting-started/consensus-clients.md

@@ -0,0 +1,67 @@
+---
+title: Connecting to Consensus Clients
+description: Instructions for connecting Geth to a consensus client
+---
+
+Geth is an [execution client](https://ethereum.org/en/glossary/#execution-client). Historically, an execution client alone was enough to run a full Ethereum node. However, ever since Ethereum swapped from [proof-of-work](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow) (PoW) to [proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos) (PoS) based consensus, Geth has needed to be coupled to another piece of software called a ["consensus client"](https://ethereum.org/en/glossary/#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 {#configuring-geth}
+
+Geth can be downloaded and installed according to the instructions on the [Installing Geth](/docs/getting-started/installing-geth) page. In order to connect to a consensus client, Geth must expose a port for the inter-client RPC connection.
+
+The RPC connection must be authenticated using a `jwtsecret` file. This is created and saved to `<datadir>/geth/jwtsecret` by default but can also be created and saved to a custom location or it can be self-generated and provided to Geth by passing the file path to `--authrpc.jwtsecret`. The `jwtsecret` file is required by both Geth and the consensus client.
+
+The authorization must then be applied to a specific address/port. This is achieved by passing an address to `--authrpc.addr` and a port number to `--authrpc.port`. It is also safe to provide either `localhost` or a wildcard `*` to `--authrpc.vhosts` so that incoming requests from virtual hosts are accepted by Geth because it only applies to the port authenticated using `jwtsecret`.
+
+A complete command to start Geth so that it can connect to a consensus client looks as follows:
+
+```sh
+geth --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
+```
+
+## Consensus clients {#consensus-clients}
+
+There are currently five consensus clients that can be run alongside Geth. These are:
+
+[Lighthouse](https://lighthouse-book.sigmaprime.io/): written in Rust
+
+[Nimbus](https://nimbus.team/): written in Nim
+
+[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](https://ethereum.org/en/developers/docs/nodes-and-clients/client-diversity) when choosing a consensus client. Instructions for installing each client are provided in the documentation linked in the list above.
+
+The consensus client must be started with the right port configuration to establish an RPC connection to the local Geth instance. In the example above, `localhost:8551` was authorized for this purpose. The consensus clients all have a command similar to `--http-webprovider` that takes the exposed Geth port as an argument.
+
+The consensus client also needs the path to Geth's `jwt-secret` in order to authenticate the RPC connection between them. Each consensus client has a command similar to `--jwt-secret` that takes the file path as an argument. This must be consistent with the `--authrpc.jwtsecret` path provided to Geth.
+
+The consensus clients all expose a [Beacon API](https://ethereum.github.io/beacon-APIs) 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.
+
+## Validators {#validators}
+
+Validators are responsible for securing the Ethereum blockchain. Validators have staked at least 32 ETH into a deposit contract and run validator software. Each of the consensus clients have their own validator software that is described in detail in their respective documentation. The easiest way to handle staking and validator key generation is to use the Ethereum Foundation [Staking Launchpad](https://launchpad.ethereum.org/). The Launchpad guides users through the process of generating validator keys and connecting the validator to the consensus client.
+
+## Syncing {#syncing}
+
+Geth cannot sync until the connected consensus client is synced. This is because Geth needs a target head to sync to. The fastest way to sync a consensus client is using checkpoint sync. To do this, a checkpoint or a url to a checkpoint provider can be provided to the consensus client on startup. There are several sources for these checkpoints. The ideal scenario is to get one from a trusted node operator, organized out-of-band, and verified against a third node or a block explorer or checkpoint provider. Some clients also allow checkpoint syncing by HTTP API access to an existing Beacon node. There are also several [public checkpoint sync endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/).
+
+Please see the pages on [syncing](/docs/fundamentals/sync-modes) for more detail. For troubleshooting, please see the `Syncing` section on the [console log messages](/docs/fundamentals/logs) page.
+
+## Using Geth {#using-geth}
+
+Geth is the portal for users to send transactions to Ethereum. The Geth Javascript console is available for this purpose, and the majority of the [JSON-RPC API](/docs/rpc) will remain available via web3js or HTTP requests with commands as json payloads. These options are explained in more detail on the [Javascript Console page](/docs/interacting-with-geth/javascript-console). The Javascript console can be started
+using the following command in a separate terminal (assuming Geth's IPC file is saved in `datadir`):
+
+```sh
+geth attach datadir/geth.ipc
+```
+
+## Summary {#summary}
+
+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.

docs/getting-started/hardware-requirements.md

@@ -0,0 +1,25 @@
+---
+title: Hardware requirements
+description: Overview of the hardware needed to run an Ethereum node
+---
+
+The hardware requirements for running a Geth node depend upon the node configuration and can change over time as upgrades to the network are implemented. Ethereum nodes can be run on low power, resource-constrained devices such as Raspberry Pi's. Prebuilt, dedicated staking machines are available from several companies - these might be good choices for users who want plug-and-play hardware specifically designed for Ethereum. However, many users will choose to run nodes on laptop or desktop computers.
+
+## Processor {#processor}
+
+It is preferable to use a quad-core (or dual-core hyperthreaded) CPU. Geth is released for a wide range of architectures.
+
+## Memory {#memory}
+
+It is recommended to use at least 16GB RAM.
+
+## Disk space {#disk-space}
+
+Disk space is usually the primary bottleneck for node operators. At the time of writing (September 2022) a 2TB SSD is recommended for a full node running Geth and a consensus client. Geth itself requires >650GB of disk space for a snap-synced full node and, with the default cache size, grows about 14GB/week. Pruning brings the total storage back down to the original 650GB.
+Archive nodes require additional space. A "full" archive node that keeps all state back to genesis requires more than 12TB of space. Partial archive nodes can also be created by turning off the garbage collector after some initial sync - the storage requirement depends how much state is saved.
+
+As well as storage capacity, Geth nodes rely on fast read and write operations. This means HDDs and cheaper HDDS can sometimes struggle to sync the blockchain. A list of SSD models that users report being able and unable to sync Geth is available in this [GitHub Gist](https://gist.github.com/yorickdowne/f3a3e79a573bf35767cd002cc977b038). Please note that the list has _not_ been verified by the Geth team.
+
+## Bandwidth {#bandwidth}
+
+It is important to have a stable and reliable internet connection, especially for running a validator because downtime can result in missed rewards or penalties. It is recommended to have at least 25Mbps download speed to run a node. Running a node also requires a lot of data to be uploaded and downloaded so it is better to use an ISP that does not have a capped data allowance.

docs/getting-started/index.md

@@ -0,0 +1,434 @@
+---
+title: Getting started with Geth
+description: Guide to getting up and running with Geth using Clef.
+---
+
+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"](/docs/getting-started/installing-geth) pages.
+
+Geth also needs to be connected to a [consensus client](docs/getting-started/consensus-clients) 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](/docs/fundamentals/security).
+
+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. This tutorial uses [Clef](/docs/tools/clef/tutorial). Clef is an account management tool external to Geth itself that allows users to sign transactions. It is developed and maintained by the Geth team.
+
+## Prerequisites {#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
+- 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](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line), 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](/docs/fundamentals/node-architecture) and our guide for configuring Geth to connect to a
+consensus client is [here](/docs/getting-started/consensus-clients).
+
+<Note>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.</Note>
+
+## Background {#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. 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/).
+
+## Step 1: Generating accounts {#generating-accounts}
+
+There are several methods for generating accounts in Geth. This tutorial demonstrates how to generate accounts using Clef, as this is considered best practice, largely because it decouples the users' key management from Geth, making it more modular and flexible. It can also be run from secure USB sticks or virtual machines, offering security benefits. For convenience, this tutorial will execute Clef on the same computer that will also run Geth, although more secure options are available (see [here](/docs/tools/clef/setup)).
+
+An account is a pair of keys (public and private). Clef needs to know where to save these keys to so that they can be retrieved later. This information is passed to Clef as an argument. This is achieved using the following command:
+
+```sh
+clef newaccount --keystore geth-tutorial/keystore
+```
+
+The specific function from Clef that generates new accounts is `newaccount` and it accepts a parameter, `--keystore`, that tells it where to store the newly generated keys. In this example the keystore location is a new directory that will be created automatically: `geth-tutorial/keystore`.
+Clef will return the following result in the terminal:
+
+```terminal
+WARNING!
+
+Clef is an account management tool. It may, like any software, contain bugs.
+
+Please take care to
+- backup your keystore files,
+- verify that the keystore(s) can be opened with your password.
+
+Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See the GNU General Public License for more details.
+
+Enter 'ok' to proceed:
+>
+```
+
+This is important information. The `geth-tutorial/keystore` directory will soon contain a secret key that can be used to access any funds held in the new account. If it is compromised, the funds can be stolen. If it is lost, there is no way to retrieve the funds. This tutorial will only use dummy funds with no real world value, but when these steps are repeated on Ethereum mainnet is critical that the keystore is kept secure and backed up.
+
+Typing `ok` into the terminal and pressing `enter` causes Clef to prompt for a password. Clef requires a password that is at least 10 characters long, and best practice would be to use a combination of numbers, characters and special characters. Entering a suitable password and pressing `enter` returns the following result to the terminal:
+
+```terminal
+-----------------------
+DEBUG[02-10|13:46:46.436] FS scan times                            list="92.081µs" set="12.629µs" diff="2.129µs"
+INFO [02-10|13:46:46.592] Your new key was generated               address=0xCe8dBA5e4157c2B284d8853afEEea259344C1653
+WARN [02-10|13:46:46.595] Please backup your key file!             path=keystore:///.../geth-tutorial/keystore/UTC--2022-02-07T17-19-56.517538000Z--ca57f3b40b42fcce3c37b8d18adbca5260ca72ec
+WARN [02-10|13:46:46.595] Please remember your password!
+Generated account 0xCe8dBA5e4157c2B284d8853afEEea259344C1653
+```
+
+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.
+
+## Step 2: Start Clef {#start-clef}
+
+The previous commands used Clef's `newaccount` function to add new key pairs to the keystore. Clef uses the private key(s) saved in the keystore is used to sign transactions. In order to do this, Clef needs to be started and left running while Geth is running simultaneously, so that the two programs can communicate between one another.
+
+To start Clef, run the Clef executable passing as arguments the keystore file location, config directory location and a chain ID. The config directory was automatically created inside the `geth-tutorial` directory during the previous step. The [chain ID](https://chainlist.org/) is an integer that defines which Ethereum network to connect to. Ethereum mainnet has chain ID 1. In this tutorial Chain ID 11155111 is used which is that of the Sepolia testnet. It is very important that this chain ID parameter is set to 11155111 - Clef uses the chain ID to sign messages so it must be correct. The following command starts Clef on Sepolia:
+
+```sh
+clef --keystore geth-tutorial/keystore --configdir geth-tutorial/clef --chainid 11155111
+```
+
+After running the command above, Clef requests the user to type “ok” to proceed. On typing "ok" and pressing enter, Clef returns the following to the terminal:
+
+```terminal
+INFO [02-10|13:55:30.812] Using CLI as UI-channel
+INFO [02-10|13:55:30.946] Loaded 4byte database                    embeds=146,841 locals=0 local=./4byte-custom.json
+WARN [02-10|13:55:30.947] Failed to open master, rules disabled    err="failed stat on geth-tutorial/clef/masterseed.json: stat geth-tutorial/clef/masterseed.json: no such file or directory"
+INFO [02-10|13:55:30.947] Starting signer                          chainid=5 keystore=geth-tutorial/keystore light-kdf=false advanced=false
+DEBUG[02-10|13:55:30.948] FS scan times                            list="133.35µs" set="5.692µs" diff="3.262µs"
+DEBUG[02-10|13:55:30.970] Ledger support enabled
+DEBUG[02-10|13:55:30.973] Trezor support enabled via HID
+DEBUG[02-10|13:55:30.976] Trezor support enabled via WebUSB
+INFO [02-10|13:55:30.978] Audit logs configured                    file=audit.log
+DEBUG[02-10|13:55:30.981] IPCs registered                          namespaces=account
+INFO [02-10|13:55:30.984] IPC endpoint opened                      url=geth-tutorial/clef/clef.ipc
+------- Signer info -------
+* intapi_version : 7.0.1
+* extapi_version : 6.1.0
+* extapi_http : n/a
+* extapi_ipc : geth-tutorial/clef/clef.ipc
+```
+
+This result indicates that Clef is running. This terminal should be left running for the duration of this tutorial. If the tutorial is stopped and restarted later Clef must also be restarted by running the previous command.
+
+## Step 3: Start Geth {#start-geth}
+
+Geth is the Ethereum client that will connect the computer to the Ethereum network. In this tutorial the network is Sepolia, 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), signer (points Geth to Clef), 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 final argument passed to Geth is the `--http` flag. This enables the http-rpc server that allows external programs to interact with Geth by sending it http requests. By default the http server is only exposed locally using port 8545: `localhost:8545`. It is also necessary to authorize some traffic for the consensus client which is done using `--authrpc` and also to set up a JWT secret token in a known location, using `--jwt-secret`.
+
+The following command should be run in a new terminal, separate to the one running Clef:
+
+```sh
+geth --sepolia --datadir geth-tutorial --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret geth-tutorial/jwtsecret --http --http.api eth,net --signer=geth-tutorial/clef/clef.ipc --http
+```
+
+Running the above command starts Geth. Geth will not sync the blockchain correctly unless there is also a consensus client that can pass Geth a valid head to sync up to. In a separate terminal, start a consensus client. Once the consensus client gets in sync, Geth will start to sync too.
+
+The terminal should rapidly fill with status updates that look similar to those below. To check the meaning of the logs, refer to the [logs page](/docs/fundamentals/logs).
+
+```terminal
+INFO [02-10|13:59:06.649] Starting Geth on sepolia testnet...
+INFO [02-10|13:59:06.652] Maximum peer count                       ETH=50 LES=0 total=50
+INFO [02-10|13:59:06.655] Using external signer                    url=geth-tutorial/clef/clef.ipc
+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: 11155111 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
+INFO [02-10|13:59:06.998] HTTP server started                      endpoint=127.0.0.1:8545 prefix= cors= vhosts=localhost
+```
+
+By default, Geth uses snap-sync which download blocks sequentially from a relatively recent block, not the genesis block. It saves the data in files in `/go-ethereum/geth-tutorial/geth/chaindata/`. One the sequence of headers has been verified, Geth downloads the block bodies and state data before starting the "state healing" phase to update the state for newly arriving data. 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
+```
+
+This message will be displayed periodically until state healing has finished:
+
+```sh
+INFO [10-20|20:20:09.510] State heal in progress                   accounts=313,309@17.95MiB slots=363,525@28.77MiB codes=7222@50.73MiB nodes=49,616,912@12.67GiB pending=29805
+```
+
+When state healing is finished, the node is in sync and ready to use.
+
+Sending an empty Curl request to the http server provides a quick way to confirm that this too has been started without any issues. In a third terminal, the following command can be run:
+
+```sh
+curl http://localhost:8545
+```
+
+If there is no error message reported to the terminal, everything is OK. Geth must be running and synced in order for a user to interact with the Ethereum network. If the terminal running Geth is closed down then Geth must be restarted again in a new terminal. 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 <other commands>`.
+
+## Step 4: Get Testnet Ether {#get-test-eth}
+
+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, 3) having paid for it with fiat money. On Ethereum testnets, the ether has no real world value so it 4) can be made freely available via faucets. Faucets allow users to request a transfer of testnet ether to their account.
+
+The address generated by Clef in Step 1 can be pasted into the Paradigm Multifaucet faucet [here](https://faucet.sepolia.dev/). The faucets adds Sepolia ETH (not real ETH) to the given address. 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 5: Interact with Geth {#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 over Geth's exposed http port using tools like 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 HTTP option. Note that the terminals running Geth and Clef should both still be active. In a new (third) terminal, the following command can be run to start the console and connect it to Geth using the exposed http port:
+
+```sh
+geth attach http://127.0.0.1:8545
+```
+
+This command causes the terminal to hang because it is waiting for approval from Clef. Approving the request in the terminal running Clef will lead to the following welcome message being 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))
+ modules: eth:1.0 net:1.0 rpc: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 (Sepolia) network.
+
+### List of accounts {#list-accounts}
+
+In this tutorial, the accounts are managed using Clef. This means that requesting information about the accounts requires explicit approval in Clef, which should still be running in its own terminal. Earlier in this tutorial, two accounts were created using Clef. 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.
+
+```js
+eth.accounts;
+```
+
+The console will hang, because Clef is waiting for approval. The following message will be displayed in the Clef terminal:
+
+```terminal
+-------- List Account request--------------
+A request has been made to list all accounts.
+You can select which accounts the caller can see
+  [x] 0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC
+    URL: keystore:///.../geth-tutorial/keystore/UTC--2022-02-07T17-19-56.517538000Z--ca57f3b40b42fcce3c37b8d18adbca5260ca72ec
+  [x] 0xCe8dBA5e4157c2B284d8853afEEea259344C1653
+    URL: keystore:///.../geth-tutorial/keystore/UTC--2022-02-10T12-46-45.265592000Z--ce8dba5e4157c2b284d8853afeeea259344c1653
+-------------------------------------------
+Request context:
+        NA - ipc - NA
+
+Additional HTTP header data, provided by the external caller:
+        User-Agent: ""
+        Origin: ""
+Approve? [y/N]:
+
+```
+
+Entering `y` approves the request from the console. In the terminal running the Javascript console, the account addresses are now displayed:
+
+```terminal
+["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", "0xce8dba5e4157c2b284d8853afeeea259344c1653"]
+```
+
+It is also possible for this request to time out if the Clef approval took too long - in this case simply repeat the request and approval. Accoutns can also be listed directly from Clef by opening a new terminal and running `clef list-accounts --keystore <path-to-keystore>`.
+
+### Checking account balance. {#checking-balances}
+
+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 Sepolia faucet should have sent 0.05 ETH to the address provided, meaning that the balance of one of the accounts should be at least 0.05 ether and the other should be 0. There are other faucets available that may dispense more ETH per request, and multipel requests can be made to accumulate more ETH. The following command displays the account balance in the console:
+
+```js
+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, assuming the account balance is 1 ETH:
+
+```terminal
+1
+```
+
+Repeating the command for the other (empty) account should yield:
+
+```terminal
+0
+```
+
+### Send ether to another account {#sending-ether}
+
+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 Clef 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.
+
+```js
+eth.sendTransaction({
+  from: '0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec',
+  to: '0xce8dba5e4157c2b284d8853afeeea259344c1653',
+  value: web3.toWei(0.1, 'ether')
+});
+```
+
+Note that submitting this transaction requires approval in Clef. In the Clef terminal, Clef will prompt for approval and request the account password. If the password is correctly entered, Geth proceeds with the transaction. The transaction request summary is presented by Clef in the Clef terminal. This is an opportunity for the sender to review the details and ensure they are correct.
+
+```terminal
+--------- Transaction request-------------
+to:    0xCe8dBA5e4157c2B284d8853afEEea259344C1653
+from:               0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC [chksum ok]
+value:              10000000000000000 wei
+gas:                0x5208 (21000)
+maxFeePerGas:          2425000057 wei
+maxPriorityFeePerGas:  2424999967 wei
+nonce:    0x3 (3)
+chainid:  0x5
+Accesslist
+
+Request context:
+        NA - ipc - NA
+
+Additional HTTP header data, provided by the external caller:
+        User-Agent: ""
+        Origin: ""
+-------------------------------------------
+Approve? [y/N]:
+
+Please enter the password for account 0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC
+```
+
+After approving the transaction, the following confirmation screen in displayed in the Clef terminal:
+
+```terminal
+-----------------------
+Transaction signed:
+ {
+    "type": "0x2",
+    "nonce": "0x3",
+    "gasPrice": null,
+    "maxPriorityFeePerGas": "0x908a901f",
+    "maxFeePerGas": "0x908a9079",
+    "gas": "0x5208",
+    "value": "0x2386f26fc10000",
+    "input": "0x",
+    "v": "0x0",
+    "r": "0x66e5d23ad156e04363e68b986d3a09e879f7fe6c84993cef800bc3b7ba8af072",
+    "s": "0x647ff82be943ea4738600c831c4a19879f212eb77e32896c05055174045da1bc",
+    "to": "0xce8dba5e4157c2b284d8853afeeea259344c1653",
+    "chainId": "0xaa36a7",
+    "accessList": [],
+    "hash": "0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb"
+  }
+```
+
+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 balances of the two accounts in the Clef keystore should have changed by ~0.1 ETH (the sender's balance will have decremented by a little over 0.1 ETH because some small was amount paid in transaction gas).
+
+### Checking the transaction hash {#checking-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 [Sepolia block explorer](https://sepolia.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:
+
+```js
+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: "0xaa36a7",
+  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 {#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.
+
+### Checking account balance {#checking-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).
+
+```sh
+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:
+
+```py
+0xc7d54951f87f7c0 / 1e18
+```
+
+This returns the balance in ether:
+
+```terminal
+0.8999684999998321
+```
+
+### Checking the account list {#checking-account-list}
+
+The curl command below returns the list of all accounts.
+
+```sh
+curl -X POST http://127.0.0.1:8545 \
+    -H "Content-Type: application/json" \
+   --data '{"jsonrpc":"2.0", "method":"eth_accounts","params":[], "id":1}'
+```
+
+This requires approval in Clef. Once approved, the following information is returned to the terminal:
+
+```terminal
+{"jsonrpc":"2.0","id":1,"result":["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec"]}
+```
+
+### Sending Transactions {#sending-transactions}
+
+Sending a transaction between accounts can also be achieved using Curl. Notice that the value of the transaction is a hexadecimal string in units of Wei. To transfer 0.1 ether, it is first necessary to convert this to Wei by multiplying by 10<sup>18</sup> then converting to hex. 0.1 ether is `"0x16345785d8a0000"` in hex. As before, update the `to` and `from` fields with the addresses in the Clef keystore.
+
+```sh
+curl -X POST http://127.0.0.1:8545 \
+    -H "Content-Type: application/json" \
+   --data '{"jsonrpc":"2.0", "method":"eth_sendTransaction", "params":[{"from": "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec","to": "0xce8dba5e4157c2b284d8853afeeea259344c1653","value": "0x16345785d8a0000"}], "id":1}'
+```
+
+This requires approval in Clef. Once the password for the sender account has been provided, Clef will return a summary of the transaction details and the terminal that made the Curl request will display a response containing the transaction hash.
+
+```terminal
+{"jsonrpc":"2.0","id":5,"result":"0xac8b347d70a82805edb85fc136fc2c4e77d31677c2f9e4e7950e0342f0dc7e7c"}
+```
+
+## Summary {#summary}
+
+This tutorial has demonstrated how to generate accounts using Clef, fund them with testnet ether and use those accounts to interact with Ethereum (Sepolia) 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. For more detailed information about Clef, please see [the Clef docs](/docs/tools/clef/tutorial).

docs/getting-started/installing-geth.md

@@ -0,0 +1,316 @@
+---
+title: Installing Geth
+description: Guide to installing Geth
+---
+
+There are several ways to install Geth, including via a package manager, downloading a pre-built bundle, running as a docker container or building from downloaded source code. On this page the various installation options are explained for several major operating systems. Users prioritizing ease of installation should choose to use a package manager or prebuilt bundle. Users prioritizing customization should build from source. It is important to run the latest version of Geth because each release includes bugfixes and improvement over the previous versions. The stable releases are recommended for most users because they have been fully tested. A list of stable releases can be found [here](https://github.com/ethereum/go-ethereum/releases). Instructions for updating existing Geth installations are also provided in each section.
+
+## Package managers {#package-managers}
+
+### MacOS via Homebrew {#macos-via-homebrew}
+
+The easiest way to install go-ethereum is to use the Geth Homebrew tap. The first step is to check that Homebrew is installed. The following command should return a version number.
+
+```sh
+brew -v
+```
+
+If a version number is returned, then Homebrew is installed. If not, Homebrew can be installed by following the instructions [here](https://brew.sh/). With Homebrew installed, the following commands add the Geth tap and install Geth:
+
+```sh
+brew tap ethereum/ethereum
+brew install ethereum
+```
+
+The previous command installs the latest stable release. Developers that wish to install the most up-to-date version can install the Geth repository's master branch by adding the `--devel` parameter to the install command:
+
+```sh
+brew install ethereum --devel
+```
+
+These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`. The full list of command line options can be viewed [here](/docs/fundamentals/Command-Line-Options) or in the terminal by running `geth --help`.
+
+Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands:
+
+```sh
+brew update
+brew upgrade
+brew reinstall ethereum
+```
+
+When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline.
+
+### Ubuntu via PPAs {#ubuntu-via-ppas}
+
+The easiest way to install Geth on Ubuntu-based distributions is with the built-in launchpad PPAs (Personal Package Archives). A single PPA repository is provided, containing stable and development releases for Ubuntu versions `xenial`, `trusty`, `impish`, `focal`, `bionic`.
+
+The following command enables the launchpad repository:
+
+```sh
+sudo add-apt-repository -y ppa:ethereum/ethereum
+```
+
+Then, to install the stable version of go-ethereum:
+
+```sh
+sudo apt-get update
+sudo apt-get install ethereum
+```
+
+Or, alternatively the develop version:
+
+```sh
+sudo apt-get update
+sudo apt-get install ethereum-unstable
+```
+
+These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`. The full list of command line options can be viewed [here](/docs/fundamentals/Command-Line-Options) or in the terminal by running `geth --help`.
+
+Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands:
+
+```sh
+sudo apt-get update
+sudo apt-get install ethereum
+sudo apt-get upgrade geth
+```
+
+When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline.
+
+### Windows {#windows}
+
+The easiest way to install Geth is to download a pre-compiled binary from the [downloads](/downloads) page. The page provides an installer as well as a zip file containing the Geth source code. The install wizard offers the user the option to install Geth, or Geth and the developer tools. The installer adds `geth` to the system's `PATH` automatically. The zip file contains the command `.exe` files that can be run from the command prompt. The full list of command line options can be viewed [here](/docs/fundamentals/Command-Line-Options) or in the terminal by running `geth --help`.
+
+Updating an existing Geth installation can be achieved by stopping the node, downloading and installing the latest version following the instructions above. When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline.
+
+### FreeBSD via pkg {#freeBSD-via-pkg}
+
+Geth can be installed on FreeBSD using the package manager `pkg`. The following command downloads and installs Geth:
+
+```sh
+pkg install go-ethereum
+```
+
+These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`.
+
+The full list of command line options can be viewed [here](/docs/fundamentals/Command-Line-Options) or in the terminal by running `geth --help`.
+
+Updating an existing Geth installation to the latest version can be achieved by stopping the node and running the following commands:
+
+```sh
+pkg upgrade
+```
+
+When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline.
+
+### FreeBSD via ports {#freeBSD-via-ports}
+
+Installing Geth using ports, simply requires navigating to the `net-p2p/go-ethereum` ports directory and running `make install` as root:
+
+```sh
+cd /usr/ports/net-p2p/go-ethereum
+make install
+```
+
+These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/local/bin/`.
+
+The full list of command line options can be viewed [here](/docs/fundamentals/Command-Line-Options) or in the terminal by running `geth --help`.
+
+Updating an existing Geth installation can be achieved by stopping the node and running the following command:
+
+```sh
+portsnap fetch
+```
+
+When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline.
+
+### Arch Linux via pacman {#arch-linux-via-pacman}
+
+The Geth package is available from the [community repo](https://www.archlinux.org/packages/community/x86_64/geth/). It can be installed by running:
+
+```sh
+pacman -S geth
+```
+
+These commands install the core Geth software and the following developer tools: `clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`. The binaries for each of these tools are saved in `/usr/bin/`.
+
+The full list of command line options can be viewed [here](/docs/fundamentals/Command-Line-Options) or in the terminal by running `geth --help`.
+
+Updating an existing Geth installation can be achieved by stopping the node and running the following command:
+
+```sh
+sudo pacman -Sy
+```
+
+When the node is started again, Geth will automatically use all the data from the previous version and sync the blocks that were missed while the node was offline.
+
+## Standalone bundle {#standalone-bundle}
+
+Stable releases and development builds are provided as standalone bundles. These are useful for users who: a) wish to install a specific version of Geth (e.g., for reproducible environments); b) wish to install on machines without internet access (e.g. air-gapped computers); or c) wish to avoid automatic updates and instead prefer to manually install software.
+
+The following standalone bundles are available:
+
+- 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
+
+Some archives contain only Geth, while other archives containing Geth and the various developer tools (`clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`). More information about these executables is available at the [`README`](https://github.com/ethereum/go-ethereum#executables).
+
+The standalone bundles can be downloaded from the [Geth Downloads](/downloads) page. To update an existing installation, download and manually install the latest version.
+
+## Docker container {#docker-container}
+
+A Docker image with recent snapshot builds from our `develop` branch is maintained on DockerHub to support users who prefer to run containerized processes. There four different Docker images available for running the latest stable or development versions of Geth.
+
+- `ethereum/client-go:latest` is the latest development version of Geth (default)
+- `ethereum/client-go:stable` is the latest stable version of Geth
+- `ethereum/client-go:{version}` is the stable version of Geth at a specific version number
+- `ethereum/client-go:release-{version}` is the latest stable version of Geth at a specific version family
+
+Pulling an image and starting a node is achieved by running these commands:
+
+```sh
+docker pull ethereum/client-go
+docker run -it -p 30303:30303 ethereum/client-go
+```
+
+There are also four different Docker images for running the latest stable or development versions of miscellaneous Ethereum tools.
+
+- `ethereum/client-go:alltools-latest` is the latest development version of the Ethereum tools
+- `ethereum/client-go:alltools-stable` is the latest stable version of the Ethereum tools
+- `ethereum/client-go:alltools-{version}` is the stable version of the Ethereum tools at a specific version number
+- `ethereum/client-go:alltools-release-{version}` is the latest stable version of the Ethereum tools at a specific version family
+
+The image has the following ports automatically exposed:
+
+- `8545` TCP, used by the HTTP based JSON RPC API
+- `8546` TCP, used by the WebSocket based JSON RPC API
+- `8547` TCP, used by the GraphQL API
+- `30303` TCP and UDP, used by the P2P protocol running the network
+
+**Note:** if you are running an Ethereum client inside a Docker container, you should mount a data volume as the client's data directory (located at `/root/.ethereum` inside the container) to ensure that downloaded data is preserved between restarts and/or container life-cycles.
+
+Updating Geth to the latest version simply requires stopping the container, pulling the latest version from Docker and running it:
+
+```sh
+docker stop ethereum/client-go
+docker pull ethereum/client-go:latest
+docker run -it -p 30303:30303 ethereum/client-go
+```
+
+## Build from source code {#build-from-source}
+
+### Most Linux systems and macOS {#linux-and-macos}
+
+Geth is written in [Go](https://golang.org/), so building from source code requires the most recent version of Go to be installed. Instructions for installing Go are available at the [Go installation page](https://golang.org/doc/install) and necessary bundles can be downloaded from the [Go download page](https://golang.org/dl/).
+
+With Go installed, Geth can be downloaded into a `GOPATH` workspace via:
+
+```sh
+go get -d github.com/ethereum/go-ethereum
+```
+
+You can also install specific versions via:
+
+```sh
+go get -d github.com/ethereum/go-ethereum@v1.9.21
+```
+
+The above commands do not build any executables. To do that you can either build one specifically:
+
+```sh
+go install github.com/ethereum/go-ethereum/cmd/geth
+```
+
+Alternatively, the following command, run in the project root directory (`ethereum/go-ethereum`) in the GO workspace, builds the entire project and installs Geth and all the developer tools:
+
+```sh
+go install ./...
+```
+
+For macOS users, errors related to macOS header files are usually fixed by installing XCode Command Line Tools with `xcode-select --install`.
+Another common error is: `go: cannot use path@version syntax in GOPATH mode`. This and other similar errors can often be fixed by enabling gomodules using `export GO111MODULE=on`.
+
+Updating an existing Geth installation can be achieved using `go get`:
+
+```sh
+go get -u github.com/ethereum/go-ethereum
+```
+
+### Windows {#windows}
+
+The Chocolatey package manager provides an easy way to install the required build tools. Chocolatey can be installed by following these [instructions](https://chocolatey.org). Then, to install the build tool the following commands can be run in an Administrator command prompt:
+
+```sh
+C:\Windows\system32> choco install git
+C:\Windows\system32> choco install golang
+C:\Windows\system32> choco install mingw
+```
+
+Installing these packages sets up the path environment variables. To get the new path a new command prompt must be opened. To install Geth, a Go workspace directory must first be created, then the Geth source code can be created and built.
+
+```sh
+C:\Users\xxx> mkdir src\github.com\ethereum
+C:\Users\xxx> git clone https://github.com/ethereum/go-ethereum src\github.com\ethereum\go-ethereum
+C:\Users\xxx> cd src\github.com\ethereum\go-ethereum
+C:\Users\xxx\src\github.com\ethereum\go-ethereum> go get -u -v golang.org/x/net/context
+C:\Users\xxx\src\github.com\ethereum\go-ethereum> go install -v ./cmd/...
+```
+
+### FreeBSD {#freeBSD}
+
+To build Geth from source code on FreeBSD, the Geth GitHub repository can be cloned into a local directory.
+
+```sh
+git clone https://github.com/ethereum/go-ethereum
+```
+
+Then, the Go compiler can be used to build Geth:
+
+```sh
+pkg install go
+```
+
+If the Go version currently installed is >= 1.5, Geth can be built using the following command:
+
+```sh
+cd go-ethereum
+make geth
+```
+
+If the installed Go version is < 1.5 (quarterly packages, for example), the following command can be used instead:
+
+```sh
+cd go-ethereum
+CC=clang make geth
+```
+
+To start the node, the followijng command can be run:
+
+```shell
+build/bin/geth
+```
+
+### Building without a Go workflow {#building-without-go}
+
+Geth can also be built without using Go workspaces. In this case, the repository should be cloned to a local repository. Then, the command
+`make geth` configures everything for a temporary build and cleans up afterwards. This method of building only works on UNIX-like operating systems, and a Go installation is still required.
+
+```sh
+git clone https://github.com/ethereum/go-ethereum.git
+cd go-ethereum
+make geth
+```
+
+These commands create a Geth executable file in the `go-ethereum/build/bin` folder that can be moved and run from another directory if required. The binary is standalone and doesn't require any additional files.
+
+To update an existing Geth installation simply stop the node, navigate to the project root directory and pull the latest version from the Geth GitHub repository. then rebuild and restart the node.
+
+```sh
+cd go-ethereum
+git pull
+make geth
+```
+
+Additionally all the developer tools provided with Geth (`clef`, `devp2p`, `abigen`, `bootnode`, `evm`, `rlpdump` and `puppeth`) can be compiled by running `make all`. More information about these tools can be found [here](https://github.com/ethereum/go-ethereum#executables).
+
+To build a stable release, e.g. v1.9.21, the command `git checkout v1.9.21` retrieves that specific version. Executing that command before running `make geth` switches Geth to a stable branch.

docs/index.md

@@ -0,0 +1,25 @@
+---
+title: Welcome to go-ethereum
+description: Documentation for the go-ethereum client
+---
+
+Go-ethereum (aka Geth) is an Ethereum client built in [Go](https://go.dev). It is one of the original and most popular Ethereum clients.
+These documentation pages are intended to help users download, install and use Geth.
+
+## Where to go from here {#where-to-go}
+
+First, make sure you have sufficient [hardware](/docs/getting-started/hardware-requirements), then [download](/downloads) and [install](/docs/getting-started/installing-geth) Geth. Make sure you are familiar with the [security considerations](/docs/fundamentals/security) and have your firewall set up.
+
+If you are just starting out with Geth, head to the [Getting started](/docs/getting-started/) page. That page guides new users through some basic functions of Geth such as creating and securing accounts and making a transaction.
+
+Then, it is recommended to read the material in the [Fundamentals](/docs/fundamentals) section - these pages will help build a foundational understanding of how Geth works from a user perspective and under the hood.
+
+More advanced topics are also available - explore them using the sidebar!
+
+## Developers and contributors {#developers-and-contributors}
+
+If you want to help develop Geth or build decentralized apps on top of it, head to our [Developer](/docs/developers) documentation.
+
+## More resources {#more-resources}
+
+We have a library of videos and articles on our [Resources](/docs/resources) page and answers to common questions on the [FAQs](/docs/faq) page.

docs/interacting-with-geth/javascript-console-contracts.md

@@ -0,0 +1,133 @@
+---
+title: 'JavaScript Console 2: Contracts'
+description: Instructions for working with contracts in the Javascript console.
+---
+
+The [Introduction to the Javascript console](/docs/interacting-with-geth/javascript-console) page outlined how a Javascript console can be attached to Geth to provide a more user-friendly interface to Ethereum than interacting directly with the JSON-RPC API. This page will describe how to deploy contracts and interact with contracts using the attached console. This page will assume the Javascript console is attached to a running Geth instance using IPC. Clef should be used to manage accounts.
+
+## Deploying a contract {#deploying-a-contract}
+
+First we need a contract to deploy. We can use the well-known `Storage.sol` contract written in Solidity. The following Solidity code can be copied and pasted into a text editor and saved as `go-ethereum/storage-contract/Storage.sol`.
+
+```js
+// SPDX License-Identifier: GPL 3.0
+
+pragma solidity ^0.8.0;
+
+contract Storage{
+
+    uint256 value = 5;
+
+    function set(uint256 number) public{
+        value = number;
+    }
+
+    function retrieve() public view returns (uint256){
+        return value;
+    }
+}
+```
+
+The contract needs to be compiled before Geth can understand it. Compiling the contract creates an [Application Binary Interface](/docs/tools/abigen) and the contract bytecode. This requires a Solidity compiler (e.g. `solc`) to be installed on the local machine. Then, compile and save the ABI and bytecode to a new `build` subdirectory using the following terminal commands:
+
+```sh
+cd ~/go-ethereum/storage-contract
+solc --bin Storage.sol -o build
+solc --abi Storage.sol -o build
+```
+
+The outputs look as follows:
+
+```sh
+# build/Storage.bin
+608060405234801561001057600080fd5b50610150806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c80632e64cec11461003b5780636057361d14610059575b600080fd5b610043610075565b60405161005091906100a1565b60405180910390f35b610073600480360381019061006e91906100ed565b61007e565b005b60008054905090565b8060008190555050565b6000819050919050565b61009b81610088565b82525050565b60006020820190506100b66000830184610092565b92915050565b600080fd5b6100ca81610088565b81146100d557600080fd5b50565b6000813590506100e7816100c1565b92915050565b600060208284031215610103576101026100bc565b5b6000610111848285016100d8565b9150509291505056fea264697066735822122031443f2fb748bdb27e539fdbeb0c6f575aec50508baaa7e4dbeb08577ef19b3764736f6c63430008110033
+```
+
+```json
+# Storage.abi
+[{"inputs":[],"name":"retrieve","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"number","type":"uint256"}],"name":"store","outputs":[],"stateMutability":"nonpayable","type":"function"}]
+```
+
+These are all the data required to deploy the contract using the Geth Javascript console. Open the Javascript console using `./geth attach geth.ipc`.
+
+Now, for convenice we can store the abi and bytecode in variables in the console:
+
+```js
+var abi = [
+  {
+    inputs: [],
+    name: 'retrieve',
+    outputs: [{ internalType: 'uint256', name: '', type: 'uint256' }],
+    stateMutability: 'view',
+    type: 'function'
+  },
+  {
+    inputs: [{ internalType: 'uint256', name: 'number', type: 'uint256' }],
+    name: 'store',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function'
+  }
+];
+
+var bytecode =
+  '608060405234801561001057600080fd5b50610150806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c80632e64cec11461003b5780636057361d14610059575b600080fd5b610043610075565b60405161005091906100a1565b60405180910390f35b610073600480360381019061006e91906100ed565b61007e565b005b60008054905090565b8060008190555050565b6000819050919050565b61009b81610088565b82525050565b60006020820190506100b66000830184610092565b92915050565b600080fd5b6100ca81610088565b81146100d557600080fd5b50565b6000813590506100e7816100c1565b92915050565b600060208284031215610103576101026100bc565b5b6000610111848285016100d8565b9150509291505056fea264697066735822122031443f2fb748bdb27e539fdbeb0c6f575aec50508baaa7e4dbeb08577ef19b3764736f6c63430008110033';
+```
+
+The ABI can be used to create an instance of the contract:
+
+```js
+var contract = eth.contract(abi);
+```
+
+This contract instance can then be deployed to the blockchain. This is done using `eth.sendTransaction`, passing the contract bytecode in the `data` field. For convenience we can create a transaction JSON object first, then pass it to `eth.sendTransaction` later. Let's use the first account in `eth.accounts` as the sender. The amount of gas to include can be determined using `eth.estimateGas`:
+
+```js
+var gas = eth.estimateGas({ data: bytecode });
+```
+
+Note that each command that touches accounts will require **approval in Clef** unless a custom rule has been implemented. The bytecode, gas and address of the sender can be bundled together into an object that will be passed to the contract's `new()` method which deploys the contract.
+
+```js
+var tx = { from: eth.accounts[0], data: bytecode, gas: gas };
+var deployed_contract = contract.new(tx);
+```
+
+The transaction hash and deployment address can now been viewed in the console by entering the variable name (in this case `deployed_contract`):
+
+```js
+{
+  abi:[{
+    inputs: [],
+    name: "retrieve",
+    outputs: [{...}],
+    stateMutability: "view",
+    type: "function"
+  },{
+    inputs: [],
+    name: "store",
+    outputs: [{...}],
+    stateMutability: "nonpayable",
+    type: "function"
+  }],
+  address: "0x2d6505f8b1130a22a5998cd31788bf6c751247f",
+  transactionHash: "0x5040a8916b23b76696ea9eba5b072546e1112cc481995219081fc86f5b911bf3",
+  allEvents: function bound(),
+  retrieve: function bound(),
+  store: function bound()
+}
+```
+
+Passing the transaction hash to `eth.getTransaction()` returns the deployment transaction details including the contract bytecode in the `input` field. To interact with the contract, create an instance by passing the deployment address to `contract.at` then call the methods.
+
+```js
+var instance = contract.at('0x2d6505f8b1130a22a5998cd31788bf6c751247f');
+// store() alters the state and therefore requires sendTransaction()
+contract.set.sendTransaction(42, { from: eth.accounts[0], gas: 1000000 });
+// retrieve does not alter state so it can be executed using call()
+contract.retrieve().call() >> 2;
+```
+
+## Summary {#summary}
+
+This page demonstrated how to create, compile, deploy and interact with an Ethereum smart contract using Geth's Javascript console.

docs/interacting-with-geth/javascript-console.md

@@ -0,0 +1,136 @@
+---
+title: JavaScript Console
+description: How to interact with Geth using Javascript
+---
+
+Geth responds to instructions encoded as JSON objects as defined in the [JSON-RPC-API](/docs/interacting-with-geth/rpc). A Geth user can send these instructions directly, for example over HTTP using tools like [Curl](https://github.com/curl/curl). The code snippet below shows a request for an account balance sent to a local Geth node with the HTTP port `8545` exposed.
+
+```sh
+curl --data '{"jsonrpc":"2.0","method":"eth_getBalance", "params": ["0x9b1d35635cc34752ca54713bb99d38614f63c955", "latest"], "id":2}' -H "Content-Type: application/json" localhost:8545
+```
+
+This returns a result which is also a JSON object, with values expressed as hexadecimal strings, for example:
+
+```terminal
+{"id":2,"jsonrpc":"2.0","result":"0x1639e49bba16280000"}
+```
+
+This is a low level and rather error-prone way to interact with Geth. Most developers prefer to use convenience libraries that abstract away some of the more tedious and awkward tasks such as converting values from hexadecimal strings into numbers, or converting between denominations of ether (Wei, Gwei, etc). One such library is [Web3.js](https://web3js.readthedocs.io/en/v1.7.3/).
+The purpose of Geth's Javascript console is to provide a built-in environment to use a subset of the Web3.js libraries to interact with a Geth node.
+
+<Note>The web3.js version that comes bundled with Geth is not up to date with the official Web3.js documentation. There are several Web3.js libraries that are not available in the Geth Javascript Console. There are also administrative APIs included in the Geth console that are not documented in the Web3.js documentation. The full list of libraries available in the Geth console is available on the [JSON-RPC API page](/docs/interacting-with-geth/rpc).</Note>
+
+## Starting the console {#starting-the-console}
+
+There are two ways to start an interactive session using Geth console. The first is to provide the `console` command when Geth is started up. This starts the node and runs the console in the same terminal. It is therefore convenient to suppress the logs from the node to prevent them from obscuring the console. If the logs are not needed, they can be redirected to the `dev/null` path, effectively muting them. Alternatively, if the logs are required they can be redirected to a text file. The level of detail provided in the logs can be adjusted by providing a value between 1-6 to the `--verbosity` flag as in the example below:
+
+```sh
+# to mute logs
+geth <other flags> console 2> /dev/null
+
+# to save logs to file
+geth <other flags> console --verbosity 3 2> geth-logs.log
+```
+
+Alternatively, a Javascript console can be attached to an existing Geth instance (i.e. one that is running in another terminal or remotely). In this case, `geth attach` can be used to open a Javascript console connected to the Geth node. It is also necessary to define the method used to connect the console to the node. Geth supports websockets, HTTP or local IPC. To use HTTP or Websockets, these must be enabled at the node by providing the following flags at startup:
+
+```sh
+# enable websockets
+geth <other flags> --ws
+
+# enable http
+geth <other flags> --http
+```
+
+The commands above use default HTTP/WS endpoints and only enables the default JSON-RPC libraries. To update the Websockets or HTTP endpoints used, or to add support for additional libraries, the `.addr` `.port` and `.api` flags can be used as follows:
+
+```sh
+# define a custom http adress, custom http port and enable libraries
+geth <other commands> --http --http.addr 192.60.52.21 --http.port 8552 --http.api eth,web3,admin
+
+# define a custom Websockets address and enable libraries
+geth <other commands> --ws --ws.addr 192.60.52.21 --ws.port 8552 --ws.api eth,web3,admin
+```
+
+It is important to note that by default **some functionality, including account unlocking is forbidden when HTTP or Websockets access is enabled**. This is because an attacker that manages to access the node via the externally-exposed HTTP/WS port then control the unlocked account. This is not a hypothetical risk: **there are bots that continually scan for http-enabled Ethereum nodes to attack**"
+
+The Javascript console can also be connected to a Geth node using IPC. When Geth is started, a `geth.ipc` file is automatically generated and saved to the data directory. This file, or a custom path to a specific ipc file can be passed to `geth attach` as follows:
+
+```sh
+geth attach datadir/geth.ipc
+```
+
+Once started, the console looks like this:
+
+```terminal
+Welcome to the Geth Javascript console!
+
+instance: Geth/v1.10.18-unstable-8d85a701-20220503/linux-amd64/go1.18.1
+coinbase: 0x281aabb85c68e1638bb092750a0d9bb06ba103ee
+at block: 12305815 (Thu May 26 2022 16:16:00 GMT+0100 (BST))
+  datadir: /home/go-ethereum/data
+  modules: admin:1.0 debug:1.0 eth:1.0 ethash:1.0 miner:1.0 net:1.0 rpc:1.0 txpool:1.0 web3:1.0
+
+To exit, press ctrl-d or type exit
+>
+```
+
+## Interactive use {#interactive-use}
+
+Once the console has been started, it can be used to interact with Geth. The console supports Javascript and the full Geth [JSON-RPC API](/docs/interacting-with-geth/rpc). For example, to check the balance of the first account already existing in the keystore:
+
+```js
+eth.getBalance(eth.accounts[0]);
+```
+
+To send a transaction (without global account unlocking):
+
+```js
+eth.sendTransaction({
+  to: eth.accounts[0],
+  to: eth.accounts[1],
+  value: web3.toWei(0.5, 'ether')
+});
+```
+
+It is also possible to load pre-written Javascript files into the console by passing the `--preload` flag when starting the console. This is useful for setting up complex contract objects or loading frequently-used functions.
+
+```sh
+geth console --preload "/my/scripts/folder/utils.js"
+```
+
+Once the interactive session is over, the console can be closed down by typing `exit` or `CTRL-D`.
+
+Remember that interactions that touch accounts need approval in Clef - either manually or by writing a custom ruleset.
+
+## Non-interactive Use: Script Mode {#non-interactive-use}
+
+It is also possible to execute JavaScript code non-interactively by passing the `--exec` and a JSON-RPC-API endpoint to `geth attach` or `geth console`. The result is displayed directly in the terminal rather than in an interactive Javascript console.
+
+For example, to display the accounts in the keystore:
+
+```sh
+geth attach --exec eth.accounts
+```
+
+```sh
+geth attach --exec eth.blockNumber
+```
+
+The same syntax can be used to execute a local script file with more complex statements on a remote node over http, for example:
+
+```sh
+geth attach http://geth.example.org:8545 --exec 'loadScript("/tmp/checkbalances.js")'
+
+geth attach http://geth.example.org:8545 --jspath "/tmp" --exec 'loadScript("checkbalances.js")'
+```
+
+The `--jspath` flag is used to set a library directory for the Javascript scripts. Any parameters passed to `loadScript()` that do not explicitly define an absolute path will be interpreted relative to the `jspath` directory.
+
+## Timers {#timers}
+
+In addition to the full functionality of JS (as per ECMA5), the Ethereum Javascript Runtime Environment (JSRE) is augmented with various timers. It implements `setInterval`, `clearInterval`, `setTimeout`, `clearTimeout` which some users will be familiar with from browser windows. It also provides implementation for `admin.sleep(seconds)` and a block based timer, `admin.sleepBlocks(n)` which sleeps till the number of new blocks added is equal to or greater than `n`.
+
+## Caveats {#caveats}
+
+Geth's console is built using the [GoJa JS Virtual Machine](https://github.com/dop251/goja) which is compatible with ECMAScript 5.1. This does not support promises or `async` functions. Web3js depends upon the `bignumber.js` library. This is auto-loaded into the console.

docs/interacting-with-geth/rpc/batch.md

@@ -0,0 +1,44 @@
+---
+title: Batch requests
+description: How to make batch requests using JSON-RPC API
+---
+
+The JSON-RPC [specification](https://www.jsonrpc.org/specification#batch) outlines how clients can send multiple requests at the same time by filling the request objects in an array. This feature is implemented by Geth's API and can be used to cut network delays. Batching offers visible speed-ups specially when used for fetching larger amounts of mostly independent data objects. Below is an example for fetching a list of blocks in JS:
+
+```js
+import fetch from 'node-fetch';
+
+async function main() {
+  const endpoint = 'http://127.0.0.1:8545';
+  const from = parseInt(process.argv[2]);
+  const to = parseInt(process.argv[3]);
+
+  const reqs = [];
+  for (let i = from; i < to; i++) {
+    reqs.push({
+      method: 'eth_getBlockByNumber',
+      params: [`0x${i.toString(16)}`, false],
+      id: i - from,
+      jsonrpc: '2.0'
+    });
+  }
+
+  const res = await fetch(endpoint, {
+    method: 'POST',
+    body: JSON.stringify(reqs),
+    headers: { 'Content-Type': 'application/json' }
+  });
+  const data = await res.json();
+}
+
+main()
+  .then()
+  .catch(err => console.log(err));
+```
+
+In this case there's no dependency between the requests. Often the retrieved data from one request is needed to issue a second one. Let's take the example of fetching all the receipts for a range of blocks. The JSON-RPC API provides `eth_getTransactionReceipt` which takes in a transaction hash and returns the corresponding receipt object, but no method to fetch receipt objects for a whole block. We need to get the list of transactions in a block, and then call `eth_getTransactionReceipt` for each of them. We can break this into 2 batch requests:
+
+- First to download the list of transaction hashes for all of the blocks in our desired range
+- And then to download the list of receipts objects for all of the transaction hashes
+
+For use-cases which depend on several JSON-RPC endpoints the batching approach can get easily complicated. In that case Geth offers a [GraphQL API](/docs/interacting-with-geth/rpc/graphql) which is more suitable.

docs/interacting-with-geth/rpc/graphql.md

@@ -0,0 +1,80 @@
+---
+title: GraphQL Server
+description: Documentation for Geth's GraphQL API
+---
+
+In addition to the [JSON-RPC APIs](/docs/interacting-with-geth/rpc/), Geth supports the GraphQL API as specified by [EIP-1767](https://eips.ethereum.org/EIPS/eip-1767). GraphQL lets you specify which fields of an objects you need as part of the query, eliminating the extra load on the client for filling in fields which are not needed. It also allows for combining several traditional JSON-RPC requests into one query which translates into less overhead and more performance.
+
+The GraphQL endpoint piggybacks on the HTTP transport used by JSON-RPC. Hence the relevant `--http` flags and the `--graphql` flag should be passed to Geth:
+
+```sh
+geth --http --graphql
+```
+
+Now queries can be raised against `http://localhost:8545/graphql`. To change the port, provide a custom port number to `--http.port`, e.g.:
+
+```sh
+geth --http --http.port 9545 --graphql
+```
+
+## GraphiQL {#graphiql}
+
+An easy way to try out queries is the GraphiQL interface shipped with Geth. To open it visit `http://localhost:8545/graphql/ui`. To see how this works let's read the sender, recipient and value of all transactions in block number 6000000. In GraphiQL:
+
+```graphql
+query txInfo {
+  block(number: 6000000) {
+    transactions {
+      hash
+      from {
+        address
+      }
+      to {
+        address
+      }
+      value
+    }
+  }
+}
+```
+
+GraphiQL also provides a way to explore the schema Geth provides to help you formulate your queries, which you can see on the right sidebar. Under the title `Root Types` click on `Query` to see the high-level types and their fields.
+
+## Query {#query}
+
+Reading out data from Geth is the biggest use-case for GraphQL. In addition to using the UI queries can also be sent programmatically. The official GraphQL[docs](https://graphql.org/code/) explain how to find bindings for many languages, or send http requests from the terminal using tools such as Curl.
+
+For example, the code snippet below shows how to obtain the latest block number using Curl. Note the use of a JSON object for the data section:
+
+```sh
+❯ curl -X POST http://localhost:8545/graphql -H "Content-Type: application/json" --data '{ "query": "query { block { number } }" }'
+{"data":{"block":{"number":6004069}}}
+```
+
+Alternatively store the JSON-ified query in a file (let's call it `block-num.query`) and do:
+
+```sh
+❯ curl -X POST http://localhost:8545/graphql -H "Content-Type: application/json" --data '@block-num.query'
+```
+
+Executing a simple query in JS looks as follows. Here the lightweight library `graphql-request` is used to perform the request. Note the use of variables instead of hardcoding the block number in the query:
+
+```js
+const { request, gql } = require('graphql-request');
+
+const query = gql`
+  query blockInfo($number: Long) {
+    block(number: $number) {
+      hash
+      stateRoot
+    }
+  }
+`;
+request('http://localhost:8545/graphql', query, { number: '6004067' })
+  .then(res => {
+    console.log(res);
+  })
+  .catch(err => {
+    console.log(err);
+  });
+```

docs/interacting-with-geth/rpc/index.md

@@ -0,0 +1,125 @@
+---
+title: JSON-RPC Server
+description: Introduction to the JSON_RPC server
+---
+
+Interacting with Geth requires sending requests to specific JSON-RPC API methods. Geth supports all standard [JSON-RPC API](https://github.com/ethereum/execution-apis) endpoints.
+The RPC requests must be sent to the node and the response returned to the client using some transport protocol. This page outlines the available transport protocols in Geth, providing the information users require to choose a transport protocol for a specific user scenario.
+
+## Introduction {#introduction}
+
+JSON-RPC is provided on multiple transports. Geth supports JSON-RPC over HTTP, WebSocket and Unix Domain Sockets. Transports must be enabled through
+command-line flags.
+
+Ethereum JSON-RPC APIs use a name-space system. RPC methods are grouped into several categories depending on their purpose. All method names are composed of
+the namespace, an underscore, and the actual method name within the namespace. For example, the `eth_call` method resides in the `eth` namespace.
+
+Access to RPC methods can be enabled on a per-namespace basis. Find documentation for individual namespaces in the sidebar.
+
+## Transports {#transports}
+
+There are three transport protocols available in Geth: IPC, HTTP and Websockets.
+
+### HTTP Server {#http-server}
+
+[HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP) is a unidirectional transport protocol that connects a client and server. The client sends a request to the server, and the server returns a response back to the client. An HTTP connection is closed after the response for a given request is sent.
+
+HTTP is supported in every browser as well as almost all programming toolchains. Due to its ubiquity it has become the most widely used transport for interacting with Geth. To start a HTTP server in Geth, include the `--http` flag:
+
+```sh
+geth --http
+```
+
+If no other commands are provided, Geth falls back to its default behaviour of accepting connections from the local loopback interface (127.0.0.1). The default listening port is 8545. The ip address and listening port can be customized using the `--http.addr` and `--http.port` flags:
+
+```sh
+geth --http --http.port 3334
+```
+
+Not all of the JSON-RPC method namespaces are enabled for HTTP requests by default. Instead, they have to be whitelisted explicitly when Geth is started. Calling non-whitelisted RPC namespaces returns an RPC error with code `-32602`.
+
+The default whitelist allows access to the `eth`, `net` and `web3` namespaces. To enable access to other APIs like debugging (`debug`), they must be configured using the `--http.api` flag. Enabling these APIs over HTTP is **not recommended** because access to these methods increases the attack surface.
+
+```sh
+geth --http --http.api eth,net,web3
+```
+
+Since the HTTP server is reachable from any local application, additional protection is built into the server to prevent misuse of the API from web pages. To enable access to the API from a web page (for example to use the online IDE, [Remix](https://remix.ethereum.org)), the server needs to be configured to accept Cross-Origin requests. This is achieved using the `--http.corsdomain` flag.
+
+```sh
+geth --http --http.corsdomain https://remix.ethereum.org
+```
+
+The `--http.corsdomain` command also acceptsd wildcards that enable access to the RPC from any origin:
+
+```sh
+--http.corsdomain '*'
+```
+
+### WebSocket Server {#websockets-server}
+
+Websocket is a bidirectional transport protocol. A Websocket connection is maintained by client and server until it is explicitly terminated by one. Most modern browsers support Websocket which means it has good tooling.
+
+Because Websocket is bidirectional, servers can push events to clients. That makes Websocket a good choice for use-cases involving [event subscription](/docs/interacting-with-geth/rpc/pubsub). Another benefit of Websocket is that after the handshake procedure, the overhead of individual messages is low,
+making it good for sending high number of requests.
+
+Configuration of the WebSocket endpoint in Geth follows the same pattern as the HTTP transport. WebSocket access can be enabled using the `--ws` flag. If no additional information is provided, Geth falls back to its default behaviour which is to establish the Websocket on port 8546. The `--ws.addr`, `--ws.port` and `--ws.api` flags can be used to customize settings for the WebSocket server. For example, to start Geth with a Websocket connection for RPC using
+the custom port 3334 and whitelisting the `eth`, `net` and `web3` namespaces:
+
+```sh
+geth --ws --ws.port 3334 --ws.api eth,net,web3
+```
+
+Cross-Origin request protection also applies to the WebSocket server. The `--ws.origins` flag can be used to allow access to the server from web pages:
+
+```sh
+geth --ws --ws.origins http://myapp.example.com
+```
+
+As with `--http.corsdomain`, using the wildcard `--ws.origins '*'` allows access from any origin.
+
+<Note>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**</Note>
+
+### IPC Server {#ipc-server}
+
+IPC is normally available for use in local environments where the node and the console exist on the same machine. Geth creates a pipe in the computers local file system (at `ipcpath`) that configures a connection between node and console. The `geth.ipc` file can also be used by other processes on the same machine to interact with Geth.
+
+On UNIX-based systems (Linux, OSX) the IPC is a UNIX domain socket. On Windows IPC is provided using named pipes. The IPC server is enabled by default and has access to all JSON-RPC namespaces.
+
+The listening socket is placed into the data directory by default. On Linux and macOS, the default location of the geth socket is
+
+```sh
+~/.ethereum/geth.ipc
+```
+
+On Windows, IPC is provided via named pipes. The default location of the geth pipe is:
+
+```sh
+\\.\pipe\geth.ipc
+```
+
+The location of the socket can be customized using the `--ipcpath` flag. IPC can be disabled
+using the `--ipcdisable` flag.
+
+## Choosing a transport protocol {#choosing-transport-protocol}
+
+The following table summarizes the relative strengths and weaknesses of each transport protocol so that users can make informed decisions about which to use.
+
+|                               | HTTP  |  WS   |  IPC  |
+| :---------------------------: | :---: | :---: | :---: |
+|      Event subscription       |   N   | **Y** | **Y** |
+|       Remote connection       | **Y** | **Y** |   N   |
+| Per-message metadata overhead | high  |  low  |  low  |
+
+As a general rule IPC is most secure because it is limited to interactions on the local machine and cannot be exposed to external traffic. It can also be used
+to subscribe to events. HTTP is a familiar and idempotent transport that closes connections between requests and can therefore have lower overall overheads if the number of requests is fairly low. Websockets provides a continuous open channel that can enable event subscriptions and streaming and handle large volumes of requests with smaller per-message overheads.
+
+## Engine-API {#engine-api}
+
+The Engine-API is a set of RPC methods that enable communication between Geth and the [consensus client](/docs/getting-started/consensus-clients). These are not designed to be exposed to the user - instead they are called automatically by the clients when they need to exchange information. The Engine API is enabled by default - the user is not required to pass any instruction to Geth to enable these methods.
+
+Read more in the [Engine API spec](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md).
+
+## Summary {#summary}
+
+RPC requests to a Geth node can be made using three different transport protocols. The protocols are enabled at startup using their respective flags. The right choice of transport protocol depends on the specific use case.

docs/interacting-with-geth/rpc/ns-admin.md

@@ -0,0 +1,260 @@
+---
+title: admin Namespace
+description: Documentation for the JSON-RPC API "admin" namespace
+---
+
+The `admin` API gives access to several non-standard RPC methods, which allows fine grained control over a Geth instance, including but not limited to network peer and RPC endpoint management.
+
+## admin_addPeer {#admin-addpeer}
+
+The `addPeer` administrative method requests adding a new remote node to the list of tracked static nodes. The node will try to maintain connectivity to these nodes at all times, reconnecting every once in a while if the remote connection goes down.
+
+The method accepts a single argument, the [`enode`](https://ethereum.org/en/developers/docs/networking-layer/network-addresses/#enode) URL of the remote peer to start tracking and returns a `BOOL` indicating whether the peer was accepted for tracking or some error occurred.
+
+| Client  | Method invocation                              |
+| :------ | ---------------------------------------------- |
+| Go      | `admin.AddPeer(url string) (bool, error)`      |
+| Console | `admin.addPeer(url)`                           |
+| RPC     | `{"method": "admin_addPeer", "params": [url]}` |
+
+### Example
+
+```js
+> admin.addPeer("enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303")
+true
+```
+
+## admin_addTrustedPeer {#admin-addtrustedpeer}
+
+Adds the given node to a reserved trusted list which allows the node to always connect, even if the slots are full. It returns a `BOOL` to indicate whether the peer was successfully added to the list.
+
+| Client  | Method invocation                                     |
+| :------ | ----------------------------------------------------- |
+| Console | `admin.addTrustedPeer(url)`                           |
+| RPC     | `{"method": "admin_addTrustedPeer", "params": [url]}` |
+
+## admin_datadir {#admin-datadir}
+
+The `datadir` administrative property can be queried for the absolute path the running Geth node currently uses to store all its databases.
+
+| Client  | Method invocation                 |
+| :------ | --------------------------------- |
+| Go      | `admin.Datadir() (string, error`) |
+| Console | `admin.datadir`                   |
+| RPC     | `{"method": "admin_datadir"}`     |
+
+### Example
+
+```js
+> admin.datadir
+"/home/john/.ethereum"
+```
+
+## admin_exportChain {#admin-exportchain}
+
+Exports the current blockchain into a local file. It optionally takes a first and last block number, in which case it exports only that range of blocks. It returns a boolean indicating whether the operation succeeded.
+
+| Client  | Method invocation                                                     |
+| :------ | --------------------------------------------------------------------- |
+| Console | `admin.exportChain(file, first, last)`                                |
+| RPC     | `{"method": "admin_exportChain", "params": [string, uint64, uint64]}` |
+
+## admin_importChain {#admin-importchain}
+
+Imports an exported list of blocks from a local file. Importing involves processing the blocks and inserting them into the canonical chain. The state from the parent block of this range is required. It returns a boolean indicating whether the operation succeeded.
+
+| Client  | Method invocation                                     |
+| :------ | ----------------------------------------------------- |
+| Console | `admin.importChain(file)`                             |
+| RPC     | `{"method": "admin_importChain", "params": [string]}` |
+
+## admin_nodeInfo {#admin-nodeinfo}
+
+The `nodeInfo` administrative property can be queried for all the information known about the running Geth node at the networking granularity. These include general information about the node itself as a participant of the [ÐΞVp2p](https://github.com/ethereum/devp2p/blob/master/caps/eth.md) P2P overlay protocol, as well as specialized information added by each of the running application protocols (e.g. `eth`, `les`, `shh`, `bzz`).
+
+| Client  | Method invocation                         |
+| :------ | ----------------------------------------- |
+| Go      | `admin.NodeInfo() (*p2p.NodeInfo, error`) |
+| Console | `admin.nodeInfo`                          |
+| RPC     | `{"method": "admin_nodeInfo"}`            |
+
+### Example
+
+```js
+> admin.nodeInfo
+{
+  enode: "enode://44826a5d6a55f88a18298bca4773fca5749cdc3a5c9f308aa7d810e9b31123f3e7c5fba0b1d70aac5308426f47df2a128a6747040a3815cc7dd7167d03be320d@[::]:30303",
+  id: "44826a5d6a55f88a18298bca4773fca5749cdc3a5c9f308aa7d810e9b31123f3e7c5fba0b1d70aac5308426f47df2a128a6747040a3815cc7dd7167d03be320d",
+  ip: "::",
+  listenAddr: "[::]:30303",
+  name: "Geth/v1.5.0-unstable/linux/go1.6",
+  ports: {
+    discovery: 30303,
+    listener: 30303
+  },
+  protocols: {
+    eth: {
+      difficulty: 17334254859343145000,
+      genesis: "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3",
+      head: "0xb83f73fbe6220c111136aefd27b160bf4a34085c65ba89f24246b3162257c36a",
+      network: 1
+    }
+  }
+}
+```
+
+## admin_peerEvents {#admin-peerevents}
+
+PeerEvents creates an [RPC subscription](/docs/interacting-with-geth/rpc/pubsub) which receives peer events from the node's p2p server. The type of events emitted by the server are as follows:
+
+- `add`: emitted when a peer is added
+- `drop`: emitted when a peer is dropped
+- `msgsend`: emitted when a message is successfully sent to a peer
+- `msgrecv`: emitted when a message is received from a peer
+
+## admin_peers {#admin-peers}
+
+The `peers` administrative property can be queried for all the information known about the connected remote nodes at the networking granularity. These include general information about the nodes themselves as participants of the [ÐΞVp2p](https://github.com/ethereum/devp2p/blob/master/caps/eth.md) P2P overlay protocol, as well as specialized information added by each of the running application protocols (e.g. `eth`, `les`, `shh`, `bzz`).
+
+| Client  | Method invocation                        |
+| :------ | ---------------------------------------- |
+| Go      | `admin.Peers() ([]*p2p.PeerInfo, error`) |
+| Console | `admin.peers`                            |
+| RPC     | `{"method": "admin_peers"}`              |
+
+### Example
+
+```js
+> admin.peers
+[{
+    caps: ["eth/61", "eth/62", "eth/63"],
+    id: "08a6b39263470c78d3e4f58e3c997cd2e7af623afce64656cfc56480babcea7a9138f3d09d7b9879344c2d2e457679e3655d4b56eaff5fd4fd7f147bdb045124",
+    name: "Geth/v1.5.0-unstable/linux/go1.5.1",
+    network: {
+      localAddress: "192.168.0.104:51068",
+      remoteAddress: "71.62.31.72:30303"
+    },
+    protocols: {
+      eth: {
+        difficulty: 17334052235346465000,
+        head: "5794b768dae6c6ee5366e6ca7662bdff2882576e09609bf778633e470e0e7852",
+        version: 63
+      }
+    }
+}, /* ... */ {
+    caps: ["eth/61", "eth/62", "eth/63"],
+    id: "fcad9f6d3faf89a0908a11ddae9d4be3a1039108263b06c96171eb3b0f3ba85a7095a03bb65198c35a04829032d198759edfca9b63a8b69dc47a205d94fce7cc",
+    name: "Geth/v1.3.5-506c9277/linux/go1.4.2",
+    network: {
+      localAddress: "192.168.0.104:55968",
+      remoteAddress: "121.196.232.205:30303"
+    },
+    protocols: {
+      eth: {
+        difficulty: 17335165914080772000,
+        head: "5794b768dae6c6ee5366e6ca7662bdff2882576e09609bf778633e470e0e7852",
+        version: 63
+      }
+    }
+}]
+```
+
+## admin_removePeer {#admin-removepeer}
+
+Disconnects from a remote node if the connection exists. It returns a boolean indicating validations succeeded. Note a `true` value doesn't necessarily mean that there was a connection which was disconnected.
+
+| Client  | Method invocation                                    |
+| :------ | ---------------------------------------------------- |
+| Console | `admin.removePeer(url)`                              |
+| RPC     | `{"method": "admin_removePeer", "params": [string]}` |
+
+## admin_removeTrustedPeer {#admin-removetrustedpeer}
+
+Removes a remote node from the trusted peer set, but it does not disconnect it automatically. It returns a boolean indicating validations succeeded.
+
+| Client  | Method invocation                                           |
+| :------ | ----------------------------------------------------------- |
+| Console | `admin.removeTrustedPeer(url)`                              |
+| RPC     | `{"method": "admin_removeTrustedPeer", "params": [string]}` |
+
+## admin_startHTTP {#admin-starthttp}
+
+The `startHTTP` administrative method starts an HTTP based JSON-RPC [API](/docs/interacting-with-geth/rpc) webserver to handle client requests. All the parameters are optional:
+
+- `host`: network interface to open the listener socket on (defaults to `"localhost"`)
+- `port`: network port to open the listener socket on (defaults to `8545`)
+- `cors`: [cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) header to use (defaults to `""`)
+- `apis`: API modules to offer over this interface (defaults to `"eth,net,web3"`)
+
+The method returns a boolean flag specifying whether the HTTP RPC listener was opened or not. Please note, only one HTTP endpoint is allowed to be active at any time.
+
+| Client  | Method invocation                                                                              |
+| :------ | ---------------------------------------------------------------------------------------------- |
+| Go      | `admin.StartHTTP(host *string, port *rpc.HexNumber, cors *string, apis *string) (bool, error)` |
+| Console | `admin.startHTTP(host, port, cors, apis)`                                                      |
+| RPC     | `{"method": "admin_startHTTP", "params": [host, port, cors, apis]}`                            |
+
+### Example
+
+```js
+> admin.startHTTP("127.0.0.1", 8545)
+true
+```
+
+## admin_startWS {#admin-startws}
+
+The `startWS` administrative method starts an WebSocket based [JSON RPC](https://www.jsonrpc.org/specification) API webserver to handle client requests. All the parameters are optional:
+
+- `host`: network interface to open the listener socket on (defaults to `"localhost"`)
+- `port`: network port to open the listener socket on (defaults to `8546`)
+- `cors`: [cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) header to use (defaults to `""`)
+- `apis`: API modules to offer over this interface (defaults to `"eth,net,web3"`)
+
+The method returns a boolean flag specifying whether the WebSocket RPC listener was opened or not. Please note, only one WebSocket endpoint is allowed to be active at any time.
+
+| Client  | Method invocation                                                                            |
+| :------ | -------------------------------------------------------------------------------------------- |
+| Go      | `admin.StartWS(host *string, port *rpc.HexNumber, cors *string, apis *string) (bool, error)` |
+| Console | `admin.startWS(host, port, cors, apis)`                                                      |
+| RPC     | `{"method": "admin_startWS", "params": [host, port, cors, apis]}`                            |
+
+### Example
+
+```js
+> admin.startWS("127.0.0.1", 8546)
+true
+```
+
+## admin_stopHTTP {#admin-stophttp}
+
+The `stopHTTP` administrative method closes the currently open HTTP RPC endpoint. As the node can only have a single HTTP endpoint running, this method takes no parameters, returning a boolean whether the endpoint was closed or not.
+
+| Client  | Method invocation                |
+| :------ | -------------------------------- |
+| Go      | `admin.StopHTTP() (bool, error`) |
+| Console | `admin.stopHTTP()`               |
+| RPC     | `{"method": "admin_stopHTTP"`    |
+
+### Example
+
+```js
+> admin.stopHTTP()
+true
+```
+
+## admin_stopWS {#admin-stopws}
+
+The `stopWS` administrative method closes the currently open WebSocket RPC endpoint. As the node can only have a single WebSocket endpoint running, this method takes no parameters, returning a boolean whether the endpoint was closed or not.
+
+| Client  | Method invocation              |
+| :------ | ------------------------------ |
+| Go      | `admin.StopWS() (bool, error`) |
+| Console | `admin.stopWS()`               |
+| RPC     | `{"method": "admin_stopWS"`    |
+
+### Example
+
+```js
+> admin.stopWS()
+true
+```

docs/interacting-with-geth/rpc/ns-clique.md

@@ -0,0 +1,138 @@
+---
+title: clique Namespace
+description: Documentation for the JSON-RPC API "clique" namespace
+---
+
+The `clique` API provides access to the state of the clique consensus engine. This API cna be used to manage signer votes and to check the health of a private network.
+
+## clique_getSnapshot {#clique-getsnapshot}
+
+Retrieves a snapshot of all clique state at a given block.
+
+| Client  | Method invocation                                           |
+| :------ | ----------------------------------------------------------- |
+| Console | `clique.getSnapshot(blockNumber)`                           |
+| RPC     | `{"method": "clique_getSnapshot", "params": [blockNumber]}` |
+
+Example:
+
+```js
+> clique.getSnapshot(5463755)
+{
+  hash: "0x018194fc50ca62d973e2f85cffef1e6811278ffd2040a4460537f8dbec3d5efc",
+  number: 5463755,
+  recents: {
+    5463752: "0x42eb768f2244c8811c63729a21a3569731535f06",
+    5463753: "0x6635f83421bf059cd8111f180f0727128685bae4",
+    5463754: "0x7ffc57839b00206d1ad20c69a1981b489f772031",
+    5463755: "0xb279182d99e65703f0076e4812653aab85fca0f0"
+  },
+  signers: {
+    0x42eb768f2244c8811c63729a21a3569731535f06: {},
+    0x6635f83421bf059cd8111f180f0727128685bae4: {},
+    0x7ffc57839b00206d1ad20c69a1981b489f772031: {},
+    0xb279182d99e65703f0076e4812653aab85fca0f0: {},
+    0xd6ae8250b8348c94847280928c79fb3b63ca453e: {},
+    0xda35dee8eddeaa556e4c26268463e26fb91ff74f: {},
+    0xfc18cbc391de84dbd87db83b20935d3e89f5dd91: {}
+  },
+  tally: {},
+  votes: []
+}
+```
+
+## clique_getSnapshotAtHash {#clique-getsnapshotathash}
+
+Retrieves the state snapshot at a given block.
+
+| Client  | Method invocation                                               |
+| :------ | --------------------------------------------------------------- |
+| Console | `clique.getSnapshotAtHash(blockHash)`                           |
+| RPC     | `{"method": "clique_getSnapshotAtHash", "params": [blockHash]}` |
+
+## clique_getSigner {#clique-getsigner}
+
+Returns the signer for a specific clique block. Can be called with either a blocknumber, blockhash or an rlp encoded blob. The RLP encoded blob can either be a block or a header.
+
+| Client  | Method invocation                                    |
+| :------ | ---------------------------------------------------- |
+| Console | `clique.getSigner(blockNrOrHashOrRlp)`               |
+| RPC     | `{"method": "clique_getSigner", "params": [string]}` |
+
+## clique_getSigners {#clique-getsigners}
+
+Retrieves the list of authorized signers at the specified block number.
+
+| Client  | Method invocation                                          |
+| :------ | ---------------------------------------------------------- |
+| Console | `clique.getSigners(blockNumber)`                           |
+| RPC     | `{"method": "clique_getSigners", "params": [blockNumber]}` |
+
+## clique_getSignersAtHash {#clique-getsignersathash}
+
+Retrieves the list of authorized signers at the specified block hash.
+
+| Client  | Method invocation                                           |
+| :------ | ----------------------------------------------------------- |
+| Console | `clique.getSignersAtHash(blockHash)`                        |
+| RPC     | `{"method": "clique_getSignersAtHash", "params": [string]}` |
+
+## clique_proposals {#clique-proposals}
+
+Returns the current proposals the node is voting on.
+
+| Client  | Method invocation                              |
+| :------ | ---------------------------------------------- |
+| Console | `clique.proposals()`                           |
+| RPC     | `{"method": "clique_proposals", "params": []}` |
+
+## clique_propose {#clique-propose}
+
+Adds a new authorization proposal that the signer will attempt to push through. If the `auth` parameter is true, the local signer votes for the given address to be included in the set of authorized signers. With `auth` set to `false`, the vote is against the address.
+
+| Client  | Method invocation                                         |
+| :------ | --------------------------------------------------------- |
+| Console | `clique.propose(address, auth)`                           |
+| RPC     | `{"method": "clique_propose", "params": [address, auth]}` |
+
+## clique_discard {#clique-discard}
+
+This method drops a currently running proposal. The signer will not cast further votes (either for or against) the address.
+
+| Client  | Method invocation                                   |
+| :------ | --------------------------------------------------- |
+| Console | `clique.discard(address)`                           |
+| RPC     | `{"method": "clique_discard", "params": [address]}` |
+
+## clique_status {#clique-status}
+
+This is a debugging method which returns statistics about signer activity for the last 64 blocks. The returned object contains the following fields:
+
+- `inturnPercent`: percentage of blocks signed in-turn
+- `sealerActivity`: object containing signer addresses and the number
+  of blocks signed by them
+- `numBlocks`: number of blocks analyzed
+
+| Client  | Method invocation                           |
+| :------ | ------------------------------------------- |
+| Console | `clique.status()`                           |
+| RPC     | `{"method": "clique_status", "params": []}` |
+
+Example:
+
+```js
+> clique.status()
+{
+  inturnPercent: 100,
+  numBlocks: 64,
+  sealerActivity: {
+    0x42eb768f2244c8811c63729a21a3569731535f06: 9,
+    0x6635f83421bf059cd8111f180f0727128685bae4: 9,
+    0x7ffc57839b00206d1ad20c69a1981b489f772031: 9,
+    0xb279182d99e65703f0076e4812653aab85fca0f0: 10,
+    0xd6ae8250b8348c94847280928c79fb3b63ca453e: 9,
+    0xda35dee8eddeaa556e4c26268463e26fb91ff74f: 9,
+    0xfc18cbc391de84dbd87db83b20935d3e89f5dd91: 9
+  }
+}
+```

docs/interacting-with-geth/rpc/ns-debug.md

@@ -0,0 +1,784 @@
+---
+title: debug Namespace
+description: methods in the debug namespace
+---
+
+The `debug` API gives you access to several non-standard RPC methods, which will allow you to inspect, debug and set certain debugging flags during runtime.
+
+### debug_accountRange
+
+Enumerates all accounts at a given block with paging capability. `maxResults` are returned in the page and the items have keys that come after the `start` key (hashed address).
+
+If `incompletes` is false, then accounts for which the key preimage (i.e: the `address`) doesn't exist in db are skipped. NB: geth by default does not store preimages.
+
+| Client  | Method invocation                                                                                                |
+| :------ | ---------------------------------------------------------------------------------------------------------------- |
+| Console | `debug.accountRange(blockNrOrHash, start, maxResults, nocode, nostorage, incompletes)`                           |
+| RPC     | `{"method": "debug_getHeaderRlp", "params": [blockNrOrHash, start, maxResults, nocode, nostorage, incompletes]}` |
+
+### debug_backtraceAt
+
+Sets the logging backtrace location. When a backtrace location is set and a log message is emitted at that location, the stack of the goroutine executing the log statement will be printed to stderr.
+
+The location is specified as `<filename>:<line>`.
+
+| Client  | Method invocation                                     |
+| :------ | ----------------------------------------------------- |
+| Console | `debug.backtraceAt(string)`                           |
+| RPC     | `{"method": "debug_backtraceAt", "params": [string]}` |
+
+Example:
+
+```js
+> debug.backtraceAt("server.go:443")
+```
+
+### debug_blockProfile
+
+Turns on block profiling for the given duration and writes profile data to disk. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually using `debug_writeBlockProfile`.
+
+| Client  | Method invocation                                              |
+| :------ | -------------------------------------------------------------- |
+| Console | `debug.blockProfile(file, seconds)`                            |
+| RPC     | `{"method": "debug_blockProfile", "params": [string, number]}` |
+
+### debug_chaindbCompact
+
+Flattens the entire key-value database into a single level, removing all unused slots and merging all keys.
+
+| Client  | Method invocation                                  |
+| :------ | -------------------------------------------------- |
+| Console | `debug.chaindbCompact()`                           |
+| RPC     | `{"method": "debug_chaindbCompact", "params": []}` |
+
+### debug_chaindbProperty
+
+Returns leveldb properties of the key-value database.
+
+| Client  | Method invocation                                           |
+| :------ | ----------------------------------------------------------- |
+| Console | `debug.chaindbProperty(property string)`                    |
+| RPC     | `{"method": "debug_chaindbProperty", "params": [property]}` |
+
+### debug_cpuProfile
+
+Turns on CPU profiling for the given duration and writes profile data to disk.
+
+| Client  | Method invocation                                            |
+| :------ | ------------------------------------------------------------ |
+| Console | `debug.cpuProfile(file, seconds)`                            |
+| RPC     | `{"method": "debug_cpuProfile", "params": [string, number]}` |
+
+### debug_dbAncient
+
+Retrieves an ancient binary blob from the freezer. The freezer is a collection of append-only immutable files. The first argument `kind` specifies which table to look up data from. The list of all table kinds are as follows:
+
+- `headers`: block headers
+- `hashes`: canonical hash table (block number -> block hash)
+- `bodies`: block bodies
+- `receipts`: block receipts
+- `diffs`: total difficulty table (block number -> td)
+
+| Client  | Method invocation                                           |
+| :------ | ----------------------------------------------------------- |
+| Console | `debug.dbAncient(kind string, number uint64)`               |
+| RPC     | `{"method": "debug_dbAncient", "params": [string, number]}` |
+
+### debug_dbAncients
+
+Returns the number of ancient items in the ancient store.
+
+| Client  | Method invocation                |
+| :------ | -------------------------------- |
+| Console | `debug.dbAncients()`             |
+| RPC     | `{"method": "debug_dbAncients"}` |
+
+### debug_dbGet
+
+Returns the raw value of a key stored in the database.
+
+| Client  | Method invocation                            |
+| :------ | -------------------------------------------- |
+| Console | `debug.dbGet(key string)`                    |
+| RPC     | `{"method": "debug_dbGet", "params": [key]}` |
+
+### debug_dumpBlock
+
+Retrieves the state that corresponds to the block number and returns a list of accounts (including storage and code).
+
+| Client  | Method invocation                                     |
+| :------ | ----------------------------------------------------- |
+| Go      | `debug.DumpBlock(number uint64) (state.World, error)` |
+| Console | `debug.traceBlockByHash(number, [options])`           |
+| RPC     | `{"method": "debug_dumpBlock", "params": [number]}`   |
+
+#### Example
+
+```js
+> debug.dumpBlock(10)
+{
+    fff7ac99c8e4feb60c9750054bdc14ce1857f181: {
+      balance: "49358640978154672",
+      code: "",
+      codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
+      nonce: 2,
+      root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+      storage: {}
+    },
+    fffbca3a38c3c5fcb3adbb8e63c04c3e629aafce: {
+      balance: "3460945928",
+      code: "",
+      codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
+      nonce: 657,
+      root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+      storage: {}
+    }
+  },
+  root: "19f4ed94e188dd9c7eb04226bd240fa6b449401a6c656d6d2816a87ccaf206f1"
+}
+```
+
+### debug_freeOSMemory
+
+Forces garbage collection
+
+| Client  | Method invocation                                |
+| :------ | ------------------------------------------------ |
+| Go      | `debug.FreeOSMemory()`                           |
+| Console | `debug.freeOSMemory()`                           |
+| RPC     | `{"method": "debug_freeOSMemory", "params": []}` |
+
+### debug_freezeClient
+
+Forces a temporary client freeze, normally when the server is overloaded. Available as part of LES light server.
+
+| Client  | Method invocation                                    |
+| :------ | ---------------------------------------------------- |
+| Console | `debug.freezeClient(node string)`                    |
+| RPC     | `{"method": "debug_freezeClient", "params": [node]}` |
+
+### debug_gcStats
+
+Returns garbage collection statistics.
+
+See https://golang.org/pkg/runtime/debug/#GCStats for information about the fields of the returned object.
+
+| Client  | Method invocation                           |
+| :------ | ------------------------------------------- |
+| Console | `debug.gcStats()`                           |
+| RPC     | `{"method": "debug_gcStats", "params": []}` |
+
+### debug_getAccessibleState
+
+Returns the first number where the node has accessible state on disk. This is the post-state of that block and the pre-state of the next
+block. The (from, to) parameters are the sequence of blocks to search, which can go either forwards or backwards.
+
+Note: to get the last state pass in the range of blocks in reverse, i.e. (last, first).
+
+| Client  | Method invocation                                              |
+| :------ | -------------------------------------------------------------- |
+| Console | `debug.getAccessibleState(from, to rpc.BlockNumber)`           |
+| RPC     | `{"method": "debug_getAccessibleState", "params": [from, to]}` |
+
+### debug_getBadBlocks
+
+Returns a list of the last 'bad blocks' that the client has seen on the network and returns them as a JSON list of block-hashes.
+
+| Client  | Method invocation                                |
+| :------ | ------------------------------------------------ |
+| Console | `debug.getBadBlocks()`                           |
+| RPC     | `{"method": "debug_getBadBlocks", "params": []}` |
+
+### debug_getBlockRlp
+
+Retrieves and returns the RLP encoded block by number.
+
+| Client  | Method invocation                                     |
+| :------ | ----------------------------------------------------- |
+| Go      | `debug.GetBlockRlp(number uint64) (string, error)`    |
+| Console | `debug.getBlockRlp(number, [options])`                |
+| RPC     | `{"method": "debug_getBlockRlp", "params": [number]}` |
+
+References: [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/)
+
+### debug_getHeaderRlp
+
+Returns an RLP-encoded header.
+
+| Client  | Method invocation                                   |
+| :------ | --------------------------------------------------- |
+| Console | `debug.getHeaderRlp(blockNum)`                      |
+| RPC     | `{"method": "debug_getHeaderRlp", "params": [num]}` |
+
+### debug_getModifiedAccountsByHash
+
+Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash, or storage hash. With one parameter, returns the list of accounts modified in the specified block.
+
+| Client  | Method invocation                                                               |
+| :------ | ------------------------------------------------------------------------------- |
+| Console | `debug.getModifiedAccountsByHash(startHash, endHash)`                           |
+| RPC     | `{"method": "debug_getModifiedAccountsByHash", "params": [startHash, endHash]}` |
+
+### debug_getModifiedAccountsByNumber
+
+Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash or
+storage hash.
+
+| Client  | Method invocation                                                               |
+| :------ | ------------------------------------------------------------------------------- |
+| Console | `debug.getModifiedAccountsByNumber(startNum uint64, endNum uint64)`             |
+| RPC     | `{"method": "debug_getModifiedAccountsByNumber", "params": [startNum, endNum]}` |
+
+### debug_getRawReceipts
+
+Returns the consensus-encoding of all receipts in a single block.
+
+| Client  | Method invocation                                               |
+| :------ | --------------------------------------------------------------- |
+| Console | `debug.getRawReceipts(blockNrOrHash)`                           |
+| RPC     | `{"method": "debug_getRawReceipts", "params": [blockNrOrHash]}` |
+
+### debug_goTrace
+
+Turns on Go runtime tracing for the given duration and writes trace data to disk.
+
+| Client  | Method invocation                                         |
+| :------ | --------------------------------------------------------- |
+| Console | `debug.goTrace(file, seconds)`                            |
+| RPC     | `{"method": "debug_goTrace", "params": [string, number]}` |
+
+### debug_intermediateRoots
+
+Executes a block (bad- or canon- or side-), and returns a list of intermediate roots: the stateroot after each transaction.
+
+| Client  | Method invocation                                                  |
+| :------ | ------------------------------------------------------------------ |
+| Console | `debug.intermediateRoots(blockHash, [options])`                    |
+| RPC     | `{"method": "debug_intermediateRoots", "params": [blockHash, {}]}` |
+
+### debug_memStats
+
+Returns detailed runtime memory statistics.
+
+See https://golang.org/pkg/runtime/#MemStats for information about the fields of the returned object.
+
+| Client  | Method invocation                            |
+| :------ | -------------------------------------------- |
+| Console | `debug.memStats()`                           |
+| RPC     | `{"method": "debug_memStats", "params": []}` |
+
+### debug_mutexProfile
+
+Turns on mutex profiling for nsec seconds and writes profile data to file. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually.
+
+| Client  | Method invocation                                          |
+| :------ | ---------------------------------------------------------- |
+| Console | `debug.mutexProfile(file, nsec)`                           |
+| RPC     | `{"method": "debug_mutexProfile", "params": [file, nsec]}` |
+
+### debug_preimage
+
+Returns the preimage for a sha3 hash, if known.
+
+| Client  | Method invocation                                |
+| :------ | ------------------------------------------------ |
+| Console | `debug.preimage(hash)`                           |
+| RPC     | `{"method": "debug_preimage", "params": [hash]}` |
+
+### debug_printBlock
+
+Retrieves a block and returns its pretty printed form.
+
+| Client  | Method invocation                                    |
+| :------ | ---------------------------------------------------- |
+| Console | `debug.printBlock(number uint64)`                    |
+| RPC     | `{"method": "debug_printBlock", "params": [number]}` |
+
+### debug_seedHash
+
+Fetches and retrieves the seed hash of the block by number
+
+| Client  | Method invocation                                  |
+| :------ | -------------------------------------------------- |
+| Go      | `debug.SeedHash(number uint64) (string, error)`    |
+| Console | `debug.seedHash(number, [options])`                |
+| RPC     | `{"method": "debug_seedHash", "params": [number]}` |
+
+### debug_setBlockProfileRate
+
+Sets the rate (in samples/sec) of goroutine block profile data collection. A non-zero rate enables block profiling, setting it to zero stops the profile. Collected profile data can be written using `debug_writeBlockProfile`.
+
+| Client  | Method invocation                                             |
+| :------ | ------------------------------------------------------------- |
+| Console | `debug.setBlockProfileRate(rate)`                             |
+| RPC     | `{"method": "debug_setBlockProfileRate", "params": [number]}` |
+
+### debug_setGCPercent
+
+Sets the garbage collection target percentage. A negative value disables garbage collection.
+
+| Client  | Method invocation                                 |
+| :------ | ------------------------------------------------- |
+| Go      | `debug.SetGCPercent(v int)`                       |
+| Console | `debug.setGCPercent(v)`                           |
+| RPC     | `{"method": "debug_setGCPercent", "params": [v]}` |
+
+### debug_setHead
+
+Sets the current head of the local chain by block number. **Note**, this is a destructive action and may severely damage your chain. Use with _extreme_ caution.
+
+| Client  | Method invocation                                 |
+| :------ | ------------------------------------------------- |
+| Go      | `debug.SetHead(number uint64)`                    |
+| Console | `debug.setHead(number)`                           |
+| RPC     | `{"method": "debug_setHead", "params": [number]}` |
+
+References:
+[Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining-algorithms/ethash/)
+
+### debug_setMutexProfileFraction
+
+Sets the rate of mutex profiling.
+
+| Client  | Method invocation                                               |
+| :------ | --------------------------------------------------------------- |
+| Console | `debug.setMutexProfileFraction(rate int)`                       |
+| RPC     | `{"method": "debug_setMutexProfileFraction", "params": [rate]}` |
+
+### debug_stacks
+
+Returns a printed representation of the stacks of all goroutines. Note that the web3 wrapper for this method takes care of the printing and does not return the string.
+
+| Client  | Method invocation                          |
+| :------ | ------------------------------------------ |
+| Console | `debug.stacks()`                           |
+| RPC     | `{"method": "debug_stacks", "params": []}` |
+
+### debug_standardTraceBlockToFile
+
+When JS-based tracing (see below) was first implemented, the intended usecase was to enable long-running tracers that could stream results back via a subscription channel. This method works a bit differently. (For full details, see [PR](https://github.com/ethereum/go-ethereum/pull/17914))
+
+- It streams output to disk during the execution, to not blow up the memory usage on the node
+- It uses `jsonl` as output format (to allow streaming)
+- Uses a cross-client standardized output, so called 'standard json'
+  - Uses `op` for string-representation of opcode, instead of `op`/`opName` for numeric/string, and other simlar small differences.
+  - has `refund`
+  - Represents memory as a contiguous chunk of data, as opposed to a list of `32`-byte segments like `debug_traceTransaction`
+
+This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact.
+
+The method can be used to dump a certain transaction out of a given block:
+
+```js
+> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {txHash:"0x4049f61ffbb0747bb88dc1c85dd6686ebf225a3c10c282c45a8e0c644739f7e9", disableMemory:true})
+["/tmp/block_0x0bbe9f14-14-0x4049f61f-099048234"]
+```
+
+Or all txs from a block:
+
+```js
+> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {disableMemory:true})
+["/tmp/block_0x0bbe9f14-0-0xb4502ea7-409046657", "/tmp/block_0x0bbe9f14-1-0xe839be8f-954614764", "/tmp/block_0x0bbe9f14-2-0xc6e2052f-542255195", "/tmp/block_0x0bbe9f14-3-0x01b7f3fe-209673214", "/tmp/block_0x0bbe9f14-4-0x0f290422-320999749", "/tmp/block_0x0bbe9f14-5-0x2dc0fb80-844117472", "/tmp/block_0x0bbe9f14-6-0x35542da1-256306111", "/tmp/block_0x0bbe9f14-7-0x3e199a08-086370834", "/tmp/block_0x0bbe9f14-8-0x87778b88-194603593", "/tmp/block_0x0bbe9f14-9-0xbcb081ba-629580052", "/tmp/block_0x0bbe9f14-10-0xc254381a-578605923", "/tmp/block_0x0bbe9f14-11-0xcc434d58-405931366", "/tmp/block_0x0bbe9f14-12-0xce61967d-874423181", "/tmp/block_0x0bbe9f14-13-0x05a20b35-267153288", "/tmp/block_0x0bbe9f14-14-0x4049f61f-606653767", "/tmp/block_0x0bbe9f14-15-0x46d473d2-614457338", "/tmp/block_0x0bbe9f14-16-0x35cf5500-411906321", "/tmp/block_0x0bbe9f14-17-0x79222961-278569788", "/tmp/block_0x0bbe9f14-18-0xad84e7b1-095032683", "/tmp/block_0x0bbe9f14-19-0x4bd48260-019097038", "/tmp/block_0x0bbe9f14-20-0x1517411d-292624085", "/tmp/block_0x0bbe9f14-21-0x6857e350-971385904", "/tmp/block_0x0bbe9f14-22-0xbe3ae2ca-236639695"]
+
+```
+
+Files are created in a temp-location, with the naming standard `block_<blockhash:4>-<txindex>-<txhash:4>-<random suffix>`. Each opcode immediately streams to file, with no in-geth buffering aside from whatever buffering the os normally does.
+
+On the server side, it also adds some more info when regenerating historical state, namely, the reexec-number if `required historical state is not avaiable` is encountered, so a user can experiment with increasing that setting. It also prints out the remaining block until it reaches target:
+
+```terminal
+INFO [10-15|13:48:25.263] Regenerating historical state            block=2385959 target=2386012 remaining=53   elapsed=3m30.990537767s
+INFO [10-15|13:48:33.342] Regenerating historical state            block=2386012 target=2386012 remaining=0    elapsed=3m39.070073163s
+INFO [10-15|13:48:33.343] Historical state regenerated             block=2386012 elapsed=3m39.070454362s nodes=10.03mB preimages=652.08kB
+INFO [10-15|13:48:33.352] Wrote trace                              file=/tmp/block_0x14490c57-0-0xfbbd6d91-715824834
+INFO [10-15|13:48:33.352] Wrote trace                              file=/tmp/block_0x14490c57-1-0x71076194-187462969
+INFO [10-15|13:48:34.421] Wrote trace file=/tmp/block_0x14490c57-2-0x3f4263fe-056924484
+```
+
+The `options` is as follows:
+
+```js
+type StdTraceConfig struct {
+  *vm.LogConfig
+  Reexec *uint64
+  TxHash *common.Hash
+}
+```
+
+### debug_standardTraceBadBlockToFile
+
+This method is similar to `debug_standardTraceBlockToFile`, but can be used to obtain info about a block which has been _rejected_ as invalid (for some reason).
+
+### debug_startCPUProfile
+
+Turns on CPU profiling indefinitely, writing to the given file.
+
+| Client  | Method invocation                                         |
+| :------ | --------------------------------------------------------- |
+| Console | `debug.startCPUProfile(file)`                             |
+| RPC     | `{"method": "debug_startCPUProfile", "params": [string]}` |
+
+### debug_startGoTrace
+
+Starts writing a Go runtime trace to the given file.
+
+| Client  | Method invocation                                      |
+| :------ | ------------------------------------------------------ |
+| Console | `debug.startGoTrace(file)`                             |
+| RPC     | `{"method": "debug_startGoTrace", "params": [string]}` |
+
+### debug_stopCPUProfile
+
+Stops an ongoing CPU profile.
+
+| Client  | Method invocation                                  |
+| :------ | -------------------------------------------------- |
+| Console | `debug.stopCPUProfile()`                           |
+| RPC     | `{"method": "debug_stopCPUProfile", "params": []}` |
+
+### debug_stopGoTrace
+
+Stops writing the Go runtime trace.
+
+| Client  | Method invocation                               |
+| :------ | ----------------------------------------------- |
+| Console | `debug.startGoTrace(file)`                      |
+| RPC     | `{"method": "debug_stopGoTrace", "params": []}` |
+
+### debug_storageRangeAt
+
+Returns the storage at the given block height and transaction index. The result can be paged by providing a `maxResult` to cap the number of storage slots returned as well as specifying the offset via `keyStart` (hash of storage key).
+
+| Client  | Method invocation                                                                                        |
+| :------ | -------------------------------------------------------------------------------------------------------- |
+| Console | `debug.storageRangeAt(blockHash, txIdx, contractAddress, keyStart, maxResult)`                           |
+| RPC     | `{"method": "debug_storageRangeAt", "params": [blockHash, txIdx, contractAddress, keyStart, maxResult]}` |
+
+### debug_traceBadBlock
+
+Returns the structured logs created during the execution of EVM against a block pulled from the pool of bad ones and returns them as a JSON object.
+For the second parameter see [TraceConfig](#traceconfig) reference.
+
+| Client  | Method invocation                                              |
+| :------ | -------------------------------------------------------------- |
+| Console | `debug.traceBadBlock(blockHash, [options])`                    |
+| RPC     | `{"method": "debug_traceBadBlock", "params": [blockHash, {}]}` |
+
+### debug_traceBlock
+
+The `traceBlock` method will return a full stack trace of all invoked opcodes of all transaction that were included in this block. **Note**, the parent of this block must be present or it will fail. For the second parameter see [TraceConfig](#traceconfig) reference.
+
+| Client  | Method invocation                                                         |
+| :------ | ------------------------------------------------------------------------- |
+| Go      | `debug.TraceBlock(blockRlp []byte, config *TraceConfig) BlockTraceResult` |
+| Console | `debug.traceBlock(tblockRlp, [options])`                                  |
+| RPC     | `{"method": "debug_traceBlock", "params": [blockRlp, {}]}`                |
+
+References:
+[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/)
+
+#### Example
+
+```js
+> debug.traceBlock("0xblock_rlp")
+{
+  gas: 85301,
+  returnValue: "",
+  structLogs: [{
+      depth: 1,
+      error: "",
+      gas: 162106,
+      gasCost: 3,
+      memory: null,
+      op: "PUSH1",
+      pc: 0,
+      stack: [],
+      storage: {}
+  },
+    /* snip */
+  {
+      depth: 1,
+      error: "",
+      gas: 100000,
+      gasCost: 0,
+      memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"],
+      op: "STOP",
+      pc: 120,
+      stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"],
+      storage: {
+        0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001",
+        0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001",
+        f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad"
+      }
+  }]
+```
+
+### debug_traceBlockByNumber
+
+Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByNumber` accepts a block number and will replay the block that is already present in the database. For the second parameter see [TraceConfig](#traceconfig) reference.
+
+| Client  | Method invocation                                                               |
+| :------ | ------------------------------------------------------------------------------- |
+| Go      | `debug.TraceBlockByNumber(number uint64, config *TraceConfig) BlockTraceResult` |
+| Console | `debug.traceBlockByNumber(number, [options])`                                   |
+| RPC     | `{"method": "debug_traceBlockByNumber", "params": [number, {}]}`                |
+
+References:
+[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/)
+
+### debug_traceBlockByHash
+
+Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByHash` accepts a block hash and will replay the block that is already present in the database. For the second parameter see [TraceConfig](#traceconfig) reference.
+
+| Client  | Method invocation                                                                |
+| :------ | -------------------------------------------------------------------------------- |
+| Go      | `debug.TraceBlockByHash(hash common.Hash, config *TraceConfig) BlockTraceResult` |
+| Console | `debug.traceBlockByHash(hash, [options])`                                        |
+| RPC     | `{"method": "debug_traceBlockByHash", "params": [hash {}]}`                      |
+
+References:
+[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/)
+
+### debug_traceBlockFromFile
+
+Similar to [debug_traceBlock](#debug_traceblock), `traceBlockFromFile` accepts a file containing the RLP of the block. For the second parameter see [TraceConfig](#traceconfig) reference.
+
+| Client  | Method invocation                                                                 |
+| :------ | --------------------------------------------------------------------------------- |
+| Go      | `debug.TraceBlockFromFile(fileName string, config *TraceConfig) BlockTraceResult` |
+| Console | `debug.traceBlockFromFile(fileName, [options])`                                   |
+| RPC     | `{"method": "debug_traceBlockFromFile", "params": [fileName, {}]}`                |
+
+References:
+[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/)
+
+### debug_traceCall
+
+The `debug_traceCall` method lets you run an `eth_call` within the context of the given block execution using the final state of parent block as the base. The first argument (just as in `eth_call`) is a [transaction object](/docs/interacting-with-geth/rpc/objects#transaction-call-object). The block can be specified either by hash or by number as the second argument. The trace can be configured similar to `debug_traceTransaction`, see [TraceConfig](#traceconfig). The method returns the same output as `debug_traceTransaction`.
+
+| Client  | Method invocation                                                                                                           |
+| :-----: | --------------------------------------------------------------------------------------------------------------------------- |
+|   Go    | `debug.TraceCall(args ethapi.CallArgs, blockNrOrHash rpc.BlockNumberOrHash, config *TraceConfig) (*ExecutionResult, error)` |
+| Console | `debug.traceCall(object, blockNrOrHash, [options])`                                                                         |
+|   RPC   | `{"method": "debug_traceCall", "params": [object, blockNrOrHash, {}]}`                                                      |
+
+#### Example
+
+No specific call options:
+
+```js
+> debug.traceCall(null, "0x0")
+{
+  failed: false,
+  gas: 53000,
+  returnValue: "",
+  structLogs: []
+}
+```
+
+Tracing a call with a destination and specific sender, disabling the storage and memory output (less data returned over RPC)
+
+```js
+debug.traceCall(
+  {
+    from: '0xdeadbeef29292929192939494959594933929292',
+    to: '0xde929f939d939d393f939393f93939f393929023',
+    gas: '0x7a120',
+    data: '0xf00d4b5d00000000000000000000000001291230982139282304923482304912923823920000000000000000000000001293123098123928310239129839291010293810'
+  },
+  'latest',
+  { disableStorage: true, disableMemory: true }
+);
+```
+
+It is possible to supply 'overrides' for both state-data (accounts/storage) and block data (number, timestamp etc). In the example below, a call which executes `NUMBER` is performed, and the overridden number is placed on the stack:
+
+```js
+> debug.traceCall({
+	from: eth.accounts[0],
+	value:"0x1",
+	gasPrice: "0xffffffff",
+	gas: "0xffff",
+	input: "0x43"},
+	"latest",
+	{"blockoverrides":
+		{"number": "0x50"}
+	})
+{
+  failed: false,
+  gas: 53018,
+  returnValue: "",
+  structLogs: [{
+      depth: 1,
+      gas: 12519,
+      gasCost: 2,
+      op: "NUMBER",
+      pc: 0,
+      stack: []
+  }, {
+      depth: 1,
+      gas: 12517,
+      gasCost: 0,
+      op: "STOP",
+      pc: 1,
+      stack: ["0x50"]
+  }]
+}
+```
+
+Curl example:
+
+```sh
+> curl -H "Content-Type: application/json" -X POST  localhost:8545 --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[null, "pending"],"id":1}'
+{"jsonrpc":"2.0","id":1,"result":{"gas":53000,"failed":false,"returnValue":"","structLogs":[]}}
+```
+
+### debug_traceChain
+
+Returns the structured logs created during the execution of EVM between two blocks (excluding start) as a JSON object. This endpoint must be invoked via `debug_subscribe` as follows:
+
+```js
+const res = provider.send('debug_subscribe', ['traceChain', '0x3f3a2a', '0x3f3a2b'])`
+```
+
+please refer to the [subscription page](/docs/interacting-with-geth/rpc/pubsub) for more details.
+
+### debug_traceTransaction
+
+**OBS** In most scenarios, `debug.standardTraceBlockToFile` is better suited for tracing!
+
+The `traceTransaction` debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given
+hash.
+
+| Client  | Method invocation                                                                           |
+| :------ | ------------------------------------------------------------------------------------------- |
+| Go      | `debug.TraceTransaction(txHash common.Hash, config *TraceConfig) (*ExecutionResult, error)` |
+| Console | `debug.traceTransaction(txHash, [options])`                                                 |
+| RPC     | `{"method": "debug_traceTransaction", "params": [txHash, {}]}`                              |
+
+#### TraceConfig
+
+In addition to the hash of the transaction you may give it a secondary _optional_ argument, which specifies the options for this specific call. The possible options are:
+
+- `disableStorage`: `BOOL`. Setting this to true will disable storage capture (default = false).
+- `disableStack`: `BOOL`. Setting this to true will disable stack capture (default = false).
+- `enableMemory`: `BOOL`. Setting this to true will enable memory capture (default = false).
+- `enableReturnData`: `BOOL`. Setting this to true will enable return data capture (default = false).
+- `tracer`: `STRING`. Name for built-in tracer or Javascript expression. See below for more details.
+
+If set, the previous four arguments will be ignored.
+
+- `timeout`: `STRING`. Overrides the default timeout of 5 seconds for JavaScript-based tracing calls.
+  Valid values are described [here](https://golang.org/pkg/time/#ParseDuration).
+- `tracerConfig`: Config for the specified `tracer`. For example see callTracer's [config](/docs/developers/evm-tracing/built-in-tracers#config).
+
+Geth comes with a bundle of [built-in tracers](/docs/developers/evm-tracing/built-in-tracers), each providing various data about a transaction. This method defaults to the [struct logger](/docs/developers/evm-tracing/built-in-tracers#structopcode-logger). The `tracer` field of the second parameter can be set to use any of the other tracers. Alternatively a [custom tracer](/docs/developers/evm-tracing/custom-tracer) can be implemented in either Go or Javascript.
+
+#### Example
+
+```js
+> debug.traceTransaction("0x2059dd53ecac9827faad14d364f9e04b1d5fe5b506e3acc886eff7a6f88a696a")
+{
+  gas: 85301,
+  returnValue: "",
+  structLogs: [{
+      depth: 1,
+      error: "",
+      gas: 162106,
+      gasCost: 3,
+      memory: null,
+      op: "PUSH1",
+      pc: 0,
+      stack: [],
+      storage: {}
+  },
+    /* snip */
+  {
+      depth: 1,
+      error: "",
+      gas: 100000,
+      gasCost: 0,
+      memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"],
+      op: "STOP",
+      pc: 120,
+      stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"],
+      storage: {
+        0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001",
+        0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001",
+        f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad"
+      }
+  }]
+```
+
+### debug_verbosity
+
+Sets the logging verbosity ceiling. Log messages with level up to and including the given level will be printed.
+
+The verbosity of individual packages and source files can be raised using `debug_vmodule`.
+
+| Client  | Method invocation                                 |
+| :------ | ------------------------------------------------- |
+| Console | `debug.verbosity(level)`                          |
+| RPC     | `{"method": "debug_vmodule", "params": [number]}` |
+
+### debug_vmodule
+
+Sets the logging verbosity pattern.
+
+| Client  | Method invocation                                 |
+| :------ | ------------------------------------------------- |
+| Console | `debug.vmodule(string)`                           |
+| RPC     | `{"method": "debug_vmodule", "params": [string]}` |
+
+#### Examples
+
+If you want to see messages from a particular Go package (directory) and all subdirectories, use:
+
+```js
+> debug.vmodule("eth/*=6")
+```
+
+If you want to restrict messages to a particular package (e.g. p2p) but exclude subdirectories, use:
+
+```js
+> debug.vmodule("p2p=6")
+```
+
+If you want to see log messages from a particular source file, use
+
+```js
+> debug.vmodule("server.go=6")
+```
+
+You can compose these basic patterns. If you want to see all output from peer.go in a package below eth (eth/peer.go, eth/downloader/peer.go) as well as output from package p2p at level <= 5, use:
+
+```js
+debug.vmodule('eth/*/peer.go=6,p2p=5');
+```
+
+### debug_writeBlockProfile
+
+Writes a goroutine blocking profile to the given file.
+
+| Client  | Method invocation                                           |
+| :------ | ----------------------------------------------------------- |
+| Console | `debug.writeBlockProfile(file)`                             |
+| RPC     | `{"method": "debug_writeBlockProfile", "params": [string]}` |
+
+### debug_writeMemProfile
+
+Writes an allocation profile to the given file. Note that the profiling rate cannot be set through the API, it must be set on the command line using the `--pprof.memprofilerate` flag.
+
+| Client  | Method invocation                                           |
+| :------ | ----------------------------------------------------------- |
+| Console | `debug.writeMemProfile(file string)`                        |
+| RPC     | `{"method": "debug_writeBlockProfile", "params": [string]}` |
+
+### debug_writeMutexProfile
+
+Writes a goroutine blocking profile to the given file.
+
+| Client  | Method invocation                                         |
+| :------ | --------------------------------------------------------- |
+| Console | `debug.writeMutexProfile(file)`                           |
+| RPC     | `{"method": "debug_writeMutexProfile", "params": [file]}` |

docs/interacting-with-geth/rpc/ns-eth.md

@@ -0,0 +1,177 @@
+---
+title: eth Namespace
+description: Documentation for the JSON-RPC API "eth" namespace
+---
+
+Documentation for the API methods in the `eth` namespace can be found on [ethereum.org](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_protocolversion). Geth provides several extensions to the standard "eth" JSON-RPC namespace that are defined below.
+
+### eth_subscribe, eth_unsubscribe {#eth-subscribe-unsubscribe}
+
+These methods are used for real-time events through subscriptions. See the [subscription documentation](/docs/interacting-with-geth/rpc/pubsub) for more information.
+
+### eth_call {#eth-call}
+
+Executes a new message call immediately, without creating a transaction on the block chain. The `eth_call` method can be used to query internal contract state, to execute validations coded into a contract or even to test what the effect of a transaction would be without running it live.
+
+#### Parameters
+
+The method takes 3 parameters: an unsigned transaction object to execute in read-only mode; the block number to execute the call against; and an optional state override-set to allow executing the call against a modified chain state.
+
+##### 1. `Object` - Transaction call object
+
+The _transaction call object_ is mandatory. Please see [here](/docs/interacting-with-geth/rpc/objects) for details.
+
+##### 2. `Quantity | Tag` - Block number or the string `latest` or `pending`
+
+The _block number_ is mandatory and defines the context (state) against which the specified transaction should be executed. It is not possible to execute calls against reorged blocks; or blocks older than 128 (unless the node is an archive node).
+
+##### 3. `Object` - State override set
+
+The _state override set_ is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call. Each address maps to an object containing:
+
+| Field       | Type       | Bytes | Optional | Description                                                                                               |
+| :---------- | :--------- | :---- | :------- | :-------------------------------------------------------------------------------------------------------- |
+| `balance`   | `Quantity` | <32   | Yes      | Fake balance to set for the account before executing the call.                                            |
+| `nonce`     | `Quantity` | <8    | Yes      | Fake nonce to set for the account before executing the call.                                              |
+| `code`      | `Binary`   | any   | Yes      | Fake EVM bytecode to inject into the account before executing the call.                                   |
+| `state`     | `Object`   | any   | Yes      | Fake key-value mapping to override **all** slots in the account storage before executing the call.        |
+| `stateDiff` | `Object`   | any   | Yes      | Fake key-value mapping to override **individual** slots in the account storage before executing the call. |
+
+The goal of the _state override set_ is manyfold:
+
+- It can be used by DApps to reduce the amount of contract code needed to be deployed on chain. Code that simply returns internal state or does pre-defined validations can be kept off chain and fed to the node on-demand.
+- It can be used for smart contract analysis by extending the code deployed on chain with custom methods and invoking them. This avoids having to download and reconstruct the entire state in a sandbox to run custom code against.
+
+- It can be used to debug smart contracts in an already deployed large suite of contracts by selectively overriding some code or state and seeing how execution changes. Specialized tooling will probably be necessary.
+
+Example:
+
+```json
+{
+  "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3": {
+    "balance": "0xde0b6b3a7640000"
+  },
+  "0xebe8efa441b9302a0d7eaecc277c09d20d684540": {
+    "code": "0x...",
+    "state": {
+      ""
+    }
+  }
+}
+```
+
+#### Return Values
+
+The method returns a single `Binary` consisting the return value of the executed contract call.
+
+#### Simple example
+
+**note that this example uses the Rinkeby network, which is now deprecated**
+
+With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --http`) we can make a call against the [CheckpointOracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540) to retrieve the list of administrators:
+
+```sh
+$ curl --data '{"method":"eth_call","params":[{"to":"0xebe8efa441b9302a0d7eaecc277c09d20d684540","data":"0x45848dfc"},"latest"],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
+```
+
+And the result is an Ethereum ABI encoded list of accounts:
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": "0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004000000000000000000000000d9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f300000000000000000000000078d1ad571a1a09d60d9bbf25894b44e4c8859595000000000000000000000000286834935f4a8cfb4ff4c77d5770c2775ae2b0e7000000000000000000000000b86e2b0ab5a4b1373e40c51a7c712c70ba2f9f8e"
+}
+```
+
+Just for the sake of completeness, decoded the response is:
+
+```sh
+0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3,
+0x78d1ad571a1a09d60d9bbf25894b44e4c8859595,
+0x286834935f4a8cfb4ff4c77d5770c2775ae2b0e7,
+0xb86e2b0ab5a4b1373e40c51a7c712c70ba2f9f8e
+```
+
+#### Override example
+
+The above _simple example_ showed how to call a method already exposed by an on-chain smart contract. What if we want to access some data not exposed by it?
+
+We can gut out the [original](https://github.com/ethereum/go-ethereum/blob/master/contracts/checkpointoracle/contract/oracle.sol) checkpoint oracle contract with one that retains the same fields (to retain the same storage layout), but one that includes a different method set:
+
+```js
+pragma solidity ^0.5.10;
+
+contract CheckpointOracle {
+    mapping(address => bool) admins;
+    address[] adminList;
+    uint64 sectionIndex;
+    uint height;
+    bytes32 hash;
+    uint sectionSize;
+    uint processConfirms;
+    uint threshold;
+
+    function VotingThreshold() public view returns (uint) {
+        return threshold;
+    }
+}
+```
+
+With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --http`) we can make a call against the live [Checkpoint Oracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540), but override its byte code with our own version that has an accessor for the voting
+threshold field:
+
+```sh
+$ curl --data '{"method":"eth_call","params":[{"to":"0xebe8efa441b9302a0d7eaecc277c09d20d684540","data":"0x0be5b6ba"}, "latest", {"0xebe8efa441b9302a0d7eaecc277c09d20d684540": {"code":"0x6080604052348015600f57600080fd5b506004361060285760003560e01c80630be5b6ba14602d575b600080fd5b60336045565b60408051918252519081900360200190f35b6007549056fea265627a7a723058206f26bd0433456354d8d1228d8fe524678a8aeeb0594851395bdbd35efc2a65f164736f6c634300050a0032"}}],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
+```
+
+And the result is the Ethereum ABI encoded threshold number:
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": "0x0000000000000000000000000000000000000000000000000000000000000002"
+}
+```
+
+Just for the sake of completeness, decoded the response is: `2`.
+
+### eth_createAccessList {#eth-createaccesslist}
+
+This method creates an [EIP2930](https://eips.ethereum.org/EIPS/eip-2930) type `accessList` based on a given `Transaction`. The `accessList` contains all storage slots and addresses read and written by the transaction, except for the sender account and the precompiles. This method uses the same `transaction` call [object](/docs/interacting-with-geth/rpc/objects#transaction-call-object) and `blockNumberOrTag` object as `eth_call`. An `accessList` can be used to unstuck contracts that became inaccessible due to gas cost increases.
+
+#### Parameters
+
+| Field              | Type     | Description                                    |
+| :----------------- | :------- | :--------------------------------------------- |
+| `transaction`      | `Object` | `TransactionCall` object                       |
+| `blockNumberOrTag` | `Object` | Optional, blocknumber or `latest` or `pending` |
+
+#### Usage
+
+```
+curl --data '{"method":"eth_createAccessList","params":[{"from": "0x8cd02c6cbd8375b39b06577f8d50c51d86e8d5cd", "data": "0x608060806080608155"}, "pending"],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
+```
+
+#### Response
+
+The method `eth_createAccessList` returns list of addresses and storage keys used by the transaction, plus the gas consumed when the access list is added.
+
+That is, it gives the list of addresses and storage keys that will be used by that transaction, plus the gas consumed if the access list is included. Like `eth_estimateGas`, this is an estimation; the list could change when the transaction is actually mined. Adding an `accessList` to a transaction does not necessary result in lower gas usage compared to a transaction without an access list.
+
+Example:
+
+```json
+{
+  "accessList": [
+    {
+      "address": "0xa02457e5dfd32bda5fc7e1f1b008aa5979568150",
+      "storageKeys": [
+        "0x0000000000000000000000000000000000000000000000000000000000000081",
+      ]
+    }
+  ]
+  "gasUsed": "0x125f8"
+}
+```

docs/interacting-with-geth/rpc/ns-les.md

@@ -0,0 +1,314 @@
+---
+title: les Namespace
+description: Documentation for the JSON-RPC API "les" namespace
+---
+
+The `les` API is for managing LES server settings, including client parameters and payment settings for prioritized clients. It also provides functions to query checkpoint information in both server and client mode.
+
+## les_serverInfo {#les-serverinfo}
+
+Get information about currently connected and total/individual allowed connection capacity.
+
+| Client  | Method invocation                            |
+| :------ | -------------------------------------------- |
+| Go      | `les.ServerInfo() map[string]interface{}`    |
+| Console | `les.serverInfo()`                           |
+| RPC     | `{"method": "les_serverInfo", "params": []}` |
+
+### Example
+
+```js
+> les.serverInfo
+{
+  freeClientCapacity: 16000,
+  maximumCapacity: 1600000,
+  minimumCapacity: 16000,
+  priorityConnectedCapacity: 180000,
+  totalCapacity: 1600000,
+  totalConnectedCapacity: 180000
+}
+```
+
+## les_clientInfo {#les-clientinfo}
+
+Get individual client information (connection, balance, pricing) on the specified list of clients or for all connected clients if the ID list is empty.
+
+| Client  | Method invocation                                                    |
+| :------ | -------------------------------------------------------------------- |
+| Go      | `les.ClientInfo(ids []enode.ID) map[enode.ID]map[string]interface{}` |
+| Console | `les.clientInfo([id, ...])`                                          |
+| RPC     | `{"method": "les_clientInfo", "params": [[id, ...]]}`                |
+
+### Example
+
+```js
+> les.clientInfo([])
+{
+  37078bf8ea160a2b3d129bb4f3a930ce002356f83b820f467a07c1fe291531ea: {
+    capacity: 16000,
+    connectionTime: 11225.335901136,
+    isConnected: true,
+    pricing/balance: 998266395881,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 501657912857,
+    priority: true
+  },
+  6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77: {
+    capacity: 100000,
+    connectionTime: 9874.839293082,
+    isConnected: true,
+    pricing/balance: 2908840710198,
+    pricing/balanceMeta: "qwerty",
+    pricing/negBalance: 206242704507,
+    priority: true
+  },
+  740c78f7d914e5c763731bc751b513fc2388ffa0b47db080ded3e8b305e68c75: {
+    capacity: 16000,
+    connectionTime: 3089.286712188,
+    isConnected: true,
+    pricing/balance: 998266400174,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 55135348863,
+    priority: true
+  },
+  9985ade55b515f79f64274bf2ae440ca8c433cfb0f283fb6010bf46f796b2a3b: {
+    capacity: 16000,
+    connectionTime: 11479.335479545,
+    isConnected: true,
+    pricing/balance: 998266452203,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 564116425655,
+    priority: true
+  },
+  ce65ada2c3e17d6da00cec0b3cc4c8ed5e74428b60f42fa287eaaec8cca62544: {
+    capacity: 16000,
+    connectionTime: 7095.794385419,
+    isConnected: true,
+    pricing/balance: 998266448492,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 214617753229,
+    priority: true
+  },
+  e1495ceb6db842f3ee66428d4bb7f4a124b2b17111dae35d141c3d568b869ef1: {
+    capacity: 16000,
+    connectionTime: 8614.018237937,
+    isConnected: true,
+    pricing/balance: 998266391796,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 185964891797,
+    priority: true
+  }
+}
+```
+
+## les_priorityClientInfo {#les-priorityclientinfo}
+
+Get individual client information on clients with a positive balance in the specified ID range, `start` included, `stop` excluded. If `stop` is zero then results are returned until the last existing balance entry. `maxCount` limits the number of returned results. If the count limit is reached but there are more IDs in the range then the first missing ID is included in the result with an empty value assigned to it.
+
+| Client  | Method invocation                                                                                |
+| :------ | ------------------------------------------------------------------------------------------------ |
+| Go      | `les.PriorityClientInfo(start, stop enode.ID, maxCount int) map[enode.ID]map[string]interface{}` |
+| Console | `les.priorityClientInfo(id, id, number)`                                                         |
+| RPC     | `{"method": "les_priorityClientInfo", "params": [id, id, number]}`                               |
+
+### Example
+
+```js
+> les.priorityClientInfo("0x0000000000000000000000000000000000000000000000000000000000000000", "0x0000000000000000000000000000000000000000000000000000000000000000", 100)
+{
+  37078bf8ea160a2b3d129bb4f3a930ce002356f83b820f467a07c1fe291531ea: {
+    capacity: 16000,
+    connectionTime: 11128.247204027,
+    isConnected: true,
+    pricing/balance: 999819815030,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 501657912857,
+    priority: true
+  },
+  6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77: {
+    capacity: 100000,
+    connectionTime: 9777.750592047,
+    isConnected: true,
+    pricing/balance: 2918549830576,
+    pricing/balanceMeta: "qwerty",
+    pricing/negBalance: 206242704507,
+    priority: true
+  },
+  740c78f7d914e5c763731bc751b513fc2388ffa0b47db080ded3e8b305e68c75: {
+    capacity: 16000,
+    connectionTime: 2992.198001116,
+    isConnected: true,
+    pricing/balance: 999819845102,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 55135348863,
+    priority: true
+  },
+  9985ade55b515f79f64274bf2ae440ca8c433cfb0f283fb6010bf46f796b2a3b: {
+    capacity: 16000,
+    connectionTime: 11382.246766963,
+    isConnected: true,
+    pricing/balance: 999819871598,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 564116425655,
+    priority: true
+  },
+  ce65ada2c3e17d6da00cec0b3cc4c8ed5e74428b60f42fa287eaaec8cca62544: {
+    capacity: 16000,
+    connectionTime: 6998.705683407,
+    isConnected: true,
+    pricing/balance: 999819882177,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 214617753229,
+    priority: true
+  },
+  e1495ceb6db842f3ee66428d4bb7f4a124b2b17111dae35d141c3d568b869ef1: {
+    capacity: 16000,
+    connectionTime: 8516.929533901,
+    isConnected: true,
+    pricing/balance: 999819891640,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 185964891797,
+    priority: true
+  }
+}
+
+> les.priorityClientInfo("0x4000000000000000000000000000000000000000000000000000000000000000", "0xe000000000000000000000000000000000000000000000000000000000000000", 2)
+{
+  6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77: {
+    capacity: 100000,
+    connectionTime: 9842.11178361,
+    isConnected: true,
+    pricing/balance: 2912113588853,
+    pricing/balanceMeta: "qwerty",
+    pricing/negBalance: 206242704507,
+    priority: true
+  },
+  740c78f7d914e5c763731bc751b513fc2388ffa0b47db080ded3e8b305e68c75: {
+    capacity: 16000,
+    connectionTime: 3056.559199029,
+    isConnected: true,
+    pricing/balance: 998790060237,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 55135348863,
+    priority: true
+  },
+  9985ade55b515f79f64274bf2ae440ca8c433cfb0f283fb6010bf46f796b2a3b: {}
+}
+```
+
+## les_addBalance {#les-addbalance}
+
+Add signed value to the token balance of the specified client and update its `meta` tag. The balance cannot go below zero or over `2^^63-1`. The balance values before and after the update are returned. The `meta` tag can be used to store a sequence number or reference to the last processed incoming payment, token expiration info, balance in other currencies or any application-specific additional information.
+
+| Client  | Method invocation                                                           |
+| :------ | --------------------------------------------------------------------------- |
+| Go      | `les.AddBalance(id enode.ID, value int64, meta string) ([2]uint64, error)}` |
+| Console | `les.addBalance(id, number, string)`                                        |
+| RPC     | `{"method": "les_addBalance", "params": [id, number, string]}`              |
+
+### Example
+
+```js
+> les.addBalance("0x6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77", 1000000000, "qwerty")
+[968379616, 1968379616]
+```
+
+## les_setClientParams {#les-setclientparams}
+
+Set capacity and pricing factors for the specified list of connected clients or for all connected clients if the ID list is empty.
+
+| Client  | Method invocation                                                                |
+| :------ | -------------------------------------------------------------------------------- |
+| Go      | `les.SetClientParams(ids []enode.ID, params map[string]interface{}) error`       |
+| Console | `les.setClientParams([id, ...], {string: value, ...})`                           |
+| RPC     | `{"method": "les_setClientParams", "params": [[id, ...], {string: value, ...}]}` |
+
+### Example
+
+```js
+> les.setClientParams(["0x6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77"], {
+	"capacity": 100000,
+	"pricing/timeFactor": 0,
+	"pricing/capacityFactor": 1000000000,
+	"pricing/requestCostFactor": 1000000000,
+	"pricing/negative/timeFactor": 0,
+	"pricing/negative/capacityFactor": 1000000000,
+	"pricing/negative/requestCostFactor": 1000000000,
+})
+null
+```
+
+## les_setDefaultParams {#les-setdefaultparams}
+
+Set default pricing factors for subsequently connected clients.
+
+| Client  | Method invocation                                                      |
+| :------ | ---------------------------------------------------------------------- |
+| Go      | `les.SetDefaultParams(params map[string]interface{}) error`            |
+| Console | `les.setDefaultParams({string: value, ...})`                           |
+| RPC     | `{"method": "les_setDefaultParams", "params": [{string: value, ...}]}` |
+
+### Example
+
+```js
+> les.setDefaultParams({
+	"pricing/timeFactor": 0,
+	"pricing/capacityFactor": 1000000000,
+	"pricing/requestCostFactor": 1000000000,
+	"pricing/negative/timeFactor": 0,
+	"pricing/negative/capacityFactor": 1000000000,
+	"pricing/negative/requestCostFactor": 1000000000,
+})
+null
+```
+
+## les_latestCheckpoint {#les-latestcheckpoint}
+
+Get the index and hashes of the latest known checkpoint.
+
+| Client  | Method invocation                                  |
+| :------ | -------------------------------------------------- |
+| Go      | `les.LatestCheckpoint() ([4]string, error)`        |
+| Console | `les.latestCheckpoint()`                           |
+| RPC     | `{"method": "les_latestCheckpoint", "params": []}` |
+
+### Example
+
+```js
+> les.latestCheckpoint
+["0x110", "0x6eedf8142d06730b391bfcbd32e9bbc369ab0b46ae226287ed5b29505a376164", "0x191bb2265a69c30201a616ae0d65a4ceb5937c2f0c94b125ff55343d707463e5", "0xf58409088a5cb2425350a59d854d546d37b1e7bef8bbf6afee7fd15f943d626a"]
+```
+
+## les_getCheckpoint {#les-getcheckpoint}
+
+Get checkpoint hashes by index.
+
+| Client  | Method invocation                                     |
+| :------ | ----------------------------------------------------- |
+| Go      | `les.GetCheckpoint(index uint64) ([3]string, error)`  |
+| Console | `les.getCheckpoint(number)`                           |
+| RPC     | `{"method": "les_getCheckpoint", "params": [number]}` |
+
+### Example
+
+```js
+> les.getCheckpoint(256)
+["0x93eb4af0b224b1097e09181c2e51536fe0a3bf3bb4d93e9a69cab9eb3e28c75f", "0x0eb055e384cf58bc72ca20ca5e2b37d8d4115dce80ab4a19b72b776502c4dd5b", "0xda6c02f7c51f9ecc3eca71331a7eaad724e5a0f4f906ce9251a2f59e3115dd6a"]
+```
+
+## les_getCheckpointContractAddress {#les-getcheckpointcontractaddress}
+
+Get the address of the checkpoint oracle contract.
+
+| Client  | Method invocation                                              |
+| :------ | -------------------------------------------------------------- |
+| Go      | `les.GetCheckpointContractAddress() (string, error)`           |
+| Console | `les.checkpointContractAddress()`                              |
+| RPC     | `{"method": "les_getCheckpointContractAddress", "params": []}` |
+
+### Example
+
+```js
+> les.checkpointContractAddress
+"0x9a9070028361F7AAbeB3f2F2Dc07F82C4a98A02a"
+```

docs/interacting-with-geth/rpc/ns-miner.md

@@ -0,0 +1,84 @@
+---
+title: miner Namespace
+description: Documentation for the JSON-RPC API "miner" namespace
+---
+
+The `miner` API is **now deprecated** because mining was switched off at the transition to proof-of-stake. It existed to provide remote control the node's mining operation and set various mining specific settings. It is provided here for historical interest!
+
+## miner_getHashrate {#miner-hashrate}
+
+Get hashrate in H/s (Hash operations per second).
+
+| Client  | Method invocation                               |
+| :------ | ----------------------------------------------- |
+| Console | `miner.getHashrate()`                           |
+| RPC     | `{"method": "miner_getHashrate", "params": []}` |
+
+## miner_setExtra {#miner-setextra}
+
+Sets the extra data a miner can include when miner blocks. This is capped at 32 bytes.
+
+| Client  | Method invocation                                  |
+| :------ | -------------------------------------------------- |
+| Go      | `miner.setExtra(extra string) (bool, error)`       |
+| Console | `miner.setExtra(string)`                           |
+| RPC     | `{"method": "miner_setExtra", "params": [string]}` |
+
+## miner_setGasPrice {#miner-setgasprice}
+
+Sets the minimal accepted gas price when mining transactions. Any transactions that are below this limit are excluded from the mining process.
+
+| Client  | Method invocation                                     |
+| :------ | ----------------------------------------------------- |
+| Go      | `miner.setGasPrice(number *rpc.HexNumber) bool`       |
+| Console | `miner.setGasPrice(number)`                           |
+| RPC     | `{"method": "miner_setGasPrice", "params": [number]}` |
+
+## miner_setRecommitInterval {#miner-setrecommitinterval}
+
+Updates the interval for recomitting the miner sealing work.
+
+| Client  | Method invocation                                             |
+| :------ | ------------------------------------------------------------- |
+| Console | `miner.setRecommitInterval(interval int)`                     |
+| RPC     | `{"method": "miner_setRecommitInterval", "params": [number]}` |
+
+## miner_start {#miner-start}
+
+Start the CPU mining process with the given number of threads and generate a new DAG if need be.
+
+| Client  | Method invocation                                   |
+| :------ | --------------------------------------------------- |
+| Go      | `miner.Start(threads *rpc.HexNumber) (bool, error)` |
+| Console | `miner.start(number)`                               |
+| RPC     | `{"method": "miner_start", "params": [number]}`     |
+
+## miner_stop {#miner-stop}
+
+Stop the CPU mining operation.
+
+| Client  | Method invocation                        |
+| :------ | ---------------------------------------- |
+| Go      | `miner.Stop() bool`                      |
+| Console | `miner.stop()`                           |
+| RPC     | `{"method": "miner_stop", "params": []}` |
+
+## miner_setEtherbase {#miner-setetherbase}
+
+Sets the etherbase, where mining rewards will go.
+
+| Client  | Method invocation                                       |
+| :------ | ------------------------------------------------------- |
+| Go      | `miner.SetEtherbase(common.Address) bool`               |
+| Console | `miner.setEtherbase(address)`                           |
+| RPC     | `{"method": "miner_setEtherbase", "params": [address]}` |
+
+## miner_setGasLimit {#miner-setgaslimit}
+
+Sets the gas limit the miner will target when mining. Note: on networks where EIP-1559 is activated, this should be set to twice the gas target (i.e. the effective gas used on average per block) to be.
+
+| Client  | Method invocation                                     |
+| :------ | ----------------------------------------------------- |
+| Go      | `miner.SetGasLimit(number *rpc.HexNumber) bool`       |
+| Console | `miner.SetGasLimit(number)`                           |
+| RPC     | `{"method": "miner_setGasLimit", "params": [number]}` |

docs/interacting-with-geth/rpc/ns-net.md

@@ -0,0 +1,33 @@
+---
+title: net Namespace
+description: Documentation for the JSON-RPC API "net" namespace
+---
+
+The `net` API provides insight about the networking aspect of the client.
+
+## net_listening {#net-listening}
+
+Returns an indication if the node is listening for network connections.
+
+| Client  | Method invocation             |
+| :------ | ----------------------------- |
+| Console | `net.listening`               |
+| RPC     | `{"method": "net_listening"}` |
+
+## net_peerCount {#net-peercount}
+
+Returns the number of connected peers.
+
+| Client  | Method invocation             |
+| :------ | ----------------------------- |
+| Console | `net.peerCount`               |
+| RPC     | `{"method": "net_peerCount"}` |
+
+## net_version {#net-version}
+
+Returns the devp2p network ID (e.g. 1 for mainnet, 5 for goerli).
+
+| Client  | Method invocation           |
+| :------ | --------------------------- |
+| Console | `net.version`               |
+| RPC     | `{"method": "net_version"}` |

docs/interacting-with-geth/rpc/ns-personal-deprecation.md

@@ -0,0 +1,221 @@
+---
+title: Personal namespace deprecation notes
+description: Alternatives to the methods in the deprecated personal namespace
+---
+
+The JSON-RPC API's `personal` namespace has historically been used to manage accounts and sign transactions and data over RPC. However, it is being deprecated in favour of using [Clef](/docs/tools/clef/introduction) as an external signer and account manager. One of the major changes is moving away from indiscriminate locking and unlocking of accounts and instead using Clef to explicitly approve or deny specific actions. This page shows the suggested replacement for each method in `personal`.
+
+## Methods without replacements
+
+### personal_unlockAccount
+
+There is no need for a direct replacement for `personal_unlockAccount`. Using Clef to manually approve actions or to attest custom rulesets is a much more secure way to interact with accounts without needing to indiscriminately unlock accounts.
+
+### personal_lockAccount
+
+There is no need for a direct replacement for `personal_lockAccount` because account locking/unlocking is replaced by Clef's approve/deny logic. This is a more secure way to interact with accounts.
+
+### personal.unpair
+
+Unpair deletes a pairing between some specific types of smartcard wallet and Geth. There is not yet an equivalent method in Clef.
+
+### personal_initializeWallet
+
+InitializeWallet is for initializing some specific types of smartcard wallet at a provided URL. There is not yet a corresponding method in Clef.
+
+## Methods with replacements
+
+### personal_listAccounts
+
+`personal_listAccounts` displays the addresses of all accounts in the keystore. It is identical to `eth.accounts`. Calling `eth.accounts` requires manual approval in Clef (unless a rule for it has been attested). There is also Clef's `list-accounts` command that can be called from the terminal.
+
+Examples:
+
+```sh
+# eth_accounts using curl
+curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}'
+```
+
+```js
+// eth_accounts in Geth's JS console
+eth.accounts;
+```
+
+```sh
+# clef list-accounts in the terminal
+clef list-accounts
+```
+
+### personal_deriveAccount
+
+`personal_deriveAccount` requests a hardware wallet to derive a new account, optionally pinning it for later use. This method is identical to `clef_deriveAccount`. The Clef method is not externally exposed so it must be called via a UI.
+
+### personal.ecRecover
+
+`personal_ecRecover` returns the address for the account that was used to create a signature. An equivalent method, `account_ecRecover` is available on the Clef external API.
+
+Example call:
+
+```sh
+curl --data '{"id": 4, "jsonrpc": "2.0", "method": "account_ecRecover","params": ["0xaabbccdd",     "0x5b6693f153b48ec1c706ba4169960386dbaa6903e249cc79a8e6ddc434451d417e1e57327872c7f538beeb323c300afa9999a3d4a5de6caf3be0d5ef832b67ef1c"]}' -X POST localhost:8550
+```
+
+### personal_importRawKey
+
+`personal.importRawKey` was used to create a new account in the keystore from a raw private key. Clef has an equivalent method that can be invoked in the terminal using:
+
+```sh
+clef importraw <private-key-as-hex-string>
+```
+
+### personal_listWallets
+
+As opposed to `listAccounts`, this method lists full details, including usb path or keystore-file paths. The equivalent method is `clef_listWallets`. This method can be called from the terminal using:
+
+```sh
+clef list-wallets
+```
+
+### personal_newAccount
+
+`personal_newAccount` was used to create a new accoutn and save it in the keystore. Clef has an equivalent method, `account_new`. It can be accessed on the terminal using an http request or using a Clef command:
+
+Example call (curl):
+
+```sh
+curl --data '{"id": 1, "jsonrpc": "2.0", "method": "account_new", "params": []}' -X POST localhost:8550
+```
+
+Example call (Clef command):
+
+```sh
+clef newaccount
+```
+
+Both require manual approval in Clef unless a custom ruleset is in place.
+
+### personal_openWallet
+
+`personal_OpenWallet` initiates a hardware wallet opening procedure by establishing a USB connection and then attempting to authenticate via the provided passphrase. Note, the method may return an extra challenge requiring a second open (e.g. the Trezor PIN matrix challenge). `personal_openWallet` is identical to `clef_openWallet`. The Clef method is not externally eposed, meaning it must be called via a UI.
+
+### personal_sendTransaction
+
+`personal_sendTransaction` ws used to sign and submit a transaction. This can be done using `eth_sendTransaction`, requiring manual approval in Clef.
+
+Example call (Javascript console):
+
+```js
+// this command requires 2x approval in Clef because it loads account data via eth.accounts[0]
+// and eth.accounts[1]
+var tx = { from: eth.accounts[0], to: eth.accounts[1], value: web3.toWei(0.1, 'ether') };
+
+// then send the transaction
+eth.sendTransaction(tx);
+```
+
+Example call (terminal)
+
+```sh
+curl --data '{"id":1,"jsonrpc":"2.0", "method":"eth_sendTransaction","params":[{"from": "0xE70CAD05D0D54Ae3C9Fe5442f901E0433f9bd14B", "to":"0x4FDc03d09Ffca5Bba3138149E29D85C8A9E2Ac42", "gas":"21000","gasPrice":"20000000000", "nonce":"94"}]}' -H "Content-Type: application/json" -X POST localhost:8545
+```
+
+### personal_sign
+
+The sign method calculates an Ethereum specific signature with `sign(keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))`. 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.
+
+`personal.sign` is equivalent to Clef's `account_signData`. It returns the calculated signature.
+
+Example call:
+
+```sh
+curl --data {"id": 3, "jsonrpc": "2.0", "method": "account_signData", "params": ["data/plain", "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db","0xaabbccdd"]} -X POST localhost:8550
+```
+
+Clef also has `account_signTypedData` that signs data structured according to [EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md) and returns the signature.
+
+Example call (use the following as a template for `<data>` in `curl --data <data> -X POST localhost:8550 -H "Content-Type: application/json"`)
+
+```sh
+{
+  "id": 68,
+  "jsonrpc": "2.0",
+  "method": "account_signTypedData",
+  "params": [
+    "0xcd2a3d9f938e13cd947ec05abc7fe734df8dd826",
+    {
+      "types": {
+        "EIP712Domain": [
+          {
+            "name": "name",
+            "type": "string"
+          },
+          {
+            "name": "version",
+            "type": "string"
+          },
+          {
+            "name": "chainId",
+            "type": "uint256"
+          },
+          {
+            "name": "verifyingContract",
+            "type": "address"
+          }
+        ],
+        "Person": [
+          {
+            "name": "name",
+            "type": "string"
+          },
+          {
+            "name": "wallet",
+            "type": "address"
+          }
+        ],
+        "Mail": [
+          {
+            "name": "from",
+            "type": "Person"
+          },
+          {
+            "name": "to",
+            "type": "Person"
+          },
+          {
+            "name": "contents",
+            "type": "string"
+          }
+        ]
+      },
+      "primaryType": "Mail",
+      "domain": {
+        "name": "Ether Mail",
+        "version": "1",
+        "chainId": 1,
+        "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC"
+      },
+      "message": {
+        "from": {
+          "name": "Cow",
+          "wallet": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826"
+        },
+        "to": {
+          "name": "Bob",
+          "wallet": "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB"
+        },
+        "contents": "Hello, Bob!"
+      }
+    }
+  ]
+}
+```
+
+### personal_signTransaction
+
+`personal_signTransaction` was used to create and sign a transaction from the given arguments. The transaction was returned in RLP-form, not broadcast to other nodes. The equivalent method is Clef's `account_signTransaction` from the external API. The arguments are a transaction object (`{"from": , "to": , "gas": , "maxPriorityFeePerGas": , "MaxFeePerGas": , "value": , "data": , "nonce": }`)) and an optional method signature that enables Clef to decode the calldata and show the user the methods, arguments and values being sent.
+
+Example call (terminal):
+
+```sh
+curl --data '{"id": 2, "jsonrpc": "2.0", "method": "account_signTransaction", "params": [{"from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db", "gas": "0x55555","gasPrice": "0x1234", "input": "0xabcd", "nonce": "0x0", "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0", "value": "0x1234"}]}' -X POST -H "Content-Type: application/json" localhost:8550
+```

docs/interacting-with-geth/rpc/ns-personal.md

@@ -0,0 +1,237 @@
+---
+title: personal Namespace
+description: Documentation for the JSON-RPC API "personal" namespace
+---
+
+<Note>The personal namespace will be deprecated in the very near future.</Note>
+
+The personal API managed private keys in the key store. It is deprecated in favour of using [Clef](/docs/tools/clef/introduction) for interacting with accounts Please refer to the [ns_personal deprecation page](/docs/interacting-with-geth/rpc/ns-personal-deprecation) to see the equivalent methods. The following documentation should be treated as archive information and users should migrate tousing Clef for account interactions.
+
+## personal_deriveAccount {#personal-deriveaccount}
+
+Requests a HD wallet to derive a new account, optionally pinning it for later reuse.
+
+| Client  | Method invocation                                                        |
+| :------ | ------------------------------------------------------------------------ |
+| Console | `personal.deriveAccount(url, path, pin)`                                 |
+| RPC     | `{"method": "personal_deriveAccount", "params": [string, string, bool]}` |
+
+## personal_importRawKey {#personal-importrawkey}
+
+Imports the given unencrypted private key (hex string) into the key store, encrypting it with the passphrase.
+
+Returns the address of the new account.
+
+| Client  | Method invocation                                                 |
+| :------ | ----------------------------------------------------------------- |
+| Console | `personal.importRawKey(keydata, passphrase)`                      |
+| RPC     | `{"method": "personal_importRawKey", "params": [string, string]}` |
+
+## personal_initializeWallets {#personal-intializewallets}
+
+Initializes a new wallet at the provided URL by generating and returning a new private key.
+
+| Client  | Method invocation                                             |
+| :------ | ------------------------------------------------------------- |
+| Console | `personal.initializeWallet(url)`                              |
+| RPC     | `{"method": "personal_initializeWallet", "params": [string]}` |
+
+## personal_listAccounts {#personal-listaccounts}
+
+Returns all the Ethereum account addresses of all keys in the key store.
+
+| Client  | Method invocation                                   |
+| :------ | --------------------------------------------------- |
+| Console | `personal.listAccounts`                             |
+| RPC     | `{"method": "personal_listAccounts", "params": []}` |
+
+### Example
+
+```js
+> personal.listAccounts
+["0x5e97870f263700f46aa00d967821199b9bc5a120", "0x3d80b31a78c30fc628f20b2c89d7ddbf6e53cedc"]
+```
+
+## personal_listWallets {#personal-listwallets}
+
+Returns a list of wallets this node manages.
+
+| Client  | Method invocation                                  |
+| :------ | -------------------------------------------------- |
+| Console | `personal.listWallets`                             |
+| RPC     | `{"method": "personal_listWallets", "params": []}` |
+
+### Example
+
+```js
+> personal.listWallets
+[{
+  accounts: [{
+    address: "0x51594065a986c58d4698c23e3d932b68a22c4d21",
+    url: "keystore:///var/folders/cp/k3x0xm3959qf9l0pcbbdxdt80000gn/T/go-ethereum-keystore65174700/UTC--2022-06-28T10-31-09.477982000Z--51594065a986c58d4698c23e3d932b68a22c4d21"
+  }],
+  status: "Unlocked",
+  url: "keystore:///var/folders/cp/k3x0xm3959qf9l0pcbbdxdt80000gn/T/go-ethereum-keystore65174700/UTC--2022-06-28T10-31-09.477982000Z--51594065a986c58d4698c23e3d932b68a22c4d21"
+}]
+```
+
+## personal_lockAccount {#personal-lockaccount}
+
+Removes the private key with given address from memory. The account can no longer be used to send transactions.
+
+| Client  | Method invocation                                        |
+| :------ | -------------------------------------------------------- |
+| Console | `personal.lockAccount(address)`                          |
+| RPC     | `{"method": "personal_lockAccount", "params": [string]}` |
+
+## personal_newAccount {#personal-newaccount}
+
+Generates a new private key and stores it in the key store directory. The key file is encrypted with the given passphrase.
+Returns the address of the new account. At the geth console, `newAccount` will prompt for a passphrase when it is not supplied as the argument.
+
+| Client  | Method invocation                                       |
+| :------ | ------------------------------------------------------- |
+| Console | `personal.newAccount()`                                 |
+| RPC     | `{"method": "personal_newAccount", "params": [string]}` |
+
+### Example
+
+```js
+> personal.newAccount()
+Passphrase:
+Repeat passphrase:
+"0x5e97870f263700f46aa00d967821199b9bc5a120"
+```
+
+The passphrase can also be supplied as a string.
+
+```js
+> personal.newAccount("h4ck3r")
+"0x3d80b31a78c30fc628f20b2c89d7ddbf6e53cedc"
+```
+
+## personal_openWallet {#personal-openwallet}
+
+Initiates a hardware wallet opening procedure by establishing a USB connection and then attempting to authenticate via the provided passphrase. Note,
+the method may return an extra challenge requiring a second open (e.g. the Trezor PIN matrix challenge).
+
+| Client  | Method invocation                                               |
+| :------ | --------------------------------------------------------------- |
+| Console | `personal.openWallet(url, passphrase)`                          |
+| RPC     | `{"method": "personal_openWallet", "params": [string, string]}` |
+
+## personal_unlockAccount {#personal-unlockaccount}
+
+Decrypts the key with the given address from the key store.
+
+Both passphrase and unlock duration are optional when using the JavaScript console. If the passphrase is not supplied as an argument, the console will prompt for
+the passphrase interactively. The unencrypted key will be held in memory until the unlock duration expires. If the unlock duration defaults to 300 seconds. An explicit duration of zero seconds unlocks the key until geth exits.
+
+The account can be used with `eth_sign` and `eth_sendTransaction` while it is unlocked.
+
+| Client  | Method invocation                                                          |
+| :------ | -------------------------------------------------------------------------- |
+| Console | `personal.unlockAccount(address, passphrase, duration)`                    |
+| RPC     | `{"method": "personal_unlockAccount", "params": [string, string, number]}` |
+
+### Examples
+
+```js
+> personal.unlockAccount("0x5e97870f263700f46aa00d967821199b9bc5a120")
+Unlock account 0x5e97870f263700f46aa00d967821199b9bc5a120
+Passphrase:
+true
+```
+
+Supplying the passphrase and unlock duration as arguments:
+
+```js
+> personal.unlockAccount("0x5e97870f263700f46aa00d967821199b9bc5a120", "foo", 30)
+true
+```
+
+To type in the passphrase and still override the default unlock duration, pass `null` as the passphrase.
+
+```js
+> personal.unlockAccount("0x5e97870f263700f46aa00d967821199b9bc5a120", null, 30)
+Unlock account 0x5e97870f263700f46aa00d967821199b9bc5a120
+Passphrase:
+true
+```
+
+## personal_unpair {#personal-unpair}
+
+Deletes a pairing between wallet and Geth.
+
+| Client  | Method invocation                                           |
+| :------ | ----------------------------------------------------------- |
+| Console | `personal.unpair(url, pin)`                                 |
+| RPC     | `{"method": "personal_unpair", "params": [string, string]}` |
+
+## personal_sendTransaction {#personal-sendtransaction}
+
+Validate the given passphrase and submit transaction.
+
+The transaction is the same argument as for `eth_sendTransaction` (i.e. [transaction object](/docs/interacting-with-geth/rpc/objects#transaction-call-object)) and contains the `from` address. If the passphrase can be used to decrypt the private key belogging to `tx.from` the transaction is verified, signed and send onto the network. The account is not unlocked globally in the node and cannot be used in other RPC calls.
+
+| Client  | Method invocation                                                |
+| :------ | ---------------------------------------------------------------- |
+| Console | `personal.sendTransaction(tx, passphrase)`                       |
+| RPC     | `{"method": "personal_sendTransaction", "params": [tx, string]}` |
+
+### Examples
+
+```js
+> var tx = {from: "0x391694e7e0b0cce554cb130d723a9d27458f9298", to: "0xafa3f8684e54059998bc3a7b0d2b0da075154d66", value: web3.toWei(1.23, "ether")}
+undefined
+> personal.sendTransaction(tx, "passphrase")
+0x8474441674cdd47b35b875fd1a530b800b51a5264b9975fb21129eeb8c18582f
+```
+
+## personal_sign {#personal-sign}
+
+The sign method calculates an Ethereum specific signature with:
+`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.
+
+See ecRecover to verify the signature.
+
+| Client  | Method invocation                                                     |
+| :------ | --------------------------------------------------------------------- |
+| Console | `personal.sign(message, account, [password])`                         |
+| RPC     | `{"method": "personal_sign", "params": [message, account, password]}` |
+
+### Examples
+
+```js
+> personal.sign("0xdeadbeaf", "0x9b2055d370f73ec7d8a03e965129118dc8f5bf83", "")
+"0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b"
+```
+
+## personal_signTransaction {#personal-signtransaction}
+
+SignTransaction will create a transaction from the given arguments and tries to sign it with the key associated with `tx.from`. If the given passwd isn't able to decrypt the key it fails. The transaction is returned in RLP-form, not broadcast to other nodes. The first argument is a [transaction object](/docs/interacting-with-geth/rpc/objects) and the second argument is the password, similar to `personal_sendTransaction`.
+
+| Client  | Method invocation                                                |
+| :------ | ---------------------------------------------------------------- |
+| Console | `personal.signTransaction(tx, passphrase)`                       |
+| RPC     | `{"method": "personal_signTransaction", "params": [tx, string]}` |
+
+## personal_ecRecover {#personal-ecrecover}
+
+`ecRecover` returns the address associated with the private key that was used to calculate the signature in `personal_sign`.
+
+| Client  | Method invocation                                                  |
+| :------ | ------------------------------------------------------------------ |
+| Console | `personal.ecRecover(message, signature)`                           |
+| RPC     | `{"method": "personal_ecRecover", "params": [message, signature]}` |
+
+### Examples
+
+```js
+> personal.sign("0xdeadbeaf", "0x9b2055d370f73ec7d8a03e965129118dc8f5bf83", "")
+"0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b"
+> personal.ecRecover("0xdeadbeaf", "0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b")
+"0x9b2055d370f73ec7d8a03e965129118dc8f5bf83"
+```

docs/interacting-with-geth/rpc/ns-txpool.md

@@ -0,0 +1,205 @@
+---
+title: txpool Namespace
+description: Documentation for the JSON-RPC API "txpool" namespace
+---
+
+The `txpool` API gives access to several non-standard RPC methods to inspect the contents of the transaction pool containing all the currently pending transactions as well as the ones queued for future processing.
+
+## txpool_content {#txpool-content}
+
+The `content` inspection property can be queried to list the exact details of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only.
+
+The result is an object with two fields `pending` and `queued`. Each of these fields are associative arrays, in which each entry maps an origin-address to a batch of scheduled transactions. These batches themselves are maps associating nonces with actual transactions.
+
+Please note, there may be multiple transactions associated with the same account and nonce. This can happen if the user broadcast mutliple ones with varying gas allowances (or even completely different transactions).
+
+| Client  | Method invocation                                                     |
+| :-----: | --------------------------------------------------------------------- |
+|   Go    | `txpool.Content() (map[string]map[string]map[string]*RPCTransaction)` |
+| Console | `txpool.content`                                                      |
+|   RPC   | `{"method": "txpool_content"}`                                        |
+
+### Example
+
+```js
+> txpool.content
+{
+  pending: {
+    0x0216d5032f356960cd3749c31ab34eeff21b3395: {
+      806: {
+        blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000",
+        blockNumber: null,
+        from: "0x0216d5032f356960cd3749c31ab34eeff21b3395",
+        gas: "0x5208",
+        gasPrice: "0xba43b7400",
+        hash: "0xaf953a2d01f55cfe080c0c94150a60105e8ac3d51153058a1f03dd239dd08586",
+        input: "0x",
+        nonce: "0x326",
+        to: "0x7f69a91a3cf4be60020fb58b893b7cbb65376db8",
+        transactionIndex: null,
+        value: "0x19a99f0cf456000"
+      }
+    },
+    0x24d407e5a0b506e1cb2fae163100b5de01f5193c: {
+      34: {
+        blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000",
+        blockNumber: null,
+        from: "0x24d407e5a0b506e1cb2fae163100b5de01f5193c",
+        gas: "0x44c72",
+        gasPrice: "0x4a817c800",
+        hash: "0xb5b8b853af32226755a65ba0602f7ed0e8be2211516153b75e9ed640a7d359fe",
+        input: "0xb61d27f600000000000000000000000024d407e5a0b506e1cb2fae163100b5de01f5193c00000000000000000000000000000000000000000000000053444835ec580000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+        nonce: "0x22",
+        to: "0x7320785200f74861b69c49e4ab32399a71b34f1a",
+        transactionIndex: null,
+        value: "0x0"
+      }
+    }
+  },
+  queued: {
+    0x976a3fc5d6f7d259ebfb4cc2ae75115475e9867c: {
+      3: {
+        blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000",
+        blockNumber: null,
+        from: "0x976a3fc5d6f7d259ebfb4cc2ae75115475e9867c",
+        gas: "0x15f90",
+        gasPrice: "0x4a817c800",
+        hash: "0x57b30c59fc39a50e1cba90e3099286dfa5aaf60294a629240b5bbec6e2e66576",
+        input: "0x",
+        nonce: "0x3",
+        to: "0x346fb27de7e7370008f5da379f74dd49f5f2f80f",
+        transactionIndex: null,
+        value: "0x1f161421c8e0000"
+      }
+    },
+    0x9b11bf0459b0c4b2f87f8cebca4cfc26f294b63a: {
+      2: {
+        blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000",
+        blockNumber: null,
+        from: "0x9b11bf0459b0c4b2f87f8cebca4cfc26f294b63a",
+        gas: "0x15f90",
+        gasPrice: "0xba43b7400",
+        hash: "0x3a3c0698552eec2455ed3190eac3996feccc806970a4a056106deaf6ceb1e5e3",
+        input: "0x",
+        nonce: "0x2",
+        to: "0x24a461f25ee6a318bdef7f33de634a67bb67ac9d",
+        transactionIndex: null,
+        value: "0xebec21ee1da40000"
+      },
+      6: {
+        blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000",
+        blockNumber: null,
+        from: "0x9b11bf0459b0c4b2f87f8cebca4cfc26f294b63a",
+        gas: "0x15f90",
+        gasPrice: "0x4a817c800",
+        hash: "0xbbcd1e45eae3b859203a04be7d6e1d7b03b222ec1d66dfcc8011dd39794b147e",
+        input: "0x",
+        nonce: "0x6",
+        to: "0x6368f3f8c2b42435d6c136757382e4a59436a681",
+        transactionIndex: null,
+        value: "0xf9a951af55470000"
+      }
+    }
+  }
+}
+```
+
+## txpool_contentFrom {#txpool-contentfrom}
+
+Retrieves the transactions contained within the txpool, returning pending as well as queued transactions of this address, grouped by nonce.
+
+| Client  | Method invocation                                      |
+| :-----: | ------------------------------------------------------ |
+| Console | `txpool.contentFrom(address)`                          |
+|   RPC   | `{"method": "txpool_contentFrom, "params": [string]"}` |
+
+## txpool_inspect {#txpool-inspect}
+
+The `inspect` inspection property can be queried to list a textual summary of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. This is a method specifically tailored to developers to quickly see the transactions in the pool and find any potential issues.
+
+The result is an object with two fields `pending` and `queued`. Each of these fields are associative arrays, in which each entry maps an origin-address to a batch of scheduled transactions. These batches themselves are maps associating nonces with transactions summary strings.
+
+Please note, there may be multiple transactions associated with the same account and nonce. This can happen if the user broadcast mutliple ones with varying gas allowances (or even completely different transactions).
+
+| Client  | Method invocation                                            |
+| :-----: | ------------------------------------------------------------ |
+|   Go    | `txpool.Inspect() (map[string]map[string]map[string]string)` |
+| Console | `txpool.inspect`                                             |
+|   RPC   | `{"method": "txpool_inspect"}`                               |
+
+### Example
+
+```js
+> txpool.inspect
+{
+  pending: {
+    0x26588a9301b0428d95e6fc3a5024fce8bec12d51: {
+      31813: "0x3375ee30428b2a71c428afa5e89e427905f95f7e: 0 wei + 500000 × 20000000000 wei"
+    },
+    0x2a65aca4d5fc5b5c859090a6c34d164135398226: {
+      563662: "0x958c1fa64b34db746925c6f8a3dd81128e40355e: 1051546810000000000 wei + 90000 gas × 20000000000 wei",
+      563663: "0x77517b1491a0299a44d668473411676f94e97e34: 1051190740000000000 wei + 90000 gas × 20000000000 wei",
+      563664: "0x3e2a7fe169c8f8eee251bb00d9fb6d304ce07d3a: 1050828950000000000 wei + 90000 gas × 20000000000 wei",
+      563665: "0xaf6c4695da477f8c663ea2d8b768ad82cb6a8522: 1050544770000000000 wei + 90000 gas × 20000000000 wei",
+      563666: "0x139b148094c50f4d20b01caf21b85edb711574db: 1048598530000000000 wei + 90000 gas × 20000000000 wei",
+      563667: "0x48b3bd66770b0d1eecefce090dafee36257538ae: 1048367260000000000 wei + 90000 gas × 20000000000 wei",
+      563668: "0x468569500925d53e06dd0993014ad166fd7dd381: 1048126690000000000 wei + 90000 gas × 20000000000 wei",
+      563669: "0x3dcb4c90477a4b8ff7190b79b524773cbe3be661: 1047965690000000000 wei + 90000 gas × 20000000000 wei",
+      563670: "0x6dfef5bc94b031407ffe71ae8076ca0fbf190963: 1047859050000000000 wei + 90000 gas × 20000000000 wei"
+    },
+    0x9174e688d7de157c5c0583df424eaab2676ac162: {
+      3: "0xbb9bc244d798123fde783fcc1c72d3bb8c189413: 30000000000000000000 wei + 85000 gas × 21000000000 wei"
+    },
+    0xb18f9d01323e150096650ab989cfecd39d757aec: {
+      777: "0xcd79c72690750f079ae6ab6ccd7e7aedc03c7720: 0 wei + 1000000 gas × 20000000000 wei"
+    },
+    0xb2916c870cf66967b6510b76c07e9d13a5d23514: {
+      2: "0x576f25199d60982a8f31a8dff4da8acb982e6aba: 26000000000000000000 wei + 90000 gas × 20000000000 wei"
+    },
+    0xbc0ca4f217e052753614d6b019948824d0d8688b: {
+      0: "0x2910543af39aba0cd09dbb2d50200b3e800a63d2: 1000000000000000000 wei + 50000 gas × 1171602790622 wei"
+    },
+    0xea674fdde714fd979de3edf0f56aa9716b898ec8: {
+      70148: "0xe39c55ead9f997f7fa20ebe40fb4649943d7db66: 1000767667434026200 wei + 90000 gas × 20000000000 wei"
+    }
+  },
+  queued: {
+    0x0f6000de1578619320aba5e392706b131fb1de6f: {
+      6: "0x8383534d0bcd0186d326c993031311c0ac0d9b2d: 9000000000000000000 wei + 21000 gas × 20000000000 wei"
+    },
+    0x5b30608c678e1ac464a8994c3b33e5cdf3497112: {
+      6: "0x9773547e27f8303c87089dc42d9288aa2b9d8f06: 50000000000000000000 wei + 90000 gas × 50000000000 wei"
+    },
+    0x976a3fc5d6f7d259ebfb4cc2ae75115475e9867c: {
+      3: "0x346fb27de7e7370008f5da379f74dd49f5f2f80f: 140000000000000000 wei + 90000 gas × 20000000000 wei"
+    },
+    0x9b11bf0459b0c4b2f87f8cebca4cfc26f294b63a: {
+      2: "0x24a461f25ee6a318bdef7f33de634a67bb67ac9d: 17000000000000000000 wei + 90000 gas × 50000000000 wei",
+      6: "0x6368f3f8c2b42435d6c136757382e4a59436a681: 17990000000000000000 wei + 90000 gas × 20000000000 wei",
+      7: "0x6368f3f8c2b42435d6c136757382e4a59436a681: 17900000000000000000 wei + 90000 gas × 20000000000 wei"
+    }
+  }
+}
+```
+
+## txpool_status {#txpool-status}
+
+The `status` inspection property can be queried for the number of transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only.
+
+The result is an object with two fields `pending` and `queued`, each of which is a counter representing the number of transactions in that particular state.
+
+| Client  | Method invocation                             |
+| :------ | --------------------------------------------- |
+| Go      | `txpool.Status() (map[string]*rpc.HexNumber)` |
+| Console | `txpool.status`                               |
+| RPC     | `{"method": "txpool_status"}`                 |
+
+### Example
+
+```js
+> txpool.status
+{
+  pending: 10,
+  queued: 7
+}
+```

docs/interacting-with-geth/rpc/pubsub.md

@@ -0,0 +1,187 @@
+---
+title: Real-time Events
+description: How to subscribe to events using JSON-RPC notifications.
+---
+
+Geth v1.4 and later support publish / subscribe using JSON-RPC notifications. This allows clients to wait for events instead of polling for them.
+
+It works by subscribing to particular events. The node will return a subscription id. For each event that matches the subscription a notification with relevant data is send together with the subscription id.
+
+Example:
+
+```sh
+// create subscription
+{"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
+```
+
+returns
+
+```sh
+{"jsonrpc":"2.0","id":1,"result":"0xcd0c3e8af590364c09d0fa6a1210faf5"}
+// incoming notifications
+{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"difficulty":"0xd9263f42a87",<...>, "uncles":[]}}}
+{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"difficulty":"0xd90b1a7ad02", <...>, "uncles":["0x80aacd1ea4c9da32efd8c2cc9ab38f8f70578fcd46a1a4ed73f82f3e0957f936"]}}}
+```
+
+to cancel the subscription:
+
+```sh
+// cancel subscription
+{"id": 1, "method": "eth_unsubscribe", "params": ["0xcd0c3e8af590364c09d0fa6a1210faf5"]}
+{"jsonrpc":"2.0","id":1,"result":true}
+```
+
+## Considerations {#considerations}
+
+1. Notifications are sent for current events and not for past events. For use cases that depend on not to miss any notifications subscriptions are probably not the best option.
+2. Subscriptions require a full duplex connection. Geth offers such connections in the form of WebSocket and IPC (enabled by default).
+3. Subscriptions are coupled to a connection. If the connection is closed all subscriptions that are created over this connection are removed.
+4. Notifications are stored in an internal buffer and sent from this buffer to the client. If the client is unable to keep up and the number of buffered notifications reaches a limit (currently 10k) the connection is closed. Keep in mind that subscribing to some events can cause a flood of notifications, e.g. listening for all logs/blocks when the node starts to synchronize.
+
+## Create subscription {#create-subscriptions}
+
+Subscriptions are created with a regular RPC call with `eth_subscribe` as method and the subscription name as first parameter. If successful it returns the subscription id.
+
+### Parameters
+
+1. Subscription name
+2. Optional arguments
+
+### Example
+
+```sh
+{"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
+{"id": 1, "jsonrpc": "2.0", "result": "0x9cef478923ff08bf67fde6c64013158d"}
+```
+
+## Cancel subscription {#cancel-subscriptions}
+
+Subscriptions are cancelled with a regular RPC call with `eth_unsubscribe` as method and the subscription id as first parameter. It returns a bool indicating if the subscription was cancelled successful.
+
+### Parameters
+
+1. subscription id
+
+### Example
+
+```sh
+{"id": 1, "method": "eth_unsubscribe", "params": ["0x9cef478923ff08bf67fde6c64013158d"]}
+{"jsonrpc":"2.0","id":1,"result":true}
+```
+
+## Supported Subscriptions {#supported-subscriptions}
+
+### newHeads {#newheads}
+
+Fires a notification each time a new header is appended to the chain, including chain reorganizations. Users can use the bloom filter to determine if the block contains logs that are interested to them. Note that if geth receives multiple blocks simultaneously, e.g. catching up after being out of sync, only the last block is emitted.
+
+In case of a chain reorganization the subscription will emit the last header in the new chain. Therefore the subscription can emit multiple headers on the same height.
+
+#### Example
+
+```sh
+{"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
+```
+
+returns
+
+```sh
+{"jsonrpc":"2.0","id":2,"result":"0x9ce59a13059e417087c02d3236a0b1cc"}
+
+{
+        "jsonrpc": "2.0",
+        "method": "eth_subscription",
+        "params": {
+            "result": {
+            "difficulty": "0x15d9223a23aa",
+            "extraData": "0xd983010305844765746887676f312e342e328777696e646f7773",
+            "gasLimit": "0x47e7c4",
+            "gasUsed": "0x38658",
+            "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+            "miner": "0xf8b483dba2c3b7176a3da549ad41a48bb3121069",
+            "nonce": "0x084149998194cc5f",
+            "number": "0x1348c9",
+            "parentHash": "0x7736fab79e05dc611604d22470dadad26f56fe494421b5b333de816ce1f25701",
+            "receiptRoot": "0x2fab35823ad00c7bb388595cb46652fe7886e00660a01e867824d3dceb1c8d36",
+            "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+            "stateRoot": "0xb3346685172db67de536d8765c43c31009d0eb3bd9c501c9be3229203f15f378",
+            "timestamp": "0x56ffeff8",
+            "transactionsRoot": "0x0167ffa60e3ebc0b080cdb95f7c0087dd6c0e61413140e39d94d3468d7c9689f"
+            },
+            "subscription": "0x9ce59a13059e417087c02d3236a0b1cc"
+        }
+        }
+```
+
+### logs {#logs}
+
+Returns logs that are included in new imported blocks and match the given filter criteria.
+
+In case of a chain reorganization previous sent logs that are on the old chain will be resend with the `removed` property set to true. Logs from transactions that ended up in the new chain are emitted. Therefore a subscription can emit logs for the same transaction multiple times.
+
+#### Parameters
+
+1. `object` with the following (optional) fields
+   - **address**, either an address or an array of addresses. Only logs that are created from these addresses are returned (optional)
+   - **topics**, only logs which match the specified topics (optional)
+
+#### Example
+
+```sh
+{"id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]}]}
+```
+
+returns
+
+```sh
+{"jsonrpc":"2.0","id":2,"result":"0x4a8a4c0517381924f9838102c5a4dcb7"}
+
+{"jsonrpc":"2.0","method":"eth_subscription","params": {"subscription":"0x4a8a4c0517381924f9838102c5a4dcb7","result":{"address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd","blockHash":"0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04","blockNumber":"0x29e87","data":"0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003","logIndex":"0x0","topics":["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],"transactionHash":"0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4","transactionIndex":"0x0"}}}
+```
+
+### newPendingTransactions {#newpendingtransactions}
+
+Returns the hash for all transactions that are added to the pending state and are signed with a key that is available in the node.
+
+When a transaction that was previously part of the canonical chain isn't part of the new canonical chain after a reorganization its again emitted.
+
+#### Parameters
+
+none
+
+#### Example
+
+```sh
+{"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions"]}
+```
+
+returns
+
+```sh
+{"jsonrpc":"2.0","id":2,"result":"0xc3b33aa549fb9a60e95d21862596617c"}
+{
+        "jsonrpc":"2.0",
+        "method":"eth_subscription",
+        "params":{
+            "subscription":"0xc3b33aa549fb9a60e95d21862596617c",
+            "result":"0xd6fdc5cc41a9959e922f30cb772a9aef46f4daea279307bc5f7024edc4ccd7fa"
+        }
+    }
+```
+
+### syncing {#syncing}
+
+Indicates when the node starts or stops synchronizing. The result can either be a boolean indicating that the synchronization has started (true), finished (false) or an object with various progress indicators.
+
+#### Parameters
+
+none
+
+#### Example
+
+```sh
+{"id": 1, "method": "eth_subscribe", "params": ["syncing"]}
+
+{"jsonrpc":"2.0","id":2,"result":"0xe2ffeb2703bcf602d42922385829ce96"}
+{"subscription":"0xe2ffeb2703bcf602d42922385829ce96","result":{"syncing":true,"status":{"startingBlock":674427,"currentBlock":67400,"highestBlock":674432,"pulledStates":0,"knownStates":0}}}}
+```

docs/monitoring/dashboards.md

@@ -0,0 +1,146 @@
+---
+title: Monitoring Geth with InfluxDB and Grafana
+description: introduction to monitoring Geth nodes with Grafana
+---
+
+There are several ways to monitor the performance of a Geth node. Insights into a node's performance are useful for debugging, tuning and understanding what is really happening when Geth is running.
+
+## Prerequisites {#prerequisites}
+
+To follow along with the instructions on this page it will be useful to have:
+
+- a running Geth instance.
+- basic working knowlegde of bash/terminal.
+
+[This video](https://www.youtube.com/watch?v=cOBab8IJMYI) provides an excellent introduction to Geth monitoring.
+
+## Monitoring stack {#monitoring-stack}
+
+An Ethereum client collects lots of data which can be read in the form of a chronological database. To make monitoring easier, this data can be fed into data visualisation software. On this page, a Geth client will be configured to push data into a InfluxDB database and Grafana will be used to visualize the data.
+
+## Setting up InfluxDB {#setting-up-influxdb}
+
+InfluxDB can be downloaded from the [Influxdata release page](https://portal.influxdata.com/downloads/). It can also be installed from a [repository](https://repos.influxdata.com/).
+
+For example the following commands will download and install InfluxDB on a Debian based Linux operating system - you can check for up-to-date instructions for your operating system on the InfluxDB [downloads page](https://portal.influxdata.com/downloads/):
+
+```sh
+curl -tlsv1.3 --proto =https -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add
+source /etc/lsb-release
+echo "deb https://repos.influxdata.com/${DISTRIB_ID,,} ${DISTRIB_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
+sudo apt update
+sudo apt install influxdb -y
+sudo systemctl enable influxdb
+sudo systemctl start influxdb
+sudo apt install influxdb-client
+```
+
+By default,InfluxDB it is reachable at `localhost:8086`. Before using the `influx` client, a new user with admin privileges needs to be created. This user will serve for high level management, creating databases and users.
+
+```sh
+curl -XPOST "http://localhost:8086/query" --data-urlencode "q=CREATE USER username WITH PASSWORD 'password' WITH ALL PRIVILEGES"
+```
+
+Now the influx client can be used to enter [InfluxDB shell](https://docs.influxdata.com/influxdb/v1.8/tools/shell/) with the new user.
+
+```sh
+influx -username 'username' -password 'password'
+```
+
+A database and user for Geth metrics can be created by communicating with it directly via its shell.
+
+```sh
+create database geth
+create user geth with password choosepassword
+```
+
+Verify created entries with:
+
+```sh
+show databases
+show users
+```
+
+Leave InfluxDB shell.
+
+```sh
+exit
+```
+
+InfluxDB is running and configured to store metrics from Geth.
+
+## Preparing Geth {#preparing-geth}
+
+After setting up database, metrics need to be enabled in Geth. Various options are available, as documented in the `METRICS AND STATS OPTIONS`
+in `geth --help` and in our [metrics page](/docs/monitoring/metrics). In this case Geth will be configured to push data into InfluxDB. Basic setup specifies the endpoint where InfluxDB is reachable and authenticates the database.
+
+```sh
+geth --metrics --metrics.influxdb --metrics.influxdb.endpoint "http://0.0.0.0:8086" --metrics.influxdb.username "geth" --metrics.influxdb.password "chosenpassword"
+```
+
+These flags can be provided when Geth is started or saved to the configuration file.
+
+Listing the metrics in the database verifies that Geth is pushing data correctly. In InfluxDB shell:
+
+```sh
+use geth
+show measurements
+```
+
+## Setting up Grafana {#setting-up-grafana}
+
+With the InfluxDB database setup and successfully receiving data from Geth, the next step is to install Grafana so that the data can be visualized.
+
+The following code snippet shows how to download, install and run Grafana on a Debian based Linux system. Up to date instructions for your operating system can be found on the Grafana [downloads page](https://grafana.com/grafana/download).
+
+```sh
+curl -tlsv1.3 --proto =https -sL https://packages.grafana.com/gpg.key | sudo apt-key add -
+echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list
+sudo apt update
+sudo apt install grafana
+sudo systemctl enable grafana-server
+sudo systemctl start grafana-server
+```
+
+When Grafana is up and running, it should be reachable at `localhost:3000`. A browser can be pointed to that URL to access a visualization dashboard. The browser will prompt for login credentials (user: `admin` and password: `admin`). When prompted, the default password should be changed and saved.
+
+The browser first redirects to the Grafana home page to set up the source data. Click on the "Data sources" icon and then click on "InfluxDB". The following configuration options are recommended:
+
+```sh
+Name: InfluxDB
+Query Language: InfluxQL
+HTTP
+  URL: http://localhost:8086
+  Access: Server (default)
+  Whitelisted cookies: None (leave blank)
+Auth
+  All options left as their default (switches off)
+Custom HTTP Headers
+  None
+InfluxDB Details
+  Database: geth
+  User: <your-user-name>
+  Password: <your-password>
+  HTTP Method: GET
+```
+
+Click on "Save and test" and wait for the confirmation to pop up.
+
+Grafana is now set up to read data from InfluxDB. Now a dashboard can be created to interpret and display it. Dashboards properties are encoded in JSON files which can be created by anybody and easily imported. On the left bar, click on the "Dashboards" icon, then "Import".
+
+For a Geth monitoring dashboard, copy the URL of [this dashboard](https://grafana.com/grafana/dashboards/13877/) and paste it in the "Import page" in Grafana. After saving the dashboard, it should look like this:
+
+![Grafana 1](/images/docs/grafana.png)
+
+## Customization {#customization}
+
+The dashboards can be customized further. Each panel can be edited, moved, removed or added. To learn more about how dashboards work, refer to
+[Grafana's documentation](https://grafana.com/docs/grafana/latest/dashboards/).
+
+Some users might also be interested in automatic [alerting](https://grafana.com/docs/grafana/latest/alerting/), which sets up alert notifications that are sent automatically when metrics reach certain values. Various communication channels are supported.
+
+## Summary {#summary}
+
+This page has outlined how to set up a simple node monitoring dashboard using Grafana.
+
+**_NB: this page was adapted from a tutorial on ethereum.org written by Mario Havel_**

docs/monitoring/ethstats.md

@@ -0,0 +1,77 @@
+---
+title: Monitoring with Ethstats
+description: Setting up an Ethstats server
+---
+
+Ethstats is a service that displays real time and historical statistics about individual
+nodes connected to a network and about the network itself. Individual node statistics include
+the last received block, block time, propagation time, connected peers, latency etc. Network
+metrics include the number of nodes, average block times, node geolocation,
+transaction counts etc.
+
+These statistics are presented to the user in the form of a dashboard served to a web browser.
+This can be configured using the public Ethstats server for Ethereum mainnet or some
+public testnets, or using a local copy of Ethstats for private networks. This page will
+demonstrate how to set up an Ethstats dashboard for private and public networks.
+
+## Prerequisites {#prerequisites}
+
+To follow the instructions on this page the following are required:
+
+- Geth
+- Node
+- NPM
+- Git
+
+## Ethstats {#ethstats}
+
+Ethstats has three components:
+
+- a server that consumes data sent to it by each individual node on a network and serves
+  statistics generated from that data.
+
+- a client that queries a node and sends its data to the server
+
+- a dashboard that displays the statistics generated by the server
+
+The summary dashboard for Ethereum Mainnet can be viewed at [ethstats.net](https://ethstats.net/).
+
+![Ethstats](/images/docs/ethstats-mainnet.png)
+
+Note that the Ethstats dashboard is not a reliable source of information about the entire Ethereum
+network because submitting data to the Ethstats server is voluntary and has to be configured by
+individual nodes. Therefore, many nodes are omitted from the summary statistics.
+
+## How to use {#how-to-use}
+
+To report statistics about the local node to Ethstats, an Ethstats server and Ethstats client both have
+to be installed alongside Geth. There are several options for installing Ethstats clients and servers,
+each with detailed installation instructions. They all share the common trait that an Ethstats service is
+started with a specific URL that can be passed to Geth.
+
+[EthNetStats "Classic"](https://github.com/ethereum/eth-netstats)
+
+[EthNet Intelligence API](https://github.com/ethereum/eth-net-intelligence-api)
+
+[Goerli Ethstats client](https://github.com/goerli/ethstats-client)
+
+[Goerli Ethstats server](https://github.com/goerli/ethstats-server)
+
+If enabled, Geth spins up a minimal Ethstats reporting daemon that pushes statistics about the
+local node to the Ethstats server.
+
+To enable this, start Geth with the `ethstats` flag, passing the Ethstats service (nodename:secret@host:port) URL.
+
+```sh
+geth <other commands> --ethstats node1:secret:127.0.0.1:9000
+```
+
+The local node will then report to Ethstats, and the statistics will be displayed in a dashboard that can be
+accessed via the web browser.
+
+## Note on WS_secret {#note-on-ws-secret}
+
+The `WS_secret` parameter is required for connecting to an Ethstats server. For a local network this can be user-defined
+on startup by providing it as an environment variable. However, for Ethereum mainnet and the public testnets predefined
+values must be known. Historically these have been made available on Gitter and Skype channels or of a forum, but these are
+no longer in use. The user will have to track down existing Ethstats users to request the `WS_secret`.

docs/monitoring/metrics.md

@@ -0,0 +1,112 @@
+---
+title: Metrics
+description: Introduction to reporting metrics from Geth
+---
+
+Geth includes a variety of optional metrics that can be reported to the user. However, metrics are disabled by default to save on the computational overhead for the average user. Users that choose to see more detailed metrics can enable them using the `--metrics` flag when starting Geth. Some metrics are classed as especially expensive and are only enabled when the `--metrics.expensive` flag is supplied. For example, per-packet network traffic data is considered expensive.
+
+The goal of the Geth metrics system is that - similar to logs - arbitrary metric collections can be added to any part of the code without requiring fancy constructs to analyze them (counter variables, public interfaces, crossing over the APIs, console hooks, etc). Instead, metrics should be "updated" whenever and wherever needed and be automatically collected, surfaced through the APIs, queryable and visualizable for analysis.
+
+## Metric types {#metric-types}
+
+Geth's metrics can be classified into four types: meters, timers, counters and guages.
+
+### Meters {#meters}
+
+Analogous to physical meters (electricity, water, etc), Geth's meters are capable of measuring the _amount_ of "things" that pass through and at the _rate_ at which they do. A meter doesn't have a specific unit of measure (byte, block, malloc, etc), it just counts arbitrary _events_. At any point in time a meter can report:
+
+- _Total number of events_ that passed through the meter
+- _Mean throughput rate_ of the meter since startup (events / second)
+- _Weighted throughput rate_ in the last _1_, _5_ and _15_ minutes (events / second)
+  ("weighted" means that recent seconds count more that in older ones\*)
+
+### Timers {#timers}
+
+Timers are extensions of _meters_, the _duration_ of an event is collected alongside a log of its occurrence. Similarly to meters, a timer can also measure arbitrary events but each requires a duration to be assigned individually. In addition generating all of the meter report types, a timer also reports:
+
+- _Percentiles (5, 20, 50, 80, 95)_, reporting that some percentage of the events took less than the reported time to execute (_e.g. Percentile 20 = 1.5s would mean that 20% of the measured events took less time than 1.5 seconds to execute; inherently 80%(=100%-20%) took more that 1.5s_)
+- Percentile 5: minimum durations (this is as fast as it gets)
+- Percentile 50: well behaved samples (boring, just to give an idea)
+- Percentile 80: general performance (these should be optimised)
+- Percentile 95: worst case outliers (rare, just handle gracefully)
+
+### Counters {#counters}
+
+A counter is a single int64 value that can be incremented and decremented. The current value of the counter can be queried.
+
+### Gauges {#guages}
+
+A gauge is a single int64 value. Its value can increment and decrement - as with a counter - but can also be set arbitrarily.
+
+## Querying metrics {#querying-metrics}
+
+Geth collects metrics if the `--metrics` flag is provided at startup. Those metrics are available via an HTTP server if the `--metrics.addr` flag is also provided. By default the metrics are served at `127.0.0.1:6060/debug/metrics` but a custom IP address can be provided. A custom port can also be provided to the `--metrics.port` flag. More computationally expensive metrics are toggled on or off by providing or omitting the `--metrics.expensive` flag. For example, to serve all metrics at the default address and port:
+
+```sh
+geth <other commands> --metrics --metrics.addr 127.0.0.1 --metrics.expensive
+```
+
+Navigating the browser to the given metrics address displays all the available metrics in the form
+of JSON data that looks similar to:
+
+```sh
+chain/account/commits.50-percentile:        374072
+chain/account/commits.75-percentile:        830356
+chain/account/commits.95-percentile:        1783005.3999976
+chain/account/commits.99-percentile:        3991806
+chain/account/commits.99.999-percentile:    3991806
+chain/account/commits.count:                43
+chain/account/commits.fifteen-minute:       0.029134344092314267
+chain/account/commits.five-minute:          0.029134344092314267
+
+...
+
+```
+
+Any developer is free to add, remove or modify the available metrics as they see fit. The precise list of available metrics is always available by opening the metrics server in the browser.
+
+Geth also supports dumping metrics directly into an influx database. In order to activate this, the `--metrics.influxdb` flag must be provided at startup. The API endpoint,username, password and other influxdb tags can also be provided. The available tags are:
+
+```sh
+--metrics.influxdb.endpoint value      InfluxDB API endpoint to report metrics to (default: "http://localhost:8086")
+--metrics.influxdb.database value      InfluxDB database name to push reported metrics to (default: "geth")
+--metrics.influxdb.username value      Username to authorize access to the database (default: "test")
+--metrics.influxdb.password value      Password to authorize access to the database (default: "test")
+--metrics.influxdb.tags value          Comma-separated InfluxDB tags (key/values) attached to all measurements (default: "host=localhost")
+--metrics.influxdbv2                   Enable metrics export/push to an external InfluxDB v2 database
+--metrics.influxdb.token value         Token to authorize access to the database (v2 only) (default: "test")
+--metrics.influxdb.bucket value        InfluxDB bucket name to push reported metrics to (v2 only) (default: "geth")
+--metrics.influxdb.organization value  InfluxDB organization name (v2 only) (default: "geth")
+```
+
+## Creating and updating metrics {#creating-and-updating-metrics}
+
+Metrics can be added easily in the Geth source code:
+
+```go
+meter := metrics.NewMeter("system/memory/allocs")
+timer := metrics.NewTimer("chain/inserts")
+```
+
+In order to use the same meter from two different packages without creating dependency cycles, the metrics can be created using `NewOrRegisteredX()` functions. This creates a new meter if no meter with this name is available or returns the existing meter.
+
+```go
+meter := metrics.NewOrRegisteredMeter("system/memory/allocs")
+timer := metrics.NewOrRegisteredTimer("chain/inserts")
+```
+
+The name given to the metric can be any arbitrary string. However, since Geth assumes it to be some meaningful sub-system hierarchy, it should be named accordingly.
+
+Metrics can then be updated:
+
+```go
+meter.Mark(n) // Record the occurrence of `n` events
+
+timer.Update(duration)  // Record an event that took `duration`
+timer.UpdateSince(time) // Record an event that started at `time`
+timer.Time(function)    // Measure and record the execution of `function`
+```
+
+## Summary {#summary}
+
+Geth can be configured to report metrics to an HTTP server or database. These functions are disabled by default but can be configured by passing the appropriate commands on startup. Users can easily create custom metrics by adding them to the Geth source code, following the instructions on this page.

docs/resources.md

@@ -0,0 +1,48 @@
+---
+title: Resources
+description: Read, watch and listen more about Geth and Ethereum
+---
+
+Here are more resources for a deeper understanding of Geth and related topics.
+
+## Read {#read}
+
+[Geth team AMA: August 2022](https://www.reddit.com/r/cryptoall/comments/wpr6dk/ama_we_are_the_go_ethereum_geth_team_18_august/)
+
+[Ethereum stack exchange](https://ethereum.stackexchange.com/)
+
+## Watch {#watch}
+
+[Geth team AMA at Devcon 6, Bogota](https://youtu.be/Wr_SHOmz4lc?t=10714)
+
+[Sina's EVM tracing workshop at Devcon 6, Bogota](https://youtu.be/b8RdmGsilfU)
+
+[Péter at ETH Prage 2022: Ethereum in numbers: where TPS meets physics](https://www.youtube.com/watch?v=TdsaVoJiy3g)
+
+[Marius at ETH Amsterdam 2022: Deep dive into Geth](https://www.youtube.com/watch?v=c4N79UXZqSc)
+
+[Péter interview at ETH Prage 2022:](https://www.youtube.com/watch?v=cfxGzZZ_uOI)
+
+[Guillame at Devconnect 2022: Stateless Ethereum](https://www.youtube.com/watch?v=XkzJncPYj0M&list=PLJijNYoOwnsuqDH9ITSvbqDOaUdA1vp2O&index=9)
+
+[lightclients at Devconnect 2022: Future of Ethereum accounts](https://www.youtube.com/watch?v=pS5asEp6ry8&list=PLJijNYoOwnsuqDH9ITSvbqDOaUdA1vp2O&index=7)
+
+[Zsolt at Devconnect 2022: Geth in the pos light client ecosystem](https://www.youtube.com/watch?v=EPZeFXau-RE&list=PLJijNYoOwnst-feT7PsCLaSdiFYzWtf7j&index=2)
+
+[Jared at Devconnect 2022: Removing SELFDESTRUCT](https://www.youtube.com/watch?v=pDr-h334-Cs&list=PLJijNYoOwnsuqDH9ITSvbqDOaUdA1vp2O&index=5)
+
+[Marius interview at ETH Prague 2022](https://www.youtube.com/watch?v=QKr3KHTjbjQ)
+
+[Marius at ETHOnline 2021: The Megre from the perspective of the execution layer](https://www.youtube.com/watch?v=3DDjfUvQ2TE)
+
+[Péter's 2020 online Geth AMA](https://www.youtube.com/watch?v=gVMDw66atr4)
+
+[Martin at Devcon 5: Protecting the base layer](https://www.youtube.com/watch?v=wLcyIgblIxE)
+
+[Péter at DevCon 5: Monitoring Ethereum infrastructure](https://www.youtube.com/watch?v=2I_Cfr-OUp4)
+
+[Péter at DevCon 4: Plugging metadata leaks in Ethereum](https://www.youtube.com/watch?v=J1JenTo7oLE)
+
+[Péter at DevCon 2: Import Geth in Go](https://www.youtube.com/watch?v=R0Ia1U9Gxjg)
+
+[Péter at dotGo 2016: Immutability in Go](https://www.youtube.com/watch?v=fNUx4jHTaIc)

docs/tools/abigen.md

@@ -0,0 +1,140 @@
+---
+title: Abigen
+description: Introduction to the Go binding generator tool, Abigen
+---
+
+Abigen is a binding-generator for easily interacting with Ethereum using Go. Abigen creates easy-to-use, type-safe Go packages from Ethereum smart contract definitions known as ABIs. This abstracts away a lot of the complexity of handling smart contract deployment and interaction in Go native applications such as encoding and decoding smart contracts into EVM bytecode. Abigen comes bundled with Geth. A full Geth installation includes the abigen binary. Abigen can also be built independently by navigating to `go-ethereum/cmd/abigen` and running `go build`, or equivalently:
+
+```sh
+$ cd $GOPATH/src/github.com/ethereum/go-ethereum
+$ go build ./cmd/abigen
+```
+
+## What is an ABI? {#what-is-an-abi}
+
+Ethereum smart contracts have a schema that defines its functions and return types in the form of a JSON file. This JSON file is known as an _Application Binary Interface_, or ABI. The ABI acts as a specification for precisely how to encode data sent to a contract and how to decode the data the contract sends back. The ABI is the only essential piece of information required to generate Go bindings. Go developers can then use the bindings to interact with the contract from their Go application without having to deal directly with data encoding and decoding. An ABI is generated when a contract is compiled.
+
+### Generating the bindings {#generating-bindings}
+
+To demonstrate the binding generator a contract is required. The contract `Storage.sol` implements two very simple functions: `store` updates a user-defined `uint256` to the contract's storage, and `retrieve` displays the value stored in the contract to the user. The Solidity code is as follows:
+
+```js
+// SPDX-License-Identifier: GPL-3.0
+
+pragma solidity >0.7.0 < 0.9.0;
+/**
+* @title Storage
+* @dev store or retrieve variable value
+*/
+
+contract Storage {
+
+	uint256 value;
+
+	function store(uint256 number) public{
+		value = number;
+	}
+
+	function retrieve() public view returns (uint256){
+		return value;
+	}
+}
+```
+
+This contract can be pasted into a text file and saved as `Storage.sol`. The following code snippet shows how an ABI can be generated for `Storage.sol` using the Solidity compiler `solc`.
+
+```sh
+solc --abi Storage.sol -o build
+```
+
+The ABI can also be generated in other ways such as using the `compile` commands in development frameworks such as [Truffle](https://trufflesuite.com/), [Hardhat](https://hardhat.org/) and [Brownie](https://eth-brownie.readthedocs.io/en/stable/) or in the online IDE [Remix](https://remix.ethereum.org/). ABIs for existing verified contracts can be downloaded from [Etherscan](https://etherscan.io/).
+
+The ABI for `Storage.sol` (`Storage.abi`) looks as follows:
+
+```json
+[
+  {
+    "inputs": [],
+    "name": "retrieve",
+    "outputs": [{ "internalType": "uint256", "name": "", "type": "uint256" }],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [{ "internalType": "uint256", "name": "number", "type": "uint256" }],
+    "name": "store",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  }
+]
+```
+
+The contract binding can then be generated by passing the ABI to `abigen` as follows:
+
+```sh
+$ abigen --abi Storage.abi --pkg main --type Storage --out Storage.go
+```
+
+Where the flags are:
+
+- `--abi`: Mandatory path to the contract ABI to bind to
+- `--pkg`: Mandatory Go package name to place the Go code into
+- `--type`: Optional Go type name to assign to the binding struct
+- `--out`: Optional output path for the generated Go source file (not set = stdout)
+
+This will generate a type-safe Go binding for the Storage contract. The generated code will look something like the snippet below, the full version of which can be viewed [here](https://gist.github.com/jmcook1186/a78e59d203bb54b06e1b81f2cda79d93).
+
+```go
+// Code generated - DO NOT EDIT.
+// This file is a generated binding and any manual changes will be lost.
+
+package main
+
+import (
+	"errors"
+	"math/big"
+	"strings"
+
+	ethereum "github.com/ethereum/go-ethereum"
+	"github.com/ethereum/go-ethereum/accounts/abi"
+	"github.com/ethereum/go-ethereum/accounts/abi/bind"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/event"
+)
+
+// Reference imports to suppress errors if they are not otherwise used.
+var (
+	_ = errors.New
+	_ = big.NewInt
+	_ = strings.NewReader
+	_ = ethereum.NotFound
+	_ = bind.Bind
+	_ = common.Big1
+	_ = types.BloomLookup
+	_ = event.NewSubscription
+)
+
+// StorageMetaData contains all meta data concerning the Storage contract.
+var StorageMetaData = &bind.MetaData{
+	ABI: "[{\"inputs\":[],\"name\":\"retrieve\",\"outputs\":[{\"internalType\":\"uint256\",\"name\":\"\",\"type\":\"uint256\"}],\"stateMutability\":\"view\",\"type\":\"function\"},{\"inputs\":[{\"internalType\":\"uint256\",\"name\":\"number\",\"type\":\"uint256\"}],\"name\":\"store\",\"outputs\":[],\"stateMutability\":\"nonpayable\",\"type\":\"function\"}]",
+}
+
+// StorageABI is the input ABI used to generate the binding from.
+// Deprecated: Use StorageMetaData.ABI instead.
+var StorageABI = StorageMetaData.ABI
+
+// Storage is an auto generated Go binding around an Ethereum contract.
+type Storage struct {
+	StorageCaller     // Read-only binding to the contract
+	StorageTransactor // Write-only binding to the contract
+	StorageFilterer   // Log filterer for contract events
+}
+...
+
+```
+
+`Storage.go` contains all the bindings required to interact with `Storage.sol` from a Go application.
+
+For instructions on how to deploy this contract to Ethereum from a Go native application read our [Go bindings page](/docs/developers/dapp-developer/native). To browse the Abigen source code visit the Geth [GitHub repository](https://github.com/ethereum/go-ethereum/tree/master/cmd/abigen).

docs/tools/clef/apis.md

@@ -0,0 +1,851 @@
+---
+title: Clef APIs
+description: Reference documentation for the Clef APIs
+---
+
+Clef uses two separate APIs. The **external API** is an untrusted set of JSON-RPC methods that can be called by a user. The **internal API** is a set of JSON-RPC methods that can be called by a UI. The UI could be Clef's native command line interface or a custom UI.
+
+## External API {#external-api}
+
+Clef listens to HTTP requests on `http.addr`:`http.port` (or to IPC on `ipcpath`), with the same JSON-RPC standard as Geth. The messages are expected to be [JSON-RPC 2.0 standard](https://www.jsonrpc.org/specification).
+
+Some of these JSON-RPC calls require user interaction in the Clef terminal. Responses may be delayed significantly or may never be received if a user fails to respond to a confirmation request.
+
+The External API is **untrusted**: it does not accept credentials, nor does it expect that requests have any authority.
+
+See the [external API changelog](https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/extapi_changelog.md) for up to date information about changes to this API.
+
+The External API encoding is as follows:
+
+- number: positive integers that are hex encoded
+- data: hex encoded data
+- string: ASCII string
+
+All hex encoded values must be prefixed with `0x`.
+
+### Methods {#methods}
+
+#### account_new {#accountnew}
+
+##### Create new password protected account
+
+The signer will generate a new private key, encrypt it according to [web3 keystore spec](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) and store it in the keystore directory. The client is responsible for creating a backup of the keystore. If the keystore is lost there is no method of retrieving lost accounts.
+
+##### Arguments
+
+None
+
+##### Result
+
+- address [string]: account address that is derived from the generated key
+
+##### Sample call
+
+```json
+{
+  "id": 0,
+  "jsonrpc": "2.0",
+  "method": "account_new",
+  "params": []
+}
+```
+
+Response
+
+```json
+{
+  "id": 0,
+  "jsonrpc": "2.0",
+  "result": "0xbea9183f8f4f03d427f6bcea17388bdff1cab133"
+}
+```
+
+#### account_list {#account-list}
+
+##### List available accounts
+
+List all accounts that this signer currently manages
+
+##### Arguments
+
+None
+
+##### Result
+
+- array with account records:
+  - account.address [string]: account address that is derived from the generated key
+
+##### Sample call
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "account_list"
+}
+```
+
+Response
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": [
+    "0xafb2f771f58513609765698f65d3f2f0224a956f",
+    "0xbea9183f8f4f03d427f6bcea17388bdff1cab133"
+  ]
+}
+```
+
+#### account_signTransaction {#account-signtransaction}
+
+##### Sign transactions
+
+Signs a transaction and responds with the signed transaction in RLP-encoded and JSON forms. Supports both legacy and EIP-1559-style transactions.
+
+##### Arguments
+
+1. transaction object (legacy):
+   - `from` [address]: account to send the transaction from
+   - `to` [address]: receiver account. If omitted or `0x`, will cause contract creation.
+   - `gas` [number]: maximum amount of gas to burn
+   - `gasPrice` [number]: gas price
+   - `value` [number:optional]: amount of Wei to send with the transaction
+   - `data` [data:optional]: input data
+   - `nonce` [number]: account nonce
+1. transaction object (1559):
+   - `from` [address]: account to send the transaction from
+   - `to` [address]: receiver account. If omitted or `0x`, will cause contract creation.
+   - `gas` [number]: maximum amount of gas to burn
+   - `maxPriorityFeePerGas` [number]: maximum priority fee per unit of gas for the transaction
+   - `maxFeePerGas` [number]: maximum fee per unit of gas for the transaction
+   - `value` [number:optional]: amount of Wei to send with the transaction
+   - `data` [data:optional]: input data
+   - `nonce` [number]: account nonce
+1. method signature [string:optional]
+   - The method signature, if present, is to aid decoding the calldata. Should consist of `methodname(paramtype,...)`, e.g. `transfer(uint256,address)`. The signer may use this data to parse the supplied calldata, and show the user. The data, however, is considered totally untrusted, and reliability is not expected.
+
+##### Result
+
+- raw [data]: signed transaction in RLP encoded form
+- tx [json]: signed transaction in JSON form
+
+##### Sample call (legacy)
+
+```json
+{
+  "id": 2,
+  "jsonrpc": "2.0",
+  "method": "account_signTransaction",
+  "params": [
+    {
+      "from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db",
+      "gas": "0x55555",
+      "gasPrice": "0x1234",
+      "input": "0xabcd",
+      "nonce": "0x0",
+      "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
+      "value": "0x1234"
+    }
+  ]
+}
+```
+
+Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "raw": "0xf88380018203339407a565b7ed7d7a678680a4c162885bedbb695fe080a44401a6e4000000000000000000000000000000000000000000000000000000000000001226a0223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20ea02aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663",
+    "tx": {
+      "nonce": "0x0",
+      "gasPrice": "0x1234",
+      "gas": "0x55555",
+      "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
+      "value": "0x1234",
+      "input": "0xabcd",
+      "v": "0x26",
+      "r": "0x223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20e",
+      "s": "0x2aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663",
+      "hash": "0xeba2df809e7a612a0a0d444ccfa5c839624bdc00dd29e3340d46df3870f8a30e"
+    }
+  }
+}
+```
+
+##### Sample call (1559)
+
+```json
+{
+  "id": 2,
+  "jsonrpc": "2.0",
+  "method": "account_signTransaction",
+  "params": [
+    {
+      "from": "0xd1a9C60791e8440AEd92019a2C3f6c336ffefA27",
+      "to": "0x8A8eAFb1cf62BfBeb1741769DAE1a9dd47996192",
+      "gas": "0x33333",
+      "maxPriorityFeePerGas": "0x174876E800",
+      "maxFeePerGas": "0x174876E800",
+      "nonce": "0x0",
+      "value": "0x10",
+      "data": "0x4401a6e40000000000000000000000000000000000000000000000000000000000000012"
+    }
+  ]
+}
+```
+
+Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "raw": "0x02f891018085174876e80085174876e80083033333948a8eafb1cf62bfbeb1741769dae1a9dd4799619210a44401a6e40000000000000000000000000000000000000000000000000000000000000012c080a0c8b59180c6e0c154284402b52d772f1afcf8ec2d245cf75bfb3212ebe676135ba02c660aaebf92d5e314fc2ba4c70f018915d174c3c1fc6e4e38d00ebf1a5bb69f",
+    "tx": {
+      "type": "0x2",
+      "nonce": "0x0",
+      "gasPrice": null,
+      "maxPriorityFeePerGas": "0x174876e800",
+      "maxFeePerGas": "0x174876e800",
+      "gas": "0x33333",
+      "value": "0x10",
+      "input": "0x4401a6e40000000000000000000000000000000000000000000000000000000000000012",
+      "v": "0x0",
+      "r": "0xc8b59180c6e0c154284402b52d772f1afcf8ec2d245cf75bfb3212ebe676135b",
+      "s": "0x2c660aaebf92d5e314fc2ba4c70f018915d174c3c1fc6e4e38d00ebf1a5bb69f",
+      "to": "0x8a8eafb1cf62bfbeb1741769dae1a9dd47996192",
+      "chainId": "0x1",
+      "accessList": [],
+      "hash": "0x8e096eb11ea89aa83900e6816fb182ff0adb2c85d270998ca2dd2394ec6c5a73"
+    }
+  }
+}
+```
+
+##### Sample call with ABI-data
+
+```json
+{
+  "id": 67,
+  "jsonrpc": "2.0",
+  "method": "account_signTransaction",
+  "params": [
+    {
+      "from": "0x694267f14675d7e1b9494fd8d72fefe1755710fa",
+      "gas": "0x333",
+      "gasPrice": "0x1",
+      "nonce": "0x0",
+      "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
+      "value": "0x0",
+      "data": "0x4401a6e40000000000000000000000000000000000000000000000000000000000000012"
+    },
+    "safeSend(address)"
+  ]
+}
+```
+
+Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 67,
+  "result": {
+    "raw": "0xf88380018203339407a565b7ed7d7a678680a4c162885bedbb695fe080a44401a6e4000000000000000000000000000000000000000000000000000000000000001226a0223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20ea02aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663",
+    "tx": {
+      "nonce": "0x0",
+      "gasPrice": "0x1",
+      "gas": "0x333",
+      "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
+      "value": "0x0",
+      "input": "0x4401a6e40000000000000000000000000000000000000000000000000000000000000012",
+      "v": "0x26",
+      "r": "0x223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20e",
+      "s": "0x2aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663",
+      "hash": "0xeba2df809e7a612a0a0d444ccfa5c839624bdc00dd29e3340d46df3870f8a30e"
+    }
+  }
+}
+```
+
+Bash example:
+
+```sh
+> curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"account_signTransaction","params":[{"from":"0x694267f14675d7e1b9494fd8d72fefe1755710fa","gas":"0x333","gasPrice":"0x1","nonce":"0x0","to":"0x07a565b7ed7d7a678680a4c162885bedbb695fe0", "value":"0x0", "data":"0x4401a6e40000000000000000000000000000000000000000000000000000000000000012"},"safeSend(address)"],"id":67}' http://localhost:8550/
+
+{"jsonrpc":"2.0","id":67,"result":{"raw":"0xf88380018203339407a565b7ed7d7a678680a4c162885bedbb695fe080a44401a6e4000000000000000000000000000000000000000000000000000000000000001226a0223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20ea02aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663","tx":{"nonce":"0x0","gasPrice":"0x1","gas":"0x333","to":"0x07a565b7ed7d7a678680a4c162885bedbb695fe0","value":"0x0","input":"0x4401a6e40000000000000000000000000000000000000000000000000000000000000012","v":"0x26","r":"0x223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20e","s":"0x2aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663","hash":"0xeba2df809e7a612a0a0d444ccfa5c839624bdc00dd29e3340d46df3870f8a30e"}}}
+```
+
+#### account_signData {#account-signdata}
+
+##### Sign data
+
+Signs a chunk of data and returns the calculated signature.
+
+##### Arguments
+
+- content type [string]: type of signed data
+  - `text/validator`: hex data with custom validator defined in a contract
+  - `application/clique`: [clique](https://github.com/ethereum/EIPs/issues/225) headers
+  - `text/plain`: simple hex data validated by `account_ecRecover`
+- account [address]: account to sign with
+- data [object]: data to sign
+
+##### Result
+
+- calculated signature [data]
+
+##### Sample call
+
+```json
+{
+  "id": 3,
+  "jsonrpc": "2.0",
+  "method": "account_signData",
+  "params": ["data/plain", "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db", "0xaabbccdd"]
+}
+```
+
+Response
+
+```json
+{
+  "id": 3,
+  "jsonrpc": "2.0",
+  "result": "0x5b6693f153b48ec1c706ba4169960386dbaa6903e249cc79a8e6ddc434451d417e1e57327872c7f538beeb323c300afa9999a3d4a5de6caf3be0d5ef832b67ef1c"
+}
+```
+
+#### account_signTypedData {#account-signtypeddata}
+
+##### Sign data
+
+Signs a chunk of structured data conformant to [EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md) and returns the calculated signature.
+
+##### Arguments
+
+- account [address]: account to sign with
+- data [object]: data to sign
+
+##### Result
+
+- calculated signature [data]
+
+##### Sample call
+
+```json
+{
+  "id": 68,
+  "jsonrpc": "2.0",
+  "method": "account_signTypedData",
+  "params": [
+    "0xcd2a3d9f938e13cd947ec05abc7fe734df8dd826",
+    {
+      "types": {
+        "EIP712Domain": [
+          {
+            "name": "name",
+            "type": "string"
+          },
+          {
+            "name": "version",
+            "type": "string"
+          },
+          {
+            "name": "chainId",
+            "type": "uint256"
+          },
+          {
+            "name": "verifyingContract",
+            "type": "address"
+          }
+        ],
+        "Person": [
+          {
+            "name": "name",
+            "type": "string"
+          },
+          {
+            "name": "wallet",
+            "type": "address"
+          }
+        ],
+        "Mail": [
+          {
+            "name": "from",
+            "type": "Person"
+          },
+          {
+            "name": "to",
+            "type": "Person"
+          },
+          {
+            "name": "contents",
+            "type": "string"
+          }
+        ]
+      },
+      "primaryType": "Mail",
+      "domain": {
+        "name": "Ether Mail",
+        "version": "1",
+        "chainId": 1,
+        "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC"
+      },
+      "message": {
+        "from": {
+          "name": "Cow",
+          "wallet": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826"
+        },
+        "to": {
+          "name": "Bob",
+          "wallet": "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB"
+        },
+        "contents": "Hello, Bob!"
+      }
+    }
+  ]
+}
+```
+
+Response
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": "0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c"
+}
+```
+
+#### account_ecRecover {#account-ecrecover}
+
+##### Recover the signing address
+
+Derive the address from the account that was used to sign data with content type `text/plain` and the signature.
+
+##### Arguments
+
+- data [data]: data that was signed
+- signature [data]: the signature to verify
+
+##### Result
+
+- derived account [address]
+
+##### Sample call
+
+```json
+{
+  "id": 4,
+  "jsonrpc": "2.0",
+  "method": "account_ecRecover",
+  "params": [
+    "0xaabbccdd",
+    "0x5b6693f153b48ec1c706ba4169960386dbaa6903e249cc79a8e6ddc434451d417e1e57327872c7f538beeb323c300afa9999a3d4a5de6caf3be0d5ef832b67ef1c"
+  ]
+}
+```
+
+Response
+
+```json
+{
+  "id": 4,
+  "jsonrpc": "2.0",
+  "result": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db"
+}
+```
+
+#### account_version {#accountversion}
+
+##### Get external API version
+
+Get the version of the external API used by Clef.
+
+##### Arguments
+
+None
+
+##### Result
+
+- external API version [string]
+
+##### Sample call
+
+```json
+{
+  "id": 0,
+  "jsonrpc": "2.0",
+  "method": "account_version",
+  "params": []
+}
+```
+
+Response
+
+```json
+{
+  "id": 0,
+  "jsonrpc": "2.0",
+  "result": "6.0.0"
+}
+```
+
+## Internal (UI) API {#internalapi}
+
+Clef has one native console-based UI, for operation without any standalone tools. However, there is also an API to communicate with an external UI. To enable that UI, the signer needs to be started with the `--stdio-ui` option, which allocates `stdin` / `stdout` for the UI API.
+
+The internal API methods need to be implemented by a UI listener. By starting the signer with the switch `--stdio-ui-test`, the signer will invoke all known methods, and expect the UI to respond with denials. This can be used during development to ensure that the API is (at least somewhat) correctly implemented.
+
+All methods in this API use object-based parameters, so that there can be no mixup of parameters: each piece of data is accessed by key.
+
+An example (insecure) proof-of-concept external UI has been implemented in [`pythonsigner.py`](https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/pythonsigner.py).
+
+The model is as follows:
+
+- The user starts the UI app (`pythonsigner.py`).
+- The UI app starts `clef` with `--stdio-ui`, and listens to the
+  process output for confirmation-requests.
+- `clef` opens the external HTTP API.
+- When the `signer` receives requests, it sends a JSON-RPC request via `stdout`.
+- The UI app prompts the user accordingly, and responds to `clef`.
+- `clef` signs (or not), and responds to the original request.
+
+See the [ui API changelog](https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/intapi_changelog.md) for information about changes to this API.
+
+**NOTE** A slight deviation from `json` standard is in place: every request and response should be confined to a single line.
+Whereas the `json` specification allows for linebreaks, linebreaks **should not** be used in this communication channel, to make
+things simpler for both parties.
+
+### Methods {#methods}
+
+#### ApproveTx / `ui_approveTx` {#approvetx}
+
+Invoked when there's a transaction for approval.
+
+##### Sample call
+
+Here's a method invocation:
+
+```sh
+curl -i -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"account_signTransaction","params":[{"from":"0x694267f14675d7e1b9494fd8d72fefe1755710fa","gas":"0x333","gasPrice":"0x1","nonce":"0x0","to":"0x07a565b7ed7d7a678680a4c162885bedbb695fe0", "value":"0x0", "data":"0x4401a6e40000000000000000000000000000000000000000000000000000000000000012"},"safeSend(address)"],"id":67}' http://localhost:8550/
+```
+
+Results in the following invocation on the UI:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "ui_approveTx",
+  "params": [
+    {
+      "transaction": {
+        "from": "0x0x694267f14675d7e1b9494fd8d72fefe1755710fa",
+        "to": "0x0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
+        "gas": "0x333",
+        "gasPrice": "0x1",
+        "value": "0x0",
+        "nonce": "0x0",
+        "data": "0x4401a6e40000000000000000000000000000000000000000000000000000000000000012",
+        "input": null
+      },
+      "call_info": [
+        {
+          "type": "WARNING",
+          "message": "Invalid checksum on to-address"
+        },
+        {
+          "type": "Info",
+          "message": "safeSend(address: 0x0000000000000000000000000000000000000012)"
+        }
+      ],
+      "meta": {
+        "remote": "127.0.0.1:48486",
+        "local": "localhost:8550",
+        "scheme": "HTTP/1.1"
+      }
+    }
+  ]
+}
+```
+
+The same method invocation, but with invalid data:
+
+```sh
+curl -i -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"account_signTransaction","params":[{"from":"0x694267f14675d7e1b9494fd8d72fefe1755710fa","gas":"0x333","gasPrice":"0x1","nonce":"0x0","to":"0x07a565b7ed7d7a678680a4c162885bedbb695fe0", "value":"0x0", "data":"0x4401a6e40000000000000002000000000000000000000000000000000000000000000012"},"safeSend(address)"],"id":67}' http://localhost:8550/
+```
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "ui_approveTx",
+  "params": [
+    {
+      "transaction": {
+        "from": "0x0x694267f14675d7e1b9494fd8d72fefe1755710fa",
+        "to": "0x0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
+        "gas": "0x333",
+        "gasPrice": "0x1",
+        "value": "0x0",
+        "nonce": "0x0",
+        "data": "0x4401a6e40000000000000002000000000000000000000000000000000000000000000012",
+        "input": null
+      },
+      "call_info": [
+        {
+          "type": "WARNING",
+          "message": "Invalid checksum on to-address"
+        },
+        {
+          "type": "WARNING",
+          "message": "Transaction data did not match ABI-interface: WARNING: Supplied data is stuffed with extra data. \nWant 0000000000000002000000000000000000000000000000000000000000000012\nHave 0000000000000000000000000000000000000000000000000000000000000012\nfor method safeSend(address)"
+        }
+      ],
+      "meta": {
+        "remote": "127.0.0.1:48492",
+        "local": "localhost:8550",
+        "scheme": "HTTP/1.1"
+      }
+    }
+  ]
+}
+```
+
+One which has missing `to`, but with no `data`:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "ui_approveTx",
+  "params": [
+    {
+      "transaction": {
+        "from": "",
+        "to": null,
+        "gas": "0x0",
+        "gasPrice": "0x0",
+        "value": "0x0",
+        "nonce": "0x0",
+        "data": null,
+        "input": null
+      },
+      "call_info": [
+        {
+          "type": "CRITICAL",
+          "message": "Tx will create contract with empty code!"
+        }
+      ],
+      "meta": {
+        "remote": "signer binary",
+        "local": "main",
+        "scheme": "in-proc"
+      }
+    }
+  ]
+}
+```
+
+#### ApproveListing / `ui_approveListing` {#approvelisting}
+
+Invoked when a request for account listing has been made.
+
+##### Sample call
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "method": "ui_approveListing",
+  "params": [
+    {
+      "accounts": [
+        {
+          "url": "keystore:///home/bazonk/.ethereum/keystore/UTC--2017-11-20T14-44-54.089682944Z--123409812340981234098123409812deadbeef42",
+          "address": "0x123409812340981234098123409812deadbeef42"
+        },
+        {
+          "url": "keystore:///home/bazonk/.ethereum/keystore/UTC--2017-11-23T21-59-03.199240693Z--cafebabedeadbeef34098123409812deadbeef42",
+          "address": "0xcafebabedeadbeef34098123409812deadbeef42"
+        }
+      ],
+      "meta": {
+        "remote": "signer binary",
+        "local": "main",
+        "scheme": "in-proc"
+      }
+    }
+  ]
+}
+```
+
+#### ApproveSignData / `ui_approveSignData` {#approvesigndata}
+
+##### Sample call
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "method": "ui_approveSignData",
+  "params": [
+    {
+      "address": "0x123409812340981234098123409812deadbeef42",
+      "raw_data": "0x01020304",
+      "messages": [
+        {
+          "name": "message",
+          "value": "\u0019Ethereum Signed Message:\n4\u0001\u0002\u0003\u0004",
+          "type": "text/plain"
+        }
+      ],
+      "hash": "0x7e3a4e7a9d1744bc5c675c25e1234ca8ed9162bd17f78b9085e48047c15ac310",
+      "meta": {
+        "remote": "signer binary",
+        "local": "main",
+        "scheme": "in-proc"
+      }
+    }
+  ]
+}
+```
+
+#### ApproveNewAccount / `ui_approveNewAccount` {#approvenewaccount}
+
+Invoked when a request for creating a new account has been made.
+
+##### Sample call
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "method": "ui_approveNewAccount",
+  "params": [
+    {
+      "meta": {
+        "remote": "signer binary",
+        "local": "main",
+        "scheme": "in-proc"
+      }
+    }
+  ]
+}
+```
+
+#### ShowInfo / `ui_showInfo` {#showinfo}
+
+The UI should show the info (a single message) to the user. Does not expect response.
+
+##### Sample call
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 9,
+  "method": "ui_showInfo",
+  "params": ["Tests completed"]
+}
+```
+
+#### ShowError / `ui_showError` {#showerror}
+
+The UI should show the error (a single message) to the user. Does not expect response.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "ui_showError",
+  "params": ["Something bad happened!"]
+}
+```
+
+#### OnApprovedTx / `ui_onApprovedTx` {#onapprovedtx}
+
+`OnApprovedTx` is called when a transaction has been approved and signed. The call contains the return value that will be sent to the external caller. The return value from this method is ignored - the reason for having this callback is to allow the ruleset to keep track of approved transactions.
+
+When implementing rate-limited rules, this callback should be used.
+
+TLDR; Use this method to keep track of signed transactions, instead of using the data in `ApproveTx`.
+
+Example call:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "ui_onApprovedTx",
+  "params": [
+    {
+      "raw": "0xf88380018203339407a565b7ed7d7a678680a4c162885bedbb695fe080a44401a6e4000000000000000000000000000000000000000000000000000000000000001226a0223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20ea02aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663",
+      "tx": {
+        "nonce": "0x0",
+        "gasPrice": "0x1",
+        "gas": "0x333",
+        "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
+        "value": "0x0",
+        "input": "0x4401a6e40000000000000000000000000000000000000000000000000000000000000012",
+        "v": "0x26",
+        "r": "0x223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20e",
+        "s": "0x2aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663",
+        "hash": "0xeba2df809e7a612a0a0d444ccfa5c839624bdc00dd29e3340d46df3870f8a30e"
+      }
+    }
+  ]
+}
+```
+
+#### OnSignerStartup / `ui_onSignerStartup` {#onsignerstartup}
+
+This method provides the UI with information about what API version the signer uses (both internal and external) as well as build-info and external API,
+in k/v-form.
+
+Example call:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "ui_onSignerStartup",
+  "params": [
+    {
+      "info": {
+        "extapi_http": "http://localhost:8550",
+        "extapi_ipc": null,
+        "extapi_version": "2.0.0",
+        "intapi_version": "1.2.0"
+      }
+    }
+  ]
+}
+```
+
+#### OnInputRequired / `ui_onInputRequired` {#oninputrequired}
+
+Invoked when Clef requires user input (e.g. a password).
+
+Example call:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "ui_onInputRequired",
+  "params": [
+    {
+      "title": "Account password",
+      "prompt": "Please enter the password for account 0x694267f14675d7e1b9494fd8d72fefe1755710fa",
+      "isPassword": true
+    }
+  ]
+}
+```

docs/tools/clef/clique-signing.md

@@ -0,0 +1,446 @@
+---
+title: Clique signing
+description: Instructions for setting up Clef to seal blocks on a Clique network
+---
+
+Clique is a proof-of-authority system where new blocks can be created by authorized ‘signers’ only. The initial set of authorized signers is configured in the genesis block. Signers can be authorized and de-authorized using a voting mechanism, thus allowing the set of signers to change while the blockchain operates. Signing blocks in Clique networks classically uses the "unlock" feature of Geth so that each node is always ready to sign without requiring a user to manually provide authorization.
+
+However, using the `--unlock` flag is generally a highly dangerous thing to do because it is indiscriminate, i.e. if an account is unlocked and an attacker obtains access to the RPC api, the attacker can sign anything without supplying a password.
+
+Clef provides a way to safely circumvent `--unlock` while maintaining a enough automation for the network to be useable.
+
+## Prerequisites {#prerequisites}
+
+It is useful to have basic knowledge of private networks and Clef. These topics are covered on our [private networks](/docs/developers/geth-developer/private-network) and [Introduction to Clef](/docs/tools/clef/introduction) pages.
+
+## Prepping a Clique network {#prepping-clique-network}
+
+First of all, set up a rudimentary testnet to have something to sign. Create a new keystore (password `testtesttest`)
+
+```terminal
+$ geth account new --datadir ./ddir
+INFO [06-16|11:10:39.600] Maximum peer count                       ETH=50 LES=0 total=50
+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:   0x9CD932F670F7eDe5dE86F756A6D02548e5899f47
+Path of the secret key file: ddir/keystore/UTC--2022-06-16T09-10-48.578523828Z--9cd932f670f7ede5de86f756a6d02548e5899f47
+
+- 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!
+```
+
+Create a genesis with that account as a sealer:
+
+```json
+{
+  "config": {
+    "chainId": 15,
+    "homesteadBlock": 0,
+    "eip150Block": 0,
+    "eip155Block": 0,
+    "eip158Block": 0,
+    "byzantiumBlock": 0,
+    "constantinopleBlock": 0,
+    "petersburgBlock": 0,
+    "clique": {
+      "period": 30,
+      "epoch": 30000
+    }
+  },
+  "difficulty": "1",
+  "gasLimit": "8000000",
+  "extradata": "0x00000000000000000000000000000000000000000000000000000000000000009CD932F670F7eDe5dE86F756A6D02548e5899f470000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+  "alloc": {
+    "0x9CD932F670F7eDe5dE86F756A6D02548e5899f47": {
+      "balance": "300000000000000000000000000000000"
+    }
+  }
+}
+```
+
+Initiate Geth:
+
+```sh
+$ geth  --datadir ./ddir init genesis.json
+```
+
+```terminal
+...
+INFO [06-16|11:14:54.123] Writing custom genesis block
+INFO [06-16|11:14:54.125] Persisted trie from memory database      nodes=1 size=153.00B time="64.715µs"  gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B
+INFO [06-16|11:14:54.125] Successfully wrote genesis state         database=lightchaindata hash=187412..4deb98
+```
+
+At this point a Geth has been initiated with a genesis configuration.
+
+## Prepping Clef {#prepping-clef}
+
+In order to make use of `clef` for signing:
+
+1. Ensure `clef` knows the password for the keystore.
+2. Ensure `clef` auto-approves clique signing requests.
+
+These two things are independent of each other. First of all, however, `clef` must be initiated (for this example the password is `clefclefclef`)
+
+```sh
+$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15 --suppress-bootwarn init
+```
+
+```terminal
+The master seed of clef will be locked with a password.
+Please specify a password. Do not forget this password!
+Password:
+Repeat password:
+
+A master seed has been generated into clef/masterseed.json
+
+This is required to be able to store credentials, such as:
+* Passwords for keystores (used by rule engine)
+* Storage for JavaScript auto-signing rules
+* Hash of JavaScript rule-file
+
+You should treat 'masterseed.json' with utmost secrecy and make a backup of it!
+* The password is necessary but not enough, you need to back up the master seed too!
+* The master seed does not contain your accounts, those need to be backed up separately!
+```
+
+After this operation, `clef` has it's own vault where it can store secrets and attestations.
+
+## Storing passwords in `clef` {#storing-passwords}
+
+With that done, `clef` can be made aware of the password. To do this `setpw <address>` is invoked to store a password for a given address. `clef` asks for the password, and it also asks for the master-password, in order to update and store the new secrets inside the vault.
+
+```sh
+$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15 --suppress-bootwarn setpw 0x9CD932F670F7eDe5dE86F756A6D02548e5899f47
+```
+
+```terminal
+Please enter a password to store for this address:
+Password:
+Repeat password:
+
+Decrypt master seed of clef
+Password:
+INFO [06-16|11:27:09.153] Credential store updated                 set=0x9CD932F670F7eDe5dE86F756A6D02548e5899f47
+```
+
+At this point, if Clef is used as a sealer, each block would require manual approval, but without needing to provide the password.
+
+### Testing stored password {#testing-stored-password}
+
+To test that the stored password is correct and being properly handled by Clef, first start `clef`:
+
+```sh
+$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15 --suppress-bootwarn
+```
+
+then start Geth:
+
+```sh
+$ geth  --datadir ./ddir --signer ./clef/clef.ipc --mine
+```
+
+Geth will ask what accounts are present - enter `y` to approve:
+
+```terminal
+-------- List Account request--------------
+A request has been made to list all accounts.
+You can select which accounts the caller can see
+  [x] 0x9CD932F670F7eDe5dE86F756A6D02548e5899f47
+    URL: keystore:///home/user/tmp/clique_clef/ddir/keystore/UTC--2022-06-16T09-10-48.578523828Z--9cd932f670f7ede5de86f756a6d02548e5899f47
+-------------------------------------------
+Request context:
+	NA - ipc - NA
+
+Additional HTTP header data, provided by the external caller:
+	User-Agent: ""
+	Origin: ""
+Approve? [y/N]:
+> y
+DEBUG[06-16|11:36:42.499] Served account_list                      reqid=2 duration=3.213768195s
+```
+
+After this, Geth will start asking `clef` to sign things:
+
+```terminal
+-------- Sign data request--------------
+Account:  0x9CD932F670F7eDe5dE86F756A6D02548e5899f47 [chksum ok]
+messages:
+  Clique header [clique]: "clique header 1 [0x9b08fa3705e8b6e1b327d84f7936c21a3cb11810d9344dc4473f78f8da71e571]"
+raw data:
+	"\xf9\x02\x14\xa0\x18t\x12:\x91f\xa2\x90U\b\xf9\xac\xc02i\xffs\x9f\xf4\xc9⮷!\x0f\x16\xaa?#M똠\x1d\xccM\xe8\xde\xc7]z\xab\x85\xb5g\xb6\xcc\xd4\x1a\xd3\x12E\x1b\x94\x8at\x13\xf0\xa1B\xfd@ԓG\x94\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xa0]1%\n\xfc\xee'\xd0e\xce\xc7t\xcc\\?\t4v\x8f\x06\xcb\xf8\xa0P5\xfeN\xea\x0ff\xfe\x9c\xa0V\xe8\x1f\x17\x1b\xccU\xa6\xff\x83E\xe6\x92\xc0\xf8n[H\xe0\x1b\x99l\xad\xc0\x01b/\xb5\xe3c\xb4!\xa0V\xe8\x1f\x17\x1b\xccU\xa6\xff\x83E\xe6\x92\xc0\xf8n[H\xe0\x1b\x99l\xad\xc0\x01b/\xb5\xe3c\xb4!\xb9\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x01\x83z0\x83\x80\x84b\xaa\xf9\xaa\xa0\u0603\x01\n\x14\x84geth\x88go1.18.1\x85linux\x00\x00\x00\x00\x00\x00\x00\xa0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x88\x00\x00\x00\x00\x00\x00\x00\x00"
+data hash:  0x9589ed81e959db6330b3d70e5f8e426fb683d03512f203009f7e41fc70662d03
+-------------------------------------------
+Request context:
+	NA -> ipc -> NA
+
+Additional HTTP header data, provided by the external caller:
+	User-Agent: ""
+	Origin: ""
+Approve? [y/N]:
+> y
+```
+
+And indeed, after approving with `y`, the password is not required - the signed block is returned to Geth:
+
+```terminal
+INFO [06-16|11:36:46.714] Successfully sealed new block            number=1 sealhash=9589ed..662d03 hash=bd20b9..af8b87 elapsed=4.214s
+```
+
+This mode of operation offers quite a poor UX because each block to be sealed requires manual approval. That is fixed in the following section.
+
+## Using rules to approve blocks {#using-rules}
+
+Clef rules allow a piece of Javascript take over the Approve/Deny decision. The Javascript snippet has access to the same information as the manual operator.
+
+The first approach, which approves listing, and returns the request data for `ApproveListing`, is demonstrated below:
+
+```js
+function ApproveListing() {
+  return 'Approve';
+}
+
+function ApproveSignData(r) {
+  console.log('In Approve Sign data');
+  console.log(JSON.stringify(r));
+}
+```
+
+In order to use a certain ruleset, it must first be 'attested'. This is to prevent someone from modifying a ruleset-file on disk after creation.
+
+```sh
+$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15 --suppress-bootwarn  attest  `sha256sum rules.js | cut -f1`
+```
+
+which returns:
+
+```terminal
+Decrypt master seed of clef
+Password:
+INFO [06-16|13:49:00.298] Ruleset attestation updated              sha256=54aae496c3f0eda063a62c73ee284ca9fae3f43b401da847ef30ea30e85e35d1
+```
+
+And `clef` can be started, pointing out the `rules.js` file.
+
+```sh
+$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15  --suppress-bootwarn  --rules ./rules.js
+```
+
+Once Geth starts asking `clef` to seal blocks, the data will be displayed. From that data, rules can be defined that allow signing clique headers but nothing else.
+
+The actual data that gets passed to the js environment (and which the ruleset display in the terminal) looks as follows:
+
+```json
+{
+  "content_type": "application/x-clique-header",
+  "address": "0x9CD932F670F7eDe5dE86F756A6D02548e5899f47",
+  "raw_data": "+QIUoL0guY+66jZpzZh1wDX4Si/ycX4zD8FQqF/1Apy/r4uHoB3MTejex116q4W1Z7bM1BrTEkUblIp0E/ChQv1A1JNHlAAAAAAAAAAAAAAAAAAAAAAAAAAAoF0xJQr87ifQZc7HdMxcPwk0do8Gy/igUDX+TuoPZv6coFboHxcbzFWm/4NF5pLA+G5bSOAbmWytwAFiL7XjY7QhoFboHxcbzFWm/4NF5pLA+G5bSOAbmWytwAFiL7XjY7QhuQEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAICg3pPDoCEYqsY1qDYgwEKFIRnZXRoiGdvMS4xOC4xhWxpbnV4AAAAAAAAAKAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIgAAAAAAAAAAA==",
+  "messages": [
+    {
+      "name": "Clique header",
+      "value": "clique header 2 [0xae525b65bc7f711bc136f502650039cd6959c3abc28fdf0ebfe2a5f85c92f3b6]",
+      "type": "clique"
+    }
+  ],
+  "call_info": null,
+  "hash": "0x8ca6c78af7d5ae67ceb4a1e465a8b639b9fbdec4b78e4d19cd9b1232046fbbf4",
+  "meta": {
+    "remote": "NA",
+    "local": "NA",
+    "scheme": "ipc",
+    "User-Agent": "",
+    "Origin": ""
+  }
+}
+```
+
+To create an extremely trustless ruleset, the `raw_data` could be verified to ensure it has the right rlp structure for a Clique header:
+
+```sh
+ echo "+QIUoL0guY+66jZpzZh1wDX4Si/ycX4zD8FQqF/1Apy/r4uHoB3MTejex116q4W1Z7bM1BrTEkUblIp0E/ChQv1A1JNHlAAAAAAAAAAAAAAAAAAAAAAAAAAAoF0xJQr87ifQZc7HdMxcPwk0do8Gy/igUDX+TuoPZv6coFboHxcbzFWm/4NF5pLA+G5bSOAbmWytwAFiL7XjY7QhoFboHxcbzFWm/4NF5pLA+G5bSOAbmWytwAFiL7XjY7QhuQEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAICg3pPDoCEYqsY1qDYgwEKFIRnZXRoiGdvMS4xOC4xhWxpbnV4AAAAAAAAAKAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIgAAAAAAAAAAA==" | base64 -d | rlpdump
+[
+  bd20b98fbaea3669cd9875c035f84a2ff2717e330fc150a85ff5029cbfaf8b87,
+  1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347,
+  0000000000000000000000000000000000000000,
+  5d31250afcee27d065cec774cc5c3f0934768f06cbf8a05035fe4eea0f66fe9c,
+  56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421,
+  56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421,
+  00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,
+  02,
+  02,
+  7a4f0e,
+  "",
+  62ab18d6,
+  d883010a14846765746888676f312e31382e31856c696e757800000000000000,
+  0000000000000000000000000000000000000000000000000000000000000000,
+  0000000000000000,
+]
+```
+
+However, `messages` could also be used. They do not come from the external caller, but are generated inernally: `clef` parsed the incoming request and verified the Clique wellformedness of the content. The following simply checks for such a message:
+
+```js
+function OnSignerStartup(info) {}
+
+function ApproveListing() {
+  return 'Approve';
+}
+
+function ApproveSignData(r) {
+  if (r.content_type == 'application/x-clique-header') {
+    for (var i = 0; i < r.messages.length; i++) {
+      var msg = r.messages[i];
+      if (msg.name == 'Clique header' && msg.type == 'clique') {
+        return 'Approve';
+      }
+    }
+  }
+  return 'Reject';
+}
+```
+
+Attest the ruleset:
+
+```sh
+$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15 --suppress-bootwarn  attest  `sha256sum rules.js | cut -f1`
+```
+
+returning
+
+```terminal
+Decrypt master seed of clef
+Password:
+INFO [06-16|14:18:53.476] Ruleset attestation updated              sha256=7d5036d22d1cc66599e7050fb1877f4e48b89453678c38eea06e3525996c2379
+```
+
+Run `clef`:
+
+```sh
+$ clef --keystore ./ddir/keystore --configdir ./clef --chainid 15  --suppress-bootwarn  --rules ./rules.js
+```
+
+Run Geth:
+
+```sh
+$ geth  --datadir ./ddir --signer ./clef/clef.ipc --mine
+```
+
+And `clef` should now happily sign blocks:
+
+```terminal
+DEBUG[06-16|14:20:02.136] Served account_version                   reqid=1 duration="131.38µs"
+INFO [06-16|14:20:02.289] Op approved
+DEBUG[06-16|14:20:02.289] Served account_list                      reqid=2 duration=4.672441ms
+INFO [06-16|14:20:02.303] Op approved
+DEBUG[06-16|14:20:03.450] Served account_signData                  reqid=3 duration=1.152074109s
+INFO [06-16|14:20:03.456] Op approved
+DEBUG[06-16|14:20:04.267] Served account_signData                  reqid=4 duration=815.874746ms
+INFO [06-16|14:20:32.823] Op approved
+DEBUG[06-16|14:20:33.584] Served account_signData                  reqid=5 duration=766.840681ms
+
+```
+
+## Refinements {#refinements}
+
+If an attacker find the Clef "external" interface (which would only happen if you start it with `http` enabled), they
+
+- cannot make it sign arbitrary transactions,
+- cannot sign arbitrary data message,
+
+However, they could still make it sign e.g. 1000 versions of a certain block height, making the chain very unstable.
+
+It is possible for rule execution to be stateful (i.e. storing data). In this case, one could, for example, store what block heights have been sealed and reject sealing a particular block height twice. In other words, these rules could be used to build a miniature version of an execution layer slashing-db.
+
+The `clique header 2 [0xae525b65bc7f711bc136f502650039cd6959c3abc28fdf0ebfe2a5f85c92f3b6]` line is split, and the number stored using `storage.get` and `storage.put`:
+
+```js
+function OnSignerStartup(info) {}
+
+function ApproveListing() {
+  return 'Approve';
+}
+
+function ApproveSignData(r) {
+  if (r.content_type != 'application/x-clique-header') {
+    return 'Reject';
+  }
+  for (var i = 0; i < r.messages.length; i++) {
+    var msg = r.messages[i];
+    if (msg.name == 'Clique header' && msg.type == 'clique') {
+      var number = parseInt(msg.value.split(' ')[2]);
+      var latest = storage.get('lastblock') || 0;
+      console.log('number', number, 'latest', latest);
+      if (number > latest) {
+        storage.put('lastblock', number);
+        return 'Approve';
+      }
+    }
+  }
+  return 'Reject';
+}
+```
+
+Running with this ruleset:
+
+```terminal
+JS:>  number 45 latest 44
+INFO [06-16|22:26:43.023] Op approved
+DEBUG[06-16|22:26:44.305] Served account_signData                  reqid=3 duration=1.287465394s
+JS:>  number 46 latest 45
+INFO [06-16|22:26:44.313] Op approved
+DEBUG[06-16|22:26:45.317] Served account_signData                  reqid=4 duration=1.010612774s
+```
+
+This might be a bit over-the-top, security-wise, and may cause problems if, for some reason, a clique-deadlock needs to be resolved by rolling back and continuing on a side-chain. It is mainly meant as a demonstration that rules can use Javascript and statefulness to construct very intricate signing logic.
+
+## TLDR quick-version {#tldr-version}
+
+Creation and attestation is a one-off event:
+
+```sh
+## Create the rules-file
+cat << END > rules.js
+function OnSignerStartup(info){}
+
+function ApproveListing(){
+  return "Approve"
+}
+
+function ApproveSignData(r){
+  if (r.content_type == "application/x-clique-header"){
+    for(var i = 0; i < r.messages.length; i++){
+      var msg = r.messages[i]
+      if (msg.name=="Clique header" && msg.type == "clique"){
+        return "Approve"
+      }
+    }
+  }
+  return "Reject"
+}
+END
+## Attest it, assumes clef master password is in `./clefpw`
+clef --keystore ./ddir/keystore \
+  --configdir ./clef --chainid 15 \
+  --suppress-bootwarn --signersecret ./clefpw \
+    attest  `sha256sum rules.js | cut -f1`
+```
+
+The normal startup command for `clef`:
+
+```sh
+clef --keystore ./ddir/keystore \
+    --configdir ./clef --chainid 15  \
+    --suppress-bootwarn --signersecret ./clefpw --rules ./rules.js
+```
+
+For Geth, the only change is to provide `--signer <path to clef ipc>`.
+
+## Summary {#summary}
+
+Clef can be used as a signer that automatically seals Clique blocks. This is a much more secure option than unlocking accounts using Geth's built-in account manager.

docs/tools/clef/datatypes.md

@@ -0,0 +1,251 @@
+---
+title: Communication data types
+description: The data types used by the Clef APIs
+---
+
+## UI Client interface {#ui-client-interface}
+
+These data types are defined in the channel between Clef and the UI
+
+### SignDataRequest {#signdatarequest}
+
+SignDataRequest contains information about a pending request to sign some data. The data to be signed can be of various types, defined by content-type. Clef has done most of the work in canonicalizing and making sense of the data, and it's up to the UI to present the user with the contents of the `message`
+
+Example:
+
+```json
+{
+  "content_type": "text/plain",
+  "address": "0xDEADbEeF000000000000000000000000DeaDbeEf",
+  "raw_data": "GUV0aGVyZXVtIFNpZ25lZCBNZXNzYWdlOgoxMWhlbGxvIHdvcmxk",
+  "messages": [
+    {
+      "name": "message",
+      "value": "\u0019Ethereum Signed Message:\n11hello world",
+      "type": "text/plain"
+    }
+  ],
+  "hash": "0xd9eba16ed0ecae432b71fe008c98cc872bb4cc214d3220a36f365326cf807d68",
+  "meta": {
+    "remote": "localhost:9999",
+    "local": "localhost:8545",
+    "scheme": "http",
+    "User-Agent": "Firefox 3.2",
+    "Origin": "www.malicious.ru"
+  }
+}
+```
+
+### SignDataResponse - approve {#signdataresponse-approve}
+
+Response to SignDataRequest
+
+Example:
+
+```json
+{
+  "approved": true
+}
+```
+
+### SignDataResponse - deny {#signdataresponse-deny}
+
+Response to SignDataRequest
+
+Example:
+
+```json
+{
+  "approved": false
+}
+```
+
+### SignTxRequest {#signtxrequest}
+
+SignTxRequest contains information about a pending request to sign a transaction. Aside from the transaction itself, there is also a `call_info`-struct. That struct contains messages of various types, that the user should be informed of.
+
+As in any request, it's important to consider that the `meta` info also contains untrusted data.
+
+The `transaction` (on input into clef) can have either `data` or `input` -- if both are set, they must be identical, otherwise an error is generated. However, Clef will always use `data` when passing this struct on (if Clef does otherwise, please file a ticket)
+
+Example:
+
+```json
+{
+  "transaction": {
+    "from": "0xDEADbEeF000000000000000000000000DeaDbeEf",
+    "to": null,
+    "gas": "0x3e8",
+    "gasPrice": "0x5",
+    "value": "0x6",
+    "nonce": "0x1",
+    "data": "0x01020304"
+  },
+  "call_info": [
+    {
+      "type": "Warning",
+      "message": "Something looks odd, show this message as a warning"
+    },
+    {
+      "type": "Info",
+      "message": "User should see this aswell"
+    }
+  ],
+  "meta": {
+    "remote": "localhost:9999",
+    "local": "localhost:8545",
+    "scheme": "http",
+    "User-Agent": "Firefox 3.2",
+    "Origin": "www.malicious.ru"
+  }
+}
+```
+
+### SignTxResponse - approve {#signtxresponse-approve}
+
+Response to request to sign a transaction. This response needs to contain the `transaction`, because the UI is free to make modifications to the transaction.
+
+Example:
+
+```json
+{
+  "transaction": {
+    "from": "0xDEADbEeF000000000000000000000000DeaDbeEf",
+    "to": null,
+    "gas": "0x3e8",
+    "gasPrice": "0x5",
+    "value": "0x6",
+    "nonce": "0x4",
+    "data": "0x04030201"
+  },
+  "approved": true
+}
+```
+
+### SignTxResponse - deny {#signtxresponse-deny}
+
+Response to SignTxRequest. When denying a request, there's no need to provide the transaction in return
+
+Example:
+
+```json
+{
+  "transaction": {
+    "from": "0x",
+    "to": null,
+    "gas": "0x0",
+    "gasPrice": "0x0",
+    "value": "0x0",
+    "nonce": "0x0",
+    "data": null
+  },
+  "approved": false
+}
+```
+
+### OnApproved - SignTransactionResult {#onapproved-signtransactionresult}
+
+SignTransactionResult is used in the call `clef` -> `OnApprovedTx(result)`
+
+This occurs _after_ successful completion of the entire signing procedure, but right before the signed transaction is passed to the external caller. This method (and data) can be used by the UI to signal to the user that the transaction was signed, but it is primarily useful for ruleset implementations.
+
+A ruleset that implements a rate limitation needs to know what transactions are sent out to the external interface. By hooking into this methods, the ruleset can maintain track of that count.
+
+**OBS:** Note that if an attacker can restore your `clef` data to a previous point in time (e.g through a backup), the attacker can reset such windows, even if he/she is unable to decrypt the content.
+
+The `OnApproved` method cannot be responded to, it's purely informative
+
+Example:
+
+```json
+{
+  "raw": "0xf85d640101948a8eafb1cf62bfbeb1741769dae1a9dd47996192018026a0716bd90515acb1e68e5ac5867aa11a1e65399c3349d479f5fb698554ebc6f293a04e8a4ebfff434e971e0ef12c5bf3a881b06fd04fc3f8b8a7291fb67a26a1d4ed",
+  "tx": {
+    "nonce": "0x64",
+    "gasPrice": "0x1",
+    "gas": "0x1",
+    "to": "0x8a8eafb1cf62bfbeb1741769dae1a9dd47996192",
+    "value": "0x1",
+    "input": "0x",
+    "v": "0x26",
+    "r": "0x716bd90515acb1e68e5ac5867aa11a1e65399c3349d479f5fb698554ebc6f293",
+    "s": "0x4e8a4ebfff434e971e0ef12c5bf3a881b06fd04fc3f8b8a7291fb67a26a1d4ed",
+    "hash": "0x662f6d772692dd692f1b5e8baa77a9ff95bbd909362df3fc3d301aafebde5441"
+  }
+}
+```
+
+### UserInputRequest {#userinputrequest}
+
+Sent when clef needs the user to provide data. If 'password' is true, the input field should be treated accordingly (echo-free)
+
+Example:
+
+```json
+{
+  "prompt": "The question to ask the user",
+  "title": "The title here",
+  "isPassword": true
+}
+```
+
+### UserInputResponse {#userinputresponse}
+
+Response to UserInputRequest
+
+Example:
+
+```json
+{
+  "text": "The textual response from user"
+}
+```
+
+### ListRequest {#listrequest}
+
+Sent when a request has been made to list addresses. The UI is provided with the full `account`s, including local directory names. Note: this information is not passed back to the external caller, who only sees the `address`es.
+
+Example:
+
+```json
+{
+  "accounts": [
+    {
+      "address": "0xdeadbeef000000000000000000000000deadbeef",
+      "url": "keystore:///path/to/keyfile/a"
+    },
+    {
+      "address": "0x1111111122222222222233333333334444444444",
+      "url": "keystore:///path/to/keyfile/b"
+    }
+  ],
+  "meta": {
+    "remote": "localhost:9999",
+    "local": "localhost:8545",
+    "scheme": "http",
+    "User-Agent": "Firefox 3.2",
+    "Origin": "www.malicious.ru"
+  }
+}
+```
+
+### ListResponse {#listresponse}
+
+Response to list request. The response contains a list of all addresses to show to the caller. Note: the UI is free to respond with any address the caller, regardless of whether it exists or not
+
+Example:
+
+```json
+{
+  "accounts": [
+    {
+      "address": "0x0000000000000000000000000000000000000000",
+      "url": ".. ignored .."
+    },
+    {
+      "address": "0xffffffffffffffffffffffffffffffffffffffff",
+      "url": ""
+    }
+  ]
+}
+```

docs/tools/clef/introduction.md

@@ -0,0 +1,150 @@
+---
+title: Introduction to Clef
+description: Introduction to the external signing tool, Clef
+---
+
+## What is Clef? {#what-is-clef}
+
+Clef is a tool for **signing transactions and data** in a secure local environment. It is intended to become a more composable and secure replacement for Geth's built-in account management. Clef decouples key management from Geth itself, meaning it can be used as an independent, standalone key management and signing application, or it can be integrated into Geth. This provides a more flexible modular tool compared to Geth's account manager. Clef can be used safely in situations where access to Ethereum is via a remote and/or untrusted node because signing happens locally, either manually or automatically using custom rulesets. The separation of Clef from the node itself enables it to run as a daemon on the same machine as the client software, on a secure usb-stick like [USB armory](https://inversepath.com/usbarmory), or even a separate VM in a [QubesOS](https://www.qubes-os.org/) type setup.
+
+## Installing and starting Clef {#installing-and-starting-clef}
+
+Clef comes bundled with Geth and can be built along with Geth and the other bundled tools using:
+
+`make all`
+
+However, Clef is not bound to Geth and can be built on its own using:
+
+`make clef`
+
+Once built, Clef must be initialized. This includes storing some data, some of which is sensitive (such as passwords, account data, signing rules etc). Initializing Clef takes that data and encrypts it using a user-defined password.
+
+`clef init`
+
+```terminal
+WARNING!
+
+Clef is an account management tool. It may, like any software, contain bugs.
+
+Please take care to
+- backup your keystore files,
+- verify that the keystore(s) can be opened with your password.
+
+Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See the GNU General Public License for more details.
+
+Enter 'ok' to proceed:
+> ok
+
+The master seed of clef will be locked with a password.
+Please specify a password. Do not forget this password!
+Password:
+Repeat password:
+
+A master seed has been generated into /home/martin/.clef/masterseed.json
+
+This is required to be able to store credentials, such as:
+* Passwords for keystores (used by rule engine)
+* Storage for JavaScript auto-signing rules
+* Hash of JavaScript rule-file
+
+You should treat 'masterseed.json' with utmost secrecy and make a backup of it!
+* The password is necessary but not enough, you need to back up the master seed too!
+* The master seed does not contain your accounts, those need to be backed up separately!
+```
+
+## Security model {#security-model}
+
+One of the major benefits of Clef is that it is decoupled from the client software, meaning it can be used by users and dapps to sign data and transactions in a secure, local environment and send the signed packet to an arbitrary Ethereum entry-point, which might include, for example, an untrusted remote node. Alternatively, Clef can simply be used as a standalone, composable signer that can be a backend component for decentralized applications. This requires a secure architecture that separates cryptographic operations from user interactions and internal/external communication.
+
+The security model of Clef is as follows:
+
+- A self-contained binary controls all cryptographic operations including encryption, decryption and storage of keystore files, and signing data and transactions.
+
+- A well defined, deliberately minimal "external" API is used to communicate with the Clef binary - Clef considers this external traffic to be UNTRUSTED. This means Clef does not accept any credentials and does not recognize authority of requests received over this channel. Clef listens on `http.addr:http.port` or `ipcpath` - the same as Geth - and expects messages to be formatted using the [JSON-RPC 2.0 standard](https://www.jsonrpc.org/specification). Some of the external API calls require some user interaction (manual approve/deny)- if it is not received responses can be delayed indefinitely.
+
+- Clef communicates with the process that invoked the binary using stin/stout. The process invoking the binary is usually the native console-based user interface (UI) but there is also an API that enables communication with an external UI. This has to be enabled using `--stdio-ui` at startup. This channel is considered TRUSTED and is used to pass approvals and passwords between the user and Clef.
+
+- Clef does not store keys - the user is responsible for securely storing and backing up keyfiles. Clef does store account passwords in its encrypted vault if they are explicitly provided to Clef by the user to enable automatic account unlocking.
+
+The external API never handles any sensitive data directly, but it can be used to request Clef to sign some data or a transaction. It is the internal API that controls signing and triggers requests for manual approval (automatic approves actions that conform to attested rulesets) and passwords.
+
+The general flow for a basic transaction-signing operation using Clef and an Ethereum node such as Geth is as follows:
+
+![Clef signing logic](/images/docs/clef_sign_flow.png)
+
+In the case illustrated in the schematic above, Geth would be started with `--signer <addr>:<port>` and would relay requests to `eth.sendTransaction`. Text in `mono` font positioned along arrows shows the objects passed between each component.
+
+Most users use Clef by manually approving transactions through the UI as in the schematic above, but it is also possible to configure Clef to sign transactions without always prompting the user. This requires defining the precise conditions under which a transaction will be signed. These conditions are known as `Rules` and they are small Javascript snippets that are _attested_ by the user by injecting the snippet's hash into Clef's secure whitelist. Clef is then started with the rule file, so that requests that satisfy the conditions in the whitelisted rule files are automatically signed. This is covered in detail on the [Rules page](/docs/tools/clef/rules).
+
+## Basic usage {#basic-usage}
+
+Clef is started on the command line using the `clef` command. Clef can be configured by providing flags and commands to `clef` on startup. The full list of command line options is available [below](#command-line-options). Frequently used options include `--keystore` and `--chainid` which configure the path to an existing keystore and a network to connect to. These options default to `$HOME/.ethereum/keystore` and `1` (corresponding to Ethereum Mainnet) respectively. The following code snippet starts Clef, providing a custom path to an existing keystore and connecting to the Goerli testnet:
+
+```sh
+clef --keystore /my/keystore --chainid 5
+```
+
+On starting Clef, the following welcome message is displayed in the terminal:
+
+```terminal
+WARNING!
+
+Clef is an account management tool. It may, like any software, contain bugs.
+
+Please take care to
+- backup your keystore files,
+- verify that the keystore(s) can be opened with your password.
+
+Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See the GNU General Public License for more details.
+
+Enter 'ok' to proceed:
+>
+```
+
+Requests requiring account access or signing now require explicit consent in this terminal. Activities such as sending transactions via a local Geth node's attached Javascript console or RPC will now hang indefinitely, awaiting approval in this terminal.
+
+A much more detailed Clef tutorial is available on the [Tutorial page](/docs/tools/clef/tutorial).
+
+## Command line options {#command-line-options}
+
+```sh
+COMMANDS:
+   init         Initialize the signer, generate secret storage
+   attest       Attest that a js-file is to be used
+   setpw        Store a credential for a keystore file
+   delpw        Remove a credential for a keystore file
+   newaccount   Create a new account
+   gendoc       Generate documentation about json-rpc format
+   help, h      Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   --loglevel value        log level to emit to the screen (default: 4)
+   --keystore value        Directory for the keystore (default: "$HOME/.ethereum/keystore")
+   --configdir value       Directory for Clef configuration (default: "$HOME/.clef")
+   --chainid value         Chain id to use for signing (1=mainnet, 3=Ropsten, 4=Rinkeby, 5=Goerli) (default: 1)
+   --lightkdf              Reduce key-derivation RAM & CPU usage at some expense of KDF strength
+   --nousb                 Disables monitoring for and managing USB hardware wallets
+   --pcscdpath value       Path to the smartcard daemon (pcscd) socket file (default: "/run/pcscd/pcscd.comm")
+   --http.addr value       HTTP-RPC server listening interface (default: "localhost")
+   --http.vhosts value     Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default: "localhost")
+   --ipcdisable            Disable the IPC-RPC server
+   --ipcpath value         Filename for IPC socket/pipe within the datadir (explicit paths escape it)
+   --http                  Enable the HTTP-RPC server
+   --http.port value       HTTP-RPC server listening port (default: 8550)
+   --signersecret value    A file containing the (encrypted) master seed to encrypt Clef data, e.g. keystore credentials and ruleset hash
+   --4bytedb-custom value  File used for writing new 4byte-identifiers submitted via API (default: "./4byte-custom.json")
+   --auditlog value        File used to emit audit logs. Set to "" to disable (default: "audit.log")
+   --rules value           Path to the rule file to auto-authorize requests with
+   --stdio-ui              Use STDIN/STDOUT as a channel for an external UI. This means that an STDIN/STDOUT is used for RPC-communication with a e.g. a graphical user interface, and can be used when Clef is started by an external process.
+   --stdio-ui-test         Mechanism to test interface between Clef and UI. Requires 'stdio-ui'.
+   --advanced              If enabled, issues warnings instead of rejections for suspicious requests. Default off
+   --suppress-bootwarn     If set, does not show the warning during boot
+```
+
+## Summary {#summary}
+
+Clef is an external key management and signer tool that comes bundled with Geth but can either be used as a backend account manager and signer for Geth or as a completely separate standalone application. Being modular and composable it can be used as a component in decentralized applications or to sign data and transactions in untrusted environments. Clef is intended to eventually replace Geth's built-in account management tools.

docs/tools/clef/rules.md

@@ -0,0 +1,241 @@
+---
+title: Rules
+description: Introduction to automated rulesets in Clef
+---
+
+Rules in Clef are sets of conditions that determine whether a given action can be approved automatically without requiring manual intervention from the user. This can be useful for automatically approving transactions between a user's own accounts, or approving patterns that are commonly used by applications. Automatic signing also requires Clef to have access to account passwords which is configured independently of the ruleset.
+
+Rules can define arbitrary conditions such as:
+
+- Auto-approve 10 transactions with contract `CasinoDapp`, with value between `0.05 ether` and `1 ether` per 24h period.
+
+- Auto-approve transactions to contract `Uniswapv2` with `value` up to 1 ether, if `gas < 44k` and `gasPrice < 40Gwei`.
+
+- Auto-approve signing if the data to be signed contains the string `"approve_me"`.
+
+- Auto-approve any requests to list accounts in keystore if the request arrives over IPC
+
+Because the rules are Javascript files they can be customized to implement any arbitrary logic on the available request data.
+
+This page will explain how rules are implemented in Clef and how best to manage credentials when automatic rulesets are enabled.
+
+## Rule Implementation {#rule-implementation}
+
+The ruleset engine acts as a gatekeeper to the command line interface - it auto-approves any requests that meet the conditions defined in a set of authenticated rule files. This prevents the user from having to manually approve or reject every request - instead they can define common patterns in a rule file and abstract that task away to the ruleset engine. The general architecture is as follows:
+
+![Clef ruleset logic](/images/docs/clef_ruleset.png)
+
+When Clef receives a request, the ruleset engine evaluates a Javascript file for each method defined in the internal [UI API docs](/docs/tools/clef/apis). For example the code snippet below is an example ruleset that calls the function `ApproveTx`. The call to `ApproveTx` is invoking the `ui_approveTx` [JSON_RPC API endpoint](/docs/tools/clef/apis). Every time an RPC method is invoked the Javascript code is executed in a freshly instantiated virtual machine.
+
+```js
+function asBig(str) {
+	if (str.slice(0, 2) == "0x") {
+		return new BigNumber(str.slice(2), 16)
+	}
+	return new BigNumber(str)
+}
+
+// Approve transactions to a certain contract if value is below a certain limit
+function ApproveTx(req) {
+	var limit = big.Newint("0xb1a2bc2ec50000")
+	var value = asBig(req.transaction.value);
+
+	if (req.transaction.to.toLowerCase() == "0xae967917c465db8578ca9024c205720b1a3651a9") && value.lt(limit)) {
+		return "Approve"
+	}
+	// If we return "Reject", it will be rejected.
+	// By not returning anything, the decision to approve/reject
+	// will be passed to the next UI, for manual processing
+}
+
+// Approve listings if request made from IPC
+function ApproveListing(req){
+    if (req.metadata.scheme == "ipc"){ return "Approve"}
+}
+```
+
+When a request is made via the external API, the logic flow is as follows:
+
+- Request is made to the `signer` binary using external API
+- `signer` calls the UI - in this case the ruleset engine
+
+- UI evaluates whether the call conforms to rules in an attested rulefile
+
+- Assuming the call returns "Approve", request is signed.
+
+There are three possible outcomes from the ruleset engine that are handled in different ways:
+
+| Return value  | Action                                  |
+| ------------- | --------------------------------------- |
+| "Approve"     | Auto-approve request                    |
+| "Reject"      | Auto-reject request                     |
+| Anything else | Pass decision to UI for manual approval |
+
+There are some additional noteworthy implementation details that are important for defining rules correctly in `ruleset.js`:
+
+- The code in `ruleset.js` **cannot** load external Javascript files.
+- The Javascript engine can access `storage` and `console`
+- The only preloaded library in the Javascript environment is `bignumber.js` version `2.0.3`.
+- Each invocation is made in a fresh virtual machine meaning data cannot be stored in global variables between invocations.
+- Since no global variable storage is available, disk backed `storage` must be used - rules should not rely on ephemeral data.
+- Javascript API parameters are always objects. This ensures parameters are accessed by _key_ to avoid misordering errors.
+- Otto VM uses ES5. ES6-specific features (such as Typed Arrays) are not supported.
+- The regular expression engine (re2/regexp) in Otto VM is not fully compatible with the [ECMA5 specification](https://tc39.es/ecma262/#sec-intro).
+- [Strict mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) is not supported. "use strict" will parse but it does nothing.
+
+## Credential management {#credential-management}
+
+The ability to auto-approve transaction requires that the signer has the necessary credentials, i.e. account passwords, to decrypt keyfiles. These are stored encrypted as follows:
+
+When the `signer` is started it generates a seed that is locked with a user specified password. The seed is saved to a location that defaults to `$HOME/.clef/masterseed.json`. The `seed` itself is a blob of bytes.
+
+The `signer` uses the `seed` to:
+
+- Generate the `path` where the configuration and credentials data are stored.
+  - `$HOME/.clef/790046d38025/config.json`
+  - `$HOME/.clef/790046d38025/credentials.json`
+- Generate the encryption password for the config and credentials files.
+
+`config.json` stores the hashes of any attested rulesets. `credentials.json` stores encrypted account passwords. The masterseed is required to decrypt these files. The decrypted account passwords can then be used to decrypt keyfiles.
+
+## Security {#security}
+
+### The Javascript VM {#javascript-vm}
+
+The downside of the very flexible rule implementation included in Clef is that the `signer` binary needs to contain a Javascript engine. This is an additional attack surface. The only viable attack is for an adversary to somehow extract cryptographic keys from memory during the Javascript VM execution. The hash-based rule attestation condition means the actual Javascript code executed by the Javascript engine is not a viable attack surface -- since if the attacker can control the ruleset, a much simpler attack would be to surreptitiously insert an attested "always-approve" rule instead of attempting to exploit the Javascript virtual machine. The Javascript engine is quite simple to implement and there are currently no known security vulnerabilities, not have there been any security problems identified for the similar Javascript VM implemented in Geth.
+
+### Writing rules {#writing-rules}
+
+Since the user has complete freedom to write custom rules, it is plausible that those rules could create unintended security vulnerabilities. This can only really be protected by coding very carefully and trying to test rulesets (e.g. on a private testnet) before implementing them on a public network.
+
+Javascript is very flexible but also easy to write incorrectly. For example, users might assume that javascript can handle large integers natively rather than explicitly using `bigInt`. This is an error commonly encountered in the Ethereum context when users attempt to multiply `gas` by `gasCost`.
+
+It’s unclear whether any other language would be more secure - there is alwas the possibility of implementing an insecure rule.
+
+### Credential security {#credential-security}
+
+Clef implements a secure, encrypted vault for storing sensitive data. This vault is encrypted using a `masterseed` which the user is responsible for storing and backing up safely and securely. Since this `masterseed` is used to decrypt the secure vault, and its security is not handled by Clef, it could represent a security vulnerability if the user does not implement best practise in keeping it safe.
+
+The same is also true for keys. Keys are not stored by Clef, they are only accessed using account passwords that Clef does store in its vault. The keys themselves are stored in an external `keystore` whose security is the responsibility of the user. If the keys are compromised, the account is not safe irrespective of the security benefits derived from Clef.
+
+## Ruleset examples {#ruleset-examples}
+
+Below are some examples of `ruleset.js` files.
+
+### Example 1: Allow destination
+
+```js
+function ApproveTx(r) {
+  if (r.transaction.to.toLowerCase() == '0x0000000000000000000000000000000000001337') {
+    return 'Approve';
+  }
+  if (r.transaction.to.toLowerCase() == '0x000000000000000000000000000000000000dead') {
+    return 'Reject';
+  }
+  // Otherwise goes to manual processing
+}
+```
+
+### Example 2: Allow listing
+
+```js
+function ApproveListing() {
+  return 'Approve';
+}
+```
+
+### Example 3: Approve signing data
+
+```js
+function ApproveSignData(req) {
+  if (req.address.toLowerCase() == '0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3') {
+    if (req.messages[0].value.indexOf('bazonk') >= 0) {
+      return 'Approve';
+    }
+    return 'Reject';
+  }
+  // Otherwise goes to manual processing
+}
+```
+
+### Example 4: Rate-limited window
+
+```js
+function big(str) {
+  if (str.slice(0, 2) == '0x') {
+    return new BigNumber(str.slice(2), 16);
+  }
+  return new BigNumber(str);
+}
+
+// Time window: 1 week
+var window = 1000 * 3600 * 24 * 7;
+
+// Limit : 1 ether
+var limit = new BigNumber('1e18');
+
+function isLimitOk(transaction) {
+  var value = big(transaction.value);
+  // Start of our window function
+  var windowstart = new Date().getTime() - window;
+
+  var txs = [];
+  var stored = storage.get('txs');
+
+  if (stored != '') {
+    txs = JSON.parse(stored);
+  }
+  // First, remove all that have passed out of the time-window
+  var newtxs = txs.filter(function (tx) {
+    return tx.tstamp > windowstart;
+  });
+  console.log(txs, newtxs.length);
+
+  // Secondly, aggregate the current sum
+  sum = new BigNumber(0);
+
+  sum = newtxs.reduce(function (agg, tx) {
+    return big(tx.value).plus(agg);
+  }, sum);
+  console.log('ApproveTx > Sum so far', sum);
+  console.log('ApproveTx > Requested', value.toNumber());
+
+  // Would we exceed weekly limit ?
+  return sum.plus(value).lt(limit);
+}
+function ApproveTx(r) {
+  if (isLimitOk(r.transaction)) {
+    return 'Approve';
+  }
+  return 'Nope';
+}
+
+/**
+ * OnApprovedTx(str) is called when a transaction has been approved and signed. The parameter
+ * 'response_str' contains the return value that will be sent to the external caller.
+ * The return value from this method is ignore - the reason for having this callback is to allow the
+ * ruleset to keep track of approved transactions.
+ *
+ * When implementing rate-limited rules, this callback should be used.
+ * If a rule responds with neither 'Approve' nor 'Reject' - the tx goes to manual processing. If the user
+ * then accepts the transaction, this method will be called.
+ *
+ * TLDR; Use this method to keep track of signed transactions, instead of using the data in ApproveTx.
+ */
+function OnApprovedTx(resp) {
+  var value = big(resp.tx.value);
+  var txs = [];
+  // Load stored transactions
+  var stored = storage.get('txs');
+  if (stored != '') {
+    txs = JSON.parse(stored);
+  }
+  // Add this to the storage
+  txs.push({ tstamp: new Date().getTime(), value: value });
+  storage.put('txs', JSON.stringify(txs));
+}
+```
+
+## Summary {#summary}
+
+Rules are sets of conditions encoded in Javascript files that enable certain actions to be auto-approved by Clef. This page outlined the implementation details and security considerations that will help to build suitrable ruleset files. See the [Clef GitHub](https://github.com/ethereum/go-ethereum/tree/master/cmd/clef) for further reading.

docs/tools/clef/setup.md

@@ -0,0 +1,180 @@
+---
+title: Advanced setup
+description: More advanced ways to set up Clef for additional security
+---
+
+Clef is a signer and account management tool that is external to Geth. This means it can be run as a separate process or even on a separate machine to the one running Geth, for example on secure hardware that is not connected to any external network, or on secure virtual machines.
+This page describes how Clef can be used with Qubes OS to provide a more secure setup than a normal laptop. Using Clef with USBArmory hardware is also briefly described.
+
+## Qubes OS {#qubes-os}
+
+### Background {#background}
+
+The Qubes operating system configures a set of virtual machines for different purposes such as:
+
+- personal
+  - Your personal email, browsing etc
+- work
+  - Work email etc
+- vault
+  - a VM without network access, where gpg-keys and/or keepass credentials are stored.
+
+A couple of dedicated virtual machines handle externalities:
+
+- sys-net provides networking to all other (network-enabled) machines
+- sys-firewall handles firewall rules
+- sys-usb handles USB devices, and can map usb-devices to certain qubes.
+
+The goal of this document is to describe how we can set up Clef to provide secure transaction signing from a `vault` vm, to another networked qube which runs Dapps.
+
+### Setup {#setup}
+
+There are two ways that this can be achieved: integrated via Qubes or integrated via networking.
+
+#### 1. Qubes Integrated {#qubes-integrated}
+
+Qubes provides a facility for inter-qubes communication via `qrexec`. A qube can request to make a cross-qube RPC request to another qube. The OS then asks the user if the call is permitted.
+
+![Example](/images/docs/qrexec-example.png)
+
+A policy-file can be created to allow such interaction. On the `target` domain, a service is invoked which can read the `stdin` from the `client` qube.
+
+This is how [Split GPG](https://www.qubes-os.org/doc/split-gpg/) is implemented. Clef can be set up in the same way:
+
+##### Server {#server}
+
+![Clef via qrexec](/images/docs/clef_qubes_qrexec.png)
+
+On the `target` qubes, we need to define the RPC service.
+
+```sh
+#!/bin/bash
+
+SIGNER_BIN="/home/user/tools/clef/clef"
+SIGNER_CMD="/home/user/tools/gtksigner/gtkui.py -s $SIGNER_BIN"
+
+# Start clef if not already started
+if [ ! -S /home/user/.clef/clef.ipc ]; then
+	$SIGNER_CMD &
+	sleep 1
+fi
+
+# Should be started by now
+if [ -S /home/user/.clef/clef.ipc ]; then
+    # Post incoming request to HTTP channel
+	curl -H "Content-Type: application/json" -X POST -d @- http://localhost:8550 2>/dev/null
+fi
+
+```
+
+This RPC service is not complete (see notes about HTTP headers below), but works as a proof-of-concept. It will forward the data received on `stdin` (forwarded by the OS) to Clef's HTTP channel.
+
+It would have been possible to send data directly to the `/home/user/.clef/.clef.ipc` socket via e.g `nc -U /home/user/.clef/clef.ipc`, but the reason for sending the request data over `HTTP` instead of `IPC` is for the ability to forward `HTTP` headers.
+
+To enable the service:
+
+```sh
+sudo cp qubes.Clefsign /etc/qubes-rpc/
+sudo chmod +x /etc/qubes-rpc/ qubes.Clefsign
+```
+
+This setup uses [gtksigner](https://github.com/holiman/gtksigner), which is a very minimal GTK-based UI that works well with minimal requirements.
+
+##### Client {#client}
+
+On the `client` qube, a listener is required to receive the request from the Dapp, and proxy it.
+
+```python
+"""
+This implements a dispatcher which listens to localhost:8550, and proxies
+requests via qrexec to the service qubes.EthSign on a target domain
+"""
+
+import http.server
+import socketserver,subprocess
+
+PORT=8550
+TARGET_DOMAIN= 'debian-work'
+
+class Dispatcher(http.server.BaseHTTPRequestHandler):
+    def do_POST(self):
+        post_data = self.rfile.read(int(self.headers['Content-Length']))
+        p = subprocess.Popen(['/usr/bin/qrexec-client-vm',TARGET_DOMAIN,'qubes.Clefsign'],stdin=subprocess.PIPE, stdout=subprocess.PIPE)
+        output = p.communicate(post_data)[0]
+        self.wfile.write(output)
+
+
+with socketserver.TCPServer(("",PORT), Dispatcher) as httpd:
+    print("Serving at port", PORT)
+    httpd.serve_forever()
+```
+
+#### Testing {#testing}
+
+To test the flow, with `debian-work` as the `target`:
+
+```sh
+$ cat newaccnt.json
+{ "id": 0, "jsonrpc": "2.0","method": "account_new","params": []}
+
+$ cat newaccnt.json| qrexec-client-vm debian-work qubes.Clefsign
+```
+
+A dialog should pop up first to allow the IPC call:
+
+![one](/images/docs/qubes_newaccount-1.png)
+
+Followed by a GTK-dialog to approve the operation:
+
+![two](/images/docs/qubes_newaccount-2.png)
+
+To test the full flow, start the client wrapper on the `client` qube:
+
+```sh
+[user@work qubes]$ python3 qubes-client.py
+```
+
+Make the request over http (`client` qube):
+
+```sh
+[user@work clef]$ cat newaccnt.json | curl -X POST -d @- http://localhost:8550
+```
+
+And it should show the same popups again.
+
+##### Pros and cons {#pros-and-cons}
+
+The benefits of this setup are:
+
+- This is the qubes-os intended model for inter-qube communication,
+- and thus benefits from qubes-os dialogs and policies for user approval
+
+However, it comes with a couple of drawbacks:
+
+- The `qubes-gpg-client` must forward the http request via RPC to the `target` qube. When doing so, the proxy
+  will either drop important headers, or replace them.
+  - The `Host` header is most likely `localhost`
+  - The `Origin` header must be forwarded
+  - Information about the remote ip must be added as a `X-Forwarded-For`. However, Clef cannot always trust an `XFF` header,
+    since malicious clients may lie about `XFF` in order to fool the http server into believing it comes from another address.
+- Even with a policy in place to allow RPC calls between `caller` and `target`, there will be several popups:
+  - One qubes-specific where the user specifies the `target` vm
+  - One clef-specific to approve the transaction
+
+#### 2. Network integrated {#network-integrated}
+
+The second way to set up Clef on a qubes system is to allow networking, and have Clef listen to a port which is accessible from other qubes.
+
+![Clef via http](/images/docs/clef_qubes_http.png)
+
+## USBArmory {#usb-armory}
+
+The [USB armory](https://inversepath.com/usbarmory) is an open source hardware design with an 800 MHz ARM processor. It is a pocket-sized computer. When inserted into a laptop, it identifies itself as a USB network interface, basically adding another network to your computer that can be used to SSH into the device.
+
+Running Clef off a USB armory means that the armory can be used as a very versatile offline computer, which only ever connects to a local network between the local computer and the device itself.
+
+Needless to say, while this model should be fairly secure against remote attacks, an attacker with physical access to the USB Armory would trivially be able to extract the contents of the device filesystem.
+
+## Summary {#summary}
+
+This page introduced two ways to setup Clef that give additional security compared to running on a normal laptop.

docs/tools/clef/tutorial.md

@@ -0,0 +1,577 @@
+---
+title: Tutorial
+description: Beginner tutorial for using Clef as an external signer for Geth
+---
+
+This page provides a step-by-step walkthrough tutorial demonstrating some common uses of Clef. This includes manual approvals and automated rules. Clef is presented both as a standalone general signer with requests made via RPC and also as a backend signer for Geth.
+
+## Initializing Clef {#initializing-clef}
+
+First things first, Clef needs to store some data itself. Since that data might be sensitive (passwords, signing rules, accounts), Clef's entire storage is encrypted. To support encrypting data, the first step is to initialize Clef with a random master seed, itself too encrypted with a password:
+
+```sh
+$ clef init
+```
+
+```terminal
+WARNING!
+
+Clef is an account management tool. It may, like any software, contain bugs.
+
+Please take care to
+- backup your keystore files,
+- verify that the keystore(s) can be opened with your password.
+
+Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See the GNU General Public License for more details.
+
+Enter 'ok' to proceed:
+> ok
+
+The master seed of clef will be locked with a password.
+Please specify a password. Do not forget this password!
+Password:
+Repeat password:
+
+A master seed has been generated into /home/martin/.clef/masterseed.json
+
+This is required to be able to store credentials, such as:
+* Passwords for keystores (used by rule engine)
+* Storage for JavaScript auto-signing rules
+* Hash of JavaScript rule-file
+
+You should treat 'masterseed.json' with utmost secrecy and make a backup of it!
+* The password is necessary but not enough, you need to back up the master seed too!
+* The master seed does not contain your accounts, those need to be backed up separately!
+```
+
+_For readability purposes, we'll remove the WARNING printout, user confirmation and the unlocking of the master seed in the rest of this document._
+
+## Remote interactions {#remote-interactions}
+
+This tutorial will use Clef with Geth on the Goerli testnet. The accounts used will be in the Goerli keystore with the path `~/go-ethereum/goerli-data/keystore`. The tutorial assumes there are two accounts in this keystore. Instructions for creating accounts can be found on the [Account managament page](/docs/fundamentals/account-management). Note that Clef can also interact with hardware wallets, although that is not demonstrated here.
+
+Clef should be started before Geth, otherwise Geth will complain that it cannot find a Clef instance to connect to. Clef should be started with the correct `chainid` for Goerli. Clef itself does not connect to a blockchain, but the `chainID` parameter is included in the data that is aggregated to form a signature. Clef also needs a path to the correct keystore passed to the `--keystore` command. A custom path to the config directory can also be provided. This is where the `ipc` file will be saved which is needed to connect Clef to Geth:
+
+```sh
+clef --keystore ~/go-ethereum/goerli-data/keystore --configdir ~/go-ethereum/goerli-data/clef --chainid=5
+```
+
+The following logs will be displayed in the console:
+
+```terminal
+INFO [07-01|11:00:46.385] Starting signer                          chainid=4 keystore= go-ethereum/goerli-data/keystore light-kdf=false advanced=false
+DEBUG[07-01|11:00:46.389] FS scan times                            list=3.521941ms set=9.017µs diff=4.112µs
+DEBUG[07-01|11:00:46.391] Ledger support enabled
+DEBUG[07-01|11:00:46.391] Trezor support enabled via HID
+DEBUG[07-01|11:00:46.391] Trezor support enabled via WebUSB
+INFO [07-01|11:00:46.391] Audit logs configured                    file=audit.log
+DEBUG[07-01|11:00:46.392] IPC registered                           namespace=account
+INFO [07-01|11:00:46.392] IPC endpoint opened                      url=go-ethereum/goerli-data/clef/clef.ipc
+------- Signer info -------
+* intapi_version : 7.0.1
+* extapi_version : 6.1.0
+* extapi_http : n/a
+* extapi_ipc : go-ethereum/goerli-data/clef/clef.ipc
+```
+
+Clef starts up in CLI (Command Line Interface) mode by default. Arbitrary remote processes may _request_ account interactions (e.g. sign a transaction), which the user can individually _confirm_ or _deny_.
+
+The code snippet below shows a request made to Clef via its _External API endpoint_ using [NetCat](http://netcat.sourceforge.net/). The request invokes the ["account_list"](/docs/tools/clef/apis#accountlist) endpoint which lists the accounts in the keystore. This command should be run in a new terminal.
+
+```sh
+echo '{"id": 1, "jsonrpc": "2.0", "method": "account_list"}' | nc -U ~/.clef/clef.ipc
+```
+
+The terminal used to send the command will now hang. This is because the process is awaiting confirmation from Clef. Switching to the Clef console reveals Clef's prompt to the user to confirm or deny the request:
+
+```terminal
+-------- List Account request--------------
+A request has been made to list all accounts.
+You can select which accounts the caller can see
+  [x] 0xD9C9Cd5f6779558b6e0eD4e6Acf6b1947E7fA1F3
+    URL: keystore://go-ethereum/goerli-data/keystore/UTC--2017-04-14T15-15-00.327614556Z--d9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3
+  [x] 0x086278A6C067775F71d6B2BB1856Db6E28c30418
+    URL: keystore://go-ethereum/goerli-data/keystore/UTC--2018-02-06T22-53-11.211657239Z--086278a6c067775f71d6b2bb1856db6e28c30418
+-------------------------------------------
+Request context:
+	NA - ipc - NA
+
+Additional HTTP header data, provided by the external caller:
+	User-Agent:
+	Origin:
+Approve? [y/N]:
+```
+
+Depending on whether the request is approved or denied, the NetCat process in the other terminal will receive one of the following responses:
+
+```terminal
+{"jsonrpc":"2.0","id":1,"result":["0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3","0x086278a6c067775f71d6b2bb1856db6e28c30418"]}
+```
+
+or
+
+```terminal
+{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"Request denied"}}
+```
+
+Apart from listing accounts, a _request_ can be submitted to create a new account, signing transactions and data or recovering signatures. The available methods are documented in the Clef [External API Spec](https://github.com/ethereum/go-ethereum/tree/master/cmd/clef#external-api-1) and the [External API Changelog](https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/extapi_changelog.md).
+
+_Note, the number of things that can be done from the External API is deliberately small to limit the power of remote calls as much as possible! Clef has an [Internal API](https://github.com/ethereum/go-ethereum/tree/master/cmd/clef#ui-api-1) too for the UI (User Interface) which is much richer and can support custom interfaces on top. But that's out of scope here._
+
+The example above used Clef completely independently of Geth. However, by defining Clef as the signer when Geth is started imposes Clef's `request - confirm - result` pattern to any interaction with the local Geth node that touches accounts, including requests made using RPC or an attached Javascript console. To demonstrate this, Geth can be started, with Clef as the signer:
+
+```sh
+geth --goerli --datadir goerli-data --signer=goerli-data/clef/clef.ipc
+```
+
+With Geth running, open a new terminal and attach a Javascript console:
+
+```sh
+geth attach goerli-data/geth.ipc
+```
+
+A simple request to list the accounts in the keystore will cause the Javascript console to hang.
+
+```js
+eth.accounts;
+```
+
+Switching to the Clef terminal reveals that this is because the request is awaiting explicit confirmation from the user. The log is identical to the one shown above, when the same request for account information was made to Clef via Netcat:
+
+```terminal
+-------- List Account request--------------
+A request has been made to list all accounts.
+You can select which accounts the caller can see
+  [x] 0xD9C9Cd5f6779558b6e0eD4e6Acf6b1947E7fA1F3
+    URL: keystore://go-ethereum/goerli-data/keystore/UTC--2017-04-14T15-15-00.327614556Z--d9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3
+  [x] 0x086278A6C067775F71d6B2BB1856Db6E28c30418
+    URL: keystore://go-ethereum/goerli-data/keystore/UTC--2018-02-06T22-53-11.211657239Z--086278a6c067775f71d6b2bb1856db6e28c30418
+-------------------------------------------
+Request context:
+	NA - ipc - NA
+
+Additional HTTP header data, provided by the external caller:
+	User-Agent:
+	Origin:
+Approve? [y/N]:
+```
+
+In this mode, the user is required to manually confirm every action that touches account data, including querying accounts, signing and sending transactions.
+
+The example below shows an ether transaction between the two accounts in the keystore using `eth.sendTransaction` in the attached Javascript console.
+
+```js
+// this command requires 2x approval in Clef because it loads account data via eth.accounts[0]
+// and eth.accounts[1]
+var tx = { from: eth.accounts[0], to: eth.accounts[1], value: web3.toWei(0.1, 'ether') };
+
+// then send the transaction
+eth.sendTransaction(tx);
+```
+
+This example demonstrates the power of Clef much more clearly than the account-listing example. In the Clef terminal, all the details of the transaction are presented to the user so that they can be reviewed before being confirmed. This gives the user an opportunity to review the fine
+details and make absolutely sure they really want to sign the transaction. `eth.sendTransaction` returns the following confirmation prompt in the Clef terminal:
+
+```terminal
+-------- Transaction request----------------
+to:     0x086278A6C067775F71d6B2BB1856Db6E28c30418
+from:               0xD9C9Cd5f6779558b6e0eD4e6Acf6b1947E7fA1F3 [chksum ok]
+value:              100000000000000000 wei
+gas:                0x5208 (21000)
+maxFeePerGas:           1500000016 wei
+maxPriorityFeePerGas:   1500000000 wei
+nonce:  0x0 (0)
+chainid: 0x5
+Accesslist
+
+Request context:
+        NA - ipc - NA
+
+Additional HTTP header data, provided by the external caller:
+    User-Agent: ""
+    Origin: ""
+---------------------------------------------
+
+Approve? [y/N]
+```
+
+Approving this transaction causes Clef to prompt the user to provide the password for the sender account. Providing the password enables the transaction to be signed and sent to Geth for broadcasting to the network. The details of the signed transaction are displayed in the console. Account passwords can also be stored in Clef's encrypted vault so that they do not have to be manually entered - [more on this below](#account-passwords).
+
+## Automatic rules {#automatic-rules}
+
+For most users, manually confirming every transaction is the right way to use Clef because a human-in-the-loop can review every action. However, there are cases when it makes sense to set up some rules which permit Clef to sign a transaction without prompting the user.
+For example, well defined rules such as:
+
+- Auto-approve transactions with Uniswap v2, with value between 0.1 and 0.5 ETH per 24h period
+- Auto-approve transactions to address `0xD9C9Cd5f6779558b6e0eD4e6Acf6b1947E7fA1F3` as long as gas < 44k and gasPrice < 80Gwei can be encoded and interpreted by Clef's built-in ruleset engine.
+
+### Rule files {#rule-files}
+
+Rules are implemented as Javascript code in `js` files. The ruleset engine includes the same methods as the JSON_RPC defined in the [UI Protocol](/docs/tools/clef/datatypes). The following code snippet demonstrates a rule file that approves a transaction if it satisfies the following conditions:
+
+- the recipient is `0xae967917c465db8578ca9024c205720b1a3651a9`
+- the value is less than 50000000000000000 wei (0.05 ETH)
+
+and approves account listing if:
+
+- the request has arrived via ipc
+
+```js
+//ancillary function for formatting numbers
+function asBig(str) {
+	if (str.slice(0, 2) == "0x") {
+		return new BigNumber(str.slice(2), 16)
+	}
+	return new BigNumber(str)
+}
+
+// Approve transactions to a certain contract if value is below a certain limit
+function ApproveTx(req) {
+	var limit = big.Newint("0xb1a2bc2ec50000")
+	var value = asBig(req.transaction.value);
+
+	if (req.transaction.to.toLowerCase() == "0xae967917c465db8578ca9024c205720b1a3651a9")
+        && value.lt(limit)) {
+	return "Approve"
+	}
+    else{
+        return "Reject"
+    }
+}
+
+// Approve listings if request made from IPC
+function ApproveListing(req){
+    if (req.metadata.scheme == "ipc"){ return "Approve"}
+}
+// returning nothing passes the decision to the next UI for manual assessment
+```
+
+There are three possible outcomes to this ruleset that are handled in different ways:
+
+| Return value     | Action                                  |
+| ---------------- | --------------------------------------- |
+| "Approve"        | Auto-approve request                    |
+| "Reject"         | Auto-approve request                    |
+| Error            | Pass decision to UI for manual approval |
+| Unexpected value | Pass decision to UI for manual approval |
+| Nothing          | Pass decision to UI for manual approval |
+
+### Attestations {#attestations}
+
+Clef will not just accept and run arbitrary scripts - that would create an attack vector because a malicious party could change the rule file.Instead, the user explicitly _attests_ to a rule file, which involves injecting the file's SHA256 hash into Clef's secure store. The following code snippet shows how to calculate a SHA256 hash for a file named `rules.js` and pass it to Clef. Note that Clef will prompt the user to provide the master password because the Clef store has to be decrypted in order to add the attestation to it.
+
+```sh
+# calculate hash
+sha256sum rules.js
+
+# attest to rules.js in Clef
+clef attest 645b58e4f945e24d0221714ff29f6aa8e860382ced43490529db1695f5fcc71c
+```
+
+Once this attestation has been added to the Clef store, it can be used to automatically approve interactions that satisfy the conditions encoded in `rules.js` in Clef.
+
+### Account passwords {#account-passwords}
+
+The rules described in `rules.js` above require access to the accounts in the Clef keystore which are protected by user-defined passwords. The signer therefore requires access to these passwords in order to automatically unlock the keystore and sign data and transactions using the accounts.
+
+This is done using `clef setpw`, passing the account address as the sole argument:
+
+```sh
+clef setpw 0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3
+```
+
+which displays the following in the terminal:
+
+```terminal
+Please enter a password to store for this address:
+Password:
+Repeat password:
+
+Decrypt master seed of clef
+Password:
+INFO [07-01|14:05:56.031] Credential store updated   key=0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3
+```
+
+Note that Clef does not really 'unlock' an account, it just abstracts the process of providing the password away from the end-user in specific, predefined scenarios. If an account password exists in the Clef vault and the rule evaluates to "Approve" then Clef decrypts the password, uses it to decrypt the key, does the requested signing and then re-locks the account.
+
+### Implementing rules {#implementing-rules}
+
+Clef can be instructed to run an attested rule file simply by passing the path to `rules.js` to the `--rules` flag:
+
+```sh
+clef --keystore go-ethereum/goerli-data/ --configdir go-ethereum/goerli-data/clef --chainid 5 --rules rules.js
+```
+
+The following logs will be displayed in the terminal:
+
+```terminal
+INFO [07-01|13:39:49.726] Rule engine configured                   file=rules.js
+INFO [07-01|13:39:49.726] Starting signer                          chainid=5 keystore=$go-ethereum/goerli-data/ light-kdf=false advanced=false
+DEBUG[07-01|13:39:49.726] FS scan times                            list=35.15µs set=4.251µs diff=2.766µs
+DEBUG[07-01|13:39:49.727] Ledger support enabled
+DEBUG[07-01|13:39:49.727] Trezor support enabled via HID
+DEBUG[07-01|13:39:49.727] Trezor support enabled via WebUSB
+INFO [07-01|13:39:49.728] Audit logs configured                    file=audit.log
+DEBUG[07-01|13:39:49.728] IPC registered                           namespace=account
+INFO [07-01|13:39:49.728] IPC endpoint opened                      url=go-ethereum/goerli-data/clef/clef.ipc
+------- Signer info -------
+* intapi_version : 7.0.0
+* extapi_version : 6.0.0
+* extapi_http : n/a
+* extapi_ipc : go-ethereum/goerli-data/clef/clef.ipc
+```
+
+Any request that satisfies the ruleset will now be auto-approved by the rule file, for example the following request to sign a transaction made using the Geth Javascript console (note that the password for account `0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3` has already been provided to `setpw` and the recipient and value comply with the rules in `rules.js`):
+
+```js
+var tx = {
+  to: '0xae967917c465db8578ca9024c205720b1a3651a9',
+  from: '0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3',
+  value: web3.toWei(0.01, 'ether')
+};
+eth.sendTransaction(tx);
+```
+
+By contrast, the following transactions _do not_ satisfy the rules in `rules.js`:
+
+```js
+// violate maximum transaction value condition
+var tx = {
+  to: '0xae967917c465db8578ca9024c205720b1a3651a9',
+  from: '0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3',
+  value: web3.toWei(1, 'ether')
+};
+eth.sendTransaction(tx);
+```
+
+```js
+// violate recipient condition
+var tx = {
+  to: '0xae967917c465db8578ca9024c205720b1a3651a9',
+  from: '0xd4c4bb7d6889453c6c6ea3e9eab3c4177b4fbcc3',
+  value: web3.toWei(0.01, 'ether')
+};
+eth.sendTransaction(tx);
+```
+
+These latter two transactions, that do not satisfy the encoded rules in `rules.js`, are not automatically approved, but instead pass the decision back to the UI for manual approval by the user.
+
+### Summary of basic usage {#summary-of-usage}
+
+To summarize, the steps required to run Clef with an automated ruleset that requires account access is as follows:
+
+**1)** Define rules as Javascript and save as a `.js` file, e.g. `rules.js`
+
+**2)** Calculate hash of rule file using `sha256sum rules.js`
+
+**3)** Attest the rules in Clef using `clef attest <hash>`
+
+**4)** Set account passwords in Clef using `clef --setpw <address>`
+
+**5)** Start Clef with rule file enabled using `clef --keystore <path-to-keystore> --chainid <chainID> --rules rules.js`
+
+**6)** Make requests directly to Clef using the external API or connect to Geth by passing `--signer=<path to clef.ipc>` at Geth startup
+
+## More rules {#more-rules}
+
+Since rules are defined as Javascript code, rulesets of arbitrary complexity can be created and they can impose conditions on any part of a transaction, not only the recipient and value. A simple example is implementing a "whitelist" of recipients where transactions that have those
+accounts in the `to` field are automatically signed (for example perhaps transactions between a user's own accounts might be whitelisted):
+
+```js
+function ApproveTx(r) {
+  if (r.transaction.to.toLowerCase() == '0xd4c4bb7d6889453c6c6ea3e9eab3c4177b4fbcc3') {
+    return 'Approve';
+  }
+  if (r.transaction.to.toLowerCase() == '0xae967917c465db8578ca9024c205720b1a3651a9') {
+    return 'Reject';
+  }
+  // Otherwise goes to manual processing
+}
+```
+
+In addition to addresses and values, other properties of a request can also be incorporated into a ruleset. The example below demonstrates a ruleset for `approve_signData` imposing the following conditions on a transaction's sender and message data.
+
+1. The sender must be `0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3`
+2. The transaction message must include the text `wen-merge`, which is `77656E2D6D65726765` in hex.
+
+If these conditions are satisfied then the transaction is auto-approved (assuming the password for `0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3` has been provided to `setpw`).
+
+```js
+function ApproveListing() {
+  return 'Approve';
+}
+
+function ApproveSignData(req) {
+  if (req.address.toLowerCase() == '0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3') {
+    if (req.messages[0].value.indexOf('wen-merge') >= 0) {
+      return 'Approve';
+    }
+    return 'Reject';
+  }
+  // Otherwise goes to manual processing
+}
+```
+
+This file should be saved as a `.js` file, hashed and attested in Clef:
+
+```sh
+sha256sum rules.js
+```
+
+which returns:
+
+```terminal
+84d9e70aa30d0e5ffb3c4b376c9490f428390a196bfdc1d36770ffd2bbe66845  rules.js
+```
+
+then:
+
+```sh
+clef attest 84d9e70aa30d0e5ffb3c4b376c9490f428390a196bfdc1d36770ffd2bbe66845
+```
+
+which returns:
+
+```terminal
+Decrypt master seed of clef
+Password:
+INFO [07-01|14:11:28.509] Ruleset attestation updated    sha256=84d9e70aa30d0e5ffb3c4b376c9490f428390a196bfdc1d36770ffd2bbe66845
+```
+
+Then, Clef can be restarted with the new rules in place:
+
+```sh
+clef --keystore go-ethereum/goerli-data/clef --configdir go-ethereum/goerli-data/clef --chainid 5 --rules rules.js
+```
+
+```terminal
+INFO [07-01|14:12:41.636] Rule engine configured                   file=rules.js
+INFO [07-01|14:12:41.636] Starting signer                          chainid=5 keystore=go-ethereum/goerli-data/clef/keystore light-kdf=false advanced=false
+DEBUG[07-01|14:12:41.636] FS scan times                            list=46.722µs set=4.47µs diff=2.157µs
+DEBUG[07-01|14:12:41.637] Ledger support enabled
+DEBUG[07-01|14:12:41.637] Trezor support enabled via HID
+DEBUG[07-01|14:12:41.638] Trezor support enabled via WebUSB
+INFO [07-01|14:12:41.638] Audit logs configured                    file=audit.log
+DEBUG[07-01|14:12:41.638] IPC registered                           namespace=account
+INFO [07-01|14:12:41.638] IPC endpoint opened                      url=go-ethereum/goerli-data/clef/clef.ipc
+------- Signer info -------
+* intapi_version : 7.0.0
+* extapi_version : 6.0.0
+* extapi_http : n/a
+* extapi_ipc : go-ethereum/goerli-data/clef/clef.ipc
+```
+
+Finally, a request can be submitted to test that the rules are being applied as expected. Here, Clef is used independently of Geth by making a request via RPC, but the same logic would be imposed if the request was made via a connected Geth node. Some arbitrary text will be included in the message data that includes the term `wen-merge`. The plaintext `clefdemotextthatincludeswen-merge` is `636c656664656d6f7465787474686174696e636c7564657377656e2d6d65726765` when represented as a hexadecimal string. This can be passed as data to an `account_signData` request as follows:
+
+```sh
+echo '{"id": 1, "jsonrpc":"2.0", "method":"account_signData", "params":["data/plain", "0x636c656664656d6f7465787474686174696e636c7564657377656e2d6d65726765"]}' | nc -U ~/go-ethereum.goerli-data/clef/clef.ipc
+```
+
+This will be automatically signed, returning a result that looks like the following:
+
+```terminal
+{"jsonrpc":"2.0","id":1,"result":"0x4f93e3457027f6be99b06b3392d0ebc60615ba448bb7544687ef1248dea4f5317f789002df783979c417d969836b6fda3710f5bffb296b4d51c8aaae6e2ac4831c"}
+```
+
+Alternatively, a request that does not include the phrase `wen-merge` will not automatically approve. For example, the following request passes the hexadecimal string representing the plaintext `clefdemotextwithoutspecialtext`:
+
+```sh
+echo '{"id": 1, "jsonrpc":"2.0", "method":"account_signData", "params":["data/plain", "0x636c656664656d6f74657874776974686f75747370656369616c74657874"]}' | nc -U ~/go-ethereum.goerli-data/clef/clef.ipc
+```
+
+This returns a `Request denied` message as follows:
+
+```terminal
+{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"Request denied"}}
+```
+
+Meanwhile, in the output logs in the Clef terminal:
+
+```terminal
+INFO [02-21|14:42:41] Op approved
+INFO [02-21|14:42:56] Op rejected
+```
+
+The signer also stores all traffic over the external API in a log file. The last 4 lines shows the two requests and their responses:
+
+```terminal
+$ tail -n 4 audit.log
+t=2022-07-01T15:52:14+0300 lvl=info msg=SignData   api=signer type=request  metadata="{\"remote\":\"NA\",\"local\":\"NA\",\"scheme\":\"NA\",\"User-Agent\":\"\",\"Origin\":\"\"}" addr="0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3 [chksum INVALID]" data=0x202062617a6f6e6b2062617a2067617a0a content-type=data/plain
+t=2022-07-01T15:52:14+0300 lvl=info msg=SignData   api=signer type=response data=0x636c656664656d6f7465787474686174696e636c7564657377656e2d6d65726765 error=nil
+t=2022-07-01T15:52:23+0300 lvl=info msg=SignData   api=signer type=request  metadata="{\"remote\":\"NA\",\"local\":\"NA\",\"scheme\":\"NA\",\"User-Agent\":\"\",\"Origin\":\"\"}" addr="0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3 [chksum INVALID]" data=0x636c656664656d6f74657874776974686f75747370656369616c74657874     content-type=data/plain
+t=2022-07-01T15:52:23+0300 lvl=info msg=SignData   api=signer type=response data=                                     error="Request denied"
+```
+
+More examples, including a ruleset for a rate-limited window, are available on the [Clef GitHub](https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/rules.md#example-1-ruleset-for-a-rate-limited-window) and on the [Rules page](/docs/tools/clef/rules).
+
+## Under the hood {#under-the-hood}
+
+The examples on this page have provided step-by-step instructions for various operations using Clef. However, they have not provided much detail as to what is happening under the hood. This section will provide some more details about how Clef organizes itself locally.
+
+Initializing Clef with a master password and providing an account password to `clef setpw` and attesting a ruleset creates the following files in the directory `~/.clef/` (this path is independent of the paths provided to `--keystore` and `--configdir` on startup):
+
+```terminal
+# displayed using $ ls -laR ~/.clef/
+
+/home/user/.clef/:
+total 24
+drwxr-x--x   3 user user  4096 Jul  1 13:45 .
+drwxr-xr-x 102 user user 12288 Jul  1 13:39 ..
+drwx------   2 user user  4096 Jul  1 13:25 02f90c0603f4f2f60188
+-r--------   1 user user   868 Jun 28 13:55 masterseed.json
+
+/home/user/.clef/02f90c0603f4f2f60188:
+total 12
+drwx------ 2 user user 4096 Jul  1 13:25 .
+drwxr-x--x 3 user user 4096 Jul  1 13:45 ..
+-rw------- 1 user user  159 Jul  1 13:25 config.json
+-rw------- 1 user user  115 Jul  1 13:35 credentials.json
+```
+
+The file `masterseed.json` includes a json object containing the masterseed which was used to derive the vault directory (in this case `02f90c0603f4f2f60188`). The vault is encrypted using a password which is also derived from the masterseed. Inside the vault are two subdirectories:
+
+`credentials.json`
+
+`config.json`
+
+Inside `credentials.json` are the confidential `ksp` data (standing for "keystore pass" - these are the account passwords used to unlock the keystore).
+
+The `config.json` file contains encrypted key/value pairs for configuration data. Usually this is only the `sha256` hashes of any attested rulesets.
+
+Vault locations map uniquely to masterseeds so that multiple instances of Clef can co-exist each with their own attested rules and their own set of keystore passwords. This is useful for, for example, maintaining separate setups for Mainnet and testnets.
+
+The contents of each of these json files can be viewed using `cat` and should look something like the following:
+
+For `config.json`:
+
+```sh
+cat ~/.clef/02f90c0603f4f2f60188/config.json
+```
+
+```terminal
+{"ruleset_sha256":{"iv":"SWWEtnl+R+I+wfG7","c":"I3fjmwmamxVcfGax7D0MdUOL29/rBWcs73WBILmYK0o1CrX7wSMc3y37KsmtlZUAjp0oItYq01Ow8VGUOzilG91tDHInB5YHNtm/YkufEbo="}}
+```
+
+and for `credentials.json`:
+
+```sh
+cat ~/.clef/02f90c0603f4f2f60188/config.json
+```
+
+```terminal
+{"0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3": {"iv": "6SC062CfaUW8uSqH","c":"C+S5kaJyrarrxrAESs4EmPjL5zmg5tRh0Q=="}}
+```
+
+## Geth integration {#geth-integration}
+
+This tutorial has bounced back and forth between demonstrating Clef as a standalone tool by making 'manual` JSON RPC requests from the terminal and integrating it as a backend singer for Geth. Using Clef for account management is considered best practise for Geth users because of the additional
+security benefits it offers over and above what it offered by Geth's built-in accounts module. Clef is far more flexible and composable than Geth's built-in account management tool and can interface directly with hardware wallets, while Apps and wallets can request signatures directly from Clef.
+
+Ultimately, the goal is to deprecate Geth's account management tools completely and replace them with Clef. Until then, users are simply encouraged to choose to use Clef as an optional backend signer for Geth. In addition to the examples on this page, the [Getting started tutorial](/docs/getting-started) also demonstrates Clef/Geth integration.
+
+## Summary {#summary}
+
+This page includes step-by-step instructions for basic and intermediate uses of Clef, including using it as a standalone app and a backend signer for Geth. Further information is available on our other Clef pages, including [Introduction](/docs/tools/clef/introduction), [Setup](/docs/tools/clef/setup),
+[Rules](/docs/tools/clef/rules), [Communication Datatypes](/docs/clef/datatypes) and [Communication APIs](/docs/tools/clef/apis). Also see the [Clef GitHub](https://github.com/ethereum/go-ethereum/tree/master/cmd/clef) for further reading.

docs/tools/devp2p.md

@@ -0,0 +1,164 @@
+---
+title: devp2p
+description: introduction to the devp2p peer-to-peer networking tool
+---
+
+[DevP2P](https://github.com/ethereum/devp2p) is a set of network protocols that form the Ethereum peer-to-peer network. The DevP2P specifications define precisely how nodes should find each other and communicate. Geth implements the DevP2P specifications in Go.
+
+The DevP2P stack includes the low-level peer-to-peer protocols that define discovery and secure sessions between nodes such as:
+
+- [Ethereum Node Records](https://github.com/ethereum/devp2p/blob/master/enr.md): A standard format for connectivity information for a node
+- [Discovery protocol](https://github.com/ethereum/devp2p/blob/master/discv4.md): Defines how nodes find each other.
+- [RLPx protocol](https://github.com/ethereum/devp2p/blob/master/rlpx.md): Defines a TCP based transport system for communication between nodes.
+
+DevP2P also includes the RLPx-based application level protocols including:
+
+- [Ethereum Wire Protocol](https://github.com/ethereum/devp2p/blob/master/caps/eth.md): facilitates exchange of blockchain data between peers
+- [Ethereum Snapshot Protocol](https://github.com/ethereum/devp2p/blob/master/caps/snap.md): enables exchange of snapshots between peers
+- [Light Ethereum Subprotocol](https://github.com/ethereum/devp2p/blob/master/caps/les.md): protocol used by light clients
+
+To debug and develop these networking components, Geth includes a command line tool called `devp2p`.
+
+This page will outline some of `devp2p`s built-in tools.
+
+## ENR Decoding {#enr-decoding}
+
+Ethereum Node Records can be decoded, verified and displayed to the terminal using `enrdump`. It takes the ENR in its encoded form, which is the base64 encoding of its RLP representation. A decoded human-readable text representation is displayed.
+
+Use `devp2p enrdump <base64>` to verify and display an Ethereum Node Record.
+
+The following is an example of the data returned by `enrdump`:
+
+```terminal
+./devp2p enrdump "enr:-J24QG3pjTFObcDvTOTJr2qPOTDH3-YxDqS47Ylm-kgM5BUwb1oD5Id6fSRTfUzTahTa7y4TWx_HSV7wri7T6iYtyAQHg2V0aMfGhLjGKZ2AgmlkgnY0gmlwhJ1a19CJc2VjcDI1NmsxoQPlCNb7N__vcnsNC8YYkFkmNj8mibnR5NuvSowcRZsLU4RzbmFwwIN0Y3CCdl-DdWRwgnZf" Node ID: 001816492db22f7572e9eea1c871a2ffe75c28162a9fbc5a9d240e480a7c176f URLv4: ./devp2p enrdump  "enr:-J24QG3pjTFObcDvTOTJr2qPOTDH3-YxDqS47Ylm-kgM5BUwb1oD5Id6fSRTfUzTahTa7y4TWx_HSV7wri7T6iYtyAQHg2V0aMfGhLjGKZ2AgmlkgnY0gmlwhJ1a19CJc2VjcDI1NmsxoQPlCNb7N__vcnsNC8YYkFkmNj8mibnR5NuvSowcRZsLU4RzbmFwwIN0Y3CCdl-DdWRwgnZf"
+Node ID: 001816492db22f7572e9eea1c871a2ffe75c28162a9fbc5a9d240e480a7c176f
+URLv4:   enode://e508d6fb37ffef727b0d0bc618905926363f2689b9d1e4dbaf4a8c1c459b0b534dcdf84342b78250a6dc013c9ee9f89d095d7a6d1ef0c5f4c57a083b22c557ef@157.90.215.208:30303
+Record has sequence number 7 and 7 key/value pairs.
+  "eth"       c7c684b8c6299d80
+  "id"        "v4"
+  "ip"        157.90.215.208
+  "secp256k1" a103e508d6fb37ffef727b0d0bc618905926363f2689b9d1e4dbaf4a8c1c459b0b53
+  "snap"      c0
+  "tcp"       30303
+  "udp"       30303
+```
+
+Read more on [Ethereum Node Records](https://ethereum.org/en/developers/docs/networking-layer/network-addresses/#enr) or browse the [specs](https://github.com/ethereum/devp2p/blob/591edbd36eb57280384d07373a818c00bddf3b31/enr.md).
+
+## Node Key Management {#node-key-management}
+
+The `devp2p key ...` command family deals with node key files.
+
+Run `devp2p key generate mynode.key` to create a new node key in the `mynode.key` file.
+
+Run `devp2p key to-enode mynode.key -ip 127.0.0.1 -tcp 30303` to create an enode:// URL corresponding to the given node key and address information.
+
+## Maintaining DNS Discovery Node Lists {#maintaining-dns-discovery-lists}
+
+The devp2p command can create and publish DNS discovery node lists.
+
+Run `devp2p dns sign <directory>` to update the signature of a DNS discovery tree.
+
+Run `devp2p dns sync <enrtree-URL>` to download a complete DNS discovery tree.
+
+Run `devp2p dns to-cloudflare <directory>` to publish a tree to CloudFlare DNS.
+
+Run `devp2p dns to-route53 <directory>` to publish a tree to Amazon Route53.
+
+More information about these commands can be found in the [DNS Discovery Setup Guide](/docs/developers/geth-developer/dns-discovery-setup).
+
+## Node Set Utilities {#node-set-utilities}
+
+There are several commands for working with JSON node set files. These files are generated by the discovery crawlers and DNS client commands. Node sets also used as the input of the DNS deployer commands.
+
+Run `devp2p nodeset info <nodes.json>` to display statistics of a node set.
+
+Run `devp2p nodeset filter <nodes.json> <filter flags...>` to write a new, filtered node set to standard output. The following filters are supported:
+
+- `-limit <N>` limits the output set to N entries, taking the top N nodes by score
+- `-ip <CIDR>` filters nodes by IP subnet
+- `-min-age <duration>` filters nodes by 'first seen' time
+- `-eth-network <mainnet/goerli/sepolia>` filters nodes by "eth" ENR entry
+- `-les-server` filters nodes by LES server support
+- `-snap` filters nodes by snap protocol support
+
+For example, given a node set in `nodes.json`, you could create a filtered set containing up to 20 eth mainnet nodes which also support snap sync using this command:
+
+```sh
+devp2p nodeset filter nodes.json -eth-network mainnet -snap -limit 20
+```
+
+## Discovery v4 Utilities {#discovery-v4-utilities}
+
+The `devp2p discv4 ...` command family deals with the [Node Discovery v4](https://github.com/ethereum/devp2p/tree/master/discv4.md) protocol.
+
+Run `devp2p discv4 ping <enode/ENR>` to ping a node.
+
+Run `devp2p discv4 resolve <enode/ENR>` to find the most recent node record of a node in the DHT.
+
+Run `devp2p discv4 crawl <nodes.json path>` to create or update a JSON node set.
+
+## Discovery v5 Utilities {#discovery-v5-utilities}
+
+The `devp2p discv5 ...` command family deals with the [Node Discovery v5](https://github.com/ethereum/devp2p/tree/master/discv5/discv5.md) protocol. This protocol is currently under active development.
+
+Run `devp2p discv5 ping <ENR>` to ping a node.
+
+Run `devp2p discv5 resolve <ENR>` to find the most recent node record of a node in the discv5 DHT.
+
+Run `devp2p discv5 listen` to run a Discovery v5 node.
+
+Run `devp2p discv5 crawl <nodes.json path>` to create or update a JSON node set containing discv5 nodes.
+
+## Discovery Test Suites {#discovery-test-suites}
+
+The devp2p command also contains interactive test suites for Discovery v4 and Discovery v5. To run these tests a networking environment must be set up with two separate UDP listening addresses are available on the same machine. The two listening addresses must also be routed such
+that they are able to reach the node you want to test.
+
+For example, to run the test on the local host when the node under test is also on the local host, assign two IP addresses (or a larger range) to the loopback interface. On macOS, this can be done by executing the following command:
+
+```sh
+sudo ifconfig lo0 add 127.0.0.2
+```
+
+Either test suite can then be run as follows:
+
+1. Start the node under test first, ensuring that it won't talk to the Internet (i.e. disable bootstrapping). An easy way to prevent unintended connections to the global DHT is listening on `127.0.0.1`.
+
+2. Get the ENR of the node and store it in the `NODE` environment variable.
+
+3. Start the test by running `devp2p discv5 test -listen1 127.0.0.1 -listen2 127.0.0.2 $NODE`.
+
+## Eth Protocol Test Suite {#eth-protocol-test-suite}
+
+The Eth Protocol test suite is a conformance test suite for the [eth protocol](https://github.com/ethereum/devp2p/blob/master/caps/eth.md).
+
+To run the eth protocol test suite, the node needs to be initialized as follows:
+
+1. initialize the Geth node with the `genesis.json` file contained in the `testdata` directory
+2. import the `halfchain.rlp` file in the `testdata` directory
+3. run Geth with the following flags:
+
+```sh
+geth --datadir <datadir> --nodiscover --nat=none --networkid 19763 --verbosity 5
+```
+
+Then, run the following command, replacing `<enode>` with the enode of the Geth node:
+
+```sh
+devp2p rlpx eth-test <enode> cmd/devp2p/internal/ethtest/testdata/chain.rlp cmd/devp2p/internal/ethtest/testdata/genesis.json
+```
+
+Repeat the above process (re-initialising the node) in order to run the Eth Protocol test suite again.
+
+### Eth66 Test Suite {#eth66-test-suite}
+
+The Eth66 test suite is also a conformance test suite for the eth 66 protocol version specifically. To run the eth66 protocol test suite, initialize a Geth node as described above and run the following command, replacing `<enode>` with the enode of the Geth node:
+
+```sh
+devp2p rlpx eth66-test <enode> cmd/devp2p/internal/ethtest/testdata/chain.rlp cmd/devp2p/internal/ethtest/testdata/genesis.json
+```
+
+## Summary {#summary}
+
+This page introduced the DevP2P stack that defines Ethereum's peer-to-peer network and the `devp2p` command line tool that comes bundled with Geth. The `devp2p` tools enables Geth developers to work on the peer-to-peer network.

docs/tools/puppeth.md

@@ -0,0 +1,175 @@
+---
+title: Puppeth
+description: introduction to the private-network boot-strapping tool, Puppeth
+---
+
+Puppeth is a tool for quickly spinning up and managing private development networks. Puppeth gives fine-grained control over the network properties including the genesis block, signers, bootnodes, dashboards, etc but abstracts away the complexity of configuring it all manually.
+The user is guided through the process by a command line wizard.
+
+Puppeth comes bundled with Geth. The binary for Puppeth is built along with the other command line tools when the user runs `make all`. By default the binaries are saved to `build/bin`. This page demonstrates how to start a private proof-of-authority network with all the nodes running on the local machine. Other configurations are also possible, for example nodes can be spread over multiple (virtual) machines and the consensus mechanism can be proof-of-work.
+
+## Creating accounts {#creating-accounts}
+
+To run a Clique network, authorized nodes must seal each block. This requires accounts to exist that can be pre-authorized in the genesis block. These accounts should be created before Puppeth is started. The accounts can be created using Geth's built in account manager as follows:
+
+```sh
+geth account new --datadir NodeId
+```
+
+For each account, replace NodeId with Node 1, 2, 3 etc. This saves the details about each account to a new directory.
+
+Geth will prompt for a password. Once provided, the public address of the new account and the location of the secret key file is displayed to the terminal. It is a good idea to copy these details down in a text document because they will be needed later. This account generation step should be repeated until the number of accounts is at least equal to the desired number of nodes on the proof-of-authority network plus a few extra that will act as non-sealing nodes. Make sure the account passwords are also securely backed up for each new account.
+
+See more on the [account management pages](/docs/fundamentals/account-management).
+
+## Starting Puppeth {#starting-puppeth}
+
+Starting Puppeth is as easy as running `puppeth` in the terminal:
+
+```sh
+puppeth
+```
+
+This starts the wizard in the terminal.
+
+```terminal
++-----------------------------------------------------------+
+| Welcome to puppeth, your Ethereum private network manager |
+|                                                           |
+| This tool lets you create a new Ethereum network down to  |
+| the genesis block, bootnodes, miners and ethstats servers |
+| without the hassle that it would normally entail.         |
+|                                                           |
+| Puppeth uses SSH to dial in to remote servers, and builds |
+| its network components out of Docker containers using the |
+| docker-compose toolset.                                   |
++-----------------------------------------------------------+
+
+Please specify a network name to administer (no spaces or hyphens, please)
+```
+
+The wizard prompts for a network name, in this case it can be called `testnetwork`. Typing `testnetwork` and Enter returns the following:
+
+```terminal
+Sweet, you can set this via --network=testnetwork next time!
+
+INFO [08-15|12:40:39.643] Administering Ethereum network      name=testnetwork
+WARN [08-15|12:40:39.643] No previous configurations found    path=/home/.puppeth/testnetwork
+
+What would you like to do? (default = stats)
+1. Show network stats
+2. Configure new genesis block
+3. Track new remote server
+4. Deploy network components
+```
+
+There are four options displayed in the terminal. Select `2. Configure new genesis block` by typing `2` and Enter. The wizard presents the option to start a new genesis block from scratch or to import one. Select `1. Create new genesis block from scratch`. Then choose `Clique - proof-of-authority` when the wizard prompts for a choice of consensus engine, and then, when prompted, a block time in seconds (e.g. 15).
+
+Next, the wizard prompts for the addresses of accounts that should be authorized to sign blocks. Here, the public addresses of the accoutjs created earlier can be pasted one-by-one. Note that the leading `0x` is preset, so do not repeat it when copy/pasting. Enter each address individually, separating them by pressing Enter (i.e. do not enter a list of addresses).
+
+In a real network these would not be arbitrary accounts as they are in this demonstration, they would be trusted accounts belonging to specific node operators authorized to seal blocks.
+
+After determining the sealer accounts, the wizard asks which accounts to prefund with ether. Provide all the sealer account addresses and the additional addresses generated earlier.
+
+```terminal
+Which accounts are allowed to seal? (mandatory at least one)
+
+> 0xbb70c0073cb20d3b20cec14f2bfbe1b61a5b2bd1
+> 0xbef818cf91f521012020ff1ec17c5e5e929b2bc6
+...
+
+Which accounts should be pre-funded? (advisable at least one)
+
+> 0xbb70c0073cb20d3b20cec14f2bfbe1b61a5b2bd1
+> 0xbef818cf91f521012020ff1ec17c5e5e929b2bc6
+```
+
+The final prompt is for a network ID. For this tutorial it is fine to skip this by hitting Enter 0 - this causes Puppeth to fallback to its default behaviour which is to randomly generate a network ID.
+
+Puppeth will then display the following message to the terminal indicating that `testnetwork`'s genesis block has been configured.
+
+```terminal
+INFO [08-15|14:25:09.630] Configured new genesis block
+```
+
+Puppeth has also returned to the 'start menu' encountered earlier. Now, the second option on the menu has updated toread `2. manage existing genesis`. Selecting that option opens a new menu where the genesis configuration can be modified, removed or exported. Choose `2` again to export the config data as a set of json files to a user-defined directory.
+
+```terminal
+What would you like to do? (default = stats)
+1. Shown network status
+2. Manage existing genesis
+3. Track new remote server
+4. Deploy network components
+
+> 2
+
+1. Modify existing configurations
+2. Export genesis configurations
+3. Remove genesis configurations
+
+> 2
+
+Which folder to save the genesis specs into? (default = current)
+  Will create testnetwork.json, testnetwork-aleth.json, testnetwork-harmony.json, testnetwork-parity.json
+
+> /home/testnetwork
+```
+
+At this point a genesis configuration has been created and backed up. There are a few more componments that are required to start the network.
+
+## Network components {#network-components}
+
+Puppeth includes wizards for adding several network components:
+
+```sh
+1. Ethstats - Network monitoring tool
+2. Bootnode - Entry point for a network
+3. Sealer - Full node minting new blocks
+4. Explorer - Chain analysis webservice
+5. Faucet - Crypto faucet to give away funds
+6. Dashboard - Website listing above web services
+```
+
+These are all accessed by starting Puppeth and selecting `4. Deploy network components` from the main menu. They should be deployed in the numerical order in which they are listed in the `Network components` submenu.
+
+### Ethstats {#ethstats}
+
+Ethstats is a network monitoring service. The Ethstats server must already be installed (see [instructions](https://github.com/cubedro/eth-netstats)) and running so that its IP address can be provided to Puppeth. The IP address of each node is also required. The wizard guides the user through providing the IP addresses and ports for Ethstats and the local nodes and setting a password for the Ethstats API.
+
+### Bootnodes {#bootnodes}
+
+Bootnodes are nodes with hardcoded addresses that allow new nodes entering the network to immediately find peers to connect to. This makes peer discovery faster. The wizard guides the user through providing IP addresses for nodes on the network that will be used as bootnodes.
+
+### Sealer {#sealer}
+
+The sealer nodes must be specified. These validate the network by sealing blocks. The wizard prompts the user to provide the IP addresses for the sealer nodes along with their keyfiles and unlock passwords. Some additional information is also set for the bootnodes including their gas limit - the higher the gas limit the more work the node has to do to validate each block. To match Ethereum set it to 15,000,000. The gas price can be anything, but since it is a private test network it may as well be small, say 1 GWei.
+
+Puppeth will display the details of each node in a table in the terminal.
+
+### Explorer {#explorer}
+
+For proof-of-work networks a block explorer akin to [etherscan](https://etherscan.io/) can be created using the Puppeth wizard.
+
+### Faucet {#faucet}
+
+A faucet is an app that allows accounts to request ether to be sent to them. This can be created easily by following the wizard. The wizard prompts the user for details related to which node will act as a server for the faucet, how much ether to release per request, intervals between releases and some optional security features.
+
+### Dashboard {#dashboard}
+
+The dashboard wizard pulls together the pieces from the already-defined network components into a single dashboard that can be navigated to in a web browser. The wizard guides the user through the necessary steps. Optionally, the explorer and faucet apps can be deployed here too.
+
+The dashboard can then be viewed by navigating to the node's ip address and the defined port in a web browser.
+
+## Starting the network {#starting-network}
+
+Start instances of Geth for each node
+
+```sh
+geth --datadir Node1 --port 30301 --bootnodes <enr> --networkid <testnetwork ID> -unlock <node 1 address> --mine
+```
+
+## Summary {#summary}
+
+Puppeth is a command line wizard that guides a user through the various stages of setting up a private network using proof-of-authority or proof-of-work consensus engine. Various network components can be added that optimize the network or enable network monitoring.
+
+[GitHub repository](https://github.com/ethereum/go-ethereum/tree/master/cmd/puppeth)

netlify.toml

@@ -0,0 +1,4 @@
+# https://docs.netlify.com/integrations/frameworks/next-js/incremental-static-regeneration/
+
+[functions]
+  included_files = ["src/**"]

next-sitemap.config.js

@@ -0,0 +1,6 @@
+/** @type {import('next-sitemap').IConfig} */
+
+module.exports = {
+  siteUrl: 'https://geth.ethereum.org',
+  generateRobotsTxt: true
+};

next.config.js

@@ -0,0 +1,12 @@
+/** @type {import('next').NextConfig} */
+const { redirects: redirectsList } = require('./redirects');
+
+module.exports = {
+  reactStrictMode: true,
+  swcMinify: true,
+  // Append the default value with md extensions
+  pageExtensions: ['ts', 'tsx', 'md'],
+  async redirects() {
+    return redirectsList;
+  }
+};

package.json

@@ -0,0 +1,49 @@
+{
+  "name": "geth-site",
+  "private": false,
+  "description": "The website for geth.ethereum.org",
+  "version": "2.0.0",
+  "author": "Nicolás Quiroz <nicolas.quiroz@ethereum.org>",
+  "scripts": {
+    "dev": "next dev",
+    "build": "npm run lint && next build && npm run format:fix",
+    "postbuild": "next-sitemap",
+    "start": "next start",
+    "lint": "next lint",
+    "format:fix": "prettier . --write --config .prettierrc --ignore-path .prettierignore --loglevel warn"
+  },
+  "dependencies": {
+    "@chakra-ui/icons": "^2.0.11",
+    "@chakra-ui/react": "^2.3.2",
+    "@docsearch/react": "3",
+    "@emotion/react": "^11.10.4",
+    "@emotion/styled": "^11.10.4",
+    "algoliasearch": "^4.14.2",
+    "chakra-ui-markdown-renderer": "^4.1.0",
+    "fast-xml-parser": "^4.0.12",
+    "focus-visible": "^5.2.0",
+    "framer-motion": "^7.3.2",
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.0",
+    "next": "^13.0.2",
+    "next-sitemap": "^3.1.32",
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "react-markdown": "^8.0.3",
+    "react-syntax-highlighter": "^15.5.0",
+    "rehype-raw": "^6.1.1",
+    "remark-gfm": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.5",
+    "@types/node": "18.7.16",
+    "@types/react": "18.0.18",
+    "@types/react-dom": "18.0.6",
+    "@types/react-syntax-highlighter": "^15.5.5",
+    "eslint": "8.23.0",
+    "eslint-config-next": "12.2.5",
+    "eslint-config-prettier": "^8.5.0",
+    "prettier": "^2.7.1",
+    "typescript": "4.8.2"
+  }
+}

public/code/qubes-client.py

@@ -0,0 +1,23 @@
+"""
+This implements a dispatcher which listens to localhost:8550, and proxies
+requests via qrexec to the service qubes.EthSign on a target domain
+"""
+
+import http.server
+import socketserver,subprocess
+
+PORT=8550
+TARGET_DOMAIN= 'debian-work'
+
+class Dispatcher(http.server.BaseHTTPRequestHandler):
+    def do_POST(self):
+        post_data = self.rfile.read(int(self.headers['Content-Length']))
+        p = subprocess.Popen(['/usr/bin/qrexec-client-vm',TARGET_DOMAIN,'qubes.Clefsign'],stdin=subprocess.PIPE, stdout=subprocess.PIPE)
+        output = p.communicate(post_data)[0]
+        self.wfile.write(output)
+
+
+with socketserver.TCPServer(("",PORT), Dispatcher) as httpd:
+    print("Serving at port", PORT)
+    httpd.serve_forever()
+

public/code/qubes.Clefsign

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+SIGNER_BIN="/home/user/tools/clef/clef"
+SIGNER_CMD="/home/user/tools/gtksigner/gtkui.py -s $SIGNER_BIN"
+
+# Start clef if not already started
+if [ ! -S /home/user/.clef/clef.ipc ]; then
+	$SIGNER_CMD &
+	sleep 1
+fi
+
+# Should be started by now
+if [ -S /home/user/.clef/clef.ipc ]; then
+    # Post incoming request to HTTP channel
+	curl -H "Content-Type: application/json" -X POST -d @- http://localhost:8550 2>/dev/null
+fi

public/docs/vulnerabilities/vulnerabilities.json

@@ -0,0 +1,168 @@
+[
+  {
+    "name": "CorruptedDAG",
+    "uid": "GETH-2020-01",
+    "summary": "Mining nodes will generate erroneous PoW on epochs > `385`.",
+    "description": "A mining flaw could cause miners to erroneously calculate PoW, due to an index overflow, if DAG size is exceeding the maximum 32 bit unsigned value.\n\nThis occurred on the ETC chain on 2020-11-06. This is likely to trigger for ETH mainnet around block `11550000`/epoch `385`, slated to occur early January 2021.\n\nThis issue is relevant only for miners, non-mining nodes are unaffected, since non-mining nodes use a smaller verification cache instead of a full DAG.",
+    "links": [
+      "https://github.com/ethereum/go-ethereum/pull/21793",
+      "https://blog.ethereum.org/2020/11/12/geth_security_release/",
+      "https://github.com/ethereum/go-ethereum/commit/567d41d9363706b4b13ce0903804e8acf214af49",
+      "https://github.com/ethereum/go-ethereum/security/advisories/GHSA-v592-xf75-856p"
+    ],
+    "introduced": "v1.6.0",
+    "fixed": "v1.9.24",
+    "published": "2020-11-12",
+    "severity": "Medium",
+    "CVE": "CVE-2020-26240",
+    "check": "Geth\\/v1\\.(6|7|8)\\..*|Geth\\/v1\\.9\\.\\d-.*|Geth\\/v1\\.9\\.1.*|Geth\\/v1\\.9\\.2(0|1|2|3)-.*"
+  },
+  {
+    "name": "Denial of service due to Go CVE-2020-28362",
+    "uid": "GETH-2020-02",
+    "summary": "A denial-of-service issue can be used to crash Geth nodes during block processing, due to an underlying bug in Go (CVE-2020-28362) versions < `1.15.5`, or `<1.14.12`",
+    "description": "The DoS issue can be used to crash all Geth nodes during block processing, the effects of which would be that a major part of the Ethereum network went offline.\n\nOutside of Go-Ethereum, the issue is most likely relevant for all forks of Geth (such as TurboGeth or ETC’s core-geth) which is built with versions of Go which contains the vulnerability.",
+    "links": [
+      "https://blog.ethereum.org/2020/11/12/geth_security_release/",
+      "https://groups.google.com/g/golang-announce/c/NpBGTTmKzpM",
+      "https://github.com/golang/go/issues/42552",
+      "https://github.com/ethereum/go-ethereum/security/advisories/GHSA-m6gx-rhvj-fh52"
+    ],
+    "introduced": "v0.0.0",
+    "fixed": "v1.9.24",
+    "published": "2020-11-12",
+    "severity": "Critical",
+    "CVE": "CVE-2020-28362",
+    "check": "Geth.*\\/go1\\.(11(.*)|12(.*)|13(.*)|14|14\\.(\\d|10|11|)|15|15\\.[0-4])$"
+  },
+  {
+    "name": "ShallowCopy",
+    "uid": "GETH-2020-03",
+    "summary": "A consensus flaw in Geth, related to `datacopy` precompile",
+    "description": "Geth erroneously performed a 'shallow' copy when the precompiled `datacopy` (at `0x00...04`) was invoked. An attacker could deploy a contract that uses the shallow copy to corrupt the contents of the `RETURNDATA`, thus causing a consensus failure.",
+    "links": [
+      "https://blog.ethereum.org/2020/11/12/geth_security_release/",
+      "https://github.com/ethereum/go-ethereum/security/advisories/GHSA-69v6-xc2j-r2jf"
+    ],
+    "introduced": "v1.9.7",
+    "fixed": "v1.9.17",
+    "published": "2020-11-12",
+    "severity": "Critical",
+    "CVE": "CVE-2020-26241",
+    "check": "Geth\\/v1\\.9\\.(7|8|9|10|11|12|13|14|15|16).*$"
+  },
+  {
+    "name": "Geth DoS via MULMOD",
+    "uid": "GETH-2020-04",
+    "summary": "A denial-of-service issue can be used to crash Geth nodes during block processing",
+    "description": "Affected versions suffer from a vulnerability which can be exploited through the `MULMOD` operation, by specifying a modulo of `0`: `mulmod(a,b,0)`, causing a `panic` in the underlying library. \nThe crash was in the `uint256` library, where a buffer [underflowed](https://github.com/holiman/uint256/blob/4ce82e695c10ddad57215bdbeafb68b8c5df2c30/uint256.go#L442).\n\n\tif `d == 0`, `dLen` remains `0`\n\nand https://github.com/holiman/uint256/blob/4ce82e695c10ddad57215bdbeafb68b8c5df2c30/uint256.go#L451 will try to access index `[-1]`.\n\nThe `uint256` library was first merged in this [commit](https://github.com/ethereum/go-ethereum/commit/cf6674539c589f80031f3371a71c6a80addbe454), on 2020-06-08. \nExploiting this vulnerabilty would cause all vulnerable nodes to drop off the network. \n\nThe issue was brought to our attention through a [bug report](https://github.com/ethereum/go-ethereum/issues/21367), showing a `panic` occurring on sync from genesis on the Ropsten network.\n \nIt was estimated that the least obvious way to fix this would be to merge the fix into `uint256`, make a new release of that library and then update the geth-dependency.\n",
+    "links": [
+      "https://blog.ethereum.org/2020/11/12/geth_security_release/",
+      "https://github.com/ethereum/go-ethereum/security/advisories/GHSA-jm5c-rv3w-w83m",
+      "https://github.com/holiman/uint256/releases/tag/v1.1.1",
+      "https://github.com/holiman/uint256/pull/80",
+      "https://github.com/ethereum/go-ethereum/pull/21368"
+    ],
+    "introduced": "v1.9.16",
+    "fixed": "v1.9.18",
+    "published": "2020-11-12",
+    "severity": "Critical",
+    "CVE": "CVE-2020-26242",
+    "check": "Geth\\/v1\\.9.(16|17).*$"
+  },
+  {
+    "name": "LES Server DoS via GetProofsV2",
+    "uid": "GETH-2020-05",
+    "summary": "A DoS vulnerability can make a LES server crash.",
+    "description": "A DoS vulnerability can make a LES server crash via malicious GetProofsV2 request from a connected LES client.\n\nThe vulnerability was patched in #21896.\n\nThis vulnerability only concern users explicitly running geth as a light server",
+    "links": [
+      "https://github.com/ethereum/go-ethereum/security/advisories/GHSA-r33q-22hv-j29q",
+      "https://github.com/ethereum/go-ethereum/pull/21896"
+    ],
+    "introduced": "v1.8.0",
+    "fixed": "v1.9.25",
+    "published": "2020-12-10",
+    "severity": "Medium",
+    "CVE": "CVE-2020-26264",
+    "check": "(Geth\\/v1\\.8\\.*)|(Geth\\/v1\\.9\\.\\d-.*)|(Geth\\/v1\\.9\\.1\\d-.*)|(Geth\\/v1\\.9\\.(20|21|22|23|24)-.*)$"
+  },
+  {
+    "name": "SELFDESTRUCT-recreate consensus flaw",
+    "uid": "GETH-2020-06",
+    "introduced": "v1.9.4",
+    "fixed": "v1.9.20",
+    "summary": "A consensus-vulnerability in Geth could cause a chain split, where vulnerable versions refuse to accept the canonical chain.",
+    "description": "A flaw was repoted at 2020-08-11 by John Youngseok Yang (Software Platform Lab), where a particular sequence of transactions could cause a consensus failure.\n\n- Tx 1:\n - `sender` invokes `caller`.\n - `caller` invokes `0xaa`. `0xaa` has 3 wei, does a self-destruct-to-self\n - `caller` does a  `1 wei` -call to `0xaa`, who thereby has 1 wei (the code in `0xaa` still executed, since the tx is still ongoing, but doesn't redo the selfdestruct, it takes a different path if callvalue is non-zero)\n\n-Tx 2:\n - `sender` does a 5-wei call to 0xaa. No exec (since no code). \n\nIn geth, the result would be that `0xaa` had `6 wei`, whereas OE reported (correctly) `5` wei. Furthermore, in geth, if the second tx was not executed, the `0xaa` would be destructed, resulting in `0 wei`. Thus obviously wrong. \n\nIt was determined that the root cause was this [commit](https://github.com/ethereum/go-ethereum/commit/223b950944f494a5b4e0957fd9f92c48b09037ad) from [this PR](https://github.com/ethereum/go-ethereum/pull/19953). The semantics of `createObject` was subtly changd, into returning a non-nil object (with `deleted=true`) where it previously did not if the account had been destructed. This return value caused the new object to inherit the old `balance`.\n",
+    "links": ["https://github.com/ethereum/go-ethereum/security/advisories/GHSA-xw37-57qp-9mm4"],
+    "published": "2020-12-10",
+    "severity": "High",
+    "CVE": "CVE-2020-26265",
+    "check": "(Geth\\/v1\\.9\\.(4|5|6|7|8|9)-.*)|(Geth\\/v1\\.9\\.1\\d-.*)$"
+  },
+  {
+    "name": "Not ready for London upgrade",
+    "uid": "GETH-2021-01",
+    "summary": "The client is not ready for the 'London' technical upgrade, and will deviate from the canonical chain when the London upgrade occurs (at block '12965000' around August 4, 2021.",
+    "description": "At (or around) August 4, Ethereum will undergo a technical upgrade called 'London'. Clients not upgraded will fail to progress on the canonical chain.",
+    "links": [
+      "https://github.com/ethereum/eth1.0-specs/blob/master/network-upgrades/mainnet-upgrades/london.md",
+      "https://notes.ethereum.org/@timbeiko/ropsten-postmortem"
+    ],
+    "introduced": "v1.10.1",
+    "fixed": "v1.10.6",
+    "published": "2021-07-22",
+    "severity": "High",
+    "check": "(Geth\\/v1\\.10\\.(1|2|3|4|5)-.*)$"
+  },
+  {
+    "name": "RETURNDATA corruption via datacopy",
+    "uid": "GETH-2021-02",
+    "summary": "A consensus-flaw in the Geth EVM could cause a node to deviate from the canonical chain.",
+    "description": "A memory-corruption bug within the EVM can cause a consensus error, where vulnerable nodes obtain a different `stateRoot` when processing a maliciously crafted transaction. This, in turn, would lead to the chain being split: mainnet splitting in two forks.\n\nAll Geth versions supporting the London hard fork are vulnerable (the bug is older than London), so all users should update.\n\nThis bug was exploited on Mainnet at block 13107518.\n\nCredits for the discovery go to @guidovranken (working for Sentnl during an audit of the Telos EVM) and reported via bounty@ethereum.org.",
+    "links": [
+      "https://github.com/ethereum/go-ethereum/blob/master/docs/postmortems/2021-08-22-split-postmortem.md",
+      "https://github.com/ethereum/go-ethereum/security/advisories/GHSA-9856-9gg9-qcmq",
+      "https://github.com/ethereum/go-ethereum/releases/tag/v1.10.8"
+    ],
+    "introduced": "v1.10.0",
+    "fixed": "v1.10.8",
+    "published": "2021-08-24",
+    "severity": "High",
+    "CVE": "CVE-2021-39137",
+    "check": "(Geth\\/v1\\.10\\.(0|1|2|3|4|5|6|7)-.*)$"
+  },
+  {
+    "name": "DoS via malicious `snap/1` request",
+    "uid": "GETH-2021-03",
+    "summary": "A vulnerable node is susceptible to crash when processing a maliciously crafted message from a peer, via the snap/1 protocol. The crash can be triggered by sending a malicious snap/1 GetTrieNodes package.",
+    "description": "The `snap/1` protocol handler contains two vulnerabilities related to the `GetTrieNodes` packet, which can be exploited to crash the node. Full details are available at the GitHub security [advisory](https://github.com/ethereum/go-ethereum/security/advisories/GHSA-59hh-656j-3p7v)",
+    "links": [
+      "https://github.com/ethereum/go-ethereum/security/advisories/GHSA-59hh-656j-3p7v",
+      "https://geth.ethereum.org/docs/vulnerabilities/vulnerabilities",
+      "https://github.com/ethereum/go-ethereum/pull/23657"
+    ],
+    "introduced": "v1.10.0",
+    "fixed": "v1.10.9",
+    "published": "2021-10-24",
+    "severity": "Medium",
+    "CVE": "CVE-2021-41173",
+    "check": "(Geth\\/v1\\.10\\.(0|1|2|3|4|5|6|7|8)-.*)$"
+  },
+  {
+    "name": "DoS via malicious p2p message",
+    "uid": "GETH-2022-01",
+    "summary": "A vulnerable node can crash via p2p messages sent from an attacker node, if running with non-default log options.",
+    "description": "A vulnerable node, if configured to use high verbosity logging, can be made to crash when handling specially crafted p2p messages sent from an attacker node. Full details are available at the GitHub security [advisory](https://github.com/ethereum/go-ethereum/security/advisories/GHSA-wjxw-gh3m-7pm5)",
+    "links": [
+      "https://github.com/ethereum/go-ethereum/security/advisories/GHSA-wjxw-gh3m-7pm5",
+      "https://geth.ethereum.org/docs/vulnerabilities/vulnerabilities",
+      "https://github.com/ethereum/go-ethereum/pull/24507"
+    ],
+    "introduced": "v1.10.0",
+    "fixed": "v1.10.17",
+    "published": "2022-05-11",
+    "severity": "Low",
+    "CVE": "CVE-2022-29177",
+    "check": "(Geth\\/v1\\.10\\.(0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16)-.*)$"
+  }
+]

public/docs/vulnerabilities/vulnerabilities.json.minisig

@@ -0,0 +1,4 @@
+untrusted comment: signature from minisign secret key
+RWQk7Lo5TQgd+9DjD2nXoabMy0BkWSuMiePPOQ9rXlwzvjhRGzEtwPDK3YupbRT9/OmyykFLGHCzWTRKVtVfYqFHL07m0DOOnww=
+trusted comment: timestamp:1652258428	file:vulnerabilities.json
+jtud9mtIiBRWA+krlBf1WCHgRzkcuzeoe9YLjLfHLEUQosbs+Ru1oaxx+nhxmjKdSRFwhPy1yoV5j9+rw55yCg==