Signer and Stacking documentation refactor and review

docs/operate/.gitbook.yaml

@@ -24,8 +24,16 @@ redirects:
   guides-and-tutorials/best-practices-to-snapshot-the-chainstate: snapshot-the-chainstate.md
 
   # guides-and-tutorials/stack-stx to operate/stacking-stx redirects
-  guides-and-tutorials/stack-stx/increase-stacking: stacking-stx/increase-stacked-position.md
-  guides-and-tutorials/stack-stx/operate-a-pool: stacking-stx/operate-a-stacking-pool.md
+  guides-and-tutorials/stack-stx/increase-stacking: stacking-stx/solo-stacking.md
+  guides-and-tutorials/stack-stx/operate-a-pool: stacking-stx/operate-a-pool.md
   guides-and-tutorials/stack-stx/stack-with-a-pool: stacking-stx/stack-with-a-pool.md
-  guides-and-tutorials/stack-stx/stacking-flow: stacking-stx/solo-stack.md
-  guides-and-tutorials/stack-stx/stop-stacking: stacking-stx/stop-stacking.md
+  guides-and-tutorials/stack-stx/stacking-flow: stacking-stx/solo-stacking.md
+  guides-and-tutorials/stack-stx/stop-stacking: stacking-stx/solo-stacking.md
+
+  # Old stacking-stx paths to new structure
+  stacking-stx/solo-stack: stacking-stx/solo-stacking.md
+  stacking-stx/operate-a-stacking-pool: stacking-stx/operate-a-pool.md
+  stacking-stx/stack-with-a-pool: stacking-stx/stack-with-a-pool.md
+  stacking-stx/delegated-stacking: stacking-stx/stack-with-a-pool.md
+  stacking-stx/increase-stacked-position: stacking-stx/solo-stacking.md
+  stacking-stx/stop-stacking: stacking-stx/solo-stacking.md

docs/operate/SUMMARY.md

@@ -25,8 +25,8 @@
   * [Best Practices for Running a sBTC Signer](run-a-sbtc-signer/best-practices-for-running-an-sbtc-signer.md)
 * [Snapshot the Chainstate](snapshot-the-chainstate.md)
 * [Stacking STX](stacking-stx/README.md)
-  * [Solo Stack](stacking-stx/solo-stack.md)
-  * [Operate a Stacking Pool](stacking-stx/operate-a-stacking-pool.md)
+  * [Solo Stacking](stacking-stx/solo-stacking.md)
   * [Stack with a Pool](stacking-stx/stack-with-a-pool.md)
-  * [Increase Stacked Position](stacking-stx/increase-stacked-position.md)
-  * [Stop Stacking](stacking-stx/stop-stacking.md)
+  * [Operate a Pool](stacking-stx/operate-a-pool.md)
+  * [Generate a Signer Signature](stacking-stx/generate-signer-signature.md)
+  * [Key and Address Rotation](stacking-stx/key-and-address-rotation.md)

docs/operate/run-a-signer/README.md

@@ -4,9 +4,9 @@
 
 ### How to Use This Guide
 
