stacks-network · radu-stacks · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,2 @@
 docker/chainstate
 .current-chainstate-dir
-
diff --git a/Makefile b/Makefile
@@ -106,7 +106,7 @@ up: check-not-running | build $(CHAINSTATE_DIR)
 genesis: check-not-running | build $(CHAINSTATE_DIR)
 	@echo "Starting $(PROJECT) network from genesis"
 	@echo "  OS: $(OS)"
-	@[ -d "$(CHAINSTATE_DIR)" ] && { echo "    Removing existing genesis chainstate dir: $(CHAINSTATE_DIR)"; sudo rm -rf $(CHAINSTATE_DIR); }
+	@[ -d "$(CHAINSTATE_DIR)" ] && { echo "    Removing existing genesis chainstate dir: $(CHAINSTATE_DIR)"; rm -rf "$(CHAINSTATE_DIR)"; }
 	@echo "  Chainstate Dir: $(CHAINSTATE_DIR)"
 	mkdir -p "$(CHAINSTATE_DIR)"
 	echo "$(CHAINSTATE_DIR)" > .current-chainstate-dir

diff --git a/README.md b/README.md
@@ -4,6 +4,7 @@
 - bind-mounts a local filesystem for data persistence
 - Uses a chainstate archive to boot the network quickly
 - Configurable signing weight across the 3 signers
+- Configured for Epoch 4.0 / PoX-5 using the PoX waterfall integration branch
 - Designed to run on Linux (tested on Debian-based) or MacOS
 
 ## Quickstart
@@ -47,6 +48,37 @@ make down
 
 ## Full list of options
 
+### Epoch 4.0 / PoX-5
+
+Hacknet defaults to the Stacks Core PoX-5 integration SHA configured in `docker/docker-compose.yml`.
+The main PoX-5 controls are:
+
+- `STACKS_CORE_BASE_BRANCH`: branch, tag, or commit SHA used to build `stacks-node` and `stacks-signer`
+- `STACKS_40_HEIGHT`: Epoch 4.0 activation height, default `262`
+- `POX_5_DEPLOYER_PRIVATE_KEY`: funded key that temporarily deploys PoX-5 prerequisite sBTC contracts until those dependencies become boot contracts
+- `POX_5_SBTC_CONTRACT`: contract id used by `.pox-5` for the sBTC token
+- `POX_5_SBTC_REGISTRY_CONTRACT`: contract id used by signer-set computation for the sBTC aggregate key
+- `POX_5_BOND_ADMIN`: principal initialized as PoX-5 bond admin
+- `POX_5_BOND_ADMIN_PRIVATE_KEY`: key used by the opt-in Bitcoin Staking helper to call `setup-bond`
+
+Changing these values requires a fresh genesis run and a regenerated chainstate archive.
+
+### Bitcoin Staking
+
+Bitcoin Staking is available as an opt-in compose profile:
+
+```sh
+docker compose -f docker/docker-compose.yml --profile default --profile bitcoin-staking up bitcoin-staking
+```
+
+The helper waits for `.pox-5`, waits for signer-manager registration, sets up an available protocol bond, mints mock sBTC to the configured participants, and registers those participants through `register-for-bond` using the sBTC path.
+
+- `BITCOIN_STAKING_KEYS`: funded participant keys, defaulting to accounts that are not used by `tx-broadcaster`
+- `BITCOIN_STAKING_BOND_INDEX`: first bond index to try, default `0`
+- `BITCOIN_STAKING_AMOUNT_USTX`: STX to lock per participant, default `99000000000000`
+- `BITCOIN_STAKING_AMOUNT_SATS`: sBTC sats to bond per participant, default `1000000`
+- `BITCOIN_STAKING_TARGET_RATE`, `BITCOIN_STAKING_STX_VALUE_RATIO`, `BITCOIN_STAKING_MIN_USTX_RATIO`: PoX-5 bond parameters
+
 ### Logs
 
 `docker logs -f <service>` will work, along with some defined Makefile targets
@@ -227,7 +259,9 @@ make down-prom
 - **stacks-signer-3**: event observer for stacks-miner-3
 - **stacks-api**: API instance receiving events from stacks-miner-1
 - **postgres**: postgres DB used by stacks-api
