✨ 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

To verify your setup, follow these steps:

Activate snos-env:

 source ./snos-env/bin/activate

Run Tests

./scripts/setup-tests.sh

cargo test

Reset Tests

If you need to reset the test environment:

./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.