# POC共识模块

# 为什么要有共识模块

众所周知,区块链的核心是共识机制。和传统互联网的cliet-server架构不同,区块链的节点是对等的,没有中心,大家权利一样;所以为了使数据达到一致性,让一个没有中心的网络维护一套大家都认同的账本,这就是共识机制的作用。 从广义上来说,共识机制就是区块链每个节点共同遵守的规则或算法,是实现互信的基础,如此才能实现去中心化的无监管,维持整个平台的正常运转。 从狭义来说,共识机制决定了每个节点对区块链上交易的验证和确认的机制。

# 共识模块要做什么

区块链的每次交易,都必须获得每个节点的认可,只有全网都达成共识后,交易才算完成。就好像民主选举中,投票方式或规则必须被全民认可,基于此才能完成选举。而在区块链中,共识机制的主要表现就是激励制度,也就是给矿工的奖励。在共识机制的保障下,每个矿工都能获得奖励,整个区块链才能有序的运转,提供公平、透明及互信的环境。因此共识模块就需要提供特定的算法来维持,即共识算法。

公链共识机制有多种,主流的有POW、POS、DPOS。NULS主网采用自主原创的POC(Proof Of Credit)共识机制,一种继承了Dpos共识机制的安全性和高效率,同时在协作方面进行了非常大的改进,可以看成是一种升级版的Dpos。

# POC共识模块职责:

  • 区块同步后的合法性验证

  • 创建共识节点、委托参与共识、取消委托、注销共识节点★

  • 共识节点打包出块

  • 网络维护激励的发放

  • 作恶节点惩罚★

    不同的共识机制其共识算法不尽相同,有标记★的为POC共识特有

# 《共识模块》在系统中的定位

共识模块在系统中是比较核心的一块,主要负责打包交易出块,验证区块头,管理系统中的共识节点信息,委托信息,处罚信息等。

# 接口列表

# createAgentValid

create agent transaction validate

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
tx string 交易

# 返回值

字段名 字段类型 参数描述
value boolean 创建节点验证结果

# stopAgentValid

stop agent transaction validate

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
tx string 交易

# 返回值

字段名 字段类型 参数描述
value boolean 停止节点交易验证结果

# depositValid

deposit agent transaction validate

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
tx string 交易

# 返回值

字段名 字段类型 参数描述
value boolean 委托交易验证结果

# withdrawValid

withdraw deposit agent transaction validate

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
tx string 交易

# 返回值

字段名 字段类型 参数描述
value boolean 退出共识交易验证结果

# cs_runChain

Running a sub chain 1.0

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId string

# 返回值

无返回值

# cs_getAgentChangeInfo

get seed nodes list

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId string

# 返回值

无返回值

# cs_addEvidenceRecord

链分叉证据记录/add evidence record

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
blockHeader string 分叉区块头一
evidenceHeader string 分叉区块头二

# 返回值

字段名 字段类型 参数描述
value boolean 处理结果

# cs_doubleSpendRecord

双花交易记录/double spend transaction record

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
block string 区块信息
tx string 分叉交易

# 返回值

字段名 字段类型 参数描述
value boolean 处理结果

# cs_getWholeInfo

查询全网共识数据/query the consensus information of the whole network

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id

# 返回值

字段名 字段类型 参数描述
agentCount int 节点数量
totalDeposit string 总委托两
rewardOfDay string 当天共识奖励总量
consensusAccountNumber int 参与共识人数
packingAgentCount int 当前轮次出块节点数量

# cs_getInfo

查询指定账户共识数据/query consensus information for specified accounts

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
address string 账户地址

# 返回值

字段名 字段类型 参数描述
agentCount int 节点数量
totalDeposit string 参与共识的总金额
joinAgentCount int 参与共识节点的数量
usableBalance string 可用余额
reward string 获得的共识奖励
rewardOfDay string 当天获得的共识奖励
agentHash string 创建的节点HASH

# cs_getPublishList

查询红黄牌记录/query punish list

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
address string 地址
type int 惩罚类型 0红黄牌记录 1红牌记录 2黄牌记录

# 返回值

字段名 字段类型 参数描述
redPunish list<string> 获得的红牌列表
yellowPunish list<string> 获得的黄牌惩罚列表

# cs_getRoundInfo

获取当前轮次信息/get current round information

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id

# 返回值

