The audit report is the artifact everyone reads. The scope document is the artifact that determines whether the report means anything. Yet scope documents remain chronically underspecified across the industry: a GitHub link, a commit hash, and a brief description of what the protocol does. That is a starting point, not a scope.
This article is written for two audiences simultaneously — protocol teams preparing to submit code for review, and auditors structuring an engagement. Both parties sign up to the scope document. Both parties suffer when it is wrong.
Why the Scope Document Is a Legal and Technical Instrument
Before examining what belongs in a scope document, it is worth being precise about what the document actually is. It is not a preliminary form or an administrative convenience. It is the foundational instrument that defines the boundaries of the auditor’s professional obligations and the protocol team’s disclosures.
The engagement letter describes the limitations of the audit and should include its terms and conditions. Like any contract, engagement letters are used to mitigate risk related to the business arrangement and the relationship between the parties, including the risk of misunderstandings.
In smart contract security, the stakes of misunderstanding are unusually high. Once a smart contract goes live on a blockchain, it can be accessed by everyone — and unfortunately this includes malicious actors who will try to take advantage of any vulnerabilities for financial gain. On a public blockchain, such exploits or hacks cannot be reversed, leading to financial and reputational loss not only for the project but also for users of the protocol.
The scope document does not eliminate that risk. What it does is clearly allocate it. When a vulnerability is found in a contract that was not listed in scope, the audit report cannot be blamed. When a vulnerability is found in a contract that was listed in scope and missed, the parties need an agreed record of what was reviewed to have any productive conversation about what happened.
A well-defined scope helps auditors establish clear objectives and outcomes for the engagement. Stakeholders understand what will be assessed, the methods to be used, and the expected deliverables. This clarity reduces misunderstandings, aligns all parties on goals, and ensures the audit process remains focused, structured, and results-oriented.
What Belongs in a Scope Document
A complete audit scope document for a smart contract engagement is not a list of file paths. It is a structured disclosure covering the system, its context, its threat environment, and the terms under which it will be reviewed. The following sections are the minimum viable set.
1. Repository Reference and Commit Hash
The most mechanically important element of any scope document is the precise code reference. A good starting point for defining an audit’s scope is the repository details, where auditors should know the specific branch and commit hash and the file path(s) leading to the contracts intended for the audit. This ensures that the auditors’ time is not wasted searching for the target, and their efforts are constrained to the in-scope components in the correct version.
This is not optional precision. If the commit hash is missing, the scope document describes an intention, not a specific system. Different commits can behave entirely differently. The audit report is only meaningful relative to a fixed state of the code.
The protocol team should provide:
- Repository URL (with NDA process confirmed if the repo is private)
- Branch name
- Exact commit hash (not a tag that can be moved)
- Explicit list of file paths that are in scope
- Explicit list of file paths that are excluded, even if they exist in the same repository
2. Protocol Description and Intended Behavior
Expected behavior should be clearly defined through functional requirements, flows, and constraints, providing a reliable baseline for findings. Smart contract security assessments are most effective when auditors can focus on security-critical logic — rather than reconstructing architecture, clarifying assumptions, or resolving build issues.
The description should not be a marketing summary. It should answer: what does each in-scope contract do, who calls it, what assets does it hold, and what are the invariants that must never be violated?
Security invariants are properties that must always be true. Total token supply should never exceed the minted amount. User balances should never exceed their deposits. Auditors identify these invariants and test whether they can be violated under any scenario.
Protocol teams that document their invariants before audit submission materially improve the quality of findings. An auditor who is told what should never happen can look for conditions under which it does. An auditor who is not told must first deduce the intent before beginning the security analysis — consuming time that was scoped and priced for something else.
3. Explicit In-Scope Contract List
Every contract that is in scope must be named individually. A statement like “the protocol contracts” is not sufficient because it introduces interpretive ambiguity when a vulnerability is found in a peripheral contract that was not explicitly discussed.
Set clear objectives by specifying which code repositories, dependencies, and deployed networks require review. Outline whether the examination will focus on source code, bytecode, or both.
For each in-scope contract, the scope document should record:
- Contract name and file path
- Deployed address (if already deployed on testnet or mainnet)
- Lines of code (nSLOC, not total lines including whitespace and comments)
- Brief functional description
- Whether it is upgradeable and which proxy pattern it uses
4. Explicit Out-of-Scope List
The out-of-scope list is as important as the in-scope list, because it is the mechanism by which both parties accept known risk boundaries. Prepare a detailed matrix: explicitly exclude modules or contracts out of scope to avoid ambiguities.
The auditor and project team should agree on which contracts, libraries, and external dependencies will be examined. Clear boundaries should be set, as out-of-scope code is not guaranteed to be secure.
Common out-of-scope candidates include:
- Frontend and off-chain components
- Governance contracts in a governance-light deployment phase
- Third-party integrations and protocol adapters
- Test files and deployment scripts
- Contracts already audited by another firm in a prior engagement
The out-of-scope section should not simply list these things. It should briefly acknowledge the risk created by each exclusion. If the audit does not cover all code in the repository, such as a governance component, this must be explicitly stated. Contracts outside the audit scope may introduce vulnerabilities, potentially impacting the overall security due to the interconnected nature of smart contracts.
Dependency Handling
Dependency handling is one of the most frequently mismanaged aspects of scope definition, and one of the most consequential. Smart contract protocols do not exist in isolation. They inherit from libraries, integrate with external protocols, and call into contracts they do not control.
All external integrations should be enumerated, including oracles, third-party libraries, and upgradeable proxy patterns.
The scope document must take an explicit position on each dependency category:
Inherited library code (e.g., OpenZeppelin): If a contract inherits from OpenZeppelin Contracts — the most audited library in the industry — and only adds minimal logic, risk concentrates in the custom code. That reduces the scope of the audit needed. The scope document should state whether inherited library code is in scope and, if not, confirm which version is being used and whether it has been audited.
Third-party protocol integrations: When a protocol calls into an oracle, a lending market, a DEX, or any external contract it does not own, the behavior of that external system should be treated as a trust assumption. The documentation should clearly and precisely define all trust boundaries in the contract — trusted relations with other contracts and significant data flows. If those integrations are not being reviewed, the scope document must describe what assumptions are being made about their correctness and behavior.
Unaudited external libraries: If the project utilizes libraries or contracts without security audits, this potentially introduces vulnerabilities. This compromises the security of the audited system, making it susceptible to attacks exploiting these external weaknesses. The scope document should flag unaudited dependencies explicitly and the protocol team should be prepared to justify the decision to rely on them.
Off-chain components affecting on-chain state: Any off-chain processes impacting on-chain interactions should be documented. Keeper bots, oracle feeds, price update scripts, and admin multisigs are all off-chain components that can determine whether on-chain logic is exploitable. If they are not in scope, the assumptions they create need to be recorded.
Architecture Documentation
Architecture documentation is the context layer that converts a list of contracts into an understandable system. Without it, auditors spend a significant portion of their available time on archaeology — reading code to understand what it does before they can begin evaluating whether it is secure.
Before auditors start their work, provide them with succinct but sufficient documentation covering the system design. The key artifacts are:
System architecture diagram: A visual representation of how contracts interact, what external systems they depend on, and what entities (users, administrators, protocols) interact with them. This does not need to be a formal UML diagram; a well-drawn flowchart serves the same function.
Data flow documentation: Auditors should gather relevant documentation about the blockchain auditing targets and their key components. This documentation may include smart contract specifications, architecture diagrams, security policies and procedures, and more.
Access control matrix: Obtain a permissions matrix identifying operator roles, privileged accounts, and any upgradeability mechanisms. In practice, this means mapping every privileged function — onlyOwner, onlyGovernance, onlyOperator — to the address or multisig that holds that role, and describing what each role can do.
Test suite: 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.
The protocol team should provide test coverage reports alongside the scope document. A solid testing suite allows auditors to focus on higher-risk areas instead of validating basic functionality. It also helps uncover issues earlier and reduces overall audit time.
Threat Model Inputs
A threat model is not a security finding — it is a structured statement about who the attacker is, what they want, and what means they have available. It belongs in the scope document because it calibrates the depth and direction of the audit.
Threat modeling is the process of identifying, classifying, and mitigating threats to your system. It focuses on finding and prioritizing potential vulnerabilities before they can be exploited, helping to develop secure foundations and maintain trust among users and investors.
Protocol teams that include threat model inputs in their scope document should address:
Actor enumeration: Who interacts with the system? Regular users, liquidity providers, governance participants, administrators, third-party integrators, and potential adversaries all have different capabilities. Auditors build a structured model of all actors who interact with the contract, what each actor wants, and what happens if a malicious actor controls any single component of the system. This shapes where review effort is concentrated.
Trust assumptions: Which actors are trusted, conditionally trusted, or adversarial? Is the admin key held by a multisig, an EOA, or a timelock? Is the oracle feed assumed to be correct, or is manipulation resistance part of the security requirement?
Known concern areas: Throughout the codebase, there may be regions that raise concerns. These could be areas that contain complex logic, novel techniques, or where issues have surfaced during development or testing. Protocol teams should point auditors toward these areas explicitly rather than waiting for them to be discovered.
Attack vector priorities: Determine explicit priorities for business-critical components and functionalities that handle large transaction volumes or sensitive user funds. Not all functions carry equal risk. A function that moves user funds deserves more scrutiny than a view function that reports balances.
Request the complete specification or whitepaper documenting intended system behaviors, business logic, and critical edge cases. Insist on an updated threat model, outlining anticipated attack vectors and established trust boundaries.
When threat model inputs are absent, auditors must construct them from scratch — which is not only inefficient but guarantees that the threat model will be less accurate than one built by the team that designed the system.
Timeline Commitments and What Happens When They Slip
Timelines in audit engagements carry more weight than in most software engagements because audit time is a fixed resource, not a queue. When a firm commits two senior engineers for three weeks starting on a specific date, those engineers are not available for other engagements during that period. A protocol team that misses its readiness deadline imposes a real cost on the firm — and may invalidate the audit scope entirely.
Complex protocols usually require 150 to 250 expert hours, translating to 4 to 6 weeks from kickoff to final sign-off.
It is strongly recommended to start engaging with audit companies as early as possible, with a reasonable lead time before the audit is scheduled to start. Scoping can be done with code developed to a reasonable level of completion — approximately 85 to 90 percent complete — so it is better to establish a communications channel ahead of time.
The scope document should record the following timeline elements:
Code freeze date: The date after which no changes will be made to in-scope contracts without a formal scope change request. A code freeze is the practice of halting non-critical changes during an audit so reviewers work against a stable, consistent version of the codebase. A clear code freeze reduces rework and ensures findings remain relevant throughout the audit.
Audit start date: The date on which auditors will begin their review, contingent on receipt of all required materials.
Interim check-in schedule: During audit, it helps to be in synchronous communication with developers, as needed. This helps in getting quick clarification on unclear topics, in preventing misunderstandings as early as possible, and in offering the development team continuous feedback, especially on crucial issues.
Report delivery date: The expected date of the initial findings report.
Remediation window: Time allocated for the protocol team to address findings before a fix review.
Fix review date: The date on which auditors will re-examine patched contracts.
When Timelines Slip
Timeline slips happen in three directions: the protocol team is not ready, the codebase expands during the audit, or findings are more complex than anticipated.
Protocol team not ready: If the protocol team cannot deliver a frozen, documented codebase by the agreed date, the audit should not begin. An audit conducted against an incomplete, unstable codebase produces findings that may be invalidated by subsequent changes. Freezing the code may seem counterintuitive to teams used to fast-paced development cycles. However, it is crucial for the integrity of the audit process. It reduces the risk of missing or reintroducing previously detected vulnerabilities.
The scope document should include a protocol for a delayed start: whether the audit slot can be preserved with a short delay, what the rescheduling terms are, and who bears the cost of the disruption.
Codebase expansion during audit: If new contracts are added, or if significant changes are made to in-scope contracts during the audit window, the scope has changed. If, by the time the project starts, you request auditing of a larger project than originally scoped, the auditing firm will communicate the difference in advance, assuming they have the time capacity to audit it.
Complexity greater than anticipated: Audit time is estimated from code complexity metrics. If the internal logic proves significantly more complex than the code metrics suggested, the audit cannot be completed to the same standard within the original time budget. The scope document should define how this situation is flagged and resolved.
Scope Change Procedures
Scope changes are inevitable in active development environments. The problem is not that scope changes happen — it is that they frequently happen without a formal procedure, leaving both parties in an undefined position.
The scope document should establish a scope change procedure covering:
Trigger definition: What constitutes a scope change? Any addition or removal of in-scope contracts, any change to the commit hash that is under review, any addition of a dependency that was previously excluded, and any expansion of the audit timeline or deliverables should all constitute formal scope changes.
Notification requirement: Scope changes must be communicated in writing by an authorized representative of the protocol team. Verbal agreements, chat messages, or informal understandings are not sufficient because they cannot be reliably referenced if a dispute arises later.
Impact assessment: When a scope change is proposed, the auditor should provide an impact assessment covering time, cost, and timeline implications before accepting it. The engagement process should include a process for scope adjustments and associated incremental fees.
Formal acceptance: Scope changes should be accepted in writing by both parties before work on the expanded or modified scope begins. This protects the auditor from being expected to cover new ground without additional time, and it protects the protocol team from assuming coverage they have not formally confirmed.
Version control of the scope document: Every accepted scope change should produce a new version of the scope document with a change log. At the conclusion of the engagement, the final scope document should accurately reflect what was reviewed.
Regularly review and update specifications to reflect changes in project scope or requirements. This discipline, applied to the scope document itself, ensures that the audit report references a scope that actually matches what was reviewed.
How a Poorly Defined Scope Creates Liability for Both Parties
The liability implications of a poorly scoped audit run in both directions, and both parties tend to underestimate their exposure.
Liability for Protocol Teams
A protocol team that deploys on the basis of an audit report without understanding what that audit actually covered is making a claim to users that may not be accurate. While an audit can enhance project quality and security, the development team bears the ultimate responsibility for ensuring high quality.
When a protocol is exploited through a contract that was not in scope — a governance contract, an oracle adapter, a staking module added after the audit — the audit report provides no protection. The audit did not cover that contract. Users who relied on the existence of the audit report as a security signal have a legitimate grievance, but the fault lies with the protocol team’s failure to scope the audit correctly, not with the auditors.
Audits dramatically lower risk, but novel attack vectors or out-of-scope integrations can still pose threats, as the 2022 Nomad Bridge hack demonstrated.
A poorly scoped audit can also create false confidence internally. Protocol teams that treat the audit report as a security clearance rather than a bounded assessment of specific code are more likely to add post-audit changes without appropriate review, more likely to underinvest in monitoring and incident response, and more likely to be surprised when something goes wrong.
Liability for Auditors
Auditors face a symmetric problem. If the scope document is vague, the auditor has implicitly agreed to be responsible for whatever a reasonable person might assume was covered. A scope document that says “the lending protocol” without enumerating specific contracts could be interpreted to include the oracle adapters, the liquidation bots, and the governance mechanisms — none of which the auditor may have reviewed.
Establishing the scope of the audit before commencing the process is critical. Auditors will have difficulty concentrating on the key areas without information on what code to cover, how complex it is, and what to focus on.
When an auditor signs a report against a vague scope and a vulnerability is later found in an adjacent contract, the question of whether that contract was implicitly in scope is a legal question, not a technical one. The auditor’s best defense is a scope document that is unambiguous about what was and was not reviewed.
Defining a scope not only sets the expectations and outlines the areas of focus but also fosters an open dialogue that can significantly improve the efficiency of the overall audit process.
Auditors should also be aware that accepting scope additions without formalizing them — as commonly happens when protocol teams informally ask “can you also look at this contract?” — creates liability for a review that was not planned, scoped, or properly resourced. The audit report must accurately reflect the scope that was actually covered. Informal additions that are not documented cannot be reliably included in that record.
The Shared Accountability Problem
The most dangerous audit engagements are those where both parties have incentives to let the scope remain vague. Protocol teams may prefer a broad-sounding scope to support marketing claims. Auditors may prefer a vague scope to avoid being held to precise commitments. The result is an audit report that neither party can fully interpret and that provides inadequate protection to either.
Audit readiness is not administrative overhead. It is a practical part of security engineering that directly affects the quality and efficiency of a review. When requirements are testable, architecture is documented, environments are reproducible, and the codebase is stable, auditors can focus on what matters most: deep analysis of logic, trust assumptions, and potential exploit paths.
The scope document is the mechanism through which shared accountability is established honestly.
Post-Audit: Scope as a Living Reference
The scope document does not become irrelevant once the audit concludes. It serves as the reference point for three ongoing activities:
Fix verification: After the initial audit, it is best practice to schedule a retesting phase to verify the implemented fixes and assess their impact on the system. The fix review should be conducted against the same scope as the original audit, with any patched code clearly identified as new commits relative to the original.
Subsequent audit planning: If the protocol launches new modules, integrates new dependencies, or substantially modifies existing contracts, the historical scope document establishes what was previously reviewed. New audit scopes should reference this record explicitly to avoid both gaps and redundant coverage.
Public disclosure: Once any identified vulnerabilities are rectified, the client may choose to make the audit report public in order to demonstrate the project’s commitment to security. A public audit report without an accompanying scope statement is nearly uninterpretable to the community members trying to evaluate protocol security. The scope document — or at minimum a clear scope summary — should accompany any published report.
Scope Document Template
The following template is designed for both protocol teams preparing a submission and auditors reviewing one. All fields are mandatory. Blank fields should be explicitly marked as “Not applicable” with a justification — they should never simply be left empty.
AUDIT SCOPE DOCUMENT
Version: [1.0]
Date: [YYYY-MM-DD]
Protocol Team Contact: [Name, Role, Email]
Audit Firm Contact: [Name, Role, Email]Section 1: Engagement Overview
| Field | Value |
|---|---|
| Protocol name | |
| Protocol category | (e.g., Lending, DEX, Bridge, Staking, Governance) |
| Blockchain(s) | |
| Audit type | (Security review / Threat model / Formal verification / Fix review) |
| Engagement lead (auditor) | |
| Engagement lead (protocol) | |
| Confidentiality | (Public / NDA required) |
Section 2: Code Reference
| Field | Value |
|---|---|
| Repository URL | |
| Branch | |
| Commit hash | |
| Total nSLOC (in scope) | |
| Build environment | (e.g., Foundry 0.x, Hardhat 2.x, Node 20) |
| Compiler version | |
| Test framework | |
| Test coverage (branch) |
Section 3: In-Scope Contracts
For each in-scope contract, complete one row of the following table:
| Contract Name | File Path | nSLOC | Deployed Address | Proxy Pattern | Brief Description |
|---|---|---|---|---|---|
Known concern areas within in-scope contracts:
List any specific functions, modules, or logic paths that the protocol team believes warrant elevated scrutiny. Include any functions where issues surfaced during internal review or testing.
Section 4: Out-of-Scope Contracts and Components
| Item | Type | Reason Excluded | Acknowledged Risk |
|---|---|---|---|
| (Contract / Library / Frontend / Oracle / Bot) |
Every exclusion must carry an acknowledged risk statement. “We accept that [item] has not been reviewed and that vulnerabilities in [item] may affect the security of the in-scope system” is the minimum acknowledgment.
Section 5: Dependencies
| Dependency | Version | Audited? | Audit Firm / Date | Trust Assumption |
|---|---|---|---|---|
| OpenZeppelin Contracts | Yes | Multiple | Inherited, not re-reviewed | |
| [External protocol integration] | ||||
| [Oracle] |
Trust boundary summary:
Describe explicitly which external systems are treated as trusted by the in-scope contracts, and under what conditions. Example: “The Chainlink ETH/USD feed is trusted to return a value within ±5% of spot price within a 1-hour update window. Manipulation of this feed is out of scope.”
Section 6: Protocol and System Description
Protocol purpose:
2–4 sentences describing what the protocol does and what value it provides to users.
Architecture narrative:
Describe how the in-scope contracts interact with each other and with external systems. Attach or link to a system architecture diagram.
Security invariants:
List the invariants that must hold at all times. Example:
- Total deposits must always equal or exceed total liabilities
- Only accounts with the ADMIN_ROLE may call
setOracle()- The total supply of the synthetic asset must never exceed the collateral value denominated in the base asset
Access control summary:
| Role | Capabilities | Held by | Mechanism |
|---|---|---|---|
| Owner | (EOA / 2-of-3 Multisig / 4-of-7 Multisig / Timelock) | ||
| Admin | |||
| Operator | |||
| Governance |
Section 7: Threat Model Inputs
Actor definitions:
| Actor | Description | Trust Level | Capabilities |
|---|---|---|---|
| Regular user | Untrusted | ||
| Liquidity provider | Untrusted | ||
| Admin | Trusted | ||
| External protocol | Conditionally trusted | ||
| Adversary | Untrusted | Flash loan access, MEV |
Anticipated attack vectors:
List the attack vectors the protocol team considers most plausible. This is not an exhaustive list — it is a starting point for the auditor’s threat analysis.
Previously identified concerns:
List any vulnerabilities or near-misses identified during development, internal review, or testing, along with the mitigations applied.
Out-of-scope attack assumptions:
State explicitly which attack vectors are accepted as out of scope. Example: “Compromise of the admin multisig private keys is out of scope. Governance attacks requiring a supermajority vote are out of scope during this engagement phase.”
Section 8: Timeline
| Milestone | Date | Owner |
|---|---|---|
| Scope document finalized and signed | Both | |
| Code freeze | Protocol team | |
| All documentation delivered | Protocol team | |
| Audit kickoff | Audit firm | |
| Mid-audit check-in | Both | |
| Initial report delivered | Audit firm | |
| Protocol team remediation complete | Protocol team | |
| Fix review begins | Audit firm | |
| Final report delivered | Audit firm | |
| Public disclosure (if applicable) | Protocol team |
Timeline slip protocol:
If the protocol team cannot meet the code freeze date: [define notification requirement, e.g., “7 calendar days written notice to the audit firm contact above”].
If the audit firm cannot meet the report delivery date: [define notification requirement and credit or rescheduling terms].
A slip of more than [X] calendar days constitutes grounds for rescheduling the engagement at no penalty to the requesting party, subject to availability.
Section 9: Scope Change Procedure
Any of the following constitutes a scope change and requires a new signed scope change addendum before work proceeds:
- Addition or removal of any in-scope contract
- Change to the commit hash under review (outside of agreed fix review cycles)
- Addition of a dependency not listed in Section 5
- Expansion or contraction of the timeline
- Change in deliverable format or depth
Scope change request process:
- Requesting party submits written scope change request to both contacts above.
- Audit firm provides written impact assessment within [X] business days.
- Both parties sign a scope change addendum before work proceeds.
- Scope document is updated to version [n+1] with change log entry.
Section 10: Deliverables and Limitations
Deliverables included in this engagement:
- Initial findings report (severity-classified, with reproduction steps)
- Executive summary suitable for public disclosure
- Fix review of remediated issues
- Final report reflecting post-remediation status
- Architecture observations (informational, not findings)
Explicit limitations:
This audit covers the contracts and versions specified in Sections 2 and 3 as of the commit hash above. It does not constitute a guarantee of security. It does not cover the items listed in Section 4. It does not evaluate the economic model, tokenomics, or governance design except where they directly affect the security of in-scope code.
An audit cannot find all vulnerabilities. Time-bounded review conducted by human experts provides reasonable assurance, not certainty.
Section 11: Signatures
| Party | Name | Role | Signature | Date |
|---|---|---|---|---|
| Protocol team | ||||
| Audit firm |
Conclusion
The scope document is not bureaucratic overhead. It is the foundation of the audit’s validity. A report that cannot be clearly mapped to a defined, agreed, and signed scope is an opinion, not an assessment. Protocol teams that invest in producing a thorough scope document arrive at the audit start date faster, receive higher-quality findings, and have a cleaner basis for public disclosure. Auditors who insist on a proper scope document protect themselves from ambiguous obligations and produce work they can stand behind.
The field has a persistent cultural bias toward treating the code as the primary artifact and the documentation as a secondary concern. In audit engagements, that priority is backwards. The code without a scope is a collection of files. The scope document makes it an audited system.