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::DefaultStorage,
    Domain,
};
use base_sdk::{
    core::Shard,
    crypto::ed25519,
    vaults::{
        Address,
        Vault,
    },
};
use domain_runtime::storage::ColumnFamilies;
use http::{
    uri::InvalidUri,
    Uri,
};
use local_laws::LocalLaws;
use proving_clients::Proving;
use snafu::{
    ResultExt,
    Snafu,
};
#[cfg(feature = "admin-api")]
use std::net::{
    Ipv6Addr,
    SocketAddr,
};
use std::{
    collections::HashMap,
    num::NonZero,
};
use storage::{
    column_family::ColumnFamilies as _,
    database::StorageError,
    key_value::KeyValueStorageWithColumnFamilies,
};

/// 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 port under which the admin API is exposed if the feature is active.
#[cfg(feature = "admin-api")]
pub const ADMIN_API_DEFAULT_PORT: u16 = 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, P> {
    shard: NonZero<Shard>,
    keypair: ed25519::PrivKey,
    base_layer: BaseLayerOptions,
    proving: P,
    storage: S,

    #[cfg(feature = "admin-api")]
    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<proving::mock::Client, 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.
    ///
    /// ## Returns
    /// A [DomainBuilder] to continue configuration or build the domain.
    pub fn from_config(config: Config) -> DomainBuilder<DbBuilderType, proving::mock::Client> {
        let builder = Self::builder(config.shard, config.keypair);
        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 {
            tracing::warn!("Domain configured to use rocksdb, but the feature is disabled");
        }

        #[cfg(feature = "rocksdb")]
        let builder = if let Some(StorageConfig::RocksDb { path }) = config.storage {
            builder.with_rocksdb(DbOptions::default().with_db_prefix_path(path))
        } else {
            builder
        };

        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, proving::mock::Client> {
        #[cfg(not(feature = "rocksdb"))]
        let storage = in_memory::Storage::new();
        #[cfg(feature = "rocksdb")]
        let storage = DbOptions::default();

        DomainBuilder {
            shard,
            keypair,
            storage,
            base_layer: BaseLayerOptions::mock(),
            proving: proving::mock::Client::global_laws(),
            #[cfg(feature = "admin-api")]
            admin_api_address: (Ipv6Addr::UNSPECIFIED, ADMIN_API_DEFAULT_PORT).into(),
        }
    }

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

impl<S, P> DomainBuilder<S, P> {
    /// 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(
    ///     proving::sp1::Client::global_laws_cpu()
    ///         .with_local_laws_cpu(local_laws_elf)
    /// );
    /// ```
    pub fn with_proving_client<P2>(self, proving: P2) -> DomainBuilder<S, P2>
    where
        P2: Proving,
    {
        DomainBuilder {
            shard: self.shard,
            keypair: self.keypair,
            base_layer: self.base_layer,
            proving,
            storage: self.storage,
            #[cfg(feature = "admin-api")]
            admin_api_address: self.admin_api_address,
        }
    }

    /// Use a custom [KeyValueStorageWithColumnFamilies] implementation
    ///
    /// ## Note
    /// The SDK assumes that iteration order for
    /// [ColumnFamilies::PendingVerifiables] (i.e. [the column
    /// family](domain_runtime::storage::PendingVerifiablesColumnFamily))
    /// is in lexicographical order of the keys/indices.
    pub fn with_storage<S2>(self, storage: S2) -> DomainBuilder<S2, P>
    where
        S2: KeyValueStorageWithColumnFamilies<
                ColumnFamilyIdentifier = ColumnFamilies,
                Error = StorageError,
            > + Send
            + Sync
            + 'static,
    {
        DomainBuilder {
            shard: self.shard,
            keypair: self.keypair,
            base_layer: self.base_layer,
            proving: self.proving,
            storage,
            #[cfg(feature = "admin-api")]
            admin_api_address: self.admin_api_address,
        }
    }

    /// 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 IP address `[::]`.
    ///
    /// Note if the`admin-api` feature is active, the API is by default exposed
    /// under [ADMIN_API_DEFAULT_PORT].
    #[cfg(feature = "admin-api")]
    pub fn with_admin_api(self, port: u16) -> Self {
        self.with_admin_api_ip((Ipv6Addr::UNSPECIFIED, port).into())
    }

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

impl<S> DomainBuilder<S, proving::mock::Client> {
    /// This method sets a local laws implementation to allow testing of local laws logic.
    /// The local laws will be incorporated into the mock proving process.
    pub fn with_mock_local_laws<L: LocalLaws>(mut self) -> Self {
        self.proving = self.proving.with_local_laws::<L>();
        self
    }
}

#[cfg(not(feature = "rocksdb"))]
type DbBuilderType = 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, P> DomainBuilder<S, P> {
        /// Use RocksDb with the given configuration as storage
        pub fn with_rocksdb(self, db_options: DbOptions) -> DomainBuilder<DbOptions, P> {
            DomainBuilder {
                shard: self.shard,
                keypair: self.keypair,
                base_layer: self.base_layer,
                proving: self.proving,
                storage: db_options,
                #[cfg(feature = "admin-api")]
                admin_api_address: self.admin_api_address,
            }
        }
    }

    impl<P> DomainBuilder<DbOptions, P>
    where
        P: Proving,
    {
        /// Build the domain to get its handles.
        pub async fn build(self) -> Result<Domain<P, 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<P, S> DomainBuilder<S, P>
where
    P: Proving,
    S: KeyValueStorageWithColumnFamilies<
            ColumnFamilyIdentifier = ColumnFamilies,
            Error = StorageError,
        > + Send
        + Sync
        + 'static,
{
    /// Build the domain to get its handles.
    pub async fn build(self) -> Result<Domain<P, S>, Error> {
        let Self {
            shard,
            keypair,
            proving,
            storage,
            base_layer,
            #[cfg(feature = "admin-api")]
            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(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 { .. } => {
                            tracing::warn!("{err}");
                            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(#1676): rethink this approach with regards to new domain state view
                let seed_vaults = if has_vaults(&storage) {
                    tracing::info!(
                        "Seed vaults already present in storage. Not fetching from RPC."
                    );
                    HashMap::new()
                } else {
                    rpc_client
                        .get_all_vaults_of(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() == 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(
            shard,
            proving,
            storage,
            base_layer,
            seed_vaults,
            #[cfg(feature = "admin-api")]
            admin_api_address,
        ))
    }
}

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

#[cfg(test)]
mod tests {
    /// 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 crate::{
            storage::options::DbOptions,
            Domain,
        };
        use base_sdk::crypto::ed25519::test_helpers::KeyDispenser as Ed25519KeyDispenser;
        use crypto::test_helper::KeyDispenser as _;
        use std::{
            num::NonZero,
            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);
    }
}