docs(tutorials): add token lifecycle tutorials

_templates/sidebar-main.html

@@ -163,6 +163,46 @@
        </ul>
       </details>
      </li>
+     <li class="toctree-l1 has-children">
+      <a class="reference internal" href="docs/tutorials/tokens.html">
+       Tokens
+      </a>
+      <details>
+       <summary>
+        <span class="toctree-toggle" role="presentation">
+         <i class="fa-solid fa-chevron-down">
+         </i>
+        </span>
+       </summary>
+       <ul>
+        <li class="toctree-l2">
+         <a class="reference internal" href="docs/tutorials/tokens/register-a-token-contract.html">
+          Register a token contract
+         </a>
+        </li>
+        <li class="toctree-l2">
+         <a class="reference internal" href="docs/tutorials/tokens/retrieve-token-info.html">
+          Retrieve token info
+         </a>
+        </li>
+        <li class="toctree-l2">
+         <a class="reference internal" href="docs/tutorials/tokens/mint-tokens.html">
+          Mint tokens
+         </a>
+        </li>
+        <li class="toctree-l2">
+         <a class="reference internal" href="docs/tutorials/tokens/burn-tokens.html">
+          Burn tokens
+         </a>
+        </li>
+        <li class="toctree-l2">
+         <a class="reference internal" href="docs/tutorials/tokens/transfer-tokens-to-an-identity.html">
+          Transfer tokens to an identity
+         </a>
+        </li>
+       </ul>
+      </details>
+     </li>
      <li class="toctree-l1 has-children">
       <a class="reference internal" href="docs/tutorials/example-apps.html">
        Example apps

docs/index.md

@@ -111,6 +111,7 @@ tutorials/create-and-fund-a-wallet
 tutorials/setup-sdk-client
 tutorials/identities-and-names
 tutorials/contracts-and-documents
+tutorials/tokens
 tutorials/example-apps
 tutorials/send-funds
 tutorials/setup-a-node

docs/tutorials/tokens.md

@@ -0,0 +1,22 @@
+```{eval-rst}
+.. tutorials-tokens:
+```
+
+# Tokens
+
+The following tutorials cover registering, querying, and managing tokens on Dash Platform, including minting, burning, and transferring them between identities.
+
+```{toctree}
+:maxdepth: 2
+:titlesonly:
+
+tokens/register-a-token-contract
+tokens/retrieve-token-info
+tokens/mint-tokens
+tokens/burn-tokens
+tokens/transfer-tokens-to-an-identity
+```
+
+:::{tip}
+You can clone a repository containing the code for all tutorials from <a href="https://github.com/dashpay/platform-readme-tutorials#readme" target="_blank">GitHub</a> or download it as a [zip file](https://github.com/dashpay/platform-readme-tutorials/archive/refs/heads/main.zip).
+:::

docs/tutorials/tokens/burn-tokens.md

@@ -0,0 +1,68 @@
+```{eval-rst}
+.. tutorials-burn-tokens:
+```
+
+# Burn tokens
+
+The purpose of this tutorial is to walk through the steps necessary to burn (permanently destroy) [tokens](../../explanations/tokens.md), reducing the total supply.
+
+## Overview
+
+Burning permanently removes tokens from circulation, decreasing the token's total supply. Burning is only possible when the token contract authorizes it, which the [Register a token contract](register-a-token-contract.md) tutorial sets up. Additional details are available in the [tokens explanation](../../explanations/tokens.md) and the [token protocol reference](../../protocol-ref/token.md).
+
+## Prerequisites
+
+- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed)
+- A configured client: [Setup SDK Client](../setup-sdk-client.md)
+- A registered token contract with a balance to burn: [Tutorial: Register a token contract](register-a-token-contract.md). Set the resulting contract ID as the `TOKEN_CONTRACT_ID` environment variable.
+
+## Code
+
+```{code-block} javascript
+:caption: token-burn.mjs
+
+import { setupDashClient } from '../setupDashClient.mjs';
+
+const { sdk, keyManager } = await setupDashClient();
+const { identity, identityKey, signer } = await keyManager.getAuth();
+
+// TOKEN_CONTRACT_ID comes from token-register.mjs.
+const dataContractId = process.env.TOKEN_CONTRACT_ID;
+const tokenPosition = 0;
+const amount = 1n; // Token amounts are bigint values
+
+try {
+  if (!dataContractId) {
+    throw new Error(
+      'Set TOKEN_CONTRACT_ID in .env from token-register.mjs output.',
+    );
+  }
+
+  const tokenId = await sdk.tokens.calculateId(dataContractId, tokenPosition);
+
+  await sdk.tokens.burn({
+    dataContractId,
+    tokenPosition,
+    amount,
+    identityId: identity.id.toString(),
+    identityKey,
+    signer,
+  });
+
+  const balances = await sdk.tokens.identityBalances(identity.id, [tokenId]);
+  const totalSupply = await sdk.tokens.totalSupply(tokenId);
+
+  console.log(`Burned ${amount} token`);
+  console.log('Token ID:', tokenId);
+  console.log(`Identity token balance: ${balances.get(tokenId) ?? 0n}`);
+  console.log('Total token supply:', totalSupply?.totalSupply ?? 0n);
+} catch (e) {
+  console.error('Something went wrong:\n', e.message);
+}
+```
+
+## What's Happening
+
+After connecting to the client, we get the auth key signer with `keyManager.getAuth()`. We then call `sdk.tokens.burn()` with the contract ID, token position, amount, and signing credentials to destroy 1 token from our balance. Token amounts are `bigint` values, which is why `1n` is written with the `n` suffix.
+
+After burning, we read back the identity's balance with `sdk.tokens.identityBalances()` and the new total supply with `sdk.tokens.totalSupply()` to confirm both have decreased.