-If you are not familiar with the concept of signing and stacking, and how they work together, be sure to check out the [Stackers and Signing concept guide](https://app.gitbook.com/s/H74xqoobupBWwBsVMJhK/block-production/signing).
+This guide is a step-by-step walkthrough for setting up and running a signer. It covers only the signer infrastructure: the signer software and the Stacks node it connects to.
 
-This guide is a step-by-step walkthrough for setting up and running a signer. If you need to troubleshoot your signer setup, see the Signer Troubleshooting section. If you need to Stack your STX, or have questions about how that process works, check out the Stack STX guide.
+If you are not familiar with the concept of signing, be sure to check out the [Stackers and Signing concept guide](https://app.gitbook.com/s/H74xqoobupBWwBsVMJhK/block-production/signing).
 
 ### Background and High-Level Process
 
@@ -18,27 +18,26 @@ This doc provides instructions to set up both using either Docker or the release
 
 * Docker and basic knowledge of pulling and running images
 * Basic knowledge of [Stacks accounts](https://app.gitbook.com/s/H74xqoobupBWwBsVMJhK/network-fundamentals/wallets-and-accounts)
-* Basic knowledge of [stacking](https://app.gitbook.com/s/H74xqoobupBWwBsVMJhK/block-production/stacking) and the stacking flow
 
 {% stepper %}
 {% step %}
-#### Signer Checklist — Pre-Launch Setup
+#### Signer Checklist: Pre-Launch Setup
 
 Quick reference of major setup steps prior to launching a signer.
 
 * 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 above).
+* Acquire Docker and basic knowledge of Stacks accounts (links above).
 {% endstep %}
 
 {% step %}
-#### Signer Checklist — Preflight Setup
+#### Signer Checklist: Preflight Setup
 
 * Generate a new private key using stacks-cli (see Preflight Setup).
 * Save the generated account information securely.
 {% endstep %}
 
 {% step %}
-#### Signer Checklist — Configuration Setup
+#### Signer Checklist: Configuration Setup
 
 * Create a `signer-config.toml` file with necessary configurations:
   * node\_host
@@ -51,7 +50,7 @@ Quick reference of major setup steps prior to launching a signer.
 {% endstep %}
 
 {% step %}
-#### Signer Checklist — Running the Signer
+#### Signer Checklist: Running the Signer
 
 * Decide whether to run the signer using Docker (recommended) or as a binary.
 * If using Docker:
@@ -63,14 +62,14 @@ Quick reference of major setup steps prior to launching a signer.
 {% endstep %}
 
 {% step %}
-#### Signer Checklist — Verify Signer Operation
+#### Signer Checklist: Verify Signer Operation
 
 * Check that the signer is listening on its configured endpoint.
 * Confirm that there are no errors and that the system is ready for connections.
 {% endstep %}
 
 {% step %}
-#### Signer Checklist — Setting Up the Stacks Node
+#### Signer Checklist: Setting Up the Stacks Node
 
 * Create a `node-config.toml`, include:
   * connection\_options.sauth\_token
@@ -79,20 +78,11 @@ Quick reference of major setup steps prior to launching a signer.
 {% endstep %}
 
 {% step %}
-#### Signer Checklist — Verify Stacks Node Operation
+#### Signer Checklist: Verify Stacks Node Operation
 
 * Check Stacks node logs for successful connection to the signer.
 * Confirm the node is syncing Bitcoin headers properly.
 {% endstep %}
-
-{% step %}
-#### Signer Checklist — 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.
-* 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).
-{% endstep %}
 {% endstepper %}
 
 ### Minimum System Requirements
@@ -163,8 +153,6 @@ docker run -d \
     --config /config.toml
 ```
 
-Hint about platform mismatch:
-
 {% hint style="info" %}
 If you get an error about the manifest not found or the image platform not matching the host platform, you probably are running on an architecture other than x64. Add `--platform=linux/amd64` to the command (for example, on M1 Mac).
 {% endhint %}
@@ -180,7 +168,7 @@ CMD ["stacks-signer", "run", "--config", "/config.toml"]
 
 ### Running the Signer as a Binary
 
-Download the pre-built binaries from the [Stacks Core releases page on Github](https://github.com/stacks-network/stacks-core/releases), unzip the archive for your architecture — inside is a `stacks-signer` binary.
+Download the pre-built binaries from the [Stacks Core releases page on Github](https://github.com/stacks-network/stacks-core/releases), unzip the archive for your architecture. It includes the `stacks-signer` binary.
 
 Run the signer:
 
@@ -216,10 +204,10 @@ You may also see a warning like:
 WARN [1712003997.160121] [stacks-signer/src/runloop.rs:247] [signer_runloop] Signer is not registered for reward cycle 556. Waiting for confirmed registration...
 ```
 
-This means your signer is running and awaiting registration; proceed to set up the Stacks node and begin stacking.
+This means your signer is running and awaiting registration; proceed to set up the Stacks node and then begin stacking.
 
 {% hint style="warning" %}
-Even after you Stack, you may still see messages saying the signer is not registered for the current or next reward cycle. This is normal until the prepare phase for your chosen reward cycle; assuming you meet the stacking minimum, the signer will be registered during that phase.
+You may see messages saying the signer is not registered for the current or next reward cycle. This is normal until the prepare phase for your chosen reward cycle; assuming you meet the stacking minimum, the signer will be registered during that phase.
 {% endhint %}
 
 ***
@@ -237,7 +225,7 @@ Guides:
 
 ## Set Up Your Stacks Node
 
-Start the Stacks node after the signer is running — the node will not run unless it can send events to the signer.
+Start the Stacks node after the signer is running. The node will not run unless it can send events to the signer.
 
 ### Stacks Node Configuration
 
@@ -304,7 +292,7 @@ EXPOSE 20443
 CMD ["stacks-node", "start", "--config", "/config.toml"]
 ```
 
-If you get connection refused errors, you may need to point `events_observer.endpoint` to the Docker signer container. If using default Docker bridge mode, `localhost` inside the container is not the host — point the endpoint to the Docker host or the signer container hostname accordingly.
+If you get connection refused errors, you may need to point `events_observer.endpoint` to the Docker signer container. If using default Docker bridge mode, `localhost` inside the container is not the host. Point the endpoint to the Docker host or the signer container hostname accordingly.
 
 ### Run a Stacks Node with a Binary
 
@@ -335,29 +323,8 @@ You may see many logs while syncing; refer to How to Read the Signer Logs if con
 
 ***
 
-## Setup Your Stacks Accounts
-
-{% hint style="info" %}
-For more on stacking and signing relationship, see the [Stack STX](broken-reference/) guide.
-{% endhint %}
-
-As a signer you’ll manage two Stacks accounts:
+## Next Steps: Stacking
 
-1. A “pool operator” wallet, which commits delegated STX to your signer
-2. Your signer’s wallet
-
-{% hint style="warning" %}
-For testing, make sure you are using testnet (not mainnet). Testnet STX can be [requested from a faucet](https://explorer.hiro.so/sandbox/faucet?chain=testnet).
-{% endhint %}
-
-### Setup Your Pool Operator Wallet
-
-Set up a pool operator wallet using any Stacks wallet, such as [Leather](https://leather.io/) or [Xverse](https://www.xverse.app/). You may generate a new account or use an existing one. Leather supports Ledger hardware wallets if you prefer.
-
-Fund the wallet with enough STX to cover transaction fees (testnet: faucet at https://explorer.hiro.so/sandbox/faucet?chain=testnet).
-
-Share this wallet’s STX address with parties that will delegate STX to you. For improved UX, you might use the helper contract allowing a BTC address for stackers ([pox4-pools](https://explorer.hiro.so/txid/SP001SFSMC2ZY76PD4M68P3WGX154XCH7NE3TYMX.pox4-pools?chain=mainnet)) and add your pool to [earn.leather.io](https://earn.leather.io/).
-
-***
+Once your signer and Stacks node are running and verified, the next step is to stack STX to register your signer for a reward cycle. See the [Stacking STX](../stacking-stx/) guide for complete instructions on solo stacking, delegated stacking, and managing your keys.
 
-If you need more detailed troubleshooting or further setup examples (config snippets, sample signer-config.toml or node-config.toml), let me know which files or examples you'd like converted or added.
+You will need to [generate a signer signature](../stacking-stx/generate-signer-signature.md) before making any stacking transaction.

docs/operate/run-a-signer/best-practices-to-run-a-signer.md

@@ -96,6 +96,103 @@ Restart the Stacks node so it runs with the enabled `event_observer`.
 * Ensure that multiple, trusted users can manage and maintain signer instances.
 * Where feasible, users should span different timezones.
 
+### Auto-restart configuration
+
+Configure your signer and Stacks node to automatically restart on failure to minimize downtime.
+
+#### Docker
+
+Use the `--restart` flag when running containers to enable automatic restarts:
+
+```bash
+docker run -d \
+    --restart unless-stopped \
+    -v $STX_SIGNER_CONFIG:/config.toml \
+    -v $STX_SIGNER_DATA:/var/stacks \
+    -p 30000:30000 \
+    -e RUST_BACKTRACE=full \
+    -e BLOCKSTACK_DEBUG=0 \
+    --name stacks-signer \
+    $IMG:$VER \
+    stacks-signer run \
+    --config /config.toml
+```
+
+The `unless-stopped` policy restarts the container automatically if it crashes or the host reboots, but not if you explicitly stop it. Apply the same policy to your Stacks node container.
+
+#### systemd
+
+If running as a binary, create a systemd service unit to handle automatic restarts. Example for the signer:
+
+{% code title="/etc/systemd/system/stacks-signer.service" %}
+```ini
+[Unit]
+Description=Stacks Signer
+After=network.target
+StartLimitBurst=3
+StartLimitIntervalSec=300
+ConditionFileIsExecutable=/usr/local/bin/stacks-signer
+ConditionPathExists=/etc/stacks/signer
+ConditionFileNotEmpty=/etc/stacks/signer/signer-config.toml
+
+[Service]
+ExecStart=/usr/local/bin/stacks-signer run --config /etc/stacks/signer/signer-config.toml
+User=stacks-signer
+Group=stacks-signer
+Type=simple
+Restart=on-failure
+RestartSec=10
+TimeoutStopSec=600
+KillSignal=SIGTERM
+
+[Install]
+WantedBy=multi-user.target
+```
+{% endcode %}
+
+Example for the Stacks node:
+
+{% code title="/etc/systemd/system/stacks-node.service" %}
+```ini
+[Unit]
+Description=Stacks Node
+After=network.target
+StartLimitBurst=3
+StartLimitIntervalSec=300
+ConditionFileIsExecutable=/usr/local/bin/stacks-node
+ConditionFileNotEmpty=/etc/stacks/node/node-config.toml
+
+[Service]
+ExecStart=/usr/local/bin/stacks-node start --config /etc/stacks/node/node-config.toml
+User=stacks-node
+Group=stacks-node
+Type=simple
+Restart=on-failure
+RestartSec=10
+TimeoutStopSec=600
+KillSignal=SIGTERM
+
+[Install]
+WantedBy=multi-user.target
+```
+{% endcode %}
+
+Enable and start the services:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable stacks-signer.service stacks-node.service
+sudo systemctl start stacks-signer.service
+sudo systemctl start stacks-node.service
+```
+
+Check their status at any time:
+
+```bash
+sudo systemctl status stacks-signer.service
+sudo systemctl status stacks-node.service
+```
+
 ### Backup signer keys in cold-storage
 
 * Keep an offline, secure backup of all Signer private keys (e.g., hardware security modules or encrypted storage devices).

docs/operate/run-a-signer/how-to-read-signer-logs.md

@@ -43,7 +43,7 @@ WARN [1712003997.160121] [stacks-signer/src/runloop.rs:247] [signer_runloop] Sig
 Action:
 
 * If you want the signer to participate, either delegate to it or stack on your own for an upcoming reward cycle.
-* For more details on stacking and registration, see the How to Stack doc: ../stack-stx/stacking-flow.md
+* For more details on stacking and registration, see the [Stacking STX](../stacking-stx/) guide.
 
 ## Informational
 

docs/operate/run-a-signer/opsec-best-practices.md

@@ -53,7 +53,7 @@ ConditionPathExists=/etc/stacks/signer
 ConditionFileNotEmpty=/etc/stacks/signer/signer-config.toml
 
 [Service]
-ExecStart=/usr/local/bin/stacks-signer run --config /home/etc/stacks/signer/signer-config.toml
+ExecStart=/usr/local/bin/stacks-signer run --config /etc/stacks/signer/signer-config.toml
 User={{ svc_user }}
 Group={{ svc_user }}
 Type=simple

docs/operate/run-a-signer/signer-quickstart.md

@@ -422,38 +422,16 @@ If the outputs of the previous commands are correct, you can proceed and start t
 {% endstep %}
 
 {% step %}
-#### Generate your signer signature
-
-In order to stack, you'll need your signer signature. The fields required are further explained in the [Generate a signer key signature](https://docs.stacks.co/guides-and-tutorials/stack-stx/stacking-flow#step-2-generate-a-signer-key-signature) guide.
-
-The command to generate a signature looks like this:
-
-```bash
-~/stacks-signer/stacks-signer generate-stacking-signature \
-  --method stack-stx \
-  --max-amount 1000000000000 \
-  --auth-id 195591226970828652622091037492597751808 \
-  --period 12 \
-  --reward-cycle 100 \
-  --pox-address 19tg... \
-  --config ~/stacks-signer/signer-config.toml \
-  --json
-```
+#### Monitoring
 
-The generated JSON can be then copy-pasted directly in the [Leather Earn](https://earn.leather.io/) website mentioned in the next step.
+If you would like to learn more about monitoring your signer and its corresponding node, you can check the [How to Monitor a Signer](how-to-monitor-signer.md) guide.
 {% endstep %}
 
 {% step %}
-#### Start stacking
+#### Next Steps: Stacking
 
-The simplest route is to solo stack. You can do that by using [Leather Earn](https://earn.leather.io/). Click on the 'Stack Independently' button and follow the instructions there.
-
-If you would like to learn more about solo stacking or running a pool operator, take a look at the [Stack STX](https://docs.stacks.co/guides-and-tutorials/stack-stx) guide.
-{% endstep %}
-
-{% step %}
-#### Monitoring
+Once your signer and Stacks node are running and verified, the next step is to stack STX to register your signer for a reward cycle. See the [Stacking STX](../stacking-stx/) guide for complete instructions on solo stacking, delegated stacking, and managing your keys.
 
-If you would like to learn more about monitoring your signer and its corresponding node, you can check the [How to Monitor a Signer](https://docs.stacks.co/guides-and-tutorials/running-a-signer/how-to-monitor-signer) guide.
+You will need to [generate a signer signature](../stacking-stx/generate-signer-signature.md) before making any stacking transaction.
 {% endstep %}
 {% endstepper %}