Pre-audit preparation plan

Day 1

Code comments and description of the protocol's main architectural features

Code comments are an essential part of an effective audit. They allow an auditor to better understand the team's idea and the function flow itself.

There is a special format - NatSpec - which is a standard for smart contracts.

Which code sections must have comments?

Firstly, it is considered good practice to write comments for all functions in general:

Second, be sure to write comments to functions that contain snippets of assembly code:

Third, large functions with many calls inside:

Fourth, any mathematical calculations:

Good examples:

Basin protocol - s the next step in the evolution of EVM-native DEXs.

Panoptic - is a permissionless options trading protocol. It enables the trading of perpetual options on top of any Uniswap V3 pool.

Useful hints:

Coinbase Solidity Style Guide - This is a guide for Coinbase engineers developing EVM-based smart contracts.

Inline Yul Style Guide - This is a guide for optimizooors developing EVM-based smart contracts.

Useful tools:

Day 2

Run your code with static analysis tools

With the evolution of web3 sphere several useful tools (such as static analysis frameworks) have launched to check the final version of your smart contracts for various vulnerabilities and optimisations.

Each of these tools can help you find bugs in your project. It is good practice not only to use them to check the code, but also to include the reports in the project documentation.

Useful tools:

Day 3

Create diagrams and graphics for your protocol

Sometimes it's quite difficult for the auditor to understand the flow between contracts or any other complex architecture of the project. In this case, diagrams can be very useful.

It is better to create graphics based on the perspective of your users: how they plan to use your protocol, how function calls will interact with each other, and what the results of the final actions will be.

There are also some great tools (online or code editor plugin) that can help you with this.

Good examples:

Protocol examples:

Open Dollar - is a floating $1.00 pegged stablecoin backed by Liquid Staking Tokens with NFT controlled vaults.

Tangible Caviar - a self-sustaining liquid-wrapper for locked tokens vePEARL, the governance token of the Pearl Exchange.

Lens Protocol V2 - is a social graph built on-chain, designed to empower creators to own their identities, and links between themselves and their community, forming a fully composable, user-owned social graph.

Useful tools:

Day 4

Specify invariants, user roles and contracts

Another crucial part of your preparation is to specify protocol invariants, user roles and contract breakdowns.

"Invariants are conditions that must always be true under a certain set of well-defined assumptions. For example, in an ERC20 contract, an invariant would be that the sum of all balances in the contract should equal the total supply. If a function call or transaction violates this invariant, something has gone wrong with the code, and the system is no longer functioning properly." - RareSkills

Descriptions of user roles can help your auditor get a clear picture of who will interact with you project. There are no "regular users", there can be: Admins, Minters, Government, Depositors, Stakers and even... Hackers!

As for contract descriptions, it will be useful to get a high level view of the protocol and figure out the main point of it. You can also specify which parts of the fork code were used in that particular contract.

Good examples:

Protocol examples:

Panoptic protocol - Panoptic is a permissionless options trading protocol. It enables the trading of perpetual options on top of any Uniswap V3 pool.

Smart Wallet - SmartWallet is a smart contract wallet. It supports multiple owners and allows for signing account-changing user operations such that they can be replayed across any EVM chain where the account has the same address.

UniStaker Infrastructure - Uniswap V3 protocol fee collection and distribution via UNI staking.

Ethena Labs - is a synthetic dollar protocol built on Ethereum that provides a crypto-native solution for money not reliant on traditional banking system infrastructure, alongside a globally accessible dollar denominated instrument - the Internet Bond.

Where to learn more about invariants:

Invariant testing in foundry - In this article, we will discuss invariants and how to perform an invariant test on solidity smart contracts using foundry test suites.

Categorizing_Properties - an awesome presentation by Certora.

Properties - This file lists all the currently implemented Echidna property tests for ERC20, ERC721, ERC4626 and ABDKMath64x64. For each property, there is a permalink to the file implementing it in the repository and a small description of the invariant tested.

Thinking About Properties - In the current directory, there are three subdirectories - Meeting Scheduler, Popsicle Finance, and Ticket Depot. Each subdirectory contains a system implemented in Solidity.

Invariant testing WETH With Foundry - In this short guide, we'll write invariant tests from the ground up for Wrapped Ether, one of the most important contracts on mainnet.

Useful tools:

Day 5

Identify scope and out-of-scope details. Follow checklists

Scope is a specific part of your protocol that you want audited. In some cases it may be your entire protocol, in others it may be just a few specific contracts.

Out-of-scope is also important to identify. You probably don't want parts of your project such as "node_modules", "tests", "scripts" to be audited and charged for.

