# RPC API

# 概述

RPC API 是 TOP Network 提供给社区使用的与链交互的接口,包括发送交易,查询交易信息、节点信息、主链信息等。

# 连接到 RPC

您可以连接到自己创建的 edge 节点,请参见 成为矿工,也可以连接到 TOP Network edge 节点。

TOP Networkedge 节点官方域名:

  • 主网:mainnet.edge.topnetwork.org

  • 测试网:testnet.edge.topnetwork.org

# 请求方法

方法名 说明
requestToken 在与链交互前需要先获取身份令牌。
根据账户获取身份令牌(identity token),每个账户身份令牌不同。
sendTransaction 发送交易,包括转账、节点 staking、节点注册、节点投票、节点领取奖励、调用合约等。
getAccount 查询链上账户信息。
getTransaction 查询账户交易信息。
getBlock 查询区块信息。
getStandbys 查询节点候选池中节点信息。
getCGP 查询链上治理参数(on-chain governance parameters)。
getChainInfo 查询主链信息。
queryNodeInfo 查询节点信息。
queryNodeReward 查询节点奖励。
listVoteUsed 查询节点投票分布。
queryVoterDividend 查询投票者分红。
queryProposal 查询提案信息。

# 请求参数

参数名称 是否必选 默认值 类型 说明
target_account_addr - String 扩展字段,当前未使用,您可传入任意一个账户地址。
body - Object body 里为具体业务参数,需将 JSON 格式转化成 Text 格式。
业务参数说明请参见各接口“请求参数”。
method - String 请求方法。
sequence_id - String 客户端会话次数,递增。
identity_token - String 与链交互前首先需要获取链访问身份令牌(identity token),身份令牌因账户不同而不同。当前未对该字段进行校验。
version 1.0 String RPC API 版本。

# 请求样例

请求方式:POST

以查询链上账户信息为例:

  • C++

    auto account_info_response = client.request("POST", "/", "target_account_addr=T800002276a7d58218ac4978733e5cca927a7d86cb7c87&body={"params":{"account_addr":"T8000066ab344963eaa071f9636faac26b0d1a39900325"}}&method=getAccount&sequence_id=5&identity_token=&version=1.0");
    
  • curl命令

    curl -X POST --data 'target_account_addr=T800002276a7d58218ac4978733e5cca927a7d86cb7c87&body={"params":{"account_addr":"T8000066ab344963eaa071f9636faac26b0d1a39900325"}}&method=getAccount&sequence_id=5&identity_token=&version=1.0'  http://localhost:19081
    

# 返回结构

返回体为 JSON 结构。

{
   "data" : {
      "account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87",
      "available_gas" : 25000,
      "balance" : 100000000000000,
      "burned_token" : 0,
      "cluster_id" : 1,
      "contract_address" : [T30000MaSkcvg2iyqMRDRMFnTQ8o5237Xs1dT9TR],
      "created_time" : 1596520429,
      "disk_staked_token" : 0,
      "group_id" : 64,
      "gas_staked_token" : 0,
      "latest_tx_hash" : "0xfcd8843c36b1c8fee81bcac7e7cf2b38682deef723e9a237918b70b3a6dfc4c9",
      "latest_tx_hash_xxhash64" : "0xdb73d04d0f5daa84",
      "latest_unit_height" : 1,
      "lock_balance" : 0,
      "lock_deposit_balance" : 0,
      "lock_gas" : 0,
      "nonce" : 1,
      "total_free_gas" : 25000,
      "total_gas" : 25000,
      "total_stake_gas" : 0,
      "unlock_disk_staked" : 0, 
      "unlock_gas_staked" : 0,
      "unused_free_gas" : 25000,
      "unused_stake_gas" : 0,
      "unused_vote_amount" : 0,
      "vote_staked_token" : 0,
      "zone_id" : 0
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "5"
}

返回参数说明

参数名称 类型 说明
data Object 返回各接口具体业务数据。
errmsg String 错误信息。
errno Int 错误码。
sequence_id String 客户端会话次数,递增。

# 错误码

RPC 标准错误码:

代码 错误类型 返回信息 说明
-32700 服务器解析错误。 body json parse error json parse errorrpc param error 服务器收到无效的 JSON。
服务器解析 JSON 文本发生错误。
-32602 无效的方法参数 miss param params account_addr or account_addr is not valid
miss param params amount or amount is not valid
miss param params last_hash or last_hash is not valid
miss param params nonce or nonce is not valid
miss param params data or data is not valid
miss param params tx_deposit or tx_deposit is not valid
miss param params to_ledger_id or to_ledger_id is not valid
miss param params from_ledger_id or from_ledger_id is not valid
miss param params tx_type or tx_type is not valid
miss param params tx_len or tx_len is not valid
miss param params send_timestamp or send_timestamp is not valid
miss param params tx_random_nonce or tx_random_nonce is not valid
miss param params last_tx_nonce or last_tx_nonce is not valid
miss param params challenge_proof or challenge_proof is not valid
miss param params tx_hash
miss param sender_action
miss param receiver_action
miss param sender_action action_hash
miss param sender_action action_type
miss param sender_action action_size
miss param sender_action account_addr
miss param sender_action action_name
miss param sender_action action_param
miss param sender_action action_authorization
miss param receiver_action action_hash
miss param receiver_action action_type
miss param receiver_action action_size
miss param receiver_action account_addr
miss param receiver_action action_name
miss param receiver_action action_param
miss param receiver_action action_authorization
miss param method or method is not valid
miss param version or version is not valid
miss param sequence_id or version is not valid
msg list is empty
方法参数丢失或者无效的方法参数(参数类型错误)。

自定义错误码:

错误码 错误类型 返回信息 说明
0 交易投递状态 OK 交易被投递成功,进入共识,不代表交易最终共识状态,交易共识最终状态需要通过交易 hash 查询。
1 业务相关的参数错误 version must be 1.0 now RPC API 版本必须是 1.0 版本。
transaction hash error 交易 hash 错误。
transaction sign error 交易签名错误。
Whitelist check failed 白名单检查失败。
Source address and destination address are the same 源地址,目的地址相同(交易检查)。
Insufficient deposit 保证金不足。
duration expiration check failed 交易超时。
Transfer amount is 0 转账金额为 0。
Transfer amount is greater than 20 billion TOP 转账金额大于 200 亿 TOP。
Voting check failed 投票检查失败。
transaction validation check failed (*) 交易检查失败(错误码)。括号内的详细错误码参见下方的 交易检查子错误码 表。
2 未知错误 unknown exception 未知错误。
3 Shard 执行错误 account not found on chain 在链上未查询到此账户信息。
account address or transaction hash error/does not exist 在链上未查询到此交易(交易既不在交易池又不在区块,可能账户地址或者 hash 错误/不存在)。
account address does not exist or block height does not exist 区块不存在(可能账户不存在、高度不存在)。
unknown msg type 发送了交易和查询之外的消息类型。
request time out 请求超时。
110 请求限流 request too often 流控开启时,同一账户、同一 IP 地址 1 秒最多发送 10 次请求。

交易检查子错误码:

错误码 说明
2949139 交易类型错,或使用了非法字段。
2949137 交易长度检查失败。
2949121 地址格式检查失败。
2949142 销毁交易检查失败。
2949141 本地合约交易检查失败。
2949134 系统合约交易检查失败。