wip

Author: kariy

crates/cartridge/src/lib.rs

@@ -5,12 +5,11 @@ pub mod vrf;
 
 pub use client::Client;
 pub use vrf::{
-    bootstrap_vrf, derive_vrf_accounts, resolve_executable, vrf_secret_key_from_account_key,
-    wait_for_http_ok, InfoResponse, RequestContext, SignedOutsideExecution, VrfBootstrap,
-    VrfBootstrapConfig, VrfBootstrapResult, VrfClient, VrfClientError, VrfDerivedAccounts,
-    VrfOutsideExecution, VrfService, VrfServiceConfig, VrfServiceProcess, VrfSidecarError,
-    VrfSidecarResult, BOOTSTRAP_TIMEOUT, SIDECAR_TIMEOUT, VRF_ACCOUNT_SALT, VRF_CONSUMER_SALT,
-    VRF_SERVER_PORT,
+    bootstrap_vrf, get_vrf_account, resolve_executable, wait_for_http_ok, InfoResponse,
+    RequestContext, SignedOutsideExecution, VrfBootstrap, VrfBootstrapConfig, VrfBootstrapResult,
+    VrfClient, VrfClientError, VrfDerivedAccounts, VrfOutsideExecution, VrfService,
+    VrfServiceConfig, VrfServiceProcess, VRF_ACCOUNT_SALT, VRF_CONSUMER_SALT,
+    VRF_HARDCODED_SECRET_KEY, VRF_SERVER_PORT,
 };
 
 #[rustfmt::skip]

crates/cartridge/src/vrf/bootstrap.rs

@@ -1,7 +1,7 @@
 //! VRF bootstrap and account derivation.
 //!
 //! This module handles:
-//! - Deriving VRF accounts and keys from source accounts
+//! - Deriving VRF accounts and keys from a fixed VRF secret
 //! - Deploying VRF account and consumer contracts via RPC
 //! - Setting up VRF public keys on deployed accounts
 //!
@@ -34,6 +34,8 @@ use url::Url;
 pub const VRF_ACCOUNT_SALT: u64 = 0x54321;
 /// Salt used for deploying VRF consumer contracts via UDC.
 pub const VRF_CONSUMER_SALT: u64 = 0x67890;
+/// Hardcoded VRF secret key used to derive VRF account credentials.
+pub const VRF_HARDCODED_SECRET_KEY: u64 = 0x111;
 /// Default timeout for bootstrap operations.
 pub const BOOTSTRAP_TIMEOUT: Duration = Duration::from_secs(10);
 
