Add local regtest payment setup with esplora (#494)

zupzup · web-flow · commit fe9f29dad3b1 · 2025-04-30T16:14:30.000+02:00
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
 /target
 /contacts/*
+/esplora/.docker_data/
 data/
 /frontend_build/*
 /identity/*
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,7 @@
+# 0.3.9
+
+* Add possibility to use a local regtest esplora setup for payment
+
 # 0.3.8
 
 * Add `esplora_base_url` as config parameter to be able to use a custom esplora based block explorer
diff --git a/crates/bcr-ebill-api/Cargo.toml b/crates/bcr-ebill-api/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bcr-ebill-api"
-version = "0.3.8"
+version = "0.3.9"
 edition = "2024"
 
 [lib]
diff --git a/crates/bcr-ebill-api/src/external/bitcoin.rs b/crates/bcr-ebill-api/src/external/bitcoin.rs
@@ -81,6 +81,9 @@ impl BitcoinClient {
             Network::Bitcoin => {
                 format!("{}/api{path}", get_config().esplora_base_url)
             }
+            Network::Regtest => {
+                format!("{}/regtest/api{path}", get_config().esplora_base_url)
+            }
             _ => {
                 format!("{}/testnet/api{path}", get_config().esplora_base_url)
             }
@@ -92,6 +95,9 @@ impl BitcoinClient {
             Network::Bitcoin => {
                 format!("{}{path}", get_config().esplora_base_url)
             }
+            Network::Regtest => {
+                format!("{}/regtest{path}", get_config().esplora_base_url)
+            }
             _ => {
                 format!("{}/testnet{path}", get_config().esplora_base_url)
             }
diff --git a/crates/bcr-ebill-core/Cargo.toml b/crates/bcr-ebill-core/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bcr-ebill-core"
-version = "0.3.8"
+version = "0.3.9"
 edition = "2024"
 
 [lib]
diff --git a/crates/bcr-ebill-persistence/Cargo.toml b/crates/bcr-ebill-persistence/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bcr-ebill-persistence"
-version = "0.3.8"
+version = "0.3.9"
 edition = "2024"
 
 [lib]
diff --git a/crates/bcr-ebill-transport/Cargo.toml b/crates/bcr-ebill-transport/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bcr-ebill-transport"
-version = "0.3.8"
+version = "0.3.9"
 edition = "2024"
 
 [lib]
diff --git a/crates/bcr-ebill-wasm/Cargo.toml b/crates/bcr-ebill-wasm/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bcr-ebill-wasm"
-version = "0.3.8"
+version = "0.3.9"
 edition = "2024"
 
 [lib]
diff --git a/crates/bcr-ebill-wasm/main.js b/crates/bcr-ebill-wasm/main.js
@@ -30,8 +30,10 @@ document.getElementById("clear_bill_cache").addEventListener("click", clearBillC
 async function start() {
   let config = {
     log_level: "debug",
-    bitcoin_network: "testnet",
-    esplora_base_url: "https://blockstream.info",
+    bitcoin_network: "regtest", // local reg test
+    esplora_base_url: "http://localhost:8094", // local reg test via docker-compose
+    // bitcoin_network: "testnet",
+    // esplora_base_url: "https://blockstream.info",
     nostr_relay: "wss://bitcr-cloud-run-05-550030097098.europe-west1.run.app",
     job_runner_initial_delay_seconds: 1,
     job_runner_check_interval_seconds: 600,
@@ -224,9 +226,9 @@ async function triggerBill() {
 
     const now = new Date();
     const issue_date = now.toISOString().split('T')[0];
-    const threeMonthsLater = new Date(now);
-    threeMonthsLater.setMonth(now.getMonth() + 3);
-    const maturity_date = threeMonthsLater.toISOString().split('T')[0];
+    const nMonthsLater = new Date(now);
+    nMonthsLater.setMonth(now.getMonth() + 0); // use to set maturity date after issue date
+    const maturity_date = nMonthsLater.toISOString().split('T')[0];
 
     let file_upload_id = document.getElementById("file_upload_id").value || undefined;
     let node_id = document.getElementById("node_id_bill").value;
diff --git a/crates/bcr-ebill-web/Cargo.toml b/crates/bcr-ebill-web/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bcr-ebill-web"
-version = "0.3.8"
+version = "0.3.9"
 edition = "2024"
 
 [dependencies]
diff --git a/docs/esplora.md b/docs/esplora.md
@@ -0,0 +1,44 @@
+# Esplora
+
+To check the bitcoin blockchain, we use the [Esplora](https://github.com/Blockstream/esplora) API.
+
+You can either use a publicly running service such as [Blockstream](https://blockstream.info/testnet/), or run a local regtest-based
+Esplora instance using Docker.
+
+For this, you also have to set the config to use `regtest` as a bitcoin network and `http://localhost:8094` for the explorer:
+
+```javascript
+  let config = {
+    log_level: "debug",
+    bitcoin_network: "regtest",
+    esplora_base_url: "http://localhost:8094",
+    nostr_relay: "wss://bitcr-cloud-run-05-550030097098.europe-west1.run.app",
+    job_runner_initial_delay_seconds: 1,
+    job_runner_check_interval_seconds: 600,
+  };
+```
+
+In the repository root, navigate to `./esplora` and run:
+
+```bash
+docker-compose up
+```
+
+This runs a regtest based Esplora instance, which you can interact with like this:
+
+```bash
+# load default wallet
+docker exec -it esplora-esplora-1 /srv/explorer/bitcoin/bin/bitcoin-cli -regtest -rpcwallet=default -rpccookiefile=/data/bitcoin/regtest/.cookie loadwallet default
+
+# generate blocks
+docker exec -it esplora-esplora-1 /srv/explorer/bitcoin/bin/bitcoin-cli -regtest -rpcwallet=default -rpccookiefile=/data/bitcoin/regtest/.cookie -generate 10
+```
+
+You can also use the `justfile` to send a payment to a given address like this:
+
+```bash
+just pay mtsCkPiHCE5gdvhV9aGD4AbpArMQADc3Ju 1.0
+```
+
+This will send the payment and mine a block and then you can check it here: [http://localhost:8094/regtest/address/mtsCkPiHCE5gdvhV9aGD4AbpArMQADc3Ju](http://localhost:8094/regtest/address/mtsCkPiHCE5gdvhV9aGD4AbpArMQADc3Ju)
+
diff --git a/docs/index.md b/docs/index.md
@@ -10,4 +10,5 @@ This is the documentation of the E-Bill API. The API can be used both as a Web A
 * [Web Configuration](web_configuration.md)
 * [Releasing new WASM versions](wasm_releasing.md)
 * [Testing](testing.md)
+* [Esplora](esplora.md)
 
diff --git a/esplora/docker-compose.yml b/esplora/docker-compose.yml
@@ -0,0 +1,12 @@
+services:
+  esplora:
+    image: blockstream/esplora:latest
+    command: >
+      bash -c "/srv/explorer/run.sh bitcoin-regtest explorer"
+    volumes:
+      - ./.docker_data/esplora/:/data
+    ports:
+      - "50001:50001"  # Electrum server
+      - "18443:18443"  # Bitcoin core
+      - "18444:18444"  # Bitcoin core
+      - "8094:80"      # Esplora frontend
diff --git a/justfile b/justfile
@@ -0,0 +1,20 @@
+# Usage:
+# just pay <address> <amount>
+# Example:
+# just pay mtsCkPiHCE5gdvhV9aGD4AbpArMQADc3Ju 1.0
+
+pay address amount:
+    @echo "Loading wallet..."
+    docker exec -it esplora-esplora-1 /srv/explorer/bitcoin/bin/bitcoin-cli -regtest -rpcwallet=default -rpccookiefile=/data/bitcoin/regtest/.cookie loadwallet default || true
+
+    @echo "generate funds..."
+    docker exec -it esplora-esplora-1 /srv/explorer/bitcoin/bin/bitcoin-cli -regtest -rpcwallet=default -rpccookiefile=/data/bitcoin/regtest/.cookie -generate 1 || true
+
+    @echo "Sending {{amount}} BTC to {{address}}..."
+    docker exec -it esplora-esplora-1 /srv/explorer/bitcoin/bin/bitcoin-cli -regtest -rpcwallet=default -rpccookiefile=/data/bitcoin/regtest/.cookie sendtoaddress {{address}} {{amount}}
+
+    @echo "Mining block to {{address}}..."
+    docker exec -it esplora-esplora-1 /srv/explorer/bitcoin/bin/bitcoin-cli -regtest -rpcwallet=default -rpccookiefile=/data/bitcoin/regtest/.cookie generatetoaddress 1 {{address}}
+
+    @echo "Done."
+

-Original file line number
+Diff line change
@@ @@ -1,3 +1,7 @@ @@
 +# 0.3.9
++
 +* Add possibility to use a local regtest esplora setup for payment
++
 # 0.3.8
 * Add `esplora_base_url` as config parameter to be able to use a custom esplora based block explorer
Original file line number	Diff line number	Diff line change
`@@ -81,6 +81,9 @@ impl BitcoinClient {`
`81`	`81`	`Network::Bitcoin => {`
`82`	`82`	`format!("{}/api{path}", get_config().esplora_base_url)`
`83`	`83`	`}`
	`84`	`+ Network::Regtest => {`
	`85`	`+ format!("{}/regtest/api{path}", get_config().esplora_base_url)`
	`86`	`+ }`
`84`	`87`	`_ => {`
`85`	`88`	`format!("{}/testnet/api{path}", get_config().esplora_base_url)`
`86`	`89`	`}`
`@@ -92,6 +95,9 @@ impl BitcoinClient {`
`92`	`95`	`Network::Bitcoin => {`
`93`	`96`	`format!("{}{path}", get_config().esplora_base_url)`
`94`	`97`	`}`
	`98`	`+ Network::Regtest => {`
	`99`	`+ format!("{}/regtest{path}", get_config().esplora_base_url)`
	`100`	`+ }`
`95`	`101`	`_ => {`
`96`	`102`	`format!("{}/testnet{path}", get_config().esplora_base_url)`
`97`	`103`	`}`