跳到主要内容

系统合约接口说明

交易接口定义#

交易接口沿用以太坊消息结构,对于特定类型的交易(如举报)通过扩展tx.input 字段来实现与以太坊交易接口的兼容 以太坊交易结构如下:

字段名长度说明
nonce8bytes当前账户发送的第几笔交易
gasPrice32bytes当前交易的gas价格
gas8bytes当前交易允许消耗的最大gas
to20bytes交易的目标地址(为nil时表示创建合约)
value32bytes当前交易转账的金额
inputbytes当前交易携带的扩展数据,前2个字节为funcTypeid,后面是参数列表
v32bytes签名v值
r32bytes签名r值
s32bytes签名s值

接口的调用方式#

例如:

platon.sendTransaction({from: "lat1nwc2am8ple8rpuqx3rsv6txljkuetsm6890u6d",to: "lat1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzlh5ge3", value: 0, gas:52792, gasPrice:500000000000, data:"0xf856838203eab842b840acae6c5bd52f6807d67da902164c6d6e3e9b8f84a06b04500961d211d3793cabbf54b25a652463967fcccde1b615680edd21321736df34b29000a39f44f78b3081808b8a01e7e4171bf4d3a00000"})

经济模型和治理相关交易都引用 sendTransaction 其中将所有入参以 十六进制编码的rlp数组作为入参

tx.input 扩展说明#

  • 字段说明
字段名位置说明
funcTypetx.input前2个字节命令码
  • funcType取值

各个接口的命令码和对应的接口如下所示,例如: 1000表示发起质押1001表示修改质押信息等等

staking接口#

1000: 发起质押

1001: 修改质押信息

1002: 增持质押

1003: 撤销质押

1004: 发起委托

1005: 减持/撤销委托

1100: 查询当前结算周期的验证人队列

1101: 查询当前共识周期的验证人列表

1102: 查询所有实时的候选人列表

1103: 查询当前账户地址所委托的节点的NodeID和质押Id

1104: 查询当前单个节点的委托信息

1105: 查询当前节点的质押信息

1200: 查询当前结算周期的区块奖励

1201: 查询当前结算周期的质押奖励

1202: 查询打包区块的平均时间

治理接口#

2000: 提交文本提案

2001: 提交升级提案

2002: 提交参数提案

2005: 提交取消提案

2003: 给提案投票

2004: 版本声明

2100: 查询提案

2101: 查询提案结果

2102: 查询提案列表

2103: 查询生效版本

2104: 查询当前块高的治理参数值

2105: 查询提案累积的可投票人数

2106: 查询治理参数列表

举报惩罚接口#

3000: 举报多签

3001: 查询节点是否有多签过

3002:查询零出块节点的列表

锁仓计划接口#

4000: 创建锁仓计划

4100: 获取锁仓信息

奖励接口#

5000: 提取委托奖励

5100: 查询委托奖励

  • 发起交易编解码协议
  1. tx.input字段以及查询结果的data字段统一使用RLP编解码协议,各个接口参数列表详见以下表格
  2. 查询结果沿用以太坊的结果返回格式
  3. 下列经济模型和治理相关的交易接口均以接口说明的顺序及类型将对应的值放置到入参数组中做了rlp编码之后再序列化成十六进制入参,并在发起交易时填写到sendTransaction的data字段

如:

增持质押:
各个入参字段的编码规则:
rlp([rlp(1002), rlp('')])

交易发起的示例:
platon.sendTransaction({from: "lat1nwc2am8ple8rpuqx3rsv6txljkuetsm6890u6d",to: "lat1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzlh5ge3", value: 0, gas:52792, gasPrice:500000000000, data:"0xf856838203eab842b840acae6c5bd52f6807d67da902164c6d6e3e9b8f84a06b04500961d211d3793cabbf54b25a652463967fcccde1b615680edd21321736df34b29000a39f44f78b3081808b8a01e7e4171bf4d3a00000"})
  • 发起查询编解码协议
  1. 下列经济模型和治理相关的查询累接口均以接口说明顺序及类型将对应的值放置到入参数组中做了rlp编码之后再序列化成十六进制入参,并在发起交易时填写到call的data字段

如:

platon.call({to: "lat1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqp3yp7hw", data:"0xda838210049594493301712671ada506ba6ca7891f436d29185821"})

所有platon.sendTransaction交易接口的结果 :

成功则回执中写的是: 0, 而失败写的是对应的错误码(错误码请参考底层内置合约错误码文档)

回执示例:

