Skip to main content
orbitflare-apex-go является клиентом на Go для Apex. Он держит одно постоянное QUIC-соединение на каждый эндпоинт Apex, аутентифицируется клиентским сертификатом, производным от вашего API-ключа, отправляет одну сериализованную транзакцию на поток и переподключается с 0-RTT при обрыве соединения. Его возможности совпадают с возможностями клиента на Rust, а его клиентский сертификат побайтово идентичен сертификату клиента на Rust.

Установка

Модуль называется github.com/orbitflare/orbitflare-apex-go; исходный код находится на GitHub:
Модуль состоит из двух пакетов: Транзакции собираются с помощью solana-go, который поддерживает сообщения legacy, v0 и v1. Путь QUIC не зависит от пакета rpc. Модуль требует Go 1.26 или новее.

Быстрый старт

Полная программа. Она собирает memo-транзакцию с вычислительным бюджетом и чаевыми, отправляет её по QUIC и ждёт подтверждения. Она читает те же переменные окружения, что и Быстрый старт: APEX_API_KEY, KEYPAIR_PATH и SOLANA_RPC_URL.
main.go
SendTransaction возвращает управление, как только транзакция записана в поток, за микросекунды и без подтверждения получения. Фрагменты ниже встраиваются в эту программу: они используют её ctx, client, apiKey, payer, tipAccount, blockhash, solanaRPC и tx. Добавьте импорты стандартной библиотеки, которые использует фрагмент, например errors, encoding/base64 или sync.

Отправка с ответом

Двунаправленный поток читает ответ Apex перед возвратом: подпись, если транзакция принята, или *apex.RejectedError с кодом допуска и сообщением. Это стоит одного дополнительного обмена с эндпоинтом, поэтому используйте его при интеграции или когда вам нужна причина сразу в ответе.
SendWithResponse(ctx, wire) делает то же самое с байтами, которые у вас уже есть, и возвращает сырой apex.Admission (Accepted, Signature, Code, Message).

Транзакции v1

Транзакции v1 могут иметь размер до 4096 байт. Вычислительный бюджет задаётся в solana.TransactionConfig сообщения, а не инструкциями ComputeBudget, и каждый незаданный лимит равен 0, поэтому задайте лимит вычислительных единиц, лимит размера загружаемых данных аккаунтов и, ради приоритета, комиссию. См. Транзакция v1.

Сырые байты

Если ваша транзакция уже сериализована (другим подписантом, другим процессом или в файле), отправьте байты как есть. Ничто не кодирует их заново.
apex.EncodePacket(wire, mevProtect, maxRetries) возвращает в точности тот пакет, который клиент записывает в поток: длину из 8 байт, транзакцию и завершающий блок из 3 байт. Это эталон для других языков.

HTTP

Пакет rpc покрывает все HTTP-маршруты эндпоинта Apex. Он передаёт ключ в заголовке x-api-key.
SendTransaction является JSON-RPC sendTransaction и подходит для замены в существующем коде. SendTransactionBinary отправляет сырые байты на /send-bin, самый дешёвый путь по HTTP. Последние два аргумента: mevProtect и maxRetries; nil оставляет бюджет повторов эндпоинта по умолчанию.

Пакеты

SendBatch отправляет до 16 транзакций в одном запросе. Каждая принимается отдельно, а результат показывает, какие из них были приняты.

Бандлы

SendBundle отправляет от одной до четырёх транзакций, которые попадают в блок по порядку, все или ни одной, причём ровно одна из них с чаевыми. Опрашивайте BundleStatuses, пока бандл не попадёт в блок или не завершится неудачей. См. Бандлы.

Параллельные отправки

*apex.Client безопасен для параллельного использования, и каждая отправка получает собственный поток в одном соединении. Создайте клиент один раз и отправляйте из любого числа горутин.

Регионы

Каждый эндпоинт Apex представлен константой apex.Region. apex.ParseRegion принимает код или название города, а apex.AllRegions содержит их список.
QUICEndpoint() возвращает <code>.apex.orbitflare.com:7001, а RPCURL() возвращает http://<code>.apex.orbitflare.com. См. Эндпоинты и регионы.

Транспорты

Транспорт не влияет на приоритет и маршрутизацию. На них влияют чаевые.

API

Каждый вызов, который обращается к сети, принимает context.Context, поэтому вы можете отменить отправку или задать ей крайний срок. Вызовите Close, когда закончите работу; он останавливает фоновое переподключение и закрывает сокет.

Параметры

Нулевое значение каждого поля даёт значения по умолчанию, поэтому задавайте только то, что вам нужно:

Keep-alive и переподключения

Соединение остаётся открытым благодаря QUIC PING каждую секунду при тайм-ауте простоя 30 секунд на эндпоинте Apex. В прогретом соединении отправка сводится к одному открытию потока и одной записи. Если соединение оборвалось:
  • Фоновая горутина замечает это и сразу выполняет новое рукопожатие, поэтому следующая отправка обычно находит живое соединение. Если соединение закрыл сам эндпоинт (неизвестный ключ, слишком много соединений), горутина удваивает ожидание после каждой попытки, вплоть до 30 секунд, вместо того чтобы настойчиво повторять.
  • Переподключение использует закэшированный сессионный тикет и отправляет ожидающую транзакцию в первом пакете рукопожатия (0-RTT). Если эндпоинт отклоняет ранние данные, клиент отправляет их повторно после рукопожатия.
  • Отправка, которая не удалась из-за потери соединения, переподключается и повторяется один раз. Установите DisableAutoReconnect, чтобы обрабатывать это самостоятельно.
  • При каждом переподключении имя хоста разрешается заново, поэтому клиент на apex.Global следует за балансировщиком к следующему ближайшему эндпоинту, когда его собственный выходит из строя, без перезапуска. Разрешение выполняется в фоновом переподключении, а не при отправке; если оно не удалось или заняло больше двух секунд, клиент сохраняет прежний адрес. Эндпоинт, заданный IP-адресом, никогда не разрешается.
Экспортируйте состояние соединения в свои метрики:

Ошибки

Ошибки оборачивают сигнальное значение, поэтому errors.Is показывает, на каком этапе произошёл сбой, а errors.As даёт доступ к типизированным ошибкам.
Пакет rpc возвращает *rpc.Error с кодом и сообщением при отклонении JSON-RPC или простого HTTP-маршрута и rpc.ErrBadResponse для ответа, который он не может прочитать. Отклонение простого HTTP-маршрута имеет код 0 и сообщение вида label: message, а метки перечислены в разделе Ошибки и лимиты запросов.

Проверьте свой ключ

Выведите ключ сертификата, который выводится из вашего API-ключа. Он должен совпадать с клиентским публичным ключом, показанным рядом с ключом в вашей панели управления; если не совпадает, ключ был скопирован неправильно.

Примеры в репозитории

Все примеры читают APEX_API_KEY, KEYPAIR_PATH (по умолчанию payer.json), SOLANA_RPC_URL и при необходимости APEX_REGION, APEX_QUIC, APEX_RPC, TIP_LAMPORTS, APEX_TX_VERSION (legacy или v1), APEX_MEMO_BYTES и APEX_CU_LIMIT. Каждый отправляет memo с чаевыми и сообщает слот, в который оно попало.

Чего клиент не делает

  • Не собирает и не подписывает транзакции и не выбирает вашу приоритетную комиссию.
  • Не выполняет симуляцию и preflight-проверки. Этого не делает никто между вами и лидером.