delta_domain_sdk/

builder.rs

//! # Builder
//!
//! Builder API to configure and construct new domains.
//!
//! See [`DomainBuilder`] and [`Domain`] for creating a configured domain
//! instance.

#[cfg(feature = "rocksdb")]
use crate::storage::options::DbOptions;
use crate::{
    base_layer::{
        mock,
        rpc,
        BaseLayer,
    },
    config::{
        Config,
        StorageConfig,
    },
    domain_agreement,
    in_memory,
    proving,
    storage::{
        Database,
        DefaultStorage,
    },
    Domain,
};
use base_sdk::{
    core::Shard,
    crypto::ed25519,
    vaults::{
        Address,
        Vault,
    },
};
use domain_runtime::{
    config::{
        BaseLayerRetryConfig,
        RuntimeConfig,
        SdlRetentionConfig,
        SignatureVerificationConfig,
    },
    storage::ColumnFamilies,
};
use http::{
    uri::InvalidUri,
    Uri,
};
use proving_clients::Proving;
use snafu::{
    ResultExt,
    Snafu,
};
use std::{
    collections::HashMap,
    net::{
        Ipv6Addr,
        SocketAddr,
    },
    num::NonZero,
};
use storage::{
    column_family::ColumnFamilies as _,
    database::{
        GenericDatabase,
        StorageError,
    },
    key_value::KeyValueStorage,
};

/// Errors occurring in the [DomainBuilder]
#[derive(Debug, Snafu)]
pub enum Error {
    /// Base layer client initialization failed
    #[snafu(display("Base layer error: {source}"))]
    BaseLayer {
        /// The underlying error from the base layer client
        source: Box<dyn std::error::Error + Send + Sync>,
    },
    /// Error when reading from storage
    #[snafu(display("Error while initializing storage: {source}"))]
    Storage {
        /// The underlying storage error
        source: StorageError,
    },
}

/// Default address to expose the admin API if the feature is active.
pub const ADMIN_API_DEFAULT_ADDR: SocketAddr =
    SocketAddr::new(std::net::IpAddr::V6(Ipv6Addr::UNSPECIFIED), 4001);

/// Builder to configure and create new domains
///
/// Obtain an instance via [Domain::builder] or [Domain::from_config], then
/// configure the domain with, for example:
/// - [`with_rpc`](Self::with_rpc) to connect to a base layer RPC
/// - [`with_proving_client`](Self::with_proving_client) to set the proving
///   client
///
/// Finally, call [`build`](Self::build) to create the [Domain].
#[derive(Debug)]
pub struct DomainBuilder<S> {
    config: RuntimeConfig,
    keypair: ed25519::PrivKey,
    base_layer: BaseLayerOptions,
    proving: Box<dyn Proving>,
    storage: S,
    admin_api_address: SocketAddr,
}

/// Options to configure the RPC client
#[derive(Debug)]
enum BaseLayerOptions {
    Rpc { url: Result<Uri, Error> },
    Mock { vaults: HashMap<Address, Vault> },
}

impl BaseLayerOptions {
    fn mock() -> Self {
        Self::Mock {
            vaults: Default::default(),
        }
    }
}

impl Domain<DefaultStorage> {
    /// Construct a new domain from configuration.
    ///
    /// See [Config] for how to load configuration.
    ///
    /// By default, a mock RPC is configured. Use [DomainBuilder::with_rpc] or
    /// set a `rpc_url` in the configuration file to use a real base layer RPC.
    ///
    /// By default, a mock proving client is used. To configure a proving client
    /// use [`with_proving_client`](DomainBuilder::with_proving_client) or set
    /// `proving` in the configuration file.
    ///
    /// ## Returns
    /// A [DomainBuilder] to continue configuration or build the domain.
    pub fn from_config(config: Config) -> DomainBuilder<DbBuilderType> {
        let builder = Self::builder(config.shard, config.keypair);

        let builder = if let Some(retention) = config.sdl_retention {
            builder.with_sdl_retention(retention)
        } else {
            builder
        };

        let builder = if let Some(url) = config.rpc_url {
            builder.with_rpc(url)
        } else {
            builder
        };

        #[cfg(not(feature = "rocksdb"))]
        if let Some(StorageConfig::Rocksdb { .. }) = config.storage {
            panic!("The `rocksdb` feature is not enabled, but the configuration requests it.");
        }

        #[cfg(feature = "rocksdb")]
        let builder = match config.storage {
            Some(StorageConfig::InMemory) => {
                panic!("The `rocksdb` feature is enabled, but the configuration requests in-memory storage.");
            },
            Some(StorageConfig::Rocksdb { path }) => {
                builder.with_rocksdb(DbOptions::default().with_db_prefix_path(path))
            },
            None => builder,
        };

        #[cfg(not(feature = "admin-api"))]
        if config.admin_api.is_some() {
            panic!("The `admin-api` feature is not enabled, but the configuration requests it.");
        }

        #[cfg(feature = "admin-api")]
        let builder = if let Some(addr) = config.admin_api {
            builder.with_admin_api_ip(addr)
        } else {
            builder
        };

        if let Some(proving_config) = config.proving {
            builder.with_proving_client(proving_config.into_proving_client())
        } else {
            builder
        }
    }

