+
+#### 对于源码编译的改造
+
+说完了适配的整体思路，继续说一下关于编译环节的改造。
+
+首先说一下`fisco`在源码编译部分的处理。`fisco`是用`cmake`进行组织编译的，在源码的`cmake`文件夹中存放着需要拉取依赖的地址和操作方式，文件目录如下图所示
+
+
+
+其中我们可以发现一个叫`ProjectLibzdb.cmake`的文件，我们进去看一下
+
+
+
+这是修改后文件，其主要作用就是根据URL地址拉取第三方依赖包。由于我们对`libzdb`进行了自己的适配改造，所以我们将改造后的`libzdb`代码上传到了自己的仓库中，以便进行下载。
+
+所以我们对`cmake`文件也进行了修改
+
+### fisco-dm源码编译
+
+本章节将针对如何从源码编译出适配达梦的`fisco-bcos`程序。当然，我们在文末也提供了直接编译好的`fisco-bcos`程序，您可以跳过这一章节，直接使用编译好的程序也可以。
+
+#### 相关依赖
+
+`fisco-bcos`:2.9.1版本
+
+`达梦数据库`:DM8
+
+`达梦驱动包`:dmoci
+
+操作系统：centos7+，ubuntu20.04，麒麟osV10；支持ARM，不支持windows系统
+
+#### libzdb适配教程
+
+由于开发周期较短，所以`libzdb`适配达梦数据库的一键配置的脚本并没有完成，所以需要进行人工手动适配，过程略有繁琐。
+
+1. 首先请准备一台装有`mysql`的电脑/服务器，将l`ibzdb-dm`代码拉取到本地，代码仓库地址：https://github.com/dyy8888/LibzdbForDM.git 此仓库提供的就是改造好的`libzdb-dm`代码
+
+2. 在`libzdbForDM`文件夹中，执行自动检测脚本，这一步会自动检测所拥有的数据库
+
+ 
+
+ ```shell
+ ./configure
+ ```
+
+ 
+
+ 可以发现检测到了`Mysql`的环境，同时会生成`MakeFile`文件
+
+ 
+
+3. 编辑`MakeFile`文件，修改其中的配置信息。
+
+ 修改前：
+
+ 
+
+ 修改后：
+
+ 
+
+ 修改前：
+
+ 
+
+ 修改后：
+
+ 
+
+ 因为自动检测到的是`mysql`环境，所以需要注释掉`mysql`相关的信息，打开`oracle`相关的
+
+ 修改前：
+
+ 
+
+ 修改后：
+
+ 
+
+ 这两步的作用是将达梦给的`dmoci`的驱动和`DCI.h`的头文件导入`libzdb`项目中。驱动和头文件会在文末的百度网盘链接中给出。下图给出`dmoci`驱动包的文件结构。可以发现其中包含驱动`dmoci.a dmoci.so`和依赖的头文件`DCI.h DCI1.h oci.h`
+
+ 
+
+ 其中：`/root/dmoci/include`其中包含`DCI.h`头文件，此路径需根据实际情况进行修改
+
+ `dmoci`为驱动，需要将达梦提供的`oci`驱动包中的`libdmoci`文件复制到系统目录下，这个目录可以参考359行前面给出路径。比如此图片中，需要将`dmoci`复制到`/usr/lib64`中
+
+ 保存退出`MakeFile`文件
+
+4. 进入src文件夹，修改其中的xconfig.h文件
+
+ 
+
+ 
+
+ 修改前：
+
+ 
+
+ 修改后：
+
+ 
+
+ 这一步的目的是关闭`mysql`，打开`oracle`
+
+5. 返回与Makefile同级目录中，如下图所示，执行编译安装步骤
+
+ 
+
+ ```shell
+ make -j4
+ sudo make install
+ ```
+
+6. 安装成功后说明适配成功，执行清除指令
+
+ ```shell
+ sudo make clean
+ ```
+
+7. 将上述适配好的代码上传到个人的仓库中，这一步的目的是`fisco`在源码编译的时候需要根据依赖的地址去下载，所以请将此代码上传一个可以进行拉取下载的仓库中。同时可能会有疑问，为什么不直接拉取作者改造好的代码呢？这是因为我自己改造的代码相关配置路径是在执行`./configure`后根据我自己服务器的相关信息产生的。所以对于用户来说，肯定和我的服务器路径不相同，所以需要您手动拉取代码后进行配置。
+
+#### fisco适配
+
+##### **源码编译**
+
+修改后的fisco代码仓库位于：https://github.com/dyy8888/FISCO-BCOS-2.9.1.git
+
+请先拉取代码到本地。
+
+```shell
+#进入cmake目录下，修改ProjectLibzdb.cmake
+将下载地址设置为上一步中适配好的libzdb代码地址，也就是您自己上传的github仓库，其他仓库也可以，只要确保可以通过URL下载下来就行
+```
+
+
+
+```shell
+#返回上一级目录，新建文件夹build
+mkdir build
+#执行cmake指令
+cmake ..
+#如果是arm64架构，执行。x86不需要
+cmake -DARCH_NATIVE=on ..
+#进行编译
+make -j4
+```
+
+在编译过程中，会自动将依赖拉取到deps目录下
+
+
+
+```shell
+#需要手动复制rt和oci驱动至deps/libs文件夹中，如下图所示，其余的依赖会在编译中自动放入。这两个依赖，#libdmoci.a在网盘提供的包里有。librt.a请在您的系统目录下寻找。也可以使用命令查找
+whereis librt.a
+```
+
+
+
+最后，可在build/bin目录下得到`fisco-bcos`可执行程序
+
+### 具体使用教程
+
+文末的百度网盘包中提供了编译好的`fisco-bcos`可执行程序，如果您跳过了源码编译环节，您可以直接看本章节进行部署使用
+
+由于测试环境仅包含一台达梦实例，所以本教程将搭建三个`mysql`节点和一个达梦节点
+
+首先根据官网文档教程搭建本地四节点的`fisco-bcos`链
+
+```shell
+## 创建操作目录
+cd ~ && mkdir -p fisco && cd fisco
+
+## 下载脚本
+curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v2.9.1/build_chain.sh && chmod u+x build_chain.sh
+## 执行建链脚本
+bash build_chain.sh -l 127.0.0.1:4 -p 30300,20200,8545
+```
+
+可以得到以下的目录结构，其中包含着四个节点
+
+
+
+```shell
+## 返回主目录，新建文件夹fisco-DM
+cd ~ && mkdir -p fisco-DM
+## 复制刚才的fisco文件夹到fisco-DM中
+cp -r fisco fisco-DM/
+```
+
+
+
+```shell
+## 我们将node0设置为达梦节点，其他节点为mysql节点。
+## 所以删除fisco文件夹中的node0文件夹，删除fisco-DM中的node1,node2,node3文件夹
+## 处理完毕后的目录结构为
+```
+
+
+
+
+
+将`fisco-DM`文件夹中的`fisco-bcos`程序，换成达梦版本的程序（源码编译而来，或者直接使用链接包中的程序）
+
+修改达梦节点（node0）下，conf/group.1.ini
+
+
+
+
+
+目前仅支持SYSDBA的写入，请确保您的用户具备`DBA`的权限
+
+启动节点后，查询节点的运行日志，检查是否共识正常。同时可以登录达梦数据库的命令行，查询相关的表格信息。如下图所示：
+
+
+
+### 软件包链接
+
+链接：https://pan.baidu.com/s/13VLvYNdrdloMZFMjzWQsrQ?pwd=dm10
+提取码：dm10
+
+fisco-dm的PR链接为：https://github.com/FISCO-BCOS/FISCO-BCOS/pull/3969
+
+这里可以看到关于fisco-dm对于底层文件的改动情况
+
+如有更多问题，可联系我们：2497213126@qq.com
+
+可以进行指导部署安装达梦区块链节点
\ No newline at end of file
diff --git a/2.x/docs/articles/index.md b/2.x/docs/articles/index.md
index 94ba43a62..78aa1358c 100644
--- a/2.x/docs/articles/index.md
+++ b/2.x/docs/articles/index.md
@@ -2,7 +2,7 @@
## 介绍
-FISCO BCOS开源社区已沉淀120+篇技术文章，这些文章涉猎理论、开发以及应用案例等方面，有助于开发者快速上手、全面掌握FISCO BCOS，依据平台关键特性，社区对这些文章进行整理编排成《深入浅出FISCO BCOS》，供各位浏览阅读。
+新的一年已经开启，为了感谢大家的长久陪伴和倾力支持，我们将FISCO BCOS开源社区成立至今超400篇技术干货和经典篇章整理成文，作为区块链干货合辑，分享给大家! 请点击这里查阅[完整版](https://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247493260&idx=1&sn=b042be04819c89169b81bcee99eb2a18&chksm=9e3a71e6e1d2ad682bf8fde9f178c91160e5d7cdf187a81cedb191b8da1605f206f9bfd98ec0&from=industrynews&version=4.1.7.6018&platform=win#rd)
《深入浅出FISCO BCOS》分为六大章节，由社区全体成员共创完成并不断优化，社区开发者可以在GitHub上提交PR贡献文章，分享FISCO BCOS开发经验与使用心得。
diff --git a/2.x/docs/community.md b/2.x/docs/community.md
index da36c3cb0..dd619fec0 100644
--- a/2.x/docs/community.md
+++ b/2.x/docs/community.md
@@ -14,7 +14,7 @@ FISCO BCOS是国内企业主导研发、对外开源、安全可控的企业级
## 更多开源工具
-
+
- **FISCO BCOS企业级金融联盟链底层平台**: [GitHub](https://github.com/FISCO-BCOS/FISCO-BCOS/tree/master-2.0) 、[Gitee](https://gitee.com/FISCO-BCOS/FISCO-BCOS/tree/master-2.0) 、 [文档](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/index.html)
- **WeBASE 区块链中间件平台**：[GitHub](https://github.com/WeBankFinTech/WeBASE) 、 [Gitee](https://gitee.com/WeBank/WeBASE) 、 [文档](https://webasedoc.readthedocs.io/)
@@ -37,6 +37,8 @@ FISCO BCOS是国内企业主导研发、对外开源、安全可控的企业级
- SmartDev-Contract 智能合约库组件：[GitHub](https://github.com/WeBankBlockchain/SmartDev-Contract) 、 [Gitee](https://gitee.com/WeBankBlockchain/SmartDev-Contract) 、 [文档](https://smartdev-doc.readthedocs.io/zh_CN/latest/docs/WeBankBlockchain-SmartDev-Contract/index.html)
- SmartDev-SCGP 合约编译插件：[GitHub](https://github.com/WeBankBlockchain/SmartDev-SCGP) 、 [Gitee](https://gitee.com/WeBankBlockchain/SmartDev-SCGP) 、 [文档](https://smartdev-doc.readthedocs.io/zh_CN/latest/docs/WeBankBlockchain-SmartDev-SCGP/index.html)
- SmartDev-Scaffold 应用开发脚手架：[GitHub](https://github.com/WeBankBlockchain/SmartDev-Scaffold) 、 [Gitee](https://gitee.com/WeBankBlockchain/SmartDev-Scaffold) 、 [文档](https://smartdev-doc.readthedocs.io/zh_CN/latest/docs/WeBankBlockchain-SmartDev-Scaffold/index.html)
+- **DDCMS分布式数据协作管理解决方案**：[GitHub](https://github.com/WeBankBlockchain/DDCMS) 、 [Gitee](https://gitee.com/WeBankBlockchain/DDCMS) 、 [文档](https://ddcms-docs.readthedocs.io/en/latest/)
+
## 加入FISCO BCOS社区
diff --git a/2.x/docs/community/MVP_list_new.md b/2.x/docs/community/MVP_list_new.md
index e83bb69fd..4ff6148cc 100644
--- a/2.x/docs/community/MVP_list_new.md
+++ b/2.x/docs/community/MVP_list_new.md
@@ -1,38 +1,21 @@
## MVP
-**2021年度 | FISCO BCOS MVP榜单**
+**2023年度 | FISCO BCOS MVP榜单**
作者：小助手
-在《大教堂与集市》一书中，开源世界好比集市，相较传统开发模式更重视开发者间的交流，每位开源社区的参与者、贡献者都是集市中的主角。
-
-FISCO BCOS开源社区“集市”历经四载共建，逐渐发展壮大，孕育出超7万个人用户、逾3000企业/机构的活跃开源生态。
-
-大家围绕FISCO BCOS开发各类实用的应用组件、持续优化项目，并自发输出技术解析、使用案例、操作实践等丰富内容。点滴的分享让FISCO BCOS的开发体验越来越丝滑友好，也让我们看到区块链的无限可能。
-
-今年3月，社区开放FISCO BCOS MVP认定以鼓励为开源社区贡献高质量技术内容的意见先锋与意见领袖。6月，社区认定了首批共10位MVP，而下半年，我们也迎来了新一批16位MVP。
+为了鼓励为开源社区贡献高质量技术内容的意见先锋与意见领袖，开源社区开放FISCO BCOS MVP认定，截止2023年，开源社区共认定63位MVP 。
这些优秀的贡献者或是将FISCO BCOS技术落地到各领域应用中，助力产业数字化，或是在多渠道布道，将开源社区精神传播到更远的地方。
下面，让我们一起来认识这些技术的践行者、社区的布道者。
-**2021年首批MVP**
-
-
-
-
-**2021年第二批MVP**
-
-
-
-**推荐阅读**:
-
-[FISCO BCOS MVP计划](https://mp.weixin.qq.com/s/cqwrzBnQaSd9-jVMrE6_WQ)
-
-[对话MVP | 谷月：结缘FISCO BCOS，成为区块链浪潮中的弄潮儿](https://mp.weixin.qq.com/s/4pufWZVsW7-fdAMsYggDyg)
+
++
+
+ + + ############################################################## -FISCO BCOS 技术文档 +FISCO BCOS 2.0 技术文档 ############################################################## -.. image:: _static/images/FISCO_BCOS_Logo.svg - FISCO BCOS 是一个稳定、高效、安全的区块链底层平台，经过多家机构、多个应用，长时间在生产环境运行的实际检验。 .. note:: @@ -230,7 +266,7 @@ FISCO BCOS 是一个稳定、高效、安全的区块链底层平台，经过多
-
+ 
.. container:: tools
@@ -258,6 +294,7 @@ FISCO BCOS 是一个稳定、高效、安全的区块链底层平台，经过多
- SmartDev-Contract 智能合约库组件：`[GitHub] -
+
2. Emergency Stop
3. Speed Bump
4. Rate Limit
5. Mutex
6. Balance Limit | +| Maintenance | 7. Data Segregation
8. Satellite
9. Contract Register
10. Contract Relay | +| Lifecycle | 11. Mortal
12. Automatic Deprecation | +| Authorization | 13. Ownership
14. Access Restriction | +| Action And Control | 15. Pull Payment
16. Commit And Reveal
17. State Machine
18. Oracle | + +接下来，本文将从这18种设计模式中选择最为通用常见的进行介绍，这些设计模式在实际开发经历中得到了大量检验。 + +## 安全性(Security) + +智能合约编写，首要考虑的就是安全性问题。在区块链世界中，恶意代码数不胜数。如果你的合约包含了跨合约调用，就要特别当心，要确认外部调用是否可信，尤其当其逻辑不为你所掌控的时候。如果缺乏防人之心，那些“居心叵测”的外部代码就可能将你的合约破坏殆尽。比如，外部调用可通过恶意回调，使代码被反复执行，从而破坏合约状态，这种攻击手法就是著名的Reentrance Attack（重入攻击）。这里，先引入一个重入攻击的小实验，以便让读者了解为什么外部调用可能导致合约被破坏，同时帮助更好地理解即将介绍的两种提升合约安全性的设计模式。 + +关于重入攻击，这里举个精简的例子。AddService合约是一个简单的计数器，每个外部合约可以调用AddService合约的addByOne来将字段_count加一，同时通过require来强制要求每个外部合约最多只能调用一次该函数。这样，_count字段就精确的反应出AddService被多少合约调用过。在addByOne函数的末尾，AddService会调用外部合约的回调函数notify。AddService的代码如下： + +``` +contract AddService{ + + uint private _count; + mapping(address=>bool) private _adders; + + function addByOne() public { + //强制要求每个地址只能调用一次 + require(_adders[msg.sender] == false, "You have added already"); + //计数 + _count++; + //调用账户的回调函数 + AdderInterface adder = AdderInterface(msg.sender); + adder.notify(); + //将地址加入已调用集合 + _adders[msg.sender] = true; + } +} + +contract AdderInterface{ + function notify() public; +} +``` + +如果AddService如此部署，恶意攻击者可以轻易控制AddService中的_count数目，使该计数器完全失效。攻击者只需要部署一个合约BadAdder，就可通过它来调用AddService，就可以达到攻击效果。BadAdder合约如下： + +``` + +contract BadAdder is AdderInterface{ + + AddService private _addService = //...; + uint private _calls; + + //回调 + function notify() public{ + if(_calls > 5){ + return; + } + _calls++; + //Attention !!!!!! + _addService.addByOne(); + } + + function doAdd() public{ + _addService.addByOne(); + } +} +``` + +BadAdder在回调函数notify中，反过来继续调用AddService，由于AddService糟糕的代码设计，require条件检测语句被轻松绕过，攻击者可以直击_count字段，使其被任意地重复添加。攻击过程的时序图如下： + + + +在这个例子中，AddService难以获知调用者的回调逻辑，但依然轻信了这个外部调用，而攻击者利用了AddService糟糕的代码编排，导致悲剧的发生。本例子中去除了实际的业务意义，攻击后果仅仅是_count值失真。真正的重入攻击，可对业务造成严重后果。比如在统计投票数目是，投票数会被改得面目全非。打铁还需自身硬，如果想屏蔽这类攻击，合约需要遵循良好的编码模式，下面将介绍两个可有效解除此类攻击的设计模式。 + +### Checks-Effects-Interaction - 保证状态完整，再做外部调用 + +该模式是编码风格约束，可有效避免重放攻击。通常情况下，一个函数可能包含三个部分： + +- Checks：参数验证 +- Effects：修改合约状态 +- Interaction：外部交互 + +这个模式要求合约按照Checks-Effects-Interaction的顺序来组织代码。它的好处在于进行外部调用之前，Checks-Effects已完成合约自身状态所有相关工作，使得状态完整、逻辑自洽，这样外部调用就无法利用不完整的状态进行攻击了。回顾前文的AddService合约，并没有遵循这个规则，在自身状态没有更新完的情况下去调用了外部代码，外部代码自然可以横插一刀，让_adders[msg.sender]=true永久不被调用，从而使require语句失效。我们以checks-effects-interaction的角度审阅原来的代码： + +``` + //Checks + require(_adders[msg.sender] == false, "You have added already"); + //Effects + _count++; + //Interaction + AdderInterface adder = AdderInterface(msg.sender); + adder.notify(); + //Effects + _adders[msg.sender] = true; +``` + +只要稍微调整顺序，满足Checks-Effects-Interaction模式，悲剧就得以避免： + +``` + //Checks + require(_adders[msg.sender] == false, "You have added already"); + //Effects + _count++; + _adders[msg.sender] = true; + //Interaction + AdderInterface adder = AdderInterface(msg.sender); + adder.notify(); +``` + +由于_adders映射已经修改完毕，当恶意攻击者想递归地调用addByOne，require这道防线就会起到作用，将恶意调用拦截在外。虽然该模式并非解决重入攻击的唯一方式，但依然推荐开发者遵循。 + +### Mutex - 禁止递归 + +Mutex模式也是解决重入攻击的有效方式。它通过提供一个简单的修饰符来防止函数被递归调用： + +``` +contract Mutex { + bool locked; + modifier noReentrancy() { + //防止递归 + require(!locked, "Reentrancy detected"); + locked = true; + _; + locked = false; + } + + //调用该函数将会抛出Reentrancy detected错误 + function some() public noReentrancy{ + some(); + } +} +``` + +在这个例子中，调用some函数前会先运行noReentrancy修饰符，将locked变量赋值为true。如果此时又递归地调用了some，修饰符的逻辑会再次激活，由于此时的locked属性已为true，修饰符的第一行代码会抛出错误。 + +## **可维护性（Maintenance）** + +在区块链中，合约一旦部署，就无法更改。当合约出现了bug，通常要面对以下问题： + +1. 合约上已有的业务数据怎么处理？ +2. 怎么尽可能减少升级影响范围，让其余功能不受影响？ +3. 依赖它的其他合约该怎么办？ + +回顾面向对象编程，其核心思想是将变化的事物和不变的事物相分离，以阻隔变化在系统中的传播。所以，设计良好的代码通常都组织得高度模块化、高内聚低耦合。利用这个经典的思想可解决上面的问题。 + +### Data segregation - 数据与逻辑相分离 + +了解该设计模式之前，先看看下面这个合约代码： + +``` +contract Computer{ + + uint private _data; + + function setData(uint data) public { + _data = data; + } + + function compute() public view returns(uint){ + return _data * 10; + } +} +``` + +此合约包含两个能力，一个是存储数据(setData函数)，另一个是运用数据进行计算(compute函数）。如果合约部署一段时间后，发现compute写错了，比如不应是乘以10，而要乘以20，就会引出前文如何升级合约的问题。这时，可以部署一个新合约，并尝试将已有数据迁移到新的合约上，但这是一个很重的操作，一方面要编写迁移工具的代码，另一方面原先的数据完全作废，空占着宝贵的节点存储资源。 + +所以，预先在编程时进行模块化十分必要。如果我们将"数据"看成不变的事物，将"逻辑"看成可能改变的事物，就可以完美避开上述问题。Data Segregation（意为数据分离）模式很好地实现了这一想法。该模式要求一个业务合约和一个数据合约：数据合约只管数据存取，这部分是稳定的；而业务合约则通过数据合约来完成逻辑操作。 + +结合前面的例子，我们将数据读写操作专门转移到一个合约DataRepository中： + +``` +contract DataRepository{ + + uint private _data; + + function setData(uint data) public { + _data = data; + } + + function getData() public view returns(uint){ + return _data; + } +} +``` + +计算功能被单独放入一个业务合约中： + +``` +contract Computer{ + DataRepository private _dataRepository; + constructor(address addr){ + _dataRepository =DataRepository(addr); + } + + //业务代码 + function compute() public view returns(uint){ + return _dataRepository.getData() * 10; + } +} +``` + +这样，只要数据合约是稳定的，业务合约的升级就很轻量化了。比如，当我要把Computer换成ComputerV2时，原先的数据依然可以被复用。 + +### Satellite - 分解合约功能 + +一个复杂的合约通常由许多功能构成，如果这些功能全部耦合在一个合约中，当某一个功能需要更新时，就不得不去部署整个合约，正常的功能都会受到波及。Satellite模式运用单一职责原则解决上述问题，提倡将合约子功能放到子合约里，每个子合约（也称为卫星合约）只对应一个功能。当某个子功能需要修改，只要创建新的子合约，并将其地址更新到主合约里即可，其余功能不受影响。 + +举个简单的例子，下面这个合约的setVariable功能是将输入数据进行计算（compute函数），并将计算结果存入合约状态_variable： + +``` +contract Base { + uint public _variable; + + function setVariable(uint data) public { + _variable = compute(data); + } + + //计算 + function compute(uint a) internal returns(uint){ + return a * 10; + } +} +``` + +如果部署后，发现compute函数写错，希望乘以的系数是20，就要重新部署整个合约。但如果一开始按照Satellite模式操作，则只需部署相应的子合约。 + +首先，我们先将compute函数剥离到一个单独的卫星合约中去： + +``` +contract Satellite { + function compute(uint a) public returns(uint){ + return a * 10; + } +} +``` + +然后，主合约依赖该子合约完成setVariable： + +``` +contract Base { + uint public _variable; + + function setVariable(uint data) public { + _variable = _satellite.compute(data); + } + + Satellite _satellite; + //更新子合约（卫星合约） + function updateSatellite(address addr) public { + _satellite = Satellite(addr); + } +} +``` + +这样，当我们需要修改compute函数时，只需部署这样一个新合约，并将它的地址传入到Base.updateSatellite即可： + +``` +contract Satellite2{ + function compute(uint a) public returns(uint){ + return a * 20; + } +} +``` + +### Contract Registry - 跟踪最新合约 + +在Satellite模式中，如果一个主合约依赖子合约，在子合约升级时，主合约需要更新对子合约的地址引用，这通过updateXXX来完成，例如前文的updateSatellite函数。这类接口属于维护性接口，与实际业务无关，过多暴露此类接口会影响主合约美观，让调用者的体验大打折扣。Contract Registry设计模式优雅地解决了这个问题。在该设计模式下，会有一个专门的合约Registry跟踪子合约的每次升级情况，主合约可通过查询此Registyr合约取得最新的子合约地址。卫星合约重新部署后，新地址通过Registry.update函数来更新。 + +``` +contract Registry{ + + address _current; + address[] _previous; + + //子合约升级了，就通过update函数更新地址 + function update(address newAddress) public{ + if(newAddress != _current){ + _previous.push(_current); + _current = newAddress; + } + } + + function getCurrent() public view returns(address){ + return _current; + } +} +``` + +主合约依赖于Registry获取最新的卫星合约地址。 + +``` +contract Base { + uint public _variable; + + function setVariable(uint data) public { + Satellite satellite = Satellite(_registry.getCurrent()); + _variable = satellite.compute(data); + } + + Registry private _registry = //...; +} +``` + +### **Contract Relay - 代理调用最新合约** + +该设计模式所解决问题与Contract Registry一样，即主合约无需暴露维护性接口就可调用最新子合约。该模式下，存在一个代理合约，和子合约享有相同接口，负责将主合约的调用请求传递给真正的子合约。卫星合约重新部署后，新地址通过SatelliteProxy.update函数来更新。 + +``` +contract SatelliteProxy{ + address _current; + function compute(uint a) public returns(uint){ + Satellite satellite = Satellite(_current); + return satellite.compute(a); + } + + //子合约升级了，就通过update函数更新地址 + function update(address newAddress) public{ + if(newAddress != _current){ + _current = newAddress; + } + } +} + + +contract Satellite { + function compute(uint a) public returns(uint){ + return a * 10; + } +} +``` + +主合约依赖于SatelliteProxy： + +``` +contract Base { + uint public _variable; + + function setVariable(uint data) public { + _variable = _proxy.compute(data); + } + SatelliteProxy private _proxy = //...; +} +``` + + + +## 生命周期（Lifecycle） + +在默认情况下，一个合约的生命周期近乎无限——除非赖以生存的区块链被消灭。但很多时候，用户希望缩短合约的生命周期。这一节将介绍两个简单模式提前终结合约生命。 + +### Mortal - 允许合约自毁 + +字节码中有一个selfdestruct指令，用于销毁合约。所以只需要暴露出自毁接口即可： + +``` +contract Mortal{ + + //自毁 + function destroy() public{ + selfdestruct(msg.sender); + } +} +``` + +### Automatic Deprecation - 允许合约自动停止服务 + +如果你希望一个合约在指定期限后停止服务，而不需要人工介入，可以使用Automatic Deprecation模式。 + +``` +contract AutoDeprecated{ + + uint private _deadline; + + function setDeadline(uint time) public { + _deadline = time; + } + + modifier notExpired(){ + require(now <= _deadline); + _; + } + + function service() public notExpired{ + //some code + } +} +``` + +当用户调用service，notExpired修饰符会先进行日期检测，这样，一旦过了特定时间，调用就会因过期而被拦截在notExpired层。 + +## 权限（Authorization） + +前文中有许多管理性接口，这些接口如果任何人都可调用，会造成严重后果，例如上文中的自毁函数，假设任何人都能访问，其严重性不言而喻。所以，一套保证只有特定账户能够访问的权限控制设计模式显得尤为重要。 + +### Ownership + +对于权限的管控，可以采用Ownership模式。该模式保证了只有合约的拥有者才能调用某些函数。首先需要有一个Owned合约： + +``` +contract Owned{ + + address public _owner; + + constructor() { + _owner = msg.sender; + } + + modifier onlyOwner(){ + require(_owner == msg.sender); + _; + } +} +``` + +如果一个业务合约，希望某个函数只由拥有者调用，该怎么办呢？如下： + +``` +contract Biz is Owned{ + function manage() public onlyOwner{ + } +} +``` + +这样，当调用manage函数时，onlyOwner修饰符就会先运行并检测调用者是否与合约拥有者一致，从而将无授权的调用拦截在外。 + +## 行为控制（Action And Control） + +这类模式一般针对具体场景使用，这节将主要介绍基于隐私的编码模式和与链外数据交互的设计模式。 + +### Commit - Reveal - 延迟秘密泄露 + +链上数据都是公开透明的，一旦某些隐私数据上链，任何人都可看到，并且再也无法撤回。Commit And Reveal模式允许用户将要保护的数据转换为不可识别数据，比如一串哈希值，直到某个时刻再揭示哈希值的含义，展露真正的原值。以投票场景举例，假设需要在所有参与者都完成投票后再揭示投票内容，以防这期间参与者受票数影响。我们可以看看，在这个场景下所用到的具体代码： + +``` +contract CommitReveal { + + struct Commit { + string choice; + string secret; + uint status; + } + + mapping(address => mapping(bytes32 => Commit)) public userCommits; + event LogCommit(bytes32, address); + event LogReveal(bytes32, address, string, string); + + function commit(bytes32 commit) public { + Commit storage userCommit = userCommits[msg.sender][commit]; + require(userCommit.status == 0); + userCommit.status = 1; // committed + emit LogCommit(commit, msg.sender); + } + + function reveal(string choice, string secret, bytes32 commit) public { + Commit storage userCommit = userCommits[msg.sender][commit]; + require(userCommit.status == 1); + require(commit == keccak256(choice, secret)); + userCommit.choice = choice; + userCommit.secret = secret; + userCommit.status = 2; + emit LogReveal(commit, msg.sender, choice, secret); + } +} +``` + +### Oracle - 读取链外数据 + +目前，链上的智能合约生态相对封闭，无法获取链外数据，影响了智能合约的应用范围。链外数据可极大扩展智能合约的使用范围，比如在保险业中，如果智能合约可读取到现实发生的意外事件，就可自动执行理赔。获取外部数据会通过名为Oracle的链外数据层来执行。当业务方的合约尝试获取外部数据时，会先将查询请求存入到某个Oracle专用合约内；Oracle会监听该合约，读取到这个查询请求后，执行查询，并调用业务合约响应接口使合约获取结果。 + + + +下面定义了一个Oracle合约： + +``` +contract Oracle { + address oracleSource = 0x123; // known source + + struct Request { + bytes data; + function(bytes memory) external callback; +} + + Request[] requests; + event NewRequest(uint); + modifier onlyByOracle() { + require(msg.sender == oracleSource); _; + } + + function query(bytes data, function(bytes memory) external callback) public { + requests.push(Request(data, callback)); + emit NewRequest(requests.length - 1); + } + + //回调函数，由Oracle调用 + function reply(uint requestID, bytes response) public onlyByOracle() { + requests[requestID].callback(response); + } +} +``` + +业务方合约与Oracle合约进行交互： + +``` +contract BizContract { + Oracle _oracle; + + constructor(address oracle){ + _oracle = Oracle(oracle); + } + + modifier onlyByOracle() { + require(msg.sender == address(_oracle)); + _; + } + + function updateExchangeRate() { + _oracle.query("USD", this.oracleResponse); + } + + //回调函数，用于读取响应 + function oracleResponse(bytes response) onlyByOracle { + // use the data + } +} +``` + +## 总结 + +本文的介绍涵盖了安全性、可维护性等多种设计模式，其中，有些偏原则性，如Security和Maintenance设计模式；有些是偏实践，例如Authrization，Action And Control。这些设计模式，尤其实践类，并不能涵盖所有场景。随着对实际业务的深入探索，会遇到越来越多的特定场景与问题，开发者可对这些模式提炼、升华，以沉淀出针对某类问题的设计模式。上述设计模式是程序员的有力武器，掌握它们可应对许多已知场景，但更应掌握提炼设计模式的方法，这样才能从容应对未知领域，这个过程离不开对业务的深入探索，对软件工程原则的深入理解。 \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/3_features/35_contract/solidity_design_programming_strategy.md b/3.x/zh_CN/docs/articles/3_features/35_contract/solidity_design_programming_strategy.md new file mode 100644 index 000000000..81abc76a4 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/35_contract/solidity_design_programming_strategy.md @@ -0,0 +1,552 @@ +# 智能合约编写之Solidity的编程攻略 + +作者：毛嘉宇｜FISCO BCOS 核心开发者 + +## **前 言** + +作为一名搬砖多年的资深码农，刚开始接触Solidity便感觉无从下手：昂贵的计算和存储资源、简陋的语法特性、令人抓狂的debug体验、近乎贫瘠的类库支持、一言不合就插入汇编语句……让人不禁怀疑，这都已经过了9012年了，居然还有这种反人类的语言？对于习惯使用各类日益“傻瓜化”的类库和自动化高级框架的码农而言，学习Solidity的过程就是一场一言难尽的劝退之旅。但随着对区块链底层技术的深入学习，大家会慢慢理解作为运行在“The World Machine”上的Solidity语言，必须要严格遵循的设计原则以及权衡后必须付出的代价。正如黑客帝国中那句著名的slogan：“Welcome to the dessert of the real”，在恶劣艰苦的环境面前，最重要的是学会如何适应环境、保存自身并快速进化。本文总结了一些Solidity编程的攻略，期待各位读者不吝分享交流，达到抛砖引玉之效。 + +## 上链的原则 + +**“如无必要，勿增实体”。** + +基于区块链技术及智能合约发展现状，数据的上链需遵循以下原则： + +- 需要分布式协作的重要数据才上链，非必需数据不上链； +- 敏感数据脱敏或加密后上链（视数据保密程度选择符合隐私保护安全等级要求的加密算法）； +- 链上验证，链下授权。 + +在使用区块链时，开发者不需要将所有业务和数据都放到链上。相反，“好钢用在刀刃上”，智能合约更适合被用在分布式协作的业务场景中。 + +## 精简函数变量 + +如果在智能合约中定义了复杂的逻辑，特别是合约内定义了复杂的函数入参、变量和返回值，就会在编译的时候碰到以下错误： + +``` +Compiler error: Stack too deep, try removing local variables. +``` + +这也是社区中的高频技术问题之一。造成这个问题的原因就是EVM所设计用于最大的栈深度为16。所有的计算都在一个栈内执行，对栈的访问只限于其顶端，限制方式为：允许拷贝最顶端16个元素中的一个到栈顶，或者将栈顶元素和下面16个元素中的一个交换。所有其他操作都只能取最顶的几个元素，运算后，把结果压入栈顶。当然可以把栈上的元素放到存储或内存中。但无法只访问栈上指定深度的那个元素，除非先从栈顶移除其他元素。如果一个合约中，入参、返回值、内部变量的大小超过了16个，显然就超出了栈的最大深度。因此，我们可以使用结构体或数组来封装入参或返回值，达到减少栈顶元素使用的目的，从而避免此错误。例如以下代码，通过使用bytes数组来封装了原本16个bytes变量。 + +``` +function doBiz(bytes[] paras) public { + require(paras.length >= 16); + // do something +} +``` + +## 保证参数和行为符合预期 + +心怀“Code is law”的远大理想，极客们设计和创造了区块链的智能合约。在联盟链中，不同的参与者可以使用智能合约来定义和书写一部分业务或交互的逻辑，以完成部分社会或商业活动。 + +相比于传统软件开发，智能合约对函数参数和行为的安全性要求更为严格。在联盟链中提供了身份实名和CA证书等机制，可以有效定位和监管所有参与者。不过，智能合约缺乏对漏洞和攻击的事前干预机制。正所谓字字珠玑，如果不严谨地检查智能合约输入参数或行为，有可能会触发一些意想不到的bug。 + +因此，在编写智能合约时，一定要注意对合约参数和行为的检查，尤其是那些对外部开放的合约函数。Solidity提供了require、revert、assert等关键字来进行异常的检测和处理。一旦检测并发现错误，整个函数调用会被回滚，所有状态修改都会被回退，就像从未调用过函数一样。以下分别使用了三个关键字，实现了相同的语义。 + +``` +require(_data == data, "require data is valid"); + +if(_data != data) { revert("require data is valid"); } + +assert(_data == data); +``` + +不过，这三个关键字一般适用于不同的使用场景： + +- require：最常用的检测关键字，用来验证输入参数和调用函数结果是否合法。 +- revert：适用在某个分支判断的场景下。 +- assert: 检查结果是否正确、合法，一般用于函数结尾。 + +在一个合约的函数中，可以使用函数修饰器来抽象部分参数和条件的检查。在函数体内，可以对运行状态使用if-else等判断语句进行检查，对异常的分支使用revert回退。在函数运行结束前，可以使用assert对执行结果或中间状态进行断言检查。在实践中，推荐使用require关键字，并将条件检查移到函数修饰器中去；这样可以让函数的职责更为单一，更专注到业务逻辑中。同时，函数修饰器等条件代码也更容易被复用，合约也会更加安全、层次化。 + +在本文中，我们以一个水果店库存管理系统为例，设计一个水果超市的合约。这个合约只包含了对店内所有水果品类和库存数量的管理，setFruitStock函数提供了对应水果库存设置的函数。在这个合约中，我们需要检查传入的参数，即水果名称不能为空。 + +``` +pragma solidity ^0.4.25; + +contract FruitStore { + mapping(bytes => uint) _fruitStock; + modifier validFruitName(bytes fruitName) { + require(fruitName.length > 0, "fruite name is invalid!"); + _; + } + function setFruitStock(bytes fruitName, uint stock) validFruitName(fruitName) external { + _fruitStock[fruitName] = stock; + } +} +``` + +如上所述，我们添加了函数执行前的参数检查的函数修饰器。同理，通过使用函数执行前和函数执行后检查的函数修饰器，可以保证智能合约更加安全、清晰。智能合约的编写需要设置严格的前置和后置函数检查，来保证其安全性。 + +## 严控函数的执行权限 + +如果说智能合约的参数和行为检测提供了静态的合约安全措施，那么合约权限控制的模式则提供了动态访问行为的控制。由于智能合约是发布到区块链上，所有数据和函数对所有参与者都是公开透明的，任一节点参与者都可发起交易，无法保证合约的隐私。因此，合约发布者必须对函数设计严格的访问限制机制。Solidity提供了函数可见性修饰符、修饰器等语法，灵活地使用这些语法，可帮助构建起合法授权、受控调用的智能合约系统。还是以刚才的水果合约为例。现在getStock提供了查询具体水果库存数量的函数。 + +``` +pragma solidity ^0.4.25; + +contract FruitStore { + mapping(bytes => uint) _fruitStock; + modifier validFruitName(bytes fruitName) { + require(fruitName.length > 0, "fruite name is invalid!"); + _; + } + function getStock(bytes fruit) external view returns(uint) { + return _fruitStock[fruit]; + } + function setFruitStock(bytes fruitName, uint stock) validFruitName(fruitName) external { + _fruitStock[fruitName] = stock; + } +} +``` + +水果店老板将这个合约发布到了链上。但是，发布之后，setFruitStock函数可被任何其他联盟链的参与者调用。虽然联盟链的参与者是实名认证且可事后追责；但一旦有恶意攻击者对水果店发起攻击，调用setFruitStock函数就能任意修改水果库存，甚至将所有水果库存清零，这将对水果店正常经营管理产生严重后果。因此，设置某些预防和授权的措施很必要：对于修改库存的函数setFruitStock，可在函数执行前对调用者进行鉴权。类似的，这些检查可能会被多个修改数据的函数复用，使用一个onlyOwner的修饰器就可以抽象此检查。owner字段代表了合约的所有者，会在合约构造函数中被初始化。使用public修饰getter查询函数，就可以通过_owner()函数查询合约的所有者。 + +``` +contract FruitStore { + address public _owner; + mapping(bytes => uint) _fruitStock; + + constructor() public { + _owner = msg.sender; + } + + modifier validFruitName(bytes fruitName) { + require(fruitName.length > 0, "fruite name is invalid!"); + _; + } + // 鉴权函数修饰器 + modifier onlyOwner() { + require(msg.sender == _owner, "Auth: only owner is authorized."); + _; + } + function getStock(bytes fruit) external view returns(uint) { + return _fruitStock[fruit]; + } + // 添加了onlyOwner修饰器 + function setFruitStock(bytes fruitName, uint stock) + onlyOwner validFruitName(fruitName) external { + _fruitStock[fruitName] = stock; + } +} +``` + +这样一来，我们可以将相应的函数调用权限检查封装到修饰器中，智能合约会自动发起对调用者身份验证检查，并且只允许合约部署者来调用setFruitStock函数，以此保证合约函数向指定调用者开放。 + +## 抽象通用的业务逻辑 + +分析上述FruitStore合约，我们发现合约里似乎混入了奇怪的东西。参考单一职责的编程原则，水果店库存管理合约多了上述函数功能检查的逻辑，使合约无法将所有代码专注在自身业务逻辑中。对此，我们可以抽象出可复用的功能，利用Solidity的继承机制继承最终抽象的合约。基于上述FruitStore合约，可抽象出一个BasicAuth合约，此合约包含之前onlyOwner的修饰器和相关功能接口。 + +``` +contract BasicAuth { + address public _owner; + + constructor() public { + _owner = msg.sender; + } + + function setOwner(address owner) + public + onlyOwner +{ + _owner = owner; + } + + modifier onlyOwner() { + require(msg.sender == _owner, "BasicAuth: only owner is authorized."); + _; + } +} +``` + +FruitStore可以复用这个修饰器，并将合约代码收敛到自身业务逻辑中。 + +``` +import "./BasicAuth.sol"; + +contract FruitStore is BasicAuth { + mapping(bytes => uint) _fruitStock; + + function setFruitStock(bytes fruitName, uint stock) + onlyOwner validFruitName(fruitName) external { + _fruitStock[fruitName] = stock; + } +} +``` + +这样一来，FruitStore的逻辑被大大简化，合约代码更精简、聚焦和清晰。 + +## 预防私钥的丢失 + +在区块链中调用合约函数的方式有两种：内部调用和外部调用。出于隐私保护和权限控制，业务合约会定义一个合约所有者。假设用户A部署了FruitStore合约，那上述合约owner就是部署者A的外部账户地址。这个地址由外部账户的私钥计算生成。但是，在现实世界中，私钥泄露、丢失的现象比比皆是。一个商用区块链DAPP需要严肃考虑私钥的替换和重置等问题。这个问题最为简单直观的解决方法是添加一个备用私钥。这个备用私钥可支持权限合约修改owner的操作，代码如下： + +``` +ontract BasicAuth { + address public _owner; + address public _bakOwner; + + constructor(address bakOwner) public { + _owner = msg.sender; + _bakOwner = bakOwner; + } + + function setOwner(address owner) + public + canSetOwner +{ + _owner = owner; + } + + function setBakOwner(address owner) + public + canSetOwner +{ + _bakOwner = owner; + } + + // ... + + modifier isAuthorized() { + require(msg.sender == _owner || msg.sender == _bakOwner, "BasicAuth: only owner or back owner is authorized."); + _; + } +} +``` + +这样，当发现私钥丢失或泄露时，我们可以使用备用外部账户调用setOwner重置账号，恢复、保障业务正常运行。 + +## 面向接口编程 + +上述私钥备份理念值得推崇，不过其具体实现方式存在一定局限性，在很多业务场景下，显得过于简单粗暴。对于实际的商业场景，私钥的备份和保存需要考虑的维度和因素要复杂得多，对应密钥备份策略也更多元化。以水果店为例，有的连锁水果店可能希望通过品牌总部来管理私钥，也有的可能通过社交关系重置帐号，还有的可能会绑定一个社交平台的管理帐号……面向接口编程，而不依赖具体的实现细节，可以有效规避这个问题。例如，我们利用接口功能首先定义一个判断权限的抽象接口： + +``` +contract Authority { + function canCall( + address src, address dst, bytes4 sig + ) public view returns (bool); +} +``` + +这个canCall函数涵盖了函数调用者地址、目标调用合约的地址和函数签名，函数返回一个bool的结果。这包含了合约鉴权所有必要的参数。我们可进一步修改之前的权限管理合约，并在合约中依赖Authority接口，当鉴权时，修饰器会调用接口中的抽象方法： + +``` +contract BasicAuth { + Authority public _authority; + + function setAuthority(Authority authority) + public + auth + { + _authority = authority; + } + + modifier isAuthorized() { + require(auth(msg.sender, msg.sig), "BasicAuth: only owner or back owner is authorized."); + _; + } + + function auth(address src, bytes4 sig) public view returns (bool) { + if (src == address(this)) { + return true; + } else if (src == _owner) { + return true; + } else if (_authority == Authority(0)) { + return false; + } else { + return _authority.canCall(src, this, sig); + } + } +} +``` + +这样，我们只需要灵活定义实现了canCall接口的合约，在合约的canCall方法中定义具体判断逻辑。而业务合约，例如FruitStore继承BasicAuth合约，在创建时只要传入具体的实现合约，就可以实现不同判断逻辑。 + +## 合理预留事件 + +迄今为止，我们已实现强大灵活的权限管理机制，只有预先授权的外部账户才能修改合约owner属性。不过，仅通过上述合约代码，我们无法记录和查询修改、调用函数的历史记录和明细信息。而这样的需求在实际业务场景中比比皆是。比如，FruitStore水果店需要通过查询历史库存修改记录，计算出不同季节的畅销与滞销水果。 + +一种方法是依托链下维护独立的台账机制。不过，这种方法存在很多问题：保持链下台账和链上记录一致的成本开销非常高；同时，智能合约面向链上所有参与者开放，一旦其他参与者调用了合约函数，相关交易信息就存在不能同步的风险。针对此类场景，Solidity提供了event语法。event不仅具备可供SDK监听回调的机制，还能用较低的gas成本将事件参数等信息完整记录、保存到区块中。FISCO BCOS社区中，也有WEBASE-Collect-Bee这样的工具，在事后实现区块历史事件信息的完整导出。 + +[WEBASE-Collect-Bee工具参考](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE-Collect-Bee/index.html) + +基于上述权限管理合约，我们可以定义相应的修改权限事件，其他事件以此类推。 + +``` +event LogSetAuthority (Authority indexed authority, address indexed from); +} +``` + +接下来，可以调用相应的事件： + +``` +function setAuthority(Authority authority) + public + auth +{ + _authority = authority; + emit LogSetAuthority(authority, msg.sender); + } +``` + +当setAuthority函数被调用时，会同时触发LogSetAuthority，将事件中定义的Authority合约地址以及调用者地址记录到区块链交易回执中。当通过控制台调用setAuthority方法时，对应事件LogSetAuthority也会被打印出来。基于WEBASE-Collect-Bee，我们可以导出所有该函数的历史信息到数据库中。也可基于WEBASE-Collect-Bee进行二次开发，实现复杂的数据查询、大数据分析和数据可视化等功能。 + +## 遵循安全编程规范 + +每一门语言都有其相应的编码规范，我们需要尽可能严格地遵循Solidity官方编程风格指南，使代码更利于阅读、理解和维护，有效地减少合约的bug数量。[Solidity官方编程风格指南参考](https://solidity.readthedocs.io/en/latest/style-guide.html)。除了编程规范，业界也总结了很多安全编程指南，例如重入漏洞、数据结构溢出、随机数误区、构造函数失控、为初始化的存储指针等等。重视和防范此类风险，采用业界推荐的安全编程规范至关重要，例如[Solidity官方安全编程指南](https://solidity.readthedocs.io/en/latest/security-considerations.html)。同时，在合约发布上线后，还需要注意关注、订阅Solidity社区内安全组织或机构发布的各类安全漏洞、攻击手法，一旦出现问题，及时做到亡羊补牢。 + +对于重要的智能合约，有必要引入审计。现有的审计包括了人工审计、机器审计等方法，通过代码分析、规则验证、语义验证和形式化验证等方法保证合约安全性。虽然本文通篇都在强调，模块化和重用被严格审查并广泛验证的智能合约是最佳的实践策略。但在实际开发过程，这种假设过于理想化，每个项目或多或少都会引入新的代码，甚至从零开始。不过，我们仍然可以视代码的复用程度进行审计分级，显式地标注出引用的代码，将审计和检查的重点放在新代码上，以节省审计成本。 + +最后，“前事不忘后事之师”，我们需要不断总结和学习前人的最佳实践，动态和可持续地提升编码工程水平，并不断应用到具体实践中。 + +### 积累和复用成熟的代码 + +前文面向接口编程中的思想可降低代码耦合，使合约更容易扩展、利于维护。在遵循这条规则之外，还有另外一条忠告：尽可能地复用现有代码库。智能合约发布后难以修改或撤回，而且发布到公开透明的区块链环境上，就意味着一旦出现bug造成的损失和风险更甚于传统软件。因此，复用一些更好更安全的轮子远胜过重新造轮子。在开源社区中，已经存在大量的业务合约和库可供使用，例如OpenZeppelin等优秀的库。如果在开源世界和过去团队的代码库里找不到合适的可复用代码，建议在编写新代码时尽可能地测试和完善代码设计。此外，还要定期分析和审查历史合约代码，将其模板化，以便于扩展和复用。 + +例如，针对上面的BasicAuth，参考防火墙经典的ACL(Access Control List)设计，我们可以进一步地继承和扩展BasicAuth，抽象出ACL合约控制的实现。 + +``` +contract AclGuard is BasicAuth { + bytes4 constant public ANY_SIG = bytes4(uint(-1)); + address constant public ANY_ADDRESS = address(bytes20(uint(-1))); + mapping (address => mapping (address => mapping (bytes4 => bool))) _acl; + + function canCall( + address src, address dst, bytes4 sig +) public view returns (bool) { + return _acl[src][dst][sig] + || _acl[src][dst][ANY_SIG] + || _acl[src][ANY_ADDRESS][sig] + || _acl[src][ANY_ADDRESS][ANY_SIG] + || _acl[ANY_ADDRESS][dst][sig] + || _acl[ANY_ADDRESS][dst][ANY_SIG] + || _acl[ANY_ADDRESS][ANY_ADDRESS][sig] + || _acl[ANY_ADDRESS][ANY_ADDRESS][ANY_SIG]; + } + + function permit(address src, address dst, bytes4 sig) public onlyAuthorized { + _acl[src][dst][sig] = true; + emit LogPermit(src, dst, sig); + } + + function forbid(address src, address dst, bytes4 sig) public onlyAuthorized { + _acl[src][dst][sig] = false; + emit LogForbid(src, dst, sig); + } + + function permit(address src, address dst, string sig) external { + permit(src, dst, bytes4(keccak256(sig))); + } + + function forbid(address src, address dst, string sig) external { + forbid(src, dst, bytes4(keccak256(sig))); + } + + function permitAny(address src, address dst) external { + permit(src, dst, ANY_SIG); + } + + function forbidAny(address src, address dst) external { + forbid(src, dst, ANY_SIG); + } +} +``` + +在这个合约里，有调用者地址、被调用合约地址和函数签名三个主要参数。通过配置ACL的访问策略，可以精确地定义和控制函数访问行为及权限。合约内置了ANY的常量，匹配任意函数，使访问粒度的控制更加便捷。这个模板合约实现了强大灵活的功能，足以满足所有类似权限控制场景的需求。 + +## 提升存储和计算的效率 + +迄今为止，在上述的推演过程中，更多的是对智能合约编程做加法。但相比传统软件环境，智能合约上的存储和计算资源更加宝贵。因此，如何对合约做减法也是用好Solidity的必修课程之一。 + +### 选取合适的变量类型 + +显式的问题可通过EVM编译器检测出来并报错；但大量的性能问题可能被隐藏在代码的细节中。Solidity提供了非常多精确的基础类型，这与传统的编程语言大相径庭。下面有几个关于Solidity基础类型的小技巧。在C语言中，可以用short\int\long按需定义整数类型，而到了Solidity，不仅区分int和uint，甚至还能定义uint的长度，比如uint8是一个字节，uint256是32个字节。这种设计告诫我们，能用uint8搞定的，绝对不要用uint16！几乎所有Solidity的基本类型，都能在声明时指定其大小。开发者一定要有效利用这一语法特性，编写代码时只要满足需求就尽可能选取小的变量类型。数据类型bytes32可存放 32 个（原始）字节，但除非数据是bytes32或bytes16这类定长的数据类型，否则更推荐使用长度可以变化的bytes。bytes类似byte[]，但在外部函数中会自动压缩打包，更节省空间。如果变量内容是英文的，不需要采用UTF-8编码，在这里，推荐bytes而不是string。string默认采用UTF-8编码，所以相同字符串的存储成本会高很多。 + +### 紧凑状态变量打包 + +除了尽可能使用较小的数据类型来定义变量，有的时候，变量的排列顺序也非常重要，可能会影响到程序执行和存储效率。其中根本原因还是EVM，不管是EVM存储插槽（Storage Slot）还是栈，每个元素长度是一个字（256位，32字节）。分配存储时，所有变量（除了映射和动态数组等非静态类型）都会按声明顺序从位置0开始依次写下。在处理状态变量和结构体成员变量时，EVM会将多个元素打包到一个存储插槽中，从而将多个读或写合并到一次对存储的操作中。值得注意的是，使用小于32 字节的元素时，合约的gas使用量可能高于使用32字节元素时。这是因为EVM每次会操作32个字节，所以如果元素比32字节小，必须使用更多的操作才能将其大小缩减到所需。这也解释了Solidity中最常见的数据类型，例如int，uint，byte32，为何都刚好占用32个字节。所以，当合约或结构体声明多个状态变量时，能否合理地组合安排多个存储状态变量和结构体成员变量，使之占用更少的存储位置就十分重要。例如，在以下两个合约中，经过实际测试，Test1合约比Test2合约占用更少的存储和计算资源。 + +``` +contract Test1 { + //占据2个slot, "gasUsed":188873 + struct S { + bytes1 b1; + bytes31 b31; + bytes32 b32; + } + S s; + function f() public { + S memory tmp = S("a","b","c"); + s = tmp; + } +} + +contract Test2 { + //占据3个slot, "gasUsed":188937 + struct S { + bytes31 b31; + bytes32 b32; + bytes1 b1; + } + // …… +} +``` + +### 优化查询接口 + +查询接口的优化点很多，比如一定要在只负责查询的函数声明中添加view修饰符，否则查询函数会被当成交易打包并发送到共识队列，被全网执行并被记录在区块中；这将大大增加区块链的负担，占用宝贵的链上资源。再如，不要在智能合约中添加复杂的查询逻辑，因为任何复杂查询代码都会使整个合约变得更长更复杂。读者可使用上文提及的WeBASE数据导出组件，将链上数据导出到数据库中，在链下进行查询和分析。 + +### 缩减合约binary长度 + +开发者编写的Solidity代码会被编译为binary code，而部署智能合约的过程实际上就是通过一个transaction将binary code存储在链上，并取得专属于该合约的地址。缩减binary code的长度可节省网络传输、共识打包数据存储的开销。例如，在典型的存证业务场景中，每次客户存证都会新建一个存证合约，因此，应当尽可能地缩减binary code的长度。常见思路是裁剪不必要的逻辑，删掉冗余代码。特别是在复用代码时，可能引入一些非刚需代码。以上文ACL合约为例，支持控制合约函数粒度的权限。 + +``` +function canCall( + address src, address dst, bytes4 sig + ) public view returns (bool) { + return _acl[src][dst][sig] + || _acl[src][dst][ANY_SIG] + || _acl[src][ANY_ADDRESS][sig] + || _acl[src][ANY_ADDRESS][ANY_SIG] + || _acl[ANY_ADDRESS][dst][sig] + || _acl[ANY_ADDRESS][dst][ANY_SIG] + || _acl[ANY_ADDRESS][ANY_ADDRESS][sig] + || _acl[ANY_ADDRESS][ANY_ADDRESS][ANY_SIG]; + } +``` + +但在具体业务场景中，只需要控制合约访问者即可，通过删除相应代码，进一步简化使用逻辑。这样一来，对应合约的binary code长度会大大缩小。 + +``` +function canCall( + address src, address dst +) public view returns (bool) { + return _acl[src][dst] + || _acl[src][ANY_ADDRESS] + || _acl[ANY_ADDRESS][dst]; + } +``` + +另一种缩减binary code的思路是采用更紧凑的写法。经实测，采取如上短路原则的判断语句，其binary长度会比采用if-else语法的更短。同样，采用if-else的结构，也会比if-if-if的结构生成更短的binary code。最后，在对binary code长度有极致要求的场景中，应当尽可能避免在合约中新建合约，这会显著增加binary的长度。例如，某个合约中有如下的构造函数： + +``` +constructor() public { + // 在构造器内新建一个新对象 + _a = new A(); +} +``` + +我们可以采用在链下构造A对象，并基于address传输和固定校验的方式，来规避这一问题。 + +``` +constructor(address a) public { + A _a = A(a); + require(_a._owner == address(this)); +} +``` + +当然，这样也可能会使合约交互方式变得复杂。但其提供了有效缩短binary code长度的捷径，需要在具体业务场景中做权衡取舍。 + +## 保证合约可升级 + +### 经典的三层结构 + +通过前文方式，我们尽最大努力保持合约设计的灵活性；翻箱倒柜复用了轮子；也对发布合约进行全方位、无死角的测试。除此之外，随着业务需求变化，我们还将面临一个问题：如何保证合约平滑、顺利的升级？作为一门高级编程语言，Solidity支持运行一些复杂控制和计算逻辑，也支持存储智能合约运行后的状态和业务数据。不同于WEB开发等场景的应用-数据库分层架构，Solidity语言甚至没有抽象出一层独立的数据存储结构，数据都被保存到了合约中。但是，一旦合约需要升级，这种模式就会出现瓶颈。 + +在Solidity中，一旦合约部署发布后，其代码就无法被修改，只能通过发布新合约去改动代码。假如数据存储在老合约，就会出现所谓的“孤儿数据”问题，新合约将丢失之前运行的历史业务数据。这种情况，开发者可以考虑将老合约数据迁移到新合约中，但此操作至少存在两个问题： + +1. 迁移数据会加重区块链的负担，产生资源浪费和消耗，甚至引入安全问题； +2. 牵一发而动全身，会引入额外的迁移数据逻辑，增加合约复杂度。 + +一种更合理的方式是抽象一层独立的合约存储层。这个存储层只提供合约读写的最基本方法，而不包含任何业务逻辑。在这种模式中，存在三种合约角色： + +- 数据合约：在合约中保存数据，并提供数据的操作接口。 +- 管理合约：设置控制权限，保证只有控制合约才有权限修改数据合约。 +- 控制合约：真正需要对数据发起操作的合约。 + +具体的代码示例如下： + +##### 数据合约： + +``` +contract FruitStore is BasicAuth { + address _latestVersion; + mapping(bytes => uint) _fruitStock; + + modifier onlyLatestVersion() { + require(msg.sender == _latestVersion); + _; + } + + function upgradeVersion(address newVersion) public { + require(msg.sender == _owner); + _latestVersion = newVersion; + } + + function setFruitStock(bytes fruit, uint stock) onlyLatestVersion external { + _fruitStock[fruit] = stock; + } +} +``` + +##### 管理合约： + +``` +contract Admin is BasicAuth { + function upgradeContract(FruitStore fruitStore, address newController) isAuthorized external { + fruitStore.upgradeVersion(newController); + } +} +``` + +##### 控制合约： + +``` +contract FruitStoreController is BasicAuth { + function upgradeStock(bytes fruit, uint stock) isAuthorized external { + fruitStore.setFruitStock(fruit, stock); + } +} +``` + +一旦函数的控制逻辑需要变更，开发者只需修改FruitStoreController控制合约逻辑，部署一个新合约，然后使用管理合约Admin修改新的合约地址参数就可轻松完成合约升级。这种方法可消除合约升级中因业务控制逻辑改变而导致的数据迁移隐患。但天下没有免费的午餐，这种操作需要在可扩展性和复杂性之间需要做基本的权衡。首先，数据和逻辑的分离降低了运行性能。其次，进一步封装增加了程序复杂度。最后，越是复杂的合约越会增加潜在攻击面，简单的合约比复杂的合约更安全。 + +### 通用数据结构 + +到目前为止，还存在一个问题，假如数据合约中的数据结构本身需要升级怎么办？ + +例如，在FruitStore中，原本只保存了库存信息，现在由于水果销售店生意发展壮大，一共开了十家分店，需要记录每家分店、每种水果的库存和售出信息。在这种情况下，一种解决方案是采用外部关联管理方式：创建一个新的ChainStore合约，在这个合约中创建一个mapping，建立分店名和FruitStore的关系。 + +此外，不同分店需要创建一个FruitStore的合约。为了记录新增的售出信息等数据，我们还需要新建一个合约来管理。假如在FruitStore中可预设一些不同类型的reserved字段，可帮助规避新建售出信息合约的开销，仍然复用FruitStore合约。但这种方式在最开始会增加存储开销。一种更好的思路是抽象一层更为底层和通用的存储结构。代码如下： + +``` +contract commonDB is BasicAuth { + mapping(bytes => uint) _uintMapping; + + function getUint(bytes key) external view returns(uint) { + return _uintMapping[key]; + } + + function setUint(bytes key, uint value) isAuthorized onlyLatestVersion external { + _uintMapping[key] = value; + } + +} +``` + +类似的，我们可加入所有数据类型变量，帮助commonDB应对和满足不同的数据类型存储需求。相应的控制合约可修改如下： + +``` +contract FruitStoreControllerV2 is BasicAuth { + function upgradeStock(bytes32 storeName, bytes32 fruit, uint stock) + isAuthorized external { + commonDB.setUint(sha256(storeName, fruit), stock); + uint result = commonDB.getUint(sha256(storeName, fruit)); + } +} +``` + +使用以上存储的设计模式，可显著提升合约数据存储灵活性，保证合约可升级。众所周知，Solidity既不支持数据库，使用代码作为存储entity，也无法提供更改schema的灵活性。但是，通过这种KV设计，可以使存储本身获得强大的可扩展性。总之，**没有一个策略是完美的，优秀的架构师善于权衡**。智能合约设计者需要充分了解各种方案的利弊，并基于实际情况选择合适的设计方案。 + +## 总结 + +文至于此，希望激起读者对在Solidity世界生存与进化的兴趣。“若有完美，必有谎言”，软件开发的世界没有银弹。本文行文过程就是从最简单的合约逐步完善和进化的过程。在Solidity编程世界中，生存与进化都离不开三个关键词：安全、可复用、高效。生命不息，进化不止。短短一篇小文难以穷尽所有生存进化之术，希望这三个关键词能帮助大家在Solidity的世界里翱翔畅游，并不断书写辉煌的故事和传说：） diff --git a/3.x/zh_CN/docs/articles/3_features/35_contract/solidity_operation_principle.md b/3.x/zh_CN/docs/articles/3_features/35_contract/solidity_operation_principle.md new file mode 100644 index 000000000..aa7c721c2 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/35_contract/solidity_operation_principle.md @@ -0,0 +1,240 @@ +# 智能合约编写之Solidity运行原理 + +作者：储雨知｜FISCO BCOS 核心开发者 + +## 引 言 + +作为一门面向智能合约的语言，Solidity与其他经典语言既有差异也有相似之处。一方面，服务于区块链的属性使其与其他语言存在差异。例如，合约的部署与调用均要经过区块链网络确认；执行成本需要被严格控制，以防止恶意代码消耗节点资源。另一方面，身为编程语言，Solidity的实现并未脱离经典语言，比如Solidity中包含类似栈、堆的设计，采用栈式虚拟机来进行字节码处理。本系列前几篇文章介绍了如何开发Solidity程序，为了让读者知其然更知其所以然，本文将进一步介绍Solidity的内部运行原理，聚焦于Solidity程序的生命周期和EVM工作机制。 + +## Solidity的生命周期 + +与其他语言一样，Solidity的代码生命周期离不开编译、部署、执行、销毁这四个阶段。下图整理展现了Solidity程序的完整生命周期： + + + +经编译后，Solidity文件会生成字节码。这是一种类似jvm字节码的代码。部署时，字节码与构造参数会被构建成交易，这笔交易会被打包到区块中，经由网络共识过程，最后在各区块链节点上构建合约，并将合约地址返还用户。当用户准备调用该合约上的函数时，调用请求同样也会经历交易、区块、共识的过程，最终在各节点上由EVM虚拟机来执行。 + +下面是一个示例程序，我们通过remix探索它的生命周期。 + +``` +pragma solidity ^0.4.25; + +contract Demo{ + uint private _state; + constructor(uint state){ + _state = state; + } + function set(uint state) public { + _state = state; + } +} +``` + +### 编译 + +源代码编译完后，可以通过ByteCode按钮得到它的二进制： + +``` +608060405234801561001057600080fd5b506040516020806100ed83398101806040528101908080519060200190929190505050806000819055505060a4806100496000396000f300608060405260043610603f576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff16806360fe47b1146044575b600080fd5b348015604f57600080fd5b50606c60048036038101908080359060200190929190505050606e565b005b80600081905550505600a165627a7a723058204ed906444cc4c9aabd183c52b2d486dfc5dea9801260c337185dad20e11f811b0029 +``` + +还可以得到对应的字节码（OpCode）： + +``` +PUSH1 0x80 PUSH1 0x40 MSTORE CALLVALUE DUP1 ISZERO PUSH2 0x10 JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST POP PUSH1 0x40 MLOAD PUSH1 0x20 DUP1 PUSH2 0xED DUP4 CODECOPY DUP2 ADD DUP1 PUSH1 0x40 MSTORE DUP2 ADD SWAP1 DUP1 DUP1 MLOAD SWAP1 PUSH1 0x20 ADD SWAP1 SWAP3 SWAP2 SWAP1 POP POP POP DUP1 PUSH1 0x0 DUP2 SWAP1 SSTORE POP POP PUSH1 0xA4 DUP1 PUSH2 0x49 PUSH1 0x0 CODECOPY PUSH1 0x0 RETURN STOP PUSH1 0x80 PUSH1 0x40 MSTORE PUSH1 0x4 CALLDATASIZE LT PUSH1 0x3F JUMPI PUSH1 0x0 CALLDATALOAD PUSH29 0x100000000000000000000000000000000000000000000000000000000 SWAP1 DIV PUSH4 0xFFFFFFFF AND DUP1 PUSH4 0x60FE47B1 EQ PUSH1 0x44 JUMPI JUMPDEST PUSH1 0x0 DUP1 REVERT JUMPDEST CALLVALUE DUP1 ISZERO PUSH1 0x4F JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST POP PUSH1 0x6C PUSH1 0x4 DUP1 CALLDATASIZE SUB DUP2 ADD SWAP1 DUP1 DUP1 CALLDATALOAD SWAP1 PUSH1 0x20 ADD SWAP1 SWAP3 SWAP2 SWAP1 POP POP POP PUSH1 0x6E JUMP JUMPDEST STOP JUMPDEST DUP1 PUSH1 0x0 DUP2 SWAP1 SSTORE POP POP JUMP STOP LOG1 PUSH6 0x627A7A723058 KECCAK256 0x4e 0xd9 MOD DIFFICULTY 0x4c 0xc4 0xc9 0xaa 0xbd XOR EXTCODECOPY MSTORE 0xb2 0xd4 DUP7 0xdf 0xc5 0xde 0xa9 DUP1 SLT PUSH1 0xC3 CALLDATACOPY XOR 0x5d 0xad KECCAK256 0xe1 0x1f DUP2 SHL STOP 0x29 +``` + +其中下述指令集为set函数对应的代码，后面会解释set函数如何运行。 + +``` +JUMPDEST DUP1 PUSH1 0x0 DUP2 SWAP1 SSTORE POP POP JUMP STOP +``` + +### 部署 + +编译完后，即可在remix上对代码进行部署，构造参数传入0x123: + + + +部署成功后，可得到一条交易回执： + + + +点开input，可以看到具体的交易输入数据： + + + +上面这段数据中，标黄的部分正好是前文中的合约二进制；而标紫的部分，则对应了传入的构造参数0x123。这些都表明，合约部署以交易作为介质。结合区块链交易知识，我们可以还原出整个部署过程： + +- 客户端将部署请求(合约二进制，构造参数)作为交易的输入数据，以此构造出一笔交易 +- 交易经过rlp编码，然后由发送者进行私钥签名 +- 已签名的交易被推送到区块链上的节点 +- 区块链节点验证交易后，存入交易池 +- 轮到该节点出块时，打包交易构建区块，广播给其他节点 +- 其他节点验证区块并取得共识。不同区块链可能采用不同共识算法，FISCO BCOS中采用PBFT取得共识，这要求经历三阶段提交（pre-prepare，prepare, commit） +- 节点执行交易，结果就是智能合约Demo被创建，状态字段_state的存储空间被分配，并被初始化为0x123 + +### 执行 + +根据是否带有修饰符view，我们可将函数分为两类：调用与交易。由于在编译期就确定了调用不会引起合约状态的变更，故对于这类函数调用，节点直接提供查询即可，无需与其他区块链节点确认。而由于交易可能引起状态变更，故会在网络间确认。下面将以用户调用了set(0x10)为假设，看看具体的运行过程。首先，函数set没有配置view/pure修饰符，这意味着其可能更改合约状态。所以这个调用信息会被放入一笔交易，经由交易编码、交易签名、交易推送、交易池缓存、打包出块、网络共识等过程，最终被交由各节点的EVM执行。在EVM中，由SSTORE字节码将参数0xa存储到合约字段_state中。该字节码先从栈上拿到状态字段_state的地址与新值0xa，随后完成实际存储。下图展示了运行过程： + + + +这里仅粗略介绍了set(0xa)是如何运行，下节将进一步展开介绍EVM的工作机制以及数据存储机制。 + +### 销毁 + +由于合约上链后就无法篡改，所以合约生命可持续到底层区块链被彻底关停。若要手动销毁合约，可通过字节码selfdestruct。销毁合约也需要进行交易确认，在此不多作赘述。 + +## EVM原理 + +在前文中，我们介绍了Solidity程序的运行原理。经过交易确认后，最终由EVM执行字节码。对EVM，上文只是一笔带过，这一节将具体介绍其工作机制。 + +### 运行原理 + +EVM是栈式虚拟机，其核心特征就是所有操作数都会被存储在栈上。下面我们将通过一段简单的Solidity语句代码看看其运行原理： + +``` +uint a = 1; +uint b = 2; +uint c = a + b; +``` + +这段代码经过编译后，得到的字节码如下： + +``` +PUSH1 0x1 +PUSH1 0x2 +ADD +``` + +为了读者更好了解其概念，这里精简为上述3条语句，但实际的字节码可能更复杂，且会掺杂SWAP和DUP之类的语句。我们可以看到，在上述代码中，包含两个指令：PUSH1和ADD，它们的含义如下： + +- PUSH1：将数据压入栈顶。 +- ADD：POP两个栈顶元素，将它们相加，并压回栈顶。 + +这里用半动画的方式解释其执行过程。下图中，sp表示栈顶指针，pc表示程序计数器。当执行完push1 0x1后，pc和sp均往下移： + + + +类似地，执行push1 0x2后，pc和sp状态如下： + + + +最后，当add执行完后，栈顶的两个操作数都被弹出作为add指令的输入，两者的和则会被压入栈： + + + + + +### 存储探究 + +在开发过程中，我们常会遇到令人迷惑的memory修饰符；阅读开源代码时，也会看到各种直接针对内存进行的assembly操作。不了解存储机制的开发者遇到这些情况就会一头雾水，所以，这节将探究EVM的存储原理。在前文《[智能合约编写之Solidity的基础特性](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485625&idx=1&sn=9af6032cbf0ad0a3f7f8b7e85faebc77&chksm=9f2efaa5a85973b3fb118b3f1a6e2cd6aef8c1852ee97e93d98afeae71975c3cffc24a0b28fd&scene=21#wechat_redirect)》中我们介绍过，一段Solidity代码，通常会涉及到局部变量、合约状态变量。而这些变量的存储方式存在差别，下面代码表明了变量与存储方式之间的关系。 + +``` +contract Demo{ + //状态存储 + uint private _state; + + function set(uint state) public { + //栈存储 + uint i = 0; + //内存存储 + string memory str = "aaa"; + } +} +``` + +#### 栈 + +栈用于存储字节码指令的操作数。在Solidity中，局部变量若是整型、定长字节数组等类型，就会随着指令的运行入栈、出栈。例如，在下面这条简单的语句中，变量值1会被读出，通过PUSH操作压入栈顶： + +``` +uint i = 1; +``` + +对于这类变量，无法强行改变它们的存储方式，如果在它们之前放置memory修饰符，编译会报错。 + +#### 内存 + +内存类似java中的堆，它用于储存"对象"。在Solidity编程中，如果一个局部变量属于变长字节数组、字符串、结构体等类型，其通常会被memory修饰符修饰，以表明存储在内存中。 + +本节中，我们将以字符串为例，分析内存如何存储这些对象。 + +##### 1. 对象存储结构 + +下面将用assembly语句对复杂对象的存储方式进行分析。assembly语句用于调用字节码操作。mload指令将被用于对这些字节码进行调用。mload(p)表示从地址p读取32字节的数据。开发者可将对象变量看作指针直接传入mload。在下面代码中，经过mload调用，data变量保存了字符串str在内存中的前32字节。 + +``` +string memory str = "aaa"; +bytes32 data; +assembly{ + data := mload(str) +} +``` + +掌握mload，即可用此分析string变量是如何存储的。下面的代码将揭示字符串数据的存储方式： + +``` +function strStorage() public view returns(bytes32, bytes32){ + string memory str = "你好"; + bytes32 data; + bytes32 data2; + assembly{ + data := mload(str) + data2 := mload(add(str, 0x20)) + } + return (data, data2); +} +``` + +data变量表示str的0~31字节，data2表示str的32~63字节。运行strStorage函数的结果如下： + +``` +0: bytes32: 0x0000000000000000000000000000000000000000000000000000000000000006 +1: bytes32: 0xe4bda0e5a5bd0000000000000000000000000000000000000000000000000000 +``` + +可以看到，第一个数据字得到的值为6，正好是字符串"你好"经UTF-8编码后的字节数。第二个数据字则保存的是"你好"本身的UTF-8编码。熟练掌握了字符串的存储格式之后，我们就可以运用assembly修改、拷贝、拼接字符串。读者可搜索Solidity的字符串库，了解如何实现string的concat。 + +##### 2. 内存分配方式 + +既然内存用于存储对象，就必然涉及到内存分配方式。memory的分配方式非常简单，就是顺序分配。下面我们将分配两个对象，并查看它们的地址： + +``` +function memAlloc() public view returns(bytes32, bytes32){ + string memory str = "aaa"; + string memory str2 = "bbb"; + bytes32 p1; + bytes32 p2; + assembly{ + p1 := str + p2 := str2 + } + return (p1, p2); +} +``` + +运行此函数后，返回结果将包含两个数据字： + +``` +0: bytes32: 0x0000000000000000000000000000000000000000000000000000000000000080 +1: bytes32: 0x00000000000000000000000000000000000000000000000000000000000000c0 +``` + +这说明，第一个字符串str1的起始地址是0x80，第二个字符串str2的起始地址是0xc0，之间64字节，正好是str1本身占据的空间。此时的内存布局如下，其中一格表示32字节（一个数据字，EVM采用32字节作为一个数据字，而非4字节）： + + + +- 0x40~0x60：空闲指针，保存可用地址，本例中是0x100，说明新的对象将从0x100处分配。可以用mload(0x40)获取到新对象的分配地址。 +- 0x80~0xc0：对象分配的起始地址。这里分配了字符串aaa +- 0xc0~0x100：分配了字符串bbb +- 0x100~...：因为是顺序分配，新的对象将会分配到这里。 + +#### 状态存储 + +顾名思义，状态存储用于存储合约的状态字段。从模型而言，存储由多个32字节的存储槽构成。在前文中，我们介绍了Demo合约的set函数，里面0x0表示的是状态变量_state的存储槽。所有固定长度变量会依序放到这组存储槽中。对于mapping和数组，存储会更复杂，其自身会占据1槽，所包含数据则会按相应规则占据其他槽，比如mapping中，数据项的存储槽位由键值k、mapping自身槽位p经keccak计算得来。从实现而言，不同的链可能采用不同实现，比较经典的是以太坊所采用的MPT树。由于MPT树性能、扩展性等问题，FISCO BCOS放弃了这一结构，而采用了分布式存储，通过rocksdb或mysql来存储状态数据，使存储的性能、可扩展性得到提高。 + +## 结语 + +本文介绍了Solidity的运行原理，运行原理总结如下。首先，Solidity源码会被编译为字节码，部署时，字节码会以交易为载体在网络间确认，并在节点上形成合约；合约函数调用，如果是交易类型，会经过网络确认，最终由EVM执行。EVM是栈式虚拟机，它会读取合约的字节码并执行。在执行过程中，会与栈、内存、合约存储进行交互。其中，栈用于存储普通的局部变量，这些局部变量就是字节码的操作数；内存用于存储对象，采用length+body进行存储，顺序分配方式进行内存分配；状态存储用于存储状态变量。理解Solidity的运行方式及其背后原理，是成为Solidity编程高手必经之路。 \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/3_features/35_contract/solidity_presensation.md b/3.x/zh_CN/docs/articles/3_features/35_contract/solidity_presensation.md new file mode 100644 index 000000000..feadcf72c --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/35_contract/solidity_presensation.md @@ -0,0 +1,58 @@ +# 深入浅出Solidity + +作者：石翔｜FISCO BCOS 核心开发者 + +在只有比特币的年代，区块链能够实现简单的价值产生和转移，但却未出现更多的商业模式。以太坊给区块链带来了维度的提升，基于区块链的应用渐趋丰富，区块链的各种商业模式加速涌现。这其中很重要的原因，是以太坊给区块链带来了一套图灵完备的编程语言。 + +区块链的主要功能，是实现了多方的共识。在比特币中，需要共识的操作是固定的，是非图灵完备的。其共识的仅仅是价值所有者的改变。但以太坊上，开发者可以自己编写需要共识的逻辑，以太坊通过智能合约语言Solidity，实现了共识逻辑的自定义。 + +## Solidity 介绍 + +Solidity语言和Java存在着些许相似之处。在众多编程语言中，Java是发展较为成熟的。Java代码在Java虚拟机（JVM）执行。JVM屏蔽掉了操作系统的差异，使得Java成为一个跨平台的语言。一套Java代码可在Windows、Linux、Mac上通用，而不需要关心操作系统的差异。 + +Solidity与Java类似。代码写好后，都需要通过编译器将代码转换成二进制，在Java中，编译器是Javac，而对于Solidity，是solc。生成后的二进制代码，会放到虚拟机里执行。Java代码在Java虚拟机（JVM）中执行，在Solidity中，是一个区块链上的虚拟机EVM。 + + + +Solidity与Java的不同之处在于，Solidity是服务于区块链的语言，代码在区块链上执行。EVM是区块链上的一个执行器。每个区块链节点都有一个EVM。Solidity在EVM中被执行后，EVM对区块链的数据进行了改变。这些数据的改变交由共识算法去共识。同时，Solidity的操作仅限于EVM内部，不能访问外部不确定系统或数据，如系统时钟，网络文件系统等。 + +Solidity的设计目的，是给区块链提供一套统一的逻辑，让相同的代码跑在区块链的每个节点上，借助共识算法，让区块链的数据以统一的方式进行改变，达到全局一致的结果。 + +## Solidity 实现细节 + +以此处的Demo合约为例，合约中有一个全局变量m，并有一个函数add()，实现给全局变量m增加x数值的功能。 + + + +通过合约编译器solc，可将此合约编译成二进制。二进制的每个字（8 bit），表示一个EVM的操作码（OPCODE）。Demo合约编译出的二进制及其相应的OPCODE如下，实现了完整的Demo合约的功能，包括对合约的装载、合约接口的调用和异常处理的逻辑。其中，标红部分是add()方法的实现。 + + + +将add()函数的OPCODE的**标红部分**摘取出来，可看到其具体的实现思想与汇编代码相同，是一种基于堆栈式的操作。其中的SLOAD将区块链上指定位置的数据读入堆栈顶部，ADD实现将堆栈顶端的两个数据相加，SSTORE再将相加后放在堆栈顶部的结果写入区块链下一个区块的数据中，为下个区块的共识做准备。 + + + +在合约二进制被部署到区块链上后，通过发送交易调用合约里的方法。节点根据交易将合约代码装载入EVM中，并根据交易的传参执行合约上相应的函数add()。 + +EVM执行合约代码，从区块链上读入当前区块的数据，进行相加操作，并将结果写入下一个区块（等待共识的区块）对应的状态数据中。 + +此后，共识算法将待执行的区块共识落盘，区块高度增加，区块链上的数据完成更新。 + + + +上述步骤可见，Solidity的实现与当今已有的做法有着很多相似之处。编译，用的是传统的套路，将代码转换成虚拟机可执行的二进制；执行，也是与传统方式相同，借助堆栈作为缓冲区执行二进制代码。 + +## Solidity 局限与改进 + +Solidity由于是第一个大规模应用的智能合约语言，存在着一些有待改进的地方。 + +**Solidity不够灵活。**Solidity语言受到自身堆栈深度的限制，函数传参和局部参数的个数总和不能超过16个。要实现一些比较复杂的函数难免有些鸡肋。Solidity是一种强类型的语言，但其类型转换较为麻烦。将整型转换成字符串时需要转换成二进制再拼接。在字符串的操作上，缺少一些方便的函数。 + +**Solidity的性能较差。**在执行上，OPCODE的执行是一种用程序模拟的汇编执行器，而不是直接使用CPU的资源。在存储上，Solidity的底层存储单位是32字节（256 bits），对硬盘的读写要求较高，浪费了大量的存储资源。 + +**针对上述两点，FISCO BCOS提供了一种用C++写合约方式：预编译合约。开发者可以用C++编写智能合约逻辑，并将其内置在节点中。** + +预编译合约的调用方法与Solidity合约相同，通过合约地址即可直接调用。FISCO BCOS提供了参数解析，将调用的参数解析成C++可识别的格式。 + +预编译合约突破了Solidity语言的限制，借助强大的C++语言，可以灵活的实现各种逻辑，灵活性大大提高。同时，C++的性能优势也得到了很好的利用，通过预编译合约编写的逻辑，相比于Solidity语言来说，性能得到提升。 + diff --git a/3.x/zh_CN/docs/articles/3_features/36_cryptographic/ecdsa_analysis.md b/3.x/zh_CN/docs/articles/3_features/36_cryptographic/ecdsa_analysis.md new file mode 100644 index 000000000..15a770346 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/36_cryptographic/ecdsa_analysis.md @@ -0,0 +1,148 @@ +# 一个数字引发的探索——ECDSA解析 + +作者：李辉忠｜FISCO BCOS 高级架构师 + +FISCO BCOS交易签名算法基于ECDSA原理进行设计，ECDSA也是比特币和以太坊采用的交易签名算法。本文介绍ECDSA及椭圆曲线加密（ECC）相关知识、ECDSA的Recover机制和实现方式、FISCO BCOS交易签名和验签的底层原理。内容偏硬（shu）核（xue），欢迎对密码学原理、区块链底层原理感兴趣的开发者一起交流。 + +## 故事开始 + +故事要从以太坊中一个神奇的魔数开始说起。 + + + +以太坊黄皮书中，关于交易签名的阐述讲到两个特殊的数「27，28」，实际上是从「0，1」通过加了一个27演变得到「27，28」，所以本质上是一个特殊的数27。这个特殊的数字27代表了什么含义呢？一次侦探之旅开始了… + +## **这像是一个bug** + +搜索发现此前已有许多关于该问题的讨论，其中，Stack Exchange的一篇帖子指出这是一个设计bug。以太坊源码github上，也有一个相关issue，该issue被打上了「type:bug」的标签。 + + + + + +Stack Exchange帖子中有一个链接给出了修复该Bug的代码，请看下面截图（红框）。在注释说明和代码可见，fromRpcSig函数对27这个魔数进行了特殊处理。从RPC过来的签名中，v值如果小于27（可能是0-3），则直接加上27作为新v值，fromRpcSig函数通过这个方式兼容ECDSA原始v值（也就是recoveryID）和以太坊v值。 + + + +这真是以太坊设计的一个bug吗？回到刚才那个fromRpcSig的源代码文件，详细看其各接口实现，我们发现有这样一行代码「v: chainId ? recovery + (chainId * 2 + 35) : recovery + 27」，这行为v赋值的代码透露了三个信息，分别是魔数27、魔数35和ChainID。 + + + +于是，疑问更多了，魔数35是什么？ChainID又是什么？ + +## 这不像是一个Bug + +带着这些疑问，再一次查阅相关设计材料，我们看到，以太坊EIP155中描述了有关ChainID的设计。基于以太坊源码构建的网络，实际运行的链有很多，为了防止一条链的交易被提交上链到另一条链，造成重放攻击，引入了ChainID的设计，在块高2,675,000的位置进行分叉实现。 + + + +明白了ChainID的作用，另一个疑问又产生了——以太坊中，有NetworkID来区分不同网络，为什么还需要ChainID？这要从NetworkID和ChainID的作用范围来解释。NetworkID主要在网络层面进行链的隔离，节点在建立相互连接的时候需要交换NetworkID，拥有一致的NetworkID才能完成握手连接。ChainID是交易层面，防止不同网络的交易被交叉重复攻击。以太坊（ETH）和经典以太坊（ETC）的主网NetworkID都是1，需要通过 ChainID机制才能防止交易在ETH和ETC网络之间交叉重放，ETH主网的ChainID是1，ETC主网的ChainID是61。说到这里其实还是没有搞清楚为什么是27，为什么是35？我们在EIP github的Issue#155中看到Jan和Buterin的交流记录，看来27是来自比特币的产物。 + + + +顺藤摸瓜，打开electrum的github，我们在electrum/electrum/ecc.py中找到如下代码 + + + + + + + + + +从代码中可见，electrum在签名时，为原本只有0-3之间的recid（recoveryID），加上了27，还有一个压缩标记，如果有压缩则再加上4，recid的值范围在27-34。至此可知，27和35大概来源于此，以太坊继承比特币的设计，在比特币源码bitcoin/src/key.cpp的CKey::SignCompact函数中也确定了该实现方式，但是比特币为什么如此设计，仍未可知。 + +## **ECDSA才是“bug”** + +故事到这里，我们对以太坊代码中那个魔数27的前世今生有大概了解，但这仅仅是故事的开端，由此引发我们进一步思考一个问题：recoveryID是什么？为了解释清楚这个问题，我们需要从ECDSA算法着手，从数学角度理解其背后的原理。ECDSA是FISCO BCOS采用的交易签名算法，由此我们会发现，ECDSA算法有一种Recover机制，它才是真正“bug”级别的功能。 + +ECDSA（Elliptic Curve Digital Signature Algorithm）是基于椭圆曲线的数字签名算法。数字签名算法是采用公私钥体系实现类似写在纸上的普通签名，用于鉴别数字信息的方法，常见的数字签名算法包括DSA、RSA和ECDSA等。椭圆曲线密码（ECC）是基于椭圆曲线数学的公钥加密算法，建立在椭圆曲线离散对数困难问题之上，常用的协议有ECDH、ECDSA和ECIES等。椭圆曲线的参数可以有多种配置方式，也就存在多种不同的曲线，例如secp256k1、secp256r1、Curve25519等，不同曲线的安全性存在一些区别，在SafeCurves中有相关对比描述。 + +ECDSA算法主要包括以下四个关键功能： + +### 产生密钥GenKey + +- 选择一条椭圆曲线E_P(a,b)，选择基点G，G的阶数为n +- 选择随机数d ∈n为私钥，计算公钥Q = d⋅G + +### 签名算法Sign + +- 对消息m使用消息摘要算法，得到z=hash(m) +- 生成随机数k∈n，计算点(x, y)=k⋅G +- 取r=x mod n，若r=0则重新选择随机数k +- 计算s = k^−1(z+rd) mod n，若s=0则重新选择随机数k +- 上述(r,s)即为ECDSA签名 + +### 验证算法Verify + +使用公钥Q和消息m，对签名(r,s)进行验证。 + +- 验证r,s∈n +- 计算z = hash(m) +- 计算u_1 =zs^−1 mod n和u_2 = rs^−1 mod n +- 计算(x, y) = u1⋅G+u2⋅Q mod n +- 判断r == x，若相等则签名验证成功 + +### 恢复算法Recover + +已知消息m和签名(r,s)，恢复计算出公钥Q。 + +- 验证r, s∈n +- 计算R=(x, y)，其中x=r,r+n,r+2n...，代入椭圆曲线方程计算获得R +- 计算z = hash(m) +- 计算u_1 = −zr^−1 mod n和u_2 = sr^−1 mod n +- 计算公钥Q= (x’, y’)=u_1⋅G+u_2⋅R + +为了回答recoveryID的问题，我们重点关注「恢复算法Recover」。在计算R的步骤可以看到，存在多个x的取值可能性，导致存在多个R的可能性，因此计算得到的Q也存在多个可能的结果，需要通过和已知的公钥对比，确定哪一个Q是正确的。如果遍历x的所有可能都未找到正确的Q，说明该消息和签名是不对应的，或者是一个未知的公钥。 + +为了确定正确的Q，需要遍历x的所有可能取值，跑多轮Recover算法，这个时间开销是比较大的。**为了提高Recover的时间效率，采用空间换时间的思路，在签名中增加一个v值，用于快速确定x，避免遍历查找试探，这个v值就是recoveryID。** + +在区块链系统中，客户端对每笔交易进行签名，节点对交易签名进行验证。如果采用「验证算法Verify」，那节点必须首先知道签发该交易所对应的公钥，因此需要在每笔交易中携带公钥，这需要消耗很大带宽和存储。如果采用「恢复算法Recover」，并且在生成的签名中携带recoveryID，就可以快速恢复出签发该交易对应的公钥，根据公钥计算出用户地址，然后在用户地址空间执行相应操作。 + +这里潜藏了一个区块链设计哲学，区块链上的资源（资产、合约）都是归属某个用户的，如果能够构造出符合该用户地址的签名，等同于掌握了该用户的私钥，因此节点无需事先确定用户公钥，仅从签名恢复出公钥，进而计算出用户地址，就可以执行这个用户地址空间的相应操作。**FISCO BCOS基于这个原理设计实现了交易签名和验签**。 + +## **recoveryID的计算** + +关于JavaSDK性能优化的文章（[记一次JavaSDK性能从8000提升至30000的过程](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485438&idx=1&sn=2d68d0f051dd42a0c68dc9da39538ea9&chksm=9f2ef5e2a8597cf4a96620f95b16b734b0efd55d7463c4d0bf04b46b51acce4cf68794a480af&scene=21#wechat_redirect)）中提到一个关键优化点——recoveryID的计算，这里仔细展开讨论。 + +ECDSA签名（r,s），其中r是椭圆曲线上一个点kG (x, y)对应的x mod n，相当于签名信息中只留下了X轴坐标相关的值，丢弃了Y轴相关的值。在「恢复算法Recover」中尝试找回Y轴对应的值构造R，进而恢复出公钥。 + +由于r = x mod n，因此r,r+n,r+2n…都可能是合法的原始x值，不同的椭圆曲线存在不同数量这样合法的x值，FISCO BCOS采用的secp256k1曲线存在两个可能r, r+n。 + +每一个X轴坐标对应两个可能的Y坐标，因此FISCO BCOS中具备四种可能的R，(r, y) (r, -y) (r+n, y’) (r+n, -y’)。但是，对于一个r值存在两个X轴坐标的概率极低，低到几乎可以忽略，以太坊中就忽略了这两种小概率事件。 + +那这个小概率事件的概率具体有多小呢？这要从secp256k1曲线的参数说起，通常描述一个椭圆曲线的点（x,y）的时候，x和y的值是 mod p 的结果，p是曲线的参数，它是一个大素数，之前提到的n也是曲线的参数，等于这条曲线上点的数量（曲线上点的数量为n*h，h也是曲线参数，该曲线h=1），在secp256k1中，n和p的值非常接近，具体可见下图。 + + + +由于r = x mod n，x是mod p的结果，r是mod n的结果，x值的范围是[0, p-1]，r值的范围是[0, n-1]。如果r+n也是曲线上的点，则r的值必须小于p-n，概率为 (p-n) / p，大约为3.73*10^-39，这个概率是非常小的。 + +基于签名结果（r, s）和签名过程中生成的随机点（x, y）的y值，recoveryID的计算方式如下： + +1. id = y & 1; //「签名算法Sign」中kG点的y坐标，根据奇偶性设置id值，因为y是mod p的结果，其奇偶性与坐标轴的正负性是完全对应的 +2. id |= (x != r ? 2 : 0); // 小概率事件，如前文解释 +3. if (s > n / 2) id = id ^ 1; // 签名计算得出的s如果大于n/2就会取n-s作为s值，因此这里做相应转换，这两个转换是同时发生的 + +[JavaSDK性能优化](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485438&idx=1&sn=2d68d0f051dd42a0c68dc9da39538ea9&chksm=9f2ef5e2a8597cf4a96620f95b16b734b0efd55d7463c4d0bf04b46b51acce4cf68794a480af&scene=21#wechat_redirect)的文章就是基于这个计算公式，将遍历探寻recoveryID改为计算获得，大幅提升了性能。 + +## 后话 + +从一个神奇的数字开始，查阅相关资料，了解设计原理，进而闯入ECDSA的世界，在一堆数学公式中迷茫、游荡，问题一个接着一个。一开始雾里看花，似懂非懂，靠着处女座的洁癖精神，总算把心中疑问一一化解。精妙绝伦的密码协议，高深莫测的数学理论，做一个区块链码农，要学习的东西还很多。唯有苦其心志，劳其筋骨，善待每一个疑点，不放过每一处细节。总会有一天，那时拨开云雾见天日，守得云开见月明。 + +------ + +#### 参考资料 + +- [Ethereum yellow paper](https://ethereum.github.io/yellowpaper/paper.pdf) +- [Stack Exchange](https://ethereum.stackexchange.com/questions/78929/whats-the-magic-numbers-meaning-of-27-or-28-in-vrs-use-to-ecrover-the-sender/78930?newreg=a613981e27424bc4b1c2c0e00d939327) +- [ISSUE](https://github.com/ethereum/go-ethereum/issues/2053) +- [EIP155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md) +- [EIP155 Issue](https://github.com/ethereum/eips/issues/155) +- [ChainID](https://chainid.network) +- [ECC wiki](https://en.wikipedia.org/wiki/Elliptic-curve_cryptography) +- [ECDSA wiki](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) +- [Curve25519 wiki](https://en.wikipedia.org/wiki/Curve25519) +- [SafeCurves](https://safecurves.cr.yp.to/index.html) +- [ECC SEC1](http://www.secg.org/sec1-v2.pdf) +- [ECC SEC2](https://www.secg.org/sec2-v2.pdf) + diff --git a/3.x/zh_CN/docs/articles/3_features/36_cryptographic/elliptic_curve.md b/3.x/zh_CN/docs/articles/3_features/36_cryptographic/elliptic_curve.md new file mode 100644 index 000000000..aadcebc5b --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/36_cryptographic/elliptic_curve.md @@ -0,0 +1,143 @@ +# 一场椭圆曲线的寻根问祖之旅 + +作者：李辉忠｜FISCO BCOS 高级架构师 + +本文介绍密码学中常见的椭圆曲线以及他们之间的关系，介绍不同标准体系的命名规则，尝试描述椭圆曲线之间的家族演义关系。文章试图讲清椭圆曲线相关概念和功能，不涉及复杂的数学证明和推理，欢迎感兴趣的同学阅读。笔者主要参考Wikipedia和相关组织网站的信息进行整理，不排除出现纰漏的可能，欢迎专家批评指正。 + +## 一个可能你没关心过的问题 + +在[《一个数字引发的探索——ECDSA解析》](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485497&idx=1&sn=44ac5977abbf92bd81e9013433a59f69&chksm=9f2efa25a8597333575c8bf0642c2e312e54d23867644021c9b2e353963d405e1d945e2a067d&scene=21#wechat_redirect)中提到的椭圆曲线secp256k1，它有一些特性，可以快速计算出recoveryID。这个secp256k1为什么如此命名？不怕各位笑话，我在弄清楚它之前，经常拼写错，写成sec256pk1，seck256p1等。 + +## 咬文嚼字secp256k1 + +搞清楚secp256k1的命名含义其实很简单，搜索引擎可以快速为你定位到答案，它出自一个密码协议标准，每一个字母和数字都代表着特定含义，我们来逐一解析。 + + + +### 1、密码协议标准 + +第一部分是「sec」，sec是Standards for Efficient Cryptography 的简称，是SECG发布的一种密码学协议标准。SECG发布的「SEC 1」和「SEC 2」两个关于椭圆曲线的协议标准，在「SEC 2」中有详细说明secp256k1以及其他曲线的参数定义。除了「sec」，还有众多其他关于椭圆曲线的协议标准，从「SafeCurve」中可以看到有下列不同类型的标准。 + + + + +「SafeCurve」此处较久没有更新，有些标准已经更新了多次，例如NIST关于数字签名的标准 FIPS 186目前在用的是第四版，第五版也在起草中了，从「NIST」官网中可见。NIST是美国的国家标准技术研究所（National Institute of Standards and Technology），因此，NIST的标准也是美国标准。 + + + +「NIST FIPS 186-4」标准中定义了若干椭圆曲线标准，例如NIST P-256、NIST P-384等，其中开头NIST也代表密码协议标准的名字。后续描述都是围绕这两个标准来解析。 + +### 2、有限域 + +第二部分是「p」，p表示该椭圆曲线是基于素数有限域Fp。有限域是离散数学中的概念，此处不做展开，简单来说，它是一个由有限数量元素组成的集合，元素之间可以进行加法和乘法计算，具备一些独特的属性。密码学中使用椭圆曲线都是基于有限域的，除了素数有限域Fp之外，还有另一种特征为2的有限域F2m（因格式问题，2m应为2的m次方，下同） ，Fp的大小（元素个数）为p，F2m的大小为2m。基于Fp的椭圆曲线为： + + + + + +基于F2m的椭圆曲线为： + + + + +在「SEC 2」中还定义了sect163k1、sect163r1等曲线，其中，t表示的是该曲线基于F2m。在「NIST FIPS 186-4」中定了P-256、B-163等曲线，P-表示基于Fp，B-表示基于F2m。 + +### 3、有限域大小 + +每个椭圆曲线E都有若干关键参数，包括阶为n的基点G和系数h等，其中，n为一个大素数，n*h为椭圆曲线上点的数量。为了计算效率考虑，h通常设置为1、2或4。通俗地讲，如果椭圆曲线上的点数量越多，那么这条椭圆曲线的安全度就越高，因此n的取值是影响曲线安全的关键。椭圆曲线又都是基于有限域的，曲线上的点都是有限域中的元素，因此，有限域大小决定了曲线安全度。第三部分「256」就是有限域大小的表现形式，还有更多其他如192、224、384等，在「NIST FIPS 186-4」中有个表格展现了Fp 和F2m 两个域的各种不同大小配置。 + + + +SEC标准在这块的设置和NIST标准类似，我们会看到p系列的曲线有p192、p224、p256（secp256k1就是其中一种）、p384和p521，t/B系列有t163/B-163、t233/B-233等。 + +### 4、Koblitz Curve + +第四部分「k」表示该曲线是Koblitz Curve，从「SEC 2」中可以看到还有此处标记为r的曲线（如secp256r1），r表示该曲线是伪随机曲线Pesudo-Random Curve。Koblitz Curve命名源自数学家「Neal Koblitz」，它是一种特殊的曲线，它的一些参数是精心挑选设置的。Koblitz Curve具有自同态的性质，可以通过优化大幅提升计算效率。相比之下，Pesudo-Random Curve的对应参数是通过随机种子计算出来的，有标准的检验算法可以检测所有参数是随机种子产生而来。对应「**2、有限域**」中的两个椭圆曲线，Koblitz Curve分别简化为 + + + + + +例如，secp256k1对应的曲线b=7，即曲线表示为 + + + + + +在「NIST FIPS 186-4」中Koblitz Curve曲线以「K-」标记开头，分别有K-163、K-233等。 + +### **5、末位标记** + +到了第五部分「1」，这是代表在前4个条件下提供了多种推荐参数设置，在SEC标准中大部分该位都是1，即只提供一种推荐参数，sect163r2是一个例外。下面把SEC和NIST两个标准推荐的曲线分别列一下，二者有较大部分是相同的参数设置。 + + + +上述表格中，同一行中SEC和NIST都出现的，两个曲线虽然名字不同，但参数完全相同，也就是说其实一样的。橙色底纹的几个SEC曲线没有对应的NIST曲线，因此SEC标准包含的曲线比NIST多一些，本文开头提到的secp256k1就是SEC单独存在的。说到这里，不得不提一个正经八卦。据说，NIST推荐的Pesudo-Random Curve，也就是P和B系列，并没有公布随机数挑选规则，外界存在一种疑虑，可能NSA（美国国家安全局）掌握了后门，能够轻易破解这些密码协议。有兴趣的同学可以搜索「Dual_EC_DRBG后门」，更大的八卦是据说中本聪选择secp256k1作为比特币签名算法的曲线，而没有选择更常用的secp256r1，也是因为这个潜藏的风险。 + +## **椭圆曲线族谱** + +调研发现，「STD」记录了比「SafeCurve」更为详细的标准和曲线，感觉这可以算是椭圆曲线族谱了。翻阅该网站记录的所有曲线，发现绝大部分还是基于「（2）有限域」中的曲线，推荐的参数不同而已。但是，在「other」中存在几种例外，E-222采用Edward Curve，Curve25519采用Montgomery Curve，Ed448采用Twisted Edward Curve。 + +Edward Curve是什么？Montgomery Curve又是怎样的？Edward与Twisted Edward Curve又有什么关系？上述问题再一次触碰到我的知识盲区，所以接下来只好以截图为主，内容源自Wikipedia，如果觉得看着有点晕，可直接跳过看结论。「Edward Curve」定义如下： + + + +「Montgomery Curve」定义如下： + + + +「Twisted Edward Curve」定义如下： + + + +「Curve25519」定义如下： + + + +「Ed25519」的定义如下： + + + +根据Wikipedia，大概可以整理出这么几个信息： + +1. Edward Curve是Twisted Edward Curve中的一种 +2. Twisted Edward Curve和Montgomery Curve可以互相转换 +3. Edward Curve和Montgomery Curve这两种曲线都具有特殊属性，例如能够为计算加速 +4. Curve25519是一种曲线，Ed25519是一种签名算法 +5. Curve25519又是精选的Montgomery Curve，具有更高的计算效率 +6. Curve25519和Ed25519采用的曲线是一致的，一个是Montgomery表现形式，一个是Twisted Edward Curve表现形式 +7. 25519的取名来自于该曲线的有限域参数p=2255- 19 + +在阅读Wikipedia的过程中发现一个名字「Weierstrass equation」，原来它才是这些曲线的鼻祖，在一个域k上的任何一个平面曲线，都可以表示成Weierstrass equation。 + + + +不难发现，前面提到过的各个公式都是Weierstrass equation的一种演化版本（Twisted Edward Curve看起来不是，但是它可以转换到Montgomery Curve，本质上也一样）到此，为椭圆曲线寻根问到祖，并且从「STD」也获知了椭圆曲线家族的族谱。 + +「STD」中罗列了多个其他标准，例如Brainpool曲线系列、BN曲线系列、MNT曲线系列等，这些系列的背后都代表了一种独特的曲线生成哲学，或是为了提供可验证的随机数，或是为了提供满足Paring的特性，或是为了提高抗攻击的能力等等，每一份精心选择的参数都是一群数学家们巧夺天工的设计。 + +## **后话** + +古有拆文解字，参透汉字玄机，道破人生天机；而今咬文嚼字，摸清椭圆原理，揭开曲线家谱。始于名字，解码secp256k1，厘清标准；终于名字，问祖weierstrass，致敬大神。 + +通过了解椭圆曲线之间的内在关系，对其设计有了更多一点的理解。知道的更多了，不知道的也更多了，那些特殊曲线的数学原理是什么？为什么具有更高的计算效率？性能能提升多少？… 又是一个深夜，拥抱最新的收获，夹杂更多的困惑。电脑中正好在播放“把太细的神经割掉，会不会比较睡得着…” + +------ + +#### 参考资料 + +- [SEC1](https://www.secg.org/sec1-v2.pdf) +- [SEC2](https://www.secg.org/sec2-v2.pdf) +- [NIST](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf) +- [STD](https://neuromancer.sk/std/) +- [SafeCurves](https://safecurves.cr.yp.to) +- [Koblitz Curves](https://link.springer.com/content/pdf/10.1007%2F3-540-46766-1_22.pdf) +- [Weierstrass Equation](https://www.lmfdb.org/knowledge/show/ec.weierstrass_coeffs) +- [Montgomery Curve wiki](https://en.wikipedia.org/wiki/Montgomery_curve) +- [Twisted Edward Curve wiki](https://en.wikipedia.org/wiki/Twisted_Edwards_curve) +- [Edward Curve wiki](https://en.wikipedia.org/wiki/Twisted_Edwards_curve) +- [ECDSA wiki](https://en.wikipedia.org/wiki/EdDSA#Ed25519) +- [Curve25519 wiki](https://en.wikipedia.org/wiki/Curve25519) +- [Curve25519 paper](http://cr.yp.to/ecdh/curve25519-20060209.pdf) +- [Ed25519 paper](http://ed25519.cr.yp.to/ed25519-20110926.pdf) + diff --git a/3.x/zh_CN/docs/articles/3_features/36_cryptographic/index.md b/3.x/zh_CN/docs/articles/3_features/36_cryptographic/index.md new file mode 100644 index 000000000..831fa8948 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/36_cryptographic/index.md @@ -0,0 +1,23 @@ +### 密码算法和协议 + +国密算法 支持 + +国密SSL 支持 + +哈希算法：Keccak256、SM3 + +对称加密算法：AES、SM4 + +非对称加密算法：ECDSA、SM2 + +非对称加密椭圆曲线：secp256k1、sm2p256v1 + +```eval_rst +.. toctree:: + :maxdepth: 1 + + national_cryptography_features.md + national_cryptography_deployment_example.md + ecdsa_analysis.md + elliptic_curve.md +``` diff --git a/3.x/zh_CN/docs/articles/3_features/36_cryptographic/national_cryptography_deployment_example.md b/3.x/zh_CN/docs/articles/3_features/36_cryptographic/national_cryptography_deployment_example.md new file mode 100644 index 000000000..31601f8f0 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/36_cryptographic/national_cryptography_deployment_example.md @@ -0,0 +1,156 @@ +# FISCO BCOS国密版部署示例 + +作者：刘海锋｜FISCO BCOS开源社区贡献者 + +随着区块链的底层技术被不断关注，越来越多的项目开始使用区块链来固化数据。近期因为工作需要，对比了多家国内的区块链产品，实际部署了几个区块链系统后，最终选择了FISCO BCOS。在实际部署的过程中，我总结出了这一套可供实际项目使用的部署流程，供区块链爱好者参考。 + +## 设计覆盖实际项目使用情况的一套场景 + +在决定使用FISCO BCOS时，为了尽可能覆盖到实际项目使用的情况，我设计了一套场景，里面包含了大多数实际情况，并且遇坑填坑，最终按照设计的场景部署成功了。以下是我设计的场景： + +1、假设多家机构组成联盟，每家机构都派出代表进驻联盟委员会(在本次测试组网部署中，假设有ABCD四家机构)。 + +2、联盟决定使用国密版FISCO BCOS组建联盟链。 + +3、联盟委员会确定联盟链组网模式(主要确认节点数量、节点分布、群组构成情况和信息交换方式等)。 + +本次测试，使用同一服务器的不同端口模拟不同节点，使用拷贝指令模拟信息交换方式(实际部署可通过U盘、邮件、网络消息传输等联盟成员信任的方式传递)，组网模式假设如下： + + + +4、联盟委员会提供联盟链的链证书(自建或向CA公司申请，本次测试使用FISCO BCOS提供的企业级部署工具自建)。 + +5、联盟的每家机构向联盟委员会申请对应机构的机构证书(本次测试使用FISCO BCOS提供的企业级部署工具自建)。 + +6、联盟每个机构，根据联盟委员会确定的联盟链组网模式，使用FISCO BCOS提供的企业级部署工具，生成机构下属的节点部署程序，并按组网模式修改对应节点部署程序的配置文件。 + +7、联盟所有机构部署并启动下属节点程序，组成联盟链。 + +8、组网变动： + +- 机构A认为自己下属节点太多，消耗资源，准备从群组1移除节点2变为游离节点，不参与共识。同时为了提高业务处理效率，将节点1设置为观察节点，不参与共识。 + +- 机构D想加入群组2，并添加机构D下属节点： + + + +- 机构D和机构B想用节点3和节点5组成新群组：群组3。 + +9、机构A和机构D向联盟委员会提出组网变动申请。 + +10、联盟委员会同意机构A和机构D的组网变动申请。 + +11、机构A开始组网变动操作： + +- 群组1的机构A或B根据联盟委员会同意的机构A组网变动申请，使用控制台或SDK发送节点2退出和节点1转换为观察节点的指令，完成机构A的组网变动请求。 + +12、机构D开始组网变动操作： + +- 第5步中，机构D已向联盟委员会申请机构D的机构证书，现在，机构D使用FISCO BCOS提供的企业级部署工具，生成机构D下属的节点部署程序，根据新的组网模式，修改节点部署程序的配置文件，启动节点，准备加入联盟链。 + +- 机构D向群组2的机构B或C发送节点5入网请求，等待机构B或C使用控制台或SDK发送节点5加入群组2共识的指令。 + +- 机构B或C根据联盟委员会同意的机构D组网变动申请，使用控制台或sdk发送节点5加入群组2共识的指令。 + +- 机构D和机构B根据联盟委员会同意的群组3组网变动申请，组建群组3。 + +13、结束。 + +## 部署联盟链准备工作 + +FISCO BCOS为实际项目中部署和使用联盟链提供了企业级部署工具，里面包含了部署联盟链所需的各种操作。联盟委员会可以使用企业级部署工具自建生成链证书并为联盟成员机构颁发自建的机构证书，联盟成员机构可以使用企业级部署工具生成群组的创世区块和机构下属的节点部署程序。 + +本次测试模拟联盟链的实际搭建过程，测试部署目录(Linux)为：/usr/local/rc3-test-BCOS/，以下简称为目录rc3-test-BCOS。 + +- 环境要求：python 2.7+/3.6+，openssl 1.0.2k+。 + +- 获取企业级部署工具：git clone https://github.com/FISCO-BCOS/generator.git，得到企业级部署工具根目录generator。 + +```eval_rst +.. note:: + - 如果因为网络问题导致长时间无法下载企业级部署工具，请尝试 `git clone https://gitee.com/FISCO-BCOS/generator.git` +``` + +- 将generator上传(或直接clone)为/usr/local/rc3-test-BCOS/generator/，以下简称为目录generator。 + +- 保证generator的操作权限：chmod -R 777 /usr/local/rc3-test-BCOS/generator/ + +- 安装企业级部署工具(一定要保证安装正确)： + +``` + cd generator + ./scripts/install.sh + + #查看版本： + ./generator -v + > INFO | v1.0.0-rc3 +``` + +- 下载国密版FISCO BCOS： + +``` + cd generator + ./generator --download_fisco ./meta -g +``` + +-g参数表示国密，去掉-g则下载的是普通版FISCO BCOS，执行完该命令，国密版FISCO BCOS会下载到generator/meta/下。 + +- 查看国密FISCO BCOS版本： + +``` +cd generator +./meta/fisco-bcos -v +``` + +``` +> FISCO-BCOS Version : 2.0.0-rc3 gm +> Build Time : 20190613 15:24:38 +> Build Type : Linux/clang/RelWithDebInfo +> Git Branch : master +> Git Commit Hash : a43952c544aa8252f7ac965e310148c099510410 +``` + +可以看到，本次测试部署使用的是` v1.0.0-rc3`版本的企业级部署工具，`2.0.0-rc3 gm`版本的FISCO BCOS(似乎与rc2版本的部署流程相同)。 + +## 证书说明 + +FISCO BCOS国密版的链证书和机构证书需要两套，分别为国密证书和普通版证书。 + +- 证书链： + +``` +> 链证书——机构证书----节点证书 +> +> 链证书——机构证书----sdk证书 +``` + +- 证书支持自建、CA公司申请，企业级部署工具底层使用`openssl`工具自建生成，如果要用CA公司申请的证书，可直接把证书文件的名称改为规定的名称即可。 +- 链证书普通版`ca.crt`，对应的私钥`ca.key`。链证书国密版`gmca.crt`，对应的私钥`gmca.key`。 +- 机构证书普通版`agency.crt`，对应的私钥`agency.key`，机构证书国密版`gmagency.crt`，对应的私钥`gmagency.key`。 +- 说明：链证书私钥需要联盟委员会保管，机构证书的私钥由各机构自行保管，证书及私钥的意义这里不做延伸。 +- 使用FISCO BCOS企业级部署工具时，所有需要证书的操作都需要将链证书和机构证书(.crt文件)放置在`generator/meta/`下。 + +## 部署联盟链详细步骤（附每一步代码） + +经过尝试，我按以下操作顺序执行，成功部署了一个符合上面场景描述的联盟链。由于步骤十分详细，而且含有大量代码，所以单独放在此处链接里：[《手把手教你实操部署FISCO BCOS联盟链》](https://blog.csdn.net/FISCO_BCOS/article/details/95496272)（温馨提示：此文附每一步代码演示，复制链接到PC端打开体验为佳。） + +## 关键步骤总结 + +1. 联盟委员会及相关成员确定组网模式； +2. 相关的各种证书的颁发； +3. 准备FISCO BCOS企业级部署工具； +4. 根据组网模式，各机构收集所要组建群组的下属节点的p2p连接信息； +5. 各群组生成并分发创世区块(文件)； +6. 各机构生成机构下属加点的节点部署程序； +7. 各机构根据组网模式，修改下属节点部署程序中的配置文件，启动联盟链。 + +## 写在最后 + +至此，这套可供实际项目使用的部署流程就搭建完成了。我在刚开始部署时，会觉得整个系统的部署很复杂，多次部署之后，觉得流程挺合理挺清楚的，因为在实际场景中不是一个人在操作，是整个联盟各机构一起在协同，按联盟链该有的组织形式去部署其实很快，多次部署中我也总结了一些经验： + +- 首先是多看官方技术文档，梳理出了大致流程。 +- 其次就是解决证书的问题，这个问题对我来说如鲠在喉，在实际业务中，证书必须是具有法律效力，由CA公司颁发的。我认为证书的生成，可以考虑从企业级部署工具中分离出来，作为搭建测试链的一个工具。当然，在实际业务中，如果不重视数据的法律效应，也可以只把证书当做一个加密的公私钥对看待。 +- FISCO BCOS目前处于快速迭代开发的阶段，推出的一些功能都很好，比如区块链浏览器。 +- 适配支持FISCO BCOS底层平台的区块链中间件平台WeBASE，功能全面，上手快速，节约大量时间都很好。 + +整体而言FISCO BCOS体验很不错，期待看到FISCO BCOS更多的突破。 \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/3_features/36_cryptographic/national_cryptography_features.md b/3.x/zh_CN/docs/articles/3_features/36_cryptographic/national_cryptography_features.md new file mode 100644 index 000000000..6068e63bf --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/36_cryptographic/national_cryptography_features.md @@ -0,0 +1,161 @@ +# FISCO BCOS的国密特性 + +作者：李昊轩｜FISCO BCOS 核心开发者 + + +> 安全是信任的保障，算法则是安全的基础，节点通信信道的建立、签名的生成、数据的加密等，都需要用到密码学的相应算法。FISCO BCOS采用国密算法，实现安全可控的区块链架构。 + +本期文章讲解国密算法的相关概念，以及国密算法在区块链中的应用。 + +## 区块链中的密码学 + +在区块链中，一般使用密码学的场景有以下几种： + +### 1. 数据哈希算法 + +哈希函数是一类单向函数，作用是将任意长度的消息转换为定长的输出值，具有单向性、无碰撞性、确定性、不可逆的性质。 +在区块链中，哈希函数用于将消息压缩成定长的输出，以及保证数据真实性，确保数据未被修改。 + +### 2. 数据加密解密算法 + +加解密算法主要分为对称加密和非对称加密两种： +- 对称加密具有速度快、效率高、加密强度高等特点，使用时需要提前协商密钥，主要对大规模数据进行加密，如FISCO BCOS的节点数据落盘时进行的加密。 +- 非对称加密具有无需协商密钥的特点，相较于对称加密计算效率较低，存在中间人攻击等缺陷，主要用于密钥协商的过程。 + +针对不同的需求，两者可以互相配合，组合使用。 + +### 3. 消息签名的生成和验证 + +在区块链中，需要对消息进行签名，用于消息防篡改和身份验证。如节点共识过程中，需要对其他节点的身份进行验证，节点需要对链上交易数据进行验证等。 + +### 4. 握手建立流程 + +前面我们讲过[**节点TLS的握手过程**](https://mp.weixin.qq.com/s?__biz=MzU5NTg0MjA4MA==&mid=2247484845&idx=1&sn=c943c8a3f55a060991ffafec8bbdb27b&scene=21#wechat_redirect)（点击直达），其中需要使用到密码组件和数字证书，都需要使用到相应的密码学算法。 + +## FISCO BCOS的国密算法 + +国密算法由国家密码局发布，包含SM1\ SM2\ SM3\ SM4\等，为我国自主研发的密码算法标准。 +为了充分支持国产密码学算法，金链盟基于国产密码学标准，实现了国密加解密、签名、验签、哈希算法、国密SSL通信协议，并将其集成到FISCO BCOS平台中，实现了对国家密码局认定的商用密码的完全支持。 +国密版FISCO BCOS将交易签名验签、p2p网络连接、节点连接、数据落盘加密等底层模块的密码学算法均替换为国密算法。 + +1. 节点TLS握手中采用国密SSL算法； +2. 交易签名生成，验证过程采用国密SM2算法； +3. 数据加密过程中采用国密SM4算法； +4. 数据摘要算法采用国密SM3算法。 + +国密版FISCO BCOS节点之间的认证选用国密SSL 1.1的ECDHE_SM4_SM3密码套件进行SSL链接的建立，差异如下表所示： + +| | **OpenSSL** | **国密SSL** | +| ------------ | ---------------------------------------- | ---------------------------------------- | +| 加密套件 | 采用ECDH、RSA、SHA-256、AES256等密码算法 | 采用国密算法 | +| PRF算法 | SHA-256 | SM3 | +| 密钥交换方式 | 传输椭圆曲线参数以及当前报文的签名 | 当前报文的签名和加密证书 | +| 证书模式 | OpenSSL证书模式 | 国密双证书模式，分别为加密证书和签名证书 | + +国密版与标准版FISCO BCOS在数据结构上的差异如下： + +| **算法类型** | **标准版**FISCO BCOS | **国密版**FISCO BCOS | +| ------------ | ---------------------------------------------- | -------------------------------------------------- | +| 签名 | ECDSA (公钥长度: 512 bits, 私钥长度: 256 bits) | SM2 (公钥长度：512 bits, 私钥长度：256 bits) | +| 哈希 | SHA3 (哈希串长度: 256 bits) | SM3 (哈希串长度: 256 bits) | +| 对称加解密 | AES (加密秘钥长度: 256 bits) | SM4 (对称密钥长度: 128 bits) | +| 交易长度 | 520bits(其中标识符8bits,签名长度512bits) | 1024bits(128字节，其中公钥512bits,签名长度512bits) | + +## 开启国密特性 + +需要使用国密版FISCO BCOS特性时，有以下几点需要注意： + +### 1. 搭建国密版FISCO BCOS区块链 + +搭建国密版FISCO BCOS的区块链方式主要有2种： + +##### (1). 使用build_chain.sh脚本搭建 + +buildchain.sh脚本的-g为国密编译选项，使用成功后会生成国密版的节点。默认从GitHub下载最新稳定版本可执行程序，操作方式： + +```bash +curl -LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v2.9.1/build_chain.sh && chmod u+x build_chain.sh +``` + +```eval_rst +.. note:: + - 如果因为网络问题导致长时间无法下载build_chain.sh脚本，请尝试 `curl -#LO https://gitee.com/FISCO-BCOS/FISCO-BCOS/raw/master-2.0/tools/build_chain.sh && chmod u+x build_chain.sh` +``` + +运行以下命令，搭建四节点的国密版FISCO BCOS联盟链 + +```bash +./build_chain.sh -l 127.0.0.1:4 -p 30300,20200,8545 -g +``` + +执行成功后，会搭建本地四节点的国密版FISCO BCOS联盟链。 + +##### (2). 使用企业级部署工具搭建 + +企业级部署工具generator的-g命令为国密相关操作，用户需要在生成相关证书，下载二进制等操作的过程中附带-g选项，操作方式： + +**参考教程**：https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/tutorial/enterprise_quick_start.html + +``` +./generator --download_fisco ./meta -g +./generator --generate_chain_certificate ./dir_chain_ca -g +./generator --generate_agency_certificate ./dir_agency_ca ./dir_chain_ca agencyB -g +... +``` + +以下操作与教程中类似 + +``` +./generator --build_install_package ./meta/peersB.txt ./nodeA -g +``` + +### 2. 使用国密版sdk/控制台 + + +国密版sdk和控制台的操作命令与普通版相同，Web3SDK和1.x版本控制台在启用国密特性时需要做如下操作： + +- (1). 将applicationContext.xml中的encryptType设置为1； +- (2). 加载私钥时需要加载国密版的私钥； +- (3). 控制台还需要获取国密版jar包。 + +```eval_rst +.. note:: + java sdk和2.6.0+版本的控制台启用国密算法时不需要额外配置 +``` + +### 3. 开启国密版落盘加密功能 + +国密版落盘加密需要同时对节点conf/gmnode.key和conf/origin_cert/node.key进行加密，其余操作与普通版相同。 + +## 总结 + +FISCO BCOS中的主要算法特性对比如下： + +| | **标准版****FISCO BCOS** | **国密版****FISCO BCOS** | +| ------------ | ------------------------ | ------------------------ | +| SSL链接 | Openssl TLSv1.2协议 | 国密TLSv1.1协议 | +| 签名验证 | ECDSA签名算法 | SM2签名算法 | +| 消息摘要算法 | SHA-256 SHA-3 | SM3消息摘要算法 | +| 落盘加密算法 | AES-256加密算法 | SM4加密算法 | +| 证书模式 | OpenSSL证书模式 | 国密双证书模式 | +| 合约编译器 | 以太坊solidity编译器 | 国密solidity编译器 | + +------ + +### 「用户提问」 + +**Q**：**王刚+云飞微联网+珠海**：请问solidity编译器也需要用到密码学算法吗？ + +**A**：**李昊轩**：solidity中的abi会用到哈希，需要底层和合约编译器都使用相同的SM3算法。 + +**Q**：**陈小军-江南科友-广州**：请问一下国密TLS协议套件是自己实现的吗，还是用了开源的？ + +**A**：**李昊轩**：国密TLS我们采用的是TASSL开源库。 + +**Q**：**腾龙(何直群)**：如果使用国密的节点，因为签名算法都换了，是不是 RPC SDK 都会不一样了？ + +**A**：**李昊轩**：是的， sdk也需要开启国密特性。 + +**Q**：**KHJ**：目前落盘加密的私钥是如何处理的？ + +**A**：**meng**：要自己保存，可以参考这里的[说明](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/storage_security.html) \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/3_features/37_safety/access_control_glance.md b/3.x/zh_CN/docs/articles/3_features/37_safety/access_control_glance.md new file mode 100644 index 000000000..a2f2b1742 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/37_safety/access_control_glance.md @@ -0,0 +1,162 @@ +# FISCO BCOS权限控制一览 + +作者：张开翔｜FISCO BCOS 首席架构师 + +**作者语** + +在多方参与的联盟链上，各方分工协作的同时也要做到**职责分明、各司其职**。链的管理者没有必要“既当裁判又当运动员”的参与业务交易，只参与交易的用户也不必很操心智能合约的开发部署。同时，"DO分离"（开发和运维分离）已经是业界成熟的做法，越权操作会带来风险，最终可能破坏信誉和造成资产损失。 + +清晰、易用、周全的**权限控制能力**，无论是对于信息安全，还是为了完善联盟治理，都至关重要。 + +本期文章讲的就是FISCO BCOS权限控制这点事，作者从FISCO BCOS的权限分类、典型的联盟链角色设计、权限控制操作基本步骤等角度进行了解析。 + +```eval_rst +.. note:: + 从 ``v1.0.9`` 开始，控制台不再支持 ``grantPermissionManager`` 命令，请使用 ``grantCommitteeMembers`` 和 ``grantOperator`` 等区块链委员权限管理相关的命令替代该命令。 +``` + +## FISCO BCOS的权限分类 + +FISCO BCOS在链刚建立起来的时候，为了方便快速地进行开发和体验，默认并没有做任何权限控制。但如果这条链是用来提供企业级服务，则从一开始就要设计权限控制的策略并落实之。 FISCO BCOS的权限分类： + + + + +### 1. 链管理员权限 + +即**分配权限的权限**，如定义账户A作为链管理员，A可以为账户B、C、D分配权限；可以设置多个管理员，如果不设置管理员，任何账户都可以无差别修改各种权限。 + +### 2. 系统管理权限 + +目前包括4种： + +- 节点管理权限（增删共识节点或观察节点） +- 系统参数修改权限 +- 修改CNS合约命名权限 +- 能否部署合约和建表的权限 + +其中部署合约和建表是“二合一”的控制项，在使用CRUD合约时，我们建议部署合约的时候一起把合约里用到的表建了（写在合约的构造函数里），否则接下来读写表的交易可能会遇到“缺表”错误。如果业务流程需要动态创建表，动态建表的权限也应该只分配给少数账户，否则链上可能会出现各种废表。 + +### 3. 用户表权限 + +以用户表为粒度，控制某些账户能否**改写某个用户表**，以避免用户表被他人意外修改，这个权限要依赖FISCO BCOS的CRUD合约写法。另外，**读用户表**不受权限控制；如果要进行数据的隐私控制，需要引入数据加密、零知识等技术。 + +### 4.合约接口权限 + +一个合约可以包括多个接口，由于合约里的逻辑和业务密切相关，接口粒度的权限控制由开发者实现，开发者可对msg.sender或 tx.orgin进行判断，决定是否允许本次调用继续处理。 + +FISCO BCOS的控制台提供了一系列控制权限的命令，可以很方便的为用户**授予（grant）、取消(revoke)、查看(list)**各种权限，可以参见控制台的文档。 + +## 联盟链中典型的权限管理角色设计 + +在联盟链里，不同的角色各司其职，分工协作，典型的角色设计可参照： + +### 1. 链管理员 + +通常是参与链的多方共同选出一个委员会，一个或多个机构可获得管理员权限，以进行人员管理和权限分配。链管理员并不负责任节点管理，修改系统参数，部署合约等系统管理操作。 + +### 2. 系统管理员 + +指定的业务运营人员或系统运维人员，按需分配各种权限，负责日常的链上管理，包括节点增删，系统参数修改等。由链管理员根据大家约定的治理规则来分配权限，比如只允许指定的账户部署合约，则给他们设定合约部署权限，这样其他账户则不能随意部署合约了。 + +### 3.交易用户 + +用户向区块链发送业务交易请求，业务交易主要是调用合约和读写用户表，可以根据业务逻辑，结合用户表权限和合约接口权限来进行灵活的控制。 + +### 4. 监管方 + +给监管方分配哪些系统和用户表权限，可参考具体的监管规则，如监管方只读所有数据，则不用设定特殊的权限。 + +管理不同角色的帐户又是另一个复杂的问题，既要清晰区分，又要便于使用，还要保证帐号安全；万一帐号丢失后要支持找回，帐号泄漏后重置，以后会另文介绍。 + +## 权限控制操作基本步骤 + +### step1 + +首先采用控制台grantPermissionManager命令设置一个或多个链管理员角色。 **Tips**：登陆控制台时，命令行里输入的是私钥明文，而使用grantPermissionManager命令输入的是“账户地址”，要注意区分。如： + +用户私钥：3bed914595c159cbce70ec5fb6aff3d6797e0c5ee5a7a9224a21cae8932d84a4 + +对应地址：0xf1585b8d0e08a0a00fff662e24d67ba95a438256 + +那么登陆控制台的命令行是： + +``` +./start.sh 1 3bed914595c159cbce70ec5fb6aff3d6797e0c5ee5a7a9224a21cae8932d84a4 +``` + +分配管理员权限的命令行是： + +``` +grantPermissionManager 0xf1585b8d0e08a0a00fff662e24d67ba95a438256 +``` + +当这个账户得到了链管理员权限后，退出当前控制台或切到另一个终端窗口，用这个账户的私钥登陆一次，即可作为链管理员进行后续的操作了。 + +**Tips**：一定要记住管理员地址和私钥的对应关系，否则一旦设置管理员权限，只有管理员可以为其他账户分配权限,其他账户的设置操作都会报告没有权限。 + +### step2 + +用链管理员账户登陆控制台，根据管理策略，依次给其他系统管理员账户分配节点管理权限，系统参数修改权限，CNS权限，部署合约和建表权限等。然后用一个有相应权限的系统管理员账户私钥登陆控制台，如有部署和建表权限的账号，以便进行下一步。 + +### step3 + +开发者编写CRUD的合约时，一旦合约在链上创建了用户表，则可以采用控制台的grantUserTableManager命令，由有权限的系统管理员指定哪些账号可以创建表和增删改该表的数据，命令行是 + +``` +grantUserTableManager t_order 0xf1585b8d0e08a0a00fff662e24d67ba95a438256 +``` + +授权0xf1585b8d0e08a0a00fff662e24d67ba95a438256这个账号可以操作**t_order**表，而其他账号不行，如要读写该表，继续添加权限，对一个表有读写权限的账号可以有多个。 + +### step4 + +对solidity合约里的某个接口，可以参考这样的代码进行控制： + +``` + function testFunction() public returns(int256) +{ + require(msg.sender == tx.origin); //这一行的效果是禁止了合约调合约 + if(msg.sender != address(0x156dff526b422b17c4f576e6c0b243179eaa8407) ) //这里为示例，直接写了账户地址明文，实际上开发时可以灵活处理。 + { return -1; } //如果调用者和预设的有权限的调用者不同，则返回 + } +``` + +msg.sender是当前合约调用者的地址，可以是用户也可以是另一个合约（合约调合约时）；tx.origin则是本次交易的真正发起用户，给交易签名的用户。 + +## 小结及参考资料 + +本文介绍FISCOBCOS在基础层面上提供的一些接口和能力，权限控制的合理性和周密程度最终会取决于使用者，关于不同链的场景化治理和安全控制，可以继续深入探讨，以得出最佳实践。 + +#### 参考资料 + +- [P2P网络详细设计](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/design/p2p/p2p.html) + +- [权限控制设计](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/design/security_control/permission_control.html) + +- [控制台的文档](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/console/console.html) + +- [权限控制实操介绍](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/permission_control.html) + +- [CRUD合约开发介绍](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/smart_contract.html#crud) + +- [CRUD合约应用示例](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/tutorial/sdk_application.html) + +------ + +#### 群友问答 + +**@李翛然**：请问几个问题： + +1）管理员分配表权限，这个操作是不是在每个节点都可以进行？ + +2）创建角色，这个操作是不是每个节点都可以操作？ + +如果以上两个问题答案是肯定的，请问是不是只要有了一个节点的超级权限，就可以修改整个网络的数据？ + +**@光路**：是肯定的，建立链之前就先协商好链管理员角色由哪一个或几个账号担任，链建立后第一时间进行角色分配，具体可以参见FISCO BCOS权限控制相关文档。 + +感谢参与本次话题讨论的小伙伴们！开源社区，因你们更美！ + + + diff --git a/3.x/zh_CN/docs/articles/3_features/37_safety/certificate_description.md b/3.x/zh_CN/docs/articles/3_features/37_safety/certificate_description.md new file mode 100644 index 000000000..4fc8c3187 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/37_safety/certificate_description.md @@ -0,0 +1,98 @@ +# FISCO BCOS证书说明 + +作者：李昊轩｜FISCO BCOS 核心开发者 + +联盟链中，链上的多方参与是一种协作关系；联盟链向授权的组织或机构开放，有准入机制。在准入机制中，证书是各参与方互相认证身份的重要凭证；可以说，**证书机制是联盟链网络安全的基石**。 + +## Part1：FISCO BCOS 证书结构 + +FISCO BCOS网络采用面向CA的准入机制，使用x509协议的证书格式，支持任意多级的证书结构，保障信息保密性、认证性、完整性及不可抵赖性。根据现有业务场景，FISCO BCOS默认采用三级的证书结构，自上而下分别为链证书、机构证书、节点证书。 + + + +▲ 图：x509协议的证书格式 + +证书内容包括了证书版本号、序列号、证书的签名算法、消息摘要算法等生成信息；同时包括了证书的颁发者、有效期、使用者、公钥信息、SSL通信需要用到的密码套件等信息。节点通过加载证书，在接受数据包时，根据证书规定的密码套件和其消息字段，对数据包中携带的证书进行验证。 + +## Part2：角色定义 + +FISCO BCOS的证书结构中有４种角色，分别是联盟链委员会、联盟链成员机构、联盟链参与方（节点和SDK）。 + +### 1. 联盟链委员会 + +联盟链委员会拥有联盟链的根证书ca.crt和私钥ca.key，通过使用ca.key对联盟链成员机构签发机构证书，负责完成联盟链成员机构的准入、剔除等操作。 + +### 2. 联盟链成员机构 + +联盟链成员机构为经过联盟链委员会许可，加入到联盟链的机构。联盟链成员机构拥有机构私钥agency.key和经过根私钥ca.key签发的机构证书agency.crt。联盟链成员机构可以通过机构私钥签发节点证书，从而配置本机构的节点和SDK。 + +### 3. 联盟链参与方 + +联盟链参与方可以通过运行节点或SDK联盟链交互，拥有与其他节点进行通信的节点证书node.crt和私钥node.key。联盟链参与方运行节点或SDK时，需要加载根证书ca.crt和相应的节点证书node.crt和私钥node.key；与其他成员进行网络通信时，使用预先加载的证书进行身份认证。 + +## Part3：证书生成流程 + +### 1. 联盟链委员会初始化根证书ca.crt + +- 本地生成私钥ca.key；自签生成根证书ca.crt。 + + + +### 2.联盟链成员机构获取机构证书agency.crt + +- 本地生成私钥agency.key； +- 由本地私钥生成证书请求文件agency.csr； +- 将证书请求文件agency.csr发送至联盟链委员会； +- 联盟链委员会使用ca.key对证书请求文件agency.csr进行签发，得到联盟链成员机构证书agency.crt； +- 联盟链委员会将联盟链成员机构证书agency.crt发送至对应成员。 + + + +### 3.节点/SDK获取证书node.crt + + + +- 本地生成私钥node.key； + +- 由本地私钥生成证书请求文件node.csr； + +- 将证书请求文件node.csr发送至联盟链成员机构； + +- 联盟链成员机构使用agency.key对证书请求文件node.csr进行签发，得到节点/SDK证书node.crt； + +- 联盟链成员机构将节点证书node.crt发送至对应实体。 + +  + +▲ 图：节点私钥相关说明 + +## Part4：证书生成实例 + +以生成联盟链成员机构机构证书为例： + +1.机构首先在本地使用机构私钥agency.key生成证书请求文件agency.csr； + +``` +openssl req -new -sha256 -subj "/CN=$name/O=fisco-bcos/OU=agency" -key ./agency.key -config ./cert.cnf -out ./agency.csr +``` + +2.联盟链委员会根据证书请求文件生成机构证书agency.crt； + +``` +openssl x509 -req -days 3650 -sha256 -CA ./ca.crt -CAkey ./ca.key -CAcreateserial -in ./agency.csr -out ./agency.crt -extensions v4_req -extfile ./cert.cnf +``` + +上述过程中的cert.cnf为证书信息配置项，可以采用默认设置。 + +## Part5：小结及参考文档 + +本文介绍了FISCO BCOS采用的相关证书说明和其对应的层级架构；在后续文章中，我们会具体讲解SSL握手过程中如何使用这些数字证书。 + +------ + +#### 参考资料 + +- [证书说明](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/certificates.html) +- [权限控制](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/permission_control.html) +- [节点准入](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/node_management.html) + diff --git a/3.x/zh_CN/docs/articles/3_features/37_safety/disk_encryption.md b/3.x/zh_CN/docs/articles/3_features/37_safety/disk_encryption.md new file mode 100644 index 000000000..e0452dd5b --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/37_safety/disk_encryption.md @@ -0,0 +1,129 @@ +# FISCO BCOS的落盘加密 + +作者：石翔｜FISCO BCOS 核心开发者 + +区块链部署是多方参与的，为了简化多方协作环境的搭建，通常会使用公有云部署区块链。机构将自己的节点部署到云上，让服务与云上的节点进行交互，实现多方协作。在这个架构中，机构内部的安全性是很高的，尤其是在金融机构。 +虽然通过网络的隔离机制，将节点限制在“内网”中，通过网络不能轻易地盗取数据，但是数据全部托管在云上，由于所有参与者都会保存一份数据，在网络和系统安全措施有疏漏或操作不当等极端情况下，可能出现某一份数据被越权访问的情况。 +为了防止数据盘被攻破或者盗取，避免数据泄露情况的发生，FISCO BCOS引入了“落盘加密”的功能。 + +## 背景架构 + +在联盟链的架构中，机构和机构之间搭建一条区块链，数据在联盟链的各个机构内是可见的。 +在某些数据安全性要求较高的场景下，联盟内部的成员并不希望联盟之外的机构能够获取联盟链上的数据。此时，就需要对联盟链上的数据进行访问控制。 + +联盟链数据的访问控制，主要分为两个方面： + +- 链上通信数据的访问控制 +- 节点存储数据的访问控制 + +对于链上通信数据的访问控制，FISCO BCOS是通过节点证书和SSL来完成。此处主要介绍节点存储数据的访问控制，即落盘加密。 + + + +## 主要思想 + +落盘加密是在机构内部进行的。在机构的内网环境中，每个机构独立地对节点的硬盘数据进行加密。 +当节点所在机器的硬盘被带离机构，并让节点在机构内网之外的网络启动，硬盘数据将无法解密，节点无法启动，进而无法盗取联盟链上的数据。 + +## 方案架构 + + + +落盘加密是在机构内部进行的，每个机构独立管理自己硬盘数据的安全。内网中，每个节点的硬盘数据是被加密的。所有加密数据的访问权限，通过Key Manager来管理。 +Key Manager部署在机构内网里，是专门管理节点硬盘数据访问秘钥的服务，外网无法访问。当内网的节点启动时，从Key Manager处获取加密数据的访问秘钥，来对自身的加密数据进行访问。 + +加密保护的对象包括： + +- 节点本地存储的数据库：rocksdb或leveldb +- 节点私钥：node.key，gmnode.key（国密） + +## 实现原理 + +具体的实现过程，是通过节点自身持有的秘钥（dataKey）和Key Manager管理的全局秘钥（superKey）来完成的。 + +### 节点 + +- 节点用自己的dataKey，对自身加密的数据（Encrypted Space）进行加解密。 +- 节点本身不会在本地磁盘中存储dataKey，而是存储dataKey被加密后的cipherDataKey。 +- 节点启动时，拿cipherDataKey向Key Manager请求，获取dataKey。 +- dataKey只在节点的内存中，当节点关闭后，dataKey自动丢弃。 + +### Key Manager + +持有全局的superKey，负责对所有节点启动时的授权请求进行响应。 + +- Key Manager在节点启动时必须在线，响应节点的启动请求。 +- 当节点启动时，发来cipherDataKey，Key Manager用superKey对cipherDataKey进行解密，若解密成功，就将节点的dataK返回给节点。 +- Key Manager只能在内网访问，机构外的外网无法访问Key Manager。 + + + +## 相关操作 + +### Key Manager操作 + +在每个机构上启动一个key-manger程序，用如下命令启动，指定Key Manager： + +``` +# 参数：端口，superkey +./key-manager 31443 123xyz +``` + +### 节点操作 + +#### （1）配置新节点dataKey + +``` +# 参数：Key Manager IP，端口，dataKey +bash key-manager/scripts/gen_data_secure_key.sh 127.0.0.1 31443 12345 +``` + +得到cipherDataKey，脚本自动打印出落盘加密所需要的ini配置(如下)。此时得到节点的cipherDataKey：cipher_data_key=ed157f4588b86d61a2e1745efe71e6ea。 + +``` +[storage_security] +enable=true +key_manager_ip=127.0.0.1 +key_manager_port=31443 +cipher_data_key=ed157f4588b86d61a2e1745efe71e6ea +``` + +将得到的落盘加密的ini配置，写入节点配置文件（config.ini）中。 + +#### （2）加密新节点的私钥 + +执行脚本，加密节点私钥： + +``` +# 参数：ip port 节点私钥文件 cipherDataKey +bash key-manager/scripts/encrypt_node_key.sh 127.0.0.1 31443 +nodes/127.0.0.1/node_127.0.0.1_0/conf/node.key +ed157f4588b86d61a2e1745efe71e6ea +``` + +执行后，节点私钥自动被加密，加密前的文件备份到了文件node.key.bak.xxxxxx中，请将备份私钥妥善保管，并删除节点上生成的备份私钥。 + +**注意**： + +国密版比非国密版需要多加密一个文件： + +- 非国密版：conf/node.key +- 国密版：conf/gmnode.key和conf/origin_cert/node.key + +#### （3）启动节点 + +直接启动节点即可。如果这个节点所在的硬盘被带出机房（内网），将无法访问Key Manager。节点拿不到自己的dataKey，无法解密硬盘数据，也无法解密自己的私钥，因而无法启动。 + +## 注意事项 + +- Key Manager是一个demo版本，目前superKey是通过命令行在启动的时候指定，在实际应用中，需要根据安全要求，自己定制加载superKey的方式，比如使用加密机进行管理。 +- 落盘加密的配置只针对新生成的节点，节点一旦启动，将无法转换成带落盘加密的节点。 +- 国密版的落盘加密比非国密版多加密一个私钥。 + +------ + +#### 参考链接 + +[Key Manager源码](https://github.com/FISCO-BCOS/key-manager) + +[Key Manager源码gitee地址](https://gitee.com/FISCO-BCOS/key-manager) diff --git a/3.x/zh_CN/docs/articles/3_features/37_safety/index.md b/3.x/zh_CN/docs/articles/3_features/37_safety/index.md new file mode 100644 index 000000000..1cdf879ae --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/37_safety/index.md @@ -0,0 +1,44 @@ +### 安全控制 + +存储安全：支持落盘数据加密存储 + +```eval_rst +.. toctree:: + :maxdepth: 1 + + disk_encryption.md +``` + + +通信安全：支持全流程SSL + +```eval_rst +.. toctree:: + :maxdepth: 1 + + tsl1.2_establish_process.md +``` + + +证书管理：支持证书颁发、撤销、更新 + +```eval_rst +.. toctree:: + :maxdepth: 1 + + certificate_description.md + third-party-CA_node_deployment.md +``` + + +权限控制：支持细粒度权限控制 + +```eval_rst +.. toctree:: + :maxdepth: 1 + + access_control_glance.md + role_authority_model_realization.md +``` + + diff --git a/3.x/zh_CN/docs/articles/3_features/37_safety/role_authority_model_realization.md b/3.x/zh_CN/docs/articles/3_features/37_safety/role_authority_model_realization.md new file mode 100644 index 000000000..93e21c0e7 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/37_safety/role_authority_model_realization.md @@ -0,0 +1,116 @@ +# FISCO BCOS 角色权限模型的实现 + +作者：白兴强｜FISCO BCOS 核心开发者 + +## 引言 + +FISCO BCOS的权限控制是通过控制账号对系统中表的写权限来实现的。这种权限控制模型非常灵活且强大，用户几乎可以控制任意一项权限，例如，通过控制权限表的写权限管理分配权限；通过控制系统合约所对应表的写权限管理链配置、节点身份管理、合约部署、用户表创建等；通过控制合约表的写权限管理合约写接口的调用。 + +然而，绝对完美是不存在的。强大灵活的权限控制也带来较高的学习成本：用户需要理解每个权限项控制的内容以及如何设置，了解链管理员和系统管理员的区别……大量的概念和操作，对用户要求极高。 + +为了降低使用难度，提升用户体验，FISCO BCOS v2.5对此功能进行了优化，新增了基于角色的权限控制。把不同的权限统归到不同角色，用户根据账号所属角色即可判断其所拥有的权限。同时v2.5基于角色引入了链上治理投票模型，使治理操作更加方便。 + +## 什么是角色权限模型？ + +使用角色权限模型后，用户只需记住角色，而角色对应的权限不言自明，例如，治理委员会委员拥有链治理相关权限，这极大降低用户理解难度与学习成本。 + + + +### 角色对应的权限 + +区块链上的参与者，可根据角色分为治理方、运维方、监管方和业务方。为避免既当裁判又当运动员，治理方、运维方应权责分离，角色互斥。 + +- 治理方：角色称为治理委员会委员，简称委员，负责区块链治理。 +- 运维方：负责区块链运维，该角色由委员添加。 +- 业务方：业务方账号由运维添加到某个合约，可以调用该合约的写接口。 +- 监管方：监管方监管链的运行，能够获取链运行中权限变更记录以及需要审计的数据。 + +各角色所对应权限具体如下表所示。 + + + +### 角色权限实现的细节 + +本小节将简单介绍委员、运维和业务角色的权限实现细节以及背后原理，以便更好理解与使用角色权限功能。 + +链初始无委员账号，当存在至少一个委员账号时，委员拥有的权限开始受到控制。联盟链实际应用中多个参与方的技术实力可能并不相同，从实际应用场景出发，我们引入了链上治理投票模型，所有治理操作需要有效投票数/委员数>生效阈值才能生效，用户通过新增的链治理预编译合约可以实现委员的增删、权重修改、投票生效阈值修改等操作。 + +投票模型有几处值得注意： + +- 每次投票操作，如果是委员投票，则记录操作内容和投票委员，不重复计票 +- 每次投票操作，计票结束后，计算有效投票数/委员数，如果大于此操作的生效阈值，则对应操作生效 +- 投票设置过期时间，根据块高，blockLimit的10倍，固定不可改 + +运维角色的新增与撤销必须由委员角色操作。链初始无运维账号，当存在至少一个运维账号时，运维拥有的权限开始受到控制。业务账号可以调用链上查询接口与运维指定合约的写接口。 + +### 兼容性说明 + +目前，角色权限模型基于对系统中各类表的写权限控制。我们做了最大努力与之前版本使用体验保持一致，但为了权限控制的完整严谨，对FISCO BCOS v2.5新建链，控制台grantPermissionManager指令不再有效，原PermissionManager的权限归属于委员角色。对于v2.5之前的链，该指令仍然有效。 + +## 如何使用角色权限？ + +本节将以“委员增删”和“运维增删”为例进行简要的实操演示，文档含括了更丰富的角色权限相关操作，欢迎移步[查看](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/permission_control.html)。 + +### 增删委员 + +使用控制台v1.0.10以上版本中自带的get_account.sh脚本，生成3个如下账号，接下来的操作以这3个账号为例演示。配置好控制台后，使用控制台的-pem选项分别加载3个私钥启动3个控制台。 + +``` +# 账号10x61d88abf7ce4a7f8479cff9cc1422bef2dac9b9a.pem# 账号20x85961172229aec21694d742a5bd577bedffcfec3.pem# 账号30x0b6f526d797425540ea70becd7adac7d50f4a7c0.pem +``` + +#### 添加账号1为委员 + +增加委员需要链治理委员会投票，有效票大于阈值才可生效。此处由于只有账号1是委员，所以账号1投票即可生效。 + + + +#### 使用账号1添加账号2为委员 + +此处由于只有账号1是委员，所以使用账号1投票后，满足阈值判断立刻生效。 + + + +#### 撤销账号2的委员权限 + +此时系统中有账号1和账号2两个委员，默认投票生效阈值50%，所以需要两个委员都投票撤销账号2的委员权限，有效票/总票数=2/2=1>0.5才满足条件。 + +账号1投票撤销账号2的委员权限，如下图： + + + +账号2操作投票撤销账号2的委员权限，如下图： + + + +### 增删运维 + +委员可以添加与撤销运维角色，运维角色的权限包括部署合约、创建表、冻结解冻所部署的合约、使用CNS服务等。 + +#### 使用账号1添加账号3为运维 + + + + +#### 使用账号3部署HelloWorld + +账号3是运维角色，可以部署合约，具体操作如下图： + + + +#### 使用账号1部署HelloWorld + +账号1是委员，不具有部署合约的权限，部署合约失败，如下图： + + + + +#### 使用账号1撤销账号3的运维权限 + +账号1是委员可以撤销运维，如下图： + + + +## 总结 + +作为联盟链的重要特性，权限控制需要做到灵活且强大，但如何在此基础上达成良好的用户体验，需要不断地改进优化。FISCO BCOS v2.5前的权限控制实现了灵活且强大的功能，但同时，社区也收到不少反馈，认为权限控制的使用理解门槛过高。通过角色权限，我们希望能在保持原有功能的同时，降低学习门槛、提升大家的使用体验。整合优化权限控制的工作仍在进行，希望未来能实现从底层到应用全覆盖的权限控制解决方案。欢迎大家共同探讨交流，积极反馈使用体验与改进建议。 \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/3_features/37_safety/third-party-CA_node_deployment.md b/3.x/zh_CN/docs/articles/3_features/37_safety/third-party-CA_node_deployment.md new file mode 100644 index 000000000..d96a4fc52 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/37_safety/third-party-CA_node_deployment.md @@ -0,0 +1,152 @@ +# FISCO BCOS上使用第三方CA证书底层节点部署实操 + +作者：林宣名｜FISCO BCOS开源社区贡献者 + +CA证书怎么生成？节点相互验证证书时会交叉验证吗？对于社区常遇到的此类问题，分享一些个人使用第三方CA证书部署底层节点的经验，希望可以给大家一些借鉴与参考。 + +## 为什么要对第三方CA证书进行改造？ + +首先，说明一下我进行第三方CA证书改造的背景和原因： + +- 社区内经常有人会问到第三方CA证书的改造问题，个人感觉这是大家都关注的要点。 +- 在我们的一些项目中，业务方指定要使用第三方CA证书，实际的生产需求也要求我们进行CA改造。 +- 在司法领域区块链存证场景中，需要由具有电子认证许可证书机构出具的认证证书才能作为电子认证。 + +鉴于以上三点，我觉得大家对如何进行第三方CA证书改造都很关注。 + +FISCO BCOS技术文档中提供了CFCA证书改造的案例，但在一些细节上还待完善，因此我想写一篇教程，结合生产环境改造、第三方CA配合、合规性、技术实现等内容具体说明，看看能否对其他社区用户有所帮助。 + +### 除了司法领域存证，还有哪些场景需要由第三方CA机构参与？ + +基本上用到CA证书的区块链场景都有可能用到第三方CA证书，是否采用第三方CA证书主要考虑： + +- 联盟链是否需要第三方CA机构背后的相关资质。 +- 联盟链中，参与方对节点准入管理、以及后续控管是否需要第三方CA机构作为公正机构来签发证书，防止自建CA体系中存在任意签发证书导致节点作恶等问题。 + +### 两级证书模式下，为什么需要配置白名单列表？如果不配置会有什么问题？ + +两级证书模式下使用第三方提供CA证书作为链证书，如果不配置白名单，只要是CA证书签发节点证书都可以连接到这条链上，配置白名单可以实现准入拦截。 + +## 实操步骤教学 + +接下来，我们来看看使用第三方CA证书部署底层节点的具体实操步骤。 + +此次改造要点为： + +- FISCO BCOS的底层CA缺省提供的是三级模式，链证书-->机构证书-->节点证书； +- 现实环境中CA方虽然可以提供三级签发的证书，但在一些场景下有合规风险； +- 目前我们采用的做法是剔除机构证书，从链证书-->节点证书的签发，其中链证书由CA方提供的CA.crt，配合白名单机制使用完成基础底层节点部署。 + +### 环境准备 + +1. 两台测试服务器：118.25.208.8、132.232.115.126 + +2. 操作系统为ubuntu:18.04 + +3. openssl 工具使用ubuntu 18.04自带 openssl 1.1.1 + +4. 选用普通版FISCO BCOS 2.5.0 版本，节点使用的节点证书算法为EC secp256k1曲线 + +5. 结合【白名单机制】一起使用 + + https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/certificate_list.html#id2 + +备注：测试过程中节点私钥和请求证书文件统一管理，但在生产环境中节点私钥应由各机构管理员进行生成，提交给CA方，私钥各自留存。 + +### 基础证书准备 + +##### 生成基础节点私钥和节点证书请求文件 + +采用openssl 工具，要求1.0.2版本以上，生成对应的节点私钥和节点证书请求文件、以及对应的node.nodeid（nodeid 是公钥的十六进制表示）。（说明：以下每个节点第四步生成node.nodeid 中的node.key ，都是对应节点的cert_IP_port.key 修改的，该操作是底层要求的。） + +- 生产节点1 node_118.25.208.8_30300 相关文件 + + + +- 生产节点2 node_118.25.208.8_30301 相关文件 + + + +- 生产节点3 node_132.232.115.126_30300 相关文件 + + + +- 生产节点4 node_132.232.115.126_30301 相关文件 + + + +说明：FISCO BCOS V2.5版本中，采用了私钥及EC secp 256k1曲线算法。 + +### CA方进行节点证书签发 + +提交各个节点的node.csr 文件给CA方，CA方返回一张CA.crt 证书作为链证书，返回四张pem格式的节点证书。（说明：FISCO BCOS中，CA方返回证书的模式为：root -> node -issuer,节点证书中糅合issuer证书内容。） + +### 建链 + +- step 1 ：下载国内镜像，cd ~/ && git clone https://gitee.com/FISCO-BCOS/generator.git + +- step 2 ：完成安装，cd ~/generator && bash ./scripts/install.sh完成安装，如果输出 usage: generator xxx，则表示安装成功 + +- step 3 ：获取节点二进制，拉取最新fisco-bcos二进制文件到meta中（国内cdn），如果输出 FISCO-BCOS Version : x.x.x-x，则表示成功 + +- step 4 ：机构分配 + + 选用 118.25.208.8 所属机构作为机构A，并由机构A负责创世区块生成 + + 选用 132.232.115.126 所属机构作为机构B + +- step 5 ：将CA方提供CA.crt 证书作为链证书 + + 在机构A所属目录手动创建dir_chain_ca目录，并将CA.crt 放到dir_chain_ca目录中 + +- step 6 ：在机构A和机构B的meta目录下进行节点证书迁移 + + 在meta目录中，手动创建对应的节点目录，其中机构A为：node_118.25.208.8_30300、node_118.25.208.8_30301，机构B为：node_132.232.115.126_30300、node_132.232.115.126_30301 + + 每个目录需要存放对应的节点证书和节点私钥、节点Id，将CA方生成的节点证书、以及最初准备的节点id、节点私钥等文件统一分发至对应的节点目录，详细如图： + + + +- step 7：机构A收集所有节点证书 + + 在机构A的meta目录下，收集对应的节点证书，用于后续生成创世区块。如图所示： + + + + +- step 8：手动配置机构A修改conf文件夹下的group_genesis.ini，生成创世区块 + +- step 9：修改机构A、机构B的conf目录下的node_deployment.ini；其中p2p 地址为外网地址、rpc、channel 地址为内网地址 + +- step 10：在机构meta目录下手动创建peers.txt 文件 + + 机构A中创建 peers.txt、peersB.txt,机构B 创建 peers.txt、peersA.txt其中以机构A为例，peers.txt 内容如下： + + + +- step 11：机构A和机构B中生成节点,在机构A的generator中执行命令./generator --build_install_package ./meta/peersB.txt ./nodeA生成机构A的对应节点；在机构B的generator中执行命令./generator --build_install_package ./meta/peersA.txt ./nodeB生成机构B的对应节点 +- step 12：运行两个机构的节点：bash ./nodeA/start_all.sh和bash ./nodeB/start_all.sh；共识状态正常则如图所示： + + + +- step 13：控制台部署并进行合约部署测试 + + 针对机构A和机构B对应的控制台操作结果进行比对，两者数据一致，确保共识正常 + +- step 14：在对应节点的config.ini 配置白名单 + +至此，我们就完成了第三方CA证书结合底层节点部署的改造。从流程上看，主要是在链证书-->机构证书-->节点证书的生成流程改变了，以及需要在meta目录下进行手动创建peers.txt文件和节点目录等。 + +## 结缘FISCO BCOS开源社区 + +说起我与FISCO BCOS开源社区的结缘也源于CA证书，在一次政企项目对接中，业主方要求区块链底层需适配国密，并使用业主方指定的CA证书。 + +早期我们团队使用的是其他区块链底层，无法直接适配国密，且改造难度大、周期长、成本高；考虑到后续国内不少项目会涉及到适配国密和CA改造等，我们迫切需要一套完备的区块链底层支持上述需求。通过圈内朋友介绍，了解到FISCO BCOS，在进行深入技术调研、可行性分析后最终选择了FISCO BCOS。 + +FISCO BCOS开源社区中创设了开放交流的氛围，欢迎大家在社区与我交流讨论。 + +------ + +关于本期分享内容的更多详情，可通过[元磁之力](https://www.yc-l.com/article/49.html)进一步了解。 + +元磁之力论坛是由林宣名和他的团队为FISCO BCOS开源社区贡献的用户交流平台，主要用于分享和学习FISCO BCOS及相关的技术知识。感谢大家为社区做出的各类贡献，您的每一次参与都将成为社区成长的动力！ \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/3_features/37_safety/tsl1.2_establish_process.md b/3.x/zh_CN/docs/articles/3_features/37_safety/tsl1.2_establish_process.md new file mode 100644 index 000000000..05df64d25 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/37_safety/tsl1.2_establish_process.md @@ -0,0 +1,141 @@ +# FISCO BCOS的TLS1.2握手流程 + +作者：李昊轩｜FISCO BCOS 核心开发者 + +### 写在前面 + +之前我们说过，互联网上应该质疑一切，因此采用传统明文方式发送数据包无疑是非常不安全的。因此https协议中要求需要加密，那么加密前需要做什么，本文将对握手建立前，通信双方的具体流程进行分析。 + +SSL通信过程是TLS1.2 **[1]** 的内容。最终目的是安全的传输数据包。SSL通信的核心是通过证书验证身份，之后通过"握手"交互生成一个本次通信的非对称会话主密钥。然后在本轮通信过程中，通过这个会话主密钥对数据包进行加解密，并在网络上只传递密文。 + +本文将以FISCO BCOS节点通信双向认证为例，讲解通信双方如何加载、使用、验证证书，并如何生成会话主密钥。 + +## Part 1 主密钥设置 + +网络压缩主要在P2P网络层实现，系统框架如下： TLS中的主密钥是一个对称密钥，即client端和server端使用的密钥是相通的，握手的过程也就是双方通过交互一些随机数，来完成主密钥的设置。 + +我们以DH密钥交换算法x协商主密钥为例，设攻击者为Eve，Eve可以获取他们传输的中间值： + +1. Alice和Bob先协商公平一个大素数p，和生成元g，Eve可以获取p和g； +2. Alice选择随机整数a∈Zp，计算A=g^a modp，将A发送给Bob，Eve可以获取A +3. Bob选择随机整数b∈Zp，计算B=g^b modp，将B发送给Alice，Eve可以获取B +4. Alice计算S=B^a = g^(ab) modp +5. Bob计算S=A^b = g^(ab) modp + +通过上述过程，Alice和Bob协商出了一个密钥S，虽然Eve获取了中间值A，B，p，g，根据离散对数问题，Eve无法获取S具体的值。 + +## Part 2 证书验证 + +之前的文章中我们讲到 [证书的签发流程](https://mp.weixin.qq.com/s?__biz=MzU5NTg0MjA4MA==&mid=2247484692&idx=1&sn=3163aec2574ce0bf7d4f64e899e9bb6d&chksm=fe6a805bc91d094df15ed5c5988897d307ed519efbb0b26c2056ad35df3a491cea1e556ee70e&token=951660177&lang=zh_CN&scene=21#wechat_redirect)（点击阅读），在本节中将以三级证书为例，讲解证书的验证过程。TLS握手中的证书验证，即通过加载双方预先都信任的根证书，从而认证对方的身份。 + + + +▲感谢社区核心开发者黎连文贡献的图 + +- 在程序启动时，会首先加载本地的ca.crt和node.crt； +- 当节点验证对方的证书时，会首先使用对方node.crt中的公钥验证附带的签名，当验证通过时，可以确认对应节点拥有当前node.crt对应的node.key； +- 之后节点会使用agency.crt中的信息验证node.crt是否为合法的agency签发； +- 最后节点会使用本地加载ca.crt中的信息验证agency.crt是否为联盟链委员会签发； +- 当两者都验证通过时，表示节点接收到的node.crt是由本地加载的ca.crt签发的。 + +## Part 3 TLS握手流程 + +下图是我们采用对两台服务器进行抓包得到了TLS握手流程： + + + +▲Client端 + + + +▲server端 + +**在流程中我们一共看到了6个数据包，分别为：** + +- client向server发送的client hello +- server向client发送的server hello，发送server证书，进行参数协商 +- client向server发送的client证书，进行参数协商 +- server向client发送的结束标志，握手完成 + +### (1) client hello + +在这步中，client向server发起建连请求，并告知server以下信息： + +``` +{ +client端支持的TLS协议 +支持xxx加密算法 +密钥协商过程需要的随机数 +} +``` + + + + +### (2) server hello + + + +server端接收到client的请求后，对其进行回应，包括： + +``` +{ +我本次使用的TLS协议 +这是我的随机数 +本次会话我们的session id +本次我们使用的加密算法 +} +``` + +### (3) server communicate + + + +如图所示，共包含四个部分: + +``` +{ +server端证书certificate +密钥交换参数server key exchange +验证client端的请求 certificate request +server端 发送完毕 server hello done +} +``` + +(2)(3)两步的操作可以总结为：server端对client端做出了“我们使用xx算法协商会话主密钥，这是我的证书，这是我的协商参数，请把你的证书发给我”的回应。 + +### (4) client certificate + +client端收到server的certificate request后，会将自己的证书发送给对方。 + +### (5) client communicate + + + +在这步中，client会先使用本地加载的ca.crt 验证server证书，之后进行参数协商操作，数据包中内容有： + +``` +{ +client 密钥交换参数 +client 对server端证书的验证结果 +使用会话主密钥的密文传输内容 +client对(1)(2)(3)过程的签名 +} +``` + +### (6) server handshake established + + + +server端接收到数据包后，会开始使用会话主密钥对数据包进行加密传输。 + +------ + +#### 参考资料 + +[【1】TLS(Transport Layer Security)](https://baike.baidu.com/item/TLS/2979545?fr=aladdin)：安全传输层协议用于在两个通信应用程序之间提供保密性和数据完整性。该协议由两层组成： TLS 记录协议（TLS Record）和 TLS 握手协议（TLS Handshake）。 + +[【2】Discrete Logarithm Problem](https://www.doc.ic.ac.uk/~mrh/330tutor/ch06s02.html) + + + diff --git a/3.x/zh_CN/docs/articles/3_features/38_privacy/index.md b/3.x/zh_CN/docs/articles/3_features/38_privacy/index.md new file mode 100644 index 000000000..497d2a065 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/38_privacy/index.md @@ -0,0 +1,9 @@ +### 隐私保护 + +物理隔离：群组间数据隔离 +隐私保护协议：支持群签名、环签名、同态加密 +场景化隐私保护机制：基于WeDPR支持隐匿支付、匿名投票、匿名竞拍、选择性披露等场景 + +- [FISCO BCOS隐私特性：群/环签名技术实现](./privacy_protection_group_and_ring_signature.md) +- [链上密文参与计算？同态加密尽显神通 | FISCO BCOS隐私特性](./privacy_protection_homomorphic_encryption.md) +- [隐私保护专题](http://mp.weixin.qq.com/mp/homepage?__biz=MzU0MDY4MDMzOA==&hid=5&sn=d9ae81771056e6fa4e196baefec33ada&scene=18#wechat_redirect) \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/3_features/38_privacy/privacy_protection_group_and_ring_signature.md b/3.x/zh_CN/docs/articles/3_features/38_privacy/privacy_protection_group_and_ring_signature.md new file mode 100644 index 000000000..1abc3ce79 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/38_privacy/privacy_protection_group_and_ring_signature.md @@ -0,0 +1,148 @@ +# FISCO BCOS隐私特性：群/环签名技术实现 + +作者：贺双洪｜FISCO BCOS 核心开发者 + +## 前言 + +安全与隐私一直是区块链领域的热点话题，也是各大主流区块链平台必争的战略高地。FISCO BCOS从底层到应用、架构到协议、存储到网络等多方面针对安全和隐私作出较大努力，目前已实现账户管理、落盘加密、安全通讯、权限控制等功能模块。本文将对FISCO BCOS隐私特性之一群环签名展开介绍。 + +群/环签名是一种特殊的签名算法，最初是为了实现隐匿支付而应用在区块链领域。其能很好地隐藏签名者身份，既能让节点验证交易签名的正确性，又不会暴露交易发起者的公钥信息。这一特性在联盟链中有着广阔的应用前景。 + +## 什么是群/环签名 + +了解群/环签名，得从匿名性说起。 + +在现实世界，匿名性是指主体的行为不会暴露主体的身份，这几乎是人类文明诞生伊始便存在的需求。 + +从密码学的角度，匿名性有两种含义： + +1. 给定一个密文，无法还原其公钥，主要用于密码算法的安全性分析； +2. 用户使用密码方案过程中不会发生身份信息的泄露，更符合现实世界的语义。 + +密码学中最早隐含身份概念的是电子签名，签名者通过私钥对消息签名，验证者可以使用签名者的公钥验证签名的合法性。在实际应用中，公钥往往和证书绑定（基于身份加密除外，因为身份即公钥，所以没有证书），证书的属性天然揭露属主的身份信息，所以传统的签名方案缺少匿名性。 + +上世纪九十年代初，Chaum和van Heyst在欧密会(EUROCRYPT)上提出了群签名的概念，有效解决了电子签名的身份隐私问题。 + +群签名中的“群”可以理解成一个组织。组织里有一个leader即群主，负责成员管理，组织里的每个成员都可以**匿名**地代表组织进行签名。群签名方案主要算法包括： + +- 创建群，由群主执行，生成群主私钥和群公钥； +- 新增群成员，由群主执行，生成群成员私钥和证书，证书用于证明群成员身份； +- 生成群签名，群成员通过私钥对信息签名； +- 验证群签名，验证者可通过群公钥验证签名的合法性，验证者可以判定这个签名确实来自这个群，但无法确定是哪一个群成员的签名； +- 打开群签名，群主可通过签名信息获取签名者证书，从而追踪到签名者身份。 + + + +由于群签名存在一个拥有绝对权限的群主角色，所以群签名的匿名性是相对的。这种特性适用于需要监管介入的场景。 + +为了追求完全匿名性，Rivest于2001年提出了一种无群主方案，任何成员可自发地加入组织。该方案中签名隐含的某个参数按照一定规则组成环状，因而被命名成环签名。本质上“群”和“环”都可理解为多个成员组成的组织，区别在于是否存在一个能打开签名的leader。 +环签名算法流程如下： + +- 初始化环，由环成员执行，生成环参数，环参数就好比微信面对面建群的密码，任何知道该参数的成员都可以加入该环； +- 加入环，由环成员执行，通过环参数获得公私钥对； +- 生成环签名，环成员使用私钥和随意多个环公钥对信息签名； +- 验证环签名，验证者可通过环参数验证签名的合法性。 + +环签名方案将签名者公钥隐藏在了签名使用的公钥列表中，公钥列表越大，匿名性越高，适用于对隐私要求较高的多方协作场景。 + +## FISCO BCOS的技术选型 + +目前，群/环签名主要应用在投票、竞标、竞拍等场景以保障参与者身份隐私。对联盟链而言，同一联盟内的多个机构有协作也有博弈，在某些场景下，保护用户身份是非常必要的。 + +FISCO BCOS集成的群/环签名方案，为用户提供一种能够保证身份匿名性的工具。基于对方案复杂度和链上计算成本的考量，链上只保留了最有必要的步骤，即签名验证，其他算法则以独立功能组件形式提供给应用层。 + +应用于区块链的群签名方案需要满足以下两点： + +1. 为了方便成员管理，需要支持群成员的撤销； +2. 考虑到区块链存储资源有限，因此签名数据不能太大，可对齐标准的RSA签名。 + +因此，我们选择了首个兼具上述特性的群签名方案BBS04《Short Group Signatures》，该方案由Boneh于2004年在美密会（CRYPTO）上提出。 + +环签名不存在能够打开签名的第三方，为了方便追责，防止签名者被诬陷，需要一种具备指责关联性和抗诽谤性的方案，即基于相同公钥列表生成的两个环签名可判断是否来自同一个签名者。基于这层考虑，我们选择了Joseph在04年提出的首个可链接的环签名方案LSAG《Linkable Spontaneous Anonymous Group Signature for Ad Hoc Groups》。 + +BBS04方案基于双线性对构造，群管理员可根据不同的线性对初始化群。不同线性对类型下的群签名存储和计算开销如下： + + + +其中各个线性对的群阶数可自由配置，上述实验使用了默认值。可以看到，链上验证的时间开销差距并不大，用户可根据自己安全性和性能需求，选择合适的线性对类型以及群阶数。 + +LSAG方案中，不同环大小的环签名存储和计算开销如下： + + + +由于环签名长度、签名和验证时间与环成员数目呈线性关系，为防止超gas，环成员数量建议不超过32个。 + +## 如何在FISCO BCOS中使用群/环签名 + +FISCO BCOS 2.3版本开始以预编译合约的形式集成了BBSO4方案和LSAG方案的签名验证算法。由于这些隐私保护特性默认不开启，要启用这些功能需要打开CRYPTO_EXTENSION编译选项，并重新编译源码。**2.5及以上版本默认开启，不再需要用户编译源码**。 + +群/环签名预编译合约地址分配如下： + + + +要完成预编译合约的调用，首先需要以solidity合约方式声明合约接口。 + +- ### 群签名 + +``` +// GroupSigPrecompiled.sol +pragma solidity ^0.4.24; +contract GroupSigPrecompiled { + function groupSigVerify(string signature, string message, string gpkInfo, string paramInfo) public constant returns(bool); +} +``` + +- ### 环签名 + +``` +// RingSigPrecompiled.sol +pragma solidity ^0.4.24; +contract RingSigPrecompiled { + function ringSigVerify(string signature, string message, string paramInfo) public constant returns(bool); +} +``` + +以验证环签名为例（请确保同级目录下已有上述的接口声明合约），在业务合约中通过地址实例化预编译合约对象以完成验证接口的调用： + +``` +// TestRingSig.sol +pragma solidity ^0.4.24; +import "./RingSigPrecompiled.sol"; + +contract TestRingSig { + RingSigPrecompiled ringSig; + function TestRingSig() + { + // 实例化RingSigPrecompiled合约 + ringSig = RingSigPrecompiled(0x5005); + } + function verify(string signature, string message, string paramInfo) public constant returns(bool) + { + return ringSig.ringSigVerify(signature, message, paramInfo); + } +} +``` + +除了预编译合约接口，FISCO BCOS还额外提供了两个核心模块供用户使用，分别是一个完整的群/环签名库以及一个群/环签名RPC服务端。签名库和服务端独立于区块链平台，用户也可以基于签名库定制化地开发自己的服务端。签名信息可在链上进行存储，然后通过在合约中调用验证接口，完成签名合法性的验证。 + +FISCO BCOS为用户提供了一个群/环签名的开发示例，以客户端为操作入口，示例架构如下图所示： + + + +群/环签名客户端调用服务端的RPC接口完成群/环的创建、成员的加入以及签名的生成；同时客户端与区块链平台交互，将签名信息上链；最后客户端调用预编译合约验证链上的签名。更多的操作步骤和技术细节，请参阅群/环签名客户端指南。参考链接如下：https://github.com/FISCO-BCOS/group-signature-client/tree/master-2.0 + +## 改进的方向 + +在学术界，群/环签名的发展已经比较成熟，基于不同场景诞生了很多新的方案。 + +例如，支持群成员主动加入的方案能有效抵抗群主作恶的陷害行为；可撤销匿名性的环签名方案支持签名者在特定场合将环签名转换成一个普通签名，以证明自己的签署者身份；支持前项安全的方案能保证用户私钥泄露不对之前签名的匿名性产生影响。 + +目前，FISCO BCOS集成的群/环签名方案各有一种，未来对于更复杂的需求，会增加更多支持方案，为用户提供更多选择。同时，针对现有客户端示例可移植性不佳的情况，未来会考虑以插件的方式提供，方便业务快速接入。 + +## 结语 + +安全与隐私是一个复杂、广阔、充满挑战的领域。 + +群/环签名模块只是为用户身份提供了匿名性保护，如何结合其它密码协议构建更加可靠、健全的安全区块链平台？如何降低用户的使用成本和开销，提供多维度、高可用的隐私保护服务？以上问题需要我们不断研究探索。 + +最后，欢迎有志之士加入FISCO BCOS安全性建设，为构建牢不可破的隐私之墙添砖加瓦。 \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/3_features/38_privacy/privacy_protection_homomorphic_encryption.md b/3.x/zh_CN/docs/articles/3_features/38_privacy/privacy_protection_homomorphic_encryption.md new file mode 100644 index 000000000..da219d2e7 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/38_privacy/privacy_protection_homomorphic_encryption.md @@ -0,0 +1,92 @@ +# 链上密文参与计算？同态加密尽显神通 | FISCO BCOS隐私特性 + +作者：贺双洪｜FISCO BCOS 核心开发者 + +## 前言 + +作为分布式系统，一方面区块链通过数据的共享、共治以及协作处理，充分发挥数据价值。而另一方面，由于资源和隐私的限制，区块链只适合保存最轻、最有必要、无隐私风险的数据，如哈希、元数据的密文等。数据可用性和隐私性之间的矛盾，在区块链中愈发明显。 + +常言：“鱼与熊掌不可兼得”，但是专治疑难杂症的密码学家们不答应，提出了一种密文也能参与计算的方案——**同态加密**（HE，Homomorphic Encryption）。本文将解释同态加密的定义以及在FISCO BCOS中的技术实现。 + +## 什么是同态加密 + +同态加密是上世纪七十年代就被提出的一个开放问题，旨在不暴露数据的情况下完成对数据的处理，关注的是**数据处理安全**。 + +想象一下这样一个场景，作为一名满怀理想的楼二代，你每天过着枯燥乏味的收租生活，希望摆脱世俗的枷锁、铜臭的苟且去追求诗与远方。你需要雇一个代理人去承担收租的粗活，但又不希望其窥探你每月躺赚的收入。于是，你请高人打造了一套装备，既能保证代理人顺利完成收租，又不会泄露收入信息。这套装备包括信封、胶水、皮夹和神奇剪刀，每一样东西都有奇特的功能： + +1. 信封一旦用胶水密封，只有神奇剪刀才能拆开。 +2. 不论信封里装了多少钱，信封的大小和重量都不会发生改变。 +3. 把多个信封放在皮夹里后，信封会在不拆开的情况下两两合并，最后变成一个信封，里面装的钱正好是合并前所有信封金额的总和。 + + + +你把信封和胶水分发给所有租客，把皮夹交给代理人。到了约定交租的日子，租客把租金放到信封里密封后交给代理人；代理人收齐信封，放到皮夹中，最后得到一个装满所有租金的信封，再转交给你；你使用神奇剪刀拆开，拿到租金。 + +在这个场景中，信封的a、b两个性质其实就是公钥加密的特性，即使用公钥加密得到的密文只有掌握私钥的人能够解密，并且密文不会泄露明文的语义信息；而c则代表加法同态的特性，两个密文可以进行计算，得到的结果解密后正好是两个原始明文的和。到此，同态加密的全貌已经呼之欲出： + +- 同态加密本质是一种公钥加密方案，即加密使用公钥pk，解密使用私钥sk； +- 同态加密支持密文计算，即由相同公钥加密生成的密文执行f()函数的同态操作，生成的新密文解密后恰好等于两个原始明文计算f()函数的结果； +- 同态加密公式描述如下： + + + +同态加密可分为全同态加密（FHE，Fully Homomorphic Encryption）和半同态加密（SWHE，Somewhat Homomorphic Encryption）。FHE顾名思义就是支持任意给定的f()函数，不过由于计算开销极大，目前学术界还没有一个实用型的FHE方案；SWHE只支持一些特定的f()函数，例如加法或者乘法等，由于开销小，在工业界尤其是云计算领域已有不少的应用。 + +## FISCO BCOS技术选型 + +在联盟链中，考虑到监管需求，链上机构可能需要将应用中的一些隐私数据上链，如营收账目、产品流量等。为了不泄露机密，机构可以使用监管方的公钥对这些信息进行加密，加密后，信息统计可交由代理机构完成。在这种场景下，由于需要针对密文进行计算，同态加密便可大展身手。 + +FISCO BCOS通过集成同态加密，为用户提供一种支持密文处理的隐私保护工具。加解密会暴露明文数据，基于安全性考量，只适合在链下完成，链上只保留同态运算接口，加解密接口则以独立算法库的形式提供给应用层。在同态加密方案的选择上，出于对计算开销的考虑，首选轻量级加法同态方案；鉴于区块链存储资源有限，密文不能太大，可对齐标准的RSA加密算法。 + +综合上述两点，我们选择了兼具以上特性的加法同态方案Paillier《Public-Key Cryptosystems Based on Composite Degree Residuosity Classes》，该方案由Paillier于1999年在欧密会（EUROCRYPT）上提出。Paillier方案的实验分析如下： + + + +其中公私钥对通过RSA密钥生成算法得到，从上表中可以看到各项开销和秘钥长度正相关。目前1024位的RSA密钥已经不再安全，推荐使用2048位及以上的密钥。 + +## 如何在FISCO BCOS中使用同态加密 + +FISCO BCOS 2.3版本以预编译合约的形式集成了Paillier方案的密文同态加法接口。要启用同态加密功能需要打开CRYPTO_EXTENSION编译选项，并重新编译源码（**2.5及以上版本默认开启，不再需要用户编译源码**）。同态加密预编译合约地址分配如下： + + + +要完成预编译合约的调用，首先需要以Solidity合约方式声明合约接口。 + +``` +// PaillierPrecompiled.sol +pragma solidity ^0.4.24; +contract PaillierPrecompiled{ + function paillierAdd(string cipher1, string cipher2) public constant returns(string); +} +``` + +然后可在业务合约中通过地址实例化预编译合约对象以完成同态加接口的调用。 + +``` +// CallPaillier.sol +pragma solidity ^0.4.24; +import "./PaillierPrecompiled.sol"; +contract CallPaillier { + PaillierPrecompiled paillier; + constructor() public + { + // 实例化PaillierPrecompiled合约 + paillier = PaillierPrecompiled(0x5003); + } + function add(string cipher1, string cipher2) public constant + returns(string) + { + return paillier.paillierAdd(cipher1, cipher2); + } +} +``` + +Paillier方案中的公私钥生成、加解密接口以独立的密码库提供给开发者。目前密码库内包含了一个Java语言的完整版Paillier方案，以及一个供预编译合约调用的C语言版同态加接口。[密码库如下](https://github.com/FISCO-BCOS/paillier-lib)。 + +## 未来改进的方向 + +开发者当下可触达的同态加密算法库只有Java版本，未来根据实际需求，我们将对齐FISCO BCOS的SDK语言种类，提供多语言版本的同态加密库。同态加密一直是密码学界难题，要实现全同态加密计算，在性能和可用性上还存在很大挑战，FISCO BCOS将持续关注该领域的技术进展。 + +## 结语 + +安全之道修远兮，FISCO BCOS将上下求索。目前，FISCO BCOS已配置包括群签名、环签名、同态加密等多种密码学工具，接下来将实现和集成面向特定场景的定制化隐私保护解决方案。欢迎大家一起使用和关注同态加密技术在隐私保护场景的应用，共同探讨交流，积极反馈、共建更为安全可靠的FISCO BCOS平台。 \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/3_features/39_wecross/index.md b/3.x/zh_CN/docs/articles/3_features/39_wecross/index.md new file mode 100644 index 000000000..313964470 --- /dev/null +++ b/3.x/zh_CN/docs/articles/3_features/39_wecross/index.md @@ -0,0 +1,8 @@ +### 跨链协议 + +SPV：提供获取SPV证明的接口 +跨链协议：基于WeCross支持同构、异构跨链 + +[WeCross跨链专题](https://mp.weixin.qq.com/mp/appmsgalbum?action=getalbum&album_id=1337945984353107969&__biz=MzU0MDY4MDMzOA==#wechat_redirect) + + \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/4_tools/41_webase/index.md b/3.x/zh_CN/docs/articles/4_tools/41_webase/index.md new file mode 100644 index 000000000..91040c38c --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/41_webase/index.md @@ -0,0 +1,13 @@ +### WeBASE + +```eval_rst +.. toctree:: + :maxdepth: 1 + + webase_release.md + webase-transaction.md + walk_in_webase_zoo.md + webase_data_output.md + webase_node_preposition.md +``` + \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/4_tools/41_webase/walk_in_webase_zoo.md b/3.x/zh_CN/docs/articles/4_tools/41_webase/walk_in_webase_zoo.md new file mode 100644 index 000000000..46b04fdf3 --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/41_webase/walk_in_webase_zoo.md @@ -0,0 +1,146 @@ +# 在WeBASE的动物园漫步 + +作者：毛嘉宇｜FISCO BCOS 核心开发者 + +**作者语**：开源软件，是大师心目中商业化大潮之外的伊甸园；是极客们聚集出没的大教堂和集市；是技术爱好者挚爱的隽永诗篇；但在我眼里，开源软件的世界就是一座动物园。 + +开源机构酷爱拿动物来命名软件或制作LOGO，这些名字早已似春雨般深入人心。比如一脸严肃，身手敏捷，酷似狮子的Tomcat。还有Python，两条肥胖蠢萌的蟒蛇形象火遍了全世界。而Linux用一个叫Tux的企鹅作为吉祥物，Tux 现在已经开始拍游戏视频、广告了，甚至还有个叫Gown的女朋友。开源社区动物园里的风景异彩纷呈，受此启发，我们将WeBASE中的两个数据导出相关组件分别取名为Monkey和Bee。 + +本文就为您介绍神通广大的Monkey和专注如一的Bee。**WeBASE是在区块链应用和FISCO BCOS节点之间搭建的中间件平台**，对技术和业务架构中的共性进行抽象，形成通用化且体验友好的组件，简化区块链应用开发流程。 + +## WeBASE-Codegen-Monkey之美猴王 + +WeBASE-Codegen-Monkey（以下简称Monkey）是WeBASE数据导出工具的代码生成组件。可帮助用户自动生成数据导出组件，更进一步地提升研发效率，帮助开发者减负。我们开发的Monkey，其命名灵感来自于美猴王——齐天大圣孙悟空。 + +Monkey提供可执行的shell脚本：generate_bee.sh。只需简单的配置，同时按要求提供智能合约文件，便可自动生成WeBASE-Collect-Bee。在执行完脚本后，Monkey会自动退出，仿佛化生变幻的美猴王，腾云而来，驾雾而去。Monkey的启动脚本，会自动下载代码、装载合约、构建生成业务代码、编译数据导出组件代码、启动数据导出的应用。generate_bee.sh的主要执行步骤如下图： + + + +其中，步骤3，脚本会自动将开发者的配置文件，放置到指定的配置路径。 步骤5，Monkey在启动后，会根据次序，生成日志、函数代码、配置和设置文件，并放置到Bee所需的路径上。步骤8，Bee在启动时，可随心所欲地加载所需的代码和配置文件。开发者也可以在预先约定的路径下，获得所需的各类脚本或参数的文件。 + +generate_bee.sh的执行过程，就如同《西游记》所述：『见他凶猛（数据导出定制化开发需求复杂），即使身外身法（读取环境和合约的配置），拔一把毫毛（下载代码、装配配置和编译Monkey代码），丢在口中嚼碎（运行monkey代码，自动生成Bee的配置和代码），望空喷去（编译Bee的代码），叫一声‘变！’（开始执行Bee的代码）即变做三二百个小猴，周围攒簇（自动建库建表并成功开始导出数据）。』 + +美猴王有七十二变的神通，Monkey有自动生成所需代码的功能，真正做到让数据导出系统开箱可用Monkey生成的代码等文件，可分为四大类： + +1. 基于合约和配置生成的具体日志解析的代码； +2. 基于合约和配置生成的具体函数解析的代码； +3. 基于配置生成的配置文件； +4. 基于合约和配置生成的设置文件。 + + + +上图中，不同类型的Paras会生成不同的代码文件。其中： + +- EventGenerateParas：包含了日志（Event）相关代码和脚本的生成。 + + 如合约文件中解析的日志entity和repository的定义、以及每个不同日志解析的代码、日志的BO类和日志的数据库建表语句。 + +- MethodGenerateParas：包含了函数（Method）相关代码和脚本的生成。 + + 如合约文件中解析的函数hibernate entity和repository的定义、以及每个不同函数解析的代码、函数的BO类和函数的数据库建表语句。 + +- ConfigGenerateParas: 包含了Bee工程的数据库建表脚本和数据库配置文件。 +- SettingsParas：包含了grafana dashboard和table_panel的json导入设置文件。 + +如上所述，为了开发者方便易用，一次配置。Monkey除了生成执行代码外，相关的区块链软件和数据导出组件的通用配置，也被放到了Monkey系统的配置中，并自动传递到Bee的配置文件中。Monkey系统集成了Beetl作为模板引擎，无论多么复杂的合约，多么繁琐的配置，都能化繁为简，快速生成。Monkey通过载入开发者编译后的solidy对应的Java文件，利用反射技术，获取合约文件的Class信息。 + + + +Monkey启动后，会创建一个代码生成的模板引擎，上述的AtomicParas则是引擎启动所必须的原料。如上图，通过这三个核心的调用步骤： + +1. 引擎通过调用getTemplateFilePath()方法，获得渲染模板的文件路径； +2. 通过getBindingMap()方法获得渲染所需的所有参数； +3. 通过getGeneratedFilePath()获得生成文件的具体路径。 + +代码生成引擎便可飞速启动，执行渲染，最终完成所需文件的自动生成。 + +当然，美猴王的传奇不会终结，Monkey系统提供了很多强大而灵活的配置，来满足拥有独特个性化需求的开发者。美猴王的征途也不会仅仅局限于数据导出，未来还将会涉足更多的领域，为大家带来更多的惊喜…… + +## WeBASE-Collect-Bee之蜜蜂 + +WeBASE-Collect-Bee（以下简称Bee） 是WeBASE中一个基于FISCO BCOS平台的数据导出组件，支持将区块链的数据导出到Mysql等数据库中。 + +为何取名『Bee』呢？古往今来，文人墨客留下了诸多歌咏蜜蜂的诗文：穿花度柳飞如箭， 粘絮寻香似落星。小小微躯能负重， 器器薄翅会乘风。——吴承恩 + +Bee系统恰如蜂群一般，专注如一，辛勤劳作。服务不停，数据导出的任务就不会停止。小蜜蜂们在区块链的花丛之中，来回穿行，在区块之间，寻找香甜、漂浮的业务数据，将海量的区块链数据，稳定高效地导出到存储之中，供开发者执行分析、计算和查询。小小微躯的蜜蜂是轻盈的，契合了Bee系统设计『轻』的气质。 + +在Monkey的协助下，遵循『契约优于配置』的原则，开发者只需修改极少的配置，辅以搭链后自带的证书和开发编译后的合约文件，执行脚本后就可以快速获得已打包的可执行Jar包，甚至可以直接启动运行。蜜蜂的轻盈还体现在，系统地提取和抽象了大量的配置项。按照开发者的个性化需求，灵活配置，按需而动。 + +系统架构图如下所示，除了核心的模块，Bee系统的模块都是可插拔的。例如是否需要引入可视化数据分析、集成测试界面、监控和Supervisor进程管理等增强功能模块。 + + + +为了让蜜蜂器器薄翅能够舞动地更加轻盈，我们在最新的V1.1.0中进行重构，将原有的单工程按照功能粒度进一步拆分。这样，开发者既可以选择直接部署一个可执行的Jar包。还可以按需引入Jar包，将指定功能模块嵌入到自己的工程中。上述的模块均基于Springboot2开发，支持个性化配置。 + + + +如上图所示，各个Jar的功能正如其名： + +- core：打包为一个可执行的BootJar包，内置开箱即用的Restful API，使得开发者更加便捷地获得数据导出的服务。同时，core自身也是一个示例，向开发者展示了，如何组合利用各个功能模块的Jar包，来开发一个功能完整的数据导出系统。 +- parser：封装了区块解析的功能。入口的方法签名可以传入一个区块Block，获得完整解析后的BlockInfoBO的Bean对象，其中包含了解析后的数据。 +- extractor：进一步封装了web3j的SDK的逻辑，可以便利地调用上链功能和获取区块链的数据。 +- db：封装了数据存储的逻辑，理论上支持各类主流的数据库，实际严格测试支持将数据存储到Mysql 5.6及以上社区版。 +- common：封装了一些公用的数据结构、工具类和公共参数等。 + +蜜蜂的微躯虽然轻盈，可是蜂群的协作却可以负重。 + +为了应对海量数据的存储，例如单表数据超过1KW条，单库容量超过1T的场景，Bee 集成了sharding-jdbc，支持可配置的多数据源存储、读写分离和分库分表。 + +为了加快数据导出的速度，Bee系统进行了多轮的性能优化，大幅提升了单机部署下数据导出的效率。同时，依托集成Elastic-Job后，获得分布式任务协调服务的能力，Bee支持实例多活部署，横向扩展，灵活伸缩。 + +蜜蜂的工作是三型分工，Bee系统的任务执行者也分为三类：任务的调度者、区块的采集者和区块的处理者。 + + + +如上图所示，具体的三类任务执行者的说明如下： + +**蜂王（Dispatcher）**： + +通过分布式协调服务，保证只有唯一的一个线程运行，负责检测区块链当前的块高和已拉取任务的明细，准备任务，检测区块的分叉状态，检测任务的超时状态和错误状态，并基于预先定义的策略执行重拉等。准备任务是指Dispatcher会基于区块的维度在数据库进行维护：为每个区块创建一条状态记录，并插入到block_task_pool的系统表中。 + +**雄蜂（Extractor）**： + +与Depot共用相同的线程，线程的总数可以通过配置文件来指定，但任务执行的分片由分布式协调服务自动调度。Extractor执行的任务职责是：从Dispatcher维护的block_task_pool系统表中拉取对应分片序号的区块任务，然后从区块链下载指定区块高度的Block数据，并修改block_task_pool系统表的任务执行状态。 + +**工蜂（Depot）**： + +与Extractor共用相同的线程，线程的总数可通过配置文件来指定，但任务执行的分片由分布式协调服务自动调度。Depot可以直接从Extractor获取到Block内容，然后执行数据导出的任务，先后执行区块解析、内容转换处理、存储数据库，最后修改block_task_pool系统表的任务执行状态。 + +这样设计的优点是隔离了不同区块在不同线程间切换的数据交换开销，大大提升了处理的效率。同时，可以通过增加部署实例、增加处理线程集合的数量，来提升数据导出的速度。如果把内容转换和内容存储比作花蜜的酿造和存储，那么区块解析就似花粉的采集——这项使工蜂日夜辛劳的工作任务，最能诠释『穿花度柳飞如箭， 粘絮寻香似落星』。 + + + +如上图所示，区块解析的结果共分为四类：区块基本信息、账户信息、函数信息、日志信息。以下为解析的简要思路： + +1、 合约加载：解析器在执行前，会加载合约的BIN、ABI和配置信息，并计算所有合约函数的MethodId。 + +2、 账户解析：根据Block可以获取区块的合约地址，根据合约地址获取runcode，再通过预先加载的合约BIN信息，识别账户的类型，最终解析出账户。 + +3、 函数解析：如果函数为构造函数，如1所述，可以解析出函数的值。 + +如果函数非构造函数，则transaction中的to字段即为合约地址。如2所述，根据合约地址可以获得函数所属的合约。再根据transaction中附带的input和预先加载的methodId进行比对，可获得函数名。 + +在精准定位了函数所属合约和函数名以后，会自动触发transactionHandler，并执行对应的解析工作。 + +4、 事件解析:基于步骤2已解析的transactionHash与合约名的映射，可以获取合约名称。根据特定的合约名称，会自动触发该合约下的eventHandler，并执行对应的解析工作。 + +5、 区块解析:根据获得的Block对象的属性解析，获得区块的概要信息。 + +所有的这些解析步骤，相同的区块都由一个工蜂来负责完成，每个工蜂为一个线程。这些线程通过线程集合，由分布式协调服务来统一分配和管理，从而达到『飞如箭』和『似落星』的效果。Bee系统严格遵循了『技能专一』的原则，致力于为FISCO BCOS提供数据导出服务，因为专一，所以极致。 + +## 总结 + +WeBASE的社区还在蓬勃发展中，欢迎来到WeBASE的动物园漫步，和我们一起发现和探索更多有趣的故事，期待未来动物园的故事里有你。 + +------ + +#### 链接指引 + +- [区块链底层平台FISCO BCOS代码仓库](https://github.com/FISCO-BCOS/FISCO-BCOS/tree/master-2.0) + +- [FISCO BCOS技术文档](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/) + +- [WeBASE代码仓库](https://github.com/WeBankFinTech/WeBASE) + +- [WeBASE技术文档](https://webasedoc.readthedocs.io/zh_CN/latest/index.html) + diff --git a/3.x/zh_CN/docs/articles/4_tools/41_webase/webase-transaction.md b/3.x/zh_CN/docs/articles/4_tools/41_webase/webase-transaction.md new file mode 100644 index 000000000..b355a1126 --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/41_webase/webase-transaction.md @@ -0,0 +1,96 @@ +# 漫谈WeBASE之交易两三事 + +作者：刘明臻｜FISCO BCOS 核心开发者 + +2019年7月2日，区块链中间件平台WeBASE正式对外开源，大家首先会想到的就是：WeBASE是什么，有什么用？WeBASE是WeBank Blockchain Application Software Extension的简写，是在区块链应用和FISCO BCOS节点之间搭建的一套通用组件。开发这套通用组件的目的是为了屏蔽区块链底层的复杂度，降低开发者的门槛，提高区块链应用的开发效率。WeBASE主要包含：节点前置、节点管理、交易链路，数据导出，Web管理平台等子系统。其完整部署架构如下图： + + + +详细了解WeBASE请点击前往：《[FISCO BCOS迎来区块链中间件平台WeBASE，应用落地提速](https://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485307&idx=1&sn=40b0002d3d261be7c2daadd73697a131&chksm=9f2ef567a8597c719225f87a490ea3307a537518cbbcd04a1c5881828a3d4ba1ae7714609522&token=773706277&lang=zh_CN#rd)》。我们计划推送WeBASE系列文章，与你一道体验WeBASE的“简约而不简单”。本文是系列文章第一篇《漫谈WeBASE之交易两三事》，打算谈谈WeBASE在交易相关方面做的一些工作。 + +## 交易的概念、基本数据结构及过程 + +交易可认为是一段发往区块链系统的请求数据，用于部署合约，调用合约接口,以求达到维护合约的生命周期，管理资产，进行价值交换等目标。交易的基本数据结构包括发送者，接受者，交易数据等。 + +一个完整的交易过程可分为交易构建并**链上执行、交易展示、交易审计**三步： + +- 首先用户可以构建一个交易，用自己的私钥给交易签名，发送到链上（通过sendRawTransaction等接口）；然后链收到交易并交由多个节点机制处理，执行相关的智能合约代码，生成交易指定的状态数据；最后将交易打包到区块里，和状态数据一起落盘存储。落盘交易即为被确认，被确认的交易通常被认为具备了事务性和一致性。 +- 随着交易确认，相应的还会有交易回执（receipt）产生，和交易一一对应且保存在区块里，用于保存一些交易执行过程中生成的信息，如：结果码、日志、消耗的gas量等。用户可以使用交易hash查询交易，交易回执展示给用户。 +- 随时间推移，链上交易越来越多，需要对链上交易进行分析，辅助监管和审计链上的行为，确保链的合理、合规运行。 + +大家对交易有了初步的了解，接下来我们就从交易的三步曲中，详细探讨WeBASE在其中充当的角色和发挥的作用。 + +## 交易上链 + +通过WeBASE有多种发送交易上链的方式,比较常见的有WeBASE管理平台和交易上链代理子系统等两种，前者由WeBAS管理平台提供一个合约IDE，可以部署和调用合约接口，这里就不赘述了。今天我们重点介绍下**交易上链代理子系统（[WeBASE-Transaction](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE-Transaction/index.html)）**。 + +目前，区块链开发者主要面临以下几个痛点： + +- 区块链学习成本高--不想关注区块链细节，想用传统的方式调用区块链服务。 + +- 现实业务的峰值可能超过区块链的处理能力--需要一套缓存系统来削峰平谷。 + +为了解决这些痛点，WeBASE-Transaction应运而生。WeBASE-Transaction是从很多区块链存证类型项目中总结出来的一套服务系统，以帮助大家快速搭建区块链应用，其功能主要是接收无状态交易请求，缓存到数据库中，再异步上链，服务支持分布式任务，多活部署，异地容灾。部署架构如下图： + + + +从部署结构图可以看到，WeBASE-Transaction具有以下几大特性： + +- **异步上链，过载保护**：区块链请求先缓存数据库，削峰平谷，由服务使用合理速度异步上链。 + +- **多活部署，分布式任务**：使用Zookeeper做分布式任务协调，将上链分为多个分布式任务，多活部署，异地容灾。 + +- **错误重试，实时对齐**：服务自动查验上链状态，错误重试，达到数据库和链上状态的实时对齐。 + +## 交易展示 + +交易上链代表着终于把数据写入区块链了。兴冲冲地跑去给老板汇报：我们数据上链啦！老板听了既高兴，也很好奇。区块链这么高深，写入区块链的数据如何展示出来？区块链交易长啥样？ + +此时你可以搭建一套WeBASE管理平台。搭建方法可以查看《[安装部署文档](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE-Install/index.html)》。使用方法可以查看《[WeBASE管理平台使用手册](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE-Console-Suit/index.html#webase)》。搭建完成后，打开WeBASE管理平台，你会发现交易是这样的：发送者、接受者、交易输入数据等。交易执行后，会产生交易回执。交易回执里面有event，记录了交易执行过程中的事件日志。 + + + + + +老板看后第一感觉，肯定是五味杂陈。此时你轻点“解码”按钮，把交易从一串“0x的天书”翻译成人类能读懂的模样。哪个用户通过哪个合约方法上链的，一目了然。老板看后必投来赞许的目光。此时你想必会有一种普天之下，舍我其谁的感觉。 + + + + + +## 交易审计 + +交易上链了，也展示了，但这还不够。联盟链中各个机构，按照联盟链委员会制定的规章，在链上共享和流转数据。这些规章往往是字面的，大家是否遵守，缺乏监管和审计。因此为了规范大家的使用方式，避免链的计算资源和存储资源被某些机构滥用，急需一套服务来辅助监管和审计链上的行为。WeBASE管理平台提供的交易审计，就是一套辅助监管和审计链上行为的服务。它结合区块链数据、WeBASE管理平台的私钥管理和合约管理三者的数据，以区块链数据为原材料，以私钥管理和合约管理为依据，做成的一个综合性的数据分析功能。 + +交易审计主要指标： + +| 用户交易数量统计 | 监控链上各个外部交易账号的每日交易量 | +| -------------------- | ------------------------------------------------------------ | +| 用户子类交易数量统计 | 监控链上各个外部交易账号的每种类型的每日交易量 | +| 异常交易用户监控 | 监控链上出现的异常交易用户（没在区块链中间件平台登记的交易用户） | +| 异常合约部署监控 | 监控链上合约部署情况，非白名单合约（没在区块链中间件平台登记的合约） | + +交易审计界面如下 + + + +WeBASE管理平台提供可视化的去中心化合约部署、交易监控、审计功能，方便识别异常的用户、异常的合约，还有异常的交易量，为联盟链治理提供依据。 + +## 回归初心 + +到这里，我们可以看到一条交易，从组装发到区块链节点，然后节点执行落盘成交易回执，交易和state，再到交易展示，交易事后审计和监管。WeBASE参与了其中的组装上链、交易展示、交易审计，基本上可以说WeBASE参与了交易的全过程。 + +在组装上链过程中提供了交易上链代理子系统，其有效屏蔽了区块链底层的复杂度，降低了开发者的门槛，助力开发者高速搭建联盟链应用。在交易展示过程中，WeBASE搭建了可视化的管理平台，对交易进行了立体化展示，方便开发者实时监控和查看交易数据。在交易事后审计和监管过程中，还提供了综合的数据分析功能，辅助监管和审计链上的行为，高效治理联盟链。 + +------ + +#### 链接指引 + +- [区块链底层平台FISCO BCOS代码仓库](https://github.com/FISCO-BCOS/FISCO-BCOS/tree/master-2.0) + +- [FISCO BCOS技术文档](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/) + +- [WeBASE代码仓库](https://github.com/WeBankFinTech/WeBASE) + +- [WeBASE技术文档](https://webasedoc.readthedocs.io/zh_CN/latest/index.html) + diff --git a/3.x/zh_CN/docs/articles/4_tools/41_webase/webase_data_output.md b/3.x/zh_CN/docs/articles/4_tools/41_webase/webase_data_output.md new file mode 100644 index 000000000..c327e3a19 --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/41_webase/webase_data_output.md @@ -0,0 +1,242 @@ +# WeBASE数据导出：助力区块链大数据场景快速落地 + +作者：张龙｜FISCO BCOS 核心开发者 + +随着区块链技术的快速发展，各类应用如雨后春笋般涌现，链上数据呈指数级增长，基于区块链的大数据场景成为兵家必争之地，数据分析也成为刚需。 + +然而由于链上数据的存储特点，只能通过接口方式从链上直接获取，这种方式需要针对智能合约接口编写大量的代码，成本很高；同时从链上读取数据，除过网络开销，还需要进行解码操作，甚至遍历MPT树等，读取性能差；更重要的是，不能直接在链上进行全局数据处理，从而无法满足大数据场景的需求，比如复杂查询、大数据挖掘和分析等。 + +针对用户的需求，我们致力于提供一种自动化、智能化的数据导出解决方案，并通过不断迭代完善，满足用户基于数据导出的各种诉求，助力区块链大数据场景快速落地。本文将从用户需求出发，逐层揭开**WeBASE数据导出**组件功能、特性和架构演进的神秘面纱。 + +WeBASE是在区块链应用和FISCO BCOS节点之间搭建的中间件平台，对技术和业务架构中的共性进行抽象，形成通用化且体验友好的组件，简化区块链应用开发流程。 + +### 用户说：链上获取数据性能差，不便于大数据处理，便有了WeBASE-Collect-Bee + +对于用户而言，希望有原始数据支持大数据处理，但由于区块链特有的链式存储结构及出于安全性而设计的编解码操作及状态树等，使得从链上读取数据性能很差，于是我们设计了[WeBASE-Collect-Bee](https://github.com/WeBankFinTech/WeBASE-Collect-Bee/tree/master ) 。 + +WeBASE-Collect-Bee初步架构如下图所示，其目的在于降低获取区块数据的开发门槛，提升数据获取效率，支持大数据处理，用户只需要进行简单配置，就可以把区块数据导出到指定的存储介质上，比如支持复杂的关系查询、大数据挖掘的数据库或大数据平台上。 + + + +WeBASE-Collect-Bee包括三个模块：区块获取模块、区块处理模块和持久化模块。 + +- 区块获取模块：根据区块ID获取相应的区块； +- 区块数据处理：解析区块数据、区块交易数据； +- 账户数据处理：解析区块链账户数据。 + +用户只需要提供链的相关配置及数据库配置，就可以一键导出链上的数据，后续可以采用SQL的方式对数据库中的数据进行操作，同时只要确保WeBASE-Collect-Bee服务正常运行，数据库可以几乎实时同步链上的数据。 + +### 用户说：业务数据获取工作量大，且不便于维护和复用，便有了WeBASE-Codegen-Monkey + +只有区块数据是远远不够的，用户更关心业务数据，即交易数据。交易数据通过调用智能合约方法上链，同时为了便于查看交易执行情况，交易中存在大量的log数据，即event数据，event数据对业务分析至关重要。 + +要想获取交易数据和event数据，必须针对区块链上的每一笔交易和event，根据智能合约进行解析，核心模块至少包括：交易/event和数据解析、数据库访问接口、POJO、SQL几个模块。 + +如下图所示，假设我们的业务包含2个智能合约、每个智能合约包含2个接口和2个event，每个模块都需要独立编写代码，那么至少需要编写32个代码文件或脚本，工作量相当大，维护复杂，且不能复用。 + + + +基于此，我们设计了[WeBASE-Codegen-Monkey](https://github.com/WeBankFinTech/WeBASE-Codegen-Monkey) 。WeBASE-Codegen-Monkey用于生成解析和存储交易/event数据的所有核心代码。用户无需编写任何代码，只需要提供智能合约文件，WeBASE-Codegen-Monkey会自动解析合约，生成获取交易/event数据的所有代码文件，并自动和WeBASE-Collect-Bee组装成为一个独立的服务。WeBASE-Codegen-Monkey架构如下图所示。 + + + +WeBASE-Codegen-Monkey包括合约解析模块、代码模板模块、代码生成模块、组件组装模块。 + +- 合约解析模块：解析智能合约文件，获取合约中的交易和event对象； +- 代码模板模块：用于生成获取交易/event数据的代码模板； +- 代码生成模块：根据获取的交易和event对象，填充代码模板，生成代码文件； +- 组件组装模块：用于将生成的代码和WeBASE-Collect-Bee组装成一个独立的服务。 + +由于新增了交易/event数据的获取，相应的WeBASE-Collect-Bee架构演进如下，新增交易数据处理模块和事件（event）数据处理模块。用户只需要提供智能合约文件，就可以获取几乎链上的所有数据。 + + + +从用户使用的角度来讲，只需要将链的证书文件和智能合约文件放在指定的目录下，然后进行节点和数据库配置，并设置智能合约的包名即可。 + +``` +#### 节点的IP及通讯端口、组号。NODE_NAME可以是任意字符和数字的组合 +system.nodeStr=[NODE_NAME]@[IP]:[PORT] +system.groupId=[GROUP_ID] + +#### 数据库的信息，暂时只支持mysql；serverTimezone 用来设置时区 +system.dbUrl=jdbc:mysql://[IP]:[PORT]/[database]?useSSL=false&serverTimezone=GMT%2b8&useUnicode=true&characterEncoding=UTF-8 +system.dbUser=[user_name] +system.dbPassword=[password] + +# 合约Java文件的包名 +monitor.contractPackName=[编译Solidity合约时指定的包名] +``` + +### 用户说：有了数据，要使用还需要开发数据访问接口，不方便，便有了用户接口 + +对于用户而言，尽管我们已经将用户关心的所有数据导出到DB中，且每一张表的名称和交易方法/event名称对应，字段名称直观易懂，但如果用户想在自己的系统中使用数据，还需要编写大量的数据库访问接口。基于此，WeBASE-Collect-Bee中增加了**用户接口模块**，如下图所示。 + + + +用户接口模块提供两种数据访问方式，一种是API方式，支持用户系统本地调用；另一种为REST方式，可通过http方式访问，降低了业务的耦合性，支持跨平台调用。 + +用户接口按照数据类型分成四类接口：区块数据接口、账户数据接口、交易数据接口和事件数据接口。其中，每类接口中都支持基于块高、hash或账户的查询，同样也支持基于时间、特定字段的复杂查询。用户接口使得用户在使用数据导出组件时，可以和自身系统零成本对接。 + +除此之外，为了便于用户进行可视化数据验证和查看，数据导出组件集成了Swagger插件，当用户完成数据导出服务部署后，可在浏览器中输入http://your_ip:port/swagger-ui.html，查看所有用户接口，并输入查询条件，进行可视化查询，如下图所示。 + + + +### 用户说：有了数据和查询接口，但是不够直观，老板看不懂，便有了Grafana集成 + +为了更加实时、可视化的展示区块链数据，满足产品、运营等非技术人员的需求，基于轻量化考虑，最终我们选择了可视化数据插件Grafana。 + +然而Grafana展示数据需要针对每一张表数据编写Dashboard模板，学习和编写模板成本很高。不过不用担心，WeBASE-Code-Monkey会自动生成Grafana脚本。用户只需要安装Grafana并进行数据源配置，然后导入生成的Dashboard模板脚本即可，实现数据可视化可在1分钟内完成，如下图所示。 + + + + +### 用户说：一个服务导出数据太慢，服务挂了怎么办，便有了多线程处理和分布式部署 + +对于数据导出服务，一旦链的性能很高，超过单机数据导出的TPS，那么DB中永远获取不到最新的数据，且数据会越来越旧，显然无法满足业务对数据的诉求。同时单机处理的风险在于系统稳定性很差，一旦单机服务挂掉，就无法获取最新数据，且无法使用用户接口进行交互。因此我们引入了多线程处理和分布式部署，架构演进如下图所示。 + + + +#### 线程管理 + +线程管理相对简单，只需要关闭多活开关，开启单节点任务模式，同时对独立线程处理的区块数进行设置即可。如下，系统默认开启4个线程，进行区块抓取和处理。 + +``` +#### 当此参数为false时，进入单节点任务模式 +system.multiLiving=false +#### 多线程下载的分片数量，当完成该分片所有的下载任务后，才会统一更新下载进度。 +system.crawlBatchUnit=100 +``` + +#### 多活管理 + +为了进一步提升数据导出效率，确保系统稳定性和容错性，我们集成了Elastic-Job，支持分布式部署、任务分片、弹性扩容、并行调度和定制化流程任务。数据导出组件在分布式环境下，首先通过一个SimpleJob对区块进行抓取，然后通过DataflowJob对区块进行处理。 + +考虑到使用Elastic-Job的成本，系统会自动生成任务分片和执行策略的所有配置，除过几个必要配置，用户不需要做任何事情就可以完成多活配置和部署。必要配置如下。 + +``` +#### 当此参数为true时，进入多节点任务模式 +system.multiLiving=true + +#### zookeeper配置信息，ip和端口 +regcenter.serverList=ip:port +#### zookeeper的命名空间 +regcenter.namespace=namespace +``` + +### 用户说：导出的数据量太大，查询和存储性能跟不上，容易崩，便有了分库分表 + +当区块链上存在海量的数据时，导出到单个数据库或单个业务表会对运维造成巨大的压力，造成数据库性能的衰减。一般来讲，单一数据库实例的数据阈值在1TB之内，单一数据库表的数据阈值在10G以内，是比较合理的范围。 + +如果数据量超过此阈值，建议对数据进行分片。将同一张表内的数据拆分到多个或同个数据库的多张表中，即分库分表。数据导出引入数据管理模块，架构演进如下图所示。 + + + +数据管理模块集成Sharding-JDBC，支持分库分表和读写分离。用户只需要设置分片数，系统会自动生成分片策略配置。如果需要支持读写分离，可以在生成的WeBASE-Collect-Bee中进行配置，可参考[数据导出高级配置](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE-Collect-Bee/install.html)。在用户接口层，用户可以无感使用同一套接口，感觉是在同一个库或表中操作一样。 + +``` +#### 交易和event数据分片配置 +system.contractName.[methodName or eventName].shardingNO=XXX +#### 区块和账户数据分片配置 +system.sys.[sysTableName].shardingNO +``` + +### 用户说：链上出现临时分叉或服务异常，DB数据不一致，便有了异常处理和监控报警 + +数据导出服务旨在导出链上数据。在确保性能、稳定性、可扩展性的前提下，如果选择了非高度一致性的共识机制，链上会有一定概率出现临时分叉，导致数据库出现脏数据；或者由于网络/服务异常等原因，导致数据导出服务无法导出链上最新数据。 + +为了确保数据正确性、数据一致性，数据导出组件新增异常管理模块和监控脚本，至此，数据导出组件功能已非常强大，完整架构如下图所示。 + + + +#### 异常处理 + +异常处理主要为了校验导入DB数据的正确性，如果选择了非高度一致性的共识机制，链上会有一定概率出现临时分叉，可能导致DB中的数据和链上的数据不一致。 + +基于6个区块后链上分叉概率趋近于0的理论，每次导出数据之前，异常管理模块会针对最近6个区块进行hash校验，如果一致，则继续导出。如果不一致，则回滚大于等于异常区块高度的所有区块数据，然后重新拉取和导入。 + +#### 监控报警 + +即使有分布式部署保证数据导出服务的稳定性，但无法保证链上数据是否真正的导出。监控脚本monitor.sh用于监控链上数据是否真正的导出。主要基于两个维度： + +- 一段时间内，DB中的数据开始落后于链上数据，直到达到某个阈值； +- 链上块高增加，一段时间内，DB中块高不变。 + +用户可以根据实际情况自行配置，如下所示。 + +``` +#### 数据导出的进度落后于链高度的报警阈值，输出报警日志 +threshold=20 +#### 如当前块高增长，但完成导出的区块数量增长小于等于1，则输出报警日志 +warn_number=1 +``` + +## 用户你尽管说 + +### 用户说：链上历史数据没有价值，全量抓取浪费资源，只想要最近的数据。 + +数据导出组件支持从特定时间或特定块高拉取数据，只需要进行简单配置即可，如下。 + +``` +#### 设置数据导出的起始高度 +system.startBlockHeight=XXXX +#### 设置数据导出的起始时间 +system.startDate=XXXX +``` + +### 用户说：我只想要部分交易/event的数据，或者只要交易/event中的部分字段数据。 + +在实际场景中，用户可能并不需要全量数据，只需要特定交易/event的数据，或者特定交易/event中的特定字段数据，数据导出支持个性化导出，可按如下配置。 + +``` +#### 设置特定交易或event数据是否导出，默认全部导出 +monitor.[contractName].[methodName/eventName].generated=on/off +#### 忽略特定合约特定event的特定字段不进行抓取 +monitor.[contractName].[methodName/eventName].ignoreParam=XXX,XXX +``` + +### 用户说：链上数据增长的不快，线程一直空转浪费机器资源。 + +数据导出组件可以灵活配置数据抓取任务的频率，可通过如下配置项进行修改。 + +``` +#### 所有method和event的抓取频率，默认5秒轮询一次 +monitor.default.frequency=5 +``` + +### 用户说：交易/event的个别字段采用string类型，数据库默认255，会导致入库报错。 + +数据导出对于智能合约中的bytes和string类型默认采用VARCHAR(255)，这种设计是为了节省数据库资源，能满足绝大部分场景，但同时也存在个别字段超过255长度，导致数据不一致。因此数据导出组件针对超长字段提供配置，可有效合理利用数据库存储空间，避免资源浪费。 + +``` +#### 配置特定合约中特定交易/event的特定字段在数据库中的长度 +length.[contractName].[methodName or eventName].[paraName]=1024 +``` + +### 用户说：导出原始数据不是我想要的，比如某个账户的最新余额，而不是所有变更历史。 + +数据导出组件会导出链上的全量数据，包含所有的历史数据。针对用户的特定数据需求，数据导出组件支持本机编译，复制执行包到其他服务器上运行，在执行generate_bee.sh后，会生成完整的WeBASE-Collect-Bee服务工程，用户可基于工程源码进行二次开发，修改导入数据的策略。 + +### 用户说：整体服务功能很强大，但是我只想把部分功能集成到自己的系统中。 + +数据导出服务考虑到模块耦合性，将整个WeBASE-Collect-Bee拆分成为区块获取、数据解析，数据库操作和公共模块，用户可按照自己的需求直接使用独立的模块。 + +## 用户不仅仅可以说 + +对于任何一个方案，没有最完美的，只有最适合的。数据导出组件致力于解决区块链大数据场景问题，不仅可以适用于具体的业务诉求，对于一个区块链项目而言，还可以作为贯穿开发、测试和运营的利器，提升研发、测试和运营的效率。 + +对于用户的需求，我们的一贯态度是：欢迎说，但也不怕说，必要时你必须得说。面对志同道合的小伙伴，我们也早已给出答案：聊，随时恭候；来，双手欢迎。 + +除了积极参与区块链领域的技术开源，我们也致力于和广大用户共建开源生态，用户不仅仅可以说，还可以加入我们，这里不仅有前沿的黑科技，还有诗和远方！ + +------ + +#### 链接指引 + +- [区块链底层平台FISCO BCOS代码仓库](https://github.com/FISCO-BCOS/FISCO-BCOS/tree/master-2.0) + +- [FISCO BCOS技术文档](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/) + +- [数据导出代码仓库]( https://github.com/WeBankFinTech/WeBASE-Codegen-Monkey) + +- [数据导出技术文档](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE-Codegen-Monkey/index.html) + diff --git a/3.x/zh_CN/docs/articles/4_tools/41_webase/webase_node_preposition.md b/3.x/zh_CN/docs/articles/4_tools/41_webase/webase_node_preposition.md new file mode 100644 index 000000000..26710d7f8 --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/41_webase/webase_node_preposition.md @@ -0,0 +1,94 @@ +# WeBASE节点前置组件功能解析 + +作者：何硕彦｜FISCO BCOS 核心开发者 + +FISCO BCOS搭链脚本已经让开发者有极致的搭链体验，怎样能快速搭建一个区块链可视化界面，以便跟区块链交互，WeBASE-Front就是可以最快满足这个期望的组件。WeBASE-Front为开发者提供区块链交互最小功能的子集，安装轻量便捷，无需安装任何第三方组件。在搭完节点之后搭建WeBASE-Front，可以在浏览器打开界面，快速开启区块链体验之旅。 + +WeBASE-Front还提供了很多友好且实用的功能： + +- 在WeBASE-Front首页界面，开发者可以查看到区块链的区块信息、交易信息、群组信息、节点数量、节点状态等，**对区块链网络的核心信息一目了然**。 +- WeBASE-Front提供了合约开发IDE，方便开发者在上面编写调试智能合约，**快速开发自己的区块链应用**。 +- WeBASE-Front集成了Web3SDK，并对Web3SDK接口进行了封装，开发者可通过HTTP请求，调用WeBASE-Front接口和区块链节点进行交互。这种方式屏蔽了SDK语言的限制，**任意语言的开发者都可以通过调用WeBASE-Front的接口与区块链交互**。 + +当然，WeBASE-Front的功能不限于此。作为WeBASE家族成员之一，该组件配合WeBASE-Node-Manager和WeBASE-Web一起使用，作为节点前置，对区块链网络的全方位监控，实现企业级区块链监控功能。 + +## 功能介绍 + +WeBASE-Front主要有以下五大功能： + +### 一、数据概览 + +显示开发者关心的常用数据：**区块块高、节点数量、交易总数、待交易数量，**并支持区块信息和交易信息的查询。 + + + +### 二、节点管理 + +显示区块链网络的**节点数量、节点ID、块高、pbftview和节点运行状态**，并支持区块链群组的动态切换。 + +### 三、合约管理 + +此为WeBASE-Front的核心功能，开发者可以在上面**编写、编译、调试合约**，以及**一键生成合约的JAVA类**，已部署合约会存在H2嵌入式数据库里，可以在合约列表里查询历史合约。 + + + +### 四、系统监控 + +系统监控分为两方面监控： + +1. 节点服务器的性能指标监控，包括**CPU、硬盘、内存、上行带宽、下行带宽**； +2. 区块链节点的性能指标监控，包括**区块高度、pbftview、待打包交易数**。 + +节点长久运行后，可以通过此功能查看服务器的性能。 + +### 五、私钥管理 + +生成椭圆曲线公私钥对，支持**导入导出私钥**，并支持给地址取别名，方便地址记忆。部署合约前需要先创建公私钥对。 + + + + +## 技术剖析 + +WeBASE-Front是基于FISCO BCOS提供的**spring-boot-starter**（请参考文末链接）项目的一个开发实例。**Web3SDK接口封装、动态切换群组、部署调用合约（无需生成JAVA类）、公私钥对产生，**这些通用功能请参考WeBASE-Front代码，开发者可以借鉴并编写自己的springboot应用。 + +为了方便安装和使用，WeBASE-Front采用了轻量级的**H2嵌入式数据库**，后端使用SSH框架，使用JPA访问数据库；前端采用**VUE**框架开发，前端资源内置在后端springboot服务中，无需安装配置nginx和mysql这些步骤，直接启动JAVA服务即可访问界面。 + +产生的公私钥和已部署的合约都会存储在H2数据库中，方便查询历史记录。性能监控功能采用的是**sigar**数据收集组件。采集的数据也会存在H2数据库中，但只保存最近一周的监控数据。 + +## 部署方式 + +作为节点前置，WeBASE-Front需要跟节点同机部署。一台机器部署多个节点时，建议只部署一个WeBASE-Front服务即可。 + +WeBASE-Front部署方式有以下三种： + +1. 单独部署作为独立控制台使用，并配有界面，部署简单快捷，只需下载WeBASE-Front应用，替换节点证书即可启动。推荐初学者和开发者使用此种部署方式，使用此组件查询区块链的相关信息和开发调试智能合约。（安装请参考文末链接） + +2. 方式1中，WeBASE-Front作为可视化控制台使用，私钥默认加密存储在H2数据库中，如果需要更安全的私钥保护方案，可以结合WeBASE-Sign服务一起部署使用，私钥保存在WeBASE-Sign中，WeBASE-Sign服务负责对交易数据进行签名，提供更安全的私钥保护方案。 + + 此方式在方式1的基础上再部署WeBASE-Sign服务，如果对私钥安全性要求较高，请采用此种部署方式。（WeBASE-Sign服务请参考文末链接） + +3. 结合WeBASE-Node-Manager和WeBASE-Web服务一起部署使用，这里WeBASE-Front只作为节点前置，多个节点前置统一由WeBASE-Node-Manager管理，WeBASE-Node-Manager有一套spring security实现的鉴权登录系统，并会拉取链上的区块信息和交易信息，存储在Mysql数据库中。生产环境下建议使用此种方式，架构图如下所示。（WeBASE安装部署请参考文末链接） + + + +## 总结 + +WeBASE-Front作为一个搭建便捷、功能强大的区块链组件，既可以独立使用，作为可视化控制台，方便开发者与区块链交互，也可以配合WeBASE-Node-Manager和WeBASE-Web一起使用，实现生产环境的区块链监控功能。 + +WeBASE-Front还在持续优化开发中，未来会增加越来越丰富的功能，如联盟链增删节点的系统管理功能、交易解析功能等。当然，持续迭代升级中也会保持它的易用性和便捷性。欢迎社区朋友提PR和ISSUE，一起参与优化。 + +------ + +#### 链接指引 + +- [Spring-boot-starter](https://github.com/FISCO-BCOS/spring-boot-starter/tree/master-2.0) + +- [Sigar数据收集组件](https://www.jianshu.com/p/c3d88dd617bf) + +- [WeBASE-Front单独安装部署说明](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE-Install/developer.html#) + +- [WeBASE-Sign服务](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE-Sign/index.html) + +- [WeBASE安装部署](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE-Install/enterprise.html) + diff --git a/3.x/zh_CN/docs/articles/4_tools/41_webase/webase_release.md b/3.x/zh_CN/docs/articles/4_tools/41_webase/webase_release.md new file mode 100644 index 000000000..e5f5bd62e --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/41_webase/webase_release.md @@ -0,0 +1,102 @@ +# FISCO BCOS迎来区块链中间件平台WeBASE，应用落地提速 + +随着区块链技术的发展，越来越多的开发者基于稳定和高效的区块链底层平台，结合智能合约和链上接口，开发各种丰富的应用，随之而来的是对区块链系统的易用性、应用开发速度、业务组件丰富性产生了更多的需求。 + +直面底层平台，“裸写”智能合约和底层代码，在技术上是可行的，而进一步提供“所见即所得”、“开箱即用”这种无门槛体验的动力，则来自社区开发者的反馈，比如： + +- 缺乏好用的智能合约开发工具，合约的开发和调试效率不高，难以便捷地管理链上各节点配置信息，观察其运行状态。 + +- 区块链上的区块、交易、回执等数据的呈现方式不够友好，对链上的海量数据难以进行灵活和多维度的分析。 + +- 针对参与到业务的各账号及其进行的交易行为，需要通用的审计工具，以便及时发现和杜绝异常。 + +为响应开源社区里持续的需求，同时将自身长期探索的成果开放分享， FISCO BCOS开源工作组成员单位——微众银行，为社区贡献一条从区块链底层通往应用落地的高速通道。 + +**7月2日，微众银行正式开源自研的区块链中间件平台——WeBASE，该平台适配支持FISCO BCOS底层平台**，面向多种对象，如开发者、运营者，并根据不同的场景，包括开发、调试、部署、审计等，打造丰富的功能组件和实用工具，提供友好的、可视化的可操作环境。 + +基于FISCO BCOS底层平台，部署WeBASE，可以简化区块链应用开发流程，大大降低企业搭建区块链应用，以及进行运营分析的时间成本、人力成本，使开发者可得心应手的操控区块链网络，更专注投入到应用开发和业务落地中。 + +**WeBASE代码仓库地址**：https://github.com/WeBankFinTech/WeBASE + +## WeBASE简介 + +**WeBASE（WeBank Blockchain Application Software Extension） 是在区块链应用和FISCO BCOS节点之间搭建的中间件平台，**如下图所示，开发者可在区块链节点上层部署WeBASE的可交互模块如浏览器、管理台和其他工具等，也可以基于WeBASE内置的组件和API，进行应用的开发。 + + + +WeBASE的“**简约而不简单**”，体现在以下几个方面： + +一 、提供友好的智能合约开发平台，支持在线编译、调试、测试、部署智能合约，具有高效的编辑环境，率先支持Solidity智能合约语言。 + + + +二、在SDK基础上封装Restful风格的API接口，Restful接口更直观，有良好的可扩展性，可轻松适配多种编程语言。通过接口可对交易数据进行编解码，可在包括网页、手机终端等设备上全方位、多维度展示链上数据细节。 + + + +三、区块链管理平台是运营管理员的首选工作台，可查看链上的数据统计、每个区块的详情、各个节点多维度的统计数据，对节点的健康度做到全方位监控。 + + + +四、数据导出组件可配置式的导出链上数据到关系型数据库、大数据处理等系统，以便对链上数据进行多元化处理，如进行数据挖掘，构建商业模型等。 + +## WeBASE的整体架构和设计原则 + +WeBASE的完整架构如下图所示： + + + +WeBASE的设计理念是一个子系统解决一个问题，无需部署所有子系统就能跑起来，因此在设计之初就遵循如下原则： + +**按需部署**：WeBASE抽象对应用开发通用共性进行抽象，形成各类服务组件，如业务接入、私钥管理、交易队列、合约开发、数据导出、审计等，开发者根据需要部署所需组件。 + +**微服务架构**：WeBASE采用微服务架构，基于spring-boot框架，提供Restful风格接口。 + +**零耦合**：WeBASE所有子系统独立存在，均可独立部署，独立运行，面向不同的场景提供服务，避免出现“全家桶”式的冗余负担。 + +**可定制**：前端体验往往带有开发者自身的业务表现，如不同的样式、不同的交互风格、不同的品牌表现等，因此WeBASE采用前后端分离的设计，后端接口保持稳定和可扩展，前端页面则由开发者自由定制。 + +## 基于WeBASE的应用开发流程 + +基于WeBASE的应用开发流程有全新的体验，下图直观比对两种开发流程的不同： + + + +显然，基于WeBASE的应用开发，流程大大简化。智能合约开发工具、完善的数据可视化平台、简易的交易上链方式，降低了开发门槛，使得开发效率大幅提升。而且对于应用上线后的交易审计、数据导出、立体监控等方面的管理，WeBASE为其提供一系列完善的组件，能有效避免开发者和企业重复破荒造路。 + +## WeBASE的下一步 + +今天，**WeBASE开源只是一小步，未来，WeBASE将有计划地开放更多功能**： + +- 提供更多直面商业领域的、经过业务验证的组件，便于集成到有共通模式的应用中，建立区块链应用开发最佳实践和标准架构； +- 提供各类行业解决方案和参考实现； +- 为云厂商提供更友好的接入方式。 + +## 社区开发者体验 + +- **网络技术总监 林冬艺** 广州市品高软件股份有限公司 + +> 品高软件是一家云计算公司，正在探索云计算与区块链的融合创新。WeBASE具有友好的界面设计、便捷的管理以及云生态的良好融合等特点，使得区块链上云变得更轻松，我们得以更专注于区块链与云计算的业务场景。 + +- **架构师 魏巍** 宝付网络科技（上海）有限公司 + +> WeBASE操作简便，社区文档非常完善，涵盖企业所需的各类组件，可插拔式的架构设计，根据所需组合使用，帮助我们解决区块链技术的后顾之忧，缩短业务数据化进程，快速实现业务价值。 + +- **CTO 金兆康** 杭州亦笔科技有限公司 + +> WeBASE的联盟治理、前置管理功能使得管理区块链就像管理聊天群一样简单。社区的及时响应、功能的快速迭代，处处体现出国内顶级区块链服务提供商的实力。 + +- **区块链架构师 孙耀普** 全链通有限公司 + +> WeBASE各系统模块都提供了丰富的部署文档，明确的部署步骤，按照部署文档就可以很快部署和使用，系统的UI设计和布局也非常合理。 +> +> 注册和登录功能，满足了客户关于区块链信息查询权限管理需求，减少了开发的工作量；系统集成了FISCO BCOS的java接口，提供了丰富的调用接口，减轻了开发工作量，降低了区块链的使用难度。 +> +> 系统提供智能合约的编辑和编译和部署功能，使智能合约开发更加便捷。 + +- **创始人 张泷** 聚滴成海(广州)信息技术有限公司 + +> 聚滴成海是一家专注区块链深层次挖掘的中间件提供服务商，我们需要直接对客户提供封装好的接口，来降低他们的开发工作量。由于我们产品性质的特殊，需要兼容多种生态、包容多种共识机制，因而我们的开发工作量非常庞大！ +> +> 但是WeBASE将各种接口已经封装的非常完善，只需稍作暴露就可以快速连接！希望WeBASE可以继续坚持对开源社区的支持，我们也愿意为之不断付出和贡献。 + diff --git a/3.x/zh_CN/docs/articles/4_tools/42_buildchain/fast_build_chain.md b/3.x/zh_CN/docs/articles/4_tools/42_buildchain/fast_build_chain.md new file mode 100644 index 000000000..71b6a7a76 --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/42_buildchain/fast_build_chain.md @@ -0,0 +1,87 @@ +# FISCO BCOS快速建链实现之路 + +作者：白兴强｜FISCO BCOS 核心开发者 + +跟很多开发者一样，团队刚开始搭链时，也经历过迷之困惑的阶段：安装哪个版本，怎么编译这么久还容易出错？配几个节点，都用什么IP端口？证书从哪里来，放到哪里去？怎么验证我的链确实搭起来了？... + +相信从FISCO BCOS1.X版本上手的工程师们，内心都有一座小火山，面对超长的文档、超多的操作步骤……每次版本部署，耗费大量时间，工程师头上都快能摊熟一枚鸡蛋。而数据表明，一个软件如果15分钟还使用不起来，用户就会流失。 +为了浇灭大家心中的小火山，一起愉快地玩耍区块链，FISCO BCOS的易用性优化势在必行。团队的第一个目标是让开发者**在5分钟内搭起开发测试链**，这就需要一个《哈利•波特》里召唤术一样的命令，我们把它称为**build_chain**。 +本文将聊聊build_chain脚本的诞生记，以及当前脚本能够提供的帮助。 + +## build_chain脚本的诞生 + +首先是去掉编译步骤，源码编译不但需要安装下载依赖，还需要配置开发环境，即便这两步一切顺利，编译过程中还可能因为内存不足而失败，更何况下载依赖经常受到网速影响导致下载失败。于是我们提供了预编译的二进制发布包，让用户跳过冗长的编译阶段。 +马上我们又发现了新的问题，即使针对不同平台都提供二进制发布包，用户的环境是千变万化的，预编译程序所依赖的动态库的安装又成了问题。 +于是我们想到了提供静态编译的二进制发布包，兼容多种Linux64位操作系统，不依赖任何其他库，省时又省力。为了实现静态编译，我们不惜重新实现部分功能，以去掉对不提供.a的外部库的依赖。 +接下来我们尝试减少部署步骤，减轻对用户的压力。 + +配置项太多太灵活，我们优化配置，所有配置都提供合适的默认值，删除不需要灵活定制的配置项。 +json格式的配置文件阅读不够直观，手工修改容易因为格式问题导致错误，我们替换为更清晰的ini文件。 +系统合约手动部署太麻烦，我们借助预编译合约实现内置系统合约来管理链上配置。 +手工搭建和工具脚本搭建的节点目录结构不统一，我们整理文档，统一工具创建的目录结构，提供辅助脚本。 + +经过上述这些优化，我们认为可以有更轻量级的部署方式，可以尝试通过一个脚本来完成部署过程中的所有事情。 +相比于大而全的部署工具，脚本更轻更快；而相比于手工部署的繁琐，脚本能够更简单。这样，build_chain脚本就诞生了。 + +## build_chain脚本提供的帮助 + +这个脚本能够完成环境检查、参数解析、FISCO BCOS二进制发布包下载、公私钥证书生成、配置文件生成和工具脚本生成等功能，支持MacOS、Linux 64bit、docker模式和国密版本搭建。 +然而实际使用后，我们发现在家里的网络条件下，脚本下载二进制发布包需要很长时间，导致5分钟内无法完成搭起一条FISCO BCOS的链。 +为了能达成5分钟建链的目标，我们又新增了CDN支持，在哪怕网络条件不是很好的情况下，也可以顺畅地在5分钟内完成建链。心中的小火山熄灭了。 + +具体而言，build_chain脚本能够提供的帮助包括以下几个： + +### 环境检查 + +build_chain脚本需要使用OpenSSL来生成节点所需要使用到的相关证书文件，而FISCO BCOS 2.0要求使用OpenSSL 1.0.2以上版本。只有找到符合要求的程序版本，脚本才能继续执行。 +需要注意的是，MacOS自带的是LibreSSL，所以需要用户使用brew install OpenSSL安装OpenSSL。 + +### 解析参数 + +build_chain脚本支持很多自定义参数，例如-p指定节点使用的端口范围、-f搭建指定配置的网络、-g搭建国密版本、-v指定FISCO BCOS程序版本号、-o指定输出路径等，[可参考详情](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/build_chain.html#id4) + + + +### 获取FISCO BCOS可执行程序 + +FISCO BCOS提供标准版和国密版本的预编译可执行程序，可以在大部分x64的Linux机器上运行。另外，为方便开发人员调试，同时提供了MacOS版本的可执行程序。 + +- build_chain脚本会根据操作系统和是否国密下载对应的可执行程序。 +- 当从GitHub下载可执行程序较慢时，会自动切换到CDN下载。如下图可以看到fisco-bcos.tar.gz只有7.72M。 +- 当不使用-v选项指定版本时，脚本会自动拉去GitHub上FISCO BCOS发布的最新版本，使用-v选项时，则下载指定版本的可执行程序。 + +对除官方明确的Ubuntu 16.04+和CentOS 7.2+以外的平台，上生产时建议使用源码编译获得的可执行程序，然后通过-b选项和-f选项搭建区块链网络。 + + + +### 生成私钥证书 + +FISCO BCOS支持证书链，默认使用三级证书链结构，使用自签CA证书作为链的根证书，使用CA签发的机构证书用于区分机构，然后使用机构私钥签发节点所使用的证书。 +节点的conf目录下会有ca.crt、node.key、node.crt三个文件，节点使用这三个文件建立双向SSL链接，使用node.key在共识过程中为区块签名。 +如果是国密版本，则脚本会下载TaSSL工具，生成国密版本的证书文件。 + +### 生成配置文件和工具脚本 + +build_chain脚本中内置了FISCO BCOS节点所需要使用的配置文件模板，根据用户指定的参数修改，生成节点所使用的配置文件([可查看配置文件的介绍](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/configuration.html))。 + +同时，为方便用户启动和停止节点，节点目录下还会生成start.sh和stop.sh（[可查看节点目录结构说明](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/build_chain.html#id5)）。 + +## 总结 + +下面来总结一下，FISCO BCOS团队提升部署速度、实现快速建链的几个要诀： + +- 1．提供静态编译的二进制发布包，兼容多种操作系统，让用户跳过冗长的编译阶段。 +- 2．简化配置，极大限度采用能保证最大成功率的默认参数，最小化用户需要关注的信息，用户只需关注少量网络配置。 +- 3．标准化目录结构，无论是用一键搭链、企业级搭链、手工搭链...生成的目标都是一样的，降低了差异化带来的复杂度。 +- 4．巧用脚本，build chain脚本可自动串起从准备环境到启动所有链节点一系列常规操作步骤，自动处理各种可能的小异常，让整个过程显得行云流水。 +- 5．优化依赖库地址、网络速度等，极大减少用户的等待消耗，谈笑间，链已经搭好。 + +对于想通过手工搭建进一步学习的同学和生产环境使用，建议使用我们提供的企业级部署工具generator。 +在性能和易用性方面，做再多努力都是值得的，我们会继续努力优化，非常欢迎各位社区的参与者提优化建议和bug。 + +------ + +#### 参考链接 + +**企业级部署工具generator**：https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/enterprise_tools/index.html + diff --git a/3.x/zh_CN/docs/articles/4_tools/42_buildchain/index.md b/3.x/zh_CN/docs/articles/4_tools/42_buildchain/index.md new file mode 100644 index 000000000..56e521013 --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/42_buildchain/index.md @@ -0,0 +1,9 @@ +### 一键搭链脚本工具 + +```eval_rst +.. toctree:: + :maxdepth: 1 + + fast_build_chain.md +``` + \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/4_tools/43_console/console_details.md b/3.x/zh_CN/docs/articles/4_tools/43_console/console_details.md new file mode 100644 index 000000000..eb5c7d5bd --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/43_console/console_details.md @@ -0,0 +1,96 @@ +# FISCO BCOS 控制台详解，飞一般的区块链体验 + +作者：廖飞强｜FISCO BCOS 核心开发者 + +我们对Linux系统中的命令行终端已经很熟悉了，通过shell终端可以顺畅地使用Linux。类似地，FISCO BCOS联盟链中，也有这样的命令行终端，称为控制台。控制台是开发者探索区块链世界的助推器，其提供的各种功能有助于跨越横在区块链入门到精通之间的座座高山，带来“开箱即用”的顺滑体验。 + +## Why: 为什么要做控制台？ + +### 体验环境影响用户从“入门到放弃”，或者“入门到精通”。 + +当学习一个新技术或产品时，除了读文档之外，尝试上手操作，获得第一手体验也尤为重要。如果体验环境配置复杂、操作繁琐，很可能导致用户从“入门到放弃”；而体验环境简单易配置、功能丰富，则会为用户迅速打开一扇新世界的大门，加速用户从入门到精通。 + +选择何种形式承载这种极速且友好的体验方式呢？如果我们有一个控制台，只要输入单条命令或代码，然后按下回车键就可以返回结果显示在用户面前。这种 “开箱即用”的效果，正是我们所期待的体验方式。 + +### 可以为FISCO BCOS实现极速体验的控制台吗？ + +FISCO BCOS 1.3版本其实已经具备快速体验的功能，由两部分组成，分别是ethconsole和Node.js工具。其中，ethconsole可以查询链上信息，包括节点、区块和交易信息；Node.js工具提供了部署和调用合约的模板js文件，协助用户实现合约的部署与调用。 + +但是这种体验方式还不够友好，那一版的ethconsole只能查询非常有限的链上信息，并不能发送交易和管理区块链，功能比较单一；通过Node.js工具需要手工编写部署和调用合约的模板js文件，操作较为繁琐，体验和ethconsole割裂，不那么顺畅。 + +因此，FISCO BCOS 2.0版本规划时，重点设计了FISCO BCOS 2.0控制台，目标是做一个易用、友好、且功能强大的全新控制台，给FISCO BCOS提供一种极速体验方式。 + +## What: 控制台实现了哪些功能？ + +控制台每一个功能的实现都源于一个个朴素的操作，一切按实际需求出发，对用户有价值的功能，一一实现。 + +### 需求1：区块链是什么，在哪里？看得见吗？ + +实现查询区块链相关的一系列命令，让区块链看得见摸得着！例如查询区块高度、区块、交易、节点等等，并且根据不同参数，提供不同的查询方式以满足不同条件下的查询需求。 + +值得关注的是，对于交易和交易回执信息查询命令（getTransactionByHash，getTransactionReceipt等），提供按ABI定义解析详细数据的功能，让交易的输入、输出和event日志信息以解码的方式呈现，而不再是满屏十六进制的天文数字。 + +### 需求2：部署和调用合约是使用区块链最核心的诉求，控制台可以直接部署和调用合约吗？ + +必须可以。控制台推出之前，部署和调用合约有两种选择：一种是借助Node.js工具，即写Node.js客户端部署和调用合约；一种是使用Java SDK, 写Java 客户端部署和调用合约。这两种方式都很强大，但并不是为极速体验设计的，用户需要编写合约之外的部署和调用代码。 + +因此，控制台实现的效果是，用户写好合约，放入指定路径，在控制台输入一个命令（deploy）即可完成部署，再用call指令就能调用合约接口，不需要其他任何额外的工作（例如将solidity合约转为java代码，编写部署和调用合约的客户端代码等）。 +deploy命令部署合约之后，会显示一个合约地址，考虑到后续调用合约时还会用到这个合约地址，控制台本地会记录部署的合约地址，并提供getDeployLog命令查看部署过的合约地址列表信息。 + +另外，FISCO BCOS区块链提供CNS功能，即合约命令服务功能。链上可以记录部署的合约名、版本号和对应的合约部署地址；部署合约时，指定合约名和版本号；调用合约时，指定合约名和版本号（若不指定，使用最近部署的合约版本号）。 + +这是一种更高级的部署和调用合约方式，也是推荐的部署和调用合约方式。因此控制台实现了利用CNS部署合约命令deployByCNS和利用CNS调用合约命令callByCNS。 +值得关注的是，为了开发者便于查看处理信息和调试合约，控制台会自动解析合约的输出和event日志信息。 + +### 需求3：FISCO BCOS 2.0支持多群组，控制台可以在线切换群组吗？ + +控制台登录之后，其命令提示符前面显示当前群组号。通过提供switch命令在线切换多群组，即不需要退出控制台就能完成无缝切换。切换之后，命令提示符前面的群组号自动更新，而后可以在切换后的群组中发送命令。 + +### 需求4：控制台可以管理区块链吗？ + +FISCO BCOS 2.0 提供节点管理、系统参数管理、权限管理功能，控制台均提供对应的命令进行操作，方便用户通过简单的命令轻松管理区块链。 +其中，节点管理的命令是addSealer(添加共识节点)、addObserver(添加观察节点)、removeNode(移除群组中的节点)；系统参数管理的命令是setSystemConfigByKey(设置系统参数)；权限管理有一系列的命令，管理区块链系统相关功能的操作权限，其具体是以grant开头的赋予权限命令，以revoke开头的撤销权限命令，以及以list开头的查询权限命令。 + +[具体使用参考这里](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/console/console.html#grantpermissionmanager) + +### 需求5：可以不用写CRUD合约，操作区块链中的用户表吗？ + +FISCO BCOS 2.0提供分布式存储，其核心在于表存储设计。CRUD合约是面向表存储的一种合约写法，合约的数据存储在用户表中，合约接口面向表进行增删改查操作。 +为了让用户不用写CRUD合约，就可体验分布式存储功能，控制台提供类似mysql语句的形式，提供创建表（create）、查看表（desc）和表的增删改查（insert, delete, update, select）命令。 +创建表和增删改命令均是发送一条需要区块链节点共识的交易，与用户编写CRUD合约操作表等效。 + +### 需求6：控制台支持国密方式发生交易吗？ + +控制台提供修改配置文件的国密开关，并下载国密版合约编译器以及替换，这就成为了国密版控制台。因此，当区块链节点是国密版本时，控制台可以连接国密节点并支持部署和调用国密版合约，发送国密版交易。 + +### 需求7：...等你来提？ + +欢迎社区用户积极提意见、建议以及需求（issue或微信社群的方式），同时也可以直接提pull request到官方console仓库，修改和新增你们需要的功能，甚至可以fork源码然后单独定制个人或组织的控制台，开源社区的共建和共享依靠社区用户广泛而积极的参与。 + +## Where: 控制台的价值在哪里 + +现在，用户只要启动控制台，就可以查询丰富的链上信息，快速部署和调用合约，轻松管理区块链，这些特性给用户带来什么价值呢？ + +- **面向初学人员**：不用搭建复杂的开发环境，只要简单的节点ip和端口配置，非常轻量级，就可以极速体验区块链功能。当启动控制台后便呈现出一个炫酷的FISCO BCOS标志图案时，会顿时感觉自己成功地与FISCO BCOS产生了第一次连接，从而信心倍增地继续探索区块链。 + + [配置和启动控制台请参考这里](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/console/console.html#id8) + +- **面向开发人员**：开发人员可以利用控制台部署和调试合约，当写好合约后，可以在控制台先部署，采用call指令调用验证合约逻辑，观察合约运行过程和结果。如果业务端采用Java开发应用，可以利用控制台的合约编译工具将Solidity合约一键编译为Java客户端代码文件，供客户端的java工程调用。 + +- **面向测试和运维人员**：可以在搭建区块链环境后，利用控制台查看链状态，操作区块链配置，测试或检查相关区块链功能。 + +**总之，控制台已成为FISCO BCOS的一个极速体验的窗口，一件强有力的利器，为用户持续带来实际价值**。 + +------ + +#### **注**： + +1、控制台已是FISCO BCOS SDK的一个标配功能，目前已提供Java版控制台（已单独成立了一个console仓库），Python版控制台和Node.js控制台。上文主要是针对Java版控制台进行的介绍，其他控制台相关功能大体相同。 + +**2、控制台文档列表**： + +[Java版控制台使用文档](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/console/console.html ) + +[Python版控制台使用文档](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/sdk/python_sdk/console.html) + +[Node.js版控制台使用文档](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/sdk/nodejs_sdk/install.html#node-js-cli**) \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/4_tools/43_console/index.md b/3.x/zh_CN/docs/articles/4_tools/43_console/index.md new file mode 100644 index 000000000..c98ed1deb --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/43_console/index.md @@ -0,0 +1,9 @@ +### 交互式控制台Console + +```eval_rst +.. toctree:: + :maxdepth: 1 + + console_details.md +``` + \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/4_tools/44_sdk/index.md b/3.x/zh_CN/docs/articles/4_tools/44_sdk/index.md new file mode 100644 index 000000000..64be7ac27 --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/44_sdk/index.md @@ -0,0 +1,15 @@ +### 多语言SDK + +```eval_rst +.. toctree:: + :maxdepth: 1 + + multilingual_sdk.md + use_javasdk_in_eclipse.md + node.js_sdk_quick_start.md + python-sdk_origin_function_and_realization.md + javasdk_performance_improvement_8000-30000.md + talking_about_java-contract-code.md + python_blockchain_box.md +``` + \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/4_tools/44_sdk/javasdk_performance_improvement_8000-30000.md b/3.x/zh_CN/docs/articles/4_tools/44_sdk/javasdk_performance_improvement_8000-30000.md new file mode 100644 index 000000000..7f63374f1 --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/44_sdk/javasdk_performance_improvement_8000-30000.md @@ -0,0 +1,152 @@ +# 记一次JavaSDK性能从8000提升至30000的过程 + +作者：李辉忠｜FISCO BCOS 高级架构师 + +## 缘起 + +FISCO BCOS在中国信通院可信区块链测评中达到2万+ TPS的交易处理能力，在同类产品中处于领先水平。此次测试标的是底层平台，目的是压测得出底层平台的性能上限，主要评估目标是底层平台的交易处理能力。 + +交易构造是由客户端（集成了SDK）完成，客户端通常可以非常容易实现平行扩展。SDK要完成交易构造的过程，实现交易组包、编码、签名、发送等一系列操作，这些过程本身是无状态的，客户端可以通过多线程的方式进行扩展，一个客户端性能达到瓶颈，可以增加更多客户端进行扩展。 + +虽然“堆机器”的平行扩展方式可以解决发送端的性能问题，但是机器本身就是珍贵的资源，进一步优化算法效率，提高资源利用率，将大有裨益。于是，我们打算先测试一下JavaSDK目前的性能，主要评测生成交易的性能。生成交易包括交易组包、参数编码、交易编码、交易签名等过程，其中，交易签名是最重要的环节，测试数据如下： + +- 8核机器，测试本地生成50W笔交易的耗时 +- 完全并行：每秒生成**8498笔**交易，平均每笔交易耗时0.12毫秒 +- 完全串行：每秒生成1504笔交易，平均每笔交易耗时0.66毫秒 + +对比C++实现交易签名，这个性能实属不高。根据以往经验判断，这里大有优化空间啊！于是团队开始了一次JavaSDK的性能优化之路。 + +## 过程 + +关于性能优化，社区做过多次分享，可以补充阅读下列文章： + +- [FISCO BCOS共识优化之路](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485295&idx=2&sn=46cff7fcdf2e807325532941fcbc98fe&chksm=9f2ef573a8597c65d159c17298ecec02097aafeedfd0192154d9d530c9a0d0a79a22c33894a0&scene=21#wechat_redirect) +- [区块链的同步及其性能优化方法](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485283&idx=1&sn=c2028923dc7ec7d8bfa808febc57e596&chksm=9f2ef57fa8597c6911f629b324e466f7058e4ae5da06aab8484c1d7db3203496ffebd9562ecb&scene=21#wechat_redirect) +- [FISCO BCOS中交易池及其优化策略](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485255&idx=1&sn=3947f289f75813c13a2f58fb00d2018e&chksm=9f2ef55ba8597c4de0a3e427f03af7b7b327a54cf440a36d38b62f520591f81463e6aca772fd&scene=21#wechat_redirect) +- [FISCO BCOS性能优化——工具篇](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485323&idx=1&sn=d63421fa2353d0e9a1506f01516f3416&chksm=9f2ef597a8597c8134f17053236863c501fb6e4f7480cca1a37926e7cfc309f8faacadf1786a&scene=21#wechat_redirect) +- [FISCO BCOS的速度与激情：](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485329&idx=1&sn=4bb6c31ff10ae1ae03cd0dbeaf023a4c&chksm=9f2ef58da8597c9bcda115382624012c240ce56a5f84450d9808281b8736bd2e9b8833eab5f2&scene=21#wechat_redirect)[性能优化方案最全解密](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485329&idx=1&sn=4bb6c31ff10ae1ae03cd0dbeaf023a4c&chksm=9f2ef58da8597c9bcda115382624012c240ce56a5f84450d9808281b8736bd2e9b8833eab5f2&scene=21#wechat_redirect) +- [让木桶没有短板，FISCO BCOS全面推进并行化改造](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485324&idx=1&sn=94cdd4e7944f1058ee01eadbb7b3ec98&chksm=9f2ef590a8597c86af366b6d3d69407d3be0d3d7e50455d2b229c1d69b1fdc6748999601cd05&scene=21#wechat_redirect) + +这些性能优化的过程中，感触最深的有两句话：『过早的优化是万恶之源』『没有任何证据支撑的优化是万恶之源』 + +优化要靠数据说话，而获取数据需要靠有效的分析工具，所以此次JavaSDK的性能优化，首要任务就是确定采用什么性能分析工具。 + +### 工具：发现java自带的分析工具挺管用 + + + + +采用HPROF跑了一次，得到下面这样的数据报告： + + + + +数据显示，热点在很底层的库函数。这个结论并不符合预期，说明 SDK本身代码不是热点，性能优化比较难入手。 + + + +幸运的是，很快好消息就来了：采用java自带的另一个工具jvisualvm，较好地可视化输出性能分析数据，同时也很直观地显示出JavaSDK本身存在热点。 + + + + +### 分析：找到一个“伪热点” + + + +通过jvisualvm工具分析出来，最大的热点是在生成随机数，这让我等有些吃惊。 + + + +上面分析的是国密版本，对于非国密如何呢？跑了一遍，热点依旧可见在createTransaction，那就试试uuid吧。 + + + +但是，打脸，来得是那叫一个快，UUID的实现也是基于SecureRandom。 + + + +群聊出现好长时间的静默……那就研究一下SecureRandom吧，看看为什么它会这么慢，也了解Java随机数的一些相关背景知识。终于，下面这个知识点让我们重拾兴奋。（[https://zhuanlan.zhihu.com/p/72697237](https://zhuanlan.zhihu.com/p/72697237)） + + + + +我那句“采用ThreadLocalRandom替换SecureRandom计算Nonce”还未敲字出去，新一轮打脸已经开始了。 + + + +这个方向的讨论为本次性能优化之旅豁开了另一扇思考之门~ + + + + +讨论很有道理，再仔细看数据，从数据层面也印证了这个想法。 + + + + +实验测试证明这是一个正确的方向，线程数降下来，这个热点就消失了。随机数那里出现热点是因为压测并发线程数开启太多，太多线程抢占资源导致随机数获取较慢。 + +### 再分析：找到令人震惊的热点 + +经过第一轮分析，算是找到一个“伪热点”，但性能提升依旧收效甚微。革命尚未成功，同志还需努力！降低线程数再跑一次性能分析，得到性能数据如下： + + + +乍一看，热点分布又是很底层的基础库操作，焦虑又弥漫心头…伴着凌晨的静谧，群聊再一次陷入了无言的沉默……直到，我又抛出一个疑问。 + + + +章鱼哥（王章）秒回，团队的激情苏醒了~为他这个回复速度，也为这个回复结果！ + + + +签名算法的实现，居然是先签名然后再做验签，而验签就是为了获得一个叫recoveryID的值（关于ECDSA的recovery原理，将在另一篇详细展开）。这里讲述一下我们为什么会兴奋。recoveryID设置的目的是为了给未来使用者可以从签名快速恢复出公钥，如果没有这个recoveryID，恢复公钥就需要遍历4种可能性，然而，这里的实现方式在生成签名的时候是通过遍历查找来计算出recoveryID。这种做法完全没有减小实际开销，只是采用“乾坤大挪移”把开销转移到签名环节了而已。实际上，recoveryID是有更快的计算方式可得到的，下一节可见。【这部分代码继承自web3j，之前没有深入考究其实现方式，当前web3j还仍然是这种实现】。出于老码农的本能，发现症状就想要第一时间先搞清楚问题影响边界在哪里，于是就有了这样的分析和尝试： + + + +同样老司机的章鱼哥快速给出了可喜的结论： + + + +到这里，心里有底了！至少把recoverFromSignature干掉是能够翻倍提升性能的，至于怎么干掉，额…再说呗。出于好奇，想再看看此时的性能数据会怎样（幸亏好奇了一下）。 + + + +重新调整姿势（换成采用ThreadLocalRandom生成nonce，以及线程并发数降低为10的版本），再来一发，再次获得惊喜的数据。 + + + + +这种情况下，性能分布也比较均匀了，没有明显的热点。 + + + +凌晨一点，总算收获满意的成果，心情是棒棒的…一秒之后，脑回路蹦出来个问题“国密的会怎样呢？明天再说吧（国密的优化会在另一篇再详细讲）。 + + + + +### 填坑：recoveryID的计算方法 + +由于对Java密码学算法库（bc-java）不够熟悉，此处也遇到不少坑，最终通过继承密码算法库，将更多所需参数暴露返回给上层，总算实现了Java版本的recoveryID计算。 + +``` +// Now we have to work backwards to figure out the recId needed to recover the signature. + ECPoint ecPoint = sig.p; + BigInteger affineXCoordValue = ecPoint.normalize().getAffineXCoord().toBigInteger(); + BigInteger affineYCoordValue = ecPoint.normalize().getAffineYCoord().toBigInteger(); + + int recId = affineYCoordValue.and(BigInteger.ONE).intValue(); + recId |= (affineXCoordValue.compareTo(sig.r) != 0 ? 2 : 0); + if (sig.s.compareTo(halfCurveN) > 0) { + sig.s = Sign.CURVE.getN().subtract(sig.s); + recId = recId ^ 1; + } +``` + +关于ECDSA算法的recover机制和recoveryID生成原理，将在后续的推送中详细展开，敬请期待。 + +## 后话 + +每一次做性能优化，都是一次很爽的体验，少不了熬夜，但永不缺激情。对代码进行抽丝剥茧，经历反复多次的发现瓶颈、无情打脸、重拾信心过程，最后到达柳暗花明。 再次用那两句话结尾：过早的优化是万恶之源，没有任何数据支撑的优化是万恶之源。共勉！ \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/4_tools/44_sdk/multilingual_sdk.md b/3.x/zh_CN/docs/articles/4_tools/44_sdk/multilingual_sdk.md new file mode 100644 index 000000000..3253035dc --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/44_sdk/multilingual_sdk.md @@ -0,0 +1,226 @@ +# 麻雀虽小五脏俱全 | 从Python-SDK谈谈FISCO BCOS多语言SDK + +作者：张开翔｜FISCO BCOS 首席架构师 + +FISCO BCOS 2.0从发布起就自带官方控制台，经过社区持续使用打磨，已经足够强大、完善、友好。 + +社区还有用各种开发语言开发的区块链应用，为满足开发者方便管理区块链节点的需求，目前Python-SDK和Nodejs-SDK已经上架，go语言版本已经在路上。 + +---- + +本文以笔者最熟悉的Python-SDK为例，分享一些SDK开发的点滴，涵盖应用开发流程、协议编解码、网络通信和安全事项等。 + +FISCO BCOS自带快速搭建特性，五分钟一键搭链后，开发者只需连上区块链节点，写合约、发交易。 + +控制台和SDK的定位，是帮助用户快速访问区块链，开发测试智能合约，实现业务逻辑。根据“**奥卡姆剃刀**”原则，设计哲学应尽量轻、模块化、浅层次，不引入多余的功能，不给用户和二次开发者造成额外负担。 + +客户端控制台和SDK就像一辆操控好、配置精的快车，供开发者和用户驾驭，轻松惬意，尽情驰骋于区块链应用之路。 + +## 控制台体验 + +首先结合从准备环境到调用合约的全流程，体验下控制台，命令行交互界面风格如下： + + + +#### 1. 准备环境 + +在开始之前，请先**通读使用手册和开发文档（非常重要！链接在文末）**，根据文档介绍，step by step初始化环境，安装依赖库，目前Python-SDK支持linux/mac/windows操作系统。 + +为了连上区块链节点，需要修改本地配置文件，填写区块链节点的对应网络端口，如果选择Channel协议，则需要配置相应的客户端证书。 + +#### 2. 在线体验 + +配置好网络后，可以运行console的get系列命令。试下手感，与FISCO BCOS亲密接触。确认链在正常工作，常用的指令有getNodeVersion、getBlockNumber、getPeers、getSyncStatus等，可以用console的usage或help命令了解所有支持的指令。 + +#### 3. 创建账户 + +创建一个新的帐户，即代表自己身份的公私钥对，发送交易时会采用私钥签名。创建的帐户用keystore格式保存在本地文件系统里，用户可以设定密码保护这个文件，注意记住创建帐户时使用的密码。 + +控制台提供的帐户相关命令是**newaccount, showaccount**（参数为账户名和密码）。如果要使用刚创建的新帐户为交易签名，记得把它配置到client_config.py文件的相应位置。 + +另外，如果账户信息需要高等级保护，则可以进行二次开发。将其放入加密机、TEE等安全区，以及开发秘钥分片、助记词等方案。 + +#### 4.编写合约 + +编写一个智能合约，或者参照SDK里自带的智能合约例子修改定制，实现自己的业务逻辑。本文重点关注solidity智能合约，FISCO BCOS还有一种“预编译合约”，采用C++开发，需要和FISCO BCOS底层代码联合编译。 + +#### 5. 编译部署 + +对合约进行编译，获得合约的ABI接口文件和BIN二进制代码文件。Python-SDK里有bcos_solc.py文件可帮助开发者简化编译器配置和调用，同时，只要正确配置了合约路径和编译器路径信息，直接运行控制台的部署或调用合约接口指令，也会尝试自动去编译合约，操作体验相当行云流水。 + +独立部署合约的话，可使用控制台的deploy指令，部署指令成功后会得到新的合约地址。参考命令是./console.py deploy SimpleInfo save，其中SimpleInfo是合约名（不需要带后缀），最后的"**save**"为可选，如果指定了"**save**"，则将合约新地址记录到本地文件里，以便后续使用。 + +#### 6. 调用合约： + +用call或sendtx命令，指定合约名、合约地址、方法名、对应的参数，调用链上合约。 + +参考命令./console.py sendtx SimpleInfo last setbalance 100，即选择SimpleInfo合约，指向其最近部署成功的地址（用"**last**"指代，可以省掉复制粘贴合约地址的繁琐操作），调用setbalance接口，传入参数100。 + +交易在链上共识完成后，控制台会自动打印交易回执里的方法返回码、交易Event log信息列表等，供用户查看，如果错误，则打印异常信息。 + +如果一切正常，到此即可基本走通区块链应用之路。 + +值得一提的是，FISCO BCOS几个语言版本的控制台，都支持按Tab键提示指令和自动完成，帮助使用者流畅无错地操作，提升用户体验。 + +再进一步，如果希望有丰富多彩的、可视化交互式页面体验，不妨使用WeBASE中间件平台。 + +## 深入了解（Dive Deeper） + +整个SDK的模块组合如下，可谓是麻雀虽小五脏俱全。 + + + +### 功能接口 + +支撑控制台等交互模块的，是已经封装完备、开箱即用的功能接口API，包括： + +#### 1. get系列 + +诸多的“get”开头的接口，用于获取链上的各种信息，包括区块、交易、回执、状态、系统信息等等。虽然几十个get接口，但其实现逻辑基本一致，都是指定命令字和参数列表，请求和处理回应，实现起来也很快。 + +#### 2. call + +对应合约的常量方法。所谓常量方法，是指合约里对应代码不修改状态，该请求不会全网广播，仅在指定节点上运行。 + +#### 3. sendRawTransaction + +构建一个交易，用账户私钥签名，发送到链上，这种交易会被广播，进行共识处理，生成的状态数据会被全网确认。部署新合约这个操作，实际上也是一种交易，只是不需要指定目标合约地址。 + +相关的是**sendRawTransactionGetReceipt**，名字很长，在**sendRawTransaction**基础上增加了获取回执的流程**，**用于简化从发交易到获取回执的闭环流程。 + +#### 4.更多 + +针对FISCO BCOS的全局系统配置、节点管理、CNS、权限等系统级功能的API，其原理是读写链上的系统合约，详细指令列表见文末。 +开发者可以参考控制台和client/bcosclient.py等代码，进行二次开发，实现更多更酷炫的功能。另外，SDK里内置了一系列的开发库和小工具，帮助管理帐户、输出日志、统一异常处理、简单的性能和耗时统计等。 + +## 合约开发相关 + +围绕着合约开发，Python-SDK实现了合约编译部署、合约地址本地化管理、ABI接口文件的管理，支持代码自动生成（参考codegen.py），一个命令行即可生成供业务端直接使用的代码，如 + +python codegen.py contracts/SimpleInfo.abi。 + +solidity合约编译后的ABI文件是个好东西。ABI 全称是 **Application Binary Interface**（应用程序二进制接口），里面详细描述了合约的接口信息，包括方法名、参数列表和类型、方法类型（常量方法，还是交易方法），以及Event log格式定义等等。 + +对ABI的管理，参见client/datatype_parser.py，加载和解析ABI文件（默认为JSON格式），根据方法名、方法4字节签名、方法类型等维度，灵活查询方法列表和方法定义，并针对方法定义、输入数据等进行编码解码，解析交易返回值、Event logs等。 + +有ABI定义在手，对合约的操控简直是可以随心所欲，开发者读懂了ABI描述，基本就能全面理解一个合约的输入输出，和合约毫无障碍地对话，这种“**面向远程接口编程**”的思想，很类似WSDL、IDL、ACE、ProtoBuffer和gRPC等经典软件设计。 + +事实上，整个SDK中最繁琐的是ABI编解码部分，为了兼容EVM，FISCO BCOS在交易处理时沿用了ABI编码，以及兼容RLP协议。 + +ABI、RLP制定了严格的规范，对基础数据类型、数组和变长数据、函数方法、参数列表等都有特定的编解码方式，否则组件之间无法通信，数据无法解析，虚拟机“不认识”所输入的交易，则不能执行合约。 + +如果自行手写这里的编解码，即使是熟手也得花不少时间，还要能保证测试通过、保持版本兼容，所幸github上已经有eth-abi、eth-utils、rlp等一系列开源项目（多为MIT宽松许可协议），可以引入这些项目且根据具体的需要进行修订（保留原作者声明和版权开源许可），能节约不少工作量，向这些项目作者们致谢，开源就是爽！ + +## 交易数据结构相关 + +在搞定了基础编解码之外，还需要实现 FISCO BCOS交易结构，重点注意支持并行处理交易增加的randomid、blocklimit字段，为支持群组特性增加的fiscoChainId和groupId字段，在交易的receipt里增加的交易output等。 + +其中，交易的blocklimit定义为“交易生命周期，该交易最晚被处理的块高”，SDK需要定期到链上查询当前块高，以确定当前交易的生命周期（比如，此交易允许在后续一百个区块内被处理）。 + +对于开发者来说，清晰理解交易的输入（tx.input）、交易回执（tx.receipt）、交易输出(tx.output)是非常重要的。 + + + +交易调用合约里的某一个方法时，首先将方法名字和参数类型列表组合，如**'set(string,uint256,address)'**，对这一段文本进行Keccak-256 (SHA-3)计算，并截取前4个字节做为“方法签名”（signature），然后对传入的参数，根据类型定义依次进行ABI编码，并和"方法签名"拼接一串二进制数据，做为交易的输入数据。 + +和交易结构体的其他字段（from、to、groupid、randomid等）一起再进行RLP编码，并用帐户私钥进行签名，得到一段二进制请求数据，由sendRawTransaction发往节点，节点收到后，立刻返回交易Hash给到客户端。 + +交易在链上被网络共识确认，处理完成后，通过getTransactionReceipt接口（传入之前获得的交易Hash），可以获得交易处理的详细结果。 + + + +在交易回执中，以下几个字段尤为关键： + +#### 1. contractAddress + +仅在部署合约交易时有效，表示新合约的地址。 + +#### 2. output + +对应方法的return值，可用于判断业务逻辑的最终处理结果（取决于合约的写法）。 + +#### 3. Logs + +如果在合约代码里，写了一些Event log， 则receipt的logs字段里可以解码出详细的信息。Event log可用于帮助客户端监听、跟踪交易的处理结果，甚至可以帮助开发者调试合约执行过程，相当于在合约里打调试日志。当然，在合约正式发布时，应清除调试的Event log，只保留必要的log，避免冗余信息存到链上。 + +Python-SDK客户端里内置了解析“方法签名”（根据4字节的signature，找到对应的方法定义）、交易input/output、receipt.logs等字段的方法。 + +在使用控制台命令行时，只要是查询交易和回执的指令，在命令行后面附带合约名（前提是使用者知道这个交易调用的是什么合约），也可以自动解析出相关的数据来，例如：./console.py getTransactionReceipt 0x79b98dbb56d2eea289f756e212d5b6e5c08960beaa8ea8331740fdcfaa8dcab1 SimpleInfo，最后这个“SimpleInfo”为可选合约名，不需要带后缀，要求在contracts/目录下有SimpleInfo.sol文件。 + +这个贴心小设计，可以帮助开发者直观探秘区块链交易的脉络，对各种信息一目了然，不会迷失在天书一样的十六进制字符海洋里。 + +## 网络协议 + +最后聊聊FISCO BCOS的两种网络协议：JSON RPC和Channel长连接。 + + + +JSON RPC连接没有证书验证和通信加密，建议在本身安全可信的环境里使用，比如本机或内网，一般用于运维管理和统计分析场合。 + +JSON RPC的格式相当简单通用，各种语言库都内置了JSON编解码以及HTTP请求协议实现，一般不需要自行开发，甚至可以采用curl、telnet等工具进行收发，如： + +``` +// Request +curl -X POST --data '{"jsonrpc":"2.0","method":"getBlockNumber","params":[1],"id":1}' http://127.0.0.1:8545 |jq +// Result +{ "id": 1, "jsonrpc": "2.0", "result": "0x1" } +``` + +Channel协议是FISCO BCOS独有的协议，Channel协议的特点是安全高效，支持双向实时通信，可用于远程调用乃至公网的通信。 + +如果使用Channel长连接方式，则需要从区块链节点上获取SDK证书，放置到SDK项目的对应路径下，证书详见文末。 + +这个协议的数据包格式示意图如下，是一种TLV(Tag/Length/Value)风格的扩展实现： + + + +**格式说明：** + +1. 所有整形数编码都是网络序，大端（Big endian）； +2. Length实际上包含了从第一个字段到最后一个字段（data）的整个数据包的长度； +3. 包头（Length+Type+Seq+Result）为定长，为（4+2+32+4) = 42字节； +4. 数据体的实际长度根据具体内容而变，字节数为Length-42字节。 + +**Channel长连接通信和数据收发的要点如下：** + +- 1. 采用TLSv1.2安全传输，SDK和节点之间需要加载证书，用证书握手、验证后才能建立长连接。 + +- 2. 长连接用心跳包维护，需要定期发起心跳包。 + +- 3. 数据按包为单位，编码成流数据传输，那么在收发数据时，需要持续从socket流里获取数据，按照数据包的格式，判断长度是否合法，数据是否收全，是否能正确的解析，对“部分收取”的数据，要保留在接受缓冲区里，待收取完成后再进行解析，不能丢弃，否则可能导致解析错误。 + + + +- 4. Channel协议支持双向通信，SDK可以主动请求节点，节点也可能往SDK推送消息，如区块链系统通知、数据更新通知、AMOP跨机构消息等。 + +- 5. 设计异步的、队列化、回调式消息处理机制，根据消息的序列号、指令类型、状态码等维度，正确处理消息。Python-SDK用了多线程以及Promise库，以尽量高速优雅地处理各种消息。 + +对socke流数据编程有一定经验的开发者，理解这个协议和实现它并不会很难。对Channel协议实现，数据包解析参见client/channelpack.py，通信和数据收发参见client/channelhandler.py。 + +## 总结 + +Python-SDK的开发始于今年6月中旬，写出第一个可用版本只花了一个星期，然后雕琢用户交互细节，以及进行代码优化、文档完善，并进行多轮测试保证质量，团队其他同学实现Nodejs版本SDK的用时也差不多。 +总的来说，在有一些基础代码参考的前提下，开发一个FISCO BCOS 特定语言版本SDK，还是挺敏捷写意的事情，一点儿也不难，Just for fun。 +在各语言版本SDK开发和迭代过程中，FISCO BCOS团队和社区开发者一直保持沟通交流，纳入优质pull request，在体验中持续优化。 + +欢迎社区开发者根据自身使用场景的实际情况，继续完善现有SDK，或贡献更多语言类型的FISCO BCOS SDK，帮助更多开发者顺畅地走在区块链之路上。 +最后，感谢杰哥、安总、小白、wheat等同学，以及多位社区开发者对Python-SDK的重要贡献。 + +------ + +#### 参考资料 + +- [FISCO BCOS官方控制台](https://github.com/FISCO-BCOS/console/tree/master-2.0) +- [Python-SDK](https://github.com/FISCO-BCOS/python-sdk) +- [Nodejs-SDK](https://github.com/FISCO-BCOS/nodejs-sdk) +- [FISCO BCOS安装](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/installation.html#fisco-bcos) +- [合约开发教程](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/smart_contract.html) +- [WeBASE](https://fintech.webank.com/webase) +- [ABI](https://solidity.readthedocs.io/en/latest/abi-spec.html) +- [RLP](https://github.com/ethereum/wiki/wiki/RLP) +- [交易数据结构](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/design/protocol_description.html) +- [RPC原理](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/design/rpc.html) +- [Channel协议定义](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/design/protocol_description.html#channelmessage-v1) +- [SDK证书](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/certificates.html) +- [AMOP跨机构](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/amop_protocol.html) + diff --git a/3.x/zh_CN/docs/articles/4_tools/44_sdk/node.js_sdk_quick_start.md b/3.x/zh_CN/docs/articles/4_tools/44_sdk/node.js_sdk_quick_start.md new file mode 100644 index 000000000..0d3c0b18d --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/44_sdk/node.js_sdk_quick_start.md @@ -0,0 +1,113 @@ +# 一文快速入门FISCO BCOS Node.js SDK + +作者：李陈希｜FISCO BCOS 核心开发者 + +SDK一般是指为了方便开发者为系统开发应用而提供的API、开发辅助工具以及文档的集合。面对不同的开发者群体，FISCO BCOS已经相继推出了面向企业级应用开发者的Java SDK（功能丰富、稳定），以及面向个人开发者的Python SDK（上手迅速、轻便）。在实际推广过程中，我们发现有部分开发者习惯使用JavaScript构建应用前端，倘若此时能有一个支持使用JavaScript进行后端开发的SDK，那么前后端的语言壁垒能够进一步被打破——开发者只需了解JavaScript，便能完成整个FISCO BCOS应用程序的前后端开发。在此背景下，FISCO BCOS Node.js SDK诞生了。本文将会介绍Node.js SDK的设计及使用。 + +## 一、SDK的设计 + +Node.js SDK遵循分层设计原则，层与层之间界限清晰、功能明确，下图为Node.js SDK的架构示意图： + + + +图中自底向上依次为： + +- **基础层**：提供网络通信、交易构造及签名、合约编译等基础功能； +- **API层**：基于基础层提供的功能，对FISCO BCOS常用功能进行了进一步地封装，暴露出API用于给上层的应用层调用。这些API覆盖基本的JSON RPC功能（查询链状态、部署合约等）及预编译合约功能（权限管理、CNS服务等）； +- **应用层**：使用Node.js SDK进行二次开发的应用程序均属于此层，如Node.js SDK自带的CLI（Command-Line Interface，命令行界面）链管理工具。 + +## 二、SDK的安装 + +### 2.1 环境准备 + +Node.js SDK依赖下列软件： + +- 8.10.0或以上的版本的Node.js，5.6.0或以上的版本的NPM； +- Python2、g++及make。Solidity编译器solc需要编译后才能使用，编译所需基础软件需要用户提供，其中Python2用于运行构建工具node-gyp，g++和make则是用于编译solc。对于没有g++和make的Windows用户，可以安装 windows-build-tools再进行构建。 + +### 2.2 安装SDK + +- 从https://github.com/FISCO-BCOS/nodejs-sdk下载sdk； + +- 进入nodejs-sdk目录； + +- 执行npm i。Node.js SDK使用lerna管理依赖项，此步用于安装lerna； + +- 执行npm repoclean。初次安装时无需执行该命令，但如果出现了安装到一半被打断等情况，建议先执行该命令以清除所有依赖项； + +- 执行npm run bootstrap，此命令会安装SDK的所有依赖项。 + +上述所有命令执行完后，API层的目录结构如下图所示： + + + + +对于应用开发者，可以重点关注 nodejs-sdk/packages/api/web3j 及 nodejs-sdk/packages/api/precompiled目录，SDK提供的所有API均位于这两个目录下的模块中，应用开发过程中通过require语句导入相应模块即可。 + +## 三、使用SDK进行开发 + +### 3.1 初始化 + +使用Node.js SDK的所有功能前，必须对SDK进行配置，配置以.json格式配置文件的形式提供。主要包括以下配置项： + +- **privateKey**：FISCO BCOS基于公私钥体系，每个账户（公钥）均有一个对应的私钥，SDK需要使用该私钥对交易进行签名； +- **nodes**：SDK连接的节点，可以有多个，当节点数大于1时，SDK的每次请求都会随机从nodes调出一个节点发送； +- **authentication**：SDK使用Channel协议与节点进行通信，Channel使用SSL安全传输协议传输数据，在双方建立通信前，需要进行必要的身份验证。因此这个配置项中需要指明SDK私钥文件、证书文件、CA根证书文件的路径，这些文件通常是在生成链的阶段自动生成； +- **groupID**：FISCO BCOS使用多群组架构，同一个节点可以隶属于多个群组，因此需要指明SDK需要连接的链的群组ID； +- **timeout**：受限于网络环境，SDK的请求有可能超时，因此可能会导致调用SDK接口的程序陷入无尽等待，因此需要指定一个超时时间，SDK在请求超时后强制返回并向调用者返回错误。 + +开发者需要在初始化阶段将配置文件载入Configuration对象中，Configuration对象是全局唯一的且被所有模块共享。 + +### 3.2 调用示例 + +以一个简单的获取当前块高的程序为例，调用步骤如下： + +1、初始化Configuration对象，将配置文件路径传入Configuration对象的setConfig函数： + +``` +const Configuration = require('./nodejs-sdk/packages/api/common/configuration').Configuration; +Configuration.setConfig(path.join(__dirname, args.config)); +``` + +2、获取当前块高的API位于Web3jService中，构造一个该对象： + +``` +const Web3jService = require('./nodejs-sdk/packages/api').Web3jService; +let web3jService = new Web3jService(); +``` + +3、调用Web3jService的getBlockNumber接口，获取返回值并在控制台中输出： + +``` +web3jService.getBlockNumber().then(blockNumber => { + console.log(blockNumber) + }); +``` + +需要注意的是，上述代码中使用了Promise.protoype.then方法。Promise正如其名字所示，封装了一个异步的操作，并且“承诺”在这个操作结束后，一定会调用用户在then或者catch中指定的回调函数。 + +由于Node.js天然支持异步的特性，Promise的概念在Node.js SDK处处存在（细心的读者可能已经注意到，Node.js SDK基础层中负责Channel通信的模块叫做channelPromise）。Node.js SDK的API调用约定是：所有的API调用时均返回Promise对象，开发者需要使用await或then...catch...方法才获取到调用结果。因此开发者在调用API时需要小心，如果直接使用了API的返回值，会很容易导致bug。 + +## 四、使用CLI工具 + +Node.js SDK除了提供API外，还提供了一个小巧的CLI工具供用户直接在命令行中对链进行操作，同时CLI工具也是一个展示如何使用Node.js SDK进行二次开发的示例。CLI工具位于packages/cli目录下，若需要使用则需要进入该目录并执行./cli.js脚本，使用之前同样需要进行配置，配置文件位于packages/cli/conf/config.json文件中。以下给出了几个使用示例： + +1、查看所连节点的版本： + + + +2、获取当前块高： + + + +3、部署合约，部署之前合约需要放置于packages/cli/contracts目录中。 + + + +4、调用HelloWorld合约的get方法： + + + +## 五、Node.js SDK的未来需要你 + +当前，Node.js SDK还在成长，在某些地方仍然需要进一步打磨，比如需要CLI工具能够解析SQL语句，或者SDK的性能需要优化……秉承开源的精神，我们相信社区的能量能够将Node.js SDK 变得更加方便易用，欢迎广大开发者踊跃在issue或PR中贡献自己的idea和力量！ \ No newline at end of file diff --git a/3.x/zh_CN/docs/articles/4_tools/44_sdk/python-sdk_origin_function_and_realization.md b/3.x/zh_CN/docs/articles/4_tools/44_sdk/python-sdk_origin_function_and_realization.md new file mode 100644 index 000000000..89fd7178d --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/44_sdk/python-sdk_origin_function_and_realization.md @@ -0,0 +1,162 @@ +# Python SDK的前世今生 + +作者：陈宇杰｜FISCO BCOS 核心开发者 + +今年6月，在已有Java SDK的基础上，FISCO BCOS相继推出了Python SDK和Go SDK，不少开发者表示，这两个组件极大降低了开发区块链应用的难度，让更多开发者可以参与到FISCO BCOS的开源共建中。今天，本文就来科普一下Python SDK的前世今生，看看这个简单易上手又发挥着极大作用的组件是如何实现功能的。 + +## Why: 为什么要做Python SDK + +众所周知，Python语言简单明了，几乎接近自然语言，可以快速上手；Java语言虽然功能强大，但语法、组件相对复杂，一般会在企业级应用中使用。为了融合两者优势，FISCO BCOS首席架构师张开翔经过两周集中开发，成就了Python SDK的第一个版本。这个版本在今年7月份社区的黑客松比赛中发挥了极大作用，帮助参赛者更好聚焦在开发项目本身。在高强度的黑客松比赛中，参赛者只有36小时去完成区块链相关项目。在和选手交流中，我们发现大多数极客开发者均是从比特币、以太坊等公链开始入门，对Java语言不是很熟悉，反而精通Python、Go、Node.JS。当时团队主推Java SDK、控制台和WeBASE等基于Java的区块链开发工具，可是短短36小时，要求不熟悉Java的极客开发者基于这些工具完成开发，确实有些强人所难。在这种情况下，已经初见雏形Python SDK就成了开发者的救命良药。最终，很多参赛项目就是基于Python SDK完成的。 + +## What: Python SDK实现了哪些功能 + +Python SDK经过不同版本的演进优化，逐步实现丰富的功能。 + +### 基础版本Python SDK + +第一版的Python SDK主要基于Windows平台开发，实现了访问FISCO BCOS链RPC服务的接口，通过Python SDK接口，用户可以获取区块链的基本信息(如区块高度、区块、交易、交易回执等)，还可以部署和调用合约。但该版本的SDK不支持Channel协议，因此无法保证SDK与节点间通信安全；且Python SDK无法接收FISCO BCOS区块链节点推送的回执、区块高度信息，因此发送交易后，必须轮询节点获取最新信息。 + +### 支持Channel协议的Python SDK + +为了提升SDK与节点通信的安全性，Python SDK在基础版本上，实现了Channel协议。支持Channel协议后的SDK在发送交易后，不需轮询节点获取交易执行结果，直接从节点接收执行结果的推送即可，这样SDK发送交易后，不会阻塞在状态轮询，实现了异步发送交易的功能。 + +### 支持Precompile合约调用 + +为了突破区块链虚拟机性能瓶颈，大幅度提升交易处理吞吐量，FISCO BCOS实现了预编译合约框架，现有的预编译合约包括命名服务合约、共识合约、系统配置合约、权限控制合约、CRUD等，为方便用户使用这些预编译合约，Python SDK提供了访问Precompile合约的接口。 + +### Python SDK控制台 + +以上功能ready后，Python SDK已经可以实现与FISCO BCOS链的所有交互，但用户仍无法通过Python SDK直观感受FISCO BCOS链，于是在实现以上所有接口的基础上，Python SDK集成了控制台console，console通过命令去调用以上接口，用户可通过命令行获取区块链节点信息、部署和调用合约。 + +### Python SDK多平台支持 + +众所周知，Python是跨平台语言，支持Windows、MacOS、 CentOS、Ubuntu等各种开发平台。而Python SDK是基于Windows系统开发的基础版本，因此部署在MacOS、CentOS系统还有一些问题，比如说：各平台依赖包要求不一致、符合Python SDK版本的Python安装方式有差异、合约编译器安装方式不相同等。 + +以上这些问题，会使部分开发者的精力在安装基本环境上消耗殆尽，为了解决这个问题，Python SDK提供了部署脚本`init_env.sh`，用户可使用该脚本，一键初始化Python SDK环境。 + +脚本`init_env.sh`的主要功能包括： + +- 若运行Python SDK的系统Python版本小于3.6.0，安装3.7.3版本的Python虚拟环境python-sdk； +- 安装v0.4.25版本的solidity编译器。 + +## How: Python SDK如何实现 + +上节介绍了Python SDK的主要功能，这节就来说说Python SDK的实现。 + +罗马不是一日建成的，Python SDK在开发过程中参考了[以太坊客户端](https://github.com/ethereum/web3.py)部分模块，包括： + +- ABI编解码模块 +- RLP编解码模块 +- 账户和密钥生成模块 + +### 实现Channel协议 + +Python SDK在以上模块的基础上，实现了支持FISCO BCOS Channel协议的RPC接口和发送交易接口。Channel消息包类型定义实现于模块`client.channelpack.ChannelPack`，主要消息包类型包括： + +- 0x12: RPC类型消息 +- 0x13: 节点心跳消息包 +- 0x30: AMOP请求包 +- 0x31: 失败的AMOP消息的包体 +- 0x32: SDK topics +- 0x35: AMOP消息包包体 +- 0x1000: 交易上链通知(包含交易回执) +- 0x1001: 区块高度推送包 + +Channel协议的实现位于`client.channel.handler.ChannelHandler`模块，为了支持异步发送交易，Python SDK引入了`pymitter`和`Promise`组件，用于管理异步事件，该模块发送交易并获取交易回执的主要工作流程如下： + +- 1. Python SDK调用`sendRawTransactionAndGetReceipt`接口，对交易进行编码和签名，并将编码好的数据作为`ChannelHandler`模块发送socket请求包的参数； +- 2. ChannelHandler接收到1的数据后，将数据包的uuid注册到异步事件队列后，将消息包放入发送缓冲区发送并发送； +- 3. 节点处理完交易后，向SDK发送类型为0x1001的交易上链通知； +- 4. SDK端ChannelHandler收到消息类型为0x1001的回包后，取出消息包的uuid，并触发该uuid对应的异步事件，将交易执行结果返回给上层应用。 + +### 实现控制台 + +Python SDK控制台实现位于`console`模块，主要调用了一下模块接口实现与区块链的交互： + +- `client.bcosclient`：Python SDK基本接口类，提供了访问FISCO BCOS RPC服务的接口、部署和调用合约的接口； +- `console_utils.precompile`：提供了访问Precompile预编译合约的功能； +- `console_utils.rpc_console`: 封装了`client.bcosclient`，实现命令行调用RPC服务功能。 + +## Python SDK使用展示 + +了解了Python SDK的由来、功能和实现，下面从控制台角度直观感受下Python SDK: + +### 获取节点版本 + +命令行终端输入`./console.py getNodeVersion`可获取节点版本： + + + + +### 部署HelloWorld合约 + +Python SDK内置HelloWorld合约，命令行终端输入`./console.py deploy HelloWorld`可部署`HelloWorld`合约，若用户需要部署自编写合约，则需将该合约放置于`contracts`子目录，并使用命令`./console.py deploy 【合约名】`来部署合约。下图是HelloWorld合约部署输出，从中可看出，合约地址为: `0xbbe16a7054c0f1d3b71f4efdb51b9e40974ad651` + + + + +### 调用HelloWorld合约 + +Python SDK控制台通过`sendtx`子命令发送交易，使用call子命令调用合约常量接口。HelloWorld合约代码如下，主要包括`set`和get两个接口，前者用于设置合约局部变量`name`，后者是常量接口，获取局部变量name的当前值。 + +``` +pragma solidity^0.4.24; +contract HelloWorld{ + string name; + constructor() public{ + name ="Hello, World!"; + } +# get interface + function get() constant public returns(string){ + return name; + } +# set interface + function set(string n) public{ + name = n; + } +} +``` + +### 调用HelloWorld set接口 + +由于`set`接口改变了合约状态，因此使用`sendtx`子命令调用，`sendtx`用法如下： + +``` +./console.py sendtx [contract_name][contract_address] [function][args] +``` + +参数包括： + +- contract_name：合约名 +- contract_address：合约地址 +- function：函数接口 +- args：参数列表 + +使用`./console.py sendtx HelloWorld 0xbbe16a7054c0f1d3b71f4efdb51b9e40974ad651 set "Hello,Fisco"`命令可将`HelloWorld`合约的`name`成员变量设置为"Hello, Fisco"，输入如下： + + + +### 调用HelloWorld get接口 + +`HelloWorld`的get是常量接口，因此使用`call`子命令调用，call用法如下： + +``` +./console.py call [contract_name] [contract_address] [function] [args] +``` + +参数包括： + +- contract_name：合约名 +- contract_address：调用的合约地址 +- function：调用的合约接口 +- args：调用参数 + +使用./console.py call HelloWorld 0xbbe16a7054c0f1d3b71f4efdb51b9e40974ad651 get获取HelloWorld合约name成员变量的最新值： + + + + +## 小结 + +本文介绍了Python SDK的前世今生，包括Python SDK的由来、功能和实现，可参考[Python SDK详细使用方法](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/sdk/python_sdk/index.html)。当然，目前Python SDK还处于不断完善过程，欢迎社区爱好者关注[相关issue](https://github.com/FISCO-BCOS/python-sdk/issues)，为Python SDK的优化贡献宝贵PR。 + diff --git a/3.x/zh_CN/docs/articles/4_tools/44_sdk/python_blockchain_box.md b/3.x/zh_CN/docs/articles/4_tools/44_sdk/python_blockchain_box.md new file mode 100644 index 000000000..1b76293d0 --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/44_sdk/python_blockchain_box.md @@ -0,0 +1,195 @@ +# FISCO BCOS即拆即用的“Python区块链盒子” + +作者：汤会枫｜FISCO BCOS开源社区贡献者 + +作者为Python开发者，将FISCO BCOS Python SDK封装成镜像，以提升配置环境的速度，提高易用性。 + +## 前言 + +作为一个 Python 开发者，我一直想通过 Python 去了解区块链。机缘巧合下，在 2019 年一次开源年会上，我接触并加入了 FISCO BCOS 开源社区，此后，一直用课余时间琢磨 FISCO BCOS 的 Python-SDK。 + +在配置环境的时候，我耗费了一些时间，因此也萌生了将整个框架封装成一个 docker 镜像的想法，我为它取名“Python 区块链盒子”，就像 Minecraft 的“工作台”一样， 可以提升配置环境的速度，提高易用性。有了这样的想法，我便开始利用课余的时间着手去编写 Dockerfile。 + + + + +我把搭建好的 docker 镜像分享给周围的同学体验，“即拆即用”的特性反响很好，大家不会因为环境配置难而退怯，能像Minecraft里的Steve一样，放下“工作台”就可以制造出一堆有用的工具出来。 + +## 什么是“Python 区块链盒子”？ + +在回答这个问题之前，先来了解一下 Python-SDK。这是由 FISCO BCOS 开源，帮助开发者运用 Python 语言开发区块链应用的组件。既然是通过 Python 语言开发，我相信它将有持续不断的生命力。 + + + + +Python 的阅读难度相对比较低，特别方便学生、初学者通过 Python-SDK 去了解、学习区块链。可尝试按以下环境要求安装搭建。 + +- Python 环境：python 3.6.3, 3.7.x +- FISCO BCOS 节点：请参考 [FISCO BCOS 安装搭建](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/installation.html) + +关于 Python-SDK，可点击参考 FISCO BCOS 团队推出的开发教程。 + +- [《麻雀虽小五脏俱全 | 从 Python-SDK 谈谈 FISCO BCOS 多语言 SDK》](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485291&idx=1&sn=c359380a89621d1a64856183568825ee&chksm=9f2ef577a8597c61e5dd5e458d489926138a42808a06517f4d6515d4666dc11a08646ccebea2&scene=21#wechat_redirect) +- [《Python-SDK 的前世今生》](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485256&idx=1&sn=f1e70be6c53ea7e690392ce1ac8b5f5e&chksm=9f2ef554a8597c4278c630f60923a683b9e47499319e31aab41ccfd98715a9db2300e7d782e3&scene=21#wechat_redirect) + +“Python 区块链盒子”相当于将配置好的 Python-SDK 和部署好的区块链打包成一个包裹，类似于将一个大房子整理成一辆房车。通过这种方式，用户无需关注环境配置问题，可减少部署时间——不用一分钟就能获得镜像，方便开发者快速上手使用，便于自动化运维。你也可以尝试将这个服务和 JenKins 结合，进一步优化运维过程。“Python 区块链盒子”可以当成 Python 区块链开发的工作台，一个现拆现用的工具箱，而且可以保证开发环境的整洁，最重要的是它很轻，就像 Minecraft 里的工作台。 + +只要你有一台计算机，就可以随时随地打开这个工具箱。安装工具箱的过程也变成了享受：只需一行代码就能上手直接研究开发，不必过多关注环境配置的繁杂，能节省大量时间，解放双手。 + +## 获得并运行“Python 区块链盒子” + +可以通过以下部署来获得这个“盒子”。 + +``` +docker run -it -p 20200:20200 --name python_sdk fiscoorg/playground:python_sdk +``` + +进入容器后，首先需要启动节点，启动节点后就可以“食用”了。在这个过程中，请注意不要使用 sh。 + +``` +bash /root/fisco/nodes/127.0.0.1/start_all.sh +``` + +随后，在/python_sdk 中进行调试，调试过程中的小贴士：console.py 添加了 tab 自动补全。 + +``` + +# 查看 SDK 使用方法 +./console.py usage + +# 获取节点版本 +./console.py getNodeVersion +``` + +``` +bash-5.0# ./console.py getNodeVersion + +INFO >> user input : ['getNodeVersion'] +INFO >> getNodeVersion >> { "Build Time": "20190923 13:22:09", "Build Type": "Linux/clang/Release", "Chain Id": "1", "FISCO-BCOS Version": "2.1.0", "Git Branch": "HEAD", "Git Commit Hash": "cb68124d4fbf3df563a57dfff5f0c6eedc1419cc", "Supported Version": "2.1.0" } +``` + +完成这些之后就成功了，前前后后，相当于在几秒内就搭建了一个开源的区块链框架。你可以把自己的合约放到/python-sdk/contracts 中，更多可以参考 [Python-SDK 的使用方法](https://github.com/FISCO-BCOS/python-sdk)。这个即拆即用的“区块链盒子”对于要使用 Python 来开发区块链应用或者学习区块链的开发者很有帮助。开发者可以通过调用/python-sdk/client 中的函数使用 ./console.py 命令行并与盒子中正在运行的区块链进行交互。 + +下面将会以 Python-Flask 开发作为例子，实现调用 HelloWorld 合约的功能。 + +- step1 进入容器 + +``` +docker run -it -p 20200:20200 -p 80:80 --name flask_web fiscoorg/playground:python_sdk +``` + +- step2 启动节点 + +``` +bash /root/fisco/nodes/127.0.0.1/start_all.sh +``` + +- step3 部署 HelloWorld 合约 + +/python-sdk/contract 下存放了 HelloWorld.sol，可以直接使用这个合约进行测试。首先，查看 HelloWorld.sol 合约的内容。 + +``` +pragma solidity ^0.4.24; + +contract HelloWorld{ + string name; + + constructor() public{ + name = "Hello, World!"; + } + + function get() constant public returns(string){ + return name; + } + + function set(string n) public{ + name = n; + } +} +``` + +可以通过 get 接口返回字符串 name 的值，通过 set 更新 name 的值。有 Solidity 编程基础的开发者还可以自己定制合约内容。然后，就可以部署 HelloWorld 合约。 + +``` +$ ./console.py deploy HelloWorld save + +INFO >> user input : ['deploy', 'HelloWorld', 'save'] + +backup [contracts/HelloWorld.abi] to [contracts/HelloWorld.abi.20190807102912] +backup [contracts/HelloWorld.bin] to [contracts/HelloWorld.bin.20190807102912] +INFO >> compile with solc compiler +deploy result for [HelloWorld] is: +{ + "blockHash": "0x3912605dde5f7358fee40a85a8b97ba6493848eae7766a8c317beecafb2e279d", + "blockNumber": "0x1", + "contractAddress": "0x2d1c577e41809453c50e7e5c3f57d06f3cdd90ce", + "from": "0x95198b93705e394a916579e048c8a32ddfb900f7", + "gasUsed": "0x44ab3", + "input": "0x6080604052...省略若干行...c6f2c20576f726c642100000000000000000000000000", + "logs": [], + "logsBloom": "0x000...省略若干行...0000", + "output": "0x", + "status": "0x0", + "to": "0x0000000000000000000000000000000000000000", + "transactionHash": "0xb291e9ca38b53c897340256b851764fa68a86f2a53cb14b2ecdcc332e850bb91", + "transactionIndex": "0x0" +} +on block : 1,address: 0x2d1c577e41809453c50e7e5c3f57d06f3cdd90ce +address save to file: bin/contract.ini +``` + +完成后可得到 HelloWord 合约部署的地址，通过这个地址调用函数接口。 + +- step4 在/python-sdk 文件夹下编辑 app.py + +``` +$ vi app.py + +# -*- coding:utf-8 -*- +from client.common import transaction_common +from flask import Flask, request +from jinja2 import escape + +app = Flask(__name__) + +tx_client = transaction_common.TransactionCommon("0x2d1c577e41809453c50e7e5c3f57d06f3cdd90ce","contracts","HelloWorld") +# tx_client = transaction_common.Transaction_Common("地址","合约路径","合约名称") + +@app.route('/') +def index(): + ''' + 调用 get 接口，获得 HelloWorld 的字符串 + ''' + new_str = request.args.get('new_str') + # 通过 new_str 的值更新 HelloWorld 的字符串 + if new_str: + tx_client.send_transaction_getReceipt("set",(new_str,)) + # 若 new_str 不为空则更新字符串 + return escape(str(tx_client.call_and_decode("get"))) + +if __name__ == '__main__': + app.run(host="0.0.0.0", port=80) +``` + +- step5 安装 app.py 依赖/运行程序 + +``` +pip install flaskpython app.py +``` + +这样就通过 Python-Flask 框架实现了调用 HelloWorld 合约，通过调用 get 接口查看字符串，调用 set 接口更新字符串。FISCO BCOS 的 Python-SDK 十分适合像我这样的学生党或者初学者去研究和了解区块链技术。十分期待更多开发者参与其中，用它搭建出更多有趣好玩的开源项目。Dockerfile 地址请参考文末，最近我也会对其做一些更新，提升其操作易用性，最新操作手册和消息将在GitHub上发布，欢迎大家关注。点击参考[更多Python Demo](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/sdk/python_sdk/demo.html)。 + +## 3. 提交 pr 体验 + +关于如何在 FISCO BCOS 中提交 pr 可点击参考开源社区整理的内容，这里不多做说明。详情请见[《揭秘 FISCO BCOS 开源项目开发协作》](http://mp.weixin.qq.com/s?__biz=MzA3MTI5Njg4Mw==&mid=2247485380&idx=1&sn=1f32ddad49b542206d24739f3de98b95&chksm=9f2ef5d8a8597cce973c9321543174de0e9a0bfebf1750cef4f6ae1641f4d189ea22d616cf98&scene=21#wechat_redirect) + +我想分享一下个人提交 pr 的体验，整个过程既新奇又有趣。萌生“区块链盒子”的 idea 之后，我很快就编写了第一个 Dockerfile，随即就提交了 pr。很快社区的小哥哥石翔就回复了我，刚开始我以为是国外友人，就一直用" Poor English "和他交流。他十分欢迎我的pr，还不断给我点赞和支持，他不但解决了许多在配置过程中的问题，还时不时分享一些小故事鼓励我。在合并我的pr过程中，十分感谢团队的热情帮助，及时向我提出review意见，并细心给我介绍需要添加的内容功能，这让我充分感受到 FISCO BCOS 社区和睦共处、互帮互助的氛围。 + +目前，“Python 区块链盒子”还有一些有待优化的地方，例如，每次启动一个容器都需要手动操作，启动节点的条件是-->机器暴露所需端口，默认是 20200, 8045, 30300。后期可能会考虑对默认启动节点的功能进行优化，添加数据卷，以及优化容器大小，使 fiscoorg/playground:python_sdk 更精致。如果你有不错的优化想法，欢迎提交 pr，来一次有趣新奇的 pr 体验 + +------ + +#### 参考链接 + +- [Dockerfile](https://github.com/FISCO-BCOS/python-sdk/blob/master/Dockerfile) + diff --git a/3.x/zh_CN/docs/articles/4_tools/44_sdk/talking_about_java-contract-code.md b/3.x/zh_CN/docs/articles/4_tools/44_sdk/talking_about_java-contract-code.md new file mode 100644 index 000000000..b62a5c43a --- /dev/null +++ b/3.x/zh_CN/docs/articles/4_tools/44_sdk/talking_about_java-contract-code.md @@ -0,0 +1,82 @@ +# 杂谈Java合约代码 + +作者：王章｜FISCO BCOS 核心开发者 + +FISCO BCOS提供了多种语言的SDK，包括Go、NodeJS、Python和Java。Java SDK不同于其他语言SDK，调用合约时，用户需要使用合约编译工具将Solidity合约源码生成对应的Java代码。这个由合约编译工具生成的与Solidity合约同名的Java代码，我们俗称Java合约代码，本文将介绍如何生成以及使用这份代码。 + +## 如何生成Java合约代码 + +合约编译工具可将Solidity源码生成对应的Java代码，具体使用方式可参考[以下链接](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/console/console.html#id10)。在说明合约编译工具如何生成Java合约代码之前，先介绍合约ABI的概念。ABI的定义为： + +``` +The Contract Application Binary Interface (ABI) is the standard way to interact with contracts in the Ethereum ecosystem, both from outside the blockchain and for contract-to-contract interaction. +``` + +ABI是以太坊生态系统中与合约交互的标准方式，包括了外部客户端与合约的交互、合约与合约之间的交互。更通俗的理解，ABI是合约接口的具体描述，包含合约的接口列表、接口名称、参数名称、参数类型、返回类型等等。这种描述通常为JSON格式，见[ABI格式详情](https://solidity.readthedocs.io/en/develop/abi-spec.html#json)。在EVM生态中，Solidity编译器可以生成合约ABI信息。合约编译工具生成Java代码时，编译Solidity合约生成ABI信息，并解析ABI文件，根据ABI文件的描述内容，确定合约包含的接口列表、各个接口的输入参数名称/类型列表、返回类型等信息。根据这些信息，合约编译工具为生成的Java合约合约类生成接口。具体可参考以下例子。 + +``` +// 示例合约 HelloWorld.sol +pragma Solidity ^0.4.25; + +contract HelloWorld { + string name; + function HelloWorld(){ + name = "Hello, World!"; + } + + function get()constant returns(string){ + return name; + } + function set(string n){ + name = n; + } +} +``` + +HelloWorld合约ABI： + +``` +[{"constant":false,"inputs":[{"name":"n","type":"string"}],"name":"set","outputs":[],"payable":false,"type":"function","stateMutability":"nonpayable"},{"constant":true,"inputs":[],"name":"get","outputs":[{"name":"","type":"string"}],"payable":false,"type":"function","stateMutability":"view"},{"inputs":[],"type":"constructor","payable":true,"stateMutability":"payable"}] +``` + +上述代码包含三个接口的描述信息：set、get、constructor(默认构造函数，无参数不处理)。关于set与get接口的生成可参考如下图示。 + +### set接口 + + + + +### get接口 + + + +最终生成的HelloWorld.java类： + +``` +// HelloWorld.java +// 注意：这里省略了无关内容，只保留了核心接口 +public class HelloWorld { + public RemoteCall
+
+
+
+
+#### 1.2 解决方案
+- 建立以打造“数字贡牌”为目标，围绕品种保护、生态茶园、生产管理、茶文旅等方面，构建“数字贡牌”产业数字化基础，运用物联网、区块链、5G等技术作为“数字贡牌”建设的技术支撑。用数字赋能产业，提升产业价值。
+
+- 建立“数字茶园”、“数字生产”、“数字展示”等三大数字化体系，可为生产经营、监管服务、决策分析提供多维度、多场景的品牌建设服务，实现“用数据说话、用数据决策、用数据管理、用数据创新”，用数据赋能“数字贡牌”品牌建设。
+
+##
+
+
+
+
+
+#### 2.1 数字茶园
+- 气象环境监测
+- 土壤墒情监测
+- 可视化视频监控
+- 病虫害监测预警
+
+
+
+
+
+
+
+#### 2.2 数字生产-生产计划管理
+生产计划管理系统是对企业计划的管理，具体包括制定计划、执行计划、完成计划等三方面的工作。企业生产计划主要分为田间管理计划、灌溉计划、植保计划、施肥计划、采收计划等方面。只有制定生产计划，企业才能合理安排产品生产过程的操作与管理。
+
+
+
+
+
+
+#### 2.3 数字生产-种植管理
+系统实现对种植产品种植过程提供专业和标准的生产档案信息表格，生产档案按照茶树特点和生产标准及企业标准进行定制，按照企业生产批次采集生产档案，实现生产档案数据的完整性，确保企业的每一个生产批次都有据可查。
+
+
+
+
+
+
+#### 2.4 数字展示-大数据平台
+
+
+
+
+
+#### 2.5 数字展示-溯源
+
+
+
+
+
+##
+
+
+
+
+#### 3.2 如何溯源
+消费者买到产品后，只需扫一扫产品上的二维码身份证,即可了解产品源产地、生产者、种养殖信息、农药施肥信息各类检测和流通信息、生产企业、产品品牌故事等。
+
+
+
+
+
+#### 3.3 业务痛点
+有了追溯体系，每件地方特色产品从哪来到哪去，中间经过哪些流通环节，皆可全程跟踪溯源
+
+
+
+
+
+#### 3.4 区块链 + 溯源
+
+
+
+
+利用区块链的去中心化和防篡改的特性。将农产品溯源的过程数据上链。当溯源过程数据上链后，数据将被痕迹化且不可篡改，这样可以有效的证明溯源数据的真实有效。
+
+##
+
+
+
+
+#### 4.2 5G、AI技术融合
+
+
+
+
+
diff --git a/3.x/zh_CN/docs/articles/6_application/industry_application_case.md b/3.x/zh_CN/docs/articles/6_application/industry_application_case.md
new file mode 100644
index 000000000..a2d5c0938
--- /dev/null
+++ b/3.x/zh_CN/docs/articles/6_application/industry_application_case.md
@@ -0,0 +1,138 @@
+# 区块链已革新哪些行业？附应用案例下载
+
+据新华社10月25日晚消息，中共中央政治局10月24日下午就区块链技术发展现状和趋势进行第十八次集体学习。中共中央总书记习近平在主持学习时强调，区块链技术的集成应用在新的技术革新和产业变革中起着重要作用。**我们要把区块链作为核心技术自主创新的重要突破口，明确主攻方向，加大投入力度，着力攻克一批关键核心技术，加快推动区块链技术和产业创新发展。**
+
+**报道指出，区块链技术应用已延伸到数字金融、物联网、智能制造、供应链管理、数字资产交易等多个领域。**
+
+作为集实践大成的开源底层平台，FISCO BCOS自2017年开源以来，已汇集上万名社区成员、超1000家企业及机构共同参与区块链产业生态构建，在各行各业广泛落地成熟应用案例，包括政务、金融、公益、医疗、教育、交通、版权、商品溯源、供应链、招聘、农业、社交、游戏等。
+
+我们甄选其中较为典型的应用场景出品区块链应用案例精编，带您迅速了解区块链的行业应用现状和前景。
+
+**[FISCO BCOS开源社区】公众号后台回复“案例”，可下载高清全本。**
+
+## 《FISCO BCOS案例精编》全文
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## 案例征集
+
+如果您有应用案例或应用计划，敬请通过公众号联系我们，FISCO BCOS开源社区将给予资源、技术等全方位支持。
+
+## 关于我们
+
+FISCO BCOS是首个由国内企业主导研发、对外开源、安全可控的企业级金融联盟链底层平台，为各行各业开展区块链应用提供可靠、免费的基础设施，源码在github完全开放：https://github.com/fisco-bcos，欢迎下载体验。
+
+平台由金融区块链合作联盟（深圳）（简称：金链盟）成立的开源工作组协作打造，于2017年12月正式对外开源，工作组成员包括博彦科技、华为、深证通、神州数码、四方精创、腾讯、微众银行、亦笔科技和越秀金科等金链盟成员机构。
\ No newline at end of file
diff --git a/3.x/zh_CN/docs/articles/7_community/group_deploy_case.md b/3.x/zh_CN/docs/articles/7_community/group_deploy_case.md
new file mode 100644
index 000000000..42f160fb4
--- /dev/null
+++ b/3.x/zh_CN/docs/articles/7_community/group_deploy_case.md
@@ -0,0 +1,313 @@
+# 多机部署-单群组双机构双节点组网模式实战
+
+作者：蒲沧龙(肖越)｜上海对外经贸大学区块链与应用研究中心成员
+
+## 0.需求分析
+
+有两台服务器，那么每台机子下一个机构生成一个节点，两个连一块，即：双机构双节点单群组。
+
+## 1.下载安装运维部署工具
+
+> *这里假设机子上什么都没有，因为使用源码编译客户端的用户不用最后一步*
+
+下载
+
+``` bash
+cd ~/ && git clone https://github.com/FISCO-BCOS/generator.git
+```
+
+安装(此操作要求用户具有sudo权限)
+``` bash
+cd ~/generator && bash ./scripts/install.sh
+```
+
+检查是否安装成功，若成功，输出 usage: generator xxx
+
+``` bash
+./generator -h
+```
+
+获取节点二进制
+拉取最新fisco-bcos二进制文件到meta中
+
+```bash
+./generator --download_fisco ./meta
+```
+
+检查二进制版本
+
+若成功，输出 FISCO-BCOS Version : x.x.x-x
+
+```bash
+./meta/fisco-bcos -v
+```
+
+这里遇到的问题是，二进制文件拉取贼慢。
+然后我再本机把generator克隆下来，发现是:
+
+
+
+工具类的download_fisco函数这里卡主了。没有cdn的朋友可以vim修改下这个url为：
+
+```bash
+fisco官方cdn：
+https://www.fisco.com.cn/cdn/fisco-bcos/releases/download/
+or直接下载：
+https://xiaoyue-blog.oss-cn-hangzhou.aliyuncs.com/fisco-bcos.tar.gz
+```
+
+这是俺的OSS，开放使用师傅们轻点敲啊。
+
+一秒不到就下完了。然后这个就是装好了：
+
+
+
+---
+
+## 2.联盟链初始化
+
+来康康拓扑图：
+
+
+
+因为官方教程是在一个机子上配的，是节点1,2。分起来的话实际上没有1,2之分的。因为是在两台机子上，也不会存在端口冲突的情况。如果端口没有打开可能会报错，这边建议把两台机子添加白名单就行了。详情可参考：[FSICO BCOS多机部署之端口开放](https://blog.csdn.net/xiaoyue2019/article/details/107401334)
+
+|机构|节点|rpc端口|channel端口|p2p端口|
+|---|---|---|---|---|
+|机构A|节点1|8545|20200|30300|
+|机构B|节点2|8545|20200|30300|
+
+### 2.1 机构初始化
+
+初始化机构AB
+
+```bash
+cd ~/generator
+cp -r ~/generator ~/generator-A
+cp -r ~/generator ~/generator-B
+```
+
+### 2.2 链初始化
+
+生成链证书ca.crt&链私钥ca.key
+
+```bash
+./generator --generate_chain_certificate ./dir_chain_ca
+```
+
+链证书和链私钥在`./dir_chain_ca`
+
+---
+
+## 3.构建群组
+
+### 3.1 初始化机构A
+
+生成机构A的证书
+
+```bash
+./generator --generate_agency_certificate ./dir_agency_ca ./dir_chain_ca agencyA
+```
+
+证书授权机构将机构证书发送给机构，机构放到meta目录下面
+
+```bash
+cp ./dir_agency_ca/agencyA/* ~/generator-A/meta/
+```
+
+### 3.2 初始化机构B
+
+生成机构B的证书
+
+```bash
+./generator --generate_agency_certificate ./dir_agency_ca ./dir_chain_ca agencyB
+```
+
+证书授权机构将机构证书发送给机构，机构放到meta目录下面
+
+```bash
+cp ./dir_agency_ca/agencyB/* ~/generator-B/meta/
+```
+
+### 3.3 机构A修改配置文件
+
+进入机构A修改node_deployment.ini节点配置文件、生成节点配置文件夹。
+
+```bash
+cd ~/generator-A
+cat > ./conf/node_deployment.ini<
+
+
+
+
+
+
+
+
diff --git a/3.x/zh_CN/docs/community/app_example.md b/3.x/zh_CN/docs/community/app_example.md
new file mode 100644
index 000000000..7c5faddd2
--- /dev/null
+++ b/3.x/zh_CN/docs/community/app_example.md
@@ -0,0 +1,9 @@
+# 6. 应用案例集
+
+
+
+
+
+公众号对话框回复【2023发展报告】下载全文
+
+
\ No newline at end of file
diff --git a/3.x/zh_CN/docs/community/contributor_list_new.md b/3.x/zh_CN/docs/community/contributor_list_new.md
new file mode 100644
index 000000000..2f83aa240
--- /dev/null
+++ b/3.x/zh_CN/docs/community/contributor_list_new.md
@@ -0,0 +1,129 @@
+## 2. 贡献者
+
+-----
+**2023年度 | FISCO BCOS贡献者榜单**
+
+作者：小助手
+
+2023年，世界风云变幻，科技日新月异。FISCO BCOS秉承对区块链技术的信仰，汇聚超过5000家企业机构、10万余名个人成员共建共治共享，打造更加活跃更加繁荣的开源联盟链生态圈。
+
+过去一年，一大批开源贡献者加入我们，从代码、工具、方案和布道多个方向支撑FISCO BCOS开源发展。百余位小伙伴为FISCO BCOS贡献代码，为社区带来了更健壮、更强大的FISCO BCOS；十余个团队为开源社区贡献工具组件和解决方案，进一步丰富开源生态组件和应用案例；六十多位伙伴成为FISCO BCOS的“自来水”，自发输出技术解读、操作实践和应用案例，以社区布道者身份推广FISCO BCOS。
+
+我们整理了2023年FISCO BCOS贡献者荣誉榜，感谢大家的热情参与和积极贡献！
+
+向上生长，向下扎根。来自社区的力量是支撑FISCO BCOS技术领先和生态繁荣的坚实底座。我们相信，一个更有活力、更加繁荣的区块链行业正在到来。期待更多小伙伴加入我们，共建区块链美好未来。
+
+以下名单排名不分先后，如有错漏，敬请联系小助手【FISCOBCOS010】完善。
+
+### 代码贡献
+
+代码贡献是指围绕FISCO BCOS项目，以及社区生态项目代码仓库所作的贡献，贡献形式包括但不限于提交PR修改源代码、贡献新代码、共建技术文档等。
+
+
+
+### 工具贡献
+在FISCO BCOS基础之上，社区开发者不断探索，开发出多种实用的组件、工具，便捷开发流程的同时也拓展了平台功能。目前，这些工具已全部开源并贡献给社区开发者使用，极大降低了应用开发的门槛和成本。
+
+**项目名称：WeCross-BCOS3-Stub**
+
+贡献方：科大讯飞股份有限公司、微众银行
+
+核心参与者：詹大卫、方洋、韩林波、郭锐
+
+项目介绍：
+
+WeCross-BCOS3-Stub是WeCross用于适配FISCO BCOS v3.0及以上版本的插件，成功实现了FISCO BCOS v3.0及以上版本的跨链适配。
+https://github.com/WeBankBlockchain/WeCross-BCOS3-Stub
+
+**项目名称：SmartDev-Contract 智能合约库组件**
+
+贡献方：宁夏为教科技有限公司、广东工业大学、厦门哈希科技有限公司、深圳职业技术大学、江西师范大学、北京伽罗华域科技有限公司、京北方信息技术股份有限公司、重庆电子工程职业学院、深圳职业技术大学、深圳信息职业技术学院、湖南科技职业学院。
+
+核心参与者：张生、陈汛、李奇龙、金伟、林滨、张宇豪、王江宇、刘武阳、何鸿坤、高野、向键雄、杜小敏、袁佳佳、彭添淞、罗嘉城、肖晶雄。
+
+项目介绍：
+
+为了让更多开发者参与到智能合约库组件优化，社区启动了“Task挑战赛”活动。2023年第1、2季活动分别征集了“供应链金融应收款保理融资”、“历史块高查询”、“类型转换合约”、“时间锁操作”、“多方投票”、“区块链资金透明监管与投票解决方案”、“打怪升级高达游戏”、“共享单车案例”、“给合约添加代码注释”、“公共领域的创新解决方”“电子病历案例”“囚徒困境”等合约。
+https://github.com/WeBankBlockchain/SmartDev-Contract
+
+### 方案贡献
+在2023深圳国际金融科技大赛等众多区块链权威赛事中，涌现不少基于FISCO BCOS的优秀参赛方案。本着回馈社区的开源精神，参赛者将这些方案贡献出来，为社区用户提供区块链学习了有益参考。
+
+**方案名称：AI4C——面向AIGC创作的文化数字产品运营平台**
+
+核心参与者：于祯奇、胡鑫、孙俨、杨国铭
+
+目前，AIGC文化创作面临海量素材难存查、链下推理不可信、产品版权难保护、利益分配不透明等诸多难题。为解决以上问题，团队构建面向文化数字产品AIGC创作的版权运营平台。平台集成可信版权标识等6大关键功能，实现文化数字作品版权全流程服务。开展链上存储检索、链下可信扩展技术研究，设计文化数字产品运营方案。已完成平台与FISCO BCOS区块链的研发部署，并使用可信计算硬件支撑生成式模型的隐私计算与推理加速。
+https://github.com/FISCO-BCOS/hackathon/pull/81/files
+
+**方案名称：基于FISCO BCOS的联邦学习平台**
+
+核心参与者：马昊滨、苏柄权
+
+该平台创新性地整合了联邦学习与区块链技术，实现了高效而安全的业务流程。创新提出串行+并行的联邦学习方式，巧妙提升了训练数据的多样性，减轻数据存储的压力，最大程度地保护了隐私安全。系统采用FISCO BCOS多群组部署和Ribbon负载均衡相结合，显著提升了区块链服务的处理效率与吞吐量。利用RocketMQ实现削峰确保了系统的稳定性；同时采用模型文件与文件索引分开存储的方式实现了大数据量文件上链存证的功能。通过公私钥文件实现节点可信认证，为整个系统提供了安全的基石。
+https://github.com/FISCO-BCOS/hackathon/pull/87/files
+
+**方案名称：基于区块链的供应链碳足迹一体化系统**
+
+核心参与者：邓淏天、梁浩天、王炜杰、轩浩均、任旭豪
+
+传统供应链厂商通常将碳足迹数据存储在各自的本地数据库中，导致不同供应链厂商之间的数据库数据无法流通，造成了碳足迹数据难以同步的问题。本作品提出“基于区块链的供应链碳足迹一元化系统”。该系统由三个关键技术组成，包括面向区块链的细粒度访问控制技术、链上链下混合存储的体系架构以及高效的链上链下协同机制。该系统实现了各供应链厂商间数据的同步和一致，从而助力企业实现“双碳”目标。
+https://github.com/FISCO-BCOS/hackathon/pull/89/files
+
+**方案名称：基于区块链和情感寄托的二手潮玩交易平台**
+
+核心参与者：卢隆基、高韬、伍嘉恒、袁瑶、林佳儿
+
+本项目旨在构建更加可信、高效、安全且富有温度的二手潮玩交易平台，通过情绪寄存和原创确权提升用户体验，利用区块链技术让情感故事永远留存、原创内容受到保护，同时减少交易过程的欺诈和恶意行为，推动二手交易市场的健康发展。本项目的创新点在于让情感产生价值，保护原创作者权益，项目初期在前景广阔的二手交易市场中，聚焦于二手潮玩这个特殊的品类，用故事和商品连结买家和卖家的情感进而产生共鸣：让卖家通过情感赋值将商品卖出更高的价格；同时为最有情感需求的买家，提供情绪消费的场所。
+https://github.com/FISCO-BCOS/hackathon/pull/80/files
+
+**方案名称：问链—基于区块链的ESG评级系统**
+
+核心参与者：郑惠文、钟南海、李志远
+
+在可持续发展的背景下，ESG评估成为了企业可持续性的重要指标。然而，当前市场上缺乏统一、透明且高效的ESG评估平台。现有的评估工具往往面临着评分标准不一、数据不透明、易篡改、流程冗余等问题，这不仅影响了评估的公正性，也增加了企业的运营成本。因此，开发基于区块链的ESG评分系统，旨在为企业提供可靠、透明且易于操作的ESG评估解决方案，本系统在成本效率方面具有显著优势，适合各种规模的企业及评估机构、相关监管机构使用。
+https://github.com/FISCO-BCOS/hackathon/pull/83/files
+
+**方案名称：碳路—基于区块链的碳资产管理与可信交易方案**
+
+核心参与者：张帆、宋雨、肖轶涛、王青楠、申铜博
+
+本方案针对碳数据采集、接入认证、碳资产交易、碳数据管理流程中存在的痛点，制定项目的解决方案，通过碳排放可信自动采集、多主体低成本接入认证、碳资产高效可信交易、碳数据动态授权管理等技术优势，提供打破碳市场资产交易壁垒、支持多元碳资产交易业务、多市场交易数据融合分析、碳资产交易与管理一体化方案。本项目使用FISCO BCOS v3.0区块链架构，前端使用VUE，后端使用SpringBoot等核心开发工具实现基于区块链的碳资产管理与可信交易一体化平台。
+https://github.com/FISCO-BCOS/hackathon/pull/92/files
+
+**方案名称：WeTender—适用于修建“四好农村路”的政府与企业之间的项目招标ESG治理模型**
+
+核心参与者：丁俞嘉、代钰堃、陈炜权、熊语嘉、盛媛
+
+WeTender是一个基于FISCO BCOS底层开源平台搭建的适用于修建“四好农村路”的政府与企业之间的项目招标的区块链数据信息管理平台，充分发挥了区块链技术的不可篡改性、可追溯性以及对智能合约的支持，致力于解决在“四好农村路”建设过程中的信任问题。
+https://github.com/FISCO-BCOS/hackathon/pull/86/files
+
+**方案名称：基于FISCO BCOS的匿名投票系统**
+
+核心参与者：陈鸣远、林泽君、叶力涛、鲁宇豪、张诗洁
+
+基于FISCO BCOS区块链平台搭建匿名权重投票系统，充分发挥了区块链技术的不可篡改性、可追溯性以及对智能合约的支持，致力于解决传统投票系统由中心化机构控制、不公开透明、不支持权重投票和隐私性等问题。
+https://github.com/FISCO-BCOS/hackathon/pull/91/files
+
+**方案名称：智慧兴农——从触网到触链，“红星苹果”特色农产品持“证”一键溯源**
+
+核心参与者：白琪利、李艺乐、高慧雯、陈国翠、常嘉璇
+
+智慧农业特色农产品溯源系统是集物联网、云计算、数据分析、区块链技术为一体的对农业环境与运输进行感知、分析、预测、控制的物联网平台。区块链是融合了数字、密码学、互联网和计算机编程等技术，通过去中心化和可信的方式，集体维护一个可靠数据库的技术方案。首先依托部署在农业生产现场的各种传感节点实时在线采集监测生长条件等实时数据，通过websocket长连接方式采集数据传输至FISCO BCOS区块链网络云端区块链计算中心，并通过储存加密保证了运行联盟链的数据在硬盘上的安全性与可视性，形成实际农作物从种植到运输全流程追溯，通过AI分析向种植户提供科学的种植指导和赋予农作物“一物一码”，提高农作物质量的真实性，为农作物了提供精准化种植、可视化管理、智能化决策。
+https://github.com/FISCO-BCOS/hackathon/pull/90/files
+
+### 布道贡献
+
+除了代码贡献与工具贡献，还有一类贡献者不吝于在各种渠道分享基于FISCO BCOS的开发经验与技术/产业观点，赋予了FISCO BCOS开源社区更强劲、长久的生命力和影响力，鼓励了更多人参与到生态共建中。
+
+布道贡献包括但不限于在各类活动中分享FISCO BCOS相关技术、撰写文章或编制视频解析FISCO BCOS相关技术等。布道渠道不限，如贡献名单有遗漏，欢迎联系小助手告知我们。
+
+
+
+### 贡献数据来源说明
+本期贡献者名单主要从GitHub中 FISCO BCOS代码仓库，以及FISCO BCOS Toolbox、WeBankBlockchain等社区生态项目的代码仓库中收集，统计时间周期为2023年1月1日-2023年12月31日，如有遗漏、改进建议，可联系小助手【FISCOBCOS010】反馈。
+
+
+
+扫码查看季度贡献者榜单
+
diff --git a/3.x/zh_CN/docs/community/join_fiscobcos.md b/3.x/zh_CN/docs/community/join_fiscobcos.md
new file mode 100644
index 000000000..986ebc307
--- /dev/null
+++ b/3.x/zh_CN/docs/community/join_fiscobcos.md
@@ -0,0 +1,20 @@
+# 5. 欢迎加入FISCO BCOS社区
+
+---
+
+## FISCO BCOS社区资源
+
+- [Github主页](https://github.com/FISCO-BCOS/FISCO-BCOS)
+- [技术文档](https://fisco-bcos-documentation.readthedocs.io)
+
+- [深度解析系列文章](http://mp.weixin.qq.com/mp/homepage?__biz=MzA3MTI5Njg4Mw==&hid=2&sn=4f6d7251fbc4a73ed600e1d6fd61efc1&scene=18#wechat_redirect)
+- [贡献代码](https://mp.weixin.qq.com/s/_w_auH8X4SQQWO3lhfNrbQ)
+- [反馈问题](https://github.com/FISCO-BCOS/FISCO-BCOS/issues)
+- [应用案例集](https://mp.weixin.qq.com/s/cUjuWf1eGMbG3AFq60CBUA)
+
+## 加入我们
+
+
+
+
+
\ No newline at end of file
diff --git a/3.x/zh_CN/docs/community/partner_list_new.md b/3.x/zh_CN/docs/community/partner_list_new.md
new file mode 100644
index 000000000..f48643f5a
--- /dev/null
+++ b/3.x/zh_CN/docs/community/partner_list_new.md
@@ -0,0 +1,414 @@
+# 4. 合作伙伴
+
+----
+
+**FISCO BCOS 合作伙伴**
+
+作者：小助手
+
+为了更好地推动区块链落地产业，为行业培育更多专业人才，助力区块链生态蓬勃发展，金链盟FISCO BCOS合作伙伴计划面向业界长期招募“产业应用合作伙伴”、“人才培育合作伙伴”与“生态发展合作伙伴”。
+
+产业应用合作伙伴旨在助力区块链技术更好落地应用，推动区块链产业发展；人才培育合作伙伴将与FISCO BCOS开源社区共同携手，基于FISCO BCOS开源区块链技术，开展课程研发、人才培育与人才认证等工作，助力共建区块链人才培育体系，为产业发展提供专业技能人才；生态发展合作伙伴将与FISCO BCOS开源社区共建区块链开源生态，以坚实的基础科技支撑引领产业高质量发展。
+
+自FISCO BCOS合作伙伴计划启动以来，有众多伙伴踊跃申请。截止2023年通过认证的金链盟FISCO BCOS合作伙伴共计50家（35家产业应用合作伙伴、13家人才培育合作伙伴、2家生态发展合作伙伴），为推动FISCO BCOS落地产业应用，助力区块链产业发展发挥重要作用。
+认证合作伙伴公示如下，欢迎大家添加小助手【FISCOBCOS010】了解并报名加入计划。
+
+
+
+
+
+
+
+### FISCO BCOS产业应用合作伙伴
+
+（下列根据公司名称首字母排序）
+
+
+
+**北京版权家科技发展有限公司**
+
+北京版权家科技发展有限公司携手FISCO BCOS提供数字版权服务，开发的版权区块链系统联合版权监管机构、司法机构、国家授时中心、CA等提供版权确权、盗版监测、版权维权以及版权交易等一站式版权综合服务，实现创作即确权、使用即授权、发现即维权！
+
+
+
+**北京众享比特科技有限公司**
+
+北京众享比特科技有限公司成立于2014年7月，是国内首批从事区块链底层平台和应用案例开发的技术驱动型公司之一，基于FISCO BCOS为国内外众多客户提供区块链产品和综合解决方案服务。
+众享比特是国家高新技术企业、北京市“专精特新”中小企业、2021北京市知识产权示范单位，获得2022/2021北京民营企业中小百强、2021/2020/2019毕马威中国领先金融科技50企业、2020/2019中关村瞪羚企业等荣誉。
+
+
+
+**广电运通集团股份有限公司**
+
+广电运通创立于1999年，隶属于广州无线电集团，是国有控股的高科技上市企业（证券代码:002152），主营业务覆盖智能金融、公共安全、交通出行、政务、大文旅、新零售及教育等领域，携手FISCO BCOS为全球客户提供具有竞争力的智能终端、运营服务及大数据解决方案。
+
+公司从国内金融自助设备起步，凭借多年来积累的场景落地能力、技术研发、供应链等优势，贯彻新发展理念，聚焦金融科技和城市智能两条主线，在智能金融、智能交通、智能安全、智能便民等领域，以科技赋能传统产业升级。在海外市场，公司已建立9大全球分支机构，产品及服务已进入全球100多个国家和地区。面对新一轮科技浪潮，广电运通将继续加快区块链、人工智能、大数据、物联网等前沿信息技术与实体经济的深度融合，为建设智慧大湾区和“数字中国”贡献力量。
+
+
+
+**广州市一链区块链科技有限公司**
+
+广州市一链区块链科技有限公司专注于区块链技术产品与行业应用解决方案，拥有软著专利10余项，成功应用FISCO BCOS于政企 “审计监管”场景，上线“区块链数据防篡改平台”。
+平台致力于“让天下的数据可信，没有造假”，已成功落地广汽本田、招商高速公路、安居宝等客户的审计监管场景。
+
+
+
+**虎彩集团有限公司**
+
+虎彩集团有限公司成立于1989年，是一家集数字印刷、原浆啤酒、智慧婚拍三大业务板块于一体的集团企业，旗下拥有数十家成员企业，涵盖虎彩印艺、泰山原浆啤酒、鲜檬智慧婚拍三大品牌。总部位于东莞国家级高新技术开发区松山湖。
+
+基于公司数字化和工业互联网战略，虎彩于2020年成立虎彩区块链创新应用中心，将区块链技术发展为公司工业互联网五大核心能力之一。基于FISCO BCOS，虎彩构建了包含从营销、物流、商城到内容的大量产业区块链应用，包括小虎智数营销、运力链、兑换商城、内容生态平台、统一交易结算平台和印刷链等平台，已广泛应用在虎彩实际业务中，服务超百万的合作伙伴和用户。
+
+
+
+**济南泉链海沃数字科技有限公司**
+
+济南泉链海沃数字科技有限公司是一家专注于RegTech(监管科技)细分领域的高新技术企业，由区块链领域知名学者、工信部认证的区块链技术专家以及金融科技领域人才组建，是国内首批进入政府试点目录的商用区块链公司之一，是航天信息、人民在线、山东数字出版等大型企业的区块链重点合作商。
+
+公司携手FISCO BCOS，提供一站式区块链应用解决方案，已推出链联金服平台、防篡改对比审查系统、专项资金监管、区块链超融合一体机、共享单车治理、社区数字化防疫、分布式大数据共享等产品，获得国内多项区块链赛事大奖。
+
+
+
+**价值互联（广州）区块链科技有限责任公司**
+
+价值互联（广州）区块链科技有限责任公司（简称“价值互联”或“Value++”），成立于2017年，专注于区块链相关技术、产品的研发和销售，通过打造基于区块链技术的数据交换和流通平台，融合区块链、隐私安全计算、云计算、人工智能等先进技术，构建企业间数据交换、交易、流通和共享平台，解决企业数据互信和数据的自由流通和交换，激活企业沉睡数据，实现数据聚合升华，帮助企业迈入DT智能化时代。
+
+
+
+**江苏安凰领御科技有限公司**
+
+江苏安凰领御科技有限公司成立于2017年8月，公司聚焦于区块链各应用场景，携手FISCO BCOS提供物联网安全服务、区块链产品、可信安全服务能力输出等多项解决方案与服务。致力于成为行业领先的区块链解决方案与服务提供商，助力政府、企业数字化转型。
+
+安凰领御于2020年11月获得了国家网信办区块链备案企业称号，2021年5月成功入选IDC区块链数字存证领域创新者。
+
+
+
+**京北方信息技术股份有限公司**
+
+京北方信息技术股份有限公司[股票代码：002987]作为领先的金融科技服务提供商，向以金融机构为主的客户提供软件与信息技术服务，为企业数字化建设聚势赋能。公司以大数据、云计算、人工智能、区块链、隐私计算及5G应用为引领，将前沿科技与金融业务场景深度耦合，成为行业发展的新引擎。
+
+京北方基于FISCO BCOS打造了通用的区块链公共服务平台，平台拥有区块链分布式账本、加密算法、数据存储、网络协议、共识机制、智能合约、应用API接口等核心模块。该平台支持业务信息上链、金融交易、合同文件和金融数据存证服务，优化业务流程，提升系统运行效率。平台支持金融业应用，可用于供应链金融、票据管理、跨境结算、工资代发等场景。利用加密算法、公私钥体系、共识算法、时间戳等技术，平台可出具金融区块链证书，提升金融安全，相关发明专利已获得国家知识产权局专利授权。
+
+
+
+**科大讯飞股份有限公司**
+
+科大讯飞股份有限公司是一家专业从事智能语音及语言技术，人工智能技术研究，软件及芯片产品开发，语音信息服务及电子政务系统集成的国家级骨干软件企业。2008年，科大讯飞在深圳证券交易所挂牌上市。
+
+科大讯飞致力于面向政府、行业和用户，构建一套基于区块链的数字身份、公共数据共享、智能感知的新型区块链基础设施，实现对数据要素的全面互联，解决数据跨地域、跨行业、跨系统的可信流通，推动数字经济变革。公司携手FISCO BCOS，提供区块链基础设施平台和区块链应用解决方案，已推出开放联盟链服务、存证溯源平台、版权保护系统、供应链金融融资平台等。
+
+
+
+**南京安链数据科技有限公司**
+
+南京安链数据科技有限公司是国内专业、领先的区块链公司，研发方向覆盖区块链、大数据分析等领域，已成功应用FISCO BCOS于物流、金融、溯源、存证等多业务场景，大幅降低区块链应用层开发成本。
+
+
+
+**厦门哈希科技有限公司**
+
+厦门哈希科技有限公司成立于2018年4月，隶属于北京哈希数道集团，是中关村北京绿色碳汇研究院理事单位，是致力于碳汇全产业链及生态价值开发与服务的绿色生态科技公司。
+
+公司坚持自主创新、掌握自主核心技术，以GEP为切入点，基于区块链底层平台FISCO BCOS，先后打造多个国家级、省级、市级生态价值开发及碳中和体系建设，通过林业碳汇、碳普惠等串联碳汇生态产业链，助力数字化转型，赋能碳市场交易，拓展“两山”转化通道，引领绿色低碳产业体系。将数字化的“绿水青山”变成真正价值的“金山银山”，为各地方政府职能机构及金融资源体提供全链条生态价值服务。
+
+
+
+**熵链科技（福建）有限公司**
+
+熵链科技（福建）有限公司是一家专注于产业数字化应用的综合服务商。公司于2017年率先布局区块链技术，搭建领先的区块链产业生态服务平台，为产业数字化发展提供先进的区块链解决方案。针对区块链供应链金融、农业溯源、分布式商业、数据存证与数据资产化等领域拥有自主的技术解决方案。熵链科技作为福建省区块链协会首任会长单位以及BSN福建省区块链主干网指定唯一运营商，汇聚全球领先区块链产业资源，具有专业的实践应用和市场拓展服务能力。
+
+
+
+**上海久誉软件系统有限公司**
+
+上海久誉软件系统有限公司成立于2013年，是由上海久事公司和上海公共交通卡股份有限公司共同投资组建的一家专业从事软件开发和系统集成的企业。
+
+携手FISCO BCOS，上海久誉围绕支付清算、消费交换两大核心技术，在卡基业务、移动支付、城市公交“一卡通”、“一票换乘”资金清分清算、智能终端、数据服务等行业领域拥有一流技术；公司集行业知识、应用开发、系统集成、运营管理、项目实施和增值服务为一体，坚持“自主创新、自有品牌、立足上海、辐射周边”的发展战略，在金融电子化、社会信息化等行业领域，为客户提供行业解决方案、系统集成服务及机具销售。公司在成立近5年时间内已获得二十三项项软件著作权和十七项软件产品认证证书。
+
+
+
+**上海碳抵信息科技有限公司**
+
+上海碳抵信息科技有限公司是一家专注于碳中和数字化的金融科技公司。公司长期深耕金融数字化服务业，在软件及小程序开发，数字化及运营管理等方面具备较强能力。
+
+目前，公司战略聚焦于“碳中和数字化”与“协同低碳”，致力于通过SaaS平台为政府及企业提供快速便捷的碳减排、碳中和服务，以及助力碳普惠体系建设运营、低碳数据增信等多元服务。
+
+基于区块链底层平台FISCO BCOS，公司打造了碳低链服务平台，为科技赋能低碳减排提供了新的实践探索思路。碳抵科技的合作伙伴包括多家低碳领域专业机构，服务客户包括多家大型公司以及多个大中型会议。
+
+
+
+**上海旺链信息科技有限公司**
+
+上海旺链信息科技有限公司成立于2016年，是高速成长的国家高新技术企业、国家工信部区块链重点实验室成员单位，总部位于上海，在宁波、合肥、长沙、西安、雅加达、新加坡设有分公司。2018年，荣登工信部赛迪区块链“中国区块链企业百强榜”；2020年，荣膺“亚洲创新企业Top10”；2022年，入选“2022中国产业区块链100强”。
+
+旺链科技以数据中心运营、云计算为依托，自研云管平台和云操作系统，为全球客户提供前沿的高新技术解决方案，包括智慧农业、区块链溯源、供应链金融、工业互联网、边缘计算、元宇宙模型渲染、高速分布式存储、自治组织管理等多个应用场景，已成功服务包含航空、政府、金融、能源、农业、医疗、教育、房地产、快消和汽车等在内的数十个行业数百家客户。
+旺链科技和FISCO BCOS一直保持良好的合作关系，基于FISCO BCOS研发了VoneBaaS区块链基础服务平台；公司也持续参与社区建设，多次荣登FISCO BCOS贡献榜单。
+
+
+
+**上海新致软件股份有限公司**
+
+上海新致软件股份有限公司成立于1994年，是国内领先的软件服务提供商。公司总部坐落于上海，在北京、深圳、大连、重庆、成都、贵安、武汉、东京等多地设立了分支机构。2020年12月，新致软件正式登陆A股科创板，使公司迎来新的发展篇章。
+
+公司依托20多年服务金融行业的实践经验，基于云计算、大数据、人工智能、区块链四大基础实验室的研发能力，为金融客户提供包括渠道、核心、数据、管理等全面的信息化解决方案，满足金融客户实现智能化、安全合规、业务多样化等需求，连续多年在中国保险业、银行业IT解决方案市场份额中占据领先地位。同时，公司的相关产品及服务已广泛应用于电信、医疗、汽车等诸多领域，赢得包括中国太保、中国人寿、中国人保、交通银行、建设银行、中国银联、中国电信、上海汽车、复星集团等众多优质客户。
+
+
+
+**上海信医科技有限公司**
+
+上海信医科技有限公司，是坐落在上海区块链生态谷的医疗区块链与大数据领军企业，是国家卫健委及上海、山东、湖北、浙江、四川、江西等多省市医疗区块链的核心成员与技术支撑单位；也是多家企业及多个健康医疗大数据中心等主流平台的合作伙伴。
+
+信医科技为多家医疗平台的建设提供FISCO BCOS区块链技术支持，包括“信医链电子病历夹应用”、“基于区块链的商业保险结算与审核支撑服务”、“基于区块链的中药饮片流转质量服务与监管平台”等。公司参与广州国家实验室、上海申康、国家健康医疗大数据（北方）中心多个专病库与科创大数据平台建设，覆盖近百个专病库。
+
+
+
+**上海域乎信息技术有限公司**
+
+上海域乎信息技术有限公司是一家以区块链技术为核心的高新技术企业，专注于区块链技术与数字资产服务，2018年通过工信部区块链系统功能测试，曾参与工信部物联网区块链蓝皮书和区块链技术安全标准编写。域乎应用FISCO BCOS实现农业数字化，确保数字农业主体身份和数据可信，助力企业、政府、银行等机构实现可信数据共享。
+
+
+
+**深圳市瀚兰区块链地产有限公司**
+
+深圳瀚兰区块链地产有限公司基于区块链帐本管理技术自主研发互联网平台兰房链，由成熟的区块链底层技术及海内外区块链专家团队提供技术支持，实现一种“非接触”式的可信赖的新型房地产商业模式，在房地产开发行业中建立信用及价值体系，立足数字经济，打造的房地产数字化运营管理SaaS工具，解决房地产开发中的痛点，为房地产行业上下游企业提质增效。
+
+
+
+**中碳绿信科技（深圳）有限公司**
+
+中碳绿信科技（深圳）有限公司成立于2018年5月17日，是中国碳中和发展集团旗下专注于以区块链赋能双碳经济的国家高新技术企业。
+
+绿信科技为产业打造跨组织协同、驱动价值共识、提炼数字资产的金融级可信协同网络-绿信链。通过降低区块链技术的使用门槛与成本，促进全球更多企业和个体基于区块链建立数字信用，实现商业创新，连接绿色金融。
+
+
+
+**深圳市新国都数字科技有限公司**
+
+深圳市新国都数字科技有限公司成立于 2016 年，是上市公司新国都股份(300130) 旗下公司。新国都数科依托数字科技能力，形成了数字政企、数字征信、数字安全、数字用工四大核心业务板块，主要提供数据治理、数据产品、数据应用开发、数据资产运营、数据安全等服务。
+
+新国都数科坚持以“数据资产运营商”为使命，以大数据、人工智能、区块链技术为核心，携手FISCO BCOS在区块链底层平台、隐私计算等领域开展合作，提供数据分析、平台技术、区块链产品和运营服务，为政府、金融机构、国有企业提供数字化服务综合解决方案，致力于为社会诚信体系建设做出贡献。
+
+
+
+**数金公共服务（青岛）有限公司**
+
+数金公共服务（青岛）有限公司是一家数字金融科技企业，是数字人民币试点落地机构和标准组成员企业，业务涉及绿色低碳及数字金融等领域。公司深度参与数字人民币试点推广过程中的技术研发、产品创新、运营拓展、资源协同以及生态建设等服务，为政府、企业以及金融机构接入数字人民币系统、开展数字人民币活动提供“场景+技术+服务”支持，推动数字金融科技生态构建和产业升级。
+
+公司携手FISCO BCOS 围绕个人碳普惠领域推出了场景化解决方案，包括利用区块链做数据的可信存证，解决数据的多方信任问题；链接碳普惠的各参与方，构建一个开放、共创、可信的碳普惠联盟链生态。
+
+
+
+**数字广东网络建设有限公司**
+
+数字广东网络建设有限公司作为广东省数字政府建设运营中心和中国电子二级机构，坚持数字政府公益性、基础性、平台性、保障性定位，聚焦数字政府公共服务、基础设施、平台建设、安全防护等主责主业，有力支撑广东省经济社会高质量发展，有力推进治理体系和治理能力现代化，为积极探索中国式现代化的广东路径作出了重要贡献。公司目前拥有近3000名员工，其中技术类人员占比超过七成。
+
+数字广东公司现已建成省市一体化的政务云平台、一网共享平台和公共支撑平台，持续夯实数字政府基础底座，并打造了粤省事、粤商通、粤政易、广东政务服务网、“一网统管”粤治慧平台、粤公平等一系列数字政府改革建设重要成果，全面支撑广东数字政府改革建设事业走在全国前列，在改善民生服务、优化营商环境、提升政府治理能力现代化等方面发挥了重要作用。数字广东将携手FISCO BCOS持续探索区块链在智慧政务领域的应用场景。
+
+
+
+**四川虹信软件股份有限公司**
+
+四川虹信软件股份有限公司是四川长虹旗下旗舰企业之一，历经十余年高速发展，成为拥有四大核心能力的高新技术企业，专注于智慧企业、智慧城市、军民融合三大业务领域前沿IT技术研发、咨询与实施。借助在智能家居领域的优势，长虹携手FISCO BCOS建立可信互联物联网，虹信软件承担身份认证模块，利用FISCO BCOS证书认证体系，完善物联网中群组/节点准入验证机制，为跨品牌智能家居场景提供可信数据基础。
+
+
+
+**四川万物数创科技有限公司**
+
+四川万物数创科技有限公司是具备科技创新能力的新经济企业。企业核心产品CoT Network万物共算网络是自主可控的多元弹性网络计算系统，融合区块链分布式计算以及边缘计算技术，为各行业和场景提供区块链系统及应用、多元计算软硬件产品、区块链服务、以及行业整体解决方案的咨询和实施。目前，四川万物基于FISCO BCOS落地了社区智慧化治理和服务、智慧党建等方向应用案例案例。
+
+公司核心团队由海外归国专家及世界500强企业管理者组成，拥有多项知识产权和优质合作伙伴。
+
+
+
+**泰康养老保险股份有限公司**
+
+泰康养老保险股份有限公司是由泰康人寿保险股份有限公司和泰康资产管理有限责任公司共同出资成立的全国性、股份制专业养老保险公司。业务范围涵盖团体保险、企业年金、个人养老保险三大领域。目前在全国已成立了23家分公司及9家企业年金中心。
+
+泰康养老作为国内五家专业养老保险公司之一，始终奉行“专业化、规范化、国际化”的发展战略，携手泰康资产，依托泰康人寿十七年丰富的员工福利及补充养老保险管理经验，坚持“以客户为中心、以价值为导向，做强员福、做大年金”的经营策略，致力于为广大企业和企业员工提供团体寿险、意外伤害险、短期健康险、团体养老险、企业年金、个人养老险全方位的员工福利计划和一站式服务，用专业的服务做市场上最好的企业员工福利解决方案的好管家。泰康养老已基于FISCO BCOS落地多个应用，未来将继续携手FISCO BCOS针对保险健康管理场景探索更多解决方案。
+
+
+
+**万高信息科技有限公司**
+
+万高成立于2014年，于2015年组建珠海分公司，为澳门提供长期、稳定、充足的人力资源保障，万高团队按不同业务划分，专责专项管理。技术研发团队稳定且项目经验丰富，旨在为客户提供更好的技术建议和开发服务。
+
+目前公司已接受FISCO BCOS专业培训的人员有8人，并计划让更多的人员接受FISCO BCOS的专业培训。万高专注移动及数据应用程式开发，2019年疫情期间，成功采用FISCO BCOS技术开发澳门健康码供澳门政府应对疫情，并助力粤澳两地健康码在2020年5月实现跨境互认。迄今，粤澳健康码跨境互认系统已服务上亿人次通关。
+
+
+
+
+**武汉链动时代科技有限公司**
+
+武汉链动时代科技有限公司携手FISCO BCOS解决区块链应用开发“最后一公里”问题，研发的“inBC区块链存证服务系统”对链上数据进行格式化协同，实现区块链存证一键触达；”Falcon零代码开发平台” 通过图形化拖拽、参数配置等即可高效完成系统搭建和部署。
+
+
+
+
+**武汉领晟旺链科技有限公司**
+
+武汉领晟旺链科技有限公司成立于2018年11月，是武汉市区块链协会秘书长单位，其前身为菲旺科技区块链事业部。公司是国内领先的区块链+智慧城市数权服务提供商，围绕“智链城市”建设，在政务、物联网、数据安全等方面打造并落地了一系列产品及解决方案，其中基于FISCO BCOS开发的“链税通” 是全国税收治理领域第一个区块链项目；“明厨亮灶区块链物联网平台”被评选为工信部2020年新型信息消费示范项目。
+
+同时，公司获批成为工业和信息化重点领域（区块链）人才能力评价机构，目前已获得区块链相关软著15项，已申报了8项专利。
+
+
+
+**易宝支付有限公司**
+
+易宝支付成立于2003年，是首批获得中国人民银行《支付业务许可证》的第三方支付机构。2006年易宝创立B端行业支付模式，为企业客户提供集技术、产品、服务为一体的一站式数字化交易服务解决方案。目前，易宝已累计服务超过百万家商户，覆盖航空、旅游、零售、能源、汽车、互联网3.0、跨境、金融、政务、本地生活等众多行业头部客户，业务规模位居行业前列。
+
+公司基于FISCO BCOS孵化了极速不卡顿的交易级联盟链——亿链，亿链首创支付节点合约规则，并引入公信力节点，可保障数字资产永久留存、可信流通。通过打造聚焦Web3.0经济系统的技术底座，持续为企业客户提供极速、安全、稳定的链上交易解决方案，构建生态共融的开放联盟链，引领Web3.0可信生态的升级跃迁。
+
+
+
+**易联众信息技术股份有限公司**
+
+易联众信息技术股份有限公司是国内民生信息服务领域上市公司。自2000年成立以来，易联众牢记“让天下没有难过的人生”的企业使命，以大数据为驱动，重点围绕“医疗保障、卫生健康、人力资源和社会保障”等民生领域，提供全方位的整体解决方案和产品与技术服务体系。公司充分利用大数据、区块链及人工智能等技术，持续研发并提升产品创新能力，推动主营业务数字创新。
+
+
+
+**浙江天演维真网络科技股份有限公司**
+
+浙江天演维真网络科技股份有限公司是全国领先的乡村振兴数字化服务整体解决方案提供商，成功应用FISCO BCOS于农业全过程溯源，目前正在融合区块链与物联网技术研发智慧农业云平台、探索区块链+农业金融应用场景。
+
+
+
+**中国铁塔股份有限公司**
+
+中国铁塔股份有限公司是由国务院推动成立的国有大型通信基础设施服务企业。主要从事通信铁塔等基站配套设施和高铁地铁公网覆盖、大型室内分布系统的建设、维护和运营，同时依托独特资源面向社会提供信息化应用和智能换电、备电、充电等能源应用服务，是我国移动通信基础设施建设的“国家队”和5G新基建的“主力军”，是全球最大通信基础设施服务商。
+中国铁塔入选2019年《财富》全球未来50强（排名第22位）和全球数字经济100强（排第71位），2018-2020连续三年被评为中国证券金紫荆奖“最具投资价值上市公司”，在第十一届中国证券金紫荆奖中荣获“十四五最具投资价值上市公司”特别大奖。
+
+中国铁塔聚焦自主可控区块链技术研发，具备FISCO BCOS开发能力，正在基于FISCO BCOS开源技术建设区块链管理平台。中国铁塔也致力于区块链应用研究，开展的“区块链+税务”的研究成果获得国资委主办的首届“国企数字场景创新专业赛”大赛一等奖，业务模式受到社会各界关注与国内外权威媒体报道。
+
+
+
+**中金数据（武汉）超算技术有限公司**
+
+中金数据（武汉）超算技术有限公司成立于2016年，位于武汉市国家网络人才与创新产业基地，是一家主要以数据中心外包与运维服务为基础，对外开展云计算、区块链、网络与信息安全、超级计算、系统集成等信息技术服务业务的高新技术企业，同时，也是武汉市科技“小巨人”企业、武汉市“瞪羚”企业，并获得武汉市大数据企业20强、武汉市软件与信息技术百强企业等资质荣誉。
+
+公司携手FISCO BCOS提供国内领先的安全数据底座和可信数据服务。公司基于云计算和区块链底层技术搭建的中金数据云链平台，面向用户提供纵贯数据中心、云计算、大数据、区块链的开发、部署、应用的一体化服务，被评为湖北省发展和改革委员会2022年数字经济试点示范项目、入选“2022年湖北省区块链十大优秀应用案例”。
+
+### FISCO BCOS人才培育合作伙伴
+
+（下列根据公司名称首字母排序）
+
+
+
+**巴比特学院**
+
+巴比特是国内领先的区块链信息与技术服务商,已发展成集资讯内容、线下活动、培训、孵化器、投资和区块链技术落地应用于一体的生态体平台。巴比特学院是巴比特旗下教育培训品牌，携手FISCO BCOS打造区块链人才高地，向社会输送优质区块链人才。
+
+
+
+**北京柏链道捷教育科技有限公司**
+
+柏链教育是国内领先的区块链及数字化教育人才服务机构，入选工信部重点领域人才评价和能力提升任务承担单位，携手FISCO BCOS推出《区块链工程技术系列认证课程》，学员通过认证考试可获得国家级区块链技术证书。
+
+
+
+**北京智谷星图教育科技有限公司**
+
+智谷星图是一家具有国际化视野的前沿科技产教融合机构，提供区块链技术解决方案的同时，围绕前沿科技（区块链、人工智能等技术）为高校提供实验室共建、专业共建和产业学院共建等服务。
+
+智谷星图的团队成员多数来自美国硅谷，拥有成熟的新技术研发能力，包括区块链底层技术积累。同时，产品及教研团队则拥有丰富的教育行业从业经验，顾问团队来自斯坦福大学、卡耐基梅隆大学等知名高校。依托于强大的硅谷产学研资源及全球产业合作方，智谷星图紧扣产业发展趋势，用新技术推动高等教育的进步，力求培养具有国际化视野及实践能力的综合型人才。
+
+
+
+**广东中创智慧科技有限公司**
+
+广东中创智慧科技有限公司成立于2018年，从事数字经济产教融合的业务。公司是广东省发改委评定的产教融合型企业、广东省产教融合促进会副会长单位，以数字经济产教融合专家为定位。中创智科通过自身优势资源，以及强大的整合能力，发展数字经济产教融合的业务，为广东省各类院校的专业建设和人才培养提供最优产教融合解决方案。包括：区块链、大数据、人工智能、信创、网络安全、工业互联网六个领域，与广东省今年7月8日发布的《广东省数字经济发展指引》中重点发展的数字经济新兴产业高度契合。
+
+中创携手FISCO BCOS支持了2022年度教育部区块链国家级培训计划项目，支持了深圳市人社局区块链应用操作员赛项，同时，也是广东省人社厅区块链应用操作员赛项唯一技术支持单位，广东省教育厅区块链技术应用赛项唯一技术支持单位。
+
+
+
+
+**教链科技（深圳）科技有限公司**
+
+教链科技（深圳）有限公司是国际领先的区块链教培产品及应用解决方案供应商，致力于构建数字化时代的职业教育培训基础设施。教链科技专注于区块链人才发展的专业服务，提供创新课题申报、学科专业共建、区块链培训课程、国家区块链人才技能等级认证培训、实训游学营和师资培训等服务。
+
+秉着“让每位区块链从业者都拥有中高级技能职称”的愿景，教链科技已经发布了《区块链应用操作员》职业培训教材，承办了国内多期区块链应用操作员职业培训，其区块链在线实训平台已通过国家工业和信息化部备案。教链科技拥有目前国内最大的区块链应用操作考试题库以及培训课程资源，基于FISCO BCOS开发的应用系统已对超过8000件的区块链课程进行版权上链保护，也是广东、海南、浙江、上海、安徽等全国多个省市的区块链职业认证合作伙伴。
+
+
+
+**链人国际咨询（北京）有限责任公司**
+
+链人国际服务G端、B端、C端，是中国领先的区块链产业人才综合服务商，三部委区块链人才认证服务商，工信部人才交流中心区块链产业人才研究所运营方，拥有院士科学家人才库、从业者人才库和师资人才库。已在高校公开课、区块链开发工程师（周末班）、《企业级联盟链原理及应用》线上课中培训FISCO BCOS区块链。
+
+
+
+**南京秉蔚信息科技有限公司**
+
+南京秉蔚信息科技有限公司聚焦区块链、人工智能、大数据新工科专业工程实践能力建设。与全球知名产业企业合作，以岗位技能需求为设计出发点，为高校提供泛IT领域的专业课程资源库，以真实商业案例实现过程为蓝本，为院校提供案例数据、实验实训手册以及实验实训环境，并和高校教师组成混编师资为学生提供专业技能实训教学服务，是“互联网+教育”领域的综合人才培养解决方案提供商，助力高校建设产学融合的新工科教育新生态。
+
+公司坚持以赛促教、以赛促学，积极参与高校相关赛事。2023年联合微众区块链作为技术支持单位支持“中国大学生计算机设计大赛-区块链应用与开发”赛道，围绕FISCO BCOS及其周边组件进行赛道命题。目前公司已与全国100余所高校有过深度合作。
+
+
+
+**前海丰创区块链（深圳）有限公司**
+
+丰创区块链成立于2016年12月，是国内较早成立并高速发展的区块链培训、咨询服务公司，目前公司具有完备、高效、成熟的运营团队，是国内最专业、最权威的区块链教育和运营团队之一，是国内首个官方（国家工信部人才交流中心）指定授权的区块链人才提升机构。
+
+目前公司已培养了首期区块链行业产品经理、区块链金融行业工程师等行业领军人才，学员遍及山东、山西、河南、河北、安徽、江苏、浙江、广东、湖南、湖北、北京、上海等25个省份（直辖市），涵盖传统行业中高层管理者、区块链爱好者、应届大学生等 。
+
+
+
+**深圳点宽网络科技有限公司**
+
+深圳点宽网络科技有限公司是一家致力于协助高校实现交叉学科建设的教育科技公司，主要在金融科技领域协助高校培养“金融+科技”的复合人才。公司为高校相关专业提供课程、实训系统、专业建设解决方案以及共建金融科技产业学院。点宽以自主研发的课程产品和实训系统产品为依托，目前已自研金融科技相关课程超400个小时，全自主研发行业实训系统6套，协助高校的经济管理、数学统计、金融工程和金融数学等专业实现金融科技人才培养服务。
+
+公司携手FISCO BCOS，落地了面向高校区块链专业人才培养的BCW v1.0区块链编程实践平台，用于区块链专业知识学习和智能合约编程实践。创新项目CERX研学资源交换平台正在研发中，该平台是一个基于FISCO BCOS区块链技术的分布式研学资产交换网络，其目标是在高校之间创建一个数据、算法模型、论文和课程的数据资产流转平台，公司首席架构师曾凭对社区的贡献荣获FISCO BCOS年度MVP。
+
+
+
+**深圳市火链教育科技有限公司**
+
+深圳市火链教育科技有限公司，简称”火链科技“，是一家专注于区块链行业生态构建、输出区块链核心技术及教育的公司，拥有国内领先的行业科技与教学水平。
+
+公司主要的产品与业务包括，为政府提供区块链技术支持与咨询服务，构建区块链生态结构，赋能地方经济；为企事业单位输出技术服务，主导或参与DApps开发；与全国各大高校合作建立区块链学院，开设区块链专业，并面向社会招生。
+
+
+
+**深圳职业技术学院**
+
+深圳职业技术学院2019年起开办区块链技术应用专业，并面向全国招生，以FISCO BCOS国产开源区块链为技术主线，成立区块链与数字经济研究所和FISCO BCOS区块链人才培育SIG，深化区块链部署运维、智能合约编程、工程项目开发等能力的培养，为区块链产业输送高素质技术技能人才。多名学生在国家及省市各类区块链比赛中获得10余项大奖，其中2名学生荣获FISCO BCOS年度MVP。
+
+
+
+**腾讯教育腾实学院**
+
+腾实学院是腾讯教育旗下的学院，提供全面、最新的教育人才培养解决方案，学院切实推动教育部关于“世界一流大学和一流学科”、“特色高水平高职学校和专业”建设的宏伟目标，涵盖区块链、人工智能、大数据等十大领域课程内容。去年开始，腾实学院与FISCO BCOS展开培训领域广泛合作。
+
+
+
+**西南林业大学**
+
+西南林业大学建设有云南省供应链管理区块链工程研究中心和云南省高校供应链管理区块链创新团队，承担了多项区块链领域的国家级项目和省部级重大项目，其研发的安全可控区块链基础服务平台“西林链”已在跨境贸易、数字烟叶、供应链和绿色食品溯源等多个领域进行应用。中心和团队携手FISCO BCOS提供区块链产品、技术研发和人才培养等服务，助力政府和企业的数字化转型。
+
+“西林链”于2022年3月通过了国家网信办第七批境内区块链信息服务备案，2022年5月通过了中国电子技术标准化研究院“区块链系统功能测试”和中国合格评定国家认可委员会（CNAS）认证
+
+### FISCO BCOS生态发展合作伙伴
+
+
+
+**北京区块链技术应用协会**
+
+北京区块链技术应用协会是中国首家区块链应用协会，于2016年正式发起成立，是依法在民政部门注册，在北京市投资促进服务中心指导成立的非营利性专业性社会组织。协会基于“政策引导、理论研究、场景应用、资本接入、技术实践“的全业务链整合原则，利用丰富的社会资源，与国内一流高校科研院所、国内外知名企业及核心会员单位共同构建政、产、学、研、用一体的区块链生态体系，旨在通过区块链集聚行业资源，跨界融合推进区块链发展，促进先进技术的创新与发展。
+协会携手FISCO BCOS在区块链行业赛事、生态交流、人才培养等多方面开展合作，推动技术成果落地应用，营造产业发展良好生态，加快推动区块链蓬勃发展。
+
+
+
+**四川省区块链行业协会**
+
+四川省区块链行业协会是在四川省经济和信息化厅的指导下，在四川省民政厅登记注册成立的社会团体。协会成立旨在推动四川区块链与实体经济融合发展，加强行业企、事业单位和个人之间的合作与联系，加速区块链技术的应用，发展四川区块链产业、积极推动本土企业开拓国内外市场，并发挥协会的纽带作用，起到推进四川省区域内区块链产业的良好发展作用。
+
+蜀信链是在四川省经济和信息化厅指导下，在四川省区块链行业协会组织下，由全省区块链相关从业与应用机构共同参与建设和运营的区域性区块链基础设施，目前已适配FISCO BCOS。协会将携手FISCO BCOS开源社区，通过多方协同共同打造合作共赢的区块链产业生态。
+
+**推荐阅读：**
+
+[FISCO BCOS合作伙伴计划正式启动，火热招募中](https://mp.weixin.qq.com/s/BXiNVs-OBY3AD13NI8gF_Q)
+
+[首批FISCO BCOS合作伙伴公示](https://mp.weixin.qq.com/s/JAm14f7LzHO8gDRe_LXjbw)
+
+[公告 | FISCO BCOS新增9家合作伙伴](https://mp.weixin.qq.com/s/p7Mv3X18h6099sHpfoOVJg)
+
+[公告 | FISCO BCOS新增6家合作伙伴](https://mp.weixin.qq.com/s/TI_M5pbBhb0utu0jf6e3hA)
diff --git a/3.x/zh_CN/docs/community/pr.md b/3.x/zh_CN/docs/community/pr.md
new file mode 100644
index 000000000..0ab96e263
--- /dev/null
+++ b/3.x/zh_CN/docs/community/pr.md
@@ -0,0 +1,75 @@
+# 3. PR 代码规范
+
+-----
+### 文章贡献PR操作指引
+
+如果你已经是社区贡献者，可直接按照如下操作完成文章PR提交；如果你初次尝试PR贡献，请参考[文档](https://mp.weixin.qq.com/s/_w_auH8X4SQQWO3lhfNrbQ)。
+
+
+#### 1、提PR的预置条件：Fork FISCO-BCOS-DOC到个人github仓库
+
+1. step1：进入[注册GitHub账号](https://github.com/join)
+2. step2: Fork [FISCO-BCOS-DOC](https://github.com/FISCO-BCOS/FISCO-BCOS-DOC) 到个人仓库
+
+#### 2、分支说明
+
+PR须提到FISCO-BCOS-DOC的release-3分支
+
+#### 3、必备工具：git [点击参考](https://gitee.com/help/articles/4106)
+
+1. mac系统：brew install git
+2. windows系统：点击[下载安装](https://git-scm.com/downloads)
+3. ubuntu系统：sudo apt install git
+4. centos系统：sudo yum install git
+
+#### 4、主要的git命令：
+
+（以下步骤只需要执行一次即可）
+
+- 将官方的[FISCO-BCOS-DOC](https://github.com/FISCO-BCOS/FISCO-BCOS-DOC)添加为upstream: git remote add upstream
+
+
+
+（以下步骤每次都要操作）
+
+**每次提交PR之前，均需要执行以下命令，同步最新的官方文档：**
+
+1. 拉取官方文档release-3分支的最新文档：git fetch upstream release-3
+
+2. 同步官方文档release-3分支最新文档到本地：git rebase upstream/release-3
+
+ (注：本步骤可能会有冲突，如果有冲突，请解决冲突，点击参考[冲突解决方法](https://gitee.com/help/articles/4194))
+
+3. 将同步后的文档推到个人的git仓库：git push origin -f
+
+**提交个人文档的主要命令**
+
+git add, git commit, git push等，[点击参考](https://gitee.com/help/articles/4114)。
+
+#### 5、文档格式说明
+
+1. 须采用markdown的格式编辑文章内容，[点击参考markdown语法](https://www.runoob.com/markdown/md-tutorial.html)。
+2. (本步骤不强制) 提交PR之前，建议先基于个人仓库的文档构建readthedocs，检查构建出来的文档显示是否符合预期，并在提交PR的时候，附带说明个人构建的readthedocs链接。
+
+点击参考[readthedocs构建方法](https://www.jianshu.com/p/d1d59d0cd58c)， FISCO-BCOS-DOC的readthedocs配置选项参考下表：
+
+| **设置字段** | **设置结果** |
+| - | - |
+| 默认分支 | release-3 |
+| 文档类型 | Sphinx |
+| 所需的文件 | repuirements.txt |
+| Python解释器 | CPython |
+| 使用系统包 | 是 |
+| Python配置文件 | conf.py |
+
+#### 6、Reviewer反馈和合入
+
+提交PR后，Reviewer会将修改意见直接在GitHub上进行反馈，你也可以添加小助手微信FISCOBCOS010进行直接沟通；最后当Reviewer合入PR时，你的文章就被录入啦！
+
+### 文章PR贡献写作规范
+
+- 开头署名为撰稿人姓名，也可以展现个人所属公司或学校，例如，作者：张三 | FISCO BCOS核心开发者；
+- 文章内容尽量包含引言介绍，段与段之间自然衔接和过度，文末总结；
+- 文章应保证文句通顺、无语病，表述不会引起读者误解；
+- 实操类文章需确保技术点准确无误，并能完成测试跑通；
+- 如果文章中涉及到相关技术文档或代码仓库链接，为避免链接失效，请使用FISCO BCOS官方链接。
\ No newline at end of file
diff --git a/3.x/zh_CN/docs/contract_develop/Liquid_develop.md b/3.x/zh_CN/docs/contract_develop/Liquid_develop.md
new file mode 100644
index 000000000..688a33473
--- /dev/null
+++ b/3.x/zh_CN/docs/contract_develop/Liquid_develop.md
@@ -0,0 +1,19 @@
+# 3. WBC-Liquid合约开发
+
+标签：``开发第一个应用`` ``WBC-Liquid`` ``合约开发`` ``区块链应用`` ``WASM``
+
+---
+FISCO BCOS 支持用以下几种方式实现智能合约
+
+* [Solidity](https://solidity.readthedocs.io/en/latest/)：以太坊生态中采用的合约编程语言，FISCO BCOS为其拓展了面向联盟链的一系列功能，是FISCO BCOS上智能合约开发最常用的方式。
+* [预编译合约](./c++_contract/add_precompiled_impl.md)：在区块链节点内部直接内置定制化的智能合约，用c++语言实现，能直接调用节点内部各种接口，面向复杂场景，使用门槛较高。
+* [WBC-Liquid](./Liquid_develop.md)：微众区块链开发的基于Rust的智能合约编程语言，借助Rust语言特性，能够实现比Solidity语言更强大的编程功能。
+
+
+
+WBC-Liquid是微众区块链开发的基于Rust的智能合约编程语言，借助Rust语言特性，能够实现比Solidity语言更强大的编程功能，相关教程请见：
+
+- 相关文档：[Liquid 在线文档](https://liquid-doc.readthedocs.io/zh_CN/latest/)
+- 相关文档：[Rust语言官方教程](https://doc.rust-lang.org/book/)
+- 相关文档：[开发第一个WBC_Liquid区块链应用](../quick_start/wbc_liquid_application.md)
+
diff --git a/3.x/zh_CN/docs/develop/precompiled/add_precompiled_impl.md b/3.x/zh_CN/docs/contract_develop/c++_contract/add_precompiled_impl.md
similarity index 100%
rename from 3.x/zh_CN/docs/develop/precompiled/add_precompiled_impl.md
rename to 3.x/zh_CN/docs/contract_develop/c++_contract/add_precompiled_impl.md
diff --git a/3.x/zh_CN/docs/contract_develop/c++_contract/index.md b/3.x/zh_CN/docs/contract_develop/c++_contract/index.md
new file mode 100644
index 000000000..87180adc5
--- /dev/null
+++ b/3.x/zh_CN/docs/contract_develop/c++_contract/index.md
@@ -0,0 +1,18 @@
+# 2. c++ 合约开发(预编译合约)
+
+标签：``预编译合约`` ``接口`` ``开发``
+
+----------
+
+```eval_rst
+.. toctree::
+ :maxdepth: 1
+
+ use_precompiled.md
+ precompiled_contract_api.md
+ precompiled_error_code.md
+ use_kv_precompiled.md
+ use_crud_precompiled.md
+ use_group_ring_sig.md
+ add_precompiled_impl.md
+```
diff --git a/3.x/zh_CN/docs/develop/precompiled/precompiled_contract_api.md b/3.x/zh_CN/docs/contract_develop/c++_contract/precompiled_contract_api.md
similarity index 100%
rename from 3.x/zh_CN/docs/develop/precompiled/precompiled_contract_api.md
rename to 3.x/zh_CN/docs/contract_develop/c++_contract/precompiled_contract_api.md
diff --git a/3.x/zh_CN/docs/develop/precompiled/precompiled_error_code.md b/3.x/zh_CN/docs/contract_develop/c++_contract/precompiled_error_code.md
similarity index 100%
rename from 3.x/zh_CN/docs/develop/precompiled/precompiled_error_code.md
rename to 3.x/zh_CN/docs/contract_develop/c++_contract/precompiled_error_code.md
diff --git a/3.x/zh_CN/docs/develop/precompiled/use_crud_precompiled.md b/3.x/zh_CN/docs/contract_develop/c++_contract/use_crud_precompiled.md
similarity index 100%
rename from 3.x/zh_CN/docs/develop/precompiled/use_crud_precompiled.md
rename to 3.x/zh_CN/docs/contract_develop/c++_contract/use_crud_precompiled.md
diff --git a/3.x/zh_CN/docs/develop/precompiled/use_group_ring_sig.md b/3.x/zh_CN/docs/contract_develop/c++_contract/use_group_ring_sig.md
similarity index 100%
rename from 3.x/zh_CN/docs/develop/precompiled/use_group_ring_sig.md
rename to 3.x/zh_CN/docs/contract_develop/c++_contract/use_group_ring_sig.md
diff --git a/3.x/zh_CN/docs/develop/precompiled/use_kv_precompiled.md b/3.x/zh_CN/docs/contract_develop/c++_contract/use_kv_precompiled.md
similarity index 100%
rename from 3.x/zh_CN/docs/develop/precompiled/use_kv_precompiled.md
rename to 3.x/zh_CN/docs/contract_develop/c++_contract/use_kv_precompiled.md
diff --git a/3.x/zh_CN/docs/develop/precompiled/use_precompiled.md b/3.x/zh_CN/docs/contract_develop/c++_contract/use_precompiled.md
similarity index 100%
rename from 3.x/zh_CN/docs/develop/precompiled/use_precompiled.md
rename to 3.x/zh_CN/docs/contract_develop/c++_contract/use_precompiled.md
diff --git a/3.x/zh_CN/docs/contract_develop/contracts_IDE_develop.md b/3.x/zh_CN/docs/contract_develop/contracts_IDE_develop.md
new file mode 100644
index 000000000..a796b8ee1
--- /dev/null
+++ b/3.x/zh_CN/docs/contract_develop/contracts_IDE_develop.md
@@ -0,0 +1,9 @@
+# 4. 使用IDE
+标签： ``IDE合约`` ``智能合约`` ``合约开发``
+
+----
+
+FISCO BCOS支持通过区块链管理平台webaseIDE部署合约以及Remix在线IDE开发合约，具体操作与部署步骤可参考下述文档：
+- [WeBASE合约IDE](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE/quick-start.html?highlight=%E5%90%88%E7%BA%A6IDE#id3)
+- [Remix在线IDE](https://remix.ethereum.org/)
+- [Solidity官方文档](https://solidity.readthedocs.io/en/latest/)
diff --git a/3.x/zh_CN/docs/contract_develop/opcode_diff.md b/3.x/zh_CN/docs/contract_develop/opcode_diff.md
new file mode 100644
index 000000000..296c96d27
--- /dev/null
+++ b/3.x/zh_CN/docs/contract_develop/opcode_diff.md
@@ -0,0 +1,70 @@
+# 5. EVM OPCODE 兼容性描述
+
+该文档从OPCODE的角度描述FISCO BCOS与以太坊在执行行为上的差异：
+
+1. 基础操作指令与以太坊相同
+2. 国密版的密码计算OPCODE为国密算法
+3. 联盟链设计
+ * Balance相关OPCODE需用开关打开
+ * POW、POS相关OPCODE默认返回0
+
+FISCO BCOS 属于[Type 3](https://vitalik.eth.limo/general/2022/08/04/zkevm.html)兼容（兼容Type描述见附录）
+
+## OPCODE 兼容性分类
+
+* 无差异
+ * 默认支持：计算类、指令跳转类、内存操作类
+ * 新版本支持：代码类，调用类
+* 半差异（详细描述见下一节）
+ * 功能类似：TIMESTAMP、GASLIMIT、SELFDESTRUCT
+ * 国密版不同：KECCAK256、CREATE2
+ * 通过开关开启：BALANCE、CALLVALUE、GASPRICE、SELFBALANCE
+* 全差异
+ * 默认返回0：COINBASE、PREVRANDAO、CHAINID、BASEFEE
+
+## OPCODE 兼容性描述列表
+
+（*表格中未给出的OPCODE为默认支持，无差异 -，半差异 ○，全差异 ●）
+
+| Stack | Name | 差异 | 描述 | 支持版本 |
+| :---: | :----------- | ---- | ------------------------------------------------------------ | ------------------ |
+| 20 | KECCAK256 | ○ | 国密类型的为SM3，非国密的不变 | |
+| 31 | BALANCE | ○ | 开启feature_balance后生效 | 3.6.0+ |
+| 34 | CALLVALUE | ○ | 开启feature_balance后生效 | 3.6.0+ |
+| 38 | CODESIZE | ○ | FISCO BCOS 的预编译合约返回 1以太坊原有的预编译合约返回 0 | 3.1.0+ | +| 39 | CODECOPY | - | | 3.2.4+
3.6.0+ | +| 3A | GASPRICE | ○ | 开启feature_balance_policy1后生效，在tx_gas_price系统配置项中配置 | 3.6.0+ | +| 3B | EXTCODESIZE | - | | 3.1.0+ | +| 3C | EXTCODECOPY | - | | 3.2.4+
3.6.0+ | +| 3F | EXTCODEHASH | - | | 3.1.0+ | +| 40 | BLOCKHASH | - | | 3.1.0+ | +| 41 | COINBASE | ● | 返回0 | | +| 42 | TIMESTAMP | ○ | 返回区块时间戳，单位为“毫秒”
（以太坊中单位为“秒”） | | +| 44 | PREVRANDAO | ● | 返回0 | | +| 45 | GASLIMIT | ○ | 通过系统合约配置，返回“单笔交易”的gas上限
（以太坊中是区块的gas上限） | | +| 46 | CHAINID | ● | 返回0 | | +| 47 | SELFBALANCE | ○ | 开启feature_balance后生效 | 3.6.0+ | +| 48 | BASEFEE | ● | 返回0 | | +| F2 | CALLCODE | - | | 3.1.0+ | +| F4 | DELEGATECALL | - | | 3.1.0+ | +| F5 | CREATE2 | ○ | 国密的计算根据SM3算法计算地址 | 3.2.4+
3.6.0+ | +| FA | STATICCALL | - | 历史版本与CALL相同，3.2.4和3.6.0开始支持 | 3.2.4+
3.6.0+ | +| FF | SELFDESTRUCT | ○ | 3.1.0+支持合约销毁
3.6.0+开启featrue_balance后支持销毁合约并回收balance | 3.6.0+ | + +## 附录：兼容等级划分 + +文章[《The different types of ZK-EVMs》](https://vitalik.eth.limo/general/2022/08/04/zkevm.html)中对以太坊的兼容性进行了等级划分 + +* Type 1：fully Ethereum-equivalent + * 完全兼容以太坊，包括RPC接口、EVM和EVM外的执行环境 +* Type 2：fully EVM-equivalent) + * 兼容EVM，EVM外的执行环境相同 +* Type 2.5：EVM-equivalent, except for gas costs + * 兼容EVM，但gas不同 +* Type 3：almost EVM-equivalent + * 采用EVM，但EVM外的执行环境存在差异，有自定义功能 +* Type 4：high-level-language equivalent + * 采用其他智能合约执行引擎 + + + diff --git a/3.x/zh_CN/docs/contract_develop/solidity_develop.md b/3.x/zh_CN/docs/contract_develop/solidity_develop.md new file mode 100644 index 000000000..f1cc492a6 --- /dev/null +++ b/3.x/zh_CN/docs/contract_develop/solidity_develop.md @@ -0,0 +1,25 @@ +# 1. Solidity合约开发 +标签： ``Solidity`` ``合约开发`` + +---- +FISCO BCOS 支持用以下几种方式实现智能合约 + +* [Solidity](https://solidity.readthedocs.io/en/latest/)：以太坊生态中采用的合约编程语言，FISCO BCOS为其拓展了面向联盟链的一系列功能，是FISCO BCOS上智能合约开发最常用的方式。 +* [预编译合约](./c++_contract/add_precompiled_impl.md)：在区块链节点内部直接内置定制化的智能合约，用c++语言实现，能直接调用节点内部各种接口，面向复杂场景，使用门槛较高。 +* [WBC-Liquid](./Liquid_develop.md)：微众区块链开发的基于Rust的智能合约编程语言，借助Rust语言特性，能够实现比Solidity语言更强大的编程功能。 + + + +FISCO BCOS上的Solidity语言的合约开发 + +- 基础的 + - 语法与以太坊相同，可参考[Solidity官方文档](https://solidity.readthedocs.io/en/latest/)进行学习。 + +- 面向联盟链拓展的 + - 编写Solidity代码，调用已[内置的合约接口](./c++_contract/use_precompiled.html#fisco-bcos-3-x)：CRUD合约、KVTable合约、群环签名、系统管理等 + + +```eval_rst +.. important:: + Solidity中有一些内置的密码学算法（如：keccak256/sha3等），当部署的FISCO BCOS区块为国密类型时，内置使用的是相应的国密算法（如：sm3等） +``` diff --git a/3.x/zh_CN/docs/design/amop_protocol.md b/3.x/zh_CN/docs/design/amop_protocol.md new file mode 100644 index 000000000..09f9288dc --- /dev/null +++ b/3.x/zh_CN/docs/design/amop_protocol.md @@ -0,0 +1,91 @@ +# 20. 链上信息传输协议AMOP + +标签：``AMOP`` ``链上信使`` ``私有话题`` ``认证流程`` + +---- +## 链上信使协议介绍 + +链上信使协议AMOP（Advanced Messages Onchain Protocol）系统旨在为联盟链提供一个安全高效的消息信道，联盟链中的各个机构，只要部署了区块链节点，无论是共识节点还是观察节点，均可使用AMOP进行通讯，AMOP有如下优势： +- 实时：AMOP消息不依赖区块链交易和共识，消息在节点间实时传输，延时在毫秒级。 +- 可靠：AMOP消息传输时，自动寻找区块链网络中所有可行的链路进行通讯，只要收发双方至少有一个链路可用，消息就保证可达。 +- 高效：AMOP消息结构简洁、处理逻辑高效，仅需少量cpu占用，能充分利用网络带宽。 +- 安全：AMOP的所有通讯链路使用SSL加密，加密算法可配置,支持身份认证机制。 +- 易用：使用AMOP时，无需在SDK做任何额外配置。 + +AMOP功能使用请参照[Java SDK AMOP](../sdk/java_sdk/amop.md). + +## 逻辑架构 + + +以银行典型IDC架构为例，各区域概述： + +- 链外区域：机构内部的业务服务区,此区域内的业务子系统使用区块链SDK，连接到区块链节点。 +- 区块链P2P网络：此区域部署各机构的区块链节点，此区域为逻辑区域，区块链节点也可部署在机构内部。 + + + +## 普通话题 + +AMOP的消息收发基于话题（Topic）订阅机制，订阅者首先订阅一个话题，发送者往该话题发送消息，订阅者即可收到。 + +**发送方式和内容** + +总共支持两种传播方式： + +* **单播**：仅随机发送给一个指定话题的订阅者。 +* **多播**：发送给所有指定话题的订阅者。 + +发送内容： + +* **文本消息** +* **文件** + + + +## 私有话题 + +在普通的配置下，任何一个订阅了某topic的接收者都能接受到发送者推送的消息。但在某些场景下，发送者只希望特定的接收者能接收到消息，不希望无关的接收者能任意的监听此topic。在此场景下，需要使用私有话题功能。 + +**私有话题**：对于特定的话题，发送者配置好期望的接受者的公钥，仅该公钥所对应的订阅者才能接收该私有话题的消息。 + +私有话题功能是自FISCO BCOS 2.1.0 之后新增的。使用过程如下： + +- 1：接收者使用[生成公私钥脚本](./account.md)生成公私钥文件，私钥保留，公钥给生产者。 +- 2：参考配置案例将配置文件配好。启动接收端和发送端进行收发消息。 + +```eval_rst +.. important:: + 注意：AMOP私有话题目前只支持非国密算法，因此生成在生成公私钥文件时，注意使用非国密工具生成。 +``` + +**私有话题的认证流程** + +假定链外系统1是话题消息发送者（消息发送端），链外系统2是话题订阅者（消息接收端）。私有话题的认证流程如下： + + + +- 1：链外系统2连接Node2,宣称订阅T1,Node2将T1加入到话题列表，并将seq加1。同时每5秒同步seq到其他节点。 +- 2：Node1收到seq之后，对比本地seq和同步过来的seq，发现不一致，则从Node2获取最新的话题列表，并将话题列表更新到p2p的话题列表，对于还没认证的私有话题，状态置为待认证。Node1遍历列表。针对每一个待认证的私有话题,进行如下操作： + - 2.1：Node1往Node1推送消息(消息类型0x37)，请求链外系统1发起私有话题认证流程。 + - 2.2：链外系统1接收到消息之后，生成随机数，并使用amop消息(消息类型0x30)将消息发送出去，并监听回包。 + - 2.3：消息经过 链外系统1-->Node1-->Node2-->链外系统2的路由，链外系统2接收到消息后解析出随机数并使用私钥签名随机数。 + - 2.4：签名包(消息类型0x31)经过 链外系统2-->Node2-->Node1->链外系统1的路由，链外系统1接收到签名包之后，解析出签名并使用公钥验证签名。 + - 2.5：链外系统1验证签名后，发送消息(消息类型0x38)，请求节点更新topic状态（认证成功或者认证失败）。 +- 3：如果认证成功，链外系统的一条消息到达Node1之后，Node1会将这条消息转发给Node2,Node2会将消息推送给链外系统2。 + + + +**发送方式和内容** + +同样的私有话题支持单播和多播，发送文本和文件。 + + + +## 错误码 + +- 99：发送消息失败，AMOP经由所有链路的尝试后，消息未能发到服务端，建议使用发送时生成的`seq`，检查链路上各个节点的处理情况。 +- 100：区块链节点之间经由所有链路的尝试后，消息未能发送到可以接收该消息的节点，和错误码‘99’一样，建议使用发送时生成的‘seq’，检查链路上各个节点的处理情况。 +- 101：区块链节点往Sdk推送消息，经由所有链路的尝试后，未能到达Sdk端，和错误码‘99’一样，建议使用发送时生成的‘seq’，检查链路上各个节点以及Sdk的处理情况。 +- 102：消息超时，建议检查服务端是否正确处理了消息，带宽是否足够。 +- 103：因节点出带宽限制，SDK发到节点的AMOP请求被拒绝。 + diff --git a/3.x/zh_CN/docs/design/architecture.md b/3.x/zh_CN/docs/design/architecture.md index 2899f1b64..290fedea5 100644 --- a/3.x/zh_CN/docs/design/architecture.md +++ b/3.x/zh_CN/docs/design/architecture.md @@ -1,4 +1,4 @@ -# 系统架构 +# 1. 系统架构 标签：``设计`` ``架构`` @@ -22,7 +22,7 @@ FISCO BCOS 3.x版本采用**微服务模块化**设计架构，总体上系统 *** -- **管理层**：管理层是为整个区块链系统各模块实现**可视化管理**的平台，包括部署、配置、日志、网络路由等管理功能。FISCO BCOS 3.x系统架构基于开源微服务框架Tars构建，这层的能力复用成熟的Tars-Framwork管理组件。 +- **管理层**：管理层是为整个区块链系统各模块实现**可视化管理**的平台，包括部署、配置、日志、网络路由等管理功能。FISCO BCOS 3.x系统架构基于开源微服务框架Tars构建，这层的能力复用成熟的Tars-Framework管理组件。  @@ -37,6 +37,6 @@ FISCO BCOS 3.x采用微服务架构，但同时也支持**灵活拆分组合** *** -- **大容量Max版**：由各个层的所有服务构成，每个服务都可独立扩展，存储采用分布式存储TiKV，管理采用Tars-Framwork服务。它适用于海量交易上链，需要支持大量数据落盘存储的场景。 +- **大容量Max版**：由各个层的所有服务构成，每个服务都可独立扩展，存储采用分布式存储TiKV，管理采用Tars-Framework服务。它适用于海量交易上链，需要支持大量数据落盘存储的场景。 - \ No newline at end of file + diff --git a/3.x/zh_CN/docs/design/boostssl.md b/3.x/zh_CN/docs/design/boostssl.md new file mode 100644 index 000000000..c099b1fa4 --- /dev/null +++ b/3.x/zh_CN/docs/design/boostssl.md @@ -0,0 +1,93 @@ +# 19. 公共网络组件BoostSSL + +标签： ``网络组件`` ``boostssl`` + +---- + +`boostssl`是`fisco-bcos`提供的一个公共网络组件，内置http、websocket两种协议，支持国密、非国密的SSL连接方式，在`FISCO-BCOS 3.0`多个模块中使用。 + +## 1. 目标 + +- 支持国密、非国密SSL连接 +- 支持HTTP协议 +- 支持WebSocket协议 +- 简单、易用的接口 + +## 2. 设计 + + + +## 3. 接口 + +待添加 + +## 4. 使用 + +**源码路径:** + +-
| name | string | No | PRI | 合约名称，name和version为联合主键 |
| version | string | No | 合约版本，name和version为联合主键 | |
| address | string | No | 合约地址 | |
| abi | string | YES | 合约abi | |
| _status_ | string | No | 分布式存储通用字段，“0”可用“1”删除 |
| 消息类型 | +字段名 | +字段含义 | +
| VoteReq | +candidate | +Candidate自身的节点索引 | +
| lastLeaderTerm | +Candidate见到过的最后一个Leader的Term，其详细作用见3.1.2节 | +|
| lastBlockNumber | +Candidate见到过的最新块的块高，其详细作用见3.1.2节 | +|
| VoteResp | +voteFlag | +对投票请求的响应标志位，用以标记对是否同意投票请求，若是拒绝还会具体标记拒绝原因，其详细作用见3.1.2节 | +
| lastLeaderTerm | +收到VoteReq的节点见到过的最新块的块高，其详细作用见3.1.2节 | +|
| Heartbeat | +leader | +发出心跳的Leader节点的节点索引 | +
| uncommitedBlock | +当Leader节点预备提交一个新块时，会先将区块数据编码进此字段以并通过心跳进行广播，其详细作用见3.2节 | +|
| uncommitedBlockNumber | +uncommitedBlock对应的块高，其详细作用见3.2节 | +|
| HeartbeatResp | +uncommitedBlockHash | +当收到Leader发送过来的uncommitedBlock数据时，节点在心跳响应中写入uncommitedBlock对应的哈希（指纹），并发送回Leader，表明节点已经收到Leader预备提交的区块数据且已写入本地缓存，其详细作用见3.2节 | +
并将解码出来的区块
写入缓存中 + Follower->>Leader: 发送ACK + loop 收集ACK + Leader->>Leader: 检查大多数节点是否已经收到区块拷贝 + end + Leader->>Sealer: 解除阻塞 + Leader->>Leader: 执行区块 + Leader->>Leader: 丢弃已经上链的交易 + +``` + +其中RaftSealer验证是否当前是否能打包交易的验证条件包括：(1) 是否为Leader；(2) 是否存在尚未完成同步的peer； (3) uncommitBlock字段是否为空，只有三个条件均符合才允许打包。 diff --git a/3.x/zh_CN/docs/design/consensus/rpbft.md b/3.x/zh_CN/docs/design/consensus/rpbft.md new file mode 100644 index 000000000..7a31da453 --- /dev/null +++ b/3.x/zh_CN/docs/design/consensus/rpbft.md @@ -0,0 +1,200 @@ +# rPBFT + +标签：``rPBFT`` ``共识算法`` + +---- +## 区块链共识困境 + +### POW类算法 + +POW算法因如下特点，不适用于交易吞吐量大、交易时延要求低的联盟链场景： +- 性能低：10分钟出一个区块，交易确认时延一个小时，耗电多 +- 无最终一致性保证 +- 吞吐量低 + +### 基于分布式一致性原理的共识算法 + +基于分布式一致性原理的共识算法，如BFT类和CFT类共识算法具有秒级交易确认时延、最终一致性、吞吐量高、不耗电等优势，尤其是BFT类共识算法还可应对节点作恶的场景，在性能、安全性等方面均可达到联盟链需求。 + +但这类算法复杂度均与节点规模有关，可支撑的网络规模有限，极大限制了联盟链节点规模。 + +综上所述，FISCO BCOS v2.3.0提出了rPBFT共识算法，旨在保留BFT类共识算法高性能、高吞吐量、高一致性、安全性的同时，尽量减少节点规模对共识算法的影响。 + +## rPBFT共识算法 + +### 节点类型 + +- 共识委员：执行PBFT共识流程的节点，有轮流出块权限 +- 验证节点：不执行共识流程，验证共识节点是否合法、区块验证，经过若干轮共识后，会切换为共识节点 + +### 核心思想 + + + +rPBFT算法每轮共识流程仅选取若干个共识节点出块，并根据区块高度周期性地替换共识节点，保障系统安全，主要包括2个系统参数： + +- `epoch_sealer_num`：每轮共识过程中参与共识的节点数目，可通过控制台发交易方式动态配置该参数 +- `epoch_block_num`: 共识节点替换周期，为防止选取的共识节点联合作恶，rPBFT每出epoch_block_num个区块，会替换一个共识节点，可通过控制台发交易的方式动态配置该参数 + +这两个配置项记录在系统配置表中，配置表主要包括配置关键字、配置对应的值、生效块高三个字段，其中生效块高记录了配置最新值最新生效块高，例：在100块发交易将`epoch_sealer_num`和`epoch_block_num`分别设置为4和10000，此时系统配置表如下： + +key | value | _enable_num_ | +:-: | :-: | :-: | +epoch_sealer_num | 4 | 101 | +epoch_block_num | 10000| 101 | + + +### 算法流程 + +#### **确定各共识节点编号IDX** + +对所有共识节点的NodeID进行排序，如下图，节点排序后的NodeID索引即为该共识节点编号： + + + +#### **链初始化** + +链初始化时，rPBFT需要选取`epoch_sealer_num`个共识节点到共识委员中参与共识，目前初步实现是选取索引为0到`epoch_sealer_num-1`的节点参与前`epoch_block_num`个区块共识。 + + +#### **共识委员节点运行PBFT共识算法** + +选取的`epoch_sealer_num`个共识委员节点运行PBFT共识算法，验证节点同步并验证这些共识委员节点共识产生的区块，验证节点的验证步骤包括： + +- 校验区块签名列表：每个区块必须至少包含三分之二共识委员的签名 +- 校验区块执行结果：本地区块执行结果须与共识委员在区块头记录的执行结果一致 + +#### **动态替换共识委员列表** + +为保障系统安全性，rPBFT算法每出`epoch_block_num`个区块后，会从共识委员列表中剔除一个节点作为验证节点，并加入一个验证节点到共识委员列表中，如下图所示： + + + +rPBFT算法目前实现中，轮流将共识委员列表节点替换为验证节点，设当前有序的共识委员会节点列表为`CommitteeSealersList`，共识节点总数为`N`，则共识`epoch_block_num`个区块后，会将`CommitteeSealersList[0]`剔除共识委员列表，并加入索引为`(CommitteeSealersList[0].IDX + epoch_sealer_num) % N`的验证节点到共识委员列表中。第`i`轮替换周期，将`CommitteeSealersList[i % epoch_sealer_num]`剔除共识委员列表，加入索引为`(CommitteeSealersList[i%epoch_sealer_num].IDX + epoch_sealer_num) % N`的验证节点到共识委员列表中。 + + +#### **节点重启** + +节点重启后，rPBFT算法需要快速确定共识委员列表，由于`epoch_block_num`可通过控制台动态更新，需要结合`epoch_block_num`最新配置生效块高获取共识委员列表，主要步骤如下： + +**计算共识周期rotatingRound** + + 设当前块高为`blockNum`，`epoch_block_num`生效块高为`enableNum`，则共识周期为: + `rotatingRound = (blockNumber - enableNum) / epoch_block_num` + +**确定共识委员起始节点索引**: `N`为共识节点总数，索引从`(rotatingRound * epoch_block_num) % N`到`(rotatingRound * epoch_block_num + epoch_sealer_num) % N`之间的节点均属于共识委员节点 + +### rPBFT算法分析 + +- 网络复杂度：O(epoch_sealer_num * epoch_sealer_num)，与节点规模无关，可扩展性强于PBFT共识算法 +- 性能：可秒级确认，且由于算法复杂度与节点数无关，性能衰减远小于PBFT +- 一致性、可用性要求：需要至少三分之二的共识委员节点正常工作，系统才可正常共识 +- 安全性：未来将引入VRF算法，随机、私密地替换共识委员，增强共识算法安全性 + + +## rPBFT网络优化 + +### Prepare包广播优化 + +为进一步提升Prepare包在带宽有限场景下广播效率，FISCO BCOS v2.3.0在rPBFT的基础上实现了Prepare包树状广播，如下图所示： + + + + +- 根据共识节点索引，构成完全n叉树(默认是3) +- Leader产生Prepare包后，沿着树状拓扑将Prepare包转发给其所有下属子节点 + +**优势**： +- 传播速度比gossip快，无冗余消息包 +- 分而治之，每个节点出带宽为O(1)，可扩展性强 + +**劣势**: 中间节点是单点，需要额外的容错策略 + + +### 基于状态包的容错方案 + +```eval_rst +.. note:: + + 基于状态包的容错策略仅在开启Prepare包树状广播时生效 +``` + +为保证节点断连情况下，开启树状广播时，Prepare包能到达每个节点，rPBFT引入了基于状态包的容错机制，如下图所示： + + + +主要流程包括： + +(1) 节点A收到Prepare后，随机选取33%节点广播Prepare包状态，记为prepareStatus，包括{blockNumber, blockHash, view, idx} + +(2) 节点B收到节点A随机广播过来的prepareStatus后，判断节点A的Prepare包状态是否比节点B当前Prepare包localPrepare状态新，主要判断包括： + +- prepareStatus.blockNumber是否大于当前块高 +- prepareStatus.blockNumber是否大于localPrepare.blockNumber +- prepareStatus.blockNumber等于localPrepare.blockNumber情况下，prepareStatus.view是否大于localPrepare.view + +以上任意一个条件成立，都说明节点A的Prepare包状态比节点B的状态新 + +(3) 若节点B的状态落后于节点A，且节点B与其父节点断连，则节点B向节点A发出prepareRequest请求，请求相应的Prepare包 + +(4) 若节点B的状态落后于节点A，但节点B与其父节点相连，若节点B最多等待[100ms(可配)](../../manual/configuration.html#rpbft)后，状态仍然落后于节点A，则节点B向节点A发出prepareRequest请求，请求相应的Prepare包 + +(5) 节点B收到节点A的prepareRequest请求后，向其回复相应的Prepare消息包 + +(6) 节点A收到节点B的Prepare消息包后，执行handlePrepare流程处理收到的Prepare包。 + + +### 流量负载均衡策略 + +```eval_rst +.. note:: + 流量负载均衡策略仅在开启Prepare包树状广播时生效 +``` + +rPBFT开启Prepare包结构优化后，其他共识节点交易缺失后，向leader请求交易，导致leader出带宽成为瓶颈，FISCO BCOS v2.3.0结合Prepare包状态，设计并实现了负载均衡策略，该策略时序图如下： + +```eval_rst +.. mermaid:: + + sequenceDiagram + participant leader + participant sealerA(父节点) + participant sealerB(子节点) + + leader->>sealerA(父节点): 发送Prepare + leader->>sealerA(父节点): 发送PrepareStatus + sealerA(父节点)->>sealerA(父节点): 更新Prepare状态缓存{leader, PrepareStatus} + sealerA(父节点)->>sealerB(子节点): 转发Prepare + sealerA(父节点)->>sealerA(父节点): 向leader请求并获取缺失交易，Prepare包加入缓存 + sealerA(父节点)->>sealerB(子节点): 发送PrepareStatus + sealerB(子节点)->>sealerB(子节点): 更新Prepare状态缓存{sealerA, PrepareStatus} + sealerB(子节点)->>sealerB(子节点): 向sealerA请求缺失并获取 + sealerB(子节点)->>leader: 发送PrepareStatus + + ``` + +**Leader的子节点sealerA的主要处理流程如下：** + +(1) leader产生新区块后，将仅包含交易哈希列表的Prepare包发送给三个子节点 + +(2) 子节点sealerA收到Prepare包后，将其沿树状拓扑转发给三个子节点 + +(3) 子节点sealerA开始处理Prepare包： + + - 从交易池中获取命中的交易，填充到Prepare包内的区块中 + - 向父节点Leader请求缺失的交易 + +(4) sealerA收到Leader的回包后，将回包内的交易填充到Prepare包内，并随机选取33%的节点广播Prepare包的状态，主要包括{blockNumber, blockHash, view, idx}，其他节点收到该状态包后，将sealerA最新状态包更新到缓存中 + +**sealerA的子节点sealerB的主要处理流程如下** + +(1) sealerB收到SealerA转发过来的Prepare包后，同样继续将该Prepare包转发给sealerB的子节点 + +(2) sealerB开始处理Prepare包，首先从交易池中获取命中的交易，填充到Prepare包的区块中，并选取节点获取缺失的交易： + - 若sealerB缓存来自节点sealerA的prepareStatus.blockHash等于Prepare.blockHash，则直接向父节点sealerA请求缺失交易 + - 若sealerB缓存的sealerA状态包哈希不等于Prepare.blockHash，但存在来自其他节点C的prepareStatus.blockHash等于prepare.blockHash，则向C请求缺失交易 + - 若sealerB缓存的任何节点prepareStatus的哈希均不但等于prepare.blockHash，最多等待[100ms(可配)](../../manual/configuration.html#rpbft)后，向Leader请求缺失的交易 + +(3) sealerB收到被请求节点回复的交易后，填充Prepare包内区块，并随机选取[33%(可配)](../../manual/configuration.html#rpbft)节点广播Prepare包状态 + +(4) 其他节点收到sealerB的状态包后，将其sealerB的最新状态包更新到缓存中 \ No newline at end of file diff --git a/3.x/zh_CN/docs/design/contract.md b/3.x/zh_CN/docs/design/contract.md index cb7548653..c12a928d1 100644 --- a/3.x/zh_CN/docs/design/contract.md +++ b/3.x/zh_CN/docs/design/contract.md @@ -8,17 +8,15 @@ 交易的执行是区块链节点上的一个重要的功能。交易的执行，是把交易中的智能合约二进制代码取出来，用执行器（Executor_）执行。共识模块（Consensus_）把交易从交易池(TxPool_)中取出，打包成区块，并调用执行器去执行区块中的交易。在交易的执行过程中，会对区块链的状态（State）进行修改，形成新区块的状态储存下来（Storage）。执行器在这个过程中，类似于一个黑盒，输入是智能合约代码，输出是状态的改变。 -随着技术的发展，人们开始关注执行器的性能和易用性。一方面，人们希望智能合约在区块链上能有更快的执行速度，满足大规模交易的需求。另一方面，人们希望能用更熟悉更好用的语言进行开发。进而出现了一些替代传统的执行器（EVM）的方案，如：JIT_、 WASM_甚至JVM。然而，传统的EVM是耦合在节点代码中的。首先要做的，是将执行器的接口抽象出来，兼容各种虚拟机的实现。因此，EVMC被设计出来。 +随着技术的发展，人们开始关注执行器的性能和易用性。一方面，人们希望智能合约在区块链上能有更快的执行速度，满足大规模交易的需求。另一方面，人们希望能用更熟悉更好用的语言进行开发。进而出现了一些替代传统的执行器（EVM）的方案，如：WASM。 +EVMC (Ethereum Client-VM Connector API)，是以太坊抽象出来的执行器的接口，旨在能够对接各种类型的执行器。 -EVMC (Ethereum Client-VM Connector API)，是以太坊抽象出来的执行器的接口，旨在能够对接各种类型的执行器。FISCO BCOS目前采用了以太坊的智能合约语言Solidity，因此也沿用了以太坊对执行器接口的抽象。 + - - -在节点上，共识模块会调用EVMC，将打包好的交易交由执行器执行。执行器执行时，对状态进行的读写，会通过EVMC的回调反过来操作节点上的状态数据。 - -经过EVMC一层的抽象，FISCO BCOS能够对接今后出现的更高效、易用性更强的执行器。目前，FISCO BCOS采用的是传统的EVM根据EVMC抽象出来的执行器---Interpreter。因此能够支持基于Solidity语言的智能合约。目前其他类型的执行器发展尚未成熟，后续将持续跟进。 +在节点上，共识模块会将打包好的区块交由执行器执行。虚拟机执行时，对状态进行的读写，会通过EVMC的回调反过来操作节点上的状态数据。 +经过EVMC的抽象，FISCO BCOS能够对接今后出现的更高效、易用性更强的执行器。目前，FISCO BCOS支持evm和wasm两种合约引擎，其中evmone作为evm的解释器，支持以Solidity为主的能编译为evm字节码的智能合约语言。wasm引擎使用wasmtime实现，支持能够编译为wasm的语言编写的合约，例如[liquid](https://liquid-doc.readthedocs.io/zh_CN/latest/index.html)，其他语言的工具链正在规划中。 .. toctree:: :maxdepth: 1 @@ -33,6 +31,4 @@ virtual_machine/gas.md .. _TxPool: ../architecture/transaction_stream.html -.. _JIT: https://github.com/ethereum/evmjit - -.. _WASM: https://webassembly.org/ \ No newline at end of file +.. _WASM: https://webassembly.org/ diff --git a/3.x/zh_CN/docs/design/contract_directory.md b/3.x/zh_CN/docs/design/contract_directory.md index b356df980..a857fe799 100644 --- a/3.x/zh_CN/docs/design/contract_directory.md +++ b/3.x/zh_CN/docs/design/contract_directory.md @@ -1,4 +1,4 @@ -# 区块链合约文件系统 +# 18. 合约文件系统BFS 标签：``合约目录``，``区块链文件系统``，``BFS`` @@ -85,11 +85,11 @@ FISCO BCOS 3.x版本引入区块链合约文件系统（Blockchain File System ### 1.2 详细使用文档 -BFS的使用体验主要集中体现在控制台，请参考控制台中BFS相关操作命令，以及使用控制台的BFS命令时的注意事项、错误出现情况请参考：[链接](../develop/console/console_commands.html#bfs)。 +BFS的使用体验主要集中体现在控制台，请参考控制台中BFS相关操作命令，以及使用控制台的BFS命令时的注意事项、错误出现情况请参考：[链接](../operation_and_maintenance/console/console_commands.html#bfs)。 -使用合约调用的BFS接口时的注意事项、错误出现情况请参考：[链接](../develop/precompiled/precompiled_contract_api.html#bfsprecompiled) 。 +使用合约调用的BFS接口时的注意事项、错误出现情况请参考：[链接](../contract_develop/c++_contract/precompiled_contract_api.html#bfsprecompiled) 。 -同时在部署合约和调用合约均支持BFS使用，请参考控制台中[deploy命令](../develop/console/console_commands.html#deploy)与[call命令](../develop/console/console_commands.html#call)。 +同时在部署合约和调用合约均支持BFS使用，请参考控制台中[deploy命令](../operation_and_maintenance/console/console_commands.html#deploy)与[call命令](../operation_and_maintenance/console/console_commands.html#call)。 ## 2. 设计文档 @@ -205,7 +205,7 @@ BFS存储表生命周期主要包括创建、修改、读取，暂时不支持 - **值得注意的是：** Solidity的地址由于其不可读的性质与BFS易读可见的原则相悖，因此Solidity部署后的合约地址只生成合约存储表，其BFS元数据不会写入 `/apps` 表内。例如：用户部署合约后地址为 0x123456，链上将会为合约创建合约存储表`/apps/123456`，但并不会将元数据写入到 `/apps` 内，即用户调用`list(/apps)`，不会显示子目录有`123456`这个资源。用户后续可以通过link操作，将solidity合约地址与BFS进行绑定。 - 在用户发起创建Table合约请求时，将会在 `/tables` 目录下创建对应的合约资源表，例如：创建Table合约 t_test合约时，将会创建 `/tables/t_test` 的存储表。 - 在执行合约时，将会读取合约资源对应的存储表中的状态数据。 -- 在部署普通合约是，将会创建合约的权限数据表，详情请参考：[权限底层节点设计](./committee_design.html#id15) +- 在部署普通合约时，将会创建合约的权限数据表，详情请参考：[权限底层节点设计](./committee_design.html#id15) #### 2.5.3 合约软链接资源生命周期 diff --git a/3.x/zh_CN/docs/design/guomi.md b/3.x/zh_CN/docs/design/guomi.md new file mode 100644 index 000000000..f78bfdc7a --- /dev/null +++ b/3.x/zh_CN/docs/design/guomi.md @@ -0,0 +1,49 @@ +# 12. 国密支持方案 + +标签：``国密算法`` ``SSL`` ``SM`` + +---- +## 设计目标 + + 为了充分支持国产密码学算法，金链盟基于[国产密码学标准](http://www.gmbz.org.cn/main/bzlb.html)，实现了国密加解密、签名、验签、哈希算法、国密SSL通信协议，并将其集成到FISCO BCOS平台中，实现了对**国家密码局认定的商用密码**的完全支持。 + +**国密版FISCO BCOS将交易签名验签、p2p网络连接、节点连接、数据落盘加密等底层模块的密码学算法均替换为国密算法**，国密版FISCO BCOS与标准版主要特性对比如下： + + | | 标准版FISCO BCOS | 国密版FISCO BCOS | + |:------------:|:--------------------:|:------------------:| + | SSL链接 | Openssl TLSv1.2协议 | 国密TLSv1.1协议 | + | 签名验证 | ECDSA签名算法 | SM2签名算法 | + | 消息摘要算法 | SHA-256 SHA-3 | SM3消息摘要算法 | + | 落盘加密算法 | AES-256加密算法 | SM4加密算法 | + | 证书模式 | OpenSSL证书模式 | 国密双证书模式 | + | 合约编译器 | 以太坊solidity编译器 | 国密solidity编译器 | + +(注：国密算法SM2, SM3, SM4均基于[国产密码学标准](http://www.gmbz.org.cn/main/bzlb.html)开发) + +## 系统框架 + +系统整体框架如下图所示： + + + +## 国密SSL 1.1 握手建立流程 + +国密版FISCO BCOS节点之间的认证选用国密SSL 1.1的ECDHE_SM4_SM3密码套件进行SSL链接的建立，差异如下表所示： + + | | OpenSSL | 国密SSL | + |:------------:|:----------------------------------------:|:----------------------------------------:| + | 加密套件 | 采用ECDH、RSA、SHA-256、AES256等密码算法 | 采用国密算法 | + | PRF算法 | SHA-256 | SM3 | + | 密钥交换方式 | 传输椭圆曲线参数以及当前报文的签名 | 当前报文的签名和加密证书 | + | 证书模式 | OpenSSL证书模式 | 国密双证书模式，分别为加密证书和签名证书 | + +## 数据结构差异 + +国密版与标准版FISCO BCOS在数据结构上的差异如下： + + | 算法类型 | 标准版FISCO BCOS | 国密版FISCO BCOS | + |:----------:|:----------------------------------------------:|:--------------------------------------------------:| + | 签名 | ECDSA (公钥长度: 512 bits, 私钥长度: 256 bits) | SM2 (公钥长度：512 bits, 私钥长度：256 bits) | + | 哈希 | SHA3 (哈希串长度: 256 bits) | SM3 (哈希串长度: 256 bits) | + | 对称加解密 | AES (加密秘钥长度: 256 bits) | SM4 (对称密钥长度: 128 bits) | + | 交易长度 | 520bits(其中标识符8bits,签名长度512bits) | 1024bits(128字节，其中公钥512bits,签名长度512bits) | diff --git a/3.x/zh_CN/docs/design/hsm.md b/3.x/zh_CN/docs/design/hsm.md new file mode 100644 index 000000000..89afc1a3a --- /dev/null +++ b/3.x/zh_CN/docs/design/hsm.md @@ -0,0 +1,29 @@ +# 15. 硬件密码机 + +标签：``硬件加密`` ``HSM`` ``密码机`` + +----- + +## 一、密码机与GMT0018简介 + +### 密码机HSM + +硬件安全模块（Hardware security module，HSM）是一种用于保障和管理强认证系统所使用的数字密钥，并同时提供相关密码学操作的计算机硬件设备。硬件安全模块一般通过扩展卡或外部设备的形式直接连接到电脑或网络服务器。 + +### GMT0018 + +《GMT0018-2012 密码设备应用接口规范》是由国家密码管理局发布的，符合中国密码行业标准的一个密码设备应用接口规范。它为公钥密码基础设施应用体系框架下的服务类密码设备制定统一的应用接口标准，通过该接口调用密码设备，向上层提供基础密码服务。为该类密码设备的开发、使用及检测提供标准依据和指导，有利于提高该类密码设备的产品化、标准化和系列化水平。 + +FISCO BCOS 2.8.0和FISCO BCOS 3.3.0版本引入了密码机功能。用户可以将密码放入密码机，通过密码机进行**共识签名**、**交易验签**。FISCO BCOS支持《GMT0018-2012 密码设备应用接口规范》的密码卡/密码机，支持SDF标准，这使得FISCO BCOS拥有更快的密码计算速度，更安全的密钥保护。 + +## 二、调用密码机的模块 + +FISCO BCOS的共识和交易模块调用了密码机。 +共识、交易模块在签名时，调用`bcos-crypto`模块，`bcos-crypto`再调用`hsm-crypto`模块，最终调用到密码机API接口完成签名。其中涉及到的参数还有通过配置文件传入的密码机内置密钥索引keyIndex，最终调用密码机签名接口`SDF_InternalSign_ECC`。 +交易模块在验签时，同理调用`bcos-crypto`模块，`bcos-crypto`再调用`hsm-crypto`模块，最终调用到密码机API接口完成签名。最终调用密码机验签接口`SDF_ExternalVerify_ECC`。 + +### hsm-crypto模块 + +hsm-crypto是个封装密码机API接口，使用C++实现的硬件加密模块（Hardware secure module），它能协助应用调用符合《GMT0018-2012密码设备通用接口规范》的PCI密码卡或者密码机进行国密算法SM2、SM3、SM4运算。FISCO BCOS节点，以及java-sdk都通过调用该模块，调用密码机API接口。[Github项目地址](https://github.com/WeBankBlockchain/hsm-crypto) + +至此，硬件密码机HSM的设计文档到此结束，关于FISCO BCOS和java-sdk如何使用密码机，请参考[构建使用硬件密码模块的国密链](../tutorial/air/use_hsm.md) diff --git a/3.x/zh_CN/docs/design/index.md b/3.x/zh_CN/docs/design/index.md index e36342219..13dff270d 100644 --- a/3.x/zh_CN/docs/design/index.md +++ b/3.x/zh_CN/docs/design/index.md @@ -38,11 +38,19 @@ ___ sync.md storage/storage.md DMC.md - contract_directory.md virtual_machine/index.rst committee_design.md storage/storage_security.md storage/archive.md + guomi.md + rip.md + network_compress.md + security_control/index.rst + hsm.md + cns_contract_name_service.md + contract_directory.md + boostssl.md + amop_protocol.md p2p.md compatibility.md ``` diff --git a/3.x/zh_CN/docs/design/network_compress.md b/3.x/zh_CN/docs/design/network_compress.md index 1bedeeeb6..74dafd975 100644 --- a/3.x/zh_CN/docs/design/network_compress.md +++ b/3.x/zh_CN/docs/design/network_compress.md @@ -1,11 +1,10 @@ -# 网络压缩 +# 13. 网络包压缩 标签：``p2p网络压缩`` ``数据压缩`` ---- -外网环境下，区块链系统性能受限于网络带宽，为了尽量减少网络带宽对系统性能的影响，FISCO BCOS 3.0在`relase-3.1`支持p2p网络压缩功能，该功能主要在发送端进行p2p网络数据包压缩，在接收端将解包数据，并将解包后的数据传递给上层模块。该p2p网络压缩功能默认开启，无需通过配置项控制。 - +外网环境下，区块链系统性能受限于网络带宽，为了尽量减少网络带宽对系统性能的影响，FISCO BCOS 3.0在`v3.1.0`支持p2p网络压缩功能，该功能主要在发送端进行p2p网络数据包压缩，在接收端将解包数据，并将解包后的数据传递给上层模块。该p2p网络压缩功能默认开启，无需通过配置项控制。 ## 系统框架 @@ -15,16 +14,14 @@ 网络压缩主要包括两个过程： -- **发送端压缩数据包**：群组层通过P2P层发送数据时，若数据包大小超过1KB，而且接收端节点是3.1及之后的版本，则压缩数据包后，更新标记位`ext`，编码后，将其发送到目标节点； +- **发送端压缩数据包**：群组层通过P2P层发送数据时，若数据包大小超过1KB，而且接收端节点是3.1.0及之后的版本，则压缩数据包后，更新标记位`ext`，编码后，将其发送到目标节点； - **接收端解压数据包**：节点收到数据包后，解码，根据标记位`ext`判断收到的数据包是否被压缩，若数据包是压缩后的数据包，则将其解压，重置ext标记位。 - ## 核心实现 综合考虑性能、压缩效率等，我们选取了[Zstd](https://github.com/facebook/zstd)来实现数据包压缩和解压功能。本节主要介绍网络压缩的实现。 - ### 数据压缩标记位 FISCO BCOS的网络数据包结构如下图： @@ -59,14 +56,13 @@ FISCO BCOS的网络数据包结构如下图： - 编码模块给packet加上包头，同时更新压缩标记位`ext`。即：若packet是压缩后的数据包，将`ext |= 0x0010`； - P2P将编码后的数据包传送到目的节点。 -**接收端处理流程：** +**接收端处理流程** - 目标机器收到数据包后，解码模块分离出包头，通过判断包头ext字段，即`m_ext & 0x0010 == 0x0010`判断网络数据是否被压缩； - 若网络数据包被压缩过，则调用解压接口，对payload数据进行解压； - reset重置ext标记位，即`m_ext &= ~0x0010`，防止同个数据包被多次解压。 - ## 兼容性说明 - **数据兼容**：不涉及存储数据的变更； -- **网络兼容rc1**：向前兼容，仅有relase-3.1及以上节点具有网络压缩功能。 \ No newline at end of file +- **网络兼容rc1**：向前兼容，仅有relase-3.1及以上节点具有网络压缩功能。 diff --git a/3.x/zh_CN/docs/design/DMC.md b/3.x/zh_CN/docs/design/parallel/DMC.md similarity index 96% rename from 3.x/zh_CN/docs/design/DMC.md rename to 3.x/zh_CN/docs/design/parallel/DMC.md index 7c0882904..8ee63f62c 100644 --- a/3.x/zh_CN/docs/design/DMC.md +++ b/3.x/zh_CN/docs/design/parallel/DMC.md @@ -1,11 +1,9 @@ -# 确定性多合约并行 +# DMC确定性多合约并行 标签：``执行`` ``并行调度`` ``DMC`` ``确定性并行合约`` ---------- -本文档用于描述**确定性多合约并行**。 - ## 1、背景 如今多核已经逐渐成为当今 CPU 的主流，未来 CPU 可能集成更多的核，进入众核时代。 @@ -43,22 +41,22 @@ DMC 方案中，调用同一个合约的多个交易在全局视角中总是串 - 如果目的合约字段成功放入哈希表，说明该消息调用的目的合约是首次执行，DMC 调度器将该消息异步发送至任意交易执行器来执行该消息; - 如果目的合约字段放入哈希表时发生冲突，说明该消息调用的目的合约已经有更早的消息调用过，DMC 调度器将该消息移动至下一阶段（阶段2）; - + **阶段2** - DMC 调度器遍历阶段1的消息，发现消息2与消息1调用了同一合约，消息3与消息5调用了同一合约，消息4与消息6调用了同一合约，DMC 调度器将首次调用合约的消息（消息1、消息3、消息4）异步发送给多个交易执行器来执行，其它（消息2、消息5、消息6）移动到下一阶段。 - 消息1、消息3和消息4，由于它们分别调用不同的合约，因此多个交易执行器可以并行执行这3个消息，DMC 调度器会等待消息1、3、4执行完成。 - + **阶段3** - 交易执行器在执行消息的过程中，如果消息对应的智能合约内部发生跨合约调用，交易执行器会中止当前消息的执行，保存消息执行的上下文，生成新的跨合约调用消息，新消息内包含前述保存的上下文，交易执行器将跨合约调用的新消息发送给 DMC 调度器。 - DMC 调度器将来自交易执行器的跨合约调用消息移动到下一阶段。 - 假如DMC 调度器在阶段2执行过程中，交易执行器执行消息2时，消息调用的智能合约发起了跨合约调用，跨合约调用的目的合约是3，则该交易执行器暂停执行消息2的执行，保存消息2的上下文，生成一个新的跨合约调用消息2’，交易执行器将跨合约调用的消息2’发送给 DMC 调度器。DMC 调度器将消息2’放到阶段3，后续 DMC 调度器在阶段3将该消息下发给其它交易执行器。 - + **阶段4** - 交易执行器将消息执行结束后，如果消息内包含上下文，相当于跨合约调用返回，交易执行器会根据消息内上下文，还原该上下文，生成新消息，并将当前消息执行的结果作为跨合约调用返回值放到新消息的参数中，将跨合约调用返回的新消息发送给 DMC 调度器。 - + - DMC 调度器将来自交易执行器的跨合约调用消息移动到下一阶段。 - DMC 调度器如果发现下一阶段非空，会将当前阶段设置为下一阶段并重复初始步骤，依次类推，直到所有交易都执行完成为止。 \ No newline at end of file diff --git a/3.x/zh_CN/docs/design/parallel/dag.md b/3.x/zh_CN/docs/design/parallel/dag.md new file mode 100644 index 000000000..b7d369cb5 --- /dev/null +++ b/3.x/zh_CN/docs/design/parallel/dag.md @@ -0,0 +1,73 @@ +# DAG交易并行 + +标签：``交易并行`` ``DAG`` + +---- + +## 1 名词解释 + +### 1.1 DAG + +一个无环的有向图称做有向无环图（**D**irected **A**cyclic **G**raph），简称DAG图。在一批交易中，可以通过一定方法识别出每笔交易需要占用的互斥资源，再根据交易在Block中的顺序及互斥资源的占用关系构造出一个交易依赖DAG图，如下图所示，凡是入度为0（无被依赖的前序任务）的交易均可以并行执行。如下图所示，基于左图的原始交易列表的顺序进行拓扑排序后，可以得到右图的交易DAG。 + + + +## 2 模块架构 + + +其中主要流程包括： + +- 用户直接或间接通过SDK发起交易。交易可以是能够并行执行的交易和不能并行执行的交易； +- 交易进入节点的交易池中，等待打包； +- 交易被Sealer打包为区块，经过共识后，发送至BlockVerifier进行验证； +- BlockVerifier根据区块中的交易列表生成交易DAG； +- BlockVerifier构造执行上下文，并行执行交易DAG； +- 区块验证通过后，区块上链。 + +## 3 重要流程 + +### 3.1 交易DAG构建 + +#### 3.1.1 DAG数据结构 + +方案中所用到的DAG数据结构如下： + +其中： +- 顶点（Vertex） + - inDegree用于存储顶点当前的入度; + - outEdge用于保存该顶点的出边信息，具体为所有出边所连顶点的ID列表。 +- DAG： + - vtxs是用于存储DAG中所有节点的列表； + - topLevel是一个并发队列，用于存储当前入度为0的节点ID，执行时供多个线程并发访问； + - totalVtxs：顶点总数 + - totalConsume：已经执行过的顶点总数； + - void init(uint32_t \_maxSize)：初始化一个最大顶点数为maxSize的DAG； + - void addEdge(ID from, ID to)：在顶点from和to之间建立一条有向边； + - void generate()：根据已有的边和顶点构造出一个DAG结构； + - ID waitPop(bool needWait)：等待从topLevel中取出一个入度为0的节点； + - void clear()：清除DAG中所有的节点与边信息。 +- TxDAG: + - dag：DAG实例 + - exeCnt：已经执行过的交易计数； + - totalParaTxs：并行交易总数； + - txs：并行交易列表 + - bool hasFinished()：若整个DAG已经执行完毕，返回true，否则返回false; + - void executeUnit()：取出一个没有上层依赖的交易并执行； +#### 3.1.2 交易DAG构造流程 + +流程如下： + + + +1. 从打包好的区块从取出区块中的所有交易； +2. 将交易数量作为最大顶点数量初始化一个DAG实例； +3. 按序读出所有交易，如果一笔交易是可并行交易，则解析其冲突域，并检查是否有之前的交易与该交易冲突，如果有，则在相应交易间构造依赖边；若该交易不可并行，则认为其必须在前序的所有交易都执行完后才能执行，因此在该交易与其所有前序交易间建立一条依赖边。 + +### 3.2 DAG执行流程 + +流程如下： + + + +1. 主线程会首先根据硬件核数初始化一个相应大小的线程组，若获取硬件核数失败，则不创建其他线程； +2. 当DAG尚未执行完毕时，线程循环等待从DAG中pop出入度为0的交易。若成功取出待执行的交易，则执行该交易，执行完后将后续的依赖任务的入度减1，若有交易入度被减至0，则将该交易加入topLevel中；若失败，则表示DAG已经执行完毕，线程退出。 \ No newline at end of file diff --git a/3.x/zh_CN/docs/design/parallel/group.md b/3.x/zh_CN/docs/design/parallel/group.md new file mode 100644 index 000000000..1221243a6 --- /dev/null +++ b/3.x/zh_CN/docs/design/parallel/group.md @@ -0,0 +1,58 @@ +# 群组架构 + +标签：``群组架构`` ``架构`` + +---- + +考虑到真实的业务场景需求，FISCO BCOS引入多群组架构，支持区块链节点启动多个群组，群组间交易处理、数据存储、区块共识相互隔离，保障区块链系统隐私性的同时，降低了系统的运维复杂度。不同群组间的交易可并行执行，提升了性能。 + + +```eval_rst +.. note:: + + 举个例子: + + 机构A、B、C所有节点构成一个区块链网络，运行业务1；一段时间后，机构A、B启动业务2，且不希望该业务相关数据、交易处理被机构C感知，有何解？ + + - **1.3系列FISCO BCOS系统** ：机构A和机构B重新搭一条链运行业务2；运维管理员需要运维两条链，维护两套端口 + + - **FISCO BCOS 2.0+** ：机构A和机构B新建一个群组运行业务2；运维管理员仅需维护一条链 + + 显然在达到相同隐私保护需求基础上，FISCO BCOS 2.0+具有更好的扩展性、可运维性和灵活性。 +``` + +多群组架构中，群组间共享网络，通过[网络准入和账本白名单](../security_control/node_management.md)实现各账本间网络消息隔离。 + + + + +群组间数据隔离，每个群组独立运行各自的共识算法，不同群组可使用不同的共识算法。每个账本模块自底向上主要包括核心层、接口层和调度层三层，这三层相互协作，FISCO BCOS可保证单个群组独立健壮地运行。 + +## 核心层 + +核心层负责将群组的[区块](../../tutorial/key_concepts.html#id3)数据、区块信息、系统表以及区块执行结果写入底层数据库。 + +存储分为世界状态(State)和分布式存储(AMDB)两部分，世界状态包括MPTState和StorageState，负责存储交易执行的状态信息，StorageState性能高于MPTState，但不存储区块历史信息；AMDB则向外暴露简单的查询(select)、提交(commit)和更新(update)接口，负责操作合约表、系统表和用户表，具有可插拔特性，后端可支持多种数据库类型，目前支持[RocksDB数据库](https://github.com/facebook/rocksdb)和MySQL[storage](../storage/storage.md)。 + + + + +## 接口层 + +接口层包括交易池(TxPool)、区块链(BlockChain)和区块执行器(BlockVerifier)三个模块。 + +- **交易池(TxPool)**: 与网络层以及调度层交互，负责缓存客户端或者其他节点广播的交易，调度层(主要是同步和共识模块)从交易池中取出交易进行广播或者区块打包； + +- **区块链(BlockChain)**: 与核心层和调度层交互，是调度层访问底层存储的唯一入口，调度层(同步、共识模块)可通过区块链接口查询块高、获取指定区块、提交区块； + +- **区块执行器(BlockVerifier)**: 与调度层交互，负责执行从调度层传入的区块，并将区块执行结果返回给调度层。 + + +## 调度层 + +调度层包括共识模块(Consensus)和同步模块(Sync)。 + +- **共识模块**：包括Sealer线程和Engine线程，分别负责打包交易、执行共识流程。Sealer线程从交易池(TxPool)取交易，并打包成新区块；Engine线程执行共识流程，共识过程会执行区块，共识成功后，将区块以及区块执行结果提交到区块链(BlockChain)，区块链统一将这些信息写入底层存储，并触发交易池删除上链区块中包含的所有交易、将交易执行结果以回调的形式通知客户端，目前FISCO BCOS主要支持[PBFT](../consensus/pbft.md)和[Raft](../storage/storage.md)共识算法； + +- **同步模块**：负责广播交易和获取最新区块， +考虑到共识过程中，[leader](../consensus/pbft.html#id1)负责打包区块，而leader随时有可能切换，因此必须保证客户端的交易尽可能发送到每个区块链节点，节点收到新交易后，同步模块将这些新交易广播给所有其他节点；考虑到区块链网络中机器性能不一致或者新节点加入都会导致部分节点区块高度落后于其他节点，同步模块提供了区块同步功能，该模块向其他节点发送自己节点的最新块高，其他节点发现块高落后于其他节点后，会主动下载最新区块。 \ No newline at end of file diff --git a/3.x/zh_CN/docs/design/parallel/index.md b/3.x/zh_CN/docs/design/parallel/index.md new file mode 100644 index 000000000..9e68ea4a9 --- /dev/null +++ b/3.x/zh_CN/docs/design/parallel/index.md @@ -0,0 +1,33 @@ +# 7. 全方位并行 + +标签：``执行`` ``并行调度`` ``DMC`` ``DAG`` + +---------- + +FISCO BCOS为提升交易处理性能，进行了全方位的并行处理设计。按照**并行粒度**从细到粗的划分，其并行机制可分为： + +* **交易**的并行：DAG交易并行、读写集并行 + +* **合约**的并行：DMC、块内分片 + +* **区块**的并行：区块DAG（设计中） + +* **链**的并行：群组架构 + +* **链服务**的并行：多链跨链 + +---------- + + + +```eval_rst +.. toctree:: + :maxdepth: 1 + + dag.md + rwset.md + DMC.md + sharding.md + group.md + multichain.md +``` \ No newline at end of file diff --git a/3.x/zh_CN/docs/design/parallel/multichain.md b/3.x/zh_CN/docs/design/parallel/multichain.md new file mode 100644 index 000000000..6cc3bec9d --- /dev/null +++ b/3.x/zh_CN/docs/design/parallel/multichain.md @@ -0,0 +1,5 @@ +# 多链跨链 +FISCO BCOS 通过多了跨链的方案与其他类型的区块链进行并行处理。方案包括： + +* [WeCross](https://github.com/WeBankFinTech/WeCross) +* [陆羽跨链协议](https://gitee.com/luyu-community/luyu-cross-chain-protocol) diff --git a/3.x/zh_CN/docs/design/parallel/rwset.md b/3.x/zh_CN/docs/design/parallel/rwset.md new file mode 100644 index 000000000..95f0970d0 --- /dev/null +++ b/3.x/zh_CN/docs/design/parallel/rwset.md @@ -0,0 +1,2 @@ +# 读写集并行 +（该方案在开发中，将于3.4.0版本发布，敬请期待） diff --git a/3.x/zh_CN/docs/design/parallel/sharding.md b/3.x/zh_CN/docs/design/parallel/sharding.md new file mode 100644 index 000000000..2312fba98 --- /dev/null +++ b/3.x/zh_CN/docs/design/parallel/sharding.md @@ -0,0 +1,145 @@ +# 块内分片 +标签: ``sharding`` ``分片`` ``交易执行`` + +------- + +## 概念 + +当一条区块链上承载了多个应用时，可采用“**块内分片**”技术实现应用间交易执行的并行化。 + +FISCO BCOS支持中对链上的合约进行分组。在执行一个区块内的交易时，一个区块内的交易会根据合约的分组情况拆分成多个“**块内分片**”下文简称：分片），相同分片的交易调度到同一个执行器中执行。 + +## 方案 + +**关键点** + +* 并行：一个区块内的不同分片调度至不同的执行器中并行执行。 +* 局部：分片内部合约的相互调用直接在同一个执行器中完成，分片间互不干扰。 +* 跨分片：跨分片调用直接在一个区块内完成，对用户透明无感，其调度基于DMC机制，避免繁重的SPV证明。 +* 配置：用户可用控制台管理合约所属的分片 +* 继承：分片内合约部署的合约属于相同的分片，消除繁琐的分片管理操作。 + +## 实现 + +实现方法如下： + +* 并行：基于[FISCO BCOS的架构](../architecture.md)实现多executor的调度。 +* 局部：一个executor内部，采用[DAG的方式并行执行](./dag.md)。 +* 跨分片：跨分片的交易采用[DMC机制进行调度](./dmc.md)，在一个区块内完成的同时，保证一致性与存在性。 +* 配置：基于[BFS](../contract_directory.md)实现合约的分片管理，启动控制台，用linkShard命令可绑定合约至分片，用 ls 命令查看分片信息。 +* 继承：分片内合约部署的合约自动继承所属分片配置 + +## 举例 + +分片1：`/shard/hello_shard` + +``` +/shard/hello_shard/hello1 +/shard/hello_shard/hello2 +/shard/hello_shard/hello3 +``` + +分片2：`/shard/account_shard` + +``` +/shard/account_shard/alice +/shard/account_shard/bob +/shard/account_shard/charies +``` + + + + + + + +## 操作举例 + +该操作需要使用控制台，请参考[此处](../../operation_and_maintenance/console/console_config.md)部署控制台。分片管理操作请参考此处。 + +**部署合约** + +> 部署两个合约：Asset、HelloWorld + +``` +[group0]: /apps> deploy Asset +transaction hash: 0x8dbee4602da3d3435ce73df3778ee975b650cfaf70ce6b53f14db6db478cec10 +contract address: 0xcceef68c9b4811b32c75df284a1396c7c5509561 +currentAccount: 0x988e6a553f434be3d37786c97abb1fe1f8b7341d + +[group0]: /apps> deploy HelloWorld +transaction hash: 0xcb860822f8d74ac447fc3d18870109a202ff788a6b1ef32970fa53497ba386d5 +contract address: 0xd24180cc0fef2f3e545de4f9aafc09345cd08903 +currentAccount: 0x988e6a553f434be3d37786c97abb1fe1f8b7341d +``` + +**创建分片** + +> 创建两个分片：account_shard 和 hello_shard + +``` +[group0]: /apps> makeShard account_shard +make shard account_shard Ok. You can use 'ls' to check + +[group0]: /apps> makeShard hello_shard +make shard hello_shard Ok. You can use 'ls' to check + +[group0]: /apps> ls /shards/ +account_shard hello_shard +``` + +**合约绑定分片** + +> 分别将上述的两个合约绑定到不同的shard + +``` +[group0]: /apps> linkShard 0xcceef68c9b4811b32c75df284a1396c7c5509561 account_shard +Add 0xcceef68c9b4811b32c75df284a1396c7c5509561 to account_shard Ok. You can use 'ls' to check + +[group0]: /apps> linkShard 0xd24180cc0fef2f3e545de4f9aafc09345cd08903 hello_shard +Add 0xd24180cc0fef2f3e545de4f9aafc09345cd08903 to hello_shard Ok. You can use 'ls' to check +``` + +**查询分片信息** + +> 用getContractShard命令查看合约已经绑定至特定的shard + +``` +[group0]: /apps> getContractShard 0xcceef68c9b4811b32c75df284a1396c7c5509561 +/shards/account_shard + +[group0]: /apps> getContractShard d24180cc0fef2f3e545de4f9aafc09345cd08903 +/shards/hello_shard +``` + +> BFS的ls命令也可以查询 + +``` +[group0]: /apps> ls /shards/account_shard/ +cceef68c9b4811b32c75df284a1396c7c5509561 + +[group0]: /apps> ls /shards/hello_shard/ +d24180cc0fef2f3e545de4f9aafc09345cd08903 +``` + +**调用shard内的合约** + +> 交易会自动调度至相应的shard中执行，不同的shard在不同的执行器中执行，该操作对用户透明，体验上与调用普通合约无区别 + +``` +[group0]: /apps> call HelloWorld 0xd24180cc0fef2f3e545de4f9aafc09345cd08903 set nice +transaction hash: 0x41637d8eb5907e84fd2bda6303d444bb7b3b9fe8cd85750dc547139710439b6e +--------------------------------------------------------------------------------------------- +transaction status: 0 +description: transaction executed successfully +--------------------------------------------------------------------------------------------- +Receipt message: Success +Return message: Success +Return value size:0 +Return types: () +Return values:() +--------------------------------------------------------------------------------------------- +Event logs +Event: {} +``` + diff --git a/3.x/zh_CN/docs/design/protocol_description.md b/3.x/zh_CN/docs/design/protocol_description.md index 4a5e869cb..ee2377f05 100644 --- a/3.x/zh_CN/docs/design/protocol_description.md +++ b/3.x/zh_CN/docs/design/protocol_description.md @@ -1,4 +1,4 @@ -# 数据结构的编码协议 +# 3. 核心数据结构 标签：``数据结构`` ``编码`` @@ -6,19 +6,20 @@ ```eval_rst .. note:: - FISCO BCOS 3.x数据和编码协议的实现位于仓库 `bcos-tars-protocol
| 划分维度 | +配置类型 | +|
| 影响范围 | +网络配置 | 全局性质的配置，节点的配置影响该节点所在的整个网络，节点对整个网络使用同一份配置， 文件名为config.* |
+
| 群组配置 | 节点的配置影响该节点所在的单个群组，每个群组各有一份配置， 文件名为group.X.*，其中X为群组号 |
+|
| 是否可改 | 固定配置 | 只使用首次配置内容，后续对配置的修改无效， 文件后缀为.genesis |
+
| 可改配置 | 配置后续可改动，节点重启生效， 文件后缀为.ini |
+|
| 存放位置 | 本地存储 | 配置存放在本地文件，用户可直接修改， 用户修改自身文件能重启生效的配置项 |
+
| 链上存储 | 配置存放在区块链上，对其修改需群组共识，目前没有需全网共识的内容， 需新链重置或通过交易修改生效的配置项 |
+
| P2P节点连接列表 | 记录本节点期望与哪些节点建立网络通信 | 网络配置 | 可改配置 | 本地存储 | +
| 节点证书 | 证明自己是由可信第三方许可的节点 | 网络配置 | 可改配置 | 本地存储 | +
| CA黑名单 | 记录本节点禁止与哪些节点建立网络通信 | 网络配置 | 可改配置 | 本地存储 | +
| 群组节点初始列表 | 记录创世块阶段参与共识/同步的节点列表 | 群组配置 | 固定配置 | 本地存储 | +
| 群组节点系统表 | 记录当前参与一群组共识/同步的节点列表 | 群组配置 | 可改配置 | 链上存储 | +
| name | string | No | PRI | 各行同一值，分布式存储基于此key实现全表查询 |
| type | string | No | 节点类型（sealer/observer） | |
| node_id | string | No | 节点NodeID | |
| enable_num | string | No | 该节点类型生效的区块高度 | |
| _status_ | string | No | 分布式存储通用字段，“0”可用“1”删除 |
-
+
## 交易生成
用户的请求给到客户端后，客户端会构建出一笔有效交易，交易中包括以下关键信息：
-1. 发送地址：即用户自己的账户，用于表明交易来自何处。
-2. 接收地址：FISCO BCOS中的交易分为两类，一类是部署合约的交易，一类是调用合约的交易。前者，由于交易并没有特定的接收对象，因此规定这类交易的接收地址固定为0x0；后者，则需要将交易的接收地址置为链上合约的地址。
-3. 交易相关的数据：一笔交易往往需要一些用户提供的输入来执行用户期望的操作，这些输入会以二进制的形式被编码到交易中。
-4. 交易签名：为了表明交易确实是由自己发送，用户会向SDK提供私钥来让客户端对交易进行签名，其中私钥和用户账户是一一对应的关系。
+1. 接收地址：FISCO BCOS中的交易分为两类，一类是部署合约的交易，一类是调用合约的交易。前者，由于交易并没有特定的接收对象，因此规定这类交易的接收地址固定为空；后者，则需要将交易的接收地址置为链上合约的地址。
+1. 交易相关的数据：一笔交易往往需要一些用户提供的输入来执行用户期望的操作，这些输入会以二进制的形式被编码到交易中。
+1. 交易签名：为了表明交易确实是由自己发送，用户会向SDK提供私钥来让客户端对交易进行签名，其中私钥和用户账户是一一对应的关系。
之后，区块链客户端会再向交易填充一些必要的字段，如用于防交易重放的交易ID及blockLimit。交易的具体结构和字段含义可以参考[编码协议文档](./protocol_description.md)，交易构造完成后，客户端随后便通过RPC信道将交易发送给节点。
-
+
## 交易池
区块链交易被发送到节点后，节点会通过验证交易签名的方式来验证一笔交易是否合法。若一笔交易合法，则节点会进一步检查该交易是否重复出现过，若从未出现过，则将交易加入交易池缓存起来。若交易不合法或交易重复出现，则将直接丢弃交易。
-
+
## 交易广播
@@ -35,15 +33,15 @@
为了提高交易处理效率，同时也为了确定交易之后的执行顺序保证事务性，当交易池中有交易时，Sealer线程负责从交易池中按照先进先出的顺序取出一定数量的交易，组装成待共识区块，随后待共识区块会被发往各个节点进行处理。
-
+
## 交易执行
-节点在收到区块后，会调用区块验证器把交易从区块中逐一拿出来执行。如果是预编译合约代码，验证器中的执行引擎会直接调用相应的C++功能，否则执行引擎就会把交易交给EVM（以太坊虚拟机）执行。
+节点在收到区块后，会调用区块验证器把交易从区块中逐一拿出来执行。如果是预编译合约代码，验证器中的执行引擎会直接调用相应的C++功能，否则执行引擎就会把交易交给EVM（以太坊虚拟机）或WASM执行。
交易可能会执行成功，也可能因为逻辑错误或Gas不足等原因执行失败。交易执行的结果和状态会封装在交易回执中返回。
-
+
## 交易共识
diff --git a/3.x/zh_CN/docs/design/virtual_machine/evm.md b/3.x/zh_CN/docs/design/virtual_machine/evm.md
index 22a9bad02..eaccc5ece 100644
--- a/3.x/zh_CN/docs/design/virtual_machine/evm.md
+++ b/3.x/zh_CN/docs/design/virtual_machine/evm.md
@@ -1,4 +1,4 @@
-# EVM 以太坊虚拟机
+# EVM 引擎
标签：``EVM`` ``智能合约`` ``虚拟机``
@@ -8,13 +8,11 @@
当智能合约被编译成二进制文件后，被部署到区块链上。用户通过调用智能合约的接口，来触发智能合约的执行操作。EVM执行智能合约的代码，修改当前区块链上的数据（状态）。被修改的数据，会被共识，确保一致性。
-
-
## EVMC – Ethereum Client-VM Connector API
-新版本的以太坊将EVM从节点代码中剥离出来，形成一个独立的模块。EVM与节点的交互，抽象出EVMC接口标准。通过EVMC，节点可以对接多种虚拟机，而不仅限于传统的基于solidity的虚拟机。
+新版本的以太坊将EVM从节点代码中剥离出来，形成一个独立的模块。EVM与节点的交互，抽象出EVMC接口标准。通过EVMC，节点可以对接多种虚拟机。
-传统的solidity虚拟机，在以太坊中称为interpreter，下文主要解释interpreter的实现。
+最初的EVM虚拟机，在以太坊中称为interpreter，下文主要解释interpreter的实现。
### EVMC 接口
@@ -27,7 +25,7 @@ EVM本身不保存状态数据，节点通过instance接口操作EVM，EVM反过
-**Instance 接口**
+**Instance接口**
定义了节点对虚拟机的操作，包括创建，销毁，设置等。
@@ -47,7 +45,6 @@ EVM本身不保存状态数据，节点通过instance接口操作EVM，EVM反过
接口定义在evmc_context_fn_table（evmc.h）中。
-
* evmc_account_exists_fn account_exists
* evmc_get_storage_fn get_storage
* evmc_set_storage_fn set_storage
@@ -61,7 +58,6 @@ EVM本身不保存状态数据，节点通过instance接口操作EVM，EVM反过
* evmc_get_block_hash_fn get_block_hash
* evmc_emit_log_fn emit_log
-
## EVM 执行
### EVM 指令
@@ -198,9 +194,6 @@ void VM::caseCall()
}
```
-
-
## 总结
-EVM是一个状态执行的机器，输入是solidity编译后的二进制指令和节点的状态数据，输出是节点状态的改变。以太坊通过EVMC实现了多种虚拟机的兼容。但截至目前，并未出现除开interpreter之外的，真正生产可用的虚拟机。也许要做到同一份代码在不同的虚拟机上跑出相同的结果，是一件很难的事情。BCOS将持续跟进此部分的发展。
-
+EVM是一个状态执行的机器，输入是solidity编译后的二进制指令和节点的状态数据，输出是节点状态的改变。以太坊通过EVMC实现了多种虚拟机的兼容。
diff --git a/3.x/zh_CN/docs/design/virtual_machine/gas.md b/3.x/zh_CN/docs/design/virtual_machine/gas.md
index 98c5dada5..d168054b0 100644
--- a/3.x/zh_CN/docs/design/virtual_machine/gas.md
+++ b/3.x/zh_CN/docs/design/virtual_machine/gas.md
@@ -1,20 +1,12 @@
-# Gas
+# Gas 计费
标签：``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消耗中的占比。
-
+EVM虚拟机有一整套Gas机制来衡量每笔交易上链消耗的CPU、内存和存储资源。FISCO BCOS 引入了Precompiled合约，支持内置的C++合约，为了提升Precompiled合约的安全性，FISCO BCOS v2.4.0在Precompiled合约中引入了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、内存和存储三个维度，模块图如下：
@@ -29,7 +21,6 @@ FISCO BCOS v2.4.0新增了`PrecompiledGas`模块进行Gas计算，Gas开销主
- `Precompiled`合约执行完毕后，可调用接口，根据运行`Precompiled`合约过程中执行的指令集合、消耗的内存，计算出该`Precompiled`合约Gas消耗。
-
### Precompiled合约Gas衡量标准
FISCO BCOS Precompiled合约Gas衡量标准参考了EVM，主要包括CPU、内存和存储三个维度。下面详细介绍Precompiled合约具体的Gas计算方法。
@@ -75,7 +66,6 @@ PaillierAdd | 同态加接口 | 0x13 |
GroupSigVerify | 群签名验证接口 | 0x14 |
RingSigVerify | 环签名验证接口 | 0x15 |
-
##### Precompiled合约基础操作衡量标准
`PrecompiledGas`定义了Precompiled合约每个基础操作对应的Gas消耗，具体如下：
@@ -105,52 +95,30 @@ 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衡量模式，如下图所示：
-
-
-
-为了提升CPU和内存在交易Gas消耗中的占比，`FreeStorageEVMSchedule`调整了创建合约、`SSTORE`、`SLOAD`等操作的Gas消耗；`FreeStorageGasMetrics`主要调整了`CreateTable`、`Insert`、`Remove`、`Update`等操作的Gas消耗。
-
### Gas衡量标准
-下面分别介绍非`FreeStorage`模式和`FreeStorage`模式下，EVM虚拟机和Precompiled合约Gas衡量标准：
+下面分别介绍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 |
+Gas | 说明 | Gas消耗 |
+|-------|--------|-------|
+CreateGas | 创建合约的Gas消耗 | 32000 |
+sloadGas| 从存储读取32字节数据消耗的Gas | 200 |
+sstoreSetGas| 添加32字节数据到存储的Gas消耗 | 20000 |
+sstoreResetGas| 更新32字节存储数据的Gas消耗 |5000 |
**Precompiled合约Gas衡量标准**
-
-Gas | 说明| GasMetrics模式下Gas消耗 | FreeStorageGasMetrics模式下Gas消耗
--------|--------|-------|--------|
-CreateTableGas| 创建表的Gas消耗 | 16000 | 500 |
-StoreGas| 向表中插入数据或更新表中数据的Gas消耗 | 10000 | 200 |
-RemoveGas| 删除表中数据的Gas消耗 | 2500 | 200 |
-
+Gas | 说明| Gas消耗 |
+-------|--------|-------|
+CreateTableGas| 创建表的Gas消耗 | 16000 |
+StoreGas| 向表中插入数据或更新表中数据的Gas消耗 | 10000 |
+RemoveGas| 删除表中数据的Gas消耗 | 2500 |
### 配置项
```eval_rst
.. note::
EVM Gas衡量标准支持插件化配置项位于 ``genesis`文件中
-```
\ No newline at end of file
+```
diff --git a/3.x/zh_CN/docs/design/virtual_machine/index.rst b/3.x/zh_CN/docs/design/virtual_machine/index.rst
index 6908d8ba0..9d97b96d7 100644
--- a/3.x/zh_CN/docs/design/virtual_machine/index.rst
+++ b/3.x/zh_CN/docs/design/virtual_machine/index.rst
@@ -1,29 +1,29 @@
##############################################################
-智能合约
+8. 智能合约引擎
##############################################################
-标签： ``智能合约`` ``虚拟机``
+标签： ``智能合约`` ``虚拟机``
----
-交易的执行是区块链节点上的一个重要的功能。交易的执行，是把交易中的智能合约二进制代码取出来，用执行器（Executor_）执行。共识模块（Consensus_）把交易从交易池中取出，打包成区块，并调用执行器去执行区块中的交易。在交易的执行过程中，会对区块链的状态（State）进行修改，形成新区块的状态储存下来（Storage）。执行器在这个过程中，类似于一个黑盒，输入是智能合约代码，输出是状态的改变。
-
-随着技术的发展，人们开始关注执行器的性能和易用性。一方面，人们希望智能合约在区块链上能有更快的执行速度，满足大规模交易的需求。另一方面，人们希望能用更熟悉更好用的语言进行开发。进而出现了一些替代传统的执行器（EVM）的方案，如：JIT_、 WASM_甚至JVM。然而，传统的EVM是耦合在节点代码中的。首先要做的，是将执行器的接口抽象出来，兼容各种虚拟机的实现。因此，EVMC被设计出来。
+交易的执行是区块链节点上的一个重要的功能。交易的执行，是把交易中的智能合约二进制代码取出来，用执行器（Executor）执行。共识模块（Consensus）把交易从交易池中取出，打包成区块，并调用执行器去执行区块中的交易。在交易的执行过程中，会对区块链的状态（State）进行修改，形成新区块的状态储存下来（Storage）。执行器在这个过程中，类似于一个黑盒，输入是智能合约代码，输出是状态的改变。
+随着技术的发展，人们开始关注执行器的性能和易用性。一方面，人们希望智能合约在区块链上能有更快的执行速度，满足大规模交易的需求。另一方面，人们希望能用更熟悉更好用的语言进行开发。进而出现了一些替代传统的执行器（EVM）的方案，如：WASM，传统的EVM是耦合在节点代码中的。首先要做的，是将执行器的接口抽象出来，兼容各种虚拟机的实现。因此，EVMC被设计出来。
EVMC (Ethereum Client-VM Connector API)，是以太坊抽象出来的执行器的接口，旨在能够对接各种类型的执行器。FISCO BCOS目前采用了以太坊的智能合约语言Solidity，因此也沿用了以太坊对执行器接口的抽象。
.. image:: ../../../images/evm/evmc_frame.png
-在节点上，共识模块会调用EVMC，将打包好的交易交由执行器执行。执行器执行时，对状态进行的读写，会通过EVMC的回调反过来操作节点上的状态数据。
+在节点上，共识模块会将打包好的区块交由执行器执行。虚拟机执行时，对状态进行的读写，会通过EVMC的回调反过来操作节点上的状态数据。
经过EVMC一层的抽象，FISCO BCOS能够对接今后出现的更高效、易用性更强的执行器。目前，FISCO BCOS采用的evmone执行solidity合约，采用wasmtime执行wasm合约。
.. toctree::
:maxdepth: 1
-
+
evm.md
precompiled.md
+ wasm.md
gas.md
.. _Executor: ./evm.html
diff --git a/3.x/zh_CN/docs/design/virtual_machine/precompiled.md b/3.x/zh_CN/docs/design/virtual_machine/precompiled.md
index f1907d425..6c6f8bfe0 100644
--- a/3.x/zh_CN/docs/design/virtual_machine/precompiled.md
+++ b/3.x/zh_CN/docs/design/virtual_machine/precompiled.md
@@ -1,4 +1,4 @@
-## 预编译合约
+## C++ 引擎
标签：``预编译合约`` ``智能合约`` ``Precompiled``
@@ -8,11 +8,11 @@
### 预编译合约与Solidity合约对比
-|表名 | 预编译合约 | Solidity合约|
-|:--------|:-----|:-----|
-|地址 | 固定地址，代码中定义 | 部署时确定|
-|合约代码 | 数据存储在表中，与合约分离，可升级合约逻辑| 合约变量和数据存储在MPT树中|
-|执行 | C++底层执行，性能更高，可实现并行 | EVM虚拟机，串行执行|
+| 表名 | 预编译合约 | Solidity合约 |
+|:---------|:-------------------------------------------|:----------------------------|
+| 地址 | 固定地址，代码中定义 | 部署时确定 |
+| 合约代码 | 数据存储在表中，与合约分离，可升级合约逻辑 | 合约变量和数据存储在MPT树中 |
+| 执行 | C++底层执行，性能更高，可实现并行 | EVM虚拟机，串行执行 |
### 模块架构
@@ -26,10 +26,8 @@ Precompiled的架构如下图所示：
- 每个预编译合约对象都会实现`call`接口，预编译合约的具体逻辑在该接口中实现。
- `call`根据交易的abi编码，获取到`Function Selector`和参数，然后执行对应的逻辑。
-```eval_rst
-.. mermaid::
-
- graph TB
+```mermaid
+ graph LR
Start(开始) --> branch1{预编译合约}
branch1 --> |是|op1[根据地址获取合约对象]
branch1 --> |否|op2[EVM]
@@ -40,11 +38,11 @@ Precompiled的架构如下图所示：
### 接口定义
-每个预编译合约都必须实现自己的`call`接口，接口接受三个参数，分别是`ExecutiveContext`执行上下文、`bytesConstRef`参数的abi编码和外部账户地址，其中外部账户地址用于判断是否具有写权限。[`Precompiled`源码](https://github.com/FISCO-BCOS/FISCO-BCOS/blob/04db9d5e9d7a9d321d90cef8dc5e2010a53ed8d3/libprecompiled/Precompiled.h#L37)。
+每个预编译合约都必须实现自己的`call`接口，接口接受两个参数，分别是`TransactionExecutive::Ptr`执行上下文、`PrecompiledExecResult::Ptr`执行参数，其中包括执行输入、外部账户地址、gas使用。[`Precompiled`源码](https://github.com/FISCO-BCOS/FISCO-BCOS/blob/76da8909d5/bcos-executor/src/vm/Precompiled.h)。
-|接口名|参数说明|接口说明|
-|:----|:------|:------|
-|`virtual bytes call(std::shared_ptr2. Emergency Stop
3. Speed Bump
4. Rate Limit
5. Mutex
6. Balance Limit | +| Maintenance | 7. Data Segregation
8. Satellite
9. Contract Register
10. Contract Relay | +| Lifecycle | 11. Mortal
12. Automatic Deprecation | +| Authorization | 13. Ownership
14. Access Restriction | +| Action And Control | 15. Pull Payment
16. Commit And Reveal
17. State Machine
18. Oracle | + +接下来，本文将从这18种设计模式中选择最为通用常见的进行介绍，这些设计模式在实际开发经历中得到了大量检验。 + +### 1.1 Checks-Effects-Interaction - 保证状态完整，再做外部调用 + +该模式是编码风格约束，可有效避免重放攻击。通常情况下，一个函数可能包含三个部分： + +- Checks：参数验证 +- Effects：修改合约状态 +- Interaction：外部交互 + +这个模式要求合约按照Checks-Effects-Interaction的顺序来组织代码。它的好处在于进行外部调用之前，Checks-Effects已完成合约自身状态所有相关工作，使得状态完整、逻辑自洽，这样外部调用就无法利用不完整的状态进行攻击了。回顾前文的AddService合约，并没有遵循这个规则，在自身状态没有更新完的情况下去调用了外部代码，外部代码自然可以横插一刀，让_adders[msg.sender]=true永久不被调用，从而使require语句失效。我们以checks-effects-interaction的角度审阅原来的代码： + +```solidity + //Checks + require(_adders[msg.sender] == false, "You have added already"); + //Effects + _count++; + //Interaction + AdderInterface adder = AdderInterface(msg.sender); + adder.notify(); + //Effects + _adders[msg.sender] = true; +``` + +只要稍微调整顺序，满足Checks-Effects-Interaction模式，悲剧就得以避免： + +```solidity + //Checks + require(_adders[msg.sender] == false, "You have added already"); + //Effects + _count++; + _adders[msg.sender] = true; + //Interaction + AdderInterface adder = AdderInterface(msg.sender); + adder.notify(); +``` + +由于_adders映射已经修改完毕，当恶意攻击者想递归地调用addByOne，require这道防线就会起到作用，将恶意调用拦截在外。虽然该模式并非解决重入攻击的唯一方式，但依然推荐开发者遵循。 + +### 1.2 Mutex - 禁止递归 + +Mutex模式也是解决重入攻击的有效方式。它通过提供一个简单的修饰符来防止函数被递归调用： + +```solidity +contract Mutex { + bool locked; + modifier noReentrancy() { + //防止递归 + require(!locked, "Reentrancy detected"); + locked = true; + _; + locked = false; + } + + //调用该函数将会抛出Reentrancy detected错误 + function some() public noReentrancy{ + some(); + } +} +``` + +在这个例子中，调用some函数前会先运行noReentrancy修饰符，将locked变量赋值为true。如果此时又递归地调用了some，修饰符的逻辑会再次激活，由于此时的locked属性已为true，修饰符的第一行代码会抛出错误。 + +### 1.3 Data segregation - 数据与逻辑相分离 + +了解该设计模式之前，先看看下面这个合约代码： + +```solidity +contract Computer{ + + uint private _data; + + function setData(uint data) public { + _data = data; + } + + function compute() public view returns(uint){ + return _data * 10; + } +} +``` + +此合约包含两个能力，一个是存储数据(setData函数)，另一个是运用数据进行计算(compute函数）。如果合约部署一段时间后，发现compute写错了，比如不应是乘以10，而要乘以20，就会引出前文如何升级合约的问题。这时，可以部署一个新合约，并尝试将已有数据迁移到新的合约上，但这是一个很重的操作，一方面要编写迁移工具的代码，另一方面原先的数据完全作废，空占着宝贵的节点存储资源。 + +所以，预先在编程时进行模块化十分必要。如果我们将"数据"看成不变的事物，将"逻辑"看成可能改变的事物，就可以完美避开上述问题。Data Segregation（意为数据分离）模式很好地实现了这一想法。该模式要求一个业务合约和一个数据合约：数据合约只管数据存取，这部分是稳定的；而业务合约则通过数据合约来完成逻辑操作。 + +结合前面的例子，我们将数据读写操作专门转移到一个合约DataRepository中： + +```solidity +contract DataRepository{ + + uint private _data; + + function setData(uint data) public { + _data = data; + } + + function getData() public view returns(uint){ + return _data; + } +} +``` + +计算功能被单独放入一个业务合约中： + +```solidity +contract Computer{ + DataRepository private _dataRepository; + constructor(address addr){ + _dataRepository =DataRepository(addr); + } + + //业务代码 + function compute() public view returns(uint){ + return _dataRepository.getData() * 10; + } +} +``` + +这样，只要数据合约是稳定的，业务合约的升级就很轻量化了。比如，当我要把Computer换成ComputerV2时，原先的数据依然可以被复用。 + +### 1.4 Satellite - 分解合约功能 + +一个复杂的合约通常由许多功能构成，如果这些功能全部耦合在一个合约中，当某一个功能需要更新时，就不得不去部署整个合约，正常的功能都会受到波及。Satellite模式运用单一职责原则解决上述问题，提倡将合约子功能放到子合约里，每个子合约（也称为卫星合约）只对应一个功能。当某个子功能需要修改，只要创建新的子合约，并将其地址更新到主合约里即可，其余功能不受影响。 + +举个简单的例子，下面这个合约的setVariable功能是将输入数据进行计算（compute函数），并将计算结果存入合约状态_variable： + +```solidity +contract Base { + uint public _variable; + + function setVariable(uint data) public { + _variable = compute(data); + } + + //计算 + function compute(uint a) internal returns(uint){ + return a * 10; + } +} +``` + +如果部署后，发现compute函数写错，希望乘以的系数是20，就要重新部署整个合约。但如果一开始按照Satellite模式操作，则只需部署相应的子合约。 + +首先，我们先将compute函数剥离到一个单独的卫星合约中去： + +```solidity +contract Satellite { + function compute(uint a) public returns(uint){ + return a * 10; + } +} +``` + +然后，主合约依赖该子合约完成setVariable： + +```solidity +contract Base { + uint public _variable; + + function setVariable(uint data) public { + _variable = _satellite.compute(data); + } + + Satellite _satellite; + //更新子合约（卫星合约） + function updateSatellite(address addr) public { + _satellite = Satellite(addr); + } +} +``` + +这样，当我们需要修改compute函数时，只需部署这样一个新合约，并将它的地址传入到Base.updateSatellite即可： + +```solidity +contract Satellite2{ + function compute(uint a) public returns(uint){ + return a * 20; + } +} +``` + +### 1.5 Contract Registry - 跟踪最新合约 + +在Satellite模式中，如果一个主合约依赖子合约，在子合约升级时，主合约需要更新对子合约的地址引用，这通过updateXXX来完成，例如前文的updateSatellite函数。这类接口属于维护性接口，与实际业务无关，过多暴露此类接口会影响主合约美观，让调用者的体验大打折扣。Contract Registry设计模式优雅地解决了这个问题。在该设计模式下，会有一个专门的合约Registry跟踪子合约的每次升级情况，主合约可通过查询此Registyr合约取得最新的子合约地址。卫星合约重新部署后，新地址通过Registry.update函数来更新。 + +```solidity +contract Registry{ + + address _current; + address[] _previous; + + //子合约升级了，就通过update函数更新地址 + function update(address newAddress) public{ + if(newAddress != _current){ + _previous.push(_current); + _current = newAddress; + } + } + + function getCurrent() public view returns(address){ + return _current; + } +} +``` + +主合约依赖于Registry获取最新的卫星合约地址。 + +```solidity +contract Base { + uint public _variable; + + function setVariable(uint data) public { + Satellite satellite = Satellite(_registry.getCurrent()); + _variable = satellite.compute(data); + } + + Registry private _registry = //...; +} +``` + +### 1.6 Contract Relay - 代理调用最新合约 + +该设计模式所解决问题与Contract Registry一样，即主合约无需暴露维护性接口就可调用最新子合约。该模式下，存在一个代理合约，和子合约享有相同接口，负责将主合约的调用请求传递给真正的子合约。卫星合约重新部署后，新地址通过SatelliteProxy.update函数来更新。 + +```solidity +contract SatelliteProxy{ + address _current; + function compute(uint a) public returns(uint){ + Satellite satellite = Satellite(_current); + return satellite.compute(a); + } + + //子合约升级了，就通过update函数更新地址 + function update(address newAddress) public{ + if(newAddress != _current){ + _current = newAddress; + } + } +} + + +contract Satellite { + function compute(uint a) public returns(uint){ + return a * 10; + } +} +``` + +主合约依赖于SatelliteProxy： + +```solidity +contract Base { + uint public _variable; + + function setVariable(uint data) public { + _variable = _proxy.compute(data); + } + SatelliteProxy private _proxy = //...; +} +``` + +### 1.7 Mortal - 允许合约自毁 + +字节码中有一个selfdestruct指令，用于销毁合约。所以只需要暴露出自毁接口即可： + +```solidity +contract Mortal{ + + //自毁 + function destroy() public{ + selfdestruct(msg.sender); + } +} +``` + +### 1.8 Automatic Deprecation - 允许合约自动停止服务 + +如果你希望一个合约在指定期限后停止服务，而不需要人工介入，可以使用Automatic Deprecation模式。 + +``` solidity +contract AutoDeprecated{ + + uint private _deadline; + + function setDeadline(uint time) public { + _deadline = time; + } + + modifier notExpired(){ + require(now <= _deadline); + _; + } + + function service() public notExpired { + //some code + } +} +``` + +当用户调用service，notExpired修饰符会先进行日期检测，这样，一旦过了特定时间，调用就会因过期而被拦截在notExpired层。 + +### 1.9 Ownership检查 + +前文中有许多管理性接口，这些接口如果任何人都可调用，会造成严重后果，例如上文中的自毁函数，假设任何人都能访问，其严重性不言而喻。所以，一套保证只有特定账户能够访问的权限控制设计模式显得尤为重要。 + +对于权限的管控，可以采用Ownership模式。该模式保证了只有合约的拥有者才能调用某些函数。首先需要有一个Owned合约： + +```solidity +contract Owned{ + + address public _owner; + + constructor() { + _owner = msg.sender; + } + + modifier onlyOwner(){ + require(_owner == msg.sender); + _; + } +} +``` + +如果一个业务合约，希望某个函数只由拥有者调用，该怎么办呢？如下： + +```solidity +contract Biz is Owned{ + function manage() public onlyOwner{ + } +} +``` + +这样，当调用manage函数时，onlyOwner修饰符就会先运行并检测调用者是否与合约拥有者一致，从而将无授权的调用拦截在外。 + +### 1.10 延迟秘密泄露 + +这类模式一般针对具体场景使用，这节将主要介绍基于隐私的编码模式和与链外数据交互的设计模式。 + +链上数据都是公开透明的，一旦某些隐私数据上链，任何人都可看到，并且再也无法撤回。Commit And Reveal模式允许用户将要保护的数据转换为不可识别数据，比如一串哈希值，直到某个时刻再揭示哈希值的含义，展露真正的原值。以投票场景举例，假设需要在所有参与者都完成投票后再揭示投票内容，以防这期间参与者受票数影响。我们可以看看，在这个场景下所用到的具体代码： + +```solidity +contract CommitReveal { + + struct Commit { + string choice; + string secret; + uint status; + } + + mapping(address => mapping(bytes32 => Commit)) public userCommits; + event LogCommit(bytes32, address); + event LogReveal(bytes32, address, string, string); + + function commit(bytes32 commit) public { + Commit storage userCommit = userCommits[msg.sender][commit]; + require(userCommit.status == 0); + userCommit.status = 1; // committed + emit LogCommit(commit, msg.sender); + } + + function reveal(string choice, string secret, bytes32 commit) public { + Commit storage userCommit = userCommits[msg.sender][commit]; + require(userCommit.status == 1); + require(commit == keccak256(choice, secret)); + userCommit.choice = choice; + userCommit.secret = secret; + userCommit.status = 2; + emit LogReveal(commit, msg.sender, choice, secret); + } +} +``` + +## 2. 智能合约编程攻略 + +[智能合约编写之Solidity的编程攻略](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/articles/3_features/35_contract/solidity_design_programming_strategy.html) + +作者：毛嘉宇｜FISCO BCOS 核心开发者 + +**“如无必要，勿增实体”。** + +- 需要分布式协作的重要数据才上链，非必需数据不上链； +- 敏感数据脱敏或加密后上链（视数据保密程度选择符合隐私保护安全等级要求的加密算法）； +- 链上验证，链下授权。 + +在使用区块链时，开发者不需要将所有业务和数据都放到链上。相反，“好钢用在刀刃上”，智能合约更适合被用在分布式协作的业务场景中。 + +### 2.1 精简函数变量 + +如果在智能合约中定义了复杂的逻辑，特别是合约内定义了复杂的函数入参、变量和返回值，就会在编译的时候碰到以下错误： + +```shell +Compiler error: Stack too deep, try removing local variables. +``` + +这也是社区中的高频技术问题之一。造成这个问题的原因就是EVM所设计用于最大的栈深度为16。所有的计算都在一个栈内执行，对栈的访问只限于其顶端，限制方式为：允许拷贝最顶端16个元素中的一个到栈顶，或者将栈顶元素和下面16个元素中的一个交换。所有其他操作都只能取最顶的几个元素，运算后，把结果压入栈顶。当然可以把栈上的元素放到存储或内存中。但无法只访问栈上指定深度的那个元素，除非先从栈顶移除其他元素。如果一个合约中，入参、返回值、内部变量的大小超过了16个，显然就超出了栈的最大深度。因此，我们可以使用结构体或数组来封装入参或返回值，达到减少栈顶元素使用的目的，从而避免此错误。例如以下代码，通过使用bytes数组来封装了原本16个bytes变量。 + +```solidity +function doBiz(bytes[] paras) public { + require(paras.length >= 16); + // do something +} +``` + +### 2.2 保证参数和行为符合预期 + +在编写智能合约时，一定要注意对合约参数和行为的检查，尤其是那些对外部开放的合约函数。Solidity提供了require、revert、assert等关键字来进行异常的检测和处理。一旦检测并发现错误，整个函数调用会被回滚，所有状态修改都会被回退，就像从未调用过函数一样。以下分别使用了三个关键字，实现了相同的语义。 + +```solidity +require(_data == data, "require data is valid"); + +if(_data != data) { revert("require data is valid"); } + +assert(_data == data); +``` + +不过，这三个关键字一般适用于不同的使用场景： + +- require：最常用的检测关键字，用来验证输入参数和调用函数结果是否合法。 +- revert：适用在某个分支判断的场景下。 +- assert: 检查结果是否正确、合法，一般用于函数结尾。 + +在一个合约的函数中，可以使用函数修饰器来抽象部分参数和条件的检查。在函数体内，可以对运行状态使用if-else等判断语句进行检查，对异常的分支使用revert回退。在函数运行结束前，可以使用assert对执行结果或中间状态进行断言检查。在实践中，推荐使用require关键字，并将条件检查移到函数修饰器中去；这样可以让函数的职责更为单一，更专注到业务逻辑中。同时，函数修饰器等条件代码也更容易被复用，合约也会更加安全、层次化。 + +以一个水果店库存管理系统为例，设计一个水果超市的合约。这个合约只包含了对店内所有水果品类和库存数量的管理，setFruitStock函数提供了对应水果库存设置的函数。在这个合约中，我们需要检查传入的参数，即水果名称不能为空。 + +```solidity +pragma solidity ^0.4.25; + +contract FruitStore { + mapping(bytes => uint) _fruitStock; + modifier validFruitName(bytes fruitName) { + require(fruitName.length > 0, "fruite name is invalid!"); + _; + } + function setFruitStock(bytes fruitName, uint stock) validFruitName(fruitName) external { + _fruitStock[fruitName] = stock; + } +} +``` + +如上所述，我们添加了函数执行前的参数检查的函数修饰器。同理，通过使用函数执行前和函数执行后检查的函数修饰器，可以保证智能合约更加安全、清晰。智能合约的编写需要设置严格的前置和后置函数检查，来保证其安全性。 + +### 2.3 严控函数的执行权限 + +如果说智能合约的参数和行为检测提供了静态的合约安全措施，那么合约权限控制的模式则提供了动态访问行为的控制。由于智能合约是发布到区块链上，所有数据和函数对所有参与者都是公开透明的，任一节点参与者都可发起交易，无法保证合约的隐私。因此，合约发布者必须对函数设计严格的访问限制机制。Solidity提供了函数可见性修饰符、修饰器等语法，灵活地使用这些语法，可帮助构建起合法授权、受控调用的智能合约系统。还是以刚才的水果合约为例。现在getStock提供了查询具体水果库存数量的函数。 + +```solidity +pragma solidity ^0.4.25; + +contract FruitStore { + mapping(bytes => uint) _fruitStock; + modifier validFruitName(bytes fruitName) { + require(fruitName.length > 0, "fruite name is invalid!"); + _; + } + function getStock(bytes fruit) external view returns(uint) { + return _fruitStock[fruit]; + } + function setFruitStock(bytes fruitName, uint stock) validFruitName(fruitName) external { + _fruitStock[fruitName] = stock; + } +} +``` + +水果店老板将这个合约发布到了链上。但是，发布之后，setFruitStock函数可被任何其他联盟链的参与者调用。虽然联盟链的参与者是实名认证且可事后追责；但一旦有恶意攻击者对水果店发起攻击，调用setFruitStock函数就能任意修改水果库存，甚至将所有水果库存清零，这将对水果店正常经营管理产生严重后果。因此，设置某些预防和授权的措施很必要：对于修改库存的函数setFruitStock，可在函数执行前对调用者进行鉴权。类似的，这些检查可能会被多个修改数据的函数复用，使用一个onlyOwner的修饰器就可以抽象此检查。owner字段代表了合约的所有者，会在合约构造函数中被初始化。使用public修饰getter查询函数，就可以通过_owner()函数查询合约的所有者。 + +```solidity +contract FruitStore { + address public _owner; + mapping(bytes => uint) _fruitStock; + + constructor() public { + _owner = msg.sender; + } + + modifier validFruitName(bytes fruitName) { + require(fruitName.length > 0, "fruite name is invalid!"); + _; + } + // 鉴权函数修饰器 + modifier onlyOwner() { + require(msg.sender == _owner, "Auth: only owner is authorized."); + _; + } + function getStock(bytes fruit) external view returns(uint) { + return _fruitStock[fruit]; + } + // 添加了onlyOwner修饰器 + function setFruitStock(bytes fruitName, uint stock) + onlyOwner validFruitName(fruitName) external { + _fruitStock[fruitName] = stock; + } +} +``` + +这样一来，我们可以将相应的函数调用权限检查封装到修饰器中，智能合约会自动发起对调用者身份验证检查，并且只允许合约部署者来调用setFruitStock函数，以此保证合约函数向指定调用者开放。 + +### 2.4 抽象通用的业务逻辑 + +分析上述FruitStore合约，我们发现合约里似乎混入了奇怪的东西。参考单一职责的编程原则，水果店库存管理合约多了上述函数功能检查的逻辑，使合约无法将所有代码专注在自身业务逻辑中。对此，我们可以抽象出可复用的功能，利用Solidity的继承机制继承最终抽象的合约。基于上述FruitStore合约，可抽象出一个BasicAuth合约，此合约包含之前onlyOwner的修饰器和相关功能接口。 + +```solidity +contract BasicAuth { + address public _owner; + + constructor() public { + _owner = msg.sender; + } + + function setOwner(address owner) + public + onlyOwner +{ + _owner = owner; + } + + modifier onlyOwner() { + require(msg.sender == _owner, "BasicAuth: only owner is authorized."); + _; + } +} +``` + +FruitStore可以复用这个修饰器，并将合约代码收敛到自身业务逻辑中。 + +```solidity +import "./BasicAuth.sol"; + +contract FruitStore is BasicAuth { + mapping(bytes => uint) _fruitStock; + + function setFruitStock(bytes fruitName, uint stock) + onlyOwner validFruitName(fruitName) external { + _fruitStock[fruitName] = stock; + } +} +``` + +这样一来，FruitStore的逻辑被大大简化，合约代码更精简、聚焦和清晰。 + +### 2.5 预防私钥的丢失 + +在区块链中调用合约函数的方式有两种：内部调用和外部调用。出于隐私保护和权限控制，业务合约会定义一个合约所有者。假设用户A部署了FruitStore合约，那上述合约owner就是部署者A的外部账户地址。这个地址由外部账户的私钥计算生成。但是，在现实世界中，私钥泄露、丢失的现象比比皆是。一个商用区块链DAPP需要严肃考虑私钥的替换和重置等问题。这个问题最为简单直观的解决方法是添加一个备用私钥。这个备用私钥可支持权限合约修改owner的操作，代码如下： + +```solidity +ontract BasicAuth { + address public _owner; + address public _bakOwner; + + constructor(address bakOwner) public { + _owner = msg.sender; + _bakOwner = bakOwner; + } + + function setOwner(address owner) + public + canSetOwner +{ + _owner = owner; + } + + function setBakOwner(address owner) + public + canSetOwner +{ + _bakOwner = owner; + } + + // ... + + modifier isAuthorized() { + require(msg.sender == _owner || msg.sender == _bakOwner, "BasicAuth: only owner or back owner is authorized."); + _; + } +} +``` + +这样，当发现私钥丢失或泄露时，我们可以使用备用外部账户调用setOwner重置账号，恢复、保障业务正常运行。 + +### 2.6 合理预留事件 + +迄今为止，我们已实现强大灵活的权限管理机制，只有预先授权的外部账户才能修改合约owner属性。不过，仅通过上述合约代码，我们无法记录和查询修改、调用函数的历史记录和明细信息。而这样的需求在实际业务场景中比比皆是。比如，FruitStore水果店需要通过查询历史库存修改记录，计算出不同季节的畅销与滞销水果。 + +一种方法是依托链下维护独立的台账机制。不过，这种方法存在很多问题：保持链下台账和链上记录一致的成本开销非常高；同时，智能合约面向链上所有参与者开放，一旦其他参与者调用了合约函数，相关交易信息就存在不能同步的风险。针对此类场景，Solidity提供了event语法。event不仅具备可供SDK监听回调的机制，还能用较低的gas成本将事件参数等信息完整记录、保存到区块中。FISCO BCOS社区中，也有WEBASE-Collect-Bee这样的工具，在事后实现区块历史事件信息的完整导出。 + +[WEBASE-Collect-Bee工具参考](https://webasedoc.readthedocs.io/zh_CN/latest/docs/WeBASE-Collect-Bee/index.html) + +基于上述权限管理合约，我们可以定义相应的修改权限事件，其他事件以此类推。 + +```solidity +event LogSetAuthority (Authority indexed authority, address indexed from); +} +``` + +接下来，可以调用相应的事件： + +```solidity +function setAuthority(Authority authority) + public + auth +{ + _authority = authority; + emit LogSetAuthority(authority, msg.sender); + } +``` + +当setAuthority函数被调用时，会同时触发LogSetAuthority，将事件中定义的Authority合约地址以及调用者地址记录到区块链交易回执中。当通过控制台调用setAuthority方法时，对应事件LogSetAuthority也会被打印出来。基于WEBASE-Collect-Bee，我们可以导出所有该函数的历史信息到数据库中。也可基于WEBASE-Collect-Bee进行二次开发，实现复杂的数据查询、大数据分析和数据可视化等功能。 + +### 2.7 遵循安全编程规范 + +每一门语言都有其相应的编码规范，我们需要尽可能严格地遵循Solidity官方编程风格指南，使代码更利于阅读、理解和维护，有效地减少合约的bug数量。[Solidity官方编程风格指南参考](https://solidity.readthedocs.io/en/latest/style-guide.html)。除了编程规范，业界也总结了很多安全编程指南，例如重入漏洞、数据结构溢出、随机数误区、构造函数失控、为初始化的存储指针等等。重视和防范此类风险，采用业界推荐的安全编程规范至关重要，例如[Solidity官方安全编程指南](https://solidity.readthedocs.io/en/latest/security-considerations.html)。同时，在合约发布上线后，还需要注意关注、订阅Solidity社区内安全组织或机构发布的各类安全漏洞、攻击手法，一旦出现问题，及时做到亡羊补牢。 + +对于重要的智能合约，有必要引入审计。现有的审计包括了人工审计、机器审计等方法，通过代码分析、规则验证、语义验证和形式化验证等方法保证合约安全性。虽然本文通篇都在强调，模块化和重用被严格审查并广泛验证的智能合约是最佳的实践策略。但在实际开发过程，这种假设过于理想化，每个项目或多或少都会引入新的代码，甚至从零开始。不过，我们仍然可以视代码的复用程度进行审计分级，显式地标注出引用的代码，将审计和检查的重点放在新代码上，以节省审计成本。 + +### 2.8 使用SmartDev应用插件 + +SmartDev包含了一套开放、轻量的开发组件集，覆盖智能合约的开发、调试、应用开发等环节，包括智能合约库（SmartDev-Contract）、智能合约编译插件（SmartDev-SCGP）和应用开发脚手架（SmartDev-Scaffold）。开发者可根据自己的情况自由选择相应的开发工具，提升开发效率。 + +详情可以看：[SmartDev应用开发组件](./smartdev_index.md) + +## 3. 智能合约部署权限控制 + +部署合约的权限控制将由治理委员会统一控制，治理委员会将以投票表决的形式控制部署权限。治理委员会对某个部署权限的提案通过后，将会主动调用固定地址0x1005预编译合约的部署权限写接口，这些写接口也限定只能治理委员会合约调用。 + +部署权限记录在BFS目录/apps下，这代表着允许在/apps目录下的写权限。 + +治理委员可以通过控制台进行部署合约权限控制等操作，详情请看 [设置部署权限类型提案](../operation_and_maintenance/console/console_commands.html#setdeployauthtypeproposal) 、[开启部署权限提案](../operation_and_maintenance/console/console_commands.html#opendeployauthproposal) 、[关闭部署权限提案](../operation_and_maintenance/console/console_commands.html#closedeployauthproposal) + +在检查部署权限时将会对交易发起地址tx.origin进行校验，若没有权限则会返回错误码 -5000。即，会对用户部署合约、用户通过合约部署合约都进行校验。 + +## 4. 智能合约执行权限控制 + +合约管理员可以对固定地址0x1005的预编译合约发起交易，对合约接口的访问ACL进行读写。 + +在执行合约接口的访问ACL的写操作时，将会确定交易发起人msg.sender是否为合约权限表记录的合约管理员，若不是则会拒绝。 + +合约管理员可以通过控制台对合约接口访问ACL的写操作等操作，详情请看：[合约管理员专用命令](../operation_and_maintenance/console/console_commands.html#setmethodauth) + +在检查合约调用权限时将会对交易发起地址tx.origin和消息发送者msg.sender进行校验，若没有权限则会返回错误码 -5000。即，会对用户调用合约、用户通过合约调用合约、合约调用合约都进行校验。 + +## 5. 智能合约运维 + +智能合约在运维时主要关注智能合约的数据状态、智能合约升级、智能合约冻结、智能合约销毁。 + +### 5.1 智能合约升级 + +在Solidity中，一旦合约部署发布后，其代码就无法被修改，只能通过发布新合约去改动代码。假如数据存储在老合约，就会出现所谓的“孤儿数据”问题，新合约将丢失之前运行的历史业务数据。这种情况，开发者可以考虑将老合约数据迁移到新合约中，但此操作至少存在两个问题： + +1. 迁移数据会加重区块链的负担，产生资源浪费和消耗，甚至引入安全问题； +2. 牵一发而动全身，会引入额外的迁移数据逻辑，增加合约复杂度。 + +一种更合理的方式是抽象一层独立的合约存储层。这个存储层只提供合约读写的最基本方法，而不包含任何业务逻辑。在这种模式中，存在三种合约角色： + +- 数据合约：在合约中保存数据，并提供数据的操作接口。 +- 管理合约：设置控制权限，保证只有控制合约才有权限修改数据合约。 +- 控制合约：真正需要对数据发起操作的合约。 + +具体的代码示例如下： + +**数据合约** + +```solidity +contract FruitStore is BasicAuth { + address _latestVersion; + mapping(bytes => uint) _fruitStock; + + modifier onlyLatestVersion() { + require(msg.sender == _latestVersion); + _; + } + + function upgradeVersion(address newVersion) public { + require(msg.sender == _owner); + _latestVersion = newVersion; + } + + function setFruitStock(bytes fruit, uint stock) onlyLatestVersion external { + _fruitStock[fruit] = stock; + } +} +``` + +**管理合约** + +```solidity +contract Admin is BasicAuth { + function upgradeContract(FruitStore fruitStore, address newController) isAuthorized external { + fruitStore.upgradeVersion(newController); + } +} +``` + +**控制合约** + +```solidity +contract FruitStoreController is BasicAuth { + function upgradeStock(bytes fruit, uint stock) isAuthorized external { + fruitStore.setFruitStock(fruit, stock); + } +} +``` + +一旦函数的控制逻辑需要变更，开发者只需修改FruitStoreController控制合约逻辑，部署一个新合约，然后使用管理合约Admin修改新的合约地址参数就可轻松完成合约升级。这种方法可消除合约升级中因业务控制逻辑改变而导致的数据迁移隐患。但天下没有免费的午餐，这种操作需要在可扩展性和复杂性之间需要做基本的权衡。首先，数据和逻辑的分离降低了运行性能。其次，进一步封装增加了程序复杂度。最后，越是复杂的合约越会增加潜在攻击面，简单的合约比复杂的合约更安全。 + +**通用数据结构——数据升级** + +到目前为止，还存在一个问题，假如数据合约中的数据结构本身需要升级怎么办？ + +例如，在FruitStore中，原本只保存了库存信息，现在由于水果销售店生意发展壮大，一共开了十家分店，需要记录每家分店、每种水果的库存和售出信息。在这种情况下，一种解决方案是采用外部关联管理方式：创建一个新的ChainStore合约，在这个合约中创建一个mapping，建立分店名和FruitStore的关系。 + +此外，不同分店需要创建一个FruitStore的合约。为了记录新增的售出信息等数据，我们还需要新建一个合约来管理。假如在FruitStore中可预设一些不同类型的reserved字段，可帮助规避新建售出信息合约的开销，仍然复用FruitStore合约。但这种方式在最开始会增加存储开销。一种更好的思路是抽象一层更为底层和通用的存储结构。代码如下： + +```solidity +contract commonDB is BasicAuth { + mapping(bytes => uint) _uintMapping; + + function getUint(bytes key) external view returns(uint) { + return _uintMapping[key]; + } + + function setUint(bytes key, uint value) isAuthorized onlyLatestVersion external { + _uintMapping[key] = value; + } + +} +``` + +类似的，我们可加入所有数据类型变量，帮助commonDB应对和满足不同的数据类型存储需求。相应的控制合约可修改如下： + +```solidity +contract FruitStoreControllerV2 is BasicAuth { + function upgradeStock(bytes32 storeName, bytes32 fruit, uint stock) + isAuthorized external { + commonDB.setUint(sha256(storeName, fruit), stock); + uint result = commonDB.getUint(sha256(storeName, fruit)); + } +} +``` + +使用以上存储的设计模式，可显著提升合约数据存储灵活性，保证合约可升级。众所周知，Solidity既不支持数据库，使用代码作为存储entity，也无法提供更改schema的灵活性。但是，通过这种KV设计，可以使存储本身获得强大的可扩展性。总之，**没有一个策略是完美的，优秀的架构师善于权衡**。智能合约设计者需要充分了解各种方案的利弊，并基于实际情况选择合适的设计方案。 + +**使用CRUD或者KV存储合约数据** + +需要存储的数据都使用CRUD数据接口进行存储，CRUD的数据是通过节点共识并持久存储在链上的。详情请参考[使用CRUD预编译合约开发应用](../contract_develop/c++_contract/use_crud_precompiled.md)，[使用KV存储预编译合约开发应用](../contract_develop/c++_contract/use_kv_precompiled.md) + +### 5.2 智能合约冻结、解冻 + +在合约出现数据异常或者出现大量访问异常时，合约管理员可以对该智能合约进行冻结操作，防止其他用户继续访问该合约。 + +合约管理员可以对固定地址0x1005的预编译合约发起交易，对合约的状态进行读写。 + +在执行合约状态的写操作时，将会确定交易发起人msg.sender是否为合约权限表记录的合约管理员，若不是则会拒绝。 + +```eval_rst +.. important:: + 兼容性说明：合约生命周期管理废止操作只能在节点版本3.2以上进行。 +``` + +合约管理员也可以通过控制台对合约进行冻结等操作，详情请看：[冻结合约命令](../operation_and_maintenance/console/console_commands.html#freezecontract)、[解冻合约命令](../operation_and_maintenance/console/console_commands.html#unfreezecontract) + +### 5.3 智能合约废止 + +当合约不再使用，且数据不再供访问，用户可以使用预留的selfdestruct进行合约销毁，合约管理员也可以使用合约废止功能主动将合约状态设定为废止。 + +**selfdestruct** + +字节码中有一个selfdestruct指令，用于销毁合约。所以只需要暴露出自毁接口即可。**注意：** 该过程不可逆，请酌情考虑后果。 + +```solidity +contract Mortal{ + + //自毁 + function destroy() public{ + selfdestruct(msg.sender); + } +} +``` + +**合约废止** + +```eval_rst +.. important:: + 兼容性说明：合约生命周期管理废止操作只能在节点版本3.2以上进行。 +``` + +**注意：** 该过程不可逆，请酌情考虑后果。 + +在执行合约状态的写操作时，将会确定交易发起人msg.sender是否为合约权限表记录的合约管理员，若不是则会拒绝。 + +合约管理员也可以通过控制台对合约进行冻结等操作，详情请看：[冻结合约命令](../operation_and_maintenance/console/console_commands.html#freezecontract) \ No newline at end of file diff --git a/3.x/zh_CN/docs/develop/index.md b/3.x/zh_CN/docs/develop/index.md new file mode 100644 index 000000000..7c8296a4e --- /dev/null +++ b/3.x/zh_CN/docs/develop/index.md @@ -0,0 +1,14 @@ +# 1. 应用开发指南 +标签： `应用开发` + +---- +应用开发部分旨在指导用户基于FISCO BCOS提供的丰富功能与组件，更快深入了解FISCO BCOS区块链以及使用相应组件进行开发。此部分主要包括以下部分： + +1. 区块链RPC接口：此部分为区块链应用开发者提供了Java API接口介绍，用户可通过此部分熟悉如何部署及调用合约。 +2. 账户使用与账户管理：此部分为区块链应用开发者具体介绍账户的创建、存储和使用方式，指导开发者可按需创建与操作账户。 +3. 合约生命周期与权限管理：此部分为应用开发者详细介绍合约从开发、部署、调用、升级、冻结再到废止的整个生命周期，以及在整个智能合约生命周期的参与角色与管理方法。 +4. 控制台部署调用合约：此部分介绍应用开发者如何下载配置控制台，并指导开发者如何通过控制台部署与调用合约。 +5. SmartDev应用开发组件：SmartDev开发组件为区块链应用开发者提供了全面的智能合约库，对于常用的功能，不必再重复造轮子，只需按需引用，就可以引入相应功能，为合约开发的效率和安全保驾护航。此部分旨在指导区块链应用开发者熟悉掌握SmartDev组件。 +6. 使用AMOP功能：FISCO BCSO提供AMOP功能（Advanced Messages Onchain Protocol），通过此部分介绍，指导用户利用AMOP协议与其它机构互传消息，通过指定接口接受系统推送消息。 +7. 使用群环签名与同态加密：FISCO BCOS以预编译合约的形式集成了同态加密、群/环签名验证功能，提供了多种隐私保护手段，开发者通可过此部分文档熟悉同态加密与群环签名算法，并了解如何使用此部分功能。 +8. 智能合约安全实践：介绍智能合约在编码、部署、运行、维护各个阶段的最佳实践以及应该使用的安全措施。 diff --git a/3.x/zh_CN/docs/develop/light_monitor.md b/3.x/zh_CN/docs/develop/light_monitor.md deleted file mode 100644 index b30db621f..000000000 --- a/3.x/zh_CN/docs/develop/light_monitor.md +++ /dev/null @@ -1,126 +0,0 @@ -# 监控工具 - -标签：``监控`` ``monitor`` - ----- - -## light_monitor.sh - -`FISCO-BCOS 3.0`区块链轻量级监控工具，可以监控区块链是否正常工作，也提供简单的接入用户告警系统的方式. - -- 监控共识是否正常. -- 监控区块同步是否正常. -- 监控磁盘空间. -- 对接告警系统，发送告警信息. - -### 使用 - -帮助: -`bash light_monitor.sh -h` - -```shell -$ bash light_monitor.sh -h -Usage: -Optional: - -g [Require] group id - -i [Require] rpc server ip - -p [Require] rpc server port - -t [Optional] block number far behind warning threshold, default: 30 - -d [Optional] disk directory to be monitor - -T [Optional] disk capacity alarm threshold, default: 5% - -h Help. -Example: - bash light_monitor.sh -i 127.0.0.1 -p 20200 -g group0 - bash light_monitor.sh -i 127.0.0.1 -p 20200 -g group0 -d /data -T 10 -``` - -**参数:** - -- `-g`: 监控的群组id，`rpc`接入多个群组时，可以部署多个light_monitor.sh，分别监控不同群组 -- `-i`: rpc ip -- `-p`: rpc port -- `-t`: 区块同步告警的阈值，共识节点之间的区块高度差值超过该阈值，说明共识或者区块同步异常，默认值`30` -- `-d`: 磁盘容量需要监控的目录 -- `-T`: 磁盘告警阈值，监控的磁盘剩余空间百分比小于该值时，触发告警，默认值`5%` -- `-h`: 帮助信息 - -#### 状态描述 - -**参数：** - -- $config_ip: rpc ip -- $config_port：rpc port -- $group: 群组id -- $height: 区块高度 - -**```OK! $config_ip:$config_port $node:$group is working properly: height $height```** - -群组`${group}`正常工作, 共识模块/区块同步正常工作 - -**```ERROR! Cannot connect to $config_ip:$config_port ${group}, method: xxxx```** - -调用`rpc`接口`xxxx`失败，`rpc`服务宕机, 严重错误，此时需要重启`rpc`服务 - -**```ERROR! Consensus timeout $config_ip:$config_port ${group}:${node}```** - -**群组共识超时，连续出现时为严重错误**。 -排查网络连接是否正常。 - -**```ERROR! insufficient disk capacity, monitor disk directory: ${dir}, left disk space percent: ${disk_space_left_percent}%```** - -磁盘空间不足，剩余`${disk_space_left_percent}%`的空间 - -为了能够持续监控区块链节点的状态, 将`light_monitor.sh`配置到`crontab`定期执行. - -```shell -# 每分钟执行一次，查看节点是否正常启动, 正常共识, 有无关键错误打印 -*/1 * * * * /data/app/127.0.0.1/light_monitor.sh >> /data/app/127.0.0.1/light_monitor.log 2>&1 -``` - -`light_monitor.log`保存`light_monitor.sh`的输出 - -**用户需要根据实际部署修改示例中的路径.** - -### 对接告警系统 - -- 接口 -`light_monitor.sh`对接告警系统的接口`alarm`, 默认实现如下： - -```shell -alarm() { - echo "$1" - alert_msg="$1" - alert_ip=$(/sbin/ifconfig eth0 | grep inet | grep -v inet6 | awk '{print $2}') - alert_time=$(date "+%Y-%m-%d %H:%M:%S") - - # TODO: alarm the message, mail or phone - - # echo "[${alert_time}]:[${alert_ip}]:${alert_msg}"| mail -s "fisco-bcos alarm message" xxxxxx@qq.com -} -``` - - `light_monitor.sh`执行触发的关键错误处都会调用该函数, 并将错误信息作为入参, 用户可以调用监控平台的API将错误信息发送至告警平台. - -- 示例 - - 假设用户的告警系统 - -- API: - `http://127.0.0.1:1111/alarm/request` - POST参数: - ```{'title':'告警主题','alert_ip':'告警服务器IP', 'alert_info':'告警内容'}``` - - 修改`alarm`函数： - -```shell -alarm() { - echo "$1" - alert_msg="$1" - alert_ip=$(/sbin/ifconfig eth0 | grep inet | grep -v inet6 | awk '{print $2}') - alert_time=$(date "+%Y-%m-%d %H:%M:%S") - - # TODO: alarm the message, mail or phone - - curl -H "Content-Type: application/json" -X POST --data "{'title':'alarm','alert_ip':'${alert_ip}','alert_info':'${alert_msg}'}" http://127.0.0.1:1111/alarm/request -} -``` diff --git a/3.x/zh_CN/docs/develop/precompiled/index.md b/3.x/zh_CN/docs/develop/precompiled/index.md deleted file mode 100644 index 91b2b1056..000000000 --- a/3.x/zh_CN/docs/develop/precompiled/index.md +++ /dev/null @@ -1,18 +0,0 @@ -# 预编译合约 - -标签：``预编译合约`` ``接口`` ``开发`` - ----------- - -```eval_rst -.. toctree:: - :maxdepth: 1 - - use_precompiled.md - precompiled_contract_api.md - precompiled_error_code.md - use_kv_precompiled.md - use_crud_precompiled.md - use_group_ring_sig.md - add_precompiled_impl.md -``` diff --git a/3.x/zh_CN/docs/develop/privacy.md b/3.x/zh_CN/docs/develop/privacy.md new file mode 100644 index 000000000..a0082c76c --- /dev/null +++ b/3.x/zh_CN/docs/develop/privacy.md @@ -0,0 +1,121 @@ +# 8. 使用同态加密与群环签名 + +标签：``隐私合约`` ``隐私保护`` ``合约开发`` ``同态加密`` ``环签名`` ``群签名`` + +---- +隐私保护是联盟链的一大技术挑战。为了保护链上数据、保障联盟成员隐私，并且保证监管的有效性，FISCO BCOS以预编译合约的形式集成了同态加密、群/环签名验证功能，提供了多种隐私保护手段。 + +文档一、二节分别对同态加密和群/环签名算法以及相关应用场景进行了简单介绍，第三、四节则详细介绍了FISCO BCOS隐私保护模块启用方法以及调用方式。 + + +```eval_rst +.. note:: + 1. FISCO BCOS 2.3.0+ 支持同态加密、群签名和环签名 + 2. FISCO BCOS 2.3.0， 2.4.0以及2.4.1，需手动编译二进制启用隐私保护模块 + 3. FISCO BCOS 2.5.0+ 默认启用隐私保护模块 +``` + +## 同态加密 + +### 算法简介 + +同态加密(Homomorphic Encryption)是公钥密码系统领域的明珠之一，已有四十余年的研究历史。其绝妙的密码特性，吸引密码学家前赴后继，在业界也受到了广泛的关注。 + +- 同态加密本质是一种公钥加密算法，即加密使用公钥pk，解密使用私钥sk； +- 同态加密支持密文计算，即由相同公钥加密生成的密文可以计算f( )操作，生成的新密文解密后恰好等于两个原始明文计算f( )的结果； +- 同态加密公式描述如下： + + + +FISCO BCOS采用的是paillier加密算法，支持加法同态。paillier的公私钥兼容主流的RSA加密算法，接入门槛低。同时paillier作为一种轻量级的同态加密算法，计算开销小易被业务系统接受。因此经过功能性和可用性的权衡，最终选定了paillier算法。 + + +### 功能组件 + +FISCO BCOS同态加密模块提供的功能组件包括： + +- paillier同态库[GitHub源码](https://github.com/FISCO-BCOS/paillier-lib)/[Gitee源码](https://gitee.com/FISCO-BCOS/paillier-lib)，包括java库和c++同态接口。 + +- paillier预编译合约，供智能合约调用，提供密文同态运算接口。 + +### 使用方式 + +对于有隐私保护需求的业务，如果涉及简单密文计算，可借助本模块实现相关功能。凡是上链的数据可通过调用paillier库完成加密，链上的密文数据可通过调用paillier预编译合约实现密文的同态加运算，密文返还回业务层后，可通过调用paillier库完成解密，得到执行结果。具体流程如下图所示： + + + +### 应用场景 + +在联盟链中，不同的业务场景需要配套不同的隐私保护策略。对于强隐私的业务，比如金融机构之间的对账，对资产数据进行加密是很有必要的。在FISCO BCOS中，用户可以调用同态加密库对数据进行加密，共识节点执行交易的时候调用同态加密预编译合约，得到密文计算的结果。 + + +## 群/环签名 + +### 算法简介 + +**群签名** + +群签名(Group Signature)是一种能保护签名者身份的具有相对匿名性的数字签名方案，用户可以代替自己所在的群对消息进行签名，而验证者可以验证该签名是否有效，但是并不知道签名属于哪一个群成员。同时，用户无法滥用这种匿名行为，因为群管理员可以通过群主私钥打开签名，暴露签名的归属信息。群签名的特性包括： + +- 匿名性：群成员用群参数产生签名，其他人仅可验证签名的有效性，并通过签名知道签名者所属群组，却无法获取签名者身份信息； +- 不可伪造性：只有群成员才能生成有效可被验证的群签名； +- 不可链接性：给定两个签名，无法判断它们是否来自同一个签名者； +- 可追踪性：在监管介入的场景中，群主可通过签名获取签名者身份。 + +**环签名** + +环签名(Ring Signature)是一种特殊的群签名方案，但具备完全匿名性，即不存在管理员这个角色，所有成员可主动加入环，且签名无法被打开。环签名的特性包括： + +- 不可伪造性：环中其他成员不能伪造真实签名者签名； +- 完全匿名性：没有群主，只有环成员，其他人仅可验证环签名的有效性，但没有人可以获取签名者身份信息。 + +### 功能组件 + +FISCO BCOS群/环签名模块提供的功能组件包括： + +- 群/环[签名库](https://github.com/FISCO-BCOS/group-signature-lib)，提供完整的群/环签名算法c++接口 + +- 群/环签名预编译合约，供智能合约调用，提供群/环签名验证接口。 + +### 使用方式 + +有签名者身份隐匿需求的业务可借助本模块实现相关功能。签名者通过调用群/环签名库完成对数据的签名，然后将签名上链，业务合约通过调用群/环签名预编译合约完成签名的验证，并将验证结果返还回业务层。如果是群签名，那么监管方还能打开指定签名数据，获得签名者身份。具体流程如下图所示： + + + +### 应用场景 + +群/环签名由于其天然的匿名性，在需要对参与者身份进行隐匿的场景中有广泛的应用前景，例如匿名投票、匿名竞拍、匿名拍卖等等，甚至在区块链UTXO模型中可用于实现匿名转账。同时，由于群签名具备可追踪性，可以用于需要监管介入的场景，监管方作为群主或者委托群主揭露签名者身份。 + +### 开发示例 + +FISCO BCOS专门为用户提供了群/环签名开发示例，包括： + +- 群/环签名服务端: 提供完整的群/环签名RPC服务。[GitHub源码](https://github.com/FISCO-BCOS/group-signature-server)、[Gitee源码](https://gitee.com/FISCO-BCOS/group-signature-server) + +- 群/环签名客户端: 调用RPC服务对数据进行签名，并提供签名上链以及链上验证等功能。[GitHub源码](https://github.com/FISCO-BCOS/group-signature-client/tree/master-2.0)、[Gitee源码](https://gitee.com/FISCO-BCOS/group-signature-client/tree/master-2.0) + +示例框架如下图所示，具体操作方法请参阅[客户端指南 Github链接](https://github.com/FISCO-BCOS/group-signature-client/tree/master-2.0)或[客户端指南 Gitee链接](https://gitee.com/FISCO-BCOS/group-signature-client/tree/master-2.0)。 + + + +## 启用方法 + +FISCO BCOS隐私保护模块是通过预编译合约实现的，默认被启用。 + +### 搭建联盟链 + +搭建本机4节点的[参考文档](../quick_start/air_installation.md)。 + +## 预编译合约接口 + +隐私模块的代码和用户开发的预编译合约都位于`FISCO-BCOS/bcos-executor/src/precompiled/extension`目录，因此隐私模块的调用方式和用户开发的预编译合约[调用流程](https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/manual/smart_contract.html#id12)相同，不过需要注意： + +已为隐私模块的预编译合约分配了地址，无需另行注册。隐私模块实现的预编译合约列表以及地址分配如下： + +源码可参考链接：[GitHub链接](https://github.com/FISCO-BCOS/FISCO-BCOS/tree/master/bcos-executor/src/precompiled/extension)、[Gitee链接](https://gitee.com/FISCO-BCOS/FISCO-BCOS/tree/master/bcos-executor/src/precompiled/extension) + + | 地址 | 功能 | 源码 | + | ------ | ---------- | ------------------------------------------------------------ | + | 0x5004 | 群签名 | GroupSigPrecompiled.cpp | + | 0x5005 | 环签名 | RingSigPrecompiled.cpp | diff --git a/3.x/zh_CN/docs/develop/sdk/c_sdk/api.md b/3.x/zh_CN/docs/develop/sdk/c_sdk/api.md deleted file mode 100644 index 505fdd315..000000000 --- a/3.x/zh_CN/docs/develop/sdk/c_sdk/api.md +++ /dev/null @@ -1,1139 +0,0 @@ -# 接口列表 - -标签：``c-sdk`` ``API`` - ----------- - -本章节介绍`c-sdk`的`API`列表，模块列表: - -- [基础操作](../c_sdk/api.html#id2) -- [错误处理](../c_sdk/api.html#id3) -- [RPC](../c_sdk/api.html#rpc) -- [AMOP](../c_sdk/api.html#amop) -- [EventSub](../c_sdk/api.html#eventsub) -- [工具类](../c_sdk/api.html#id4) - - [KeyPair](../c_sdk/api.html#keypair) - - [ABI编解码](../c_sdk/api.html#abi) - - [交易构造](../c_sdk/api.html#id5) - -## 1. 基础操作 - -本小节介绍`c-sdk`的基础操作，包括`sdk`对象的创建、启动、停止、释放。 - -### `bcos_sdk_version` - -- 原型: - - `const char* bcos_sdk_version()` -- 功能: - - 获取c-sdk的版本以及构建信息 -- 参数: - - 无 -- 返回: - - 字符串类型，包括c-sdk的版本以及构建信息，示例: - - ```shell - FISCO BCOS C SDK Version : 3.1.0 - Build Time : 20220915 11:11:11 - Build Type : Darwin/appleclang/Release - Git Branch : main - Git Commit : dbc82415510a0e59339faebcd72e540fe408d2d0 - ``` - -- 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 - -### `bcos_sdk_create` - -- 原型: - - `void* bcos_sdk_create(struct bcos_sdk_c_config* config)` -- 功能: - - 创建`sdk`对象指针 -- 参数: - - config: 配置对象, 参考[配置对象](./config.html#id2) -- 返回: - - 返回`sdk`指针 - - 失败返回`NULL`,可以调用`bcos_sdk_get_last_error`获取错误信息, 参考`bcos_sdk_get_last_error`接口介绍 -- 注意: - - 创建的`sdk`对象，需要由`bcos_sdk_destroy`接口释放，以免内存泄露 - -### `bcos_sdk_create_by_config_file` - -- 原型: - - `void* bcos_sdk_create_by_config_file(const char *config_file)` -- 功能: - - 创建`sdk`对象指针 -- 参数: - - config_file: 配置文件, 参考[配置文件](./config.html#id3) -- 返回: - - 返回`sdk`指针 - - 失败返回`NULL`,可以调用`bcos_sdk_get_last_error`获取错误信息, 参考`bcos_sdk_get_last_error`接口介绍 -- 注意: - - 创建的`sdk`对象，需要由`bcos_sdk_destroy`接口释放，以免内存泄露 - -### `bcos_sdk_start` - -- 原型: - - `void bcos_sdk_start(void* sdk)` -- 功能: - - 启动`sdk` -- 参数: - - sdk: `sdk`指针 -- 返回: - - 无, 可以使用`bcos_sdk_get_last_error`确认是否启动成功, 参考`bcos_sdk_get_last_error`介绍 - -### `bcos_sdk_stop` - -- 原型: - - `void bcos_sdk_stop(void* sdk)` -- 功能: - - 停止`sdk` -- 参数: - - sdk: `sdk`指针 -- 返回: - - 无 - -### `bcos_sdk_destroy` - -- 原型: - - `void bcos_sdk_destroy(void* sdk)` -- 功能: - - 停止并且释放`sdk` -- 参数: - - sdk: `sdk`指针 -- 返回: 无 - -### `bcos_sdk_c_free` - -- 原型: - - `void bcos_sdk_c_free(void* p)` -- 功能: - - 释放内存 -- 参数: - - p: 指针 -- 返回: 无 - -## 2. 错误处理 - -本小节介绍`c-sdk`的错误处理接口。 - -**注意: 这些接口仅仅对同步调用接口有效，异步接口的错误信息在回调中返回**。 - -### `bcos_sdk_is_last_opr_success` - -- 原型: - - `int bcos_sdk_is_last_opr_success()` -- 功能: - - 最近一次操作是否成功，等价于`bcos_sdk_get_last_error`返回结果不为0。 -- 参数: - - 无 -- 返回: - - 0: 操作失败 - - 1: 操作成功 - -### `bcos_sdk_get_last_error` - -- 原型: - - `int bcos_sdk_get_last_error()` -- 功能: - - 获取上一次操作的返回状态, 失败时可以调用`bcos_sdk_get_last_error_msg`获取错误描述信息 -- 参数: - - 无 -- 返回: - - 0: 成功, 其他表示错误码, 可以使用`bcos_sdk_get_last_error_msg`获取错误描述信息 - -### `bcos_sdk_get_last_error_msg` - -- 原型: - - `const char* bcos_sdk_get_last_error_msg()` -- 功能: - - 获取上一次操作的错误信息描述, 与`bcos_sdk_get_last_error`配合使用 -- 参数: - - 无 -- 返回: 错误描述信息 - -## 3. RPC接口 - -本小节介绍如何在`c-sdk`中调用`FISCO-BCOS 3.0`的`rpc`接口，与节点交互。 - -### `bcos_rpc_call` - -- 原型: - - `void bcos_rpc_call(void* sdk, const char* group, const char* node, const char* to, const char* data, bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 调用合约，查询操作，无需共识 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 请求发往的节点名称(节点名称可以通过`getGroupInfo`获取), 值为`NULL`或者空字符串时, 在群组中按最高块高的原则, 随机选择一个节点 - - `to`: 合约地址 - - `data`: 编码后的参数 - - 调用`solidity`合约时为`ABI`编码 - - 调用`liquid`合约时为`liquid`编码 - - `callback`: 回调函数, 函数原型: - - ```shell - typedef void (*bcos_sdk_c_struct_response_cb)(struct bcos_sdk_c_struct_response* resp) - ``` - - `bcos_sdk_c_struct_response`定义及字段含义: - - ```c - struct bcos_sdk_c_struct_response - { - int error; // 返回状态, 0成功, 其他失败 - char* desc; // 失败时描述错误信息 - - void* data; // 返回数据, error=0 时有效 - size_t size; // 返回数据大小, error=0 时有效 - - void* context; // 回调上下文,调用接口时传入的`context`参数 - }; - ``` - - **!!!注意: 回调的数据`data`仅在回调线程有效,多线程场景下,用户需自行拷贝保证数据的线程安全** - - `context`: 回调上下文, 在回调`bcos_sdk_c_struct_response`中`context`字段返回 -- 返回: - - 无 - -### `bcos_rpc_send_transaction` - -- 原型: - - `void bcos_rpc_send_transaction(void* sdk, const char* group, const char* node, const char* data, int proof, bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 发送交易，需要区块链共识 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `data`: 签名的交易，十六进制c风格字符串 - - `proof`: 是否返回交易回执证明, 0：不返回，1：返回 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_transaction` - -- 函数原型: `void bcos_rpc_get_transaction(void* sdk, const char* group, const char* node, const char* tx_hash,int proof, bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 根据交易哈希获取交易 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `tx_hash`: 交易哈希 - - `proof`: 是否返回交易证明, 0：不返回, 1：返回 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_transaction_receipt` - -- 原型: - - ```shell - void bcos_rpc_get_transaction_receipt(void* sdk, const char* group, const char* node, const char* tx_hash, int proof, bcos_sdk_c_struct_response_cb callback, void* context) - ``` - -- 功能: - - 根据交易哈希获取交易回执 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `tx_hash`: 交易哈希 - - `proof`: 是否返回交易回执证明, 0: 不返回,1: 返回 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_block_by_hash` - -- 原型: - - ```shell - void bcos_rpc_get_block_by_hash(void* sdk, const char* group, const char* node,const char* block_hash, int only_header, int only_tx_hash, bcos_sdk_c_struct_response_cb callback, void* context) - ``` - -- 功能: - - 根据区块哈希获取区块 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `block_hash`: 区块哈希 - - `only_header`: 是否只获取区块头, 1: 是, 0: 否 - - `only_tx_hash`: 是否只获取区块的交易哈希, 1: 是, 0: 否 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_block_by_number` - -- 原型: - - ```shell - void bcos_rpc_get_block_by_number(void* sdk, const char* group, const char* node, int64_t block_number, int only_header, int only_tx_hash, bcos_sdk_c_struct_response_cb callback, void* context) - ``` - -- 功能: - - 根据块高获取区块 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `block_number`: 区块高度 - - `only_header`: 是否只获取区块头, 1: 是, 0: 否 - - `only_tx_hash`: 是否只获取区块的交易哈希, 1: 是, 0: 否 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_block_hash_by_number` - -- 原型: - - `void bcos_rpc_get_block_hash_by_number(void* sdk, const char* group, const char* node, int64_t block_number, bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 根据块高获取区块哈希 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `block_number`: 区块高度 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: 无 - -### `bcos_rpc_get_block_limit` - -- 原型: - - `int64_t bcos_rpc_get_block_limit(void* sdk, const char* group)` -- 功能: - - 获取块高限制，创建签名交易时需要使用 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID -- 返回: - - `>0`时返回`block limit`值 - - `<=0`表示获取失败，此时表示查询不到该群组 - -### `bcos_rpc_get_block_number` - -- 原型: - - `void bcos_rpc_get_block_number(void* sdk, const char* group, const char* node,bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取群组块高 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_code` - -- 原型: - - `void bcos_rpc_get_code(void* sdk, const char* group, const char* node, const char* address,bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 根据合约地址,查询合约代码 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `address`: 合约地址 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: 无 - -### `bcos_rpc_get_sealer_list` - -- 原型: - - `void bcos_rpc_get_sealer_list(void* sdk, const char* group, const char* node,bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取群组共识节点列表 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_observer_list` - -- 原型: - - `void bcos_rpc_get_observer_list(void* sdk, const char* group, const char* node,bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取群组观察节点列表 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_pending_tx_size` - -- 原型: - - `void bcos_rpc_get_pending_tx_size(void* sdk, const char* group, const char* node,bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取交易池待打包的交易数量 -- 参数； - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 空 - -### `bcos_rpc_get_sync_status` - -- 原型: - - `void bcos_rpc_get_sync_status(void* sdk, const char* group, const char* node,bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取群组的区块同步状态 -- 参数； - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_consensus_status` - -- 原型: - - `void bcos_rpc_get_consensus_status(void* sdk, const char* group, const char* node,bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取节点的共识状态 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_system_config_by_key` - -- 原型: - - `void bcos_rpc_get_system_config_by_key(void* sdk, const char* group, const char* node,const char* key,bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取系统配置 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `key`: 配置`key` - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 空 - -### `bcos_rpc_get_total_transaction_count` - -- 原型: - - `void bcos_rpc_get_total_transaction_count(void* sdk, const char* group, const char* node, bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取当前区块高度下的交易总量 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `node`: 节点名称, 参考`bcos_rpc_call`接口对`node`的说明 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_group_peers` - -- 原型: - - `void bcos_rpc_get_group_peers(void* sdk, const char* group, bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取群组的网络连接信息 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_peers` - -- 原型: - - `void bcos_rpc_get_peers(void* sdk, bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取网关的`p2p`网络连接信息 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_group_list` - -- 原型: - - `void bcos_rpc_get_group_list(void* sdk, bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取群组列表 -- 参数: - - `sdk`: `sdk`指针 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_group_info` - -- 原型: - - `void bcos_rpc_get_group_info(void* sdk, const char* group, bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取群组信息 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 群组ID - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_group_info_list` - -- 原型: - - `void bcos_rpc_get_group_info_list(void* sdk, bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取群组列表详情 -- 参数: - - sdk: `sdk`指针 - - `callback`: 参考`bcos_rpc_call`接口对`context`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -### `bcos_rpc_get_group_node_info` - -- 原型: - - `void bcos_rpc_get_group_node_info(void* sdk, const char* group, const char* node,bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 获取群组的节点信息 -- 参数: - - sdk: `sdk`指针 - - group: 群组ID - - node: 节点名称 - - `callback`: 参考`bcos_rpc_call`接口对`callback`的说明 - - `context`: 参考`bcos_rpc_call`接口对`context`的说明 -- 返回: - - 无 - -## 4. AMOP接口 - -本小节介绍在`c-sdk`使用FISCO-BCOS 3.0`AMOP`功能的接口。 - -### `bcos_amop_subscribe_topic` - -- 原型: - - `void bcos_amop_subscribe_topic(void* sdk, char** topics, size_t count)` -- 功能: - - 订阅topic -- 参数: - - `sdk`: `sdk`指针 - - `topics`: topics内容 - - `count`: topics长度 -- 返回: - - 无 - -### `bcos_amop_subscribe_topic_with_cb` - -- 原型: - - `void bcos_amop_subscribe_topic_with_cb(void* sdk, const char* topic, bcos_sdk_c_amop_subscribe_cb cb, void* context)` -- 功能: - - 订阅`topic`，并设置接收`topic`消息的回调函数 -- 参数: - - `sdk`: `sdk`指针 - - `topic`: topic - - `cb`: 回调函数, 函数原型如下: - - ```shell - typedef void (*bcos_sdk_c_amop_subscribe_cb)( - const char* endpoint, const char* seq, struct bcos_sdk_c_struct_response* resp); - ``` - - 字段含义: - - endpoint: 接收消息的网络连接标记, 回复消息调用`bcos_amop_send_response`时需要使用 - - seq: 消息标记, 回复消息调用`bcos_amop_send_response`时需要使用 - - resp: 参考`bcos_rpc_call`接口`callback`对`bcos_sdk_c_struct_response`的说明 - - - `context`: 回调上下文, 参考`bcos_rpc_call`接口对`context`的说明 - -### `bcos_amop_set_subscribe_topic_cb` - -- 原型: - - `void bcos_amop_set_subscribe_topic_cb(void* sdk, bcos_sdk_c_amop_subscribe_cb cb, void* context)` -- 功能: - - 为`topic`设置回调函数，接收到的`topic`消息没有单独设置回调函数时，默认回调函数会被调用 -- 参数: - - `sdk`: `sdk`指针 - - `cb`: `topic`回调函数, 参考`bcos_amop_subscribe_topic_with_cb`接口对`cb`的说明 - - `context`: 回调上下文 - -### `bcos_amop_unsubscribe_topic` - -- 原型: - - `void bcos_amop_unsubscribe_topic(void* sdk, char** topics, size_t count)` -- 功能: - - 取消订阅 -- 参数: - - `sdk`: `sdk`指针 - - `topics`: topics内容 - - `count`: topics长度 - -### `bcos_amop_publish` - -- 原型: - - `void bcos_amop_publish(void* sdk, const char* topic, void* data, size_t size, uint32_t timeout,bcos_sdk_c_amop_publish_cb cb, void* context)` -- 功能: - - 发送`topic`消息 -- 参数: - - `sdk`: `sdk`指针 - - `topic`: topic - - `data`: 消息内容 - - `size`: 消息长度 - - `timeout`: 超时时间,单位ms - - `cb`: 回调函数, 函数原型如下: - - ```shell - typedef void (*bcos_sdk_c_amop_publish_cb)(struct bcos_sdk_c_struct_response* resp) - ``` - - - `context`: 回调上下文 - -### `bcos_amop_broadcast` - -- 原型: - - `void bcos_amop_broadcast(void* sdk, const char* topic, void* data, size_t size)` -- 功能: - - 发送`topic`广播消息 -- 参数: - - `sdk`: `sdk`指针 - - `topic`: topic - - `data`: 消息内容 - - `size`: 消息长度 - -### `bcos_amop_send_response` - -- 原型: - - `void bcos_amop_send_response(void* sdk, const char* peer, const char* seq, void* data, size_t size)` -- 功能: - - 发送回复消息 -- 参数: - - `sdk`: `sdk`指针 - - `peer`: 接收消息的网络连接标记, 参考`bcos_amop_subscribe_topic_with_cb`接口回调函数`cb`的字段`endpoint`说明 - - `seq`: 消息标记, 参考`bcos_amop_subscribe_topic_with_cb`接口回调函数`cb`的字段`seq`说明 - - `data`: 消息内容 - - `size`: 消息长度 - -## 5. EventSub接口 - -本小节介绍在`c-sdk`使用FISCO-BCOS 3.0`EventSub`事件订阅功能的接口。 - -### `bcos_event_sub_subscribe_event` - -- 原型: - - `const char* bcos_event_sub_subscribe_event(void* sdk, const char* group, const char* params,bcos_sdk_c_struct_response_cb callback, void* context)` -- 功能: - - 合约事件订阅 -- 参数: - - `sdk`: `sdk`指针 - - `group`: 请求群组ID - - `params`: 请求参数，c风格JSON字符串 - - addresses: 字符串数组，订阅Event的合约地址列表，为空时表示所有的合约 - - fromBlock: 整形，初始区块，-1表示从当前最高块开始 - - toBlock: 整形，结束区块，-1表示不限制区块高度，已经是最高块时也继续等待新的区块 - - topics: 字符串数组，订阅的topic列表，为空时表示所有的topic - - 示例: - - ```shell - { - "addresses": ["6849F21D1E455e9f0712b1e99Fa4FCD23758E8F1"], - "fromBlock": -1, - "toBlock": -1, - "topics": [] - } - ``` - - - `context`: 回调上下文 -- 返回: - - 合约事件订阅的任务id，c风格字符串 - -### `bcos_event_sub_unsubscribe_event` - -- 原型: - - `void bcos_event_sub_unsubscribe_event(void* sdk, const char* id)` -- 功能: - - 取消合约事件订阅 -- 参数: - - `sdk`: `sdk`指针 - - `id`: 合约事件订阅的任务id，`bcos_event_sub_subscribe_event`的返回值 - -## 6. 工具类 - -本小结介绍`c-sdk`的基础工具类的使用，包括`KeyPair`签名对象、`ABI`编解码、构造签名交易。 - -### 6.1 `KeyPair`签名对象 - -- `bcos_sdk_create_keypair` - - 原型: - - `void* bcos_sdk_create_keypair(int crypto_type)` - - 功能: - - 创建`KeyPair`对象 - - 参数: - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - `KeyPair`对象指针 - - 失败返回`NULL`，使用`bcos_sdk_get_last_error`、 `bcos_sdk_get_last_error_msg`获取错误码和错误描述信息 - - 注意: - - `KeyPair`对象不再使用时需要调用`bcos_sdk_destroy_keypair`接口释放，以免造成内存泄露 -- `bcos_sdk_create_keypair_by_private_key` - - 原型: - - `void* bcos_sdk_create_keypair_by_private_key(int crypto_type, void* private_key, unsigned length)` - - 功能: - - 加载私钥创建`KeyPair`对象 - - 参数: - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - private_key: 私钥，字节数组格式 - - length: 数组长度 - - 返回: - - `KeyPair`对象指针 - - 失败返回`NULL`使用`bcos_sdk_get_last_error`、 `bcos_sdk_get_last_error_msg`获取错误码和错误描述信息 - - 注意: - - `KeyPair`对象不再使用时需要调用`bcos_sdk_destroy_keypair`接口释放，以免造成内存泄露 -- `bcos_sdk_create_keypair_by_hex_private_key` - - 原型: - - `void* bcos_sdk_create_keypair_by_hex_private_key(int crypto_type, const char* private_key)` - - 功能: - - 加载私钥创建`KeyPair`对象 - - 参数: - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - private_key: 私钥，十六进制c风格字符串格式 - - 返回: - - `KeyPair`对象指针 - - 失败返回`NULL`，使用`bcos_sdk_get_last_error`、 `bcos_sdk_get_last_error_msg`获取错误码和错误描述信息 - - 注意: - - `KeyPair`对象不再使用时需要调用`bcos_sdk_destroy_keypair`接口释放，以免造成内存泄露 -- `bcos_sdk_get_keypair_type` - - 原型: - - `int bcos_sdk_get_keypair_type(void* key_pair)` - - 功能: - - 获取`KeyPair`对象类型 - - 参数: - - key_pair: `KeyPair`对象指针 - - 返回: - - 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) -- `bcos_sdk_get_keypair_address` - - 原型: - - `const char* bcos_sdk_get_keypair_address(void* key_pair)` - - 功能: - - 获取`KeyPair`对象对应的账户地址 - - 参数: - - key_pair: `KeyPair`对象指针 - - 返回: - - 账户地址，十六进制c风格字符串 - - 注意: - - 返回的字符串不使用时使用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_get_keypair_public_key` - - 原型: - - `const char* bcos_sdk_get_keypair_public_key(void* key_pair)` - - 功能: - - 获取`KeyPair`对象的公钥字符串 - - 参数: - - key_pair: `KeyPair`对象指针 - - 返回: - - 公钥，十六进制c风格字符串 - - 注意: - - 返回的字符串不使用时使用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_get_keypair_private_key` - - 原型: - - `const char* bcos_sdk_get_keypair_private_key(void* key_pair)` - - 功能: - - 获取`KeyPair`对象的私钥字符串 - - 参数: - - key_pair: `KeyPair`对象指针 - - 返回: - - 私钥，十六进制c风格字符串 - - 注意: - - 返回的字符串不使用时使用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_destroy_keypair` - - 原型: - - `void bcos_sdk_destroy_keypair(void* key_pair)` - - 功能: - - 释放`KeyPair`对象 - - 参数: - - key_pair: `KeyPair`对象指针 - - 返回: - - 无 - -### 6.2 `ABI`编解码 - -- `bcos_sdk_abi_encode_constructor` - - 原型: - - `const char* bcos_sdk_abi_encode_constructor(const char* abi, const char* bin, const char* params, int crypto_type)` - - 功能: - - 编码构造函数参数 - - 参数: - - abi: 合约ABI，JSON字符串 - - bin: 合约BIN，十六进制c风格字符串 - - params: 构造函数参数，JSON字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 编码后的参数，十六进制c风格字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 - -- `bcos_sdk_abi_encode_method` - - 原型: - - `const char* bcos_sdk_abi_encode_method(const char* abi, const char* method_name, const char* params, int crypto_type)` - - 功能: - - 编码接口参数 - - 参数: - - abi: 合约ABI，JSON字符串 - - method_name: 接口名 - - params: 构造函数的参数，JSON字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 编码后的参数，十六进制c风格字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_abi_encode_method_by_method_id` - - 原型: - - `const char* bcos_sdk_abi_encode_method_by_method_id(const char* abi, const char* method_id, const char* params, int crypto_type)` - - 功能: - - 根据methodID编码参数 - - 参数: - - abi: 合约ABI，JSON字符串 - - method_id: methodID - - params: 构造函数的参数，JSON字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 编码后的参数，十六进制c风格字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_abi_encode_method_by_method_sig` - - 原型: - - `const char* bcos_sdk_abi_encode_method_by_method_sig(const char* method_sig, const char* params, int crypto_type)` - - 功能: - - 根据接口signature编码参数 - - 参数: - - method_sig: 接口signature - - params: 构造函数的参数，JSON字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 编码后的参数，十六进制c风格字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_abi_decode_method_input` - - 原型: - - `const char* bcos_sdk_abi_decode_method_input(const char* abi, const char* method_name, const char* data, int crypto_type)` - - 功能: - - 根据接口名解析输入参数 - - 参数: - - abi: 合约ABI，JSON字符串 - - method_name: 接口名 - - data: 编码的参数，十六进制c风格字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 解析后的参数，十六进制c风格JSON字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_abi_decode_method_input_by_method_id` - - 原型: - - `const char* bcos_sdk_abi_decode_method_input_by_method_id(const char* abi, const char* method_id, const char* data, int crypto_type)` - - 功能: - - 根据methodID解析输入参数 - - 参数: - - abi: 合约ABI - - method_id: methodID - - data: ABI编码的参数，十六进制c风格字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 解析后的参数，十六进制c风格JSON字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_abi_decode_method_input_by_method_sig` - - 原型: - - `const char* bcos_sdk_abi_decode_method_input_by_method_sig(const char* method_sig, const char* data, int crypto_type)` - - 功能: - - 根据接口signature解析输入参数 - - 参数: - - method_sig: 接口signature - - data: 编码的参数，十六进制c风格字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 解析后的参数，十六进制c风格JSON字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_abi_decode_method_output` - - 原型: - - `const char* bcos_sdk_abi_decode_method_output(const char* abi, const char* method_name, const char* data, int crypto_type)` - - 功能: - - 根据接口名解析返回参数 - - 参数: - - abi: 合约ABI - - method_name: 接口名 - - data: 编码的返回，十六进制c风格字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 解析后的返回，十六进制c风格JSON字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_abi_decode_method_output_by_method_id` - - 原型: - - `const char* bcos_sdk_abi_decode_method_output_by_method_id(const char* abi, const char* method_id, const char* data, int crypto_type)` - - 功能: - - 根据methodID解析返回参数 - - 参数: - - abi: 合约ABI - - method_id: methodID - - data: 编码的返回，十六进制c风格字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 解析后的返回，十六进制c风格JSON字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_abi_decode_event` - - 原型: - - `const char* bcos_sdk_abi_decode_event(const char* abi, const char* event_name, const char* data, int crypto_type)` - - 功能: - - 根据event名解析event参数 - - 参数: - - abi: 合约ABI - - event_name: event名 - - data: 编码的返回，十六进制c风格字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 解析后的event参数，十六进制c风格JSON字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_abi_decode_event_by_topic` - - 原型: - - `const char* bcos_sdk_abi_decode_event_by_topic(const char* abi, const char* topic, const char* data, int crypto_type)` - - 功能: - - 根据topic解析event参数 - - 参数: - - abi: 合约ABI - - topic: event topic - - data: 编码的返回，十六进制c风格字符串 - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - 返回: - - 解析后的event参数，十六进制c风格JSON字符串 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 - -### 6.3 构造签名交易 - -- `bcos_sdk_get_group_wasm_and_crypto` - - 原型: - - `void bcos_sdk_get_group_wasm_and_crypto(void* sdk, const char* group_id, int* wasm, int* crypto_type)` - - 功能: - - 获取群组的部分基础信息 1. 群组运行`wasm`合约，还是`solidity`合约 2. 群组为国密还是非国密环境 - - 参数: - - `sdk`: sdk对象，`bcos_sdk_create`或者`bcos_sdk_create_by_config_file`创建 - - `group_id`: 群组ID - - `wasm`: 返回值，该群组是否运行`wasm`合约 - - 0: 否，群组运行`solidity`合约， - - 1: 是，群组运行`wasm`合约 - - `crypto_type`: 返回值，该群组是否为国密类型，0: 否，1: 是 - - 返回: - - 无 - -- `bcos_sdk_get_group_chain_id` - - 原型: - - `const char* bcos_sdk_get_group_chain_id(void* sdk, const char* group_id)` - - 功能: - - 获取群组的链ID，构造交易时需使用该参数 - - 参数: - - `sdk`: sdk对象，`bcos_sdk_create`或者`bcos_sdk_create_by_config_file`创建 - - `group_id`: 群组ID - - 返回: - - 群组的链ID - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 - -- `bcos_sdk_create_transaction_data` - - 原型: - - `void* bcos_sdk_create_transaction_data(const char* group_id, const char* chain_id, const char* to, const char* data, const char* abi, int64_t block_limit)` - - 功能: - - 创建`TransactionData`对象，该对象是未签名的交易对象 - - 参数: - - `group_id`: 群组ID - - `chain_id`: 链ID，可以调用`bcos_sdk_get_group_chain_id`接口获取群组的链ID - - `to`: 调用的合约地址，部署合约时设置为空字符串"" - - `data`: ABI编码后的参数，十六进制c风格字符串，参考[ABI编解码](../c_sdk/api.html#abi) - - `abi`: 合约的ABI，JSON字符串，可选参数，部署合约时可以将合约的ABI传入，默认传入空字符串"" - - `block_limit`: 区块限制，可以调用`bcos_rpc_get_block_limit`接口获取 - - 返回: - - `TransactionData`对象指针 - - 失败返回`NULL`，使用`bcos_sdk_get_last_error`、 `bcos_sdk_get_last_error_msg`获取错误码和错误描述信息 - - 注意: - - `TransactionData`对象需要调用`bcos_sdk_destroy_transaction_data`接口释放，以免造成内存泄露 - -- `bcos_sdk_destroy_transaction_data` - - 原型: - - `void bcos_sdk_destroy_transaction_data(void* transaction_data)` - - 功能: - - 释放`TransactionData`对象 - - 参数: - - `transaction_data`: `TransactionData`对象指针 - - 返回: - - 无 -- `bcos_sdk_calc_transaction_data_hash` - - 原型: - - `const char* bcos_sdk_calc_transaction_data_hash(int crypto_type, void* transaction_data)` - - 功能: - - 计算`TransactionData`对象哈希 - - 参数: - - crypto_type: 类型, ECDSA: BCOS_C_SDK_ECDSA_TYPE(0), SM: BCOS_C_SDK_SM_TYPE(1) - - `transaction_data`: `TransactionData`对象指针 - - 返回: - - `TransactionData`对象哈希 - - 失败返回`NULL`，使用`bcos_sdk_get_last_error`、 `bcos_sdk_get_last_error_msg`获取错误码和错误描述信息 - - 注意: - - **`TransactionData`对象的哈希，也是交易的哈希** - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 -- `bcos_sdk_sign_transaction_data_hash` - - 原型: - - `const char* bcos_sdk_sign_transaction_data_hash(void* keypair, const char* transcation_hash)` - - 功能: - - 交易哈希签名 - - 参数: - - keypair:`KeyPair`对象，参考[`KeyPair`签名对象](../c_sdk/api.html#keypair) - - transcation_hash: 交易哈希，由`bcos_sdk_calc_transaction_data_hash`接口生成 - - 返回: - - 交易签名，字符串类型 - - 失败返回`NULL`，调用`bcos_sdk_get_last_error`、 `bcos_sdk_get_last_error_msg`获取错误码和错误描述信息 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 - -- `bcos_sdk_create_signed_transaction_with_signed_data` - - 原型: - - ```shell - const char* bcos_sdk_create_signed_transaction_with_signed_data(void* transaction_data, const char* signed_transaction_data, const char* transaction_data_hash, int32_t attribute) - ``` - - - 功能: - - 创建签名的交易 - - 参数: - - transaction_data: `TransactionData`对象 - - signed_transaction_data: 交易哈希的签名，十六进制c风格字符串，`bcos_sdk_sign_transaction_data_hash`接口生成 - - transaction_data_hash: 交易哈希，十六进制c风格字符串，`bcos_sdk_calc_transaction_data_hash`接口生成 - - attribute: 交易额外属性，待拓展，默认填0即可 - - 返回: - - 签名的交易，十六进制c风格字符串 - - 失败返回`NULL`，调用`bcos_sdk_get_last_error`、 `bcos_sdk_get_last_error_msg`获取错误码和错误描述信息 - - 注意: - - 返回的字符串需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 - -- `bcos_sdk_create_signed_transaction` - - 原型: - - ```shell - void bcos_sdk_create_signed_transaction(void* key_pair, const char* group_id, const char* chain_id, const char* to, const char* data, const char* abi, int64_t block_limit, int32_t attribute, char** tx_hash, char** signed_tx) - ``` - - - 功能: - - 创建签名的交易 - - 参数: - - key_pair: `KeyPair`对象，参考[`KeyPair`签名对象](../c_sdk/api.html#keypair) - - group_id: 群组ID - - chain_id: 链ID，可以调用`bcos_sdk_get_group_chain_id`接口获取群组的链ID - - to: 调用的合约地址，部署合约时设置为空字符串"" - - data: ABI编码后的参数，参考[ABI编解码](../c_sdk/api.html#abi) - - abi: 合约的ABI，可选参数，部署合约时可以将合约的ABI传入，默认空字符串"" - - block_limit: 区块限制，可以调用`bcos_rpc_get_block_limit`接口获取 - - attribute: 交易额外属性，待拓展，默认填0即可 - - tx_hash: 返回值，交易哈希，十六进制c风格字符串 - - signed_tx: 返回值，签名的交易，十六进制c风格字符串 - - 返回: - - 调用`bcos_sdk_get_last_error`接口判断是否成功，0表示成功，其他值表示错误码 - - 注意: - - 返回的`tx_hash`、`signed_tx`需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 - - **说明**: - - `bcos_sdk_create_signed_transaction`相当于下面几个接口功能的组合，创建交易、交易哈希、交易签名流程需要分开处理时，使用下面几个接口: - - `bcos_sdk_create_transaction_data`: 创建`TransactionData` - - `bcos_sdk_calc_transaction_data_hash`: 计算交易哈希 - - `bcos_sdk_sign_transaction_data_hash`: 交易哈希签名 - - `bcos_sdk_create_signed_transaction_with_signed_data`: 创建签名的交易 - -- `bcos_sdk_create_transaction_builder_service` - - 原型: - - `void* bcos_sdk_create_transaction_builder_service(void* sdk, const char* group_id)` - - 功能: - - 创建`TransactionBuilderService`对象，简化构造签名交易的姿势，可以对比`bcos_sdk_create_transaction_data_with_tx_builder_service`与`bcos_sdk_create_transaction_data`接口的差异 - - 参数: - - sdk: sdk对象指针 - - group_id: 群组ID - - 返回: - - `TransactionBuilderService`对象指针 - - 失败返回`NULL`，调用`bcos_sdk_get_last_error`、 `bcos_sdk_get_last_error_msg`获取错误码和错误描述信息 - - 注意: - - `TransactionBuilderService`对象需要使用`bcos_sdk_destroy_transaction_builder_service`销毁，以免造成内存泄露 -- `bcos_sdk_destroy_transaction_builder_service` - - 原型: - - `bcos_sdk_destroy_transaction_builder_service(void* service)` - - 功能: - - 销毁`TransactionBuilderService`对象 - - 参数: - - `TransactionBuilderService`对象指针 - - 返回: - - 无 -- `bcos_sdk_create_transaction_data_with_tx_builder_service` - - 原型: - - `void* bcos_sdk_create_transaction_data_with_tx_builder_service(void* tx_builder_service, const char* to, const char* data, const char* abi)` - - 功能: - - 创建`TransactionData`对象 - - 参数: - - tx_builder_service: `TransactionBuilderService`对象指针 - - to: 调用的合约地址，部署合约时设置为空字符串"" - - data: ABI编码后的参数，参考[ABI编解码](../c_sdk/api.html#abi) - - abi: 合约的ABI，可选参数，部署合约时可以将合约的ABI传入，默认空字符串"" - - 返回: - - `TransactionData`对象指针 - - 失败返回`NULL`使用`bcos_sdk_get_last_error`、 `bcos_sdk_get_last_error_msg`获取错误码和错误描述信息 - - 注意: - - 创建的`TransactionData`对象需要由`bcos_sdk_destroy_transaction_data`接口释放，以免造成内存泄露 -- `bcos_sdk_create_signed_transaction_with_tx_builder_service` - - 原型: - - ```shell - void bcos_sdk_create_signed_transaction_with_tx_builder_service(void*tx_builder_service, void* key_pair, const char*to, const char* data, const char* abi, int32_t attribute, char** tx_hash, char** signed_tx) - ``` - - - 功能: - - 创建签名的交易 - - 参数: - - tx_builder_service: `TransactionBuilderService`对象指针 - - key_pair: `KeyPair`对象，参考[`KeyPair`签名对象](../c_sdk/api.html#keypair) - - to: 调用的合约地址，部署合约时设置为空字符串"" - - data: ABI编码后的参数，参考[ABI编解码](../c_sdk/api.html#abi) - - abi: 合约的ABI，可选参数，部署合约时可以将合约的ABI传入，默认空字符串"" - - attribute: 交易额外属性，待拓展，默认填0即可 - - tx_hash: 返回值，交易哈希，十六进制c风格字符串 - - signed_tx: 返回值，签名的交易，十六进制c风格字符串 - - 注意: - - 返回的`tx_hash`、`signed_tx`需要调用`bcos_sdk_c_free`释放，以免造成内存泄露 diff --git a/3.x/zh_CN/docs/develop/sdk/c_sdk/dylibs.md b/3.x/zh_CN/docs/develop/sdk/c_sdk/dylibs.md deleted file mode 100644 index 3740fb7e7..000000000 --- a/3.x/zh_CN/docs/develop/sdk/c_sdk/dylibs.md +++ /dev/null @@ -1,28 +0,0 @@ -# 动态库 - -标签：``c-sdk`` ``dynamic library`` - ----------- - -## 动态库 - - `bcos-c-sdk`已经提供了各个平台的动态库, 用户可以直接下载使用: - -- bcos-c-sdk.dll # windows dll - - [github下载](https://github.com/FISCO-BCOS/bcos-c-sdk/releases/download/v3.0.1/bcos-c-sdk.dll) - - [CDN下载](https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/c-sdk/releases/v3.0.1/bcos-c-sdk.dll) -- bcos-c-sdk.lib # windows dll symbol - - [github下载](https://github.com/FISCO-BCOS/bcos-c-sdk/releases/download/v3.0.1/bcos-c-sdk.lib) - - [CDN下载](https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/c-sdk/releases/v3.0.1/bcos-c-sdk.lib) -- libbcos-c-sdk-aarch64.so # linux arm64 - - [github下载](https://github.com/FISCO-BCOS/bcos-c-sdk/releases/download/v3.0.1/libbcos-c-sdk-aarch64.so) - - [CDN下载](https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/c-sdk/releases/v3.0.1/libbcos-c-sdk-aarch64.so) -- libbcos-c-sdk.so # linux x64 - - [github下载](https://github.com/FISCO-BCOS/bcos-c-sdk/releases/download/v3.0.1/libbcos-c-sdk.so) - - [CDN下载](https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/c-sdk/releases/v3.0.1/libbcos-c-sdk.so) -- libbcos-c-sdk-aarch64.dylib # mac m1 - - [github下载](https://github.com/FISCO-BCOS/bcos-c-sdk/releases/download/v3.0.1/libbcos-c-sdk-aarch64.dylib) - - [CDN下载](https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/c-sdk/releases/v3.0.1/libbcos-c-sdk-aarch64.dylib) -- libbcos-c-sdk.dylib # mac x64 - - [github下载](https://github.com/FISCO-BCOS/bcos-c-sdk/releases/download/v3.0.1/libbcos-c-sdk.dylib) - - [CDN下载](https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/c-sdk/releases/v3.0.1/libbcos-c-sdk.dylib) diff --git a/3.x/zh_CN/docs/develop/sdk/c_sdk/index.md b/3.x/zh_CN/docs/develop/sdk/c_sdk/index.md deleted file mode 100644 index 78ed42ba1..000000000 --- a/3.x/zh_CN/docs/develop/sdk/c_sdk/index.md +++ /dev/null @@ -1,21 +0,0 @@ -# C SDK - -标签：``c-sdk`` ``区块链应用`` - ----------- - -`c-sdk`是FISCO-BCOS 3.0实现的c版本的sdk, 提供c风格的访问区块链的接口,支持rpc、amop和合约事件订阅等基础功能。用户可以用于开发c语言的区块链应用,也可以方便其他开发人员在c sdk基础上进行封装,快速开发其他语言版本的sdk。 - -```eval_rst -.. toctree:: - :maxdepth: 1 - - env.md - compile.md - dylibs.md - config.md - api.md - dev.md - appendix.md - faq.md -``` diff --git a/3.x/zh_CN/docs/develop/sdk/cpp_sdk/index.md b/3.x/zh_CN/docs/develop/sdk/cpp_sdk/index.md deleted file mode 100644 index 56aaa0780..000000000 --- a/3.x/zh_CN/docs/develop/sdk/cpp_sdk/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# CPP SDK - -标签：``cpp-sdk`` ``区块链应用`` - ----- \ No newline at end of file diff --git a/3.x/zh_CN/docs/develop/sdk/index.md b/3.x/zh_CN/docs/develop/sdk/index.md deleted file mode 100644 index c9587f2f1..000000000 --- a/3.x/zh_CN/docs/develop/sdk/index.md +++ /dev/null @@ -1,33 +0,0 @@ -# 多语言SDK - -标签： ``SDK`` - ----- - -```eval_rst -.. important:: - 相关软件和环境版本说明！`请查看