A Comprehensive Smart Contract Audit Readiness Guide

The team will need people with all the skills and knowledge necessary to successfully implement the full scope of the project. Team members will need a strong understanding both of the project and any external dependencies.

Consider:

1.1.1. Does the team have the requisite competencies for the project? In addition to any project-specific skills, does the team collectively possess the skills listed below?

1.1.1.1. Software Development

1.1.1.2. Understanding of the Blockchain and Smart Contracts

1.1.2. Are the core team members well-versed with—and, ideally, active participants in—neighboring communities that will be essential to the project?

A project’s owners should consider how the project’s needs and its team’s skill set overlap. Any gaps should be identified and rectified.

Every successful team needs a way of working together that structures how it makes progress—and guarantees that it does. Appropriate project management controls are an essential part of a successful project and protect against “brain drain” from inevitable turnover.

Consider:

1.2.1. Does the team have an established way to set goals, plan its work, and check on its progress? If so, how long have these controls been in place and how have they been working?

1.2.2. How would the team assign responsibility for interacting with auditors during an audit? 

1.2.3. Do the team’s business processes ensure that all team members are aware of the work other team members are doing and the issues they are facing? If a team member left the project, would another team member be able to step in and keep the project moving forward without a steep learning curve?

1.2.4. Is the project’s Git process well organized? Does the team follow specific and established procedures for branching and pull requests that maintain version control in the code?

A project’s owners should consider the ways in which their team plans work, ensures progress, and hedges against turnover. If they have not already done so, they should establish business processes that promote progress and create resiliency.

The team will require a leader with the skills and temperament necessary to set priorities, manage team members, and resolve problems and conflicts. This role could be an official Project Manager, but might also be a Lead Developer, Chief Technology Officer, or anyone who will take responsibility for managing the project.

Consider:

1.3.1. Does the team have a strong leader with experience leading complex developments?

1.3.2. Does the team’s leader have the judgment necessary to prioritize wisely among competing goods?

1.3.3. Does the team’s leader have the temperament necessary to engage and motivate team members and other stakeholders?

A project's owners should consider what steps can be taken to enhance the strengths and mitigate the weaknesses of the team’s leader. The Manager’s Path by Camille Fournier is a good resource on the art and science of technical management.

Smart contract coding without community is inherently insecure. If a Web3 project’s prospective users cannot inspect it, study it, hack it, and experiment on it, they are not going to trust it, either. Closed code makes users vulnerable to a project’s owners—and to anyone more capable than those owners. When would-be users have money at stake, closed code is an insurmountable obstacle to project adoption. Transparent and legally open-sourced code is one of the most important steps in fostering community trust in the project.

Consider:

2.1.1. What free software license works best for the project’s needs?

2.1.2. What battle-tested open-source code might facilitate the needs of the project?

Project owners should review the Free Software Definition and ensure that the project is using the license that best suits its needs. OpenZeppelin Contracts—the community-vetted standard for smart contract development—are also an excellent resource; they can be easily imported into a project’s codebase using the Node Package Manager. (See item 3.1.5.)

Whether or not the code is ready to deploy, it is good to consider how a project will attract and inform its community.

Consider:

2.2.1. How will the team market the project?

2.2.2. Who will serve as the project’s community manager? Should this be a new hire?

By considering these issues in advance of deployment, a project’s owners can create buzz around the project and build its momentum.

An audit can build public trust in a project’s code and facilitate its adoption. Community growth will create both challenges and opportunities.

Consider:

2.3.1. How will the team channel input from the community?

2.3.2. Should the project establish a community code of conduct and contribution guidelines?

2.3.3. Should the project establish a bug bounty program to incentivize its community to look out for vulnerabilities?

The project’s owners should consider how the project team would leverage the advantages of an engaged community. The varied and insightful writings and videos of Jono Bacon are a good resource for thinking about this.

Consider:

3.1.1. Does the code follow reasonable naming conventions? Naming should be as straightforward as possible. If a project’s naming is not straightforward, it should be explained in a glossary.

3.1.2. Is the code’s style consistent throughout the codebase? It should be. It is a good idea to follow Solidity’s style guide, but at the very least a project’s style should be documented somewhere. Moreover, developers should consider running a linter on every new line of code.

3.1.3. Is the code modular? Ideally, code should be in short and straightforward segments. If functionality is split into multiple modules (such as libraries or other contracts), it should be well encapsulated and the codebase should be navigable without too much jumping around.

3.1.4. Are various operations organized similarly? For both security and readability, it is a good idea to follow similar steps in operations performed. Code should follow the Checks-Effects-Interactions convention. Moreover, failing early and loudly is a recommended practice.

3.1.5. When the project imports external dependencies and libraries, does it do so in a clear, obvious, and well-documented way? When using industry-standard libraries and interfaces, it is always best to import these directly whenever possible, using tools such as the Node Package Manager (NPM), rather than copying and pasting.

