diff --git a/.gitbook/includes/note-for-existing-signersth....md b/.gitbook/includes/note-for-existing-signersth....md index 066012dfa8..5cfef01210 100644 --- a/.gitbook/includes/note-for-existing-signersth....md +++ b/.gitbook/includes/note-for-existing-signersth....md @@ -26,7 +26,7 @@ The output will specify which configuration key caused the panic (there may be m ``` $ stacks-node check-config --config ./Config.toml -INFO [1737983444.257621] [testnet/stacks-node/src/main.rs:278] [main] stacks-node 3.1.0.0.4 (release/3.1.0.0.4:43d4ee9, release build, linux [x86_64]) +INFO [1737057614.446096] [testnet/stacks-node/src/main.rs:278] [main] stacks-node 3.1.0.0.3 (release/3.1.0.0.3:906a8cc, release build, linux [x86_64]) INFO [1729707265.671604] [testnet/stacks-node/src/main.rs:318] [main] Loading config at path ./Config.toml WARN [1729707265.671992] [testnet/stacks-node/src/main.rs:325] [main] Invalid config file: Invalid toml: unknown field `foo`, expected one of `name`, `seed`, `deny_nodes`, `working_dir`, `rpc_bind`, `p2p_bind`, `p2p_address`, `data_url`, `bootstrap_node`, `local_peer_seed`, `miner`, `stacker`, `mock_mining`, `mock_mining_output_dir`, `mine_microblocks`, `microblock_frequency`, `max_microblocks`, `wait_time_for_microblocks`, `wait_time_for_blocks`, `next_initiative_delay`, `prometheus_bind`, `marf_cache_strategy`, `marf_defer_hashing`, `pox_sync_sample_secs`, `use_test_genesis_chainstate`, `always_use_affirmation_maps`, `require_affirmed_anchor_blocks`, `chain_liveness_poll_time_secs`, `stacker_dbs`, `fault_injection_block_push_fail_probability` for key `node` at line 20 column 1 ``` @@ -40,6 +40,6 @@ Note that in the Stacks node config file, the `block_proposal_token` field has b For quick reference, here are the current latest versions you'll want to be running as a signer. If you don't yet have your signer up and running, this guide will walk you through that. * [Binaries](https://github.com/stacks-network/stacks-core/releases/latest) -* Signer Docker Image - [3.1.0.0.4.0](https://hub.docker.com/layers/blockstack/stacks-signer/3.1.0.0.4.0/images/sha256-847f9787e7c9fc3927944d9cb268b2857cbf6c99e33697381b32d3b984d762a7) -* Stacks Node Docker Image - [3.1.0.0.4](https://hub.docker.com/layers/blockstack/stacks-core/3.1.0.0.4/images/sha256-9fd51e4d2af004d44ca6de5b889390a12e2615cb3f1f13e5ac1bfed849aa3bba) +* Signer Docker Image - [3.1.0.0.3.0](https://hub.docker.com/layers/blockstack/stacks-signer/3.1.0.0.3.0/images/sha256-d250b45bd9df406f9e63d995d2176609a631aad3b191d4f66a925be9cb170af0) +* Stacks Node Docker Image - [3.1.0.0.3](https://hub.docker.com/layers/blockstack/stacks-core/3.1.0.0.3/images/sha256-8ac612356f4bb60f69ddb81676778907b484c0ab43951b91c3476a6cd41476a1) {% endhint %} diff --git a/example-contracts/stacking.md b/example-contracts/stacking.md index 53f605b61c..3a36d2d7af 100644 --- a/example-contracts/stacking.md +++ b/example-contracts/stacking.md @@ -2,7 +2,7 @@ Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get\_pox\_info). -Currently, stacking uses the pox-4 contract. The deployed pox-4 contract and included comments can be [viewed in the explorer](https://explorer.hiro.so/txid/SP000000000000000000002Q6VF78.pox-4?chain=mainnet). +Currently stacking uses the pox-4 contract. The deployed pox-4 contract and included comments can be [viewed in the explorer](https://explorer.hiro.so/txid/SP000000000000000000002Q6VF78.pox-4?chain=mainnet). In this walkthrough, we'll cover the entire stacking contract from start to finish, including descriptions of the various functions and errors, and when you might use/encounter them. @@ -12,7 +12,7 @@ Rather than walking through the contract line by line, which you can do by simpl At the bottom you will find a list of some errors you may run into and their explanations. -There are a few utilities that make interacting with this contract easier including [Leather Earn](https://earn.leather.io) as an UI and the [@stacks/stacking package](https://www.npmjs.com/package/@stacks/stacking) for a JS library. +There are a few utilities that make interacting with this contract easier including [Lockstacks](https://lockstacks.com) as a UI and the [@stacks/stacking package](https://www.npmjs.com/package/@stacks/stacking) for a JS library. Hiro has a [detailed guide](https://docs.hiro.so/stacks.js/guides/how-to-integrate-stacking) available for stacking using this library as well as a [Nakamoto guide](https://docs.hiro.so/nakamoto/stacks-js) specifically for the additions made to work with `pox-4`. @@ -86,14 +86,14 @@ Here's the full code for that function, then we'll dive into how it works below First let's cover the needed parameters. -* `amount-ustx` is the amount of STX you would like to lock, denoted in micro-STX, or uSTX (1 STX = 1,000,000 uSTX). -* `pox-addr` is a tuple that encodes the Bitcoin address to be used for the PoX rewards, details below. -* `start-burn-ht` is the Bitcoin block height you would like to begin stacking. You will receive rewards in the reward cycle following `start-burn-ht`. Importantly, `start-burn-ht` may not be further into the future than the current reward cycle, and in most cases should be set to the current burn block height. -* `lock-period` sets the number of reward cycles you would like you lock your STX for, this can be between 1 and 12. -* `signer-sig` is a unique generated signature that proves ownership of this signer. Further details for its role and how to generate it can be found in the [How to Stack](../guides-and-tutorials/stack-stx/stacking-flow.md) document. -* `signer-key` is the public key of your signer, more details in the [How to Run a Signer](../guides-and-tutorials/running-a-signer/) document. -* `max-amount` sets the maximum amount allowed to be stacked during the provided stacking period. -* `auth-id` is a unique string to prevent re-use of this stacking transaction. +* `amount-ustx` is the amount of STX you would like to lock, denoted in micro-STX, or uSTX (1 STX = 1,000,000 uSTX) +* `pox-addr` is a tuple that encodes the Bitcoin address to be used for the PoX rewards, details below +* `start-burn-ht` is the Bitcoin block height you would like to begin stacking. You will receive rewards in the reward cycle following `start-burn-ht`. Importantly, `start-burn-ht` may not be further into the future than the next reward cycle, and in most cases should be set to the current burn block height. +* `lock-period` sets the number of reward cycles you would like you lock your STX for, this can be 1-12 +* `signer-sig` is a unique generatedf signature that proves ownership of this signer. Further details for its role and how to generate it can be found in the [How to Stack](../guides-and-tutorials/stack-stx/stacking-flow.md) doc +* `signer-key` is the public key of your signer, more details in the [How to Run a Signer](../guides-and-tutorials/running-a-signer/) doc +* `max-amount` sets the maximum amount allowed to be stacked during the provided stacking period +* `auth-id` is a unique string to prevent re-use of this stacking transaction {% hint style="warning" %} It's important to make sure that these fields match what you pass in to the signer signature generation. If they don't, you will likely get error 35 (`ERR_INVALID_SIGNATURE_PUBKEY`) \ @@ -145,7 +145,7 @@ Finally we return the lock up information so the node can carry out the lock by From here, the locked STX tokens will be unlocked automatically at the end of the lock period. -The other option is that the stacker can call the `stack-increase` or `stack-extend` functions to either increase the amount of STX they have locked or extend the time to lock them, respectively. +The other option is that the stacker can call the `stack-increase` or `stack-extend` functions to either increase the amount of STX they have locked or increase the amount of time to lock them, respectively. ### Delegated Stacking @@ -158,6 +158,7 @@ Delegated stacking has a few additional steps to it. It is essentially a three-s There are also a few alternative steps here depending on the action you want to take. * Revoke delegation +* Each of these steps has a corresponding function. Let's dig into them. @@ -210,9 +211,9 @@ This function does not actually lock the STX, but just allows the pool operator This function takes a few parameters: -* `amount-ustx` is the amount the stacker is delegating denoted in uSTX. -* `delegate-to` is the Stacks address of the pool operator (or delegate) being delegated to. -* `until-burn-ht` is an optional parameter that describes when this delegation expires. +* `amount-ustx` is the amount the stacker is delegating denoted in uSTX +* `delegate-to` is the Stacks address of the pool operator (or delegate) being delegated to +* `until-burn-ht` is an optional parameter that describes when this delegation expires * `pox-addr` is an optional Bitcoin address. If this is provided, the pool operator must send rewards to this address. If it is not provided, it is up to the discretion of the pool operator where to send the rewards. It first runs through a few checks to ensure that the function caller is allowed, the provided `pox-addr` is valid, and that the stacker is not already delegating. @@ -303,11 +304,11 @@ This function can only be called after a stacker has called their respective `de Like the other functions, this function takes in several parameters and runs through several checks before updating the contract state. -* `stacker` is the principal of the stacker who has delegated their STX. -* `amount-ustx` is at most the amount of uSTX they have delegated. -* `pox-addr` is the Bitcoin address the rewards will be sent to. If the stacker passed this field in to their `delegate-stx` function, this must be the same value. -* `start-burn-ht` corresponds to the field passed in by the stacker. -* `lock-period` corresponds to the number of cycles to lock the funds for. This can be at most 12, or the number of cycles left until the cycle matching `until-burn-ht` argument in `delegate-stx` (if set by delegator). +* `stacker` is the principal of the stacker who has delegated their STX +* `amount-ustx` is the amount they have delegated in uSTX +* `pox-addr` is the Bitcoin address the rewards will be sent to. If the stacker passed this field in to their `delegate-stx` function, this must be the same value +* `start-burn-ht` corresponds to the field passed in by the stacker +* `lock-period` corresponds to the same field that the stacker passed in Now we assign a few variables using `let` before running several checks. @@ -331,9 +332,9 @@ After those checks and partial stacking, we update the `stacking-state` map and At this point this stacker's STX are considered partially stacked. We still need to perform one more step as the pool operator in order to officially lock them. -#### stack-aggregation-commit-indexed +#### stack-aggregation-commit -The `stack-aggregation-commit-indexed` function is just a wrapper for the private `inner-stack-aggregation-commit` function, so that is the source code included here. +The `stack-aggregation-commit` function is just a wrapper for the private `inner-stack-aggregation-commit` function, so that is the source code included here. ```clojure ;; Commit partially stacked STX and allocate a new PoX reward address slot. @@ -441,7 +442,7 @@ The reason is because there are a finite amount of reward slots (4,000) and each Stackers need to be able to stack the minimum in order to be eligible for one of these reward slots. A delegator may choose to delegate to a pool (even if they meet the minimum stacking requirement) if they do not want to handle the infrastructure of running a signer or the actual stacking operations, which is why this option exists. -#### delegate-stack-stx and stack-aggregation-commit-indexed +#### delegate-stack-stx and stack-aggregation-commit In both of these functions, `pox-addr` corresponds to the address where the pool operator would like the rewards to be sent. @@ -468,8 +469,8 @@ To fix this, check all of the data you passed in to see where the mismatch is. #### Error 4 - ERR\_STACKING\_NO\_SUCH\_PRINCIPAL -The stacking contract looks up partially stacked stx (after you have called `delegate-stack-stx`) with the lookup key `(pox-addr, stx-address, reward-cycle)`. This error means that either when you generated your signature or called the `stack-aggregation-commit` function, you passed in the wrong parameter for one of these. More information in the [stacking guide](../guides-and-tutorials/stack-stx/stacking-flow.md#delegator-initiates-delegation). +The stacking contract looks up partially stacked stx (after you have called `delegate-stack-stx`) with the lookup key `(pox-addr, stx-address, reward-cycle`. This error means that either when you generated your signature or called the `stack-aggregation-commit` function, you passed in the wrong parameter for one of these. More information in the [stacking guide](../guides-and-tutorials/stack-stx/stacking-flow.md#delegator-initiates-delegation). -#### Error 24 - ERR\_INVALID\_START\_BURN\_HEIGHT; +#### Error 24 - -This means that the `start-burn-height` parameter parsed was invalid (in a past or future cycle, instead of the current one). This error will mostly be seen in `stack-stx` or `delegate-stack-stx` failed transactions. +`24` : the `start-burn-height` param was invalid diff --git a/guides-and-tutorials/running-a-signer/README.md b/guides-and-tutorials/running-a-signer/README.md index 121d78ee77..752ccf6d3a 100644 --- a/guides-and-tutorials/running-a-signer/README.md +++ b/guides-and-tutorials/running-a-signer/README.md @@ -10,9 +10,9 @@ If you need to Stack your STX, or have questions about how that process works, c ### Background and High-Level Process -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 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 Stacks node. +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 Stacks node. -This doc will provide instructions on how to set up both using either Docker or using the release binaries available in the [stacks core](https://github.com/stacks-network/stacks-core/releases) repository. +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. @@ -31,11 +31,11 @@ Detailed steps for each of these are laid out below, but this checklist is being **Pre-Launch Setup** * [ ] Ensure your system meets the [minimum system requirements](./#minimum-system-requirements). -* [ ] Acquire Docker and basic knowledge of Stacks accounts, stacking, and the Nakamoto stacking flow (links provided above). +* [ ] Acquire Docker and basic knowledge of Stacks accounts, stacking, and the Nakamoto stacking flow (links provided below). **Preflight Setup** -* [ ] Generate a new private key using stacks-cli. +* [ ] Generate a new private key on testnet using stacks-cli. * [ ] Save the generated account information securely. **Configuration Setup** @@ -66,15 +66,15 @@ Detailed steps for each of these are laid out below, but this checklist is being **Setting Up the Stacks Node** -* [ ] Create a `node-config.toml`, including the following necessary settings: - * connection\_options.sauth\_token +* [ ] Create a `node-config.toml` with the necessary settings: + * auth\_token * events\_observer.endpoint (matching the signer configuration) * [ ] Decide whether to run the Stacks node using Docker or as a binary. * [ ] If using Docker: * [ ] Set up the Docker container with the correct ports and volumes. * [ ] Run the Stacks node Docker container. * [ ] If running as a binary: - * [ ] Build `stacks-core` from source or download the pre-built binary. + * [ ] Download the appropriate binary. * [ ] Run it with the command: `./stacks-node start --config `. **Verify Stacks Node Operation** @@ -85,7 +85,7 @@ Detailed steps for each of these are laid out below, but this checklist is being **Setup Stacks Accounts** * [ ] Set up a “pool operator” wallet in a Stacks wallet (e.g., Leather or Xverse). -* [ ] Fund the pool operator wallet with sufficient STX for transaction fees. +* [ ] Fund the pool operator wallet with STX (testnet) sufficient for transaction fees. * [ ] Share the pool operator wallet’s STX address with delegating parties. * [ ] Fund your signer's STX wallet with enough STX to cover transaction fees (recommend at least 100-200 STX). @@ -100,11 +100,17 @@ These are the **minimum required specs** to be able to run a node and signer, bu * 4 vcpu * 4GB memory if running only a Stacks node and signer * 10GB memory if running Stacks + Bitcoin node + signer -* 1.5+TB storage (1TB for Bitcoin node, 450GB for Stacks node, and 50 GB for signer) +* 1.5+ TB storage (1TB for Bitcoin node, 350GB for Stacks node, and 50 GB for signer) + +#### Signer only + +* 1 cpu +* 256MB memory +* 50GB storage ### Preflight Setup -Before you get your signer set up, you'll need to [generate a new private key](https://docs.stacks.co/stacks-101/accounts#creation). The `stacks-cli` provides a mechanism for quickly generating a new account keychain via a simple CLI interface. The linked guide will show you how to create one of those accounts on testnet. +Before you get your signer set up, you'll need to [generate a new private key on testnet](https://docs.stacks.co/stacks-101/accounts#creation). The `stacks-cli` provides a mechanism for quickly generating a new account keychain via a simple CLI interface. The linked guide will show you how to create one of those accounts on testnet. Once you follow the instructions linked above, be sure to save the information in a secure location, you'll need it in a future step. @@ -120,25 +126,29 @@ Create a new file called `signer-config.toml`. In that file, put the contents fr ### Running the Signer -There are two options for running the signer: Docker and running with a binary. The recommended option is to use Docker. If you want to run as a binary, you will need to either build `stacks-core` from source, or download a signer release binary from the [stacks core releases page](https://github.com/stacks-network/stacks-core/releases). Instructions for how to do this are contained below in the relevant section. +There are two options for running the signer: Docker and building from source. The recommended option is to use Docker. If you want to run as a binary, you will need to build `stacks-core` from source. Instructions for how to do this are contained below in the relevant section. + +{% hint style="warning" %} +Note that at the moment the signer should only be run on testnet using these instructions. The mainnet release is still under development. +{% endhint %} #### Running the Signer with Docker -You can run the signer as a Docker container using the [`blockstack/stacks-signer:3.1.0.0.4.0`](https://hub.docker.com/layers/blockstack/stacks-signer/3.1.0.0.4.0/images/sha256-847f9787e7c9fc3927944d9cb268b2857cbf6c99e33697381b32d3b984d762a7) image. +You can run the signer as a Docker container using the [`blockstack/stacks-signer:3.1.0.0.3.0`](https://hub.docker.com/layers/blockstack/stacks-signer/3.1.0.0.3.0/images/sha256-d250b45bd9df406f9e63d995d2176609a631aad3b191d4f66a925be9cb170af0) image. When running the Docker container, you’ll need to ensure a few things: -* The port configured as the `endpoint` (in the above linked example, “30000”) must be exposed to your Stacks node. Note that this endpoint should not be public, but must be exposed to your Stacks node. -* You’ll need a volume with at least a few GB of available storage that contains the folder your `db_path` is in. In the above example, that would be `/var`. -* You’ll need to mount your `signer-config.toml` file as a volume, noted below with the first `-v` flag. +* The port configured as the `endpoint` (in the above linked example, “30000”) must be exposed to your Stacks node. Note that this endpoint should not be public, but must be exposed to your Stacks node +* You’ll need a volume with at least a few GB of available storage that contains the folder your `db_path` is in. In the above example, that would be /var +* You’ll need to include your `signer-config.toml` file as noted below with the first `-v` flag -An example command for running the Docker image with `docker run` is shown below. +An example command for running the Docker image with ”`docker run`” is shown below. -Be sure to replace the `STX_SIGNER_PATH` with the correct path to your config file and where you want to install and run the signer. In this example it will be done in the current directory. +Be sure to replace the `STX_SIGNER_PATH` with the correct path to your config file and where you want to install and run the signer. In this example it will be doing so in the current directory. ```bash IMG="blockstack/stacks-signer" -VER="3.1.0.0.4.0" +VER="3.1.0.0.3.0" STX_SIGNER_PATH="./" STX_SIGNER_DATA="$STX_SIGNER_PATH/data" STX_SIGNER_CONFIG="$STX_SIGNER_PATH/signer-config.toml" @@ -164,7 +174,7 @@ For example, if you are running on M1 Mac, you would add `--platform=linux/amd64 Or, with a custom Dockerfile: ```docker -FROM blockstack/stacks-signer:3.1.0.0.4.0 +FROM blockstack/stacks-signer:3.1.0.0.3.0 COPY signer-config.toml /config.toml EXPOSE 30000 CMD ["stacks-signer", "run", "--config", "/config.toml"] @@ -236,34 +246,34 @@ The important aspects that you’ll need to change are: * `working_dir`: a directory path where the node will persist data * `auth_token`: an authentication token that your signer uses to authenticate certain requests to your node. This must match the value you used as `auth_password` in the signer’s configuration. -* `events_observer.endpoint`: This is the host (IP address and port) where your signer is configured to listen for events. An example string would be ”`127.0.0.1:30000`” or ”`stacks-signer.local:30000`” +* `events_observer.endpoint`: This is the host (IP address and port) where your signer is configured to listen for events. An example string would be ”`127.0.0.1:30000`” or ”`my-signer.local:30000`” #### Start with an archive -It will be much faster to start with an archive of the chain state rather than syncing from genesis. +If you are running your Stacks node on the primary testnet, it will be much faster to start with an archive of the chain state rather than syncing from genesis. -Archives can be found at [https://archive.hiro.so](https://archive.hiro.so). For the Stacks node mainnet, the latest snapshot can be found at [https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.gz](https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.gz). You can also [browse all mainnet snapshots](https://archive.hiro.so/mainnet/stacks-blockchain/). +Archives can be found from [https://archive.hiro.so](https://archive.hiro.so). For the Stacks node testnet, the latest snapshot can be found at [https://archive.hiro.so/testnet/stacks-blockchain/testnet-stacks-blockchain-latest.tar.gz](https://archive.hiro.so/testnet/stacks-blockchain/testnet-stacks-blockchain-latest.tar.gz). You can also [browse all testnet snapshots](https://archive.hiro.so/testnet/stacks-blockchain/). You’ll want to download this on the same machine that will run the Stacks node. One way to do this is: ``` -curl -# https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.gz -o stacks-snapshot.tar.gz +curl -# https://archive.hiro.so/testnet/stacks-blockchain/testnet-stacks-blockchain-latest.tar.gz -o stacks-snapshot.tar.gz tar -zxvf stacks-snapshot.tar.gz ``` -This will decompress the snapshot and create a `mainnet` folder in the same place that you downloaded the archive. +This will decompress the snapshot and create a `xenon` folder in the same place that you downloaded the archive. -For the Stacks node to use this archive, you must specify `working_dir` in your config file to be the place where you can find the `mainnet` folder. +For the Stacks node to use this archive, you must specify `working_dir` in your config file to be the place where you can find the `xenon` folder. For example: -* The snapshot is available at /Users/blah/mainnet +* The snapshot is available at /Users/blah/xenon * You will set working\_dir to equal ”/Users/blah” - * Note that the string does not include the `mainnet` part + * Note that the string does not include the “xenon” part #### Run a Stacks Node with Docker -You can run the Stacks node as a Docker container using the `blockstack/stacks-core` image, currently on [version 3.1.0.0.4](https://hub.docker.com/layers/blockstack/stacks-core/3.1.0.0.4/images/sha256-9fd51e4d2af004d44ca6de5b889390a12e2615cb3f1f13e5ac1bfed849aa3bba). When running the Docker container, you’ll need to ensure a few things: +You can run the Stacks node as a Docker container using the `blockstack/stacks-core` image, currently on [version 3.1.0.0.3](https://hub.docker.com/layers/blockstack/stacks-core/3.1.0.0.3/images/sha256-8ac612356f4bb60f69ddb81676778907b484c0ab43951b91c3476a6cd41476a1). When running the Docker container, you’ll need to ensure a few things: * The port configured for `p2p_bind` must be exposed to the internet * The port configured for `rpc_bind` must be accessible by your signer @@ -274,7 +284,7 @@ An example for running the node’s Docker image with docker run is below. Be su ```bash IMG="blockstack/stacks-core" -VER="3.1.0.0.4" +VER="3.1.0.0.3" STX_NODE_CONFIG="./node-config.toml" docker run -d \ @@ -292,14 +302,14 @@ docker run -d \ Or, using a custom Dockerfile: ```docker -FROM blockstack/stacks-core:3.1.0.0.4 +FROM blockstack/stacks-core:3.1.0.0.3 COPY node-config.toml /config.toml EXPOSE 20444 EXPOSE 20443 CMD ["stacks-node", "start", "--config", "/config.toml"] ``` -If when running your node you get a connection refused error that looks like this, you may need to point your `event_observer`'s `endpoint` field to the Docker signer container. +If when running your node you get a connection refused error that looks like this, you may need to point to Docker. First, be sure that you have the proper entry point specified in your `node-config.toml` file. @@ -313,7 +323,7 @@ If you do not want to use Docker, you can alternatively run your stacks node as Official binaries are available from the [Stacks Core releases page on Github](https://github.com/stacks-network/stacks-core/releases). Each release includes pre-built binaries. Download the ZIP file for your server’s architecture and decompress it. Inside of that folder is a `stacks-node` binary. -You can start the binary with the following command (be sure to replace node-config.toml with the actual path of your config file): +You can start the binary with: ```bash ./stacks-node start --config node-config.toml @@ -348,7 +358,7 @@ As a signer you’ll need to fund and manage two Stacks accounts: 2. Your signer’s wallet {% hint style="warning" %} -For testing, make sure that you are using testnet, and not mainnet STX. You can change network settings within your wallet, and testnet STX can be [requested from a faucet](https://explorer.hiro.so/sandbox/faucet?chain=testnet). +For testing, make sure that you are using testnet, and not mainnet, STX. You can change network settings within your wallet, and testnet STX can be [requested from a faucet](https://explorer.hiro.so/sandbox/faucet?chain=testnet). {% endhint %} #### Setup Your Pool Operator Wallet @@ -357,4 +367,4 @@ You can set up your pool operator wallet using any Stacks wallet, such as [Leath Once your wallet has been created, you’ll need to fund it with enough STX to cover transaction fees. For testnet, you can use a [faucet exposed by the Stacks Explorer](https://explorer.hiro.so/sandbox/faucet?chain=testnet). -Finally, share this wallet’s STX address with the parties that will be delegating STX to you. For improved user experience, you might want to use the helper contract that allows to specify a btc address for stackers ([pox4-pools](https://explorer.hiro.so/txid/SP001SFSMC2ZY76PD4M68P3WGX154XCH7NE3TYMX.pox4-pools?chain=mainnet)) and to add your pool to [earn.leather.io](https://earn.leather.io). +Finally, share this wallet’s STX address with the parties that will be delegating STX to you. For improved user experience, you might want to use the helper contract that allows to specify a btc address for stackers ([pox4-pools](https://explorer.hiro.so/txid/SP001SFSMC2ZY76PD4M68P3WGX154XCH7NE3TYMX.pox4-pools?chain=mainnet)) and to add your pool to [lockstacks.com](https://lockstacks.com). diff --git a/guides-and-tutorials/running-a-signer/how-to-monitor-signer.md b/guides-and-tutorials/running-a-signer/how-to-monitor-signer.md index 26eb99e91d..742720323d 100644 --- a/guides-and-tutorials/running-a-signer/how-to-monitor-signer.md +++ b/guides-and-tutorials/running-a-signer/how-to-monitor-signer.md @@ -22,7 +22,7 @@ Once done, access your dashboard and: 2. "Add new connection", and 3. select "Hosted Prometheus metrics". 4. Now select "Via Grafana Alloy", then -5. On step 2, select "Run Grafana Alloy" to generate an API token. +5. on step 2, select "Run Grafana Alloy" to generate an API token. Note the token `GCLOUD_RW_API_KEY` and the parameters `GCLOUD_HOSTED_METRICS_URL` and `GCLOUD_HOSTED_METRICS_ID`, we will use them later. @@ -47,7 +47,8 @@ metrics_endpoint = "127.0.0.1:30001" prometheus_bind = "127.0.0.1:9153" ``` -The pre-compiled binaries already include the monitoring feature. However, if you are compiling the application binaries yourself, remember to enable the Cargo feature `monitoring_prom` while building them, for example: +If you compile the application binaries yourself, remember to enable the Cargo +feature `monitoring_prom` while building them, for example: ```bash cargo build --features monitoring_prom,slog_json --release diff --git a/guides-and-tutorials/running-a-signer/how-to-read-signer-logs.md b/guides-and-tutorials/running-a-signer/how-to-read-signer-logs.md index d106e2c1c7..c2ef30efd5 100644 --- a/guides-and-tutorials/running-a-signer/how-to-read-signer-logs.md +++ b/guides-and-tutorials/running-a-signer/how-to-read-signer-logs.md @@ -20,7 +20,7 @@ Let's go through some of the common log messages you might see, what they mean, #### Signer uninitialized or not registered -If you get a message like the following, saying that your signer is uninitialized, it means that your signer is not registered for the current or upcoming reward cycle (or the burnchain block height is not yet at the second block in the prepare phase) for the signer to know if it is registered. Your signer is running successfully, there is just another action you need to take. +If you get a message like the following saying your signer is uninitialized, that means that it has not registered for the current or upcoming reward cycle (or the burnchain block height is not yet at the second block in the prepare phase) for the signer to know if it is registered. Your signer is running successfully, there is just another action you need to take. `Signer spawned successfully. Waiting for messages to process... INFO [1711088054.872542] [stacks-signer/src/runloop.rs:278] [signer_runloop] Running one pass for signer ID# 0. Current state: Uninitialized` @@ -32,7 +32,7 @@ WARN [1712003997.160121] [stacks-signer/src/runloop.rs:247] [signer_runloop] Sig At this point if you want your signer to do something you need someone to either delegate or you need to stack on your own for an upcoming reward cycle. -For more on this, be sure to check out the [How to Stack](../stack-stx/stacking-flow.md) doc. +For more on this, be sure to check out the [How to Stack ](../stack-stx/stacking-flow.md)doc. ### Informational diff --git a/guides-and-tutorials/running-a-signer/opsec-best-practices.md b/guides-and-tutorials/running-a-signer/opsec-best-practices.md index 6293f0da82..c17c2a7e6a 100644 --- a/guides-and-tutorials/running-a-signer/opsec-best-practices.md +++ b/guides-and-tutorials/running-a-signer/opsec-best-practices.md @@ -23,7 +23,7 @@ An obvious attack vector is a direct attack on the system running the stacks-sig **Some countermeasures that can help mitigate this vector include:** -1. **Run the stacks-signer on a separate system from the stacks-node.** This is important, as the IP addresses of systems running the stacks-signer cannot be trivially enumerated, but the same is not true for systems running stacks-node, due to the fact that stacks-node systems participate in the peer to peer network. If an attacker can't find your stacks-signer, they can't attack it (directly). It’s best practice to ensure that the stacks-node and stacks-signer communicate only over trusted networks, ideally using localhost (127.0.0.1) or a secure private subnet. While running the stacks-signer on a separate system is an option, it’s not necessary for security. Instead, running both on the same virtual machine within a private network, with traffic firewalled to allow only incoming peer-to-peer (P2P) connections (port 20444), provides a secure and easier setup. This minimizes the risk of exposure to attacks while avoiding the complexity of managing multiple systems. +1. **Run the stacks-signer on a separate system from the stacks-node.** This is important, as the IP addresses of systems running the stacks-signer cannot be trivially enumerated, but the same is not true for systems running stacks-node, due to the fact that stacks-node systems participate in the peer to peer network. If an attacker can't find your stacks-signer, they can't attack it (directly). It’s best practice to ensure that the stacks-node and stacks-signer communicate only over trusted networks, ideally using localhost (127.0.0.1) or a secure private subnet. While running the stacks-signer on a separate system is an option, it’s not necessary for security. Instead, running both on the same virtual machine within a private network, with traffic firewalled to allow only incoming peer-to-peer (P2P) connections (port 2044), provides a secure and easier setup. This minimizes the risk of exposure to attacks while avoiding the complexity of managing multiple systems. 2. **Run the stacks-signer as a separate user from the stacks-node**. This is helpful in situations where due to resource constraints, it's not possible to separate the stacks-signer and stacks-node deployments onto separate workloads. Run the stacks-signer as a separate user from the stacks-node to enhance security, especially when resource constraints prevent deploying them on separate systems. The key here is ensuring that each user has exclusive ownership and access to its respective configuration files. For example, the user running the signer binary (e.g., signer) should own the signer’s config file, with permissions set restrictively to prevent other users from reading it. The same principle applies to the stacks-node user. This setup ensures that only the appropriate processes can access sensitive configuration details. 3. **Harden the systemd configuration for the stacks-signer.** Hardening systemd can help mitigate the blast radius from an attack that successfully gets control of the stacks-signer process. An example stacks-signer.service systemd unit is below. Specifically, this systemd unit prevents certain filesystem writes (which can prevent an attacker from gaining persistence). Read more about [systemd hardening](https://www.ctrl.blog/entry/systemd-service-hardening.html). diff --git a/guides-and-tutorials/running-a-signer/signer-quickstart.md b/guides-and-tutorials/running-a-signer/signer-quickstart.md index c6e03e594a..503e0d7e07 100644 --- a/guides-and-tutorials/running-a-signer/signer-quickstart.md +++ b/guides-and-tutorials/running-a-signer/signer-quickstart.md @@ -3,20 +3,20 @@ {% hint style="info" %} ### **Current Signer and Stacks Node Versions** -**Stacks Signer - 3.1.0.0.4.0** +**Signer - 3.1.0.0.3.0** -* [Docker Image](https://hub.docker.com/layers/blockstack/stacks-signer/3.1.0.0.4.0/images/sha256-847f9787e7c9fc3927944d9cb268b2857cbf6c99e33697381b32d3b984d762a7) -* [GitHub Release](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.4.0) +* [Docker Image](https://hub.docker.com/layers/blockstack/stacks-signer/3.1.0.0.3.0/images/sha256-d250b45bd9df406f9e63d995d2176609a631aad3b191d4f66a925be9cb170af0) +* [GitHub Release](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.3.0) -**Stacks Node - 3.1.0.0.4** +**Stacks Node - 3.1.0.0.3** -* [Docker Image](https://hub.docker.com/layers/blockstack/stacks-core/3.1.0.0.4/images/sha256-9fd51e4d2af004d44ca6de5b889390a12e2615cb3f1f13e5ac1bfed849aa3bba) +* [Docker Image](https://hub.docker.com/layers/blockstack/stacks-core/3.1.0.0.3/images/sha256-8ac612356f4bb60f69ddb81676778907b484c0ab43951b91c3476a6cd41476a1) * [GitHub Release](https://github.com/stacks-network/stacks-core/releases/latest) {% endhint %} -If you want to get up and running as an active signer as quickly as possible, here is a list of the commands you need to run and actions to take. +If you want to get up and running as an active signer as quickly as possible. Here is a list of the commands you need to run and actions to take. If you are not familiar with how signing works yet, be sure to check out the [Stackers and Signing](../../concepts/block-production/stackers-and-signing.md) concept guide. @@ -83,7 +83,7 @@ From this file, you'll need the `privateKey` value. ### Download the stacks-signer binary -Official binaries are available from the [Stacks Core releases page on Github](https://github.com/stacks-network/stacks-core/releases). Each release includes pre-built binaries. Download the [latest signer release ZIP file](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.4.0) for your server’s architecture and decompress it. Inside of that folder is a `stacks-signer` binary. +Official binaries are available from the [Stacks Core releases page on Github](https://github.com/stacks-network/stacks-core/releases). Each release includes pre-built binaries. Download the [latest signer release ZIP file](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.3.0) for your server’s architecture and decompress it. Inside of that folder is a `stacks-signer` binary. Assuming a `Linux x64 glibc` machine, the commands to download and uncompress the signer binary look like this: @@ -92,7 +92,7 @@ Assuming a `Linux x64 glibc` machine, the commands to download and uncompress th cd ~/stacks-signer # Download the signer binary zip -wget https://github.com/stacks-network/stacks-core/releases/download/signer-3.1.0.0.4.0/linux-glibc-x64.zip +wget https://github.com/stacks-network/stacks-core/releases/download/signer-3.1.0.0.3.0/linux-glibc-x64.zip # Unzip the signer binary archive unzip linux-glibc-x64.zip @@ -154,7 +154,7 @@ To ensure the signer has been set up correctly, you can run the following comman ~/stacks-signer/stacks-signer --version # Output: -stacks-signer stacks-signer signer-3.1.0.0.4.0 (release/signer-3.1.0.0.4.0:43d4ee9, release build, linux [x86_64]) +stacks-signer stacks-signer signer-3.1.0.0.3.0 (release/signer-3.1.0.0.3.0:309b8d5, release build, linux [x86_64]) # Verify the config file ~/stacks-signer/stacks-signer check-config -c ~/stacks-signer/signer-config.toml @@ -189,7 +189,7 @@ We have created guides for running both a [full Bitcoin node](../nodes-and-miner ### Download the stacks-node binary -Official binaries are available from the [Stacks Core releases page on Github](https://github.com/stacks-network/stacks-core/releases). Each release includes pre-built binaries. Download the [latest node release ZIP file](https://github.com/stacks-network/stacks-core/releases/tag/3.1.0.0.4) for your server’s architecture and decompress it. Inside of that folder is a `stacks-node` binary. +Official binaries are available from the [Stacks Core releases page on Github](https://github.com/stacks-network/stacks-core/releases). Each release includes pre-built binaries. Download the [latest node release ZIP file](https://github.com/stacks-network/stacks-core/releases/tag/3.1.0.0.3) for your server’s architecture and decompress it. Inside of that folder is a `stacks-node` binary. Assuming a `Linux x64 glibc` machine, the commands to download and uncompress the node binary look like this: @@ -198,7 +198,7 @@ Assuming a `Linux x64 glibc` machine, the commands to download and uncompress th cd ~/stacks-node # Download the node binary zip -wget https://github.com/stacks-network/stacks-core/releases/download/3.1.0.0.4/linux-glibc-x64.zip +wget https://github.com/stacks-network/stacks-core/releases/download/3.1.0.0.3/linux-glibc-x64.zip # Unzip the node binary archive unzip linux-glibc-x64.zip @@ -211,7 +211,7 @@ Create the configuration file required to start the node (be sure to replace `
@@ -85,11 +85,11 @@ If these manual transactions are confirmed, and the signer has enough STX associ #### Solo stacking -The workflow for solo stackers is simpler, because there are less stacking transactions that need to be made. +The workflow for solo stackers is more simple, because there are less stacking transactions that need to be made. For solo stacking, the only transaction that needs to be made is `stack-stx`. Included in this transaction’s payload is the signer’s public key. -In order for the signer to be registered in reward cycle N+1, the `stack-stx` transaction must be confirmed during the first 2000 blocks of reward cycle N. The last 100 blocks of cycle N (the “prepare phase”) is where DKG occurs. +In order for the signer to be registered in reward cycle N+1, the `stack-st`x transaction must be confirmed during the first 2000 blocks of reward cycle N. The last 100 blocks of cycle N (the “prepare phase”) is where DKG occurs. The start of the prepare phase is when Stacks nodes determine the official signer set of the next reward cycle. @@ -97,7 +97,7 @@ The start of the prepare phase is when Stacks nodes determine the official signe The workflow for delegated signers is more complex, because it requires more transactions. -This workflow is explained more in detail in the [operate a pool](operate-a-pool.md) guide, but the high-level workflow is: +This workflow is explained more in a previous section, but the high-level workflow is: 1. Stackers delegate their STX to a pool operator 2. The pool operator makes `delegate-stack-stx` transactions to “approve” specific stackers. This needs to be called for every individual stacker that delegates to them. @@ -112,3 +112,7 @@ During the prepare phase before a reward cycle, Stacks nodes automatically deter The signer software is continuously polling the Stacks node to see if it is registered for a cycle. If the signer software finds that it is registered (by matching its public key to the signers stored in the `signers` contract) it begins performing its duties as a signer. During the prepare phase, the signers perform DKG through StackerDB messages. Once an aggregate public key is determined, the signer automatically makes a `vote-for-aggregate-key` transaction. No out-of-band action is needed to be taken for this to occur. + +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. diff --git a/guides-and-tutorials/stack-stx/operate-a-pool.md b/guides-and-tutorials/stack-stx/operate-a-pool.md index bec2afa0a6..4f92ef079b 100644 --- a/guides-and-tutorials/stack-stx/operate-a-pool.md +++ b/guides-and-tutorials/stack-stx/operate-a-pool.md @@ -8,15 +8,15 @@ The guide below applies to those who want to operate a pool, meaning they want t For pool operators, the flow is a bit different than solo stacking. Remember that as a pool operator, other stackers are delegating their STX to you to stack on behalf of them. This additional role adds a couple of extra steps to your stacking flow if operating as a pool operator. -Similar to the changes to solo Stacking, the big difference for delegation flows is the inclusion of signer keys and signatures. Because pool operators need to make transactions to “finalize” a delegation, these new arguments add new complexities to the stacking flow. +Similar to the changes to solo Stacking, the big difference for delegation flows is the inclusion of signer keys and signatures. Because signers need to make transactions to “finalize” a delegation, these new arguments add new complexities to the signer. #### Delegator initiates delegation {% hint style="info" %} -This step is not required to apply to pool operators/signers. It is included here to illustrate the end-to-end flow, but if you are operating as a pool operator/signer you will not have to perform this step. Instead, users delegate their STX to you as the pool operator. +This step does not apply to pool operators/signers. It is included here to illustrate the end-to-end flow, but if you are operating as a pool operator/signer you will not perform this step. Instead, users delegate their stx to you as the pool operator. {% endhint %} -The first step, where the delegator sets up their delegation to a pool operator, is to call `delegate-stx`. This function does not directly delegate the STX, but rather allows the pool operator to issue the stacking lock on behalf of the user calling this function. You can think of calling this function as the delegator giving permission to the pool operator to stack on their behalf. +The first step, where the delegator sets up their delegation to a pool operator, is to call `delegate-stx`. This function does not directly delegate the stx, but rather allows the pool operator to issue the stacking lock on behalf of the user calling this function. You can think of calling this function as the delegator giving permission to the pool operator to stack on their behalf.
@@ -74,14 +74,14 @@ The first step, where the delegator sets up their delegation to a pool operator, The arguments here are unchanged from previous versions of PoX: -* Amount: Denoted in uSTX (1 STX = 1,000,000 uSTX) +* Amount: Denoted in ustx (1 stx = 1,000,000 ustx) * Delegate to: the STX address of the pool operator they're delegating to. Note that this is different from the “signer key” used. Instead, this is the STX address that is used to make PoX transactions. -* Until burn height: an optional argument representing the BTC block height when the delegation expires. If none is used, the delegation permission expires only when explicitly revoked. +* Until burn height: an optional argument when the delegation expires. If none is used, the delegation permission expires only when explicitly revoked. * Pox Address: an optional BTC address that, if specified, the signer must use to accept this delegation #### Pool operator “activates” the delegation -Just as in the older PoX contract, after a delegator calls the `delegate-stx` function, the pool operator calls `delegate-stack-stx` to commit the delegator’s STX. +Just as in the current PoX contract, after a delegator calls the `delegate-stx` function, the pool operator calls `delegate-stack-stx` to commit the delegator’s STX.
@@ -164,25 +164,25 @@ Just as in the older PoX contract, after a delegator calls the `delegate-stx` fu The arguments are: * Stacker: the STX address of the delegator -* Amount: denoted in uSTX (1 STX = 1,000,000 uSTX) -* Pox Address: The BTC address of the pool operator where they will receive the BTC rewards. If the delegator has set his own BTC address in the `delegate-stx` call, this address will have to be the same one, otherwise the contract call will fail. -* Start burn height: The BTC block height in which delegation can begin. This field is used to ensure that an old transaction intended for an earlier cycle will fail, and also prevents callers from "post-dating" the call to a future cycle. The best option here is to add 1 or 2 to the current BTC block height when you initiate this transaction. Note that the delegation will not actively be stacked at this block height, but whatever reward cycle is passed in the aggregation commit function (explained below). -* Lock period: number of cycles to lock for. If the delegator provided the until burn height argument, then the end of these cycles cannot be past the expiration provided. The maximum lock period that a pool operator can provide in this function call is 12. +* Amount: denoted in ustx (1 stx = 1,000,000 ustx) +* Pox Address: The BTC address of the pool operator where they will receive the BTC rewards +* Start burn height: The BTC block height in which delegation can begin. This field is used to ensure that an old transaction intended for an earlier cycle will fail, and also prevents callers from "post-dating" the call to a future cycle. The best option here is to add 1 or 2 to the current block height when you initiate this transaction. Note that the delegation will not actively begin at this block height, but whatever reward cycle is passed in the aggregation commit function (below). +* Lock period: number of cycles to lock for. If the delegator provided the until burn height argument, then the end of these cycles cannot be past the expiration provided. Max lock period is 12 This step also allows the pool operator to proactively choose which Stackers they’ll accept delegation from. For “closed” pools, the pool operator will only call this function for approved Stackers. It is up to each pool operator who runs a closed pool to implement this process. -This step can be repeated for multiple Stackers before going to the next step. +This step can happen for many Stackers before going to the next step. {% hint style="info" %} -If you look at the function source code, you'll see that the `delegate-stack-stx` function sets the stacker's first reward cycle to be the _next_ reward cycle. +If you look at the function source code, you'll see that the `delegate-stack-stx` function sets the stacker's reward cycle to be the _next_ reward cycle. -When generating your signature and your `stack-aggregation-commit-indexed` transaction, you'll want to make sure that the reward cycles match. +When generating your signature and your `stack-aggregation-commit` transaction, you'll want to make sure that the reward cycles match. -So if you are in cycle 557 when you call the `delegate-stack-stx` function, you'll want to pass in cycle 558 or higher when you generate your signature and your `stack-aggregation-commit-indexed` transaction. +So if you are in cycle 557 when you call the `delegate-stack-stx` function, you'll want to pass in cycle 558 when you generate your signature and your `stack-aggregation-commit` transaction. -With `stack-aggregation-commit-indexed`, the `reward-cycle` arg is saying "I'm commiting these stacks to be stacked in cycle N". But the `delegate-stack-stx` transaction gets you setup for next cycles, aka 558 and higher. +With `stack-aggregation-commit`, the `reward-cycle` arg is saying "I'm commiting these stacks to be stacked in cycle N". But the `delegate-stack-stx` transaction gets you setup for next cycle, aka 558. -Also make sure that, when you generate your signature, you use 558 or higher as the reward cycle. In solo stacking methods, you use the current reward cycle in the signature, but not for `stack-aggregation-commit-indexed`. This is because with `stack-aggregation-commit-indexed` you can commit stacks for future cycles, not just the N+1 cycle. +Also make sure that, when you generate your signature, you use 558 as the reward cycle. in solo stacking methods, you use the current reward cycle in the signature, but not for `stack-aggregation-commit`. This is because with `stack-aggregation-commit` you can commit stacks for future cycles, not just the n+1 cycle {% endhint %} #### Pool operator “commits” delegated STX @@ -190,7 +190,7 @@ Also make sure that, when you generate your signature, you use 558 or higher as The next step is for the pool operator to call `stack-aggregation-commit-indexed`. {% hint style="info" %} -In the contract source code, you'll notice a similarly named function called `stack-aggregation-commit`. This is a legacy function that makes it difficult to increase the stacking amount, as it does not return the reward index of the stacking slot, which is required in order to call the `stack-aggregation-increase` function. We recommend using `stack-aggregation-commit-indexed`. +In the contract source code, you'll notice a similarly named function called `stack-aggregation-commit`. This is a legacy function that makes it difficult to increas the stacking amount. We recommend using `stack-aggregation-commit-indexed`. {% endhint %}
@@ -199,7 +199,7 @@ In the contract source code, you'll notice a similarly named function called `st Note that the `stack-aggregation-commit-indexed` function wraps the `inner-stack-aggregation-commit` function. The wrapped inner function is included here. -Check out the [deployed contract](https://explorer.hiro.so/txid/SP000000000000000000002Q6VF78.pox-4?chain=mainnet) to see the flow of contract calls. +Check out the [deployed contract](https://explorer.hiro.so/txid/0xaf8857ee1e4b8afc72f85b85ad785e1394672743acc63f4df79fb65b5e8b9d2a?chain=testnet) to see the flow of contract calls. ```clojure ;; Commit partially stacked STX and allocate a new PoX reward address slot. @@ -258,34 +258,32 @@ Check out the [deployed contract](https://explorer.hiro.so/txid/SP00000000000000
-At this point, the STX are committed to the pool operator, and the pool operator has some “aggregate balance” of committed STX. The pool operator is not actually eligible for reward slots and signer initialization until this step is finished. +At this point, the STX are committed to the pool operator, and the pool operator has some “aggregate balance” of committed STX. The pool operator is not actually eligible for rewards and signer slots until this step is called. -The pool operator cannot call this function until the total number of STX committed is larger than the minimum threshold required to Stack. This minimum stacking threshold is a function of the total number of STX stacked divided by the available number of reward slots. +The pool operator cannot call this until the total number of STX committed is larger than the minimum threshold required to Stack. This minimum stacking threshold is a function of the total number of liquid STX. {% hint style="info" %} -This number varies and can be found by visiting the pox endpoint of Hiro's API at [https://api.hiro.so/v2/pox](https://api.hiro.so/v2/pox) and looking at the `min_threshold_ustx` field. (1 STX = 1,000,000 uSTX). +This number varies and can be found by visiting the pox endpoint of Hiro's API at [https://api.testnet.hiro.so/v2/pox](https://api.testnet.hiro.so/v2/pox) and looking at the `min_threshold_ustx` field. (1 STX = 1,000,000 uSTX). {% endhint %} -Once the threshold is reached, the pool operator calls `stack-aggregation-commit-indexed`. This is the point where you as the pool operator must provide your signer key and signer key signature. The arguments are: +Once the threshold is reached, the pool operator calls `stack-aggregation-commit`. This is the point where you as the pool operator must provide your signer key and signer key signature. The arguments are: * Pox Address: the BTC address to receive rewards -* Reward-cycle: a reward cycle in the future (see the note above on passing the correct reward cycle) -* Signer public key: the public key of your signer (remember that this may be different than the address you are using to operate the pool, but this step is how you associate the two together) -* Signer signature: A signature proving control of your signing key (details on how to do this are below) -* Max Amount: This parameter is used to validate the signer signature provided. It represents the maximum number of uSTX (1 stx = 1,000,000 uSTX) that can be stacked in this transaction. -* Auth Id: This parameter is used to validate the signer signature provided. It is a random integer that prevents the re-use of this particular signer signature. +* Reward-cycle: the current reward cycle (see the note above on passing the correct reward cycle here) +* Signer key: the public key of your signer (remember that this may be different than the address you are using to operate the pool, but this step is how you associate the two together) +* Signer signature: Your generated signer signature (details on how to do this are below) {% hint style="info" %} In the Definitions and Roles section in the previous document, we described how the pool operator and signer may be the same entity, but not necessarily have the same address. -Signers who are also pool operators and wish to have STX delegated to them should have a separate keychain associated with their pool operator account in order to make Stacking transactions such as `delegate-stack-stx` and `stack-aggregation-commit-indexed`. +Signers who are also pool operators and have stx delegated to them also need a separate keychain to make Stacking transactions such as `delegate-stack-stx` listed earlier. -So, as a signing entity operating a pool, you should have two accounts: +So as a signing entity operating a pool, you will have two accounts: -* Your pool operator account, which you will use to conduct all of the stacking operations we have covered here. -* Your signer account, which is what you used to set up your signer. This signer public key is what you will pass in to the above aggregation commit function, and is also the key you will use when generating your signer signature. +* Your pool operator account, which you will use to conduct all of the stacking operations we have covered here +* Your signer account, which is what you used to set up your signer. This signer public key is what you will pass in to the above aggregation commit function, and is also the key you will use when generating your signer signature -If you are operating as a signer and a pool operator, you should have a separate key because you might need to rotate your signer key when necessary. +If you are operating as a signer and a pool operator, you'll need a separate key because you need to have the ability to rotate your signer key when necessary. The PoX contract is designed to support rotating the signer key without needing your Stackers to un-stack and re-stack later. You cannot rotate a pool operator key without needing to wait for all delegated Stackers to un-stack and finally re-stack to the new pool operator address. @@ -298,7 +296,7 @@ To act as a signer, each step up to this point must be taken before the prepare #### Pool operator increases amount committed -Even after the signer commits to a certain amount of STX in the previous step, the signer can increase this amount once more delegations are received. The initial steps must be taken for each Stacker (`delegate-stx` and then `delegate-stack-stx`), and then `stack-aggregation-increase` can be called with the index returned from the first `stack-aggregation-commit-indexed` call and a new signature. +Even after the signer commits to a certain amount of STX in the previous step, the signer can increase this amount once more delegations are received. The initial steps must be taken for each Stacker (`delegate-stx` and then `delegate-stack-stx`), and then `stack-aggregation-increase` can be called with the index returned from the first `stack-aggregation-commit-indexed` call and a new signature..
@@ -388,12 +386,12 @@ Even after the signer commits to a certain amount of STX in the previous step, t ### Step by Step Stacking Guide -Now that you are familiar with the overall stacking flow and the different roles played, let's dive into the step-by-step guide for actually conducting the stacking process as a pool operator. +Now that you are familiar with the overall stacking flow and the different roles played, let's dive into the step-by-step guide for actually conducting the stacking process as apool operator. {% hint style="info" %} -There are several ways you can go about stacking. This guide will cover using [Leather Earn](https://earn.leather.io), which is a stacking web application and the simplest option. +There are several ways you can go about stacking. This guide will cover using Lockstacks, which is a stacking web application and the simplest option. -Additionally, you can choose to call the stacking functions directly from the [deployed contract](https://explorer.hiro.so/txid/SP000000000000000000002Q6VF78.pox-4?chain=mainnet) in the explorer. +Additionally, you can choose to call the stacking functions directly from the [deployed contract](https://explorer.hiro.so/txid/0xaf8857ee1e4b8afc72f85b85ad785e1394672743acc63f4df79fb65b5e8b9d2a?chain=testnet) in the explorer. The fields and process will be the same, but the UI will differ. @@ -418,60 +416,57 @@ In the note above about pool operator vs signer keys, this corresponds to your s #### Overview of signer keys and signatures -The main difference with Stacking in Nakamoto is that the Signer needs to include new parameters in their Stacking transactions. These are Clarity transactions that pool operators will call when interacting with the `pox-4.clar` contract. Interacting with that contract is how you as a pool operator actually stack the delegated STX tokens. +The main difference with Stacking in Nakamoto is that the Signer (either solo Stacker or signer running a pool) needs to include new parameters in their Stacking transactions. These are Clarity transactions that pool operators will call when interacting with the `pox-4.clar` contract. Interacting with that contract is how you as a pool operator actually stack your STX tokens. + +Here is an overview of the fields you will need to pass. We'll cover how to get and pass these fields as we dive further into this doc. {% hint style="info" %} -The current pox-4 contract address can be found by visiting the following endpoint of the Hiro API: [https://api.hiro.so/v2/pox](https://api.hiro.so/v2/pox). +The current pox-4 contract address can be found by visiting the following endpoint of the Hiro API: [https://api.testnet.hiro.so/v2/pox](https://api.testnet.hiro.so/v2/pox). -You can then visit the [Stacks Explorer](https://explorer.hiro.so) to view the contract and pass in the contract id. +You can then visit the [Nakamoto Explorer](https://explorer.hiro.so/?chain=testnet) to view the contract and pass in the contract id. You may want to review this contract to familiarize yourself with it. {% endhint %} -Here is an overview of the new fields you will need to pass in some of your stacking transactions: - -1. `signer-key`: the public key that corresponds to the `stacks_private_key` your signer is using. -2. `signer-signature`: a signature that demonstrates that you actually control your `signer-key`. Because signer keys need to be unique, this is also a safety check to ensure that other Stackers can’t use someone else’s signer key. -3. `max-amount`: The maximum amount of uSTX (1 STX = 1,000,000 uSTX) that can be locked in the transaction that uses this signature. For example, if calling `stack-aggregation-increase`, then this parameter dictates the maximum amount of uSTX that can be used to add more locked STX to the already committed position. -4. `auth-id`: a random integer that prevents re-use of a particular signature, similar to how nonces are used with transactions. +1. `signer-key`: the public key that corresponds to the `stacks_private_key` your signer is using +2. `signer-signature`: a signature that demonstrates that you actually controls your `signer-key`. Because signer keys need to be unique, this is also a safety check to ensure that other Stackers can’t use someone else’s public key +3. `max-amount`: The maximum amount of ustx (1 stx = 1,000,000 ustx) that can be locked in the transaction that uses this signature. For example, if calling `stack-increase`, then this parameter dictates the maximum amount of ustx that can be used to add more locked STX +4. `auth-id`: a random integer that prevents re-use of a particular signature, similar to how nonces are used with transactions -Signer signatures are signatures created using a particular signer key. They demonstrate that the controller of that signer key is allowing a Stacker to use their signer's public key. The signer signature’s message hash is created using the following data: +Signer signatures are signatures created using a particular signer key. They demonstrate that the controller of that signer key is allowing a Stacker to use their signing key. The signer signature’s message hash is created using the following data: -* `method`: a string that indicates the Stacking method that is allowed to utilize this signature. The valid options are `stack-stx`, `stack-extend`, `stack-increase`, `agg-commit` (for `stack-aggregation-commit-indexed`) and `agg-increase` (for `stack-aggregation-increase`). -* `max-amount`: described above. -* `auth-id`: described above. -* `period`: a value between 1 and 12, which indicates how long the Stacker is allowed to lock their STX for in this particular Stacking transaction. For `agg-commit`, this must be equal to 1. -* `reward-cycle`: This represents the reward cycle in which the Stacking transaction can be confirmed (for `stack-aggregation-commit-indexed`, this has to be set to 1). +* `method`: a string that indicates the Stacking method that is allowed to utilize this signature. The valid options are `stack-increase`, `stack-stx`, `stack-extend`, or `agg-commit` (for stack-aggregation-commit) +* `max-amount`: described above +* `auth-id`: described above +* `period`: a value from 0-12, which indicates how long the Stacker is allowed to lock their STX for in this particular Stacking transaction. For `agg-commit`, this must be equal to 1 +* `reward-cycle`: This represents the reward cycle in which the Stacking transaction can be confirmed (see the note above on passing in the correct reward cycle for `stack-stx` vs `stack-aggregation-commit`) * `pox-address`: The Bitcoin address that is allowed to be used for receiving rewards. This corresponds to the Bitcoin address associated with your signer -* `config`: This represents the signer configuration file path where the `stacks_private_key` is located, and it is used for signing the generated signature. Now that we have an overview of role and contents of signatures, let's see how to actually generate them. You have several options available. -**Generating your signature with Degen Lab's stacks.tools** +**Generating your signature with Degen Labs stacks.tools** -Degen Lab has a signature generation tool that will generate a signature using their signer. This is the quickest and simplest option. To generate a signature using this method, all you need to do is visit their [signature tool](https://signature.stacking.tools/) and pass in the relevant information as covered on the page. +Degen Labs has a signature generation tool that will generator a signature using their signer. This is the quickest and simplest option. To generate a signature using this method, all you need to do is visit their [signature tool](https://signature.stacking.tools/) and pass in the relevant information as covered on this page. #### Generating your signature with stacks.js -The [@stacks/stacking](https://www.npmjs.com/package/@stacks/stacking) NPM package provides interfaces to generate and use signer signatures. +The [@stacks/stacking](https://www.npmjs.com/package/@stacks/stacking) NPM package provides interfaces to generate and use signer signatures. You'll need to use `@stacks/stacking` package version 6.13.0. -There is a function called `signPoxSignature` that will allow you to generate this signature and pass it in to the stacking function. +There is a new function called `signPoxSignature` that will allow you to generate this signature and pass it in to the stacking function. More information and code samples can be found on [Hiro's Nakamoto docs](https://docs.hiro.so/nakamoto/stacks-js). #### Generating your signature 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. +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 -# Max Amount equivallent to 1M STX -# Auth Id should be a random string less than 14 characters stacks-signer generate-stacking-signature \ - --method agg-commit \ + --method stack-stx \ --max-amount 1000000000000 \ - --auth-id 71948271489 \ + --auth-id 12345 \ --period 1 \ --reward-cycle 100 \ --pox-address bc1... \ @@ -481,33 +476,34 @@ stacks-signer generate-stacking-signature \ These arguments match those described in section [Overview of signer keys and signatures](operate-a-pool.md#overview-of-signer-keys-and-signatures), with the addition of: +* `--config`, to provide the configuration file path; * `--json`, to optionally output the resulting signature in JSON. -You can use the following command to generate a random `32` bit integer as `auth-id`: +You can use the following command to generate a random `128` bit integer as `auth-id`: ```bash -python3 -c 'import secrets; print(secrets.randbits(32))' +python3 -c 'import secrets; print(secrets.randbits(128))' ``` Once the `generate-stacking-signature` command is run, the CLI will output a JSON: ```json -{"authId":"12345","maxAmount":"1234","method":"agg-commit","period":1,"poxAddress":"bc1...","rewardCycle":100,"signerKey":"aaaaaaaa","signerSignature":"bbbbbbbbbbb"} +{"authId":"12345","maxAmount":"1234","method":"stack-stx","period":1,"poxAddress":"bc1...","rewardCycle":100,"signerKey":"aaaaaaaa","signerSignature":"bbbbbbbbbbb"} ``` You will use the JSON when calling Stacking transactions from your pool operator address as outlined above. Remember that this may be different than your signer address. -#### Generating your signature with Leather Earn +#### Generating your signature with Lockstacks -Leather Earn is a web application that provides an easy-to-use interface for stacking and generating signatures. We'll cover using Leather Earn for stacking at the end of this document, here we will cover how to use it to generate a signature. +Lockstacks is a web application that provides an easy-to-use interface for stacking and generating signatures. We'll cover using Lockstacks for stacking at the end of this document, here we will cover how to use it to generate a 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 [earn.leather.io](https://earn.leather.io) to generate a signer key signature. Make sure you’re connected to the correct network.\ +You can visit [lockstacks.com](https://lockstacks.com) to generate a signer key signature. Make sure you’re connected to the correct network.\ \ -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/#preflight-setup-1), not the account that will serve as your pool operator address. Once you’ve setup that account on Leather, you can log in to Leather Earn.\ +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/#preflight-setup-1), not the account that will serve as your pool operator address. 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. @@ -517,24 +513,24 @@ The fields are: * Reward cycle: * 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-indexed, this field must equal the cycle used in that function’s “reward cycle” argument. Typically, that equates to current\_cycle + 1. + * 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-indexed, use “1”**. +* 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 Leather Earn will verify the signature before the transaction is made. +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, Leather Earn will have the signer key and signature you generated. +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 can use in your Stacking transactions, including the signer public key and signature. +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 Leather Earn page where you make your Stacking transaction. Alternatively, this information can be entered manually. +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 Leather Earn pages for actually making those transactions in the next section of this document. +We'll cover the Lockstacks pages for actually making those transactions in the next section of this document. #### Using a hardware or software wallet to generate signatures @@ -568,15 +564,15 @@ When the user needs to generate signatures: 2. Your signer signature 8. Finally, make a Stacking transaction using the signer key and signer signature. -Now that you have your signer signature generated, it's time to start stacking. This process will vary depending on your chosen method. We've included instructions for solo stacking using [Leather Earn](https://earn.leather.io) below. +Now that you have your signer signature generated, it's time to start stacking. This process will vary depending on your chosen method. We've included instructions for solo stacking and stacking as a pool operator below. ### Step 3: Stack as a pool operator -The first step with delegated stacking involves a stacker delegating their Stacks to a specific pool operator. Stackers can do this by visiting the “Stack in a pool” page on Leather Earn. +The first step with delegated stacking involves a stacker delegating their Stacks to a specific pool operator. Stackers can do this by visiting the “Stack in a pool” page on Lockstacks. As the pool operator, you must provide a STX address (a “pool admin address”) that will manage delegations. As discussed in previous sections, 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. -Pool operators can log in to Leather Earn and visit [https://earn.leather.io/pool-admin](https://earn.leather.io/pool-admin) to make pool management transactions. +Pool operators can log in to LockStacks and visit [https://lockstacks.com/pool-admin](https://lockstacks.com/pool-admin) to make pool management transactions. #### delegate-stack-stx @@ -584,7 +580,7 @@ Once a user has delegated to a pool operator, the pool operator must call `deleg #### 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 Leather Earn. The pool operator enters the following information: +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 operator enters the following information: * Reward cycle: the reward cycle where the operator is “commiting” delegated STX. This must be done for every individual reward cycle where the pool will be acting as a signer. * BTC address diff --git a/guides-and-tutorials/stack-stx/stack-with-a-pool.md b/guides-and-tutorials/stack-stx/stack-with-a-pool.md index 8d2f78e8c5..d6c70ee00a 100644 --- a/guides-and-tutorials/stack-stx/stack-with-a-pool.md +++ b/guides-and-tutorials/stack-stx/stack-with-a-pool.md @@ -12,19 +12,19 @@ If you do not meet this minimum, you'll need to delegate your STX to a pool oper This is a non-custodial delegation, meaning that your STX do not actually leave your wallet. +Delegating your STX to a pool operator involves a few steps: + {% hint style="info" %} Pool operators have a lot of control over exactly how they implement stacking. Usually users will be interacting with a wrapper contract that the pool operator has created to utilize the core stacking contract. {% endhint %} -Delegating your STX to a pool operator involves a few steps: - 1. Find a pool to delegate to 2. Use the pool's UI with your wallet of choice to call a delegate function with a few parameters 3. Pool operator will then stack your STX tokens on your behalf 4. Pool operator will allocate rewards proportionally based on how much you have stacked 5. Pool operator will distribute your rewards at the end of the stacking cycle -Let's dig into each of these. If you want to learn more about the specific functions and the contract that handles the stacking process, be sure to take a look at the [stacking contract walkthrough](../../example-contracts/stacking.md). +Let's dig into each of these. If you want to dig into the specific functions and the contract that handles this process, be sure to take a look at the [stacking contract walkthrough](../../example-contracts/stacking.md). ### Find a pool @@ -38,7 +38,7 @@ Then you'll use your chosen pool operator's UI to call their delegation function ### Pool operator stacks tokens -Once you grant permission for the pool operator to delegate, they will take over and call a separate function in the stacking contract to actually stack those delegated tokens. At this point your STX will be locked. +Once you grant permission for the pool operator to delegate. They will take over and call a separate function in the stacking contract to actually stack those delegated tokens. At this point your STX will be locked. Depending on how the pool operator handles things, they may offer the option to automatically continue to stack your STX for up to 12 continuous cycles. diff --git a/guides-and-tutorials/stack-stx/stacking-flow.md b/guides-and-tutorials/stack-stx/stacking-flow.md index 859c0cdf27..76842aff22 100644 --- a/guides-and-tutorials/stack-stx/stacking-flow.md +++ b/guides-and-tutorials/stack-stx/stacking-flow.md @@ -5,7 +5,7 @@ This doc assumes you are familiar with stacking at a conceptual level. If not, y The guide below applies to those who want to solo stack, meaning they meet the minimum stacking requirement and need to either run a signer or collaborate with a signer. {% hint style="info" %} -There is a dapp created by Degen Lab for [solo stacking](https://solo.stacking.tools/) without needing a signer, as Degen Lab operates a signer. This is likely the easiest option for solo stacking. We'll cover this option below. +There is a dapp created by DegenLabs for [solo stacking](https://solo.stacking.tools/) without needing a signer, as DegenLabs operates a signer. This is likely the easiest option for solo stacking. We'll cover this option below. {% endhint %} If you prefer to participate in a pool by delegating your STX, you do not need to operate a signer either. If you fall into this category, check out the [Stack with a Pool](stack-with-a-pool.md) guide. @@ -124,7 +124,7 @@ In general, you don’t need to do anything actively during this period, other t If you do not want to operate a signer on your own, you can work with another signer. To do this, you will need to collaborate with them to get their signer key and signer signature (details in the following sections), which will have to be passed when calling the stacking functions. -Rather than needing to find a signer to collaborate with, you can use the solo stacking dapp created by Degen Lab in order to use their signer to solo stack. They've created a UI that makes this process really simple. +Rather than needing to find a signer to collaborate with, you can use the solo stacking dapp created by DegenLabs in order to use their signer to solo stack. They've created a UI that makes this process really simple. They also have a tool for you to generate a signer signature if you prefer to call the stacking functions yourself. @@ -329,7 +329,7 @@ The arguments are: Now that you are familiar with the overall stacking flow and the different roles played, let's dive into the step-by-step guide for actually conducting the stacking process. {% hint style="info" %} -There are several ways you can go about stacking. This guide will cover using Leather Earn, which is a stacking web application and the simplest option. +There are several ways you can go about stacking. This guide will cover using Lockstacks, which is a stacking web application and the simplest option. Additionally, you can choose to call the stacking functions directly from the [deployed contract](https://explorer.hiro.so/txid/SP000000000000000000002Q6VF78.pox-4?chain=mainnet) in the explorer. @@ -382,13 +382,12 @@ Signer signatures are signatures created using a particular signer key. They dem * `period`: a value between 1 and 12, which indicates the number of cycles that the Stacker is allowed to lock their STX for in this particular Stacking transaction. For `agg-commit`, this must be equal to 1 * `reward-cycle`: This represents the reward cycle in which the Stacking transaction can be confirmed. For solo stacking operations (`stack-stx`, `stack-extend` and `stack-increase`), this has to be set as the current cycle. * `pox-address`: The Bitcoin address that is allowed to be used for receiving rewards. This can be set to any Bitcoin address that you have access to. -* `config`: This represents the signer configuration file path where the `stacks_private_key` is located, and it is used for signing the generated signature. Now that we have an overview of role and contents of signatures, let's see how to actually generate them. You have several options available. -**Generating your signature with Degen Lab's stacks.tools** +**Generating your signature with Degen Labs stacks.tools** -Degen Lab has a signature generation tool that will generate a signature using their signer. This is the quickest and simplest option. To generate a signature using this method, all you need to do is visit their [signature tool](https://signature.stacking.tools/) and pass in the relevant information as covered on this page. +Degen Labs has a signature generation tool that will generate a signature using their signer. This is the quickest and simplest option. To generate a signature using this method, all you need to do is visit their [signature tool](https://signature.stacking.tools/) and pass in the relevant information as covered on this page. #### Generating your signature with stacks.js @@ -420,6 +419,7 @@ stacks-signer generate-stacking-signature \ These arguments match those described in section [Overview of signer keys and signatures](stacking-flow.md#overview-of-signer-keys-and-signatures), with the addition of: +* `--config`, to provide the configuration file path * `--json`, to optionally output the resulting signature in JSON You can use the following command to generate a random `32` bit integer as `auth-id`: @@ -436,17 +436,17 @@ Once the `generate-stacking-signature` command is run, the CLI will output a JSO You will use the JSON when calling Stacking transactions from your Stacker address as outlined above. Remember that this may be different than your signer address. -#### Generating your signature with Leather Earn +#### Generating your signature with Lockstacks -Leather Earn is a web application that provides an easy-to-use interface for stacking and generating signatures. We'll cover using Leather Earn for stacking at the end of this document, here we will cover how to use it to generate a signature. +Lockstacks is a web application that provides an easy-to-use interface for stacking and generating signatures. We'll cover using Lockstacks for stacking at the end of this document, here we will cover how to use it to generate a 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 [earn.leather.io](https://earn.leather.io) to generate a signer key signature. Make sure you’re connected to the correct network.\ +You can visit [lockstacks.com](https://lockstacks.com) to generate a signer key signature. Make sure you’re connected to the correct network.\ \ -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/#preflight-setup-1), not the account that will serve as your pool operator address. Once you’ve setup that account on Leather, you can log in to Leather Earn.\ +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/#preflight-setup-1), not the account that will serve as your pool operator address. 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. @@ -461,19 +461,19 @@ The fields are: * 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-indexed, use “1”**. +* 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 Leather Earn will verify the signature before the transaction is made. +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, Leather Earn will have the signer key and signature you generated. +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 can use in your Stacking transactions, 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 Leather Earn page where you make your Stacking transaction. Alternatively, this information can be entered manually. +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 entered manually. -We'll cover the Leather Earn pages for actually making those transactions in the next section of this document. +We'll cover the Lockstacks pages for actually making those transactions in the next section of this document. #### Using a hardware or software wallet to generate signatures @@ -507,13 +507,13 @@ When the user needs to generate signatures: 2. Your signer signature 8. Finally, make a Stacking transaction using the signer key and signer signature. -Now that you have your signer signature generated, it's time to start stacking. This process will vary depending on your chosen method. We've included instructions for solo stacking using [Leather Earn](https://earn.leather.io) below. +Now that you have your signer signature generated, it's time to start stacking. This process will vary depending on your chosen method. We've included instructions for solo stacking using [Leather Earn](https://earn.leather.io/sign-in?chain=mainnet) below. ### Step 3: Stack your STX #### stack-stx -To start, you'll visit [Leather Earn](https://earn.leather.io) and click the “Stack independently” button on the home page. +To start, you'll visit [Lockstacks](https://lockstacks.com) and click the “Stack independently” button on the home page. This page will allow you to input the following input: @@ -528,7 +528,7 @@ This page will allow you to input the following input: #### stack-extend -If you want to extend the time that your STX will be locked for, you can use the stack-extend page on Leather Earn. +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. @@ -544,7 +544,7 @@ On this page are the following fields: #### stack-increase -If you want to increase the amount of STX locked, you can use the stack-increase page on Leather Earn. +If you want to increase the amount of STX locked, you can use the stack-increase 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 increase. diff --git a/nakamoto-upgrade/nakamoto-activation-guide-for-signers.md b/nakamoto-upgrade/nakamoto-activation-guide-for-signers.md index 275006a908..2d24f8b6ee 100644 --- a/nakamoto-upgrade/nakamoto-activation-guide-for-signers.md +++ b/nakamoto-upgrade/nakamoto-activation-guide-for-signers.md @@ -17,8 +17,8 @@ This initial phase focuses on testing Signer 3.0 readiness in a testnet environm **Action Required:** -1. Update stacks-node to version 3.1.0.0.4 ([here](https://github.com/stacks-network/stacks-core/releases/tag/3.1.0.0.4)) -2. Update signer to version 3.1.0.0.4.0 ([here](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.4.0)) +1. Update stacks-node to version 3.1.0.0.3 ([here](https://github.com/stacks-network/stacks-core/releases/tag/3.1.0.0.3)) +2. Update signer to version 3.1.0.0.3.0 ([here](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.3.0)) 3. [Run a Primary Testnet node](setting-up-a-primary-post-nakamoto-testnet-node.md) alongside your Signer 4. Create a testnet wallet address 5. Complete the provided form ([here](https://blocksurvey.io/signer-nakamoto-activation-upgrade-GrOV5aivQ2.z2fh3bqEyLQ?v=o)) diff --git a/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md b/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md index 323b591fa5..03624a4dee 100644 --- a/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md +++ b/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md @@ -30,9 +30,9 @@ The main thing exchanges will notice when the Nakamoto rollout is complete is th * [Testnet documentation](https://docs.stacks.co/nakamoto-upgrade/nakamoto) * [API documentation](https://docs.hiro.so/nakamoto/stacks-js) -* [Core Binaries](https://github.com/stacks-network/stacks-core/releases/tag/3.1.0.0.4) -* [Signer Binary](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.4.0) -* [Core Docker Images](https://hub.docker.com/r/blockstack/stacks-core/tags?page=1\&name=3.1.0.0.4) -* [Signer Docker Image](https://hub.docker.com/r/blockstack/stacks-signer/tags?page=1\&name=3.1.0.0.4.0) +* [Core Binaries](https://github.com/stacks-network/stacks-core/releases/tag/3.1.0.0.3) +* [Signer Binary](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.3.0) +* [Core Docker Images](https://hub.docker.com/r/blockstack/stacks-core/tags?page=1\&name=3.1.0.0.3) +* [Signer Docker Image](https://hub.docker.com/r/blockstack/stacks-signer/tags?page=1\&name=3.1.0.0.3.0) * [Stacks Blockchain API](https://github.com/hirosystems/stacks-blockchain-api/releases/tag/v8.4.0) * [Stacks Blockchain API Docker Images](https://hub.docker.com/r/hirosystems/stacks-blockchain-api/tags?page=1\&name=8.4.0) diff --git a/nakamoto-upgrade/setting-up-a-primary-post-nakamoto-testnet-node.md b/nakamoto-upgrade/setting-up-a-primary-post-nakamoto-testnet-node.md index 1d84c19749..8c08642cf7 100644 --- a/nakamoto-upgrade/setting-up-a-primary-post-nakamoto-testnet-node.md +++ b/nakamoto-upgrade/setting-up-a-primary-post-nakamoto-testnet-node.md @@ -2,7 +2,7 @@ ### **Setup A Stacks Primary Testnet Node** -Once your signer is upgraded to version 3.1.0.0.4.0 ([here](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.4.0)) you’ll need to run a primary testnet node alongside it. +Once your signer is upgraded to version 3.1.0.0.3.0 ([here](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.3.0)) you’ll need to run a primary testnet node alongside it. You have two options here. The first is to run the Bash script below and it will handle everything for you, including creating the configuration file, downloading and extracting a chain state archive, and getting the node up and running. @@ -20,7 +20,7 @@ STACKS_RPC_PORT="40443" STACKS_P2P_PORT="40444" IMG="blockstack/stacks-core" -VER="3.1.0.0.4" +VER="3.1.0.0.3" STX_NODE_CONFIG="${STACKS_DIR}/Config.toml" mkdir -p ${STACKS_DIR}/data @@ -249,7 +249,7 @@ An example for running the node’s Docker image with docker run is below. Be su ```bash IMG="blockstack/stacks-core" -VER="3.1.0.0.4" +VER="3.1.0.0.3" STX_NODE_CONFIG="./node-config.toml" @@ -268,7 +268,7 @@ stacks-node start \\ Or, using a custom Dockerfile: ```docker -FROM blockstack/stacks-core:3.1.0.0.4 +FROM blockstack/stacks-core:3.1.0.0.3 COPY node-config.toml /config.toml EXPOSE 20444 EXPOSE 20443 diff --git a/reference/stacks-node-configuration.md b/reference/stacks-node-configuration.md index 59c2f29f68..e481da53f8 100644 --- a/reference/stacks-node-configuration.md +++ b/reference/stacks-node-configuration.md @@ -149,82 +149,3 @@ peer_port = 8333 endpoint = "localhost:3700" events_keys = ["*"] ``` - -### Example Testnet Follower Configuration - -```toml -[node] - -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "029266faff4c8e0ca4f934f34996a96af481df94a89b0c9bd515f3536a95682ddc@seed.testnet.hiro.so:30444" -prometheus_bind = "127.0.0.1:9153" -working_dir = "/stacks-blockchain" - -[burnchain] -chain = "bitcoin" -mode = "krypton" -peer_host = "bitcoin.regtest.hiro.so" -peer_port = 18444 -pox_prepare_length = 100 -pox_reward_length = 900 - -[[ustx_balance]] -address = "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST319CF5WV77KYR1H3GT0GZ7B8Q4AQPY42ETP1VPF" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST221Z6TDTC5E0BYR2V624Q2ST6R0Q71T78WTAX6H" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST2TFVBMRPS5SSNP98DQKQ5JNB2B6NZM91C4K3P7B" -amount = 10000000000000000 - -[fee_estimation] -fee_estimator = "fuzzed_weighted_median_fee_rate" - -[[burnchain.epochs]] -epoch_name = "1.0" -start_height = 0 - -[[burnchain.epochs]] -epoch_name = "2.0" -start_height = 0 - -[[burnchain.epochs]] -epoch_name = "2.05" -start_height = 1 - -[[burnchain.epochs]] -epoch_name = "2.1" -start_height = 2 - -[[burnchain.epochs]] -epoch_name = "2.2" -start_height = 3 - -[[burnchain.epochs]] -epoch_name = "2.3" -start_height = 4 - -[[burnchain.epochs]] -epoch_name = "2.4" -start_height = 5 - -[[burnchain.epochs]] -epoch_name = "2.5" -start_height = 6 - -[[burnchain.epochs]] -epoch_name = "3.0" -start_height = 1_900 - -[[burnchain.epochs]] -epoch_name = "3.1" -start_height = 2_000 -``` diff --git a/reference/the-stack.md b/reference/the-stack.md index 80a45bd8e1..e8bca365c4 100644 --- a/reference/the-stack.md +++ b/reference/the-stack.md @@ -64,7 +64,7 @@ One of the key use cases for Stacks is being able to directly interact with the #### Stacking Tools -The Degen Lab team has created a [suite of tools](https://stacking.tools/) to make stacking significantly easier including a signer signature generator, a solo stacking dapp to stack without needing to run a signer, and a TypeScript library for mocking stacking functions. +The DegenLabs team has created a [suite of tools](https://stacking.tools/) to make stacking significantly easier including a signer signature generator, a solo stacking dapp to stack without needing to run a signer, and a TypeScript library for mocking stacking functions. #### Oracles and Price Feeds