You can specify bugs from previous audits, some weird tokens behaviour or blockchain networks are out-of-scope. AuditProfile gives you a great example of things to put on your out-of-scope list.

Could be in your out-of-scope list:

- Impacts requiring attacks that the reporter has already exploited themselves, leading to damage

- Impacts caused by attacks requiring hypothetical access to leaked keys/credentials

- Impacts caused by attacks requiring access to privileged addresses (governance, strategist) except in such cases where the contracts are intended to have no privileged access to functions that make the attack possible

- Impacts relying on attacks involving the depegging of an external stablecoin where the attacker does not directly cause the depegging due to a bug in code

- Mentions of secrets, access tokens, API keys, private keys, etc. in Github will be considered out of scope without proof that they are in-use in production

- Impacts on test files and configuration files unless stated otherwise in the bug bounty program

- Feature requests

Protocol examples:

Ethereum Credit Guild seeks to strike a new middle ground between honest-majority systems and pure peer to peer lending.

Ondo Finance - rUSDY Is an interest bearing stablecoin, and can be thought of as a rebasing variant of Ondo's USDY (Ondo U.S. Dollar Yield) token

Useful checklists:

Solodit checklist - one of the best checklists from the creators of the project that helps auditors to search for bugs from different audit reports.

The Ultimate 100+ Point Checklist - while no checklist can cover every issue that comes up in a solidity code review, these are ones I’ve seen recurring in my code reviews or that arise out of unexpected quirks in Solidity or blockchain environments.

Multichain Auditor - observations and tips for auditing protocols on multiple chains

Bridge Security Checklist: Client Side - a great checklist by Spearbit, a decentralized network of expert security engineers offering reviews and other security related services to Web3 projects with the goal of creating a stronger ecosystem.

A Thread on Auditing Merkle Proofs in Smart Contracts - would be perfect if you have Merkle trees in your protocol

Arbitrum: Basic Features, Technical Details and Differences from Ethereum - in this article we focus only on those aspects that can be really useful for auditing Arbitrum-based projects

Liquid Staking Derivatives (LSD) Checklist - a great checklist by Decurity for DeFi projects.

The ultimate security checklist - a nice checklist by Beirao for different stages of protocol development.

Integration Checklist for LayerZero - a checklist is intended to help prepare a project that integrates LayerZero for an external audit or Mainnet deployment.

ERC4337 Audit Checklist - a detailed checklist with some points on integration with other standarts and different examples.

Development Guidelines - Follow these high-level recommendations to build more secure smart contracts.

Day 6

Final preparations and a setup guide

Before requesting the audit, it is necessary to freeze your code and not make any changes for at least 3-4 days before the process.

Some companies or solo auditors recommend a team to get a separate repo on GitHub for the audit purposes.

Prepare all protocol documentation in the repo and provide the names, emails and time zones of key team members who will liaise with the auditors and answer their questions.

The setup guide must be clear to understand and launch the protocol in a new environment. Specify any commands or actions that need to be taken to install any required dependencies and run tests for your protocol.

Protocol setup examples:

PoolTogether - unlocks organic usage for wallets, yield sources & blockchains

AI Arena - is a PvP platform fighting game where the fighters are AIs that were trained by humans.

Day 7

Find the right company or solo auditor

There are several ways to get your first audit done: hire a company, hire an established solo auditor or hire a not-well-known auditor.

Companies cost more than any of the other options. This option can also be good for a protocol public reports and marketing.

Established solo auditors often work with a team of other good auditors. Generally there will be 3-5 different researchers working on your project.

Not-well-known auditor is a person who usually participates in public contests and shows nice results. Their service is usually cheaper, but it can be perfect for the very first audit to illuminate the most common vulnerabilities.

Please note, the security report is not a result but a process. Even big protocols with top level developers can miss some details that could lead to a protocol break. One audit is never enough!

Some companies to hire:

TrailOfBits - Since 2012, Trail of Bits has helped secure some of the world’s most targeted organizations and products.

Spearbit - Spearbit is a decentralized network of security experts that offers Web3 security consulting services.

Consensys Diligence - Consensys Diligence offers a range of products and services to help teams launch their blockchain applications with confidence.

Cyfrin - Cyfrin helps secure some of the top protocols and organizations in DeFi. We combine top leading researchers to enhance the security of our customers and their users.

Contest platforms leaderboards:

Code4rena leaderboard

CodeHawks leaderboard

Cantina leaderboard

Sherlock leaderboard

Immunefi leaderboard

Hat finance leaderboard

Suggestions and questions are welcome here: Twitter: @RightNowIn