Інтеграція з Glassnode API для on-chain аналітики

Інтеграція Glassnode API: де губляться дані on-chain

Інтеграція Glassnode API починається не з отримання ключа, а з устрою потоку: підключення до даних блокчейну відбувається або підпискою на нові блоки, або періодичним опитуванням метрик за адресами й агрегатами.

Коректну картину обидва режими дають лише за безперервного з'єднання та явної обробки реорганізацій ланцюга — увесь інший час дані виглядають цілими, хоча вже втрачені.

Перший збій — пропуски блоків під час обриву з'єднання.

Підписка відновлюється мовчки, без довантаження пропущеного діапазону висот, і у звіті залишається діра: метрики потоку на кшталт кількості активних адрес за добу занижені, а перерахунок за неповними даними відтворює ту саму помилку. Знайти її постфактум можна лише звіркою з власним вузлом.

Другий клас — розходження балансів гаманця після реорганізації. Транзакція, уже врахована як підтверджена, переходить у скасовану гілку, а агрегат за адресою зберігає попереднє значення: у ризик-моделі така адреса проходить як платоспроможна до першої звірки.

Третя проблема — затримка. Ручне вивантаження метрик відстає від стану мережі на години, тому ліміти й стоп-фактори перераховуються за вчорашнім зрізом.

Ціна всіх трьох збоїв одна: цифри у звітності перестають сходитися з даними вузла, і довіра до них втрачається раніше, ніж виявляється причина. Розбираємо, як це закривається на рівні архітектури збору.

Що дає налагоджений потік мережевих метрик

Потік мережевих метрик блокчейну корисний рівно настільки, наскільки він свіжий. Збирач опитує джерело з кроком, що збігається з вікном агрегації метрики, і зберігає позначку останньої успішної відповіді: дашборд показує поточний стан мережі, а не зріз, що відстав на добу.

Якщо надійшла часткова відповідь, вікно позначається як неповне й перезапитується, а не потрапляє у сховище з дірою.

Цілісність історії транзакцій тримається на ідемпотентному записі: метрика прив'язана до пари «сутність — часове вікно», тому повторне завантаження того самого діапазону не створює дублів і не розриває ряд.

Довантаження йде окремим проходом від межі вже зібраних даних, і пропущений інтервал закривається сам після збою.

Стійкість збору метрик — це поведінка під час відмов, а не їх відсутність.

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

Інтеграцію з Glassnode ведемо як зі звичайним зовнішнім джерелом — зі схемою даних, контрактом відповіді та перевірками якості на вході.

Результат вимірюваний: затримка між подією в мережі та її появою на дашборді — хвилини, частка пропущених вікон в історії — нуль, а клас відмов, коли повторне завантаження псувало вже зібрані дані, знято повністю.

Підключення до Glassnode: опитування, підписка, репліка

Режим отримання даних визначає, що продукт зможе робити: аналітичний дашборд терпить затримку в хвилини, а алерт на рух коштів за гаманцем — ні. Тому вибір робиться не «який спосіб кращий», а під потрібну свіжість та обсяг запитів. Нижче — три робочі схеми та їхні обмеження.

Порівняння режимів

На практиці схеми комбінуються: підписка закриває термінові події, опитування — регулярні зрізи та звірку, репліка — важкі вибірки й те, що не повинно виходити назовні.

Раз на добу проганяємо звірку репліки із зовнішнім джерелом за контрольними метриками — розходження вище порогу означає відставання або збій індексації, і ми перемикаємо розрахунки на дані з опитування, поки репліка доганяє. Такий контур дає передбачувану свіжість без постійного зростання кількості запитів.

Етапи впровадження: від аудиту до експлуатації

Збір даних on-chain рідко ламається одразу — розходження накопичується: частина адрес випадає з вибірки, метрика рахується за іншим вікном, реорганізація блоку спотворює історію заднім числом.

Тому впровадження йде фіксованими етапами, де кожен наступний спирається на перевірений результат попереднього, а не на припущення.

