ZooBC ウィキ
インテグレーション

ノード API

すべての ZooBC ノードは、1 つの公開 HTTP API を提供しています。ウォレット、エクスプローラー、コマンドラインツール、そしてあらゆるウェブページは、これを通じてチェーンを読み、トランザクションを送信します。読み取りには鍵もアカウントも API キーも必要なく、API はどこでホストされたページにも答えます。書き込みに必要なのは、送信者が署名したトランザクションだけです。

基本

  • 場所：既定ではポート 8080 の平文の HTTP/1.1 で、/api/v1/ の下に 100 を超えるルートがあります。ノードは / と /wallet で ウェブウォレット も提供します。
  • ノードに TLS はない：公開サイトは ゲートウェイを通じて HTTPS で API に届きます。ゲートウェイは、深い履歴のためにアーカイブのサービスも前に置きます。
  • すべてのページに開かれている：すべての応答が Access-Control-Allow-Origin: * を持ち、ブラウザの OPTIONS の確認には直ちに答えるため、どのドメインのページからでも API を呼び出せます（1 枚の HTML ページでアプリを作る）。
  • ほとんどが読み取り：8 つを除くすべてのルートは、認証の要らない読み取りです。トランザクションの送信に API キーは要りません。トランザクションが自分の署名を運んでいるからです。
  • クライアントのアドレスごとの制限：既定では書き込みのリクエストは 1 分あたり 300 回です（それを超えるとノードは Retry-After ヘッダー付きの 429 で答えます）。読み取りは、運用者が制限を設定しない限り無制限です。
1 枚の HTML ページが GET リクエストでチェーンを読み、署名済みのバイト列をノードまたはゲートウェイに POST します。API はすべてのオリジンに答えます
1 枚の HTML ページが GET リクエストでチェーンを読み、署名済みのバイト列をノードまたはゲートウェイに POST します。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

2 列目のパスはすべて /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 秒に 1 ブロックなので、数秒ごとのポーリングで十分です。支払いと引き換えに商品を引き渡す前には、確認済みになるのを待ち、できれば finalized フラグを待ってください。

応答が失われた場合は、まったく同じ署名済みのバイト列を再送してください。ハッシュはそのバイト列から計算されるため、すでにそのトランザクションを持っているノードは、それがすでにブロックに取り込まれている場合でも、重複として印を付けて再び 202 で答え、トランザクションは一度しか実行されません。新しいタイムスタンプで署名し直すと別のトランザクションになり、二重払いはそうして起こります。

送信されたトランザクションのステータスは、staging から mempool、confirmed へ、あるいは rejected へと進みます。バージョン 0.5.8 以降、confirmed になったトランザクションには後で finalized フラグが付きます。同じバイト列を再送すれば同じハッシュになり、一度だけ実行されます
送信されたトランザクションのステータスは、staging から mempool、confirmed へ、あるいは rejected へと進みます。バージョン 0.5.8 以降、confirmed になったトランザクションには後で finalized フラグが付きます。同じバイト列を再送すれば同じハッシュになり、一度だけ実行されます

署名付きのリクエストと取り消し

いくつかのリクエストは独自の署名を運びます。METHOD:PATH:TIMESTAMP:BODY に対する Ed25519 署名で、300 秒間有効です。5 分以内に署名付きの認証に 20 回失敗したクライアントは、300 秒間締め出されます。保留中のトランザクションは、署名付きの DELETE リクエストで 1 つのノードのプールから取り下げることができます（署名付きメッセージと暗号化メッセージ）。

ノードのその他のインターフェース

  • ポート 8001：ノード間のピアツーピアネットワーク。
  • ポート 8545：MetaMask が使う Ethereum 形式の JSON-RPC アダプター。既定ではノード自身のマシン上のみ。
  • ポート 8332：Bitcoin Core 形式の RPC アダプター。既定ではオフで、運用者自身の認証情報が必要です。

関連項目