BCOS系统合约介绍

BCOS系统合约介绍
- 设计概述
- 实现概述
  - 系统代理合约
  - 节点管理合约
  - 机构证书合约
  - 权限管理合约
  - 全网配置合约
- 自定义扩展
  - 示例1-自定义业务配置合约
  - 示例2-自定义业务权限Filter合约

设计概述

BCOS区块链为了满足准入控制、身份认证、配置管理、权限管理等需求，在网络启动之初，会部署一套功能强大、结构灵活且支持自定义扩展的智能合约，统称系统合约。

系统合约原则上由区块链管理员在网络启动之初部署全网生效。若是在网络运行期间重新部署变更升级，则需要在全网所有节点许可的情况下由区块链管理员来执行操作。

当前BCOS系统合约主要有五个模块，系统代理模块、节点管理模块、机构证书模块、权限管理模块、全网配置模块。系统合约模块可以根据需要自定义扩展，它既可以供区块链核心调用也可以对DAPP提供服务。每个模块由一个或多个智能合约来实现。模块结构图如下：

实现概述

当前BCOS对系统代理模块、节点管理模块、机构证书模块、权限管理模块、全网配置模块都做了对应的合约实现。合约源代码目录为systemcontractv2/。下面依次介绍各个合约实现的接口与逻辑。

系统代理合约

SystemProxy.sol是系统代理模块的实现合约。它实现了路由到合约地址的命名服务，提供了系统合约的统一入口。内部实现中是通过mapping类型成员变量_routes来维护所有的路由表信息。路由表信息项的数据结构主要是：

