# keep-starknet-strange/snos architecture

> Architecture diagram of the GitHub repository keep-starknet-strange/snos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keep-starknet-strange/snos
- Repository: https://github.com/keep-starknet-strange/snos

## Overview

##### Project type and purpose
- This is a Rust workspace that provides:
- A core library (“crates/starknet-os”) implementing the Starknet OS logic in Rust
- Supporting libraries (e.g., “starknet-os-types”, “cairo-type-derive”)
- CLI tools (binaries under “crates/bin” such as **prove_block**, **hint_tool**, **output_segment**)
- An RPC client (“crates/rpc-client”) and an RPC replay helper (“crates/rpc-replay”)
- Purpose: re-execute Starknet transactions from a block, verify state transitions via the Cairo OS program, and produce a PIE (Program Independent Execution) for STARK proof generation.

##### File structure
- Top-level directories:
- **cairo-lang**: submodule for the Cairo compiler sources
- **crates/**: workspace members
– **starknet-os**: core OS logic (hints, syscalls, execution engine)
– **starknet-os-types**: data structures for contract classes, state diffs, hashes, etc.
– **rpc-client**: HTTP client targeting full nodes (Pathfinder)
– **rpc-replay**: builds OSInput from raw RPC data (state diffs, proofs, transactions)
– **bin/**: CLI entry points (prove_block, hint_tool, output_segment)
- **scripts/** & **setup-scripts/**: environment setup, test orchestration
- **tests/**: integration tests that exercise the entire flow
- Key config files:
- **Cargo.toml** & **rust-toolchain**: Rust workspace configuration
- **pyproject.toml**, **requirements.txt**: Python venv for Cairo compiler
- **.github/workflows/**: CI pipelines (lint, test, block proofs)

##### README for additional insights
- Describes the high-level flow: CLI → gather state/transaction data → feed the Starknet OS → produce PIE → STARK proof
- Highlights dependencies: Rust ≥1.76, a synced Pathfinder archive node, Cairo compiler environment
- Explains the **prove_block** binary end-to-end use case

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Service
    ExternalNode["Pathfinder RPC Service"]:::external

    %% CLI Tools
    subgraph "CLI Layer"
        direction TB
        ProveBlock["prove_block CLI"]:::cli
        RPCReplayCLI["rpc-replay Helper CLI"]:::cli
        HintTool["hint_tool CLI"]:::cli
        OutputSegment["output_segment CLI"]:::cli
        Cairo0Run["cairo0_run CLI"]:::cli
    end

    %% RPC Modules
    subgraph "RPC Modules"
        direction TB
        RPCClient["rpc-client Library"]:::library
        RPCReplay["rpc-replay Library"]:::library
    end

    %% Core Libraries
    subgraph "Core Libraries"
        direction TB
        TypesLib["starknet-os-types"]:::library
        DeriveMacro["cairo-type-derive"]:::library
        StarknetOS["starknet-os Core Library"]:::library
    end

    %% Environment
    subgraph "Cairo Compiler Environment"
        direction TB
        CairoLang["cairo-lang Submodule"]:::env
        PythonEnv["Python venv (pyproject.toml, requirements.txt)"]:::env
    end

    %% Artifacts
    PIE["PIE (Program Independent Execution)"]:::artifact
    Segments["Formatted Segments"]:::artifact

    %% Testing & Config
    subgraph "Support & CI"
        direction TB
        IntegrationTests["Integration Tests Harness"]:::support
        WorkspaceConfig["Workspace Config (Cargo.toml, rust-toolchain)"]:::support
        CI["CI Pipelines (.github/workflows)"]:::support
        Scripts["Scripts & Setup-Scripts"]:::support
    end

    %% Data Flows
    ProveBlock -->|fetch RPC data| RPCClient
    RPCClient -->|RPC calls| ExternalNode
    RPCClient -->|return raw data| RPCReplay
    RPCReplayCLI -->|invoke replay| RPCReplay
    RPCReplay -->|build OSInput| StarknetOS
    StarknetOS -->|loads Cairo OS program| CairoLang
    StarknetOS -->|executes with Python| PythonEnv
    StarknetOS -->|produces| PIE
    OutputSegment -->|consume PIE| PIE
    OutputSegment -->|produce| Segments
    HintTool -->|analyze| PIE
    Cairo0Run -->|execute| StarknetOS

    %% Testing & Config connections
    ProveBlock --> IntegrationTests
    IntegrationTests --> WorkspaceConfig
    IntegrationTests --> CI
    IntegrationTests --> Scripts

    %% Click Events
    click StarknetOS "https://github.com/keep-starknet-strange/snos/tree/main/crates/starknet-os"
    click TypesLib "https://github.com/keep-starknet-strange/snos/tree/main/crates/starknet-os-types"
    click DeriveMacro "https://github.com/keep-starknet-strange/snos/tree/main/crates/cairo-type-derive"
    click ProveBlock "https://github.com/keep-starknet-strange/snos/blob/main/crates/bin/prove_block/src/main.rs"
    click OutputSegment "https://github.com/keep-starknet-strange/snos/blob/main/crates/bin/output_segment/src/main.rs"
    click HintTool "https://github.com/keep-starknet-strange/snos/blob/main/crates/bin/hint_tool/src/main.rs"
    click Cairo0Run "https://github.com/keep-starknet-strange/snos/blob/main/crates/bin/cairo0_run/src/main.rs"
    click RPCClient "https://github.com/keep-starknet-strange/snos/blob/main/crates/rpc-client/src/lib.rs"
    click RPCClient "https://github.com/keep-starknet-strange/snos/blob/main/crates/rpc-client/src/client.rs"
    click RPCClient "https://github.com/keep-starknet-strange/snos/tree/main/crates/rpc-client/src/pathfinder/"
    click RPCReplay "https://github.com/keep-starknet-strange/snos/blob/main/crates/rpc-replay/src/lib.rs"
    click RPCReplay "https://github.com/keep-starknet-strange/snos/blob/main/crates/rpc-replay/src/block_context.rs"
    click RPCReplay "https://github.com/keep-starknet-strange/snos/blob/main/crates/rpc-replay/src/rpc_state_reader.rs"
    click RPCReplay "https://github.com/keep-starknet-strange/snos/blob/main/crates/rpc-replay/src/transactions.rs"
    click RPCReplay "https://github.com/keep-starknet-strange/snos/blob/main/crates/rpc-replay/src/utils.rs"
    click CairoLang "https://github.com/keep-starknet-strange/snos/tree/main/cairo-lang/"
    click IntegrationTests "https://github.com/keep-starknet-strange/snos/tree/main/tests/integration/"
    click IntegrationTests "https://github.com/keep-starknet-strange/snos/tree/main/tests/integration/common/"
    click WorkspaceConfig "https://github.com/keep-starknet-strange/snos/blob/main/Cargo.toml"
    click WorkspaceConfig "https://github.com/keep-starknet-strange/snos/tree/main/rust-toolchain"
    click PythonEnv "https://github.com/keep-starknet-strange/snos/blob/main/pyproject.toml"
    click PythonEnv "https://github.com/keep-starknet-strange/snos/blob/main/requirements.txt"
    click CI "https://github.com/keep-starknet-strange/snos/blob/main/.github/workflows/check.yml"
    click CI "https://github.com/keep-starknet-strange/snos/blob/main/.github/workflows/prove_blocks.yml"
    click Scripts "https://github.com/keep-starknet-strange/snos/tree/main/scripts/"
    click Scripts "https://github.com/keep-starknet-strange/snos/tree/main/setup-scripts/"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef library fill:#d4edda,stroke:#28a745,color:#000;
    classDef external fill:#fff3cd,stroke:#ffcc00,color:#000;
    classDef env fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef artifact fill:#f8f9fa,stroke:#adb5bd,color:#000,shape:cylinder;
    classDef support fill:#f1f3f5,stroke:#868e96,color:#000;
```
