Struct Sdk 

pub struct Sdk {
    pub network: Network,
    /* private fields */
}

Dash Platform SDK

This is the main entry point for interacting with Dash Platform. It can be initialized in two modes:

• Normal: Connects to a remote Dash Platform node.
• Mock: Uses a mock implementation of Dash Platform.

Recommended method of initialization is to use SdkBuilder. There are also some helper methods:

• SdkBuilder::new_testnet() Create a SdkBuilder that connects to testnet.
• SdkBuilder::new_mainnet() Create a SdkBuilder that connects to mainnet.
• SdkBuilder::new_mock() Create a mock SdkBuilder.
• Sdk::new_mock() Create a mock Sdk.

Thread safety

Sdk is thread safe and can be shared between threads. It uses internal locking when needed.

It is also safe to clone the Sdk.

Examples

See tests/ for examples of using the SDK.

Fields

network: Network

The network that the sdk is configured for (Dash (mainnet), Testnet, Devnet, Regtest)

Implementations

impl Sdk

pub async fn get_transaction( &self, txid: &str, ) -> Result<Option<FetchedCoreTransaction>, Error>

Fetch a Core transaction by its id via DAPI getTransaction.

txid is the transaction id as a hex string (big-endian display form). Returns Ok(Some(..)) with the decoded transaction plus its confirmation/lock metadata; Ok(None) when the node does not know the tx (empty response or gRPC NOT_FOUND) so the caller can retry with the id byte-reversed; and Err for a transient/transport failure that must not be masked by a doomed reversed-id retry.

pub async fn get_transaction_placement( &self, txid: &str, settings: RequestSettings, ) -> Result<Option<CoreTransactionPlacement>, Error>

Fetch where a Core transaction was mined via DAPI getTransaction, including the block hash the node reports.

Same txid form and Ok(None) / Err contract as Sdk::get_transaction; settings override the SDK’s request settings for this call, so a caller on a deadline can bound it. The placement is unverified — see CoreTransactionPlacement.

pub async fn get_block_by_hash( &self, hash: &BlockHash, settings: RequestSettings, ) -> Result<Option<Block>, Error>

Fetch a Core block by hash via DAPI getBlock.

Returns Ok(None) when the node does not serve the block (gRPC NOT_FOUND or an empty reply) and Err for any other failure, including bytes that do not decode as a block. The bytes are self-reported by the queried node: check block_hash() against a header chain you trust before relying on anything in the block.

pub async fn start_instant_send_lock_stream( &self, from_block_hash: Vec<u8>, address: &Address, ) -> Result<Streaming<TransactionsWithProofsResponse>, Error>

Starts the stream to listen for instant send lock messages

pub async fn wait_for_asset_lock_proof_for_transaction( &self, stream: Streaming<TransactionsWithProofsResponse>, transaction: &Transaction, time_out: Option<Duration>, ) -> Result<AssetLockProof, Error>

Waits for a response for the asset lock proof

impl Sdk

pub async fn sync_address_balances<P: AddressProvider>( &self, provider: &mut P, config: Option<AddressSyncConfig>, last_sync_timestamp: Option<u64>, ) -> Result<AddressSyncResult<P::Tag, P::Address>, Error>

Synchronize address balances using privacy-preserving trunk/branch chunk queries with incremental block-based catch-up.

This method discovers address balances for addresses supplied by the provider, using an iterative query process that fetches chunks of the address tree rather than individual addresses. This provides privacy by making it unclear which specific addresses are being queried.

After the tree scan, incremental catch-up fetches balance changes from the checkpoint height to chain tip so the result is as fresh as possible.

On subsequent calls, pass AddressSyncResult::new_sync_timestamp as last_sync_timestamp so the function can decide whether a full tree rescan is needed or incremental-only catch-up suffices. The provider should implement AddressProvider::last_sync_height (returning the stored AddressSyncResult::new_sync_height) and AddressProvider::current_balances to supply state from the previous sync.

Arguments

• provider: An implementation of AddressProvider that supplies addresses and handles callbacks when addresses are found or proven absent.
• config: Optional configuration; uses defaults if None.
• last_sync_timestamp: Optional block time (Unix seconds) from the previous sync’s AddressSyncResult::new_sync_timestamp. Pass None to always perform a full tree scan.

Returns

• Ok(AddressSyncResult): Contains found addresses with balances/nonces, absent addresses, new_sync_height and new_sync_timestamp to store for the next call.
• Err(Error): If the sync fails after exhausting retries.

Example

use dash_sdk::{Sdk, platform::address_sync::{AddressProvider, AddressSyncConfig}};

// First sync — full tree scan + catch-up (no timestamp)
let result = sdk.sync_address_balances(&mut wallet, None, None).await?;
let saved_height = result.new_sync_height;       // → provider.last_sync_height()
let saved_timestamp = result.new_sync_timestamp;  // → last_sync_timestamp param

// Subsequent sync — incremental only if within threshold
let result = sdk.sync_address_balances(&mut wallet, None, Some(saved_timestamp)).await?;

impl Sdk

pub async fn create_contact_request<F, Fut, G, Gut, H, Hut>( &self, input: ContactRequestInput, ecdh_provider: EcdhProvider<F, Fut, G, Gut>, get_extended_public_key: H, ) -> Result<ContactRequestResult, Error>

