開発者

完全なリファレンス

すべてのルート、そのパラメーター、レスポンスの形式：

APIリファレンスを開く →  ·  別の表示

どちらのアドレスも同じドキュメントを提供します。

ダウンロード

運用者がこのゲートウェイで公開したファイルは/dl/<name>で配信されます。名前は[A-Za-z0-9._-]からなる単一のセグメントで、すべて添付ファイルとして送信され、ページとして表示されることはありません。このオリジンはウォレットも提供しており、ここで表示されたページはウォレットのオリジンを引き継いでしまうためです。

リリースバンドルは/releases/<version>/<arch>/の下に置かれ、/releases/latestが現在のバンドルを指します。ノードインストーラーの場所： /install.

このゲートウェイは正常ですか？確認中…

/gateway/status は、このゲートウェイが自身と到達可能なノードについて把握している情報を報告します：モード、ドメイン、許可リストにあるノード数、応答しているノード。

/gateway/system-stats はマシンの状態を報告します：CPU、メモリ、ディスク、稼働時間。ゲートウェイのページに表示される数値は、ここから取得しています。

curl https://this-gateway/gateway/status
curl https://this-gateway/gateway/system-stats

どちらもキーは不要です。どちらもチェーンについては何も公開しません。チェーンの情報には上記の/api/v1/…を使ってください。

特定のノードへのアクセス

チェーンのルートは、このゲートウェイが選んだいずれかのアーカイブノードから応答します。特定のノードに問い合わせるには、そのIPをホスト名に入れ（ドットはダッシュに置き換えます）、必要に応じて-p<port>でAPIポートを指定します：

curl https://ip-192-168-1-100.this-gateway/api/v1/node/info
curl https://ip-192-168-1-100-p8080.this-gateway/api/v1/node/info

応答するのは、このゲートウェイの許可リストにあるノードだけです。それ以外はプロキシされずに拒否されるため、ホスト名を使ってゲートウェイ経由で任意のホストにアクセスすることはできません。

リレー

音声、ビデオ、画面共有はピアツーピアで行われます。ファイアウォールが直接接続を妨げる場合は、リレーがクレジットと引き換えに通信を中継します。/relay/infoはリレーのアドレス、料金、決済先チェーンのジェネシスハッシュを報告します。ウォレットは支払いの前にそれを自身のノードと照合します。別のチェーン上のリレーは、受け取った支払いをクレジットとして反映できないからです。

curl https://this-gateway/relay/info

管理パネル

ゲートウェイ自体の管理機能はzoobc.network/adminにあります。/etc/zoobc/gateway.jsonにあるadmin_api_keyで保護されており、このキーはインストーラーがサーバーごとに生成します。デフォルトのキーはありません。

許可リスト

ゲートウェイは、知らされたノードにのみプロキシします。このリストがあるからこそ、ip-…形式のホスト名によってゲートウェイがオープンプロキシになることを防げます。

3つの書き込み操作には、いずれも管理キーが必要です。パブリックモードでは、ゲートウェイはチェーン自体のレジストリからもノードを検出します。プライベートモードでは次のものだけを使います： static_nodes.

リリースツール

ファイルハッシャーは、手作業で確認したい任意のファイルのSHA-256をブラウザ内で計算します。/verifyは、ダウンロードしたバンドルをチェーンが公開したハッシュと照合します。

2つのドキュメント

ハードウェアウォレットのチームに必要なことはすべてここに記載しており、詳細は下の2つのPDFにまとめています。どちらもZooBCノードv0.4.0（7ad161a4時点のzoobc-main）と、稼働中のv0.4.0ノードが受理したトランザクションベクターに対して検証済みです。

バージョン2.1は、1つの重要な点でドラフト1に取って代わります：トランザクション署名がチェーンにバインドされるようになりました。ドラフト1に基づいて実装した方にとって、署名ダイジェストとApprovalEscrowのボディという2つの変更は互換性を壊すものです。旧v0.3.2の構成を実装しているものはないため、現行のドキュメントのみに基づいて実装してください。

1ページの要約

まずこの4点を

ほかの何よりも実装を左右する4つのポイント。

鍵導出とアドレス

リファレンス：zoobc-signer/extension/lib/zoobc-crypto.js（リファレンスウォレットとバイト単位で同一）。ノード側の同等の実装： src/crypto/slip10.cpp.

