Need Help Writing Your Technical Specification?
Get expert guidance on writing a production-quality blockchain specification.
Complete Guide
Quick Answer
A blockchain technical specification contains 3 sections: System Overview (1 page — what the system does, key security assumptions, protocol invariants), State Variables (one table per contract — variable name, type, valid range, who can modify), and Function Specifications (for every public/external function — caller, preconditions, state changes, events, post-conditions, edge cases). Timeline: 1-2 days for simple ERC-20, 2-3 weeks for DeFi lending protocol, 3-4 weeks for full DEX with governance.
What the Specification Contains
Section 1 — System overview (1 page):
One paragraph: what does this system do? Second paragraph: what are the key security assumptions? Third paragraph: what are the protocol invariants (statements that must always be true)?
Example invariant statements:
"The sum of all user collateral values (in USD) times their respective collateral factors must always exceed the sum of all user debt values at any oracle price."
"totalSupply of receipt tokens must always equal total underlying assets in the vault minus accrued fees."
"A user's health factor must be checked before any withdrawal or borrow that increases their debt or reduces their collateral."
Section 2 — State variables (one table per contract):
| Variable Name | Type | Initial Value | Valid Range | Who Can Modify |
|---|---|---|---|---|
| totalDeposits | uint256 | 0 | 0 ≤ x ≤ MAX_UINT256 | Internal only (via deposit/withdraw) |
| feeRate | uint256 | 250 | 0 ≤ x ≤ 1000 (0%–10%) | Owner only |
| userBalances | mapping(address→uint256) | {} | 0 ≤ each ≤ totalDeposits | Internal only |
Section 3 — Function specifications:
For every public or external function:
Function: deposit(uint256 amount)
Caller: Any address
Preconditions:
- amount > 0
- caller has approved this contract to spend >= amount of the deposit token
- total deposits after this call do not exceed the deposit cap
State changes:
- userBalances[msg.sender] increases by amount
- totalDeposits increases by amount
- depositToken is transferred from msg.sender to this contract
Events emitted:
- Deposited(msg.sender, amount, block.timestamp)
Post-conditions:
- userBalances[msg.sender] == userBalances[msg.sender] (before) + amount
- totalDeposits == totalDeposits (before) + amount
Edge cases:
- amount = 0: reverts with "Amount must be positive"
- amount exceeds deposit cap: reverts with "Deposit cap exceeded"
- token transfer fails: reverts (ERC-20 transferFrom revert propagates)