How to Prepare a Smart Contract for a Security Audit

A smart contract is not audit-ready simply because coding is finished and tests technically pass. Before external auditors begin, they need to understand the system, its architecture, and exactly what is included in the review.

They also need to reproduce the build, run the tests, and understand the trust model behind privileged roles and external integrations. Disclose known risks upfront, and base the audit on one stable release candidate.

Poor preparation can waste audit time on setup issues, documentation gaps, and basic defects instead of deeper security concerns. Smart contract audit preparation comes near the end of the wider smart contract development process, once development and testing are stable.

When Is a Smart Contract Ready for an Audit?

A contract is closer to audit-ready once core features are implemented and the architecture has genuinely stabilized. Requirements should be unlikely to change, tests should be passing, and known major issues should already be fixed. Documentation needs to match the actual code, external integrations should be identified clearly, and the team should know the exact release candidate. 

Define the Smart Contract Audit Scope

A precise scope tells auditors exactly what they need to review and what falls outside the engagement.

List the Contracts and Files in Scope

Include core contracts, libraries, proxy contracts, implementations, custom interfaces, deployment scripts, governance scripts, and migration scripts. Avoid vague scope statements such as review everything in the contracts folder, since that wastes valuable auditor time.

Define What Is Out of Scope

Document the frontend, backend, unchanged third-party libraries, mocks, infrastructure, and existing external protocols clearly upfront. Also record any assumptions your contracts make about these excluded components, since assumptions still matter.

Confirm the Target Blockchain and Environment

Record the blockchain or network, chain-specific behavior, production integrations, external contract addresses, oracle assumptions, and bridge assumptions. This context helps auditors understand real deployment conditions rather than guessing them independently.

Record the Repository and Commit Hash

Include the repository, branch or tag, and exact commit hash the auditor should review against. The auditor should always work against one single, authoritative version of the codebase.

Document Compiler and Build Settings

Record the Solidity version, optimizer settings, EVM target, framework version, dependency versions, and any relevant build flags used. This information avoids any confusion between the developer and auditor environments on the actual review process.

The deliverable of this section is a full scope document for a smart contract audit that reviewers can confidently refer back to throughout the audit. These requirements for smart contract audit are met early on to avoid any confusion at the start of the formal review.

Prepare the Technical Documentation

Good documentation gives auditors the context they need to understand the protocol without reverse engineering its purpose.

Explain What the Protocol Does

Write a plain language overview covering the purpose, users, assets, major actions, and important rules of the system. Avoid simply repeating Solidity function names, since auditors need context that code alone cannot provide.

Document the Main User Flows

Show flows like, deposit, update accounting, mint shares, withdraw or deposit collateral, borrow, repay, and withdraw. These flows give auditors a mental model before they start implementing individual functions.

Create a Contract Architecture Diagram

Show the linking of users and wallets to entry contracts, core contracts, external protocols or oracles, and accounting or treasury components. Sometimes, a visual diagram can communicate this relationship faster than words alone.

Document External Integrations

List tokens, oracles, decentralized exchanges, bridges, lending protocols, relayers, APIs, and cross-chain infrastructure the system depends on. Each integration represents an assumption the auditor needs to evaluate carefully during review.

Explain the Upgrade Model

If upgradeable, document the proxy type, implementation, admin, upgrader, timelock, and storage layout used throughout the system. If the contract is immutable instead, state that clearly so no false assumptions form.

Document Roles, Permissions, and Trust Assumptions

Documenting roles and trust assumptions helps auditors understand who can control critical parts of the system.

List Every Privileged Role

Document every owner, admin, operator, pauser, upgrader, treasury, and governance role that exists anywhere in the system. Missing even one privileged role can leave a significant blind spot during the actual security review.

Create a Permission Matrix

A permission matrix makes each role’s capabilities explicit, helping auditors verify access controls and identify unauthorized actions quickly.

Document Multisigs and Timelocks

Explain which actions require multisig approval, which actions are delayed by a timelock, and who can execute each one. This documentation prevents confusion about how quickly privileged actions can actually take effect.

Identify Trusted External Systems

Document trust assumptions around oracle providers, bridges, backend signers, relayers, and other external protocols your contracts rely on. These external trust assumptions often introduce risks that pure code review alone cannot catch. A documented smart contract threat model should capture each of these trust relationships clearly.

Document Emergency Controls

Explain who can pause the system, what exactly gets paused, how recovery works, and who can resume normal operations. Also document what happens during a suspected key compromise, since that scenario needs a clear plan.

