delta_domain_sdk/

client.rs

//! # Client
//!
//! [`DomainClient`] to perform actions on a running domain.

use crate::{
    base_layer::{
        BaseLayer,
        BaseLayerPortError,
    },
    domain_agreement,
};
use base_sdk::{
    core::{
        Planck,
        SdlId,
        Shard,
    },
    sdl::VerificationKey,
};
use domain_runtime::endpoint::Update;
use snafu::{
    ResultExt,
    Snafu,
};
use std::num::NonZero;
use tokio::sync::broadcast;
use verifiable::types::VerifiableWithDiffs;

/// Errors occurring in the [DomainClient]
#[derive(Debug, Snafu)]
pub enum Error {
    /// Error from the runtime task endpoint
    #[snafu(display("{source}"))]
    Endpoint {
        /// The underlying endpoint error
        source: domain_runtime::endpoint::Error,
    },

    /// Base layer client initialization or communication failed
    #[snafu(display("Base layer error: {source}"))]
    BaseLayer {
        /// The underlying error
        source: BaseLayerPortError,
    },

    /// Failed to check for the domain agreement
    #[snafu(display("Domain agreement check failed: {source}"))]
    DomainAgreement {
        /// The underlying error
        source: domain_agreement::Error,
    },
}

/// Client to perform actions on a running domain.
///
/// The client is cloneable and can be shared across tasks. It provides methods
/// to apply verifiable messages, submit state diffs to the base layer, and
/// generate and submit proofs.
///
/// Without [running](crate::runner::Runner::run) the domain first, actions
/// performed by the client cannot be executed.
#[derive(Debug, Clone)]
pub struct DomainClient {
    // data
    shard: NonZero<Shard>,
    local_laws_vkey: Option<VerificationKey>,

    // clients, endpoints
    endpoint: domain_runtime::Endpoint,
    base_layer: BaseLayer,
}

impl DomainClient {
    pub(crate) const fn new(
        shard: NonZero<Shard>,
        local_laws_vkey: Option<VerificationKey>,
        endpoint: domain_runtime::Endpoint,
        base_layer: BaseLayer,
    ) -> Self {
        Self {
            shard,
            local_laws_vkey,
            endpoint,
            base_layer,
        }
    }

    /// Apply state diffs to the vaults
    ///
    /// Changes to the vaults are visible immediately locally. The resulting state
    /// diff is buffered until a call to [Self::submit].
    ///
    /// # Parameters
    ///
    /// * `messages` - The verifiable messages with diffs to be applied
    ///
    /// # Returns
    ///
    /// Ok(()) if application succeeded, or an Error if it failed
    pub async fn apply(&self, messages: Vec<VerifiableWithDiffs>) -> Result<(), Error> {
        tracing::debug!("Applying {} verifiable(s)", messages.len());
        self.endpoint
            .handle_apply(messages)
            .await
            .context(EndpointSnafu)
    }

    /// Submit all diffs that were applied since the last call to the base
    /// layer and return the hash of the resulting SDL.
    ///
    /// # Returns
    ///
    /// * `Ok(Some(sdl_id))` - If diffs were successfully submitted, returns the SDL id
    /// * `Ok(None)` - If there were no pending diffs to submit
    /// * `Err(error)` - If the submission failed
    pub async fn submit(&self) -> Result<Option<SdlId>, Error> {
        let sdl_id = self.endpoint.handle_submit().await.context(EndpointSnafu)?;
        Ok(sdl_id)
    }

    /// Prove the SDL specified by the hash.
    ///
    /// Generates a proof for the SDL with the given hash and only returns once
    /// the proof is finished (or fails).
    ///
    /// Use [Self::prove_with_local_laws_input] if you need to provide
    /// additional inputs for the local laws.
    ///
    /// # Parameters
    ///
    /// * `sdl_id` - The id of the SDL to generate a proof for
    ///
    /// # Returns
    /// Ok(()) if proving succeeded, Error otherwise
    pub async fn prove(&self, sdl_id: SdlId) -> Result<(), Error> {
        self.endpoint
            .handle_prove(sdl_id, None)
            .await
            .context(EndpointSnafu)
    }

    /// Prove the SDL specified by the hash with additional inputs.
    ///
    /// Generates a proof for the SDL with the given hash and only returns once
    /// the proof is finished (or fails).
    ///
    /// # Parameters
    ///
    /// * `sdl_id` - The id of the SDL to generate a proof for
    /// * `local_laws_input` - Additional inputs to the configured local laws
    ///
    /// # Returns
    /// Ok(()) if proving succeeded, Error otherwise
    pub async fn prove_with_local_laws_input(
        &self,
        sdl_id: SdlId,
        local_laws_input: Box<dyn erased_serde::Serialize + Send + Sync>,
    ) -> Result<(), Error> {
        self.endpoint
            .handle_prove(sdl_id, Some(local_laws_input))
            .await
            .context(EndpointSnafu)
    }

    /// Submit the proof of the SDL specified by the hash to the base layer.
    ///
    /// # Parameters
    ///
    /// * `sdl_id` - The id of the SDL whose proof should be submitted
    ///
    /// # Returns
    ///
    /// Ok(()) if the proof was successfully submitted, or an Error if it failed
    pub async fn submit_proof(&self, sdl_id: SdlId) -> Result<(), Error> {
        self.endpoint
            .handle_submit_proof(sdl_id)
            .await
            .context(EndpointSnafu)
    }

