<doc>(develop): add contract life cycle doc, add console commands. (#1584)

* <doc>(console): add console commands.

* <doc>(develop): add contract life cycle doc.

Author: kyonRay

3.x/zh_CN/docs/develop/console/console_commands.md

@@ -170,7 +170,7 @@ quit
 
 **新增Liquid部署方式**：当连接节点在配置开启 “is_wasm=true”选项时，可自动启动控制台使用，具体配置项请参考：[节点配置](../../tutorial/air/config.md)
 
-Solidity部署参数：
+**Solidity部署参数：**
 
 - 合约路径：合约文件的路径，支持相对路径、绝对路径和默认路径三种方式。用户输入为文件名时，从默认目录获取文件，默认目录为: `contracts/solidity`，比如：HelloWorld。
 - 开启静态分析：可选项，默认为关闭。若开启，则会开启静态分析并行字段冲突域，加速合约并行执行速度。静态分析需要耗时较久，请耐心等待一段时间。
@@ -213,6 +213,22 @@ contract address: /asset_test
 currentAccount: 0x52d8001791a646d7e0d63e164731b8b7509c8bda
 ```
 
+**deploy with BFS:**
+
+支持在部署合约时在BFS创建别名, 使用参数 `-l` 将HelloWorld部署后的地址link到/apps/hello/v1目录：
+
+```shell
+[group0]: /apps> deploy -l ./hello/v1 HelloWorld
+deploy contract with link, link path: /apps/hello/v1
+transaction hash: 0x1122b7933e3468d007eea4f49c7e5182083f59b739dc06e40ee621129fed04e8
+contract address: 0xcceef68c9b4811b32c75df284a1396c7c5509561
+currentAccount: 0x7c6bb210ac67412f38ff850330b2dcd294437498
+link path: /apps/hello/v1
+
+[group0]: /apps> ls ./hello/v1
+v1 -> cceef68c9b4811b32c75df284a1396c7c5509561
+```
+
 ### 2. call
 
 运行call，调用合约。
@@ -310,6 +326,27 @@ Event: {}
 
 ```
 
+**Call with BFS:**
+
+可以调用在BFS目录中创建的link文件，调用姿势和调用普通合约类似。
+
+```shell
+[group0]: /apps> call ./hello/v1 set "Hello, BFS."
+transaction hash: 0x0b39db7b23aebe78b50a5f45da0e94381a4f4495c7286ab3039f9a761a3cc655
+---------------------------------------------------------------------------------------------
+transaction status: 0
+description: transaction executed successfully
+---------------------------------------------------------------------------------------------
+Receipt message: Success
+Return message: Success
+Return value size:0
+Return types: ()
+Return values:()
+---------------------------------------------------------------------------------------------
+Event logs
+Event: {}
+```
+
 ### 3. getCode
 
 运行getCode，根据合约地址查询合约二进制代码。
@@ -329,6 +366,7 @@ Event: {}
 
 - 合约路径：合约文件的路径，支持相对路径、绝对路径和默认路径三种方式。用户输入为文件名时，从默认目录获取文件，默认目录为: `contracts/solidity`，比如：TableTest。
 - 合约名：(可选)合约名称，默认情况下使用合约文件名作为合约名参数
+- 合约地址：(可选)在部署后的合约地址，listAbi会向节点发起getAbi的请求
 
 ```shell
 [group0]: /apps> listAbi KVTableTest
@@ -346,6 +384,15 @@ Event list:
  update              |   0x49cc36b56a9320d20b2d9a1938a972c849191bceb97500bfd38fa8a590dac73a  |   update(string,int256,string)
  select              |   0x5b325d7821528d3b52d0cc7a83e1ecef0438f763796770201020ac8b8813ac0a  |   select(string)
  insert              |   0xe020d464e502c11b54a7e37e568c78f0fcd360213eb5f4ac0a25a17733fc19f7  |   insert(string,int256,string)
+
+# 使用地址参数
+[group0]: /apps> listAbi cceef68c9b4811b32c75df284a1396c7c5509561
+Method list:
+ name                |    constant  |    methodId    |    signature
+  --------------------------------------------------------------
+ set                 |    false     |    4ed3885e    |    set(string)
+ get                 |    true      |    6d4ce63c    |    get()
+
 ```
 
 ### 5. getDeployLog
@@ -1213,22 +1260,25 @@ latest -> 2b5dcbae97f9d9178e8b051b08c9fb4089bae71b
 [group0]: /apps> tree ..
 /
 ├─apps
-│ └─Hello
-│   └─latest
 ├─sys
+│ ├─account_manager
 │ ├─auth
 │ ├─bfs
+│ ├─cast_tools
 │ ├─consensus
 │ ├─crypto_tools
+│ ├─dag_test
+│ ├─discrete_zkp
+│ ├─group_sig
 │ ├─kv_storage
-│ ├─parallel_config
+│ ├─ring_sig
 │ ├─status
+│ ├─table_manager
 │ └─table_storage
 ├─tables
-│ └─person
 └─usr
 
-5 directory, 10 contracts.
+4 directory, 14 contracts.
 
 # 使用深度为1
 [group0]: /apps> tree .. 1
@@ -2220,7 +2270,37 @@ Against Voters:
 
 ```
 
+#### 2.15. freezeAccount/unfreezeAccount
+
+冻结、解冻账户，冻结的账户不可以发起任何**写**交易，可通过unfreezeAccount解冻。
+该命令只有治理委员才可以调用。
 
+```shell
+[group0]: /apps> call HelloWorld 0xc8ead4b26b2c6ac14c9fd90d9684c9bc2cc40085 set test
+transaction hash: 0x8844e61177f25cfafa9974525d6b8cb71f9ff2ec86cb40244018097bce8999bd
+---------------------------------------------------------------------------------------------
+transaction status: 22
+---------------------------------------------------------------------------------------------
+Receipt message: Account is frozen.
+Return message: Account is frozen.
+---------------------------------------------------------------------------------------------
+```
+
+#### 2.16. abolishAccount
+
+废止账户，废止的账户不可以发起任何**写**交易，且不可恢复。
+该命令只有治理委员才可以调用。
+
+```shell
+[group0]: /apps> call HelloWorld 0xc8ead4b26b2c6ac14c9fd90d9684c9bc2cc40085 set test
+transaction hash: 0xcf5a5ceda91ac198cf0cf363da8646095a8ca5f4a1b2e3fc090127f388944030
+---------------------------------------------------------------------------------------------
+transaction status: 23
+---------------------------------------------------------------------------------------------
+Receipt message: Account is abolished.
+Return message: Account is abolished.
+---------------------------------------------------------------------------------------------
+```
 
 ### 3. 合约管理员专用命令
 

3.x/zh_CN/docs/develop/console/index.md

@@ -2,7 +2,15 @@
 
 标签：``console`` ``控制台`` ``命令行交互工具``
 
-------------
+---------
+
+```eval_rst
+.. important::
+    - ``控制台`` 只支持FISCO BCOS 3.0+版本，基于 `Java SDK <../sdk/java_sdk/index.html>`_ 实现。
+    - 可通过命令 ``./start.sh --version`` 查看当前控制台版本
+```
+
+[控制台](https://github.com/FISCO-BCOS/console)是FISCO BCOS 3.0重要的交互式客户端工具，它通过[Java SDK](../sdk/java_sdk/index.md)与区块链节点建立连接，实现对区块链节点数据的读写访问请求。控制台拥有丰富的命令，包括查询区块链状态、管理区块链节点、部署并调用合约等。此外，控制台提供一个合约编译工具，用户可以方便快捷的将Solidity和webankblockchain-liquid合约文件编译后的WASM文件转换为Java合约文件。
 
 ```eval_rst
 .. important::

3.x/zh_CN/docs/develop/contract_life_cycle.md

@@ -0,0 +1,143 @@
+# 合约生命周期与权限管理
+
+标签：``合约管理`` ``合约生命周期`` ``部署合约`` ``调用合约`` ``冻结合约`` ``废止合约``
+
+----
+
+本文档描述合约从开发、部署、调用、升级、冻结再到废止的整个生命周期，以及在整个智能合约生命周期的参与角色与管理方法。
+
+```eval_rst
+.. important::
+   合约生命周期管理冻结、解冻、废止操作以及合约部署调用权限控制，均需要将开启区块链权限模式，详情请参考【权限治理使用指南】。
+```
+
+## 1. 智能合约开发
+
+FISCO BCOS平台支持Solidity、Liquid、Precompiled三种智能合约使用形式。
+
+- Solidity合约与以太坊相同，用Solidity语法实现，在FISCO BCOS 3.0+版本中，支持0.4.25～0.8.11版本的Solidity合约。
+- Liquid由微众银行区块链团队开发并完全开源，是一种嵌入式领域特定语言（ embedded Domain Specific Language，eDSL），能够用来编写运行于区块链底层平台FISCO BCOS的智能合约。
+- 预编译（Precompiled）合约使用C++开发，内置于FISCO BCOS平台，相比于Solidity合约具有更好的性能，其合约接口需要在编译时预先确定，适用于逻辑固定但需要共识的场景。
+
+**延伸阅读**
+
+[WeBASE合约IDE](https://webasedoc.readthedocs.io/zh_CN/latest/)
+[Solidity官方文档](https://solidity.readthedocs.io/en/latest/)
+[Remix在线IDE](https://remix.ethereum.org/)
+[Liquid官方文档](https://liquid-doc.readthedocs.io/zh_CN/latest/)
+[预编译合约使用文档](https://fisco-bcos-doc.readthedocs.io/zh_CN/latest/docs/develop/precompiled/index.html)
+
+## 2. 智能合约部署与调用
+
+用户完成智能合约的开发之后，将智能合约部署上链并发起调用交易。用户可通过[SDK](./sdk/index.md)将编译好的合约打包成交易发送到FISCO BCOS区块链节点上链。社区已提供高度包装的工具，用户可快速开箱使用：
+
+- 使用控制台： [控制台](./console/index.md)，控制台包装了Java SDK，提供命令行交互功能，供给开发者使用的节点查询与管理的工具。
+- 使用Java合约生成工具：[Java合约生成工具](./console/console_config.html#java)支持Solidity的自动编译并生成Java文件、支持指定wbc-liquid编译后的WASM文件以及ABI文件生成Java文件。
+
+**延伸阅读**
+
+[开发第一个Solidity区块链应用](../quick_start/solidity_application.md)
+[开发第一个Liquid区块链应用](../quick_start/wbc_liquid_application.md)
+[Gradle SpringBoot 应用示例](./sdk/java_sdk/spring_boot_starter.md)
+[Maven SpringBoot 应用示例](./sdk/java_sdk/spring_boot_crud.md)
+
+## 3. 智能合约数据存储
+
+智能合约在部署过后，底层存储结构就将会创建一张数据表，用于存储合约对应的opcode、ABI JSON字符串和state状态数据。其中：
+
+- opcode为只能合约在编译后生成的代码段，用于每次调用时加载到虚拟机中执行；
+- ABI JSON字符串是为了方便外部SDK调用，存储的接口文件，其中记载着智能合约各个接口的参数返回格式、各个接口的并行冲突域；
+- state状态数据存储的是智能合约在运行时的需要持久存储的数据，例如合约成员变量等。
+
+创建的表名为“目录+合约地址”，我们以地址 0x1234567890123456789012345678901234567890 为例，在存储的表名就为 “/apps/1234567890123456789012345678901234567890”，其中“/apps/”为BFS固定前缀，详情请参考[BFS设计文档](../design/contract_directory.md)。
+
+| Key   | Value          |
+|-------|----------------|
+| code  | 十六进制opcode |
+| abi   | ABI JSON字符串 |
+| state | ...            |
+
+## 4. 智能合约升级
+
+从本文第3节可以看出，每个智能合约部署上链都有独立地址，独立地址对应着存储中的独立的存储表。因此，智能合约升级也要将升级情况分为保留数据升级和不保留数据升级。
+
+- 保留旧合约数据升级的情况较为复杂，具体解决方案有以下几种：
+  - （推荐）用户在开发智能合约时就需要主动将合约分为 **逻辑合约** 和 **数据合约**，数据合约用于存储需要在链上存储的数据，开放数据读写接口供逻辑合约使用，逻辑合约在计算时调用数据合约的读写接口。当需要升级时，只需要升级逻辑合约，新的逻辑合约调用旧的数据合约接口，旧的逻辑合约不再使用。
+  - （推荐）相当于第一种方案的扩展，需要存储的数据都使用CRUD数据接口进行存储，CRUD的数据是通过节点共识并持久存储在链上的。详情请参考[使用CRUD预编译合约开发应用](./precompiled/use_crud_precompiled.md)，[使用KV存储预编译合约开发应用](./precompiled/use_kv_precompiled.md)
+  - 通过使用delegate call的代理合约主动调用逻辑合约，产生的状态数据均保存在代理合约中，逻辑合约保持接口不变的情况下可以升级。
+- 不保留数据升级的情况更加简单，用户将升级的合约重新部署，将会有新的地址。应用基于新地址的合约进行操作即可，也将使用新合约的数据，旧合约记录的数据将存在链上，需要应用主动避免新业务逻辑调用旧合约数据。
+
+## 5. 智能合约权限管理操作
+
+```eval_rst
+.. important::
+   合约生命周期管理冻结、解冻、废止操作以及合约部署调用权限控制，均需要将开启区块链权限模式，详情请参考【权限治理使用指南】。
+```
+
+在开启区块链权限模式之后，每次合约部署将在存储层创建合约存储数据表之外，会额外创建一张合约权限数据表，用于记录合约管理员地址、合约状态、合约接口ACL。默认情况下，合约的管理员地址就是发起部署合约操作的账户地址（如果存在合约创建合约，合约管理员地址为交易发起账户tx.origin）。
+
+![](../../images/develop/contract_auth.png)
+
+合约管理员可以通过AuthManagerPrecompiled的接口对合约进行操作，固定地址为0x1005。
+
+```solidity
+enum Status{
+    normal,
+    freeze,
+    abolish
+}
+abstract contract AuthManagerPrecompiled {
+    // 合约管理员读写，resetAdmin只允许治理委员会合约调用
+    function getAdmin(address path) public view virtual returns (address);
+    function resetAdmin(address path, address admin) public virtual returns (int256);
+    // 合约接口权限读写
+    function setMethodAuthType(address path, bytes4 func, uint8 authType) public virtual returns (int256);
+    function openMethodAuth(address path, bytes4 func, address account) public virtual returns (int256);
+    function closeMethodAuth(address path, bytes4 func, address account) public virtual returns (int256);
+    function checkMethodAuth(address path, bytes4 func, address account) public view virtual returns (bool);
+    function getMethodAuth(address path, bytes4 func) public view virtual returns (uint8,string[] memory,string[] memory);
+    // 合约状态读写
+    function setContractStatus(address _address, Status _status) public virtual returns(int);
+    function contractAvailable(address _address) public view virtual returns (bool);
+    
+    // 部署合约权限读写，写接口只允许治理委员会合约调用
+    function deployType() public view virtual returns (uint256);
+    function setDeployAuthType(uint8 _type) public virtual returns (int256);
+    function openDeployAuth(address account) public virtual returns (int256);
+    function closeDeployAuth(address account) public virtual returns (int256);
+    function hasDeployAuth(address account) public view virtual returns (bool);
+}
+```
+
+### 5. 1智能合约冻结、解冻、废止
+
+合约管理员可以对固定地址0x1005的预编译合约发起交易，对合约的状态进行读写。
+
+在执行合约状态的写操作时，将会确定交易发起人msg.sender是否为合约权限表记录的合约管理员，若不是则会拒绝。
+
+```eval_rst
+.. important::
+   兼容性说明：合约生命周期管理废止操作只能在节点版本3.2以上进行。
+```
+
+合约管理员也可以通过控制台对合约进行冻结等操作，详情请看：[冻结合约命令](./console/console_commands.html#freezecontract)、[解冻合约命令](./console/console_commands.html#unfreezecontract)
+
+### 5.2. 智能合约部署权限控制
+
+部署合约的权限控制将由治理委员会统一控制，治理委员会将以投票表决的形式控制部署权限。治理委员会对某个部署权限的提案通过后，将会主动调用固定地址0x1005预编译合约的部署权限写接口，这些写接口也限定只能治理委员会合约调用。
+
+部署权限记录在BFS目录/apps下，这代表着允许在/apps目录下的写权限。
+
+治理委员可以通过控制台进行部署合约权限控制等操作，详情请看 [设置部署权限类型提案](./console/console_commands.html#setdeployauthtypeproposal) 、[开启部署权限提案](./console/console_commands.html#opendeployauthproposal) 、[关闭部署权限提案](./console/console_commands.html#closedeployauthproposal)
+
+在检查部署权限时将会对交易发起地址tx.origin进行校验，若没有权限则会返回错误码 -5000。即，会对用户部署合约、用户通过合约部署合约都进行校验。
+
+### 5.3. 智能合约调用权限控制
+
+合约管理员可以对固定地址0x1005的预编译合约发起交易，对合约接口的访问ACL进行读写。
+
+在执行合约接口的访问ACL的写操作时，将会确定交易发起人msg.sender是否为合约权限表记录的合约管理员，若不是则会拒绝。
+
+合约管理员可以通过控制台对合约接口访问ACL的写操作等操作，详情请看：[合约管理员专用命令](./console/console_commands.html#setmethodauth)
+
+在检查合约调用权限时将会对交易发起地址tx.origin和消息发送者msg.sender进行校验，若没有权限则会返回错误码 -5000。即，会对用户调用合约、用户通过合约调用合约、合约调用合约都进行校验。

3.x/zh_CN/images/develop/contract_auth.png

@@ -262,8 +262,9 @@ FISCO BCOS 是一个稳定、高效、安全的区块链底层平台，经过多
    docs/develop/api.md
    docs/develop/precompiled/index.md
    docs/develop/account.md
-   docs/develop/stress_testing.md
    docs/develop/committee_usage.md
+   docs/develop/contract_life_cycle.md
+   docs/develop/stress_testing.md
    docs/develop/light_monitor.md