docs: add delegation tutorial

src/common/navigation.yaml

@@ -23,6 +23,7 @@ sections:
               - path: /running-mainnet-node
               - path: /running-testnet-node
               - path: /integrate-stacking
+              - path: /integrate-stacking-delegation
               - path: /stacking-using-CLI
 
           - title: Stacks 1.0

src/pages/understand-stacks/integrate-stacking.md

@@ -10,12 +10,10 @@ images:
   sm: /images/pages/stacking-rounded.svg
 ---
 
-![What you'll create in this tutorial](/images/stacking-view.png)
+> Try the [Stacks Wallet](https://www.hiro.so/wallet) to experience the Stacking flow as a token holder
 
 ## Introduction
 
-!> The Stacking implementation is still in development and could change in the coming weeks
-
 In this tutorial, you'll learn how to integrate Stacking by interacting with the respective smart contract, as well as reading data from the Stacks blockchain.
 
 This tutorial highlights the following functionality:
@@ -313,7 +311,7 @@ const stackingStatus = await client.getStatus();
 
 To display the unlocking time, you need to use the `firstRewardCycle` and the `lockPeriod` fields.
 
--> Coming soon: how to obtain rewards paid out to the stacker? how to find out if an account has stacked tokens?
+// TODO: Rewards and get-stacker-info
 
 **Congratulations!** With the completion of this step, you successfully learnt how to ...
 
@@ -322,19 +320,3 @@ To display the unlocking time, you need to use the `firstRewardCycle` and the `l
 - Verify stacking eligibility
 - Add stacking action
 - Display stacking status
-
-## Implementing delegation
-
-~> Right now, the tooling does not support the delegation flow. However, the delegation flow can be implemented with contract calls to the Stacking contract
-
-Stacking delegation requires you to implement a different flow. Until the provided tooling supports this flow, it is best to implement the required contract calls directly.
-
-Below is a description of contract calls required to integrate delegation:
-
-1. Account holders call the [`delegate-stx`](/references/stacking-contract#delegate-stx) method and provide the delegator address, the amount accessible to the delegator, the address rewards should be send to, and the burn height at which the delegation relationship should be terminated. This needs to happen only once. The account holder can specify a delegation amount that is higher that their balance and must hold the expected amount when locking is happening
-2. For each delegation relationship that was created, the delegator calls the [`delegate-stack-stx`](/references/stacking-contract#delegate-stack-stx) method to lock up the STX token from the account holder. This method must be called during each cycle (unless specified for multiple cycles) and until the delegator locked up enough STX tokens required to participate in Stacking. This method will check the account balances. Once successfully executed, the STX tokens in the account will be locked up
-3. With pooling being completed and the minimum STX token threshold reached, the delegator calls the [`stack-aggregation-commit`](/references/stacking-contract#stack-aggregation-commit) to confirm participation in the next cycle(s)
-
-In case STX token holders want to terminate the delegation relationship before it terminates as planned, they can call the [`revoke-delegate-stx`](/references/stacking-contract#revoke-delegate-stx) method.
-
--> A delegator doesn't need to _own_ a minimum amount ot STX token to reach the threshold. However, they need funds to pay for transaction fees on the network.

src/pages/understand-stacks/integration-stacking-delegation.md

@@ -0,0 +1,135 @@
+---
+title: Integrate Stacking delegation
+description: Learn how to add Stacking delegation capabilities to your wallet or exchange
+icon: TestnetIcon
+experience: advanced
+duration: 60 minutes
+tags:
+  - tutorial
+images:
+  sm: /images/pages/stacking-rounded.svg
+---
+
+## Introduction
+
+In this tutorial, you'll learn how to integrate the Stacking delegation flow by interacting with the respective smart contract, as well as reading data from the Stacks blockchain.
+
+This tutorial highlights the following functionality:
+
+- As an account holder: delegate STX tokens
+- As an account holder: revoke delegation rights
+- As a delegator: Stack STX toksn on behalf of the account holder
+- As a delegator: Commit to Stacking with all delegated STX tokens
+
+## Requirements
+
+First, you'll need to understand the [Stacking delegation mechanism](/understand-stacks/stacking).
+
+You'll also need [NodeJS](https://nodejs.org/en/download/) `12.10.0` or higher to complete this tutorial. You can verify your installation by opening up your terminal and run the following command:
+
+```bash
+node --version
+```
+
+Finally, you need to have access to at least two accounts (STX account holder and delegator). For testing purposes on the testnet, you can use the CLI to generate them:
+
+```shell
+stacks make_keychain -t > account.json
+stacks make_keychain -t > delegator.json
+```
+
+You can use the faucet to obtain testnet STX tokens for the test account. Replace <stxAddress> below with your address:
+
+```shell
+curl -XPOST "https://stacks-node-api.testnet.stacks.co/extended/v1/faucets/stx?address=<stxAddress>&stacking=true"
+```
+
+## Overview
+
+In this tutorial, we'll implement the Stacking delegation flow laid out in the [Stacking guide](/understand-stacks/stacking#delegation).
+
+## Step 1: Integrate libraries
+
+Install the stacking, network, transactions libraries and bn.js for large number handling:
+
+```shell
+npm install --save @stacks/stacking @stacks/network @stacks/transactions bn.js
+```
+
+-> See additional [Stacking library reference](https://github.com/blockstack/stacks.js/tree/master/packages/stacking)
+
+## Step 2: Delegate STX tokens
+
+To get started, delegate STX tokens as an account holder:
+
+```js
+import { getNonce } from '@stacks/transactions';
+import { StacksTestnet, StacksMainnet } from '@stacks/network';
+import { StackingClient } from '@stacks/stacking';
+import BN from 'bn.js';
+
+const network = new StacksTestnet();
+// for mainnet: const network = new StacksMainnet();
+const client = new StackingClient(address, network);
+
+// how much to stack, in microSTX
+const amountMicroStx = new BN(100000000000);
+// STX address of the delegator
+const delegateTo = 'ST2MCYPWTFMD2MGR5YY695EJG0G1R4J2BTJPRGM7H';
+// burn height at which the delegation relationship should be revoked (optional)
+const untilBurnBlockHeight = 5000;
+// a BTC address for reward payouts
+const poxAddress = 'mvuYDknzDtPgGqm2GnbAbmGMLwiyW3AwFP';
+// private key of the account holder for transaction signing
+const privateKey = 'd48f215481c16cbe6426f8e557df9b78895661971d71735126545abddcd5377001';
+
+const delegetateResponse = await client.delegateStx({
+  amountMicroStx,
+  delegateTo,
+  untilBurnBlockHeight, // optional
+  poxAddress, // optional
+  privateKey,
+});
+
+// {
+//   txid: '0xf6e9dbf6a26c1b73a14738606cb2232375d1b440246e6bbc14a45b3a66618481',
+// }
+```
+
+This methos calls the [`delegate-stx`](/references/stacking-contract#delegate-stx) method of the Stacking contract.
+
+-> To avoid handling private keys, it is recommended to use the [Stacks Wallet](https://www.hiro.so/wallet) to sign the delegation transaction
+
+## Step 3:
+
+For each delegation relationship that was created, the delegator calls the [`delegator-stack-stx`](/references/stacking-contract#delegate-stack-stx) method to lock up the STX token from the account holder. This method must be called until the delegator locked up enough STX tokens required to participate in Stacking
+
+## Step 4:
+
+With pooling being completed and the minimum STX token threshold reached, the delegator calls the [`stack-aggregation-commit`](/references/stacking-contract#stack-aggregation-commit) to confirm participation in the next cycle(s)
+
+**Congratulations!** With the completion of this step, you successfully learnt how to ...
+
+- Generate Stacks accounts
+- Display stacking info
+- Verify stacking eligibility
+- Add stacking action
+- Display stacking status
+
+## Optional: Revoke delegation rights
+
+Delegators will be able to Stack STX tokens on the account holder's behalf until either the set burn height is reached or the account holder revokes the rights.
+
+To revoke delegation rights, the account holder can call the `revokeDelegatestx` method.
+
+```js
+const revokeResponse = await client.revokeDelegateStx(privateKey);
+
+// {
+//   txid: '0xf6e9dbf6a26c1b73a14738606cb2232375d1b440246e6bbc14a45b3a66618481',
+// }
+```
+
+This method calls the [`revoke-delegate-stx`](/references/stacking-contract#revoke-delegate-stx) method of the Stacking contract.
+
+-> To avoid handling private keys, it is recommended to use the [Stacks Wallet](https://www.hiro.so/wallet) to sign the revoke transaction

src/pages/understand-stacks/stacking.md

@@ -44,14 +44,17 @@ The Stacking flow is different for delegation use cases:
 
 ![stacking flow](/images/stacking-delegation-illustration.png)
 
-- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. An account can only be associated with one single delegator
+- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator
-- The account has to define the delegation relationship. They can optionally restrict the reward address that must be used and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack
+- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack
 - Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking
-- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle(s). The delegator must send a commitment for each account they want to include
+- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle(s)
 - Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6)
 - The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights
 
--> Note that the delegation flow allows reward addresses to be used multiple times. This is not the case for the individual Stacking flow.
+If you would like to implement this flow in your own wallet, exchange, or any other application, please have a look at this tutorial:
+
+[@page-reference | inline]
+| /understand-stacks/integrate-stacking-delegation
 
 ## PoX mining