Enable gas price

docs/concepts/architecture.md

@@ -25,6 +25,6 @@ GoQuorum includes the following changes to geth:
 * Block validation logic is changed to handle [private transactions](privacy/private-and-public.md#private-transactions).
 * Transaction creation is changed to allow for replacing transaction data with encrypted hashes to preserve private data
   where required.
-* [The pricing of gas is removed.](free-gas-network.md) Gas itself remains.
+* [The pricing of gas is removed unless explicitly enabled.](free-gas-network.md) Gas itself remains.
 
 For more information about the GoQuorum architecture and its differences from geth, contact us on [GoQuorum support](../support.md).

docs/concepts/free-gas-network.md

@@ -4,7 +4,7 @@ description: Free gas networks
 
 # Free gas networks
 
-GoQuorum is a free gas network, which means there's no gas price.
+By default, GoQuorum is a free gas network, which means there's no gas price.
 
 Transactions use computational resources, so they have associated costs.
 *Gas* is the cost unit and *gas price* is the price per gas unit.
@@ -22,7 +22,7 @@ Some private networks might allocate Ether and use a non-zero gas price to limit
 In free gas networks, the gas price is zero but transactions still use gas, so the transaction cost (gas used multiplied
 by the gas price) is zero.
 
-In GoQuorum, gas price is completely removed.
+In GoQuorum, gas price is completely removed unless [explicitly enabled](gas-enabled-network.md).
 Gas price is not included as a transaction object parameter in [GoQuorum privacy API methods](../reference/api-methods.md#privacy-methods).
 When using standard Ethereum JSON-RPC methods such as
 [`sendSignedTransaction`](https://web3js.readthedocs.io/en/v1.3.4/web3-eth.html#sendsignedtransaction), you must set

docs/concepts/gas-enabled-network.md

@@ -0,0 +1,89 @@
+---
+description: Gas enabled networks
+---
+
+# Gas enabled networks
+
+By default, GoQuorum is a [free gas network](free-gas-network.md), which means gas is priced at zero and is not consumed when transactions are processed.
+However, gas price can be enabled if required.
+
+Transactions use computational resources, so they have associated costs.
+*Gas* is the cost unit and *gas price* is the price per gas unit.
+The transaction cost is the gas used multiplied by the gas price.
+
+If gas is enabled, then similar to public Ethereum networks, the account submitting the transaction pays the transaction cost, in Ether.
+The miner (or validator, in proof of authority networks) that includes the transaction in a block receives the
+transaction cost.
+
+## Using gas in GoQuorum
+
+### Enabling gas price
+
+To enable gas price in GoQuorum, set `enableGasPriceBlock` in the GoQuorum
+[genesis file](../configure-and-manage/configure/genesis-file/genesis-options.md) `config` object to a future block, when the entire network is
+ready to transact with gas price enabled transactions.
+All GoQuorum nodes in the network must be initialized with the same `enableGasPriceBlock` value.
+
+!!! note
+
+    You need to re-run `geth init` when you update the genesis file to incorporate the changes. This does not delete or modify any current sync process or saved blocks.
+
+## Nuances of gas price in GoQuorum
+
+There are some nuances around gas price and the rewarded account, which vary depending on which consensus mechanism is selected.
+These will impact how a gas enabled GoQuorum network is set up, and are described below.
+
+### Private transactions
+
+The amount of gas consumed by a private transaction is only the `intrinsic gas` value, and this is based on the private transaction hash held in the `data` field (rather than the entire private payload).
+The actual cost of creating or executing a private contract cannot be used. Members who are not party to the transaction will be unable to calculate the private gas cost and the network will not be able to reach a consensus.
+
+Also, the amount of gas used is by a private transaction is not show in the transaction receipt.
+This is to avoid leakage of details about the private transaction.
+
+### Privacy marker transactions
+
+The (public) privacy marker transaction will consume gas as normal.
+However, the inner private transaction is not available to non-participants, therefore members who are not party to the transaction will be unable to even calculate the intrinsic gas.
+Therefore the private transaction will not consume any gas.
+
+### Raft
+
+The transaction cost is rewarded to the etherbase account (aka coinbase account), which is the default primary local account.
+The etherbase account can be set on startup using the command line flag `--miner.etherbase`.
+Note that for technical reasons the etherbase account cannot be changed at runtime using `miner.SetEtherbase()`.
+
+If `--mine` is not provided on the command line then the (leader) node will still mint blocks, but `--miner.gasprice` will be ignored.
+Also, the txpool default gasPrice won’t be set to 1000000000.
+Therefore we suggest starting all raft nodes with ‘--mine'.
+
+Standard geth behaviour is that if a transaction has less gas than the accepted minimum (set using `--miner.gasprice`) then it will not be mined by remote miner nodes.
+On Raft, there is no rotation of miners, therefore if the local node is not the minter then it means the transaction will remain pending until it is resubmitted with an above minimum gas value (or until the local node becomes the miner).
+
+Raft inherits the static block reward that is awarded to miners on upstream geth. The static block reward amount varies according to the current release, with the following values currently defined:
+
+- FrontierBlockReward           = big.NewInt(5e+18) // Block reward in wei for successfully mining a block
+- ByzantiumBlockReward          = big.NewInt(3e+18) // Block reward in wei for successfully mining a block upward from Byzantium
+- ConstantinopleBlockReward     = big.NewInt(2e+18) // Block reward in wei for successfully mining a block upward from Constantinople
+
+!!! info
+
+    The block `miner` field is now populated with the rewarded account.
+
+### Istanbul
+
+Standard geth behaviour is that if a transaction has less gas than the accepted minimum (set using `--miner.gasprice`) then it will not be mined by remote miner nodes.
+On Istanbul, it means the transaction is only processed when the current node becomes voted in as minter.
+
+The Istanbul block signer is rewarded for creating the block, using the account number derived from the nodekey of the miner.
+
+Note that `miner.SetEtherbase()`, and the command line flag `--miner.etherbase` have no effect for Istanbul.
+
+### Clique
+
+Standard geth behaviour is that if a transaction has less gas than the accepted minimum (set using `--miner.gasprice`) then it will not be mined by remote miner nodes.
+On Clique, it means the transaction is only processed when the current node becomes voted in as minter.
+
+The Clique block signer is rewarded for creating the block, this is the coinbase account of the miner and will be present in the `extraData` field of the genesis block or have been added using `clique.propose()` (otherwise an "unathorized signer" error will occur).
+
+Note that `miner.SetEtherbase()`, and the command line flag `--miner.etherbase` have no effect for Clique.

mkdocs.navigation.yml

@@ -82,6 +82,7 @@ nav:
           - Comparing PoA consensus protocols: concepts/consensus/comparing-poa.md
       - Account management: concepts/account-management.md
       - Free gas network: concepts/free-gas-network.md
+      - Gas enabled network: concepts/gas-enabled-network.md
       - Privacy:
           - concepts/privacy/index.md
           - Public and private transactions: concepts/privacy/private-and-public.md