Lesson 7 - Smart Contract Control

This lesson targets to improve the security culture within the Aleph Zero community, as a common error may occur in the community.

This part aims to help preparing for a security audit which is necessary to achieve the highest level of security possible. It is important to view an audit as a partnership between your team and the auditing company. Therefore, it is crucial to prepare the necessary documents for the good functioning of audit.



A complete documentations for a security audit should contains the following elements:

  • An explanation of the purpose of the smart contract, this could include:

    • An overview of the smart contract and its purpose.

    • An explanation of how it works.

  • Documentation and explanation of all smart contract's functions and variables.

  • Examples and use cases:

    • This will demonstrate how the smart contract can be used. This will help the security audit team to understand the smart contract and facilitate their examination of the threat and vulnerabilities of the smart contract.

  • Security considerations: Document any security considerations or vulnerabilities associated with the smart contract. This should include information on how to mitigate risks and ensure the contract's secure operation.

  • Machine setup, installation, deployment and testing instructions:

    • This will allow the security audit team to deploy the smart contract and try to exploit any of the vulnerabilities that they found in the code.

    • Document how to test the smart contract to ensure that it is working correctly. This should include information on testing methodologies and tools, as well as any test scripts or scenarios that have been developed.

  • Additional Documentation:

    • architecture diagrams;

    • threat models;

    • academic papers;

    • whitepapers;

    • blog posts;

    • or any other piece of documentation relevant to the project.

Collaborative environment

It is important to view an audit as a collaborative effort. Something to avoid is to interact only at the start of the audit and then receive a report at the end of the engagement. To create a collaborative engagement, we recommend the following steps:

  • A secure communication channel using end-to-end encryption needs to be initialized between technical people on you side and the audit team. Popular communication channels used during audit include:

    • Telegram

    • Microsoft Teams

    • Slack

  • The credential for auditors needs to granted:

  • Share the repository with the audit team

  • Share Documentation

  • The smart contract needs to be frozen. In other words, no modifications are made while the audit is being performed.

    • Inform the commit hash value to the audit team.

  • Verify that the audit team can answer the following questions

    • What does it do?

    • Who does it do this for?

    • What kind of information will it hold/handle?

    • How does it handle entities or identities?

    • What aspects seem most concerning?


During the audit, you should make sure that you perform the following task:

  • Schedule regular meetings between your engineers and the audit team

  • Make sure that high-risk findings have been escalated immediately via a secure channel.

  • Answer any questions from the audit team.

  • Correct or review all findings, with high-impacting findings taking priority.


Once the contract has been deployed, the following element needs to be discussed:

  • Keep monitoring new security attacks and evaluate your contracts accordingly.

  • Apply remedies to the smart contracts immediately if new vulnerabilities are discovered.

    • Ensure that the contract is upgradable.

  • Run automated code analysis tools whenever new commits are added to the repository.

  • Pause the smart contract when an unusual event occurs.

    • Contract needs to have a pause option.

  • Consider re-auditing your smart contracts if significant updates have been made.

  • Feel free to contact security partners for evaluating and scoping.

Last updated