    /// Subscribes to a stream of events from the running domain.
    pub fn updates(&self) -> broadcast::Receiver<Update> {
        self.endpoint.stream_updates()
    }

    /// Shorthand to apply verifiables, submit an SDL, generate and submit a
    /// proof
    ///
    /// This method combines the following:
    /// 1. [apply](Self::apply) to apply verifiables to the vaults
    /// 2. [submit](Self::submit) to batch the changes in an SDL and submit it
    ///    to the base layer
    /// 3. [proving](Self::prove) to start proving the SDL
    /// 4. [submit_proof](Self::submit_proof) to submit the proof to the base
    ///    layer
    ///
    /// This method does not allow setting additional inputs for the local laws.
    ///
    /// # Parameters
    ///
    /// * `messages` - The verifiable messages to be applied
    ///
    /// # Returns
    ///
    /// * `Ok(Some(sdl_id))` - Success, an SDL with this id was created & proven
    /// * `Ok(None)` - Success but there were no state changes to submit
    /// * `Err(error)` - Any step in the process failed.
    pub async fn apply_prove_submit(
        &self,
        messages: Vec<VerifiableWithDiffs>,
    ) -> Result<Option<SdlId>, Error> {
        tracing::debug!(
            "Starting apply_prove_submit with {} verifiable(s)",
            messages.len()
        );
        self.apply(messages).await?;

        let Some(new_sdl_id) = self.submit().await? else {
            tracing::debug!("apply_prove_submit: no diffs to submit");
            return Ok(None);
        };

        self.prove(new_sdl_id).await?;

        self.submit_proof(new_sdl_id).await?;
        tracing::debug!("apply_prove_submit completed for SDL {new_sdl_id}");
        Ok(Some(new_sdl_id))
    }

    /// Submit a Domain Agreement for this domain.
    ///
    /// Having an active domain agreement is a prerequisite to submit transactions to the
    /// base layer. You can check whether a domain agreement is already active with
    /// [Self::check_valid_domain_agreement].
    ///
    /// Note that after submitting the domain agreement, it still has to be applied on the
    /// base layer, before the domain is allowed to send transactions.
    ///
    /// # Parameters
    /// - `new_shard_fee` -  amount of native token that will be charged to the
    ///   domain operator keys's base layer vault for creation of the new shard
    ///
    /// # Returns
    /// - `Ok(())` - if the domain agreement was successfully submitted
    /// - `Err(_)` - see [crate::domain_agreement::Error] for error interpretation
    pub async fn submit_domain_agreement(&self, new_shard_fee: Planck) -> Result<(), Error> {
        self.base_layer
            .submit_domain_agreement(self.shard, new_shard_fee, self.local_laws_vkey)
            .await
            .context(BaseLayerSnafu)
    }

    /// Check that there is an active Domain Agreement for this domain.
    ///
    /// This method can typically be used as a safe-guard before calling
    /// [Self::submit] or other methods that require an active domain agreement
    /// for transactions to be accepted.
    ///
    /// # Returns
    /// - `Ok(())` - if there is an active domain agreement for this domain
    /// - `Err(_)` - see [crate::domain_agreement::Error] for interpretation
    pub async fn check_valid_domain_agreement(&self) -> Result<(), domain_agreement::Error> {
        self.base_layer
            .check_valid_domain_agreement(self.shard)
            .await
    }

    /// Ensure that the domain has a valid Domain Agreement.
    ///
    /// If no valid Domain Agreement is
    /// [found](Self::check_valid_domain_agreement), a new one will be
    /// [submitted](Self::submit_domain_agreement) and awaited up to `timeout`.
    ///
    /// # Parameters
    /// - `new_shard_fee` -  amount of native token that will be charged to the
    ///   domain operator keys's base layer vault for creation of the new shard
    /// - `interval` - duration between polling for the the domain agreement
    /// - `timeout` - maximal duration to await the new domain agreement
    pub async fn ensure_domain_agreement(&self, new_shard_fee: Planck) -> Result<(), Error> {
        if self.check_valid_domain_agreement().await.is_ok() {
            tracing::info!("The domain already has a valid domain agreement.");
            return Ok(());
        }

        tracing::info!("Submitting a new domain agreement...");
        self.submit_domain_agreement(new_shard_fee).await?;
        let mut updates = self.updates();

        loop {
            // Since `self.endpoint` holds the `broadcast::Sender` the recv can never error out
            // so we can safely ignore the else branch here.
            if let Ok(Update::NewEpoch(_)) = updates.recv().await {
                tracing::info!("New epoch began, checking for domain agreement");
                return self
                    .check_valid_domain_agreement()
                    .await
                    .context(DomainAgreementSnafu);
            }
        }
    }
}

#[cfg(test)]
mod test {
    use super::*;
    use crate::base_layer::mock;

    impl DomainClient {
        /// Get access to the underlying mock base layer, if configured.
        ///
        /// This is a test-only escape hatch for asserting on base-layer interactions
        /// (e.g. submitted transaction nonces) without going through the public API.
        pub fn mock_rpc(&self) -> mock::BaseLayer {
            let BaseLayer::Mock(inner) = &self.base_layer else {
                panic!("Called `mock_rpc` on a domain with a real RPC")
            };
            inner.clone()
        }
    }
}