Деплой смарт-контрактів на Near: вузькі місця та збої
Деплой смарт-контрактів Near — це не одна операція, а дві незалежні: завантаження коду в сховище акаунта та виклик методу-ініціалізатора, який створює стан. Ручний порядок ламається передбачувано: код оновили, а схему стану під нього — ні.
Контракт публікується успішно, але перший же виклик падає на розборі збережених даних, і акаунт залишається у стані, з якого штатного виходу вже немає.
Друга категорія збоїв — збірка. Якщо версія компілятора, набір залежностей і параметри оптимізації не зафіксовані, один і той самий вихідний код дає різні артефакти.
Невідтворювана збірка означає, що опублікований код неможливо звірити з репозиторієм: не можна ні підтвердити відсутність сторонніх правок, ні зібрати точно ту саму версію для повернення.
Третя — доступ. Ключі акаунта, під якими йшла публікація, часто живуть в історії команд, у листуванні або на машині одного інженера.
Втрата ключів акаунта не зупиняє вже працюючий контракт, але закриває можливість оновлення: акаунт залишається без власника, і повернути керування нічим.
Окремо — відсутність відкату. Публікація в основній мережі незворотна, і якщо попередній код не збережено й не перевірено на тестовій мережі, помилка публікації контракту спливає вже на живих користувачах. Нижче розбираємо, як це закривається.
Що дає керована викладка: швидкість і передбачуваність
Керована викладка починається з повторюваної збірки: один і той самий вихідний код і зафіксовані залежності дають ідентичний артефакт, тому перевірене на тестовій мережі йде в основну без розходжень.
Час до робочого запуску в чистому оточенні вкладається в один прохід — підготовка акаунтів, публікація та ініціалізація стану йдуть заздалегідь описаним порядком, а не з пам'яті виконавця.
Частка невдалих публікацій у мережі Near падає першою. До наведення ладу зривалася приблизно кожна третя спроба: акаунт не створено, ключ не той, на сховищі не вистачає покриття під стан контракту.
Тепер ці перевірки проходять до надсилання транзакції, і в основну мережу йде тільки те, що вже відпрацювало на копії.
Час відновлення після збою скорочується з годин до десятків хвилин. Відомо, який артефакт розгорнуто, який стан йому відповідає і на яку версію можна повернутися — відкат перетворюється на операцію замість розслідування.
Разом із цим зникає цілий клас відмов: хибні адреси акаунтів, незакриті міграції стану, ручні правки, що не потрапили в історію. Викладка перестає бути подією з напругою і стає рутинним кроком, який можна доручити черговому інженеру.
Режими викладки: порівняння підходів та обмежень
Режими викладки розрізняються не інструментом запуску, а тим, хто ініціює публікацію і що в цей момент відбувається з даними контракту. Код оновлюється однією операцією, а стан залишається попереднім — якщо структура записів змінилася, новий код починає читати несумісні дані.
Тому в мережі Near вибір режиму визначається трьома параметрами: оборотністю, вимогами до доступів і ціною помилки.
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Ручна публікація з локального середовища | Перший запуск, налагодження, разові правки | Усе залежить від машини інженера: ключі й версія збірки ніде не зафіксовані, повтор не відтворюється |
| Конвеєр публікації | Регулярні випуски, перевірки перед публікацією, кілька середовищ | Потребує захищених доступів у середовищі збірки; помилкова збірка йде без паузи на підтвердження |
| Оновлення за схемою стану | Змінюється структура збережених даних | Потрібен окремий крок перенесення стану, копія перед запуском і перевірка повноти перенесення |
| Зміна акаунта | Змінюється власник або потрібна чиста адреса | Дані між акаунтами не переносяться автоматично, стара історія та зовнішні посилання втрачають актуальність |
Режими частіше комбінують, ніж обирають один: код іде через конвеєр, перенесення стану виконується окремим кроком із попередньою копією, а зміна акаунта планується як окрема кампанія — з періодом, коли обидві адреси працюють паралельно і трафік переводиться поступово.
Етапи інженерної роботи: від аудиту до передачі
Процес будуємо так, щоб оновлення контракту виходило передбачувано, а стан не доводилося перезбирати вручну. Пропуск аудиту схеми зберігання або прав ключів зазвичай спливає вже після розгортання в основній мережі — коли виправлення коштує найдорожче.
- Аудит коду та схеми зберігання. Розбираємо структуру стану: які поля залишаються незмінними, що потребує міграції, скільки займає зберігання на акаунті контракту. Фіксуємо місця, де оновлення торкнеться вже записаних даних.
- Схема акаунтів і ролей. У Near акаунт — це і є контракт, тому права розділяємо: субакаунти під контракти, окремий ключ на розгортання, функціональні ключі лише на виклик конкретних методів. Зміна коду і списання балансу в одному ключі не поєднуються.
- Відтворювана збірка. Задаємо параметри компілятора і порядок формування артефакту, щоб у будь-якого інженера виходив ідентичний результат, а хеш збірки збігався з тим, що йде в мережу.
- Тестові середовища. Локальний вузол для швидких прогонів і окрема тестова мережа для інтеграції, де перевіряємо міграції стану, роботу ключів і сценарії з реальною затримкою фіналізації.
- Перевірка перед випуском. Прогоняємо тести за критичними шляхами контракту, перевіряємо граничні значення депозитів і репетируємо відкат на попередній артефакт.
- Поетапне розгортання. Спочатку обмежений список акаунтів, потім усі — зі спостереженням за витратою сховища і відмовами викликів.
- Передача й навчання. Віддаємо документацію, схему акаунтів і ролей, доступи та інструкцію з випуску оновлень, щоб команда далі працювала без нас.
Акаунти та сховище в Near: політики доступу
На Near доступ визначається не лише кодом контракту, а й ієрархією акаунтів: у кожного свій ключ, свій набір дозволених викликів і свій обсяг даних у постійному сховищі.
Тому в поставку входить не лише контракт, а й документи, за якими доступ і зберігання можна відтворити й передати іншій команді — без відновлення логіки з листування.
- Карта акаунтів і ролей: власник, акаунт для викату нових версій, службові акаунти для автоматичних викликів і ролі лише для читання — права не змішуються в одному ключі.
- Політики доступу: які методи доступні кожній ролі, що потребує підтвердження другим ключем, що обмежено списком адрес або часовим вікном.
- Схема зберігання стану: які дані лежать у постійному сховищі, що обчислюється на льоту, як влаштовані ключі записів і як змінюється баланс зберігання при зростанні обсягу.
- Регламент оновлення: порядок викату нової версії — підготовка перенесення стану, прогін на копії мережі, перемикання — з точками, де процес можна безпечно зупинити.
- Регламент відкату: як повернути попередню версію разом із сумісним станом, хто ухвалює рішення і за який час операція виконується.
- Розмежування середовищ: окремі набори ключів для тестової та основної мережі, заборона на перенесення ключів і даних між ними.
- Журнал операцій: які дії фіксуються, де зберігаються записи і як за ними розібрати інцидент, не перезбираючи контракт.
Документація потрібна не для звітності: через півроку новий інженер входить у проєкт за нею. Усе перелічене ведемо в репозиторії поруч із кодом — контракт на Rust і описи доступу змінюються в одному наборі змін.
Кейс: перенесення логіки на новий акаунт зі збереженням даних
Що було
На одному акаунті жили і логіка, і стан, а випуск версії складався з ручних кроків: зібрати контракт, викласти код, наздогнати стан і звірити його очима.
Збірка не повторювалася — два прогони з одних вихідних кодів давали різні артефакти, а розходження спливало вже на живому акаунті. Відкату не було: при помилці акаунт піднімали з копії, і недоступність розтягувалася на години.
Що стало
Перенесення логіки на новий акаунт у Near розклали на відтворювану збірку й окремий крок міграції стану. Скрипт рахує ключі та контрольні суми на старому акаунті, потім на новому і зупиняється при розходженні — битий стан не йде в роботу.
Старий акаунт залишається точкою відкату: поки перевірки не пройдені, перемикання скасовується однією операцією.
Ручних кроків стало 3 замість 12, перенесення займає близько півгодини замість чотирьох годин. Усі перенесення проходять без розходжень стану, тоді як раніше збоїла приблизно кожна друга спроба.
Повернення на попередній акаунт — хвилини, а не години відновлення з копії, і виконується тією ж командою, що й перенесення.
Що робити, якщо логіка вже розгорнута і зберігає дані?
Оновлення контракту на Near влаштовано так: код перезаписується повністю, а сховище стану залишається недоторканим.
Тому повторний деплой на той самий акаунт сам по собі дані не скидає — ризик в іншому: новий код починає читати старі ключі за зміненою схемою і падає на першому ж виклику або, що гірше, мовчки віддає хибні значення.
Сумісність схеми тримають дисципліною: поля додають у кінець структури, порядок і типи наявних не чіпають без потреби, а несумісні правки виносять в окремий метод міграції.
Він повторно ініціалізує контракт із явним ігноруванням попереднього стану, читає старі ключі, розкладає їх у новому форматі й записує назад одним викликом — щоб стан не залишився в проміжному вигляді при обриві.
Перехід на новий акаунт потрібен, коли змінюється власник або сама адреса. Автоматичного переїзду тут немає: стан переносять читанням ключів і записом на новий акаунт, або залишають старий тонким прошарком, який делегує виклики вперед.
Другий шлях кращий, якщо на адресу вже посилаються гаманці, фронтенд та інші контракти — їхні виклики продовжують працювати без правок.
Щоб застосунок залишився робочим, зберігають попередні імена й сигнатури методів, а міграцію виносять в окремий виклик, який виконується до перемикання.
Репетиція йде на копії стану, до і після звіряються контрольні значення — баланси, кількість записів, доступність публічних методів. Попередній код тримають під рукою для відкатного деплою, якщо перевірки на живих даних не зійдуться.
Технічні сумніви перед стартом робіт
Перед стартом майже кожна команда ставить ті самі питання: де лежатимуть ключі, що станеться з акаунтом при оновленні коду, як перенести доступ зі стенда на продакшн і чи можна довіряти чужому контракту. Нижче — короткі відповіді щодо кожного.
Для нас це не листування, а частина робіт: рішення фіксуються в конфігурації, а не в повідомленнях чату — інакше через півроку ніхто не згадає, чому в ключа такий рівень прав.
Як ключі доступу не опиняться в репозиторії та в логах?
Приватні ключі зберігаються поза кодом: локально — у системному сховищі, в автоматичній збірці — в захищених змінних середовища з обмеженим доступом.
На деплой видається ключ із правом виклику лише конкретних методів контракту, а не повний доступ до акаунта: витік такого ключа не дає змоги вивести кошти. Після передачі проєкту права відкликаються і випускаються нові.
Що буде з акаунтом і даними при оновленні контракту?
Код оновлюється на місці, акаунт і його сховище зберігаються, тому звернення за попередньою адресою продовжують працювати. Розрив виникає, якщо змінилася структура даних або сигнатури методів.
Ми заздалегідь описуємо міграцію стану, додаємо функції перенесення і прогоняємо оновлення на ізольованому стенді, перш ніж торкатися продуктивного акаунта.
Як переноситься доступ між стендом і продакшном?
Переносити стан напряму не можна — середовища незалежні. Переноситься конфігурація: список акаунтів, набір ключів, схема прав і дані ініціалізації, а стан розгортається заново тими самими міграціями. Так продакшн повторює перевірений сценарій стенда, а не копіює його наосліп.
Чи можна довіряти вже написаному контракту — своєму чи чужому?
Перед доопрацюванням чужого коду ми звіряємо опублікований байткод із вихідними кодами і складом залежностей: якщо вони розходяться, змінювати логіку небезпечно. Далі — перевірка прав ключів, точок оновлення і логіки виведення коштів. Знайдені розходження фіксуємо як умову, яку потрібно зняти до початку робіт.
Обговоримо задачу: повернемося з оцінкою та планом
Щоб повернутися з оцінкою і планом робіт, а не із загальними формулюваннями, нам вистачає мінімального набору вхідних. Чим конкретніший вхід, тим точніші терміни і менше уточнювальних кіл до початку робіт.
Що надіслати для старту:
- Посилання на репозиторій або архів із вихідними кодами контракту на Rust, включно з маніфестом збірки та зафіксованою версією компілятора.
- Список і призначення акаунтів: який контракт куди розгортається, хто власник, які ключі доступу видані й на які методи.
- Опис storage: які структури пишуться в стан, очікуваний обсяг, чи є міграції і як планується перенесення даних.
- Цільову мережу і режим роботи: тестова чи основна, потрібна пропускна здатність, ліміти на запис.
- Поточну схему викладки: скрипти збірки, ручні кроки, що вже автоматизовано, а що робиться руками.
- Вимоги до перевірок: які сценарії зобов'язані проходити до релізу і хто підтверджує готовність.
Ми розберемо контракт, модель стану і права на ключі окремо — при розгортанні це три незалежні джерела відмов. Подивимося, де зашиті припущення про розмір стану, як поводиться логіка при частково застосованих змінах і що відбувається з акаунтом при невдалій викладці.
Повернемося з оцінкою та планом робіт: етапи, порядок викладки, точки повернення до попереднього стану, склад перевірок і те, що потрібно від вашого боку на кожному кроці. Опишіть задачу — надішлемо розбір із конкретними термінами.
