From 9313ab969139a0278c3d6de3d5dfd4e0c28af03f Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 3 Jul 2024 16:35:29 -0400 Subject: [PATCH 1/7] docs: rust sdk basics --- docs/index.md | 9 +++ docs/sdk-rs/quick-start.md | 147 +++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 docs/sdk-rs/quick-start.md diff --git a/docs/index.md b/docs/index.md index ff087078b..e135a2f8e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -202,3 +202,12 @@ dapi-client-js/overview dapi-client-js/quick-start dapi-client-js/usage/usage ``` + +```{toctree} +:maxdepth: 2 +:titlesonly: +:caption: Rust SDK +:hidden: + +sdk-rs/quick-start +``` diff --git a/docs/sdk-rs/quick-start.md b/docs/sdk-rs/quick-start.md new file mode 100644 index 000000000..610ce4362 --- /dev/null +++ b/docs/sdk-rs/quick-start.md @@ -0,0 +1,147 @@ +# Quick Start + +## Install dependencies + +Several packages are required to use the Dash SDK. Install them by running: + +```shell +# Install required packages +sudo apt-get install clang cmake gcc unzip +# Install recent protobuf version +wget https://github.com/protocolbuffers/protobuf/releases/download/v26.1/protoc-26.1-linux-x86_64.zip +sudo unzip protoc-*-linux-x86_64.zip -d /usr/local +``` + +## Install Rustup + +Rustup is the [recommended tool](https://www.rust-lang.org/tools/install) to install Rust and keep it updated. To download Rustup and install +Rust, run the following in your terminal, then follow the on-screen instructions: + +```shell +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +After installation, ensure that your system's environment variables are updated. Restart your +terminal or run: + +```shell +. "$HOME/.cargo/env" +``` + +Check if Rust is installed correctly by running: + +```shell +rustc --version +``` + +You should see the installed version of Rust. + +## Create a new project + +Rust comes with a build tool and package manager called Cargo. Use it to create a new project by +running the following command in your terminal. Replacing `dash_project` with your desired project +name: + +```shell +cargo new dash_project +``` + +Change into your new project's directory: + +```shell +cd dash_project +``` + +Add the following dependencies to `Cargo.toml`: + +``` toml +[dependencies] +dash-sdk = { git = "https://github.com/dashpay/platform" } +tokio = { version = "1", features = ["full"] } +dapi-grpc = { git = "https://github.com/dashpay/platform", features = ["client",] } +rs-dapi-client = { git = "https://github.com/dashpay/platform" } +dpp = { git = "https://github.com/dashpay/platform", features = ["client",] } +``` + +Open `src/main.rs` and replace its contents with this code: + +```rust +use dapi_grpc::platform::v0::{ + get_identity_request::GetIdentityRequestV0, get_identity_response::GetIdentityResponseV0, + get_identity_response::Version as GetIdentityResponseVersion, GetIdentityRequest, + GetIdentityResponse, ResponseMetadata, +}; +use dash_sdk::platform::Identifier; +use dash_sdk::{Sdk, SdkBuilder}; +use dpp::platform_value::string_encoding::Encoding; +use rs_dapi_client::{DapiRequest, Uri}; +use std::error::Error; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let sdk = SdkBuilder::new(rs_dapi_client::AddressList::from_iter([ + "https://52.42.202.128:1443".parse::()?, + ])) + .build() + .expect("Failed to build SDK"); + + let identity_id = Identifier::from_string( + "2rEwrPmMBqdYzFwtofrPd8RtMCotcKFxRoATkqqQeW7P", + Encoding::Base58, + )?; + + let result = fetch_identity(identity_id, &sdk).await; + match result { + Ok(_) => println!("Identity fetched successfully."), + Err(e) => eprintln!("Error fetching identity: {:?}", e), + } + + Ok(()) +} + +async fn fetch_identity(identity_id: Identifier, sdk: &Sdk) -> Result<(), Box> { + let request = GetIdentityRequest { + version: Some(dapi_grpc::platform::v0::get_identity_request::Version::V0( + GetIdentityRequestV0 { + id: identity_id.to_vec(), + prove: false, + }, + )), + }; + + let identity_response = request + .execute(sdk, rs_dapi_client::RequestSettings::default()) + .await; + println!("Identity fetch result: {:?}", identity_response); + + match identity_response { + Ok(GetIdentityResponse { + version: Some(GetIdentityResponseVersion::V0(GetIdentityResponseV0 { + result: Some(dapi_grpc::platform::v0::get_identity_response::get_identity_response_v0::Result::Identity(bytes)), + metadata: Some(ResponseMetadata { protocol_version, .. }) + })), + }) => { + println!("Identity bytes: {:?}", bytes); + println!("Protocol version: {}", protocol_version); + }, + _ => eprintln!("No identity was received"), + } + + Ok(()) +} +``` + +Build and run the project: + +```shell +cargo run +``` + +You should see output similar to: + +``` +Identity fetch result: Ok(GetIdentityResponse { version: Some(V0(GetIdentityResponseV0 { metadata: Some(ResponseMetadata { height: 3545, core_chain_locked_height: 1057533, epoch: 194, time_ms: 1720037818812, protocol_version: 1, chain_id: "dash-testnet-46" }), result: Some(Identity([0, 27, 120, 234, 64, 77, 128, 39, 95, 97, 84, 3, 190, 94, 195, 152, 119, 222, 62, 61, 205, 74, 127, 72, 225, 59, 150, 72, 50, 141, 143, 28, 62, 5, 0, 0, 0, 0, 0, 0, 0, 0, 33, 3, 245, 177, 206, 91, 24, 183, 208, 204, 116, 210, 242, 219, 243, 121, 210, 10, 68, 97, 215, 187, 132, 58, 19, 181, 158, 50, 100, 15, 176, 234, 25, 217, 0, 1, 0, 1, 0, 2, 0, 0, 0, 33, 2, 104, 172, 93, 255, 84, 19, 139, 70, 252, 113, 120, 50, 176, 83, 194, 52, 126, 43, 96, 84, 254, 37, 130, 85, 104, 52, 185, 24, 91, 113, 235, 178, 0, 2, 0, 2, 0, 1, 0, 0, 0, 33, 3, 249, 77, 70, 255, 0, 223, 110, 197, 2, 109, 8, 113, 134, 141, 168, 174, 23, 211, 232, 222, 88, 59, 226, 189, 73, 43, 85, 11, 157, 27, 65, 199, 0, 3, 0, 3, 3, 1, 0, 0, 0, 33, 2, 244, 30, 16, 91, 151, 102, 49, 150, 212, 147, 93, 14, 112, 139, 176, 68, 241, 49, 95, 207, 238, 146, 176, 115, 53, 108, 7, 228, 237, 103, 13, 227, 0, 4, 0, 4, 0, 3, 0, 0, 0, 33, 3, 178, 111, 125, 30, 123, 61, 172, 86, 142, 6, 184, 161, 236, 83, 52, 10, 100, 169, 210, 150, 84, 61, 164, 190, 201, 62, 104, 218, 191, 7, 118, 57, 1, 253, 0, 0, 1, 144, 85, 175, 57, 216, 252, 55, 149, 47, 218, 2])) })) }) +Identity bytes: [0, 27, 120, 234, 64, 77, 128, 39, 95, 97, 84, 3, 190, 94, 195, 152, 119, 222, 62, 61, 205, 74, 127, 72, 225, 59, 150, 72, 50, 141, 143, 28, 62, 5, 0, 0, 0, 0, 0, 0, 0, 0, 33, 3, 245, 177, 206, 91, 24, 183, 208, 204, 116, 210, 242, 219, 243, 121, 210, 10, 68, 97, 215, 187, 132, 58, 19, 181, 158, 50, 100, 15, 176, 234, 25, 217, 0, 1, 0, 1, 0, 2, 0, 0, 0, 33, 2, 104, 172, 93, 255, 84, 19, 139, 70, 252, 113, 120, 50, 176, 83, 194, 52, 126, 43, 96, 84, 254, 37, 130, 85, 104, 52, 185, 24, 91, 113, 235, 178, 0, 2, 0, 2, 0, 1, 0, 0, 0, 33, 3, 249, 77, 70, 255, 0, 223, 110, 197, 2, 109, 8, 113, 134, 141, 168, 174, 23, 211, 232, 222, 88, 59, 226, 189, 73, 43, 85, 11, 157, 27, 65, 199, 0, 3, 0, 3, 3, 1, 0, 0, 0, 33, 2, 244, 30, 16, 91, 151, 102, 49, 150, 212, 147, 93, 14, 112, 139, 176, 68, 241, 49, 95, 207, 238, 146, 176, 115, 53, 108, 7, 228, 237, 103, 13, 227, 0, 4, 0, 4, 0, 3, 0, 0, 0, 33, 3, 178, 111, 125, 30, 123, 61, 172, 86, 142, 6, 184, 161, 236, 83, 52, 10, 100, 169, 210, 150, 84, 61, 164, 190, 201, 62, 104, 218, 191, 7, 118, 57, 1, 253, 0, 0, 1, 144, 85, 175, 57, 216, 252, 55, 149, 47, 218, 2] +Protocol version: 1 +Identity fetched successfully. +``` From 6df71b9a95393e185b17565a100b53e881ccb3ec Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 3 Jul 2024 17:24:42 -0400 Subject: [PATCH 2/7] docs: add link and warning about sdk docs --- docs/sdk-rs/quick-start.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/sdk-rs/quick-start.md b/docs/sdk-rs/quick-start.md index 610ce4362..4cc786fea 100644 --- a/docs/sdk-rs/quick-start.md +++ b/docs/sdk-rs/quick-start.md @@ -145,3 +145,9 @@ Identity bytes: [0, 27, 120, 234, 64, 77, 128, 39, 95, 97, 84, 3, 190, 94, 195, Protocol version: 1 Identity fetched successfully. ``` + +## SDK documentation + +> 🚧 Work in progress +> +> SDK documentation will be available on docs.rs once the Dash SDK crate is published. Meanwhile, the [pre-release documentation](https://dashpay.github.io/docs-platform/dash_sdk/) is available for reference. Please keep in mind that it is incomplete and may be outdated. From 6b7a2d3363036cc558c470ea1ea20a27e6b99290 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 4 Jul 2024 15:56:09 -0400 Subject: [PATCH 3/7] docs: update to add sdk example and split out dapi client example include Core install instructions --- docs/sdk-rs/quick-start.md | 121 +++++++++++++++++++++++++++++++++++-- 1 file changed, 117 insertions(+), 4 deletions(-) diff --git a/docs/sdk-rs/quick-start.md b/docs/sdk-rs/quick-start.md index 4cc786fea..5f1b3f79f 100644 --- a/docs/sdk-rs/quick-start.md +++ b/docs/sdk-rs/quick-start.md @@ -1,6 +1,8 @@ # Quick Start -## Install dependencies +## Prerequisites + +### Install dependencies Several packages are required to use the Dash SDK. Install them by running: @@ -12,7 +14,7 @@ wget https://github.com/protocolbuffers/protobuf/releases/download/v26.1/protoc- sudo unzip protoc-*-linux-x86_64.zip -d /usr/local ``` -## Install Rustup +### Install Rustup Rustup is the [recommended tool](https://www.rust-lang.org/tools/install) to install Rust and keep it updated. To download Rustup and install Rust, run the following in your terminal, then follow the on-screen instructions: @@ -36,6 +38,39 @@ rustc --version You should see the installed version of Rust. +### Install Dash Core + +Currently, the SDK is dependent on a Dash Core full node to support proof verification and provide +wallet access. Follow the instructions below to install Dash Core and run it on Testnet. **Note:** +it is possible, although not recommended, to retrieve data from Dash Platform without proof + +- [Dash Core installation instructions](inv:user:std#dashcore-installation) +- [Running Dash Core on Testnet](inv:user:std#dashcore-testnet) + +Located the `dash.conf` file by right-clicking the Dash Core icon and selecting `Open Wallet Configuration File`. Configure it as shown below (replace `***` with a username and password of your choice): + +```ini +testnet=1 + +[test] +server=1 +listen=1 +rpcallowip=127.0.0.1 +rpcuser=*** +rpcpassword=*** +``` + +Restart Dash Core to apply the changes. + +> 🚧 **Using Dash Platform without Dash Core** +> +> The Rust SDK requests proofs for all data retrieved from Platform. This makes it the recommended +> (most secure) option, but also is why a Dash Core full node is currently required. +> +> The [JavaScript SDK](../tutorials/introduction.md) provides access to Dash Platform without +> requiring a full node; however, it **_does not support Dash Platform's proofs_**. The Rust DAPI +> client can also perform read operations without a full node if proofs are not requested. See the [DAPI client example](#dapi-client-example) below for details. + ## Create a new project Rust comes with a build tool and package manager called Cargo. Use it to create a new project by @@ -63,7 +98,85 @@ rs-dapi-client = { git = "https://github.com/dashpay/platform" } dpp = { git = "https://github.com/dashpay/platform", features = ["client",] } ``` -Open `src/main.rs` and replace its contents with this code: +Open `src/main.rs` and replace the contents with this code: + +```rust +use dash_sdk::{ + platform::{Fetch, Identifier}, + Sdk, SdkBuilder, +}; +use dpp::{ + identity::accessors::IdentityGettersV0, platform_value::string_encoding::Encoding, + prelude::Identity, +}; +use rs_dapi_client::{AddressList, Uri}; +use std::error::Error; + +pub fn setup_sdk() -> Result> { + let dapi_addresses = "https://52.42.202.128:1443"; + let sdk = SdkBuilder::new(AddressList::from_iter([dapi_addresses.parse::()?])) + .with_core("127.0.0.1", 19998, "user", "pass") + .build() + .expect("Failed to build SDK"); + + Ok(sdk) +} + +#[tokio::main] +async fn main() -> Result<(), Box> { + let sdk = setup_sdk()?; + + let identity_id = Identifier::from_string( + "2rEwrPmMBqdYzFwtofrPd8RtMCotcKFxRoATkqqQeW7P", + Encoding::Base58, + )?; + + match Identity::fetch(&sdk, identity_id).await { + Ok(Some(identity)) => { + println!("Identity id: {}", identity.id()); + println!("Identity balance: {}", identity.balance()); + } + Ok(None) => { + eprintln!("Identity not found: {}", identity_id); + } + Err(e) => { + eprintln!("Error fetching data from Platform: {}", e); + } + } + + Ok(()) +} +``` + +Build and run the project: + +```shell +cargo run +``` + +You should see output similar to: + +```text +Identity id: 2rEwrPmMBqdYzFwtofrPd8RtMCotcKFxRoATkqqQeW7P +Identity balance: 932523994 +``` + +## DAPI client example + +This example demonstrates how to retrieve an identity from Dash Platform using the Rust DAPI client. It does not request or check proofs for the retrieved data, but it does not require a connection to a Dash Core full node. + +Add the following dependencies to `Cargo.toml`: + +``` toml +[dependencies] +dash-sdk = { git = "https://github.com/dashpay/platform" } +tokio = { version = "1", features = ["full"] } +dapi-grpc = { git = "https://github.com/dashpay/platform", features = ["client",] } +rs-dapi-client = { git = "https://github.com/dashpay/platform" } +dpp = { git = "https://github.com/dashpay/platform", features = ["client",] } +``` + +Open `src/main.rs` and replace the contents with this code: ```rust use dapi_grpc::platform::v0::{ @@ -104,7 +217,7 @@ async fn fetch_identity(identity_id: Identifier, sdk: &Sdk) -> Result<(), Box Date: Mon, 8 Jul 2024 10:49:40 -0400 Subject: [PATCH 4/7] docs: add overview and update warning location --- docs/index.md | 15 ++++++++------- docs/sdk-rs/overview.md | 33 +++++++++++++++++++++++++++++++++ docs/sdk-rs/quick-start.md | 12 ++++++------ 3 files changed, 47 insertions(+), 13 deletions(-) create mode 100644 docs/sdk-rs/overview.md diff --git a/docs/index.md b/docs/index.md index e135a2f8e..1e8c62b4d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -181,7 +181,7 @@ Previous Version of Docs 🚧 Work in progress +> +> SDK documentation will be available on docs.rs once the Dash SDK crate is published. Meanwhile, the [pre-release documentation](https://dashpay.github.io/docs-platform/dash_sdk/) is available for reference. Please keep in mind that it is incomplete and may be outdated. + +### Mocking + +Dash Platform SDK supports mocking with `mocks` feature which provides a +convenient way to define mock expectations and use the SDK without actual +connection to the Platform. + +You can see examples of mocking in [mock_fetch.rs](https://github.com/dashpay/platform/blob/v1.0-dev/packages/rs-sdk/tests/fetch/mock_fetch.rs) and [mock_fetch_many.rs](https://github.com/dashpay/platform/blob/v1.0-dev/packages/rs-sdk/tests/fetch/mock_fetch_many.rs). diff --git a/docs/sdk-rs/quick-start.md b/docs/sdk-rs/quick-start.md index 5f1b3f79f..e5e097e3c 100644 --- a/docs/sdk-rs/quick-start.md +++ b/docs/sdk-rs/quick-start.md @@ -161,6 +161,12 @@ Identity id: 2rEwrPmMBqdYzFwtofrPd8RtMCotcKFxRoATkqqQeW7P Identity balance: 932523994 ``` +## SDK documentation + +> 🚧 Work in progress +> +> SDK documentation will be available on docs.rs once the Dash SDK crate is published. Meanwhile, the [pre-release documentation](https://dashpay.github.io/docs-platform/dash_sdk/) is available for reference. Please keep in mind that it is incomplete and may be outdated. + ## DAPI client example This example demonstrates how to retrieve an identity from Dash Platform using the Rust DAPI client. It does not request or check proofs for the retrieved data, but it does not require a connection to a Dash Core full node. @@ -258,9 +264,3 @@ Identity bytes: [0, 27, 120, 234, 64, 77, 128, 39, 95, 97, 84, 3, 190, 94, 195, Protocol version: 1 Identity fetched successfully. ``` - -## SDK documentation - -> 🚧 Work in progress -> -> SDK documentation will be available on docs.rs once the Dash SDK crate is published. Meanwhile, the [pre-release documentation](https://dashpay.github.io/docs-platform/dash_sdk/) is available for reference. Please keep in mind that it is incomplete and may be outdated. From ddd2d0ca4f77a82c43e0ee5a6acf83b2790198a4 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 8 Jul 2024 11:03:04 -0400 Subject: [PATCH 5/7] docs: minor corrections --- docs/sdk-rs/quick-start.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sdk-rs/quick-start.md b/docs/sdk-rs/quick-start.md index e5e097e3c..22896595e 100644 --- a/docs/sdk-rs/quick-start.md +++ b/docs/sdk-rs/quick-start.md @@ -47,7 +47,7 @@ it is possible, although not recommended, to retrieve data from Dash Platform wi - [Dash Core installation instructions](inv:user:std#dashcore-installation) - [Running Dash Core on Testnet](inv:user:std#dashcore-testnet) -Located the `dash.conf` file by right-clicking the Dash Core icon and selecting `Open Wallet Configuration File`. Configure it as shown below (replace `***` with a username and password of your choice): +Locate the `dash.conf` file by right-clicking the Dash Core icon and selecting `Open Wallet Configuration File`. Configure it as shown below (replace `` and `` with values of your choice): ```ini testnet=1 @@ -56,8 +56,8 @@ testnet=1 server=1 listen=1 rpcallowip=127.0.0.1 -rpcuser=*** -rpcpassword=*** +rpcuser= +rpcpassword= ``` Restart Dash Core to apply the changes. From ecf7bb68f9a58d6c211e8f91bf350fe6146dceee Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 8 Jul 2024 11:12:20 -0400 Subject: [PATCH 6/7] docs: sidebar update --- _templates/sidebar-main.html | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/_templates/sidebar-main.html b/_templates/sidebar-main.html index cb06cb809..e813c017e 100644 --- a/_templates/sidebar-main.html +++ b/_templates/sidebar-main.html @@ -266,7 +266,7 @@
  • Previous Version of Docs
    • -

    Dash SDK

    +

    JavaScript SDK

    +

    Rust SDK

    +

    DAPI Client