Блокчейн-API в приложениях Web3: как они работают
Что делает блокчейн-API в Web3-приложении: читает данные цепочки, отправляет транзакции и уведомления, а также почему смарт-контрактам нужны оракулы.
Проверил(а) Maurice Sobiera
Блокчейн-API — это веб-интерфейс, который позволяет приложению читать данные блокчейна и отправлять транзакции без собственной ноды. В Web3-приложении он стоит между пользовательским интерфейсом и сетью. Смарт-контракты не могут сами вызывать веб-API, поэтому данные извне попадают в них через оракулы.
Эта статья разделяет два направления, в которых API и блокчейны связываются, и объясняет, где применяется каждое из них.
Что делает блокчейн-API в Web3-приложении?
Блокчейн-API даёт приложению три возможности: он читает данные цепочки, отправляет транзакции и сообщает о событиях. Без него вашему бэкенду пришлось бы самому запускать ноду, поддерживать её синхронизацию и разбирать блоки.
| Задача | Пример | Как это работает |
|---|---|---|
| Чтение | Баланс адреса, транзакции в блоке | Запрос к ноде или к провайдеру API |
| Запись | Отправка перевода токена | Транзакция подписывается приватным ключом и рассылается в сеть |
| Уведомление | Сообщение бэкенду о поступлении депозита | Вебхук или опрос ноды |
Chaingateway — один из таких API. Эндпоинты для кошельков, переводов и вебхуков перечислены в файле OpenAPI. Вебхуки есть для Bitcoin, Ethereum, BNB Smart Chain, Polygon, Arbitrum и Tron. У Solana вебхуков нет, поэтому приложению на Solana приходится опрашивать сеть.
Почему смарт-контракт не может вызвать веб-API?
Смарт-контракт не может вызвать веб-API, потому что каждая нода должна выполнить его и получить тот же результат. В документации Ethereum сказано, что подтягивание внешних данных сделало бы детерминированность невозможной. Ценовой API мог бы вернуть разным нодам разные значения, и ноды перестали бы сходиться в состоянии цепочки (ethereum.org: оракулы).
Это свойство самой архитектуры. Оно не зависит от языка цепочки или от конкретного API. Следствие такое: прежде чем контракт сможет использовать данные, их нужно записать в цепочку транзакцией.
Как внешние данные попадают в смарт-контракт?
Внешние данные попадают в контракт через оракул. Оракул — это приложение, которое получает, проверяет и передаёт внешнюю информацию смарт-контрактам. Кредитный протокол, которому нужна цена актива, или контракт, который зависит от данных о погоде или рейсах, без оракула не обойдётся.
В документации Ethereum описаны две распространённые схемы:
- Publish-subscribe: оракул публикует поток данных, а контракты его читают. Это подходит для данных, которые часто меняются, например для цен токенов.
- Request-response: контракт запрашивает конкретные данные, а оракул отвечает через callback. Это подходит для больших наборов данных, из которых контракту нужна лишь небольшая часть. Тот, кто делает запрос, платит за поиск и за газ callback-вызова.
Оракул, которым управляет одна сторона, — единая точка отказа. Если эта сторона выйдет из строя, будет взломана или солжёт, контракт начнёт действовать на основе неверных данных. В той же документации описаны децентрализованные сервисы оракулов. В них несколько участников согласовывают данные, прежде чем они попадут в контракт. Децентрализация бывает разной по степени, и всё равно нужно решить, насколько вы доверяете выбранному оракулу.
Какой API нужен для какой задачи?
Ответ зависит от направления потока данных.
| Направление | Задача | Инструмент |
|---|---|---|
| Из цепочки в приложение | Читать балансы, отправлять переводы, получать уведомления о депозитах | Блокчейн-API или собственная нода |
| Из внешнего мира в контракт | Передать контракту цену, оценку или значение погоды | Оракул |
| Из контракта во внешний мир | Запустить действие после события в цепочке | Логи событий, которые читает сервис, или оракул |
Платёжная система использует только первую строку. Пользователь платит на адрес, вебхук доходит до вашего бэкенда, а бэкенд зачисляет средства на аккаунт в собственной базе данных. Оракул здесь не участвует. О том, как разделить работу между цепочкой и базой данных, см. блокчейн или база данных.
Как приложение читает события контракта?
Приложение читает события контракта через логи. Когда контракт генерирует событие, нода сохраняет его в квитанции транзакции. Метод eth_getLogs из Ethereum JSON-RPC API возвращает логи, подходящие под фильтр. Этот API следует спецификации JSON-RPC 2.0. Так обычно находят переводы токенов.
Фильтр для событий Transfer стандарта ERC-20 одного токена в диапазоне блоков выглядит так:
{ "jsonrpc": "2.0", "method": "eth_getLogs", "params": [{ "fromBlock": "0x10d4f00", "toBlock": "0x10d4f0a", "address": "0xTokenContract", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }], "id": 1}Первый topic — хеш сигнатуры события Transfer(address,address,uint256). Остальные topics содержат индексированные аргументы: здесь отправителя и получателя. Сумма находится в поле data каждого лога в виде шестнадцатеричного числа.
Диапазон блоков важен. Многие провайдеры ограничивают диапазон или число результатов одного вызова eth_getLogs, поэтому сканеру приходится постранично проходить блоки. Блокчейн-API, который декодирует эти логи за вас или отправляет их как вебхуки, избавляет от этого кода. Смысл логов он не меняет: лог из блока, который позже подвергнется реорганизации цепочки, исчезает вместе с этим блоком.
Каковы ограничения блокчейн-API?
API не меняет принципов работы цепочки. Транзакция становится окончательной только тогда, когда так решает сама цепочка. API может показать её как ожидающую или подтверждённую раньше этого момента. Считайте депозит зачисленным только после того, как пройдут правила финальности цепочки.
Неудачные доставки вебхуков не повторяются автоматически. Chaingateway перечисляет их в эндпоинте неудачных уведомлений каждой сети, например GET /api/v2/tron/webhooks/notifications/failed, и вы повторно отправляете их через эндпоинт повтора. Бэкенд, который обрабатывает вебхуки, также должен быть идемпотентным. Повторно отправленное уведомление не должно дважды зачислить средства на аккаунт.
Внешний API также создаёт зависимость от провайдера. Если нужен прямой доступ к протоколу, можно по-прежнему запустить ноду и общаться с ней через JSON-RPC.
Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.