fault_proving(global_roots): GraphQL API for serving state roots

.changes/added/2742.md

@@ -0,0 +1 @@
+Added API crate for merkle root service.

Cargo.toml

@@ -14,6 +14,7 @@ members = [
   "crates/fuel-gas-price-algorithm",
   "crates/keygen",
   "crates/metrics",
+  "crates/proof_system/global_merkle_root/api",
   "crates/proof_system/global_merkle_root/service",
   "crates/proof_system/global_merkle_root/storage",
   "crates/services",
@@ -106,6 +107,10 @@ fuel-vm-private = { version = "0.59.2", package = "fuel-vm", default-features =
 
 # Common dependencies
 anyhow = "1.0"
+async-graphql = { version = "7.0.11", features = [
+  "graphiql",
+  "tracing",
+], default-features = false }
 async-trait = "0.1"
 aws-sdk-kms = "1.37"
 cynic = { version = "3.1.0", features = ["http-reqwest"] }

crates/fuel-core/Cargo.toml

@@ -12,10 +12,7 @@ version = { workspace = true }
 
 [dependencies]
 anyhow = { workspace = true }
-async-graphql = { version = "7.0.11", features = [
-  "graphiql",
-  "tracing",
-], default-features = false }
+async-graphql = { workspace = true }
 async-graphql-value = "7.0.11"
 async-trait = { workspace = true }
 axum = { workspace = true }

crates/proof_system/global_merkle_root/api/Cargo.toml

@@ -0,0 +1,37 @@
+[package]
+authors = { workspace = true }
+categories = ["cryptography::cryptocurrencies"]
+description = "GraphQL API for the global merkle root service."
+edition = { workspace = true }
+homepage = { workspace = true }
+keywords = ["blockchain", "cryptocurrencies", "fuel-client", "fuel-core"]
+license = { workspace = true }
+name = "fuel-core-global-merkle-root-api"
+repository = { workspace = true }
+version = { workspace = true }
+
+[dependencies]
+anyhow = { workspace = true }
+async-graphql = { workspace = true }
+async-trait = { workspace = true }
+axum = { workspace = true }
+derive_more = { workspace = true }
+fuel-core-services = { workspace = true }
+fuel-core-storage = { workspace = true, features = ["alloc"] }
+fuel-core-types = { workspace = true, default-features = false, features = [
+  "serde",
+  "alloc",
+] }
+hex = { workspace = true }
+hyper = { workspace = true }
+tokio = { workspace = true }
+tracing = { workspace = true }
+
+[dev-dependencies]
+fuel-core-storage = { workspace = true, features = ["std", "test-helpers"] }
+fuel-core-types = { workspace = true, default-features = false, features = [
+  "serde",
+  "random",
+  "test-helpers",
+] }
+reqwest = { workspace = true }

crates/proof_system/global_merkle_root/api/src/lib.rs

@@ -0,0 +1,19 @@
+//! The GraphQL API of the state root service
+
+#![deny(clippy::arithmetic_side_effects)]
+#![deny(clippy::cast_possible_truncation)]
+#![deny(unused_crate_dependencies)]
+#![deny(missing_docs)]
+#![deny(warnings)]
+
+/// Port definitions
+pub mod ports;
+
+/// API service definition
+pub mod service;
+
+/// GraphQL schema definition
+pub mod schema;
+
+#[cfg(test)]
+pub mod tests;

crates/proof_system/global_merkle_root/api/src/ports.rs

@@ -0,0 +1,12 @@
+use fuel_core_storage::Error as StorageError;
+use fuel_core_types::{
+    fuel_tx::Bytes32,
+    fuel_types::BlockHeight,
+};
+
+/// Represents the ability to retrieve a state root at a given block height
+pub trait GetStateRoot {
+    /// Get the state root at the given height
+    fn state_root_at(&self, height: BlockHeight)
+        -> Result<Option<Bytes32>, StorageError>;
+}

crates/proof_system/global_merkle_root/api/src/schema.rs

@@ -0,0 +1,112 @@
+use std::{
+    array::TryFromSliceError,
+    fmt::Display,
+    str::FromStr,
+};
+
+use async_graphql::{
+    EmptyMutation,
+    EmptySubscription,
+    InputValueError,
+    ScalarType,
+};
+use hex::FromHexError;
+
+use crate::ports;
+
+/// The schema of the state root service.
+pub type Schema<Storage> =
+    async_graphql::Schema<Query<Storage>, EmptyMutation, EmptySubscription>;
+
+/// The query type of the schema.
+pub struct Query<Storage> {
+    storage: Storage,
+}
+
+impl<Storage> Query<Storage> {
+    /// Create a new query object.
+    pub fn new(storage: Storage) -> Self {
+        Self { storage }
+    }
+}
+
+#[async_graphql::Object]
+impl<Storage> Query<Storage>
+where
+    Storage: ports::GetStateRoot + Send + Sync,
+{
+    async fn state_root(
+        &self,
+        height: BlockHeight,
+    ) -> async_graphql::Result<Option<MerkleRoot>> {
+        let state_root = self.storage.state_root_at(height.0.into())?;
+
+        Ok(state_root.map(|root| MerkleRoot(*root)))
+    }
+}
+
+/// GraphQL scalar type for block height.
+#[derive(
+    Clone,
+    Copy,
+    Debug,
+    PartialEq,
+    Eq,
+    PartialOrd,
+    Ord,
+    derive_more::FromStr,
+    derive_more::Display,
+)]
+pub struct BlockHeight(u32);
+
+/// GraphQL scalar type for the merkle root.
+#[derive(Clone, Copy, Debug)]
+pub struct MerkleRoot([u8; 32]);
+
+impl Display for MerkleRoot {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "0x{}", hex::encode(self.0))
+    }
+}
+
+impl FromStr for MerkleRoot {
+    type Err = MerkleRootParseError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let bytes = hex::decode(s.trim_start_matches("0x"))?;
+        Ok(MerkleRoot(bytes.as_slice().try_into()?))
+    }
+}
+
+/// Error type for the merkle root parsing.
+#[derive(Clone, Debug, derive_more::Display, derive_more::From, derive_more::Error)]
+pub enum MerkleRootParseError {
+    /// The merkle root isn't valid hex.
+    DecodeFailure(FromHexError),
+    /// The merkle root has the wrong number of bytes.
+    WrongLength(TryFromSliceError),
+}
+
+macro_rules! impl_scalar_type {
+    ($type:ty) => {
+        #[async_graphql::Scalar]
+        impl ScalarType for $type {
+            fn parse(
+                value: async_graphql::Value,
+            ) -> async_graphql::InputValueResult<Self> {
+                let async_graphql::Value::String(text) = value else {
+                    return Err(InputValueError::expected_type(value))
+                };
+
+                text.parse().map_err(InputValueError::custom)
+            }
+
+            fn to_value(&self) -> async_graphql::Value {
+                async_graphql::Value::String(self.to_string())
+            }
+        }
+    };
+}
+
+impl_scalar_type!(MerkleRoot);
+impl_scalar_type!(BlockHeight);