Документирование смарт-контрактов (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, а аудиторы работают быстрее.
Хотите так же? Свяжитесь с нами для консультации — подберём оптимальный формат под ваш проект. Получите расчёт сроков и стоимости.
Разработка смарт-контрактов
Мы столкнулись с ситуацией: контракт задеплоен, через две недели приходит сообщение — пул дренирован на $800k. Смотрим транзакцию в Tenderly: атакующий вызвал deposit(), внутри callback на ERC-777 повторно вызвал withdraw() — баланс обновился только после второго выхода. Классическая reentrancy, но не через ETH transfer, а через хук ERC-777. ReentrancyGuard стоял только на withdraw().
Такие случаи — не редкость. Смарт-контракт — это финансовая логика без возможности пропатчить её ночью. Наша команда разрабатывает контракты под ключ, встраивая защиту от reentrancy, MEV и gas-атак на ранних этапах.
Как мы разрабатываем смарт-контракты под ключ
Начинаем с аудита бизнес-логики и выбора стека. Solidity 0.8.x — стандарт для EVM-совместимых чейнов: Ethereum, Arbitrum, Optimism, Polygon, BSC, Avalanche C-Chain. Для Solana используем Rust и Anchor: модель аккаунтов и программ требует явного объявления всех ресурсов. Для проектов с формальной верификацией подходит Move (Aptos, Sui) — линейные типы языка исключают копирование ресурсов на уровне компилятора. Vyper выбираем для контрактов, где критична простота аудита (Curve Finance).
| Язык |
Модель исполнения |
Типичная область |
Риски |
| Solidity 0.8.x |
EVM, последовательное исполнение |
DeFi, NFT, токены |
Reentrancy, переполнение (unchecked) |
| Rust (Anchor) |
Solana, параллельное |
Высоконагруженные DEX, игры |
Неправильное объявление аккаунтов |
| Move |
Aptos/Sui, ресурсная |
Крупные протоколы |
Сложность экосистемы |
| Vyper |
EVM, ограниченный синтаксис |
Критические контракты (Curve) |
Зависимость от стабильности компилятора |
Gas optimization — не преждевременная оптимизация, а архитектурное решение. На Ethereum mainnet деплой плохо спроектированного контракта может стоить 2–5 ETH только из-за неоптимального storage layout. Переупаковка структуры Proposal с 7 слотов до 4 сэкономила 18k gas на каждом голосовании — около $1.5 при gas price 30 gwei. Экономия на масштабе протокола с тысячами голосований в день даёт ощутимую годовую выгоду.
Типичные ошибки в gas: передача массивов через memory вместо calldata в external функциях (дороже в 2–3 раза); использование require с длинными строками вместо custom error error InsufficientBalance(...). Кастомные ошибки дешевле на 50–200 gas на revert и передают структурированные данные фронтенду.
Почему аудит смарт-контрактов критичен для безопасности
Аудит — не разовая проверка, а встроенный этап разработки. Используем три уровня:
-
Статический анализ —
Slither (30 секунд в CI) выявляет reentrancy, неинициализированные переменные, опасный delegatecall.
-
Фаззинг и invariant тесты —
Foundry с --fuzz-runs 50000 находит edge cases, которые пропускают сотни unit-тестов. Реальный кейс: AMM контракт с кастомной математикой после 150 тестов в Hardhat — Foundry нашёл integer division truncation, позволявший пылевой атаке копить dust на контракте. Echidna проверяет инварианты («сумма всех балансов ≤ totalSupply»).
-
Ручной code review — наши инженеры с опытом 10+ лет в блокчейне выявляют логические ошибки, которые не ловят инструменты. Для протоколов с TVL > $1M обязателен внешний аудит со стороны Trail of Bits, Consensys Diligence или OpenZeppelin. Срок — 2–4 недели.
Любой апгрейдируемый протокол должен иметь timelock. TimelockController из OpenZeppelin: операция предлагается → ждёт минимальный delay (48–72 часа) → выполняется. Без timelock один скомпрометированный deployer wallet = потеря всего пула.
Какие паттерны апгрейда выбираем
| Паттерн |
Механизм |
Риск |
Когда использовать |
Наш опыт |
| Transparent Proxy (OZ) |
admin vs user разделение |
Storage collision, centralization |
Стандартные проекты |
15+ реализаций |
| UUPS |
Логика апгрейда в implementation |
Забыть _authorizeUpgrade → контракт навсегда сломан |
Газ-оптимизированные проекты |
7 проектов |
| Diamond (EIP-2535) |
Множество facets |
Сложность аудита |
Крупные протоколы с 10+ контрактами |
3 внедрения |
| Beacon Proxy |
Один beacon для множества proxies |
Beacon = single point of failure |
Фабрики однотипных контрактов |
5 фабрик |
Storage collision — главная опасность прокси. Implementation v2 не должен добавлять переменные перед существующими. OpenZeppelin Upgrades plugin для Hardhat и Foundry проверяет это автоматически, но только при использовании его API.
Как защитить контракт от MEV и front-running
На Ethereum mainnet транзакции в mempool видны всем. MEV-боты проводят sandwich-атаки на DEX, фронтраннинги минтинга и governance. Решение: commit-reveal scheme для аукционов, приватная отправка через Flashbots PROTECT RPC. EIP-7702 и PBS (proposer-builder separation) меняют картину, но пока не массово.
Процесс разработки
-
Аналитика — спецификация функций, диаграмма вызовов, анализ edge cases. Без этого кодинг начинается впустую.
-
Разработка — Solidity/Rust с тестами параллельно. Тест → код → рефакторинг. Используем Foundry для fuzz и invariant тестов.
-
Внутренний аудит — Slither + Echidna + ручной code review. Foundry invariant tests для протокольных инвариантов.
-
Внешний аудит — для проектов с реальными деньгами. Срок: 2–4 недели.
-
Деплой — Foundry scripts или Hardhat Ignition с verify на Etherscan. Gnosis Safe для ownership transfer сразу после деплоя.
-
Мониторинг — Tenderly alerts, OpenZeppelin Defender, Forta Network.
Что входит в работу
- Документация на архитектуру и спецификацию контракта (NatSpec).
- Исходный код с репозиторием и CI (Slither, Foundry, coverage).
- Развёрнутая версия контракта с verify на блокчейн-эксплорере.
- Результаты аудита (внутреннего и внешнего по запросу).
- Доступы к мониторингу и управлению (Gnosis Safe).
- Гарантия на код: фиксы критических багов в течение месяца после деплоя.
- Консультация по интеграции с веб-интерфейсом (wagmi, RainbowKit).
Сроки ориентировочно
- ERC-20 token с базовыми функциями: 1–2 недели
- Vesting контракт с cliff/linear schedule: 2–3 недели
- NFT ERC-721/1155 с маркетплейсом: 4–6 недель
- AMM или lending протокол: 2–4 месяца
- Мультичейн протокол с bridge: 4–7 месяцев
Аудит добавляет 3–6 недель и идёт параллельно с финальным тестированием где возможно. Стоимость рассчитывается индивидуально — свяжитесь с нами, и мы оценим ваш проект бесплатно.
Закажите разработку смарт-контракта — получите консультацию по архитектуре и защите от reentrancy, MEV и gas-атак. Хотите обсудить детали? Напишите нам — мы подберём оптимальный стек под вашу задачу.