Define the Smart Contract Invariants

Invariants define the security and accounting properties that must remain true under every valid transaction sequence

Identify What Must Always Remain True

Common invariants include assets staying greater than or equal to liabilities, and unauthorized accounts never being able to mint tokens. Rewards should never be claimed twice, and supply should never exceed its defined cap.

Document Financial and Accounting Invariants

These invariants matter especially for vaults, lending platforms, staking systems, DeFi protocols, and real-world asset platforms handling value. Getting accounting invariants wrong can directly translate into real financial loss for users.

Define Access Control Invariants

Examples include only governance being able to upgrade the system, and only the pauser being able to trigger a pause. No regular user should ever be able to change protocol-wide parameters directly.

Record Economic Assumptions

Document oracle freshness requirements, rounding behaviour, collateral thresholds, liquidation rules, reward calculations, and fee logic. Such economic assumptions are often cloaking subtle risks that pure logic review tends to overlook entirely.

Connect Invariants to Tests

Map each invariant to a corresponding test so auditors can verify that critical security properties are supported by actual testing evidence.

Clean Up the Code Before the Audit

Cleaning the codebase removes unnecessary review noise and allows auditors to focus their attention on meaningful security and business logic risks.

Fix Compiler Warnings

Investigate every compiler warning rather than ignoring it, since warnings sometimes point toward genuine underlying logic issues. A clean compile also signals attention to detail that auditors tend to notice quickly.

Remove Dead and Experimental Code

Remove unused functions, outdated modules, commented-out logic, unused imports, and leftover debugging code from the repository. Dead code adds unnecessary review surface without providing any real value to the final product.

Resolve TODO and FIXME Comments

Fix outstanding TODO and FIXME comments directly, or document them clearly as known limitations if they cannot be resolved yet. Leaving them unresolved and unexplained creates unnecessary uncertainty during the review process.

Improve Naming and Code Structure

Aim for small functions, clear naming, predictable control flow, useful NatSpec comments, and readable access control logic throughout. Readable code genuinely speeds up review and reduces the chance of misunderstanding intent.

Document Modified Third-Party Code

Clearly identify any forks, patched libraries, custom changes, and differences from the original upstream version being used. Undocumented modifications to trusted libraries are a common source of unexpected audit findings.

Pin Dependency Versions

Pin exact versions of Solidity, OpenZeppelin, Foundry, Hardhat, and any other Solidity libraries used in the project. Our guide to smart contract development tools covers these frameworks and libraries in more depth.

Complete Smart Contract Testing Before the Audit

Thorough testing helps identify defects before handoff and gives auditors stronger evidence about how the contracts behave under different conditions.

Unit Testing

Cover valid inputs, invalid inputs, permissions, state changes, edge values, and expected failure behavior across every core function. Unit tests form the foundation that every later testing layer builds directly upon.

Integration Testing

Test interactions between contracts, tokens, oracles, bridges, decentralized exchanges, and other external protocols your system depends on. Integration problems often surface only when components interact, not when tested in isolation.

Fork Testing

Use a realistic blockchain state where simplified mocks would otherwise be insufficient to represent real production conditions accurately. Fork testing exposes integration issues that purely mocked environments routinely fail to catch.

Fuzz Testing

Generate unexpected inputs automatically to expose edge cases that manual test writing would likely never anticipate. This approach often reveals arithmetic and boundary issues hiding beneath otherwise passing test suites.

Invariant Testing

Test whether core security properties remain true across long, varied sequences of actions rather than single isolated transactions. This directly verifies the invariants documented earlier during specification and design work.

Test Failure and Edge Cases

Include zero values, duplicate actions, stale prices, failed external calls, paused states, and unexpected transaction ordering scenarios. These edge cases frequently reveal assumptions that only hold true under normal, expected conditions.

Review Test Coverage

Coverage identifies genuinely untested areas of code, but high coverage alone never proves the system is actually correct. Our detailed breakdown of smart contract testing methods covers these testing approaches in greater depth.

Run Security Tools Before the Audit

Automated security tools can identify common vulnerability patterns early, allowing auditors to spend more time investigating complex protocol-specific risks.

Static Analysis

Smart contract static analysis tools such as Slither and Aderyn scan code without executing transactions, flagging common vulnerability patterns automatically. Running these early catches obvious issues well before a human reviewer ever sees the code.

Fuzzing and Property Testing

Depending on the project, Foundry, Echidna, or Medusa can automatically generate test cases that stress contract logic thoroughly. These tools often uncover edge cases that manual testing alone would likely miss entirely.

Formal Verification

For high-value or mathematically defined properties, tools like Certora, Halmos, or Kontrol can mathematically verify specific behavior. Not every project genuinely needs formal verification, since it suits narrow, well-defined properties best.

Review and Triage Tool Findings

Classify every finding as fixed, a false positive, an accepted risk, a known limitation, or something needing auditor review. Chasing a meaningless zero warning result often wastes time better spent on genuine security priorities.

Review the Highest Risk Parts of the Smart Contract

Focus the internal review on contract areas where failures could create significant security, financial, access-control, or operational consequences.

Access Control and Admin Functions

Review ownership, role changes, minting and burning, pause functionality, upgrade mechanisms, and treasury actions across the entire system. These areas typically carry the highest impact if something goes seriously wrong.

Asset Transfers and Accounting

Review deposits, withdrawals, shares, rewards, debt, collateral, and fee calculations throughout every relevant contract in the system. Accounting errors here directly translate into real financial impact for actual users.

External Calls and Integrations

Review callbacks, token interactions, protocol integrations, bridge dependencies, and cross-contract assumptions made throughout the codebase. External calls introduce dependencies on systems your own code cannot fully control or verify.

Oracle and Pricing Logic

Check for stale prices, decimal handling, update frequency, fallback logic, and assumptions about potential price manipulation. Oracle-related bugs remain one of the most common causes of serious DeFi exploits.

Arithmetic and Rounding

Pay particular attention to financial calculations, since small rounding errors can compound significantly across many repeated transactions. Even minor arithmetic mistakes can create exploitable discrepancies over time in active systems.

Upgradeability and Storage

Review initializers, storage layout, upgrade authorization, and how implementation changes interact with existing stored contract data. Storage layout mistakes during an upgrade can silently corrupt data without any obvious error.

Cross-Chain Logic

Review message authentication, replay protection, destination assumptions, and bridge dependencies for any cross-chain functionality present. Cross-chain systems introduce additional trust assumptions beyond a single blockchain environment.

Economic and Business Logic

Focus specifically on system-specific risks rather than only generic, well-known Solidity bugs that tools already catch. Business logic flaws often matter more than technical bugs in financially significant systems.

Test Deployment and Upgrade Procedures

Testing deployment and upgrade procedures ensures that the contracts reviewed are properly configured, initialised, upgraded, and released to production environments.

Test Deployment Scripts

Run the same scripts intended for production deployment, rather than relying on a different, informal manual process. This ensures the tested process matches what will actually happen at launch.

Verify Constructor and Initializer Parameters

Check exact deployment values carefully, since incorrect parameters can quietly produce a contract that behaves unexpectedly from day one. A single wrong parameter can undermine otherwise correct and well-audited Solidity code.

Test Proxy Upgrades

For upgradeable contracts, validate the complete upgrade process end to end rather than only testing individual isolated steps. A working individual step does not guarantee the full upgrade sequence behaves correctly together.

Check Storage Compatibility

Confirm new implementations preserve existing storage layout safely, since storage collisions can silently corrupt previously stored contract data. This check matters every single time an upgradeable contract changes.

Verify Role Transfers

Test the transfer from a temporary deployer account to the intended multisig, governance contract, or timelock carefully. Confirm no unintended privileged access accidentally remains with the original deploying wallet afterward.

Test Governance and Multisig Actions

Confirm that governance proposals and multisig approval actions genuinely work correctly before any real mainnet deployment occurs. Discovering a broken governance flow after launch creates unnecessary operational risk.

Make Sure the Project Is Reproducible

Auditors should be able to clone, build, and test the project reliably without depending on hidden local configuration or undocumented setup steps.

Document Environment Requirements

Include the required compiler, framework, package manager, RPC needs, and any necessary environment variables clearly in documentation. Missing environment details are a common and entirely avoidable source of early audit delays.

Pin Compiler and Tool Versions

Pinning versions avoids differences between developer and auditor environments that could otherwise produce inconsistent results. Version mismatches can cause confusing, hard-to-diagnose discrepancies during the review process.

Provide Build Commands

The auditor should know exactly how to compile the project without needing to guess or reverse engineer the process. Clear build commands remove an unnecessary barrier before genuine review work can even begin.

Provide Test Commands

Avoid undocumented test setup steps that force the auditor to guess how to actually run your existing test suite. Clear, documented test commands save meaningful time during the earliest stages of review.

Test Everything From a Fresh Clone

The project should work through a simple clone, install, build, and test sequence without any hidden local configuration. This confirms genuine reproducibility rather than an environment that only works on one developer's machine.

Document Known Issues and Accepted Risks

By disclosing known issues and accepted risks, auditors get the full context and can distinguish documented limitations from unforeseen vulnerabilities.

Known Bugs

List anything already identified internally, even minor issues the team has not yet gotten around to fixing. Auditors need the complete picture, not just the problems the team feels comfortable sharing.

Accepted Design Risks

Explain clearly why the team intentionally accepts certain risks rather than eliminating them from the system design. Context around intentional tradeoffs helps auditors evaluate whether that reasoning genuinely holds up.

External Dependency Risks

Document assumptions about third-party systems your contracts rely on, including what happens if those systems fail. These external risks often sit outside your direct control but still affect overall system safety.

Features Not Yet Implemented

Make clear what functionality is intentionally incomplete, so auditors do not mistake missing features for unintentional bugs. This prevents wasted time investigating something the team already knows is unfinished.

Previous Security Findings

Provide previous audits, bug bounty findings, internal security findings, and their current remediation status to the audit team. Previous findings often reveal patterns worth checking again in the current codebase.

Prepare the Smart Contract Audit Package

Give auditors a full package of code, scope, documentation, testing evidence, known risks, dependencies and deployment information.

Freeze the Code Before the Audit Starts

Freeze the reviewed code at a specific commit so auditors and developers work from the same version throughout the security engagement.

Create the Audit Release Candidate

Identify the exact version being reviewed clearly, so there is never confusion about which code the findings actually apply to. This release candidate becomes the fixed reference point for the entire engagement.

Record the Final Commit

Use a fixed commit or tag instead of an evolving branch during the audit. Recording this reference ensures auditors and developers remain aligned on the exact code version under review.

Stop Unplanned Feature Changes

Avoid moving the audit target by introducing new features while the review is still actively underway. Unplanned changes risk invalidating findings or introducing new, unreviewed risk mid-engagement.

Define How Mid-Audit Changes Will Be Handled

If a change becomes genuinely necessary, notify the auditor, provide a diff, record the new commit, and determine whether re-review is needed. This structured process avoids silent, undocumented drift from the original scope.

What to Do During the Security Audit

Clear communication and timely responses help auditors resolve the technical questions quickly and keep things moving through the security review.

Assign a Technical Contact

This person should understand the architecture, business logic, build process, tests, integrations, and deployment procedures thoroughly. A knowledgeable contact prevents unnecessary delays caused by unanswered technical questions.

Answer Auditor Questions Quickly

Unanswered behavior questions can genuinely slow the entire review, especially when auditors are blocked waiting for clarification. Fast, clear answers keep the audit moving at a reasonable pace throughout.

Keep the Audit Scope Stable

Avoid unrelated feature development happening inside the same branch currently being audited by the review team. Scope creep during an active audit creates confusion about what was genuinely reviewed.

Track Questions and Findings

Maintain one clear, shared record of questions and findings rather than letting them scatter across multiple separate channels. A single source of truth prevents important details from quietly getting lost.

What to Do After the Audit

When you get the report, go through the findings systematically, check the remediation, add regression tests, and make sure the final release matches the code that was reviewed.

Review the Findings

Understand both the specific issue and its underlying root cause before attempting to implement any kind of fix. Treating symptoms without understanding causes often leaves the real problem unresolved.

Fix the Root Cause

Avoid superficial patches that leave the actual underlying design issue unresolved beneath a surface-level fix. A proper fix addresses why the vulnerability existed, not just its immediate visible symptom.

Add Regression Tests

For each meaningful finding, there should ideally be a test that will prevent the same issue from silently creeping back in later. Regression tests turn a one-time fix into a permanent, verified safeguard going forward.

Re-Test Related Contracts

A single fix can affect other components in ways that are not always immediately obvious during initial review. Re-testing surrounding functionality catches unintended side effects before they reach production.

Send Fixes for Auditor Review

Where remediation review is included in the engagement, send fixes back to the original auditor for confirmation. This closes the loop and confirms the fix genuinely resolves the identified issue correctly.

Freeze the Final Release Candidate

Make sure the production build still corresponds exactly to the reviewed and remediated code before any deployment occurs. Any drift between the audited version and the deployed version undermines the entire audit's value.

Smart Contract Pre-Audit Checklist

Use this final checklist to confirm the codebase, documentation, testing, deployment process, and audit materials are ready for external review.

