feat(katana) : add explorer flag and build folder

.github/workflows/ci.yml

@@ -11,13 +11,44 @@ env:
   RUST_VERSION: 1.81.0
 
 jobs:
+  build-explorer:
+    runs-on: ubuntu-latest
+    needs: [fmt, cairofmt]
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: recursive
+          fetch-depth: 0
+      - name: Initialize submodules
+        run: |
+          git submodule update --init --recursive
+          ls -la crates/katana/explorer/ui
+      - uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+      - name: Build Explorer UI
+        run: |
+          cd crates/katana/explorer/ui
+          bun install
+          bun run build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: explorer-dist
+          path: crates/katana/explorer/ui/dist
+
   build:
     runs-on: ubuntu-latest-4-cores
-    needs: [fmt, cairofmt]
+    needs: [fmt, cairofmt, build-explorer]
     container:
       image: ghcr.io/dojoengine/dojo-dev:v1.2.1
     steps:
       - uses: actions/checkout@v3
+        with:
+          submodules: true
+      - uses: actions/download-artifact@v4
+        with:
+          name: explorer-dist
+          path: crates/katana/explorer/ui/dist
       - uses: Swatinem/rust-cache@v2
       - run: |
           cargo build -r --bin katana

.gitignore

@@ -24,3 +24,5 @@ examples/spawn-and-move/manifests/saya/**
 **/*.log
 
 artifacts/
+
+crates/katana/explorer/ui

.gitmodules

@@ -4,3 +4,7 @@
 [submodule "crates/katana/contracts/piltover"]
 	path = crates/katana/contracts/piltover
 	url = https://github.com/keep-starknet-strange/piltover.git
+[submodule "crates/katana/explorer/ui"]
+	path = crates/katana/explorer/ui
+	url = https://github.com/cartridge-gg/explorer
+	branch = main

Cargo.toml