where F: FnOnce(&IdentityPublicKey, u32) -> Fut, Fut: Future<Output = Result<SecretKey, Error>>, G: FnOnce(&PublicKey) -> Gut, Gut: Future<Output = Result<[u8; 32], Error>>, H: FnOnce(u32) -> Hut, Hut: Future<Output = Result<Vec<u8>, Error>>,

Create a contact request document

This creates a local contact request document according to DIP-15 specification. The document is not yet submitted to the platform. This method automatically handles ECDH key derivation and encryption of the extended public key and account label.

Arguments

• input - The contact request input containing sender/recipient information and unencrypted data
• ecdh_provider - Provider for ECDH key exchange (client-side or SDK-side)
• get_extended_public_key - Async function to retrieve the extended public key to share with recipient
  • Parameters: (account_reference: u32)
  • Returns: The unencrypted extended public key bytes — the 69-byte DIP-15 compact form (parentFingerprint(4) ‖ chainCode(32) ‖ pubKey(33)), NOT a 78/107-byte BIP32/DIP-14 serialization. A non-69-byte return is rejected before encryption.

Returns

Returns a ContactRequestResult containing the created document

Errors

Returns an error if:

• The DashPay contract cannot be fetched
• The contactRequest document type is not found
• The sender or recipient doesn’t have the required encryption keys
• ECDH encryption fails
• The shared secret, private key, or extended public key cannot be retrieved

pub async fn send_contact_request<S: Signer<IdentityPublicKey>, F, Fut, G, Gut, H, Hut>( &self, input: SendContactRequestInput<S>, ecdh_provider: EcdhProvider<F, Fut, G, Gut>, get_extended_public_key: H, ) -> Result<SendContactRequestResult, Error>

where F: FnOnce(&IdentityPublicKey, u32) -> Fut, Fut: Future<Output = Result<SecretKey, Error>>, G: FnOnce(&PublicKey) -> Gut, Gut: Future<Output = Result<[u8; 32], Error>>, H: FnOnce(u32) -> Hut, Hut: Future<Output = Result<Vec<u8>, Error>>,

Send a contact request to the platform

This creates a contact request document with automatic ECDH encryption and submits it to the platform as a state transition.

Arguments

• input - The send contact request input containing document data, key, and signer
• ecdh_provider - Provider for ECDH key exchange (client-side or SDK-side)
• get_extended_public_key - Async function to retrieve the extended public key to share with recipient
  • Parameters: (account_reference: u32)
  • Returns: The unencrypted extended public key bytes — the 69-byte DIP-15 compact form (parentFingerprint(4) ‖ chainCode(32) ‖ pubKey(33)), NOT a 78/107-byte BIP32/DIP-14 serialization.

Returns

Returns a SendContactRequestResult containing the submitted document

Errors

Returns an error if:

• Document creation fails (including ECDH encryption)
• State transition submission fails

impl Sdk

pub async fn fetch_sent_contact_requests( &self, identity_id: Identifier, after_created_at: Option<u64>, ) -> Result<ContactRequestDocuments, Error>

Fetch contact requests sent by identity_id ($ownerId ==), newer than after_created_at if given, fully paginated.

pub async fn fetch_received_contact_requests( &self, identity_id: Identifier, after_created_at: Option<u64>, ) -> Result<ContactRequestDocuments, Error>

Fetch contact requests received by identity_id (toUserId ==), newer than after_created_at if given, fully paginated.

pub async fn fetch_all_contact_requests_for_identity( &self, identity: &Identity, after_created_at: Option<u64>, ) -> Result<(ContactRequestDocuments, ContactRequestDocuments), Error>

Fetch both sent and received contact requests for an identity, each newer than after_created_at if given.

impl Sdk

