Чому claim-контракт токенів ламається під навантаженням
У claim-контракті токенів збої нарахування нагород зводяться до трьох механік. Гонка: перевірка «адреса ще не отримувала» і запис про видачу розділені, і дві транзакції в одному блоці проходять її обидві.
Повторне отримання токенів — через той самий підпис або другу адресу, коли право на нагороду не прив’язане до рахунку. Третій сценарій — зовнішній виклик під час виплати, що повертає керування до оновлення стану.
Пікове навантаження в мережі перетворює рідкісну гонку в закономірність. Комісія зростає, частина транзакцій зависає в черзі, гаманець повторює надсилання з новим одноразовим номером — і обидва екземпляри потрапляють у блок.
Вузол під лімітом запитів видає помилку на читанні стану, а вітрина знову показує нагороду доступною, провокуючи нові спроби.
Тому логіку видачі будують навколо ідемпотентного ключа на кожну виплату, монотонного лічильника епох замість булевого прапора й ліміту на адресу за період. Розрахунок суми відокремлюють від переказу, а зміна стану відбувається до зовнішніх викликів.
Аудит логіки видачі перевіряє не код на око, а стан до й після на копії мережі — з паралельними запитами, відкатами й повторним входом у метод.
Окремо перевіряємо поведінку за відмови: недоступний вузол, двічі отримане підтвердження, виплата, що обірвалася на середині. Контракт має залишатися в узгодженому стані, а отримувач — мати зрозумілий спосіб добрати нагороду без подвійної емісії. Далі розбираємо, як це закривається на рівні схеми й коду.
Що змінюється після переробки логіки нарахування токенів
Оптимізація логіки видачі в claim-контракті — це зміна класу поведінки під навантаженням, а не косметика в коді. На прийманні дивимося на вимірювані показники, а не на формулювання «стало швидше».
- Частка успішних видач. Раніше масова видача розвалювалася частково: одні учасники отримували токени, інші — відмову через вичерпання ліміту газу всередині циклу. Після винесення нарахування в окремий розрахунок і пакетного надсилання частка успішних операцій у пік тримається вище 99%, а ручних розборів звернень стає на порядок менше.
- Час відгуку контракту. Підтвердження заявки більше не чекає повного перерахунку прав: інтерфейс отримує відповідь одразу, розрахунок іде фоном. Час відгуку перестає лінійно зростати із кількістю одночасних заявок.
- Зниження частки відмов. Зникає цілий клас: повторні та конкурентні заявки, спроби отримати токени двічі. Ідемпотентність заявки закриває їх на рівні контракту, а не в підтримці.
- Комісія мережі при масовій видачі. Пакетне надсилання замінює сотні окремих переказів однією операцією — вартість видачі на тисячі адрес падає в рази.
- Обсяг ручних розборів. Журнал подій і явні стани заявки дозволяють розібрати інцидент за логами, без звірок вручну.
Перевіряємо це на тестовому контурі з профілем навантаження, близьким до робочого, а стандартні примітиви токена беремо з аудитованих бібліотек (OpenZeppelin) — базу не винаходимо заново.
Порівняння підходів до видачі прав і нарахування нагород
Перше рішення — як права потрапляють у мережу: одним пулом підписів або окремими переказами на кожну адресу. Друге — де зберігається істина про нагороду: у стані контракту чи в офчейн-реестрі, який лише підтверджує право. Третє — хто оплачує комісію мережі. Ці три вибори незалежні, але разом вони задають вартість видачі та вимоги до довіри.
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Єдиний пул підписів | Нагород багато, отримувачі забирають їх самі | Потрібен коректний розрахунок набору й захист від повторного отримання |
| Індивідуальні перекази | Отримувачів одиниці або нагорода нараховується подієво | Кількість транзакцій зростає лінійно, разом із нею і сумарна комісія |
| Ончейн-перевірка прав | Критична незалежність від нашого сервісу | Кожна перевірка пише в стан — при масовій видачі дорожче |
| Офчейн-реестр нагород | Дані змінюються часто, важлива швидкість нарахування | Потребує довіри до реєстру або підтвердження підписом |
| Субсидування комісії мережі | Отримувач не повинен тримати кошти на комісію | Витрати на всю видачу лягають на власника контракту |
| Комісію платить отримувач | Проєкт не бере на себе зобов’язання щодо видачі | Поріг входу: без балансу право забрати не можна |
Робочий claim-контракт токенів майже завжди збирають із двох-трьох рядків цієї таблиці. Класика — офчейн-реестр нагород плюс єдиний пул підписів: сервіс рахує набір, а контракт за одну транзакцію закриває видачу на групу адрес.
Довіра до реєстру при цьому знімається перевіркою підпису в мережі, і отримувачу залишається одна транзакція — за неї він і платить комісію, якщо субсидування не закладено.
Етапи впровадження: від аудиту до передачі в експлуатацію
Впровадження claim-контракту — це не разове вивантаження коду, а послідовність, де кожен крок спирається на попередній.
Починаємо з розбору поточної логіки нарахувань і закінчуємо передачею в експлуатацію з навчанням команди — так на кожному етапі видно, що саме вже перевірено, а що ще ні.
- Розбір поточної логіки нарахувань. Як рахуються права на токени, де зберігаються дані, хто ініціює виплату. На виході — карта розбіжностей між документами та фактичною поведінкою системи.
- Схема контракту. Ролі, ліміти, пауза, механіка повторного звернення. Узгоджуємо до коду: правка на схемі займає години, після запуску — тижні.
- Аудит смарт-контракту. Дивимося зовнішні виклики й залежності, перевіряємо, що станеться за відмови зовнішнього джерела і як це позначиться на вже нарахованих правах.
- Тестовий контур. Розгортаємо копію мережі з реальним обсягом даних та історією операцій — на ній відпрацьовуємо сценарії, які не можна безпечно перевіряти в основній мережі.
- Граничні стани. Нульове й повторне звернення, запит на межі вікна, одночасні виплати, зупинка й відновлення. Кожен сценарій — окрема перевірка з очікуваним результатом.
- Передача в експлуатацію. Передаємо ключі за схемою мультипідпису, документацію та регламент оновлень. Навчаємо команду: як читати події, як реагувати на зупинку, як готувати нову версію.
Передача — не фінальна точка: документація описує, як викотити оновлення контракту без втрати вже нарахованих прав.
Документація, схеми доступу та регламенти випуску
Передаємо не лише код, а й робочу документацію: без неї команда супроводу не зможе ні випустити токени за регламентом, ні відкликати роль у співробітника, який пішов.
Кожен артефакт пишемо під конкретного читача — інженера підтримки, аудитора, відповідального за випуск, — і перевіряємо на живому стенді: розгортаємо за інструкцією та переконуємося, що кроки відтворюються без автора.
- Схема ролей доступу — хто чим керує: випуск, пауза операцій, зміна ставок або лімітів, виведення коштів; позначено, які ролі допустимо тримати на одному ключі, а які розводяться по різних.
- Документація контракту — призначення методів, події та їхні поля, стан і переходи, поведінка за відмов; із прикладами викликів та очікуваними результатами.
- Регламент випуску токенів — порядок дій від заявки до підтвердження: хто ініціює, хто підтверджує, які перевірки передують підпису, що звіряється після.
- Інструкція з оновлення — покроковий порядок для нової версії: підготовка, перевірка сумісності стану, вікно міграції, критерій успіху та порядок повернення до попередньої версії.
- Політики роботи з ключами — де зберігаються, скільки підписів потрібно для критичних операцій, як проходить ротація і що робити при компрометації.
- Чек-лист приймання та розгортання — контрольні точки перед публікацією: тести на копії основної мережі, перевірка прав, ліміти, коректність адрес.
- Пам’ятка для підтримки — типові звернення та дії за ними, які події вважати нормою, а які потребують зупинки випуску й розбору.
Артефакти лежать у вашому репозиторії поруч із кодом і оновлюються разом із ним — під час наступного доопрацювання інженер піднімає контекст за документами, а не за листуванням.
Кейс: як скоротили частку невдалих нарахувань
Точка старту
Клієнт — сервіс із накопиченням балів і періодичною видачею токенів: розрахунок нарахувань жив в одному сервісі, а підпис і надсилання транзакцій виконував він же, без ідемпотентних ключів на кожну видачу.
На піках навантаження позиції йшли повторно через конфлікти черги підпису, частину відхиляли через вичерпаний ліміт газу, частина губилася між двома спробами ретраю. Частка успішних видач трималася близько 94% — тобто кожна двадцята видача потребувала ручного втручання.
Що змінили і що вийшло
Контур розділили на три незалежні частини: розрахунок нарахувань, чергу видач з унікальним ідентифікатором позиції та окремий підписувач, що працює по одній транзакції за раз.
Контракти зібрали на перевіреній базі OpenZeppelin — із захистом від повторного виклику, роллю оператора й паузою на весь контур.
Кожна видача отримала ключ ідемпотентності: повторна спроба відхиляється на рівні контракту, а не на рівні сервісу, тому подвійне нарахування стало неможливим за побудовою.
Додали попередню перевірку газу й повтор із перерахунком ліміту, а збійні позиції поїхали в окрему чергу з алертом — оператор бачить, що саме застрягло, і не розбирає це вручну за логами.
| Метрика | До | Після |
|---|---|---|
| Частка успішних видач | ~94% | 99,8% |
| Час відновлення після збою | 30–40 хв | до 3 хв |
| Звернення в підтримку за реліз | 20–30 | поодинокі |
| Подвійні нарахування | регулярно | клас відмов зник |
Видачі перестали бути вузьким місцем релізу: черга розбирається сама, а на ручний розбір залишаються тільки позиції з помилковими вхідними даними.
Що робити, якщо емісію вже розгорнуто в мережі
Розгорнутий контракт емісії — це вже зафіксований стан мережі, а не файл у репозиторії, який можна перезаписати.
Адреса, історія нарахувань і права власників незмінні, тому завдання не в заміні, а в акуратному переході: нова логіка видачі починає працювати, стара історія залишається перевірюваною.
Найчастіше точку входу залишають попередньою, а логіку виносять за неї: контракт-обгортка приймає звернення за тією ж адресою і делегує їх новому модулю.
Власникам і зовнішнім інтеграціям нічого змінювати не потрібно — гаманці продовжують звертатися туди ж, куди зверталися раніше, а оновлення проходить непомітно для сервісу.
Перенесення стану реєстру йде снапшотом: фіксуємо зріз накопичених нагород і позначок про отримання на конкретному блоці, переносимо в новий модуль і звіряємо підсумки до й після — суми за адресами, кількість невибраних нагород, контрольні суми.
Окремо рахуємо дельту: ті, хто отримав право на нагороду між зняттям снапшота й увімкненням нової логіки, не повинні ні випасти з реєстру, ні подвоїти нарахування.
Сумісність версій закривається періодом паралельної роботи: новий модуль читає історію зі старого контракту в попередньому форматі, а нові записи веде вже у своєму.
Поки обидва джерела дають однакову відповідь на запити залишків, перемикання можна відкотити, не втративши дані й не зупинивши видачу.
Саме тому міграцію планують як послідовність оборотних кроків, а не як одномоментну зміну логіки. Такий порядок зберігає безперервність сервісу для власників, залишає слід для перевірки й знімає ризик подвійних нарахувань — класу відмов, який найдорожче виправляти постфактум.
Технічні питання, які варто закрити до старту
До старту зазвичай спливають ті самі технічні сумніви: що заважає отримати нарахування двічі, чи можна обмежити коло адрес, хто оплачує комісію мережі і як переконатися, що суми в таблиці нарахувань правильні. Нижче — короткі відповіді, які ми закриваємо на етапі проєктування контракту, а не після запуску.
Як виключається повторне отримання токенів?
Право на нарахування фіксується знімком на момент деплою — деревом нарахувань або обліковою таблицею. Кожен claim позначає адресу використаною, причому прапорець ставиться до переказу коштів: інакше повторний виклик у межах тієї самої транзакції може пройти двічі. Повторне звернення просто відкочується транзакцією.
Чи можна обмежити отримання за адресами або регіонами?
Так: білий список, ліміт на адресу в одному раунді, відсікання заданих діапазонів. Регіон контракт не перевіряє — він не знає юрисдикцію гаманця. Список допущених формується до деплою, і регіональні правила діють на вході, а не в коді.
Хто оплачує комісію мережі?
За замовчуванням отримувач: claim викликає сам власник, контракт оплату не бере. Якщо потрібен спонсор комісії, додаємо релейер із підписаними дозволами й окремо рахуємо ліміти, щоб релейер не витрачав кошти на потоковий спам.
Як перевіряється коректність нарахувань?
Суми звіряємо двома незалежними способами: перерахунком із вихідних даних і за журналом контракту. До відкриття claim проганяємо суху перевірку доказів для вибірки адрес — розбіжності видно до перших транзакцій, а не за зверненнями власників.
Обговоримо задачу і повернемося з оцінкою та планом
Оцінка задачі йде від вашої поточної логіки: чим точніше описаний вхід, тим менше припущень у плані робіт і тим швидше ми називаємо строки. Надішліть те, що вже є — цього достатньо, щоб повернутися з розбором, оцінкою та пропозицією щодо архітектури.
- Схему або текстовий опис поточної логіки видачі: хто ініціює, у якому порядку, що відбувається при повторному зверненні і як обробляється помилка.
- Сценарії видачі токенів: разові та хвильові, з вікнами за часом, лімітами на адресу й правилами для отримувача.
- Обмеження: ролі та права доступу, обов’язкові зовнішні перевірки, вимоги до звітності й аудиту операцій.
- Список отримувачів або правило його формування: знімок власників, оновлюваний реєстр, розрахунок за формулою від заданих умов.
- Що вже розгорнуто: адреси контрактів, цільові мережі, наявність тестового контуру, дані про минулі запуски й відомі збої.
- Вимоги до супроводу: хто тримає ключі, як узгоджуються зміни, який рівень доступу потрібен нам для підтримки видачі.
Далі — план робіт з етапами, контрольними точками та перевірюваним результатом на кожному кроці. Супровід контракту оформлюємо як регламент: спостереження за видачами, порядок реакції на інциденти, акуратні оновлення логіки без зупинки підтримки видачі токенів. Опишіть задачу — повернемося з оцінкою та планом.







