Usc full refactor

ksew1 · ksew1 · commit 18f87cf666e2 · 2025-10-19T21:32:50.000+02:00
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/crates/cheatnet/src/runtime_extensions/forge_runtime_extension/cheatcodes/declare.rs b/crates/cheatnet/src/runtime_extensions/forge_runtime_extension/cheatcodes/declare.rs
@@ -68,11 +68,9 @@ pub fn get_class_hash(sierra_class: &SierraClass) -> Result<ClassHash> {
 }
 
 fn get_contract_class(contract_artifact: &StarknetContractArtifacts) -> RunnableCompiledClass {
-    let contract_class = CompiledClassV1::try_from_json_string(
-        &contract_artifact.casm,
-        get_current_sierra_version(),
-    )
-    .expect("Failed to read contract class from json");
+    let contract_class =
+        CompiledClassV1::try_from((contract_artifact.casm.clone(), get_current_sierra_version()))
+            .expect("Failed to read contract class from json");
 
     #[cfg(feature = "cairo-native")]
     return match &contract_artifact.executor {
diff --git a/crates/forge-runner/src/lib.rs b/crates/forge-runner/src/lib.rs
@@ -22,7 +22,7 @@ use std::sync::{Arc, Mutex};
 use test_case_summary::{AnyTestCaseSummary, Fuzzing};
 use tokio::sync::mpsc::{Sender, channel};
 use tokio::task::JoinHandle;
-use universal_sierra_compiler_api::AssembledProgramWithDebugInfo;
+use universal_sierra_compiler_api::representation::RawCasmProgram;
 
 pub mod build_trace_data;
 pub mod coverage_api;
@@ -106,7 +106,7 @@ pub fn maybe_generate_coverage(
 #[tracing::instrument(skip_all, level = "debug")]
 pub fn run_for_test_case(
     case: Arc<TestCaseWithResolvedConfig>,
-    casm_program: Arc<AssembledProgramWithDebugInfo>,
+    casm_program: Arc<RawCasmProgram>,
     forge_config: Arc<ForgeConfig>,
     versioned_program_path: Arc<Utf8PathBuf>,
     send: Sender<()>,
@@ -141,7 +141,7 @@ pub fn run_for_test_case(
 #[tracing::instrument(skip_all, level = "debug")]
 fn run_with_fuzzing(
     case: Arc<TestCaseWithResolvedConfig>,
-    casm_program: Arc<AssembledProgramWithDebugInfo>,
+    casm_program: Arc<RawCasmProgram>,
     forge_config: Arc<ForgeConfig>,
     versioned_program_path: Arc<Utf8PathBuf>,
     send: Sender<()>,
diff --git a/crates/forge-runner/src/package_tests.rs b/crates/forge-runner/src/package_tests.rs
@@ -19,7 +19,7 @@ use serde::Serialize;
 use starknet_types_core::felt::Felt;
 use std::collections::HashMap;
 use std::sync::Arc;
-use universal_sierra_compiler_api::AssembledProgramWithDebugInfo;
+use universal_sierra_compiler_api::representation::RawCasmProgram;
 
 pub mod raw;
 pub mod with_config;
@@ -66,10 +66,7 @@ impl TestDetails {
         builtins
     }
 
-    pub fn try_into_program(
-        &self,
-        casm_program: &AssembledProgramWithDebugInfo,
-    ) -> Result<Program> {
+    pub fn try_into_program(&self, casm_program: &RawCasmProgram) -> Result<Program> {
         let builtins = self.builtins();
 
         let assembled_program = &casm_program.assembled_cairo_program;
@@ -102,7 +99,7 @@ pub struct TestTarget<C> {
     pub tests_location: TestTargetLocation,
     pub sierra_program: ProgramArtifact,
     pub sierra_program_path: Arc<Utf8PathBuf>,
-    pub casm_program: Arc<AssembledProgramWithDebugInfo>,
+    pub casm_program: Arc<RawCasmProgram>,
     pub test_cases: Vec<TestCase<C>>,
 }
 
diff --git a/crates/forge-runner/src/package_tests/with_config_resolved.rs b/crates/forge-runner/src/package_tests/with_config_resolved.rs
@@ -6,7 +6,7 @@ use cheatnet::runtime_extensions::forge_config_extension::config::{
     RawAvailableResourceBoundsConfig, RawFuzzerConfig,
 };
 use starknet_api::block::BlockNumber;
-use universal_sierra_compiler_api::AssembledProgramWithDebugInfo;
+use universal_sierra_compiler_api::representation::RawCasmProgram;
 use url::Url;
 
 pub type TestTargetWithResolvedConfig = TestTarget<TestCaseResolvedConfig>;
@@ -29,10 +29,7 @@ impl TestCaseWithResolvedConfig {
         }
     }
 
-    pub fn try_into_program(
-        &self,
-        casm_program: &AssembledProgramWithDebugInfo,
-    ) -> Result<Program> {
+    pub fn try_into_program(&self, casm_program: &RawCasmProgram) -> Result<Program> {
         self.test_details.try_into_program(casm_program)
     }
 }
diff --git a/crates/forge-runner/src/running.rs b/crates/forge-runner/src/running.rs
@@ -43,7 +43,7 @@ use std::rc::Rc;
 use std::sync::{Arc, Mutex};
 use tokio::sync::mpsc::Sender;
 use tokio::task::JoinHandle;
-use universal_sierra_compiler_api::AssembledProgramWithDebugInfo;
+use universal_sierra_compiler_api::representation::RawCasmProgram;
 
 pub mod config_run;
 mod execution;
@@ -62,7 +62,7 @@ pub use syscall_handler::syscall_handler_offset;
 #[tracing::instrument(skip_all, level = "debug")]
 pub fn run_test(
     case: Arc<TestCaseWithResolvedConfig>,
-    casm_program: Arc<AssembledProgramWithDebugInfo>,
+    casm_program: Arc<RawCasmProgram>,
     forge_config: Arc<ForgeConfig>,
     versioned_program_path: Arc<Utf8PathBuf>,
     send: Sender<()>,
@@ -93,7 +93,7 @@ pub fn run_test(
 #[tracing::instrument(skip_all, level = "debug")]
 pub(crate) fn run_fuzz_test(
     case: Arc<TestCaseWithResolvedConfig>,
-    casm_program: Arc<AssembledProgramWithDebugInfo>,
+    casm_program: Arc<RawCasmProgram>,
     forge_config: Arc<ForgeConfig>,
     versioned_program_path: Arc<Utf8PathBuf>,
     send: Sender<()>,
@@ -159,7 +159,7 @@ pub enum RunResult {
 #[tracing::instrument(skip_all, level = "debug")]
 pub fn run_test_case(
     case: &TestCaseWithResolvedConfig,
-    casm_program: &AssembledProgramWithDebugInfo,
+    casm_program: &RawCasmProgram,
     runtime_config: &RuntimeConfig,
     fuzzer_rng: Option<Arc<Mutex<StdRng>>>,
     versioned_program_path: &Utf8Path,
diff --git a/crates/forge-runner/src/running/config_run.rs b/crates/forge-runner/src/running/config_run.rs
@@ -18,7 +18,7 @@ use starknet_api::block::{
 };
 use starknet_types_core::felt::Felt;
 use std::default::Default;
-use universal_sierra_compiler_api::AssembledProgramWithDebugInfo;
+use universal_sierra_compiler_api::representation::RawCasmProgram;
 
 struct PhantomStateReader;
 
@@ -61,7 +61,7 @@ impl StateReader for PhantomStateReader {
 #[tracing::instrument(skip_all, level = "debug")]
 pub fn run_config_pass(
     test_details: &TestDetails,
-    casm_program: &AssembledProgramWithDebugInfo,
+    casm_program: &RawCasmProgram,
     tracked_resource: &ForgeTrackedResource,
 ) -> Result<RawForgeConfig> {
     let program = test_details.try_into_program(casm_program)?;
diff --git a/crates/scarb-api/Cargo.toml b/crates/scarb-api/Cargo.toml
@@ -23,9 +23,11 @@ itertools.workspace = true
 universal-sierra-compiler-api = { path = "../universal-sierra-compiler-api" }
 foundry-ui = { path = "../foundry-ui" }
 cairo-native = { workspace = true, optional = true }
+cairo-lang-starknet-classes.workspace = true
 native-api = { path = "../native-api", optional = true }
 tracing.workspace = true
 
 [dev-dependencies]
 assert_fs.workspace = true
 indoc.workspace = true
+num-bigint.workspace = true
diff --git a/crates/scarb-api/src/artifacts.rs b/crates/scarb-api/src/artifacts.rs
@@ -1,6 +1,7 @@
 use anyhow::Result;
 
 use crate::artifacts::representation::StarknetArtifactsRepresentation;
+use cairo_lang_starknet_classes::casm_contract_class::CasmContractClass;
 #[cfg(feature = "cairo-native")]
 use cairo_native::executor::AotContractExecutor;
 use camino::{Utf8Path, Utf8PathBuf};
@@ -19,7 +20,7 @@ pub struct StarknetContractArtifacts {
     /// Compiled sierra code
     pub sierra: String,
     /// Compiled casm code
-    pub casm: String,
+    pub casm: CasmContractClass,
 
     #[cfg(feature = "cairo-native")]
     /// Optional AOT compiled native executor
@@ -106,7 +107,7 @@ impl StarknetArtifactsFiles {
     fn compile_artifact_at_path(&self, path: &Utf8Path) -> Result<StarknetContractArtifacts> {
         let sierra = fs::read_to_string(path)?;
 
-        let casm = serde_json::to_string(&compile_contract_sierra_at_path(path)?)?;
+        let casm = compile_contract_sierra_at_path(path)?;
 
         #[cfg(feature = "cairo-native")]
         let executor = self.compile_to_native(&sierra)?;
@@ -153,9 +154,11 @@ mod tests {
     use crate::tests::setup_package;
     use assert_fs::TempDir;
     use assert_fs::fixture::{FileWriteStr, PathChild};
+    use cairo_lang_starknet_classes::casm_contract_class::CasmContractEntryPoints;
     use camino::Utf8PathBuf;
     use deserialized::{StarknetArtifacts, StarknetContract, StarknetContractArtifactPaths};
     use indoc::indoc;
+    use num_bigint::BigUint;
 
     #[test]
     fn test_unique_artifacts() {
@@ -165,7 +168,15 @@ mod tests {
             (
                 StarknetContractArtifacts {
                     sierra: "sierra1".to_string(),
-                    casm: "casm1".to_string(),
+                    casm: CasmContractClass {
+                        prime: BigUint::default(),
+                        compiler_version: String::default(),
+                        bytecode: vec![],
+                        bytecode_segment_lengths: None,
+                        hints: vec![],
+                        pythonic_hints: None,
+                        entry_points_by_type: CasmContractEntryPoints::default(),
+                    },
                     #[cfg(feature = "cairo-native")]
                     executor: None,
                 },
diff --git a/crates/scarb-api/src/lib.rs b/crates/scarb-api/src/lib.rs
@@ -611,15 +611,13 @@ mod tests {
 
         let contract = contracts.get("ERC20").unwrap();
         assert_eq!(&sierra_contents_erc20, &contract.0.sierra);
-        assert!(!contract.0.casm.is_empty());
 
         let sierra_contents_erc20 = fs::read_to_string(
             temp.join("target/dev/basic_package_HelloStarknet.contract_class.json"),
         )
         .unwrap();
         let contract = contracts.get("HelloStarknet").unwrap();
         assert_eq!(&sierra_contents_erc20, &contract.0.sierra);
-        assert!(!contract.0.casm.is_empty());
     }
 
     #[test]
diff --git a/crates/sncast/src/helpers/scarb_utils.rs b/crates/sncast/src/helpers/scarb_utils.rs
@@ -175,7 +175,7 @@ pub fn build_and_load_artifacts(
             CompilationOpts::default()
         ).context("Failed to load artifacts. Make sure you have enabled sierra code generation in Scarb.toml")?
         .into_iter()
-        .map(|(name, (artifacts, _))| (name, CastStarknetContractArtifacts { sierra: artifacts.sierra, casm: artifacts.casm }))
+        .map(|(name, (artifacts, _))| (name, CastStarknetContractArtifacts { sierra: artifacts.sierra, casm: serde_json::to_string(&artifacts.casm).expect("valid serialization")  }))
         .collect())
     } else {
         let profile = &config.profile;
@@ -189,7 +189,7 @@ pub fn build_and_load_artifacts(
             CompilationOpts::default(),
         ).context("Failed to load artifacts. Make sure you have enabled sierra code generation in Scarb.toml")?
         .into_iter()
-        .map(|(name, (artifacts, _))| (name, CastStarknetContractArtifacts { sierra: artifacts.sierra, casm: artifacts.casm }))
+        .map(|(name, (artifacts, _))| (name, CastStarknetContractArtifacts { sierra: artifacts.sierra, casm: serde_json::to_string(&artifacts.casm).expect("valid serialization") }))
         .collect())
     }
 }
diff --git a/crates/universal-sierra-compiler-api/src/command.rs b/crates/universal-sierra-compiler-api/src/command.rs
@@ -7,6 +7,7 @@ use std::{
 };
 use thiserror::Error;
 
+/// Errors that can occur while working with `universal-sierra-compiler` command.
 #[derive(Debug, Error)]
 pub enum USCError {
     #[error(
@@ -23,15 +24,14 @@ pub enum USCError {
     RunFailed(#[source] CommandError),
 }
 
-/// A builder for `universal-sierra-compiler` command invocation.
+/// An internal builder for `universal-sierra-compiler` command invocation.
 #[derive(Debug)]
 pub struct USCInternalCommand {
     inner: Command,
 }
 
 impl USCInternalCommand {
-    /// Creates a default `universal-sierra-compiler` command,
-    /// which will look for `universal-sierra-compiler` in `$PATH`
+    /// Creates a new `universal-sierra-compiler` command builder.
     pub fn new() -> Result<Self, USCError> {
         ensure_available()?;
         let mut cmd = Command::new(binary_path());
@@ -45,12 +45,13 @@ impl USCInternalCommand {
         self
     }
 
-    /// Build executable `universal-sierra-compiler` command.
+    /// Returns the constructed [`Command`].
     #[must_use]
     pub fn command(self) -> Command {
         self.inner
     }
 
+    /// Runs the `universal-sierra-compiler` command and returns the [`Output`].
     pub fn run(self) -> Result<Output, USCError> {
         self.command().output_checked().map_err(USCError::RunFailed)
     }
diff --git a/crates/universal-sierra-compiler-api/src/compile.rs b/crates/universal-sierra-compiler-api/src/compile.rs
@@ -7,6 +7,7 @@ use strum_macros::Display;
 use tempfile::Builder;
 use thiserror::Error;
 
+/// Errors that can occur during Sierra compilation.
 #[derive(Debug, Error)]
 pub enum CompilationError {
     #[error("Failed to write Sierra JSON to temp file: {0}")]
@@ -29,6 +30,7 @@ pub enum SierraType {
     Raw,
 }
 
+/// Compiles the given Sierra JSON into the specified type using the `universal-sierra-compiler`.
 pub fn compile_sierra(
     sierra_json: &Value,
     sierra_type: SierraType,
@@ -43,6 +45,7 @@ pub fn compile_sierra(
     compile_sierra_at_path(utf8_path, sierra_type)
 }
 
+/// Compiles the Sierra file at the given path into the specified type using the `universal-sierra-compiler`.
 #[tracing::instrument(skip_all, level = "debug")]
 pub fn compile_sierra_at_path(
     sierra_file_path: &Utf8Path,
diff --git a/crates/universal-sierra-compiler-api/src/lib.rs b/crates/universal-sierra-compiler-api/src/lib.rs
@@ -1,3 +1,10 @@
+//! API for compiling Sierra programs using the `universal-sierra-compiler` (USC).
+//!
+//! This crate provides functions to compile Sierra JSON representations of contracts and raw programs into their respective Casm formats.
+//!
+//! # Note:
+//! To allow more flexibility when changing internals, please make public as few items as possible.
+
 use crate::command::{USCError, USCInternalCommand};
 use crate::compile::{CompilationError, SierraType, compile_sierra, compile_sierra_at_path};
 use crate::representation::RawCasmProgram;
@@ -10,35 +17,37 @@ mod command;
 mod compile;
 pub mod representation;
 
-pub type AssembledProgramWithDebugInfo = RawCasmProgram;
-
-pub type CasmCodeOffset = usize;
-pub type CasmInstructionIdx = usize;
-
+/// Compiles Sierra JSON of a contract into [`CasmContractClass`].
 pub fn compile_contract_sierra(sierra_json: &Value) -> Result<CasmContractClass, CompilationError> {
     let json = compile_sierra(sierra_json, SierraType::Contract)?;
     serde_json::from_str(&json).map_err(CompilationError::Deserialization)
 }
 
+/// Compiles Sierra JSON file at the given path of a contract into [`CasmContractClass`].
 pub fn compile_contract_sierra_at_path(
     sierra_file_path: &Utf8Path,
 ) -> Result<CasmContractClass, CompilationError> {
     let json = compile_sierra_at_path(sierra_file_path, SierraType::Contract)?;
     serde_json::from_str(&json).map_err(CompilationError::Deserialization)
 }
 
+/// Compiles Sierra JSON of a raw program into [`RawCasmProgram`].
 pub fn compile_raw_sierra(sierra_json: &Value) -> Result<RawCasmProgram, CompilationError> {
     let json = compile_sierra(sierra_json, SierraType::Raw)?;
     serde_json::from_str(&json).map_err(CompilationError::Deserialization)
 }
 
+/// Compiles Sierra JSON file at the given path of a raw program into [`RawCasmProgram`].
 pub fn compile_raw_sierra_at_path(
     sierra_file_path: &Utf8Path,
 ) -> Result<RawCasmProgram, CompilationError> {
     let json = compile_sierra_at_path(sierra_file_path, SierraType::Raw)?;
     serde_json::from_str(&json).map_err(CompilationError::Deserialization)
 }
 
+/// Creates a `universal-sierra-compiler --version` command.
+///
+/// Only exists because of how requirements checker was implemented.
 pub fn version_command() -> Result<Command, USCError> {
     Ok(USCInternalCommand::new()?.arg("--version").command())
 }

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ use cheatnet::runtime_extensions::forge_config_extension::config::{`
`6`	`6`	`RawAvailableResourceBoundsConfig, RawFuzzerConfig,`
`7`	`7`	`};`
`8`	`8`	`use starknet_api::block::BlockNumber;`
`9`		`-use universal_sierra_compiler_api::AssembledProgramWithDebugInfo;`
	`9`	`+use universal_sierra_compiler_api::representation::RawCasmProgram;`
`10`	`10`	`use url::Url;`
`11`	`11`
`12`	`12`	`pub type TestTargetWithResolvedConfig = TestTarget<TestCaseResolvedConfig>;`
`@@ -29,10 +29,7 @@ impl TestCaseWithResolvedConfig {`
`29`	`29`	`}`
`30`	`30`	`}`
`31`	`31`
`32`		`- pub fn try_into_program(`
`33`		`- &self,`
`34`		`- casm_program: &AssembledProgramWithDebugInfo,`
`35`		`- ) -> Result<Program> {`
	`32`	`+ pub fn try_into_program(&self, casm_program: &RawCasmProgram) -> Result<Program> {`
`36`	`33`	`self.test_details.try_into_program(casm_program)`
`37`	`34`	`}`
`38`	`35`	`}`
Original file line number	Diff line number	Diff line change
`@@ -611,15 +611,13 @@ mod tests {`
`611`	`611`
`612`	`612`	`let contract = contracts.get("ERC20").unwrap();`
`613`	`613`	`assert_eq!(&sierra_contents_erc20, &contract.0.sierra);`
`614`		`- assert!(!contract.0.casm.is_empty());`
`615`	`614`
`616`	`615`	`let sierra_contents_erc20 = fs::read_to_string(`
`617`	`616`	`temp.join("target/dev/basic_package_HelloStarknet.contract_class.json"),`
`618`	`617`	`)`
`619`	`618`	`.unwrap();`
`620`	`619`	`let contract = contracts.get("HelloStarknet").unwrap();`
`621`	`620`	`assert_eq!(&sierra_contents_erc20, &contract.0.sierra);`
`622`		`- assert!(!contract.0.casm.is_empty());`
`623`	`621`	`}`
`624`	`622`
`625`	`623`	`#[test]`