字段名 字段类型 参数描述
totalWeight double 当前轮次总权重
index long 轮次下标
startTime long 轮次开始时间
endTime long 轮次结束时间
memberCount int 本轮次出块节点数
memberList list<object> 本轮次出块成员信息
        roundIndex long 轮次下标
        roundStartTime long 轮次开始时间
        packingIndexOfRound int 该节点在本轮次中第几个出块
        agent object 共识节点信息
                agentAddress byte[] 节点地址
                packingAddress byte[] 出块地址
                rewardAddress byte[] 奖励地址
                deposit biginteger 保证金
                commissionRate byte 佣金比例
                time long 创建时间
                blockHeight long 所在区块高度
                delHeight long 节点注销高度
                status int 状态,0:待共识 unConsensus, 1:共识中 consensus
                creditVal double 信誉值
                totalDeposit biginteger 节点总委托金额
                txHash nulshash 创建该节点的交易HASH
                memberCount int 参与共识人数
                alais string 节点别名
        depositList list<object> 当前节点委托信息
                deposit biginteger 委托金额
                agentHash nulshash 委托的节点HASH
                address byte[] 委托账户
                time long 委托时间
                status int 状态
                txHash nulshash 委托交易HASH
                blockHeight long 委托交易被打包的高度
                delHeight long 退出委托高度
        sortValue string 排序值
        packStartTime long 当前节点开始出块时间
        packEndTime long 当前节点出块结束时间
preRound object<meetinground> 上一轮信息
myMember object 当前节点出块信息
        roundIndex long 轮次下标
        roundStartTime long 轮次开始时间
        packingIndexOfRound int 该节点在本轮次中第几个出块
        agent object 共识节点信息
                agentAddress byte[] 节点地址
                packingAddress byte[] 出块地址
                rewardAddress byte[] 奖励地址
                deposit biginteger 保证金
                commissionRate byte 佣金比例
                time long 创建时间
                blockHeight long 所在区块高度
                delHeight long 节点注销高度
                status int 状态,0:待共识 unConsensus, 1:共识中 consensus
                creditVal double 信誉值
                totalDeposit biginteger 节点总委托金额
                txHash nulshash 创建该节点的交易HASH
                memberCount int 参与共识人数
                alais string 节点别名
        depositList list<object> 当前节点委托信息
                deposit biginteger 委托金额
                agentHash nulshash 委托的节点HASH
                address byte[] 委托账户
                time long 委托时间
                status int 状态
                txHash nulshash 委托交易HASH
                blockHeight long 委托交易被打包的高度
                delHeight long 退出委托高度
        sortValue string 排序值
        packStartTime long 当前节点开始出块时间
        packEndTime long 当前节点出块结束时间

# cs_getRoundMemberList

查询指定区块所在轮次的成员列表/Query the membership list of the specified block's rounds

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
extend string 区块头扩展信息

# 返回值

字段名 字段类型 参数描述
packAddressList list<string> 当前伦次出块地址列表

# cs_getConsensusConfig

获取共识模块配置信息/get consensus config

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id

# 返回值

字段名 字段类型 参数描述
seedNodes string 种子节点列表
inflationAmount integer 委托金额最大值
agentAssetId integer 共识资产ID
agentChainId integer 共识资产链ID
awardAssetId integer 奖励资产ID(共识奖励为本链资产)

# cs_runMainChain

run main chain 1.0

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId string

# 返回值

无返回值

# cs_stopChain

stop a chain 1.0

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId string

# 返回值

无返回值

# cs_getAgentList

查询当前网络中的共识节点列表/Query the list of consensus nodes in the current network

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
pageNumber int 页码
pageSize int 每页大小
keyWord string 关键字

# 返回值

字段名 字段类型 参数描述
agentHash string 节点HASH
agentAddress string 节点地址
packingAddress string 节点出块地址
rewardAddress string 节点奖励地址
deposit string 抵押金额
commissionRate byte 佣金比例
agentName string 节点名称
agentId string 节点ID
introduction string 节点简介
time long 节点创建时间
blockHeight long 节点打包高度
delHeight long 节点失效高度
status int 状态
creditVal double 信誉值
totalDeposit string 总委托金额
txHash string 创建节点交易HASH
memberCount int 委托人数
version string 版本

# cs_stopAgent

注销节点/stop agent

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
address string 节点地址
password string 密码

# 返回值

字段名 字段类型 参数描述
txHash string 停止节点交易HASH

# cs_createAgent

创建节点交易/create agent transaction

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
agentAddress string 节点地址
packingAddress string 节点出块地址
rewardAddress string 奖励地址,默认节点地址
commissionRate int 佣金比例
deposit string 抵押金额
password string 密码

# 返回值

字段名 字段类型 参数描述
txHash string 创建节点交易HASH

# cs_getAgentInfo

查询指点节点节点详细信息/Query pointer node details

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
agentHash string 节点HASH

# 返回值

