diff --git a/docs/Concepts/Protocol-Upgrades.md b/docs/Concepts/Protocol-Upgrades.md index a33edcfad97..28efce6e700 100644 --- a/docs/Concepts/Protocol-Upgrades.md +++ b/docs/Concepts/Protocol-Upgrades.md @@ -26,4 +26,4 @@ example, [Istanbul](https://eips.ethereum.org/EIPS/eip-1679). For compatibility with future protocol upgrades, do not hardcode any gas price assumptions. Implementing upgradeable contracts enables contracts to be upgraded if a protocol upgrade does - include breaking changes. \ No newline at end of file + include breaking changes. \ No newline at end of file diff --git a/docs/HowTo/Configure/Configure-Mining.md b/docs/HowTo/Configure/Configure-Mining.md index a305753f308..ffc3fa891c4 100644 --- a/docs/HowTo/Configure/Configure-Mining.md +++ b/docs/HowTo/Configure/Configure-Mining.md @@ -1,48 +1,67 @@ +--- description: Using Hyperledger Besu for PoW CPU mining - +--- # Mining -## Configure CPU Mining +## Configure CPU mining + +To enable CPU mining, start Hyperledger Besu with the following options: -Start Hyperledger Besu with the following options to enable CPU mining: ```bash besu --rpc-http-api=ETH,MINER --miner-enabled --miner-coinbase= ``` -Where `` is the account to which mining rewards are to be paid. For example, `fe3b557e8fb62b89f4916b721be55ceb828dbd73`. +Where `` is the account you pay mining rewards to. For example, +`fe3b557e8fb62b89f4916b721be55ceb828dbd73`. + +Start and stop mining using the [`miner_start`](../../Reference/API-Methods.md#miner_start) and +[`miner_stop`](../../Reference/API-Methods.md#miner_stop) APIs. -Use the [`miner_start`](../../Reference/API-Methods.md#miner_start) and [`miner_stop`](../../Reference/API-Methods.md#miner_stop) APIs to start and stop mining. +## Configure GPU mining -## Configure GPU Mining +Besu supports GPU mining, tested using [Ethminer](https://github.com/ethereum-mining/ethminer) with +the `stratum+tcp` scheme. -Besu supports GPU mining and has been tested using [Ethminer](https://github.com/ethereum-mining/ethminer) with the `stratum+tcp` scheme. Start Hyperledger Besu with the following options to enable GPU mining: +To enable GPU mining, start Hyperledger Besu with the following options: ```bash besu --rpc-http-api=ETH,MINER --miner-enabled --miner-stratum-enabled --miner-coinbase= ``` -Where `` is the account to which mining rewards are to be paid. For example, `fe3b557e8fb62b89f4916b721be55ceb828dbd73`. +Where `` is the account you pay mining rewards to. For example, +`fe3b557e8fb62b89f4916b721be55ceb828dbd73`. Optional command line options are: -* [`--miner-stratum-host`](../../Reference/CLI/CLI-Syntax.md#miner-stratum-host) to specify the host of the mining service. -* [`--miner-stratum-port`](../../Reference/CLI/CLI-Syntax.md#miner-stratum-port) to specify the port of the mining service. +* [`--miner-stratum-host`](../../Reference/CLI/CLI-Syntax.md#miner-stratum-host) to specify the + host of the mining service. +* [`--miner-stratum-port`](../../Reference/CLI/CLI-Syntax.md#miner-stratum-port) to specify the + port of the mining service. !!! note - Besu also supports the `getwork` scheme. Use the [`--miner-stratum-enabled`](../../Reference/CLI/CLI-Syntax.md#miner-stratum-enabled) option and [enable the `ETH` RPCs](../../Reference/CLI/CLI-Syntax.md#rpc-http-api). - + + Besu also supports the `getwork` scheme. Use the + [`--miner-stratum-enabled`](../../Reference/CLI/CLI-Syntax.md#miner-stratum-enabled) option and + [enable the `ETH` RPCs](../../Reference/CLI/CLI-Syntax.md#rpc-http-api). + The `getwork` scheme is supported as the `http` scheme in certain mining software. -Use the [`miner_start`](../../Reference/API-Methods.md#miner_start) and [`miner_stop`](../../Reference/API-Methods.md#miner_stop) APIs to start and stop mining. +Start and stop mining using the [`miner_start`](../../Reference/API-Methods.md#miner_start) and +[`miner_stop`](../../Reference/API-Methods.md#miner_stop) APIs. ## Mining APIs -JSON-RPC API methods for mining are: - -* [`miner_start`](../../Reference/API-Methods.md#miner_start) to start mining. -* [`miner_stop`](../../Reference/API-Methods.md#miner_stop) to stop mining. -* [`eth_mining`](../../Reference/API-Methods.md#eth_mining) to determine whether the client is actively mining new blocks. -* [`eth_hashrate`](../../Reference/API-Methods.md#eth_hashrate) to get the number of hashes per second with which the node is mining. Is not supported for GPU mining. -* [`eth_getWork`](../../Reference/API-Methods.md#eth_getwork) to get the hash of the current block, the seed hash, and the target boundary condition to be met. Only used when using the `getwork` scheme. -* [`eth_submitWork`](../../Reference/API-Methods.md#eth_submitwork) to submit the PoW solution. Only used when using the `getwork` scheme. \ No newline at end of file +The JSON-RPC API methods for mining are: + +* [`miner_start`](../../Reference/API-Methods.md#miner_start) to start mining. +* [`miner_stop`](../../Reference/API-Methods.md#miner_stop) to stop mining. +* [`eth_mining`](../../Reference/API-Methods.md#eth_mining) to determine whether the client is + actively mining new blocks. +* [`eth_hashrate`](../../Reference/API-Methods.md#eth_hashrate) to get the number of hashes per + second with which the node is mining. Not supported for GPU mining. +* [`eth_getWork`](../../Reference/API-Methods.md#eth_getwork) to get the hash of the current block, + the seed hash, and the target boundary condition. Only used when using the `getwork` + scheme. +* [`eth_submitWork`](../../Reference/API-Methods.md#eth_submitwork) to submit the PoW solution. + Only used when using the `getwork` scheme. \ No newline at end of file diff --git a/docs/HowTo/Configure/Configure-TLS.md b/docs/HowTo/Configure/Configure-TLS.md index 5a5b3664661..967442aa54d 100644 --- a/docs/HowTo/Configure/Configure-TLS.md +++ b/docs/HowTo/Configure/Configure-TLS.md @@ -1,10 +1,12 @@ +--- description: Configure TLS - +--- # Configure TLS Hyperledger Besu supports TLS for client and server communication. For example, you can -[configure TLS](../../Concepts/TLS.md) for communication between EthSigner and Besu, and Besu and Orion. +[configure TLS](../../Concepts/TLS.md) for communication between EthSigner and Besu, and Besu and +Orion. Configure TLS communication from the command line. @@ -15,39 +17,41 @@ Configure TLS communication from the command line. ## Configure Client TLS -Allow clients (for example a dApp, curl, or EthSigner) to send and receive -secure HTTP JSON-RPCs. +Allow clients (for example a dApp, curl, or EthSigner) to send and receive secure HTTP JSON-RPCs. **Client Prerequisites**: -* The client must be configured for TLS. +* Configure the client for TLS. * Client's PKCS #12 keystore information. ### Create the Known Clients File -The known clients file allows clients with self-signed certificates or -non-public certificates to connect to Besu. +The known clients file allows clients with self-signed certificates or non-public certificates to +connect to Besu. -Create a file (in this example, `knownClients`) that lists one or more trusted -clients. Use the format` ` where: +Create a file (in this example, `knownClients`) that lists one or more trusted clients. Use the +format` ` where: * `` is the Common Name specified in the client certificate. * `` is the SHA-256 fingerprint of the client certificate. !!! example + ``` ethsigner 8E:E0:85:9F:FC:2E:2F:21:31:46:0B:82:4C:A6:88:AB:30:34:9A:C6:EA:4F:04:31:ED:0F:69:A7:B5:C2:2F:A7 curl FC:18:BF:39:45:45:9A:15:46:76:A6:E7:C3:94:64:B8:34:84:A3:8E:B8:EA:67:DC:61:C0:29:E6:38:B8:B7:99 ``` - -You can use [`openssl`](https://www.openssl.org/) or [`keytool`](https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html) -to display the SHA256 fingerprint. + +You can use [`openssl`](https://www.openssl.org/) or +[`keytool`](https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html) to display +the SHA256 fingerprint. !!! example + ``` keytool -list -v -keystore -storetype PKCS12 -storepass `. ``` - + ### Start Besu ```bash @@ -56,49 +60,55 @@ besu --rpc-http-enabled --rpc-http-tls-enabled --rpc-http-tls-client-auth-enable The command line: -* Enables the HTTP JSON-RPC service using the [`--rpc-http-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-enabled) option. -* Enables TLS for the HTTP JSON-RPC service using the [`--rpc-http-tls-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-enabled) -option. -* Enables TLS client authentication using the [`--rpc-http-tls-client-auth-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-client-auth-enabled) option. -* Specifies the keystore using the [`--rpc-http-tls-keystore-file`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-keystore-file) option. -* Specifies the file that contains the password to decrypt the keystore using -the [`--rpc-http-tls-keystore-password-file`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-keystore-password-file) option. -* [Specifies the clients](#create-the-known-clients-file) that are allowed to connect to Besu using the -[`--rpc-http-tls-known-clients-file`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-known-clients-file) option. +* Enables the HTTP JSON-RPC service using the + [`--rpc-http-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-enabled) option. +* Enables TLS for the HTTP JSON-RPC service using the + [`--rpc-http-tls-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-enabled) option. +* Enables TLS client authentication using the + [`--rpc-http-tls-client-auth-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-client-auth-enabled) option. +* Specifies the keystore using the + [`--rpc-http-tls-keystore-file`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-keystore-file) + option. +* Specifies the file that contains the password to decrypt the keystore using the + [`--rpc-http-tls-keystore-password-file`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-keystore-password-file) option. +* [Specifies the clients](#create-the-known-clients-file) allowed to connect to Besu using the + [`--rpc-http-tls-known-clients-file`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-known-clients-file) option. !!! note + Set [`--rpc-http-tls-ca-clients-enabled`](../../Reference/CLI/CLI-Syntax.md#rpc-http-tls-ca-clients-enabled) to `true` to allow access to clients with signed and trusted root CAs. - + ## Configure Server TLS Allow Besu to securely communicate with the server (Orion). - + **Server Prerequisites**: -* The server must be configured to allow TLS communication +* Configure the server to allow TLS communication. * Server's certificate information. ### Create the Known Servers file -Create a file (in this example, `knownServers`) that lists one or more trusted -servers. The file contents use the format `: ` -where: +Create a file (in this example, `knownServers`) that lists one or more trusted servers. The file +contents use the format `: ` where: * `` is the server hostname * `` is the port used for communication * `` is the SHA-256 fingerprint of the server's certificate. !!! example + ``` localhost:8888 3C:B4:5A:F9:88:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:AC 127.0.0.1:8888 3C:B4:5A:F9:88:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:AC ``` !!! note - Specify both hostname and IP address in the file if unsure which is used in - requests. - + + If you are unsure whether requests use the hostname or an IP address, configure both in the + file. + ### Start Besu ```bash @@ -107,8 +117,12 @@ besu --privacy-tls-enabled --privacy-tls-keystore-file=/Users/me/my_node/keystor The command line: -* Enables TLS with the server using the [`--privacy-tls-enabled`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-enabled) option. -* Specifies the keystore using the [`--privacy-tls-keystore-file`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-keystore-file) option. -* Specifies the file that contains the password to decrypt the keystore using -the [`--privacy-tls-keystore-password-file`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-keystore-password-file) option. -* Specifies the trusted servers using the [`--privacy-tls-known-enclave-file`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-known-enclave-file) option. \ No newline at end of file +* Enables TLS with the server using the + [`--privacy-tls-enabled`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-enabled) option. +* Specifies the keystore using the + [`--privacy-tls-keystore-file`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-keystore-file) + option. +* Specifies the file that contains the password to decrypt the keystore using the + [`--privacy-tls-keystore-password-file`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-keystore-password-file) option. +* Specifies the trusted servers using the + [`--privacy-tls-known-enclave-file`](../../Reference/CLI/CLI-Syntax.md#privacy-tls-known-enclave-file) option. \ No newline at end of file diff --git a/docs/HowTo/Configure/Contracts-in-Genesis.md b/docs/HowTo/Configure/Contracts-in-Genesis.md index 172cef3d954..352859adf10 100644 --- a/docs/HowTo/Configure/Contracts-in-Genesis.md +++ b/docs/HowTo/Configure/Contracts-in-Genesis.md @@ -1,11 +1,13 @@ -description: Pre-deploying contracts in genesis file - +--- +description: Predeploying contracts in the genesis file +--- -# Predeploying Contracts in the Genesis File +# Predeploying contracts in the genesis file -To predeploy contracts when starting Besu, specify contract code in the genesis file. +To predeploy contracts when starting Besu, specify the contract code in the genesis file. + +!!! example "Contract code in the genesis file" -!!! example "Contract Code in Genesis File" ```json { ... @@ -22,10 +24,10 @@ To predeploy contracts when starting Besu, specify contract code in the genesis ... } ``` - -The contract code in the genesis file defines: -* Address -* Balance -* Bytecode -* Key value pairs for contract storage. \ No newline at end of file +The contract code in the genesis file defines the: + +* Address +* Balance +* Bytecode +* Key value pairs for contract storage. \ No newline at end of file diff --git a/docs/HowTo/Configure/FreeGas.md b/docs/HowTo/Configure/FreeGas.md index e8aede55f9d..1cf5b4a1607 100644 --- a/docs/HowTo/Configure/FreeGas.md +++ b/docs/HowTo/Configure/FreeGas.md @@ -1,54 +1,61 @@ -description: Configuring Free Gas Networks - +--- +description: Configuring free gas networks +--- -# Free Gas Networks +# Free gas networks -Transactions use computational resources so have an associated cost. Gas is the cost unit and the gas -price is the price per gas unit. The transaction cost is the gas used * gas price. +Transactions use computational resources so have an associated cost. Gas is the cost unit and the +gas price is the price per gas unit. The transaction cost is the gas used * gas price. -In public networks, the transaction cost is paid in Ether by the account submitting the transaction. -The transaction cost is paid to the miner (or validator in PoA networks) that includes the transaction in a block. +In public networks, the account submitting the transaction pays the transaction cost, in Ether. +The miner (or validator in PoA networks) that includes the transaction in a block receives +transaction cost. -In many private networks, the validators are run by the network participants and do not require gas as an -incentive to participate. Generally, networks that do not require gas as an incentive, configure the gas price to be 0 (that is, make gas free). -Some private networks may allocate Ether and use a non-zero gas price to limit resource use. +In many private networks, network participants run the validators and do not require gas as an +incentive. Networks no require gas as an incentive usually configure the gas price to be zero (that +is, make the gas free). Some private networks might allocate Ether and use a non-zero gas price to +limit resource use. !!! tip - We are using the term _free gas network_ to refer to a network where the gas price is set to zero. - A network with gas price of zero is also known as a _zero gas network_ or _no gas network_. -In a free gas network, transactions still use gas but the gas price is 0 meaning the transaction cost is 0: + We use the term _free gas network_ to refer to a network with a gas price of zero. A network + with a gas price of zero is also known as a _zero gas network_ or _no gas network_. -Transaction cost = gas used * 0 (gas price) +In a free gas network, transactions still use gas but the gas price is zero, meaning the +transaction cost is zero. Transaction cost = gas used * 0 (the gas price). -## Configuring Hyperledger Besu for Free Gas +## Configuring free gas in Hyperledger Besu -When gas is free, limiting block and contract sizes is less important. In free gas networks, we increase the -block size limit and set the contract size limit to the maximum value. +When gas is free, limiting block and contract sizes is less important. In free gas networks, we +increase the block size limit and set the contract size limit to the maximum value. -### 1. Set Block Size +### 1. Set the block size -If you want to remove gas from consideration and don't mind blocks potentially taking longer -to be created, set the block size limit (measured in gas) in the genesis file to the maximum accepted by Truffle (`0x1fffffffffffff`): +If you want to remove gas from consideration and don't mind blocks potentially taking longer to +create, in the genesis file set the block size limit (measured in gas) to the maximum accepted by +Truffle (`0x1fffffffffffff`). ```json "gasLimit": "0x1fffffffffffff" ``` -If you are more concerned about blocks arriving on time and don't have very expensive individual transactions, set the -`gasLimit` to a value closer to the amount of gas your validators can process in the configured block time. +If you are more concerned about blocks arriving on time and don't have expensive individual +transactions, set `gasLimit` to a value closer to the amount of gas your validators can process in +the configured block time. -### 2. Set Contract Size +### 2. Set the contract size -Set the contract size limit to the maximum supported size (in bytes) in the `config` section of the genesis file: +In the `config` section of the genesis file set the contract size limit to the maximum supported +size (in bytes). ```json "contractSizeLimit": 2147483647 ``` -### 3. Start Besu with Minimum Gas Price of 0 +### 3. Start Besu with a minimum gas price of zero -When starting nodes, set the [minimum gas price](../../Reference/CLI/CLI-Syntax.md#min-gas-price) to 0: +When starting nodes, set the [minimum gas price](../../Reference/CLI/CLI-Syntax.md#min-gas-price) +to zero. ```bash tab="Command Line" --min-gas-price=0 @@ -58,30 +65,31 @@ When starting nodes, set the [minimum gas price](../../Reference/CLI/CLI-Syntax. min-gas-price=0 ``` -## Configuring Truffle for Free Gas +## Configuring free gas in Truffle -If using Truffle to develop on your free gas network, you also need to configure Truffle for free gas. +If using Truffle to develop on your free gas network, you also need to configure free gass in +Truffle. -Similar to setting block and contract size limits to their maximum values for Besu, we set the -transaction gas limit in Truffle to the maximum possible. +Like setting block and contract size limits to their maximum values for Besu, set the transaction +gas limit in Truffle to the maximum possible. !!! important - Besu does not implement private key management. To use Besu with Truffle, you must configure - a [Truffle wallet](../Develop-Dapps/Truffle.md). + Besu does not support private key management. To use Besu with Truffle, you must configure + a [Truffle wallet](../Develop-Dapps/Truffle.md). ### Update truffle-config.js -Update the `truffle-config.js` file: +Update the `truffle-config.js` file: -1. Set the gas price to 0: +1. Set the gas price to zero. ```js gasPrice:0 ``` -1. Set the gas limit for a transaction (that is, contract creation) to be the block gas limit - 1 +1. Set the gas limit for a transaction (that is, contract creation) to be the block gas limit - 1. ```js gas: "0x1ffffffffffffe" - ``` + ``` diff --git a/docs/HowTo/Configure/Genesis-File.md b/docs/HowTo/Configure/Genesis-File.md index 2b8cef983a8..0320a73c2c2 100644 --- a/docs/HowTo/Configure/Genesis-File.md +++ b/docs/HowTo/Configure/Genesis-File.md @@ -1,21 +1,25 @@ -description: Configuring network using genesis file - +--- +description: Configuring a network using the genesis file +--- -# Creating Hyperledger Besu Genesis File +# Creating the Hyperledger Besu genesis file -The genesis file defines the first block in the chain and the first block defines which chain you want to join. +The genesis file defines the first block in the chain and the first block defines which chain you +want to join. -For Ethereum MainNet and public testnets (for example, Rinkeby), the genesis configuration is defined in -Besu and used when a public network is specified using the [`--network`](../../Reference/CLI/CLI-Syntax.md#network) -command line option. +For Ethereum MainNet and public testnets (for example, Rinkeby) the genesis configuration +definition is in Besu and used when specifying a public network using the +[`--network`](../../Reference/CLI/CLI-Syntax.md#network) command line option. -For private networks, create a JSON genesis file and specify the genesis file using the [`--genesis-file`](../../Reference/CLI/CLI-Syntax.md#genesis-file) -command line option. +For private networks, create a JSON genesis file and specify the genesis file using the +[`--genesis-file`](../../Reference/CLI/CLI-Syntax.md#genesis-file) command line option. -[Network wide settings](../../Reference/Config-Items.md) are specified in the genesis file so all nodes in a network must use the same genesis file. +The genesis file specifies the [network-wide settings](../../Reference/Config-Items.md) so all +nodes in a network must use the same genesis file. -!!! example - ```json +!!! example + + ```json { "config": { "chainId": 2018, @@ -36,7 +40,7 @@ command line option. "alloc": { "9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb": { "balance": "0xad78ebc5ac6200000" - } + } } } ``` diff --git a/docs/HowTo/Configure/Passing-JVM-Options.md b/docs/HowTo/Configure/Passing-JVM-Options.md index b7981994437..beb6c77e03f 100644 --- a/docs/HowTo/Configure/Passing-JVM-Options.md +++ b/docs/HowTo/Configure/Passing-JVM-Options.md @@ -1,15 +1,20 @@ +--- description: Passing Java virtual machine JVM options to Hyperledger Besu at runtime - +--- -# Passing JVM Options +# Passing JVM options -To perform tasks such as attaching a debugger or configuring the garbage collector, pass JVM options to Hyperledger Besu. +To perform tasks such as attaching a debugger or configuring the garbage collector, pass JVM +options to Hyperledger Besu. -Besu passes the contents of the `BESU_OPTS` environmental variable to the JVM. Set standard JVM options in the `BESU_OPTS` variable. +Besu passes the contents of the `BESU_OPTS` environmental variable to the JVM. Set standard JVM +options in the `BESU_OPTS` variable. -For Bash-based executions, you can set the variable for only the scope of the program execution by setting it before starting Besu. +For Bash-based executions, you can set the variable for only the scope of the program execution by +setting it before starting Besu. !!! example + ```bash BESU_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 \ besu --network=rinkeby diff --git a/docs/HowTo/Configure/Using-Configuration-File.md b/docs/HowTo/Configure/Using-Configuration-File.md index 77e1c710cd0..9f04bc6c299 100644 --- a/docs/HowTo/Configure/Using-Configuration-File.md +++ b/docs/HowTo/Configure/Using-Configuration-File.md @@ -1,58 +1,65 @@ -description: Using Hyperledger Besu Configuration File - +--- +description: Using the Hyperledger Besu configuration file +--- -# Using Hyperledger Besu Configuration File +# Using the Hyperledger Besu configuration file -To specify command line options in a file, use a TOML configuration file. +To specify command line options in a file, use a TOML configuration file. -The configuration file can be saved and reused across node startups. To specify the configuration file, -use the [`--config-file`](../../Reference/CLI/CLI-Syntax.md#config-file) option. +Save the configuration file and reuse it across node startups. To specify the configuration file, +use the [`--config-file`](../../Reference/CLI/CLI-Syntax.md#config-file) option. -To override an option specified in the configuration file, specify the same option on the command line or as -an [environment variable](../../Reference/CLI/CLI-Syntax.md#besu-environment-variables). If an option is specified in multiple places, -the order of priority is command line, environment variable, configuration file. +To override an option specified in the configuration file, either specify the same option on the +command line or as an +[environment variable](../../Reference/CLI/CLI-Syntax.md#besu-environment-variables). For options +specified in more than one place, the order of precedence is command line, environment variable, +configuration file. -## TOML Specification +## TOML specification -The configuration file must be a valid TOML file and is composed of key/value pairs. Each key is the -same as the corresponding command line option name without the leading dashes (`--`). +The configuration file must be a valid TOML file composed of key/value pairs. Each key is the same +as the corresponding command line option name without the leading dashes (`--`). -Values must be be specified according to TOML specifications for string, numbers, arrays, and booleans. -Specific differences between the command line and the TOML file format are: +Values must conform to TOML specifications for string, numbers, arrays, and booleans. Specific +differences between the command line and the TOML file format are: -* Comma-separated lists on the command line are string arrays in the TOML file -* File paths, hexadecimal numbers, URLs, and <host:port> values must be enclosed in quotes. +* Comma-separated lists on the command line are string arrays in the TOML file. +* Enclose file paths, hexadecimal numbers, URLs, and <host:port> values in quotes. !!!tip - The [command line reference](../../Reference/CLI/CLI-Syntax.md) includes configuration file examples for each option. -!!!example "Example TOML configuration file" + The [command line reference](../../Reference/CLI/CLI-Syntax.md) includes configuration file + examples for each option. + +!!!example "Sample TOML configuration file" + ```toml # Valid TOML config file data-path="~/besudata" # Path - + # Network bootnodes=["enode://001@123:4567", "enode://002@123:4567", "enode://003@123:4567"] - + p2p-host="1.2.3.4" p2p-port=1234 max-peers=42 - + rpc-http-host="5.6.7.8" rpc-http-port=5678 - + rpc-ws-host="9.10.11.12" rpc-ws-port=9101 - + # Chain genesis-file="~/genesis.json" # Path to the custom genesis file - + # Mining miner-enabled=true miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" ``` - -!!!example "Starting Besu with a Configuration File" + +!!!example "Starting Besu with a configuration file" + ```bash besu --config-file=/home/me/me_node/config.toml ``` diff --git a/docs/HowTo/Upgrade/Upgrade-Protocol.md b/docs/HowTo/Upgrade/Upgrade-Protocol.md index df276c012e0..052923a7901 100644 --- a/docs/HowTo/Upgrade/Upgrade-Protocol.md +++ b/docs/HowTo/Upgrade/Upgrade-Protocol.md @@ -1,18 +1,25 @@ -description: Upgrading protocol versions - +--- +description: Upgrading protocol versions +--- -## Upgrading your protocol in a private network +## Upgrading your protocol in a private network -To [upgrade the protocol](../../Concepts/Protocol-Upgrades.md) in a private network: +To [upgrade the protocol](../../Concepts/Protocol-Upgrades.md) (also known as a hardfork) in a +private network: -1. Review included EIPs for breaking changes. A [meta EIP](https://eips.ethereum.org/meta) -for each protocol upgrade lists included EIPs. For example, [Istanbul](https://eips.ethereum.org/EIPS/eip-1679). -1. Network participants agree on block number at which to [upgrade](../../Concepts/Protocol-Upgrades.md). -1. For each node in the network: +1. Review included EIPs for breaking changes. A [meta EIP](https://eips.ethereum.org/meta) + for each protocol upgrade lists included EIPs. For example, + [Istanbul](https://eips.ethereum.org/EIPS/eip-1679). +1. Network participants agree on block number at which to + [upgrade](../../Concepts/Protocol-Upgrades.md). +1. For each node in the network: - a. Add the [milestone block number](../../Reference/Config-Items.md#milestone-blocks) to the genesis file. - b. Restart node before reaching milestone block. + a. Add the + [milestone block number](../../Reference/Config-Items.md#milestone-blocks) to the genesis + file. + b. Restart the node before reaching milestone block. -!!! caution - To avoid a forked network, all network participants must update their genesis file to include the - agreed on milestone block and restart their node before reaching the milestone block. \ No newline at end of file +!!! caution + + To avoid a forked network, all network participants must update their genesis file to include + the agreed on milestone block and restart their node before reaching the milestone block. \ No newline at end of file