feat(core,host): initial aggregation API

core/src/interfaces.rs

@@ -442,14 +442,84 @@ impl TryFrom<ProofRequestOpt> for ProofRequest {
     }
 }
 
-#[serde_as]
-#[derive(Clone, Debug, Serialize, Deserialize)]
+#[derive(Default, Clone, Serialize, Deserialize, Debug, ToSchema)]
+#[serde(default)]
 /// A request for proof aggregation of multiple proofs.
 pub struct AggregationRequest {
-    /// All the proofs to verify
-    pub proofs: Vec<Proof>,
+    /// The block numbers and l1 inclusion block numbers for the blocks to aggregate proofs for.
+    pub block_numbers: Vec<(u64, u64)>,
+    /// The network to generate the proof for.
+    pub network: Option<String>,
+    /// The L1 network to generate the proof for.
+    pub l1_network: Option<String>,
+    // Graffiti.
+    pub graffiti: Option<String>,
+    /// The protocol instance data.
+    pub prover: Option<String>,
     /// The proof type.
-    pub proof_type: ProofType,
-    /// Additional prover params.
-    pub prover_args: HashMap<String, Value>,
+    pub proof_type: Option<String>,
+    /// Blob proof type.
+    pub blob_proof_type: Option<String>,
+    #[serde(flatten)]
+    /// Any additional prover params in JSON format.
+    pub prover_args: ProverSpecificOpts,
+}
+
+impl AggregationRequest {
+    /// Merge proof request options into aggregation request options.
+    pub fn merge(&mut self, opts: &ProofRequestOpt) -> RaikoResult<()> {
+        let this = serde_json::to_value(&self)?;
+        let mut opts = serde_json::to_value(opts)?;
+        merge(&mut opts, &this);
+        *self = serde_json::from_value(opts)?;
+        Ok(())
+    }
+}
+
+impl From<AggregationRequest> for Vec<ProofRequestOpt> {
+    fn from(value: AggregationRequest) -> Self {
+        value
+            .block_numbers
+            .iter()
+            .map(
+                |&(block_number, l1_inclusion_block_number)| ProofRequestOpt {
+                    block_number: Some(block_number),
+                    l1_inclusion_block_number: Some(l1_inclusion_block_number),
+                    network: value.network.clone(),
+                    l1_network: value.l1_network.clone(),
+                    graffiti: value.graffiti.clone(),
+                    prover: value.prover.clone(),
+                    proof_type: value.proof_type.clone(),
+                    blob_proof_type: value.blob_proof_type.clone(),
+                    prover_args: value.prover_args.clone(),
+                },
+            )
+            .collect()
+    }
+}
+
+impl From<ProofRequestOpt> for AggregationRequest {
+    fn from(value: ProofRequestOpt) -> Self {
+        let block_numbers = if let Some(block_number) = value.block_number {
+            vec![(
+                block_number,
+                value
+                    .l1_inclusion_block_number
+                    .unwrap_or_else(|| block_number - 1),
+            )]
+        } else {
+            vec![]
+        };
+
+        Self {
+            block_numbers,
+            network: value.network,
+            l1_network: value.l1_network,
+            graffiti: value.graffiti,
+            prover: value.prover,
+            proof_type: value.proof_type,
+            blob_proof_type: value.blob_proof_type,
+            prover_args: value.prover_args,
+        }
+    }
 }

core/src/lib.rs

