Вики ZooBC
Интеграции

API узла

Каждый узел ZooBC предоставляет один публичный HTTP API. Через него кошельки, обозреватели, инструменты командной строки и любая веб-страница читают цепочку и отправляют транзакции. Для чтения не нужны ни ключ, ни аккаунт, ни ключ API, и API отвечает страницам, размещённым где угодно. Для записи нужна только транзакция, подписанная её отправителем.

Основы

  • Где: простой HTTP/1.1, по умолчанию на порту 8080, с более чем сотней маршрутов под /api/v1/. Узел также отдаёт веб-кошелёк по адресам / и /wallet.
  • На узле нет TLS: публичные сайты обращаются к API по HTTPS через шлюз, который, кроме того, ставит перед узлом архивный сервис для глубокой истории.
  • Открыт для любой страницы: каждый ответ несёт 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-цепочка/spine/blocks/:height

Все пути во втором столбце находятся под /api/v1/. /movements перечисляет каждое изменение баланса аккаунта с его причиной, включая уплаченную аренду и выигранные вознаграждения. /pubkey возвращает публичный ключ нативного аккаунта по одному только адресу. Начиная с версии 0.5.8 маршруты цепочки сообщают finalized_height, а каждая транзакция — флаг finalized, который устанавливается, когда её блок охватывает соподписанный spine-блок (финальность и откат).

Так любой может посмотреть любой адрес. Цепочка записывает ключи, а не имена, поэтому приватность в ZooBC обеспечивается тем, как используются адреса, а не скрытыми балансами (аккаунты и адреса).

Отправка транзакции

Клиент собирает байты транзакции, подписывает ключом отправителя дайджест, привязанный к цепочке, используя genesis_hash, прочитанный из /api/v1/node/info (подписание транзакции), и отправляет результат на 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 секунд опроса каждые пару секунд более чем достаточно. Прежде чем отдавать товар в обмен на платёж, дождитесь подтверждения, а лучше — флага finalized.

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

Статус отправленной транзакции переходит от staging к mempool, к confirmed или к rejected; начиная с версии 0.5.8 транзакция в статусе confirmed затем получает флаг finalized; повторная отправка тех же байтов даёт тот же хеш и исполняется один раз
Статус отправленной транзакции переходит от staging к mempool, к confirmed или к rejected; начиная с версии 0.5.8 транзакция в статусе confirmed затем получает флаг finalized; повторная отправка тех же байтов даёт тот же хеш и исполняется один раз

Подписанные запросы и отмена

Несколько запросов несут собственную подпись: подпись Ed25519 над METHOD:PATH:TIMESTAMP:BODY, действительную 300 секунд. Клиент, который 20 раз не прошёл подписанную аутентификацию за 5 минут, блокируется на 300 секунд. Ожидающую транзакцию можно отозвать из пула одного узла подписанным запросом DELETE (подписанные и зашифрованные сообщения).

Другие интерфейсы узла

  • Порт 8001: одноранговая сеть между узлами.
  • Порт 8545: адаптер JSON-RPC в стиле Ethereum, по умолчанию на собственной машине узла, которым пользуется MetaMask.
  • Порт 8332: RPC-адаптер в стиле Bitcoin Core, по умолчанию выключенный, которому нужны собственные учётные данные оператора.

См. также