API доступности RAILGUN

Anon запускает монитор, который проверяет сервисы Railgun, от которых зависит его кошелёк: узел PPOI, собственный индексатор Anon, Subsquid, бродкастеры и Waku. Монитор повторно проверяет их примерно раз в 30 секунд по каждой сети и публикует результат одним небольшим JSON-документом по публичному URL. Читать его может любой: кошельки, дашборды, страницы статуса и скрипты. API-ключ и аккаунт не нужны.

GET https://api.anon.inc/api/v1/railgun/liveness

Это независимая картина, полученная собственным монитором Anon. Это не официальный статус Railgun и никогда не сигнал «безопасно проводить транзакции». Ограничения перечислены в разделе Чего это не показывает.

Бета: этот API находится в бета-версии. Поля, перечисления и форма ответа могут измениться без предупреждения. Срока уведомления нет, обязательств по объявлению устаревшим (deprecation) или выводу из эксплуатации (sunset) тоже нет. Пишите клиент так, чтобы он игнорировал неизвестные поля и значения. См. Статус беты.

Запрос никогда не запускает пробу; каждый ответ берётся из сохранённого снимка.

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

curl -i https://api.anon.inc/api/v1/railgun/liveness

Ответ содержит отчёт и заголовки кеширования:

HTTP/2 200
content-type: application/json; charset=utf-8
cache-control: public, max-age=15, s-maxage=30, stale-while-revalidate=30, stale-if-error=300
etag: "79d583eb71a37058"
access-control-allow-origin: *
access-control-expose-headers: ETag

Отправьте ETag обратно в заголовке If-None-Match, чтобы узнать, изменилось ли что-нибудь. Если нет, ответом будет 304 Not Modified без тела:

curl -i https://api.anon.inc/api/v1/railgun/liveness \
  -H 'If-None-Match: "79d583eb71a37058"'

В браузере обычный fetch работает с любого источника:

const response = await fetch("https://api.anon.inc/api/v1/railgun/liveness", {
  headers: { Accept: "application/json" },
  signal: AbortSignal.timeout(8000),
});
if (!response.ok) throw new Error(`liveness: HTTP ${response.status}`);
const report = await response.json();

Строка достоверна только до момента собственного истечения срока. Перед показом проверяйте каждую строку по своим часам. Строка без пригодных данных — unknown, а строка с истёкшим сроком жизни — stale. Ни ту, ни другую нельзя показывать как исправную:

const FIVE_MINUTES = 5 * 60 * 1000;
const CLOCK_SKEW = 30 * 1000;
const ACTIONABLE = new Set(["current", "catching-up", "degraded", "unavailable"]);

function effectiveStatus(check, now = Date.now()) {
  // Neither of these asserts anything that could go stale.
  if (check.status === "unmonitored" || check.status === "unknown") return check.status;
  // A status this client does not know is not evidence.
  if (!ACTIONABLE.has(check.status)) return "unknown";
  const observed = Date.parse(check.observedAt);
  const expires = Date.parse(check.expiresAt);
  // Missing, unparseable or inconsistent timestamps are not evidence either.
  if (!Number.isFinite(observed) || !Number.isFinite(expires)) return "unknown";
  if (observed > now + CLOCK_SKEW || expires <= observed) return "unknown";
  const stale = expires <= now || now - observed >= FIVE_MINUTES;
  return stale ? "stale" : check.status;
}

// Decide for yourself which chains count as mainnets.
const MAINNETS = new Set([1, 42161, 137, 56]);
const ppoi = report.checks.filter((c) => c.service === "ppoi" && MAINNETS.has(c.chainId));
console.log(ppoi.map((c) => `${c.chainId}: ${effectiveStatus(c)}`));

Эндпоинт

GET https://api.anon.inc/api/v1/railgun/liveness

• Аутентификация и параметры не нужны. Любая строка запроса игнорируется.
• HEAD возвращает только заголовки. OPTIONS отвечает на предварительные CORS-запросы.
• Тело имеет тип application/json; charset=utf-8 и занимает несколько килобайт.
• Один ответ охватывает все сервисы во всех сетях. Получите его один раз и отфильтруйте нужное.

Пример ответа

Сокращённый отчёт из пяти проверок, значения условные. Настоящий отчёт перечисляет все сервисы во всех сетях.

{
  "schemaVersion": 1,
  "generatedAt": "2026-10-03T12:00:05.418Z",
  "checks": [
    {
      "service": "waku",
      "chainId": null,
      "status": "current",
      "reason": "responding",
      "observedAt": "2026-10-03T11:59:40.993Z",
      "lastSuccessAt": "2026-10-03T11:59:40.993Z",
      "expiresAt": "2026-10-03T12:02:10.993Z",
      "metrics": { "peers": 2 }
    },
    {
      "service": "ppoi",
      "chainId": 1,
      "status": "current",
      "reason": "synced",
      "observedAt": "2026-10-03T11:59:52.206Z",
      "lastSuccessAt": "2026-10-03T11:59:52.206Z",
      "expiresAt": "2026-10-03T12:02:22.206Z",
      "metrics": { "position": 139296, "head": 139296 }
    },
    {
      "service": "broadcasters",
      "chainId": 1,
      "status": "current",
      "reason": "responding",
      "observedAt": "2026-10-03T11:59:40.993Z",
      "lastSuccessAt": "2026-10-03T11:59:40.993Z",
      "expiresAt": "2026-10-03T12:02:10.993Z",
      "metrics": { "responding": 82, "monitored": 85 }
    },
    {
      "service": "indexer",
      "chainId": 1,
      "status": "catching-up",
      "reason": "behind",
      "observedAt": "2026-10-03T11:59:58.731Z",
      "lastSuccessAt": "2026-10-03T11:59:58.731Z",
      "expiresAt": "2026-10-03T12:02:28.731Z",
      "metrics": { "position": 26115307, "head": 26115332 }
    },
    {
      "service": "subsquid",
      "chainId": 137,
      "status": "unavailable",
      "reason": "unreachable",
      "observedAt": "2026-10-03T12:00:01.093Z",
      "lastSuccessAt": "2026-10-03T11:58:09.870Z",
      "expiresAt": "2026-10-03T12:02:31.093Z",
      "metrics": {}
    }
  ]
}

• Строка waku — общая проверка Waku, поэтому её chainId равен null. Её статус current, а peers — число пиров отслеживаемого соединения Anon с Waku.
• Строка broadcasters имеет статус current: из 85 бродкастеров, которых Anon отслеживает в этой сети, ответили 82. monitored — настоящий знаменатель.
• Строка ppoi актуальна. position — проверенный индекс TXID узла PPOI, а head — текущий индекс того же узла.
• Строка indexer отстаёт от опорного значения на 25 блоков, что больше допуска, поэтому показывает catching-up.
• Строка subsquid имеет статус unavailable: монитор Anon не получил пригодного ответа на трёх пробах подряд. observedAt — время последней неудачной пробы, а lastSuccessAt хранит последний момент, когда сервис отвечал. У неудачи нет метрик.
• Проверки сейчас упорядочены так: waku, ppoi, broadcasters, indexer, subsquid, внутри каждого сервиса — по возрастанию chainId. Не полагайтесь на этот порядок.

Поля

Отчёт

Проверка

Метки времени — в UTC с точностью до миллисекунд и с буквальным Z на конце: YYYY-MM-DDTHH:mm:ss.sssZ.

Метрики

Могут появиться новые ключи. Неизвестные ключи игнорируйте. Каждая перечисленная здесь метрика — неотрицательное целое число не больше 2^53 − 1. Неизвестная метрика опускается. Её никогда не заменяют на 0, поэтому отсутствующий ключ нельзя читать как ноль. У неотслеживаемой строки "metrics": {}.

position может быть больше head: опорный блок читается по собственному расписанию и может быть старше на минуту. Ограничивайте отставание снизу нулём.

Статус и причина

Статус

Вот статусы на сегодня. Это не закрытое множество: пока API в бета-версии, значения могут добавляться или переименовываться без предупреждения. Любой нераспознанный статус считайте unknown — только для этой строки.

Строка, у которой наступил expiresAt, устарела независимо от того, что говорит её статус, и строка недоступного сервиса может дойти до вас именно так. См. Актуальность и кеширование.

Причина

Причины тоже не образуют закрытого множества. Пишите клиент так, чтобы неизвестная причина обрабатывалась только по status. Отслеживание Waku и бродкастеров всё ещё может добавить новые причины.

Пороговые значения

