GITBOOK-65: Add Lockstacks section

nakamoto-upgrade/nakamoto.md

@@ -51,7 +51,7 @@ After a DKG (Distributed Key Generation) round, signer votes are submitted to th
 
 The explorer will allow you to view fast blocks as they come in. Be sure to turn on “Live updates” to see them coming in in real time. [https://explorer.hiro.so/?chain=testnet\&api=https://api.nakamoto.testnet.hiro.so](https://explorer.hiro.so/?chain=testnet\&api=https://api.nakamoto.testnet.hiro.so)
 
-<figure><img src="../.gitbook/assets/image.png" alt=""><figcaption><p>Turn on Live Updates to view blocks coming in in real time</p></figcaption></figure>
+<figure><img src="../.gitbook/assets/image (4).png" alt=""><figcaption><p>Turn on Live Updates to view blocks coming in in real time</p></figcaption></figure>
 
 #### Local Development Environment
 

nakamoto-upgrade/signing-and-stacking/running-a-signer.md

@@ -10,7 +10,7 @@
 
 In order to run a signer, you'll need to run a signer and a Stacks node side-by-side. Specifically, you'll want to run a testnet follower node. Instructions for doing this are listed below in the "Running Your Stacks Node" section. The signer will monitor for events coming from the stacks node and is in charge of using the generated account (next section) to sign incoming Stacks blocks sent from the Stcks node.
 
-This doc will provide instructions on how to set up both using either Docker or building from source. Binaries will not be available in the initial release but will be released at a later date. 
+This doc will provide instructions on how to set up both using either Docker or building from source. Binaries will not be available in the initial release but will be released at a later date.
 
 It will also walk through how to set up the config files to get the signer and Stacks node communicating correctly.
 
@@ -26,24 +26,22 @@ The Nakamoto release and thus the signer software you'll want to run is containe
 
 <summary>Signer Checklist</summary>
 
-
-
 Detailed steps for each of these are laid out below, but this checklist is being included as a way to quickly reference if you have taken all the appropriate actions to run a signer.
 
-### Pre-Launch Setup
+#### Pre-Launch Setup
 
 * [ ] Ensure your system meets the following requirements:
   * 4 vCPU
   * 8GB memory
   * 150 GB storage (250 GB if running a Stacks node)
 * [ ] Acquire Docker and basic knowledge of Stacks accounts, stacking, and the Nakamoto stacking flow (links provided below).
 
-### Preflight Setup
+#### Preflight Setup
 
 * [ ] Generate a new private key on testnet using stacks-cli.
 * [ ] Save the generated account information securely.
 
-### Configuration Setup
+#### Configuration Setup
 
 * [ ] Create a `signer-config.toml` file with necessary configurations:
   * node\_host
@@ -54,7 +52,7 @@ Detailed steps for each of these are laid out below, but this checklist is being
   * stacks\_private\_key
 * [ ] Store `signer-config.toml` securely and note down the values used.
 
-### Running the Signer
+#### Running the Signer
 
 * [ ] Decide whether to run the signer using Docker (recommended) or as a binary.
 * [ ] If using Docker:
@@ -65,12 +63,12 @@ Detailed steps for each of these are laid out below, but this checklist is being
   * [ ] Build `stacks-core` from source or download the pre-built binary.
   * [ ] Run the signer using the command: `stacks-signer run --config <path_to_config>`.
 
-### Verify Signer Operation
+#### Verify Signer Operation
 
 * [ ] Check that the signer is listening on its configured endpoint.
 * [ ] Confirm that there are no errors and the system is ready for connections.
 
-### Setting Up the Stacks Node
+#### Setting Up the Stacks Node
 
 * [ ] Create a `node-config.toml` with the necessary settings:
   * block\_proposal\_token
@@ -83,12 +81,12 @@ Detailed steps for each of these are laid out below, but this checklist is being
   * [ ] Download the appropriate binary.
   * [ ] Run it with the command: `./stacks-node start --config <path_to_config>`.
 
-### Verify Stacks Node Operation
+#### Verify Stacks Node Operation
 
 * [ ] Check the Stacks node logs for successful connection to the signer.
 * [ ] Confirm that the node is syncing Bitcoin headers properly.
 
-### Setup Stacks Accounts
+#### Setup Stacks Accounts
 
 * [ ] Set up a “pool operator” wallet in a Stacks wallet (e.g., Leather or Xverse).
 * [ ] Fund the pool operator wallet with STX (testnet) sufficient for transaction fees.
@@ -278,4 +276,4 @@ Before the Nakamoto transition, signers need a small amount of STX to cover tran
 
 In a previous step, where you generated a keychain, an address field was included in the output. This is your signer wallet’s STX address. You can also choose to use the mnemonic to access the wallet with [Leather](https://leather.io) or [Xverse](https://www.xverse.app).
 
-Transfer funds (or use the faucet) into the signer’s wallet address. We recommend at least 100-200 STX to cover transaction fees.\
+Transfer funds (or use the faucet) into the signer’s wallet address. We recommend at least 100-200 STX to cover transaction fees.\\

nakamoto-upgrade/signing-and-stacking/stacking-flow.md

@@ -296,3 +296,138 @@ During the prepare phase, the signers perform DKG through StackerDB messages. On
 During the instantiation phase (before fast blocks and full Nakamoto rules go live), the signer must pay a STX transaction fee for this transaction to be confirmed. Critically, this means that a minimum balance must be kept in the STX address associated with the signer’s key. There is a config field called `tx_fee_ms` (transaction fee in micro-stacks) that can be optionally configured to set the fee for these transactions. If the config field is omitted, the fee defaults to 10,000 micro-stacks (0.01 STX).
 
 During the Activation phase (after fast blocks and full Nakamoto rules have been activated), the signer doesn’t need to pay fees for this transaction, so no STX balance needs to be kept in that address.
+
+### Stacking with Lockstacks
+
+#### Prerequisite: generate a signature
+
+Before you can stack using Lockstacks, you'll need to make sure you have generated your signer signature. There are two ways to do this: through the CLI or using Lockstacks itself.
+
+#### Using the stacks-signer CLI
+
+If you already have your signer configured and set up, you can use the stacks-signer CLI to generate this signature. You can either SSH into your running signer or use the stacks-signer CLI locally. If using the CLI locally, you will need to ensure you have a matching configuration file located on your filesystem. Having a matching configuration file is important to ensure that the signer public key you make in Stacking transactions is the same as in your hosted signer.
+
+The CLI command is:
+
+```bash
+stacks-signer generate-stacking-signature \
+  --pox-address bc123... \
+  --reward-cycle 100 \
+  --config ./config.toml \
+  --period 12 \
+  --topic stack-stx
+```
+
+These arguments are:
+
+* pox-address: the BTC address where the signer wants to receive Stacking rewards
+* reward-cycle: For solo stacking, this must refer to the current reward cycle where the user will broadcast their Stacking transaction. For the stack-aggregation-commit transaction, used in delegated signing, this should match the reward-cycle they are using as an argument in stack-aggregation-commit.
+* config: path to a local Signer configuration file
+* period: for solo stacking, this refers to the lock-period argument the user makes in stack-stx and the extend-count argument in stack-extend. For stack-aggregation-commit, this should equal 1.
+* topic: This string is dependent on the Stacking function where the signature will be used.
+  * For stack-stx, the topic needs to be stack-stx
+  * For stack-extend, the topic needs to be stack-extend
+  * For stack-aggregation-commit, the topic needs to be agg-commit.
+
+Once the command is run, the CLI will output two fields:
+
+* Signature: 0xaaaaaaaaa
+* Public Key: 0xbbbbbb
+
+You will use both the signature and public key in Stacking transactions.
+
+#### Using Lockstacks to generate the signature
+
+{% hint style="info" %}
+At the time of writing, this has only been tested using the [Leather](https://leather.io) wallet.
+{% endhint %}
+
+You can visit [staging.lockstacks.com](http://staging.lockstacks.com) to generate a signer key signature. Make sure you’re connected to the correct network (ie Nakamoto Testnet).\
+\
+To generate a signer key signature, it’s important that you’ve logged in Leather with the same secret key that was used to [generate your signer key](running-a-signer.md#preflight-setup-1). Once you’ve setup that account on Leather, you can log in to Lockstacks.\
+\
+Click the link “Signer key signature” at the bottom of the page. This will open the “generate a signer key signature” page.
+
+<figure><img src="../../.gitbook/assets/image.png" alt=""><figcaption></figcaption></figure>
+
+The fields are:
+
+* Reward cycle:&#x20;
+  * For all solo stacking transactions, this must equal the current reward cycle, not the cycle in which they will start stacking. The field defaults to the current reward cycle.
+  * For stack-aggregation-commit, this field must equal the cycle used in that function’s “reward cycle” argument. Typically, that equates to current\_cycle + 1.
+* Bitcoin address: the PoX reward address that can be used
+* Topic: the stacking function that will use this signature
+* Max amount: max amount of STX that can be used. Defaults to “max possible amount”
+* Auth ID: defaults to random int
+* Duration: must match the number of cycles used in the stacking transaction. For stack-aggregation-commit, use “1”.
+
+{% hint style="warning" %}
+Each of these fields must be exactly matched in order for the Stacking transaction to work. Future updates to Lockstacks will verify the signature before the transaction is made.
+{% endhint %}
+
+Click the “generate signature” button to popup a Leather page where you can generate the signature. Once you submit that popup, Lockstacks will have the signer key and signature you generated.
+
+After you sign that message, you'll see the information you need to share with Stackers who are delegating to you, including the signer public key and signature.
+
+You can click the “copy” icon next to “signer details to share with stackers”. This will copy a JSON string, which can be directly pasted into the Lockstacks page where you make your Stacking transaction. Alternatively, this information can be shared and entered manually.
+
+We'll cover the Lockstacks pages for actually making those transactions next.
+
+### Solo Stacking
+
+#### stack-stx
+
+To start, you'll visits Lockstacks and clicks the “Stack independently” button on the home page.
+
+This page will allow you to input the following input:
+
+* The amount of STX you want to lock
+* The duration (in number of cycles) to lock for
+* Your BTC address where you will receive Stacking rewards
+* New fields:
+  * Your signer public key
+  * Your signer key signature (this is what you generated in the previous step)
+  * Auth ID
+  * Max amount
+
+#### stack-extend
+
+If you want to extend the amount of time that your STX will be locked for, you can use the stack-extend page on Lockstacks.
+
+If you’re already stacking, the home page will provide a link to “view stacking details”. From there, you can choose to extend.
+
+On this page are the following fields:
+
+* The number of cycles you want to extend for
+* Your BTC address to receive rewards
+* New fields:
+  * Signer public key
+  * Signer key signature
+
+### Delegated stacking
+
+The first step with delegated stacking involves a stacker delegating their Stacks to a specific signer. Stackers can do this by visiting the “Stack in a pool” page on Lockstacks.
+
+Signers must provide a STX address (a “pool admin address”) that will manage delegations. This is a separate address from the signer’s private key, and this can be any address. This address is what will be used when making transactions to confirm and aggregate delegated STX.
+
+Signers can log in to LockStacks and visit [https://lockstacks.com/pool-admin](https://lockstacks.com/pool-admin?chain=mainnet) to make pool management transactions.
+
+#### delegate-stack-stx
+
+Once a user has delegated to a signer, the signer must call delegate-stack-stx for each individual stacker.
+
+There is no change to this flow in Nakamoto.
+
+#### stack-aggregation-commit
+
+Once a pool has enough delegated STX to become a signer, the pool admin needs to visit the stack-aggregation-commit page on Lockstacks. The pool admin enters the following information:
+
+* Reward cycle: the reward cycle where the admin is “commiting” delegated STX. This must be done for every individual reward cycle where the pool will be acting as a signer.
+* BTC address
+* New fields:
+  * Signer public key
+  * Signer key signature
+  * Auth ID
+  * Max amount
+
+Once this transaction has been confirmed, the signer is eligible to be a signer for an upcoming reward cycle.

stacks-101/stacking.md

@@ -67,7 +67,7 @@ Keep in mind that the target duration for a reward cycles is \~2 weeks. This dur
 
 ### Stacking delegation flow
 
-<figure><img src="../.gitbook/assets/image (4).png" alt=""><figcaption></figcaption></figure>
+<figure><img src="../.gitbook/assets/image (4) (1).png" alt=""><figcaption></figcaption></figure>
 
 The Stacking flow is different for delegation use cases: