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.