{"id":13561429,"url":"https://github.com/bitlightlabs/bitlight-local-env-public","last_synced_at":"2025-04-03T17:30:49.775Z","repository":{"id":224074873,"uuid":"761201816","full_name":"bitlightlabs/bitlight-local-env-public","owner":"bitlightlabs","description":"A ready-to-use Bitcoin regtest environment required for testing the open-source RGB project by BitLight","archived":false,"fork":false,"pushed_at":"2024-08-23T19:17:43.000Z","size":411,"stargazers_count":25,"open_issues_count":0,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-01T19:48:19.138Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://blog.bitlightlabs.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitlightlabs.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-21T12:37:41.000Z","updated_at":"2025-03-31T04:13:40.000Z","dependencies_parsed_at":"2024-08-01T13:17:10.668Z","dependency_job_id":"23ec9a38-7e42-462c-a710-7bb7a828a6e7","html_url":"https://github.com/bitlightlabs/bitlight-local-env-public","commit_stats":null,"previous_names":["bitlightlabs/bitlight-local-env-public"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitlightlabs%2Fbitlight-local-env-public","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitlightlabs%2Fbitlight-local-env-public/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitlightlabs%2Fbitlight-local-env-public/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitlightlabs%2Fbitlight-local-env-public/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitlightlabs","download_url":"https://codeload.github.com/bitlightlabs/bitlight-local-env-public/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247046801,"owners_count":20874725,"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-08-01T13:00:56.563Z","updated_at":"2025-04-03T17:30:45.503Z","avatar_url":"https://github.com/bitlightlabs.png","language":"Shell","funding_links":[],"categories":["Services"],"sub_categories":["Main RGB Standards"],"readme":"# Bitlight Local Development Environment\n\nThis is a local development environment for Bitlight. It is based on Docker and Docker Compose.\n\n## Prerequisites\n\n- [Docker](https://www.docker.com/)\n- [Docker Compose](https://docs.docker.com/compose/)\n- Make\n\n## Getting Started\n\n1. Clone this repository\n2. check the `.env` file and change the values if needed\n3. Run `make start` or `make up` to start the development environment\n4. Run `curl localhost:3002` to see the Esplora API running\n5. Run `make test` to run the tests\n6. Open the `http://localhost:5002` in your browser to see the Esplora UI\n\n```shell\nbitlight-local-env % curl -s localhost:3002/mempool | jq\n{\n  \"count\": 0,\n  \"vsize\": 0,\n  \"total_fee\": 0,\n  \"fee_histogram\": []\n}\n```\n\u003e For more information about the Esplora API, check the [Esplora API documentation](https://github.com/Blockstream/esplora/blob/master/API.md)\n\n## Commands\n\n- `make start` - Start the development environment with full logs\n- `make up` - Start the development environment\n- `make down` - Stop the development environment\n- `make restart` - Restart the development environment\n- `make clean` - Remove all the containers and volumes\n- `make recreate` - Recreate the development environment\n- `make logs` - Show the logs of the development environment\n- `make full-logs` - Show the logs of the development environment with full logs\n- `make cli` or `make core-cli` - Run a bash shell inside the bitcoin-core container\n- `make alice-cli` - Run a bkd-cli repl inside the Alice Wallet container\n- `make bob-cli` - Run a bkd-cli repl inside the Bob Wallet container\n\n- `make up-lnd` - Start the LND containers: Alice, Bob\n- `make down-lnd` - Stop the LND containers\n\n- `make start-docs` - Start the documentation server, the docs is located in the `docs` folder\n\nFor manual run tests:\n- `make activate` - Get environment variables and activate them\n\n\u003e Other commands are available, check the `Makefile` for more information\n\n## CLI Commands\n\nRun `make cli` to enter the bitcoin-core container. The following commands are available:\n\n### Custom commands\n\nIn the bitcoin-core container, the following commands are available (they are just bash scripts in the `docker/bitcoin/cli/bin` folder):\n\n- `load_wallet` - Load the default minter wallet and show address and balance\n- `mint \u003cblocks_number\u003e` - Mint \\\u003cblocks_number\\\u003e blocks to the default wallet\n- `send \u003caddress\u003e \u003camount\u003e` - Send \\\u003camount\\\u003e to \\\u003caddress\\\u003e from the default wallet\n\n\u003e The default wallet is `wallet`, and used for minting and sending BTC.\n\u003e You can create your own commands by adding a new bash script in the `docker/bitcoin/cli/bin` folder\n\n### Wallets\n\nIn Example, we have two wallets: Alice and Bob. You can use the following commands to interact with the wallets:\n\n- `make alice-cli` - Run a bkd-cli repl inside the Alice Wallet container\n- `make bob-cli` - Run a bkd-cli repl inside the Bob Wallet container\n\nIf you want to add new wallets,\n1. you can refer to the `docker-compose.yml` file and add a new wallet service with service name `wallet-\u003cwallet_name\u003e`.\n2. run `make up` to start the new wallet.\n3. run `make wallet-\u003cwallet_name\u003e-cli` to enter the new wallet container.\n\n### Examples\n\n#### Create A new wallet Alice and send 25 BTC to Alice's address\n\nRun `make alice-cli` to enter the Alice Wallet container and chose the descriptor to start the REPL.\n\n```console\nPlease choose a descriptor to start the REPL:\n - (9) RGB Descriptor 9/*: tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/*)\n - (90) RGB Descriptor 9/0: tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/0)\n - (00) Bitcoin Descriptor 0/0: tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/0/0)\n - (*) quit\nEnter your choice: 9 \u003c== choose 9 for RGB Descriptor 9/*\n```\n\nNow, you can use the `wallet` object to interact with the wallet, for example:\n```shell\nwallet sync\nwallet get_balance\nwallet list_unspent\nwallet get_new_address\n```\n\nThe output should be similar to the following:\n```console\n$ make alice-cli \ndocker compose -p bitlight-local-env exec -it  wallet-alice /start-wallet.sh repl\nStarting wallet...\nWallet Name: alice\nNetwork             :  regtest\nWallet Name         :  alice\nFingerprint         :  5183a8d8\nRoot XPRV           :  tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW\nXPUB                :  [5183a8d8/86'/1'/0']tpubDDtdVYn7LWnWNUXADgoLGu48aLH4dZ17hYfRfV9rjB7QQK3BrphnrSV6pGAeyfyiAM7DmXPJgRzGoBdwWvRoFdJoMVpWfmM9FCk8ojVhbMS/*\nFixed XPUB          :  [5183a8d8/86'/1'/0']tpubDDtdVYn7LWnWNUXADgoLGu48aLH4dZ17hYfRfV9rjB7QQK3BrphnrSV6pGAeyfyiAM7DmXPJgRzGoBdwWvRoFdJoMVpWfmM9FCk8ojVhbMS/\u003c0;1;9;10\u003e/*\nRGB Descriptor 9/0  :  tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/0)\nRGB Address         :  bcrt1pr3rupmav8a7av7dqfyvynu2wk02lduggnh9ln4ndze9aqvuv9y3sklwrss\nRGB Descriptor 9/*  :  tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/*)\nBitcoin Descriptor 0/0:  tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/0/0)\nBitcoin Address     :  bcrt1pn0s2pajhsw38fnpgcj79w3kr3c0r89y3xyekjt8qaudje70g4shs20nwfx\nBalance             :  0\nWallet is ready\nPlease choose a descriptor to start the REPL:\n - (9) RGB Descriptor 9/*: tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/*)\n - (90) RGB Descriptor 9/0: tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/0)\n - (00) Bitcoin Descriptor 0/0: tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/0/0)\n - (*) quit\nEnter your choice: 9\nStarting REPL with descriptor tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/*)\nuse 'wallet' to interact with the wallet of alice\nuse 'help' to see available commands\nAvailable commands:\n  wallet sync\n  wallet get_balance\n  wallet get_new_address\n  wallet list_unspent\nPress Ctrl+D to exit\n\u003e\u003e \n```\n\nIn the output, you can see the base information about the wallet, such as the `XPUB`, `RGB Address`, and `Balance`.\nNow you can use the `wallet` object to interact with the wallet, for example:\n\n```console\n\u003e\u003e wallet sync \n{}\n\u003e\u003e wallet get_balance\n{\n  \"satoshi\": {\n    \"confirmed\": 0,\n    \"immature\": 0,\n    \"trusted_pending\": 0,\n    \"untrusted_pending\": 0\n  }\n}\n\u003e\u003e wallet list_unspent \n[]\n\u003e\u003e wallet get_new_address\n{\n  \"address\": \"bcrt1pr3rupmav8a7av7dqfyvynu2wk02lduggnh9ln4ndze9aqvuv9y3sklwrss\"   \u003c== Alice's address used to receive BTC\n}\n\u003e\u003e \n```\nRemember the address `bcrt1pr3rupmav8a7av7dqfyvynu2wk02lduggnh9ln4ndze9aqvuv9y3sklwrss` for the next step.\nNow, let's send 25 BTC to Alice's address.\n\nOpen a new terminal and run `make core-cli` to enter the bitcoin-core container, and run following commands:\n```shell\nload_wallet\nsend bcrt1pr3rupmav8a7av7dqfyvynu2wk02lduggnh9ln4ndze9aqvuv9y3sklwrss 25\nmint 1\n```\nThe output should be similar to the following:\n```console\n$ make core-cli \ndocker compose -p bitlight-local-env exec -it -w /cli bitcoin-core /cli/active.sh\n/cli $ load_wallet\nload wallet's address: bcrt1qv6428v9lzk9ac5aswp4hlaf773r48824stfvx9 with balance: 50.00000000\n/cli $ send bcrt1pr3rupmav8a7av7dqfyvynu2wk02lduggnh9ln4ndze9aqvuv9y3sklwrss 25\nload wallet's address: bcrt1qx4mwpxpw0d8prsrw4fg8q2s94au6s2qk5dwc9g with balance: 50.00000000\n9b2eca8ba85f2e11e97c820bfc5990a20387812f313cea6e8889c309ed8bff45\nSent 25 to bcrt1pr3rupmav8a7av7dqfyvynu2wk02lduggnh9ln4ndze9aqvuv9y3sklwrss\n/cli $ mint 1\nload wallet's address: bcrt1q2rtzrwrlpjnknsct2re3ez595wx2c9ezmspacl with balance: 24.99996940\n[\n  \"13b179e2d1735e9dce6d5eb5f4b6272d354db2fa062abd66d2e8f08e63adb20f\"\n]\n/cli $ \n```\n\nNow, open `http://localhost:5002/tx/recent` in your browser, you should see the transaction with 25 BTC sent to Alice's address, open it, and you will see the transaction details.\n\n![screen_shot_transaction_details.png](docs/public/img/screen_shot_transaction_details.png)\n\nNow, let's check the balance of Alice's wallet by running `make alice-cli` or  go back to the previous terminal, and run the following commands:\n```shell\nwallet sync\nwallet get_balance\nwallet list_unspent\n```\nThe output should be similar to the following:\n```console\n$ make alice-cli\ndocker compose -p bitlight-local-env exec -it  wallet-alice /start-wallet.sh repl\nStarting wallet...\nWallet Name: alice\nNetwork             :  regtest\nWallet Name         :  alice\nFingerprint         :  5183a8d8\nRoot XPRV           :  tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW\nXPUB                :  [5183a8d8/86'/1'/0']tpubDDtdVYn7LWnWNUXADgoLGu48aLH4dZ17hYfRfV9rjB7QQK3BrphnrSV6pGAeyfyiAM7DmXPJgRzGoBdwWvRoFdJoMVpWfmM9FCk8ojVhbMS/*\nFixed XPUB          :  [5183a8d8/86'/1'/0']tpubDDtdVYn7LWnWNUXADgoLGu48aLH4dZ17hYfRfV9rjB7QQK3BrphnrSV6pGAeyfyiAM7DmXPJgRzGoBdwWvRoFdJoMVpWfmM9FCk8ojVhbMS/\u003c0;1;9;10\u003e/*\nRGB Descriptor 9/0  :  tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/0)\nRGB Address         :  bcrt1pr3rupmav8a7av7dqfyvynu2wk02lduggnh9ln4ndze9aqvuv9y3sklwrss\nRGB Descriptor 9/*  :  tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/*)\nBitcoin Descriptor 0/0:  tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/0/0)\nBitcoin Address     :  bcrt1pn0s2pajhsw38fnpgcj79w3kr3c0r89y3xyekjt8qaudje70g4shs20nwfx\nBalance             :  2500000000\nWallet is ready\nPlease choose a descriptor to start the REPL:\n - (9) RGB Descriptor 9/*: tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/*)\n - (90) RGB Descriptor 9/0: tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/0)\n - (00) Bitcoin Descriptor 0/0: tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/0/0)\n - (*) quit\nEnter your choice: 9  \u003c== choose 9 for RGB Descriptor 9/*\nStarting REPL with descriptor tr(tprv8ZgxMBicQKsPeHzjP5LTL818LxwHbJNLZRa98Qdnn7M98fW15365cB1Sz9QZvYufASRKH6JEPhfpxVuFTKMHxDcEAVboqKuZdMmxzKVhMnW/86'/1'/0'/9/*)\nuse 'wallet' to interact with the wallet of alice\nuse 'help' to see available commands\nAvailable commands:\n  wallet sync\n  wallet get_balance\n  wallet get_new_address\n  wallet list_unspent\nPress Ctrl+D to exit\n\u003e\u003e wallet sync\n{}\n\u003e\u003e wallet get_balance\n{\n  \"satoshi\": {\n    \"confirmed\": 2500000000,\n    \"immature\": 0,\n    \"trusted_pending\": 0,\n    \"untrusted_pending\": 0\n  }\n}\n\u003e\u003e wallet list_unspent\n[\n  {\n    \"is_spent\": false,\n    \"keychain\": \"External\",\n    \"outpoint\": \"9b2eca8ba85f2e11e97c820bfc5990a20387812f313cea6e8889c309ed8bff45:1\",\n    \"txout\": {\n      \"script_pubkey\": \"51201c47c0efac3f7dd679a0491849f14eb3d5f6f1089dcbf9d66d164bd0338c2923\",\n      \"value\": 2500000000\n    }\n  }\n]\n```\nNow, you can see the balance of Alice's wallet is 25 BTC, and the transaction is confirmed.\n\n### Bitcoin Core commands\n- `bitcoin-cli -regtest getblockchaininfo` - Get the blockchain information\n- `bitcoin-cli -regtest getnewaddress` - Get a new address\n- `bitcoin-cli -regtest generatetoaddress 101 \u003caddress\u003e` - Generate 101 blocks to the address\n- `bitcoin-cli -regtest getbalance` - Get the balance of the wallet\n\nThere are more commands available. Run `bitcoin-cli help` to see all the available commands.\n\n## Configuration\n\nThe configuration is done via the `.env` file. The following variables are available:\n\n- `API_PORT` - The port for the Esplora API\n- `RPC_USER` - The username for the RPC server\n- `RPC_PASSWORD` - The password for the RPC server\n\n## TODO\n\n- [x] Create a docker-compose file\n- [x] Create a bitcoind container and configure it to run on regtest\n- [x] Configure Esplora API to use the bitcoind container\n- [x] Create blocks for the blockchain via mining\n- [x] cli to interact with the bitcoind container with examples\n- [x] Add Esplora UI service","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitlightlabs%2Fbitlight-local-env-public","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitlightlabs%2Fbitlight-local-env-public","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitlightlabs%2Fbitlight-local-env-public/lists"}