dash_sdk/
lib.rs

1//! # Dash Platform Rust SDK
2//!
3//! This is the official Rust SDK for the Dash Platform. Dash Platform is a Layer 2 cryptocurrency technology that
4//! builds upon the Dash layer 1 network. This SDK provides an abstraction layer to simplify usage of the Dash
5//! Platform along with data models based on the Dash Platform Protocol (DPP), query traits for reading data, and
6//! state transition traits for writing data.
7//!
8//!
9//! ## Dash Platform Protocol Data Model
10//!
11//! SDK data model uses types defined in [Dash Platform Protocol (DPP)](crate::platform::dpp). The core types are:
12//!
13//! 1. [`Identity`](crate::platform::Identity)
14//! 2. [`DataContract`](crate::platform::DataContract)
15//! 3. [`Document`](crate::platform::Document)
16//!
17//! To define document search conditions, you can use [`DriveDocumentQuery`](crate::platform::DriveDocumentQuery) and convert it
18//! to [`DocumentQuery`](crate::platform::DocumentQuery) with the [`From`] trait.
19//!
20//! Basic DPP objects are re-exported in the [`platform`] module.
21//!
22//! ## Querying (Reading Data)
23//!
24//! Data can be read from Platform using the following traits:
25//!
26//! 1. [`Fetch`](crate::platform::Fetch) - fetch a single object from Platform with proof verification
27//! 2. [`FetchMany`](crate::platform::FetchMany) - fetch multiple objects from Platform with proof verification
28//! 3. [`FetchUnproved`](crate::platform::FetchUnproved) - fetch a single object without proof verification
29//!    (e.g., for node status queries)
30//! 4. [`FetchCurrent`](crate::platform::fetch_current_no_parameters::FetchCurrent) - fetch current
31//!    state for parameter-free queries (e.g., current epoch, total credits)
32//!
33//! These traits return objects based on provided queries. Some example queries include:
34//!
35//! 1. [`Identifier`](crate::platform::Identifier) - fetches an object by its identifier
36//! 2. [`DocumentQuery`](crate::platform::DocumentQuery) - fetches documents based on search conditions; see
37//!    [query syntax documentation](https://docs.dash.org/projects/platform/en/stable/docs/reference/query-syntax.html)
38//!    for more details.
39//! 3. [`DriveDocumentQuery`](crate::platform::DriveDocumentQuery) - can be used to build more complex queries
40//!
41//! ## State Transitions (Writing Data)
42//!
43//! Data is written to Platform by broadcasting state transitions. The SDK provides traits for common
44//! write operations:
45//!
46//! - [`PutIdentity`](crate::platform::transition::put_identity::PutIdentity) - register a new identity
47//! - [`PutContract`](crate::platform::transition::put_contract::PutContract) - publish a data contract
48//! - [`PutDocument`](crate::platform::transition::put_document::PutDocument) - create or replace a document
49//! - [`TransferToIdentity`](crate::platform::transition::transfer::TransferToIdentity) - transfer credits between identities
50//! - [`WithdrawFromIdentity`](crate::platform::transition::withdraw_from_identity::WithdrawFromIdentity) - withdraw credits
51//! - [`TopUpIdentity`](crate::platform::transition::top_up_identity::TopUpIdentity) - add credits to an identity
52//! - [`PutVote`](crate::platform::transition::vote::PutVote) - cast a masternode vote
53//!
54//! For document operations, builder-based APIs are also available (see [`platform::documents::transitions`]).
55//!
56//! ## Testability
57//!
58//! SDK operations can be mocked using [Sdk::new_mock()].
59//!
60//! Examples can be found in `tests/fetch/mock_fetch.rs` and `tests/fetch/mock_fetch_many.rs`.
61//!
62//! ## Error handling
63//!
64//! Errors of type [Error] are returned by the SDK. Note that missing objects ("not found") are not
65//! treated as errors; `Ok(None)` is returned instead.
66//!
67//! Mocking functions often panic instead of returning an error.
68//!
69//! ## Logging
70//!
71//! This project uses the `tracing` crate for instrumentation and logging. The `tracing` ecosystem provides a powerful,
72//! flexible framework for adding structured, context-aware logs to your program.
73//!
74//! To enable logging, you can use the `tracing_subscriber` crate which allows applications to customize how events are processed and recorded.
75//! An example can be found in `tests/fetch/common.rs:setup_logs()`.
76//!
77// TODO re-enable when docs are complete
78// #![warn(missing_docs)]
79#![allow(rustdoc::private_intra_doc_links)]
80#![allow(clippy::result_large_err)]
81
82pub mod core;
83pub mod error;
84mod internal_cache;
85pub mod mock;
86pub mod platform;
87pub mod sdk;
88
89pub use error::Error;
90pub use sdk::{RequestSettings, Sdk, SdkBuilder};
91
92pub use dapi_grpc;
93pub use dpp;
94#[cfg(feature = "core_spv")]
95pub use dpp::dash_spv;
96#[cfg(feature = "core_rpc_client")]
97pub use dpp::dashcore_rpc;
98pub use drive;
99pub use drive_proof_verifier::types as query_types;
100pub use drive_proof_verifier::Error as ProofVerifierError;
101#[cfg(feature = "shielded")]
102pub use grovedb_commitment_tree;
103pub use rs_dapi_client as dapi_client;
104pub mod sync;
105
106/// Version of the SDK
107pub const VERSION: &str = env!("CARGO_PKG_VERSION");
dash_sdk/lib.rs

dash_sdk/
lib.rs
