✨ SNOS ✨

A Rust Library for running the Starknet OS.

Report Bug · Request Feature

Table of Contents

• Table of Contents
• 📖 About
• 🛠️ Getting Started
  • Prerequisites
  • Installation
• 🧪 Running Tests
  • Run Tests
  • Reset Tests
• 🚀 Usage
  • Adding SNOS as a Dependency
  • Using the prove_block Binary
• 🤝 Related Projects
• 📚 Documentation
• 📜 License

📖 About

Starknet OS is a Cairo program designed to prove the integrity of state transitions between blocks on Starknet.

By re-executing transactions from a block and verifying consistency, it produces a PIE (Program Independent Execution) result. This PIE can be used to generate a STARK proof of integrity, which, if accepted by Starknet L1 verifiers, confirms block validity and updates the Starknet state root in the StarknetCore contract.

🛠️ Getting Started

Prerequisites

Ensure you have the following dependencies installed:

• Rust 1.76.0 or newer

Optional

• pyenv (recommended for managing Python versions and setting up environment)

• rclone (recommended for downloading Pathfinder's database and being able to quickly use prove_block binary)

Installation

1. Clone the Repository

Clone this repository and its submodules:

git clone https://github.com/keep-starknet-strange/snos.git --recursive

Install project dependencies

In order to compile the Starknet OS Cairo program, you’ll need the Cairo compiler:

• Follow the Cairo documentation
• Or simply run:

./setup-scripts/setup-cairo.sh

This will create a virtual environment and download needed dependencies to compile cairo programs. You will need to activate it to compile Cairo programs.

🧪 Running Tests

SNOS includes comprehensive end-to-end tests for PIE generation. Tests can be run using the convenient Makefile or directly with cargo.

Quick Start - Using Makefile

# Run quick integration tests (no RPC required)
make test-quick

# Check test environment
make env-check

# Run full e2e tests (requires RPC endpoint)
make test-e2e

# See all available test commands
make help

Test Categories

• Quick Integration Tests: Fast tests that verify workspace integration without requiring external RPC
• E2E PIE Generation Tests: Complete workflow tests that generate actual PIE files
• Error Handling Tests: Comprehensive error scenario testing
• Performance Tests: Timing and resource usage validation

Using Different RPC Endpoints

# Test against local Pathfinder instance
make test-e2e RPC_URL=http://localhost:9545

# Test against Sepolia testnet
make test-sepolia

# Test with verbose output
make test-pie VERBOSE=true

Legacy Test Setup

For the original Cairo test environment:

# Activate Cairo environment
source ./snos-env/bin/activate

# Set up tests
./scripts/setup-tests.sh

# Run workspace tests
cargo test --workspace

# Reset test environment if needed
./scripts/reset-tests.sh

🚀 Usage

Adding SNOS as a dependency

You can add the following to your rust project's Cargo.toml:

starknet-os = { git = "https://github.com/keep-starknet-strange/snos", rev = "662d1706f5855044e52ebf688a18dd80016c8700" }

Using the prove_block Binary

To execute correctly, SNOS requires detailed block information, including:

• State changes: Information about new classes, contracts, and any modifications to contract storage. (See StateDiff)
• Storage proofs: Merkle Proofs from both class and contract tries, needed for validating that updated values match the global state root.
• Transaction execution Information: Data on calls, subcalls, and specific program counters visited (VisitedPCs) during execution.

The prove_block binary handles this entire process by collecting, formatting, and feeding the necessary data into the OS, ensuring the correct OSInput is passed for execution.

To accomplish this, it queries the required information from a full node. Currently, Pathfinder is the only full node implementing all the necessary RPC methods, so a synced Pathfinder instance running as an archive node (to provide access to storage proofs) is required to execute this binary successfully.

For example, you can run Pathfinder executing:

PATHFINDER_ETHEREUM_API_URL="YOUR_KEY" ./target/release/pathfinder --data-directory /home/herman/pathfinder-data --http-rpc 0.0.0.0:9545 --storage.state-tries archive

Once you have a synced full node, you can start generating PIEs of a given block by running:

cargo run --release -p prove_block -- --block-number 200000 --rpc-provider http://0.0.0.0:9545

🤝 Related Projects

• cairo compiler: A blazing fast compiler for Cairo, written in Rust
• cairo vm: A faster and safer implementation of the Cairo VM in Rust
• blockifier: The transaction-executing component in the Starknet sequencer.
• pathfinder: A Starknet full node written in Rust
• madara: A powerful Starknet client written in Rust.

📚 Documentation

Cairo:

• The Cairo Book
• How Cairo Works
• Cairo – a Turing-complete STARK-friendly CPU architecture
• A Verified Algebraic Representation of Cairo Program Execution

Starknet

• Starknet Docs
  • Starknet State
• MoonsongLabs talk in StarknetCC

StarknetOS

• Pragma Article on os.cairo
• os.cairo code

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.