    /// Construct a new domain with the builder.
    ///
    /// The storage layer used is defined by the cargo feature `rocksdb`
    /// (RocksDB if set, in-memory if not).
    ///
    /// # Parameters
    /// * `shard` - the shard this domain operates
    /// * `keypair` - the domain signs transactions with
    ///
    /// ## Returns
    /// A [DomainBuilder] to continue configuration or build the domain.
    pub fn builder(
        shard: NonZero<Shard>,
        keypair: ed25519::PrivKey,
    ) -> DomainBuilder<DbBuilderType> {
        #[cfg(not(feature = "rocksdb"))]
        let storage = Database::new(in_memory::Storage::new());
        #[cfg(feature = "rocksdb")]
        let storage = DbOptions::default();

        // this is the unique place where default values are defined
        DomainBuilder {
            config: RuntimeConfig {
                shard,
                signature_verification: SignatureVerificationConfig::Enabled,
                sdl_retention: SdlRetentionConfig::default(),
                base_layer_retry: BaseLayerRetryConfig::OnEpochMismatch,
            },
            keypair,
            storage,
            base_layer: BaseLayerOptions::mock(),
            proving: Box::new(proving::mock::Client::global_laws()),
            admin_api_address: ADMIN_API_DEFAULT_ADDR,
        }
    }

    /// Same as [Self::builder] but with storage forced to in-memory and
    /// base layer retry activated.
    ///
    ///  NOTE: tests should always use this constructor!
    pub fn in_mem_builder(
        shard: NonZero<Shard>,
        keypair: ed25519::PrivKey,
    ) -> DomainBuilder<Database<in_memory::Storage>> {
        Self::builder(shard, keypair).with_storage(in_memory::Storage::new())
    }
}

impl<S> DomainBuilder<S> {
    /// Use the given proving client to generate proofs.
    ///
    /// This can be a custom implementation of [Proving] or a provided one, for
    /// example SP1 (the `sp1` feature needs to be active for that):
    /// ```rust,no_run
    /// use delta_domain_sdk::{proving, Domain};
    /// # use std::num::NonZero;
    /// # use base_sdk::crypto::ed25519::PrivKey;
    /// # let builder = Domain::builder(NonZero::new(1).unwrap(), PrivKey::generate());
    /// # let local_laws_elf = &[1,2,3];
    ///
    /// # #[cfg(feature = "sp1")]
    /// builder.with_proving_client(
    ///     Box::new(proving::sp1::Client::global_laws_cpu()
    ///         .with_local_laws_cpu(local_laws_elf))
    /// );
    /// ```
    pub fn with_proving_client(self, proving: Box<dyn Proving>) -> Self {
        Self {
            config: self.config,
            keypair: self.keypair,
            base_layer: self.base_layer,
            proving,
            storage: self.storage,
            admin_api_address: self.admin_api_address,
        }
    }

    /// Use a custom [KeyValueStorage] implementation
    ///
    /// ## Note
    /// SDK assumes that iteration order for [column families][ColumnFamilies]
    /// is in lexicographical order of the keys/indices.
    pub fn with_storage<S2>(self, storage: S2) -> DomainBuilder<Database<S2>>
    where
        S2: KeyValueStorage<ColumnFamilyIdentifier = ColumnFamilies, Error = StorageError>
            + Send
            + Sync
            + 'static,
    {
        self.with_database(Database::new(storage))
    }

