update go-sdk documentation (#899)

1. add chainGovernance interface and contractLifeCycle interface in api.md 2. add chainGovernance，contractLifeCycle，consensus，permission commands in console.md
FISCO-BCOS · Aug 11, 2020 · 6f82293 · 6f82293
1 parent eae8641
commit 6f82293
Show file tree

Hide file tree

Showing 12 changed files with 1,068 additions and 52 deletions.
diff --git a/docs/design/p2p/p2p.md b/docs/design/p2p/p2p.md
@@ -155,4 +155,245 @@ FISCO BCOS P2P模块提供高效、通用和安全的网络通信基础功能，
         区块链节点B->>区块链节点A: 返回节点状态
         区块链节点A->>区块链节点A: 更新节点B的状态和seq
 
-```
+```
+
+## AMOP 消息转发流程
+
+### 单播时序图
+
+```eval_rst
+.. mermaid::
+
+    sequenceDiagram
+        participant sdk [Subscriber]
+
+        participant 节点0
+        
+        participant 节点1
+        
+        participant sdk [Publisher]
+        
+        sdk [Subscriber]->>节点0: 订阅 topic1、类型：0x32
+        
+        节点0->>节点0: 更新 topic 列表
+        
+        节点1->>节点0: 请求 topic 列表
+        
+        节点0-->>节点1: 响应 topic 列表
+        
+        sdk [Publisher]->>节点1: 往 topic1 单播消息、类型：0x30
+        
+        节点1->>节点0: 节点转发消息
+
+        节点0->>sdk [Subscriber]: 节点转发消息
+
+        sdk [Subscriber]-->>节点0: 回包、类型：0x31
+
+        节点0-->>节点1: 节点转发消息
+
+        节点1-->>sdk [Publisher]:节点转发消息
+
+```
+
+```eval_rst
+.. note::
+
+    - 单播是指如果有多个 Subscriber 订阅同一个 topic，节点则随机选择一个 Subscriber 推送消息
+    - 消息发布者和消息订阅者需要选择同一个 topic
+    - Subscriber 接收到消息之后的回包是由 sdk 自动发送，不需要用户自己处理，该回包仅仅表示 Subscriber 成功收到消息
+    - 如果 Publisher 在推送消息之前，没有对应的订阅者，那么 Publisher 将会收到错误码 *100*，表示网络中没有可用节点
+
+```
+
+### 多播时序图
+
+```eval_rst
+.. mermaid::
+
+    sequenceDiagram
+        participant sdk [Subscriber0]
+        
+        participant sdk [Subscriber1]
+
+        participant 节点0
+        
+        participant 节点1
+        
+        participant 节点2
+        
+        participant sdk [Publisher]
+        
+        sdk [Subscriber0]->>节点0: 订阅 topic1、类型：0x32
+        
+        节点0->>节点0: 更新 topic 列表
+        
+        节点1->>节点0: 请求 topic 列表
+        
+        节点0-->>节点1: 响应 topic 列表
+        
+        节点2->>节点0: 请求 topic 列表
+        
+        节点0-->>节点2: 响应 topic 列表
+        
+        sdk [Subscriber1]->>节点1: 订阅 topic1、类型：0x32
+        
+        节点1->>节点1: 更新 topic 列表
+        
+        节点0->>节点1: 请求 topic 列表
+        
+        节点1-->>节点0: 响应 topic 列表
+        
+        节点2->>节点1: 请求 topic 列表
+        
+        节点1-->>节点2: 响应 topic 列表
+        
+        sdk [Publisher]->>节点2: 往 topic1 多播消息、类型：0x35
+        
+        节点2->>节点0: 节点转发消息
+
+        节点2->>节点1: 节点转发消息
+        
+        节点2-->>sdk [Publisher]: 回包、类型：0x31
+
+        节点0->>sdk [Subscriber0]: 节点转发消息
+
+        节点1->>sdk [Subscriber1]: 节点转发消息
+        
+```
+
+```eval_rst
+.. note::
+
+    - 多播是指如果有多个 Subscriber 订阅同一个 topic，节点则向所有的 Subscriber 推送消息
+    - 只要网络正常，即使没有 Subsciber 接收消息， Publisher 也可以收到节点消息推送成功的响应包
+
+```
+
+### 带身份验证的单播时序图
+
+```eval_rst
+.. mermaid::
+
+    sequenceDiagram
+        participant sdk [Publisher]
+
+        participant 节点0
+        
+        participant 节点1
+        
+        participant 节点2
+
+        participant sdk [Subscriber0]
+        
+        participant sdk [Subscriber1]
+        
+        sdk [Publisher]->>节点0: 订阅 hello、类型：0x32
+        
+        节点1->>节点0: 请求 topic 列表
+        
+        节点0-->>节点1: 响应 topic 列表
+        
+        节点2->>节点0: 请求 topic 列表
+        
+        节点0-->>节点2: 响应 topic 列表
+
+        sdk [Subscriber0]->>节点1: 订阅 world（非身份验证）、类型：0x32
+        
+        节点2 ->> 节点1: 请求 topic 列表
+        
+        节点1-->>节点2: 响应 topic 列表
+        
+        节点0->>节点1: 请求 topic 列表
+        
+        节点1-->>节点0: 响应 topic 列表
+        
+        sdk [Subscriber1]->>节点2: 订阅 hello、类型：0x32
+        
+        节点1 ->> 节点2: 请求 topic 列表
+        
+        节点2-->>节点1: 响应 topic 列表
+        
+        节点0->>节点2: 请求 topic 列表
+        
+        节点2-->>节点0: 响应 topic 列表
+
+        节点0->>节点0: !$VerifyChannel_!$TopicNeedVerify_hello_{uuid} topic 待验证
+
+        节点0->>sdk [Publisher]: 发送 topic 为 !$TopicNeedVerify_hello 的消息，类型：0x37
+        
+        sdk [Publisher]-->>节点0: 回包，类型：0x31
+        
+        sdk [Publisher]->>sdk [Publisher]: 生成随机数
+        
+        sdk [Publisher]->>节点0: 发送 topic 为<br> !$VerifyChannel_!$TopicNeedVerify_hello_{uuid} <br>的消息，类型：0x30
+        
+        节点0->>节点2: 节点转发消息
+        
+        节点2->>sdk [Subscriber1]: 节点转发消息
+        
+        sdk [Subscriber1]->>sdk [Subscriber1]: 使用私钥 S 对随机数进行签名
+        
+        sdk [Subscriber1]-->>节点2: 回包，包中 topic 为 !$VerifyChannel_!$TopicNeedVerify_hello、类型：0x31
+        
+        节点2-->>节点0: 节点转发消息
+        
+        节点0-->>sdk [Publisher]: 节点转发消息
+        
+        sdk [Publisher]->>sdk [Publisher]: 使用公钥 P 验证签名
+        
+        sdk [Publisher]->>节点0: 更新 topic  !$TopicNeedVerify_hello，类型：0x38
+        
+        节点0->>节点0: 更新状态
+        
+        sdk [Publisher]->>节点0: 单播、类型：0x30
+
+        节点0->>节点2: 节点转发消息
+        
+        节点2->>sdk [Subscriber1]: 节点转发消息
+
+        sdk [Subscriber1]-->>节点2: 回包、类型：0x31
+
+        节点2-->>节点0: 节点转发消息
+
+        节点0-->>sdk [Publisher]: 节点转发消息
+
+```
+
+```eval_rst
+.. note::
+
+    - 身份验证： Publisher 在推送消息的时候，只给满足身份条件的订阅者推送消息
+    - Publisher 拥有公钥 P，同时监听 #!\$TopicNeedVerify_hello 和 #!\$PushChannel_#!\$TopicNeedVerify_hello 两个 topic
+    - Subscriber1 拥有私钥 S，同时监听 #!\$TopicNeedVerify_hello 和#!\$VerifyChannel_#!\$TopicNeedVerify_hello_{uuid} 两个 topic
+    - 时序图中所有的 !$ 前都缺少符号 #， mermaid 不支持该符号转义
+    - 节点0 给 Publisher 发送的 0x37 消息包中除了 topic：#!\$TopicNeedVerify_hello，还有 topicForCert：#!\$VerifyChannel_#!\$TopicNeedVerify_hello_{uuid} 以及 NodeID
+    - Publisher 收到 0x37 消息后回包，包中使用的 topic 为：#!$VerifyChannel_#!$VerifyChannel_#!$TopicNeedVerify_hello_{uuid} 
+    - 身份验证通过之后，推送消息使用的 topic 为 !$TopicNeedVerify_hello 
+    - 带身份验证的多播在验证身份的流程上同带身份验证的单播一致。不同点在于身份验证通过之后，单播推送消息是一对一，而多播推送消息是一对多
+
+```
+
+**通信协议使用的数据结构**:
+- 0x37 消息类型中 content 数据结构：
+
+    ```json
+    {"nodeId":"2bb4562f4f4b69e2c5156510da4beddfca548403eb7cea49bd56daed46de31e4d78a44fdfa051170c64f0233dbc0fd75b5b4e8bc2df50a3c9ade833794128623","topic":"#!$TopicNeedVerify_hello","topicForCert":"#!$VerifyChannel_#!$TopicNeedVerify_hello_92be6ce4dbd311eaae5a983b8fda4e0e"}
+    ```
+
+- 随机数单播中的 content 数据结构：
+
+    ```json
+    {"randValue":"14131f50ef730219d48e1f9c441db871c","topic":"hello"}
+    ```
+
+- 随机数签名回包中 content 数据结构：
+
+    ```json
+    {"signature":"vU/Vzqn4MiP0nO1xN+M5TOk/YcyFtY/TLrgU38jFdooN66r3TzNVKEBpkNId8gCuAeNpNPCo8vmTV3dcs/Xj1AE="}
+    ```
+
+- 0x38 消息类型中 content 数据结构：
+
+    ```json
+    {"checkResult":0,"nodeId":"2bb4562f4f4b69e2c5156510da4beddfca548403eb7cea49bd56daed46de31e4d78a44fdfa051170c64f0233dbc0fd75b5b4e8bc2df50a3c9ade833794128623","topic":"#!$TopicNeedVerify_hello"}
+    ```
diff --git a/docs/sdk/go_sdk/amopExamples.md b/docs/sdk/go_sdk/amopExamples.md
@@ -0,0 +1,73 @@
+# AMOP 使用案例
+
+AMOP（Advanced Messages Onchain Protocol）即链上信使协议，旨在为联盟链提供一个安全高效的消息信道，联盟链中的各个机构，只要部署了区块链节点，无论是共识节点还是观察节点，均可使用AMOP进行通讯，AMOP有如下优势：
+
+-   实时：AMOP消息不依赖区块链交易和共识，消息在节点间实时传输，延时在毫秒级。
+-   可靠：AMOP消息传输时，自动寻找区块链网络中所有可行的链路进行通讯，只要收发双方至少有一个链路可用，消息就保证可达。
+-   高效：AMOP消息结构简洁、处理逻辑高效，仅需少量cpu占用，能充分利用网络带宽。
+-   安全：AMOP的所有通讯链路使用SSL加密，加密算法可配置,支持身份认证机制。
+-   易用：使用AMOP时，无需在SDK做任何额外配置。
+
+进一步了解 AMOP，请参考：[链上信使协议](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/amop_protocol.html)。案例源码，请参考：[go-sdk](https://github.com/FISCO-BCOS/go-sdk)
+
+**初始化**：
+
+-   搭建单群组四节点区块链网络，可参考：[安装](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/installation.html)。
+
+## 单播案例
+
+**单播** 指的是节点从监听相同 Topic 的多个订阅者中随机抽取一个订阅者转发消息，流程详细可参考 [单播时序图](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/design/p2p/p2p.html#id11)
+
+-   启动 AMOP 消息订阅者：
+
+    ```shell
+    # go run examples/amop/sub/subscriber.go [endpoint] [topic]
+    > go run examples/amop/sub/subscriber.go 127.0.0.1:20201 hello
+
+      Subscriber success
+      2020/08/11 21:21:50 received: hello, FISCO BCOS, I am unique broadcast publisher! 0
+      2020/08/11 21:21:52 received: hello, FISCO BCOS, I am unique broadcast publisher! 1
+      2020/08/11 21:21:54 received: hello, FISCO BCOS, I am unique broadcast publisher! 2
+      2020/08/11 21:21:56 received: hello, FISCO BCOS, I am unique broadcast publisher! 3
+    ```
+
+-   运行 AMOP 消息发布者：
+
+    ```shell
+    # go run examples/amop/unicast_pub/publisher.go [endpoint] [topic]
+    > go run examples/amop/unicast_pub/publisher.go 127.0.0.1:20200 hello
+
+      2020/08/11 21:21:50 publish message: hello, FISCO BCOS, I am unique broadcast publisher! 0 
+      2020/08/11 21:21:52 publish message: hello, FISCO BCOS, I am unique broadcast publisher! 1 
+      2020/08/11 21:21:54 publish message: hello, FISCO BCOS, I am unique broadcast publisher! 2 
+      2020/08/11 21:21:56 publish message: hello, FISCO BCOS, I am unique broadcast publisher! 3
+    ```
+
+## 多播案例
+
+**多播** 指的是节点向监听相同 Topic 的所有订阅者转发消息。只要网络正常，即使没有监听 Topic 的订阅者，消息发布者也会收到节点消息推送成功的响应包，流程详细可参考 [多播时序图](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/design/p2p/p2p.html#id12)
+
+-   启动 AMOP 消息订阅者：
+
+    ```shell
+    # go run examples/amop/sub/subscriber.go [endpoint] [topic]
+    > go run examples/amop/sub/subscriber.go 127.0.0.1:20201 hello
+
+      Subscriber success
+      2020/08/11 21:23:54 received: hello, FISCO BCOS, I am multi broadcast publisher! 0
+      2020/08/11 21:23:56 received: hello, FISCO BCOS, I am multi broadcast publisher! 1
+      2020/08/11 21:23:58 received: hello, FISCO BCOS, I am multi broadcast publisher! 2
+      2020/08/11 21:24:00 received: hello, FISCO BCOS, I am multi broadcast publisher! 3
+    ```
+
+-   运行 AMOP 消息发布者：
+
+    ```shell
+    # go run examples/amop/multicast_pub/publisher.go [endpoint] [topic]
+    > go run examples/amop/multicast_pub/publisher.go 127.0.0.1:20200 hello 
+
+      2020/08/11 21:23:54 publish message: hello, FISCO BCOS, I am multi broadcast publisher! 0 
+      2020/08/11 21:23:56 publish message: hello, FISCO BCOS, I am multi broadcast publisher! 1 
+      2020/08/11 21:23:58 publish message: hello, FISCO BCOS, I am multi broadcast publisher! 2 
+      2020/08/11 21:24:00 publish message: hello, FISCO BCOS, I am multi broadcast publisher! 3
+    ```