add confirmations config flag, rewrite payment handling, remove gloo,rewrite payment, payment state in db, adapt bill data (#603)

Author: zupzup

.github/workflows/wasm_release.yml

@@ -49,7 +49,7 @@ jobs:
       - name: Install Rust toolchain
         uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: 1.87.0
+          toolchain: 1.89.0
 
       - name: Install wasm-pack
         run: |

CHANGELOG.md

@@ -1,3 +1,14 @@
+# 0.4.4
+
+* Add `num_confirmations_for_payment` config flag and a `payment_config` part of the api config, to configure the amount of confirmations needed until an on-chain payment is considered `paid`
+* Rewrite payment logic to iterate transactions and calculate payment state based on the first transaction that covers the amount
+    * We now are also able to differentiate between a payment not being sent, being in the mem pool, being paid and unconfirmed and paid and confirmed
+    * Add payment state for sell, recourse and bill payments to DB (breaking DB change - reset IndexedDB)
+    * Restructure `BillCurrentWaitingState` to remove duplication (breaking API change - check `index.d.ts`)
+        * Add info for if a payment is in the mempool with it's transaction id, as well as how many confirmations it has, in the bill data (breaking DB change - reset IndexedDB)
+* Removed the `gloo` dependency, since it's going to be archived
+* Add chain propagation for company chains and identity chain
+
 # 0.4.3
 
 * Add endpoints to fetch files as base64 for identity, contacts, companies and bills

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace.package]
-version = "0.4.3"
+version = "0.4.4"
 edition = "2024"
 license = "MIT"
 
@@ -30,11 +30,13 @@ chrono = { version = "0.4", default-features = false, features = [
   "serde",
   "clock",
 ] }
