A guide to writing smart contract specifications. ### Who this is for This document describes how to write smart contract specifications. These could be written both by smart contract engineers involved directly in the design process or by product managers and other executives writing documents to facilitate hand-off to engineering. A good smart contract specification can serve several purposes: - **Provide evidence that the smart contract is designed and implementation-ready.** Often smart contracts are designed at a high-level and then passed on to engineers who inevitably are forced to rework ideas for solidity, address user experience problems (especially when it comes to other protocol consumers) or even economic questions, - **Identify unknown risks in the design process**. By designing up front, difficult assumptions will surface earlier in the process allowing teams to mitigate or adapt, - **Allow granular issues to be assigned to developers**. A great specification will identify clear modules, contracts and functionality that facilitate the sub-division of work under a common language, - **Help auditors and other third-party contributors get up to speed with the contracts**. A specification is often the best entry point for learning a protocol and can reduce auditing costs, support community governance and other spill-over benefits. ### How do I design a smart contract Before you can write a specification, you need to design your protocol. ### Outline of a smart contract specification Here is a simple outline that you can use for any specifications. Not every specification needs all of these (and some are more appropriate for engineers and less for community facing specifications). **Context and problem definition** State clearly what problem the protocol or feature is designed to address and any design constraints (e.g., has to be effected without introducing any new smart contracts in an existing system, cannot add new storage, cannot break existing interfaces that 3rd party wallets may uses). Add related governance discussions if idea was originated politically. Discuss user personas of expected protocol consumers. **Related systems and case studies** Identify related resources and implementations that could be helpful: - Protocols solving similar problems or sub-problems, - Implementation tricks and ideas that could be relevant, - Third-party standards, tools and libraries that could be useful (e.g., template contract). **Terminology** Introduce any new terminology or clarify use of existing terminology as appopriate. **High-level summary of proposed solution** Discuss at a high-level how the implementation will work. This should include only the most important decisions and should use parallels as appropriate. **High-level modules or architecture** For more complex multi-contract solutions, an architecture diagram of all the contracts and how they interrelate. Can also illustrate asset flows. **Detailed specification** The detailed specification should clearly answer the following elements: - What contracts and functions are being introduced. How would they be consumed, - What third-party contracts and libraries are to be integrated, - What new storage and event types are being added to facilitate new functionality, - How it works. Where appropriate, it is useful to include pseudo-code or specific code fragments with gas-sensitive or storage-specific solutions. **Appendix** The appendix can provide additional clarity to the most common questions, such as: - What alternative designs were considered (this can significantly facilitate understanding), - What risks exist in this implementation, - Any formal proofs or detailed specifications for particularly sensitive parts, - Testing guidelines and testing paths. ### Tailoring the specification Writing the specification should be an art more than a science. Different audiences, objectives and complexities call for entirely different specifications. In the gallery below, you can see some examples of specifications that fit at different spectrums of the following trade-offs: - Implementation only vs. focus on problem/risks, - High-level description vs. formal/executable specification (formal here means in the mathematical sense that a program could be used to verify if an implementation adheres to the specification). ### How to know if the specification is ready Here are some questions you can ask to see if the specification is ready to be handed off: - Have you received feedback from several people about the specification and its clarity/legibility? - Has it been reviewed by an expert or original protocol author? - Do the most difficult open questions have precise solutions/explanations in the specification Could an engineer readily fill in the blanks? - Have key naming decisions (for functions, storage variables) been made consistently with both existing contracts and prevalent industry terminology or are they passed on to engineers? - Is the specification clearly structured? ### Examples of specifications (varying from very high-level to very low-level) [](https://github.com/compound-finance/compound-protocol/blob/master/docs/CompoundProtocol.pdf) The original high-level Compound specification. Excellent example of how to detail functions [Protocol Overview](https://docs.aave.com/developers/the-core-protocol/protocol-overview) AAVE documentation site [Dai Stablecoin Purple Paper](http://web.archive.org/web/20200516101314/https://makerdao.com/purple/) MakerDAO original formal specification ("purple paper"). Very low-level example of a formal spec [Concentrated Liquidity | Uniswap](https://docs.uniswap.org/concepts/V3-overview/concentrated-liquidity) High-level explanation of Uniswap V3 concentrated liquidity concept [Overview](https://docs.tokensets.com/) Good discussion of user roles in the Set protocol [Litepaper](https://docs.tokensets.com/protocol/litepaper) Example lite paper