    /// Use a custom [KeyValueStorage] implementation wrapped in a [Database].
    ///
    /// ## Note
    /// SDK assumes that iteration order for [column families][ColumnFamilies]
    /// is in lexicographical order of the keys/indices.
    pub fn with_database<S2>(self, database: Database<S2>) -> DomainBuilder<Database<S2>>
    where
        S2: KeyValueStorage<ColumnFamilyIdentifier = ColumnFamilies, Error = StorageError>
            + Send
            + Sync
            + 'static,
    {
        DomainBuilder {
            config: self.config,
            keypair: self.keypair,
            base_layer: self.base_layer,
            proving: self.proving,
            storage: database,
            admin_api_address: self.admin_api_address,
        }
    }

    /// Configure SDL retention behavior.
    pub const fn with_sdl_retention(mut self, sdl_retention: SdlRetentionConfig) -> Self {
        self.config.sdl_retention = sdl_retention;
        self
    }

    /// Configure base layer transaction retry.
    pub const fn with_base_layer_retry(mut self, config: BaseLayerRetryConfig) -> Self {
        self.config.base_layer_retry = config;
        self
    }

    /// Use an RPC to connect to the base layer network.
    ///
    /// # Parameters
    /// * `url` - of the base layer RPC
    pub fn with_rpc(mut self, url: impl TryInto<Uri, Error = InvalidUri> + Send) -> Self {
        self.base_layer = BaseLayerOptions::Rpc {
            url: url.try_into().boxed().context(BaseLayerSnafu),
        };
        self
    }
    /// Override any previously configured RPC (even `rpc_url` from config file)
    /// and use a mock RPC as base layer network that can return the given
    /// `mock_vaults` when requested.
    ///
    /// Note that only sharded vaults are supported.
    pub fn with_mock_rpc(mut self, mock_vaults: HashMap<Address, Vault>) -> Self {
        self.base_layer = BaseLayerOptions::Mock {
            vaults: mock_vaults,
        };
        self
    }

    /// Expose the admin HTTP API under the given `port` and IPv6 address `[::]`.
    ///
    /// Note if the`admin-api` feature is active, the API is by default exposed
    /// under [ADMIN_API_DEFAULT_ADDR].
    #[cfg(feature = "admin-api")]
    pub fn with_admin_api(self, port: u16) -> Self {
        self.with_admin_api_ip((ADMIN_API_DEFAULT_ADDR.ip(), port).into())
    }

    /// Expose the admin HTTP API under the given IP address and port.
    ///
    /// Note if the`admin-api` feature is active, the API is by default exposed
    /// under IP `[::]` and [ADMIN_API_DEFAULT_ADDR].
    #[cfg(feature = "admin-api")]
    pub const fn with_admin_api_ip(mut self, ip: SocketAddr) -> Self {
        self.admin_api_address = ip;
        self
    }
}

#[cfg(not(feature = "rocksdb"))]
type DbBuilderType = Database<in_memory::Storage>;
#[cfg(feature = "rocksdb")]
type DbBuilderType = DbOptions;

#[cfg(feature = "rocksdb")]
mod rocksdb {
    use super::*;
    use crate::storage::{
        options::DbOptions,
        rocksdb,
    };
    use storage::database::spec::DbSpecWithUserOptions;
    use storage_rocksdb::RocksDb;

    // We still implement this setter, so people can manually configure RocksDB
    impl<S> DomainBuilder<S> {
        /// Use RocksDb with the given configuration as storage
        pub fn with_rocksdb(self, db_options: DbOptions) -> DomainBuilder<DbOptions> {
            DomainBuilder {
                config: self.config,
                keypair: self.keypair,
                base_layer: self.base_layer,
                proving: self.proving,
                storage: db_options,
                admin_api_address: self.admin_api_address,
            }
        }
    }

    impl DomainBuilder<DbOptions> {
        /// Build the domain to get its handles.
        pub async fn build(self) -> Result<Domain<rocksdb::Storage>, Error> {
            let db_spec_with_options = DbSpecWithUserOptions::new(self.storage.clone().into());
            let storage = RocksDb::new_static(db_spec_with_options).context(StorageSnafu)?;
            self.with_storage(storage).build().await
        }
    }
}