{  blockHash: "0x9ac7f6702512c5572185e5acd64e6eb297296b603a795aa634c5a99bd01ef9d1",  blockNumber: 836,  contractAddress: null,  cumulativeGasUsed: 52724,  from: "lat1c8enpvs5v6974shxgxxav5dsn36e5jl4v29pec",  gasUsed: 52724,  logs: [{      address: "lat1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzlh5ge3",      blockHash: "0x9ac7f6702512c5572185e5acd64e6eb297296b603a795aa634c5a99bd01ef9d1",      blockNumber: 836,      data: "0xc786333031313032", // 这个字段就是成功的"0"或者失败的"xxxx"错误码的rlp结果,解开它即可      logIndex: 0,      removed: false,      topics: ["0x4ca61667a6086c915d0bf1b542abd171bdf676d52eed640e514e984beed3fefe"],      transactionHash: "0x4c874a3af9c67c14317e6f62bf0279bc5a8db2f4cbb20a74873192aa46675d7b",      transactionIndex: 0  }],  logsBloom: "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000080000000000000000080002000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000004000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",  status: "0x1",  to: "lat1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzlh5ge3",  transactionHash: "0x4c874a3af9c67c14317e6f62bf0279bc5a8db2f4cbb20a74873192aa46675d7b",  transactionIndex: 0}

platon.call查询类接口结果统一格式:

名称类型说明
Codeuint32表示ppos内置合约返回的错误码
Retinterface{}(万能类型) 当Code为:0 时,返回json的查询结果(列表或单个对象),具体结果格式参见以下查询相关接口返回值;当Code非0时,返回错误提示信息字符串

注:以下查询接口(platon_call调用的接口)如无特殊声明,返回参数都按照上述格式返回

staking接口#

以下staking相关接口的合约地址为:
主网:lat1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzsjx8h7
EIP55地址:0x1000000000000000000000000000000000000002

  1. createStaking: 发起质押
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1000)Y
typuint16(2bytes)表示使用账户自由金额还是账户的锁仓金额做质押,0: 自由金额; 1: 锁仓金额;2: 优先使用锁仓余额,锁仓余额不足则剩下的部分使用自由金额Y
benefitAddress20bytes用于接受出块奖励和质押奖励的收益账户Y,客户端可传: '0x00000...000' (零账户地址,零地址代表被视为丢掉收益von)
nodeId64bytes被质押的节点Id(也叫候选人的节点Id)Y
externalIdstring外部Id(有长度限制,给第三方拉取节点描述的Id)Y,客户端可默认传: '' (空字符串)
nodeNamestring被质押节点的名称(有长度限制,表示该节点的名称)Y,客户端可默认传: '' (空字符串)
websitestring节点的第三方主页(有长度限制,表示该节点的主页)Y,客户端可默认传: '' (空字符串)
detailsstring节点的描述(有长度限制,表示该节点的描述)Y,客户端可默认传: '' (空字符串)
amount*big.Int(bytes)质押的vonY
rewardPeruint16(2bytes)委托所得到的奖励分成比例,采用BasePoint 1BP=0.01%Y
programVersionuint32程序的真实版本,治理rpc获取Y
programVersionSign65bytes程序的真实版本签名,治理rpc获取Y
blsPubKey96bytesbls的公钥Y
blsProof64bytesbls的证明,通过拉取证明接口获取Y
  1. editCandidate: 修改质押信息
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1001)Y
benefitAddress20bytes用于接受出块奖励和质押奖励的收益账户N,默认值: nil (0x00...零账户地址,零地址代表被视为丢掉收益von)
nodeId64bytes被质押的节点Id(也叫候选人的节点Id)Y
rewardPeruint16(2bytes)委托所得到的奖励分成比例,采用BasePoint 1BP=0.01%,例:传500就是5%的奖励作为委托奖励N,默认值:nil(空byte)
externalIdstring外部Id(有长度限制,给第三方拉取节点描述的Id)N,默认值: nil(空byte)
nodeNamestring被质押节点的名称(有长度限制,表示该节点的名称)N,默认值: nil(空byte)
websitestring节点的第三方主页(有长度限制,表示该节点的主页)N,默认值: nil(空byte)
detailsstring节点的描述(有长度限制,表示该节点的描述)N,默认值: nil(空byte)
  1. increaseStaking: 增持质押
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1002)Y
nodeId64bytes被质押的节点Id(也叫候选人的节点Id)Y
typuint16(2bytes)表示使用账户自由金额还是账户的锁仓金额做质押,0: 自由金额; 1: 锁仓金额Y
amount*big.Int(bytes)增持的vonY
  1. withdrewStaking: 撤销质押(一次性发起全部撤销,多次到账)
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1003)Y
nodeId64bytes被质押的节点的NodeIdY
  1. delegate: 发起委托
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1004)Y
typuint16(2bytes)表示使用账户自由金额还是账户的锁仓金额做委托,0: 自由金额; 1: 锁仓金额Y
nodeId64bytes被质押的节点的NodeIdY
amount*big.Int(bytes)委托的金额(按照最小单位算,1LAT = 10**18 von)Y
  1. withdrewDelegation: 减持/撤销委托(全部减持就是撤销)
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1005)Y
stakingBlockNumuint64(8bytes)代表着某个node的某次质押的唯一标识Y
nodeId64bytes被质押的节点的NodeIdY
amount*big.Int(bytes)减持生效的委托的金额(按照最小单位算,1LAT = 10**18 von)Y

