{"id":19178051,"url":"https://github.com/cmdruid/regtest-workbench","last_synced_at":"2025-05-07T20:44:19.181Z","repository":{"id":38187514,"uuid":"491282667","full_name":"cmdruid/regtest-workbench","owner":"cmdruid","description":"A containerized stack of Bitcoin and Lightning, plus a full suite of development tools. Prototype and deploy your next project with lightning speed!","archived":false,"fork":false,"pushed_at":"2022-10-12T19:36:20.000Z","size":8040,"stargazers_count":15,"open_issues_count":6,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-07T20:43:54.743Z","etag":null,"topics":["bitcoin","core-lightning","developer-tools","lightning-network","regtest"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmdruid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-05-11T21:53:19.000Z","updated_at":"2024-07-09T09:47:57.000Z","dependencies_parsed_at":"2023-01-19T14:15:50.136Z","dependency_job_id":null,"html_url":"https://github.com/cmdruid/regtest-workbench","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/cmdruid%2Fregtest-workbench","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdruid%2Fregtest-workbench/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdruid%2Fregtest-workbench/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdruid%2Fregtest-workbench/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmdruid","download_url":"https://codeload.github.com/cmdruid/regtest-workbench/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252954143,"owners_count":21830895,"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":["bitcoin","core-lightning","developer-tools","lightning-network","regtest"],"created_at":"2024-11-09T10:36:35.537Z","updated_at":"2025-05-07T20:44:19.152Z","avatar_url":"https://github.com/cmdruid.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Regtest Workbench\n\nA robust, featured-rich development environment for building on-top of Bitcoin and Lightning.\n\nLaunch multiple Bitcoin / Lightning nodes, and watch them form an automated network of miners, validators, and lightning channels. Each node contains an interactive terminal, web wallet, and suite of development tools.\n\nAlso included in each node:\n - Multiple interfaces to connect with: Spark, REST, LightningRPC, and more.\n - Full Tor (V3) services support for all interfaces (plus peering!).\n - Support for latest version of Zeus wallet via REST and sparko connect.\n - Fully automated opening and balancing of channels between nodes.\n - Automated loading and hot-loading of plugins for Core Lightning.\n - Multiple launch configurations: safe mode, dev mode, and headless mode.\n - Plugins for auto-pay and invoice traffic generation.\n\nEverything is configured out of the box. Simply open up a node port and connect your application. Prototype and deploy your next project with lightning speed!\n\n## How to Use\n\n\u003e *Note: Make sure that docker is installed, and your user is part of the docker group.*\n\nTo spin up a basic network of three nodes:\n\n```shell\n## Clone this repository, and make it your working directory.\n\ngit clone \"https://github.com/cmdruid/regtest-workbench.git\"\ncd regtest-workbench\n\n## Compiles all the binaries that we will need. May take a while!\n./workbench.sh build\n\n## Your first (and main) node. Seeds the blockchain and mines blocks.\n./workbench.sh start master --miner\n\n## Meet Alice, who connects to master and requests funding.\n./workbench.sh start alice --faucet master\n\n## Meet Bob, also funded by master, who peers and opens a channel with Alice.\n./workbench.sh start bob --faucet master --channels alice\n\n## Meet Carol, who likes to use shorter commands, and start in headless mode.\n./workbench.sh start carol -f master -c alice,bob --headless\n\n## ... repeat for as many nodes as you like!\n\n## You can also launch many nodes at once.\n./workbench.sh spawn\n\n## A detailed guide is built into the help screen.\n./workbench.sh --help\n```\nThe `start` keyword designates your node with a name tag. Each node will automatically connect to its designated peers, request funds from a faucet, open payment channels, and collectively balance those channels.\n\nThe `--peers` flag will instruct nodes on whom to peer with, and share transactions / blocks.\nThe `--faucet` flag will instruct your node to peer and request funds from another node.\nThe `--channels` flag will instruct your node to peer and open channels with another node.\nThe `--peers` and `--channels` flags accept a comma-separated list of nametags (*e.x alice,bob,carol*).\n\nBy default, nodes will request a balance of 10 BTC, and open channels with a balance of 5 million sats (split 50/50 between parties). You can modify these settings (and much more) by editing the `.env.sample` file at the root of this repo.\n\nUse the `--miner` flag with your first node in order to initiate the chain. Your miner will detect an empty chain, then auto-generate blocks up to a certain height. Block rewards require at least 100 blocks to mature, so the default starting height is 150.\n\nBy default, Your miner is configured to watch the mempool, then auto-generate blocks when it sees an unconfirmed transaction. The default poll time is 2 seconds, so transactions should confirm quickly. If you wish to deploy multiple miners, use a different configuration that avoids chain splits.\n\nThe format for configuring each miner is `--miner=poll-time,interval-time,fuzz-amount` in seconds. For example, the configuration `0,10,20` will disable polling, schedule a block every 10 seconds, plus a random value between 1 and 20 seconds.\n\n\u003e Tip: *Use your initial miner node as your main faucet, since the block rewards will have made him filthy rich! Miners may also generate more blocks in order to procure funds if their wallet balance is low.*\n\nNodes with the `--rest` flag will provide a REST interface on port 3001 (provided by CL-REST). Include `--ports 3001 --ports 4001` if you wish to connect to it locally.\n\nNodes with the `--tor` flag will auto-magically use onion routing when peered with other tor-enabled nodes, no extra configuration required. This flag will also configure a node's endpoints as (v3) hidden services. Tor nodes can still communicate with non-tor nodes, but will default to using tor when available (unless given the `--local` flag).\n\nAll pertinent settings, keys and credentials for a node is namespaced and stored in the `/share` folder. Nodes will use this folder in order to peer and communicate with other nodes. The files for each node are refreshed when you restart that node, so configuration data will always be current.\n\n\u003e Note: *Nodes are designed to work completely over tor, using the `/share` folder. You can copy / distribute a node's shared files onto other machines and build a regtest network across the web!*\n\nEach node launches with a simple web-wallet for managing invoices and test payments (*provided by sparko*). Nodes will print their local address and login credentials to the console upon startup. You can also manage payments easily using `bitcoin-cli` and `lightning-cli`.\n\n\u003e Tip: *The short-hand `bcli` and `lcli` are also available. Check out the `config/.bash_aliases` file for more handy aliases!*\n\nUse the `--devmode` flag to enter a node's console before the startup script is run. This flag will also mount the /run folder directly, allowing you to hack / modify the source code for this project in real-time. Don't forget to use version control. ;-)\n\n\u003e Tip: *If you have a node suffering from issues, run the `node-start` command within the node's terminal. It is the main start script, and designed to help refresh configurations, restart services, or diagnose / resolve issues that crop up during the startup process. If all else fails, restart the node using the`--wipe` flag to erase its persistent storage, and give your node a fresh start!*\n\nAll nodes ship with Flask and Nodejs included, plus a core library of development tools. Check out the example projects located in `contrib/examples` if you want to jump into web/app development right away!\n\n\u003e *FYI contrib/examples is sparse at the moment. More demo projects will be added mid-June. Please contact me if you would like to help contribute!*\n\n## Repository Overview\n\n### \\#\\# ./build\n\nThis path contains the build script, related dockerfiles, and compiled binaries. When you run the `workbench.sh` script, it will fist scan the `build/dockerfiles` and `build/out` path in order to compare files. If a binary appears to be missing, the start script will then call the build script (with the related dockerfile), and request to build the missing binary from source. Compiled binaries are then copied `build/out`.\n\nIf you have just cloned this repositry, it's best to run `./workbench.sh build` as a first step, so that launching your first node doesn't force you to compile everything at once.\n\nAll files located in `build/out` are copied over to the main docker image and installed at build time, so feel free to include any binaries you wish! The script recognizes tar.gz compression, and will strip the first folder before unpacking into `/usr`, so make sure to pack your files accordingly.\n\nYou can also add your own `build/dockerfiles`, or modify the existing ones in order to try different builds and versions. If you add a custom dockerfile, make sure it also names the binary with a matching substring, so the start script can correctly determine if your binary is present / missing.\n\n### \\#\\# ./config\n\nThese are the configuration files used by the main services in the stack. The entire config folder is copied at build time, to `/root/config` in the image. Feel free to modify these files or add your own, then use commands `build` or `rebuild` to refresh the image.\n\nThe `.bash_aliases` file is also loaded upon startup, feel free to use it to customize your environment!\n\n### \\#\\# ./contrib\n\n*Work in progress. Will contain example templates and demos for building bitcoin / lightining connected apps.*\n\n### \\#\\# ./run\n\nThis folder contains the main `entrypoint.sh` script, libraries and tools, plus all other scripts used to manage services in the stack.\n\n- Most of the source code for this project is located in `lib`.\n- Files in `lib\\bin` are available in the container's PATH.\n- Files in `lib\\pylib` are available in the container's PYPATH.\n- Files in `lib\\nodelib` are available in the container's NODEPATH.\n- Files in `plugins` are loaded by lightningd at startup (*main script must match folder name*).\n- Scripts in `startup` are executed in alpha-numeric order when `node-start` is run.\n\nThe entire run folder is copied at build time, located at `/root/run` in the image. Feel free to modify these files or add your own, then use `--build` or `--rebuild` flags to refresh the image when restarting a node. When a node is started in `--devmode`, the `run` folder is mounted directly, and you can modify the source files in real-time.\n\n### \\#\\# ./share\n\nEach node will mount this folder on startup, then use it as a shared repository for providing their own configuration data. Each folder is namespaced after a node's hostname, and used by other nodes in order to peer and connect with each other. These files are constantly created and destroyed by their respective nodes, so that the data remains fresh and accurate.\n\nIf tor is enabled for a given node, its share data can also be copied to other machines for more complex configurations.\n\n## CL-REST\n\nStarting workbench with `--ports 3001` maps the `3001` port to the host's `3001` port. `3001` is CL-RESTS's data port. Likewise with `--ports 4001`, giving you access to the documentation port `https://localhost:4001/api-docs`.\n\n### Copying the cert and macaroon\n\nYou'll want to copy the cert and macaroon out of the container:\n\n```\ndocker cp bob.regtest.node:/data/certs/certificate.pem .\ndocker cp bob.regtest.node:/data/certs/access.macaroon .\n```\n\nHere's an sample Python call to the '/v1/getinfo` endpoint:\n\n```python\nimport base64, codecs, json, requests\n\nurl = \"https://localhost:3001/v1/getinfo\"\ncert_path = \"certificate.pem\"\nmacaroon = codecs.encode(open(\"access.macaroon\", \"rb\").read(), \"hex\")\nheaders = {\"macaroon\": macaroon, \"encodingtype\": \"hex\"}\nr = requests.get(url, headers=headers, verify=cert_path)\nprint(r.json())\n```\n\n\n## Development\n\n*Work in progress. Feel free to hack the project on your own!*\n\nThere are three main modes to choose from when launching a container: **safe mode**, **development mode**, and **headless mode**.\n\nBy default, a node will launch in safe mode. A copy of the `/run` folder is made at build time, and code changes to `/run` will not affect the node (unless you rebuild and re-launch). The node will continue to run in the background once you exit the node terminal. The node is also configured to self-restart in the event of a crash.\n\nWhen launching a node with `--devmode` enabled, a few things change. The `node-start` script will not start automatically; you will have to call it yourself. The `/run` folder will be mounted directly into the container, so you can modify the source code in real-time.\n\nAny changes to the source code will apply to *all* nodes. Re-run the start script to apply changes. When you exit the terminal, the container will be instantly destroyed, however the internal `/data` store will persist.\n\nIf you end up borking a node, use the `--wipe` flag at launch to erase the node's persistent storage. The start scripts are designed to be robust, and nodes are highly disposable. Feel free to crash, wipe, and re-launch nodes as often as you like!\n\nBoth safe-mode and dev-mode can be augmented with `--headless` mode, which launches a node without connecting to it. You can still monitor nodes through a management service like **portainer**, or simply login to the node using `./workbench login *nametag*`.\n\nTo mount folders into a node's environment, use the format `--mount local/path:/mount/path` for each folder you wish to mount. Paths can be relative or absolute.\n\nTo open and forward ports from a node's environment, use the format `--ports int1:ext1,int2:ext2, ...`, with a comma to separate port declarations, and colon to separate internal:external ports.\n\nThe `--passthru` flag will allow you to pass a quoted string of flags directly to the internal `docker run` script. With great power comes great responsibility! :-)\n\n## Contribution\n\nAll suggestions and contributions are welcome! If you have any questions about this project, feel free to submit an issue up above, or contact me on social media.\n\n## Tools\n\n**Bitcoin Core Config Generator**  \nCovers the myriad of options available for bitcoin.conf.  \nhttps://jlopp.github.io/bitcoin-core-config-generator\n\n**LNURL Decoder**\nDecode lnurl strings.    \nhttps://lnurl.fiatjaf.com/codec\n\n## Resources\n\n**Bitcoin Developer Reference**  \nA great resource for documentation on Bitcoin's RPC interface, and other technical details.  \nhttps://developer.bitcoin.org/reference/index.html\n\n**Bitcoin Github Docs**  \nAnother great resource for all things related to Bitcoin Core.  \nhttps://github.com/bitcoin/bitcoin/tree/master/doc\n\n**Core Lightning Documentation**  \nThe go-to resource for Core Lightning's RPC interface.  \nhttps://lightning.readthedocs.io\n\n**Core Lighting REST API Docs**  \nDocumentation for the REST interface that is provided by the RTL team.  \nhttps://github.com/Ride-The-Lightning/c-lightning-REST#apis\n\n**LNURL Specification**  \nDocumentation that details the LNURL specification.  \nhttps://github.com/fiatjaf/lnurl-rfc\n\n**Bolt 12 Landing Page**  \nA nice landing page for info regarding the Bolt 12 specification.  \nhttps://bolt12.org\n\n**Sparko Client**  \nIncredibly useful web-rpc interface and web-client for Core Lightning.  \nhttps://github.com/fiatjaf/sparko-client\n\n**Pyln-client**  \nThe main library for interfacing with Core Lightning over RPC. Very powerful.  \nhttps://github.com/ElementsProject/lightning/tree/master/contrib/pyln-client\n\n**Python Documentation**  \nOfficial resource for the python language.  \nhttps://docs.python.org/3\n\n**Flask Documentation**  \nThe go-to resource for documentation on using Flask.  \nhttps://flask.palletsprojects.com/en/2.1.x\n\n**Node.js Documentation**  \nThe go-to resource for documentation on using Nodejs.  \nhttps://nodejs.org/api\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmdruid%2Fregtest-workbench","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmdruid%2Fregtest-workbench","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmdruid%2Fregtest-workbench/lists"}