impl<S> DomainBuilder<Database<S>>
where
    S: KeyValueStorage<ColumnFamilyIdentifier = ColumnFamilies, Error = StorageError>
        + Send
        + Sync
        + 'static,
{
    /// Build the domain to get its handles.
    pub async fn build(self) -> Result<Domain<S>, Error> {
        let Self {
            config,
            keypair,
            proving,
            storage: db,
            base_layer,
            admin_api_address,
        } = self;

        let (base_layer, seed_vaults) = match base_layer {
            BaseLayerOptions::Rpc { url } => {
                let rpc_client = rpc::BaseLayer::new(url?.to_string(), keypair)
                    .await
                    .boxed()
                    .context(BaseLayerSnafu)?;

                rpc_client
                    .check_valid_domain_agreement(config.shard)
                    .await
                    .or_else(|err| match err {
                        // actually return/fail for RPC errors
                        domain_agreement::Error::Rpc { source } => {
                            Err(source).context(BaseLayerSnafu)
                        },
                        domain_agreement::Error::NotFound
                        | domain_agreement::Error::WrongOperator { .. } => Ok(()),
                    })?;

                // Fetches ALL non-empty vaults of the shard from the RPC and
                // will thus overwrite any vaults stored in an existing RocksDB.
                // Therefore, we only want to overwrite if there is no vault
                // data already in the storage (i.e. fresh RocksDB or in-memory).
                // TODO(#2021): remove this
                let seed_vaults = if has_vaults(db.storage()) {
                    tracing::info!(
                        "Seed vaults already present in storage. Not fetching from RPC."
                    );
                    HashMap::new()
                } else {
                    rpc_client
                        .get_all_vaults_of(config.shard)
                        .await
                        .boxed()
                        .context(BaseLayerSnafu)?
                };

                (BaseLayer::Rpc(rpc_client), seed_vaults)
            },

            BaseLayerOptions::Mock {
                vaults: mock_vaults,
            } => {
                // Clone local mock vaults to DB seed
                let seed_vaults = mock_vaults
                    .iter()
                    .filter(|(id, _)| id.shard() == config.shard.get())
                    .map(|(address, vault)| (address.owner(), vault.clone()))
                    .collect();

                tracing::info!("Starting domain with a mock base layer RPC.");
                (
                    BaseLayer::Mock(mock::BaseLayer::new(mock_vaults)),
                    seed_vaults,
                )
            },
        };

        tracing::info!(
            "The domain will be started with {} seed vaults.",
            seed_vaults.len()
        );

        Ok(Domain::new(
            config,
            proving,
            db,
            base_layer,
            seed_vaults,
            admin_api_address,
        ))
    }
}

fn has_vaults<S>(storage: &S) -> bool
where
    S: KeyValueStorage<ColumnFamilyIdentifier = ColumnFamilies>,
{
    matches!(
        storage.iter(ColumnFamilies::FinalizedVaults.name()).next(),
        Some(Ok(_))
    )
}

#[cfg(test)]
mod tests {
    use super::*;
    use base_sdk::crypto::ed25519::test_helpers::KeyDispenser as Ed25519KeyDispenser;
    use crypto::test_helper::KeyDispenser as _;

    /// Test to ensure that build is available for in-memory storage
    #[cfg(not(feature = "rocksdb"))]
    #[tokio::test]
    async fn test_from_config_in_mem() {
        let config = Config::with_defaults(
            NonZero::new(1).unwrap(),
            Ed25519KeyDispenser::default().dispense(),
        );

        assert!(Domain::from_config(config).build().await.is_ok())
    }

    /// Test to ensure that `with_rocksdb` is available on a rocksdb-enabled
    /// builder. The assertion is more for style.
    #[cfg(feature = "rocksdb")]
    #[test]
    fn test_with_rocksdb() {
        use std::path::PathBuf;

        let db_options = DbOptions::default().with_db_prefix_path(PathBuf::from("/test"));
        let builder = Domain::builder(
            NonZero::new(1).unwrap(),
            Ed25519KeyDispenser::default().dispense(),
        )
        .with_rocksdb(db_options.clone());

        assert_eq!(builder.storage, db_options);
    }
}