返参:

注:交易结果存储在交易回执的logs.data中,如果是赎回全部委托,存储 rlp.Encode([][]byte{[]byte(状态码0), rlp.Encode(委托的收益) }),否则和之前结构一样

参数类型说明是否必须
delegateIncome*big.int委托的收益N
  1. getVerifierList: 查询当前结算周期的验证人队列

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1100)Y

返参: 列表

名称类型说明是否可为空(零值)
NodeId64bytes被质押的节点Id(也叫候选人的节点Id)N
StakingAddress20bytes发起质押时使用的账户(后续操作质押信息只能用这个账户,撤销质押时,von会被退回该账户或者该账户的锁仓信息中)N
BenefitAddress20bytes用于接受出块奖励和质押奖励的收益账户Y, 零账户地址
RewardPeruint16(2bytes)当前结算周期奖励分成比例,采用BasePoint 1BP=0.01%Y
NextRewardPeruint16(2bytes)下一个结算周期奖励分成比例,采用BasePoint 1BP=0.01%Y
StakingTxIndexuint32(4bytes)发起质押时的交易索引N
ProgramVersionuint32被质押节点的PlatON进程的真实版本号(获取版本号的接口由治理提供)N
StakingBlockNumuint64(8bytes)发起质押时的区块高度N
Shares*big.Int(bytes)当前候选人总共质押加被委托的von数目N
ExternalIdstring外部Id(有长度限制,给第三方拉取节点描述的Id)Y, 默认为空字符串
NodeNamestring被质押节点的名称(有长度限制,表示该节点的名称)Y, 默认为空字符串
Websitestring节点的第三方主页(有长度限制,表示该节点的主页)Y, 默认为空字符串
Detailsstring节点的描述(有长度限制,表示该节点的描述)Y, 默认为空字符串
ValidatorTermuint32(4bytes)验证人的任期(在结算周期的101个验证人快照中永远是0,只有在共识轮的验证人时才会被有值,刚被选出来时也是0,继续留任时则+1)Y,默认为 0
DelegateTotal*big.Int(bytes)当前候选人生效的总委托数量Y
DelegateRewardTotal*big.Int(bytes)候选人当前发放的总委托奖励Y
  1. getValidatorList: 查询当前共识周期的验证人列表

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1101)Y

返参: 列表

名称类型说明是否可为空(零值)
NodeId64bytes被质押的节点Id(也叫候选人的节点Id)N
StakingAddress20bytes发起质押时使用的账户(后续操作质押信息只能用这个账户,撤销质押时,von会被退回该账户或者该账户的锁仓信息中)N
BenefitAddress20bytes用于接受出块奖励和质押奖励的收益账户Y,默认为零账户地址
RewardPeruint16(2bytes)当前结算周期奖励分成比例,采用BasePoint 1BP=0.01%Y
NextRewardPeruint16(2bytes)下一个结算周期奖励分成比例,采用BasePoint 1BP=0.01%Y
StakingTxIndexuint32(4bytes)发起质押时的交易索引N
ProgramVersionuint32(4bytes)被质押节点的PlatON进程的真实版本号(获取版本号的接口由治理提供)N
StakingBlockNumuint64(8bytes)发起质押时的区块高度N
Shares*big.Int(bytes)当前候选人总共质押加被委托的von数目N
ExternalIdstring外部Id(有长度限制,给第三方拉取节点描述的Id)Y, 默认为空字符串
NodeNamestring被质押节点的名称(有长度限制,表示该节点的名称)Y, 默认为空字符串
Websitestring节点的第三方主页(有长度限制,表示该节点的主页)Y, 默认为空字符串
Detailsstring节点的描述(有长度限制,表示该节点的描述)Y, 默认为空字符串
ValidatorTermuint32(4bytes)验证人的任期(在结算周期的101个验证人快照中永远是0,只有在共识轮的验证人时才会被有值,刚被选出来时也是0,继续留任时则+1)N
DelegateTotal*big.Int(bytes)当前候选人生效的总委托数量Y
DelegateRewardTotal*big.Int(bytes)候选人当前发放的总委托奖励Y
  1. getCandidateList: 查询所有实时的候选人列表

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1102)Y

返参: 列表

