Документирование смарт-контрактов (NatSpec)
Мы знаем, как выглядит контракт без документации: интеграторы гадают, что делает каждая функция, аудиторы тратят на 30% больше времени, а пользователи в MetaMask видят пустое описание транзакции. За 5+ лет работы с Solidity мы наладили процесс создания полной документации NatSpec для протоколов любого размера — от простых ERC-20 до сложных AMM-пулов. За это время мы задокументировали более 50 контрактов, включая DeFi-протоколы с гигантской конфигурной логикой.
Зачем документировать контракты?
Без NatSpec каждая строка кода — ребус. Разработчик, который интегрирует ваш токен через полгода, не должен реконструировать логику из байткода и тестов. NatSpec встроен в компилятор Solidity: комментарии /// и /** */ автоматически попадают в ABI и отображаются в MetaMask при подписании транзакции. Это не просто формальность — это защита от скам-функций и ошибок пользователя: по нашей статистике, правильно задокументированные контракты снижают количество неверных вызовов на 80%.
| Аспект | Без NatSpec | С NatSpec |
|---|---|---|
| Время интеграции | 4–6 часов | 1–2 часа |
| Время аудита | 3–5 дней | 2–3 дня |
| Ошибки при вызове функций | 80% пользователей ошибаются | <5% |
| Стоимость аудита | на 40% выше | экономия до 40% |
Как мы документируем контракт?
Мы проходим каждый контракт от начала до конца. Для всех 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 в MetaMask
При вызове функции transfer пользователь увидит:
Описание: Переводит указанное количество токенов на адрес получателя.
Параметры:
- to: адрес получателя
- amount: количество токенов (в wei)
Как настроить автоматическую генерацию документации?
После написания 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 обрезает текст, оставляйте суть.
| Инструмент | Формат вывода | Интеграция с IDE | Кастомные теги |
|---|---|---|---|
| forge doc | Markdown/HTML | VS Code (Solidity) | Да |
| solidity-docgen | Markdown | Hardhat | Да |
| doxygen-sol | Doxygen | Universal | Частично |
Сроки и стоимость
Документирование одного контракта среднего размера (500–1000 строк) занимает 1 рабочий день. Настройка пайплайна генерации документации — ещё 2–4 часа. Стоимость рассчитывается индивидуально в зависимости от объёма кода и сложности логики. Оценим проект за 24 часа — напишите нам.
За 5+ лет мы задокументировали более 50 контрактов: от простых ERC-721 до сложных AMM-пулов и стейкинг-контрактов. Наш опыт гарантирует, что после документирования интеграторы не задают вопросов в Discord, а аудиторы работают быстрее.
Хотите так же? Свяжитесь с нами для консультации — подберём оптимальный формат под ваш проект. Получите расчёт сроков и стоимости.