The DeFi Developer’s Guide to Achieving Successful Transparency — Part 1
This is the first article of a series going in depth on how developer’s in the DeFi space can instill confidence in their users. Learn how to build trust and transparency using DeFi Safety’s clear and comprehensive guidelines.
What is DeFi Safety?
We are an organization focused on improving the blockchain ecosystem by conducting independent reviews on DeFi projects using our own rigorous, transparent and well documented process. We are not financially incentivized by projects to do our reviews. We truly believe that by giving developers clear transparency standards we can improve the quality of Decentralized Finance as a whole.
Why is Transparency Important?
Transparency is important for users and developers because it allows both parties to review information, make informed decisions and signal any exploitable problems on a Decentralized Application. With public information, especially regarding smart contracts, a user (with perhaps some Solidity knowledge) can read and understand what your protocol does, and if it’s working as it should be. Integrating transparent practices will make your code stronger, your development and testing more robust and users more inclined to invest in your project. With transparency, everybody wins.
The “EASY” Guide
There are eight criteria points relating to DeFi Safety’s public review process that are covered in this article. These eight points are the easiest for a project to fully achieve according to their review process. This is the bare minimum you, as a project manager or developer should shoot for on the path to Successful Transparency.
We will clarify how each criteria impacts the scoring system and grading metrics that we use to review a project or protocol. Grades can either be represented as a percent (%) of completeness or as a simple yes or no (Y/N). The Overall Score Impact is the percent value each question is worth as a part of DeFi Safety’s complete review process.
Let’s dive in.
Are the executing code addresses readily available?
Overall Score Impact: 8%
This is one of the most important questions within the scope of our entire review process. It is impossible to get a passing score without fully or partially meeting this criteria point.
It is mission critical to provide clear and easily located addresses for all contracts executing code on your protocol. If your contracts aren’t publicly viewable there’s no reliable way to verify your project does what it says, simple as that. Prioritizing a clear path to view your code is the easiest way to gain user confidence. Ideally, all contract addresses should be up to date, listed on a single page and include any token addresses and AMM strategies or similar protocols.
This criteria point is reflected as a percent and can have varying levels of completion. Our scoring guidelines for finding executing code addresses are as follows:
100% — Clearly labelled and easy to find.
A complete list of all deployed contract addresses are clearly outlined in your documentation. There’s a distinct section for contract addresses on your website, documentation or Github repo. Make this clear, complete and easy to find for an excellent score for this crucial component of transparency.
70% — Clearly labelled, but takes a bit of looking.
Your addresses are buried in a long documentation page and not given a clear or separated section. It’s not easy to find at first glance or worse, users need to use the search function to find your contracts. A common oversight is not identifying addresses provided as smart contract addresses. Without proper context, labeling and organization, transparency becomes impaired.
40% — Addresses listed in mainnet.json, Discord or sub-graph.
You will receive this score if your addresses were found outside of your documentation, website or whitepaper. Discord is a great community tool but it cannot replace legitimate documentation! At or below this grade we strongly recommend revisiting your documentation.
20% — Addresses found, but not clear or easy to find.
If your contract addresses are buried within multiple sub-sections and not labelled clearly as addresses nor contracts in the sub-heading.
0% — Executing Addresses could not be found.
This is CODE RED. If there’s no public way to view your deployed contract addresses you will not pass this review!
Is there a Public Software Repository? (Y/N)
Overall Score Impact: 2%
Ethereum was founded on open-source software and ideally these same principles continue to resonate within blockchain development. Maintaining a Public Repository is a great method to demystify your development process.
YES
A public repository usually takes the form of a Github repo clearly linked on your website and/or documentation that is accessible by anyone. Users are able to see in your repository how your code is implemented and your development and testing workflow.
NO
This would mean your repository is set to private or the link could not be found anywhere publicly that directs to your repository.
We understand there are advantages and legitimate reasons to maintain a private repo, especially in DeFi. However, transparency does not thrive under these constraints and your review score would reflect this decision. Check out this Medium article for guidance on how to maximize transparency with a private repo.
Is the team public (not anonymous)? (Y/N)
Overall Score Impact: 6%
Showing who you are and proving your identity, is a very obvious way to promote your accountability and dedication to the public. There are very real mental “red flags” raised when a team guards closely there identities and hides behind aliases.
YES
The full, first and last, names of some of the team members should be public on the website or documentation. If we can’t find it on either of those sources we’ll examine official medium authors or twitter accounts.
NO
We search high and low and cannot find any real names of your team or they use exclusively aliases in interacting with the public.
Is there a Whitepaper? (Y/N)
Overall Score Impact: 2%
A whitepaper, in the DeFi Safety review process, can be a document or set of text that explains what your project does. It should show up on your website or in your Github Repo, Medium articles can also be accepted. This is a critical piece of any protocol, if users can’t find a clear explanation of what your application does then trusting your platform becomes all the more unlikely.
YES
You have a whitepaper or dedicated text that explains how your protocol or application works. It can be found somewhere on your website, Github repo or Medium account.
NO
A whitepaper or dedicated section of text explaining what your protocol does could not be found publicly anywhere on your project.
How easy is it to find the status of the access controls? (%)
Overall Score Impact: 2%
This question refers to the access controls of your smart contracts. We refer specifically to who can access and what can be changed within your protocol. This is an important extension of the first criteria outlined in this article, it dives deeper, providing essential details on the powers of your smart contract administrators.
This documentation component can be complex by nature and might not be easily digestible by the average user but DeFi Safety provides an example guide which may help you breakdown and label your access controls. Often access control documentation is found under a “Governance” heading.
We grade this criteria on a percent based on how clear and easy it is to find this documentation.
100% — Quick to find and clearly labelled on Website, Docs or Repo.
The access controls for your contracts can be found in your main documentation within a dedicated section. Administrator controls are labelled and organized clearly and correctly on this page.
70% — Takes a bit of looking, but clearly labelled on Website, Docs, or Repo.
If your access controls are in a larger sub-section instead of a dedicated section this is less than ideal. It should be easy to find from the Table of Contents or Appendix of your Documentation.
40% — Not well labelled and in multiple places.
Your access controls are a bit scattered everywhere. There is not a section or sub-section with all the consolidated information. Your labelling is not easy to understand or not correct.
20% — Not labelled and in multiple places.
Similar to above, your access controls are not consolidated into a section or sub-section; the information is scattered. The information that could be found is not labelled.
0% — Access control information not found.
Your contract access controls could not be found anywhere publicly on neither your website nor documentation nor repository!
How clear and complete is the Access Control information? (%)
Overall Score Impact: 4%
This criteria examines how the information is supplied for your access controls. An important piece we consider is if your contracts are upgradeable or immutable. What type of entity owns your upgradeable contracts, and finally how the contracts are upgraded including any variable changes that result from the process.
100% — All contracts are immutable
Upgradeable contracts, by nature are not a great practice for creating trust. Only if ALL of your deployed contracts are immutable can you expect to receive a perfect score.
90% — Contracts are identified, Owners are identified and so are the contracts’ upgrade capabilities.
There are three sub-points each having a weight of +30% for each one fully satisfied. Fully complete all three for a maximal score of 90%.
- Are all the contracts clearly labelled as upgradeable?
- Is the type of ownership clearly indicated? i.e Multisig/ OnlyOwner/Defined Roles
- Do you provide details on the capabilities for change in the specified contracts?
Are the effects of upgradeable contracts explained in non-technical terms? (%)
Overall Score Impact: 4%
Administrators might be able to make changes to the protocol via upgradeable contracts that could impact user investments. Clear, accessible explanations help users make informed decisions. It is encouraged to use plain language, avoiding technical terminology and programming language, like Solidity, to convey information.
Criteria is graded based on the clarity of the information. However a perfect score can only be achieved by not having any upgradeable contracts.
100% — All contracts are Immutable
As mentioned in other points, the best solution regarding contracts is to use exclusively immutable contracts. This is the only way to get 100% on this criteria.
90% — Information is clear and in non-software language
The descriptions are clear, well documented and avoid non-software language, i.e Solidity. Pertinent information relating to investment safety is conveyed in common language.
30% — Information is in software specific language
The appropriate information is provided regarding upgradeable contracts. However, it relies on software specific language that would not be understood by the average user.
How well documented are the smart contract pause controls? (%)
Overall Score Impact: 4%
Pause controls are extremely important in that if a protocol’s security has been compromised an admin can freeze the contracts. Having pause controls is not a mandatory part of transparency but conveying to users if they exist and how they are implemented is strongly encouraged. If you do not have pause controls then your documentation should explicitly mention this. Testing pause control proves that you are able to pause quickly when needed.
100%
There are two scenarios to achieve a full score for this criteria:
1. All your contracts are immutable or you do not need pause control(s) and explain why clearly.
2. Pause control(s) have been clearly documented and evidence can be found of at least one test done within the last 3 months.
80%
Your pause controls are documented clearly but no evidence could be found of recent or regular tests.
40%
Contract pause controls are mentioned in your documentation but there’s not details provided on their capability or testing done on them.
0%
No documentation or explanations could be found regarding your pause controls.
Summary
”EASY” Guide Overall Score Impact: 32%
Some key themes to summarize this article are:
- Keep your contracts, team and repository identified, organized and public!
- Convey what your protocol does in clear, common language.
- Smart Contracts deserve dedicated, digestible documentation for access controls.
- Make sure your users understand how your contracts can change so they can make informed investment decisions.
The first steps are here to becoming a trusted DeFi project. Keep these in mind and consider how your protocol can go about their implementation. Transparency is a tricky issue, DeFi Safety is here to help you make it happen.
Check out all the DeFi protocol reviews on The DeFi Safety website or have a look at their latest public review process in their documentation.