-tokio = { version = "1.43", default-features = false, features = [
+tokio = { version = "1.46", default-features = false, features = [
   "rt",
   "sync",
+  "macros",
+  "time",
 ] }
-tokio_with_wasm = { version = "0.8", features = ["rt", "sync"] }
+tokio_with_wasm = { version = "0.8", features = ["rt", "sync", "macros", "time"] }
 async-trait = "0.1"
 serde_json = "1"
 serde = { version = "1", default-features = false, features = ["derive"] }
@@ -57,6 +59,7 @@ miniscript = { version = "12.3" }
 base64 = "0.22"
 mockall = "0.13.1"
 bcr-ebill-core = { path = "./crates/bcr-ebill-core" }
+bcr-ebill-api = { path = "./crates/bcr-ebill-api" }
 bcr-ebill-persistence = { path = "./crates/bcr-ebill-persistence" }
 bcr-ebill-transport = { path = "./crates/bcr-ebill-transport" }
 surrealdb = { version = "2.3", default-features = false }

crates/bcr-ebill-api/src/external/bitcoin.rs

@@ -1,10 +1,16 @@
 use crate::get_config;
 use async_trait::async_trait;
-use bcr_ebill_core::{PublicKey, ServiceTraitBounds, util};
+use bcr_ebill_core::{
+    PublicKey, ServiceTraitBounds,
+    bill::{InMempoolData, PaidData, PaymentState},
+    util,
+};
 use bitcoin::{Network, secp256k1::Scalar};
 use log::debug;
 use serde::Deserialize;
 use thiserror::Error;
+use tokio::alias::try_join;
+use tokio_with_wasm as tokio;
 
 /// Generic result type
 pub type Result<T> = std::result::Result<T, super::Error>;
@@ -27,6 +33,10 @@ pub enum Error {
     /// all errors originating from dealing with private secp256k1 keys
     #[error("External Bitcoin Private Key error: {0}")]
     PrivateKey(String),
+
+    /// all errors originating from dealing with invalid data from the API
+    #[error("Got invalid data from the API")]
+    InvalidData(String),
 }
 
 #[cfg(test)]
@@ -38,16 +48,17 @@ use mockall::automock;
 pub trait BitcoinClientApi: ServiceTraitBounds {
     async fn get_address_info(&self, address: &str) -> Result<AddressInfo>;
 
-    #[allow(dead_code)]
     async fn get_transactions(&self, address: &str) -> Result<Transactions>;
 
-    #[allow(dead_code)]
     async fn get_last_block_height(&self) -> Result<u64>;
 
-    #[allow(dead_code)]
-    fn get_first_transaction(&self, transactions: &Transactions) -> Option<Txid>;
-
-    async fn check_if_paid(&self, address: &str, sum: u64) -> Result<(bool, u64)>;
+    /// Checks payment by iterating over the transactions on the address in chronological order, until
+    /// the target amount is filled, returning the respective payment status
+    async fn check_payment_for_address(
+        &self,
+        address: &str,
+        target_amount: u64,
+    ) -> Result<PaymentState>;
 
     fn get_address_to_pay(
         &self,
@@ -163,32 +174,17 @@ impl BitcoinClientApi for BitcoinClient {
         Ok(height)
     }
 
-    fn get_first_transaction(&self, transactions: &Transactions) -> Option<Txid> {
-        transactions.last().cloned()
-    }
-
-    async fn check_if_paid(&self, address: &str, sum: u64) -> Result<(bool, u64)> {
-        debug!("checking if btc address {address} is paid {sum}");
-        let info_about_address = self.get_address_info(address).await?;
-
-        // the received and spent sum need to add up to the sum
-        let received_sum = info_about_address.chain_stats.funded_txo_sum; // balance on address
-        let spent_sum = info_about_address.chain_stats.spent_txo_sum; // money already spent
-
-        // Tx is still in mem_pool (0 if it's already on the chain)
-        let received_sum_mempool = info_about_address.mempool_stats.funded_txo_sum;
-        let spent_sum_mempool = info_about_address.mempool_stats.spent_txo_sum;
-
-        let sum_chain_mempool: u64 =
-            received_sum + spent_sum + received_sum_mempool + spent_sum_mempool;
-        if sum_chain_mempool >= sum {
-            // if the received sum is higher than the sum we're looking
-            // to get, it's OK
-            Ok((true, received_sum + spent_sum)) // only return sum received on chain, so we don't
-        // return a sum if it's in mempool
-        } else {
-            Ok((false, 0))
-        }
+    async fn check_payment_for_address(
+        &self,
+        address: &str,
+        target_amount: u64,
+    ) -> Result<PaymentState> {
+        debug!("checking if btc address {address} is paid {target_amount}");
+        // in parallel, get current chain height, transactions and address info for the given address
+        let (chain_block_height, txs) =
+            try_join!(self.get_last_block_height(), self.get_transactions(address),)?;
+
+        payment_state_from_transactions(chain_block_height, txs, address, target_amount)
     }
 
     fn get_address_to_pay(
@@ -243,30 +239,218 @@ impl BitcoinClientApi for BitcoinClient {
     }
 }
 
+fn payment_state_from_transactions(
+    chain_block_height: u64,
+    txs: Transactions,
+    address: &str,
+    target_amount: u64,
+) -> Result<PaymentState> {
+    // no transactions - no payment
+    if txs.is_empty() {
+        return Ok(PaymentState::NotFound);
+    }
+
+    let mut total = 0;
+    let mut tx_filled = None;
+
+    // sort from back to front (chronologically)
+    for tx in txs.iter().rev() {
+        for vout in tx.vout.iter() {
+            // sum up outputs towards the address to check
+            if vout.scriptpubkey_address == *address {
+                total += vout.value;
+            }
+        }
+        // if the current transaction covers the amount, we save it and break
+        if total >= target_amount {
+            tx_filled = Some(tx.to_owned());
+            break;
+        }
+    }
+
+    match tx_filled {
+        Some(tx) => {
+            // in mem pool
+            if !tx.status.confirmed {
+                debug!("payment for {address} is in mem pool {}", tx.txid);
+                Ok(PaymentState::InMempool(InMempoolData { tx_id: tx.txid }))
+            } else {
+                match (
+                    tx.status.block_height,
+                    tx.status.block_time,
+                    tx.status.block_hash,
+                ) {
+                    (Some(block_height), Some(block_time), Some(block_hash)) => {
+                        let confirmations = chain_block_height - block_height + 1;
+                        let paid_data = PaidData {
+                            block_time,
+                            block_hash,
+                            confirmations,
+                            tx_id: tx.txid,
+                        };
+                        if confirmations
+                            >= get_config().payment_config.num_confirmations_for_payment as u64
+                        {
+                            // paid and confirmed
+                            debug!(
+                                "payment for {address} is paid and confirmed with {confirmations} confirmations"
+                            );
+                            Ok(PaymentState::PaidConfirmed(paid_data))
+                        } else {
+                            // paid but not enough confirmations yet
+                            debug!(
+                                "payment for {address} is paid and unconfirmed with {confirmations} confirmations"
+                            );
+                            Ok(PaymentState::PaidUnconfirmed(paid_data))
+                        }
+                    }
+                    _ => {
+                        log::error!(
+                            "Invalid data when checking payment for {address} - confirmed tx, but no metadata"
+                        );
+                        Err(Error::InvalidData(format!("Invalid data when checking payment for {address} - confirmed tx, but no metadata")).into())
+                    }
+                }
+            }
+        }
+        None => {
+            // not enough funds to cover amount
+            debug!(
+                "Not enough funds to cover {target_amount} yet when checking payment for {address}: {total}"
+            );
+            Ok(PaymentState::NotFound)
+        }
+    }
+}
+
 /// Fields documented at https://github.com/Blockstream/esplora/blob/master/API.md#addresses
-#[derive(Deserialize, Debug)]
+#[derive(Deserialize, Debug, Clone)]
 pub struct AddressInfo {
     pub chain_stats: Stats,
     pub mempool_stats: Stats,
 }
 
-#[derive(Deserialize, Debug)]
+#[derive(Deserialize, Debug, Clone)]
 pub struct Stats {
     pub funded_txo_sum: u64,
     pub spent_txo_sum: u64,
 }
 
-pub type Transactions = Vec<Txid>;
+pub type Transactions = Vec<Tx>;
 
 /// Available fields documented at https://github.com/Blockstream/esplora/blob/master/API.md#transactions
 #[derive(Deserialize, Debug, Clone)]
-#[allow(dead_code)]
-pub struct Txid {
+pub struct Tx {
+    pub txid: String,
     pub status: Status,
+    pub vout: Vec<Vout>,
+}
+
+#[derive(Deserialize, Debug, Clone)]
+pub struct Vout {
+    pub value: u64,
+    pub scriptpubkey_address: String,
 }
 
-#[allow(dead_code)]
 #[derive(Deserialize, Debug, Clone)]
 pub struct Status {
-    pub block_height: u64,
+    // Height of the block the tx is in
+    pub block_height: Option<u64>,
+    // Unix Timestamp
+    pub block_time: Option<u64>,
+    // Hash of the block the tx is in
+    pub block_hash: Option<String>,
+    // Whether it's in the mempool (false), or in a block (true)
+    pub confirmed: bool,
+}
+
+#[cfg(test)]
+pub mod tests {
+    use crate::tests::tests::init_test_cfg;
+
+    use super::*;
+
+    #[test]
+    fn test_payment_state_from_transactions() {
+        init_test_cfg();
+        let test_height = 4578915;
+        let test_addr = "n4n9CNeCkgtEs8wukKEvWC78eEqK4A3E6d";
+        let test_amount = 500;
+        let mut test_tx = Tx {
+            txid: "".into(),
+            status: Status {
+                block_height: Some(test_height - 7),
+                block_time: Some(1731593927),
+                block_hash: Some(
+                    "000000000061ad7b0d52af77e5a9dbcdc421bf00e93992259f16b2cf2693c4b1".into(),
+                ),
+                confirmed: true,
+            },
+            vout: vec![Vout {
+                value: 500,
+                scriptpubkey_address: test_addr.to_owned(),
+            }],
+        };
+
+        let res_empty =
+            payment_state_from_transactions(test_height, vec![], test_addr, test_amount);
+        assert!(matches!(res_empty, Ok(PaymentState::NotFound)));
+
+        let res_paid_confirmed = payment_state_from_transactions(
+            test_height,
+            vec![test_tx.clone()],
+            test_addr,
+            test_amount,
+        );
+        assert!(matches!(
+            res_paid_confirmed,
+            Ok(PaymentState::PaidConfirmed(..))
+        ));
+
+        test_tx.status.block_height = Some(test_height - 1); // only 2 confirmations
+        let res_paid_unconfirmed = payment_state_from_transactions(
+            test_height,
+            vec![test_tx.clone()],
+            test_addr,
+            test_amount,
+        );
+        assert!(matches!(
+            res_paid_unconfirmed,
+            Ok(PaymentState::PaidUnconfirmed(..))
+        ));
+
+        test_tx.status.block_height = None;
+        test_tx.status.block_time = None;
+        test_tx.status.block_hash = None;
+        let res_paid_confirmed_no_data = payment_state_from_transactions(
+            test_height,
+            vec![test_tx.clone()],
+            test_addr,
+            test_amount,
+        );
+        assert!(matches!(
+            res_paid_confirmed_no_data,
+            Err(super::super::Error::ExternalBitcoinApi(Error::InvalidData(
+                ..
+            )))
+        ));
+
+        test_tx.status.confirmed = false;
+        let res_in_mem_pool = payment_state_from_transactions(
+            test_height,
+            vec![test_tx.clone()],
+            test_addr,
+            test_amount,
+        );
+        assert!(matches!(res_in_mem_pool, Ok(PaymentState::InMempool(..))));
+
+        test_tx.vout[0].value = 200;
+        let res_not_filled = payment_state_from_transactions(
+            test_height,
+            vec![test_tx.clone()],
+            test_addr,
+            test_amount,
+        );
+        assert!(matches!(res_not_filled, Ok(PaymentState::NotFound)));
+    }
 }

crates/bcr-ebill-api/src/lib.rs

@@ -29,6 +29,7 @@ pub struct Config {
     pub data_dir: String,
     pub nostr_config: NostrConfig,
     pub mint_config: MintConfig,
+    pub payment_config: PaymentConfig,
 }
 
 static CONFIG: OnceLock<Config> = OnceLock::new();
@@ -45,6 +46,13 @@ impl Config {
     }
 }
 
+/// Payment specific configuration
+#[derive(Debug, Clone, Default)]
+pub struct PaymentConfig {
+    /// Amount of confirmations until we consider an on-chain payment as paid
+    pub num_confirmations_for_payment: usize,
+}
+
 /// Nostr specific configuration
 #[derive(Debug, Clone, Default)]
 pub struct NostrConfig {