Професійний деплой CosmWasm смарт-контрактів у Cosmos

Чому розгортання CosmWasm-контракту зривається в тестовій мережі

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

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

Помилка розгортання смарт-контракту видна відразу, але стан мережі вже змінився, і повернутися до вихідної точки не можна.

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

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

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

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

Тому розгортання CosmWasm-контракту планують як операцію з перевірюваним станом і зворотними кроками — розбираємо, як це закривається.

Що дає кероване розгортання контрактів в основній мережі

Що вимірюємо до початку робіт

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

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

Які класи відмов зникають

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

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

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

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

Режими розгортання контрактів: порівняння та обмеження

У CosmWasm розгортання — це дві транзакції: store закріплює байткод і видає code id, instantiate створює екземпляр із початковим станом і записом admin у ContractInfo. Вибір режиму зводиться до двох осей: хто підписує ці операції та чи залишається admin у контракту після запуску.

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

Що вирішує admin до першого запуску

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

Якщо оновлюваність не потрібна, admin знімають через ClearAdmin відразу після запуску, і контракт стає незмінним.

Порядок робіт: від аудиту коду до передачі керування

Розгортання CosmWasm-контрактів — не одна команда, а послідовність із контрольними точками.

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

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

Конфігурації, схеми й регламенти: що залишається у вас

Розгортання CosmWasm-контрактів в основній мережі закінчується не фактом «працює», а набором артефактів, за якими систему можна експлуатувати й розвивати без нас.

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

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

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

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

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

Що змінили

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

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

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

Чим міграція CosmWasm-контракту відрізняється від нового розгортання

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

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

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

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

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

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

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

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

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

Технічні сумніви: доступи, ключі та перевантаження мережі

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

Де зберігається ключ адміністратора?

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

Скільки перевірок проходить контракт до основної мережі?

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

Обов'язково перевіряємо сценарій міграції та відкат на попередню версію — він має працювати до старту.

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

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

Ми відстежуємо заповненість блоків і при сплеску активності переносимо випуск на спокійне вікно — результат не залежить від моменту запуску.

Що якщо розгортання перервалося на середині?

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

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

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

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

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

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

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