pub async fn contest_fund_to_join( &self, document_type: DocumentTypeRef<'_>, document: &Document, ) -> Result<Option<Credits>, Error>

The fund a contested create of document pays to join its contest now, or None when the document joins no contest: the contest’s fund, doubled once the contest holds 250 contenders and again for every 50 more (protocol version 14; before it the fund never doubles).

The contenders are counted with proved contested resource vote state queries of up to 100 contenders each, so a contest of n contenders costs n / 100 + 1 of them. The fund is priced at the protocol version known once they are read, which the first response of an SDK that auto-detects the version brings.

pub async fn prefunded_voting_balance_to_join( &self, document_type: DocumentTypeRef<'_>, document: &Document, ) -> Result<Option<(String, Credits)>, Error>

The prefunded voting balance a create of document states to join its contest now: the name of the contested index the document falls under and Self::contest_fund_to_join, or None when the document joins no contest. It is what a create transition built by hand carries, the pair DocumentCreateTransition keeps as prefunded_voting_balance.

impl Sdk

pub async fn document_create<S: Signer<IdentityPublicKey>>( &self, create_document_transition_builder: DocumentCreateTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<DocumentCreateResult, Error>

Creates a new document on the platform.

This method broadcasts a document creation transition to add a new document to the specified data contract. The result contains the created document. For an indexOnly document type the proof shows the document’s entry at the proof’s block, not that this create wrote it: no stronger proof exists for such a document.

Arguments

• create_document_transition_builder - Builder containing document creation parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a DocumentCreateResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• Document validation fails

impl Sdk

pub async fn document_delete<S: Signer<IdentityPublicKey>>( &self, delete_document_transition_builder: DocumentDeleteTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<DocumentDeleteResult, Error>

Deletes an existing document from the platform.

This method broadcasts a document deletion transition to permanently remove a document from the platform. The result confirms the deletion. For an indexOnly document type the proof shows the document’s entry gone at the proof’s block, not that this delete removed it: no stronger proof exists for such a document.

Arguments

• delete_document_transition_builder - Builder containing document deletion parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a DocumentDeleteResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• Document not found or already deleted
• Insufficient permissions to delete the document

impl Sdk

pub async fn document_purchase<S: Signer<IdentityPublicKey>>( &self, purchase_document_transition_builder: DocumentPurchaseTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<DocumentPurchaseResult, Error>

Purchases a document from its current owner.

This method broadcasts a document purchase transition to buy a document at its set price and transfer ownership to the purchaser. The result contains the purchased document with updated ownership.

Arguments

• purchase_document_transition_builder - Builder containing purchase parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a DocumentPurchaseResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• Document not found or not for sale
• Insufficient funds to complete the purchase
• Price mismatch (document price changed)
• Invalid purchaser identity

impl Sdk

pub async fn document_replace<S: Signer<IdentityPublicKey>>( &self, replace_document_transition_builder: DocumentReplaceTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<DocumentReplaceResult, Error>

Replaces an existing document on the platform.

This method broadcasts a document replacement transition to update an existing document with new data. The result contains the updated document.

Arguments

• replace_document_transition_builder - Builder containing document replacement parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a DocumentReplaceResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• Document validation fails
• Document not found or revision mismatch

impl Sdk

pub async fn document_set_price<S: Signer<IdentityPublicKey>>( &self, set_price_document_transition_builder: DocumentSetPriceTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<DocumentSetPriceResult, Error>

Sets the price for a document on the platform.

This method broadcasts a document price update transition to set or change the price of an existing document. The result contains the updated document.

Arguments

• set_price_document_transition_builder - Builder containing price update parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a DocumentSetPriceResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• Document not found
• Insufficient permissions to set price
• Invalid price value

impl Sdk

pub async fn document_transfer<S: Signer<IdentityPublicKey>>( &self, transfer_document_transition_builder: DocumentTransferTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<DocumentTransferResult, Error>

Transfers ownership of a document to another identity.

This method broadcasts a document transfer transition to change the ownership of an existing document to a new identity. The result contains the transferred document.

Arguments

• transfer_document_transition_builder - Builder containing transfer parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a DocumentTransferResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• Document not found
• Insufficient permissions to transfer the document
• Invalid recipient identity

impl Sdk

pub async fn get_contested_dpns_normalized_usernames( &self, limit: Option<u32>, start_after: Option<String>, ) -> Result<Vec<String>, Error>

Get all contested DPNS usernames

Arguments

• limit - Maximum number of results to return
• start_after - Optional name to start after (for pagination)

Returns

Returns a list of contested DPNS usernames

pub async fn get_contested_dpns_vote_state( &self, label: &str, limit: Option<u32>, ) -> Result<Contenders, Error>

Get the vote state for a contested DPNS username

Arguments

• label - The username label to check (e.g., “alice”)
• limit - Maximum number of contenders to return

Returns

Returns the contenders and their vote counts for the username

pub async fn get_contested_dpns_voters_for_identity( &self, label: &str, contestant_id: Identifier, limit: Option<u32>, ) -> Result<(), Error>

Get voters who voted for a specific identity for a contested DPNS username

Arguments

• label - The username label (e.g., “alice”)
• contestant_id - The identity ID of the contestant
• limit - Maximum number of voters to return

Returns

Returns the list of masternode voters who voted for this contestant

pub async fn get_contested_dpns_identity_votes( &self, identity_id: Identifier, limit: Option<u32>, offset: Option<u16>, ) -> Result<Vec<ContestedDpnsUsername>, Error>

Get all contested DPNS usernames that an identity has voted on

Arguments

• identity_id - The identity ID (typically a masternode ProTxHash)
• limit - Maximum number of votes to return
• offset - Offset for pagination

Returns

Returns the list of contested DPNS usernames this identity has voted on

pub async fn get_contested_dpns_usernames_by_identity( &self, identity_id: Identifier, limit: Option<u32>, ) -> Result<Vec<ContestedDpnsUsername>, Error>

Get all contested DPNS usernames where an identity is a contender

Arguments

• identity_id - The identity ID to search for
• limit - Maximum number of results to return

Returns

Returns the list of contested DPNS usernames where this identity is competing

pub async fn get_contested_non_resolved_usernames( &self, limit: Option<u32>, ) -> Result<BTreeMap<String, ContestInfo>, Error>

Get contested usernames that are not yet resolved

This method fetches all currently contested DPNS usernames that haven’t been resolved yet. It gets current contests and returns the contenders and end time for each unresolved name.

Arguments

• limit - Maximum number of results to return

Returns

Returns a map of contested but unresolved DPNS usernames to their contest info (contenders and end time)

pub async fn get_non_resolved_dpns_contests_for_identity( &self, identity_id: Identifier, limit: Option<u32>, ) -> Result<BTreeMap<String, ContestInfo>, Error>

Get non-resolved DPNS contests for a specific identity

This method fetches all currently contested DPNS usernames that haven’t been resolved yet and filters them to only include contests where the specified identity is a contender.

Arguments

• identity_id - The identity ID to filter contests for
• limit - Maximum number of results to return

Returns

Returns a map of contested but unresolved DPNS usernames (where the identity is a contender) to their contenders

pub async fn get_current_dpns_contests( &self, start_time: Option<TimestampMillis>, end_time: Option<TimestampMillis>, limit: Option<u16>, ) -> Result<BTreeMap<String, TimestampMillis>, Error>

Get current DPNS contests (active vote polls)

This method fetches all currently active DPNS username contests by querying vote polls by their end date. It automatically paginates through all results if there are more than the limit.

Arguments

• start_time - Optional start time to filter contests (in milliseconds)
• end_time - Optional end time to filter contests (in milliseconds)
• limit - Maximum number of results per query (defaults to 100)

Returns

Returns a map of contested DPNS names to their end timestamps

impl Sdk

pub async fn get_dpns_usernames_by_identity( &self, identity_id: Identifier, limit: Option<u32>, ) -> Result<Vec<DpnsUsername>, Error>

Get DPNS usernames owned by a specific identity

This searches for domains where the identity is listed in records.identity. Note: This does not search for domains owned by the identity (no index on $ownerId)

Arguments

• identity_id - The identity ID to search for
• limit - Maximum number of results to return (default: 10)

Returns

Returns a list of DPNS usernames associated with the identity

pub async fn get_all_dpns_usernames_by_identity( &self, identity_id: Identifier, page_limit: u32, max_pages: usize, ) -> Result<(Vec<DpnsUsername>, bool), Error>

Get every DPNS username associated with identity_id, paging through the records.identity index page_limit documents at a time.

Returns the usernames and whether the set is known to be complete: true once a page comes back shorter than page_limit, false when the end was not provably reached (the caller must then treat the result as a lower bound, not the owned set). Documents that do not parse as DPNS domains are skipped, as in Self::get_dpns_usernames_by_identity.

When true can be trusted

Continuing a page relies on startAfter inside the records.identity equality bucket, which only the query lowering introduced with protocol version 14 (non_primary_key_path_query: 1) serves. The earlier lowering drops the rest of the bucket after any cursor, so a second page would come back empty and read as the end. On such a platform version (the one the SDK runs at once the first page has answered) the loop reads only the first page: true then means the identity has fewer than page_limit names, and a full first page returns false. Otherwise false means max_pages full pages were read without reaching the end.

pub async fn check_dpns_name_availability( &self, label: &str, ) -> Result<bool, Error>

Check if a DPNS username is available

Arguments

• label - The username label to check (e.g., “alice”)

Returns

Returns true if the username is available, false if it’s taken

pub async fn resolve_dpns_name_to_identity( &self, name: &str, ) -> Result<Option<Identifier>, Error>

Resolve a DPNS name to an identity ID

Arguments

• name - The full domain name (e.g., “alice.dash”) or just the label (e.g., “alice”)

Returns

Returns the identity ID associated with the domain, or None if not found

pub async fn search_dpns_names( &self, prefix: &str, limit: Option<u32>, ) -> Result<Vec<DpnsUsername>, Error>

Search for DPNS names that start with a given prefix

Arguments

• prefix - The prefix to search for (e.g., “ali” to find “alice”, “alicia”, etc.)
• limit - Maximum number of results to return (default: 10)

Returns

Returns a list of DPNS usernames that match the prefix

impl Sdk

pub async fn register_dpns_name<S: Signer<IdentityPublicKey>>( &self, input: RegisterDpnsNameInput<S>, ) -> Result<RegisterDpnsNameResult, Error>

Register a DPNS username in a single operation

This method handles both the preorder and domain registration steps automatically. It generates the necessary entropy, creates both documents, and submits them in order.

Arguments

• input - The registration input containing label, identity, public key, and signer

Returns

Returns a RegisterDpnsNameResult containing both created documents and the full domain name

Errors

Returns an error if:

• The DPNS contract cannot be fetched
• Document types are not found in the contract
• Document creation or submission fails

pub async fn is_dpns_name_available(&self, name: &str) -> Result<bool, Error>

Check if a DPNS name is available

Arguments

• name - The username label (e.g., “alice”) or full DPNS name (e.g., “alice.dash”). The .dash suffix is matched case-insensitively and stripped before normalization, mirroring Sdk::resolve_dpns_name.

Returns

Returns true if the name is available, false if it’s taken

pub async fn resolve_dpns_name( &self, name: &str, ) -> Result<Option<Identifier>, Error>

Resolve a DPNS name to an identity ID

Arguments

• name - The full domain name (e.g., “alice.dash”) or just the label (e.g., “alice”)

Returns

Returns the identity ID associated with the domain, or None if not found

impl Sdk

pub async fn fetch_seated_charter( &self, target_contract_id: Identifier, ) -> Result<Option<SeatedCharter>, Error>

The seated charter of target_contract_id: the electedCharter whose targetContractId is it, None when the contract has none (no contest awarded yet, or no elected moderation at all).

pub async fn fetch_submitted_charter( &self, submitted_charter_id: Identifier, ) -> Result<Option<Document>, Error>

The submittedCharter (a proposal) with id submitted_charter_id, None when there is none.

pub async fn fetch_elected_charter( &self, elected_charter_id: Identifier, ) -> Result<Option<SeatedCharter>, Error>

The electedCharter with id elected_charter_id, None when there is none. A stored elected charter is always a seated one.

pub async fn fetch_moderation_team( &self, target_contract_id: Identifier, ) -> Result<Option<ModerationTeam>, Error>

The team that moderates target_contract_id: the seated charter’s leader plus its elected members and the members the leader added, less those the leader removed. None when the contract has no seated charter.

pub async fn fetch_submitted_charters( &self, target_contract_id: Identifier, page: CharterDocumentsPage, ) -> Result<Documents, Error>

One page of the proposals (submittedCharter documents) for target_contract_id, in filing order. CharterDocumentsPage::after gives the next page.

pub async fn fetch_join_requests( &self, submitted_charter_id: Identifier, page: CharterDocumentsPage, ) -> Result<Documents, Error>

One page of the join requests for the proposal submitted_charter_id, in the order of their owners’ ids. CharterDocumentsPage::after gives the next page.

pub async fn fetch_pending_resignation_requests( &self, elected_charter_id: Identifier, ) -> Result<Vec<Document>, Error>

The resignation requests for the charter elected_charter_id the leader has not acted on: those whose writer is still on the team (the leader takes an added member off by deleting its addedModerator, and an elected one with a removedModerator). A withdrawn request is deleted, so it is not among them either. Empty when there is no such charter.

impl Sdk

pub async fn build_join_request( &self, input: JoinRequestInput, ) -> Result<ModerationCharterRequest, Error>

Builds a join request for the proposal input.submitted_charter_id: fetches the proposal and its leader, and encrypts the message with the keys the schema demands (see build_join_request_document). The result is put like any document create.

pub async fn build_resignation_request( &self, input: ResignationRequestInput, ) -> Result<ModerationCharterRequest, Error>

Builds a resignation request from the seated charter input.elected_charter_id: fetches the charter and its leader, and encrypts the message with the keys the schema demands (see build_resignation_request_document). The result is put like any document create; deleting the document withdraws the request.

impl Sdk

pub async fn fetch_moderation_charters_contract( &self, ) -> Result<Arc<DataContract>, Error>

The moderation charters system contract: from the context provider when it holds it, fetched otherwise.

The contract exists from protocol version 14. An unpinned SDK starts mainnet and testnet at 13 and only learns a newer version from a verified response, and the contract’s schema does not parse at 13, so below 14 the SDK first learns the network’s version; a network still below 14 has no such contract, which is an error.

impl Sdk

pub async fn fetch_system_data_contract( &self, contract_id: Identifier, ) -> Result<Option<Arc<DataContract>>, Error>

The system data contract contract_id, from the context provider when it holds it at the SDK’s protocol version, fetched and proved otherwise. None when the network has no such contract.

impl Sdk

pub async fn token_burn<S: Signer<IdentityPublicKey>>( &self, burn_tokens_transition_builder: TokenBurnTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<BurnResult, Error>

Burns tokens to permanently remove them from circulation.

This method broadcasts a burn transition to destroy a specified amount of tokens. The result varies based on token configuration:

• Standard tokens return the owner’s remaining balance
• Tokens with history tracking return documents
• Group-managed tokens include group power and action status

Arguments

• burn_tokens_transition_builder - Builder containing burn parameters including amount
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a BurnResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• Insufficient token balance for burning

impl Sdk

pub async fn token_claim<S: Signer<IdentityPublicKey>>( &self, claim_tokens_transition_builder: TokenClaimTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<ClaimResult, Error>

Claims tokens for a specific identity.

This method broadcasts a claim transition to acquire ownership of tokens that have been allocated or made available for claiming. The result includes a document that records the claim details.

Arguments

• claim_tokens_transition_builder - Builder containing claim parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a ClaimResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• A group action result is missing the expected document

impl Sdk

pub async fn token_update_contract_token_configuration<S: Signer<IdentityPublicKey>>( &self, config_update_transition_builder: TokenConfigUpdateTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<ConfigUpdateResult, Error>

Updates the configuration of a token contract.

This method broadcasts a configuration update transition to modify token settings such as minting rules, transfer restrictions, or other contract parameters. The result always includes a document with the updated configuration details.

Arguments

• config_update_transition_builder - Builder containing configuration update parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a ConfigUpdateResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• A group action result is missing the expected document

impl Sdk

pub async fn token_destroy_frozen_funds<S: Signer<IdentityPublicKey>>( &self, destroy_frozen_funds_transition_builder: TokenDestroyFrozenFundsTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<DestroyFrozenFundsResult, Error>

Destroys frozen tokens permanently.

This method broadcasts a destroy frozen funds transition to permanently remove frozen tokens from circulation. This operation always maintains a historical record of the destruction.

Arguments

• destroy_frozen_funds_transition_builder - Builder containing destruction parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a DestroyFrozenFundsResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type

impl Sdk

pub async fn token_purchase<S: Signer<IdentityPublicKey>>( &self, purchase_tokens_transition_builder: TokenDirectPurchaseTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<DirectPurchaseResult, Error>

Purchases tokens directly at the configured price.

This method broadcasts a direct purchase transition to buy tokens at the price set by the token owner. The purchase uses platform credits as payment. The result varies based on token configuration:

• Standard tokens return the purchaser’s new balance
• Tokens with history tracking return documents
• Group-managed tokens include group power information

Arguments

• purchase_tokens_transition_builder - Builder containing purchase parameters including amount
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a DirectPurchaseResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• Insufficient credits for the purchase

impl Sdk

pub async fn token_emergency_action<S: Signer<IdentityPublicKey>>( &self, emergency_action_transition_builder: TokenEmergencyActionTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<EmergencyActionResult, Error>

Executes an emergency action on a token contract.

This method broadcasts an emergency action transition for critical token management operations that require group authorization. Emergency actions are typically used for scenarios like halting trading, recovering from critical bugs, or other urgent interventions.

Arguments

• emergency_action_transition_builder - Builder containing emergency action parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing an EmergencyActionResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type
• The group authorization is insufficient

impl Sdk

pub async fn token_freeze<S: Signer<IdentityPublicKey>>( &self, freeze_tokens_transition_builder: TokenFreezeTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<FreezeResult, Error>

Freezes tokens for a specific identity.

This method broadcasts a freeze transition to temporarily lock tokens, preventing their transfer until they are unfrozen. The result varies based on token configuration:

• Standard tokens return identity info
• Tokens with history tracking return documents
• Group-managed tokens include group power information

Arguments

• freeze_tokens_transition_builder - Builder containing freeze parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a FreezeResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type

impl Sdk

pub async fn token_mint<S: Signer<IdentityPublicKey>>( &self, mint_tokens_transition_builder: TokenMintTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<MintResult, Error>

Mints new tokens according to the token’s configuration.

This method broadcasts a mint transition to create new tokens and allocate them to the specified recipient. The result varies based on token configuration:

• Standard tokens return the recipient’s new balance
• Tokens with history tracking return documents
• Group-managed tokens include group power and action status

Arguments

• mint_tokens_transition_builder - Builder containing mint parameters including amount and recipient
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a MintResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type

impl Sdk

pub async fn token_set_price_for_direct_purchase<S: Signer<IdentityPublicKey>>( &self, set_price_transition_builder: TokenChangeDirectPurchasePriceTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<SetPriceResult, Error>

Sets or updates the pricing schedule for direct token purchases.

This method broadcasts a set price transition to define how tokens can be purchased directly. The pricing schedule can include fixed prices or dynamic pricing rules. The result varies based on token configuration:

• Standard tokens return the pricing schedule
• Tokens with history tracking return documents
• Group-managed tokens include group power and action status

Arguments

• set_price_transition_builder - Builder containing pricing parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a SetPriceResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type

impl Sdk

pub async fn token_transfer<S: Signer<IdentityPublicKey>>( &self, transfer_tokens_transition_builder: TokenTransferTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<TransferResult, Error>

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 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 recipient and amount
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing a TransferResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type

impl Sdk

pub async fn token_unfreeze_identity<S: Signer<IdentityPublicKey>>( &self, unfreeze_tokens_transition_builder: TokenUnfreezeTransitionBuilder, signing_key: &IdentityPublicKey, signer: &S, ) -> Result<UnfreezeResult, Error>

Unfreezes tokens for a specific identity.

This method broadcasts an unfreeze transition to restore transfer capabilities for previously frozen tokens. The result varies based on token configuration:

• Standard tokens return identity info
• Tokens with history tracking return documents
• Group-managed tokens include group power information

Arguments

• unfreeze_tokens_transition_builder - Builder containing unfreeze parameters
• signing_key - The identity public key for signing the transition
• signer - Implementation of the Signer trait for cryptographic signing

Returns

Returns a Result containing an UnfreezeResult on success, or an Error on failure.

Errors

This function will return an error if:

• The transition signing fails
• Broadcasting the transition fails
• The proof verification returns an unexpected result type

impl Sdk

pub fn new_mock() -> Self

Initialize Dash Platform SDK in mock mode.

This is a helper method that uses SdkBuilder to initialize the SDK in mock mode.

See also SdkBuilder.

pub fn verify_response_metadata( &self, method_name: &str, metadata: &ResponseMetadata, ) -> Result<(), Error>

Verify response metadata against the current state of the SDK.

pub async fn refresh_protocol_version(&self) -> Result<u32, Error>

Eagerly teach this SDK the network’s current protocol version and ratchet up to it.

Issues ordinary proven getEpochsInfo queries ([ExtendedEpochInfo::fetch_current]) and discards the epoch payload. The protocol version those queries carry in their verified response metadata is ratcheted in by the same Self::maybe_update_protocol_version path every other query uses — only after proof + quorum-signature verification succeeds. Refresh therefore inherits the exact cryptographic trust of ordinary traffic; it adds no second, weaker source of truth.

On a pinned SDK (SdkBuilder::with_version, version_pinned on) this issues no request and returns the pinned version.

If the fetch fails the failure is non-fatal: whatever version was already learned is kept — we never fall back to an unverified one. Note that [ExtendedEpochInfo::fetch_current] makes more than one round trip, and each verified response ratchets the version on its own. A refresh that ends in an error may therefore still have raised the stored version, and the value returned here reflects that. This is by construction: every ratchet step is proof-verified and upward-only, so a partial refresh can only ever leave the SDK closer to the network’s real version.

On a proofs-disabled SDK (SdkBuilder::with_proofs(false)) this is a no-op that returns the current version: refresh relies on a proven query, so with proofs off there is no trusted source to ratchet from.

Returns the SDK’s protocol version number after the (possible) ratchet.

pub fn context_provider(&self) -> Option<impl ContextProvider>

Return ContextProvider used by the SDK.

pub fn mock(&mut self) -> MutexGuard<'_, MockDashPlatformSdk>

Returns a mutable reference to the MockDashPlatformSdk instance.

Use returned object to configure mock responses with methods like expect_fetch.

Panics

Panics when:

• the self instance is not a Mock variant,
• the self instance is in use by another thread.

pub async fn get_identity_nonce( &self, identity_id: Identifier, bump_first: bool, settings: Option<PutSettings>, ) -> Result<IdentityNonce, Error>

Get or fetch identity nonce, querying Platform when stale or absent. Treats a missing nonce as 0 before applying the optional bump; on first interaction this may return 0 or 1 depending on bump_first. Does not verify identity existence.

pub async fn get_identity_contract_nonce( &self, identity_id: Identifier, contract_id: Identifier, bump_first: bool, settings: Option<PutSettings>, ) -> Result<IdentityNonce, Error>

Get or fetch identity-contract nonce, querying Platform when stale or absent. Treats a missing nonce as 0 before applying the optional bump; on first interaction this may return 0 or 1 depending on bump_first. Does not verify identity or contract existence.

pub async fn refresh_identity_nonce(&self, identity_id: &Identifier)

Marks identity nonce cache entries as stale so they are re-fetched from Platform on the next call to [get_identity_nonce] or [get_identity_contract_nonce].

pub fn version<'v>(&self) -> &'v PlatformVersion

Return Dash Platform version information used by this SDK.

With auto-detection (default) the SDK starts at the per-network min_protocol_version (or the seed set via SdkBuilder::with_initial_version) and then tracks the network’s version — auto-detection only ever ratchets upward (fetch_max). A version pinned via SdkBuilder::with_version() is returned as pinned.

pub fn protocol_version_number(&self) -> u32

Return the raw protocol version number currently used by this SDK.

pub fn prove(&self) -> bool

Indicate if the sdk should request and verify proofs.

pub fn query_settings(&self) -> QuerySettings<'_>

Build a [QuerySettings] borrowing this SDK’s protocol version and prove flag.

Hand the resulting context to crate::platform::Query::query when you need to encode a user-facing query into a wire TransportRequest without taking a full &Sdk dependency through the encoder layer.

pub fn set_context_provider<C: ContextProvider + 'static>( &self, context_provider: C, )

Set the ContextProvider to use.

ContextProvider is used to access state information, like data contracts and quorum public keys.

Note that this will overwrite any previous context provider.

pub fn cancelled(&self) -> WaitForCancellationFuture<'_>

Returns a future that resolves when the Sdk is cancelled (e.g. shutdown was requested).

pub fn shutdown(&self)

Request shutdown of the Sdk and all related operations.

pub fn address_list(&self) -> &AddressList

Return the [DapiClient] address list

pub fn address_ban_info(&self) -> Vec<AddressBanInfo>

Return an owned snapshot of every DAPI address’ ban state, including the reason the address was banned (when recorded).

Delegates to AddressList::ban_info. Useful for diagnostics and surfacing ban state up through the platform-wallet FFI to the iOS example app.

Trait Implementations

impl Clone for Sdk

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl DapiRequestExecutor for Sdk

fn execute<'life0, 'async_trait, R>( &'life0 self, request: R, settings: RequestSettings, ) -> Pin<Box<dyn Future<Output = ExecutionResult<R::Response, DapiClientError>> + Send + 'async_trait>>

where R: 'async_trait + TransportRequest, Self: 'async_trait, 'life0: 'async_trait,

Execute request using this DAPI client.

impl Debug for Sdk

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl IdentityCreateFromShieldedPool for Sdk

fn identity_create_from_shielded_pool_transition( &self, public_keys: Vec<IdentityPublicKeyInCreation>, denomination: u64, send_to_address_on_creation_failure: PlatformAddress, bundle: OrchardBundleParams, ) -> Result<StateTransition, Error>

Build (and structurally validate) the Type-20 transition from PoP-signed keys + bundle params, without broadcasting it.

fn identity_create_from_shielded_pool<'life0, 'async_trait>( &'life0 self, public_keys: Vec<IdentityPublicKeyInCreation>, denomination: u64, send_to_address_on_creation_failure: PlatformAddress, bundle: OrchardBundleParams, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<StateTransitionProofResult, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Create a new identity funded by spending shielded-pool notes.

impl IdentityTopUpFromShieldedPool for Sdk

fn identity_top_up_from_shielded_pool_transition( &self, identity_id: Identifier, top_up_amount: u64, bundle: OrchardBundleParams, ) -> Result<StateTransition, Error>

Build and structure-check the transition without broadcasting it.

fn identity_top_up_from_shielded_pool<'life0, 'async_trait>( &'life0 self, identity_id: Identifier, top_up_amount: u64, bundle: OrchardBundleParams, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<StateTransitionProofResult, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Build, broadcast, and wait for proven execution. Returns the VerifiedIdentityWithShieldedNullifiers proof result (the credited identity and the spent nullifiers), so a wallet only marks notes spent once the top-up is cryptographically proven included.

impl ShieldFromAssetLock for Sdk

fn shield_from_asset_lock<'life0, 'life1, 'async_trait>( &'life0 self, asset_lock_proof: AssetLockProof, asset_lock_proof_private_key: &'life1 [u8], bundle: OrchardBundleParams, value_balance: u64, surplus_output: Option<PlatformAddress>, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Shield funds from an L1 asset lock into the shielded pool. The asset lock proof proves ownership of L1 funds, and the ECDSA signature binds those funds to this specific Orchard bundle.

impl<S: Signer<PlatformAddress>> ShieldFunds<S> for Sdk

fn shield_funds<'life0, 'life1, 'async_trait>( &'life0 self, inputs: BTreeMap<PlatformAddress, Credits>, bundle: OrchardBundleParams, amount: u64, fee_strategy: AddressFundsFeeStrategy, signer: &'life1 S, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Shield funds from platform addresses into the shielded pool. Address nonces are fetched automatically.

fn shield_funds_with_nonce<'life0, 'life1, 'async_trait>( &'life0 self, inputs: BTreeMap<PlatformAddress, (AddressNonce, Credits)>, bundle: OrchardBundleParams, amount: u64, fee_strategy: AddressFundsFeeStrategy, signer: &'life1 S, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Shield funds with explicitly provided address nonces.

impl<S: Signer<PlatformAddress>> TransferAddressFunds<S> for Sdk

fn transfer_address_funds<'life0, 'life1, 'async_trait>( &'life0 self, inputs: BTreeMap<PlatformAddress, Credits>, outputs: BTreeMap<PlatformAddress, Credits>, fee_strategy: AddressFundsFeeStrategy, signer: &'life1 S, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<(AddressInfos, u64), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Broadcast address funds transfer (nonces looked up automatically) and return refreshed balances.

fn transfer_address_funds_with_nonce<'life0, 'life1, 'async_trait>( &'life0 self, inputs: BTreeMap<PlatformAddress, (AddressNonce, Credits)>, outputs: BTreeMap<PlatformAddress, Credits>, fee_strategy: AddressFundsFeeStrategy, signer: &'life1 S, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<(AddressInfos, u64), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Broadcast address funds transfer with explicitly provided address nonces.

impl TransferShielded for Sdk

fn transfer_shielded<'life0, 'async_trait>( &'life0 self, bundle: OrchardBundleParams, value_balance: u64, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Transfer funds within the shielded pool. Authentication is via Orchard spend authorization signatures in the bundle actions.

impl UnshieldFunds for Sdk

fn unshield_funds<'life0, 'async_trait>( &'life0 self, output_address: PlatformAddress, unshielding_amount: u64, bundle: OrchardBundleParams, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Unshield funds from the shielded pool to a platform address. Authentication is via Orchard spend authorization signatures in the bundle actions.

impl<S: Signer<PlatformAddress>> WithdrawAddressFunds<S> for Sdk

fn withdraw_address_funds<'life0, 'life1, 'async_trait>( &'life0 self, inputs: BTreeMap<PlatformAddress, Credits>, change_output: Option<(PlatformAddress, Credits)>, fee_strategy: AddressFundsFeeStrategy, core_fee_per_byte: u32, pooling: Pooling, output_script: CoreScript, signer: &'life1 S, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<(AddressInfos, u64), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Withdraws address balances (nonces fetched automatically).

fn withdraw_address_funds_with_nonce<'life0, 'life1, 'async_trait>( &'life0 self, inputs: BTreeMap<PlatformAddress, (AddressNonce, Credits)>, change_output: Option<(PlatformAddress, Credits)>, fee_strategy: AddressFundsFeeStrategy, core_fee_per_byte: u32, pooling: Pooling, output_script: CoreScript, signer: &'life1 S, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<(AddressInfos, u64), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Withdraws address balances with explicitly provided nonces.

impl WithdrawShielded for Sdk

fn withdraw_shielded<'life0, 'async_trait>( &'life0 self, unshielding_amount: u64, bundle: OrchardBundleParams, core_fee_per_byte: u32, pooling: Pooling, output_script: CoreScript, settings: Option<PutSettings>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Withdraw funds from the shielded pool to a Core address. Authentication is via Orchard spend authorization signatures in the bundle actions.