seed = PBKDF2-HMAC-SHA512(NFKD(mnemonic), "mnemonic" + passphrase, 2048, 64)
I    = HMAC-SHA512("ed25519 seed", seed);  k = I[0..32], c = I[32..64]

for index in [44, 883, account]:                       # all hardened
    data = 0x00 || k || u32be(index + 0x80000000)
    I    = HMAC-SHA512(c, data);  k = I[0..32], c = I[32..64]

pubkey = Ed25519.publicKeyFromSeed(k)                  # k is the 32-byte seed

アカウント0はm/44'/883'/0'、アカウント1はm/44'/883'/1'、以下同様です。鍵導出はチェーンバインディングの影響を受けません。1組の鍵ですべてのZooBCチェーンに対応でき、異なるのは署名だけです。

表示用アドレスは、36バイトのアカウントではなく公開鍵から生成されます：

buf[35] = pubkey(32) || "ZBC"
h       = SHA3-256(buf);  buf[32..35] = h[0..3]        # 3-byte checksum
s       = base32(buf)                                   # RFC 4648 A-Z2-7, no padding, 56 chars
address = "ZBC_" + s[0..8] + "_" + s[8..16] + ...       # 7 groups, canonical length 66

デコード時は、アンダースコア、ダッシュ、スペース、区切りなしのいずれも、大文字・小文字を問わず受け付け、チェックサムを再計算して照合する必要があります。上記の3バイトのSHA3チェックサムは、コードとチェーンが用いる定義です。これと、計算例のアドレスを再現する仕様書内のリファレンス実装に基づいて実装してください。

未署名トランザクションのワイヤーフォーマット

信頼できる情報源：src/util/transaction_util.cpp:144-270。ワイヤーフォーマットはv0.4.0で変更されていません。以下の長さやオフセットは、チェーンバインディングの影響を受けません。

エスクローブロック末尾のmulti_partyバイトは必須です。これを省略したり、エスクローなしのマーカーを別の値で書いたりすると、ノードは「Invalid transaction signature」とだけ返し、それ以上の診断情報はありません。

計算例（チェーンで検証済み）

自分宛てに1 ZBCを送るSendZBC。手数料0.05 ZBC、タイムスタンプ1700000000、エスクローなし、メッセージなし。仕様書にある7つのベクターのうちのベクター0です。

01000000                 type = 1 (SendZBC)
01                       version
00f1536500000000         timestamp 1700000000
00000000 5e8eb28d...2152 sender    (type 0 + pubkey)
00000000 5e8eb28d...2152 recipient (type 0 + pubkey)
404b4c0000000000         fee 5 000 000
08000000                 body length 8
00e1f50500000000         body: amount 100 000 000
02000000                 no-escrow marker
00000000                 message length 0

これで113バイトです。署名用のプリイメージは、その前にさらに38バイトを付加します：

5a42432d5458              tag "ZBC-TX"          6 bytes
090ab3c7...a61878         genesis hash         32 bytes
0100000001...00000000     the 113 bytes above 113 bytes
                                              ---------
                                              151 bytes

digest = SHA3-256(preimage) = f37e5340...4644fc、署名9a3b044d...03bb07、tx_hash = f00a6692...ce78b0。稼働中のv0.4.0ノードはHTTP 202と、まさにこのハッシュを返しました。

署名手順（デバイス側）

input : account_index, genesis_hash(32), unsigned_bytes

