A more up to date version version of this article (from September 2019) can be found here.

If you are planning to launch a project on the Ethereum blockchain, you probably know the importance of a third-party code audit. An external audit can ensure that your contracts function as intended and remove vulnerabilities in the code.

Choosing a team of experienced, rigorous auditors is of course essential, but your preparation will also impact the quality of the audit. Some effort on your part will go a long way toward getting you a better, faster audit.

The Preparedness Mindset

Imagine you’re about to onboard a senior developer to your team. You have very little time to get them FULLY up to speed on your codebase, also they’re remote, and you’re not going to talk to them much because you’re busy. This is essentially the relationship you have with an auditor.

Through our experience working with teams at ConsenSys and prominent project in the Ethereum ecosystem, we’ve identified a few things you can do to help us (or whoever your auditor is) help you:

1. Adhere to best practices

ConsenSys Diligence, with the help of the community, actively maintains a guide to what we consider Smart Contract Best Practices. We recommend reading this document early on, and again prior to seeking an audit.

2. Provide a plain english specification

Smart contract development has often been likened to writing mission critical code for NASA, and yet projects rarely have a specification describing what their contract code is meant to do.

Writing a specification is always a good idea, and doesn’t have to be a scary proposition. Many developers tell us this process helped them clarify their thinking and even identify issues in their own code.

Your specification should describe, in plain English, how each function of a contract should work and how those functions should work together. Functions may be treated as “black boxes”; the specification should describe what goes in, what comes out, what should happen, and what should not. After this, outline the design decisions behind the intended behavior of your code, rather than alternative approaches you might have chosen. This will help clarify for yourself the alternatives, as well as how people may misinterpret or misuse your code.

Diagrams are tremendously helpful, and highly indicative of a well thought-out design process. Both WeiFund and Golem have excellent specification diagrams that can be used as examples.

3. Think start to finish

Your smart contract code could be well-audited and safe. But there are still several critical steps before that code is deployed on the blockchain. Any mishaps in those steps could wipe out all your team’s efforts at providing a safe system.

Thus, a documented deployment process is essential in order to avoid introducing insecurities. Such a guide would include: which compiler version to use for which contracts, the order in which contracts will be deployed, and constructor parameters for initialization of each contract.

4. Write a good README

Your project should have a good README.md file which clearly describes how to install the system locally and run the test suite. It should also clearly link to other references which are useful to understanding the project.

If your contracts have a complex inheritance graph, this should be documented. If you will run a bug bounty after the audit (which we recommend), provide instructions for participation.

5. Clean up the project repository

Reducing clutter in your code makes an auditor’s job much easier. You should remove any unused or unnecessary contracts, files, or code.

You should also indicate:

which contracts are only used for testing purposes, and are not part of the final system,

which contracts are reused from audited code, or inherit heavily from audited code.

A good directory layout for your contracts might look something like this:

.

├── contracts

├── Migrations.sol

├── NewContract0.sol

├── NewContract1.sol

├── NewContract2.sol

├── NewContract3.sol

├── base

│ ├── MultiSigWallet.sol

│ ├── StandardToken.sol

│ └── Owned.sol

└── test

├── ReentryTestContract.sol

└── TestContract.sol

In the above directory tree,

./contracts/*.sol : would be the primary focus of the audit.

: would be the primary focus of the audit. ./contracts/base/*.sol would be well audited contracts which are inherited by the top level contracts. They might still require scrutiny, but to a lesser degree.

would be well audited contracts which are inherited by the top level contracts. They might still require scrutiny, but to a lesser degree. ./contracts/test/*.sol would be contracts which exist only for testing purposes, and are not meant to be deployed with the contract system.

6. Lint your code

Use solium, or solcheck, and follow the official Solidity style guide. Also use a linter on your test suite.

7. Comment complex sections of code

Gratuitous comments are not necessary, but comments clarifying your intention can be helpful, especially in highly complex sections of code.

8. Measure your test coverage

You’re using a test driven development approach to writing your contracts, right? ;)

Measuring test coverage is helpful for identifying sections of code that are not tested, or need more testing. Solidity-coverage is a great tool for this.

Of course 100% test coverage is not a panacea, so we also evaluate the quality and thoroughness of the test code. Writing tests in Python, or using the async / await syntax of NodeJS makes them much more readable and easier to follow.

9. Freeze the codebase

The purpose of a code audit is not to clean up your code or check for simple mistakes. Your contract system must be considered ready prior to the commencement of an audit. A commit hash from your git repo is required to specify the state of the code to be audited.

Conclusion

A good code audit can bring tremendous peace of mind, but it doesn’t relieve you or your developers of responsibility. Taking the time to prepare your code for a proper handoff will allow your auditors to do their best work, and allow you to feel more confident in your contract system.

Like this piece? Sign up here for our weekly newsletter.