Introduction

Stwo is a next-generation zkVM framework that brings several innovative features to the zero-knowledge proof ecosystem:

Leverages Circle STARKs over the Mersenne31 prime field for fast prover performance
Seamlessly integrated with Cairo
Features efficient lookup tables with LogUp (future integration with GKR)

This documentation will guide you through understanding and using Stwo, from basic concepts to advanced features.

Quickstart

The fastest way to get started with Stwo is to use the stwo-cairo repository:

git clone https://github.com/starkware-libs/stwo-cairo
cd stwo-cairo

⚠️ Note: Stwo, the proof system used by Stwo-Cairo, is currently under active development. The API and features may change frequently, and the system is not yet cryptographically sound. Use it for testing and experimentation only.

Getting Started with Proofs

After running a Cairo program, you'll get four important files:

air_public_inputs.json: Contains publicly verifiable information
air_private_inputs.json: Contains private computation details
trace.bin: Records the program's execution steps
memory.bin: Stores the program's memory state

To generate a proof, use the adapted_stwo command:

cargo run --bin adapted_stwo --release \
--pub_json <path_to_air_public_input> \
--priv_json <path_to_air_private_input> \
--proof_path <path for proof output>

For optimal performance, add these flags:

RUSTFLAGS="-C target-cpu=native -C opt-level=3" --features="std"

Creating Your First Cairo Executable

Setup Requirements

Install Scarb (Cairo's package manager) using asdf. Use version 2.10.0 or later:

asdf global scarb 2.10.0

asdf global scarb latest:nightly

Creating a Project

Start a new project:

scarb new <project_name>

Configure your Scarb.toml file:

[package]
name = "my_project"
version = "0.1.0"
edition = "2024_07"

[[target.executable]]

[cairo]
enable-gas = false

[dependencies]
cairo_execute = "2.10.0"

Create a simple program in src/lib.cairo:

#[executable]
fn main(num: u8) -> u8 {
    num
}

Run your program:

scarb execute -p my_project --print-program-output --arguments 5

Execution Options

You can run your program in two modes:

standalone: Direct execution and proving (default)
bootloader: Execution resulting in a PIE, or Position Independent Executable. This cannot be proved by itself, must be provided as input to a bootloader program.

Use the --target flag to specify your mode:

scarb execute --target standalone  # or bootloader

Input Formats

Inputs are provided as comma-separated values. Here are some examples:

For fn main(num: u8): Use --arguments 1
For fn main(num1: u8, num2: u16): Use --arguments 1,2
For fn main(num1: u8, tuple: (u16, u16)): Use --arguments 1,2,3

More info about serialization of cairo types can be found here

When using the --arguments-file flag, the arguments should be represented as hex strings. For example, 1,2,3 in the above example becomes ["0x1", "0x2", "0x3"].

Current Limitations

Gas tracking must be disabled <- only used for Starknet smart contracts
System calls (syscalls) are not supported <- this means no external calls to other contracts are allowed (e.g. corelib functions)
Execution steps are currently padded for optimization <- only applies for standalone target,

Using Scarb for Proofs

From Scarb 2.10.0, you can generate proofs directly:

Run your program:

scarb execute

Generate a proof:

scarb prove --execution_id 1

Verify the proof:

scarb verify <path_to_proof_json>

Your proofs will be stored in ./target/execute/<package_name>/execution<N>/proof/.

You can also verify a proof using scarb:

scarb verify <path_to_proof_json>

Troubleshooting

Stwo As a Universal AIR Prover/Verifier

Stwo is designed as a universal framework for proving and verifying Algebraic Intermediate Representations (AIRs). This chapter explains how Stwo serves as a foundation for various zero-knowledge proof applications.

Universal AIR Framework

Stwo provides a flexible framework that allows developers to:

Define custom AIRs for specific computational tasks
Leverage optimized proving mechanisms
Utilize efficient lookup tables
Compose multiple AIRs together

Core Components

The universal AIR framework consists of:

AIR Definition Layer
- Custom constraint systems
- Trace generation
- Polynomial commitments
Proving Layer
- Circle STARK proving system
- Efficient Mersenne31 field operations
- Lookup table optimizations
Verification Layer

How to Write an AIR using Stwo Abstractions

This guide walks through the process of creating a custom AIR using Stwo's abstractions and tools.

AIR Structure

An AIR in Stwo consists of:

Trace columns
Transition constraints
Boundary constraints
Lookup tables (optional)

Best Practices

When writing an AIR:

Keep constraints simple and modular
Use lookup tables for repeated patterns
Optimize field operations
Consider composition with other AIRs

Simple M31 AIR Example

This chapter presents a complete example of implementing a simple AIR over the Mersenne31 field.

Column Definition: Single column for the sequence values
Transition Constraint: Each value is the square of the previous
Boundary Constraint: Sets the initial value
Proving: Generates a proof of the sequence
Verification: Checks the proof's validity

Lookup Abstraction

Stwo provides powerful abstractions for implementing efficient lookup tables in AIRs.

Overview

Lookup tables in Stwo allow for:

Efficient verification of value membership
Reduced polynomial degree
Composition of multiple tables
(planned)GKR integration

Performance Considerations

Table size vs. proof size tradeoffs
Optimal table composition strategies
Memory usage optimization
Lookup batch processing

Separate OpCode, Separate AIRs

This chapter explains how Stwo enables composition of multiple AIRs, particularly useful for complex computations with distinct operations.

AIR Composition

Stwo allows you to:

Define separate AIRs for different operations
Compose them efficiently
Maintain modularity and reusability

Benefits of Separation

Modularity
- Each operation has its own AIR
- Easier to test and verify
- Simpler to maintain
Optimization
- Specialized constraints per operation
- Efficient lookup table usage
- Better proof composition
Flexibility
- Mix and match operations
- Add new operations easily
- Reuse existing AIRs

Cairo

How Cairo AIR is built on top of Stwo. Maybe compare with stone prover implementation?

Builtins

go through an example of XOR builtin

AIR

Link to ethSTARK paper on definition of AIRs
go through example of Poseidon & Blake for how Stwo implements AIRs
Dynamic AIRs?

Circle STARKs & Circle FRI

TODO: Refer to Leo's paper?

Lookups

logUp
GKR

stwo-book