名称类型说明是否可为空(零值)
NodeId64bytes被质押的节点Id(也叫候选人的节点Id)N
StakingAddress20bytes发起质押时使用的账户(后续操作质押信息只能用这个账户,撤销质押时,von会被退回该账户或者该账户的锁仓信息中)N
BenefitAddress20bytes用于接受出块奖励和质押奖励的收益账户Y,默认为零账户地址
RewardPeruint16(2bytes)当前结算周期奖励分成比例,采用BasePoint 1BP=0.01%Y
NextRewardPeruint16(2bytes)下一个结算周期奖励分成比例,采用BasePoint 1BP=0.01%Y
StakingTxIndexuint32(4bytes)发起质押时的交易索引N
ProgramVersionuint32(4bytes)被质押节点的PlatON进程的真实版本号(获取版本号的接口由治理提供)N
Statusuint32(4bytes)候选人的状态(状态是根据uint32的32bit来放置的,可同时存在多个状态,值为多个同时存在的状态值相加【0: 节点可用 (32个bit全为0); 1: 节点不可用 (只有最后一bit为1); 2: 节点零出块需要锁定但无需解除质押(只有倒数第二bit为1); 4: 节点的von不足最低质押门槛(只有倒数第三bit为1); 8:节点被举报双签(只有倒数第四bit为1)); 16: 节点零出块需要锁定并解除质押(倒数第五位bit为1); 32: 节点主动发起撤销(只有倒数第六位bit为1)】N
StakingEpochuint32(4bytes)当前变更质押金额时的结算周期N
StakingBlockNumuint64(8bytes)发起质押时的区块高度N
Sharesstring(0x十六进制字符串)当前候选人总共质押加被委托的von数目N
Releasedstring(0x十六进制字符串)发起质押账户的自由金额的锁定期质押的vonY,默认为0
ReleasedHesstring(0x十六进制字符串)发起质押账户的自由金额的犹豫期质押的vonY,默认为0
RestrictingPlanstring(0x十六进制字符串)发起质押账户的锁仓金额的锁定期质押的vonY,默认为0
RestrictingPlanHesstring(0x十六进制字符串)发起质押账户的锁仓金额的犹豫期质押的vonY,默认为0
ExternalIdstring外部Id(有长度限制,给第三方拉取节点描述的Id)Y, 默认为空字符串
NodeNamestring被质押节点的名称(有长度限制,表示该节点的名称)Y, 默认为空字符串
Websitestring节点的第三方主页(有长度限制,表示该节点的主页)Y, 默认为空字符串
Detailsstring节点的描述(有长度限制,表示该节点的描述)Y, 默认为空字符串
DelegateEpochuint32(4bytes)节点最后一次被委托的结算周期数Y
DelegateTotalstring(0x十六进制字符串)节点被委托的生效总数量Y
DelegateTotalHesstring(0x十六进制字符串)节点被委托的未生效的总数量Y
DelegateRewardTotal*big.Int(bytes)候选人当前发放的总委托奖励Y
  1. getRelatedListByDelAddr: 查询当前账户地址所委托的节点的NodeID和质押Id

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1103)Y
addrcommon.address(20bytes)委托人的账户地址Y

返参: 列表

名称类型说明是否可为空(零值)
Addr20bytes委托人的账户地址N
NodeId64bytes验证人的节点IdN
StakingBlockNumuint64(8bytes)发起质押时的区块高度N
  1. getDelegateInfo: 查询当前单个节点的委托信息

入参:

参数类型说明是否必须
funcTypeuint16代表方法类型码(1104)Y
stakingBlockNumuint64(8bytes)发起质押时的区块高度Y
delAddr20bytes委托人账户地址Y
nodeId64bytes验证人的节点IdY

返参:结构如下

名称类型说明是否可为空(零值)
Addr20bytes委托人的账户地址N
NodeId64bytes验证人的节点IdN
StakingBlockNumuint64(8bytes)发起质押时的区块高度N
DelegateEpochuint32(4bytes)最近一次对该候选人发起的委托时的结算周期N
Releasedstring(0x十六进制字符串)发起委托账户的自由金额的锁定期委托的vonY,默认为0
ReleasedHesstring(0x十六进制字符串)发起委托账户的自由金额的犹豫期委托的vonY,默认为0
RestrictingPlanstring(0x十六进制字符串)发起委托账户的锁仓金额的锁定期委托的vonY,默认为0
RestrictingPlanHesstring(0x十六进制字符串)发起委托账户的锁仓金额的犹豫期委托的vonY,默认为0
CumulativeIncomestring(0x十六进制字符串)待领取的委托收益Y,默认为0
  1. getCandidateInfo: 查询当前节点的质押信息

入参:

参数类型说明是否必须
funcTypeuint16代表方法类型码(1105)Y
nodeId64bytes验证人的节点IdY

返参: 列表

