This document describes the process for a PQ Audit (Process Quality) on a deployed smart contract. The focus of this process is on DeFi contracts but it could be applied to any smart contract.
The intent is generation of a simple quality score for the smart contract application being audited. It will indicate the overall quality of the development process and the documents that the process generated. The readers can dig into the details of the audit in order to learn how the score was generated. Every step will be documented and available for review.
The basic premise of these audits is that developers following and documenting a good software development process should have secure code and maintain security. For blockchain developments a good process should have public readily auditable documents and other traces, making the process clear.
These audits are developed and focused towards released operating smart contract applications. The initial focus is on DeFi applications as these bring in many new users investing significant sums that are trusted by the smart contracts.
PQ audits are initially done without the audited organization’s permission or support using exclusively documents publicly available such as the website, the software repository of the code (GitHub, etc), and the code available from Etherscan. After the initial audit report is generated, it will be presented to the developers of the audited organization for correction or improvement. The results of these corrections will be clear and publicly documented in a new version of the report.
The author has no commercial arrangement with the organizations being audited. These audits are not funded by the organization being audited. The author is aiming for community support to audit as a public good.
Very simply, the audit looks for the following declarations from the developer's site. With these declarations, it is reasonable to trust the smart contracts.
Here are my smart contracts on the blockchain
You can see it matches a software repository used to develop the code
Here is the documentation that explains what my smart contract does
Here are the tests I ran to verify my smart contract
Here are the audit(s) performed with reviews of my code by third party experts
The author of this process has a long history in the avionics industry. Aerospace software development has always maintained that a rigorous and frequently audited software development process leads to safe and secure software that can be supported for many decades. The avionics process is DO-178C. It is significantly more rigorous than the expectation of this audit process, however the steps used and overarching philosophy has guided the specification of this audit process.
This report is for informational purposes only and does not constitute investment advice of any kind, nor does it constitute an offer to provide investment advisory or other services. Nothing in this report shall be considered a solicitation or offer to buy or sell any security, future, option or other financial instrument or to offer or provide any investment advice or service to any person in any jurisdiction. Nothing contained in this report constitutes investment advice or offers any opinion with respect to the suitability of any security, and the views expressed in this report should not be taken as advice to buy, sell or hold any security. The information in this report should not be relied upon for the purpose of investing. In preparing the information contained in this report, we have not taken into account the investment needs, objectives and financial circumstances of any particular investor. This information has no regard to the specific investment objectives, financial situation and particular needs of any specific recipient of this information and investments discussed may not be suitable for all investors.
Any views expressed in this report by us were prepared based upon the information available to us at the time such views were written. Changed or additional information could cause such views to change. All information is subject to possible correction. Information may quickly become unreliable for various reasons, including changes in market conditions or economic circumstances.
The process breaks the scores into the following sections;
Executing Code Verification
Documentation for the Executing Code
Overall test strategy for Executing Code
Review of Software Security Audits
The final audit score is indicated as a percentage. The percentage is calculated as (Total Possible Points) / (Achieved Points). For each element the answer can be either Yes/No or a percentage. For each element there is a “Scoring Weight”. The element points achieved is the scoring weight times the answer. The Achieved Points is the sum of every element’s points.
The scoring matrix for each element is highlighted as below;
Any PQ audit starts with code being executed and used by the application. It answers and generates a score on the following questions;
Is the executing code address(s) readily available? (Y/N)
Is the code actively being used? (%)
Are the Contract(s) Verified/Verifiable? (Y/N)
Does the code match a tagged version in the code hosting platform? (%)
Is the software repository healthy? (%)
Obviously this process lends itself to code already deployed and in use on the mainnet. These are the initial targets of these audits. The process could be adapted in the future toward code in the development process but not yet deployed.
Is the address of the deployed contract on the mainnet clearly available on the public documents for the service? An image of the web page with the address will be recorded as part of the audit.
If the contract address is found through alternate, unclear means, then this score will be zero but the rest of the audit will take place using the address.
If the address is not found, the rest of the audit takes place without code. The audit results will be zero, even if an audit is available as there is no confidence on the code that is executed wrt to the code audited. The test and documentation sections will receive scores based on the software repository contents as these indicate the care of the developers.
Make the ethereum addresses of the smart contract utilized by your application available on either your website or your github (in the README for instance). Ensure the address is up to date. This is a very important question wrt to the final score.
This looks at the transaction history of the contract through Etherscan. The results are scored as indicated below. The proof is documented in an appendix. The chart is generated by searching the address, clicking Analytics, then Transactions (for the Transaction chart) and scale it to one month.
100% More than 10 transactions a day
70% More than 10 transactions a week
40% More than 10 transactions a month
10% Less than 10 transactions a month
0% No activity
This checks that the contract code that is executing on the mainnet (taking into account proxy contracts for updated code) is indicated as verified by Etherscan/ETHPM as appropriate. This means the contract tab for the address has “Contract Source Verified (Exact Match)” indicated. The code for this contract is the code that will be audited. As this information is on the blockchain and cannot be edited, no screenshot is required.
Ensure that the deployed code is verified as described in this article for Etherscan or ETHPM. Improving this score may require redeployment.
We find and match the executing code with code in the software repository and check for a match. Ideally this code is in a clearly marked area and matches 100%.
100% All code matches and Repository was clearly labelled 60 % All code matches but no labelled repository. Repository was found manually 30% Almost all code does match perfectly and repository was found manually 0% Most matching Code could not be found
The outputs of this process are;
The web address to the developer’s public software repository
The commit hash or release tag of the deployed contracts
A % comparison of the deployed code to the indicated repository. Ideally of course they 100% match.
100% - The repository source matches deployed all code 100%. The repository was easy to find (labelled clearly). The repository was tagged for the deployed version
90% - The repository source matches all deployed code 100% Tag was not labelled appropriately.
80% - The repository source matches all deployed code 100% Release is not tagged.
60% - Minor differences in the software repository not in deployed code. Release is not tagged
20% - Deployed code has significant differences not found in any public repository
0% - No reference to most of the deployed code in a public repository was found
Ensure there is a clearly labelled repository holding all the contracts, documentation and tests for the deployed code. Ensure an appropriately labeled tag exists corresponding to deployment dates. Release tags are clearly communicated.
A healthy software repository has evidence of activity that indicates the deployed code was developed and tested in that repository. A number of commits, branches and releases indicates health. An unhealthy repository has so few actions that it is obvious the code was not developed or tested there.
If the code was clearly developed in a private repository, but the final code is public then points will be high but not 100%. The author considers public development preferable.
The numbers are subjective by the author. Continued development after a release indicates that the team takes the security of their application seriously, and is continuously looking for issues in their code that could lead to a vulnerability against the deployed version of the code.
Ensure there is a clearly labelled repository holding all the contracts, documentation and tests for the deployed code. Continue to test and perform other verification activities after deployment, including routine maintenance updating to new releases of testing and deployment tools.
The documentation section describes the quality of the system and software documentation and commenting. In this initial version of the Process Audit standard, only basic documentation is requested. For perspective, the aerospace software requirements are mentioned below.
Required questions are;
Is there a whitepaper? (Y/N)
Are the basic application requirements documented? (Y/N)
Are the requirements available publicly? (Y/N)
Do the requirements fully (100%) cover the deployed contracts? (%)
Are there sufficiently detailed comments for all functions within the deployed contract code (%)
Is it possible to trace software requirements to the implementation in code (%)
This is simple. Is there a white paper or other basic description of what the project is doing referenced by either the web site or the GitHub. Yes/No.
Ensure the white paper is available for download from your website or at least the software repository. Ideally update the whitepaper to meet the capabilities of your present application.
This is also simple but very important. Are the basic system requirements of the smart contracts documented in either the website or the GitHub? Yes/No. A requirements document is the foundation of application documentation. This document says what the smart contracts do and should have some connection with the code and contracts allowing at least general traceability of requirements to code.
Write the document based on the deployed code. For guidance, refer to the SecurEth System Description Document for guidance. This document can be written after deployment.
The goal for a 100% score is for documented requirements (in either the website or the GitHub) that cover all of the developed source code. It does not have to cover public libraries, though they should be mentioned. The requirements do not need rigid requirement diction (such as a "shall" in every requirement). For guidance, refer to the SecurEth System Description Document.
For this initial version of the Process Audit process the auditor qualitatively determines the number between 0 and 100. Include example source in the appendices to justify the score.
This score can improve by adding content to the requirements document such that it comprehensively covers the requirements. For guidance, refer to the SecurEth System Description Document . Using tools that aid traceability detection will help.
Software requirements are not the same as system requirements (that are referenced in the previous questions). Software requirements refer specifically to the code implementation. It is an additional layer of documentation within the code and must exclusively be in comments in the source file. Ideally the comments have fixed formatting giving consistent comments for all authors in all source files for the project. For guidance refer to the SecurEth Software Requirements.
For this initial version of the Process Audit process the auditor qualitatively determines the number between 0 and 100 and include example source in the appendices to justify the score.
This score can improve by adding comments to the deployed code such that it comprehensively covers the code. For guidance, refer to the SecurEth Software Requirements.
Traceability is a documented link between the requirement and the code. It can be a number or other simple identifier (such as a shortened content hash) that connects a text requirement to the code it implements. Since requirements are usually in separate documents from the software requirements/comments traceability links each requirement to the code that implements it. Ideally there are requirements for every piece of code, 100% requirement traceability. For reference, check the SecurEth guidelines on traceability.
For this initial version of the Process Audit process the auditor qualitatively determines the number between 0 and 100 and include example source in the appendices to justify the score.
Guidance: 100% - Clear explicit traceability between code and documentation at a requirement level for all code 60% - Clear association between code and documents via non explicit traceability 40% - Documentation lists all the functions and describes their functions 0% - No connection between documentation and code
This score can improve by adding traceability from requirements to code such that it is clear where each requirement is coded. For reference, check the SecurEth guidelines on traceability.
For reference, this presents the software and system requirements for aerospace code certification in an extremely simplified format. It makes a useful comparison.
All System Requirements documented in proper requirements diction
There is documented traceability from each system requirement to software requirements or low level requirements
All software requirements (or low-level requirements/comments) exist for each part of software code
There is documented traceability from the low level requirements to the software code they cover
Every piece of software code is covered by both unit tests and system tests. If a unit test covers the requirements of the system test, the single test suffices.
There is documented traceability from the software to the tests
They were requirement review meetings held according to a documented process to review every requirement
There are documented software requirement reviews held according to a documented process for each software requirement
There are test reviews held according to a documented process for each test
When there is a requirement to change software code for which already reviewed requirements, code or test must change than a change impact analysis document must review the changes and recommend which reviews must be held again on the requirements, software and tests
During the audit any test can be chosen by the auditor and the auditor can review traceability from the test through the code to the requirements with reviews for each step in the process
This section covers the test suite that the deployed passed before its deployment on the mainnet. Ideally the suite is in the same repository, completely covers all code as the deployed contracts and has a report indicating a successful run. Additional testing can include Formal Verification and active test/stress environments.
In future versions of this process, the auditor will attempt to run the tests on the deployed code, independently verifying the test results. In this initial version we look for the test artifacts in the repository and give a qualitative score based on the artifacts that exist and those that do not.
Full test suite (Covers all the deployed code) (%)
Code coverage (Covers all the deployed lines of code, or explains misses) (%)
Scripts and instructions to run the tests (Y/N)
Packaged with the deployed code (Y/N)
Report of the results (%)
Formal Verification test done (%)
Stress Testing environment (%)
Does the deployed code have a suite of tests and scripts to run them? Do the tests allow for comprehensive testing of the code? If the tests are not in the deployed software repository, then tests done on identical or very similar have value. It is better to test after deployment than never test at all. Testing is described in the SecurEth guidelines.
In later versions of this process we will run the test suite to verify coverage and completeness. At this point we compare the software lines of code between the tests and the smart contracts. A comprehensive test suite might have a test SLOC/ contract SLOC of 150% or more. A 100% ratio is considered minimally acceptable. These numbers are just guidelines. The score for this element is a qualitative number decided by the author after reviewing the tests and the ratio.
This score can improve by adding tests to fully cover the code. Document what is covered by traceability or test results in the software repository.
Here we consider if the unit tests fully cover the code. Ideally there is a report of a code coverage run with results in the repository. The normal goal is 100% code coverage. Without a report, the author determines a percentage based on the test suite percentage, artifacts in the test scripts and qualitative estimation. If there are any departures, there should be documentation on why certain pieces of code cannot be tested. This should be minimal and well-argued.
100% - Documented full coverage 99-51% - Value of test coverage from documented results 50% - No indication of code coverage but clearly there is a reasonably complete set of tests 30% - Some tests evident but not complete 0% - No test for coverage seen
This score can improve by adding tests achieving full code coverage. A clear report and scripts in the software repository will guarantee a high score.
Can 3rd parties run the full test suite using well documented scripts in the deployed software repository? Yes/No. If the scripts and tests are in a similar repository with the same code this is acceptable (but not ideal).
Add the scripts to the repository and ensure they work. Ask an outsider to create the environment and run the tests. Improve the scripts and docs based on their feedback.
Simple question. Are the tests in the same software repository as the deployed code, Yes / No?
Improving this score requires redeployment of the code, with the tests. This score gives credit to those who test their code before deployment and release them together. If a developer adds tests after deployment they can gain full points for all test elements except this one.
Ideally there is a test report in the repository of the test results before the code was deployed. Surprisingly most repositories don’t have one. Most testing tools make tests that only report errors. No output means a pass. When auditing deployed code this is not informative. A test report also indicates what is not covered and why. Often there are corner cases of code that are difficult or impossible to test. A report indicates this with a brief explanation.
Code coverage proof actually needs a report. The output should indicate the successful coverage, on what code and using what options.
The output is a percentage. This allows the author to “grade” the report, if it exists.
Add a report with the results. The test scripts should generate the report or elements of it.
Formal verification is a specific process of testing software processes that is well suited to some blockchain software. Its use is still limited, but it adds value in some cases. For this reason the weight is lower than other elements. The output is a percentage. This allows the author to “grade” the report, if it exists.
A Stress testing environment is an active test environment (not the active mainnet) that is used for testing limits of the application. This would run on a testnet with simulated inputs. By maintaining an up to date test environment, the developers can test possible limit cases as they develop. It adds another layer of protection. The output is a percentage determined by the author.
Smart contract audits are typically an indicator of quality in the blockchain world. The intent is to have 3rd party blockchain software experts review your code and tests to look for overall quality and the subtle blockchain specific weaknesses that could be utilized by an attacker.
If the smart contract address on the mainnet are not found, the audit results will be zero, even if an audit is available as there is no confidence on the code that is executed wrt to the code audited.
For this reason the score multiplier is high; 70.
Multiple Audits performed before deployment and results public and implemented or not required (100%)
Single audit performed before deployment and results public and implemented or not required (90%)
Audit(s) performed after deployment and no changes required. Audit report is public. (70%)
No audit performed (20%)
Audit Performed after deployment, existence is public, report is not public and no improvements deployed OR smart contract address' not found, question 1 (0%)