+- **pox5-setup**: temporary bootstrap that deploys `sbtc-registry` and `sbtc-token` before Epoch 4.0 so `.pox-5` can initialize until those dependencies become boot contracts
 - **stacker**: stack for `stacks-signer-1`, `stacks-signer-2` and `stacks-signer-3`
+- **bitcoin-staking**: optional helper that configures a PoX-5 protocol bond and registers funded participants with mock sBTC
 - **tx-broadcaster**: submits token transfer txs to ensure stacks block production during a sortition
 
 ## Bitcoin Miner
@@ -363,6 +397,34 @@ _Dedicated address for Bitcoin block production after initial setup (~200 blocks
 ‣ WIF:          cMz2ZSsaVgWPFUkE44zHpJepB4NdwB9L938h53hQfFoot81AZFb3
 ```
 
+## Bitcoin Staking Accounts
+
+Funded accounts used by the optional `bitcoin-staking` profile. These are separate from the transaction-generation accounts to avoid nonce contention with `tx-broadcaster`.
+
+### Bitcoin Staking 1
+
+```text
+‣ Private Key:  d9493653ea195060a599a356bd8381f70f52f007827dd25e7486d14e5197157801
+‣ Public Key:   020d6085b50919598386c7e96a252283420eecdf7cbaca4b968e90295e386c2028
+‣ STX Address:  ST2N30Q9PQPPPTBFYN4WN7KF3N2KRHZA9QFAABWP4
+```
+
+### Bitcoin Staking 2
+
+```text
+‣ Private Key:  c47a4264c2bd5b20ddb2ee3f731118555ecf41c63befd998d3bff89f204c0c9701
+‣ Public Key:   02303e0b336ce291e545558385521eaab845653ef4d9c7afa8fd445c15f39d6da2
+‣ STX Address:  ST3ZPZ54BV6BARTSGGM05PCJ5HA0XRAHYK3T8RSM8
+```
+
+### Bitcoin Staking 3
+
+```text
+‣ Private Key:  7b546d17e6d8aea6692f456c45489f218700eb3074a11f1a01f9c8c2cdf2a98901
+‣ Public Key:   0249cd888fc2e95faf7c82f83f79e20c5e8ef60829edd93ded57ef90542d794909
+‣ STX Address:  ST3AY3W1J4F67C5VSD8AZYD6N10P5M8SYT8WQWV40
+```
+
 ## Testing Accounts
 
 _Unused but funded accounts that may be used to deploy contracts or other txs_

diff --git a/docker/chainstate.tar.zstd b/docker/chainstate.tar.zstd
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
@@ -62,7 +62,7 @@
   - &BITCOIN_MINER_IP 10.0.0.251
 
   # External Docker Images
-  - &IMAGE_STACKS_API hirosystems/stacks-blockchain-api:8.13.6@sha256:f23e1a0f5f288605c39f6a6c8dab50bf6b9ab2f723ebaae5ad89b9a903642462
+  - &IMAGE_STACKS_API hirosystems/stacks-blockchain-api:9.0.0-pox5.8
   - &IMAGE_POSTGRES postgres:16.6-bookworm@sha256:c965017e1d29eb03e18a11abc25f5e3cd78cb5ac799d495922264b8489d5a3a1
   - &IMAGE_BITCOIN bitcoin/bitcoin:25.2@sha256:14b4777166cba8de36b62ce72801038760a8f490122781b66d40592c8c69ebda
 
@@ -88,13 +88,28 @@
   - &STACKS_32_HEIGHT ${STACKS_32_HEIGHT:-234}
   - &STACKS_33_HEIGHT ${STACKS_33_HEIGHT:-235}
   - &STACKS_34_HEIGHT ${STACKS_34_HEIGHT:-242}
+  - &STACKS_40_HEIGHT ${STACKS_40_HEIGHT:-262}
+  - &STACKS_CHAIN_ID ${STACKS_CHAIN_ID:-2147483648}
   - &STACKING_CYCLES ${STACKING_CYCLES:-1} # number of cycles to stack-stx or stack-extend for
   - &POX_PREPARE_LENGTH ${POX_PREPARE_LENGTH:-5}
   - &POX_REWARD_LENGTH ${POX_REWARD_LENGTH:-20}
   - &REWARD_RECIPIENT_1 ${REWARD_RECIPIENT_1:-ST1XVSVQN0KP5SDYFNT8E5TXWVW0XZVQEDBMCJ3XM} # priv: a6143d20cd73d0dce2179e2af7771372a95b9d6795924492bd4d15d17709531e01
   - &REWARD_RECIPIENT_2 ${REWARD_RECIPIENT_2:-ST2FW15NGB4H76FMVXKHYYSM865YVS6V3SA1GNABC} # priv: fe3087801196d8027008146b13e6d365920c2e4b7bc9969729ec2f0f22ef74fc01
   - &REWARD_RECIPIENT_3 ${REWARD_RECIPIENT_3:-ST2MES40ZEXTX9M4YXW9QSWHRVC9HYT419S198VPM} # priv: ed7eb063c61b8e892987228f1fcfb74eab5009568861613dc4b074b708a7893701
-  - &STACKS_CORE_BASE_BRANCH ${STACKS_CORE_BASE_BRANCH:-3.4.0.0.2} # branch, tag, or commit SHA
+  - &POX_5_DEPLOYER_PRIVATE_KEY ${POX_5_DEPLOYER_PRIVATE_KEY:-27e27a9c242bcf79784bb8b19c8d875e23aaf65c132d54a47c84e1a5a67bc62601}
+  - &POX_5_DEPLOYER_ADDRESS ${POX_5_DEPLOYER_ADDRESS:-ST2SBXRBJJTH7GV5J93HJ62W2NRRQ46XYBK92Y039}
+  - &POX_5_SBTC_CONTRACT ${POX_5_SBTC_CONTRACT:-ST2SBXRBJJTH7GV5J93HJ62W2NRRQ46XYBK92Y039.sbtc-token}
+  - &POX_5_SBTC_REGISTRY_CONTRACT ${POX_5_SBTC_REGISTRY_CONTRACT:-ST2SBXRBJJTH7GV5J93HJ62W2NRRQ46XYBK92Y039.sbtc-registry}
+  - &POX_5_BOND_ADMIN ${POX_5_BOND_ADMIN:-ST2SBXRBJJTH7GV5J93HJ62W2NRRQ46XYBK92Y039}
+  - &POX_5_BOND_ADMIN_PRIVATE_KEY ${POX_5_BOND_ADMIN_PRIVATE_KEY:-27e27a9c242bcf79784bb8b19c8d875e23aaf65c132d54a47c84e1a5a67bc62601}
+  - &BITCOIN_STAKING_KEYS ${BITCOIN_STAKING_KEYS:-d9493653ea195060a599a356bd8381f70f52f007827dd25e7486d14e5197157801,c47a4264c2bd5b20ddb2ee3f731118555ecf41c63befd998d3bff89f204c0c9701,7b546d17e6d8aea6692f456c45489f218700eb3074a11f1a01f9c8c2cdf2a98901}
+  - &BITCOIN_STAKING_BOND_INDEX ${BITCOIN_STAKING_BOND_INDEX:-0}
+  - &BITCOIN_STAKING_AMOUNT_USTX ${BITCOIN_STAKING_AMOUNT_USTX:-99000000000000}
+  - &BITCOIN_STAKING_AMOUNT_SATS ${BITCOIN_STAKING_AMOUNT_SATS:-1000000}
+  - &BITCOIN_STAKING_TARGET_RATE ${BITCOIN_STAKING_TARGET_RATE:-1000}
+  - &BITCOIN_STAKING_STX_VALUE_RATIO ${BITCOIN_STAKING_STX_VALUE_RATIO:-100}
+  - &BITCOIN_STAKING_MIN_USTX_RATIO ${BITCOIN_STAKING_MIN_USTX_RATIO:-10000}
+  - &STACKS_CORE_BASE_BRANCH ${STACKS_CORE_BASE_BRANCH:-e04ba8e101fe2f71fae9c79a956b599e0523f3ae} # branch, tag, or commit SHA
   - &PAUSE_HEIGHT ${PAUSE_HEIGHT:-999999999999}
   - &PAUSE_TIMER 86400000
 
@@ -139,8 +154,12 @@
     STACKS_32_HEIGHT: *STACKS_32_HEIGHT
     STACKS_33_HEIGHT: *STACKS_33_HEIGHT
     STACKS_34_HEIGHT: *STACKS_34_HEIGHT
+    STACKS_40_HEIGHT: *STACKS_40_HEIGHT
     POX_PREPARE_LENGTH: *POX_PREPARE_LENGTH
     POX_REWARD_LENGTH: *POX_REWARD_LENGTH
+    POX_5_SBTC_CONTRACT: *POX_5_SBTC_CONTRACT
+    POX_5_SBTC_REGISTRY_CONTRACT: *POX_5_SBTC_REGISTRY_CONTRACT
+    POX_5_BOND_ADMIN: *POX_5_BOND_ADMIN
     STACKS_LOG_JSON: *STACKS_LOG_JSON
     STACKS_LOG_DEBUG: *STACKS_LOG_DEBUG
     STACKS_LOG_FORMAT_TIME: *STACKS_LOG_FORMAT_TIME
@@ -432,6 +451,9 @@
       PG_USER: "postgres"
       PG_PASSWORD: "postgres"
       PG_DATABASE: "postgres"
+      # Preserve hacknet's existing public-schema DB layout; API v9 defaults to
+      # stacks_blockchain_api.
+      PG_SCHEMA: "public"
       STACKS_CHAIN_ID: "0x80000000"
       STACKS_CORE_EVENT_PORT: 3700
       STACKS_CORE_EVENT_HOST: "0.0.0.0"
@@ -453,6 +475,38 @@
 
   # Stacker
   # ------------------
+  # Temporary bootstrap for PoX-5 dependency contracts until stacks-core ships
+  # them as boot contracts.
+  pox5-setup:
+    build: stacker
+    container_name: pox5-setup
+    depends_on:
+      - stacks-miner-1
+    environment:
+      STACKS_CORE_RPC_HOST: stacks-miner-1
+      STACKS_CORE_RPC_PORT: 20443
+      STACKS_CHAIN_ID: *STACKS_CHAIN_ID
+      STACKS_25_HEIGHT: *STACKS_25_HEIGHT
+      STACKS_30_HEIGHT: *STACKS_30_HEIGHT
+      STACKS_40_HEIGHT: *STACKS_40_HEIGHT
+      POX_PREPARE_LENGTH: *POX_PREPARE_LENGTH
+      POX_REWARD_LENGTH: *POX_REWARD_LENGTH
+      POX_5_DEPLOYER_PRIVATE_KEY: *POX_5_DEPLOYER_PRIVATE_KEY
+      POX_5_DEPLOYER_ADDRESS: *POX_5_DEPLOYER_ADDRESS
+      POX_5_SBTC_CONTRACT: *POX_5_SBTC_CONTRACT
+      POX_5_SBTC_REGISTRY_CONTRACT: *POX_5_SBTC_REGISTRY_CONTRACT
+      POX_5_BOND_ADMIN: *POX_5_BOND_ADMIN
+      STACKING_KEYS: 41634762d89dfa09133a4a8e9c1378d0161d29cd0a9433b51f1e3d32947a73dc01,9bfecf16c9c12792589dd2b843f850d5b89b81a04f8ab91c083bdf6709fbefee01,3ec0ca5770a356d6cd1a9bfcbf6cd151eb1bd85c388cc00648ec4ef5853fdb7401
+      SERVICE_NAME: pox5-setup
+    entrypoint:
+      - /bin/bash
+      - -c
+      - |
+        set -e
+        exec npx tsx /root/pox5-setup.ts
+    profiles:
+      - default
+
   stacker:
     build: stacker
     container_name: stacker
@@ -462,19 +516,62 @@
       STACKS_CORE_RPC_HOST: stacks-miner-1
       STACKS_CORE_RPC_PORT: 20443
       STACKING_CYCLES: *STACKING_CYCLES
+      STACKS_CHAIN_ID: *STACKS_CHAIN_ID
       STACKING_KEYS: 41634762d89dfa09133a4a8e9c1378d0161d29cd0a9433b51f1e3d32947a73dc01,9bfecf16c9c12792589dd2b843f850d5b89b81a04f8ab91c083bdf6709fbefee01,3ec0ca5770a356d6cd1a9bfcbf6cd151eb1bd85c388cc00648ec4ef5853fdb7401
       # STACKING_SLOT_DISTRO: 1,4,5
       STACKING_SLOT_DISTRO: 2,2,2 # Sets the stacking weight for the 3 stacking addresses. Default is evenly distributed across all 3 stackers
       STACKS_25_HEIGHT: *STACKS_25_HEIGHT
       STACKS_30_HEIGHT: *STACKS_30_HEIGHT
+      STACKS_40_HEIGHT: *STACKS_40_HEIGHT
       POX_PREPARE_LENGTH: *POX_PREPARE_LENGTH
       POX_REWARD_LENGTH: *POX_REWARD_LENGTH
+      POX_5_DEPLOYER_PRIVATE_KEY: *POX_5_DEPLOYER_PRIVATE_KEY
+      POX_5_DEPLOYER_ADDRESS: *POX_5_DEPLOYER_ADDRESS
+      POX_5_SBTC_CONTRACT: *POX_5_SBTC_CONTRACT
+      POX_5_SBTC_REGISTRY_CONTRACT: *POX_5_SBTC_REGISTRY_CONTRACT
+      POX_5_BOND_ADMIN: *POX_5_BOND_ADMIN
       STACKING_INTERVAL: 2 # Interval (seconds) for checking if stacking transactions are needed
       POST_TX_WAIT: 10 # Seconds to wait after a stacking transaction is broadcast before continuing the loop
       SERVICE_NAME: stacker
     profiles:
       - default
 
+  bitcoin-staking:
+    build: stacker
+    container_name: bitcoin-staking
+    depends_on:
+      - stacks-miner-1
+      - pox5-setup
+      - stacker
+    environment:
+      STACKS_CORE_RPC_HOST: stacks-miner-1
+      STACKS_CORE_RPC_PORT: 20443
+      STACKS_25_HEIGHT: *STACKS_25_HEIGHT
+      STACKS_30_HEIGHT: *STACKS_30_HEIGHT
+      POX_PREPARE_LENGTH: *POX_PREPARE_LENGTH
+      POX_REWARD_LENGTH: *POX_REWARD_LENGTH
+      POX_5_DEPLOYER_PRIVATE_KEY: *POX_5_DEPLOYER_PRIVATE_KEY
+      POX_5_BOND_ADMIN: *POX_5_BOND_ADMIN
+      POX_5_BOND_ADMIN_PRIVATE_KEY: *POX_5_BOND_ADMIN_PRIVATE_KEY
+      POX_5_SBTC_CONTRACT: *POX_5_SBTC_CONTRACT
+      BITCOIN_STAKING_KEYS: *BITCOIN_STAKING_KEYS
+      BITCOIN_STAKING_BOND_INDEX: *BITCOIN_STAKING_BOND_INDEX
+      BITCOIN_STAKING_AMOUNT_USTX: *BITCOIN_STAKING_AMOUNT_USTX
+      BITCOIN_STAKING_AMOUNT_SATS: *BITCOIN_STAKING_AMOUNT_SATS
+      BITCOIN_STAKING_TARGET_RATE: *BITCOIN_STAKING_TARGET_RATE
+      BITCOIN_STAKING_STX_VALUE_RATIO: *BITCOIN_STAKING_STX_VALUE_RATIO
+      BITCOIN_STAKING_MIN_USTX_RATIO: *BITCOIN_STAKING_MIN_USTX_RATIO
+      STACKING_KEYS: 41634762d89dfa09133a4a8e9c1378d0161d29cd0a9433b51f1e3d32947a73dc01,9bfecf16c9c12792589dd2b843f850d5b89b81a04f8ab91c083bdf6709fbefee01,3ec0ca5770a356d6cd1a9bfcbf6cd151eb1bd85c388cc00648ec4ef5853fdb7401
+      SERVICE_NAME: bitcoin-staking
+    entrypoint:
+      - /bin/bash
+      - -c
+      - |
+        set -e
+        exec npx tsx /root/bitcoin-staking.ts
+    profiles:
+      - bitcoin-staking
+
   tx-broadcaster:
     build: stacker
     container_name: tx-broadcaster

diff --git a/docker/stacker/Dockerfile b/docker/stacker/Dockerfile
@@ -6,6 +6,7 @@ WORKDIR /root
 COPY ./stacking/package.json /root/
 RUN npm i
 
-COPY ./stacking/stacking.ts ./stacking/common.ts ./stacking/tx-broadcaster.ts /root/
+COPY ./stacking/*.ts /root/
+COPY ./stacking/contracts /root/contracts
 
 CMD ["npx", "tsx", "/root/stacking.ts"]