The soundness of a project’s code has a direct relationship with the security of the money involved. For this reason, testing is an essential component of secure development, and project developers should conduct unit tests for all—or nearly all—of a project’s code. Failing to test code may be leaving the door open to a costly exploit.

Developers should follow a process of test-driven development, which uses short Agile development cycles to minimize the number and impact of assumptions. The Red-Green-Refactor approach is a recommended best practice. Developers should begin by testing at the unit level, then working their way up to testing at the level of a user, and finally to testing at the level of interactions with other systems.

Reviewing a project’s test suite helps an auditor understand the intent behind a project’s code, thereby assisting in successful auditing. It should come as no surprise that auditors frequently find code vulnerabilities by calling exposed functions that are absent from the test suite. For this reason, the existence of a comprehensive test suite is a good proxy for the overall quality of a project, and auditors consider this factor when assessing a project’s audit-readiness. Developers should construct a readable, well-structured, and fast test suite.

Consider:

3.2.3. Does the test suite test against local forks? Developers integrating with multiple projects should run a set of integration tests against local forks of mainnet. Leveraging forking capabilities of existing tools can be a useful approach to testing edge cases. However, developers should note this approach may require more set up and wiring, demanding stronger maintenance efforts. To mitigate, projects should consider a limited set of smoke tests before deployment against a local fork of mainnet.

3.2.4. Does the test suite cover at least 90 percent of the code? While high coverage does not guarantee that the test suite can detect all vulnerabilities, it does indicate that an appropriate level of effort is being devoted to testing.

3.2.5. Does the test suite include helpers? Developers should spend time building and using helpers and utilities. These make their tests more legible and easier to write.

3.2.6. Does the test suite include more advanced tests? For more advanced projects, developers may incorporate a range of more advanced testing tools to achieve a greater degree of confidence in their code’s correctness. Such tools may include those for fuzzing and property based testing. These advanced testing approaches are becoming increasingly common.

3.2.7. Does the test suite meet well-known standards? Developers should strive to meet generally accepted testing standards, such as the Smart Contract Security Verification Standards (SCSVS) for G12: Test Coverage.

There are a number of helpful test suite resources. For a short overview, consult Test Driven Development: By Example by Kent Beck. In developing a comprehensive test suite, developers may find that some scenarios are difficult to test; for these situations, it can be valuable to refer to Gerard Meszaros’s xUnit Test Patterns. Of course, there is often value in following the examples of others; developers should review testing guidelines shared by others in the ecosystem.

While it may not be any developer’s favorite part of a project, good documentation is essential to success—and it is the first place auditors will look to understand a project’s purpose, features, and inner workings.

Project documentation should be clear, comprehensive, and up-to-date. Specifically, auditors will consider:

3.3.1. Does the documentation achieve all of the following objectives:

3.3.1.1. Does it tell users, contributors, and auditors the intention behind the project?

3.3.1.2. Does it provide detailed explanations of what the code is doing—as well as statements of what it is not doing in any place where omitting such information might cause confusion?

3.3.1.3. Whenever applicable, does it explain why one way of achieving a particular aim was chosen over another way?

3.3.1.4. Whenever applicable, does it make explicit any assumptions made by the developers?

3.3.2 Does the project have a Readme file? A Readme should serve as a straightforward index of its project. It should follow the simple and effective Standard Readme style. It should also include a specific section that states how members of the community should disclose any security vulnerabilities found in the project.

3.3.3. Does the code have rich documentation in every contract, function, event, and variable that documents every function included in the public API? While it is tempting to think that clearly written code does not require documentation, the fact is that protocols for decentralized applications will be called by a wide variety of external agents. For this reason, good docstrings are important. They should follow the NatSpec format. If functions are private/internal, but implement sensitive logic, they should be documented as well.

3.3.4. Does the project have inline comments? In addition to NatSpec, it is a good idea to have inline comments to explain complex functionality and the current status of certain sections of code. It is also important to check for “TODOs” and ensure that they are resolved prior to an audit or large release.

3.3.5. Does the project have automated tools to parse and generate external documentation based on the contracts’ inline documentation? Updating documentation for protocols that regularly change can be time-consuming. It is always a good idea to make documentation changes part of an automated deployment pipeline, so that when code documentation changes, public-facing documentation is automatically updated as well.

3.3.6. Is there external documentation on the project’s website? Such documentation might include more expansive discussion of the project’s system architecture, economic incentives, roles, and other relevant design considerations.

3.3.7. Is there documentation on the deployment process for on-chain code changes? For smart contract protocols that make on-chain upgrades, a clear deployment process is essential. (This is true whether upgrades are initiated from a privileged account or a DAO.) The deployment process can have implications for both the security and the functionality of the code. OpenZeppellin Upgrades Plugins are a great resource to help manage upgradeable contracts on Ethereum.