Розробка системи нормалізації даних з крипто-джерел

Нормалізація криптоданих: що ламається на вході

Необроблені вивантаження з криптоджерел майже ніколи не збігаються за структурою.

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

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

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

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

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

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

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

Що змінюється після впровадження: ефект у вимірюваних величинах

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

Швидкість підключення нового джерела

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

Частка автоматичних звірянь

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

Клас усунених відмов

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

Єдина схема обліку

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

Варіанти підключення джерел: порівняння підходів

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

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

Як обирати

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

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

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

Як будується впровадження: етапи інженерної роботи

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

Біржі, оглядачі блоків і агрегатори віддають різну глибину історії, частоту оновлення та структуру відповіді, по-різному називаючи той самий актив.

1. Аудит джерел. За кожним джерелом фіксуємо формат відповіді, глибину історії, частоту оновлення, обмеження на кількість запитів і поведінку при збої — отримуємо карту покриття ще до проєктування схеми.
2. Карта розбіжностей. Зводимо відмінності в один документ: як кожне джерело позначає інструмент, у якій шкалі віддає час і обсяги, де з’являються дублікати, пропуски й розриви під час перезбирання блоків.
3. Правила зіставлення полів. Проєктуємо канонічну схему та довідники відповідності: єдиний ідентифікатор активу, одне представлення часу й точності, явний пріоритет джерела при конфлікті значень.
4. Налаштування приймання. Збираємо потік обробки з повторними спробами, ключем ідемпотентності та дедуплікацією, щоб той самий блок або угода не подвоювали дані під час перерахунку.
5. Перевірка на історичних зрізах. Проганяємо правила на минулих періодах: звіряємо кількість записів і контрольні суми, ловимо дрейф схеми та випадки, коли джерело змінювало формат відповіді.
6. Передача й регламент. Віддаємо схему, довідники, журнал розбіжностей і порядок підключення нового джерела, щоб розширення набору джерел не вимагало перезбирання логіки.

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

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

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

Усе лежить у вашому репозиторії та вашій інфраструктурі: ми залишаємося на зв’язку для розвитку, але не як єдині, хто може натиснути кнопку.

Кейс: розбіжності між біржею та внутрішнім обліком

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

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

Метрики до та після

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

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

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

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

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

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

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

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

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

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

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

Технічні сумніви: джерела, збої, обмеження

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

Джерело змінило формат — старі дані зламаються?

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

Джерело недоступне кілька годин — дані загубляться?

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

Що з операціями, які не вдалося розібрати?

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

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

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

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

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

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