{"id":19291736,"url":"https://github.com/hirosystems/stacks-regtest-env","last_synced_at":"2025-04-22T06:31:42.925Z","repository":{"id":60266711,"uuid":"533333474","full_name":"hirosystems/stacks-regtest-env","owner":"hirosystems","description":"Easily run a Stacks node in Kypton mode with a Bitcoind regtest instance","archived":false,"fork":false,"pushed_at":"2025-03-11T20:00:32.000Z","size":429,"stargazers_count":4,"open_issues_count":9,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-15T21:43:55.883Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hirosystems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-06T13:19:43.000Z","updated_at":"2024-10-23T18:58:11.000Z","dependencies_parsed_at":"2024-02-28T14:49:31.552Z","dependency_job_id":"a570dbb3-69ea-4e3a-8f9a-35b6f463b5cc","html_url":"https://github.com/hirosystems/stacks-regtest-env","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fstacks-regtest-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fstacks-regtest-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fstacks-regtest-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fstacks-regtest-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hirosystems","download_url":"https://codeload.github.com/hirosystems/stacks-regtest-env/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250183235,"owners_count":21388681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T22:27:43.780Z","updated_at":"2025-04-22T06:31:42.672Z","avatar_url":"https://github.com/hirosystems.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stacks Regtest Environment\n\nEasily run a Stacks node in Kypton mode with a Bitcoind regtest instance\n\n## Self-contained Stacks 3.0 image\n\nThis repo uses Docker Compose to orchestrate multiple images and run a fully working Nakamoto Stacks environment. This includes:\n\n- A Bitcoin regtest node\n- A Stacks miner node\n- 3 Stacks signers\n- Scripts for monitoring and auto-stacking\n\nMake sure you have Docker and Docker Compose installed and running on your machine, then run:\n\n```bash\n./run.sh\n```\n\nThis will output the logs from each service. You can view the logs for a single service with:\n\n```\ndocker-compose logs $service_name\n```\n\nAdd `-f` to automatically follow new logs. The service names can be found in [./docker-compose.yml](./docker-compose.yml), such as `stacks-node`, `signer-0`, and `monitor`.\n\n## Self-contained Stacks 2.1 image\n\nThis 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.\n\nThe 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:\n\n- PoX reward slot registration and payout events\n- Mempool events\n- Microblock events\n\n#### Usage examples\n\nRun a Stacks node, mining blocks on a 2.5 second interval, with the RPC port 20443 exposed (https://localhost:20443/v2/info):\n\n```shell\ndocker run -p \"20443:20443\" -e \"MINE_INTERVAL=2.5s\" hirosystems/stacks-api-e2e\n\n```\n\nAn 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:\n\n```shell\ndocker run -p \"20443:20443\" -e \"MINE_INTERVAL=2.5s\" -e \"STACKS_EVENT_OBSERVER=host.docker.internal:3700\" hirosystems/stacks-api-e2e\n```\n\nA Stacks 2.1 `coinbase-alt-recipient` reward address can be configured using the `REWARD_RECIPIENT` environment variable.\nThis configures the Stacks node `[miner.block_reward_recipient]` toml config value.\nIf not specified, regular `coinbase` transactions will be mined.\nNote that the address will receive STX rewards 100 blocks _after_ Epoch 2.1 is activated.\nUsage example:\n\n```shell\ndocker run -p \"20443:20443\" -e \"REWARD_RECIPIENT=STQM73RQC4EX0A07KWG1J5ECZJYBZS4SJ4ERC6WN\" hirosystems/stacks-api-e2e\n```\n\nIn addition, the image has several tags providing different Stacks bootstrapping sequence configs:\n\n- The default tag `latest` starts directly in epoche 2.1 with PoX-2 activated\n- 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\n\nIt's possible to build images with custom bootstrapping sequences by specifying the build args:\n\n- `STACKS_21_HEIGHT` - the burnblock height at which epoch 2.1 is activated\n- `STACKS_POX2_HEIGHT` - the burnblock height at which PoX-2 is activated\n\nNote that the first Stacks block will be mined at burnblock height 104.\nSo, 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`:\n\n```shell\n# clone repo\ngit clone https://github.com/hirosystems/stacks-regtest-env.git\ncd stacks-regtest-env\n# build\ndocker build -t my_image -f Dockerfile.e2e --build-arg \"STACKS_21_HEIGHT=114\" --build-arg \"STACKS_POX2_HEIGHT=124\" .\n# run\ndocker run -p \"20443:20443\" -e \"MINE_INTERVAL=5s\" my_image\n```\n\n## Run with Docker Compose\n\nClone this repo and change to its directory:\n\n```shell\ngit clone https://github.com/hirosystems/stacks-regtest-env.git\ncd stacks-regtest-env\n```\n\nRun the command to start the network:\n\n```shell\ndocker compose -f docker-compose-miner.yml -f docker-compose-follower.yml up --build -d\n```\n\nThe initial [101 blocks on bitcoind](https://developer.bitcoin.org/examples/testing.html#regtest-mode) (required to have any spendable tBTC in regtest) are mined immediately, after which Stacks blocks will be mined for every new bitcoin block.\n\nThe block mining interval defaults to 500ms. This can be configured with the `MINE_INTERVAL` environment variable, for example:\n\n```shell\nMINE_INTERVAL=2.5s docker compose -f docker-compose-miner.yml -f docker-compose-follower.yml up --build -d\n```\n\nThe Stacks 2.1 `coinbase-alt-recipient` reward address can be configured using the `REWARD_RECIPIENT` environment variable.\nThis configures the Stacks node `[miner.block_reward_recipient]` toml config value.\nIf not specified, regular `coinbase` transactions will be mined.\nNote that the address will receive STX rewards 100 blocks _after_ Epoch 2.1 is activated.\nUsage example:\n\n```shell\nREWARD_RECIPIENT=STQM73RQC4EX0A07KWG1J5ECZJYBZS4SJ4ERC6WN MINE_INTERVAL=2.5s docker compose -f docker-compose-miner.yml -f docker-compose-follower.yml up --build -d\n```\n\n#### The following services are created\n\n###### Bitcoind node in regtest mode\n\n- JSON-RPC interface available at http://localhost:18443\n- RPC auth username and password are both `btc`\n- tBTC is available from the miner account:\n  - Address: `miEJtNKa3ASpA19v5ZhvbKTEieYjLpzCYT`\n  - Private key: `9e446f6b0c6a96cf2190e54bcd5a8569c3e386f091605499464389b8d4e0bfc201`\n  - Private key (WIF format): `cStMQXkK5yTFGP3KbNXYQ3sJf2qwQiKrZwR9QJnksp32eKzef1za`\n\n###### Mining script that automatically triggers bitcoind to mine new Bitcoin blocks\n\n- Block mining interval defaults to 500ms, configure using the `MINE_INTERVAL` environment variable\n\n###### Stacks-node in kypton mode (i.e. a regtest-like local testnet)\n\n- RPC available at http://localhost:20443/v2/info\n- STX are preseeded to several accounts listed in [`stacks-krypton-miner.toml`](stacks-krypton-miner.toml), first account:\n  - Address: `STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6`\n  - Key: `cb3df38053d132895220b9ce471f6b676db5b9bf0b4adefb55f2118ece2478df01`\n\n###### Stacks API instance\n\n- API available at http://localhost:3999/extended/v1/block\n- Playground/debug webpages listed at http://localhost:3999/extended/v1/debug/broadcast\n\n###### PostgreSQL database required by the Stacks API\n\n- PG port is available at 5490\n- Both username and password are `postgres`\n- Database name: `stacks_blockchain_api`\n\n_Note:_ The chainstate is reset every time docker compose `up` is run.\n\n### Shutdown\n\n```shell\ndocker compose -f docker-compose-miner.yml -f docker-compose-follower.yml down --volumes --remove-orphans --timeout=1 --rmi=all\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhirosystems%2Fstacks-regtest-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhirosystems%2Fstacks-regtest-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhirosystems%2Fstacks-regtest-env/lists"}