Node access management

This chapter will give a brief introduction on node access management. For implementation methods please read Node access management


Single-chain multi-ledger

Blockchain is a technology with decentralized and transparent distributed data storage which has lower cost in trust and highly reliability of data interaction. But meanwhile, the transaction data of blockchain faces threat of leakage:

  • for public chain, any nodes can join some network and acquire all data from global ledger;
  • for consortium chain, through there is network access mechanism, nodes can still acquire data from global ledger once joined blockchain.

FISCO BCOS, as a consortium chain, has proposed Single-chain multi-ledger solution to solve the privacy issue. It has also adopted Group concept, transferring the traditional storage/execution mechanism from one-chain one-ledger to one chain and multi-ledger and realizing independency and secrecy of data on a chain based on groups.



As the above diagram shows, node A, B, C join the blue group and co-maintain the blue ledger; node B, C join the pink group and co-maintain the pink ledger; node A, B join the yellow group and co-maintain the yellow ledger. The three groups share the public internet service but have independent ledger storage and transaction executive environment each. Client end sends transaction to a group it belongs, in which transaction and data will be consensus and stored by members, while other group can not sense or access to the transaction.

Node access mechanism

Based on groups, node access management can be divided into Network access mechanism and Group access mechanism. Rules of the mechanism are recorded in the configuration, which will be read by node once it is started to implement access control of network and group.

Terms definition

Node type

Nodes mentioned in this document are all permitted with network access for P2P communication. The process of network access involves adding P2P node connection list and certificate verification.

  • Group node:nodes with network permission that joined a group. Group node is either consensus node or observer node. Consensus node takes part in consensus block generation and transaction/block syncing; observer node only involves block syncing. The process of node access involves the sending of transactions to dynamically create/remove node.
  • Free node:nodes with network permission but not join any group. Free node doesn’t get group permission nor join consensus and syncing process.

The relations of node:


node relations

Config type

division of dimension config type
affected scope network configglobal config; node config affects all network; nodes share the same config within the network
Config file named config.*
group confignode configuration affects the group it belongs to; each group has a config
Config file named group.X.*, X being group number
configure modifiable or notfixed config modifiable or notstick to the initial config, modification will be invalid,
suffix named .genesis
config modifiableconfig modifiable, valid when restarting node,
suffix named .ini
store locationlocal storageconfig stored in local file for user to modify directly,
by modifying the file user can restart valid config items
store on chainconfig stored on blockchain, the modification of which need to be consensus by group. currently there is no content needing global consensus,
need to reset chan or modify valid config items through transactions

Node access config items

The config items involving in node access management are: P2P node connection list, node certificate, CA blacklist, group node initial list and group node system list.

config items
effect area
modifiable or not
store location
P2P node connection listrecord nodes that this node wants to connect withnetwork configconfig modifiablelocal storage
node certificateprove itself as a node permitted by a trusted third-partynetwork configconfig modifiablelocal storage
CA blacklistrecord the nodes that this node forbids to connect withnetwork configconfig modifiablelocal storage
group node initial listrecord nodes joining consensus/syncing in genesis blockgroup configfixed configlocal storage
group node system listrecord list of nodes joining group consensus/syncinggroup configconfig modifiablestore on chain

Model structure


model structure

In the diagram of relation between config items and system model above, A->B means that B model depends on data of A model, and B model’s initialized later than model A.

Core process

Regular initialize process


regular initialize process

The first initialization

When a node is started at the first time, groups it belongs to write the fixed config to block 0 and commit to blockchain. The detail logic of initialization is:


The first initialization

Config contents concerning node access management and needing to be written in this phase include:group node initial list->group node system list.


  • The block 0 of each node in one ledger should be the same, that is the fixed config file should be the same;
  • The following starts of nodes should contain checking if block 0 information is the same with the fixed config file. If the config file has been modified, node will send warning message in its next start but won’t interfere with other groups’ operation.

Node networking based on CA blacklist

SSL certificate to confirm nodes access to blockchain. Nodes on one chain all trust a trustable third party (issuer of node certificate).

FISCO BCOS requires implementation of SSL two-way certificate. During handshake, nodes acquire each other’s node ID from the certificates and verify if it is in CA blacklist. If is, close the connect; if not, create session.

CA blacklist mechanism also supports SSL one-way certificate, which is used in this case: when node has created session, it can acquire the counter node’s ID from session to verify if it’s in the CA blacklist. If is, shut down the session.

Node types and transfer

The three types of nodes (consensus node/observer node/free node) can transfer through APIs like this:


consensus node types and related transfer operations

API and Config

Hierarchy of node config file


Hierarchy of config file

The organization rules of config file are: independent config among groups;fixed config and modifiable config are independent. The files involved include: network modifiable config file config.ini, group fixed config file group.N.genesis and group modifiable config file group.N.ini, among which N is the group number of node. For network/group modifiable config file, if the value of config item is not shown in the file, the program will use the default value.

Config file example

For **network modifiable config file **config.ini, node access management involves P2P node connection list [p2p], node certificate [secure], CA blacklist [certificate_blacklist]. [certificate_blacklist] is optional. Example of config items:


For the convenience of development and experience, the recommended configuration of listen_ip is For security considerations, please modify it to a safe listening address according to the actual business network situation, such as the internal IP or a specific external IP

    ;p2p listen ip
    ;p2p listen port
    ;nodes to connect
;certificate blacklist
    ;crl.0 should be nodeid, nodeid's length is 128 

;certificate configuration
    ;directory the certificates located in
    ;the node private key file
    ;the node certificate file
    ;the ca certificate file

For group fixed config filegroup.N.genesis, node access management involves group node initial list [consensus]. Example of config items:

;consensus configuration
    ;consensus algorithm type, now support PBFT(consensus_type=pbft) and Raft(consensus_type=raft)
    ;the max number of transactions of a block
    ;the node id of leaders

Group node system list definition

namestringNoPRIentries share the same value, query of table based on the key in distributed storage
typestringNonode type(sealer/observer)
node_idstringNonode ID
enable_numstringNovalid block number of the node type
_status_stringNogeneral fields of distributed storage, “0” available “1” delete

Group system API definition

Group system list implements whitelist mechanism in group level (comparing to the implementation of CA blacklist). APIs offered by group system list include:

contract ConsensusSystemTable
    // modify one node to be sealer
    function addSealer(string nodeID) public returns(int256);
    // modify one node to be observer
    function addObserver(string nodeID) public returns(int256);
    // remove the node from group system list
    function remove(string nodeID) public returns(int256);

Expectation on functions

  • Modifiable config is valid by restart after modification. In the future, dynamic loading and real-time validation can be realized;
  • CA blacklist has realized the node-based blacklist. In the future, we will consider about blacklist based on agency.