gRPC: прокси к TRON-ноде

UsdtPull отдаёт доступ к собственной TRON-ноде по gRPC. Сервис — тонкий прокси: контракты
java-tron (GreatVoyage-v4.8.2.2) не изменены, запрос и ответ передаются байт в байт. Всё, что
добавлено сверху, — аутентификация по API-ключу, проверка подписки и учёт лимитов.

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


Адрес (production)	`node.usdtpull.com:443`
Адрес (staging)	`node.test.usdtpull.com:443`
Транспорт	HTTP/2 поверх TLS (ALPN `h2`), не plaintext
Типы вызовов	только unary; стримовые методы контракта на прокси не зарегистрированы
Максимальный размер сообщения	64 МБ в каждую сторону
Server reflection	включён (`grpc.reflection.v1` и `v1alpha`), доступен без API-ключа

1. Что нужно до первого вызова

API-ключ. Создаётся в кабинете или через REST (POST /v1/api-keys). У ключа есть список
разрешённых IP — звонить можно только с них.

Подписка на ноду. Без активной подписки прокси отвечает PermissionDenied /
ERR_NODE_SUBSCRIPTION_NOT_FOUND. Покупается по REST:

Список allowedIps и его максимум фиксируются в подписке в момент покупки — последующее
изменение тарифа уже оплаченный доступ не урезает.

Два независимых allowlist'а. IP вызывающего должен присутствовать и в списке API-ключа, и в
списке подписки. Это самая частая причина PermissionDenied на корректно подписанном запросе.

2. Подпись запроса

В metadata каждого вызова (кроме reflection) передаются четыре ключа:

Ключ	Значение
`x-api-key`	публичная часть API-ключа
`x-timestamp`	Unix-время в секундах; расхождение с сервером — не больше 2 минут
`x-nonce`	уникальная строка на каждый запрос (UUID подходит); повтор в пределах 5 минут отклоняется как replay
`x-signature`	base64 от HMAC-SHA256, см. ниже

Подписываемая строка для gRPC короче, чем для REST, — тела в ней нет:

{timestamp}\n{nonce}\n{fullMethod}

fullMethod — полное имя метода с ведущим слэшем, как оно идёт в HTTP/2-фрейме:
/protocol.Wallet/GetNowBlock2. Разделитель — \n (LF, не CRLF).

signature = base64( HMAC-SHA256( key = secret, message = "{timestamp}\n{nonce}\n{fullMethod}" ) )

secret — приватная часть ключа: она показывается один раз при создании, на сервере хранится
зашифрованной.

Генератор на Python (пригодится и для ручных вызовов через grpcurl):

3. Контракт: reflection или .proto

Reflection (рекомендуется). Сервер отдаёт все дескрипторы сам, локальные .proto не нужны:

Доступные сервисы: protocol.Wallet (full node), protocol.WalletSolidity (solidity node),
protocol.WalletExtension, protocol.Database, protocol.Monitor, protocol.Network.
Маршрутизация выполняется на нашей стороне: вызовы WalletSolidity уходят на solidity-ноду,
остальные — на full node.

.proto-файлы. Если клиент генерирует код заранее — берите немодифицированные протоколы
java-tron GreatVoyage-v4.8.2.2 (protocol/src/main/protos): корень — api/api.proto, он
импортирует core/Tron.proto и core/contract/*.proto. Те же файлы мы отдаём интеграторам
архивом по запросу.

4. Пример вызова: grpcurl

Самый простой метод — GetNowBlock2 с пустым запросом:

Запрос с полями — GetAccount. Поле address имеет тип bytes, то есть в JSON у grpcurl это
base64 от 21 сырого байта адреса (0x41 + 20 байт), а не base58:

Подпись считается на каждый вызов заново: fullMethod входит в payload, а nonce одноразовый.

5. Пример вызова: Node.js

6. Пример вызова: C#

7. Ответ и ошибки

Успешный ответ — обычное protobuf-сообщение контракта ноды; трейлеры ноды прокидываются клиенту
как есть. Ошибку прокси отдаёт стандартным gRPC-статусом и двумя трейлерами:

x-error-code — стабильный машинный код (те же коды, что и в REST);

x-retry-after-seconds — только там, где повтор имеет смысл (лимиты и квота).

Статус	`x-error-code`	Причина
`Unauthenticated`	`ERR_API_KEY_MISSING_SIGNATURE_HEADERS`	не передан один из четырёх заголовков
`Unauthenticated`	`ERR_API_KEY_INVALID_SIGNATURE`	payload собран иначе: не тот `fullMethod`, CRLF вместо LF, не тот secret
`Unauthenticated`	`ERR_API_KEY_TIMESTAMP_INVALID`	часы клиента разошлись с сервером больше чем на 2 минуты
`Unauthenticated`	`ERR_API_KEY_REPLAY`	повторно использован `nonce`
`Unauthenticated`	`ERR_API_KEY_NOT_FOUND` / `ERR_API_KEY_EXPIRED`	ключ удалён или истёк
`Unauthenticated`	`ERR_API_KEY_IP_NOT_AUTHORIZED`	IP не в allowlist ключа
`PermissionDenied`	`ERR_NODE_IP_NOT_ALLOWED`	IP не в allowlist подписки
`PermissionDenied`	`ERR_NODE_SUBSCRIPTION_NOT_FOUND` / `ERR_NODE_SUBSCRIPTION_EXPIRED`	нет активной подписки
`PermissionDenied`	`ERR_AUTH_USER_BANNED`	пользователь заблокирован
`ResourceExhausted`	`ERR_TOO_MANY_REQUESTS`	превышен rps или rpm тарифа
`ResourceExhausted`	`ERR_NODE_REQUEST_QUOTA_EXCEEDED`	исчерпана квота запросов за период подписки
`Unavailable`	—	нода недоступна; повторять с backoff
`Unimplemented`	—	метод вне контракта ноды или стримовый

Лимиты: MaxRequestsPerSecond берётся из тарифа, лимит в минуту выводится как rps × 60, сверху
действует общая квота запросов на период подписки. Остаток квоты и дней — в
GET /v1/node-subscription/current.

8. Настройка в Apidog

Новый проект → gRPC Project.

Импорт контракта → Server Reflection, адрес node.usdtpull.com:443. Загружать .proto
вручную не нужно: при импорте файлом Apidog требует добавить все зависимости
(core/Tron.proto и core/contract/*.proto) руками.

В запросе на вкладке Metadata добавить x-api-key, x-timestamp, x-nonce,
x-signature. Подпись зависит от метода и времени, поэтому для отладки её удобно
генерировать скриптом из раздела 2, а в автотестах — считать в pre-request скрипте.

1. Что нужно до первого вызова#

2. Подпись запроса#

3. Контракт: reflection или .proto#

4. Пример вызова: grpcurl#

5. Пример вызова: Node.js#

6. Пример вызова: C##

7. Ответ и ошибки#

8. Настройка в Apidog#