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,41 +4,40 @@
 
 ### 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](../../learn/block-production/signing.md).
 
 ### Background and High-Level Process
 
 To run a signer you'll run a signer and a Stacks node side-by-side. Specifically, run a follower node. The signer monitors events from the Stacks node and uses the generated account (see Preflight Setup) to sign incoming Stacks blocks sent from the Stacks node.
 
-This doc provides instructions to set up both using either Docker or the release binaries available in the [stacks core releases](https://github.com/stacks-network/stacks-core/releases) repository, and how to configure them so the signer and Stacks node communicate correctly.
+This doc provides instructions to set up both using either Docker or the release binaries available in the [stacks core releases](https://github.com/stacks-network/stacks-core/releases/latest) repository, and how to configure them so the signer and Stacks node communicate correctly.
 
 ### Knowledge Prerequisites
 
 * 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
+* Basic knowledge of [Stacks accounts](../../learn/network-fundamentals/wallets-and-accounts.md)
 
 {% 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
@@ -124,13 +114,13 @@ Signers are intended to work with a local node. The node<->signer connection is
 
 ## Create a Configuration File
 
-Create a file named `signer-config.toml`. Populate it with the example signer config file contents from the [Sample Configuration Files](https://app.gitbook.com/s/GVj1Z9vMuEOMe7oH7Wnq/node-operations/signer-configuration) page. Each field is described on that page.
+Create a file named `signer-config.toml`. Populate it with the example signer config file contents from the [Sample Configuration Files](../../reference/node-operations/signer-configuration.md) page. Each field is described on that page.
 
 ***
 
 ## Running the Signer
 
-Two options: Docker (recommended) or binary. Binaries are available on the [Stacks Core releases page](https://github.com/stacks-network/stacks-core/releases).
+Two options: Docker (recommended) or binary. Binaries are available on the [Stacks Core releases page](https://github.com/stacks-network/stacks-core/releases/latest).
 
 ### Running the Signer with Docker
 
@@ -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/latest), 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,11 +225,11 @@ 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
 
-Create `node-config.toml`. See the [Sample Configuration Files](https://app.gitbook.com/s/GVj1Z9vMuEOMe7oH7Wnq/node-operations/signer-configuration) page for the full contents.
+Create `node-config.toml`. See the [Sample Configuration Files](../../reference/node-operations/signer-configuration.md) page for the full contents.
 
 Important fields to change:
 
@@ -304,11 +292,11 @@ 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
 
-Download the pre-built `stacks-node` binary from the [Stacks Core releases](https://github.com/stacks-network/stacks-core/releases).
+Download the pre-built `stacks-node` binary from the [Stacks Core releases](https://github.com/stacks-network/stacks-core/releases/latest).
 
 Start the node:
 
@@ -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,110 @@ 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
+```
+
+View logs with:
+
+```bash
+journalctl -xefu stacks-signer
+journalctl -xefu stacks-node
+```
+
 ### 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