### Install Rust via rustup on macOS or Linux Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/README.md Install Rust using rustup on macOS or Linux. After installation, macOS users must install pkgconf and openssl via Homebrew. ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` -------------------------------- ### Install required packages on macOS Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/README.md After installing Rust on macOS, install pkgconf and openssl using Homebrew. ```bash brew install pkgconf ``` ```bash brew install openssl ``` -------------------------------- ### Example instruction sequence with operands and destinations Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/ledger/puzzle/epoch/docs/spec.md Defines a sequence of three instructions (IsEq, Ternary, Div) with operands and destinations, weighted by VERY_LOW. The sequence uses ephemeral and register destinations, and operands including Register, Literal, Ephemeral, Input, and RegisterOffset. ```rust (vec![ (Instruction::IsEq, vec![ Operand::Register(LiteralType::Field), Operand::Literal(Literal::Field(Field::zero()))], vec![ Destination::Ephemeral(LiteralType::Boolean, 0) ]), (Instruction::Ternary, vec![ Operand::Ephemeral(LiteralType::Boolean, 0), Operand::Input(LiteralType::Field, 0), Operand::Register(LiteralType::Field)], vec![ Destination::Ephemeral(LiteralType::Field, 1)]), (Instruction::Div, vec![ Operand::RegisterOffset(LiteralType::Field, 1), Operand::Ephemeral(LiteralType::Field, 1)], vec![Destination::Register(LiteralType::Field)])], VERY_LOW) ``` -------------------------------- ### Run a specific test namespace with cargo test --test '' Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/synthesizer/tests/README.md Runs a specific set of tests. Can be stacked with the flags above. Example shows running test_program_parse. ```bash cargo test --test '' // Example cargo test --test 'test_program_parse' ``` -------------------------------- ### Formatting Command Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/AGENTS.md Run this before staging to fix formatting issues. ```bash cargo +nightly-2026-04-02 fmt --all ``` -------------------------------- ### Build snarkVM from source Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/README.md Clone the development (staging) branch of snarkVM and build the library in release mode. ```bash # Fetch the repository's development (staging) branch git clone --branch staging --single-branch https://github.com/ProvableHQ/snarkVM.git cd snarkVM # Build the library cargo build --release ``` -------------------------------- ### Run Puzzle::prove benchmark with custom Criterion settings Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/ledger/puzzle/README.md Use this command to benchmark Puzzle::prove with 100 samples, 3s warmup, and 10s measurement time, as the default 10-sample setting is too noisy and causes CI failures at 200%. ```bash cargo bench --package=snarkvm-ledger-puzzle --bench puzzle --features=setup -- Puzzle::prove \ --sample-size 100 --warm-up-time 3 --measurement-time 10 ``` -------------------------------- ### Register Table Preamble (Aleo Instructions) Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/ledger/puzzle/epoch/docs/spec.md Initializes the register table for the epoch program with 2-deep stacks per LiteralType. It declares public inputs for boolean, i8, i16, i32, i64, i128, and field types, then computes equality, hashes (hash.psd2), multiplications (mul.w), and ternary selections to populate registers r14 through r39. ```aleo input r0 as boolean.public; input r1 as boolean.public; input r2 as i8.public; input r3 as i8.public; input r4 as i16.public; input r5 as i16.public; input r6 as i32.public; input r7 as i32.public; input r8 as i64.public; input r9 as i64.public; input r10 as i128.public; input r11 as i128.public; input r12 as field.public; input r13 as field.public; is.eq r1 r0 into r14; is.eq r3 r2 into r15; is.eq r5 r4 into r16; is.eq r7 r6 into r17; is.eq r9 r8 into r18; is.eq r11 r10 into r19; hash.psd2 r12 into r20 as u8; hash.psd2 r13 into r21 as u8; hash.psd2 r12 into r22 as u16; hash.psd2 r13 into r23 as u16; hash.psd2 r12 into r24 as u32; hash.psd2 r13 into r25 as u32; hash.psd2 r12 into r26 as u64; hash.psd2 r13 into r27 as u64; hash.psd2 r12 into r28 as u128; hash.psd2 r13 into r29 as u128; mul.w r3 r2 into r30; mul.w r5 r4 into r31; mul.w r7 r6 into r32; mul.w r9 r8 into r33; mul.w r11 r10 into r34; ternary r15 r30 r2 into r35; ternary r16 r31 r4 into r36; ternary r17 r32 r6 into r37; ternary r18 r33 r8 into r38; ternary r19 r34 r10 into r39; ``` -------------------------------- ### Pre-commit Hook Command Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/AGENTS.md Runs workspace-wide clippy and formatting checks. Use before committing. ```bash cargo clippy --workspace --all-targets --all-features -- -D warnings && cargo +nightly-2026-04-02 fmt --all -- --check ``` -------------------------------- ### Run all tests with cargo test --test '*' Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/synthesizer/tests/README.md Runs all integration tests in the synthesizer test framework. ```bash cargo test --test '*' ``` -------------------------------- ### Validation Commands Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/AGENTS.md Run these commands in order to validate a crate. Clippy warnings are errors, and formatting requires the nightly toolchain pinned in CI. ```bash cargo check -p cargo clippy -p -- -D warnings cargo +nightly-2026-04-02 fmt --check cargo test -p ``` -------------------------------- ### Cut the release branch: git push origin origin/staging:refs/heads/release/v4.13 Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/BRANCHING_AND_RELEASING.md Creates the release branch `release/v4.13` at the current `staging` commit and pushes it to the remote. Run after fetching from origin. ```bash git fetch origin git push origin origin/staging:refs/heads/release/v4.13 ``` -------------------------------- ### Run tests with filter using TEST_FILTER Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/synthesizer/tests/README.md Runs only test files whose name contains the query. Recommended for specific tests because vm_execute_and_finalize can take a long time. ```bash TEST_FILTER= cargo test --test '*' ``` -------------------------------- ### Epoch Program Solution Pseudocode Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/ledger/puzzle/epoch/docs/spec.md Describes the algorithm for constructing a valid epoch solution. It samples the epoch program once per epoch, then iterates with a counter, generating a nonce via sha2, seeding a chacha RNG, constructing inputs and Merkle leaves, computing a SHA3-256 Merkle root (arity 8), and comparing the derived target against puzzle_target. The loop increments the counter and retries until the target is met, then returns the counter and root. ```pseudocode ############################################################################# # Inputs ############################################################################# # The address to be rewarded Address address # The block hash of the latest epoch N::Blockhash epoch_hash # The counter u64 counter # The target difficulty u64 puzzle_target ############################################################################# # Sample the epoch program, once per epoch ############################################################################# EpochProgram program = EpochProgram::new(epoch_hash) ############################################################################# # Construct a valid solution ############################################################################# counter = 0 while (1) # Generate nonce for the RNG # Note, this nonce should be unique to **all** attempts u64 nonce = sha2(sha2(address, epoch_hash, counter)).to_u64() # Seed the RNG using nonce rng = chacha(nonce) # Construct the inputs to the program Vec inputs = program.construct_inputs(rng) # Construct the leaves of the Merkle Tree Vec> leaves = program.to_leaves(inputs); # Generate the root of a SHA3-256 Merkle Tree with arity 8 over the leaves u256 root = merkle_tree(leaves) # Get the lower 64 bits of the root u64 root_as_u64 = root.to_u64() # Compute the target u64 target = if root_as_u64 == 0u64 { u64::MAX } else { u64::MAX / root_as_u64 } # If the candidate does not meet the target, try again if target < puzzle_target counter++ next return (counter, root) ``` -------------------------------- ### Cargo Test Commands for SnarkVM Crates Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/AGENTS.md Use these commands to run tests for a specific crate, a specific test function, or integration tests with the required features. Synthesizer tests are slow, so run only the specific test function. Integration tests require the 'test,dev-print' features. ```bash cargo test -p # Run crate tests ``` ```bash cargo test -p -- test_name # Run specific test ``` ```bash cargo test -p snarkvm-synthesizer --features test,dev-print # Integration tests ``` -------------------------------- ### Test program anatomy with configuration and Aleo program Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/synthesizer/tests/README.md Shows the structure of a test program in ./tests/program: a YAML config comment (randomness, cases with function/inputs/private_key) followed by the Aleo program. The config seeds the test and defines test cases; private_key is optional. ```yaml /* randomness: 1337 cases: - function: mint inputs: [aleo1j2hfs6yru47h2nvsjdefwtw6nwaj0y4zcl02juyy29txm7nt6y9qln7uhp, 100u64] - function: split inputs: [ "{ owner: aleo1j2hfs6yru47h2nvsjdefwtw6nwaj0y4zcl02juyy29txm7nt6y9qln7uhp.private, microcredits: 100u64.private, _nonce: 0group.public }", 50u64] private_key: APrivateKey1zkpFbGDx4znwxo1zrxfUscfGn1Vy3My3ia5gRHx3XwaLtCR - function: split inputs: [ "{ owner: aleo1j2hfs6yru47h2nvsjdefwtw6nwaj0y4zcl02juyy29txm7nt6y9qln7uhp.private, microcredits: 100u64.private, _nonce: 0group.public }", 50u64] private_key: APrivateKey1zkpJhviKDvvm7yu7SZuhSudVR7zjCRG2HznuAHwuGYc1xqN */ program mint_and_split.aleo; record credits: owner as address.private; microcredits as u64.private; function mint: input r0 as address.public; input r1 as u64.public; cast r0 r1 into r2 as credits.record; output r2 as credits.record; function split: input r0 as credits.record; input r1 as u64.private; sub r0.microcredits r1 into r2; cast r0.owner r1 into r3 as credits.record; cast r0.owner r2 into r4 as credits.record; output r3 as credits.record; output r4 as credits.record; ``` -------------------------------- ### Run variable_base benchmark with CUDA feature Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/algorithms/cuda/README.md Enables the cuda feature to run the variable_base benchmark in the algorithms directory. Requires CUDA toolkit and a compatible GPU. ```bash cd snarkVM/algorithms cargo bench --bench variable_base --features "cuda" ``` -------------------------------- ### Git graph: release candidate tags v4.13.0-rc.1 and v4.13.0-rc.2 Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/BRANCHING_AND_RELEASING.md Mermaid gitGraph diagram showing the `release/v4.13` branch with commits tagged `v4.13.0-rc.1` and `v4.13.0-rc.2`, while `staging` continues with commit D. ```mermaid %%{init: {'gitGraph': {'mainBranchName': 'staging'}}}%% gitGraph commit id: "A" commit id: "B" branch release/v4.13 checkout staging commit id: "C" checkout release/v4.13 commit id: "bump 4.13.0" tag: "v4.13.0-rc.1" checkout staging commit id: "D" checkout release/v4.13 commit id: "fix" tag: "v4.13.0-rc.2" ``` -------------------------------- ### Git graph: version bump and extended CI fixes Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/BRANCHING_AND_RELEASING.md Mermaid gitGraph diagram showing the `bump-v4.13.0` branch created from `release/v4.13`, with commits for the version bump and extended CI fixes, then merged back into `release/v4.13`. `staging` continues with commit C. ```mermaid %%{init: {'gitGraph': {'mainBranchName': 'staging'}}}%% gitGraph commit id: "A" commit id: "B" branch release/v4.13 checkout staging commit id: "C" checkout release/v4.13 branch bump-v4.13.0 commit id: "bump 4.13.0" commit id: "fix extended CI" checkout release/v4.13 merge bump-v4.13.0 ``` -------------------------------- ### Git graph: release/v4.13 branch creation Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/BRANCHING_AND_RELEASING.md Mermaid gitGraph diagram showing the `release/v4.13` branch created from the `staging` branch at commit B. The `mainBranchName` is set to `staging`. ```mermaid %%{init: {'gitGraph': {'mainBranchName': 'staging'}}}%% gitGraph commit id: "A" commit id: "B" branch release/v4.13 ``` -------------------------------- ### Git graph: merge release/v4.13 into staging Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/BRANCHING_AND_RELEASING.md Mermaid gitGraph diagram showing the `release/v4.13` branch merged into `staging` with a merge commit, followed by commit E on `staging`. ```mermaid %%{init: {'gitGraph': {'mainBranchName': 'staging'}}}%% gitGraph commit id: "A" commit id: "B" branch release/v4.13 checkout staging commit id: "C" checkout release/v4.13 commit id: "bump 4.13.0" tag: "v4.13.0-rc.1" checkout staging commit id: "D" checkout release/v4.13 commit id: "fix" tag: "v4.13.0-rc.2" tag: "v4.13.0" checkout staging merge release/v4.13 commit id: "E" ``` -------------------------------- ### Git graph: final release tag v4.13.0 Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/BRANCHING_AND_RELEASING.md Mermaid gitGraph diagram showing the `release/v4.13` branch with the commit tagged both `v4.13.0-rc.2` and `v4.13.0`, indicating the accepted release candidate is tagged as the final release. ```mermaid %%{init: {'gitGraph': {'mainBranchName': 'staging'}}}%% gitGraph commit id: "A" commit id: "B" branch release/v4.13 checkout staging commit id: "C" checkout release/v4.13 commit id: "bump 4.13.0" tag: "v4.13.0-rc.1" checkout staging commit id: "D" checkout release/v4.13 commit id: "fix" tag: "v4.13.0-rc.2" tag: "v4.13.0" ``` -------------------------------- ### Git graph: patch release v4.13.1 Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/BRANCHING_AND_RELEASING.md Mermaid gitGraph diagram showing the patch release process: a `bump 4.13.1` commit tagged `v4.13.1-rc.1`, a fix commit tagged `v4.13.1-rc.2` and `v4.13.1`, and a final merge of `release/v4.13` into `staging`. ```mermaid %%{init: {'gitGraph': {'mainBranchName': 'staging'}}}%% gitGraph commit id: "A" commit id: "B" branch release/v4.13 checkout staging commit id: "C" checkout release/v4.13 commit id: "bump 4.13.0" tag: "v4.13.0-rc.1" checkout staging commit id: "D" checkout release/v4.13 commit id: "fix" tag: "v4.13.0-rc.2" tag: "v4.13.0" checkout staging merge release/v4.13 commit id: "E" checkout release/v4.13 commit id: "bump 4.13.1" tag: "v4.13.1-rc.1" checkout staging commit id: "F" checkout release/v4.13 commit id: "fix 2" tag: "v4.13.1-rc.2" tag: "v4.13.1" checkout staging merge release/v4.13 ``` -------------------------------- ### Regenerate expectation files with REWRITE_EXPECTATIONS Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/synthesizer/tests/README.md Regenerates expectation files. Can be stacked with TEST_FILTER to regenerate expectations for a specific test. ```bash REWRITE_EXPECTATIONS=1 cargo test --test '*' ``` -------------------------------- ### Merkle Puzzle Pseudocode Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/ledger/puzzle/epoch/docs/spec.md Pseudocode for constructing a Merkle puzzle solution. It samples the number of leaves once per epoch using the epoch hash, then iterates with a counter to find a nonce that yields a target meeting the puzzle target. The solution returns the counter and root when the target condition is satisfied. ```pseudocode ############################################################################# # Inputs ############################################################################# # The address to be rewarded Address address # The block hash of the latest epoch N::Blockhash epoch_hash # The counter u64 counter # The target difficulty u64 puzzle_target ############################################################################# # Sample the number of leaves in the Merkle Tree, once per epoch ############################################################################# # Seed the RNG using the lower 64 bits of the epoch hash u64 epoch_hash_as_u64 = epoch_hash.to_u64() epoch_rng = chacha(epoch_hash_to_u64) # Sample the number of leaves u32 num_leaves = epoch_rng.sample_range(100000, 200000) ############################################################################# # Construct a valid solution ############################################################################# counter = 0 while (1) # Generate nonce for the RNG # Note, this nonce should be unique to **all** attempts u64 nonce = sha2(sha2(addr, epoch_hash, counter)).to_u64() # Seed the RNG using nonce rng = chacha(nonce) # Construct the leaves of the Merkle Tree Vec> leaves = rng.sample_leaves(num_leaves) # Generate the root of a SHA3-256 Merkle Tree with arity 8 over the leaves u256 root = merkle_tree(leaves) # Get the lower 64 bits of the root u64 root_as_u64 = root.to_u64() # Compute the target u64 target = if root_as_u64 == 0u64 { u64::MAX } else { u64::MAX / root_as_u64 } # If the candidate does not meet the target, try again if target < puzzle_target counter++ next return (counter, root) ``` -------------------------------- ### Add snarkvm dependency to Cargo.toml Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/README.md Add snarkvm as a library dependency in your Rust project's Cargo.toml. Replace .. with the desired published version. ```toml [dependencies] snarkvm = ".." ``` -------------------------------- ### Add snarkvm dependency with cuda feature Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/algorithms/cuda/README.md Adds the snarkvm crate as a dependency with the cuda feature enabled in Cargo.toml. ```toml [dependencies.snarkvm] version = "" features = ["cuda"] ``` -------------------------------- ### Resolve merge conflicts on the bot's pull request branch Source: https://github.com/aleo-labs-protocol/snarkvm/blob/staging/BRANCHING_AND_RELEASING.md Use when the merge bot reports conflicts on a release branch merge into staging. Fetch the remote, check out the bot's pull request branch (e.g., ci/merge-release/v4.13-into-staging), resolve conflicts, commit, and push to that branch. Do not push the resolution to the release branch. ```bash git fetch origin git checkout ci/merge-release/v4.13-into-staging # Resolve the conflicts, then commit. git push origin ci/merge-release/v4.13-into-staging ```