字段名 字段类型 参数描述
agentHash string 节点HASH
agentAddress string 节点地址
packingAddress string 节点出块地址
rewardAddress string 节点奖励地址
deposit string 抵押金额
commissionRate byte 佣金比例
agentName string 节点名称
agentId string 节点ID
introduction string 节点简介
time long 节点创建时间
blockHeight long 节点打包高度
delHeight long 节点失效高度
status int 状态
creditVal double 信誉值
totalDeposit string 总委托金额
txHash string 创建节点交易HASH
memberCount int 委托人数
version string 版本

# cs_getAgentStatus

查询指定共识节点状态/query the specified consensus node status 1.0

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
agentHash string 节点HASH

# 返回值

字段名 字段类型 参数描述
status byte 节点状态

# cs_updateAgentConsensusStatus

修改节点共识状态/modifying the Node Consensus State

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id

# 返回值

字段名 字段类型 参数描述
N/A void 无特定返回值,无错误则表示节点共识状态修改成功

# cs_updateAgentStatus

修改节点打包状态/modifying the Packing State of Nodes

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
status int 节点状态

# 返回值

字段名 字段类型 参数描述
N/A void 无特定返回值,无错误则表示节点打包状态修改成功

# cs_getNodePackingAddress

获取当前节点出块地址/Get the current node's out-of-block address

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id

# 返回值

字段名 字段类型 参数描述
packAddress string 当前节点出块地址

# cs_getAgentAddressList

获取当前网络共识节点出块地址列表或则查询最近N个区块的出块地址/Get all node out-of-block addresses or specify N block out-of-block designations

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id

# 返回值

字段名 字段类型 参数描述
packAddress string 共识节点列表

# cs_getPackerInfo

获取当前节点的出块账户信息/modifying the Packing State of Nodes

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id

# 返回值

字段名 字段类型 参数描述
address string 当前节点出块地址
password string 当前节点密码
packAddressList list<string> 当前打包地址列表

# cs_getSeedNodeInfo

获取种子节点信息/get seed node info

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id

# 返回值

字段名 字段类型 参数描述
address string 当前节点出块地址
password string 当前节点密码
packAddressList list<string> 当前打包地址列表

# cs_stopContractAgent

智能合约注销节点/contract stop agent

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
contractAddress string 合约地址
contractSender string 合约调用者地址
contractBalance string 合约地址的当前余额
contractNonce string 合约地址的当前nonce值
blockTime long 当前打包的区块时间

# 返回值

字段名 字段类型 参数描述
返回值 list<string> 返回交易HASH和交易

# cs_createContractAgent

智能合约创建节点/contract create agent

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
packingAddress string 出块地址
deposit string 抵押金额
commissionRate string 佣金比例
contractAddress string 合约地址
contractSender string 合约调用者地址
contractBalance string 合约地址的当前余额
contractNonce string 合约地址的当前nonce值
blockTime long 当前打包的区块时间

# 返回值

字段名 字段类型 参数描述
返回值 list<string> 返回交易HASH和交易

# cs_contractDeposit

智能合约委托共识/contract deposit agent transaction

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
agentHash string 委托的节点HASH
deposit string 委托金额
contractAddress string 合约地址
contractSender string 合约调用者地址
contractBalance string 合约地址的当前余额
contractNonce string 合约地址的当前nonce值
blockTime long 当前打包的区块时间

# 返回值

字段名 字段类型 参数描述
返回值 list<string> 返回交易HASH和交易

# cs_contractWithdraw

智能合约退出共识/contract withdraw deposit agent transaction

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
joinAgentHash string 节点HASH
contractAddress string 合约地址
contractSender string 合约调用者地址
contractBalance string 合约地址的当前余额
contractNonce string 合约地址的当前nonce值
blockTime long 当前打包的区块时间

# 返回值

字段名 字段类型 参数描述
返回值 list<string> 返回交易HASH和交易

# cs_getContractDepositInfo

智能合约查询指定账户委托信息/Intelligent Contract Query for Assigned Account Delegation Information

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
joinAgentHash string 节点HASH
contractAddress string 合约地址
contractSender string 合约调用者地址

# 返回值

字段名 字段类型 参数描述
返回值 list<string> 委托信息

# cs_getContractAgentInfo

智能合约节点/contract get agent info

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
agentHash string 节点HASH
contractAddress string 合约地址
contractSender string 合约调用者地址

# 返回值

字段名 字段类型 参数描述
返回值 list<string> 节点信息

# cs_triggerCoinBaseContract

交易模块触发CoinBase智能合约/trigger coin base contract

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
tx string 交易信息
blockHeader string 区块头
stateRoot string stateRoot

# 返回值

字段名 字段类型 参数描述
value string stateRoot

# cs_chainRollBack

区块回滚/chain rollback

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
height int 区块回滚到的高度

# 返回值

字段名 字段类型 参数描述
value boolean 区块回滚结果

# cs_addBlock

接收并缓存新区块/Receiving and caching new blocks

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
blockHeader string 区块头

