docs: complete instructions

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

@@ -17,8 +17,7 @@ In this tutorial, you'll learn how to integrate the Stacking delegation flow by
 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 token on behalf of the account holder
-- As a delegator: Stack STX toksn on behalf of the account holder
 - As a delegator: Commit to Stacking with all delegated STX tokens
 
 ## Requirements
@@ -38,7 +37,7 @@ 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:
+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"
@@ -46,7 +45,7 @@ curl -XPOST "https://stacks-node-api.testnet.stacks.co/extended/v1/faucets/stx?a
 
 ## Overview
 
-In this tutorial, we'll implement the Stacking delegation flow laid out in the [Stacking guide](/understand-stacks/stacking#delegation).
+In this tutorial, we'll implement the Stacking delegation flow laid out in the [Stacking guide](/understand-stacks/stacking#stacking-delegation-flow).
 
 ## Step 1: Integrate libraries
 
@@ -74,12 +73,16 @@ 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';
 
@@ -96,25 +99,83 @@ const delegetateResponse = await client.delegateStx({
 // }
 ```
 
-This methos calls the [`delegate-stx`](/references/stacking-contract#delegate-stx) method of the Stacking contract.
+This method 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:
+## Step 3: Stack STX tokens
+
+With an established delegation relationship, the delegator can stack STX tokens on behalf of the account holder.
+
+```js
+// the stacks STX address
+const address = 'ST3XKKN4RPV69NN1PHFDNX3TYKXT7XPC4N8KC1ARH';
+
+// block height at which to stack
+const burnBlockHeight = 2000;
 
-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
+// the delegator initiates a different client
+const delegatorAddress = 'ST22X605P0QX2BJC3NXEENXDPFCNJPHE02DTX5V74';
 
-## Step 4:
+// number cycles to stack
+const cycles = 3;
+
+// delegator private key for transaction signing
+const delegatorPrivateKey = 'd48f215481c16cbe6426f8e557df9b78895661971d71735126545abddcd5377001';
+
+// the BTC address for reward payouts; either to the delegator or to the BTC address set by the account holder
+const delegatePoxAddress = 'msiYwJCvXEzjgq6hDwD9ueBka6MTfN962Z';
+
+// if you call this method multiple times during the same block, you need to increase the nonce manually
+let nonce = getNonce(delegatorAddress, network);
+nonce = nonce.add(new BN(1));
+
+const delegatorClient = new StackingClient(delegatorAddress, network);
+
+const delegetateStackResponses = await delegatorClient.delegateStackStx({
+  stacker: address,
+  amountMicroStx,
+  poxAddress: delegatePoxAddress, // if set in step 2, this needs to match `poxAddress`
+  burnBlockHeight,
+  cycles,
+  privateKey: delegatorPrivateKey,
+  nonce, // optional
+});
+
+//   {
+//     txid: '0xf6e9dbf6a26c1b73a14738606cb2232375d1b440246e6bbc14a45b3a66618481',
+//   }
+```
+
+This function calls the [`delegator-stack-stx`](/references/stacking-contract#delegate-stack-stx) method of the Stacking contract 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: Commit to Stacking
+
+As soon as pooling is completed and the minimum STX token threshold reached, the delegator needs to confirm participation for the next cycle(s):
+
+```js
+// reward cycle id to commit to
+const rewardCycle = 12;
+
+const delegetateCommitResponse = await delegatorClient.stackAggregationCommit({
+  poxAddress: delegatePoxAddress, // this must be the delegator bitcoin address
+  rewardCycle,
+  privateKey: privateKeyDelegate,
+});
+
+// {
+//   txid: '0xf6e9dbf6a26c1b73a14738606cb2232375d1b440246e6bbc14a45b3a66618481',
+// }
+```
 
-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)
+This method calls the [`stack-aggregation-commit`](/references/stacking-contract#stack-aggregation-commit) function of the Stacking contract.
 
-**Congratulations!** With the completion of this step, you successfully learnt how to ...
+**Congratulations!** With the completion of this step, you successfully learnt how to use the Stacking library to ...
 
-- Generate Stacks accounts
+- Delegate STX tokens as an account holder
-- Display stacking info
+- Stack STX token on behalf of an account holder
-- Verify stacking eligibility
+- Commit to Stacking with all delegated STX tokens
-- Add stacking action
-- Display stacking status
 
 ## Optional: Revoke delegation rights
 

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

@@ -311,8 +311,6 @@ const stackingStatus = await client.getStatus();
 
 To display the unlocking time, you need to use the `firstRewardCycle` and the `lockPeriod` fields.
 
-// TODO: Rewards and get-stacker-info
-
 **Congratulations!** With the completion of this step, you successfully learnt how to ...
 
 - Generate Stacks accounts
@@ -320,3 +318,14 @@ To display the unlocking time, you need to use the `firstRewardCycle` and the `l
 - Verify stacking eligibility
 - Add stacking action
 - Display stacking status
+
+## Optional: Rewards
+
+Currently, the Stacking library does not provide methods to get the paid rewards for a set address. However, the [Stacks Blockchain API exposes endpoints](https://blockstack.github.io/stacks-blockchain-api/#tag/Burnchain) to get more details.
+
+As an example, if you want to get the rewards paid to `btcAddress`, you can make the following API call:
+
+```shell
+# for mainnet, replace `testnet` with `mainnet`
+curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/burnchain/rewards/<btcAddress>'
+```

src/pages/understand-stacks/stacking.md

@@ -38,7 +38,7 @@ If you would like to implement this flow in your own wallet, exchange, or any ot
 [@page-reference | inline]
 | /understand-stacks/stacking-using-CLI
 
-### Delegation
+## Stacking delegation flow
 
 The Stacking flow is different for delegation use cases: