FISCO BCOS系统合约介绍

作者：fisco-dev

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

设计概述

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

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

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

模块图

实现概述

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

系统代理合约

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

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

主要接口如下：

节点管理合约

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

在FISCO 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;#区块高度
    }

主要接口如下：

机构证书合约

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

机构证书的数据结构是：

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

主要接口如下：

权限管理合约

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

当前FISCO 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标志位。

主要接口如下：

全网配置合约

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

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

主要接口如下：

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

自定义扩展

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

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

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

• 至此，业务配置合约已经完成在系统代理合约的路由注册，已可在业务交易中调用。业务配置合约的使用方法：

• 调用SystemProxy的getRoute接口运行时获得业务配置合约地址。

• 通过业务配置合约地址调用查询配置值接口get获得配置值。

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

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

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