Technical Specification for Blockchain Projects: Full Guide
When launching a DeFi protocol, an audit often reveals reentrancy, forcing an urgent rewrite of the logic. Without a clear technical specification, every sprint becomes chaos: developers change functions, and testers can't cover new scenarios. According to statistics, 60% of blockchain projects face reentrancy due to the lack of a specification. A specification helps anticipate such attacks at the design stage. We have gone through 50+ blockchain projects and know: a high-quality technical specification is the foundation for product reliability.
Why a Regular Specification Doesn't Work for Blockchain?
Traditional specifications are designed for centralized systems where bugs can be fixed with a server patch. In blockchain, after a contract is deployed, logic can only be changed through an upgrade strategy — which requires a carefully designed proxy architecture. For example, UUPS proxy, described in the Smart contract documentation of OpenZeppelin, allows contract upgrades via a timelock. In addition, every operation costs gas: a non-optimized call can cost $50 during peak hours. An error in fee calculations makes the product unprofitable. We have seen projects where smart contracts had to be rewritten from scratch because the specification didn't include access role specifications or didn't consider flash loan attacks.
What Sections Should a Blockchain Project Technical Specification Contain?
System Overview
- Project goal and key stakeholders.
- Chosen blockchain (L1/L2) and justification: Ethereum, Polygon, Arbitrum, or Solana.
- High-level architecture with a diagram — interaction of contracts, off-chain components.
- Integrations: oracles (Chainlink), bridge, external protocols.
How to Describe Smart Contracts in the Specification?
Each contract needs a detailed description: function signatures with parameters, emitted events, access roles (AccessControl), configurable parameters. It's important to specify standards (ERC-20, ERC-721, ERC-1155, ERC-4626) and proxy type. Here is an example for a liquidity pool contract:
Contract: LiquidityPool Network: Arbitrum One Standards: ERC-20 compatible Upgradeability: UUPS proxy Functions: - deposit(uint256 amount) — deposit tokens, mint LP shares - withdraw(uint256 shares) — burn LP shares, receive tokens + accumulated fees - swap(address tokenIn, uint256 amountIn, uint256 minAmountOut) — swap 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) Roles (Access Control): - DEFAULT_ADMIN_ROLE: Gnosis Safe 3/5 - PAUSE_ROLE: Protocol Defender (multisig or automated) - FEE_MANAGER_ROLE: DAO timelock Parameters (configurable): - swapFee: 0.3% (range: 0.01%-1%) - protocolFeeShare: 20% from swap fee Example of a liquidity pool contract specification: above is a full template — fill it out for each contract. Specify a gas budget: e.g., max gas per deposit = 200k gas. This prevents unexpected costs after deployment.
Token Specification (if any)
Token: PROTO Standard: ERC-20 + ERC-2612 (Permit) Supply: 100,000,000 (fixed) Decimals: 18 Mintable: no (fixed supply) Burnable: yes (holder can burn) Pausable: yes (PAUSE_ROLE) Distributor: special Vesting contract Off-Chain Components
- Indexer (The Graph subgraph) — which events are indexed, GraphQL schema.
- Backend API (if needed) — endpoints, authentication.
- Frontend — tech stack, wallet integration (wagmi, RainbowKit).
Infrastructure
Deploy: - Foundry Deploy Scripts + Hardhat for verification - Multisig owner: Gnosis Safe 3/5 - Timelock: 48 hours for admin functions - Proxy: UUPS (implementation upgrade through timelock) Monitoring: - OpenZeppelin Defender for alerts - Tenderly for transaction simulation - The Graph for historical data Networks for deployment: - Testnet: Arbitrum Sepolia - Mainnet: Arbitrum One Security
- List of smart contract patterns: Reentrancy guard, CEI, checks for oracle manipulation.
- Protection against flash loan attacks: check pool balance before and after swap.
- Access control scheme: each role linked to a specific address (EOA, multisig, DAO).
- Upgrade strategy with timelock: initiation and rollback process.
Testing
Unit tests (Foundry):
- All public functions.
- Edge cases and boundary conditions.
- Revert scenarios.
Fuzz tests:
- Invariants: "totalShares * pricePerShare = totalAssets".
- Random deposit/withdraw sequences.
Fork tests:
- Integration with real protocols on a forked mainnet.
Coverage target: 95%+.
Audit Plan
- Audit scope: which contracts are checked.
- Timeline: audit after code freeze, before mainnet.
- Criteria for readiness: all medium+ findings fixed.
How to Save on Gas with the Specification?
A clearly stated gas budget in the specification forces developers to optimize code from the start. For example, a limit of 200k gas per deposit requires storage-efficient patterns. According to our data, this approach saves up to $20,000 per year on transaction costs. Additionally, a proper upgrade strategy reduces update costs: a project with UUPS and timelock updates in 48 hours with minimal risks — 7 times faster than redeploying the entire contract.
Typical Mistakes in Technical Specifications and How to Avoid Them
Lack of role specification. "Only owner can call this function" — but is the owner an EOA, multisig, or DAO? In the specification, specify specific addresses or roles. Our experience shows that up to 90% of reentrancy attacks occur due to incorrect permission distribution.
No upgrade strategy. Developers decide on the fly — risk of incompatible solutions. Compare: a project without an upgrade strategy, when an error occurs, requires a full redeploy, leading to loss of liquidity and trust. A project with UUPS and timelock updates in 48 hours with minimal risks.
No target gas budget. The contract is written, and then it turns out each call costs $50 in gas. Specify a budget in the specification: e.g., max gas per deposit = 200k gas (for Solidity 0.8.20). This can save up to $20,000 per year on transactions. Lack of specification also leads to additional audit costs of $5,000–$10,000.
Failure scenarios not described. What happens if the oracle is unavailable, if the counterparty does not implement the interface? Write down all alternative paths and pause mechanisms.
What Is Included in Turnkey Specification Writing?
| Section | Description | Duration |
|---|---|---|
| Requirements analysis | Interview with the client, competitor research, business logic specification | 3-5 days |
| Architecture design | Choice of L2, stack, contract patterns, upgrade strategy | 2-4 days |
| Smart contract specification | Functions, events, roles, gas budget, test scenarios | 4-7 days |
| Off-chain description | Indexer, backend, frontend, integrations with Chainlink, bridge | 2-3 days |
| Infrastructure and monitoring | Deploy scripts, Defender alerts, Tenderly simulation | 1-2 days |
| Final documentation | Summary table, checklist for developers, testing and audit plan | 1-2 days |
The entire process takes 1 to 4 weeks depending on complexity. After delivering the specification, you get a document that can be handed over to any development team — it reduces code review and audit time by 30%. If you need assistance in writing a specification, contact us.
How to Build an Upgrade Strategy: Step-by-Step Instructions
- Choose the proxy type: UUPS, Beacon, or Transparent. For most DeFi products, UUPS is suitable — it is cheaper and more flexible.
- Configure governance: multisig Gnosis Safe 3/5 + 48-hour timelock.
- Document the rollback procedure: how to revert to the old version if the new one contains a critical bug.
Comparison of upgrade strategies:
| Parameter | UUPS | Transparent | Beacon |
|---|---|---|---|
| Deployment cost | Low | Medium | Low |
| Code complexity | Medium | Low | High |
| Security | High | High | Medium |
| Gas efficiency | High | Medium | High |
We recommend UUPS for contracts with infrequent updates. Get a consultation on your project — we'll help you choose the optimal strategy.