Aleo Audit Contest Handbook - Sherlock

Summary

The following document is to provide a primer for participants in the upcoming Aleo audit contest. Specifically, what follows is:

What is Aleo?
Scope of the contest
A brief overview of the codebase
Instructions on how to get started
Further references

What is Aleo?

Aleo is a privacy-preserving, programmable blockchain that leverages zero-knowledge cryptography. Specifically, Aleo implements a variant of the Zexe protocol. The main differences between the original paper and the current Aleo protocol are:

The Zexe paper describes a computing paradigm and only obliquely describes a blockchain/decentralized ledger. In Aleo, we explicitly define that blockchain, maintained by nodes that validate changes to and update that ledger. The consensus mechanism used by these nodes is a variant of Proof-of-Stake called Narwhal-Bullshark.
Zexe does not explicitly specify a proof system to be used. In Aleo's case, we use the Varuna proof system, which is a variant of Marlin that incorporates several improvements
Zexe describes a concept of "state" and "state management" much more akin to the UTXO model of ZCash, which helps ensure the viability of confidential transactions. However, it makes multiparty interactions complex. Therefore, Aleo nodes also run an "on-chain VM", which is very similar to the EVM in the sense that clients send signed instructions (aka transactions) to consensus-participating nodes to process and update the corresponding state (each deployed program has an associated store called a "mapping," and this is what is updated with the "on-chain VM" transactions, which we call finalize transactions). However, unlike the EVM, Aleo implements its own set of opcodes designed to be zkSNARK-circuit friendly.

The opcodes that define the logic of an Aleo program are called Aleo Opcodes. These opcodes define a foundational program that governs how value is represented, generated, spent, and transferred. It is this program (credits.aleo) that is most relevant for this audit contest and should be considered primary scope.

For more resources on Aleo, please refer to the section heading below titled 'Further Reading'.

Scope of the Contest

Recently, Aleo incorporated changes to its consensus model to allow for a more flexible paradigm for staking/delegating. These changes were described in Aleo Request-For-Comment (ARC)-0041 (link- see option 3). Given that all public value transfer is governed by this program, it is essential that all of the logic there is "secure" in the sense that there is no unintended side effect of any function call which results in value being transferred contrary to the intention of the concerned stakeholder.

credits.aleo is written in Aleo instructions, which in turn are compiled by snarkVM into Aleo opcodes, which is the format in which they are executed by the consensus-participating nodes. The mechanism by which these instructions are compiled into opcodes (and then synthesized into circuits) occurs at various places in the synthesizer and circuit modules of the codebase, as well as vulnerabilities in any related module that results in a vulnerability in validator bonding. Although these large modules are not the focus of the audit contest, they are "in-scope" in the sense that vulnerabilities that are discovered in those modules which result in a vulnerability in credits.aleo will be counted.

Overview of the Aleo Codebase

The Aleo codebase consists of two primary libraries: snarkOS and snarkVM

snarkOS is primarily concerned with the ledger and consensus. It relies heavily upon several cryptographic primitives defined in snarkVM.
snarkVM implements the Zexe protocol/VM, as well as defines all of the ancillary cryptography associated with making it work. A layout of the codebase is shown below

Image Not Showing Possible Reasons

The image was uploaded to a note which you don't have access to
The note which the image was originally uploaded to has been deleted

Learn More →

credits.aleo exists in the synthesizer library. It is effectively a precompiled program in the AleoVM. The program is written in Aleo Opcodes. Here is a quick summary of the functions it defines:

mint: Used to create new credits for a specified owner.
transfer: Used to move credits from one user to another.
fee: Used to apply a fee on a credits transfer.
bond_public: Bonds credits to a public address.
unbond_public: Unbonds credits from a public address to a private address.
bond_private: Bonds credits to a private address.
unbond_private: Unbonds credits from a private address.

There is also logic relating to staking and delegation.

Note that credits.aleo can be used for both public and private transactions. Private transactions use the synthesized circuit (defined by the credits.aleo) and a user's private witness data (e.g. their private inputs) to generate a zero-knowledge proof (ZKP) of a valid transaction. Alternatively, public transactions use the finalize paradigm described above.

For private transactions, synthesizer relies on many primitives defined in the circuit library.

Getting Started

To get started and build an understanding of how Aleo Instructions work under the hood, we encourage audit contest participants to try out our 'Hello, Aleo' example in our documentation here.

Aleo Audit Contest Handbook - Sherlock

Summary

What is Aleo?

Scope of the Contest

Overview of the Aleo Codebase

Getting Started

Further Reading

Read more

ARC-0100 Compliance Best Practices for Developers and Operators on Aleo

Zero-Knowledge Cryptography Introduction

Aleo Economics Summary

Aleo Talk