feat(solana-solvers): PR 1 crate skeleton, config, /solve scaffold (#4632)

# Description
First PR of the Jupiter solver: a new `solana-solvers` crate that hosts
the `/solve` API. It mirrors the `crates/solvers` shape over
Solana-native types without reusing the EVM code, which is typed end to
end on EVM primitives (`U256`, 20-byte `Address`, single-call calldata)
with no chain abstraction. This PR is the skeleton. The Jupiter adapter,
solution assembly, and solve loop land in the following PRs.

# Changes
- New `crates/solana-solvers` binary crate (`main`/`lib`/`run`/`cli`),
an axum HTTP server with `/healthz` and `/solve`.
- Subcommand CLI (`solana-solvers jupiter --config ...`), so a Solana
baseline engine can slot in later.
- `observe`-based logging (JSON option, panic hook) and graceful
shutdown on SIGTERM/SIGINT.
- `/solve` is a scaffold: it accepts any auction and returns
`{"solutions": []}`, so the driver wiring can be exercised before real
quoting lands.
- Config: a `[dex]` table for the Jupiter backend (endpoint, api-key,
slippage) with `deny_unknown_fields`, plus
`config/example.jupiter.toml`.
- Lean dependency set (axum, clap, observe, serde, tokio, url). No EVM
deps pulled in.

# How to test
New unit tests (config parse plus unknown-key rejection).

# Notes
- Part of the Jupiter solver PR plan (specs repo PR
cowprotocol/solana-services-specifications#33).
PRs 2-4 add the Jupiter adapter, solution assembly, and the solve loop.

Author: squadgazzz

Cargo.lock

@@ -0,0 +1,29 @@
+[package]
+name = "solana-solvers"
+version = "0.1.0"
+edition = "2024"
+description = "Solana solver engines for CoW Protocol (Jupiter dex-wrapper)"
+license = "GPL-3.0-or-later"
+
+[lib]
+name = "solana_solvers"
+path = "src/lib.rs"
+
+[[bin]]
+name = "solana-solvers"
+path = "src/main.rs"
+
+[dependencies]
+axum = { workspace = true }
+clap = { workspace = true, features = ["derive", "env"] }
+observe = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+tokio = { workspace = true, features = ["fs", "macros", "rt-multi-thread", "signal"] }
+toml = { workspace = true }
+tower-http = { workspace = true, features = ["limit"] }
+tracing = { workspace = true }
+url = { workspace = true, features = ["serde"] }
+
+[lints]
+workspace = true

crates/solana-solvers/Cargo.toml

@@ -0,0 +1,13 @@
+# Example Jupiter solver configuration.
+# Run with: solana-solvers jupiter --config <this file>
+
+[dex]
+# Jupiter swap API base URL. Use api.jup.ag, or a Triton-hosted endpoint.
+endpoint = "https://api.jup.ag"
+# API key from the Jupiter developer portal (or Triton). Works without one but
+# heavily rate-limited, set it for production.
+api-key = "your-jupiter-api-key"
+# Slippage tolerance in basis points, sent to Jupiter as slippageBps. 50 = 0.5%.
+slippage-bps = 50
+# Buy orders quote via Jupiter ExactOut, which is route-limited. Off by default.
+enable-buy-orders = false

crates/solana-solvers/config/example.jupiter.toml

@@ -0,0 +1,55 @@
+//! HTTP API for the solver engine.
+//!
+//! Serves the `/solve` contract the driver calls. The handler is a scaffold: it
+//! accepts any auction and returns no solutions.
+
+use {
+    crate::config::Config,
+    axum::{
+        Json,
+        Router,
+        extract::State,
+        routing::{get, post},
+    },
+    serde_json::{Value, json},
+    std::{future::Future, net::SocketAddr, sync::Arc},
+    tower_http::limit::RequestBodyLimitLayer,
+};
+
+const REQUEST_BODY_LIMIT: usize = 10 * 1024 * 1024;
+
+pub struct Api {
+    pub addr: SocketAddr,
+    pub config: Config,
+}
+
+impl Api {
+    /// Bind and serve until `shutdown` resolves.
+    pub async fn serve(
+        self,
+        shutdown: impl Future<Output = ()> + Send + 'static,
+    ) -> std::io::Result<()> {
+        let app = Router::new()
+            .route("/healthz", get(healthz))
+            .route("/solve", post(solve))
+            .with_state(Arc::new(self.config))
+            .layer(RequestBodyLimitLayer::new(REQUEST_BODY_LIMIT))
+            .layer(axum::extract::DefaultBodyLimit::disable());
+
+        let listener = tokio::net::TcpListener::bind(self.addr).await?;
+        tracing::info!(addr = %self.addr, "solana-solvers listening");
+        axum::serve(listener, app)
+            .with_graceful_shutdown(shutdown)
+            .await
+    }
+}
+
+async fn healthz() -> &'static str {
+    "ok"
+}
+
+/// Scaffold `/solve`: accepts any auction and returns no solutions, so the
+/// driver wiring can be exercised against an empty result.
+async fn solve(State(_config): State<Arc<Config>>, Json(_auction): Json<Value>) -> Json<Value> {
+    Json(json!({ "solutions": [] }))
+}

crates/solana-solvers/src/api.rs

@@ -0,0 +1,38 @@
+//! CLI arguments for the `solana-solvers` binary.
+
+use {
+    clap::{Parser, Subcommand},
+    std::{net::SocketAddr, path::PathBuf},
+};
+
+/// Run a Solana solver engine.
+#[derive(Parser, Debug)]
+#[command(version)]
+pub struct Args {
+    /// The log filter.
+    #[arg(long, env, default_value = "warn,solana_solvers=debug")]
+    pub log: String,
+
+    /// Whether to use JSON format for the logs.
+    #[clap(long, env, default_value = "false")]
+    pub use_json_logs: bool,
+
+    /// The socket address to bind to.
+    #[arg(long, env, default_value = "127.0.0.1:7900")]
+    pub addr: SocketAddr,
+
+    #[command(subcommand)]
+    pub command: Command,
+}
+
+/// The solver engine to run. `config` is a path to a TOML config file.
+#[derive(Subcommand, Debug)]
+#[clap(rename_all = "lowercase")]
+pub enum Command {
+    /// Wrap Jupiter's quote API into single-order solutions.
+    Jupiter {
+        #[clap(long, env)]
+        config: PathBuf,
+    },
+    // TODO: add a baseline engine subcommand.
+}

crates/solana-solvers/src/cli.rs

@@ -0,0 +1,71 @@
+//! Solver-engine configuration.
+
+use {serde::Deserialize, std::path::Path, url::Url};
+
+/// Jupiter solver configuration.
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "kebab-case", deny_unknown_fields)]
+pub struct Config {
+    pub dex: JupiterConfig,
+}
+
+/// The `[dex]` table for the Jupiter backend. The subcommand selects the
+/// engine, so there is no per-aggregator sub-table.
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "kebab-case", deny_unknown_fields)]
+pub struct JupiterConfig {
+    /// Base URL of the Jupiter swap API (`api.jup.ag`) or a Triton-hosted Metis
+    /// endpoint.
+    pub endpoint: Url,
+
+    /// API key from the Jupiter developer portal (or Triton). Requests work
+    /// without one but are heavily rate-limited, so set it for production.
+    #[serde(default)]
+    pub api_key: Option<String>,
+
+    /// Slippage tolerance in basis points, sent to Jupiter as `slippageBps`.
+    /// 50 = 0.5%.
+    pub slippage_bps: u16,
+
+    /// Whether buy orders (Jupiter `ExactOut`) are served. Off by default.
+    #[serde(default)]
+    pub enable_buy_orders: bool,
+}
+
+/// Load and parse the TOML config file.
+///
+/// # Panics
+///
+/// Panics on I/O or parse errors: a bad config is a startup failure.
+pub async fn load(path: &Path) -> Config {
+    let text = tokio::fs::read_to_string(path)
+        .await
+        .unwrap_or_else(|err| panic!("read config {}: {err}", path.display()));
+    toml::from_str(&text).unwrap_or_else(|err| panic!("parse config {}: {err}", path.display()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_example_config() {
+        let config: Config =
+            toml::from_str(include_str!("../config/example.jupiter.toml")).unwrap();
+        assert_eq!(config.dex.endpoint.as_str(), "https://api.jup.ag/");
+        assert_eq!(config.dex.slippage_bps, 50);
+        assert!(!config.dex.enable_buy_orders);
+        assert!(config.dex.api_key.is_some());
+    }
+
+    #[test]
+    fn rejects_unknown_keys() {
+        let toml = r#"
+[dex]
+endpoint = "https://api.jup.ag"
+slippage-bps = 50
+bogus = true
+"#;
+        assert!(toml::from_str::<Config>(toml).is_err());
+    }
+}

crates/solana-solvers/src/config.rs

@@ -0,0 +1,11 @@
+//! Solana solver engines for CoW Protocol.
+//!
+//! An MVP dex-wrapper over Jupiter, mirroring the `crates/solvers` shape over
+//! Solana-native types (`u64`, `Pubkey`, instructions). Hosts the `/solve` API.
+
+pub mod api;
+mod cli;
+pub mod config;
+mod run;
+
+pub use run::start;

crates/solana-solvers/src/lib.rs

@@ -0,0 +1,4 @@
+#[tokio::main]
+async fn main() {
+    solana_solvers::start(std::env::args()).await;
+}

crates/solana-solvers/src/main.rs

@@ -0,0 +1,57 @@
+//! Binary entry: parse args, initialize observability, dispatch to the engine.
+
+#[cfg(unix)]
+use tokio::signal::unix::{self, SignalKind};
+use {
+    crate::{
+        api::Api,
+        cli::{Args, Command},
+        config,
+    },
+    clap::Parser,
+};
+
+/// Parse args and run the selected solver engine until shutdown.
+pub async fn start(args: impl IntoIterator<Item = String>) {
+    observe::panic_hook::install();
+    let args = Args::parse_from(args);
+
+    let obs_config = observe::Config::new(
+        &args.log,
+        Some(tracing::Level::ERROR),
+        args.use_json_logs,
+        None,
+    );
+    observe::tracing::init::initialize_reentrant(&obs_config);
+    tracing::info!(version = %observe::version::git_version(), "running solana-solvers with {args:#?}");
+
+    match args.command {
+        Command::Jupiter { config: path } => {
+            let config = config::load(&path).await;
+            let api = Api {
+                addr: args.addr,
+                config,
+            };
+            if let Err(err) = api.serve(shutdown_signal()).await {
+                tracing::error!(?err, "server error");
+            }
+        }
+    }
+}
+
+#[cfg(unix)]
+async fn shutdown_signal() {
+    // Kubernetes sends SIGTERM; locally SIGINT (ctrl-c) is most common.
+    let mut interrupt = unix::signal(SignalKind::interrupt()).expect("install SIGINT handler");
+    let mut terminate = unix::signal(SignalKind::terminate()).expect("install SIGTERM handler");
+    tokio::select! {
+        _ = interrupt.recv() => (),
+        _ = terminate.recv() => (),
+    };
+}
+
+#[cfg(windows)]
+async fn shutdown_signal() {
+    // Signal handling is not supported on Windows.
+    std::future::pending().await
+}