# 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:

0) What is Aleo?
1) Scope of the contest
2) A brief overview of the codebase
3) Instructions on how to get started
4) 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](https://eprint.iacr.org/2018/962.pdf). The main differences between the original paper and the current Aleo protocol are:

1) 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.

2) Zexe does not explicitly specify a proof system to be used. In Aleo's case, we use the [Varuna](https://www.youtube.com/watch?v=ZdHmk2cBlQ0) proof system, which is a variant of Marlin that incorporates several improvements

3) 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](https://developer.aleo.org/aleo/opcodes/). These opcodes define a foundational program that governs how value is represented, generated, spent, and transferred. It is [this program](https://github.com/AleoNet/snarkVM/blob/74a437897e80514cb88e52a3033df5f69181aed8/synthesizer/program/src/resources/credits.aleo) (`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](https://docs.google.com/document/d/1hBNolEE-WXM5E_0CChsS3uT2kgzgzTTC-VDRVOFICJM/edit#heading=h.7492flf47nuv)). 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

<br>


`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](https://developer.aleo.org/aleo/hello).

## Further Reading ##

* [Aleo Instructions Language Guide](https://developer.aleo.org/aleo/language/)
* [Aleo Opcodes Reference](https://developer.aleo.org/aleo/opcodes/)
* [An Introduction to SnarkVM](https://kehiy.medium.com/snarkvm-an-introduction-0e3bbed695cb)
* This article explains the high level data flow of Leo Source -> Aleo Instructions -> Aleo VM Opcodes -> R1CS circuit representation
* Of all previous audits zkSecurity's Audit of Aleo's Synthesizer focuses on parts of Aleo's codebase most related to this Sherlock contest's scope:
* [zkSecurity Audit of Aleo's Synthesizer](https://www.zksecurity.xyz/blog/posts/aleo-synthesizer/) (October '23)
* Other previous audits of Aleo do not focus on the subcomponents related to the scope of this contest but may still be relevant for educational purposes:
* [zkSecurity Aleo Consensus Audit Report](https://www.zksecurity.xyz/blog/2023-aleo-consensus.pdf) (October '23)
* [nccgroup Aleo snarkVM Implementation Review](https://research.nccgroup.com/2023/12/13/public-report-aleo-snarkvm-implementation-review/) (December '23)
* [nccgroup Aleo snarkOS Implementation and Consensus Mechanism Review](https://research.nccgroup.com/2024/02/08/public-report-aleo-snarkos-implementation-and-consensus-mechanism-review/) (Feb '24')
* [Aleo snarkVM, snarkOS, and BullsharkBFT](https://github.com/trailofbits/publications/blob/master/reviews/2023-10-aleo-securityreview.pdf) (Novemeber '23')
* [Aleo Concepts](https://developer.aleo.org/concepts/) - high level discussion of various concepts in the Aleo architecture
* [Leo Language Links](https://www.leo-lang.org/) - This contains resources for various IDE plugins that support Leo. There currently does not exist a plugin for Aleo Assmebly.
* [awesome-aleo](https://github.com/AleoNet/awesome-aleo) - A consolidated list of Aleo talks and resources
* [Getting Started with Aleo](https://developer.aleo.org/getting_started)
* [Zexe](https://eprint.iacr.org/2018/962.pdf) - the original paper that inspired Aleo
* [Varuna](https://www.youtube.com/watch?v=ZdHmk2cBlQ0) - Talk covering Varuna (Aleo's proof system) presented in fall 2023 at ZK Summit 10.