@@ -18,6 +18,7 @@ members = [
 	"crates/katana/cli",
 	"crates/katana/controller",
 	"crates/katana/core",
+	"crates/katana/explorer",
 	"crates/katana/executor",
 	"crates/katana/feeder-gateway",
 	"crates/katana/grpc",
@@ -98,6 +99,7 @@ katana-codecs-derive = { path = "crates/katana/storage/codecs/derive" }
 katana-core = { path = "crates/katana/core", default-features = false }
 katana-db = { path = "crates/katana/storage/db" }
 katana-executor = { path = "crates/katana/executor" }
+katana-explorer = { path = "crates/katana/explorer" }
 katana-feeder-gateway = { path = "crates/katana/feeder-gateway" }
 katana-messaging = { path = "crates/katana/messaging" }
 katana-node = { path = "crates/katana/node", default-features = false }

crates/katana/cli/Cargo.toml

@@ -8,6 +8,7 @@ version.workspace = true
 [dependencies]
 katana-chain-spec.workspace = true
 katana-core.workspace = true
+katana-explorer.workspace = true
 katana-messaging.workspace = true
 katana-node.workspace = true
 katana-primitives.workspace = true

crates/katana/cli/src/args.rs

@@ -1,5 +1,6 @@
 //! Katana node CLI options and configuration.
 
+use std::net::SocketAddr;
 use std::path::PathBuf;
 use std::sync::Arc;
 
@@ -11,6 +12,7 @@ use clap::Parser;
 use katana_chain_spec::rollup::ChainConfigDir;
 use katana_chain_spec::ChainSpec;
 use katana_core::constants::DEFAULT_SEQUENCER_ADDRESS;
+use katana_explorer::Explorer;
 use katana_messaging::MessagingConfig;
 use katana_node::config::db::DbConfig;
 use katana_node::config::dev::{DevConfig, FixedL1GasPriceConfig};
@@ -24,6 +26,7 @@ use katana_node::config::sequencing::SequencingConfig;
 use katana_node::config::Config;
 use katana_primitives::genesis::allocation::DevAllocationsGenerator;
 use katana_primitives::genesis::constant::DEFAULT_PREFUNDED_ACCOUNT_BALANCE;
+use katana_rpc::cors::HeaderValue;
 use serde::{Deserialize, Serialize};
 use tracing::{info, Subscriber};
 use tracing_log::LogTracer;
@@ -115,6 +118,9 @@ pub struct NodeArgs {
     #[cfg(feature = "slot")]
     #[command(flatten)]
     pub slot: SlotOptions,
+
+    #[command(flatten)]
+    pub explorer: ExplorerOptions,
 }
 
 impl NodeArgs {
@@ -135,6 +141,14 @@ impl NodeArgs {
         // Launch the node
         let handle = node.launch().await.context("failed to launch node")?;
 
+        // Then start the explorer if enabled
+        if self.explorer.explorer {
+            let rpc_url = format!("http://{}", handle.rpc.addr());
+            let rpc_url = Url::parse(&rpc_url).context("failed to parse node url")?;
+            let addr = SocketAddr::new(self.explorer.explorer_addr, self.explorer.explorer_port);
+            let _ = Explorer::new(rpc_url)?.start(addr)?;
+        }
+
         // Wait until an OS signal (ie SIGINT, SIGTERM) is received or the node is shutdown.
         tokio::select! {
             _ = dojo_utils::signal::wait_signals() => {
@@ -229,14 +243,35 @@ impl NodeArgs {
                 modules
             };
 
+            let mut cors_origins = self.server.http_cors_origins.clone();
+
+            // Add explorer URL to CORS origins if explorer is enabled
+            if self.explorer.explorer {
+                // Add both http://127.0.0.1:PORT and http://localhost:PORT
+                cors_origins.push(
+                    HeaderValue::from_str(&format!(
+                        "http://127.0.0.1:{}",
+                        self.explorer.explorer_port
+                    ))
+                    .context("Failed to create CORS header")?,
+                );
+                cors_origins.push(
+                    HeaderValue::from_str(&format!(
+                        "http://localhost:{}",
+                        self.explorer.explorer_port
+                    ))
+                    .context("Failed to create CORS header")?,
+                );
+            }
+
             Ok(RpcConfig {
                 apis: modules,
                 port: self.server.http_port,
                 addr: self.server.http_addr,
                 max_connections: self.server.max_connections,
+                cors_origins,
                 max_request_body_size: None,
                 max_response_body_size: None,
-                cors_origins: self.server.http_cors_origins.clone(),
                 max_event_page_size: Some(self.server.max_event_page_size),
                 max_proof_keys: Some(self.server.max_proof_keys),
                 max_call_gas: Some(self.server.max_call_gas),

crates/katana/cli/src/options.rs

@@ -9,6 +9,7 @@
 
 #[cfg(feature = "server")]
 use std::net::IpAddr;
+use std::net::Ipv4Addr;
 
 use clap::Args;
 use katana_node::config::execution::{DEFAULT_INVOCATION_MAX_STEPS, DEFAULT_VALIDATION_MAX_STEPS};
@@ -409,6 +410,47 @@ pub struct SlotOptions {
     pub controller: bool,
 }
 
+const DEFAULT_EXPLORER_ADDR: IpAddr = IpAddr::V4(Ipv4Addr::LOCALHOST);
+const DEFAULT_EXPLORER_PORT: u16 = 3001;
+
+#[derive(Debug, Args, Clone, Serialize, Deserialize, PartialEq)]
+#[command(next_help_heading = "Explorer options")]
+pub struct ExplorerOptions {
+    /// Enable and launch the explorer frontend
+    ///
+    /// This will start a web server that serves the explorer UI.
+    #[arg(long)]
+    #[serde(default)]
+    pub explorer: bool,
+
+    /// The address to run the explorer frontend on.
+    #[arg(long = "explorer.addr", value_name = "ADDRESS")]
+    #[arg(default_value_t = DEFAULT_EXPLORER_ADDR)]
+    pub explorer_addr: IpAddr,
+
+    /// The port to run the explorer frontend on.
+    ///
+    /// NOTE(@kariy):
+    // Right now we prevent the port from being 0 because that would mean the actual port would only
+    // be available after the server has been started. And due to some limitations with how the
+    // explorer requires that the node is started first (to get the actual socket address) and
+    // that we also need to pass the explorer address as CORS to the node server.
+    #[arg(long = "explorer.port", value_name = "PORT")]
+    #[arg(default_value_t = DEFAULT_EXPLORER_PORT)]
+    #[arg(value_parser = clap::value_parser!(u16).range(1..))]
+    pub explorer_port: u16,
+}
+
+impl Default for ExplorerOptions {
+    fn default() -> Self {
+        Self {
+            explorer: false,
+            explorer_addr: DEFAULT_EXPLORER_ADDR,
+            explorer_port: DEFAULT_EXPLORER_PORT,
+        }
+    }
+}
+
 // ** Default functions to setup serde of the configuration file **
 fn default_seed() -> String {
     DEFAULT_DEV_SEED.to_string()

crates/katana/explorer/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "katana-explorer"
+version.workspace = true
+edition.workspace = true
+repository.workspace = true
+license-file.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+url.workspace = true
+tiny_http = "0.12"
+tracing.workspace = true
+urlencoding = "2.1.2"
+rust-embed = "6.8.1"