explorer: contract module for managing metadata and source code

This commit introduces a new module that enhances the functionality of the ExplorerService by adding functions for managing and retrieving contract-related data. The new methods include capabilities to retrieve contracts and native contracts, transforming them into ContractRecords suitable for handling by the RPC layer. In addition, we added functionality to handle contract metadata and source code.

Contract Metadata

The new module introduces functions to manage ContractMetadata, including fetching metadata for a given ContractId and adding ContractId and ContractMetaData pairs to the contract metadata store.

Contract Source Code

The module also handles operations on contract source code, such as fetching a list of source code file paths for a given ContractId, retrieving source code content for a specified ContractId and path, and adding source code for a ContractId from a provided tar file. The latter function extracts the tar archive and stores each source file with its path prefixed by the ContractId.

Auxiliary Functions

New auxiliary functions have been added for transforming contract details into a form suitable for the RPC layer, filtering contracts based on their ContractId using a provided function, and extracting source code files from a TAR archive.

Updates to Explorer Startup Sequence

The Explorer startup sequence has been updated to include the loading of native contract source code and metadata. This ensures the explorer prepared with the necessary contract data before beginning its operations.

Bundling Native Contract Source Code On Build

This commit introduces bundling of native contract source code during the build process. a new make target bundle_contracts_src to bundle native contract source code into tar files. This allows the explorer to load the latest native contract source code at startup, enhancing its ability to manage and display contract-related information. The current implementation redirects certain tar output to /dev/null to suppress verbose output. Future improvements will explore more elegant ways to manage this output in a subsequent commit.

Test Functions

We added test coverage to validate functionality across various scenarios, such as loading, storage, retrieval, and validation of contract metadata and contract source code. The primary goal is to validate the core service functionality to ensure the ExplorerService is properly handling contract-related data.
- test_add_metadata: Verifies the addition of ContractMetaData, ensuring the inserted metadata can be correctly retrieved and matches the expected values.
- test_load_native_contract_metadata: Ensures that native contract metadata can be loaded and correctly retrieved for all pre-defined native contract IDs.
- test_load_native_contracts: Validates both the loading and retrieval of native contract source code. It checks that the source paths and contents match the expected results in the corresponding tar archives.
- test_to_contract_record: Tests the transformation of contract details suitable for the RPC layer.

Auxiliary Test Functions
- setup: Sets up a temporary environment for testing by initializing an ExplorerService instance with an isolated sled database.
- verify_source_paths: Confirms that the source paths extracted from a contract tar archive match the source paths retrieved from the store a given ContractId.
- verify_source_content: Validates that the content of files from a contract tar archive matches the content retrieved from the store for a given ContractId.

Running Tests
cargo test contracts::tests

script/research/blockchain-explorer/Cargo.toml

@@ -16,10 +16,6 @@ darkfi-sdk = {path = "../../../src/sdk"}
 darkfi-serial = "0.4.2"
 drk = {path = "../../../bin/drk"}
 
-# Misc
-log = "0.4.22"
-sled-overlay = "0.1.6"
-
 # JSON-RPC
 async-trait = "0.1.83"
 tinyjson = "2.5.1"
@@ -37,6 +33,17 @@ serde = {version = "1.0.210", features = ["derive"]}
 structopt = "0.3.26"
 structopt-toml = "0.5.1"
 
+# Database
+sled-overlay = "0.1.6"
+
+# Misc
+log = "0.4.22"
+lazy_static = "1.5.0"
+tar = "0.4.43"
+
+# Testing
+tempdir = "0.3.7"
+
 [patch.crates-io]
 halo2_proofs = {git="https://github.com/parazyd/halo2", branch="v4"}
 halo2_gadgets = {git="https://github.com/parazyd/halo2", branch="v4"}

script/research/blockchain-explorer/Makefile

@@ -19,11 +19,11 @@ SRC = \
 
 BIN = $(shell grep '^name = ' Cargo.toml | sed 1q | cut -d' ' -f3 | tr -d '"')
 
-all: $(BIN)
+all: $(BIN) bundle_contracts_src
 
 $(BIN): $(SRC)
 	RUSTFLAGS="$(RUSTFLAGS)" $(CARGO) build --target=$(RUST_TARGET) --release --package $@
-    # TODO: Update target path to darkfi project workspace once explorer is transitioned to bin
+	# TODO: Update target path to darkfi project workspace once explorer is transitioned to bin
 	cp -f target/$(RUST_TARGET)/release/$@ $@
 	cp -f target/$(RUST_TARGET)/release/$@ ../../../$@
 