docs/tutorials/tokens/mint-tokens.md

@@ -0,0 +1,68 @@
+```{eval-rst}
+.. tutorials-mint-tokens:
+```
+
+# Mint tokens
+
+The purpose of this tutorial is to walk through the steps necessary to mint (issue) new [tokens](../../explanations/tokens.md), increasing the total supply.
+
+## Overview
+
+Minting issues new tokens to the contract owner, increasing the token's total supply up to its maximum. Minting is only possible when the token contract authorizes it, which the [Register a token contract](register-a-token-contract.md) tutorial sets up. Additional details are available in the [tokens explanation](../../explanations/tokens.md) and the [token protocol reference](../../protocol-ref/token.md).
+
+## Prerequisites
+
+- [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed)
+- A configured client: [Setup SDK Client](../setup-sdk-client.md)
+- A registered token contract: [Tutorial: Register a token contract](register-a-token-contract.md). Set the resulting contract ID as the `TOKEN_CONTRACT_ID` environment variable.
+
+## Code
+
+```{code-block} javascript
+:caption: token-mint.mjs
+
+import { setupDashClient } from '../setupDashClient.mjs';
+
+const { sdk, keyManager } = await setupDashClient();
+const { identity, identityKey, signer } = await keyManager.getAuth();
+
+// TOKEN_CONTRACT_ID comes from token-register.mjs.
+const dataContractId = process.env.TOKEN_CONTRACT_ID;
+const tokenPosition = 0;
+const amount = 10n; // Token amounts are bigint values
+
+try {
+  if (!dataContractId) {
+    throw new Error(
+      'Set TOKEN_CONTRACT_ID in .env from token-register.mjs output.',
+    );
+  }
+
+  const tokenId = await sdk.tokens.calculateId(dataContractId, tokenPosition);
+
+  await sdk.tokens.mint({
+    dataContractId,
+    tokenPosition,
+    amount,
+    identityId: identity.id.toString(),
+    identityKey,
+    signer,
+  });
+
+  const balances = await sdk.tokens.identityBalances(identity.id, [tokenId]);
+  const totalSupply = await sdk.tokens.totalSupply(tokenId);
+
+  console.log(`Minted ${amount} tokens`);
+  console.log('Token ID:', tokenId);
+  console.log(`Identity token balance: ${balances.get(tokenId) ?? 0n}`);
+  console.log('Total token supply:', totalSupply?.totalSupply ?? 0n);
+} catch (e) {
+  console.error('Something went wrong:\n', e.message);
+}
+```
+
+## What's Happening
+
+After connecting to the client, we get the auth key signer with `keyManager.getAuth()`. We then call `sdk.tokens.mint()` with the contract ID, token position, amount, and signing credentials to issue 10 new tokens to our identity. Token amounts are `bigint` values, which is why `10n` is written with the `n` suffix.
+
+After minting, we read back the identity's balance with `sdk.tokens.identityBalances()` and the new total supply with `sdk.tokens.totalSupply()` to confirm both have increased.