名称类型说明是否可为空(零值)
NodeId64bytes被质押的节点Id(也叫候选人的节点Id)N
StakingAddress20bytes发起质押时使用的账户(后续操作质押信息只能用这个账户,撤销质押时,von会被退回该账户或者该账户的锁仓信息中)N
BenefitAddress20bytes用于接受出块奖励和质押奖励的收益账户Y,默认为零账户地址
RewardPeruint16(2bytes)当前结算周期奖励分成比例,采用BasePoint 1BP=0.01%Y
NextRewardPeruint16(2bytes)下一个结算周期奖励分成比例,采用BasePoint 1BP=0.01%Y
StakingTxIndexuint32(4bytes)发起质押时的交易索引N
ProgramVersionuint32(4bytes)被质押节点的PlatON进程的真实版本号(获取版本号的接口由治理提供)N
Statusuint32(4bytes)候选人的状态(状态是根据uint32的32bit来放置的,可同时存在多个状态,值为多个同时存在的状态值相加【0: 节点可用 (32个bit全为0); 1: 节点不可用 (只有最后一bit为1); 2: 节点零出块需要锁定但无需解除质押(只有倒数第二bit为1); 4: 节点的von不足最低质押门槛(只有倒数第三bit为1); 8:节点被举报双签(只有倒数第四bit为1)); 16: 节点零出块需要锁定并解除质押(倒数第五位bit为1); 32: 节点主动发起撤销(只有倒数第六位bit为1)】N
StakingEpochuint32(4bytes)当前变更质押金额时的结算周期N
StakingBlockNumuint64(8bytes)发起质押时的区块高度N
Sharesstring(0x十六进制字符串)当前候选人总共质押加被委托的von数目Y,默认为0
Releasedstring(0x十六进制字符串)发起质押账户的自由金额的锁定期质押的vonY,默认为0
ReleasedHesstring(0x十六进制字符串)发起质押账户的自由金额的犹豫期质押的vonY,默认为0
RestrictingPlanstring(0x十六进制字符串)发起质押账户的锁仓金额的锁定期质押的vonY,默认为0
RestrictingPlanHesstring(0x十六进制字符串)发起质押账户的锁仓金额的犹豫期质押的vonY,默认为0
ExternalIdstring外部Id(有长度限制,给第三方拉取节点描述的Id)Y, 默认为空字符串
NodeNamestring被质押节点的名称(有长度限制,表示该节点的名称)Y, 默认为空字符串
Websitestring节点的第三方主页(有长度限制,表示该节点的主页)Y, 默认为空字符串
Detailsstring节点的描述(有长度限制,表示该节点的描述)Y, 默认为空字符串
DelegateEpochuint32(4bytes)节点最后一次被委托的结算周期Y,默认为0
DelegateTotalstring(0x十六进制字符串)节点被委托的生效总数量Y,默认为0
DelegateTotalHesstring(0x十六进制字符串)节点被委托的未生效总数量Y,默认为0
DelegateRewardTotal*big.Int(bytes)候选人当前发放的总委托奖励Y
  1. getPackageReward: 查询当前结算周期的区块奖励

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1200)Y

返参:

类型说明是否可为空(零值)
string(0x十六进制字符串)区块奖励N
  1. getStakingReward: 查询当前结算周期的质押奖励

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1201)Y

返参:

类型说明是否可为空(零值)
string(0x十六进制字符串)质押奖励N
  1. getAvgPackTime: 查询打包区块的平均时间

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(1202)Y

返参:

类型说明是否可为空(零值)
uint64打包区块的平均时间(单位为毫秒)N

治理接口#

以下 治理相关接口的合约地址为:
主网:lat1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq93t3hkm
EIP55地址:0x1000000000000000000000000000000000000005

  1. submitText: 提交文本提案
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2000)Y
verifierdiscover.NodeID(64bytes)提交提案的验证人Y
pIDIDstring(uint64)PIPIDY
  1. submitVersion: 提交升级提案
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2001)Y
verifierdiscover.NodeID(64bytes)提交提案的验证人Y
pIDIDstring(uint64)PIPIDY
newVersionuint32(4bytes)升级版本Y
endVotingRoundsuint64投票共识轮数量。说明:假设提交提案的交易,被打包进块时的共识轮序号时round1,则提案投票截止块高,就是round1 + endVotingRounds这个共识轮的第230个块高(假设一个共识轮出块250,ppos揭榜提前20个块高,250,20都是可配置的 ),其中0 < endVotingRounds <= 4840(约为2周,实际论述根据配置可计算),且为整数)Y
  1. submitParam: 提交参数提案
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2002)Y
verifierdiscover.NodeID(64bytes)提交提案的备选人Y
pIDIDstring(uint64)PIPIDY
modulestring参数模块Y
namestring参数名称Y
newValuestring参数新值Y
  1. submitCancel: 提交取消提案
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2005)Y
verifierdiscover.NodeID(64bytes)提交提案的验证人Y
pIDIDstring(uint64)PIPIDY
endVotingRoundsuint64投票共识轮数量。参考提交升级提案的说明,同时,此接口中此参数的值不能大于对应升级提案中的值Y
tobeCanceledProposalIDcommon.hash(32bytes)待取消的升级提案IDY
  1. vote: 给提案投票
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2003)Y
verifierdiscover.NodeID(64bytes)投票验证人Y
proposalIDcommon.Hash(32bytes)提案IDY
optionuint8(1byte) 0x01:支持 0x02:反对 其他值:弃权投票选项Y
programVersionuint32(4bytes)节点代码版本,有rpc的getProgramVersion接口获取Y
versionSigncommon.VesionSign(65bytes)代码版本签名,有rpc的getProgramVersion接口获取Y
  1. declareVersion: 版本声明
