refactor(rpc): Cartridge Controller deployment layer

bin/katana/src/cli/rpc/starknet.rs

@@ -5,7 +5,7 @@ use clap::{Args, Subcommand};
 use katana_primitives::block::{BlockHash, BlockIdOrTag, BlockNumber, ConfirmedBlockIdOrTag};
 use katana_primitives::class::ClassHash;
 use katana_primitives::contract::StorageKey;
-use katana_primitives::execution::{EntryPointSelector, FunctionCall};
+use katana_primitives::execution::{Call, EntryPointSelector};
 use katana_primitives::transaction::TxHash;
 use katana_primitives::{ContractAddress, Felt};
 use katana_rpc_types::event::{EventFilter, EventFilterWithPage, ResultPageRequest};
@@ -398,8 +398,7 @@ impl StarknetCommands {
                 let entry_point_selector = args.selector;
                 let calldata = args.calldata;
 
-                let function_call =
-                    FunctionCall { contract_address, entry_point_selector, calldata };
+                let function_call = Call { contract_address, entry_point_selector, calldata };
 
                 let block_id = args.block.0;
                 let result = client.call(function_call, block_id).await?;

crates/cartridge/Cargo.toml

@@ -10,10 +10,11 @@ build = "build.rs"
 katana-contracts.workspace = true
 katana-genesis.workspace = true
 katana-primitives.workspace = true
-katana-rpc-types = { path = "../rpc/rpc-types" }
+katana-rpc-types = { workspace = true  }
 
 anyhow.workspace = true
 ark-ff = "0.4.2"
+cainome-cairo-serde.workspace = true
 lazy_static.workspace = true
 reqwest.workspace = true
 serde.workspace = true

crates/cartridge/src/client.rs → crates/cartridge/src/api.rs

@@ -17,12 +17,12 @@ pub enum Error {
 
 /// Client for interacting with the Cartridge service.
 #[derive(Debug, Clone)]
-pub struct Client {
+pub struct CartridgeApiClient {
     url: Url,
     client: reqwest::Client,
 }
 
-impl Client {
+impl CartridgeApiClient {
     /// Creates a new [`CartridgeApiClient`] with the given URL.
     pub fn new(url: Url) -> Self {
         Self { url, client: reqwest::Client::new() }

crates/cartridge/src/lib.rs

@@ -1,15 +1,14 @@
 #![cfg_attr(not(test), warn(unused_crate_dependencies))]
 
-pub mod client;
+pub mod api;
 pub mod vrf;
 
-pub use client::Client;
-pub use vrf::{
-    bootstrap_vrf, get_vrf_account, resolve_executable, wait_for_http_ok, InfoResponse,
-    RequestContext, SignedOutsideExecution, VrfAccountCredentials, VrfBootstrap,
-    VrfBootstrapConfig, VrfBootstrapResult, VrfClient, VrfClientError, VrfOutsideExecution,
-    VrfService, VrfServiceConfig, VrfServiceProcess, VRF_ACCOUNT_SALT, VRF_CONSUMER_SALT,
-    VRF_HARDCODED_SECRET_KEY, VRF_SERVER_PORT,
+pub use api::CartridgeApiClient;
+pub use vrf::server::{
+    bootstrap_vrf, get_vrf_account, resolve_executable, wait_for_http_ok, VrfAccountCredentials,
+    VrfBootstrap, VrfBootstrapConfig, VrfBootstrapResult, VrfServer, VrfServerConfig,
+    VrfServiceProcess, VRF_ACCOUNT_SALT, VRF_CONSUMER_SALT, VRF_HARDCODED_SECRET_KEY,
+    VRF_SERVER_PORT,
 };
 
 #[rustfmt::skip]

crates/cartridge/src/vrf/client.rs

@@ -1,6 +1,9 @@
-use katana_primitives::Felt;
+use cainome_cairo_serde::CairoSerde;
+use katana_primitives::execution::Call;
+use katana_primitives::{ContractAddress, Felt};
 use katana_rpc_types::outside_execution::{OutsideExecutionV2, OutsideExecutionV3};
 use serde::{Deserialize, Serialize};
+use starknet::macros::selector;
 use url::Url;
 
 #[derive(Debug, Default, Clone, serde::Serialize, serde::Deserialize)]
@@ -25,11 +28,30 @@ pub enum VrfOutsideExecution {
 /// A signed outside execution request.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SignedOutsideExecution {
-    pub address: Felt,
+    pub address: ContractAddress,
     pub outside_execution: VrfOutsideExecution,
     pub signature: Vec<Felt>,
 }
 
+impl From<SignedOutsideExecution> for Call {
+    fn from(value: SignedOutsideExecution) -> Self {
+        let (entry_point_selector, mut calldata) = match &value.outside_execution {
+            VrfOutsideExecution::V2(v) => {
+                let calldata = OutsideExecutionV2::cairo_serialize(v);
+                (selector!("execute_from_outside_v2"), calldata)
+            }
+            VrfOutsideExecution::V3(v) => {
+                let calldata = OutsideExecutionV3::cairo_serialize(v);
+                (selector!("execute_from_outside_v3"), calldata)
+            }
+        };
+
+        calldata.extend(value.signature);
+
+        Call { contract_address: value.address, entry_point_selector, calldata }
+    }
+}
+
 /// Response from GET /info endpoint.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct InfoResponse {

crates/cartridge/src/vrf/mod.rs

@@ -1,181 +1,6 @@
-//! VRF (Verifiable Random Function) support for Cartridge.
-//!
-//! This module provides:
-//! - VRF client for communicating with the VRF server
-//! - Bootstrap logic for deploying VRF contracts
-//! - Sidecar process management
+//! Cartridge VRF (Verifiable Random Function) service.
 
-mod bootstrap;
 mod client;
+pub mod server;
 
-use std::net::{IpAddr, Ipv4Addr, SocketAddr};
-use std::path::{Path, PathBuf};
-use std::process::Stdio;
-use std::time::{Duration, Instant};
-use std::{env, io};
-
-pub use bootstrap::{
-    bootstrap_vrf, get_vrf_account, VrfAccountCredentials, VrfBootstrap, VrfBootstrapConfig,
-    VrfBootstrapResult, BOOTSTRAP_TIMEOUT, VRF_ACCOUNT_SALT, VRF_CONSUMER_SALT,
-    VRF_HARDCODED_SECRET_KEY,
-};
 pub use client::*;
-use katana_primitives::{ContractAddress, Felt};
-use tokio::process::{Child, Command};
-use tokio::time::sleep;
-use tracing::{debug, info, warn};
-use url::Url;
-
-const LOG_TARGET: &str = "katana::cartridge::vrf::sidecar";
-
-pub const VRF_SERVER_PORT: u16 = 3000;
-const DEFAULT_VRF_SERVICE_PATH: &str = "vrf-server";
-pub const SIDECAR_TIMEOUT: Duration = Duration::from_secs(10);
-
-#[derive(Debug, thiserror::Error)]
-pub enum Error {
-    #[error("bootstrap_result not set - call bootstrap() or bootstrap_result()")]
-    BootstrapResultNotSet,
-    #[error("sidecar binary not found at {0}")]
-    BinaryNotFound(PathBuf),
-    #[error("sidecar binary '{0}' not found in PATH")]
-    BinaryNotInPath(PathBuf),
-    #[error("PATH environment variable is not set")]
-    PathNotSet,
-    #[error("failed to spawn VRF sidecar")]
-    Spawn(#[source] io::Error),
-    #[error("VRF sidecar did not become ready before timeout")]
-    SidecarTimeout,
-    #[error("bootstrap failed")]
-    Bootstrap(#[source] anyhow::Error),
-}
-
-pub type Result<T, E = Error> = std::result::Result<T, E>;
-
-#[derive(Debug, Clone)]
-pub struct VrfServiceConfig {
-    pub vrf_account_address: ContractAddress,
-    pub vrf_private_key: Felt,
-    pub secret_key: u64,
-}
-
-#[derive(Debug, Clone)]
-pub struct VrfService {
-    config: VrfServiceConfig,
-    path: PathBuf,
-}
-
-impl VrfService {
-    pub fn new(config: VrfServiceConfig) -> Self {
-        Self { config, path: PathBuf::from(DEFAULT_VRF_SERVICE_PATH) }
-    }
-
-    /// Sets the path to the vrf service program.
-    ///
-    /// If no path is set, the default executable name [`DEFAULT_VRF_SERVICE_PATH`] will be used.
-    pub fn path<T: Into<PathBuf>>(mut self, path: T) -> Self {
-        self.path = path.into();
-        self
-    }
-
-    pub async fn start(self) -> Result<VrfServiceProcess> {
-        let bin = resolve_executable(&self.path)?;
-
-        let mut command = Command::new(bin);
-        command
-            .arg("--port")
-            .arg(VRF_SERVER_PORT.to_string())
-            .arg("--account-address")
-            .arg(self.config.vrf_account_address.to_hex_string())
-            .arg("--account-private-key")
-            .arg(self.config.vrf_private_key.to_hex_string())
-            .arg("--secret-key")
-            .arg(self.config.secret_key.to_string())
-            .stdout(Stdio::inherit())
-            .stderr(Stdio::inherit())
-            .kill_on_drop(true);
-
-        let process = command.spawn().map_err(Error::Spawn)?;
-        let addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), VRF_SERVER_PORT);
-
-        let url = Url::parse(&format!("http://{addr}")).expect("valid url");
-        let client = VrfClient::new(url);
-        wait_for_http_ok(&client, "vrf info", SIDECAR_TIMEOUT).await?;
-
-        info!(%addr, "VRF service started.");
-
-        Ok(VrfServiceProcess { process, addr, inner: self })
-    }
-}
-
-/// A running VRF sidecar process.
-#[derive(Debug)]
-pub struct VrfServiceProcess {
-    process: Child,
-    inner: VrfService,
-    addr: SocketAddr,
-}
-
-impl VrfServiceProcess {
-    /// Get the address of the VRF service.
-    pub fn addr(&self) -> &SocketAddr {
-        &self.addr
-    }
-
-    pub fn process(&mut self) -> &mut Child {
-        &mut self.process
-    }
-
-    pub fn config(&self) -> &VrfServiceConfig {
-        &self.inner.config
-    }
-
-    pub async fn shutdown(&mut self) -> io::Result<()> {
-        self.process.kill().await
-    }
-}
-
-/// Resolve an executable path, searching in PATH if necessary.
-pub fn resolve_executable(path: &Path) -> Result<PathBuf> {
-    if path.components().count() > 1 {
-        return if path.is_file() {
-            Ok(path.to_path_buf())
-        } else {
-            Err(Error::BinaryNotFound(path.to_path_buf()))
-        };
-    }
-
-    let path_var = env::var_os("PATH").ok_or(Error::PathNotSet)?;
-    for dir in env::split_paths(&path_var) {
-        let candidate = dir.join(path);
-        if candidate.is_file() {
-            return Ok(candidate);
-        }
-    }
-
-    Err(Error::BinaryNotInPath(path.to_path_buf()))
-}
-
-/// Wait for the VRF sidecar to become ready by polling its `/info` endpoint.
-pub async fn wait_for_http_ok(client: &VrfClient, name: &str, timeout: Duration) -> Result<()> {
-    let start = Instant::now();
-
-    loop {
-        match client.info().await {
-            Ok(_) => {
-                info!(target: LOG_TARGET, %name, "sidecar ready");
-                return Ok(());
-            }
-            Err(err) => {
-                debug!(target: LOG_TARGET, %name, error = %err, "waiting for sidecar");
-            }
-        }
-
-        if start.elapsed() > timeout {
-            warn!(target: LOG_TARGET, %name, "sidecar did not become ready in time");
-            return Err(Error::SidecarTimeout);
-        }
-
-        sleep(Duration::from_millis(200)).await;
-    }
-}