1. Аудит джерел даних. Інвентаризуємо, які метрики вже збираються, з яких джерел, з якою періодичністю, де дублі та прогалини. Фіксуємо перелік адрес і контрактів, які справді потрібні продукту, — решта у вибірку не потрапляє.

2. Схема потоків даних. Описуємо шлях від запиту до API до вітрини: хто споживач, де кеш, де зберігається сира відповідь, як обробляються обмеження за частотою запитів і повторні спроби під час збою.

3. Налаштування доступу. Розводимо середовища, видаємо окремі ключі сервісам, налаштовуємо ротацію та права лише на читання — витік одного ключа не відкриває доступ до решти.

4. Реалізація збагачення. Приводимо відповіді до власної моделі, нормалізуємо адреси й одиниці вимірювання, обробляємо часткові та порожні відповіді як штатний випадок, а не як помилку.

5. Перевірка на історичних даних. Проганяємо розрахунки на минулих періодах і звіряємо з незалежним джерелом або власною копією вузла. Розходження розбираємо до причини — зазвичай це інший інтервал агрегації або невраховані внутрішні перекази.

6. Моніторинг. Ставимо оповіщення на свіжість даних, частку помилок і затримку оновлення: збій видно до того, як його помітить користувач.

7. Передача в експлуатацію. Віддаємо документацію щодо потоків і метрик, регламент оновлення залежностей, план відкату та навчання команди, яка залишається вести рішення.

Що передаємо на руки: схеми, права доступу, регламенти

Після запуску у вас залишається не набір скриптів, а комплект, за яким команда може експлуатувати збір даних і розвивати його без нас. Нижче — що саме передаємо на руки і навіщо кожен артефакт потрібен у щоденній роботі.

• Конфігурації збору — перелік метрик, частоти опитування, вікна агрегації та ліміти звернень до Glassnode API, з позначками, що змінювати при зростанні навантаження.
• Схема потоків даних — шлях від запиту до сховища: де стоять буфери, як обробляються повтори та розходження між джерелами.
• Правила доступу до даних — ролі та області видимості, порядок видачі й відкликання ключів, зберігання секретів окремо від репозиторію, ротація.
• Регламент збору метрик — обов'язковий та опціональний набори, фіксація пропусків, пороги, після яких збір вважається неповним.
• Документація щодо інтеграції — опис полів і типів, словник метрик, приклади запитів і відповідей, порядок версіонування схеми.
• Регламент реакції на збій — рівні інцидентів, строки реакції, що вважається деградацією, а що зупинкою збору.
• Інструкція відновлення після збою — відкат до останньої цілісної точки, довантаження пропущеного діапазону, перевірка збіжності.

Окремо передаємо тестовий контур з тими самими правилами доступу: зміни метрик і частот перевіряються на ньому, а не на робочому зборі.

Разом із матрицею відповідальних — хто володіє конфігурацією, хто видає доступи, куди повідомляти про проблеми — це знімає залежність від однієї людини.

Кейс: аналітика гаманців без втрати історії

Клієнт — сервіс аналітики гаманців: адреси, баланси, зв'язки між контрагентами. Збір ішов через власну службу індексації, і під час обриву зв'язку з вузлом блокчейну підтверджені блоки не доганялися: історія транзакцій рвалася, а баланси розходилися з фактичним станом мережі.

Окремий біль — перебудова ланцюжка: після відкату частини блоків записи залишалися від попередньої гілки й псували вибірки за адресами.

Ми перевели збір на Glassnode і переписали контур запису: блоки й транзакції зберігаються ідемпотентно за хешем, висота блоку працює вказівником догону, а після простою служба сама дочитує пропущений діапазон.

Раз на добу дані звіряються з нашим вузлом блокчейну за контрольними сумами балансів і кількістю операцій — розходження йдуть у звіт, а не в клієнтські вивантаження.

Що змінилося

• Частка втрачених блоків: 6–7% на кожному обриві → нуль, догін відбувається автоматично.
• Відновлення історії після обриву: близько 40 хвилин ручних операцій → 2–3 хвилини без участі інженера.
• Розходження під час звірки з вузлом: до 2% вибірок → менше 0,1%, кожне розбирається точково.

