Техническое задание на блокчейн-проект: полное руководство

Составление технического задания на блокчейн-проект

При запуске DeFi-протокола аудит часто выявляет reentrancy, и тогда нужно срочно переписывать логику. Без чёткого ТЗ каждый спринт превращается в хаос: разработчики меняют функции, а тестировщики не успевают покрывать новые сценарии. По статистике, 60% блокчейн-проектов сталкиваются с reentrancy из-за отсутствия спецификации. ТЗ помогает предусмотреть такие атаки на этапе проектирования. Мы прошли через 50+ блокчейн-проектов и знаем: качественное техническое задание — это фундамент, на котором держится надёжность продукта.

Почему обычное ТЗ не работает для блокчейна?

Традиционное ТЗ создаётся для централизованных систем, где баги исправляются патчем на сервере. В блокчейне после деплоя контракта изменить логику можно только через upgrade strategy — а это требует тщательно спроектированной архитектуры прокси. Например, UUPS proxy, описанный в Smart contract документации OpenZeppelin, позволяет обновлять контракт через timelock. Кроме того, каждая операция стоит газа: неоптимизированный вызов может стоить $50 в час пик. Ошибка в расчётах комиссий делает продукт нерентабельным. Мы видели проекты, где смарт-контракты пришлось переписывать заново из-за того, что ТЗ не включало спецификацию ролей доступа или не рассматривало атаки через flash loan.

Какие разделы должно содержать техническое задание на блокчейн-проект?

Обзор системы

• Цель проекта и ключевые stakeholders.
• Выбранный блокчейн (L1/L2) и обоснование: Ethereum, Polygon, Arbitrum или Solana.
• Высокоуровневая архитектура с diagram — взаимодействие контрактов, off-chain компонентов.
• Интеграции: оракулы (Chainlink), bridge, внешние протоколы.

Как прописать смарт-контракты в ТЗ?

Каждый контракт требует детального описания: сигнатуры функций с параметрами, генерируемые события, роли доступа (AccessControl), настраиваемые параметры. Важно указать стандарты (ERC-20, ERC-721, ERC-1155, ERC-4626) и тип прокси. Приводим пример для контракта пула ликвидности:

Contract: LiquidityPool Сеть: Arbitrum One Стандарты: ERC-20 compatible Апгрейдаемость: UUPS proxy Функции: - deposit(uint256 amount) — депозит токенов, mint LP shares - withdraw(uint256 shares) — burn LP shares, получить токены + accumulated fees - swap(address tokenIn, uint256 amountIn, uint256 minAmountOut) — обмен События (Events): - Deposit(address indexed user, uint256 amount, uint256 shares) - Withdraw(address indexed user, uint256 shares, uint256 amount) - Swap(address indexed user, address tokenIn, uint256 amountIn, uint256 amountOut) Роли (Access Control): - DEFAULT_ADMIN_ROLE: Gnosis Safe 3/5 - PAUSE_ROLE: Protocol Defender (multisig или automated) - FEE_MANAGER_ROLE: DAO timelock Параметры (configurable): - swapFee: 0.3% (range: 0.01%-1%) - protocolFeeShare: 20% от swap fee 

Пример спецификации контракта пула ликвидности: выше приведен полный шаблон — заполните его для каждого контракта. Укажите gas budget: например, max gas per deposit = 200k gas. Это предотвратит неожиданные затраты после деплоя.

Токен спецификация (если есть)

Token: PROTO Standard: ERC-20 + ERC-2612 (Permit) Supply: 100,000,000 (fixed) Decimals: 18 Mintable: нет (fixed supply) Burnable: да (holder может сжечь) Pausable: да (PAUSE_ROLE) Distributor: специальный Vesting контракт 

Off-chain компоненты

• Indexer (The Graph subgraph) — какие события индексируются, GraphQL схема.
• Backend API (если нужен) — endpoints, authentication.
• Frontend — технический стек, wallet интеграция (wagmi, RainbowKit).