参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2004)Y
verifierdiscover.NodeID(64bytes)声明的节点,只能是验证人/候选人Y
programVersionuint32(4bytes)声明的版本,有rpc的getProgramVersion接口获取Y
versionSigncommon.VesionSign(65bytes)声明的版本签名,有rpc的getProgramVersion接口获取Y
  1. getProposal: 查询提案

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)2100Y
proposalIDcommon.Hash(32bytes)提案IDY

返参为以下四种类型中的一种:

TextProposal:文本提案#
  • 字段说明:
字段类型说明
ProposalIDcommon.Hash(32bytes)提案ID
Proposercommon.NodeID(64bytes)提案节点ID
ProposalTypebyte提案类型, 0x01:文本提案; 0x02:升级提案;0x03参数提案;0x04取消提案。
PIPIDstring提案PIPID
SubmitBlock8bytes提交提案的块高
EndVotingBlock8bytes提案投票结束的块高,系统根据SubmitBlock
VersionProposal:升级提案#
  • 字段说明:
字段类型说明
ProposalIDcommon.Hash(32bytes)提案ID
Proposercommon.NodeID(64bytes)提案节点ID
ProposalTypebyte提案类型, 0x01:文本提案; 0x02:升级提案;0x03参数提案;0x04取消提案。
PIPIDstring提案PIPID
SubmitBlock8bytes提交提案的块高
EndVotingRounds8bytes投票持续的共识周期数量
EndVotingBlock8bytes提案投票结束的块高,系统根据SubmitBlock,EndVotingRounds算出
ActiveBlock8bytes提案生效块高,系统根据EndVotingBlock算出
NewVersionuint升级版本
CancelProposal:取消提案#
  • 字段说明:
字段类型说明
ProposalIDcommon.Hash(32bytes)提案ID
Proposercommon.NodeID(64bytes)提案节点ID
ProposalTypebyte提案类型, 0x01:文本提案; 0x02:升级提案;0x03参数提案;0x04取消提案。
PIPIDstring提案PIPID
SubmitBlock8bytes提交提案的块高
EndVotingRounds8bytes投票持续的共识周期数量
EndVotingBlock8bytes提案投票结束的块高,系统根据SubmitBlock,EndVotingRounds算出
TobeCanceledcommon.Hash(32bytes)提案要取消的升级提案ID
ParamProposal:参数提案#
  • 字段说明:
字段类型说明
ProposalIDcommon.Hash(32bytes)提案ID
Proposercommon.NodeID(64bytes)提案节点ID
ProposalTypebyte提案类型, 0x01:文本提案; 0x02:升级提案;0x03参数提案;0x04取消提案。
PIPIDstring提案PIPID
SubmitBlock8bytes提交提案的块高
EndVotingBlock8bytes提案投票结束的块高,系统根据SubmitBlock,EndVotingEpochRounds算出
Moudulestring参数模块名
Namestring参数名称
NewVersionuint参数新值
  1. getTallyResult: 查询提案结果

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2101)Y
proposalIDcommon.Hash(32bytes)提案IDY

返参:

字段类型说明
proposalIDcommon.Hash(32bytes)提案ID
yeasuint64(8bytes)赞成票
naysuint64(8bytes)反对票
abstentionsuint64(8bytes)弃权票
accuVerifiersuint64(8bytes)在整个投票期内有投票资格的验证人总数
statusbyte状态
canceledBycommon.Hash(32bytes)当status=0x06时,记录发起取消的ProposalID
  1. listProposal: 查询提案列表

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2102)Y

返参:

参考getProposal接口返回值

  1. getActiveVersion: 查询节点的链生效版本

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2103)Y

返参:

版本号的json字符串,如{65536},表示版本是:1.0.0。 解析时,需要把ver转成4个字节。主版本:第二个字节;小版本:第三个字节,patch版本,第四个字节。

  1. getGovernParamValue: 查询当前块高的治理参数值

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2104)Y
modulestring参数模块Y
namestring参数名称Y

返参:

参数值的json字符串,如{"32"}。返回的都是字符串,客户端自行转成目标类型。

  1. getAccuVerifiersCount: 查询提案的累积可投票人数

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2105)Y
proposalIDcommon.Hash(32bytes)提案IDY
blockHashcommon.Hash(32bytes)块hashY

返参: 是个[]uint16数组