• Scope: Repository selected, fixed commit, contracts and scripts, exclusions, network, build settings.
• Documentation: Full system overview, user flows documented, architecture diagram available, dependencies documented, clear explanation of upgrade model
• Roles and permissions:Privileged roles listed, permission matrix created, multisigs documented, timelocks documented, emergency controls tested thoroughly.
• Invariants and risks: Core invariants are defined, economic assumptions are documented, trust assumptions are recorded, and known risks are openly disclosed.
• Code quality: reviewed compiler warnings, removed dead code, fixed TODO and FIXME items, pinned dependencies, documented changed libraries.
• Testing: Unit tests passing, integration tests passing, fork tests used where relevant, fuzz tests used where appropriate, invariants tested, edge cases tested, coverage reviewed.
• Security tools: Static analysis done, findings triaged, clearly documented accepted risks.
• Deployment and upgrades: Deployment scripts tested, Initializers tested, Upgrade flow tested, Storage compatibility reviewed, Role handover tested
• Reproducibility: New clone builds, test instructions work, tool versions well documented.
• Audit package: Scope package complete, known issues disclosed, previous audits included, technical contact assigned, audit commit frozen.

Common Smart Contract Audit Preparation Mistakes

Avoiding these common preparation mistakes can reduce unnecessary delays and help auditors spend more time analyzing meaningful security risks.

Auditing Code That Is Still Changing

Sending code that keeps changing during review turns findings stale quickly and wastes significant auditor time overall. A stable release candidate should always exist before the engagement formally begins.

Sending a Repository Without a Clear Scope

Vague scope forces auditors to guess which files genuinely matter, wasting time that should go toward real security analysis. Clear scope definition should always happen before any handoff occurs.

Poor or Missing Documentation

Without documentation, auditors must reverse engineer intent from code alone, which slows review and increases the chance of missed context. Good documentation saves meaningful time throughout the entire engagement.

Treating the Audit as the First Security Review

An audit should follow internal review and thorough testing, not substitute for them as the project's only security check. Relying solely on an external audit wastes its value on basic, avoidable issues.

Testing Only the Happy Path

Testing only the expected, successful scenarios will not uncover the failure conditions and edge cases where serious vulnerabilities usually reside. Adversarial and negative testing should be equally considered before handoff.

Relying Only on Code Coverage

High coverage numbers can give a false confidence of security while logical and economic flaws remain completely undetected. Coverage should complement, not replace, genuinely thoughtful test design.

Ignoring Deployment and Upgrade Scripts

Deployment and upgrade scripts are risky in their own right and therefore deserve just as much testing as the core contract logic. Ignoring them can undermine even a perfectly audited codebase.

Hiding Known Risks

Concealing known issues from auditors defeats the purpose of the review and can leave genuine risks completely unaddressed. Full disclosure always produces a more useful audit outcome.

Leaving Dependencies Unpinned

Floating dependency versions can quietly change behavior between development, audit, and deployment, creating inconsistent and unpredictable results. Pinning versions removes this entirely avoidable source of risk.

Changing Code Without Informing the Auditor

Silent changes during an active audit can invalidate findings or introduce new, unreviewed risk without anyone's immediate knowledge. Always notify the auditor before making any mid-audit changes.

Treating an Audit as a Security Guarantee

Passing an audit never means a contract is completely free of every possible vulnerability under every circumstance. Audits meaningfully reduce risk, but they never eliminate it.

How Long Does It Take to Prepare for a Smart Contract Audit?

There is no single universal timeline, since preparation time depends heavily on several genuinely variable factors. Number of contracts, size of codebase, maturity of documentation, maturity of testing, complexity of the protocol, integrations, upgradeability, and unsolved bugs and such impact the overall timeline.

Previous security work also matters a lot, as a project that has had previous audits generally needs less foundational work. A mature protocol may only need to have its scope finalised, its reproducibility checked, and its handoff prepared before the engagement begins.

An immature codebase may need significant additional development and testing before an external audit genuinely makes sense. Businesses planning this timeline alongside budget should review smart contract development cost for realistic estimates across different project types.

Conclusion

A smart contract is ready for an external security audit when reviewers can understand the system and identify its scope clearly. They should be able to reproduce the code, evaluate the risk model, run the tests, and inspect real security evidence. Good preparation does not make the audit easier by hiding problems from the reviewing team. It removes avoidable noise so auditors can focus on the hardest problems, including business logic, permissions, economics, and unexpected interactions.