struct SystemContract {address _addr;        #合约地址bool _cache;       #缓存标志位uint _blocknumber;    #生效区块高度}

主要接口如下：

接口	输入参数	输出参数	说明
getRoute	string key#路由名称	address, bool,uint # 合约地址，缓存标志位，生效区块高度	获取路由信息
setRoute	string key, address addr, bool cache# 路由名称，合约地址，缓存标志位，生效区块高度	无	设置路由信息，若该路由名称已存在，则覆盖

节点管理合约

NodeAction.sol是节点管理模块的实现合约。它实现了对网络中所有节点列表信息的登记、管理、维护功能。每当网络中有节点加入或退出都必须与节点管理合约进行交互。

在BCOS中节点分为三种类型：核心节点、全节点、轻节点。

enum NodeType{None,Core,   //核心 Full,   //全节点 Light   //轻节点 }

节点信息的数据结构是：

struct NodeInfo{string       id;         #节点身份ID    string       ip;         #机器IP       uint        port;       #机器端口NodeType    category;  #节点类型string     desc;       #节点描述 string        CAhash;     #节点机构证书哈希string     agencyinfo; #节点其他信息uint     idx;        #节点序号uint       blocknumber;#区块高度}

主要接口如下：

接口	输入参数	输出参数	说明
registerNode	string _id,string _ip,uint _port,NodeType _category,string _desc,string _CAhash,string _agencyinfo,uint _idx #节点身份ID、IP、端口、节点类型、节点描述、节点CA哈希、节点agency、节点序号	bool #注册结果	注册节点，若该节点信息已存在，则忽略
cancelNode	string _id #节点身份ID	bool #注册结果	注销节点，若该节点信息不存在，则忽略

机构证书合约

CAAction.sol是机构证书模块的实现合约。它实现了对网络中所有节点的机构证书信息的登记、管理、维护功能。当网络启用机构证书验证功能的情况下，网络中节点加入或退出都需要与机构证书合约进行交互。

机构证书的数据结构是：

struct CaInfo{string  hash;      #节点机构证书哈希string pubkey;     #证书公钥string orgname;        #机构名称uint notbefore;        #证书启用日期uint notafter;       #证书失效时间CaStatus status; #证书状态string    whitelist;#IP白名单string    blacklist;#IP黑名单uint    blocknumber;#生效区块高度}

主要接口如下：

接口	输入参数	输出参数	说明
update	string _hash,string _pubkey,string _orgname,uint _notbefore,uint _notafter,CaStatus _status,string _whitelist,string _blacklist # 证书哈希、证书公钥、机构名称、证书启用日期、证书失效时间、证书状态、IP白名单、IP黑名单	bool #更新结果	更新证书信息，若该证书信息不存在，则新建证书记录
get	string _hash#证书哈希	string,string,string,uint,uint,CaStatus,uint# 证书哈希、证书公钥、机构名称、证书启用日期、证书失效时间、证书状态、生效区块块号	查询证书信息

权限管理合约

BCOS基于角色的身份权限设计有三要点：一个外部账户只属于一个角色；一个角色拥有一个权限项列表；一个权限项由合约地址加上合约接口来唯一标识。

当前BCOS权限管理模块主要由TransactionFilterChain.sol、TransactionFilterBase.sol、AuthorityFilter.sol、Group.sol四个合约来实现。

TransactionFilterChain是对Filter模型的实现框架。它在内部维护了一个实现继承于TransactionFilterBase的Filter合约地址列表。它对区块链核心提供了统一的权限检查接口process。process执行过程中会对Filter合约地址列表中的所有Filter依次执行process函数，以完成所有需要的权限检查。

TransactionFilterBase是Filter的基类合约。所有Filter必须要实现它的process接口。AuthorityFilter是继承于TransactionFilterBase的角色权限Filter实现。它的process接口实现了对用户所属角色组的权限项进行检查逻辑。

Group是对角色的实现。它内部维护了该角色的所有权限项的mapping标志位。

主要接口如下：

合约	接口	输入参数	输出参数	说明
TransactionFilterBase	process	address origin, address from, address to, string func, string input# 用户外部账户、交易发起账户、合约地址、合约接口、交易输入数据	bool#处理结果	权限检查
Group	setPermission	address to, string func, bool perrmission# 合约地址、合约接口、权限标记	bool#处理结果	设置角色权限项

全网配置合约

ConfigAction.sol是全网配置模块的实现合约。它维护了BCOS区块链中全网运行的可配置信息。配置信息可以通过交易广播上链来达到全网配置的一致性更新。原则上只能由区块链管理员来发出全网配置更新交易。

ConfigAction.sol的内部实现中维护了配置项信息的mapping 成员变量。

主要接口如下：

接口	输入参数	输出参数	说明
set	string key, string value# 配置项、配置值	无	设置配置项
get	string key #配置项	string, uint# 配置值、生效区块高度	查询配置值

当前BCOS主要有以下全网配置项：

配置项	说明	默认值	推荐值
maxBlockHeadGas	块最大GAS （16进制）	200000000	20000000000
intervalBlockTime	块间隔(ms) （16进制）	1000	1000
maxBlockTranscations	块最大交易数（16进制）	1000	1000
maxNonceCheckBlock	交易nonce检查最大块范围（16进制）	1000	1000
maxBlockLimit	blockLimit超过当前块号的偏移最大值（16进制）	1000	1000
maxTranscationGas	交易的最大gas（16进制）	20000000	20000000
CAVerify	CA验证开关	FALSE	FALSE

自定义扩展

示例1-自定义业务配置合约

假设业务需要利用系统合约框架，自定义业务配置合约以对业务相关合约提供配置服务。大体可以参考以下步骤来扩展：

根据业务合约需求，实现业务配置合约的设置配置项接口set和查询配置值接口get。
部署业务配置合约，获得业务配置合约链上地址。
调用系统代理合约SystemProxy的setRoute接口，将业务配置合约地址注册到路由表中。
至此，业务配置合约已经完成在系统代理合约的路由注册，已可在业务交易中调用。

业务配置合约的使用方法：

调用SystemProxy的getRoute接口运行时获得业务配置合约地址。
通过业务配置合约地址调用查询配置值接口get获得配置值。

示例2-自定义业务权限Filter合约

假设业务需要增加业务权限校验逻辑，则可以利用权限管理合约的Filter机制来无缝扩展。大体可以参考以下步骤来扩展：

继承于TransactionFilterBase实现一个业务权限Filter合约，业务权限Filter合约根据业务需要的权限校验逻辑实现process接口。
部署业务权限Filter合约，获得对应的合约地址。
调用系统代理合约SystemProxy的getRoute接口，获得TransactionFilterChain合约地址。
调用TransactionFilterChain合约的addFilter接口，将业务权限Filter合约地址注册到Filter合约列表中。

至此，业务权限Filter合约已经启用。

https://github.com/toxotguo/BCOS-Development-Guide/blob/master/BCOS%E7%B3%BB%E7%BB%9F%E5%90%88%E7%BA%A6%E4%BB%8B%E7%BB%8D.md