名称类型说明
uint16累积可投票人数
uint16赞成票数
uint16反对票数
uint16弃权票数
  1. listGovernParam: 查询治理参数列表

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(2106)Y
modulestring参数模块。如果输入空串"",表示查询所有治理参数Y

返参:

是个[]GovernParam数组

名称类型说明
ParamItemParamItem参数项
ParamValueParamValue参数值

其中:

ParamItem

名称类型说明
Modulestring参数模块
Namestrig参数名称
Descstring参数说明

ParamValue

名称类型说明
StaleValuestring旧参数值
Valuestring参数值
ActiveBlockuint64块高。(>=ActiveBLock,将取Value;否则取StaleValue)

下面是治理相关的类型的定义说明#

ProposalType: 提案类型定义#
类型定义说明
TextProposal0x01文本提案
VersionProposal0x02升级提案
ParamProposal0x03参数提案
CancelProposal0x04取消提案
ProposalStatus: 提案状态定义#

对文本提案来说,有:0x01,0x02,0x03三种状态; 对升级提案来说,有:0x01,0x03,0x04,0x05,0x06五种状态。 对参数提案来说,有:0x01,0x02,0x03,0x6四种状态; 对取消提案来说,有:0x01,0x02,0x03三种状态;

类型定义说明
Voting0x01投票中
Pass0x02投票通过
Failed0x03投票失败
PreActive0x04(升级提案)预生效
Active0x05(升级提案)生效
Canceled0x06被取消

举报惩罚接口#

以下 slashing相关接口的合约地址为:
主网:lat1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqyva9ztf
EIP55地址:0x1000000000000000000000000000000000000004

  1. ReportDuplicateSign: 举报双签

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(3000)Y
typuint8代表双签类型,1:prepareBlock,2:prepareVote,3:viewChangeY
datastring单个证据的json值,格式参照RPC接口EvidencesY
  1. CheckDuplicateSign: 查询节点是否已被举报过多签

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(3001)Y
typuint32代表双签类型,1:prepareBlock,2:prepareVote,3:viewChangeY
nodeId64bytes举报的节点IdY
blockNumberuint64多签的块高Y

回参:

类型描述是否可能为空
string举报的交易HashY, 可能为零交易Hash,即: 0x000...000
  1. ZeroProduceNodeList: 查询零出块的节点列表

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(3002)Y

回参:

类型描述是否可能为空
List(NodeId)零出块的节点列表,nodeId列表Y

锁仓接口#

以下 锁仓相关接口的合约地址为:
主网:lat1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqp7pn3ep
EIP55地址:0x1000000000000000000000000000000000000001

  1. CreateRestrictingPlan: 创建锁仓计划

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(4000)Y
account20bytes锁仓释放到账账户Y
plan[]RestrictingPlanplan 为 RestrictingPlan 类型的列表(数组),RestrictingPlan 定义如下:type RestrictingPlan struct { Epoch uint64 Amount:big.Int}其中,Epoch:表示结算周期的倍数,需大于0,Epoch为1表示在交易所在结算周期释放锁仓。与每个结算周期出块数的乘积表示在目标区块高度上释放锁定的资金。Epoch 每周期的区块数至少要大于最高不可逆区块高度。Amount:表示目标区块上待释放的金额。Y
  1. GetRestrictingInfo: 获取锁仓信息。

注:本接口支持获取历史数据,请求时可附带块高,默认情况下查询最新块的数据。

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(4100)Y
account20bytes锁仓释放到账账户Y

返参:

返回参数为下面字段的 json 格式字符串

名称类型说明是否可能为空
balancestring(0x十六进制字符串)总锁仓余额-已释放金额N
pledgestring(0x十六进制字符串)质押/抵押金额Y, 默认为 0
debtstring(0x十六进制字符串)欠释放金额Y, 默认为 0
plansbytes锁仓分录信息,json数组:[{"blockNumber":"","amount":""},...,{"blockNumber":"","amount":""}]。其中:blockNumber:big.Int,释放区块高度amount:\string(0x十六进制字符串),释放金额N

奖励接口#

以下 委托奖励相关接口的合约地址为:

主网:lat1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqxlcypcy
EIP55地址:0x1000000000000000000000000000000000000006

  1. withdrawDelegateReward: 提取账户当前所有的可提取的委托奖励

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(5000)Y

返参:

注:交易结果存储在交易回执的logs.data中,如交易成功,存储 rlp.Encode([][]byte{[]byte(状态码0), rlp.Encode(节点收益列表) }),如交易不成功,与之前方式一致。

节点收益列表为数组,按未领取的周期数逆序领取,最多一次性领取20个节点。

参数类型说明是否可为空(零值)
NodeIDdiscover.NodeID(64bytes)节点IDN
StakingNumuint64节点的质押块高N
Reward*big.Int领取到的收益N
  1. getDelegateReward: 查询账户在各节点未提取委托奖励。