1. k      = SLIP10(m/44'/883'/account_index')
2. pub    = Ed25519.pub(k);  self = 00000000 || pub
3. parse unsigned_bytes; every length must land exactly at the end
4. require version == 1 and sender == self
5. decode body per type; render the approval screen; wait for the user
6. digest = SHA3-256("ZBC-TX" || genesis_hash || unsigned_bytes)
7. sig    = Ed25519.sign(k, digest)          # the digest IS the message
8. return sig(64), and tx_hash = SHA3-256(unsigned_bytes || sig) for the host to cross-check

ステップ6でトランザクション全体をRAMに保持しなくて済むよう、ストリーミングSHA3を使ってください。6バイトのタグ、32バイトのジェネシス、トランザクションの順に投入します。

タグは、仕様全体の中で最も実装ミスが起きやすい箇所です。"ZBC-TX"は6バイトのASCII（5a 42 43 2d 54 58）で、NUL終端文字も長さプレフィックスもありません。文字列を終端したり7バイトを書き込んだりするファームウェアは、一見有効な署名を生成しますが、チェーン上では汎用的なエラーで失敗し、診断情報も得られません。何よりも先に、ベクター0で検証してください。

チェーンバインディングにできること、できないこと

32バイトのジェネシスはホストが提供し、デバイスが自分で調べることはありません。そのため署名はチェーンに依存せず、1つのコードパスでTestNet、devnet、MainNet、そしてあらゆるプライベートまたは並行のZooBCチェーンに対応できます。

そのため、既知のジェネシスハッシュの一覧をファームウェアに持たせることは依然として望ましいものの、その目的は1つだけです：信頼できるネットワーク名を画面に表示することです。ハッシュが一覧にない場合は、「UNKNOWN CHAIN」と先頭8桁の16進数を表示します。

未知のチェーンをデフォルトで拒否しないでください。devnetのハッシュは再起動のたびに変わり、プライベートチェーンや並行チェーンはZooBCではごく普通のものです。一律に拒否すると、デバイスは統合作業にも正当なデプロイにも使えなくなります。ベンダーがそのロックを望む場合は、デフォルトでオフの明示的なユーザー設定にしてください。

トランザクションタイプ：標準ファームウェアが対応すべきもの

タイプID = group + 256 × subtype。全部で56のタイプがあります。次の3つでZBCの支払い、任意のトークンの支払い、エスクローの完了をカバーでき、いずれもボディは小さく固定長です。

token_id はハッシュから導出される符号付き64ビット値のため、負になることがあります。ジェネシスコインはID 1から14で、ZBC自体はID 0であり、TransferTokenに現れることはありません。各トークンには、デバイスでは検証できない独自のdecimals（0から8）があります。

ApprovalEscrowはv0.4.0で変更されました。ボディはかつてapprovalと8バイトのID（12バイト）でしたが、現在はapprovalとエスクローされたトランザクションの32バイトのハッシュ（36バイト）になり、パーサーはそれ以外の長さを拒否します。理由はまさにハードウェアウォレットに関わるものです。8バイトのIDしか見えない署名者は、何を解放しようとしているのか確認できず、しかも8バイトのIDは、デバイスに提示される偽のエスクローに対して2^64の探索で見つけられてしまいます。完全なハッシュがあれば、デバイスは承認対象を検証できます。

デバイスが検証する項目

ユーザーが画面で承認する内容

チェーンで検証済みのリファレンス署名ツールに基づき、画面ごとに次の順序で表示します。

タイムスタンプは表示しなくて構いません。ユーザーにとって意味のある情報ではなく、ウィンドウはノードが強制します。

ホストとデバイスのプロトコル

トランスポートには、ベンダー独自のUSB/HIDレイヤーと既存の分割転送の仕組みを使います。重要なのは内容です。

genesis_hashは表示用のヒントではなく、署名を左右する値です。ドラフト1では、ネットワークのパラメーターはラベルを選ぶだけだったため、列挙型でも構いませんでした。現在はダイジェストの内部に含まれるため、実際の32バイトでなければならず、誤った値からはどのチェーンも受け付けない署名が生成されます。

生データ署名のルール。生データ署名コマンドは、ちょうど32バイトの入力には決して署名してはならず、テキストとして表示できる入力にのみ署名すべきです。32バイトの生入力は、ユーザーが見たこともないトランザクションのSHA3ダイジェストかもしれず、そうなるとメッセージ署名コマンドがブラインドでのトランザクション署名に化けてしまいます。長さ32を拒否すれば、チェーン側を変更することなくその穴を塞げます。

全体のシーケンス

Website (page)         Companion / host           device                    Gateway / node
   |-- connect ---------->|                            |                          |
   |                      |-- GET_PUBLIC_KEY(0) ----->|  (shows ZBC_... address) |
   |<-- address ----------|<-- pubkey, address -------|                          |
   |-- GET /api/v1/node/info  (genesis_hash, signing_version, height) ---------->|
   |-- GET /api/v1/accounts/<addr>  (balances) --------------------------------->|
   |-- GET /api/v1/accounts/<addr>/tokens, /api/v1/tokens/<id> (decimals) ------>|
   |   user fills the form                             |                          |
   |-- GET /api/v1/blockchain/estimate-fee?type=1&body_length=8 ---------------->|
   |<-- {minimum_fee, timestamp} ------------------------------------------------|
   |-- fields {type, recipient, body, fee, message} -->|                          |
   |                      |  serialize the 11 fields   |                          |
   |                      |-- SIGN_TX(0, genesis, -->|  parse, verify, display,  |
   |                      |            bytes)         |  user approves            |
   |                      |<-- signature, tx_hash ---|                          |
   |<-- signature --------|                            |                          |
   |-- POST /api/v1/transactions {JSON} ---------------------------------------->|
   |<-- 202 {status:"success", transaction_hash} --------------------------------|
   |-- GET /api/v1/transactions/<hash>/status  (staging, mempool, confirmed) --->|

ホストはノードのtransaction_hashとデバイスのtx_hashを比較します。両者は一致しなければならず、一致しない場合はホストが署名後にバイトを改変したことを意味します。

genesis_hashとsigning_versionは、ブロードキャスト先のエンドポイントから読み取ってください。署名を判定するのはそのチェーンだからです。

チェーンの識別

ZooBCにある唯一のネットワーク識別子はジェネシスブロックハッシュです。ノードはピア接続の前にこれを比較します。ネットワークIDのバイトはありません。GET /api/v1/node/infoは、v0.4.0で追加された2つのフィールドとともにこれを返します：

"genesis_hash": "090ab3c7...", "signing_version": 2, "signing_tag": "ZBC-TX"

signing_version がない場合、そのノードはv0.4.0より前のもので、チェーンにバインドされていない旧来のダイジェストを適用しています。現行のチェーンのみをサポートするホストは、このフィールドがないことを「ここでは署名しない」の合図として扱って構いません。ノードは小文字の16進数を出力し、アーカイブAPIは大文字で出力するため、大文字・小文字を区別せずにデコードし、先頭に0xがあれば取り除いてください。どちらでもバイト列は同じです。

どこから読み取るか。ゲートウェイは/api/v1/node/infoに、ノードではなくアーカイブサービスから応答します。アーカイブはミラー元のノードから2つの署名フィールドを引き継ぎ、ビルド7ad161a4以降では、ノードが報告している場合に限りそのまま出力します。signing_versionはノードのエンドポイントから、またはそのビルド以降のゲートウェイから読み取り、フィールドがない場合は回答とみなさず、「ノードに問い合わせる」合図として扱ってください。

ブロードキャスト

POST /api/v1/transactions. v0.4.0でも変更なし、新しいフィールドもありません。transaction_body_bytesはボディのみです。ノードは名前付きフィールドからエンベロープを再構築し、自身のジェネシスハッシュとタグを前に付けてダイジェストを再計算するため、すべてのフィールドは署名した内容と一致していなければなりません。

{
  "version": 1,
  "timestamp": 1700000000,
  "transaction_type": 1,
  "fee": 5000000,
  "sender_account_address":    "00000000 5e8eb28d ... 2152",
  "recipient_account_address": "00000000 5e8eb28d ... 2152",
  "transaction_body_bytes": "00e1f50500000000",
  "signature": "9a3b044d ... 03bb07",
  "message_hex": "...optional...",
  "escrow": { "approver_address": "...", "commission": 0, "timeout": 1700003600 }
}

成功時はHTTP 202と{"status":"success","duplicate":false,"transaction_hash":"..."}が返ります。duplicate:trueはノードがすでにそのトランザクションを保持していることを意味するので、再送しないでください。200も成功として扱ってください。失敗時は400とエラーボディ、または負荷が高いときは503が返ります。

役立つ統合テスト：ステージングプールは最初に署名をチェックするため、「Sender account does not exist」のような後段のエラーに達したトランザクションは、すでに署名検証を通過しています。資金のない鍵でも、署名の経路を検証できます。

署名が拒否されたとき

現時点では、チェーンの不一致を他の署名エラーと区別できません。旧来のダイジェストも、誤ったチェーンのダイジェストも、まったく同じボディを返します：

{"success":false,"error":"Transaction validation failed: ValidationError: Invalid transaction signature","code":400}

そのため、原因は可能性の高いものから順に、次の順序で確認してください：

開発に使うエンドポイント

読み取りはアーカイブ、ゲートウェイ、ノードの順に振り分けます。ブロードキャストはゲートウェイかノードに送り、アーカイブエンドポイントには決して送らないでください.

ジェネシスハッシュはハードコードせず、実行時に読み取ってください。devnetのジェネシスハッシュは再起動のたびに変わります。ファームウェア内のハッシュ表は画面に名前を表示するためだけのものなので、古いエントリが残っていても署名が壊れることはなく、「UNKNOWN CHAIN」と表示されるだけです。devnetのハッシュが実際に変わると、それ以前に作成された署名はすべて無効になりますが、これは機能が正しく働いている証拠です。