diff --git a/src/pages/understand-stacks/integration-stacking-delegation.md b/src/pages/understand-stacks/integrate-stacking-delegation.md similarity index 58% rename from src/pages/understand-stacks/integration-stacking-delegation.md rename to src/pages/understand-stacks/integrate-stacking-delegation.md index ff16747f..94137073 100644 --- a/src/pages/understand-stacks/integration-stacking-delegation.md +++ b/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 toksn on behalf of the account holder +- As a delegator: Stack STX token 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 below with your address: +You can use the faucet to obtain testnet STX tokens for the test account. Replace `` below with your address: ```shell curl -XPOST "https://stacks-node-api.testnet.stacks.co/extended/v1/faucets/stx?address=&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 -- Display stacking info -- Verify stacking eligibility -- Add stacking action -- Display stacking status +- Delegate STX tokens as an account holder +- Stack STX token on behalf of an account holder +- Commit to Stacking with all delegated STX tokens ## Optional: Revoke delegation rights diff --git a/src/pages/understand-stacks/integrate-stacking.md b/src/pages/understand-stacks/integrate-stacking.md index 20271364..e044d465 100644 --- a/src/pages/understand-stacks/integrate-stacking.md +++ b/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/' +``` diff --git a/src/pages/understand-stacks/stacking.md b/src/pages/understand-stacks/stacking.md index 739aac77..a788b7ea 100644 --- a/src/pages/understand-stacks/stacking.md +++ b/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: