Updates for the API

api/builder.toml

@@ -1,10 +1,28 @@
 # Copyright (c) 2024 Espresso Systems (espressosys.com)
 # This file is part of the HotShot Builder Protocol.
 #
-# TODO: License
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
 
 [meta]
-NAME = "hs-builder"
+NAME = "hs-builder-get"
 DESCRIPTION = ""
 FORMAT_VERSION = "0.1.0"
 
@@ -36,10 +54,12 @@ Get the specified block candidate.
 Returns application-specific encoded transactions type
 """
 
-[route.submit_txn]
-PATH = ["submittxn/:txn"]
-":txn" = "TaggedBase64"
+[route.claim_header]
+PATH = ["claimheader/:block_hash/:signature"]
+":block_hash" = "TaggedBase64"
+":signature" = "TaggedBase64"
 DOC = """
+Get the specified block candidate.
 
-Returns ---
+Returns application-specific block header type
 """

api/submit.toml

@@ -0,0 +1,33 @@
+# Copyright (c) 2024 Espresso Systems (espressosys.com)
+# This file is part of the HotShot Builder Protocol.
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+
+[meta]
+NAME = "hs-builder-submit"
+DESCRIPTION = ""
+FORMAT_VERSION = "0.1.0"
+
+[route.submit_txn]
+PATH = ["/submit"]
+METHOD = "POST"
+DOC = "Submit a transaction to builder's private mempool."

src/block_info.rs

@@ -25,3 +25,12 @@ pub struct AvailableBlockData<I: NodeType> {
     pub sender: <I as NodeType>::SignatureKey,
     pub _phantom: PhantomData<I>,
 }
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq, Hash)]
+#[serde(bound = "")]
+pub struct AvailableBlockHeader<I: NodeType> {
+    pub block_header: <I as NodeType>::BlockHeader,
+    pub signature: <<I as NodeType>::SignatureKey as SignatureKey>::PureAssembledSignatureType,
+    pub sender: <I as NodeType>::SignatureKey,
+    pub _phantom: PhantomData<I>,
+}

src/builder.rs

@@ -10,9 +10,16 @@ use hotshot_types::{
 use serde::{Deserialize, Serialize};
 use snafu::{ResultExt, Snafu};
 use tagged_base64::TaggedBase64;
-use tide_disco::{api::ApiError, method::ReadState, Api, RequestError, StatusCode};
+use tide_disco::{
+    api::ApiError,
+    method::{ReadState, WriteState},
+    Api, RequestError, StatusCode,
+};
 
-use crate::{api::load_api, data_source::BuilderDataSource};
+use crate::{
+    api::load_api,
+    data_source::{AcceptsTxnSubmits, BuilderDataSource},
+};
 
 #[derive(Args, Default)]
 pub struct Options {
@@ -61,6 +68,16 @@ pub enum Error {
         source: BuildError,
         resource: String,
     },
+    #[snafu(display("error unpacking transaction: {source}"))]
+    #[from(ignore)]
+    TxnUnpack {
+        source: RequestError,
+    },
+    #[snafu(display("error submitting transaction: {source}"))]
+    #[from(ignore)]
+    TxnSubmit {
+        source: BuildError,
+    },
     Custom {
         message: String,
         status: StatusCode,
@@ -84,6 +101,8 @@ impl tide_disco::error::Error for Error {
                 BuildError::Missing => StatusCode::NotFound,
                 BuildError::Error { .. } => StatusCode::InternalServerError,
             },
+            Error::TxnUnpack { .. } => StatusCode::BadRequest,
+            Error::TxnSubmit { .. } => StatusCode::InternalServerError,
             Error::Custom { .. } => StatusCode::InternalServerError,
         }
     }
@@ -130,6 +149,44 @@ where
                     })
             }
             .boxed()
+        })?
+        .get("claim_header", |req, state| {
+            async move {
+                let hash: BuilderCommitment = req.blob_param("block_hash")?;
+                let signature = req.blob_param("signature")?;
+                state
+                    .claim_block_header(&hash, &signature)
+                    .await
+                    .context(BlockClaimSnafu {
+                        resource: hash.to_string(),
+                    })
+            }
+            .boxed()
+        })?;
+    Ok(api)
+}
+
+pub fn submit_api<State, Types: NodeType>(options: &Options) -> Result<Api<State, Error>, ApiError>
+where
+    State: 'static + Send + Sync + WriteState,
+    <State as ReadState>::State: Send + Sync + AcceptsTxnSubmits<Types>,
+    Types: NodeType,
+{
+    let mut api = load_api::<State, Error>(
+        options.api_path.as_ref(),
+        include_str!("../api/submit.toml"),
+        options.extensions.clone(),
+    )?;
+    api.with_version("0.0.1".parse().unwrap())
+        .post("submit_txn", |req, state| {
+            async move {
+                let tx = req
+                    .body_auto::<<Types as NodeType>::Transaction>()
+                    .context(TxnUnpackSnafu)?;
+                state.submit_txn(tx).await.context(TxnSubmitSnafu)?;
+                Ok(())
+            }
+            .boxed()
         })?;
     Ok(api)
 }

src/data_source.rs

@@ -7,7 +7,7 @@ use hotshot_types::{
 use tagged_base64::TaggedBase64;
 
 use crate::{
-    block_info::{AvailableBlockData, AvailableBlockInfo},
+    block_info::{AvailableBlockData, AvailableBlockHeader, AvailableBlockInfo},
     builder::BuildError,
 };
 
@@ -27,5 +27,17 @@ where
         block_hash: &BuilderCommitment,
         signature: &<<I as NodeType>::SignatureKey as SignatureKey>::PureAssembledSignatureType,
     ) -> Result<AvailableBlockData<I>, BuildError>;
-    async fn submit_txn(&self, txn: <I as NodeType>::Transaction) -> Result<(), BuildError>;
+    async fn claim_block_header(
+        &self,
+        block_hash: &BuilderCommitment,
+        signature: &<<I as NodeType>::SignatureKey as SignatureKey>::PureAssembledSignatureType,
+    ) -> Result<AvailableBlockHeader<I>, BuildError>;
+}
+
+#[async_trait]
+pub trait AcceptsTxnSubmits<I>
+where
+    I: NodeType,
+{
+    async fn submit_txn(&mut self, txn: <I as NodeType>::Transaction) -> Result<(), BuildError>;
 }