From 9e603838141b8ed97f6a4d1a9fe02fa563d5bb5f Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Feb 2026 00:03:40 +0000 Subject: [PATCH 01/11] docs(rs-sdk): fix rustdoc inaccuracies and resolve all cargo doc warnings - Fix crate-level docs: correct type name references (DriveQuery -> DriveDocumentQuery), fix grammar ("can be executing" -> "can be executed"), update test file paths, remove outdated reference to C bindings, fix crate name (dash-platform-sdk -> SDK) - Fix 32 cargo doc warnings: - Resolve broken intra-doc links for ProTxHash, VotePollsByDocumentTypeQuery, ContestedDocumentVotePollDriveQuery, ContestedDocumentVotePollVotesDriveQuery, ContestedResourceVotesGivenByIdentityQuery, VotePollsByEndDateDriveQuery, KeysInPath, ProposerBlockCounts, TransportRequest, sync_address_balances, AddressProvider::last_sync_height - Remove references to non-existent MockRequest trait and SdkBuilder::with_wallet() - Replace BroadcastRequestForNewIdentity references with BroadcastRequestForStateTransition - Fix unclosed HTML tags in Vec doc comments - Fix redundant explicit link targets for Identifier in query.rs - Escape regex pattern in dpns_usernames to prevent markdown parsing - Update mock.rs test file path references https://claude.ai/code/session_01HdTH5NBEVTmxbW63RCkS9J --- packages/rs-sdk/src/lib.rs | 21 ++++++----- packages/rs-sdk/src/mock.rs | 2 +- .../rs-sdk/src/platform/address_sync/types.rs | 8 ++--- packages/rs-sdk/src/platform/delegate.rs | 10 +++--- .../rs-sdk/src/platform/dpns_usernames/mod.rs | 2 +- packages/rs-sdk/src/platform/fetch.rs | 2 +- packages/rs-sdk/src/platform/fetch_many.rs | 36 +++++++++---------- packages/rs-sdk/src/platform/query.rs | 6 ++-- .../platform/transition/broadcast_request.rs | 12 +++---- .../src/platform/types/proposed_blocks.rs | 2 +- packages/rs-sdk/src/sdk.rs | 2 +- 11 files changed, 51 insertions(+), 52 deletions(-) diff --git a/packages/rs-sdk/src/lib.rs b/packages/rs-sdk/src/lib.rs index 582d44c291d..b522a14a2e7 100644 --- a/packages/rs-sdk/src/lib.rs +++ b/packages/rs-sdk/src/lib.rs @@ -2,8 +2,7 @@ //! //! This is the official Rust SDK for the Dash Platform. Dash Platform is a Layer 2 cryptocurrency technology that //! builds upon the Dash layer 1 network. This SDK provides an abstraction layer to simplify usage of the Dash -//! Platform along with data models based on the Dash Platform Protocol (DPP), a CRUD interface, and bindings -//! for other technologies such as C. +//! Platform along with data models based on the Dash Platform Protocol (DPP) and a CRUD interface. //! //! //! ## Dash Platform Protocol Data Model @@ -12,21 +11,21 @@ //! types are supported: //! //! 1. [`Identity`](crate::platform::Identity) -//! 2. [`Data Contract`](crate::platform::DataContract) +//! 2. [`DataContract`](crate::platform::DataContract) //! 3. [`Document`](crate::platform::Document) //! -//! To define document search conditions, you can use [`DriveQuery`](crate::platform::DriveDocumentQuery) and convert it +//! To define document search conditions, you can use [`DriveDocumentQuery`](crate::platform::DriveDocumentQuery) and convert it //! to [`DocumentQuery`](crate::platform::DocumentQuery) with the [`From`] trait. //! //! Basic DPP objects are re-exported in the [`platform`] module. //! //! ## CRUD Interface //! -//! Operations on data model objects can be executing using traits following CRUD (Create, Read, Update, and Delete) +//! Operations on data model objects can be executed using traits following CRUD (Create, Read, Update, and Delete) //! approach. The following traits are already implemented: //! -//! 1. [`Fetch`](crate::platform::Fetch) -//! 2. [`FetchMany`](crate::platform::FetchMany) +//! 1. [`Fetch`](crate::platform::Fetch) - fetch a single object from Platform +//! 2. [`FetchMany`](crate::platform::FetchMany) - fetch multiple objects from Platform //! //! Fetch and FetchMany traits return objects based on provided queries. Some example queries include: //! @@ -34,17 +33,17 @@ //! 2. [`DocumentQuery`](crate::platform::DocumentQuery) - fetches documents based on search conditions; see //! [query syntax documentation](https://docs.dash.org/projects/platform/en/stable/docs/reference/query-syntax.html) //! for more details. -//! 3. [`DriveQuery`](crate::platform::DriveDocumentQuery) - can be used to build more complex queries +//! 3. [`DriveDocumentQuery`](crate::platform::DriveDocumentQuery) - can be used to build more complex queries //! //! ## Testability //! //! SDK operations can be mocked using [Sdk::new_mock()]. //! -//! Examples can be found in `tests/mock_*.rs`. +//! Examples can be found in `tests/fetch/mock_fetch.rs` and `tests/fetch/mock_fetch_many.rs`. //! //! ## Error handling //! -//! Errors of type [Error] are returned by the dash-platform-sdk. Note that missing objects ("not found") are not +//! Errors of type [Error] are returned by the SDK. Note that missing objects ("not found") are not //! treated as errors; `Ok(None)` is returned instead. //! //! Mocking functions often panic instead of returning an error. @@ -55,7 +54,7 @@ //! flexible framework for adding structured, context-aware logs to your program. //! //! To enable logging, you can use the `tracing_subscriber` crate which allows applications to customize how events are processed and recorded. -//! An example can be found in `tests/common.rs:setup_logs()`. +//! An example can be found in `tests/fetch/common.rs:setup_logs()`. //! // TODO re-enable when docs are complete // #![warn(missing_docs)] diff --git a/packages/rs-sdk/src/mock.rs b/packages/rs-sdk/src/mock.rs index 6ccd2be80f4..99fd660a5a2 100644 --- a/packages/rs-sdk/src/mock.rs +++ b/packages/rs-sdk/src/mock.rs @@ -17,7 +17,7 @@ //! sdk.mock().expect_fetch(query, None as Option); //! ``` //! -//! See tests/mock_*.rs for more detailed examples. +//! See `tests/fetch/mock_fetch.rs` and `tests/fetch/mock_fetch_many.rs` for more detailed examples. #[cfg(not(feature = "mocks"))] mod noop; diff --git a/packages/rs-sdk/src/platform/address_sync/types.rs b/packages/rs-sdk/src/platform/address_sync/types.rs index dce04a46d90..ae4a8ec3d08 100644 --- a/packages/rs-sdk/src/platform/address_sync/types.rs +++ b/packages/rs-sdk/src/platform/address_sync/types.rs @@ -55,7 +55,7 @@ pub struct AddressSyncConfig { /// Maximum age in seconds before a full tree rescan is forced. /// - /// When `last_sync_timestamp` is passed to [`sync_address_balances`], the + /// When `last_sync_timestamp` is passed to [`sync_address_balances`](super::sync_address_balances), the /// function compares `now - last_sync_timestamp` against this threshold. /// If the elapsed time exceeds this value, a full tree rescan is performed /// instead of incremental-only catch-up. @@ -113,15 +113,15 @@ pub struct AddressSyncResult { /// /// After each sync the caller should persist two values: /// 1. This `new_sync_height` — return it from - /// [`AddressProvider::last_sync_height`] on the next call. + /// [`AddressProvider::last_sync_height`](super::provider::AddressProvider::last_sync_height) on the next call. /// 2. [`new_sync_timestamp`](Self::new_sync_timestamp) — pass it as the - /// `last_sync_timestamp` parameter of [`sync_address_balances`]. + /// `last_sync_timestamp` parameter of [`sync_address_balances`](super::sync_address_balances). pub new_sync_height: u64, /// Platform block time (Unix seconds) at the point of the latest response. /// /// Store this value and pass it back as `last_sync_timestamp` on the next - /// call to [`sync_address_balances`]. The function compares it against the + /// call to [`sync_address_balances`](super::sync_address_balances). The function compares it against the /// current wall-clock time to decide whether a full tree rescan is needed. pub new_sync_timestamp: u64, } diff --git a/packages/rs-sdk/src/platform/delegate.rs b/packages/rs-sdk/src/platform/delegate.rs index 501cc8707d4..f82127c205c 100644 --- a/packages/rs-sdk/src/platform/delegate.rs +++ b/packages/rs-sdk/src/platform/delegate.rs @@ -11,14 +11,14 @@ /// Delegate the execution of a transport request to the appropriate variant of an enum wrapper. /// /// Given two enums, request and response, that wrap multiple requests/responses for one object type, this macro -/// implements [TransportRequest](crate::platform::dapi::transport::TransportRequest) for the request enum and +/// implements [TransportRequest](rs_dapi_client::transport::TransportRequest) for the request enum and /// delegates the execution of the transport request to the appropriate variant. /// /// Each variant in request enum must have a corresponding variant in response enum. /// Variant names in request and response enums must match. /// Variants must take exactly one argument that implements -/// [TransportRequest](crate::platform::dapi::transport::TransportRequest) (for request) and -/// [TransportResponse](crate::platform::dapi::transport::TransportResponse) (for response), where for a given variant, +/// [TransportRequest](rs_dapi_client::transport::TransportRequest) (for request) and +/// `TransportResponse` (for response), where for a given variant, /// response must be the response type of the request variant. /// /// Macro [delegate_enum!](crate::delegate_enum!) can be used to generate these enums and implement required @@ -127,7 +127,7 @@ macro_rules! delegate_from_proof_variant { /// /// In order to support multiple request/response types for one object (like, GetIdentityRequest and /// GetIdentityByPublicKeyHashRequest for Identity), we need to wrap them in an enum and -/// delegate [TransportRequest](crate::platform::dapi::transport::TransportRequest) +/// delegate [TransportRequest](rs_dapi_client::transport::TransportRequest) /// and [FromProof](drive_proof_verifier::FromProof) to the appropriate variant. /// /// This macro creates enums for requests (`$request`) and responses (`$response`) and variants (`$variant`) for @@ -135,7 +135,7 @@ macro_rules! delegate_from_proof_variant { /// /// It also calls [delegate_transport_request_variant!](crate::delegate_transport_request_variant!) and /// [delegate_from_proof_variant!](crate::delegate_from_proof_variant!) to delegate -/// [TransportRequest](crate::platform::dapi::transport::TransportRequest) +/// [TransportRequest](rs_dapi_client::transport::TransportRequest) /// and [FromProof](drive_proof_verifier::FromProof) /// traits to the appropriate variant. macro_rules! delegate_enum { diff --git a/packages/rs-sdk/src/platform/dpns_usernames/mod.rs b/packages/rs-sdk/src/platform/dpns_usernames/mod.rs index a801fdc041c..58c1b4a9792 100644 --- a/packages/rs-sdk/src/platform/dpns_usernames/mod.rs +++ b/packages/rs-sdk/src/platform/dpns_usernames/mod.rs @@ -43,7 +43,7 @@ pub fn convert_to_homograph_safe_chars(input: &str) -> String { /// - It contains only alphanumeric characters and hyphens /// - It doesn't have consecutive hyphens (enforced by the pattern) /// -/// Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]$ +/// Pattern: `^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]$` /// /// # Arguments /// diff --git a/packages/rs-sdk/src/platform/fetch.rs b/packages/rs-sdk/src/platform/fetch.rs index a80eaacb97b..5e904b597ab 100644 --- a/packages/rs-sdk/src/platform/fetch.rs +++ b/packages/rs-sdk/src/platform/fetch.rs @@ -69,7 +69,7 @@ where /// /// Most likely, one of the types defined in [`dapi_grpc::platform::v0`]. /// - /// This type must implement [`TransportRequest`] and [`MockRequest`]. + /// This type must implement [`TransportRequest`]. type Request: TransportRequest + Into<::Request>>::Request>; /// Fetch single object from Platform. diff --git a/packages/rs-sdk/src/platform/fetch_many.rs b/packages/rs-sdk/src/platform/fetch_many.rs index bf20f76abc3..b960a138614 100644 --- a/packages/rs-sdk/src/platform/fetch_many.rs +++ b/packages/rs-sdk/src/platform/fetch_many.rs @@ -53,7 +53,7 @@ use std::fmt::Debug; /// and use [FetchMany::fetch_many()] for your object type. /// /// You can also use convenience methods: -/// * [FetchMany::fetch_many_by_identifiers()] - to fetch multiple objects by their identifiers, +/// * [FetchMany::fetch_by_identifiers()] - to fetch multiple objects by their identifiers, /// * [FetchMany::fetch_many_with_limit()] - to fetch not more than `limit` objects. /// /// ## Generic Parameters @@ -100,7 +100,7 @@ where /// /// Most likely, one of the types defined in [`dapi_grpc::platform::v0`]. /// - /// This type must implement [`TransportRequest`] and [`MockRequest`](crate::mock::MockRequest). + /// This type must implement [`TransportRequest`]. type Request: TransportRequest + Into<>::Request>>::Request>; @@ -426,14 +426,14 @@ impl FetchMany for ProtocolVersionVote /// Fetch information about protocol version upgrade voted by each node. /// /// Returns list of [MasternodeProtocolVotes](drive_proof_verifier::types::MasternodeProtocolVote) -/// indexed by [ProTxHash](dashcore_rpc::dashcore::ProTxHash). Each item in this list represents +/// indexed by [ProTxHash](dpp::dashcore_rpc::dashcore::ProTxHash). Each item in this list represents /// node protxhash and its preferred protocol version. /// /// ## Supported query types /// -/// * [ProTxHash](dashcore_rpc::dashcore::ProTxHash) - proTxHash of first object to find; will return up to +/// * [ProTxHash](dpp::dashcore_rpc::dashcore::ProTxHash) - proTxHash of first object to find; will return up to /// [DEFAULT_NODES_VOTING_LIMIT](super::query::DEFAULT_NODES_VOTING_LIMIT) objects -/// * [`Option`](dashcore_rpc::dashcore::ProTxHash) - proTxHash that can be and [Option]; if it is `None`, +/// * `Option` - proTxHash that can be and [Option]; if it is `None`, /// the query will return all objects /// * [`LimitQuery`](super::LimitQuery) - limit query that allows to specify maximum number of objects /// to fetch; see also [FetchMany::fetch_many_with_limit()]. @@ -444,14 +444,14 @@ impl FetchMany for MasternodeProtocolVote { /// Fetch information about the proposed block count by proposers for a given epoch. /// /// Returns list of [ProposerBlockCounts](drive_proof_verifier::types::ProposerBlockCounts) -/// indexed by [ProTxHash](dashcore_rpc::dashcore::ProTxHash). Each item in this list represents +/// indexed by [ProTxHash](dpp::dashcore_rpc::dashcore::ProTxHash). Each item in this list represents /// node protxhash and the amount of blocks that were proposed. /// /// ## Supported query types /// -/// * [ProTxHash](dashcore_rpc::dashcore::ProTxHash) - proTxHash of first object to find; will return up to +/// * [ProTxHash](dpp::dashcore_rpc::dashcore::ProTxHash) - proTxHash of first object to find; will return up to /// [DEFAULT_NODES_VOTING_LIMIT](super::query::DEFAULT_NODES_VOTING_LIMIT) objects -/// * [`Option`](dashcore_rpc::dashcore::ProTxHash) - proTxHash that can be and [Option]; if it is `None`, +/// * `Option` - proTxHash that can be and [Option]; if it is `None`, /// the query will return all objects /// * [`LimitQuery`](super::LimitQuery) - limit query that allows to specify maximum number of objects /// to fetch; see also [FetchMany::fetch_many_with_limit()]. @@ -462,12 +462,12 @@ impl FetchMany for ProposerBlockCountByRange { /// Fetch information about the proposed block count by proposers for a given epoch. /// /// Returns list of [ProposerBlockCounts](drive_proof_verifier::types::ProposerBlockCounts) -/// indexed by [ProTxHash](dashcore_rpc::dashcore::ProTxHash). Each item in this list represents +/// indexed by [ProTxHash](dpp::dashcore_rpc::dashcore::ProTxHash). Each item in this list represents /// node pro_tx_hash and the amount of blocks that were proposed. /// /// ## Supported query types /// -/// * [ProTxHash](dashcore_rpc::dashcore::ProTxHash) - proTxHash of an evonode to find; will return one evonode block count +/// * [ProTxHash](dpp::dashcore_rpc::dashcore::ProTxHash) - proTxHash of an evonode to find; will return one evonode block count impl FetchMany for ProposerBlockCountById { type Request = GetEvonodesProposedEpochBlocksByIdsRequest; } @@ -478,7 +478,7 @@ impl FetchMany for ProposerBlockCountById { /// /// ## Supported query types /// -/// * [Vec](dpp::prelude::Identifier) - list of identifiers of data contracts to fetch +/// * `Vec` - list of identifiers of data contracts to fetch /// impl FetchMany for DataContract { type Request = GetDataContractsRequest; @@ -488,7 +488,7 @@ impl FetchMany for DataContract { /// /// ## Supported query types /// -/// * [VotePollsByDocumentTypeQuery] +/// * [`VotePollsByDocumentTypeQuery`](drive::query::vote_polls_by_document_type_query::VotePollsByDocumentTypeQuery) impl FetchMany for ContestedResource { type Request = GetContestedResourcesRequest; } @@ -499,7 +499,7 @@ impl FetchMany for ContestedResource { /// /// ## Supported query types /// -/// * [ContestedDocumentVotePollDriveQuery] +/// * [`ContestedDocumentVotePollDriveQuery`](drive::query::vote_poll_vote_state_query::ContestedDocumentVotePollDriveQuery) #[async_trait::async_trait] impl FetchMany for ContenderWithSerializedDocument { type Request = GetContestedResourceVoteStateRequest; @@ -508,7 +508,7 @@ impl FetchMany for ContenderWithSerializedDocument { ///  Fetch voters /// ## Supported query types /// -/// * [ContestedDocumentVotePollVotesDriveQuery] +/// * [`ContestedDocumentVotePollVotesDriveQuery`](drive::query::vote_poll_contestant_votes_query::ContestedDocumentVotePollVotesDriveQuery) impl FetchMany for Voter { type Request = GetContestedResourceVotersForIdentityRequest; } @@ -518,7 +518,7 @@ impl FetchMany for Voter { /// /// ## Supported query types /// -/// * [ContestedResourceVotesGivenByIdentityQuery] +/// * [`ContestedResourceVotesGivenByIdentityQuery`](drive::query::contested_resource_votes_given_by_identity_query::ContestedResourceVotesGivenByIdentityQuery) impl FetchMany for ResourceVote { type Request = GetContestedResourceIdentityVotesRequest; } @@ -528,7 +528,7 @@ impl FetchMany for ResourceVote { /// /// ## Supported query types /// -/// * [VotePollsByEndDateDriveQuery] +/// * [`VotePollsByEndDateDriveQuery`](drive::query::VotePollsByEndDateDriveQuery) impl FetchMany for VotePoll { type Request = GetVotePollsByEndDateRequest; } @@ -538,7 +538,7 @@ impl FetchMany for VotePoll { /// /// ## Supported query types /// -/// * [Vec](dpp::prelude::Identifier) - list of identifiers of identities whose balance we want to fetch +/// * `Vec` - list of identifiers of identities whose balance we want to fetch impl FetchMany for drive_proof_verifier::types::IdentityBalance { type Request = GetIdentitiesBalancesRequest; } @@ -552,7 +552,7 @@ impl FetchMany for drive_proof_verifier::types::A /// /// ## Supported query types /// -/// * [KeysInPath] +/// * [`KeysInPath`](drive_proof_verifier::types::KeysInPath) impl FetchMany for Element { type Request = GetPathElementsRequest; } diff --git a/packages/rs-sdk/src/platform/query.rs b/packages/rs-sdk/src/platform/query.rs index eb9bdaa4427..a7827789b04 100644 --- a/packages/rs-sdk/src/platform/query.rs +++ b/packages/rs-sdk/src/platform/query.rs @@ -60,7 +60,7 @@ pub const DEFAULT_NODES_VOTING_LIMIT: u32 = 100; /// /// Some examples of queries include: /// -/// 1. [`Identifier`](crate::platform::Identifier) - fetches an object by its identifier; implemented for +/// 1. [`Identifier`] - fetches an object by its identifier; implemented for /// [Identity](dpp::prelude::Identity), [DataContract](dpp::prelude::DataContract) and [Document](dpp::document::Document). /// 2. [`DocumentQuery`] - fetches [Document](dpp::document::Document) based on search conditions; see /// [query syntax documentation](https://docs.dash.org/projects/platform/en/stable/docs/reference/query-syntax.html) @@ -68,7 +68,7 @@ pub const DEFAULT_NODES_VOTING_LIMIT: u32 = 100; /// /// ## Example /// -/// To fetch individual [Identity](dpp::prelude::Identity) object by its [Identifier](crate::platform::Identifier), +/// To fetch individual [Identity](dpp::prelude::Identity) object by its [`Identifier`], /// you just need to create it and use [Fetch](crate::platform::Fetch) /// or [FetchMany](crate::platform::FetchMany) trait: /// @@ -81,7 +81,7 @@ pub const DEFAULT_NODES_VOTING_LIMIT: u32 = 100; /// let identity = Identity::fetch(&sdk, query); /// ``` /// -/// As [Identifier](crate::platform::Identifier) implements [Query], the `query` variable in the code +/// As [`Identifier`] implements [Query], the `query` variable in the code /// above can be used as a parameter for [Fetch::fetch()](crate::platform::Fetch::fetch()) /// and [FetchMany::fetch_many()](crate::platform::FetchMany::fetch_many()) methods. pub trait Query: Send + Debug + Clone { diff --git a/packages/rs-sdk/src/platform/transition/broadcast_request.rs b/packages/rs-sdk/src/platform/transition/broadcast_request.rs index 4218b4dbd5f..1779d5270e4 100644 --- a/packages/rs-sdk/src/platform/transition/broadcast_request.rs +++ b/packages/rs-sdk/src/platform/transition/broadcast_request.rs @@ -1,10 +1,10 @@ -//! Broadcast trait representing the action of broadcasting a new identity state transition to Platform. +//! Broadcast trait representing the action of broadcasting a state transition to Platform. //! -//! The [BroadcastRequestForNewIdentity] trait is designed for the creation and broadcasting of new identity state transitions. +//! The [`BroadcastRequestForStateTransition`] trait is designed for the creation and broadcasting of state transitions. //! This involves the generation of a state transition object, signing it, and then broadcasting it to Platform. //! //! This trait is expected to be implemented by objects that encapsulate the necessary data and logic to perform -//! these operations, including the handling of asset lock proof and signing operations. +//! these operations, including the handling of signing operations. use std::fmt::Debug; use dapi_grpc::platform::v0::wait_for_state_transition_result_request::{ @@ -22,7 +22,7 @@ use crate::error::Error; /// Trait implemented by objects that can be used to broadcast new identity state transitions. /// -/// [BroadcastRequestForNewIdentity] trait is used when a new identity needs to be created and broadcasted on Platform. +/// [`BroadcastRequestForStateTransition`] trait is used when a state transition needs to be broadcasted on Platform. /// It encapsulates the data, the signing process, and the logic required to perform the broadcast operation. /// /// Implementors of this trait will typically be responsible for creating an identity state transition, @@ -60,8 +60,8 @@ use crate::error::Error; /// } /// ``` /// -/// As [BroadcastRequestForStateTransition] is a trait, it can be implemented for any type that represents -/// a new identity creation operation, allowing for flexibility in how new identities are broadcasted. +/// As [`BroadcastRequestForStateTransition`] is a trait, it can be implemented for any type that represents +/// a state transition, allowing for flexibility in how state transitions are broadcasted. pub trait BroadcastRequestForStateTransition: Send + Debug + Clone { /// Converts the current instance into an instance of the `TransportRequest` type, ready for broadcasting. /// diff --git a/packages/rs-sdk/src/platform/types/proposed_blocks.rs b/packages/rs-sdk/src/platform/types/proposed_blocks.rs index ae5a3656a1c..2509e74ab9f 100644 --- a/packages/rs-sdk/src/platform/types/proposed_blocks.rs +++ b/packages/rs-sdk/src/platform/types/proposed_blocks.rs @@ -42,7 +42,7 @@ pub trait ProposedBlockCountEx { /// /// ## See also /// - /// - [`ProposerBlockCounts`](crate::ProposerBlockCounts): The data structure holding the result of this operation. + /// - [`ProposerBlockCounts`](drive_proof_verifier::types::ProposerBlockCounts): The data structure holding the result of this operation. async fn fetch_proposed_blocks_by_range( sdk: &Sdk, epoch: Option, diff --git a/packages/rs-sdk/src/sdk.rs b/packages/rs-sdk/src/sdk.rs index bdfd001c2eb..b9332323e00 100644 --- a/packages/rs-sdk/src/sdk.rs +++ b/packages/rs-sdk/src/sdk.rs @@ -972,7 +972,7 @@ impl SdkBuilder { /// /// This is a convenience method that configures the SDK to use Dash Core as a wallet and context provider. /// - /// For more control over the configuration, use [SdkBuilder::with_wallet()] and [SdkBuilder::with_context_provider()]. + /// For more control over the configuration, use [`SdkBuilder::with_context_provider()`]. /// /// This is temporary implementation, intended for development purposes. pub fn with_core(mut self, ip: &str, port: u16, user: &str, password: &str) -> Self { From 9288afe6c1b2fdb957ea236e4c940e9b8a4859f3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Feb 2026 00:23:18 +0000 Subject: [PATCH 02/11] chore: use rust stable toolchain to workaround index error Switch from pinned Rust 1.92 to stable (currently 1.93.1) to work around an index error. https://claude.ai/code/session_01HdTH5NBEVTmxbW63RCkS9J --- rust-toolchain.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rust-toolchain.toml b/rust-toolchain.toml index 366a9cfa3ae..0b9461857bd 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,5 +1,5 @@ [toolchain] # Rust version the same as in /README.md -channel = "1.92" +channel = "stable" targets = ["wasm32-unknown-unknown"] From e2b003fa5590cf14373883efdeae400d06102c98 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Feb 2026 00:24:47 +0000 Subject: [PATCH 03/11] revert: restore rust-toolchain.toml to 1.92 Revert toolchain change. Will use `cargo +stable doc` instead to workaround the index error only for doc generation. https://claude.ai/code/session_01HdTH5NBEVTmxbW63RCkS9J --- rust-toolchain.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rust-toolchain.toml b/rust-toolchain.toml index 0b9461857bd..366a9cfa3ae 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,5 +1,5 @@ [toolchain] # Rust version the same as in /README.md -channel = "stable" +channel = "1.92" targets = ["wasm32-unknown-unknown"] From 72f7d6dbdfae5b4bc6bfd295a2beb9d560026e44 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Feb 2026 00:35:42 +0000 Subject: [PATCH 04/11] docs(rs-sdk): fix inaccurate and misleading rustdoc comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - lib.rs: Replace misleading "CRUD interface" with accurate description of query traits (Fetch, FetchMany, FetchUnproved, FetchCurrent) and state transition traits (PutIdentity, PutContract, PutDocument, etc.) - put_contract.rs: Fix doc saying "document" instead of "contract" - put_document.rs: Fix doc saying "identity" instead of "document" - vote.rs: Fix docs saying "identity" instead of "vote" (two places) - query.rs: Fix duplicate "epoch records" doc on DEFAULT_NODES_VOTING_LIMIT - waitable.rs: Fix typos "a wait" -> "a way", "conveniance" -> "convenience" - tokens/mod.rs: Fix wrong doc on token_info module (was "Identity token balances queries", now "Token info queries") - total_credits_in_platform.rs: Fix module doc saying "Epoch-related" - fetch_current_no_parameters.rs: Broaden FetchCurrent doc from epoch-specific to generic (also used for TotalCreditsInPlatform) All changes verified with `RUSTDOCFLAGS="-D warnings" cargo doc` — zero warnings and no broken intra-doc links. https://claude.ai/code/session_01HdTH5NBEVTmxbW63RCkS9J --- packages/rs-sdk/src/lib.rs | 36 ++++++++++++++----- .../platform/fetch_current_no_parameters.rs | 12 ++++--- packages/rs-sdk/src/platform/query.rs | 2 +- packages/rs-sdk/src/platform/tokens/mod.rs | 2 +- .../src/platform/transition/put_contract.rs | 4 +-- .../src/platform/transition/put_document.rs | 2 +- .../rs-sdk/src/platform/transition/vote.rs | 4 +-- .../src/platform/transition/waitable.rs | 4 +-- .../types/total_credits_in_platform.rs | 2 +- 9 files changed, 45 insertions(+), 23 deletions(-) diff --git a/packages/rs-sdk/src/lib.rs b/packages/rs-sdk/src/lib.rs index b522a14a2e7..12c06afa1cd 100644 --- a/packages/rs-sdk/src/lib.rs +++ b/packages/rs-sdk/src/lib.rs @@ -2,13 +2,13 @@ //! //! This is the official Rust SDK for the Dash Platform. Dash Platform is a Layer 2 cryptocurrency technology that //! builds upon the Dash layer 1 network. This SDK provides an abstraction layer to simplify usage of the Dash -//! Platform along with data models based on the Dash Platform Protocol (DPP) and a CRUD interface. +//! Platform along with data models based on the Dash Platform Protocol (DPP), query traits for reading data, and +//! state transition traits for writing data. //! //! //! ## Dash Platform Protocol Data Model //! -//! SDK data model uses types defined in [Dash Platform Protocol (DPP)](crate::platform::dpp). At this point, the following -//! types are supported: +//! SDK data model uses types defined in [Dash Platform Protocol (DPP)](crate::platform::dpp). The core types are: //! //! 1. [`Identity`](crate::platform::Identity) //! 2. [`DataContract`](crate::platform::DataContract) @@ -19,15 +19,18 @@ //! //! Basic DPP objects are re-exported in the [`platform`] module. //! -//! ## CRUD Interface +//! ## Querying (Reading Data) //! -//! Operations on data model objects can be executed using traits following CRUD (Create, Read, Update, and Delete) -//! approach. The following traits are already implemented: +//! Data can be read from Platform using the following traits: //! -//! 1. [`Fetch`](crate::platform::Fetch) - fetch a single object from Platform -//! 2. [`FetchMany`](crate::platform::FetchMany) - fetch multiple objects from Platform +//! 1. [`Fetch`](crate::platform::Fetch) - fetch a single object from Platform with proof verification +//! 2. [`FetchMany`](crate::platform::FetchMany) - fetch multiple objects from Platform with proof verification +//! 3. [`FetchUnproved`](crate::platform::FetchUnproved) - fetch a single object without proof verification +//! (e.g., for node status queries) +//! 4. [`FetchCurrent`](crate::platform::fetch_current_no_parameters::FetchCurrent) - fetch current +//! state for parameter-free queries (e.g., current epoch, total credits) //! -//! Fetch and FetchMany traits return objects based on provided queries. Some example queries include: +//! These traits return objects based on provided queries. Some example queries include: //! //! 1. [`Identifier`](crate::platform::Identifier) - fetches an object by its identifier //! 2. [`DocumentQuery`](crate::platform::DocumentQuery) - fetches documents based on search conditions; see @@ -35,6 +38,21 @@ //! for more details. //! 3. [`DriveDocumentQuery`](crate::platform::DriveDocumentQuery) - can be used to build more complex queries //! +//! ## State Transitions (Writing Data) +//! +//! Data is written to Platform by broadcasting state transitions. The SDK provides traits for common +//! write operations: +//! +//! - [`PutIdentity`](crate::platform::transition::put_identity::PutIdentity) - register a new identity +//! - [`PutContract`](crate::platform::transition::put_contract::PutContract) - publish a data contract +//! - [`PutDocument`](crate::platform::transition::put_document::PutDocument) - create or replace a document +//! - [`TransferToIdentity`](crate::platform::transition::transfer::TransferToIdentity) - transfer credits between identities +//! - [`WithdrawFromIdentity`](crate::platform::transition::withdraw_from_identity::WithdrawFromIdentity) - withdraw credits +//! - [`TopUpIdentity`](crate::platform::transition::top_up_identity::TopUpIdentity) - add credits to an identity +//! - [`PutVote`](crate::platform::transition::vote::PutVote) - cast a masternode vote +//! +//! For document operations, builder-based APIs are also available (see [`platform::documents::transitions`]). +//! //! ## Testability //! //! SDK operations can be mocked using [Sdk::new_mock()]. diff --git a/packages/rs-sdk/src/platform/fetch_current_no_parameters.rs b/packages/rs-sdk/src/platform/fetch_current_no_parameters.rs index 9d87bc9ea86..74d42ca27e5 100644 --- a/packages/rs-sdk/src/platform/fetch_current_no_parameters.rs +++ b/packages/rs-sdk/src/platform/fetch_current_no_parameters.rs @@ -4,13 +4,17 @@ use dapi_grpc::platform::v0::{Proof, ResponseMetadata}; #[async_trait] -/// Helper trait for managing Epoch information +/// Helper trait for fetching current state from Platform without query parameters. +/// +/// Implemented for types that have a single "current" value on Platform, such as +/// the current epoch ([`ExtendedEpochInfo`](dpp::block::extended_epoch_info::ExtendedEpochInfo)) +/// or total credits in platform. pub trait FetchCurrent: Sized { - /// Fetch current (the latest) epoch from Platform. + /// Fetch the current value from Platform. async fn fetch_current(sdk: &Sdk) -> Result; - /// Fetch current (the latest) epoch from Platform with metadata. + /// Fetch the current value from Platform with metadata. async fn fetch_current_with_metadata(sdk: &Sdk) -> Result<(Self, ResponseMetadata), Error>; - /// Fetch current (the latest) epoch from Platform with metadata and proof. + /// Fetch the current value from Platform with metadata and proof. async fn fetch_current_with_metadata_and_proof( sdk: &Sdk, ) -> Result<(Self, ResponseMetadata, Proof), Error>; diff --git a/packages/rs-sdk/src/platform/query.rs b/packages/rs-sdk/src/platform/query.rs index a7827789b04..b239841e931 100644 --- a/packages/rs-sdk/src/platform/query.rs +++ b/packages/rs-sdk/src/platform/query.rs @@ -50,7 +50,7 @@ use std::fmt::Debug; /// Default limit of epoch records returned by Platform. pub const DEFAULT_EPOCH_QUERY_LIMIT: u32 = 100; -/// Default limit of epoch records returned by Platform. +/// Default limit of masternode voting records returned by Platform. pub const DEFAULT_NODES_VOTING_LIMIT: u32 = 100; /// Trait implemented by objects that can be used as queries. diff --git a/packages/rs-sdk/src/platform/tokens/mod.rs b/packages/rs-sdk/src/platform/tokens/mod.rs index b1c05f465ac..d8bc6b10d7a 100644 --- a/packages/rs-sdk/src/platform/tokens/mod.rs +++ b/packages/rs-sdk/src/platform/tokens/mod.rs @@ -3,7 +3,7 @@ pub mod builders; pub mod identity_token_balances; /// Token contract info query pub mod token_contract_info; -/// Identity token balances queries +/// Token info queries pub mod token_info; /// Token status query pub mod token_status; diff --git a/packages/rs-sdk/src/platform/transition/put_contract.rs b/packages/rs-sdk/src/platform/transition/put_contract.rs index 9b7cf384eda..a608c3f6566 100644 --- a/packages/rs-sdk/src/platform/transition/put_contract.rs +++ b/packages/rs-sdk/src/platform/transition/put_contract.rs @@ -19,8 +19,8 @@ use super::waitable::Waitable; #[async_trait::async_trait] /// A trait for putting a contract to platform pub trait PutContract>: Waitable { - /// Puts a document on platform - /// setting settings to `None` sets default connection behavior + /// Puts a contract on platform + /// Setting settings to `None` sets default connection behavior async fn put_to_platform( &self, sdk: &Sdk, diff --git a/packages/rs-sdk/src/platform/transition/put_document.rs b/packages/rs-sdk/src/platform/transition/put_document.rs index fa3646717ee..20b45a8900a 100644 --- a/packages/rs-sdk/src/platform/transition/put_document.rs +++ b/packages/rs-sdk/src/platform/transition/put_document.rs @@ -32,7 +32,7 @@ pub trait PutDocument>: Waitable { settings: Option, ) -> Result; - /// Puts an identity on platform and waits for the confirmation proof + /// Puts a document on platform and waits for the confirmation proof #[allow(clippy::too_many_arguments)] async fn put_to_platform_and_wait_for_response( &self, diff --git a/packages/rs-sdk/src/platform/transition/vote.rs b/packages/rs-sdk/src/platform/transition/vote.rs index 5c9ce012856..30abf33e6bf 100644 --- a/packages/rs-sdk/src/platform/transition/vote.rs +++ b/packages/rs-sdk/src/platform/transition/vote.rs @@ -20,7 +20,7 @@ use super::waitable::Waitable; #[async_trait::async_trait] /// A trait for putting a vote on platform pub trait PutVote>: Waitable { - /// Puts an identity on platform + /// Puts a vote on platform async fn put_to_platform( &self, voter_pro_tx_hash: Identifier, @@ -29,7 +29,7 @@ pub trait PutVote>: Waitable { signer: &S, settings: Option, ) -> Result<(), Error>; - /// Puts an identity on platform and waits for the confirmation proof + /// Puts a vote on platform and waits for the confirmation proof async fn put_to_platform_and_wait_for_response( &self, voter_pro_tx_hash: Identifier, diff --git a/packages/rs-sdk/src/platform/transition/waitable.rs b/packages/rs-sdk/src/platform/transition/waitable.rs index faee580b315..21804da94fb 100644 --- a/packages/rs-sdk/src/platform/transition/waitable.rs +++ b/packages/rs-sdk/src/platform/transition/waitable.rs @@ -13,10 +13,10 @@ use dpp::state_transition::StateTransitionLike; use dpp::voting::votes::Vote; use dpp::ProtocolError; -/// Waitable trait provides a wait to wait for a response of a state transition after it has been broadcast and +/// Waitable trait provides a way to wait for a response of a state transition after it has been broadcast and /// receive altered objects. /// -/// This is simple conveniance trait wrapping the [`BroadcastStateTransition::wait_for_response`] method. +/// This is a simple convenience trait wrapping the [`BroadcastStateTransition::wait_for_response`] method. #[async_trait::async_trait] pub trait Waitable: Sized { async fn wait_for_response( diff --git a/packages/rs-sdk/src/platform/types/total_credits_in_platform.rs b/packages/rs-sdk/src/platform/types/total_credits_in_platform.rs index ebfd7879674..7aff591cf3c 100644 --- a/packages/rs-sdk/src/platform/types/total_credits_in_platform.rs +++ b/packages/rs-sdk/src/platform/types/total_credits_in_platform.rs @@ -1,4 +1,4 @@ -//! Epoch-related types and helpers +//! Total credits in platform types and helpers use crate::platform::fetch_current_no_parameters::FetchCurrent; use crate::{platform::Fetch, Error, Sdk}; use async_trait::async_trait; From 7967db5b8349cf30cdb77687fa0c0378bf5fd5de Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Feb 2026 01:02:30 +0000 Subject: [PATCH 05/11] docs(rs-sdk): fix rustdoc inaccuracies across 32 files Comprehensive review of all rustdoc comments in rs-sdk found and fixed issues across 32 files including: - Copy-paste errors (wrong object types in trait docs, wrong parameter names in argument lists) - Factual inaccuracies (wrong method names, wrong return type docs, incorrect trait bound claims, wrong default value references) - Misleading descriptions (broadcast_request.rs claimed signing/identity operations but trait only serializes state transitions) - Terminology errors ("request" vs "transition" in token builders, code identifiers like "config_update" in prose text) - Typos and grammar (double spaces, missing prepositions, missing plurals, misspellings, non-breaking space characters) - Incorrect doc links (wrong type names, singular vs plural, redundant explicit link targets) - Wrong/copy-pasted supported query type lists in FetchMany impls - Missing parameter documentation Verified with RUSTDOCFLAGS="-D warnings" cargo doc -- zero warnings. https://claude.ai/code/session_01HdTH5NBEVTmxbW63RCkS9J --- packages/rs-sdk/src/core/dash_core_client.rs | 4 +- packages/rs-sdk/src/error.rs | 2 +- packages/rs-sdk/src/mock/provider.rs | 10 +-- packages/rs-sdk/src/mock/sdk.rs | 15 +++-- .../src/platform/block_info_from_metadata.rs | 10 +-- packages/rs-sdk/src/platform/delegate.rs | 2 +- .../src/platform/documents/document_query.rs | 2 +- .../platform/documents/transitions/create.rs | 3 +- .../dpns_usernames/contested_queries.rs | 2 +- packages/rs-sdk/src/platform/fetch.rs | 21 +++--- packages/rs-sdk/src/platform/fetch_many.rs | 25 ++++---- packages/rs-sdk/src/platform/group_actions.rs | 2 +- .../src/platform/tokens/builders/burn.rs | 2 +- .../platform/tokens/builders/config_update.rs | 17 +++-- .../src/platform/tokens/builders/destroy.rs | 4 +- .../tokens/builders/emergency_action.rs | 6 +- .../src/platform/tokens/builders/freeze.rs | 4 +- .../src/platform/tokens/builders/mint.rs | 2 +- .../src/platform/tokens/builders/purchase.rs | 5 +- .../src/platform/tokens/builders/set_price.rs | 2 +- .../src/platform/tokens/builders/transfer.rs | 2 +- .../src/platform/tokens/builders/unfreeze.rs | 2 +- .../tokens/transitions/emergency_action.rs | 2 +- .../set_price_for_direct_purchase.rs | 2 +- .../platform/tokens/transitions/transfer.rs | 6 +- .../platform/tokens/transitions/unfreeze.rs | 2 +- .../platform/transition/broadcast_request.rs | 64 ++++--------------- .../src/platform/transition/transfer.rs | 7 +- packages/rs-sdk/src/platform/types/evonode.rs | 2 +- .../src/platform/types/proposed_blocks.rs | 15 ++--- packages/rs-sdk/src/sdk.rs | 8 +-- packages/rs-sdk/src/sync.rs | 4 +- 32 files changed, 107 insertions(+), 149 deletions(-) diff --git a/packages/rs-sdk/src/core/dash_core_client.rs b/packages/rs-sdk/src/core/dash_core_client.rs index 8d60fe1a5a6..fe1fdb39f73 100644 --- a/packages/rs-sdk/src/core/dash_core_client.rs +++ b/packages/rs-sdk/src/core/dash_core_client.rs @@ -112,7 +112,7 @@ impl LowLevelDashCoreClient { .map_err(Error::CoreClientError) } - /// Return address to which change of transaction can be sent. + /// Return the wallet balance. #[allow(dead_code)] #[deprecated(note = "This function is marked as unused.")] pub fn get_balance(&self) -> Result { @@ -164,7 +164,7 @@ impl LowLevelDashCoreClient { )) } - /// Require list of validators from Core. + /// Request list of masternodes from Core. /// /// See also [Dash Core documentation](https://docs.dash.org/projects/core/en/stable/docs/api/remote-procedure-calls-evo.html#protx-list) #[allow(unused)] diff --git a/packages/rs-sdk/src/error.rs b/packages/rs-sdk/src/error.rs index 5e2543180b7..70551d5c8eb 100644 --- a/packages/rs-sdk/src/error.rs +++ b/packages/rs-sdk/src/error.rs @@ -28,7 +28,7 @@ pub enum Error { /// Drive error #[error("Drive error: {0}")] Drive(#[from] drive::error::Error), - /// Drive error + /// Drive proof error with associated proof bytes and block info #[error("Drive error with associated proof: {0}")] DriveProofError(drive::error::proof::ProofError, Vec, BlockInfo), /// DPP error diff --git a/packages/rs-sdk/src/mock/provider.rs b/packages/rs-sdk/src/mock/provider.rs index 6680d6b28eb..1db9190ffcf 100644 --- a/packages/rs-sdk/src/mock/provider.rs +++ b/packages/rs-sdk/src/mock/provider.rs @@ -1,4 +1,4 @@ -//! Example ContextProvider that uses the Core gRPC API to fetch data from Platform. +//! Example ContextProvider that uses the Core RPC API and the Sdk to fetch data. use crate::core::LowLevelDashCoreClient; use crate::platform::Fetch; @@ -14,7 +14,7 @@ use std::hash::Hash; use std::num::NonZeroUsize; use std::sync::Arc; -/// Context provider that uses the Core gRPC API to fetch data from Platform. +/// Context provider that uses the Core RPC API and the Sdk to fetch data. /// /// Example [ContextProvider] used by the Sdk for testing purposes. pub struct GrpcContextProvider { @@ -137,9 +137,9 @@ impl GrpcContextProvider { /// Save data contract to disk. /// - /// Files are named: `quorum_pubkey--.json` + /// Files are named: `data_contract-.json` /// - /// Note that this will overwrite files with the same quorum type and quorum hash. + /// Note that this will overwrite files with the same data contract ID. /// /// Any errors are logged on `warn` level and ignored. #[cfg(feature = "mocks")] @@ -251,7 +251,7 @@ impl ContextProvider for GrpcContextProvider { /// /// This is used to cache objects that are expensive to fetch from Platform, like data contracts. pub struct Cache { - // We use a Mutex to allow access to the cache when we don't have mutable &self + // We use a RwLock to allow access to the cache when we don't have mutable &self // And we use Arc to allow multiple threads to access the cache without having to clone it inner: std::sync::RwLock>>, } diff --git a/packages/rs-sdk/src/mock/sdk.rs b/packages/rs-sdk/src/mock/sdk.rs index c7904f05d4b..8a2e3b26215 100644 --- a/packages/rs-sdk/src/mock/sdk.rs +++ b/packages/rs-sdk/src/mock/sdk.rs @@ -72,7 +72,7 @@ impl MockDashPlatformSdk { /// /// ## Note /// - /// You have to call [MockDashPlatformSdk::with_sdk()] to set sdk, otherwise Mock SDK will panic. + /// You have to call [MockDashPlatformSdk::set_sdk()] to set sdk, otherwise Mock SDK will panic. pub(crate) fn new(version: &'static PlatformVersion, dapi: Arc>) -> Self { Self { from_proof_expectations: Default::default(), @@ -275,7 +275,7 @@ impl MockDashPlatformSdk { /// ## Generic Parameters /// /// - `O`: Type of the object that will be returned in response to the query. Must implement [Fetch] and [MockResponse]. - /// - `Q`: Type of the query that will be sent to Platform. Must implement [Query] and [Mockable]. + /// - `Q`: Type of the query that will be sent to Platform. Must implement [Query]. /// /// ## Arguments /// @@ -352,13 +352,14 @@ impl MockDashPlatformSdk { /// ## Generic Parameters /// /// - `O`: Type of the object that will be returned in response to the query. - /// Must implement [FetchMany]. `Vec` must implement [MockResponse]. - /// - `Q`: Type of the query that will be sent to Platform. Must implement [Query] and [Mockable]. + /// Must implement [FetchMany]. + /// - `Q`: Type of the query that will be sent to Platform. Must implement [Query]. + /// - `R`: Collection type for the results. Must implement [MockResponse]. /// /// ## Arguments /// /// - `query`: Query that will be sent to Platform. - /// - `objects`: Vector of objects that will be returned in response to `query`, or None if no objects are expected. + /// - `objects`: Collection of objects that will be returned in response to `query`, or None if no objects are expected. /// /// ## Returns /// @@ -487,7 +488,7 @@ impl MockDashPlatformSdk { removed_from_proof || removed_from_dapi } - /// Wrapper around [FromProof] that uses mock expectations instead of executing [FromProof] trait. + /// Wrapper around [FromProof] that uses mock expectations, falling back to [FromProof] if no expectation is found. pub(crate) fn parse_proof_with_metadata>( &self, request: O::Request, @@ -535,7 +536,7 @@ impl MockDashPlatformSdk { Ok(data) } - /// Return context provider implementation defined for upstreeam Sdk object. + /// Return context provider implementation defined for upstream Sdk object. fn context_provider(&self) -> Option { if let Some(sdk) = self.sdk.load_full() { sdk.clone().context_provider() diff --git a/packages/rs-sdk/src/platform/block_info_from_metadata.rs b/packages/rs-sdk/src/platform/block_info_from_metadata.rs index 5e96e136550..a30f57815b1 100644 --- a/packages/rs-sdk/src/platform/block_info_from_metadata.rs +++ b/packages/rs-sdk/src/platform/block_info_from_metadata.rs @@ -7,8 +7,8 @@ use drive::error::proof::ProofError; /// Constructs a `BlockInfo` structure from the provided response metadata. This function /// translates metadata received from a platform response into a format that is specific to the /// application's needs, particularly focusing on block-related information. It ensures that -/// the epoch value from the metadata does not exceed the maximum allowed for a 16-bit integer, -/// as this is a constraint for the `BlockInfo` structure. +/// the epoch value from the metadata does not exceed `MAX_EPOCH`, +/// as this is a constraint for the `Epoch` type used in the `BlockInfo` structure. /// /// # Parameters /// - `response_metadata`: A reference to `ResponseMetadata` obtained from a platform response. @@ -20,18 +20,18 @@ use drive::error::proof::ProofError; /// - `time_ms`: The timestamp of the block in milliseconds. /// - `height`: The height of the block. /// - `core_height`: The core chain locked height, indicating the height of the block in the core blockchain that is considered final and securely linked to this block. -/// - `epoch`: The epoch number, converted to a 16-bit integer. +/// - `epoch`: The epoch number, converted to an `Epoch` struct via a 16-bit index. /// /// # Errors /// Returns an error if: -/// - The `epoch` value in the response metadata exceeds the maximum value that can be represented by a 16-bit integer. This is considered a data validity error as it indicates Platform returned an unexpectedly high epoch number. +/// - The `epoch` value in the response metadata exceeds `MAX_EPOCH`. This is considered a data validity error as it indicates Platform returned an unexpectedly high epoch number. /// /// The function encapsulates errors into the application's own `Error` type, providing a unified interface for error handling across the application. pub fn block_info_from_metadata(response_metadata: &ResponseMetadata) -> Result { if response_metadata.epoch > MAX_EPOCH as u32 { return Err( drive::error::Error::Proof(ProofError::InvalidMetadata(format!( - "platform returned an epoch {} that was higher that maximum of a 16 bit integer", + "platform returned an epoch {} that was higher than the maximum allowed epoch", response_metadata.epoch ))) .into(), diff --git a/packages/rs-sdk/src/platform/delegate.rs b/packages/rs-sdk/src/platform/delegate.rs index f82127c205c..f58ecb03652 100644 --- a/packages/rs-sdk/src/platform/delegate.rs +++ b/packages/rs-sdk/src/platform/delegate.rs @@ -131,7 +131,7 @@ macro_rules! delegate_from_proof_variant { /// and [FromProof](drive_proof_verifier::FromProof) to the appropriate variant. /// /// This macro creates enums for requests (`$request`) and responses (`$response`) and variants (`$variant`) for -/// each request (`$req`) /response (`$req`) pair. Variant name in request and response enums are the same. +/// each request (`$req`) /response (`$resp`) pair. Variant name in request and response enums are the same. /// /// It also calls [delegate_transport_request_variant!](crate::delegate_transport_request_variant!) and /// [delegate_from_proof_variant!](crate::delegate_from_proof_variant!) to delegate diff --git a/packages/rs-sdk/src/platform/documents/document_query.rs b/packages/rs-sdk/src/platform/documents/document_query.rs index 7808977e2aa..6fd5bc0fd70 100644 --- a/packages/rs-sdk/src/platform/documents/document_query.rs +++ b/packages/rs-sdk/src/platform/documents/document_query.rs @@ -41,7 +41,7 @@ use crate::platform::Fetch; #[derive(Debug, Clone, PartialEq, dash_platform_macros::Mockable)] #[cfg_attr(feature = "mocks", derive(serde::Serialize, serde::Deserialize))] pub struct DocumentQuery { - /// Data contract ID + /// Data contract pub data_contract: Arc, /// Document type for the data contract pub document_type_name: String, diff --git a/packages/rs-sdk/src/platform/documents/transitions/create.rs b/packages/rs-sdk/src/platform/documents/transitions/create.rs index 26c77e4acda..450836ae167 100644 --- a/packages/rs-sdk/src/platform/documents/transitions/create.rs +++ b/packages/rs-sdk/src/platform/documents/transitions/create.rs @@ -107,7 +107,7 @@ impl DocumentCreateTransitionBuilder { /// /// # Arguments /// - /// * `settings` - The settings to add + /// * `creation_options` - The creation options to add /// /// # Returns /// @@ -128,7 +128,6 @@ impl DocumentCreateTransitionBuilder { /// * `identity_public_key` - The public key of the identity /// * `signer` - The signer instance /// * `platform_version` - The platform version - /// * `options` - Optional state transition creation options /// /// # Returns /// diff --git a/packages/rs-sdk/src/platform/dpns_usernames/contested_queries.rs b/packages/rs-sdk/src/platform/dpns_usernames/contested_queries.rs index 40436258dce..a73231feb3f 100644 --- a/packages/rs-sdk/src/platform/dpns_usernames/contested_queries.rs +++ b/packages/rs-sdk/src/platform/dpns_usernames/contested_queries.rs @@ -32,7 +32,7 @@ pub struct ContestInfo { pub end_time: TimestampMillis, } -/// Result of a contested DPNS username +/// A contested DPNS username #[derive(Debug, Clone)] pub struct ContestedDpnsUsername { /// The domain label (e.g., "alice") diff --git a/packages/rs-sdk/src/platform/fetch.rs b/packages/rs-sdk/src/platform/fetch.rs index 5e904b597ab..3c197c810bf 100644 --- a/packages/rs-sdk/src/platform/fetch.rs +++ b/packages/rs-sdk/src/platform/fetch.rs @@ -6,7 +6,7 @@ //! ## Traits //! - [Fetch]: An asynchronous trait that defines how to fetch data from Platform. //! It requires the implementing type to also implement [Debug] and [FromProof] -//! traits. The associated [Fetch::Request]` type needs to implement [TransportRequest]. +//! traits. The associated [`Fetch::Request`] type needs to implement [TransportRequest]. use crate::mock::MockResponse; use crate::sync::retry; @@ -34,8 +34,9 @@ use super::DocumentQuery; /// To fetch an object from Platform, you need to define some query (criteria that fetched object must match) and /// use [Fetch::fetch()] for your object type. /// -/// Implementators of this trait should implement at least the [fetch_with_metadata()](Fetch::fetch_with_metadata) -/// method, as other methods are convenience methods that call it with default settings. +/// Implementors of this trait must define the associated [`Fetch::Request`] type. +/// All methods have default implementations; override [fetch_with_metadata_and_proof()](Fetch::fetch_with_metadata_and_proof) +/// if custom fetch logic is needed, as other methods are convenience methods that call it. /// /// ## Example /// @@ -112,9 +113,9 @@ where /// /// ## Returns /// - /// Returns: - /// * `Ok(Some(Self))` when object is found - /// * `Ok(None)` when object is not found + /// Returns a tuple of the fetched object and [ResponseMetadata]: + /// * `Ok((Some(Self), ResponseMetadata))` when object is found + /// * `Ok((None, ResponseMetadata))` when object is not found /// * [`Err(Error)`](Error) when an error occurs /// /// ## Error Handling @@ -135,7 +136,7 @@ where /// Fetch object from Platform that satisfies provided [Query]. /// Most often, the Query is an [Identifier] of the object to be fetched. /// - /// This method is meant to give the user library a way to see the underlying proof + /// This method is meant to give the library user a way to see the underlying proof /// for educational purposes. This method should most likely only be used for debugging. /// /// ## Parameters @@ -146,9 +147,9 @@ where /// /// ## Returns /// - /// Returns: - /// * `Ok(Some(Self))` when object is found - /// * `Ok(None)` when object is not found + /// Returns a tuple of the fetched object, [ResponseMetadata], and the underlying [Proof]: + /// * `Ok((Some(Self), ResponseMetadata, Proof))` when object is found + /// * `Ok((None, ResponseMetadata, Proof))` when object is not found /// * [`Err(Error)`](Error) when an error occurs /// /// ## Error Handling diff --git a/packages/rs-sdk/src/platform/fetch_many.rs b/packages/rs-sdk/src/platform/fetch_many.rs index b960a138614..c043cc153cc 100644 --- a/packages/rs-sdk/src/platform/fetch_many.rs +++ b/packages/rs-sdk/src/platform/fetch_many.rs @@ -129,7 +129,7 @@ where /// /// Returns a `Result` containing either: /// - /// * list of objects matching the [Query] indexed by a key type `K`, where an item can be None of + /// * list of objects matching the [Query] indexed by a key type `K`, where an item can be None if /// the object was not found for provided key /// * [`Error`](crate::error::Error). /// @@ -270,7 +270,7 @@ where /// /// ## Supported query types /// -/// * [DriveQuery](crate::platform::DriveDocumentQuery) - query that specifies document matching criteria +/// * [DriveDocumentQuery](crate::platform::DriveDocumentQuery) - query that specifies document matching criteria /// * [DocumentQuery](crate::platform::documents::document_query::DocumentQuery) #[async_trait::async_trait] impl FetchMany for Document { @@ -433,7 +433,7 @@ impl FetchMany for ProtocolVersionVote /// /// * [ProTxHash](dpp::dashcore_rpc::dashcore::ProTxHash) - proTxHash of first object to find; will return up to /// [DEFAULT_NODES_VOTING_LIMIT](super::query::DEFAULT_NODES_VOTING_LIMIT) objects -/// * `Option` - proTxHash that can be and [Option]; if it is `None`, +/// * `Option` - optional proTxHash; if it is `None`, /// the query will return all objects /// * [`LimitQuery`](super::LimitQuery) - limit query that allows to specify maximum number of objects /// to fetch; see also [FetchMany::fetch_many_with_limit()]. @@ -449,12 +449,10 @@ impl FetchMany for MasternodeProtocolVote { /// /// ## Supported query types /// -/// * [ProTxHash](dpp::dashcore_rpc::dashcore::ProTxHash) - proTxHash of first object to find; will return up to -/// [DEFAULT_NODES_VOTING_LIMIT](super::query::DEFAULT_NODES_VOTING_LIMIT) objects -/// * `Option` - proTxHash that can be and [Option]; if it is `None`, -/// the query will return all objects -/// * [`LimitQuery`](super::LimitQuery) - limit query that allows to specify maximum number of objects -/// to fetch; see also [FetchMany::fetch_many_with_limit()]. +/// * [`LimitQuery>`](super::LimitQuery) - query specifying an optional epoch index +/// and a limit on the number of objects to fetch +/// * [`LimitQuery`](super::LimitQuery) - limit query wrapping +/// a raw request for more fine-grained control impl FetchMany for ProposerBlockCountByRange { type Request = GetEvonodesProposedEpochBlocksByRangeRequest; } @@ -467,7 +465,9 @@ impl FetchMany for ProposerBlockCountByRange { /// /// ## Supported query types /// -/// * [ProTxHash](dpp::dashcore_rpc::dashcore::ProTxHash) - proTxHash of an evonode to find; will return one evonode block count +/// * [`ProposerBlockCountByIdsQuery`](super::query::ProposerBlockCountByIdsQuery) - query specifying an optional epoch +/// and a list of evonode ProTxHashes to look up +/// * [`(EpochIndex, Vec)`] - tuple of epoch index and list of evonode ProTxHashes impl FetchMany for ProposerBlockCountById { type Request = GetEvonodesProposedEpochBlocksByIdsRequest; } @@ -495,7 +495,7 @@ impl FetchMany for ContestedResource { /// Fetch multiple contenders for a contested document resource vote poll. /// -/// Returns [Contender](drive_proof_verifier::types::Contenders) indexed by [Identifier](dpp::prelude::Identifier). +/// Returns [Contenders](drive_proof_verifier::types::Contenders) indexed by [Identifier](dpp::prelude::Identifier). /// /// ## Supported query types /// @@ -505,7 +505,8 @@ impl FetchMany for ContenderWithSerializedDocument { type Request = GetContestedResourceVoteStateRequest; } -///  Fetch voters +/// Fetch voters for a contested document resource vote poll. +/// /// ## Supported query types /// /// * [`ContestedDocumentVotePollVotesDriveQuery`](drive::query::vote_poll_contestant_votes_query::ContestedDocumentVotePollVotesDriveQuery) diff --git a/packages/rs-sdk/src/platform/group_actions.rs b/packages/rs-sdk/src/platform/group_actions.rs index 6af6309b4fa..c12199ae04d 100644 --- a/packages/rs-sdk/src/platform/group_actions.rs +++ b/packages/rs-sdk/src/platform/group_actions.rs @@ -132,7 +132,7 @@ impl FetchMany for GroupAction { } #[derive(Debug, Clone)] -/// Query to fetch available signatures of specific data contract and group action +/// Query to fetch signers of a specific data contract group action pub struct GroupActionSignersQuery { /// Data contract ID pub contract_id: Identifier, diff --git a/packages/rs-sdk/src/platform/tokens/builders/burn.rs b/packages/rs-sdk/src/platform/tokens/builders/burn.rs index 5519042a615..e714a1d4a27 100644 --- a/packages/rs-sdk/src/platform/tokens/builders/burn.rs +++ b/packages/rs-sdk/src/platform/tokens/builders/burn.rs @@ -117,7 +117,7 @@ impl TokenBurnTransitionBuilder { /// /// # Arguments /// - /// * `state_transition_creation_options` - The signing options to add + /// * `state_transition_creation_options` - The state transition creation options to add /// /// # Returns /// diff --git a/packages/rs-sdk/src/platform/tokens/builders/config_update.rs b/packages/rs-sdk/src/platform/tokens/builders/config_update.rs index 8cf15ae4a85..960ad87470c 100644 --- a/packages/rs-sdk/src/platform/tokens/builders/config_update.rs +++ b/packages/rs-sdk/src/platform/tokens/builders/config_update.rs @@ -16,7 +16,7 @@ use dpp::tokens::calculate_token_id; use dpp::version::PlatformVersion; use std::sync::Arc; -/// A builder to configure and broadcast token config_update transitions +/// A builder to configure and broadcast token configuration update transitions pub struct TokenConfigUpdateTransitionBuilder { pub data_contract: Arc, pub token_position: TokenContractPosition, @@ -30,7 +30,7 @@ pub struct TokenConfigUpdateTransitionBuilder { } impl TokenConfigUpdateTransitionBuilder { - /// Start building a config_update tokens transition for the provided DataContract. + /// Start building a token configuration update transition for the provided DataContract. /// /// # Arguments /// @@ -38,7 +38,6 @@ impl TokenConfigUpdateTransitionBuilder { /// * `token_position` - The position of the token in the contract /// * `owner_id` - The identifier of the state transition owner /// * `update_token_configuration_item` - The token configuration change item - /// * `using_group_info` - Group transition info status /// /// # Returns /// @@ -62,7 +61,7 @@ impl TokenConfigUpdateTransitionBuilder { } } - /// Adds a public note to the token config_update transition + /// Adds a public note to the token configuration update transition /// /// # Arguments /// @@ -76,7 +75,7 @@ impl TokenConfigUpdateTransitionBuilder { self } - /// Adds a user fee increase to the token config_update transition + /// Adds a user fee increase to the token configuration update transition /// /// # Arguments /// @@ -90,7 +89,7 @@ impl TokenConfigUpdateTransitionBuilder { self } - /// Adds group information to the token config update transition + /// Adds group information to the token configuration update transition /// /// # Arguments /// @@ -107,7 +106,7 @@ impl TokenConfigUpdateTransitionBuilder { self } - /// Adds settings to the token config_update transition + /// Adds settings to the token configuration update transition /// /// # Arguments /// @@ -121,7 +120,7 @@ impl TokenConfigUpdateTransitionBuilder { self } - /// Adds state transition creation options to the token config_update transition + /// Adds state transition creation options to the token configuration update transition /// /// # Arguments /// @@ -138,7 +137,7 @@ impl TokenConfigUpdateTransitionBuilder { self } - /// Signs the token config_update transition + /// Signs the token configuration update transition /// /// # Arguments /// diff --git a/packages/rs-sdk/src/platform/tokens/builders/destroy.rs b/packages/rs-sdk/src/platform/tokens/builders/destroy.rs index 8269ce074ee..b1686785a9b 100644 --- a/packages/rs-sdk/src/platform/tokens/builders/destroy.rs +++ b/packages/rs-sdk/src/platform/tokens/builders/destroy.rs @@ -15,7 +15,7 @@ use dpp::tokens::calculate_token_id; use dpp::version::PlatformVersion; use std::sync::Arc; -/// A builder to configure and broadcast token destroy funds transitions +/// A builder to configure and broadcast token destroy frozen funds transitions pub struct TokenDestroyFrozenFundsTransitionBuilder { pub data_contract: Arc, pub token_position: TokenContractPosition, @@ -29,7 +29,7 @@ pub struct TokenDestroyFrozenFundsTransitionBuilder { } impl TokenDestroyFrozenFundsTransitionBuilder { - /// Start building a mint tokens request for the provided DataContract. + /// Start building a destroy frozen funds transition for the provided DataContract. /// /// # Arguments /// diff --git a/packages/rs-sdk/src/platform/tokens/builders/emergency_action.rs b/packages/rs-sdk/src/platform/tokens/builders/emergency_action.rs index c6f3e97caf3..00b052b1145 100644 --- a/packages/rs-sdk/src/platform/tokens/builders/emergency_action.rs +++ b/packages/rs-sdk/src/platform/tokens/builders/emergency_action.rs @@ -16,7 +16,7 @@ use dpp::tokens::emergency_action::TokenEmergencyAction; use dpp::version::PlatformVersion; use std::sync::Arc; -/// A builder to configure and broadcast emergency action transitions +/// A builder to configure and broadcast token emergency action transitions pub struct TokenEmergencyActionTransitionBuilder { pub data_contract: Arc, pub token_position: TokenContractPosition, @@ -30,7 +30,7 @@ pub struct TokenEmergencyActionTransitionBuilder { } impl TokenEmergencyActionTransitionBuilder { - /// Start building a pause tokens request for the provided DataContract. + /// Start building a pause token transition for the provided DataContract. /// /// # Arguments /// @@ -59,7 +59,7 @@ impl TokenEmergencyActionTransitionBuilder { } } - /// Start building a resume tokens request for the provided DataContract. + /// Start building a resume token transition for the provided DataContract. /// /// # Arguments /// diff --git a/packages/rs-sdk/src/platform/tokens/builders/freeze.rs b/packages/rs-sdk/src/platform/tokens/builders/freeze.rs index 29c4f4d86d5..12c4c9ad229 100644 --- a/packages/rs-sdk/src/platform/tokens/builders/freeze.rs +++ b/packages/rs-sdk/src/platform/tokens/builders/freeze.rs @@ -29,14 +29,14 @@ pub struct TokenFreezeTransitionBuilder { } impl TokenFreezeTransitionBuilder { - /// Start building a mint tokens request for the provided DataContract. + /// Start building a freeze tokens transition for the provided DataContract. /// /// # Arguments /// /// * `data_contract` - An Arc to the data contract /// * `token_position` - The position of the token in the contract /// * `actor_id` - The identifier of the actor - /// * `freeze_identity_id` - The identifier of the frozen identity + /// * `freeze_identity_id` - The identifier of the identity to freeze /// /// # Returns /// diff --git a/packages/rs-sdk/src/platform/tokens/builders/mint.rs b/packages/rs-sdk/src/platform/tokens/builders/mint.rs index fe14d7bf5f2..45614d06bd3 100644 --- a/packages/rs-sdk/src/platform/tokens/builders/mint.rs +++ b/packages/rs-sdk/src/platform/tokens/builders/mint.rs @@ -31,7 +31,7 @@ pub struct TokenMintTransitionBuilder { } impl TokenMintTransitionBuilder { - /// Start building a mint tokens request for the provided DataContract. + /// Start building a mint tokens transition for the provided DataContract. /// /// # Arguments /// diff --git a/packages/rs-sdk/src/platform/tokens/builders/purchase.rs b/packages/rs-sdk/src/platform/tokens/builders/purchase.rs index fce0a483cf8..67771fc1ae9 100644 --- a/packages/rs-sdk/src/platform/tokens/builders/purchase.rs +++ b/packages/rs-sdk/src/platform/tokens/builders/purchase.rs @@ -29,14 +29,15 @@ pub struct TokenDirectPurchaseTransitionBuilder { } impl TokenDirectPurchaseTransitionBuilder { - /// Start building a purchase tokens request for the provided DataContract. + /// Start building a purchase tokens transition for the provided DataContract. /// /// # Arguments /// /// * `data_contract` - An Arc to the data contract /// * `token_position` - The position of the token in the contract - /// * `issuer_id` - The identifier of the issuer + /// * `actor_id` - The identifier of the purchaser /// * `amount` - The amount of tokens to purchase + /// * `total_agreed_price` - The total price in credits the purchaser agrees to pay /// /// # Returns /// diff --git a/packages/rs-sdk/src/platform/tokens/builders/set_price.rs b/packages/rs-sdk/src/platform/tokens/builders/set_price.rs index 65ded0944e3..57c298d3b61 100644 --- a/packages/rs-sdk/src/platform/tokens/builders/set_price.rs +++ b/packages/rs-sdk/src/platform/tokens/builders/set_price.rs @@ -33,7 +33,7 @@ pub struct TokenChangeDirectPurchasePriceTransitionBuilder { } impl TokenChangeDirectPurchasePriceTransitionBuilder { - /// Start building a change direct purchase price tokens request for the provided DataContract. + /// Start building a token change direct purchase price transition for the provided DataContract. /// /// # Arguments /// diff --git a/packages/rs-sdk/src/platform/tokens/builders/transfer.rs b/packages/rs-sdk/src/platform/tokens/builders/transfer.rs index aa0162021d2..a8cf0514e5c 100644 --- a/packages/rs-sdk/src/platform/tokens/builders/transfer.rs +++ b/packages/rs-sdk/src/platform/tokens/builders/transfer.rs @@ -31,7 +31,7 @@ pub struct TokenTransferTransitionBuilder { } impl TokenTransferTransitionBuilder { - /// Start building a mint tokens request for the provided DataContract. + /// Start building a transfer tokens transition for the provided DataContract. /// /// # Arguments /// diff --git a/packages/rs-sdk/src/platform/tokens/builders/unfreeze.rs b/packages/rs-sdk/src/platform/tokens/builders/unfreeze.rs index e1d3f7ef2b4..8cf605f36a9 100644 --- a/packages/rs-sdk/src/platform/tokens/builders/unfreeze.rs +++ b/packages/rs-sdk/src/platform/tokens/builders/unfreeze.rs @@ -29,7 +29,7 @@ pub struct TokenUnfreezeTransitionBuilder { } impl TokenUnfreezeTransitionBuilder { - /// Start building a mint tokens request for the provided DataContract. + /// Start building an unfreeze tokens transition for the provided DataContract. /// /// # Arguments /// diff --git a/packages/rs-sdk/src/platform/tokens/transitions/emergency_action.rs b/packages/rs-sdk/src/platform/tokens/transitions/emergency_action.rs index bf07779539f..7639122ea18 100644 --- a/packages/rs-sdk/src/platform/tokens/transitions/emergency_action.rs +++ b/packages/rs-sdk/src/platform/tokens/transitions/emergency_action.rs @@ -1,4 +1,4 @@ -//! Emergency action operations for token management. +//! Token emergency action operations for the Dash Platform SDK. //! //! This module provides functionality for executing emergency actions on tokens, //! typically requiring group authorization for critical interventions. diff --git a/packages/rs-sdk/src/platform/tokens/transitions/set_price_for_direct_purchase.rs b/packages/rs-sdk/src/platform/tokens/transitions/set_price_for_direct_purchase.rs index 578b2683441..30311488ec4 100644 --- a/packages/rs-sdk/src/platform/tokens/transitions/set_price_for_direct_purchase.rs +++ b/packages/rs-sdk/src/platform/tokens/transitions/set_price_for_direct_purchase.rs @@ -1,4 +1,4 @@ -//! Token price setting operations for direct purchase functionality. +//! Token price setting operations for the Dash Platform SDK. //! //! This module provides functionality to set or update pricing schedules //! for tokens that can be purchased directly. diff --git a/packages/rs-sdk/src/platform/tokens/transitions/transfer.rs b/packages/rs-sdk/src/platform/tokens/transitions/transfer.rs index 4cb03fe5985..cf809fcc672 100644 --- a/packages/rs-sdk/src/platform/tokens/transitions/transfer.rs +++ b/packages/rs-sdk/src/platform/tokens/transitions/transfer.rs @@ -29,17 +29,17 @@ pub enum TransferResult { } impl Sdk { - /// Transfers tokens from one identity to one or more recipients. + /// Transfers tokens from one identity to another. /// /// This method broadcasts a transfer transition to move tokens between identities. /// The result varies based on token configuration: - /// - Standard tokens return updated balances for all affected identities + /// - Standard tokens return updated balances for the affected identities /// - Tokens with history tracking return documents /// - Group-managed tokens include group power information /// /// # Arguments /// - /// * `transfer_tokens_transition_builder` - Builder containing transfer parameters including recipients and amounts + /// * `transfer_tokens_transition_builder` - Builder containing transfer parameters including recipient and amount /// * `signing_key` - The identity public key for signing the transition /// * `signer` - Implementation of the Signer trait for cryptographic signing /// diff --git a/packages/rs-sdk/src/platform/tokens/transitions/unfreeze.rs b/packages/rs-sdk/src/platform/tokens/transitions/unfreeze.rs index ed68ca5eefd..19c1668f4bc 100644 --- a/packages/rs-sdk/src/platform/tokens/transitions/unfreeze.rs +++ b/packages/rs-sdk/src/platform/tokens/transitions/unfreeze.rs @@ -77,7 +77,7 @@ impl Sdk { Ok(UnfreezeResult::IdentityInfo(owner_id_result, info)) } StateTransitionProofResult::VerifiedTokenActionWithDocument(doc) => { - // This means the token keeps freezing history + // This means the token keeps unfreezing history Ok(UnfreezeResult::HistoricalDocument(doc)) } StateTransitionProofResult::VerifiedTokenGroupActionWithDocument(power, doc) => { diff --git a/packages/rs-sdk/src/platform/transition/broadcast_request.rs b/packages/rs-sdk/src/platform/transition/broadcast_request.rs index 1779d5270e4..35e129aaee6 100644 --- a/packages/rs-sdk/src/platform/transition/broadcast_request.rs +++ b/packages/rs-sdk/src/platform/transition/broadcast_request.rs @@ -1,10 +1,10 @@ //! Broadcast trait representing the action of broadcasting a state transition to Platform. //! -//! The [`BroadcastRequestForStateTransition`] trait is designed for the creation and broadcasting of state transitions. -//! This involves the generation of a state transition object, signing it, and then broadcasting it to Platform. +//! The [`BroadcastRequestForStateTransition`] trait is designed for serializing state transitions +//! into transport requests suitable for broadcasting to Platform. //! -//! This trait is expected to be implemented by objects that encapsulate the necessary data and logic to perform -//! these operations, including the handling of signing operations. +//! This trait is expected to be implemented by objects that encapsulate the necessary data and logic +//! to serialize a state transition and prepare it for transport. use std::fmt::Debug; use dapi_grpc::platform::v0::wait_for_state_transition_result_request::{ @@ -20,67 +20,25 @@ use dpp::state_transition::StateTransition; use crate::error::Error; -/// Trait implemented by objects that can be used to broadcast new identity state transitions. +/// Trait implemented by objects that can be used to create broadcast requests for state transitions. /// /// [`BroadcastRequestForStateTransition`] trait is used when a state transition needs to be broadcasted on Platform. -/// It encapsulates the data, the signing process, and the logic required to perform the broadcast operation. +/// It encapsulates the serialization logic required to convert a state transition into a transport request. /// -/// Implementors of this trait will typically be responsible for creating an identity state transition, -/// signing it with the provided private key and signer, and preparing it for transport to Platform. -/// -/// ## Example -/// -/// To broadcast a new [Identity](dpp::prelude::Identity) state transition, you would typically -/// create an [IdentityCreateTransition](dpp::state_transition::identity_create_transition::IdentityCreateTransition), -/// sign it, and use the `broadcast_new_identity` method provided by this trait: -/// -/// ```rust, ignore -/// -/// use dash_sdk::{Sdk, platform::{BroadcastNewIdentity, IdentityCreateTransition}}; -/// use dpp::identity::signer::Signer; -/// use dpp::prelude::{AssetLockProof, PrivateKey}; -/// use dpp::version::PlatformVersion; -/// -/// let mut sdk = Sdk::new_mock(); -/// let asset_lock_proof = AssetLockProof::new(/* parameters for the asset lock proof */); -/// let private_key = PrivateKey::from(/* private key data */); -/// let signer = /* implementation of Signer trait */; -/// let platform_version = PlatformVersion::latest(); -/// -/// let identity_transition = IdentityCreateTransition::new(/* parameters for the transition */); -/// let result = identity_transition.broadcast_new_identity(asset_lock_proof, private_key, &signer, &platform_version); -/// -/// match result { -/// Ok(transport_request) => { -/// // The transport_request can now be sent to Platform to broadcast the new identity. -/// } -/// Err(e) => { -/// // Handle the error -/// } -/// } -/// ``` +/// Implementors of this trait will typically be responsible for serializing a state transition +/// and preparing it for transport to Platform. /// /// As [`BroadcastRequestForStateTransition`] is a trait, it can be implemented for any type that represents /// a state transition, allowing for flexibility in how state transitions are broadcasted. pub trait BroadcastRequestForStateTransition: Send + Debug + Clone { - /// Converts the current instance into an instance of the `TransportRequest` type, ready for broadcasting. - /// - /// This method takes ownership of the instance upon which it's called (hence `self`), and attempts to perform the conversion, - /// including signing the state transition with the provided private key and signer. - /// - /// # Arguments - /// - /// * `asset_lock_proof` - The proof that locks the asset which is used to create the identity. - /// * `asset_lock_proof_private_key` - The private key associated with the asset lock proof. - /// * `signer` - The signer to be used for signing the state transition. - /// * `platform_version` - The version of Platform for which the state transition is intended. + /// Serializes the state transition into a [`BroadcastStateTransitionRequest`] ready for broadcasting. /// /// # Returns - /// On success, this method yields an instance of the `TransportRequest` type (`T`), which can be used to broadcast the new identity state transition to Platform. + /// On success, this method yields a [`BroadcastStateTransitionRequest`] which can be sent to Platform. /// On failure, it yields an [`Error`]. /// /// # Error Handling - /// This method propagates any errors encountered during the signing or conversion process. + /// This method propagates any errors encountered during serialization. /// These are returned as [`Error`] instances. fn broadcast_request_for_state_transition( &self, diff --git a/packages/rs-sdk/src/platform/transition/transfer.rs b/packages/rs-sdk/src/platform/transition/transfer.rs index 77d385fe928..158f1220de7 100644 --- a/packages/rs-sdk/src/platform/transition/transfer.rs +++ b/packages/rs-sdk/src/platform/transition/transfer.rs @@ -14,17 +14,16 @@ use super::waitable::Waitable; #[async_trait::async_trait] pub trait TransferToIdentity: Waitable { - /// Function to transfer credits from an identity to another identity. Returns the final - /// identity balance. + /// Transfers credits from an identity to another identity. /// - /// If signing_transfer_key_to_use is not set, we will try to use one in the signer that is + /// If `signing_transfer_key_to_use` is not set, we will try to use one in the signer that is /// available for the transfer. /// /// This method will resolve once the state transition is executed. /// /// ## Returns /// - /// Final balance of the identity after the transfer. + /// A tuple of `(sender_balance, receiver_balance)` after the transfer. async fn transfer_credits + Send>( &self, sdk: &Sdk, diff --git a/packages/rs-sdk/src/platform/types/evonode.rs b/packages/rs-sdk/src/platform/types/evonode.rs index bb59b60cdd7..1ccc5553f4f 100644 --- a/packages/rs-sdk/src/platform/types/evonode.rs +++ b/packages/rs-sdk/src/platform/types/evonode.rs @@ -111,7 +111,7 @@ impl TransportRequest for EvoNode { impl From for GetStatusRequest { fn from(_node: EvoNode) -> Self { - // we don't need to send any data to the node, and address is handled in impl TrasportRequest + // we don't need to send any data to the node, and address is handled in impl TransportRequest GetStatusRequestV0 {}.into() } } diff --git a/packages/rs-sdk/src/platform/types/proposed_blocks.rs b/packages/rs-sdk/src/platform/types/proposed_blocks.rs index 2509e74ab9f..74ff71f6520 100644 --- a/packages/rs-sdk/src/platform/types/proposed_blocks.rs +++ b/packages/rs-sdk/src/platform/types/proposed_blocks.rs @@ -22,18 +22,17 @@ pub trait ProposedBlockCountEx { /// Fetches the proposed block counts for proposers within a given range. /// /// This asynchronous method retrieves the number of blocks proposed by various proposers, - /// starting from an optional proposer transaction hash (`ProTxHash`) and returning a limited - /// number of results if specified. If a proposer transaction hash is provided, the query will - /// start at that hash. The optional boolean flag determines whether to include the proposer - /// identified by the `ProTxHash` in the results. + /// optionally filtered to a specific epoch, and returning a limited number of results if + /// specified. If start info is provided, the query will start at that key, and the + /// `start_included` flag determines whether to include the starting proposer in the results. /// /// ## Parameters /// /// * `sdk`: A reference to the `Sdk` instance, which handles the platform interaction. - /// * `limit`: An optional `u16` representing the maximum number of proposer block counts to retrieve. - /// * `start_pro_tx_hash`: An optional tuple where the first element is a `ProTxHash` to start - /// from, and the second element is a boolean indicating whether to include the starting proposer - /// in the results. + /// * `epoch`: An optional [`EpochIndex`] to filter results to a specific epoch. + /// * `limit`: An optional `u32` representing the maximum number of proposer block counts to retrieve. + /// * `start_pro_tx_hash`: An optional [`QueryStartInfo`] specifying + /// the key to start from and whether to include the starting proposer in the results. /// /// ## Returns /// diff --git a/packages/rs-sdk/src/sdk.rs b/packages/rs-sdk/src/sdk.rs index b9332323e00..1f79ef579b7 100644 --- a/packages/rs-sdk/src/sdk.rs +++ b/packages/rs-sdk/src/sdk.rs @@ -229,7 +229,7 @@ fn get_current_time_seconds() -> u64 { } impl Sdk { - /// Initialize Dash Platform SDK in mock mode. + /// Initialize Dash Platform SDK in mock mode. /// /// This is a helper method that uses [`SdkBuilder`] to initialize the SDK in mock mode. /// @@ -596,7 +596,7 @@ impl Sdk { self.cancel_token.cancelled() } - /// Request shutdown of the Sdk and all related operation. + /// Request shutdown of the Sdk and all related operations. pub fn shutdown(&self) { self.cancel_token.cancel(); } @@ -867,7 +867,7 @@ impl SdkBuilder { ) } - /// Create a new SdkBuilder instance preconfigured mainnet (production network). NOT IMPLEMENTED YET. + /// Create a new SdkBuilder instance preconfigured for mainnet (production network). NOT IMPLEMENTED YET. /// /// This is a helper method that preconfigures [SdkBuilder] for production use. /// Use this method if you want to connect to Dash Platform mainnet with production-ready product. @@ -927,7 +927,7 @@ impl SdkBuilder { /// /// Tune request settings used to connect to the Dash Platform. /// - /// Defaults to [RequestSettings::default()]. + /// Defaults to [`DEFAULT_REQUEST_SETTINGS`], which sets retries to 3. /// /// See [`RequestSettings`] for more information. pub fn with_settings(mut self, settings: RequestSettings) -> Self { diff --git a/packages/rs-sdk/src/sync.rs b/packages/rs-sdk/src/sync.rs index 591cfddce98..4cc395df613 100644 --- a/packages/rs-sdk/src/sync.rs +++ b/packages/rs-sdk/src/sync.rs @@ -90,7 +90,7 @@ where unimplemented!("block_on is not supported in wasm"); } -/// Worker function that runs the provided future and sends the result back to the caller using oneshot channel. +/// Worker function that runs the provided future and sends the result back to the caller using mpsc channel. #[cfg(not(target_arch = "wasm32"))] async fn worker( fut: F, @@ -160,7 +160,7 @@ async fn worker( /// ## Troubleshooting /// /// Compiler error: `no method named retry found for closure`: -/// - ensure returned value is [`ExecutionResult`]., +/// - ensure returned value is [`ExecutionResult`]. /// - consider adding `.await` at the end of the closure. pub async fn retry( address_list: &AddressList, From 82d6d1d860d1cb6eb6445acb4dcc60dcc1dd52bc Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Feb 2026 01:28:21 +0000 Subject: [PATCH 06/11] docs(rs-sdk): restore corrected usage example in broadcast_request.rs The previous commit removed an inaccurate example that referenced BroadcastNewIdentity/broadcast_new_identity (a different trait). Restore a corrected example that accurately demonstrates the BroadcastRequestForStateTransition trait and its actual API. https://claude.ai/code/session_01HdTH5NBEVTmxbW63RCkS9J --- .../platform/transition/broadcast_request.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/packages/rs-sdk/src/platform/transition/broadcast_request.rs b/packages/rs-sdk/src/platform/transition/broadcast_request.rs index 35e129aaee6..d7692a161c0 100644 --- a/packages/rs-sdk/src/platform/transition/broadcast_request.rs +++ b/packages/rs-sdk/src/platform/transition/broadcast_request.rs @@ -28,6 +28,23 @@ use crate::error::Error; /// Implementors of this trait will typically be responsible for serializing a state transition /// and preparing it for transport to Platform. /// +/// ## Example +/// +/// Given a [`StateTransition`](dpp::state_transition::StateTransition), you can create a broadcast +/// request using the `broadcast_request_for_state_transition` method: +/// +/// ```rust,ignore +/// use dash_sdk::platform::transition::broadcast_request::BroadcastRequestForStateTransition; +/// use dpp::state_transition::StateTransition; +/// +/// // Assume `state_transition` is an already-constructed and signed StateTransition +/// let broadcast_request = state_transition +/// .broadcast_request_for_state_transition() +/// .expect("failed to serialize state transition"); +/// +/// // The broadcast_request can now be sent to Platform via DAPI. +/// ``` +/// /// As [`BroadcastRequestForStateTransition`] is a trait, it can be implemented for any type that represents /// a state transition, allowing for flexibility in how state transitions are broadcasted. pub trait BroadcastRequestForStateTransition: Send + Debug + Clone { From 48cf56bf0eb0962cc2b601af2875c6ed2dc53370 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Feb 2026 01:31:32 +0000 Subject: [PATCH 07/11] docs(rs-sdk): expand broadcast_request example to show sending via DAPI Add a two-step example showing how to serialize a state transition into a request and then execute it via DAPI. Also point users to the higher-level BroadcastStateTransition trait for the common case with retry logic and proof verification. https://claude.ai/code/session_01HdTH5NBEVTmxbW63RCkS9J --- .../platform/transition/broadcast_request.rs | 27 ++++++++++++++++--- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/packages/rs-sdk/src/platform/transition/broadcast_request.rs b/packages/rs-sdk/src/platform/transition/broadcast_request.rs index d7692a161c0..8c81191c198 100644 --- a/packages/rs-sdk/src/platform/transition/broadcast_request.rs +++ b/packages/rs-sdk/src/platform/transition/broadcast_request.rs @@ -31,18 +31,37 @@ use crate::error::Error; /// ## Example /// /// Given a [`StateTransition`](dpp::state_transition::StateTransition), you can create a broadcast -/// request using the `broadcast_request_for_state_transition` method: +/// request and send it to Platform: /// /// ```rust,ignore /// use dash_sdk::platform::transition::broadcast_request::BroadcastRequestForStateTransition; +/// use rs_dapi_client::DapiRequest; /// use dpp::state_transition::StateTransition; /// -/// // Assume `state_transition` is an already-constructed and signed StateTransition -/// let broadcast_request = state_transition +/// // Assume `sdk` is a connected Sdk instance and +/// // `state_transition` is an already-constructed and signed StateTransition. +/// +/// // Step 1: Serialize the state transition into a transport request +/// let request = state_transition /// .broadcast_request_for_state_transition() /// .expect("failed to serialize state transition"); /// -/// // The broadcast_request can now be sent to Platform via DAPI. +/// // Step 2: Send the request to Platform via DAPI +/// let response = request +/// .execute(&sdk, sdk.dapi_client_settings) +/// .await +/// .expect("broadcast failed"); +/// ``` +/// +/// For most use cases, prefer the higher-level +/// [`BroadcastStateTransition`](super::broadcast::BroadcastStateTransition) trait which wraps +/// this trait with retry logic, error handling, and optional proof verification: +/// +/// ```rust,ignore +/// use dash_sdk::platform::transition::broadcast::BroadcastStateTransition; +/// +/// // Broadcast and wait for Platform to confirm the state transition +/// state_transition.broadcast_and_wait(&sdk, None).await?; /// ``` /// /// As [`BroadcastRequestForStateTransition`] is a trait, it can be implemented for any type that represents From 6ae32f12fb9fe60652cb15d24344dd4173454602 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Feb 2026 01:33:31 +0000 Subject: [PATCH 08/11] docs(rs-sdk): simplify broadcast_request example to use broadcast_and_wait Replace the low-level DAPI example with a concise broadcast_and_wait snippet and link to the BroadcastStateTransition trait docs. https://claude.ai/code/session_01HdTH5NBEVTmxbW63RCkS9J --- .../platform/transition/broadcast_request.rs | 31 +++---------------- 1 file changed, 5 insertions(+), 26 deletions(-) diff --git a/packages/rs-sdk/src/platform/transition/broadcast_request.rs b/packages/rs-sdk/src/platform/transition/broadcast_request.rs index 8c81191c198..ff15f2d50e1 100644 --- a/packages/rs-sdk/src/platform/transition/broadcast_request.rs +++ b/packages/rs-sdk/src/platform/transition/broadcast_request.rs @@ -30,37 +30,16 @@ use crate::error::Error; /// /// ## Example /// -/// Given a [`StateTransition`](dpp::state_transition::StateTransition), you can create a broadcast -/// request and send it to Platform: -/// -/// ```rust,ignore -/// use dash_sdk::platform::transition::broadcast_request::BroadcastRequestForStateTransition; -/// use rs_dapi_client::DapiRequest; -/// use dpp::state_transition::StateTransition; -/// -/// // Assume `sdk` is a connected Sdk instance and -/// // `state_transition` is an already-constructed and signed StateTransition. -/// -/// // Step 1: Serialize the state transition into a transport request -/// let request = state_transition -/// .broadcast_request_for_state_transition() -/// .expect("failed to serialize state transition"); -/// -/// // Step 2: Send the request to Platform via DAPI -/// let response = request -/// .execute(&sdk, sdk.dapi_client_settings) -/// .await -/// .expect("broadcast failed"); -/// ``` -/// -/// For most use cases, prefer the higher-level +/// To broadcast a [`StateTransition`](dpp::state_transition::StateTransition) and wait for +/// Platform to confirm it, use the higher-level /// [`BroadcastStateTransition`](super::broadcast::BroadcastStateTransition) trait which wraps -/// this trait with retry logic, error handling, and optional proof verification: +/// this trait with retry logic, error handling, and proof verification: /// /// ```rust,ignore /// use dash_sdk::platform::transition::broadcast::BroadcastStateTransition; /// -/// // Broadcast and wait for Platform to confirm the state transition +/// // Assume `sdk` is a connected Sdk instance and +/// // `state_transition` is an already-constructed and signed StateTransition. /// state_transition.broadcast_and_wait(&sdk, None).await?; /// ``` /// From a5f4159d5d31e1a73be830665dd0b9fd171c5ac1 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Feb 2026 01:36:07 +0000 Subject: [PATCH 09/11] docs(rs-sdk): fix redundant explicit link in broadcast_request.rs Remove redundant explicit link target for StateTransition that caused a rustdoc warning with -D warnings. https://claude.ai/code/session_01HdTH5NBEVTmxbW63RCkS9J --- packages/rs-sdk/src/platform/transition/broadcast_request.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/rs-sdk/src/platform/transition/broadcast_request.rs b/packages/rs-sdk/src/platform/transition/broadcast_request.rs index ff15f2d50e1..abce2d60314 100644 --- a/packages/rs-sdk/src/platform/transition/broadcast_request.rs +++ b/packages/rs-sdk/src/platform/transition/broadcast_request.rs @@ -30,7 +30,7 @@ use crate::error::Error; /// /// ## Example /// -/// To broadcast a [`StateTransition`](dpp::state_transition::StateTransition) and wait for +/// To broadcast a [`StateTransition`] and wait for /// Platform to confirm it, use the higher-level /// [`BroadcastStateTransition`](super::broadcast::BroadcastStateTransition) trait which wraps /// this trait with retry logic, error handling, and proof verification: From 6a6b9be081e4588e0f5f0ecf8777875cce42142e Mon Sep 17 00:00:00 2001 From: lklimek <842586+lklimek@users.noreply.github.com> Date: Thu, 26 Feb 2026 02:38:22 +0100 Subject: [PATCH 10/11] Update packages/rs-sdk/src/core/dash_core_client.rs --- packages/rs-sdk/src/core/dash_core_client.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/rs-sdk/src/core/dash_core_client.rs b/packages/rs-sdk/src/core/dash_core_client.rs index fe1fdb39f73..a3a94f80783 100644 --- a/packages/rs-sdk/src/core/dash_core_client.rs +++ b/packages/rs-sdk/src/core/dash_core_client.rs @@ -164,7 +164,7 @@ impl LowLevelDashCoreClient { )) } - /// Request list of masternodes from Core. + /// Request list of Platform validators from Core. /// /// See also [Dash Core documentation](https://docs.dash.org/projects/core/en/stable/docs/api/remote-procedure-calls-evo.html#protx-list) #[allow(unused)] From 65b7f6cecd5130e053f54a219965b2eb8370aaf7 Mon Sep 17 00:00:00 2001 From: lklimek <842586+lklimek@users.noreply.github.com> Date: Thu, 26 Feb 2026 02:38:31 +0100 Subject: [PATCH 11/11] Update packages/rs-sdk/src/platform/block_info_from_metadata.rs --- packages/rs-sdk/src/platform/block_info_from_metadata.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/rs-sdk/src/platform/block_info_from_metadata.rs b/packages/rs-sdk/src/platform/block_info_from_metadata.rs index a30f57815b1..bfa2cea5b28 100644 --- a/packages/rs-sdk/src/platform/block_info_from_metadata.rs +++ b/packages/rs-sdk/src/platform/block_info_from_metadata.rs @@ -20,7 +20,7 @@ use drive::error::proof::ProofError; /// - `time_ms`: The timestamp of the block in milliseconds. /// - `height`: The height of the block. /// - `core_height`: The core chain locked height, indicating the height of the block in the core blockchain that is considered final and securely linked to this block. -/// - `epoch`: The epoch number, converted to an `Epoch` struct via a 16-bit index. +/// - `epoch`: The epoch number, converted to an `Epoch` struct via a 16-bit number. /// /// # Errors /// Returns an error if: