Документування смарт-контрактів (NatSpec)

Документування смарт-контрактів (NatSpec)

Ми знаємо, як виглядає контракт без документації: інтегратори гадають, що робить кожна функція, аудитори витрачають на 30% більше часу, а користувачі в MetaMask бачать порожній опис транзакції. За 5+ років роботи з Solidity ми налагодили процес створення повної документації NatSpec для протоколів будь-якого розміру — від простих ERC-20 до складних AMM-пулів. За цей час ми задокументували понад 50 контрактів, включаючи DeFi-протоколи з гігантською конфігураційною логікою.

Навіщо документувати контракти?

Без NatSpec кожен рядок коду — ребус. Розробник, який інтегрує ваш токен через півроку, не повинен реконструювати логіку з байткоду та тестів. NatSpec вбудований в компілятор Solidity: коментарі /// та /** */ автоматично потрапляють в ABI і відображаються в MetaMask при підписанні транзакції. Це не просто формальність — це захист від скам-функцій і помилок користувача: за нашою статистикою, правильно задокументовані контракти знижують кількість неправильних викликів на 80%.

Як ми документуємо контракт?

Ми проходимо кожен контракт від початку до кінця. Для всіх public та external функцій, подій та кастомних помилок:

• @notice — зрозумілий користувачу опис (що робить функція, навіщо викликати, що станеться).
• @dev — технічні нюанси: газ-ліміти, реверт-умови, припущення про стан.
• @param / @return — точний опис параметрів та повернення, включаючи одиниці виміру (wei, basis points).

Доповнюємо @custom:security — позначаємо місця, обов’язкові для перевірки аудитором. Для контрактів з OpenZeppelin Upgrades додаємо @custom:oz-upgrades-unsafe-allow, інакше плагін відхилить міграцію.

Приклад правильно задокументованої функції:

/// @notice Переводить токени на вказану адресу /// @dev Не працює з ERC-777 токенами через hook'и; використовуй safeTransfer для невідомих отримувачів /// @param to Адреса отримувача, не може бути address(0) /// @param amount Кількість токенів в мінімальних одиницях (wei) /// @return success True якщо переклад пройшов успішно function transfer(address to, uint256 amount) external returns (bool success); 

Як налаштувати автоматичну генерацію документації?

Після написання NatSpec документацію можна генерувати автоматично. Використовуйте forge doc з Foundry: достатньо додати в foundry.toml секцію [doc] та запустити forge doc. Для Hardhat встановіть плагін solidity-docgen та налаштуйте hardhat.config.ts. Ми налаштовуємо CI/CD так, що при кожному деплої документація оновлюється та публікується на GitHub Pages або Vercel. Весь процес займає 2–4 години, і ви отримуєте актуальну HTML-документацію без додаткових зусиль.

Чому NatSpec критичний для безпеки?

Більшість реентрабель-атак відбуваються через нерозуміння логіки контракту інтегратором. Коли у функції немає @notice, розробник викликає її з невірними параметрами або не очікує побічних ефектів. NatSpec знімає цю невизначеність. Крім того, інструменти аналізу (Slither, Mythril) можуть читати @custom:security та автоматично перевіряти позначені ділянки. Стандарт NatSpec описаний в документації Solidity.

Що входить в результат?

• Повний аудит існуючих коментарів (якщо є).
• Написання NatSpec для всіх public/external функцій, подій, помилок.
• Генерація HTML-документації через forge doc або solidity-docgen.
• Інтеграція з CI/CD (автоматична генерація при деплої).
• Консультація з best practices: які теги обов’язкові, які — опціональні.

Ми гарантуємо 100% покриття public API та проходження перевірки компілятора — кожен тег синтаксично коректний.

Типові помилки при створенні NatSpec

• Плутанина @notice та @dev: перше — для користувача, друге — для розробника.
• Пропуск опису повернення (@return) — користувач не знає, що функція поверне.
• Відсутність @custom:security в місцях з потенційними вразливостями (flash loan, oracle).
• Занадто довгі описи — MetaMask обрізає текст, залишайте суть.

Терміни та вартість

Документування одного контракту середнього розміру (500–1000 рядків) займає 1 робочий день. Налаштування пайплайну генерації документації — ще 2–4 години. Вартість розраховується індивідуально в залежності від обсягу коду та складності логіки. Оцінимо проект за 24 години — напишіть нам.

За 5+ років ми задокументували понад 50 контрактів: від простих ERC-721 до складних AMM-пулів та стейкінг-контрактів. Наш досвід гарантує, що після документування інтегратори не задають питань в Discord, а аудитори працюють швидше.

Хочете так само? Зв’яжіться з нами для консультації — підберемо оптимальний формат під ваш проект. Отримайте розрахунок термінів та вартості.