delta_domain_sdk/

lib.rs

//! # delta domain SDK
//!
//! This crate provides a comprehensive SDK for building and running domains on
//! delta network. It includes components for managing the domain lifecycle,
//! handling transactions, storing state, and communicating with the base layer
//! (delta network).
//!
//! ## Running a Domain
//!
//! The [`Domain`] struct is the entry point for building and running a domain.
//! It provides three components:
//! - a [`runner`](Domain::runner) to launch the domain's event loop;
//! - a [`client`](Domain::client) to perform actions (apply, submit, prove, ...); and
//! - [`views`](Domain::views) to read state and data.
//!
//! Create a [`Domain`] with the [builder](Domain::builder) or [from a
//! configuration file](Domain::from_config), and destructure it into its
//! subcomponents upon creation:
//!
//! ```rust,no_run
//! use delta_domain_sdk::{Domain, Config};
//!
//! async fn example() -> Result<(), Box<dyn std::error::Error>> {
//!     let config = Config::load()?;
//!     let Domain { runner, client, views } = Domain::from_config(config)
//!         .build()
//!         .await?;
//!     Ok(())
//! }
//! ```
//!
//! The runner must be launched before using the client or views — see
//! [`Runner`](runner::Runner) for details.
//!
//! [API Documentation](crate::domain)
//!
//! ### Connectivity
//!
//! The RPC adapter handles communication with the base layer:
//! - fetching vault data;
//! - submitting transactions; and
//! - streaming events from the base layer.
//!
//! Configure the RPC URL in the [configuration file](Config) via the `rpc_url`
//! field, or programmatically with
//! [`with_rpc`](builder::DomainBuilder::with_rpc).
//!
//! When no RPC URL is configured, a mock RPC is used. The mock RPC provides
//! testing utilities like mock vaults and simulation of base layer events.
//!
//! ### Storage
//!
//! [`storage`] handles the persistence of vault and state diff data. The SDK
//! supports different backends:
//! - in-memory storage for testing and development; and
//! - [RocksDB](https://rocksdb.org/) for production use
//!
//! You can choose which storage backend is used by setting or omitting the
//! `rocksdb` crate feature.
//!
//! [API Documentation](crate::storage)
//!
//! ### Proving
//!
//! The proving client generates zero-knowledge proofs for state transitions.
//! Find the available implementations
//! [here](./proving/trait.Proving.html#implementors).
//!
//! [API Documentation](crate::proving)
//!
//! ## Key Concepts
//!
//! ### Vaults
//!
//! Vaults represent account state. There are two types:
//!
//! - [`BaseVault`](base_sdk::vaults::BaseVault): Used on the base shard and
//!   contains native token balance and account nonce.
//!
//! - [`Vault`](base_sdk::vaults::Vault): Used on domains and contains native
//!   token balance, shard ID, and optional data such as token holdings, token
//!   mint metadata, and NFT mint metadata.
//!
//! Vaults are uniquely identified by an
//! ([`Address`](base_sdk::vaults::Address)).
//!
//! ### State Diff List (SDL)
//!
//! A [`StateDiffList`](base_sdk::sdl::StateDiffList) is a collection of state
//! changes (diffs) resulting from transaction execution. SDLs:
//! - represent atomic batches of state changes;
//! - include information about the originating shard and proposer; and
//! - require cryptographic proofs for validation.
//!
//! ### Verifiables
//!
//! [`VerifiableType`](crate::base::verifiable::VerifiableType) are
//! cryptographically signed messages that can be verified and executed to
//! produce state changes. such as:
//! - [`DebitAllowance`](crate::base::verifiable::debit_allowance::DebitAllowance):
//!   permission to debit tokens from a source vault; or
//! - [`fungible::Mint`](crate::base::verifiable::fungible::Mint): instruction
//!   to mint new fungible tokens.
//!
//! ## Features
//!
//! - `rocksdb`: enables persistent [RocksDB](https://rocksdb.org/) storage
//!   (*use for production*), if disabled an in-memory storage is used by
//!   default
//! - `sp1`: enables [SP1]-based zero-knowledge proof generation
//! - `metrics`: enables performance metrics collection
//!
//! [SP1]: https://docs.succinct.xyz/docs/sp1/introduction
//!
//! ## Example Usage
//!
//! ```rust,no_run
//! use delta_domain_sdk::{Domain, Config};
//!
//! async fn run_domain() -> Result<(), Box<dyn std::error::Error>> {
//!     let config = Config::load()?;
//!     let Domain { runner, client, views } = Domain::from_config(config)
//!         .with_rpc("http://localhost:8545")
//!         .build().await.unwrap();
//!
//!     runner.run_in_background().await.unwrap();
//!     Ok(())
//! }
//! ```
//!
//! ## Development
//!
//! Unlike a smart contract, a domain is a server application in the traditional
//! sense. Developers should apply well-know application development practices
//! like [the twelve-factor app](https://12factor.net/). Some tips:
//!
//! - Listen to any IPv4 or IPv6 address instead of `localhost`.

pub mod builder;

pub mod config;
pub use config::Config;

pub mod client;
pub use client::DomainClient;
pub mod domain;
pub use domain::Domain;
pub mod runner;
pub mod views;

pub mod storage;
pub use storage::in_memory;
#[cfg(feature = "rocksdb")]
pub use storage::rocksdb;

// Re-exported core components from domain_runtime
pub use domain_runtime::{
    execution,
    sdls::types::{
        SdlState,
        SdlUpdate,
    },
};

/// Logic to generate proofs
pub mod proving {
    pub use local_laws;
    pub use proving_clients::*;
}

/// General purpose delta types and helpers re-exported from the base SDK
pub mod base {
    pub use base_sdk::*;

    /// Types to verify global laws and generate state diffs
    pub mod verifiable {
        pub use verifiable::types::*;
    }
}

pub(crate) mod base_layer;

/// Utils to deal with Domain Agreements
pub mod domain_agreement;

#[cfg(feature = "admin-api")]
mod admin_api;

#[cfg(test)]
mod tests;