Створення та розгортання смарт-контрактів у Sui: повний посібник

Чому розгортання смарт-контрактів Sui зривається на публікації

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

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

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

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

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

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

Що змінюється, коли реліз контрактів перестає бути ручним

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

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

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

Чек-лист, за яким збираємо контур:

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

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

Способи публікації та оновлення пакетів: порівняння

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

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

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

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

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

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

Етапи робіт

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

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

Комплект постачання: конфігурації, схеми, регламенти

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

Тому комплект документації збирається паралельно з кодом і передається разом із ним, а не «допишеться потім».

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

Кожен артефакт ми проходимо разом із вашою командою до передачі — питання щодо складу краще зняти на цьому етапі. Опишіть задачу, і ми повернемося з оцінкою та планом: розгортання смарт-контрактів Sui перестане залежати від одного підрядника.

Кейс: як скоротили цикл випуску контрактів учетверо

Як було: випуск залежав від однієї людини

Продукт — кілька пов'язаних пакетів контрактів на Sui, команда розподілена, чотири інженери в різних часових поясах.

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

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

Що змінили

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

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

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

Що стало

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

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

Що робити, якщо контракт уже розгорнуто в Sui і потребує правок?

Опублікований код у Sui незмінний: контракт розгортається як об'єкт-пакет, а не як файл на сервері, тому «поправити пару рядків і перезалити» тут не працює.

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

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

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

Дані живуть в об'єктах, а не в коді пакета, тому оновлення логіки саме собою стан не чіпає.

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

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

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

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

Часті технічні сумніви перед стартом

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

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

Як перевіряється безпека логіки контракту?

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

Що буде, якщо в новій версії знайдеться помилка?

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

Наскільки докладною має бути документація щодо контракту?

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

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

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

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

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

До складу першого етапу співпраці входить:

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

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