From b434a76c91981440f3a421609f4093a3c7fff01a Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 10 Oct 2024 10:53:56 -0400 Subject: [PATCH] docs: update tutorials for v1.4 (#82) * docs: update tutorials to continue connecting to testnet Platform v1.4 SDK will connect to mainnet by default instead of testnet so the network option has been set to continue using testnet * docs: add credit withdraw tutorial * chore: rename file and add tutorial to sidebar * chore: small updates --- _templates/sidebar-main.html | 10 +++ docs/tutorials/connecting-to-testnet.md | 3 +- .../retrieve-a-data-contract.md | 2 +- docs/tutorials/identities-and-names.md | 1 + .../withdraw-an-identity-balance.md | 70 +++++++++++++++++++ docs/tutorials/setup-sdk-client.md | 5 +- 6 files changed, 87 insertions(+), 4 deletions(-) create mode 100644 docs/tutorials/identities-and-names/withdraw-an-identity-balance.md diff --git a/_templates/sidebar-main.html b/_templates/sidebar-main.html index 05c9724ee..6589b81f3 100644 --- a/_templates/sidebar-main.html +++ b/_templates/sidebar-main.html @@ -49,6 +49,11 @@ identity’s balance +
  • Withdraw an + identity's balance +
    • +
  • Update an identity @@ -59,6 +64,11 @@ an account’s identities
    • +
  • Transfer to + an identity +
    • +
  • Register a name for an diff --git a/docs/tutorials/connecting-to-testnet.md b/docs/tutorials/connecting-to-testnet.md index 6c4fac112..14065a24f 100644 --- a/docs/tutorials/connecting-to-testnet.md +++ b/docs/tutorials/connecting-to-testnet.md @@ -27,7 +27,8 @@ npm install dash ### 2. Connect to Dash Platform :::{tip} -The JavaScript Dash SDK connects to testnet by default. Mainnet can only be accessed by [connecting via address](#connect-via-address). +The JavaScript Dash SDK connects to mainnet by default. To connect to other networks, +set the `network` option when instantiating the client as shown in the following example. ::: Create a file named `dashConnect.js` with the following contents. Then run it by typing `node dashConnect.js` from the command line: diff --git a/docs/tutorials/contracts-and-documents/retrieve-a-data-contract.md b/docs/tutorials/contracts-and-documents/retrieve-a-data-contract.md index 2cbbbb8d3..4ca0f9918 100644 --- a/docs/tutorials/contracts-and-documents/retrieve-a-data-contract.md +++ b/docs/tutorials/contracts-and-documents/retrieve-a-data-contract.md @@ -43,7 +43,7 @@ const Dash = require('dash'); const { PlatformProtocol: { Identifier } } = Dash; const myContractId = 'a contract ID'; -const client = new Dash.Client(); +const client = new Dash.Client({ network: 'testnet' }); client.platform.contracts.get(myContractId) .then((myContract) => { diff --git a/docs/tutorials/identities-and-names.md b/docs/tutorials/identities-and-names.md index 5c63252cd..c77eef381 100644 --- a/docs/tutorials/identities-and-names.md +++ b/docs/tutorials/identities-and-names.md @@ -13,6 +13,7 @@ The following tutorials cover creating and managing identities as well as creati identities-and-names/register-an-identity identities-and-names/retrieve-an-identity identities-and-names/topup-an-identity-balance +identities-and-names/withdraw-an-identity-balance identities-and-names/update-an-identity identities-and-names/retrieve-an-accounts-identities identities-and-names/transfer-credits-to-an-identity diff --git a/docs/tutorials/identities-and-names/withdraw-an-identity-balance.md b/docs/tutorials/identities-and-names/withdraw-an-identity-balance.md new file mode 100644 index 000000000..0758666b2 --- /dev/null +++ b/docs/tutorials/identities-and-names/withdraw-an-identity-balance.md @@ -0,0 +1,70 @@ +```{eval-rst} +.. tutorials-withdraw-identity-balance: +``` + +:::{attention} +Mainnet withdrawals will not be available until the activation of Dash Platform v1.4 on mainnet in late October or early November. They are already available on testnet. +::: + +# Withdraw an Identity's balance + +The purpose of this tutorial is to walk through the steps necessary to withdraw part of their identity's balance from Platform to a Dash address. + +## Overview + +Over time, users may want to convert some of their identity's [Platform credits](../../explanations/identity.md#credits) back to Dash for use on the Core chain. + +## Prerequisites + +- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed) +- A wallet mnemonic with some funds in it: [Tutorial: Create and Fund a Wallet](../../tutorials/create-and-fund-a-wallet.md) +- A configured client: [Setup SDK Client](../setup-sdk-client.md) +- A Dash Platform Identity with a credit balance: [Tutorial: Register an Identity](../../tutorials/identities-and-names/register-an-identity.md) +- A Core chain address to receive the withdrawn credits as Dash + +## Code + +```javascript +const setupDashClient = require('../setupDashClient'); + +const client = setupDashClient(); + +const withdrawCredits = async () => { + const identityId = 'an identity ID goes here'; + const identity = await client.platform.identities.get(identityId); + + console.log('Identity balance before transfer: ', identity.balance); + + const toAddress = 'a Dash address goes here'; + const amount = 1000000; // Number of credits to withdraw + const amountDash = amount / (1000 * 100000000); + + console.log(`Withdrawing ${amount} credits (${amountDash} DASH)`); + // Temporarily force minRelay to have a value so withdrawal succeeds + // https://github.com/dashpay/platform/issues/2233 + client.wallet.storage.getDefaultChainStore().state.fees.minRelay = 1000; + + const response = await client.platform.identities.withdrawCredits( + identity, + amount, + { + toAddress, + }, + ); + return client.platform.identities.get(identityId); +}; + +withdrawCredits() + .then((d) => console.log('Identity balance after withdrawal: ', d.balance)) + .catch((e) => console.error('Something went wrong:\n', e)) + .finally(() => client.disconnect()); +``` + +## What's Happening + +After connecting to the Client, we get an identity and set the withdrawal address and amount. We then call `platform.identities.withdrawCredits` with the identity, withdrawal amount in credits, and the destination address. This creates an unlock transaction and decreases the identity's credit balance by the relevant amount including a fee. The updated identity balance is output to the console. Once the withdrawal is processed, it is broadcast to the Core chain where the unlocked Dash is sent to the provided destination address. + +:::{note} +:class: note +Since the SDK does not cache wallet information, lengthy re-syncs (5+ minutes) may be required for some Core chain wallet operations. See [Wallet Operations](../setup-sdk-client.md#wallet-operations) for options. +::: diff --git a/docs/tutorials/setup-sdk-client.md b/docs/tutorials/setup-sdk-client.md index 045d7be55..189d7f21d 100644 --- a/docs/tutorials/setup-sdk-client.md +++ b/docs/tutorials/setup-sdk-client.md @@ -18,7 +18,8 @@ In this tutorial we will show how to configure the client for use in the remaini ## Code :::{tip} -The JavaScript Dash SDK connects to testnet by default. Mainnet can only be accessed by [connecting via address](./connecting-to-testnet.md#connect-to-a-network). +The JavaScript Dash SDK connects to mainnet by default. To connect to other networks, +set the `network` option when instantiating the client as shown in the following example. ::: Save the following client configuration module in a file named `setupDashClient.js`. This module @@ -30,7 +31,7 @@ will be re-used in later tutorials. // Fully configured client options const clientOptions = { - // The network to connect to ('testnet' or 'local') + // The network to connect to ('mainnet', 'testnet' or 'local') network: 'testnet', // Wallet configuration for transactions and account management