Перейти к основному содержимому

Примеры NEAR Data

Готовое расследование​

Поймать новый блок как можно раньше, а затем подтвердить его после finality​

Используйте это расследование, когда нужно заметить новый блок как можно раньше, но финальный ответ всё равно должен опираться на финализированный блок и иногда на точное чтение через RPC.

Стратегия

Пусть NEAR Data сначала скажет, что что-то изменилось, а затем переиспользуйте то же семейство блоков для стабильного подтверждения.

01block-optimistic или last-block-optimistic дают самый ранний полезный сигнал.

02block или last-block-final подтверждают, что то же наблюдение дошло до финализированной истории.

03RPC block нужен только в самом конце, когда уже известна точная высота или хеш.

Цель

  • Быстро заметить недавний блок, а затем проверить то же самое, когда догонит finality.
ПоверхностьЭндпоинтКак используемЗачем используем
Самое быстрое обнаружениеNEAR Data block-optimisticОпрашиваем оптимистичные блоки, чтобы как можно раньше заметить новое изменение в семействе блоковДаёт самый ранний полезный сигнал ещё до финализированного подтверждения
Маршрут для последнего оптимистичного блокаNEAR Data last-block-optimisticИспользуем маршрут перенаправления, когда клиент должен всегда следовать за самым новым оптимистичным блокомУпрощает клиент опроса, когда важнее получать последний блок, а не работать с явными высотами
Стабильное подтверждениеNEAR Data block или last-block-finalПовторно проверяем то же семейство блоков, когда финальность догоняет ранее замеченное изменениеПодтверждает, что замеченное в оптимистичном режиме изменение действительно попало в финализированную историю
Лёгкая сводка по блокуNEAR Data block-headersЧитаем данные заголовков, если для ответа достаточно времени и общего хода событийПозволяет не запрашивать более широкий блок, когда хватает заголовков
Точный разбор через RPCRPC Блок по ID или Блок по высотеПолучаем точный блок, как только понятно, какой именно блок важенЗдесь уже имеет смысл RPC, если нужен тот самый блок-объект, который вернул бы сам протокол

Что должен включать полезный ответ

  • какое наблюдение по оптимистичному блоку впервые запустило расследование
  • когда то же наблюдение стало финализированным
  • изменил ли точный разбор через RPC интерпретацию

Shell-сценарий проверки финализированного блока​

Используйте этот сценарий, когда вспомогательный маршрут сам выбирает для вас последний финализированный блок, но следующий шаг всё равно требует точной проверки через RPC.

Что вы делаете

  • Смотрите redirect, который возвращает GET /v0/last_block/final.
  • Загружаете итоговый документ блока.
  • Извлекаете block.header.height через jq.
  • Переиспользуете эту высоту в RPC block по высоте.
NEARDATA_BASE_URL=https://mainnet.neardata.xyz
RPC_URL=https://rpc.mainnet.fastnear.com

FINAL_LOCATION="$(
  curl -s -D - -o /dev/null "$NEARDATA_BASE_URL/v0/last_block/final" \
    | awk 'tolower($1) == "location:" {print $2}' \
    | tr -d '\r'
)"

printf 'Redirect target: %s\n' "$FINAL_LOCATION"

curl -s "$NEARDATA_BASE_URL$FINAL_LOCATION" \
  | tee /tmp/neardata-final-block.json \
  | jq '{height: .block.header.height, hash: .block.header.hash}'

BLOCK_HEIGHT="$(jq -r '.block.header.height' /tmp/neardata-final-block.json)"

curl -s "$RPC_URL" \
  -H 'content-type: application/json' \
  --data "$(jq -nc --arg block_height "$BLOCK_HEIGHT" '{
    jsonrpc: "2.0",
    id: "fastnear",
    method: "block",
    params: {
      block_id: ($block_height | tonumber)
    }
  }')" \
  | jq '{height: .result.header.height, hash: .result.header.hash, chunks: (.result.chunks | length)}'

Зачем нужен следующий шаг?

Helper route — самый простой способ опрашивать сценарий «последний финализированный блок». Как только он сообщил точную высоту блока, RPC становится естественным следующим шагом, если нужен точный блок-объект без догадок о том, что именно проверять.

Частые задачи​

Отслеживать последний оптимистичный блок​

Начните здесь

Следующая страница при необходимости

Остановитесь, когда

  • Уже можно сообщить о последнем оптимистичном блоке или зафиксировать отставание по свежести.

Переходите дальше, когда

Безопасно отслеживать ход финализации блоков​

Начните здесь

Следующая страница при необходимости

Остановитесь, когда

  • Уже можно показывать движение финализированных блоков без перехода к более глубоким протокольным деталям.

Переходите дальше, когда

  • Пользователю нужны точные поля блока или семантика транзакций. Переходите к RPC Reference.

Использовать маршруты перенаправления в клиенте опроса​

Начните здесь

Следующая страница при необходимости

  • Следуйте по URL блока, который вернул маршрут перенаправления, и уже там читайте нужные данные.

Остановитесь, когда

  • Клиент надёжно проходит по маршруту перенаправления и получает нужный ресурс блока.

Переходите дальше, когда

  • Само перенаправление мешает клиенту. Тогда переходите на прямые маршруты блоков.

Перейти от опроса свежих блоков к точному RPC-разбору​

Начните здесь

  • Используйте подходящий маршрут NEAR Data, чтобы найти недавний блок или событие в семействе блоков, которое нужно исследовать.

Следующая страница при необходимости

  • Block by Height, Block by ID или другой RPC-метод, как только станет понятно, какой именно блок или следующий объект для проверки нужен.

Остановитесь, когда

  • Уже можно чётко назвать недавний блок, который заслуживает проверки через RPC.

Переходите дальше, когда

  • Пользователь просит точную структуру данных в терминах протокола, а не просто свежее чтение.

Частые ошибки​

  • Воспринимать NEAR Data как push-стрим, а не как API для опроса.
  • Начинать с RPC, когда настоящая задача — мониторинг свежих блоков.
  • Забывать, что невалидный ключ может вернуть 401 ещё до перенаправления, а сами перенаправления подходят не каждому HTTP-клиенту.
  • Оставаться на NEAR Data после того, как пользователь уже попросил точные протокольные детали блока.

Полезные связанные страницы​