Skip to content

Commit 8584147

Browse files
toxotguotoxotguo
committed
BCOS系统合约介绍
1 parent e2e1e44 commit 8584147

File tree

3 files changed

+197
-0
lines changed

3 files changed

+197
-0
lines changed

‎BCOS系统合约介绍.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
2+
3+
# BCOS系统合约介绍
4+
<!-- TOC -->
5+
6+
- [BCOS系统合约介绍](#bcos系统合约介绍)
7+
- [设计概述](#设计概述)
8+
- [实现概述](#实现概述)
9+
- [系统代理合约](#系统代理合约)
10+
- [节点管理合约](#节点管理合约)
11+
- [机构证书合约](#机构证书合约)
12+
- [权限管理合约](#权限管理合约)
13+
- [全网配置合约](#全网配置合约)
14+
- [自定义扩展](#自定义扩展)
15+
- [示例1-自定义业务配置合约](#示例1-自定义业务配置合约)
16+
- [示例2-自定义业务权限Filter合约](#示例2-自定义业务权限filter合约)
17+
18+
<!-- /TOC -->
19+
20+
## 设计概述
21+
22+
BCOS区块链为了满足准入控制、身份认证、配置管理、权限管理等需求，在网络启动之初，会部署一套功能强大、结构灵活且支持自定义扩展的智能合约，统称系统合约。
23+
24+
系统合约原则上由区块链管理员在网络启动之初部署全网生效。若是在网络运行期间重新部署变更升级，则需要在全网所有节点许可的情况下由区块链管理员来执行操作。
25+
26+
当前BCOS系统合约主要有五个模块，系统代理模块、节点管理模块、机构证书模块、权限管理模块、全网配置模块。系统合约模块可以根据需要自定义扩展，它既可以供区块链核心调用也可以对DAPP提供服务。每个模块由一个或多个智能合约来实现。模块结构图如下：
27+
28+
![模块图](./images/systemcontract_module.png)
29+
30+
## 实现概述
31+
32+
当前BCOS对系统代理模块、节点管理模块、机构证书模块、权限管理模块、全网配置模块都做了对应的合约实现。合约源代码目录为systemcontractv2/。下面依次介绍各个合约实现的接口与逻辑。
33+
34+
### 系统代理合约
35+
36+
SystemProxy.sol是系统代理模块的实现合约。它实现了路由到合约地址的命名服务，提供了系统合约的统一入口。内部实现中是通过mapping类型成员变量_routes来维护所有的路由表信息。路由表信息项的数据结构主要是：
37+
38+
```
39+
struct SystemContract {
40+
address _addr; #合约地址
41+
bool _cache; #缓存标志位
42+
uint _blocknumber; #生效区块高度
43+
}
44+
```
45+
46+
主要接口如下：
47+
48+
| 接口 | 输入参数 | 输出参数 | 说明 |
49+
| -------- | :--------------------------------------- | -------------------------------------- | -------------------- |
50+
| getRoute | string key#路由名称 | address, bool,uint # 合约地址，缓存标志位，生效区块高度 | 获取路由信息 |
51+
| setRoute | string key, address addr, bool cache# 路由名称，合约地址，缓存标志位，生效区块高度 | 无 | 设置路由信息，若该路由名称已存在，则覆盖 |
52+
53+
54+
55+
### 节点管理合约
56+
57+
NodeAction.sol是节点管理模块的实现合约。它实现了对网络中所有节点列表信息的登记、管理、维护功能。每当网络中有节点加入或退出都必须与节点管理合约进行交互。
58+
59+
在BCOS中节点分为三种类型：核心节点、全节点、轻节点。
60+
61+
```
62+
enum NodeType{
63+
None,
64+
Core, //核心
65+
Full, //全节点
66+
Light //轻节点
67+
}
68+
```
69+
70+
节点信息的数据结构是：
71+
72+
```
73+
struct NodeInfo{
74+
string id; #节点身份ID
75+
string ip; #机器IP
76+
uint port; #机器端口
77+
NodeType category; #节点类型
78+
string desc; #节点描述
79+
string CAhash; #节点机构证书哈希
80+
string agencyinfo; #节点其他信息
81+
uint idx; #节点序号
82+
uint blocknumber;#区块高度
83+
}
84+
```
85+
86+
主要接口如下：
87+
88+
| 接口 | 输入参数 | 输出参数 | 说明 |
89+
| ------------ | :--------------------------------------- | ---------- | ------------------- |
90+
| registerNode | string _id,string _ip,uint _port,NodeType _category,string _desc,string _CAhash,string _agencyinfo,uint _idx #节点身份ID、IP、端口、节点类型、节点描述、节点CA哈希、节点agency、节点序号 | bool #注册结果 | 注册节点 ，若该节点信息已存在，则忽略 |
91+
| cancelNode | string _id #节点身份ID | bool #注册结果 | 注销节点，若该节点信息不存在，则忽略 |
92+
93+
94+
95+
### 机构证书合约
96+
97+
CAAction.sol是机构证书模块的实现合约。它实现了对网络中所有节点的机构证书信息的登记、管理、维护功能。当网络启用机构证书验证功能的情况下，网络中节点加入或退出都需要与机构证书合约进行交互。
98+
99+
机构证书的数据结构是：
100+
101+
```
102+
struct CaInfo{
103+
string hash; #节点机构证书哈希
104+
string pubkey; #证书公钥
105+
string orgname; #机构名称
106+
uint notbefore; #证书启用日期
107+
uint notafter; #证书失效时间
108+
CaStatus status; #证书状态
109+
string whitelist;#IP白名单
110+
string blacklist;#IP黑名单
111+
uint blocknumber;#生效区块高度
112+
}
113+
```
114+
115+
主要接口如下：
116+
117+
| 接口 | 输入参数 | 输出参数 | 说明 |
118+
| ------ | ---------------------------------------- | ---------------------------------------- | ------------------------- |
119+
| update | string _hash,string _pubkey,string _orgname,uint _notbefore,uint _notafter,CaStatus _status,string _whitelist,string _blacklist # 证书哈希、证书公钥、机构名称、 证书启用日期、 证书失效时间、证书状态、IP白名单、IP黑名单 | bool #更新结果 | 更新证书信息， 若该证书信息不存在，则新建证书记录 |
120+
| get | string _hash#证书哈希 | string,string,string,uint,uint,CaStatus,uint# 证书哈希、证书公钥、机构名称、证书启用日期、证书失效时间、证书状态、生效区块块号 | 查询证书信息 |
121+
122+
123+
124+
### 权限管理合约
125+
126+
BCOS基于角色的身份权限设计有三要点：一个外部账户只属于一个角色；一个角色拥有一个权限项列表； 一个权限项由合约地址加上合约接口来唯一标识。
127+
128+
当前BCOS权限管理模块主要由TransactionFilterChain.sol、TransactionFilterBase.sol、AuthorityFilter.sol、Group.sol四个合约来实现。
129+
130+
TransactionFilterChain是对Filter模型的实现框架。它在内部维护了一个实现继承于TransactionFilterBase的Filter合约地址列表。它对区块链核心提供了统一的权限检查接口process。process执行过程中会对Filter合约地址列表中的所有Filter依次执行process函数，以完成所有需要的权限检查。
131+
132+
TransactionFilterBase是Filter的基类合约。所有Filter必须要实现它的process接口。AuthorityFilter是继承于TransactionFilterBase的角色权限Filter实现。它的process接口实现了对用户所属角色组的权限项进行检查逻辑。
133+
134+
Group是对角色的实现。它内部维护了该角色的所有权限项的mapping标志位。
135+
136+
主要接口如下：
137+
138+
| 合约 | 接口 | 输入参数 | 输出参数 | 说明 |
139+
| --------------------- | ------------- | ---------------------------------------- | --------- | ------- |
140+
| TransactionFilterBase | process | address origin, address from, address to, string func, string input# 用户外部账户、交易发起账户、合约地址、合约接口、交易输入数据 | bool#处理结果 | 权限检查 |
141+
| Group | setPermission | address to, string func, bool perrmission# 合约地址、合约接口、权限标记 | bool#处理结果 | 设置角色权限项 |
142+
143+
144+
145+
### 全网配置合约
146+
147+
ConfigAction.sol是全网配置模块的实现合约。它维护了BCOS区块链中全网运行的可配置信息。 配置信息可以通过交易广播上链来达到全网配置的一致性更新。原则上只能由区块链管理员来发出全网配置更新交易。
148+
149+
ConfigAction.sol的内部实现中维护了配置项信息的mapping 成员变量。
150+
151+
主要接口如下：
152+
153+
| 接口 | 输入参数 | 输出参数 | 说明 |
154+
| ---- | --------------------------------- | ------------------------ | ----- |
155+
| set | string key, string value# 配置项、配置值 | 无 | 设置配置项 |
156+
| get | string key #配置项 | string, uint# 配置值、生效区块高度 | 查询配置值 |
157+
158+
当前BCOS主要有以下全网配置项：
159+
160+
| 配置项 | 说明 | 默认值 | 推荐值 |
161+
| -------------------- | ---------------------------- | --------- | ----------- |
162+
| maxBlockHeadGas | 块最大GAS （16进制） | 200000000 | 20000000000 |
163+
| intervalBlockTime | 块间隔(ms) （16进制） | 1000 | 1000 |
164+
| maxBlockTranscations | 块最大交易数（16进制） | 1000 | 1000 |
165+
| maxNonceCheckBlock | 交易nonce检查最大块范围（16进制） | 1000 | 1000 |
166+
| maxBlockLimit | blockLimit超过当前块号的偏移最大值（16进制） | 1000 | 1000 |
167+
| maxTranscationGas | 交易的最大gas（16进制） | 20000000 | 20000000 |
168+
| CAVerify | CA验证开关 | FALSE | FALSE |
169+
170+
## 自定义扩展
171+
172+
### 示例1-自定义业务配置合约
173+
174+
假设业务需要利用系统合约框架，自定义业务配置合约以对业务相关合约提供配置服务。大体可以参考以下步骤来扩展：
175+
176+
1. 根据业务合约需求，实现业务配置合约的设置配置项接口set和查询配置值接口get。
177+
2. 部署业务配置合约，获得业务配置合约链上地址。
178+
3. 调用系统代理合约SystemProxy的setRoute接口，将业务配置合约地址注册到路由表中。
179+
4. 至此，业务配置合约已经完成在系统代理合约的路由注册，已可在业务交易中调用。
180+
181+
业务配置合约的使用方法：
182+
183+
1. 调用SystemProxy的getRoute接口运行时获得业务配置合约地址。
184+
2. 通过业务配置合约地址调用查询配置值接口get获得配置值。
185+
186+
### 示例2-自定义业务权限Filter合约
187+
188+
假设业务需要增加业务权限校验逻辑，则可以利用权限管理合约的Filter机制来无缝扩展。大体可以参考以下步骤来扩展：
189+
190+
1. 继承于TransactionFilterBase实现一个业务权限Filter合约，业务权限Filter合约根据业务需要的权限校验逻辑实现process接口。
191+
2. 部署业务权限Filter合约，获得对应的合约地址。
192+
3. 调用系统代理合约SystemProxy的getRoute接口，获得TransactionFilterChain合约地址。
193+
4. 调用TransactionFilterChain合约的addFilter接口，将业务权限Filter合约地址注册到Filter合约列表中。
194+
5. 至此，业务权限Filter合约已经启用。
195+
196+

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ BCOS 开发指南（非官方）
1414

1515
第二章 [节点动态入网、退网](https://github.com/toxotguo/BCOS-Development-Guide/blob/master/chapter-02.md)
1616

17+
BCOS系统合约介绍 [BCOS系统合约介绍](https://github.com/toxotguo/BCOS-Development-Guide/blob/master/BCOS系统合约介绍.md)

‎images/systemcontract_module.png‎

30.2 KB
Loading

0 commit comments

Comments
 (0)