Для команди клієнта це означає, що аналітика гаманців перестала залежати від стійкості каналу до вузла, а спірні баланси більше не потребують ручного перерахунку.

Чим підписка на події відрізняється від періодичного опитування?

Різниця в тому, хто ініціює передавання даних. За підписки джерело, наприклад Glassnode, саме надсилає подію, щойно в мережі з'явився новий блок або пройшла транзакція за відстежуваною адресою.

За періодичного опитування ми самі запитуємо зріз за розкладом і порівнюємо, що змінилося. Від цього вибору залежать затримка оновлення даних, навантаження на джерело даних і вартість обслуговування збору.

Затримка за підписки дорівнює часу доставки події — секунди, і вона не зростає з кількістю відстежуваних адрес.

В опитування затримка в середньому дорівнює половині інтервалу: хочеш свіжіше — опитуй частіше, а кожен цикл — це ще один запит за всіма адресами, навіть якщо руху за ними не було.

Навантаження й супровід розходяться у зворотний бік. Підписка потребує постійно живого з'єднання: контроль обривів, перепідключення з відновленням контексту, накопичення подій на час збою.

Опитування простіше — переживає перезапуск і дедуплікується за курсором, — але на сотнях адрес перетворюється на потік порожніх відповідей.

За замовчуванням проєктуємо гібрид: підписка для оперативних реакцій, опитування — для звірки стану та добору пропущених періодів. Затримка залишається секундною, а збір даних не залежить від того, чи переживе з'єднання нічний обрив.

Часті технічні питання щодо підключення до аналітики

Перед стартом інтеграції інженери задають приблизно ті самі питання: як аналітичний шар поводиться під навантаженням, що відбувається під час вичерпання лімітів і як переконатися, що метрики не «поїхали» після збою.

Нижче — відповіді за чотирма вузлами, які найчастіше визначають стійкість роботи з Glassnode та будь-яким іншим джерелом даних on-chain.

Чи можна перезібрати історію даних?

Історія завантажується порціями з курсором за часом і записується так, що повторний прогін не створює дублів. Перезбирання йде в окремому контурі й не заважає оперативному потоку метрик — період і набір показників можна уточнити заднім числом.

Як перевіряється цілісність даних?

Звіряємо контрольні суми за інтервалами, шукаємо пропуски та аномальні стрибки щодо сусідніх точок, агрегати порівнюємо з незалежним джерелом. Розходження потрапляють у звіт і не доїжджають до вітрини, на якій будуються рішення.

Що відбувається за недоступності джерела?

Резервне джерело метрик підключається за перевіркою доступності — другий провайдер або власна нода з індексером. Після повернення основного пріоритет перемикається назад автоматично, а дані за час простою позначаються як неповні, щоб аналітика не будувала висновки на дірах.

Обговоримо задачу та повернемося з оцінкою і планом

Точна оцінка та план робіт випливають із конкретики, а не із загальних побажань. Тому перший крок співпраці — розбір задачі інтеграції з інженером, який її вестиме: він ставить запитання, ви відповідаєте на ті, що вже є, а відсутні вимоги до збору даних ми формулюємо разом.

Що надсилаєте натомість, щоб оцінка була точною:

• які мережі та типи адрес у фокусі, включно з позначкою біржових і кастодіальних гаманців;
• перелік метрик, за якими будуються сигнали, і пороги, за яких вони спрацьовують;
• глибина історичних вивантажень і частота оновлення: разова звірка чи постійний потік;
• як дані потрапляють до споживачів — база, регулярний звіт, панель моніторингу, оповіщення;
• вимоги до доступів: хто видає ключі до джерела, де вони зберігаються, чи є обмеження за частотою запитів;
• приклади ручних вивантажень, щоб ми повторили вашу логіку розрахунку, а не винаходили її заново.

За підсумками розбору повертаємося з оцінкою та планом робіт: склад етапів, що робимо ми і що залишається на вашому боці, точки перевірки та порядок приймання.

Перший перевірюваний результат зазвичай невеликий — підключення до джерела та звірка розрахунків на контрольних адресах, щоб ви побачили збіжність цифр до основної розробки.