@@ -63,7 +65,7 @@ pub struct VrfBootstrapConfig {
 /// Result of VRF bootstrap operations.
 #[derive(Debug, Clone)]
 pub struct VrfBootstrapResult {
-    /// The VRF secret key (derived from source account).
+    /// The VRF secret key used by the VRF sidecar.
     pub secret_key: u64,
     pub vrf_account_address: ContractAddress,
     pub vrf_account_private_key: Felt,
@@ -74,8 +76,7 @@ pub struct VrfBootstrapResult {
 /// Derived VRF account information.
 #[derive(Debug, Clone)]
 pub struct VrfDerivedAccounts {
-    pub source_address: ContractAddress,
-    pub source_private_key: Felt,
+    pub vrf_account_private_key: Felt,
     pub vrf_account_address: ContractAddress,
     pub vrf_public_key_x: Felt,
     pub vrf_public_key_y: Felt,
@@ -86,22 +87,19 @@ pub struct VrfDerivedAccounts {
 // Bootstrap Functions
 // ============================================================================
 
-/// Derive VRF accounts from source account.
+/// Derive VRF accounts from the hardcoded VRF secret key.
 ///
 /// This computes the deterministic VRF account address and VRF key pair
-/// from the source account's private key.
-pub fn derive_vrf_accounts(
-    bootstrapper_address: ContractAddress,
-    bootstrapper_private_key: Felt,
-) -> Result<VrfDerivedAccounts> {
-    // vrf-server expects a u64 secret, so derive one from the account key.
-    let secret_key = vrf_secret_key_from_account_key(bootstrapper_private_key);
+/// from a fixed VRF private key.
+pub fn get_vrf_account() -> Result<VrfDerivedAccounts> {
+    let secret_key = VRF_HARDCODED_SECRET_KEY;
+    let vrf_account_private_key = Felt::from(secret_key);
     let public_key = generate_public_key(scalar_from_felt(secret_key.into()));
     let vrf_public_key_x = felt_from_field(public_key.x)?;
     let vrf_public_key_y = felt_from_field(public_key.y)?;
 
     let account_public_key =
-        SigningKey::from_secret_scalar(bootstrapper_private_key).verifying_key().scalar();
+        SigningKey::from_secret_scalar(vrf_account_private_key).verifying_key().scalar();
 
     let vrf_account_class_hash = CartridgeVrfAccount::HASH;
     // When using UDC with unique=0 (non-unique deployment), the deployer_address
@@ -115,8 +113,7 @@ pub fn derive_vrf_accounts(
     .into();
 
     Ok(VrfDerivedAccounts {
-        source_address: bootstrapper_address,
-        source_private_key: bootstrapper_private_key,
+        vrf_account_private_key,
         vrf_account_address,
         vrf_public_key_x,
         vrf_public_key_y,
@@ -135,11 +132,10 @@ pub async fn bootstrap_vrf(
     let chain_id_felt = provider.chain_id().await.context("failed to get chain ID from node")?;
     let chain_id = ChainId::Id(chain_id_felt);
 
-    let derived =
-        derive_vrf_accounts(bootstrapper_account_address, bootstrapper_account_private_key)?;
+    let derived = get_vrf_account()?;
     let vrf_account_address = derived.vrf_account_address;
     let account_public_key =
-        SigningKey::from_secret_scalar(bootstrapper_account_private_key).verifying_key().scalar();
+        SigningKey::from_secret_scalar(derived.vrf_account_private_key).verifying_key().scalar();
 
     let vrf_account_class_hash = CartridgeVrfAccount::HASH;
 
@@ -205,7 +201,7 @@ pub async fn bootstrap_vrf(
     // Set VRF public key on the deployed account
     // Create account for the VRF account to call set_vrf_public_key on itself
     let vrf_signer =
-        LocalWallet::from(SigningKey::from_secret_scalar(bootstrapper_account_private_key));
+        LocalWallet::from(SigningKey::from_secret_scalar(derived.vrf_account_private_key));
     let mut vrf_account = SingleOwnerAccount::new(
         provider.clone(),
         vrf_signer,
@@ -258,8 +254,7 @@ pub async fn bootstrap_vrf(
         vrf_consumer_address,
         chain_id,
         vrf_account_address,
-        // right now, we take the bootstrapper account private key as the vrf account's private key
-        vrf_account_private_key: bootstrapper_account_private_key,
+        vrf_account_private_key: derived.vrf_account_private_key,
     })
 }
 
@@ -350,37 +345,29 @@ fn scalar_from_felt(value: Felt) -> ScalarField {
     ScalarField::from_be_bytes_mod_order(&bytes)
 }
 
-/// Derive a u64 VRF secret key from an account private key.
-///
-/// Uses the low 64 bits of the account key.
-pub fn vrf_secret_key_from_account_key(value: Felt) -> u64 {
-    let bytes = value.to_bytes_be();
-    let mut tail = [0_u8; 8];
-    tail.copy_from_slice(&bytes[24..]);
-    u64::from_be_bytes(tail)
-}
-
 fn felt_from_field<T: std::fmt::Display>(value: T) -> Result<Felt> {
     let decimal = value.to_string();
     Felt::from_dec_str(&decimal).map_err(|err| anyhow!("invalid field value: {err}"))
 }
 
 #[cfg(test)]
 mod tests {
-    use katana_primitives::Felt;
-
-    use super::vrf_secret_key_from_account_key;
+    use super::{get_vrf_account, VRF_HARDCODED_SECRET_KEY};
 
     #[test]
-    fn vrf_secret_key_uses_low_64_bits() {
-        let mut bytes = [0_u8; 32];
-        for (i, byte) in bytes.iter_mut().enumerate() {
-            *byte = i as u8;
-        }
+    fn derive_vrf_accounts_uses_hardcoded_secret_key() {
+        let derived = get_vrf_account().expect("must derive");
+        assert_eq!(derived.secret_key, VRF_HARDCODED_SECRET_KEY);
+        assert_eq!(derived.vrf_account_private_key, VRF_HARDCODED_SECRET_KEY.into());
+    }
 
-        let felt = Felt::from_bytes_be(&bytes);
-        let secret = vrf_secret_key_from_account_key(felt);
+    #[test]
+    fn derive_vrf_accounts_is_deterministic() {
+        let first = get_vrf_account().expect("first derivation");
+        let second = get_vrf_account().expect("second derivation");
 
-        assert_eq!(secret, 0x18191a1b1c1d1e1f);
+        assert_eq!(first.vrf_account_address, second.vrf_account_address);
+        assert_eq!(first.vrf_public_key_x, second.vrf_public_key_x);
+        assert_eq!(first.vrf_public_key_y, second.vrf_public_key_y);
     }
 }

crates/cartridge/src/vrf/mod.rs

@@ -5,18 +5,177 @@
 //! - Bootstrap logic for deploying VRF contracts
 //! - Sidecar process management
 
+mod bootstrap;
 mod client;
 
-pub mod bootstrap;
-pub mod sidecar;
+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, derive_vrf_accounts, vrf_secret_key_from_account_key, VrfBootstrap,
-    VrfBootstrapConfig, VrfBootstrapResult, VrfDerivedAccounts, BOOTSTRAP_TIMEOUT,
-    VRF_ACCOUNT_SALT, VRF_CONSUMER_SALT,
+    bootstrap_vrf, get_vrf_account, VrfBootstrap, VrfBootstrapConfig, VrfBootstrapResult,
+    VrfDerivedAccounts, BOOTSTRAP_TIMEOUT, VRF_ACCOUNT_SALT, VRF_CONSUMER_SALT,
+    VRF_HARDCODED_SECRET_KEY,
 };
 pub use client::*;
-pub use sidecar::{
-    resolve_executable, wait_for_http_ok, Error as VrfSidecarError, Result as VrfSidecarResult,
-    VrfService, VrfServiceConfig, VrfServiceProcess, SIDECAR_TIMEOUT, VRF_SERVER_PORT,
-};
+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;
+    }
+}