Smart Contract Documentation (NatSpec)

We know what a contract looks like without documentation: integrators guess what each function does, auditors spend 30% more time, and users in MetaMask see an empty transaction description. Over 5+ years working with Solidity, we've established a process for creating full NatSpec documentation for protocols of any size—from simple ERC-20 to complex AMM pools. To date, we've documented over 50 contracts, including DeFi protocols with massive configuration logic.

Why Document Contracts?

Without NatSpec, every line of code is a puzzle. A developer integrating your token six months later should not have to reconstruct logic from bytecode and tests. NatSpec is built into the Solidity compiler: /// and /** */ comments automatically end up in the ABI and display in MetaMask when signing a transaction. This is not just a formality—it's protection against scam functions and user errors. According to our statistics, properly documented contracts reduce incorrect function calls by 80%.

How We Document a Contract

We go through each contract from start to finish. For all public and external functions, events, and custom errors:

• @notice — a user-friendly description (what the function does, why to call it, what will happen).
• @dev — technical nuances: gas limits, revert conditions, state assumptions.
• @param / @return — precise description of parameters and return values, including units (wei, basis points).

We supplement with @custom:security — marking places that require auditor verification. For contracts using OpenZeppelin Upgrades, we add @custom:oz-upgrades-unsafe-allow; otherwise the plugin will reject the migration.

Example of a properly documented function:

/// @notice Transfers tokens to a specified address
/// @dev Does not work with ERC-777 tokens due to hooks; use safeTransfer for unknown recipients
/// @param to Recipient address, cannot be address(0)
/// @param amount Number of tokens in smallest units (wei)
/// @return success True if the transfer was successful
function transfer(address to, uint256 amount) external returns (bool success);

How to Set Up Automatic Documentation Generation

Once NatSpec is written, documentation can be generated automatically. Use forge doc from Foundry: just add a [doc] section to foundry.toml and run forge doc. For Hardhat, install the solidity-docgen plugin and configure hardhat.config.ts. We set up the CI/CD so that documentation is updated and published to GitHub Pages or Vercel with every deploy. The whole process takes 2–4 hours, and you get up-to-date HTML documentation without extra effort.

Why NatSpec Is Critical for Security

Most reentrancy attacks happen because the integrator misunderstands the contract logic. When a function lacks @notice, the developer calls it with wrong parameters or does not expect side effects. NatSpec removes that uncertainty. Additionally, analysis tools (Slither, Mythril) can read @custom:security and automatically check marked sections. The NatSpec standard is described in the Solidity documentation.

What's Included in the Result

• Full audit of existing comments (if any).
• Writing NatSpec for all public/external functions, events, and errors.
• Generation of HTML documentation via forge doc or solidity-docgen.
• Integration with CI/CD (automatic generation on deploy).
• Consultation on best practices: which tags are mandatory, which are optional.

We guarantee 100% coverage of the public API and passing the compiler check—every tag is syntactically correct.

Typical Mistakes in NatSpec Creation

• Confusing @notice and @dev: the former is for the user, the latter for the developer.
• Missing @return description—the user doesn't know what the function returns.
• Missing @custom:security in places with potential vulnerabilities (flash loans, oracles).
• Overly long descriptions—MetaMask truncates text; keep it concise.

Timelines and Cost

Documenting one medium-sized contract (500–1000 lines) takes 1 working day. Setting up the documentation generation pipeline takes another 2–4 hours. Cost is calculated individually based on code volume and logic complexity. We will estimate your project within 24 hours—contact us.

Over 5+ years, we have documented more than 50 contracts: from simple ERC-721 to complex AMM pools and staking contracts. Our experience ensures that after documentation, integrators ask no questions on Discord and auditors work faster.

Want the same? Contact us for a consultation—we'll choose the optimal format for your project. Get a timeline and cost estimate.

Smart Contract Development

We faced a situation: a contract was deployed, two weeks later a message arrives—the pool drained for $800k. Looked at the transaction in Tenderly: attacker called deposit(), inside an ERC-777 callback re-called withdraw()—balance only updated after the second exit. Classic reentrancy, but not via ETH transfer—through an ERC-777 hook. ReentrancyGuard was only on withdraw().

Such cases are not rare. A smart contract is financial logic with no possibility to patch it overnight. Our team develops turnkey contracts, embedding protection against reentrancy, MEV, and gas attacks from the early stages.

How We Develop Smart Contracts Turnkey

We start with business logic audit and stack selection. Solidity 0.8.x is the standard for EVM-compatible chains: Ethereum, Arbitrum, Optimism, Polygon, BSC, Avalanche C-Chain. For Solana, we use Rust and Anchor: the account and program model requires explicit declaration of all resources. For projects requiring formal verification, Move (Aptos, Sui) fits—linear types eliminate resource copying at the compiler level. Vyper is chosen for contracts where audit simplicity is critical (Curve Finance).

Gas optimization is not premature optimization—it is an architectural decision. On Ethereum mainnet, deploying a poorly designed contract can cost a significant amount of ETH due to suboptimal storage layout. Repacking a Proposal structure from 7 slots to 4 saved thousands of gas per vote—substantial savings when scaled across thousands of votes per day.

Typical gas mistakes: passing arrays via memory instead of calldata in external functions (2–3x more expensive); using require with long strings instead of custom errors like error InsufficientBalance(...). Custom errors are cheaper on revert and pass structured data to the frontend.

Why Smart Contract Audit Is Critical for Security

Audit is not a one-time check—it is a built-in development stage. We use three levels:

1. Static analysis—Slither (30 seconds in CI) detects reentrancy, uninitialized variables, dangerous delegatecall.
2. Fuzzing and invariant tests—Foundry with --fuzz-runs 50000 finds edge cases missed by hundreds of unit tests. Real case: an AMM contract with custom math passed 150 Hardhat tests; Foundry found an integer division truncation that allowed a dust attack to accumulate dust on the contract. Echidna checks invariants ("sum of all balances ≤ totalSupply").
3. Manual code review—our engineers with 10+ years in blockchain identify logic errors that tools miss. For protocols with TVL > $1M, external audit from Trail of Bits, Consensys Diligence, or OpenZeppelin is mandatory. Timeline: 2–4 weeks.

Any upgradeable protocol must have a timelock. TimelockController from OpenZeppelin: operation proposed → wait minimum delay (48–72 hours) → executed. Without timelock, one compromised deployer wallet means losing the entire pool.

What Upgrade Patterns Do We Choose?

Storage collision is the main danger of proxies. Implementation v2 must not add variables before existing ones. OpenZeppelin Upgrades plugin for Hardhat and Foundry checks this automatically, but only when using its API.

How to Protect a Contract from MEV and Front-Running

On Ethereum mainnet, transactions in the mempool are visible to all. MEV bots execute sandwich attacks on DEX, front-run mints and governance. Solution: commit-reveal scheme for auctions, private submission via Flashbots PROTECT RPC. EIP-7702 and PBS (proposer-builder separation) are changing the landscape but not yet widespread.

What Is the Development Process?

1. Analysis—functional specification, call diagram, edge case analysis. Without this, coding starts in vain.
2. Development—Solidity/Rust with tests in parallel. Test → code → refactoring. Use Foundry for fuzz and invariant tests.
3. Internal audit—Slither + Echidna + manual code review. Foundry invariant tests for protocol invariants.
4. External audit—for projects with real money. Timeline: 2–4 weeks.
5. Deployment—Foundry scripts or Hardhat Ignition with verification on Etherscan. Gnosis Safe for ownership transfer immediately after deployment.
6. Monitoring—Tenderly alerts, OpenZeppelin Defender, Forta Network.

What Is Included

• Architecture documentation and contract specification (NatSpec).
• Source code with repository and CI (Slither, Foundry, coverage).
• Deployed contract with verification on blockchain explorer.
• Audit results (internal and external upon request).
• Access to monitoring and management (Gnosis Safe).
• Code warranty: critical bug fixes within one month after deployment.
• Consultation on web integration (wagmi, RainbowKit).

Estimated Timelines

• ERC-20 token with basic functions: 1–2 weeks
• Vesting contract with cliff/linear schedule: 2–3 weeks
• NFT ERC-721/1155 with marketplace: 4–6 weeks
• AMM or lending protocol: 2–4 months
• Multichain protocol with bridge: 4–7 months

Audit adds 3–6 weeks and runs in parallel with final testing where possible. Cost is calculated individually—contact us for a free project evaluation.

Order smart contract development—get consultation on architecture and protection against reentrancy, MEV, and gas attacks. Want to discuss details? Write to us—we will select the optimal stack for your task.