入参:

参数类型说明是否必须
funcTypeuint16(2bytes)代表方法类型码(5100)Y
address20bytes要查询账户的地址Y
nodeIDs[]discover.NodeID要查询的节点,如果为空则查询账户委托的所有节点(当返回所有节点时将会进行排序,按DelegateEpoch升序,相同时按快排结果排列)N

返参:

是个[]Reward数组

名称类型说明
nodeIDdiscover.NodeID(64bytes)节点ID
stakingNumuint64节点的质押块高
rewardstring(0x十六进制字符串)未领取的委托收益

PPOS RPC 接口说明#

查询双出、双签证据接口#

  • 方法名称:platon_evidences
  • 入参:无
  • 出参:
参数类型描述
jsonrpcstringrpc版本号
idintid序号
resultstring证据字符串

result为证据字符串,包含3种证据类型,分别是:duplicatePrepare、duplicateVote、duplicateViewchange 每种类型包含多个证据,所以是数组结构,解析时需注意

duplicatePrepare

字段名类型说明
prepareAepochuint64共识轮epoch值
viewNumberuint64共识轮view值
blockHashstring区块hash
blockNumberuint64区块number
blockIndexuint32区块在一轮view中的索引值
blockDatastring区块rlp编码值
validateNodeindexuint32验证人在一轮epoch中的索引值
nodeIdstring验证人nodeID
blsPubKeyobject验证人bls公钥
signaturebyte[]消息签名
prepareBepochuint64共识轮epoch值
viewNumberuint64共识轮view值
blockHashstring区块hash
blockNumberuint64区块number
blockIndexuint32区块在一轮view中的索引值
blockDatastring区块rlp编码值
validateNodeindexuint32验证人在一轮epoch中的索引值
nodeIdstring验证人nodeID
blsPubKeyobject验证人bls公钥
signaturebyte[]消息签名

duplicateVote

字段名类型说明
voteAepochuint64共识轮epoch值
viewNumberuint64共识轮view值
blockHashstring区块hash
blockNumberuint64区块number
blockIndexuint32区块在一轮view中的索引值
validateNodeindexuint32验证人在一轮epoch中的索引值
nodeIdstring验证人nodeID
blsPubKeyobject验证人bls公钥
signaturebyte[]消息签名
voteBepochuint64共识轮epoch值
viewNumberuint64共识轮view值
blockHashstring区块hash
blockNumberuint64区块number
blockIndexuint32区块在一轮view中的索引值
validateNodeindexuint32验证人在一轮epoch中的索引值
nodeIdstring验证人nodeID
blsPubKeyobject验证人bls公钥
signaturebyte[]消息签名

duplicateViewchange

字段名类型说明
viewAepochuint64共识轮epoch值
viewNumberuint64共识轮view值
blockHashstring区块hash
blockNumberuint64区块number
validateNodeindexuint32验证人在一轮epoch中的索引值
nodeIdstring验证人nodeID
blsPubKeyobject验证人bls公钥
blockEpochuint32区块产生的epoch值
blockViewuint32区块产生的view值
signaturebyte[]消息签名
viewBepochuint64共识轮epoch值
viewNumberuint64共识轮view值
blockHashstring区块hash
blockNumberuint64区块number
validateNodeindexuint32验证人在一轮epoch中的索引值
nodeIdstring验证人nodeID
blsPubKeyobject验证人bls公钥
blockEpochuint32区块产生的epoch值
blockViewuint32区块产生的view值
signaturebyte[]消息签名

查询区块聚合签名接口#

  • 方法名称:platon_getPrepareQC
  • 入参:blockNumber (必须)
  • 出参:
参数类型描述
jsonrpcstringrpc版本号
idintid序号
resultstring聚合签名结构体

QuorumCert

字段名类型说明
epochuint64共识轮epoch值
viewNumberuint64共识轮view值
blockHashstring区块hash
blockNumberuint64区块number
blockIndexuint32区块在一轮view中的索引值
signaturestring聚合签名字符串
validatorSetstring验证人索引集合

查询代码版本以及签名#

  • 方法名称:admin_getProgramVersion
  • 入参:无
  • 出参:
参数类型描述是否可能为空
jsonrpcstringrpc版本号N
idintid序号N
resultstring字符串N

result为JSON字符串,包含Version和Sign两个字段

查询bls证明#

  • 方法名称:admin_getSchnorrNIZKProve
  • 入参:无
  • 出参:
参数类型描述是否可能为空
jsonrpcstringrpc版本号N
idintid序号N
resultstringbls证明N

打开数据库垃圾回收#

  • 方法名称: debug_disableDBGC
  • 入参: 无
  • 出参: 无

关闭数据库垃圾回收#

  • 方法名称: debug_enableDBGC
  • 入参: 无
  • 出参: 无