Merge pull request #1027 from HorizenOfficial/pc/version_0_12_notes

0.12.0 release notes & docs

CHANGELOG.md

@@ -1,5 +1,13 @@
 **0.12.0**
 1. Sparkz dependency updated to 2.4.0
+    * Updates in EON forger nodes connection policy (see release notes for further info) 
+2. New stake management support (see release notes for further info)
+3. Reward from mainchain - new rules (see release notes for further info)
+4. Added metrics endpoint
+5. Minor fixes:
+    * [eth RPC endpoint]  web3_clientVersion now returns also the EON version
+    * [eth RPC endpoint] Better error handling: in case of error the response status code will be 400 instead of 200
+    * [eth RPC endpoint] In case of batch requests, the response is  now always an array,  even with a batch composed of only one element.
 
 **0.11.0**
 1. Sparkz dependency updated to 2.3.0

doc/release/0.12.0.md

@@ -4,16 +4,129 @@
 
 ## Notes about new/updated Features
 
----
-## Bug Fixes
+### Stake V2 
 
----
+Support for new stake management, with two main targets:
 
-## Improvements
-
----
-## Update test instructions from previous version
+- Switch from a “UTXO based” to an “Account based” model (no more stakeId assigned to each delegation operation, but just a balance assigned to each pair [forger,delegator])
+- Allow the possibility to redirect earnings to a smart-contract, which will be responsible for rewards distribution among the delegators.
+
+Notable changes:
+- The old stake native smart contract will be deprecated/deactivated.
+A new native smart contract will be activated.
+Methods exposed will allow to:
+
+    - Introduce a preliminary mandatory registration step for forgers: will be performed by executing a transaction declaring the forger public keys (VRF key and block sign key), the percentage of rewards to be redirected to a smart contract responsible to manage the delegators’ rewards (named “reward share”), and the address of that smart contract. (The last two fields will be optional).
+    An additional signature will be required with the method to prove the sender is the effective owner of the forger keys: for this reason the preferred way is to use the new http endpoint /transaction/registerForger to invoke the tx based on the local wallet data (it will handle automatically the additional signature). A method is also available in the native smart contract, but currently there is no way to generate a vrf signature from outside the node (it requires the cryptolib, and we don’t have the layer to invoke it from javascript)
+    - A minimum amount of 10 ZEN will be required to be sent with the transaction: it will be converted automatically into the first stake assigned to the forger.
+    - The registration step will not be required for existing forgers owning a stake before the hardfork: they will be automatically added to the list of registered ones, with “reward share” = 0 and “smart contract address” = none.
+    - Introduce an updateForger() method to allow forgers with “reward share” = 0 and “smart contract address” = none to update the fields. The update will be allowed only one time: once set, the values will be immutable. This protects delegators from distribution mechanisms being changed without their knowledge.
+    - Modify the consensus lottery to consider only forgers owning an amount of stakes (directly or delegated) equals or over to 10 ZEN.
+
+The following changes will happen in the http endpoints:
+- /transaction/allForgingStakes and /transaction/myForgingStakes
+Same format as now, but the output field stakeId will no more be present
+- /transaction/makeForgerStake<br>
+**DEPRECATED** (creation of a new stake will be doable only by calling the native smart contract method delegate)
+- /transaction/spendForgingStake<br>
+**DEPRECATED** (withdraw of a stake will be doable only by calling the native smart contract method withdraw)
+
+The following addition will be included in:<br>
+
+Endpoint: /block/getFeePayments <br>
+Rpc endpoint: zen_getFeePayments<br>
+
+Their result will keep the same format as now, but will also include the reward paid to the address of the smart contracts (if defined).
+
+We will also detail the amount coming from the mainchain redistribution: to be retrocompatible they will be into additional fields valueFromMainchain and valueFromFees:
+
+```
+{
+    "result" : {            
+        "feePayments" : [
+            {
+            "address" : "c49dedc85a2c360fea781bcea2bc5d58fde19",
+            "value" : 2000000   -> total
+            "valueFromMainchain:": 500000    -> part from the mainchain
+            "valueFromFees": 1500000      -> part from the fees 
+            }
+        ]
+    }
+}
+```
+### Reward from mainchain - new rules
+
+The maximum ZEN amount redistributed to forgers from the special address 0x000000000000000000003333333333333333333 in a single withdrawal epoch is now  limited to a maximum value expressed by the following formula:
+
+- MAX_VALUE_REDISTRIBUTED = sum [10% of Mainchain’s block-reward Coinbase of each mainchain block reference included in the withdrawal epoch]
+
+- Funds over the limit will stay in the address balance and will be redistributed in the following epochs.
+
+For example:<br>
+Current Mainchain block reward: 6.25 ZEN<br>
+Number of mainchain block-reference in a withdrawal epoch: 100<br>
+MAX_VALUE_REDISTRIBUTED = 10%(6.25) * 100 = 62.5 ZEN<br>
+
+###  Updates in RPC endpoints
+
+- web3_clientVersion now returns also the EON version, in the following format:
+EON_VERSION/SDK_VERSION/ARCHITECTURE/JAVA_VERSION
+
+- Better error handling: in case of error the response status code will be 400 instead of 200.
+
+- In case of batch requests, the response is now always an array, even with a batch composed of only one element. Previously, if the batch request was composed by only one element,  the response was an object.
+
+###   New metrics endpoint
+A new endpoint can be optionally exposed (on a different port from the serverAPI) to show some node metrics.
+To configure it, you can add the following new fragment in the settings file (fragment is optional, the value displayed are the defaults):
+```
+metricsApi {
+ enabled = false
+ bindAddress = "127.0.0.1:9088"
+ timeout = 5s
+ #apiKeyHash = ""
+}
+```
+
+Format:
+
+The metrics will be exposed in a http endpoint /metrics, in Prometheus format, one line per metric, in this format:
+
+```
+metric_id value
+```
+
+Available metrics:
+
+Following metrics will be available (also listed in the endpoint /metrics/help):
+
+- **block_apply_time**<br>
+Time to apply block to node wallet and state (milliseconds)
+- **block_apply_time_fromslotstart**<br>
+Delta between timestamp when block has been applied successfully on this node and start timestamp of the slot it belongs to (milliseconds)
+- **block_applied_ok**<br>
+Number of received blocks applied successfully (absolute value since start of the node)
+- **block_applied_ko**<br>
+Number of received blocks not applied (absolute value since start of the node)
+- **mempool_size**<br>
+Mempool size (number of transactions in this node mempool)
+- **forge_block_count**<br>
+Number of forged blocks by this node (absolute value since start of the node)
+- **forge_lottery_time**<br>
+Time to execute the lottery (milliseconds)
+- **forge_blockcreation_time**<br>
+Time to create a new forged block (calculated from the start timestamp of the slot it belongs to) (milliseconds)
+
+###   Updates in EON forger nodes connection policy
+
+Default value for the property:
+
+maxForgerConnections
+
+Has been increased from 20 to 100.
+(Remember this only applies if no value is set explicitly in conf / docker env).
 
+Furthermore, the dedicated connection pool for forgers nodes (governed by the above property) now only applies if the node is itself a forger.
 
 ---
 Full [Changelog](/CHANGELOG.md) file here