Разработчикам

Полный справочник

Все маршруты, их параметры и формат ответа:

Откройте справочник 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. Доступ к ним защищён значением admin_api_key из /etc/zoobc/gateway.json, которое установщик генерирует для каждой машины отдельно; ключа по умолчанию нет.

Список разрешённых узлов

Шлюз проксирует запросы только к тем узлам, о которых ему сообщили. Именно этот список не даёт имени хоста в форме ip-… превратить шлюз в открытый прокси.

Все три операции записи требуют ключа администратора. В публичном режиме шлюз также находит узлы в собственном реестре блокчейна; в приватном режиме он использует только static_nodes.

Инструменты для релизов

Инструмент хеширования файлов вычисляет SHA-256 в браузере для всего, что вы хотите проверить вручную, а /verify сверяет загруженный пакет с хешами, опубликованными в блокчейне.

Два документа

Всё, что нужно команде аппаратного кошелька, описано здесь, а полностью в двух PDF ниже. Оба документа проверены на узле ZooBC v0.4.0 (zoobc-main на коммите 7ad161a4) и на векторах транзакций, которые принял работающий узел v0.4.0.

Версия 2.1 отличается от черновика 1 в одном существенном отношении: подписи транзакций теперь привязаны к блокчейну. Два изменения ломают совместимость для всех, кто разрабатывал по черновику 1: дайджест подписания и тело ApprovalEscrow. Старую конструкцию v0.3.2 больше ничто не реализует, поэтому разрабатывайте только по текущему документу.

Сводка на одной странице

Сначала прочитайте эти четыре пункта

Четыре момента, которые влияют на реализацию сильнее всего остального.

Вывод ключей и адреса

Эталон: 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' и так далее. Привязка к блокчейну не влияет на вывод ключей: один набор ключей работает во всех блокчейнах 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» без какой-либо дополнительной диагностики.

Разобранный пример, проверенный в блокчейне

SendZBC на 1 ZBC самому себе, комиссия 0,05 ZBC, timestamp 1700000000, без эскроу, без сообщения. Это вектор 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

Используйте потоковый SHA3, чтобы на шаге 6 не держать всю транзакцию в RAM. Подайте 6 байтов тега, затем 32 байта генезиса, затем транзакцию.

Тег остаётся самым вероятным местом ошибки реализации во всей спецификации. "ZBC-TX" состоит из шести байтов ASCII, 5a 42 43 2d 54 58, без завершающего NUL и без префикса длины. Прошивка, которая добавляет к строке завершающий символ или записывает семь байтов, выдаёт подпись, которая выглядит корректной, но отвергается в блокчейне с общей ошибкой и без диагностики. Прежде всего проверьте это на векторе 0.

Что привязка к блокчейну делает и чего не делает

32 байта генезиса передаёт хост; устройство их не ищет. Поэтому подписание не зависит от блокчейна, и один путь кода обслуживает TestNet, devnet, MainNet и любой приватный или параллельный блокчейн ZooBC.

Поэтому таблица известных хешей генезиса в прошивке по-прежнему нужна, но только для одной цели: показать на экране надёжное имя сети, а если хеша нет в таблице, показать «UNKNOWN CHAIN» и первые 8 символов hex.

Не отклоняйте нераспознанные блокчейны по умолчанию. Хеш devnet меняется при каждом перезапуске, а приватные и параллельные блокчейны для ZooBC обычное дело, поэтому жёсткий отказ делает устройство бесполезным для интеграции и законных развёртываний. Если производитель хочет такую блокировку, сделайте её явной пользовательской настройкой, выключенной по умолчанию.

Типы транзакций: что должна поддерживать стандартная прошивка

Id типа = group + 256 × subtype. Всего существует пятьдесят шесть типов. Эти три покрывают оплату в 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: хеш генезис-блока. Узлы сравнивают его перед установлением связи; байта network-id нет. GET /api/v1/node/info возвращает его вместе с двумя полями, появившимися в v0.4.0:

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

signing_version отсутствует: значит, узел старше v0.4.0 и применяет устаревший непривязанный дайджест. Хост, поддерживающий только актуальные блокчейны, может считать отсутствие поля сигналом «здесь не подписывать». Узел выводит hex в нижнем регистре, а архивный API в верхнем, поэтому декодируйте без учёта регистра и удаляйте начальный 0x, если он есть. Байты в любом случае одни и те же.

Откуда его считывать. Шлюз отвечает на /api/v1/node/info из архивного сервиса, а не из узла. Архивный сервис передаёт два поля подписания от узла, который он зеркалирует, и выдаёт их ровно тогда, когда их сообщает узел, начиная со сборки 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 всё же меняется, все подписи, сделанные до этого, становятся недействительными: так и задумано.