@@ -39,4 +39,14 @@ install: all
 uninstall:
 	rm -f $(DESTDIR)$(PREFIX)/bin/$(BIN)
 
-.PHONY: all clean install uninstall
+bundle_contracts_src:
+	@mkdir -p $(CURDIR)/native_contracts_src
+	@(cd ../../../src && \
+		tar -cf $(CURDIR)/native_contracts_src/deployooor_contract_src.tar -C contract/deployooor/src --transform 's,^./,,' . && \
+		tar -cf $(CURDIR)/native_contracts_src/dao_contract_src.tar -C contract/dao/src --transform 's,^./,,' . 2>/dev/null && \
+		find contract/dao/proof -name '*.zk' -exec tar -rf $(CURDIR)/native_contracts_src/dao_contract_src.tar --transform 's,^.*proof/,proof/,' {} + && \
+		tar -cf $(CURDIR)/native_contracts_src/money_contract_src.tar -C contract/money/src --transform 's,^./,,' . && \
+		find contract/money/proof -name '*.zk' -exec tar -rf $(CURDIR)/native_contracts_src/money_contract_src.tar --transform 's,^.*proof/,proof/,' {} + \
+	)
+
+.PHONY: all clean install uninstall native_contracts

script/research/blockchain-explorer/src/contract_meta_store.rs

@@ -38,8 +38,6 @@ pub struct ContractMetaData {
     pub description: String,
 }
 
