Merge pull request #242 from HerodotusDev/docs_codebase_refactor

Docs codebase refactor

Author: Okm165

.github/workflows/build-cli.yml

@@ -33,7 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: true
 
@@ -92,7 +92,7 @@ jobs:
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: true
 
@@ -103,9 +103,11 @@ jobs:
 
       - name: Set up Rust
         uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: nightly-2025-04-06
 
       - name: Cargo Cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             ~/.cargo/bin/
@@ -146,7 +148,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: true
 
@@ -157,9 +159,11 @@ jobs:
 
       - name: Set up Rust
         uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: nightly-2025-04-06
 
       - name: Cargo Cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             ~/.cargo/bin

.github/workflows/mdbook.yaml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: true
 
@@ -30,9 +30,11 @@ jobs:
 
       - name: Set up Rust
         uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: nightly-2025-04-06
 
       - name: Cargo Cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             ~/.cargo/bin

.github/workflows/rust-vm.yaml

@@ -1,10 +1,20 @@
 name: rust-vm-CI
 
 on:
+  workflow_dispatch:
+  pull_request:
   push:
     branches:
       - "**"
 
+env:
+  RUST_BACKTRACE: 1
+  CARGO_TERM_COLOR: always
+
+concurrency:
+  group: "${{ github.workflow }}-${{ github.ref }}"
+  cancel-in-progress: true
+
 jobs:
   check:
     name: Format and Lint
@@ -16,7 +26,7 @@ jobs:
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: true
 
@@ -27,6 +37,8 @@ jobs:
 
       - name: Set up Rust
         uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: nightly-2025-04-06
 
       - name: Cargo cache
         uses: actions/cache@v4
@@ -57,10 +69,13 @@ jobs:
         run: .venv/bin/cairo-format -c src/*.cairo
 
       - name: Run clippy check
-        run: cargo clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+
+      - name: Future incompatibility report
+        run: cargo report future-incompatibilities
 
   test:
-    name: Run Tests
+    name: Run Tests (stable / offline)
     strategy:
       fail-fast: false
       matrix:
@@ -69,7 +84,7 @@ jobs:
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: true
 
@@ -80,10 +95,65 @@ jobs:
 
       - name: Set up Rust
         uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: nightly-2025-04-06
+      
+      - name: Set up Scarb
+        uses: software-mansion/setup-scarb@v1
+
+      - name: Cargo cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            target/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Set up Cairo (Linux)
+        if: runner.os == 'Linux'
+        run: uv sync
+
+      - name: Set up Cairo (macOS)
+        if: runner.os == 'macOS'
+        run: CFLAGS=-I/opt/homebrew/opt/gmp/include LDFLAGS=-L/opt/homebrew/opt/gmp/lib uv sync
+
+      - name: Build Test Contracts
+        run: scarb build
+
+      - name: Run cargo tests (stable)
+        run: cargo test --workspace --all-targets
+
+  integration:
+    name: Run Integration Tests (optional / requires secrets)
+    if: ${{ secrets.RPC_URL_HERODOTUS_INDEXER != '' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: nightly-2025-04-06
 
       - name: Install Nextest
         uses: taiki-e/install-action@nextest
-      
+
       - name: Set up Scarb
         uses: software-mansion/setup-scarb@v1
 
@@ -109,13 +179,14 @@ jobs:
       - name: Build Test Contracts
         run: scarb build
 
-      - name: Run Nextest Tests
+      - name: Run Nextest Tests (integration)
         env:
+          HDP_INTEGRATION_TESTS: "1"
           RPC_URL_ETHEREUM_MAINNET: ${{ secrets.RPC_URL_ETHEREUM_MAINNET }}
           RPC_URL_ETHEREUM_TESTNET: ${{ secrets.RPC_URL_ETHEREUM_TESTNET }}
           RPC_URL_HERODOTUS_INDEXER: ${{ secrets.RPC_URL_HERODOTUS_INDEXER }}
           RPC_URL_STARKNET_MAINNET: ${{ secrets.RPC_URL_STARKNET_MAINNET }}
           RPC_URL_STARKNET_TESTNET: ${{ secrets.RPC_URL_STARKNET_TESTNET }}
           RPC_URL_OPTIMISM_MAINNET: ${{ secrets.RPC_URL_OPTIMISM_MAINNET }}
-          RPC_URL_OPTIMISM_SEPOLIA: ${{ secrets.RPC_URL_OPTIMISM_SEPOLIA }}
+          RPC_URL_OPTIMISM_TESTNET: ${{ secrets.RPC_URL_OPTIMISM_TESTNET }}
         run: cargo nextest run --profile ci

.gitignore

@@ -33,13 +33,14 @@ dist/
 # --- IDEs ---
 .idea/
 .vscode/
+.cursor/
 
 # --- Whitelist ---
 # Keep specific files that would otherwise be ignored
 !example.env
 !packages/cairo-lang-0.13.3.zip
 !examples/**/*.json