# 返回值

字段名 字段类型 参数描述
value boolean 接口执行成功与否

# cs_receiveHeaderList

接收并缓存区块列表/Receive and cache block lists

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
headerList string 区块头列表

# 返回值

字段名 字段类型 参数描述
value boolean 是否成功接收处理

# cs_validBlock

验证区块/verify block correctness

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
download int 区块状态
block string 区块信息

# 返回值

字段名 字段类型 参数描述
value boolean 验证结果

# cs_createMultiAgent

多签账户创建节点/Multi-Sign Account create agent transaction

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
agentAddress string 节点地址(多签地址)
packingAddress string 节点出块地址
rewardAddress string 奖励地址,默认节点地址
commissionRate int 佣金比例
deposit string 抵押金额
password string 签名账户密码
signAddress string 签名账户地址

# 返回值

字段名 字段类型 参数描述
tx string 完整交易序列化字符串,如果交易没达到最小签名数可继续签名
txHash string 交易hash
completed boolean true:交易已完成(已广播),false:交易没完成,没有达到最小签名数

# cs_stopMultiAgent

多签账户注销节点/Multi-Sign Account stop agent

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
address string 节点地址(多签地址)
password string 签名账户密码
signAddress string 签名账户地址

# 返回值

字段名 字段类型 参数描述
tx string 完整交易序列化字符串,如果交易没达到最小签名数可继续签名
txHash string 交易hash
completed boolean true:交易已完成(已广播),false:交易没完成,没有达到最小签名数

# cs_multiDeposit

多签账户委托共识/Multi-Sign Account deposit agent transaction

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
address string 多签账户地址
agentHash string 节点HASH
deposit string 委托金额
password string 签名账户密码
signAddress string 签名账户地址

# 返回值

字段名 字段类型 参数描述
tx string 完整交易序列化字符串,如果交易没达到最小签名数可继续签名
txHash string 交易hash
completed boolean true:交易已完成(已广播),false:交易没完成,没有达到最小签名数

# cs_multiWithdraw

多签账户退出共识/Multi-Sign Account withdraw deposit agent transaction

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
address string 多签账户地址
txHash string 加入共识交易HASH
password string 签名账户密码
signAddress string 签名账户地址

# 返回值

字段名 字段类型 参数描述
tx string 完整交易序列化字符串,如果交易没达到最小签名数可继续签名
txHash string 交易hash
completed boolean true:交易已完成(已广播),false:交易没完成,没有达到最小签名数

# cs_random_seed_count

根据高度和原始种子个数生成一个随机种子并返回

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
height long 最大高度
count int 原始种子个数
algorithm string 算法标识:SHA3...

# 返回值

字段名 字段类型 参数描述
seed string 生成的随机种子
algorithm string 算法标识
count int 原始种子个数

# cs_random_seed_height

根据高度区间生成一个随机种子并返回

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
startHeight long 起始高度
endHeight long 截止高度
algorithm string 算法标识:SHA3...

# 返回值

字段名 字段类型 参数描述
seed string 生成的随机种子
algorithm string 算法标识
count int 原始种子个数

# cs_random_raw_seeds_count

根据高度查找原始种子列表并返回

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
height long 起始高度
count int 截止高度

# 返回值

字段名 字段类型 参数描述
返回值 list<string>

# cs_random_raw_seeds_height

根据高度区间查询原始种子列表并返回

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
startHeight long 起始高度
endHeight long 截止高度

# 返回值

字段名 字段类型 参数描述
返回值 list<string>

# cs_getDepositList

查询指定账户或指定节点的委托信息/Query delegation information for a specified account or node

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
pageNumber int 页码
pageSize int 每页数量
address string 账户地址
agentHash string 节点HASH

# 返回值

字段名 字段类型 参数描述
deposit string 委托金额
agentHash string 节点HASH
address string 账户地址
time long 委托时间
txHash string 委托交易HASH
blockHeight long 委托交易被打包高度
delHeight long 退出委托高度
status int 节点状态 0:待共识, 1:已共识
agentName string 节点名称
agentAddress string 节点地址

# cs_depositToAgent

创建委托交易/deposit agent transaction

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
address string 账户地址
agentHash string 节点HASH
deposit string 委托金额
password string 账户密码

# 返回值

字段名 字段类型 参数描述
txHash string 加入共识交易Hash

# cs_withdraw

退出委托交易/withdraw deposit agent transaction

# scope:public

# version:1.0

# 参数列表

参数名 参数类型 参数描述 是否非空
chainId int 链id
address string 账户地址
txHash string 加入共识交易HASH
password string 账户密码

# 返回值

字段名 字段类型 参数描述
txHash string 退出共识交易Hash
Last Updated: 2019-9-3 16:38:35