ZooBC 维基
集成

节点 API

每个 ZooBC 节点都提供一个公共 HTTP API。钱包、区块浏览器、命令行工具和任何网页都通过它读取链并提交交易。读取不需要密钥、账户或 API 密钥，而且 API 会回应托管在任何地方的页面。写入只需要一笔由发送方签名的交易。

基本情况

  • 位置：默认在 8080 端口上提供普通 HTTP/1.1，/api/v1/ 下有一百多个路由。节点还在 / 和 /wallet 提供网页钱包。
  • 节点上没有 TLS：公共网站通过网关以 HTTPS 访问 API，网关还会在节点前面放置一个归档服务，用于深远的历史。
  • 向所有页面开放：每个响应都带有 Access-Control-Allow-Origin: *，浏览器的 OPTIONS 检查会立即得到回应，因此任何域名上的页面都能调用这个 API（用一个 HTML 页面构建应用）。
  • 以读取为主：除八个路由外，其余都是无需认证的读取。提交交易不需要 API 密钥，因为交易自带签名。
  • 按客户端地址限制：默认每分钟 300 个写请求（超出后节点返回 429，并带有 Retry-After 头）；除非运营者设置了限制，否则读取不受限。
单个 HTML 页面用 GET 请求读取链，并把已签名的字节提交给节点或网关；API 回应每一个来源
单个 HTML 页面用 GET 请求读取链，并把已签名的字节提交给节点或网关；API 回应每一个来源

可以读取什么

领域示例
节点与链/api/v1/node/info（含 genesis_hash 和 signing_version）、/api/v1/blockchain/rules
账户/accounts/:address（余额、可花费余额、锁定的质押）、/history、/transactions、/movements、/datasets、/escrows、/group、/pubkey
交易/transactions/:hash/status
节点注册表/nodes?status=all、/nodes?status=queued
服务注册表/registry/gateways、/registry/archivals、/registry/relays
发布版本/release/list、/release/authority
应用/apps、/apps/open、/apps/pool、/apps/stats、/apps/:id
跨链桥/bridge/coins、/bridge/withdrawals/:hash
脊链/spine/blocks/:height

第二列中的所有路径都位于 /api/v1/ 之下。/movements 列出账户余额的每一次变动及其原因，包括支付的租金和赢得的奖励。/pubkey 仅凭地址就能返回原生账户的公钥。自 0.5.8 版本起，链的路由会报告 finalized_height，每笔交易会带一个 finalized 标志，在一个经联署的脊链区块覆盖其所在区块后被设置（最终性与回滚）。

任何人都可以这样查询任何地址。链记录的是密钥而不是姓名，因此 ZooBC 上的隐私来自地址的使用方式，而不是来自隐藏的余额（账户与地址）。

提交交易

客户端构建交易的字节，使用从 /api/v1/node/info 读到的 genesis_hash，用发送方的密钥签署链绑定摘要（签署交易），然后把结果提交到 POST /api/v1/transactions。不需要任何 SDK：有 Ed25519、SHA3-256 和创世哈希就够了。

节点返回 HTTP 202，意思是“已接受”而不是“已完成”，并返回交易的哈希。随后客户端轮询 /api/v1/transactions/<hash>/status，其状态依次经过：

  1. staging，然后是 mempool，此时交易在等待进入区块；
  2. 一旦被打包进区块，变为 confirmed，并附带区块高度；
  3. 或者，如果被拒绝，变为 rejected，并附带原因和所处阶段；如果节点不知道这笔交易，则为 not_found（404）。

按每 15 秒一个区块计算，每隔几秒轮询一次就足够了。在凭一笔付款交付货物之前，要等待确认，最好等到最终确定标志。

如果回复丢失，就重新发送完全相同的已签名字节。哈希是根据这些字节计算的，因此已经持有该交易的节点（即使这笔交易已被打包进区块）会再次返回 202，并标记为重复，而交易只会执行一次。用新的时间戳重新签名会产生一笔不同的交易，重复付款正是这样发生的。

已提交交易的状态从 staging 到 mempool 再到 confirmed，或者变为 rejected；从 0.5.8 版本起，已确认的交易随后还会获得 finalized 标记；重新发送相同的字节得到相同的哈希，只执行一次
已提交交易的状态从 staging 到 mempool 再到 confirmed，或者变为 rejected；从 0.5.8 版本起，已确认的交易随后还会获得 finalized 标记；重新发送相同的字节得到相同的哈希，只执行一次

签名请求与取消

少数请求带有自己的签名：对 METHOD:PATH:TIMESTAMP:BODY 的 Ed25519 签名，有效期 300 秒。在 5 分钟内有 20 次签名认证失败的客户端会被锁定 300 秒。待处理的交易可以用一个签名的 DELETE 请求从某个节点的交易池中撤回（签名消息与加密消息）。

节点的其他接口

  • 8001 端口：节点之间的点对点网络。
  • 8545 端口：以太坊式 JSON-RPC 适配器，默认只在节点本机上，供 MetaMask 使用。
  • 8332 端口：Bitcoin Core 风格的 RPC 适配器，默认关闭，需要运营者自己设置的凭据。

另见