Update sBTC docs for v1.1.0 changes (#1724)

* Update sBTC docs for v1.1.0 changes

* Fix inaccuracies with sBTC system

* Update concepts/sbtc/auxiliary-features/signer-wallet-rotation.md

Co-authored-by: Daniel Jordon <[email protected]>

* Update wallet rotation scenarios

---------

Co-authored-by: wileyj <[email protected]>
Co-authored-by: Daniel Jordon <[email protected]>
Co-authored-by: aldur <[email protected]>

Author: 4 people

concepts/sbtc/auxiliary-features/signer-wallet-rotation.md

@@ -1,41 +1,35 @@
 # Signer Wallet Rotation
 
-Signer Wallet Rotation is a crucial security feature in the sBTC system that allows sBTC Signers to rotate their private keys securely.
+Signer wallet rotation allows sBTC signers to update their private keys and modify the signer set composition. This mechanism is how the network maintains security over time and adapts to changing participants.
 
-## Overview
+## How it works
 
-- sBTC Signers have the ability to rotate their private keys.
-- This feature enhances the long-term security of the sBTC system.
-- Key rotation is coordinated among signers and requires on-chain voting by the signers.
+The sBTC system uses a multi-signature wallet on Bitcoin to custody BTC deposits. When the system needs to change who controls this wallet - either by rotating keys or changing the signer set - it uses the rotation mechanism.
 
-## Process
+As of v1.1.0, the system supports:
 
-1. Signers coordinate offline to initiate the key rotation process.
-2. Signers vote on-chain for the new signer set (new set of keys).
-3. Once the new signer set is determined, signers conduct a wallet handoff.
-4. The signers re-execute the Distributed Key Generation (DKG) process.
+- Adding new signers to the set
+- Removing existing signers
+- Replacing specific signers
+- Rotating keys for current signers
 
-## Implementation
+When signers agree on a new configuration, the system automatically runs a Distributed Key Generation (DKG) protocol to create new signing shares for the updated group. Once complete, control of the sBTC wallet transfers to the new configuration.
 
-The Signer Wallet Rotation process is facilitated by:
+## The rotation process
 
-1. **Signer Key Rotation CLI**: Allows individual signers to initiate a private key rotation.
-2. **Key Rotation Clarity Contracts**: Handle the on-chain aspects of the rotation process.
+Here's what happens during a typical rotation:
 
-## Security Considerations
+1. Signers coordinate off-chain to decide on the new signer set
+2. Each signer operator updates their configuration with the newly decided set
+3. Once all signers have configured the exact same set of signers, DKG occurs automatically
+4. The new signer set takes control of the sBTC wallet
 
-- The rotation process must ensure that the sBTC UTxO remains secure throughout the transition.
-- Proper coordination among signers is crucial to prevent any disruption in sBTC operations.
-- The new keys must be thoroughly verified before being put into use.
+The Bitcoin UTXOs remain under continuous control throughout this process - there's no moment where funds are unsecured.
 
-## Benefits
+## When rotation occurs
 
-1. **Enhanced Security**: Regular key rotations reduce the risk of key compromise.
-2. **Flexibility**: Allows for the replacement of compromised or lost keys.
-3. **Continuity**: Enables long-term operation of the sBTC system with evolving security measures.
+Key rotation typically happens when:
 
-## Best Practices
+**Signer changes**: When someone leaves the signer set or new participants join, the configuration must be updated to reflect the new membership.
 
-- Signers should rotate their keys on a regular schedule (e.g., every 6 months).
-- Emergency rotation procedures should be in place for suspected key compromises.
-- The rotation process should be audited and tested regularly to ensure smooth execution when needed.
+**Security events**: If a key might be compromised, an emergency rotation can be initiated to secure the system.

guides-and-tutorials/sbtc/how-to-run-sbtc-signer.md

@@ -50,26 +50,18 @@ You will need `bitcoind` version 25 or higher.
 
 Your Bitcoin node must include these settings for sBTC signer operation:
 
-   - `txindex=1`: Transaction indexing must be enabled
-   - `server=1`: RPC server must be enabled
-   - `zmqpubhashblock=tcp://*:28332`: ZMQ block hash notifications
-   - `zmqpubrawblock=tcp://*:28332`: ZMQ raw block notifications
+- `txindex=1`: Transaction indexing must be enabled
+- `server=1`: RPC server must be enabled
 
-### ZeroMQ (ZMQ) Configuration
+### RPC-Based Block Detection
 
-The ZeroMQ configuration specified above enables real-time blockchain event
-notifications from Bitcoin Core to the sBTC signer.
+Starting with sBTC v1.1.0, the signer uses RPC polling instead of ZeroMQ for
+block detection.
 
-The two required ZMQ endpoints serve distinct purposes:
-
-- `zmqpubhashblock`: Broadcasts only block hashes for lightweight block
-  detection
-- `zmqpubrawblock`: Broadcasts complete block data for transaction processing
-
-This notification system creates a direct event stream when:
+The signer connects to Bitcoin Core via RPC and polls for new bitcoin blocks. This process works as follows:
 
 1. Bitcoin Core validates a new block
-1. Block data publishes via ZMQ
+1. Signer detects the block via RPC polling
 1. Signer processes relevant sBTC transactions
 
 ### Example
@@ -84,9 +76,7 @@ bitcoind \
   -rpcport=${BITCOIN_RPC_PORT} \
   -rpcallowip=0.0.0.0/0 \
   -rpcallowip=::/0 \
-  -txindex \
-  -zmqpubhashblock="tcp://*:${BITCOIN_ZMQ_PORT}" \
-  -zmqpubrawblock="tcp://*:${BITCOIN_ZMQ_PORT}"
+  -txindex
 ```
 
 ## 2. Configure your Stacks node
@@ -113,7 +103,6 @@ events_keys = [
 See
 [here](https://github.com/stacks-network/sbtc/blob/main/docker/mainnet/nodes/stacks/Config.toml.in).
 
-
 ## 3. Configure your sBTC Signer
 
 The signer configuration file (`signer-config.toml`) defines the signer's
@@ -133,7 +122,8 @@ Defines how the signer connects to Bitcoin Core:
 ```toml
 [bitcoin]
 rpc_endpoints = ["http://user:pass@your-bitcoin-node:8332"]
-block_hash_stream_endpoints = ["tcp://localhost:28332"]
+# Note: block_hash_stream_endpoints are no longer used as of v1.1.0
+# The signer now uses RPC polling for block detection
 ```
 
 ### Core Signer Parameters
@@ -172,6 +162,13 @@ See
 [here](https://github.com/stacks-network/sbtc/blob/main/docker/mainnet/docker-compose.yml)
 for a Docker Compose including all the required components.
 
+{% hint style="warning" %}
+
+When deploying with Docker, always use [immutable image tags](https://docs.docker.com/reference/cli/docker/image/pull/#pull-an-image-by-digest-immutable-identifier) - the image digests are provided below. Verify the attestation of these images using this [guide](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds#verifying-artifact-attestations-with-the-github-cli).
+
+We publish our images on [GitHub Container Registry](https://github.com/stacks-sbtc/sbtc/pkgs/container/sbtc).
+{% endhint %}
+
 ## Monitoring
 
 Monitoring Details TBD