Это значения на момент запуска. Они относятся к политике монитора, а не к схеме, поэтому Anon может изменить их, не меняя версию схемы.

Сервисы и сети

• Сети. Отслеживаются основные сети Ethereum (1), Arbitrum (42161), Polygon (137) и BNB Chain (56). Sepolia (11155111) — тестовая сеть, никогда не входит в сводку по основным сетям и не имеет развёртывания Subsquid, поэтому её строка subsquid не отслеживается. Новые сети могут появиться без предупреждения.
• Waku и бродкастеры. Обе проверки отслеживаются с 2026-10-04 и сообщают настоящий статус с причиной responding или partial-coverage и метриками peers, responding и monitored. По-прежнему могут появиться новые значения reason и новые ключи metrics. Обрабатывайте это так, как описано в разделе Статус беты.
• Опорные блоки. Последние блоки сетей берутся из публичных RPC-эндпоинтов. Собственной строки у них нет.
• Кто что запускает. Узел PPOI и развёртывание Subsquid Anon не эксплуатирует. Сбой там отображается как показание Anon о настроенном развёртывании.

О самих сервисах см. Прокси PPOI, Сеть бродкастеров и Синхронизация кошелька.

Актуальность и кеширование

Монитор примерно раз в 30 секунд повторно проверяет каждый отвечающий источник и сохраняет снимок. Каждый запрос обслуживается из этого снимка в памяти. Ответ содержит:

Cache-Control: public, max-age=15, s-maxage=30, stale-while-revalidate=30, stale-if-error=300

Насколько может устареть строка? Для отвечающего источника данных строка на исходном сервере может быть старше примерно на 44 секунды: период в 30 секунд, 3 секунды джиттера, проба длительностью до 10 секунд и секунда на публикацию. Кеши добавляют ещё до 60 секунд (30 секунд s-maxage и 30 секунд stale-while-revalidate). Поэтому исправная строка доходит до вас не позже чем примерно через 104 секунды после наблюдения, в пределах своего срока жизни в 150 секунд, и не должна приходить уже просроченной.

Источник, который продолжает давать сбои, проверяется реже. После каждого подряд идущего сбоя монитор ждёт вдвое дольше, прежде чем снова обратиться к этому источнику: 30 секунд, затем 60 секунд, затем предел в 2 минуты. С учётом джиттера и пробы, которая может длиться до 10 секунд, строка недоступного источника может быть старше примерно на 133 секунды на исходном сервере и примерно на 193 секунды к тому моменту, когда кеш отдаёт её вам. Это больше её срока жизни в 150 секунд, поэтому строка unavailable может дойти до вас уже просроченной. Тогда она выглядит как устаревшая, а не как unavailable. Считайте устаревшую строку «нет свежего показания», но никогда не исправной. Недоступный сервис может выглядеть именно так.

Актуальность принадлежит каждой строке, а не HTTP. Считайте строку устаревшей, если её expiresAt совпадает с текущим моментом по вашим часам или уже прошёл, либо если с её observedAt прошло 5 минут или больше, что бы ни говорил её status. Считайте строку unknown, если временная метка, нужная её статусу, отсутствует или не читается, если observedAt находится в будущем более чем примерно на 30 секунд или если expiresAt не позже observedAt. Ответ 200, ответ 304 или попадание в кеш никогда не продлевают строку.

Остановившийся монитор. Пока монитор жив, generatedAt обновляется не реже чем раз в 30 секунд, даже если все пробы зависли. Если монитор останавливается, сохранённый отчёт остаётся прежним, а его строки устаревают по expiresAt. То же происходит с копией, отданной через stale-if-error. Обе выглядят устаревшими и никогда исправными.

ETag и 304. ETag — сильный валидатор: 16-символьный хеш тела в кавычках. Монитор публикует отчёт при завершении каждой пробы и не реже чем раз в 30 секунд, а generatedAt входит в тело, поэтому ETag меняется не реже. If-None-Match сравнивается слабо: префикс W/ игнорируется, а * подходит к любому значению. Ответ 304 содержит заголовки ETag, Cache-Control и CORS и не содержит тела.

Коды состояния HTTP и ошибки

На этом маршруте ошибки имеют вид {"error": "<message>"} с заголовками Content-Type: application/json; charset=utf-8 и Cache-Control: no-store:

{"error":"liveness report unavailable"}

Ветвите логику по коду состояния HTTP, а не по тексту сообщения. Ответ шлюза 404 ({"message":"Not Found"}) и ответ CDN 429 используют другие тела: ответ 429 — это страница Cloudflare в формате text/plain.

В браузере 429 прочитать нельзя. У страницы 429 от CDN нет Access-Control-Allow-Origin, поэтому браузер её блокирует, а fetch отклоняется с TypeError, как при любом сетевом сбое или ошибке CORS. Ваш код не увидит ни статус, ни Retry-After. Относитесь к любому сетевому сбою так же, как к 429 или 503: увеличивайте паузы, храните последний хороший отчёт и позвольте его строкам устареть по expiresAt.

После загрузки первого снимка сбои никогда не приводят к 503. Сервер продолжает отдавать последний снимок, а его строки устаревают по expiresAt.

CORS

Отчёт публичный и не содержит данных, зависящих от вызывающего, поэтому каждый ответ разрешает любой источник:

Это отправляется в каждом ответе (200, 304, 204, 405 и 503) независимо от Origin запроса. Нет Access-Control-Allow-Credentials. Ответ не содержит Vary: Origin, но CDN всё равно хранит отдельную кешированную копию для каждого значения заголовка запроса Origin, поэтому первый запрос с нового источника может оказаться кеш-промахом (MISS). Строка запроса игнорируется: запрос с любым ?x= использует ту же копию.

На предварительный запрос (OPTIONS) отвечают кодом 204 и заголовками:

Обычный fetch с заголовком Accept — простой запрос и не требует предварительного. Скрипту, который сам задаёт If-None-Match, он нужен, и этот заголовок разрешён.

Добросовестное использование

• Ключа и SLA нет. Это публичная лента в бета-версии, работающая в меру возможностей.
• Соблюдайте Cache-Control и используйте ETag с If-None-Match, чтобы неизменившийся отчёт обходился ответом 304.
• Опрашивайте не чаще чем раз в 15–30 секунд. Данные меняются примерно раз в 30 секунд, поэтому более частые запросы вернут лишь кешированные копии.
• Кошелькам стоит запрашивать отчёт, когда пользователь открывает экран, который от него зависит, а не по таймеру.
• Серверы, которые опрашивают отчёт, должны отправлять описательный User-Agent, сообщающий, кто вы, например my-wallet/1.4 (+https://example.com/contact).
• Запросы свыше 120 в минуту с одного IP на этот путь ограничиваются: в ответ приходит 429 примерно на 60 секунд. Попадания в кеш тоже учитываются. При 429 и 5xx увеличивайте паузы между запросами.
• В браузере 429 выглядит как ошибка CORS или сети, а не как читаемый ответ. Относитесь к любому сетевому сбою так же, как к 429 или 503: увеличивайте паузы, храните последний хороший отчёт и позвольте его строкам устареть по expiresAt (см. Коды состояния HTTP и ошибки).

Статус беты

Этот API находится в бета-версии, и Anon пока не даёт никаких обещаний о его стабильности.

• Может измениться без предупреждения. Поля, перечисления и форма ответа могут быть добавлены, переименованы, изменены по типу или удалены без срока уведомления. Anon не обязуется проводить процедуру объявления устаревшим или вывода из эксплуатации и не обещает заголовки Deprecation и Sunset.
• schemaVersion может измениться. /api/v1 — версия маршрутов шлюза для всего развёртывания, а не версия этого эндпоинта. schemaVersion самого эндпоинта находится в теле, сейчас 1, и он тоже может измениться. JSON Schema намеренно нестрогая и описывает сегодняшний ответ. Это не обещание.
• Пока хост — api.anon.inc. Позже может появиться псевдоним вроде api.railscan.io. Срок не обещается.
• Изменения фиксируются по мере возможности в журнале изменений ниже.

Как написать клиент, который это переживёт:

• Игнорируйте неизвестные поля. Игнорируйте неизвестные поля объектов на всех уровнях: в отчёте, в каждой проверке и в metrics.
• Не полагайтесь на закрытые множества. Нераспознанный status считайте unknown — только для этой строки. Нераспознанную reason считайте «без подробностей» и действуйте по status. Игнорируйте строки с service или chainId, которые вы не используете. Игнорируйте неизвестные ключи metrics.
• Пусть ломается одна строка, а не весь отчёт. Одна нечитаемая строка не должна обнулять все остальные.
• Проверяйте schemaVersion. Если это неизвестное вам значение, форма могла измениться. Считайте отчёт нечитаемым, пока не обновитесь, а не гадайте.

Что верно сегодня. Так эндпоинт ведёт себя сейчас, поэтому обрабатывайте это правильно, но это не обещание:

• Метрики. У каждой проверки есть объект metrics, а ключ неизвестной метрики опускается. У неотслеживаемой строки metrics: {}. Никогда не читайте отсутствующую метрику как 0.
• Одна строка на область. Каждая пара из сервиса и chainId встречается не более одного раза. waku — единственная общая строка, у неё chainId: null. Не суммируйте строки вслепую. Решайте, какие сети считать основными, по собственному списку допустимых сетей: Sepolia (11155111) никогда не входит в сводки по основным сетям.
• Актуальность определяется по строке. Используйте правило из раздела Актуальность и кеширование. Сейчас expiresAt равен null только у строк unknown и unmonitored.
• Числа. Ограничивайте отставание снизу нулём, потому что position может превышать head. responding никогда не превышает monitored. Все метрики — неотрицательные безопасные целые числа.

Чего это не показывает

• Это не официальный статус Railgun. Это монитор Anon, который читает сервисы, настроенные в Anon, из инфраструктуры Anon. Ваша картина по этим сервисам может отличаться.
• Это не сигнал «безопасно проводить транзакции». Если у ppoi статус current, это не означает, что конкретное экранирование доступно для траты или конкретное доказательство действительно. Это означает лишь, что настроенный узел PPOI проверил всё до собственного текущего индекса. Это ничего не говорит о PPOI-валидности, соответствии требованиям или доступном балансе какого-либо кошелька.
• Строка ухудшенной работы бродкастеров — это неполное показание. Она означает, что часть отслеживаемых бродкастеров не ответила. Другие бродкастеры или способы доставки могут по-прежнему работать. Способ и его ограничения приватности проверьте в разделе Сеть бродкастеров.
• Пиры Waku — это не доставка. peers считает соединения отслеживаемого соединения Anon. Он не показывает, что сообщение доходит до бродкастера и возвращается.
• Строки индексатора и Subsquid — не синхронизация вашего кошелька. Они показывают, догнали ли эти сервисы свои сети. Синхронизация самого кошелька — отдельный процесс. См. Синхронизация кошелька.

История

За последние 14 дней GET https://api.anon.inc/api/v1/railgun/liveness/history возвращает те же строки в виде 5-минутных интервалов, с долей доступности за 24 часа, 7 и 14 дней. Это отдельный эндпоинт со своим кешем, предназначенный для графиков и страниц статуса. См. API истории доступности. Чтобы узнать, что верно прямо сейчас, по-прежнему используйте этот эндпоинт.

Приватность

Запрос к этому эндпоинту не несёт ничего о вашем кошельке: ни адреса, ни аккаунта. Anon и CDN перед ним всё же видят ваш IP-адрес и User-Agent, как при любом HTTPS-запросе. Кошелёк, который опрашивает отчёт по таймеру, показывает интерес этого IP к Railgun в ритме 30 секунд. Если это важно, опрашивайте отчёт лениво, только когда он нужен, или получайте его на своём сервере и обслуживайте пользователей из этого кеша.

Журнал изменений

2026-10-04

Waku и бродкастеры теперь отслеживаются, поэтому их строки сообщают настоящий статус вместо unmonitored. Ограничение частоты применяется: при более чем 120 запросах в минуту с одного IP на этот путь в ответ приходит 429 примерно на 60 секунд.

Версия 1 (бета)

Первый выпуск, в бета-версии: обещаний стабильности нет. schemaVersion 1. Сервисы ppoi, indexer, subsquid, broadcasters и waku в сетях Ethereum, Arbitrum, Polygon, BNB Chain и Sepolia. Waku и бродкастеры перечислены, но на момент запуска не отслеживались. Срок жизни каждой проверки — 150 секунд, монитор повторно проверяет отвечающий источник примерно раз в 30 секунд (источник, который продолжает давать сбои, — реже), а ответ можно кешировать в общих кешах на 30 секунд.