add descriptions to network-statistic and precompiled-gas (#789)

docs/api.md

@@ -870,6 +870,24 @@ curl -X POST --data '{"jsonrpc":"2.0","method":"sendRawTransaction","params":[1,
 curl -X POST --data '{"jsonrpc":"2.0","method":"sendRawTransaction","params":[1,"f90114a003eebc46c9c0e3b84799097c5a6ccd6657a9295c11270407707366d0750fcd598411e1a30084b2d05e008201f594bab78cea98af2320ad4ee81bba8a7473e0c8c48d80a48fff0fc400000000000000000000000000000000000000000000000000000000000000040101a48fff0fc40000000000000000000000000000000000000000000000000000000000000004b8408234c544a9f3ce3b401a92cc7175602ce2a1e29b1ec135381c7d2a9e8f78f3edc9c06ee55252857c9a4560cb39e9d70d40f4331cace4d2b3121b967fa7a829f0a00f16d87c5065ad5c3b110ef0b97fe9a67b62443cb8ddde60d4e001a64429dc6ea03d2569e0449e9a900c236541afb9d8a8d5e1a36844439c7076f6e75ed624256f"],"id":1}' http://127.0.0.1:8545 |jq 
 ```
 
+## sendRawTransactionAndGetProof
+
+执行一个签名的交易，交易上链后，推送交易回执、交易Merkle证明、交易回执Merkle证明，Merkle证明可参考[这里](./design/merkle_proof.md)。
+
+```eval_rst
+.. note::
+    - ``supported_version < 2.2.0``: 调用 ``sendRawTransactionAndGetProof`` 接口，交易上链后仅推送交易回执
+    - ``supported_version >= 2.2.0``: 调用 ``sendRawTransactionAndGetProof`` 接口，交易上链后推送交易回执、交易Merkle证明、交易回执Merkle证明
+```
+
+### 参数          
+- `groupID`: `unsigned int` - 群组ID           
+- `rlp`: `string` - 签名的交易数据
+
+### 返回值          
+- `string` - 交易哈希
+- 示例：同`sendRawTransaction`，参考[这里](./api.html#sendrawtransaction)
+
 
 ## getTransactionByHashWithProof
 返回根据交易哈希查询的带证明的交易信息，本接口仅在兼容性版本为2.2.0及以后的版本有效，证明信息是为了验证交易的存在性，交易存在性证明请参考文档[交易证明](./design/merkle_proof.md) 

docs/change_log/2_4_0.md

@@ -14,11 +14,11 @@
 
 **新特性**
 
-- 支持动态群组生命周期管理
-- 支持网络流量和Gas统计
-- Precompiled合约支持Gas
-- 支持EVM Gas衡量标准插件化配置
-- 添加新接口SendTransactionAndGetProof推送交易和交易回执证明
+- 支持动态群组生命周期管理: 相关的RPC接口包括[generateGroup](../api.html#generategroup)、[startGroup](../api.html#startgroup)、[stopGroup](../api.html#stopgroup)、[removeGroup](../api.html#removegroup)、[recoverGroup](../api.html#recovergroup)、[queryGroupStatus](../api.html#querygroupstatus)
+- 支持[网络流量和Gas统计](../design/features/stat.md)
+- [Precompiled合约支持Gas](../design/virtual_machine/gas.html#precompiledgas)
+- [支持EVM Gas衡量标准插件化配置](../design/virtual_machine/gas.html#evm-gas)
+- 添加新接口[SendTransactionAndGetProof](../api.html#sendrawtransactionandgetproof)推送交易和交易回执证明
 
 
 **更新**

docs/design/features/index.rst

@@ -38,3 +38,4 @@ FISCO BCOS引入的合约命名服务CNS通过提供链上合约名称与合约
    storage_security.md
    network_compress.md
    contract_management.md
+   stat.md

docs/design/features/stat.md

@@ -0,0 +1,153 @@
+# 网络流量和Gas统计
+
+FISCO BCOS 2.0引入了多群组架构，允许一个节点启动若干个群组，这种架构可快速平行扩展、简化了运维复杂度、降低了管理成本，但由于一个节点进程运行了多个群组，增加了群组监控复杂度。考虑到实时监控系统资源使用情况在实际生产系统中非常重要，FISCO BCOS v2.4.0引入了统计日志，并实现了群组级别的网络流量统计以及交易级别的Gas消耗统计功能。
+
+## 模块架构
+
+下图网络流量和Gas统计的模块图，FISCO BCOS节点实时统计群组内网络、Gas消耗信息，并将其输出到统计日志中：
+
+![](../../../images/stat/network_gas_stat.png)
+
+网络流量统计信息定期输出到统计日志中，目前统计的网络流量主要包括：
+
+- SDK到节点的网络流量：统计每个群组RPC流量、交易推送流量以及事件推送流量
+
+- P2P网络流量：统计群组间因同步、共识等模块进行P2P网络交互产生的网络流量
+
+- 网络总流量：每个群组网络消耗总流量，包括SDK到节点的网络流量和P2P网络流量
+
+
+Gas统计输出通过区块落盘触发，每落盘一个区块会将对应的Gas消耗信息输出到统计日志中，目前统计的信息包括：
+
+- 每个区块Gas消耗信息
+
+- 每笔交易Gas消耗信息
+
+
+## 统计日志详细说明
+
+```eval_rst
+.. note::
+    - 统计日志的级别是info
+    - 统计日志每一小时分割一次
+```
+
+### 网络流量统计日志
+
+为了方便开发者根据网络流量统计日志对系统进行诊断，FISCO BCOS v2.4.0统计网络流量时，根据流量的相关模块做了细分。这里详细介绍网络流量统计日志的格式和关键字含义。
+
+```eval_rst
+.. note::
+    - 输出到日志里的网络流量单位是字节Byte
+    - 网络统计功能仅统计某个时间段的网络消耗总流量，统计信息输出到日志后，计数器会清零，重新开始下一轮统计
+```
+
+#### SDK到节点的网络流量
+
+SDK到节点的网络流量统计日志记录的模块关键字是`SDK`，不仅统计了每个群组与SDK之间的总的出流量和入流量，还细分了RPC请求产生的流量、事件推送流量以及交易推送流量。日志示例如下：
+
+```bash
+info|2020-04-24 12:58:41.173045|SDK|,g=1,SDK_RPCIn=10023,SDK_EventLogIn=500,SDK_totalIn=10523,SDK_RPC_Out=0,SDK_Txs_Out=0,SDK_EventLog_Out=0,SDK_total_Out=0
+```
+**关键字说明**
+
+日志关键字 | 说明
+-|-
+g | 群组ID
+SDK_RPCIn | RPC请求入流量 |
+SDK_EventLogIn | 事件推送相关的入流量 |
+SDK_totalIn | 群组的总的入流量 |
+SDK_RPC_Out | RPC请求出流量 |
+SDK_Txs_Out | 交易推送产生的出流量 |
+SDK_EventLog_Out | 事件推送产生的出流量 |
+SDK_total_Out |群组的总出流量 |
+
+#### P2P网络流量
+
+群组间P2P流量统计日志记录的模块关键字是`P2P`，不仅统计了每个群组总的P2P出流量和入流量，还细分了共识流量、同步流量，日志示例如下：
+
+```bash
+info|2020-04-24 12:58:41.173077|P2P|,g=2,P2P_CONSIn=80505,P2P_SYNCIn=19008,P2P_totalIn=99513,P2P_CONS_Out=211377,P2P_SYNC_Out=19008,P2P_total_Out=230385  
+```
+
+**关键字说明**
+
+日志关键字 | 说明
+-|-
+g | 群组ID
+P2P_CONSIn | 因共识模块调度产生的入流量 |
+P2P_SYNCIn | 因同步模块调度产生的入流量 |
+P2P_totalIn | 群组总的P2P入流量 |
+P2P_CONS_Out | 因共识模块调度产生的出流量 |
+P2P_SYNC_Out | 因同步模块调度产生的出流量 |
+P2P_total_Out | 群组总的P2P出流量 |
+
+
+#### 群组总流量
+
+为方便业务方对区块链系统的整体带宽消耗有所了解，网络流量统计模块还统计了每个群组的总出流量和入流量，模块关键字是`Total`，日志示例如下：
+
+```bash
+info|2020-04-24 12:58:41.173052|Total|,g=1,Total_In=74524,Total_Out=115434 
+```
+
+**关键字说明**
+
+日志关键字 | 说明
+-|-
+g | 群组ID
+Total_In | 群组总的入流量 |
+Total_Out | 群组总的出流量 |
+
+
+### Gas消耗统计日志
+
+交易的Gas消耗衡量了交易消耗的物理资源，为了方便业务方监测交易资源消耗情况，FISCO BCOS v2.4.0统计了每个区块、每笔交易的Gas消耗情况。
+
+#### 每个区块Gas消耗信息
+
+区块Gas消耗的统计日志记录模块关键字是`BlockGasUsed`，统计信息包括：区块高度、区块所属群组、区块内交易数目、区块gas消耗等，日志示例如下：
+
+```bash
+info|2020-04-24 12:46:31.974147|BlockGasUsed|,g=2,txNum=193,gasUsed=3860579,blockNumber=1419,sealerIdx=2,blockHash=b10bdcc5da9c9cd5399ca5821bed9ae6f3fecbe1ddf8ec723b44e6fa30c4bd05,nodeID=0e23d6e237cfc5041d1754fa6682d71bef842b29ddfe3412b284aeac4b8b4794a51df409b667829750c2b4e91bdf95f51742e001e44dc9f97123a5002e49b8ca
+```
+
+**关键字说明**
+
+日志关键字 | 说明
+-|-
+g | 群组ID
+txNum | 区块内交易数目 |
+gasUsed | 区块内所有交易Gas消耗的总和 |
+blockNumber | 区块高度 |
+sealerIdx | 产生该区块的共识节点索引 |
+blockHash | 区块哈希 |
+nodeID | 节点Node ID|
+
+#### 每笔交易Gas消耗信息
+
+每笔交易Gas消耗的统计日志记录模块关键字是`TxsGasUsed`，主要统计了每笔交易的Gas消耗，日志示例如下：
+
+```bash
+info|2020-04-24 12:46:31.976080|TxsGasUsed|,g=2,txHash=a81ae1f60289cf7e8f6987b20c68ba9580a1c34d9252c5b4b9c097113309b9d7,gasUsed=20003
+```
+
+**关键字说明**
+
+日志关键字 | 说明
+-|-
+g | 群组ID
+txHash | 交易哈希 |
+gasUsed | 交易消耗的Gas |
+
+
+## 配置选项
+
+```eval_rst
+.. note::
+    统计日志配置选项位于 ``config.ini`` 中，详细可参考 `这里 <../../manual/configuration.html#id8>`_ 
+```
+
+
+
+

docs/design/virtual_machine/gas.md

@@ -0,0 +1,153 @@
+# Gas
+
+EVM虚拟机有一整套Gas机制来衡量每笔交易上链消耗的CPU、内存和存储资源。FISCO BCOS 2.0引入了Precompiled合约，支持内置的C++合约，为了提升Precompiled合约的安全性，FISCO BCOS v2.4.0在Precompiled合约中引入了Gas机制。
+
+此外，EVM原始的Gas机制中，交易的主要Gas消耗来源于存储，考虑到联盟链场景更关注CPU和内存消耗，FISCO BCOS v2.4.0调整了存储Gas，引入`Free Storage` Gas衡量模式，提升CPU和内存在交易Gas消耗中的占比。
+
+
+## Precompiled合约支持Gas计算
+
+```eval_rst
+.. note::
+    Precompiled合约支持Gas计算的特性从v2.4.0开始支持，当 ``supported_version`` 小于v2.4.0，或者旧链直接替换二进制升级时，不支持该特性
+```
+
+### 模块架构
+
+FISCO BCOS v2.4.0新增了`PrecompiledGas`模块进行Gas计算，Gas开销主要包括CPU、内存和存储三个维度，模块图如下：
+
+![](../../../images/evm/precompiled_gas.png)
+
+`PrecompiledGas`主要记录了每个交易执行Precompiled合约过程中调用的基础操作、占用内存消耗的Gas，交易调用Precompiled合约时Gas计算机制如下：
+
+- 虚拟机执行交易调用`Precompiled`合约的`call`接口时，每调用一个基础操作，会将其对应的`OPCode`添加到`PrecompiledGas`的**运行时指令集合**中
+
+- 虚拟机执行交易调用`Precompiled`合约的`call`接口时，基础操作占用的内存变化时，会更新`PrecompiledGas`的运行时消耗的内存
+
+- `Precompiled`合约执行完毕后，可调用接口，根据运行`Precompiled`合约过程中执行的指令集合、消耗的内存，计算出该`Precompiled`合约Gas消耗。
+
+
+### Precompiled合约Gas衡量标准
+
+FISCO BCOS Precompiled合约Gas衡量标准参考了EVM，主要包括CPU、内存和存储三个维度。下面详细介绍Precompiled合约具体的Gas计算方法。
+
+#### Precompiled合约内存Gas计算
+
+Precompiled合约内存消耗主要来自于输入、输出以及运行时产生的额外内存消耗。某笔交易消耗的总内存为`txMemUsed`时，其对应的内存Gas计算公式如下。即：每32字节增加`memoryGasUnit`个Gas，`memoryGasUnit`的值为3.
+
+```
+    MemoryGas(txMemUsed) = memoryGasUnit * txMemUsed / 32 + (txMemUsed * txMemUsed)/512
+```
+
+#### Precompiled合约CPU、存储Gas计算
+
+为了计算Precompiled合约基础操作消耗的Gas，FISCO BCOS v2.4.0将Precompiled合约映射到具体的操作码，并定义了每个基础操作对应的Gas。
+
+##### Precompiled合约基础操作对应的操作码
+
+`PrecompiledGas`模块将Precompiled合约基础操作映射到了操作码如下：
+
+操作 | 说明 |  操作码  
+-|-|-
+EQ | ConditionPrecompiled的EQ调用，判断两个操作数是否相等 | 0x00 |
+GE | ConditionPrecompiled的GE调用，判读左值是否大于等于右值 | 0x01 |
+GT | ConditionPrecompiled的GT调用，判断左值是否大于右值 | 0x02 |
+LE | ConditionPrecompiled的LE调用，判断左值是否小于等于右值 | 0x03 |
+LT | ConditionPrecompiled的LT调用，判断左值是否小于右值 | 0x04 |
+NE | ConditionPrecompiled的NE调用，判断左值是否不等于右值 | 0x05 |
+Limit | ConditionPrecompiled的Limit调用，限制从CRUD接口中查询出来的数据条数 | 0x06 |
+GetInt | EntryPrecompiled的getInt调用，将字符串转换成int256/uint256返回 | 0x07 |
+GetAddr | EntryPrecompiled的getAddress调用，将字符串转换成Address | 0x08 |
+Set | EntryPrecompiled的set调用，设置指定Key的值为指定的Value | 0x09 |
+GetByte32 | EntryPrecompiled的getByte32，将字符串转换为byte 32| 0x0a |
+GetByte64 | EntryPrecompiled的getByte64，将字符串转换为byte 64 | 0x0b |
+GetString | EntryPrecompiled的getString，获取输入的Key对应的值Value | 0x0c |
+CreateTable | TableFactoryPrecompiled的createTable调用，创建表 | 0x0d |
+OpenTable | TableFactoryPrecompiled的openTable调用，打开表 | 0x0e |
+Select | TablePrecompiled的select调用，查询表 | 0x0f |
+Insert | TablePrecompiled的insert调用，向表中插入指定记录 | 0x10 |
+Update | TablePrecompiled的update调用，更新指定表中的指定记录 | 0x11 |
+Remove | TablePrecompiled的remove调用，删除指定表中的指定记录 | 0x12 |
+PaillierAdd | 同态加接口 | 0x13 |
+GroupSigVerify | 群签名验证接口 | 0x14 |
+RingSigVerify | 环签名验证接口 | 0x15 |
+
+
+##### Precompiled合约基础操作衡量标准
+
+`PrecompiledGas`定义了Precompiled合约每个基础操作对应的Gas消耗，具体如下：
+
+操作 | Gas消耗
+-|-
+EQ | 3 |
+GE | 3 |
+GT | 3 |
+LE | 3 |
+LT | 3 |
+NE | 3 |
+Limit | 3 |
+GetInt | 3 |
+GetAddr | 3 |
+Set | 3 |
+GetByte32 | 3 |
+GetByte64 | 3 |
+GetString | 3 |
+CreateTable | 16000 |
+OpenTable | 200 |
+Select | 200 |
+Insert | 10000 |
+Update | 10000 |
+Remove | 2500 |
+PaillierAdd | 20000 |
+GroupSigVerify | 20000 |
+RingSigVerify | 20000 |
+
+
+## EVM Gas衡量标准插件化
+
+如前面所述，针对部分场景衡量交易资源耗用时，更加关注CPU和Gas，FISCO BCOS v2.4.0引入了`Free Storage`的Gas衡量模式，提升CPU和内存在交易Gas消耗中的占比。
+
+
+```eval_rst
+.. note::
+    EVM Gas衡量标准支持插件化配置的特性从v2.4.0开始支持，当 ``supported_version`` 小于v2.4.0，或者旧链直接替换二进制升级时，不支持该特性
+```
+
+### 模块架构
+
+为了支持Gas衡量标准插件化配置和FreeStorage的Gas衡量模式，FISCO BCOS v2.4.0在以太坊EVMSchedule引入`FreeStorageEVMSchedule`，在PrecopmiledGas的GasMetrics基础上引入了`FreeStorageGasMetrics`，并根据`genesis`文件的`enable_free_storage`配置项决定启用哪种Gas衡量模式，如下图所示：
+
+![](../../../images/evm/free_storage.png)
+
+为了提升CPU和内存在交易Gas消耗中的占比，`FreeStorageEVMSchedule`调整了创建合约、`SSTORE`、`SLOAD`等操作的Gas消耗；`FreeStorageGasMetrics`主要调整了`CreateTable`、`Insert`、`Remove`、`Update`等操作的Gas消耗。
+
+### Gas衡量标准
+
+下面分别介绍非`FreeStorage`模式和`FreeStorage`模式下，EVM虚拟机和Precompiled合约Gas衡量标准：
+
+**EVM虚拟机Gas衡量标准**
+
+
+Gas | 说明 | EVMSchedule模式下Gas消耗 | FreeStorageEVMSchedule模式下Gas消耗
+-|- | - | - 
+CreateGas | 创建合约的Gas消耗  | 32000 | 16000 |
+sloadGas| 从存储读取32字节数据消耗的Gas  | 200 |  1200|
+sstoreSetGas| 添加32字节数据到存储的Gas消耗 | 20000 | 1200 |
+sstoreResetGas| 更新32字节存储数据的Gas消耗 |5000 | 1200 |
+
+ **Precompiled合约Gas衡量标准**
+
+
+Gas | 说明| GasMetrics模式下Gas消耗 | FreeStorageGasMetrics模式下Gas消耗
+-|- | - | - 
+CreateTableGas| 创建表的Gas消耗 | 16000 | 500 | 
+StoreGas| 向表中插入数据或更新表中数据的Gas消耗 | 10000 | 200 | 
+RemoveGas| 删除表中数据的Gas消耗 | 2500 | 200 | 
+
+
+### 配置项
+
+```eval_rst
+.. note::
+    EVM Gas衡量标准支持插件化配置项位于 ``genesis`` 文件中，详细可参考 `这里 <../../manual/configuration.html#evm>`_ 
+```

docs/design/virtual_machine/index.rst

@@ -22,6 +22,7 @@ EVMC (Ethereum Client-VM Connector API)，是以太坊抽象出来的执行器
 
    evm.md
    precompiled.md
+   gas.md
 
 .. _Executor: ./evm.html
 

docs/manual/build_chain.md

@@ -155,6 +155,10 @@ $ bash build_chain.sh -l 127.0.0.1:2 -C 2
 ### **`D`选项[**Optional**]**
 无参数选项，设置该选项时，生成节点的目录名为IP_P2P端口，默认为节点从0开始的编号。
 
+### **`E`选项[**Optional**]**
+
+无参数选项，设置该选项时，启用[Free Storage](design/virtual_machine/gas.html#evm-gas) Gas模式，默认关闭`Free Storage` Gas模式
+
 ## 节点文件组织结构
 
 - cert文件夹下存放链的根证书和机构证书。