zone117x/stacks-regtest-env

Easily run a Stacks node in Kypton mode with a Bitcoind regtest instance

Stacks Regtest Environment

Easily run a Stacks node in Kypton mode with a Bitcoind regtest instance

Self-contained Stacks 2.1 image

This repo publishes a Docker image that contains a Stacks 2.1 node running in Krypton mode (local testnet). It bundles a bitcoind regtest instance and an auto-mining script.

The image can be ran as a drop-in replacement for a Stacks node running in mocknet mode, but with the benefits of full burnchain and miner capabilities such as:

• PoX reward slot registration and payout events
• Mempool events
• Microblock events

Usage examples

Run a Stacks node, mining blocks on a 2.5 second interval, with the RPC port 20443 exposed (https://localhost:20443/v2/info):

docker run -p "20443:20443" -e "MINE_INTERVAL=2.5s" hirosystems/stacks-api-e2e

An event observer can be registered using the STACKS_EVENT_OBSERVER environnment variable. For example, assuming the observer is running on the host machine on port 3700:

docker run -p "20443:20443" -e "MINE_INTERVAL=2.5s" -e "STACKS_EVENT_OBSERVER=host.docker.internal:3700" hirosystems/stacks-api-e2e

A Stacks 2.1 coinbase-alt-recipient reward address can be configured using the REWARD_RECIPIENT environment variable. This configures the Stacks node [miner.block_reward_recipient] toml config value. If not specified, regular coinbase transactions will be mined. Note that the address will receive STX rewards 100 blocks after Epoch 2.1 is activated. Usage example:

docker run -p "20443:20443" -e "REWARD_RECIPIENT=STQM73RQC4EX0A07KWG1J5ECZJYBZS4SJ4ERC6WN" hirosystems/stacks-api-e2e

In addition, the image has several tags providing different Stacks bootstrapping sequence configs:

• The default tag latest starts directly in epoche 2.1 with PoX-2 activated
• Tag stacks2.1-transition starts in epoche 2.0, then transitions to epoche 2.1 after ~15 blocks, then activates PoX-2 after another ~15 blocks

It's possible to build images with custom bootstrapping sequences by specifying the build args:

• STACKS_21_HEIGHT - the burnblock height at which epoch 2.1 is activated
• STACKS_POX2_HEIGHT - the burnblock height at which PoX-2 is activated

Note that the first Stacks block will be mined at burnblock height 104. So, for example, if you want epoch 2.1 to activate at Stacks block 10, and PoX-2 at Stacks block 20, then specify STACKS_21_HEIGHT=114 and STACKS_POX2_HEIGHT=124:

# clone repo
git clone https://github.com/hirosystems/stacks-regtest-env.git
cd stacks-regtest-env
# build
docker build -t my_image -f Dockerfile.e2e --build-arg "STACKS_21_HEIGHT=114" --build-arg "STACKS_POX2_HEIGHT=124" .
# run
docker run -p "20443:20443" -e "MINE_INTERVAL=5s" my_image

Run with Docker Compose

Clone this repo and change to its directory:

git clone https://github.com/hirosystems/stacks-regtest-env.git
cd stacks-regtest-env

Run the command to start the network:

docker compose -f docker-compose-miner.yml -f docker-compose-follower.yml up --build -d

The initial 101 blocks on bitcoind (required to have any spendable tBTC in regtest) are mined immediately, after which Stacks blocks will be mined for every new bitcoin block.

The block mining interval defaults to 500ms. This can be configured with the MINE_INTERVAL environment variable, for example:

MINE_INTERVAL=2.5s docker compose -f docker-compose-miner.yml -f docker-compose-follower.yml up --build -d

The Stacks 2.1 coinbase-alt-recipient reward address can be configured using the REWARD_RECIPIENT environment variable. This configures the Stacks node [miner.block_reward_recipient] toml config value. If not specified, regular coinbase transactions will be mined. Note that the address will receive STX rewards 100 blocks after Epoch 2.1 is activated. Usage example:

REWARD_RECIPIENT=STQM73RQC4EX0A07KWG1J5ECZJYBZS4SJ4ERC6WN MINE_INTERVAL=2.5s docker compose -f docker-compose-miner.yml -f docker-compose-follower.yml up --build -d

The following services are created

Bitcoind node in regtest mode

• JSON-RPC interface available at http://localhost:18443
• RPC auth username and password are both btc
• tBTC is available from the miner account:
  • Address: miEJtNKa3ASpA19v5ZhvbKTEieYjLpzCYT
  • Private key: 9e446f6b0c6a96cf2190e54bcd5a8569c3e386f091605499464389b8d4e0bfc201
  • Private key (WIF format): cStMQXkK5yTFGP3KbNXYQ3sJf2qwQiKrZwR9QJnksp32eKzef1za

Mining script that automatically triggers bitcoind to mine new Bitcoin blocks

• Block mining interval defaults to 500ms, configure using the MINE_INTERVAL environment variable

Stacks-node in kypton mode (i.e. a regtest-like local testnet)

• RPC available at http://localhost:20443/v2/info
• STX are preseeded to several accounts listed in stacks-krypton-miner.toml, first account:
  • Address: STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6
  • Key: cb3df38053d132895220b9ce471f6b676db5b9bf0b4adefb55f2118ece2478df01

Stacks API instance

• API available at http://localhost:3999/extended/v1/block
• Playground/debug webpages listed at http://localhost:3999/extended/v1/debug/broadcast

PostgreSQL database required by the Stacks API

• PG port is available at 5490
• Both username and password are postgres
• Database name: stacks_blockchain_api

Note: The chainstate is reset every time docker compose up is run.

Shutdown

docker compose -f docker-compose-miner.yml -f docker-compose-follower.yml down --volumes --remove-orphans --timeout=1 --rmi=all

stacks-regtest-env's Issues

Abnormal behavior after starting with Docker compose

Hello, I tried to set up a local test environment according to the README, but the behavior of the container after running seems to be abnormal. The stacks-regtest-env commit I use is 4a0fcd7, and the stacks-core commit is 9b377f9c36357d6bdc7df4134c0bfd358c42c651.

I start the container using this command

REWARD_RECIPIENT=STQM73RQC4EX0A07KWG1J5ECZJYBZS4SJ4ERC6WN MINE_INTERVAL=2.5s docker compose -f docker-compose-miner.yml -f docker-compose-follower.yml up --build -d

The logs of stacks-regtest-env-stacks-node-miner keep appearing

...
WARN [1711268740.843700] [testnet/stacks-node/src/neon_node.rs:5176] [main] Tenure: skipped tenure because no active VRF key. Trying to register one.
INFO [1711268740.845788] [testnet/stacks-node/src/burnchains/bitcoin_regtest_controller.rs:856] [relayer-http://0.0.0.0:20443] Miner node: submitting leader_key_register op - 035379aa40c02890d253cfa577964116eb5295570ae9f7287cbae5f2585f5b2c7c, waiting for its inclusion in the next Bitcoin block
ERRO [1711268740.846368] [testnet/stacks-node/src/burnchains/bitcoin_regtest_controller.rs:1661] [relayer-http://0.0.0.0:20443] Bitcoin RPC failure: transaction submission failed - Network("Bitcoin RPC: status(500) != success, body is 'Object {\"error\": Object {\"code\": Number(-1), \"message\": String(\"sendrawtransaction \\\"hexstring\\\" ( maxfeerate )\\n\\nSubmit a raw transaction (serialized, hex-encoded) to local node and network.\\n\\nNote that the transaction will be sent unconditionally to all peers, so using this\\nfor manual rebroadcast may degrade privacy by leaking the transaction's origin, as\\nnodes will normally not rebroadcast non-wallet transactions already in their mempool.\\n\\nAlso see createrawtransaction and signrawtransactionwithkey calls.\\n\\nArguments:\\n1. hexstring     (string, required) The hex string of the raw transaction\\n2. maxfeerate    (numeric or string, optional, default=0.10) Reject transactions whose fee rate is higher than the specified value, expressed in BTC/kB.\\n                 Set to 0 to accept any fee rate.\\n                 \\n\\nResult:\\n\\\"hex\\\"    (string) The transaction hash in hex\\n\\nExamples:\\n\\nCreate a transaction\\n> bitcoin-cli createrawtransaction \\\"[{\\\\\\\"txid\\\\\\\" : \\\\\\\"mytxid\\\\\\\",\\\\\\\"vout\\\\\\\":0}]\\\" \\\"{\\\\\\\"myaddress\\\\\\\":0.01}\\\"\\nSign the transaction, and get back the hex\\n> bitcoin-cli signrawtransactionwithwallet \\\"myhex\\\"\\n\\nSend the transaction (signed hex)\\n> bitcoin-cli sendrawtransaction \\\"signedhex\\\"\\n\\nAs a JSON-RPC call\\n> curl --user myusername --data-binary '{\\\"jsonrpc\\\": \\\"1.0\\\", \\\"id\\\": \\\"curltest\\\", \\\"method\\\": \\\"sendrawtransaction\\\", \\\"params\\\": [\\\"signedhex\\\"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/\\n\")}, \"id\": String(\"stacks\"), \"result\": Null}'")

The log of stacks-regtest-env-stacks-node-follower is

...
INFO [1711268734.199457] [stackslib/src/burnchains/burnchain.rs:1475] [main] Syncing Bitcoin blocks: 100.0% (96 to 101 out of 101)
INFO [1711268734.205651] [stackslib/src/burnchains/burnchain.rs:976] [burnchain-db] Update PoX affirmation maps for reward cycle, prev_reward_cycle: 19, this_reward_cycle: 20, block_height: 100, cycle-length: 5
INFO [1711268734.223447] [stackslib/src/chainstate/burn/db/sortdb.rs:2329] [chains-coordinator-0.0.0.0:20443] Reward cycle #20 (100): (F*w) not reached, expecting consensus over proof of burn
INFO [1711268734.224183] [stackslib/src/chainstate/burn/db/sortdb.rs:3612] [chains-coordinator-0.0.0.0:20443] Begin reward-cycle sortition with present anchor block=None
INFO [1711268734.225312] [stackslib/src/chainstate/burn/db/sortdb.rs:3612] [chains-coordinator-0.0.0.0:20443] Begin reward-cycle sortition with present anchor block=None
INFO [1711268734.225328] [stackslib/src/chainstate/burn/db/sortdb.rs:3612] [chains-coordinator-0.0.0.0:20443] Begin reward-cycle sortition with present anchor block=None
INFO [1711268735.209353] [testnet/stacks-node/src/run_loop/neon.rs:1138] [main] Runloop: Downloaded burnchain blocks up to height 101; target height is 101; remote_chain_height = 101 next_sortition_height = 101, sortition_db_height = 96
INFO [1711268735.233943] [testnet/stacks-node/src/run_loop/neon.rs:1138] [main] Runloop: Downloaded burnchain blocks up to height 101; target height is 101; remote_chain_height = 101 next_sortition_height = 101, sortition_db_height = 101
INFO [1711268735.234034] [testnet/stacks-node/src/run_loop/neon.rs:1255] [main] Runloop: Synchronized full burnchain up to height 101. Proceeding to mine blocks

The log of stacks-regtest-env-bitcoind-miner is

...
No Stacks mining tx detected
No Stacks mining tx detected
No Stacks mining tx detected
No Stacks mining tx detected
No Stacks mining tx detected
No Stacks mining tx detected
No Stacks mining tx detected
No Stacks mining tx detected

The log of stacks-regtest-env-bitcoind is

2024-03-24T08:25:08Z [default wallet] AddToWallet 26cedaae1ee806e2fc5c70a2452cd5509cdf2b9d8b60716b8b33444795f9de5e  new
2024-03-24T08:25:08Z CreateNewBlock(): block weight: 900 txs: 0 fees: 0 sigops 400
2024-03-24T08:25:08Z UpdateTip: new best=3a33cbfe8432f1b8e16213dac4ed2eeb651bb26ca02dd7a78997f5485dde9f10 height=99 version=0x20000000 log2_work=7.643856 tx=100 date='2024-03-24T08:25:26Z' progress=1.000000 cache=0.0MiB(99txo)
2024-03-24T08:25:08Z [default wallet] AddToWallet 1b32811dcc4534798fe1bbe8876da7e01d59d2d194e584ef79379141fe1f1c9b  new
2024-03-24T08:25:08Z CreateNewBlock(): block weight: 900 txs: 0 fees: 0 sigops 400
2024-03-24T08:25:08Z UpdateTip: new best=7ca3af572892c760fd3b99055f95318bdb695a2f1b55bf7615b2db064034931c height=100 version=0x20000000 log2_work=7.658211 tx=101 date='2024-03-24T08:25:26Z' progress=1.000000 cache=0.0MiB(100txo)
2024-03-24T08:25:08Z CreateNewBlock(): block weight: 900 txs: 0 fees: 0 sigops 400
2024-03-24T08:25:08Z [default wallet] AddToWallet 0ad37cd16d8615500045b7fb261ee6f5ff81e7142e5c078d7aab067e6a4af780  new
2024-03-24T08:25:08Z UpdateTip: new best=46fcf8c644a57ed963243d5ec8f4cbd0a584df0118a178d4dc4486a2ec2cdfe6 height=101 version=0x20000000 log2_work=7.672425 tx=102 date='2024-03-24T08:25:26Z' progress=1.000000 cache=0.0MiB(101txo)
2024-03-24T08:25:08Z [default wallet] AddToWallet 0e9d5594500cfcc517035213fce9d1f601a9eb72e3ce4cff62dfaead3287b5b0  new
2024-03-24T08:26:08Z Adding fixed seed nodes as DNS doesn't seem to be available.

I cannot interact with the network normally, such as querying account information

curl http://localhost:20443/v2/accounts/STQM73RQC4EX0A07KWG1J5ECZJYBZS4SJ4ERC6WN

No stacks chain tip exists at this point in time.

My test environment is:

OS: Ubuntu 22.04 jammy
Kernel: x86_64 Linux 6.5.0-26-generic
CPU: Intel Xeon Gold 5218R @ 64x 2.095GHz
RAM: 32GB

Docker version is

Docker version 24.0.6, build ed223bc