-!crates/server/tests/*.json
+!crates/state_server/tests/*.json
 
 # State server db folder
 crates/state_server/db

Cargo.lock

@@ -22,12 +22,10 @@ alloy = { version = "1.0", features = ["full"] }
 alloy-rlp = { version = "0.3", features = ["derive"] }
 alloy-trie = { version = "0.9", features = ["ethereum", "serde"] }
 anyhow = "1.0.100"
-api = { path = "src/crates/api" }
 axum = { version = "0.8", features = ["tracing"] }
 bincode = "2.0.1"
 bitvec = "1.0.1"
 bytemuck = { version = "1.20", features = ["derive"] }
-cairo_runner = { path = "src/crates/cairo-runner" }
 cairo_type_derive = { path = "crates/cairo_type_derive" }
 cairo-lang-casm = "2.12.3"
 cairo-lang-starknet-classes = "2.12.3"
@@ -88,3 +86,16 @@ utoipa = { version = "5.3.1", features = ["axum_extras"] }
 utoipa-swagger-ui = { version = "9", features = ["axum"] }
 uuid = { version = "1.18.1", features = ["v4"] }
 version-compare = "0.2.0"
+
+[workspace.lints.rust]
+unsafe_code = "forbid"
+
+[workspace.lints.clippy]
+unwrap_used = "warn"
+expect_used = "warn"
+panic = "warn"
+redundant_closure_for_method_calls = "warn"
+cloned_instead_of_copied = "warn"
+too_many_arguments = "warn"
+type_complexity = "warn"
+large_enum_variant = "warn"

Cargo.toml

@@ -1,30 +1,76 @@
-FROM rust:1.89.0
+# syntax=docker/dockerfile:1.7
+FROM rust:1.89.0 AS builder
+
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 
 # Install uv, the Python package manager.
 COPY --from=ghcr.io/astral-sh/uv:0.8.13 /uv /uvx /bin/
 
 # Set the working directory for all subsequent commands.
 WORKDIR /hdp-cairo
 
+# Install the pinned nightly toolchain.
+ARG RUST_TOOLCHAIN=nightly-2025-04-06
+RUN rustup toolchain install "${RUST_TOOLCHAIN}" && rustup default "${RUST_TOOLCHAIN}"
+
 # Copy dependency files FIRST to leverage Docker's layer caching.
 # If these files don't change, Docker won't re-run the `uv sync` step.
+ENV PROJECT_ROOT=/hdp-cairo
 COPY pyproject.toml uv.lock ./
 COPY packages/cairo-lang-0.13.3.zip ./packages/cairo-lang-0.13.3.zip
 
 # Synchronize and install project dependencies using uv.
-RUN uv sync
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen
+
+# Pre-fetch Rust dependencies using workspace sources.
+COPY Cargo.toml Cargo.lock ./
+COPY crates/ ./crates/
+COPY tests/ ./tests/
+COPY packages/eth_essentials/cairo_vm_hints/ ./packages/eth_essentials/cairo_vm_hints/
+RUN --mount=type=cache,target=/usr/local/cargo/registry \
+    --mount=type=cache,target=/usr/local/cargo/git \
+    cargo fetch
 
 # Copy the rest of the application source code into the container.
 COPY . .
 
+# Precompile Cairo artifacts and set stable paths for the binary.
+ENV HDP_COMPILED_JSON=/opt/hdp/compiled.json
+ENV DRY_RUN_COMPILED_JSON=/opt/hdp/dry_run_compiled.json
+RUN mkdir -p /opt/hdp && \
+    .venv/bin/cairo-compile --cairo_path=/hdp-cairo:/hdp-cairo/packages/eth_essentials /hdp-cairo/src/hdp.cairo \
+      --output "$HDP_COMPILED_JSON" --proof_mode && \
+    .venv/bin/cairo-compile --cairo_path=/hdp-cairo:/hdp-cairo/packages/eth_essentials \
+      /hdp-cairo/src/contract_bootloader/contract_dry_run.cairo --output "$DRY_RUN_COMPILED_JSON"
+
 # Install the specific Rust binary from the local crate.
 # We use the `--locked` flag to ensure the build uses the exact versions
 # specified in Cargo.lock, for reproducibility.
-RUN cargo install --path ./crates/cli --locked
+RUN --mount=type=cache,target=/usr/local/cargo/registry \
+    --mount=type=cache,target=/usr/local/cargo/git \
+    cargo install --path ./crates/cli --locked
+
+FROM debian:trixie-slim
+
+RUN useradd --create-home --uid 10001 hdp && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /usr/local/cargo/bin/hdp-cli /usr/local/bin/hdp-cli
+COPY --from=builder --chown=hdp:hdp /opt/hdp /opt/hdp
+
+ENV HDP_COMPILED_JSON=/opt/hdp/compiled.json
+ENV DRY_RUN_COMPILED_JSON=/opt/hdp/dry_run_compiled.json
+
+USER hdp
 
 # Set the default executable for the container.
-ENTRYPOINT ["/hdp-cairo/target/release/hdp-cli"]
+ENTRYPOINT ["hdp-cli"]
 
 # Set the default command when the container is run without any arguments.
 # This provides a default action for the entrypoint.
-CMD ["program-hash"]
+CMD ["program-hash"]
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 CMD ["hdp-cli", "--version"]