@@ -455,8 +455,8 @@ mod tests {
             .unwrap();
 
         let proof_request = ProofRequest {
-            l1_inclusion_block_number: 0,
             block_number,
+            l1_inclusion_block_number: 0,
             network,
             graffiti: B256::ZERO,
             prover: Address::ZERO,

host/src/server/api/mod.rs

@@ -18,6 +18,7 @@ use crate::ProverState;
 
 pub mod v1;
 pub mod v2;
+pub mod v3;
 
 pub fn create_router(concurrency_limit: usize, jwt_secret: Option<&str>) -> Router<ProverState> {
     let cors = CorsLayer::new()
@@ -37,11 +38,13 @@ pub fn create_router(concurrency_limit: usize, jwt_secret: Option<&str>) -> Rout
 
     let v1_api = v1::create_router(concurrency_limit);
     let v2_api = v2::create_router();
+    let v3_api = v3::create_router();
 
     let router = Router::new()
         .nest("/v1", v1_api)
-        .nest("/v2", v2_api.clone())
-        .merge(v2_api)
+        .nest("/v2", v2_api)
+        .nest("/v3", v3_api.clone())
+        .merge(v3_api)
         .layer(middleware)
         .layer(middleware::from_fn(check_max_body_size))
         .layer(trace)
@@ -58,7 +61,7 @@ pub fn create_router(concurrency_limit: usize, jwt_secret: Option<&str>) -> Rout
 }
 
 pub fn create_docs() -> utoipa::openapi::OpenApi {
-    v2::create_docs()
+    v3::create_docs()
 }
 
 async fn check_max_body_size(req: Request, next: Next) -> Response {

host/src/server/api/v2/mod.rs

@@ -11,7 +11,7 @@ use crate::{
     ProverState,
 };
 
-mod proof;
+pub mod proof;
 
 #[derive(OpenApi)]
 #[openapi(

host/src/server/api/v2/proof/mod.rs

@@ -11,10 +11,10 @@ use crate::{
     Message, ProverState,
 };
 
-mod cancel;
-mod list;
-mod prune;
-mod report;
+pub mod cancel;
+pub mod list;
+pub mod prune;
+pub mod report;
 
 #[utoipa::path(post, path = "/proof",
     tag = "Proving",

host/src/server/api/v3/mod.rs

@@ -0,0 +1,166 @@
+use axum::{response::IntoResponse, Json, Router};
+use raiko_lib::prover::Proof;
+use raiko_tasks::TaskStatus;
+use serde::{Deserialize, Serialize};
+use utoipa::{OpenApi, ToSchema};
+use utoipa_scalar::{Scalar, Servable};
+use utoipa_swagger_ui::SwaggerUi;
+
+use crate::{
+    server::api::v1::{self, GuestOutputDoc},
+    ProverState,
+};
+
+mod proof;
+
+#[derive(OpenApi)]
+#[openapi(
+    info(
+        title = "Raiko Proverd Server API",
+        version = "3.0",
+        description = "Raiko Proverd Server API",
+        contact(
+            name = "API Support",
+            url = "https://community.taiko.xyz",
+            email = "info@taiko.xyz",
+        ),
+        license(
+            name = "MIT",
+            url = "https://github.com/taikoxyz/raiko/blob/main/LICENSE"
+        ),
+    ),
+    components(
+        schemas(
+            raiko_core::interfaces::ProofRequestOpt,
+            raiko_core::interfaces::ProverSpecificOpts,
+            crate::interfaces::HostError,
+            GuestOutputDoc,
+            ProofResponse,
+            TaskStatus,
+            CancelStatus,
+            PruneStatus,
+            Proof,
+            Status,
+        )
+    ),
+    tags(
+        (name = "Proving", description = "Routes that handle proving requests"),
+        (name = "Health", description = "Routes that report the server health status"),
+        (name = "Metrics", description = "Routes that give detailed insight into the server")
+    )
+)]
+/// The root API struct which is generated from the `OpenApi` derive macro.
+pub struct Docs;
+
+#[derive(Debug, Deserialize, Serialize, ToSchema)]
+#[serde(untagged)]
+pub enum ProofResponse {
+    Status {
+        /// The status of the submitted task.
+        status: TaskStatus,
+    },
+    Proof {
+        /// The proof.
+        proof: Proof,
+    },
+}
+
+#[derive(Debug, Deserialize, Serialize, ToSchema)]
+#[serde(tag = "status", rename_all = "lowercase")]
+pub enum Status {
+    Ok { data: ProofResponse },
+    Error { error: String, message: String },
+}
+
+impl From<Vec<u8>> for Status {
+    fn from(proof: Vec<u8>) -> Self {
+        Self::Ok {
+            data: ProofResponse::Proof {
+                proof: serde_json::from_slice(&proof).unwrap_or_default(),
+            },
+        }
+    }
+}
+
+impl From<Proof> for Status {
+    fn from(proof: Proof) -> Self {
+        Self::Ok {
+            data: ProofResponse::Proof { proof },
+        }
+    }
+}
+
+impl From<TaskStatus> for Status {
+    fn from(status: TaskStatus) -> Self {
+        Self::Ok {
+            data: ProofResponse::Status { status },
+        }
+    }
+}
+
+impl IntoResponse for Status {
+    fn into_response(self) -> axum::response::Response {
+        Json(serde_json::to_value(self).unwrap()).into_response()
+    }
+}
+
+#[derive(Debug, Deserialize, Serialize, ToSchema)]
+#[serde(tag = "status", rename_all = "lowercase")]
+/// Status of cancellation request.
+/// Can be `ok` for a successful cancellation or `error` with message and error type for errors.
+pub enum CancelStatus {
+    /// Cancellation was successful.
+    Ok,
+    /// Cancellation failed.
+    Error { error: String, message: String },
+}
+
+impl IntoResponse for CancelStatus {
+    fn into_response(self) -> axum::response::Response {
+        Json(serde_json::to_value(self).unwrap()).into_response()
+    }
+}
+
+#[derive(Debug, Serialize, ToSchema, Deserialize)]
+#[serde(tag = "status", rename_all = "lowercase")]
+/// Status of prune request.
+/// Can be `ok` for a successful prune or `error` with message and error type for errors.
+pub enum PruneStatus {
+    /// Prune was successful.
+    Ok,
+    /// Prune failed.
+    Error { error: String, message: String },
+}
+
+impl IntoResponse for PruneStatus {
+    fn into_response(self) -> axum::response::Response {
+        Json(serde_json::to_value(self).unwrap()).into_response()
+    }
+}
+
+#[must_use]
+pub fn create_docs() -> utoipa::openapi::OpenApi {
+    [
+        v1::health::create_docs(),
+        v1::metrics::create_docs(),
+        proof::create_docs(),
+    ]
+    .into_iter()
+    .fold(Docs::openapi(), |mut doc, sub_doc| {
+        doc.merge(sub_doc);
+        doc
+    })
+}
+
+pub fn create_router() -> Router<ProverState> {
+    let docs = create_docs();
+
+    Router::new()
+        // Only add the concurrency limit to the proof route. We want to still be able to call
+        // healthchecks and metrics to have insight into the system.
+        .nest("/proof", proof::create_router())
+        .nest("/health", v1::health::create_router())
+        .nest("/metrics", v1::metrics::create_router())
+        .merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", docs.clone()))
+        .merge(Scalar::with_url("/scalar", docs))
+}