A smart contract brief is a written specification that tells developers and auditors exactly what the contracts must do, on which chain, under whose control and with which deliverables. It is the document you send with a request for proposal (RFP), and it determines the quality of every quote you receive. A good brief covers context, roles, functional rules, parameters, integrations, administrative powers, non-functional requirements, tests, audit expectations, timeline and budget. This guide explains each section, the gaps most often left open and how a precise brief makes quotes comparable.
Why a brief matters
A brief matters because vendors can only price and plan what they understand, and in smart contracts every unstated assumption becomes either a cost overrun or a security risk. Without a written specification, each developer fills the gaps differently, and you receive quotes that describe different projects.
A brief serves four purposes at once:
- Pricing. It gives every vendor the same basis for estimating effort.
- Contracting. It becomes the reference for what is included in the engagement and what counts as a change request.
- Development. It guides design choices and the tests that prove the contracts behave as intended.
- Audit. It tells auditors what the code is supposed to do. Auditors look for differences between intended and actual behavior, so a missing specification limits what they can verify.
A brief is not a technical design document. You describe the behavior, the rules and the constraints; the developers propose the architecture. You do not need to write code to write a good brief, but you do need to make decisions.
What a smart contract brief must contain
A complete brief answers twelve questions, grouped below in the order vendors usually read them. Short answers are fine; missing answers are not.
1. Context and objectives
Describe the project in a few paragraphs: what problem it solves, for whom, and why it needs a smart contract rather than a conventional system. State the business objective (launch a token, open a lending market, tokenize a fund) and what success looks like at launch.
2. Users and roles
List every type of actor and what each can do. Typical roles include end users, token holders, an owner or administrator, operators (for example a price updater or a compliance officer), and other contracts. For each role, specify who holds it at launch and whether it can be transferred.
3. Functional requirements
Write the rules as precise statements: "A user can stake tokens at any time; rewards accrue per second; withdrawal is possible after a 7-day lock." Cover the normal flow, then the exceptions: what happens when a balance is zero, when a deadline passes, when a transfer is refused. Numbered requirements make later discussion and testing much easier.
4. Token economics or parameters
List every number the contracts depend on: total supply, decimals, minting and burning rules, fees and their recipients, vesting schedules, interest rate models, collateral ratios, limits and caps. For each parameter, say whether it is fixed at deployment or adjustable later, and by whom.
5. Target chain and standards
Name the blockchain (or blockchains) and the standards to follow, such as ERC-20, ERC-721 or ERC-1155 on EVM chains. The chain affects the language, the tooling, the available auditors and the cost. If you are undecided, say so and ask vendors to recommend one with their reasons.
6. Integrations
List every external system the contracts rely on: price oracles, other protocols, bridges, wallets, a back end or indexer, identity or compliance providers. Each integration adds assumptions about behavior and failure that must be specified and tested.
7. Administrative powers and upgradeability
State what the administrator can change, pause or withdraw, and how those powers are protected. Will the contracts be upgradeable through a proxy, or immutable? Will admin actions go through a multisig wallet and a timelock? Is there an emergency pause, and who can lift it? This section is often the one users and auditors examine most closely, because it defines how much trust the system requires.
8. Non-functional requirements
Include gas efficiency targets if they matter, compatibility constraints (compiler version, library choices such as well-known open-source implementations), code style, documentation standards (for example NatSpec comments on public functions) and any regulatory constraints such as transfer restrictions or investor whitelists.
9. Deliverables
List what you expect to receive: source code in a repository you control, deployment scripts, technical documentation, a test suite with coverage report, deployment on a testnet, then mainnet, and, if relevant, a web front end or back end. State the license and ownership of the code.
10. Tests
Specify the minimum testing expected: unit tests for every function, integration tests for full user journeys, and, for complex financial logic, fuzzing and invariant tests (properties that must always hold, such as "total deposits equal the sum of user balances"). Ask for the coverage level you expect and for tests to run automatically.
11. Audit expectations
State that the code will be audited by an independent firm that did not develop it, and what that implies for developers: a code freeze on a tagged commit, documentation handed to auditors, availability to answer questions, and time to fix findings before a re-audit. Define the expected audit scope if you already know it. Remember that an audit reduces risk but does not guarantee the absence of bugs.
12. Timeline and budget
Give your target dates (testnet, audit start, mainnet launch) and a budget range. A budget range does not weaken your negotiating position; it helps vendors propose a realistic scope instead of guessing. Plan the audit budget separately, on top of development.
Common gaps in smart contract briefs
The most common gaps are the ones that seem obvious to the client and are therefore never written down. The table below lists those that most often cause diverging quotes or audit findings.
| Gap | Why it causes problems |
|---|---|
| Admin powers left vague | Vendors assume different control models; auditors cannot judge whether a power is intended |
| Parameters "to be defined" | Effort cannot be estimated, and late changes affect code already tested |
| Edge cases ignored | Zero balances, rounding, paused states and expired deadlines are where many bugs live |
| No test expectations | Quotes vary widely in quality, and weak tests raise the cost of the audit |
| Upgradeability undecided | It changes the architecture, the deployment and the audit effort |
| Integrations unlisted | Each oracle or external protocol adds work and risk that no one priced |
| Audit not planned | The schedule leaves no time for the audit, the fixes and the re-audit |
| Front end not mentioned | Some quotes include it and others do not, which makes prices incomparable |
A useful test: give the brief to someone outside the project and ask them to explain what the contracts do and who controls them. Every question they ask points to a missing section.
How a good brief makes quotes comparable
A precise brief makes quotes comparable because every vendor prices the same scope, the same deliverables and the same assumptions, so differences in price reflect differences in approach rather than in interpretation.
To get the most out of it:
- Ask for a common quote format. Request the same fields from every vendor: price and currency, duration, team composition, detailed scope, assumptions, exclusions and what happens after the audit.
- Ask vendors to list their assumptions. Where the brief is silent, each vendor will make a choice. Making those choices visible lets you spot them and settle them.
- Keep one version. If you clarify a point for one vendor, share the clarification with all of them.
- Separate development and audit. Send the development brief to developers first. Once the code is ready, the same brief, updated with the final design, becomes the basis for audit quotes from independent auditors.
The guide on how to compare smart contract quotes explains how to read the answers once they arrive. To check whether a quote is in a plausible range before you negotiate, the development cost calculator applies the site's public model; its figures are indicative, and real quotes depend on the scope.
Writing the brief in practice
The fastest way to write a brief is to answer a structured questionnaire, then turn the answers into a document with numbered requirements. Most project owners can produce a first version in a few hours if the key decisions have already been made.
A practical sequence:
- Write the context and the list of roles first; they frame everything else.
- Draft the functional rules as short numbered statements, starting with the main user journey.
- Collect every parameter in one list, with its value or its range.
- Decide the administrative model and upgradeability before contacting vendors.
- Add deliverables, tests, audit expectations, timeline and budget.
- Have a technical person review the draft for contradictions and missing edge cases.
The brief generator follows this structure and produces a document you can send as an RFP. On smart-contract.com, the brief is also used to request quotes in a common format from developers, then from independent auditors who have no development engagement on the same project.
Key takeaways
- A smart contract brief specifies behavior, roles, parameters, control and deliverables; the developers propose the architecture.
- Administrative powers, upgradeability, parameters and edge cases are the sections most often missing and the ones that matter most for security.
- Test and audit expectations belong in the brief from the start, with time and budget for fixes and a re-audit.
- A common quote format and shared clarifications make quotes comparable, so price differences reflect approach, not interpretation.