-// Temporarily suppress unused code warning until the store is integrated with the explorer code
-#[allow(dead_code)]
 impl ContractMetaData {
     pub fn new(name: String, description: String) -> Self {
         Self { name, description }
@@ -53,8 +51,6 @@ pub struct ContractSourceFile {
     pub content: String,
 }
 
-// Temporarily suppress unused code warning until the store is integrated with the explorer code
-#[allow(dead_code)]
 impl ContractSourceFile {
     /// Creates a `ContractSourceFile` instance.
     pub fn new(path: String, content: String) -> Self {
@@ -75,8 +71,6 @@ pub struct ContractMetaStore {
     pub source_code: sled::Tree,
 }
 
-// Temporarily suppress unused code warning until the store is integrated with the explorer code
-#[allow(dead_code)]
 impl ContractMetaStore {
     /// Creates a `ContractMetaStore` instance.
     pub fn new(db: &sled::Db) -> Result<Self> {

script/research/blockchain-explorer/src/contracts.rs

@@ -0,0 +1,516 @@
+/* This file is part of DarkFi (https://dark.fi)
+ *
+ * Copyright (C) 2020-2024 Dyne.org foundation
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+use std::io::{Cursor, Read};
+
+use tar::Archive;
+use tinyjson::JsonValue;
+
+use darkfi::{Error, Result};
+use darkfi_sdk::crypto::{ContractId, DAO_CONTRACT_ID, DEPLOYOOOR_CONTRACT_ID, MONEY_CONTRACT_ID};
+use darkfi_serial::deserialize;
+
+use crate::{
+    contract_meta_store::{ContractMetaData, ContractSourceFile},
+    ExplorerService,
+};
+
+/// Represents a contract record embellished with details that are not stored on-chain.
+#[derive(Debug, Clone)]
+pub struct ContractRecord {
+    /// The Contract ID as a string
+    pub id: String,
+
+    /// The optional name of the contract
+    pub name: Option<String>,
+
+    /// The optional description of the contract
+    pub description: Option<String>,
+}
+
+impl ContractRecord {
+    /// Auxiliary function to convert a `ContractRecord` into a `JsonValue` array.
+    pub fn to_json_array(&self) -> JsonValue {
+        JsonValue::Array(vec![
+            JsonValue::String(self.id.clone()),
+            JsonValue::String(self.name.clone().unwrap_or_default()),
+            JsonValue::String(self.description.clone().unwrap_or_default()),
+        ])
+    }
+}
+impl ExplorerService {
+    /// Retrieves all contracts from the store excluding native contracts (DAO, Deployooor, and Money),
+    /// transforming them into `Vec` of [`ContractRecord`]s, and returns the result.
+    pub fn get_contracts(&self) -> Result<Vec<ContractRecord>> {
+        let native_contracts = [*DAO_CONTRACT_ID, *DEPLOYOOOR_CONTRACT_ID, *MONEY_CONTRACT_ID];
+        self.get_filtered_contracts(|contract_id| !native_contracts.contains(contract_id))
+    }
+
+    /// Retrieves all native contracts (DAO, Deployooor, and Money) from the store, transforming them
+    /// into `Vec` of [`ContractRecord`]s and returns the result.
+    pub fn get_native_contracts(&self) -> Result<Vec<ContractRecord>> {
+        let native_contracts = [*DAO_CONTRACT_ID, *DEPLOYOOOR_CONTRACT_ID, *MONEY_CONTRACT_ID];
+        self.get_filtered_contracts(|contract_id| native_contracts.contains(contract_id))
+    }
+
+    /// Fetches a list of source code file paths for a given [ContractId], returning an empty vector
+    /// if no contracts are found.
+    pub fn get_contract_source_paths(&self, contract_id: &ContractId) -> Result<Vec<String>> {
+        self.db.contract_meta_store.get_source_paths(contract_id).map_err(|e| {
+            Error::DatabaseError(format!(
+                "[get_contract_source_paths] Retrieval of contract source code paths failed: {e:?}"
+            ))
+        })
+    }
+
+    /// Fetches [`ContractMetaData`] for a given [`ContractId`], returning `None` if no metadata is found.
+    pub fn get_contract_metadata(
+        &self,
+        contract_id: &ContractId,
+    ) -> Result<Option<ContractMetaData>> {
+        self.db.contract_meta_store.get(contract_id).map_err(|e| {
+            Error::DatabaseError(format!(
+                "[get_contract_metadata] Retrieval of contract metadata paths failed: {e:?}"
+            ))
+        })
+    }
+
+    /// Fetches the source code content for a specified [`ContractId`] and `path`, returning `None` if
+    /// no source content is found.
+    pub fn get_contract_source_content(
+        &self,
+        contract_id: &ContractId,
+        path: &str,
+    ) -> Result<Option<String>> {
+        self.db.contract_meta_store.get_source_content(contract_id, path).map_err(|e| {
+            Error::DatabaseError(format!(
+                "[get_contract_source_content] Retrieval of contract source file failed: {e:?}"
+            ))
+        })
+    }
+
+    /// Fetches the total contract count of all deployed contracts in the explorer database.
+    pub fn get_contract_count(&self) -> usize {
+        self.db.blockchain.contracts.wasm.len()
+    }
+
+    /// Adds source code for a specified [`ContractId`] from a provided tar file (in bytes).
+    ///
+    /// This function extracts the tar archive from `tar_bytes`, then loads each source file
+    /// into the store. Each file is keyed by its path prefixed with the Contract ID.
+    /// Returns a successful result or an error.
+    pub fn add_contract_source(&self, contract_id: &ContractId, tar_bytes: &[u8]) -> Result<()> {
+        // Untar the source code
+        let source = untar_source(tar_bytes)?;
+
+        // Insert contract source code
+        self.db.contract_meta_store.insert_source(contract_id, &source).map_err(|e| {
+            Error::DatabaseError(format!(
+                "[add_contract_source] Adding of contract source code failed: {e:?}"
+            ))
+        })
+    }
+
+    /// Adds provided [`ContractId`] with corresponding [`ContractMetaData`] pairs into the contract
+    /// metadata store, returning a successful result upon success.
+    pub fn add_contract_metadata(
+        &self,
+        contract_ids: &[ContractId],
+        metadata: &[ContractMetaData],
+    ) -> Result<()> {
+        self.db.contract_meta_store.insert_metadata(contract_ids, metadata).map_err(|e| {
+            Error::DatabaseError(format!(
+                "[add_contract_metadata] Upload of contract source code failed: {e:?}"
+            ))
+        })
+    }
+
+    /// Converts a [`ContractId`] into a [`ContractRecord`].
+    ///
+    /// This function retrieves the [`ContractMetaData`] associated with the provided Contract ID
+    /// and uses any found metadata to construct a contract record. Upon success, the function
+    /// returns a [`ContractRecord`] containing relevant details about the contract.
+    fn to_contract_record(&self, contract_id: &ContractId) -> Result<ContractRecord> {
+        let metadata = self.db.contract_meta_store.get(contract_id)?;
+        let name: Option<String>;
+        let description: Option<String>;
+
+        // Set name and description based on the presence of metadata
+        if let Some(metadata) = metadata {
+            name = Some(metadata.name);
+            description = Some(metadata.description);
+        } else {
+            name = None;
+            description = None;
+        }
+
+        // Return transformed contract record
+        Ok(ContractRecord { id: contract_id.to_string(), name, description })
+    }
+
+    /// Auxiliary function that retrieves [`ContractRecord`]s filtered by a provided `filter_fn` closure.
+    ///
+    /// This function accepts a filter function `Fn(&ContractId) -> bool` that determines
+    /// which contracts are included based on their [`ContractId`]. It iterates over
+    /// Contract IDs stored in the blockchain's contract tree, applying the filter function to decide inclusion.
+    /// Converts the filtered Contract IDs into [`ContractRecord`] instances, returning them as a `Vec`,
+    /// or an empty `Vec` if no contracts are found.
+    fn get_filtered_contracts<F>(&self, filter_fn: F) -> Result<Vec<ContractRecord>>
+    where
+        F: Fn(&ContractId) -> bool,
+    {
+        let contract_keys = self.db.blockchain.contracts.wasm.iter().keys();
+
+        // Iterate through stored Contract IDs, filtering out the contracts based filter
+        contract_keys
+            .filter_map(|serialized_contract_id| {
+                // Deserialize the serialized Contract ID
+                let contract_id: ContractId = match serialized_contract_id
+                    .map_err(Error::from)
+                    .and_then(|id_bytes| deserialize(&id_bytes).map_err(Error::from))
+                {
+                    Ok(id) => id,
+                    Err(e) => {
+                        return Some(Err(Error::DatabaseError(format!(
+                            "[get_filtered_contracts] Contract ID retrieval or deserialization failed: {e:?}"
+                        ))));
+                    }
+                };
+
+                // Apply the filter
+                if filter_fn(&contract_id) {
+                    // Convert the matching Contract ID into a `ContractRecord`, return result
+                    return match self.to_contract_record(&contract_id).map_err(|e| {
+                        Error::DatabaseError(format!("[get_filtered_contracts] Failed to convert contract: {e:?}"))
+                    }) {
+                        Ok(record) => Some(Ok(record)),
+                        Err(e) => Some(Err(e)),
+                    };
+                }
+
+                // Skip contracts that do not match the filter
+                None
+            })
+            .collect::<Result<Vec<ContractRecord>>>()
+    }
+}
+
+/// Auxiliary function that extracts source code files from a TAR archive provided as a byte slice [`&[u8]`],
+/// returning a `Vec` of [`ContractSourceFile`]s representing the extracted file paths and their contents.
+pub fn untar_source(tar_bytes: &[u8]) -> Result<Vec<ContractSourceFile>> {
+    // Use a Cursor and archive to read the tar file
+    let cursor = Cursor::new(tar_bytes);
+    let mut archive = Archive::new(cursor);
+
+    // Vectors to hold the source paths and source contents
+    let mut source: Vec<ContractSourceFile> = Vec::new();
+
+    // Iterate through the entries in the tar archive
+    for tar_entry in archive.entries()? {
+        let mut tar_entry = tar_entry?;
+        let path = tar_entry.path()?.to_path_buf();
+
+        // Check if the entry is a file
+        if tar_entry.header().entry_type().is_file() {
+            let mut content = Vec::new();
+            tar_entry.read_to_end(&mut content)?;
+
+            // Convert the contents into a string
+            let source_content = String::from_utf8(content)
+                .map_err(|_| Error::ParseFailed("Failed converting source code to a string"))?;
+
+            // Collect source paths and contents
+            let path_str = path.to_string_lossy().into_owned();
+            source.push(ContractSourceFile::new(path_str, source_content));
+        }
+    }
+
+    Ok(source)
+}
+
+/// This test module ensures the correctness of the [`ExplorerService`] functionality with
+/// respect to smart contracts.
+///
+/// The tests in this module cover adding, loading, storing, retrieving, and validating contract
+/// metadata and source code. The primary goal is to validate the accuracy and reliability of
+/// the `ExplorerService` when handling contract-related operations.
+#[cfg(test)]
+mod tests {
+    use std::{fs::File, io::Read, path::Path};
+
+    use tar::Archive;
+    use tempdir::TempDir;
+
+    use darkfi::Error::Custom;
+    use darkfi_sdk::crypto::MONEY_CONTRACT_ID;
+
+    use super::*;
+    use crate::test_utils::init_logger;
+
+    /// Tests the adding of [`ContractMetaData`] to the store by adding
+    /// metadata, and verifying the inserted data matches the expected results.
+    #[test]
+    fn test_add_metadata() -> Result<()> {
+        // Setup test, returning initialized service
+        let service = setup()?;
+
+        // Unique identifier for contracts in tests
+        let contract_id: ContractId = *MONEY_CONTRACT_ID;
+
+        // Declare expected metadata used for test
+        let expected_metadata: ContractMetaData = ContractMetaData::new(
+            "Money Contract".to_string(),
+            "Money Contract Description".to_string(),
+        );
+
+        // Add the metadata
+        service.add_contract_metadata(&[contract_id], &[expected_metadata.clone()])?;
+
+        // Get the metadata that was loaded as actual results
+        let actual_metadata = service.get_contract_metadata(&contract_id)?;
+
+        // Verify existence of loaded metadata
+        assert!(actual_metadata.is_some());
+
+        // Confirm actual metadata match expected results
+        assert_eq!(actual_metadata.unwrap(), expected_metadata.clone());
+
+        Ok(())
+    }
+
+    /// This test validates the loading and retrieval of native contract metadata. It sets up the
+    /// explorer service, loads native contract metadata, and then verifies metadata retrieval
+    /// for each native contract.
+    #[test]
+    fn test_load_native_contract_metadata() -> Result<()> {
+        // Setup test, returning initialized service
+        let service = setup()?;
+
+        // Load native contract metadata
+        service.load_native_contract_metadata()?;
+
+        // Define Contract IDs used to retrieve loaded metadata
+        let native_contract_ids = [*DAO_CONTRACT_ID, *DEPLOYOOOR_CONTRACT_ID, *MONEY_CONTRACT_ID];
+
+        // For each native contract, verify metadata was loaded
+        for contract_id in native_contract_ids.iter() {
+            let metadata = service.get_contract_metadata(contract_id)?;
+            assert!(metadata.is_some());
+        }
+
+        Ok(())
+    }
+
+    /// This test validates the loading, storage, and retrieval of native contract source code. It sets up the
+    /// explorer service, loads native contract sources, and then verifies both the source paths and content
+    /// for each native contract. The test compares the retrieved source paths and content against the expected
+    /// results from the corresponding tar archives.
+    #[test]
+    fn test_load_native_contracts() -> Result<()> {
+        // Setup test, returning initialized service
+        let service = setup()?;
+
+        // Load native contracts
+        service.load_native_contract_sources()?;
+
+        // Define contract archive paths
+        let native_contract_tars = [
+            "native_contracts_src/dao_contract_src.tar",
+            "native_contracts_src/deployooor_contract_src.tar",
+            "native_contracts_src/money_contract_src.tar",
+        ];
+
+        // Define Contract IDs to associate with each contract source archive
+        let native_contract_ids = [*DAO_CONTRACT_ID, *DEPLOYOOOR_CONTRACT_ID, *MONEY_CONTRACT_ID];
+
+        // Iterate archive and verify actual match expected results
+        for (&tar_file, &contract_id) in native_contract_tars.iter().zip(&native_contract_ids) {
+            // Verify that source paths match
+            verify_source_paths(&service, tar_file, contract_id)?;
+
+            // Verify that source content match
+            verify_source_content(&service, tar_file, contract_id)?;
+        }
+
+        Ok(())
+    }
+
+    /// This test validates the transformation of a [`ContractId`] into a [`ContractRecord`].
+    /// It sets up the explorer service, adds test metadata for a specific Contract ID, and then verifies the
+    /// correct transformation of this Contract ID into a ContractRecord.
+    #[test]
+    fn test_to_contract_record() -> Result<()> {
+        // Setup test, returning initialized service
+        let service = setup()?;
+
+        // Unique identifier for contracts in tests
+        let contract_id: ContractId = *MONEY_CONTRACT_ID;
+
+        // Declare expected metadata used for test
+        let expected_metadata: ContractMetaData = ContractMetaData::new(
+            "Money Contract".to_string(),
+            "Money Contract Description".to_string(),
+        );
+
+        // Load contract metadata used for test
+        service.add_contract_metadata(&[contract_id], &[expected_metadata.clone()])?;
+
+        // Transform Contract ID to a `ContractRecord`
+        let contract_record = service.to_contract_record(&contract_id)?;
+
+        // Verify that name and description exist
+        assert!(
+            contract_record.name.is_some(),
+            "Expected to_contract_record to return a contract with name"
+        );
+        assert!(
+            contract_record.description.is_some(),
+            "Expected to_contract_record to return a contract with description"
+        );
+
+        // Verify that id, name, and description match expected results
+        assert_eq!(contract_id.to_string(), contract_record.id);
+        assert_eq!(expected_metadata.name, contract_record.name.unwrap());
+        assert_eq!(expected_metadata.description, contract_record.description.unwrap());
+
+        Ok(())
+    }
+
+    /// Sets up a test case for contract metadata store testing by initializing the logger
+    /// and returning an initialized [`ExplorerService`].
+    fn setup() -> Result<ExplorerService> {
+        // Initialize logger to show execution output
+        init_logger(simplelog::LevelFilter::Off, vec!["sled", "runtime", "net"]);
+
+        // Create a temporary directory for sled DB
+        let temp_dir = TempDir::new("test")?;
+
+        // Initialize a sled DB instance using the temporary directory's path
+        let db_path = temp_dir.path().join("sled_db");
+
+        // Initialize the explorer service
+        ExplorerService::new(db_path.to_string_lossy().into_owned())
+    }
+
+    /// This Auxiliary function verifies that the loaded native contract source paths match the expected results
+    /// from a given contract archive. This function extracts source paths from the specified `tar_file`, retrieves
+    /// the actual paths for the [`ContractId`] from the ExplorerService, and compares them to ensure they match.
+    fn verify_source_paths(
+        service: &ExplorerService,
+        tar_file: &str,
+        contract_id: ContractId,
+    ) -> Result<()> {
+        // Read the tar file and extract source paths
+        let tar_bytes = std::fs::read(tar_file)?;
+        let mut expected_source_paths = extract_file_paths_from_tar(&tar_bytes)?;
+
+        // Retrieve and sort actual source paths for the provided Contract ID
+        let mut actual_source_paths = service.get_contract_source_paths(&contract_id)?;
+
+        // Sort paths to ensure they are in the same order needed for assert
+        expected_source_paths.sort();
+        actual_source_paths.sort();
+
+        // Verify actual source matches expected result
+        assert_eq!(
+            expected_source_paths, actual_source_paths,
+            "Mismatch between expected and actual source paths for tar file: {}",
+            tar_file
+        );
+
+        Ok(())
+    }
+
+    /// This auxiliary function verifies that the loaded native contract source content matches the
+    /// expected results from a given contract source archive. It extracts source files from the specified
+    /// `tar_file`, retrieves the actual content for each file path using the [`ContractId`] from the
+    /// ExplorerService, and compares them to ensure the content match.
+    fn verify_source_content(
+        service: &ExplorerService,
+        tar_file: &str,
+        contract_id: ContractId,
+    ) -> Result<()> {
+        // Read the tar file
+        let tar_bytes = std::fs::read(tar_file)?;
+        let expected_source_paths = extract_file_paths_from_tar(&tar_bytes)?;
+
+        // Validate contents of tar archive source code content
+        for file_path in expected_source_paths {
+            // Get the source code content
+            let actual_source = service.get_contract_source_content(&contract_id, &file_path)?;
+
+            // Verify source content exists
+            assert!(
+                actual_source.is_some(),
+                "Actual source `{}` is missing in the store.",
+                file_path
+            );
+
+            // Read the source content from the tar archive
+            let expected_source = read_file_from_tar(tar_file, &file_path)?;
+
+            // Verify actual source matches expected results
+            assert_eq!(
+                actual_source.unwrap(),
+                expected_source,
+                "Actual source does not match expected results `{}`.",
+                file_path
+            );
+        }
+
+        Ok(())
+    }
+
+    /// Auxiliary function that reads the contents of specified `file_path` within a tar archive.
+    fn read_file_from_tar(tar_path: &str, file_path: &str) -> Result<String> {
+        let file = File::open(tar_path)?;
+        let mut archive = Archive::new(file);
+        for entry in archive.entries()? {
+            let mut entry = entry?;
+            if let Ok(path) = entry.path() {
+                if path == Path::new(file_path) {
+                    let mut content = String::new();
+                    entry.read_to_string(&mut content)?;
+                    return Ok(content);
+                }
+            }
+        }
+
+        Err(Custom(format!("File {} not found in tar archive.", file_path)))
+    }
+
+    /// Auxiliary function that extracts all file paths from the given `tar_bytes` tar archive.
+    pub fn extract_file_paths_from_tar(tar_bytes: &[u8]) -> Result<Vec<String>> {
+        let cursor = Cursor::new(tar_bytes);
+        let mut archive = Archive::new(cursor);
+
+        // Collect paths from the tar archive
+        let mut file_paths = Vec::new();
+        for entry in archive.entries()? {
+            let entry = entry?;
+            let path = entry.path()?;
+
+            // Skip directories and only include files
+            if entry.header().entry_type().is_file() {
+                file_paths.push(path.to_string_lossy().to_string());
+            }
+        }
+
+        Ok(file_paths)
+    }
+}

script/research/blockchain-explorer/src/main.rs

@@ -16,8 +16,13 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-use std::{collections::HashSet, sync::Arc};
+use std::{
+    collections::{HashMap, HashSet},
+    str::FromStr,
+    sync::Arc,
+};
 
+use lazy_static::lazy_static;
 use log::{error, info};
 use rpc_blocks::subscribe_blocks;
 use sled_overlay::sled;
@@ -38,8 +43,13 @@ use darkfi::{
     validator::utils::deploy_native_contracts,
     Error, Result,
 };
+use darkfi_sdk::crypto::{ContractId, DAO_CONTRACT_ID, DEPLOYOOOR_CONTRACT_ID, MONEY_CONTRACT_ID};
 
-use crate::metrics_store::MetricsStore;
+use crate::{
+    contract_meta_store::{ContractMetaData, ContractMetaStore},
+    contracts::untar_source,
+    metrics_store::MetricsStore,
+};
 
 /// Crate errors
 mod error;
@@ -50,15 +60,18 @@ mod rpc_blocks;
 mod rpc_statistics;
 mod rpc_transactions;
 
-/// Database functionality related to blocks
+/// Service functionality related to blocks
 mod blocks;
 
-/// Database functionality related to transactions
+/// Service functionality related to transactions
 mod transactions;
 
-/// Database functionality related to statistics
+/// Service functionality related to statistics
 mod statistics;
 
+/// Service functionality related to contracts
+mod contracts;
+
 /// Test utilities used for unit and integration testing
 mod test_utils;
 
@@ -71,6 +84,26 @@ mod contract_meta_store;
 const CONFIG_FILE: &str = "blockchain_explorer_config.toml";
 const CONFIG_FILE_CONTENTS: &str = include_str!("../blockchain_explorer_config.toml");
 
+// Load the contract source archives to bootstrap them on explorer startup
+lazy_static! {
+    static ref NATIVE_CONTRACT_SOURCE_ARCHIVES: HashMap<String, &'static [u8]> = {
+        let mut src_map = HashMap::new();
+        src_map.insert(
+            MONEY_CONTRACT_ID.to_string(),
+            &include_bytes!("../native_contracts_src/money_contract_src.tar")[..],
+        );
+        src_map.insert(
+            DAO_CONTRACT_ID.to_string(),
+            &include_bytes!("../native_contracts_src/dao_contract_src.tar")[..],
+        );
+        src_map.insert(
+            DEPLOYOOOR_CONTRACT_ID.to_string(),
+            &include_bytes!("../native_contracts_src/deployooor_contract_src.tar")[..],
+        );
+        src_map
+    };
+}
+
 #[derive(Clone, Debug, Deserialize, StructOpt, StructOptToml)]
 #[serde(default)]
 #[structopt(name = "blockchain-explorer", about = cli_desc!())]
@@ -112,6 +145,7 @@ struct Args {
 ///
 /// - Data Transformation: Converting database data into structured responses suitable for RPC callers.
 /// - Blocks: Synchronization, retrieval, counting, and management.
+/// - Contracts: Handling native and user contract data, source code, tar files, and metadata.
 /// - Metrics: Providing metric-related data over the life of the chain.
 /// - Transactions: Synchronization, calculating gas data, retrieval, counting, and related block information.
 pub struct ExplorerService {
@@ -120,20 +154,75 @@ pub struct ExplorerService {
 }
 
 impl ExplorerService {
-    /// Creates a new `ExplorerService` instance
-    ///
-    /// The function sets up a new explorer database using the given [`String`] `db_path`, deploying
-    /// native contracts needed for calculating transaction gas data.
-    async fn new(db_path: String) -> Result<Self> {
+    /// Creates a new `ExplorerService` instance.
+    pub fn new(db_path: String) -> Result<Self> {
         // Initialize explorer database
         let db = ExplorerDb::new(db_path)?;
 
-        // Deploy native contracts needed to calculated transaction gas data and commit changes
-        let overlay = BlockchainOverlay::new(&db.blockchain)?;
+        Ok(Self { db })
+    }
+
+    /// Initializes the explorer service by deploying native contracts and loading native contract
+    /// source code and metadata required for its operation.
+    pub async fn init(&self) -> Result<()> {
+        self.deploy_native_contracts().await?;
+        self.load_native_contract_sources()?;
+        self.load_native_contract_metadata()?;
+        Ok(())
+    }
+
+    /// Deploys native contracts required for gas calculation and retrieval.
+    pub async fn deploy_native_contracts(&self) -> Result<()> {
+        let overlay = BlockchainOverlay::new(&self.db.blockchain)?;
         deploy_native_contracts(&overlay, 10).await?;
         overlay.lock().unwrap().overlay.lock().unwrap().apply()?;
+        Ok(())
+    }
 
-        Ok(Self { db })
+    /// Loads native contract source code into the explorer database by extracting it from tar archives
+    /// created during the explorer build process. The extracted source code is associated with
+    /// the corresponding [`ContractId`] for each loaded contract and stored.
+    pub fn load_native_contract_sources(&self) -> Result<()> {
+        // Iterate each native contract source archive
+        for (contract_id_str, archive_bytes) in NATIVE_CONTRACT_SOURCE_ARCHIVES.iter() {
+            // Untar the native contract source code
+            let source_code = untar_source(archive_bytes)?;
+
+            // Parse contract id into a contract id instance
+            let contract_id = &ContractId::from_str(contract_id_str)?;
+
+            // Add source code into the `ContractMetaStore`
+            self.db.contract_meta_store.insert_source(contract_id, &source_code)?;
+            info!("Loaded contract source for contract {}", contract_id_str.to_string());
+        }
+        Ok(())
+    }
+
+    /// Loads [`ContractMetaData`] for deployed native contracts into the explorer database by adding descriptive
+    /// information (e.g., name and description) used to display contract details.
+    pub fn load_native_contract_metadata(&self) -> Result<()> {
+        let contract_ids = [*MONEY_CONTRACT_ID, *DAO_CONTRACT_ID, *DEPLOYOOOR_CONTRACT_ID];
+
+        // Create pre-defined native contract metadata
+        let metadatas = [
+            ContractMetaData::new(
+                "Money".to_string(),
+                "Facilitates money transfers, atomic swaps, minting, freezing, and staking of consensus tokens".to_string(),
+            ),
+            ContractMetaData::new(
+                "DAO".to_string(),
+                "Provides functionality for Anonymous DAOs".to_string(),
+            ),
+            ContractMetaData::new(
+                "Deployoor".to_string(),
+                "Handles non-native smart contract deployments".to_string(),
+            ),
+        ];
+
+        // Load contract metadata into the `ContractMetaStore`
+        self.db.contract_meta_store.insert_metadata(&contract_ids, &metadatas)?;
+
+        Ok(())
     }
 }
 
@@ -147,6 +236,8 @@ pub struct ExplorerDb {
     pub blockchain: Blockchain,
     /// Store for tracking chain-related metrics
     pub metrics_store: MetricsStore,
+    /// Store for managing contract metadata, source code, and related data
+    pub contract_meta_store: ContractMetaStore,
 }
 
 impl ExplorerDb {
@@ -156,17 +247,19 @@ impl ExplorerDb {
         let sled_db = sled::open(&db_path)?;
         let blockchain = Blockchain::new(&sled_db)?;
         let metrics_store = MetricsStore::new(&sled_db)?;
+        let contract_meta_store = ContractMetaStore::new(&sled_db)?;
+
         info!(target: "blockchain-explorer", "Initialized explorer database {}, block count: {}", db_path.display(), blockchain.len());
-        Ok(Self { sled_db, blockchain, metrics_store })
+        Ok(Self { sled_db, blockchain, metrics_store, contract_meta_store })
     }
 }
 
 /// Defines a daemon structure responsible for handling incoming JSON-RPC requests and delegating them
 /// to the backend layer for processing. It provides a JSON-RPC interface for managing operations related to
-/// blocks, transactions, and metrics.
+/// blocks, transactions, contracts, and metrics.
 ///
 /// Upon startup, the daemon initializes a background task to handle incoming JSON-RPC requests.
-/// This includes processing operations related to blocks, transactions, and metrics by
+/// This includes processing operations related to blocks, transactions, contracts, and metrics by
 /// delegating them to the backend and returning appropriate RPC responses. Additionally, the daemon
 /// synchronizes blocks from the `darkfid` daemon into the explorer database and subscribes
 /// to new blocks, ensuring that the local database remains updated in real-time.
@@ -186,8 +279,11 @@ impl Explorerd {
         let rpc_client = RpcClient::new(endpoint.clone(), ex).await?;
         info!(target: "blockchain-explorer", "Created rpc client: {:?}", endpoint);
 
-        // Initialize explorer service
-        let service = ExplorerService::new(db_path).await?;
+        // Create explorer service
+        let service = ExplorerService::new(db_path)?;
+
+        // Initialize the explorer service
+        service.init().await?;
 
         Ok(Self { rpc_connections: Mutex::new(HashSet::new()), rpc_client, service })
     }