Инфраструктура

Деплой: - Foundry Deploy Scripts + Hardhat для верификации - Multisig owner: Gnosis Safe 3/5 - Timelock: 48 часов для admin функций - Proxy: UUPS (implementation upgrade через timelock) Мониторинг: - OpenZeppelin Defender для alerts - Tenderly для транзакций simulation - The Graph для исторических данных Сети для деплоя: - Testnet: Arbitrum Sepolia - Mainnet: Arbitrum One 

Безопасность

• Список smart contract паттернов: Reentrancy guard, CEI, проверки oracle manipulation.
• Защита от flash loan attack: проверка баланса пула до и после swap.
• Access control схема: каждая роль привязана к конкретному адресу (EOA, multisig, DAO).
• Upgrade strategy с timelock: процесс инициирования и отката.

Тестирование

Unit tests (Foundry):

• Все публичные функции.
• Edge cases и boundary conditions.
• Revert scenarios.

Fuzz tests:

• Инварианты: "totalShares * pricePerShare = totalAssets".
• Random deposit/withdraw sequences.

Fork tests:

• Integration с реальными протоколами на fork mainnet.

Coverage target: 95%+.

Аудит план

• Объём аудита: какие контракты проверяются.
• Timeline: аудит после code freeze, до mainnet.
• Критерии готовности: все medium+ находки fixed.

Как сэкономить на gas с помощью ТЗ?

Чётко указанный gas budget в ТЗ позволяет разработчикам оптимизировать код с самого начала. Например, ограничение в 200k gas на deposit вынуждает использовать storage-efficient паттерны. По нашим данным, такой подход экономит до $20,000 на транзакциях за год. Кроме того, правильная upgrade strategy снижает стоимость обновлений: проект с UUPS и timelock обновляется за 48 часов с минимальными рисками — в 7 раз быстрее, чем передеплой всего контракта.

Типичные ошибки в ТЗ и как их избежать

Отсутствие спецификации ролей. «Только owner может вызвать функцию» — а owner это EOA, multisig или DAO? В спецификации укажите конкретные адреса или роли. Наш опыт показывает, что до 90% reentrancy-атак происходят из-за неверного распределения прав.

Нет upgrade стратегии. Разработчики сами решают в процессе — риск несовместимых решений. Сравним: проект без upgrade strategy при ошибке требует полного передеплоя, что ведёт к потере ликвидности и доверия. Проект с UUPS и timelock обновляется за 48 часов с минимальными рисками.

Не указан целевой gas budget. Контракт написан, потом оказывается что каждый вызов стоит $50 gas. Указывайте бюджет в ТЗ: например, max gas per deposit = 200k gas (для Solidity 0.8.20). Это позволит сэкономить до $20,000 на транзакциях за год. Недостаток спецификации также приводит к дополнительным расходам на аудит в размере $5,000–$10,000.

Не описаны failure scenarios. Что происходит если оракул недоступен, если контрагент не имплементирует интерфейс? Пропишите все альтернативные пути и механизмы паузы.

Что входит в составление ТЗ под ключ?

Весь процесс занимает от 1 до 4 недель в зависимости от сложности. После сдачи ТЗ вы получаете документ, который можно передать любой команде разработчиков — он сокращает время code review и аудита на 30%. Если вам нужна помощь в составлении ТЗ, свяжитесь с нами.

Как построить upgrade strategy: пошаговая инструкция

1. Выберите тип прокси: UUPS, Beacon или Transparent. Для большинства DeFi-продуктов подходит UUPS — он дешевле и гибче.
2. Настройте управление: мультисиг Gnosis Safe 3/5 + timelock 48 часов.
3. Задокументируйте процедуру отката: как вернуть старую версию, если новая содержит критический баг.

Сравнение стратегий апгрейда:

Рекомендуем UUPS для контрактов с редкими обновлениями. Получите консультацию по вашему проекту — мы поможем выбрать оптимальную стратегию.