Merge branch 'experiments/bitcoin-native'

.idea/.gitignore

@@ -0,0 +1,5 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/side.iml" filepath="$PROJECT_DIR$/.idea/side.iml" />
+    </modules>
+  </component>
+</project>

.idea/side.iml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="EMPTY_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/crates/bft-json-crdt/benches" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/crates/bft-json-crdt/bft-crdt-derive/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/crates/bft-json-crdt/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/crates/bft-json-crdt/tests" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/side-node/src" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/side-node/tests" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/side-watcher/src" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/target" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

README.md

@@ -50,11 +50,29 @@ Next dev tasks:
 
 ### Side Watcher
 
-The Side Watcher is a simple relayer node that sits between the Side Chain (Cosmos) and the decentralized Side Nodes. At the moment, it simply relays transactions between nodes via a websocket.
+The Side Watcher is a simple relayer node that sits between the Side Chain (Cosmos) and the decentralized Side Nodes. At the moment, it simply relays transactions between nodes via a websocket. We aim to eliminate this component from the architecture, but for the moment it simplifies networking and consensus agreement while we experiment with higher-value concepts.
 
-Next, the Side Watcher needs to:
+To fulfill the promises in the Lite Paper, the Side Watcher needs to:
 
-[ ] make a block for the P2P when the Side Chain creates a block (see litepaper)
+[ ] make a block for the P2P when the Side Chain creates a block
 [ ] submit P2P chain data to the Side Chain
 
 Later, we will aim to remove the Side Watcher from the architecture, by (a) moving to pure P2P transactions between Side Nodes, and (b) doing leader election of a Side Node to reach agreement on the submitted block.
+
+## Bitcoin integration
+
+There is a Bitcoin client integrated into the node, which can do simple coin transfers using esplora and the Mutinynet server's Signet (30 second blocktime).
+
+The client's demo driver can be run by doing:
+
+```
+cargo run -- init dave
+cargo run -- init sammy
+cargo run -- btc
+```
+
+You'll need to have funded the "dave" address prior to running the `btc` command - otherwise the transfer will fail gracefully.
+
+I was using this primarily as a way to experiment with constructing and broadcasting Bitcoin transactions, with the hope that it would be possible to move on to more advanced constructions (e.g. state channels). However, now that I look at all the options, it seems that multi-party state channels in Bitcoin are (probably) impossible to construct.
+
+There is a second, unused Bitcoin client in place which uses Blockstream's Electrum server, but this didn't seem to be working properly with respect to Signet Bitcoin network during my testing, so I went with the esplora / Mutiny version instead.

crates/bft-json-crdt/bft-crdt-derive/src/lib.rs

@@ -11,7 +11,7 @@ use syn::{
 
 /// Helper to get tokenstream representing the parent crate
 fn get_crate_name() -> TokenStream {
-    let cr8 = crate_name("bft-json-crdt").unwrap_or(FoundCrate::Itself);
+    let cr8 = crate_name("bft-json-bft-crdt").unwrap_or(FoundCrate::Itself);
     match cr8 {
         FoundCrate::Itself => quote! { ::bft_json_crdt },
         FoundCrate::Name(name) => {
@@ -109,13 +109,19 @@ pub fn derive_json_crdt(input: OgTokenStream) -> OgTokenStream {
                         }
                     }
 
-                    impl #impl_generics std::fmt::Debug for #ident #ty_generics #where_clause {
+                    // I'm pulling this out so that we can see actual CRD content in debug output.
-                        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                    //
-                            let mut fields = Vec::new();
+                    // The plan is to mostly get rid of the macros anyway, so it's a reasonable first step.
-                            #(fields.push(format!("{}", #ident_strings.to_string()));)*
+                    // It could (alternately) be just as good to keep the macros and change this function to
-                            write!(f, "{{ {:?} }}", fields.join(", "))
+                    // output actual field content instead of just field names.
-                        }
+                    //
-                    }
+                    // impl #impl_generics std::fmt::Debug for #ident #ty_generics #where_clause {
+                    //     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                    //         let mut fields = Vec::new();
+                    //         #(fields.push(format!("{}", #ident_strings.to_string()));)*
+                    //         write!(f, "{{ {:?} }}", fields.join(", "))
+                    //     }
+                    // }
 
                     impl #impl_generics #crate_name::json_crdt::CrdtNode for #ident #ty_generics #where_clause {
                         fn apply(&mut self, op: #crate_name::op::Op<#crate_name::json_crdt::JsonValue>) -> #crate_name::json_crdt::OpState {

crates/bft-json-crdt/src/json_crdt.rs

@@ -18,7 +18,7 @@ use fastcrypto::{
     // Verifier,
 };
 // TODO: serde's json object serialization and deserialization (correctly) do not define anything
-// object field order in JSON objects. However, the hash check impl in bft-json-crdt does take order
+// object field order in JSON objects. However, the hash check impl in bft-json-bft-crdt does take order
 // into account. This is going to cause problems later for non-Rust implementations, BFT hash checking
 // currently depends on JSON serialization/deserialization object order. This shouldn't be the case
 // but I've hacked in an IndexMap for the moment to get the PoC working. To see the problem, replace this with
@@ -549,7 +549,7 @@ mod test {
     #[test]
     fn test_derive_basic() {
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Player {
             x: LwwRegisterCrdt<f64>,
             y: LwwRegisterCrdt<f64>,
@@ -564,14 +564,14 @@ mod test {
     #[test]
     fn test_derive_nested() {
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Position {
             x: LwwRegisterCrdt<f64>,
             y: LwwRegisterCrdt<f64>,
         }
 
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Player {
             pos: Position,
             balance: LwwRegisterCrdt<f64>,
@@ -589,7 +589,7 @@ mod test {
     #[test]
     fn test_lww_ops() {
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Test {
             a: LwwRegisterCrdt<f64>,
             b: LwwRegisterCrdt<bool>,
@@ -649,7 +649,7 @@ mod test {
     #[test]
     fn test_vec_and_map_ops() {
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Test {
             a: ListCrdt<String>,
         }
@@ -689,14 +689,14 @@ mod test {
     #[test]
     fn test_causal_field_dependency() {
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Item {
             name: LwwRegisterCrdt<String>,
             soulbound: LwwRegisterCrdt<bool>,
         }
 
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Player {
             inventory: ListCrdt<Item>,
             balance: LwwRegisterCrdt<f64>,
@@ -755,7 +755,7 @@ mod test {
     #[test]
     fn test_2d_grid() {
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Game {
             grid: ListCrdt<ListCrdt<LwwRegisterCrdt<bool>>>,
         }
@@ -816,7 +816,7 @@ mod test {
     #[test]
     fn test_arb_json() {
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Test {
             reg: LwwRegisterCrdt<JsonValue>,
         }
@@ -852,13 +852,13 @@ mod test {
     #[test]
     fn test_wrong_json_types() {
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Nested {
             list: ListCrdt<f64>,
         }
 
         #[add_crdt_fields]
-        #[derive(Clone, CrdtNode)]
+        #[derive(Clone, CrdtNode, Debug)]
         struct Test {
             reg: LwwRegisterCrdt<bool>,
             strct: ListCrdt<Nested>,

crates/bft-json-crdt/tests/byzantine.rs

@@ -20,7 +20,7 @@ use serde_json::json;
 // 5. block actual messages from honest actors (eclipse attack)
 
 #[add_crdt_fields]
-#[derive(Clone, CrdtNode)]
+#[derive(Clone, CrdtNode, Debug)]
 struct ListExample {
     list: ListCrdt<char>,
 }
@@ -91,13 +91,13 @@ fn test_forge_update() {
 }
 
 #[add_crdt_fields]
-#[derive(Clone, CrdtNode)]
+#[derive(Clone, CrdtNode, Debug)]
 struct Nested {
     a: Nested2,
 }
 
 #[add_crdt_fields]
-#[derive(Clone, CrdtNode)]
+#[derive(Clone, CrdtNode, Debug)]
 struct Nested2 {
     b: LwwRegisterCrdt<bool>,
 }

crates/bft-json-crdt/tests/editing-trace.js

@@ -259796,7 +259796,7 @@ function insertAt(idx, elt) {
       const pos = new_log.findIndex(log => log[0] === parent_id)
       new_log.push([ID_COUNTER, pos, 0, elt])
       crdt.splice(raw_i + 1, 0, { deleted: false, content: elt, id: ID_COUNTER })
-      // console.log(`insert at ${idx} translated as op [${ID_COUNTER}, ${pos}, ${0}, ${escape(elt)}] found at ${raw_i + 1}::`, crdt[raw_i + 1])
+      // console.log(`insert at ${idx} translated as op [${ID_COUNTER}, ${pos}, ${0}, ${escape(elt)}] found at ${raw_i + 1}::`, bft-crdt[raw_i + 1])
       return
     }
 
@@ -259816,7 +259816,7 @@ function deleteAt(idx) {
       const pos = new_log.findIndex(log => log[0] === our_id)
       new_log.push([ID_COUNTER, pos, 1]);
       crdt[raw_i].deleted = true
-      // console.log(`delete at ${idx} translated as op [${ID_COUNTER}, ${pos}, ${1}] found at ${raw_i} with our_id ${our_id}::`, crdt[raw_i])
+      // console.log(`delete at ${idx} translated as op [${ID_COUNTER}, ${pos}, ${1}] found at ${raw_i} with our_id ${our_id}::`, bft-crdt[raw_i])
       return
     }
 
@@ -259853,7 +259853,7 @@ function rawJSString(edits) {
 //     deleteAt(edit[0])
 //   }
 // }
-// console.log(crdt)
+// console.log(bft-crdt)
 // rawJSString(mock_edits)
 // console.log(new_log)
 // const subset = edits.slice(0, 50000) 

side-node/Cargo.lock

@@ -1,7 +0,0 @@
-# This file is automatically @generated by Cargo.
-# It is not intended for manual editing.
-version = 3
-
-[[package]]
-name = "side-node"
-version = "0.1.0"

side-node/Cargo.toml

@@ -6,22 +6,31 @@ edition = "2021"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
+anyhow = "1.0.86"
 async-trait = "0.1.52"
+bdk = { version = "0.29.0", default-feature = false, features = ["all-keys"] }
+bdk_esplora = "0.15.0"
+bdk_sqlite = "0.2.0"
+bdk_wallet = { version = "1.0.0-alpha.13", features = ["all-keys"] }
 bft-json-crdt = { path = "../crates/bft-json-crdt" }
 bft-crdt-derive = { path = "../crates/bft-json-crdt/bft-crdt-derive" }
+bitcoin = { version = "0.32.2", features = ["rand"] }
 clap = { version = "4.5.4", features = ["derive"] }
 dirs = "5.0.1"
+electrum-client = "0.20"
 ezsockets = { version = "*", features = ["client"] }
 fastcrypto = "0.1.8"
+indexmap = { version = "2.2.6", features = ["serde"] }
+reqwest = { version = "*", features = ["blocking"] }
 # serde_cbor = "0.11.2" # move to this once we need to pack things in CBOR
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0.117"
 sha256 = "1.5.0"
 tokio = { version = "1.37.0", features = ["full"] }
+toml = "0.8.14"
 tracing = "0.1.32"
 # tracing-subscriber = "0.3.9"
-toml = "0.8.14"
+
-indexmap = { version = "2.2.6", features = ["serde"] }
 
 [dev-dependencies]
 uuid = { version = "1.8.0", features = ["v4"] }

side-node/src/bft_crdt/keys.rs

@@ -8,7 +8,7 @@ use bft_json_crdt::keypair::{make_keypair, Ed25519KeyPair};
 use fastcrypto::traits::EncodeDecodeBase64;
 
 /// Writes a new Ed25519 keypair to the file at key_path.
-pub(crate) fn write(key_path: PathBuf) -> Result<(), std::io::Error> {
+pub(crate) fn write(key_path: &PathBuf) -> Result<(), std::io::Error> {
     let keys = make_keypair();
 
     let mut file = File::create(key_path)?;
@@ -17,10 +17,10 @@ pub(crate) fn write(key_path: PathBuf) -> Result<(), std::io::Error> {
     Ok(())
 }
 
-pub(crate) fn load_from_file(side_dir: PathBuf) -> Ed25519KeyPair {
+pub(crate) fn load_from_file(side_dir: &PathBuf) -> Ed25519KeyPair {
     let key_path = crate::utils::side_paths(side_dir.clone()).0;
 
-    let data = fs::read_to_string(key_path).expect("couldn't read key file");
+    let data = fs::read_to_string(key_path).expect("couldn't read bft-bft-crdt key file");
     println!("data: {:?}", data);
 
     Ed25519KeyPair::decode_base64(&data).expect("couldn't load keypair from file")

side-node/src/bft_crdt/mod.rs

@@ -5,8 +5,11 @@ use bft_json_crdt::{
 };
 use serde::{Deserialize, Serialize};
 
+pub mod keys;
+pub mod websocket;
+
 #[add_crdt_fields]
-#[derive(Clone, CrdtNode, Serialize, Deserialize)]
+#[derive(Clone, CrdtNode, Serialize, Deserialize, Debug)]
 pub struct TransactionList {
     pub list: ListCrdt<Transaction>,
 }
@@ -19,7 +22,7 @@ impl TransactionList {
 
 /// A fake Transaction struct we can use as a simulated payload
 #[add_crdt_fields]
-#[derive(Clone, CrdtNode, Serialize, Deserialize, PartialEq)]
+#[derive(Clone, CrdtNode, Serialize, Deserialize, PartialEq, Debug)]
 pub struct Transaction {
     from: String,
     to: String,

side-node/src/bft_crdt/websocket.rs

@@ -5,19 +5,17 @@ use tokio::sync::mpsc;
 
 use crate::utils;
 
-pub struct WebSocketClient {
+pub struct Client {
     incoming_sender: mpsc::Sender<SignedOp>,
-    handle: ezsockets::Client<WebSocketClient>,
+    handle: ezsockets::Client<Client>,
 }
 
-impl WebSocketClient {
+impl Client {
     /// Start the websocket client
-    pub async fn new(
+    pub async fn new(incoming_sender: mpsc::Sender<SignedOp>) -> ezsockets::Client<Client> {
-        incoming_sender: mpsc::Sender<SignedOp>,
-    ) -> ezsockets::Client<WebSocketClient> {
         let config = ClientConfig::new("ws://localhost:8080/websocket");
         let (handle, future) = ezsockets::connect(
-            |client| WebSocketClient {
+            |client| Client {
                 incoming_sender,
                 handle: client,
             },
@@ -32,14 +30,14 @@ impl WebSocketClient {
 }
 
 #[async_trait]
-impl ezsockets::ClientExt for WebSocketClient {
+impl ezsockets::ClientExt for Client {
     // Right now we're only using the Call type for sending signed ops
     // change this to an enum if we need to send other types of calls, and
     // match on it.
     type Call = String;
 
-    /// When we receive a text message, apply the crdt operation contained in it to our
+    /// When we receive a text message, apply the bft-crdt operation contained in it to our
-    /// local crdt.
+    /// local bft-crdt.
     async fn on_text(&mut self, text: String) -> Result<(), ezsockets::Error> {
         let string_sha = utils::shassy(text.clone());
         println!("received text, sha: {string_sha}");
@@ -47,9 +45,7 @@ impl ezsockets::ClientExt for WebSocketClient {
         let object_sha = utils::shappy(incoming.clone());
         println!("deserialized: {}", object_sha);
         if string_sha != object_sha {
-            println!("SHA mismatch: {string_sha} != {object_sha}");
+            panic!("sha mismatch: {string_sha} != {object_sha}, bft-bft-crdt has failed");
-            println!("text: {text}");
-            println!("incoming: {incoming:?}");
         }
         self.incoming_sender.send(incoming).await?;
         Ok(())

side-node/src/bitcoin/clients/electrum.rs

@@ -0,0 +1,101 @@
+use crate::{bitcoin, utils};
+use bdk::bitcoin::psbt::PartiallySignedTransaction;
+use bdk::bitcoin::Network;
+use bdk::database::MemoryDatabase;
+use bdk::keys::ExtendedKey;
+use bdk::template::Bip84;
+use bdk::wallet::AddressIndex::{self, New};
+use bdk::wallet::AddressInfo;
+use bdk::{blockchain::ElectrumBlockchain, electrum_client, SyncOptions};
+use bdk::{FeeRate, KeychainKind, SignOptions, TransactionDetails, Wallet};
+
+/// DEPRECATED
+///
+/// This is a bdk example that uses the Electrum client to interact with the Bitcoin network.
+/// Electrum is a light client that connects to a server to get information about the Bitcoin network.
+/// The BDK itself does not have the ability to connect to e.g. esplora servers. As the Blockstream Electrum Signet
+/// server does not appear to be picking up transactions properly at the moment, I've shifted over to using
+/// the (more complex) `bdk_wallet` crate and the esplora client there (see the other bitcoin client).
+///
+/// Note:the types below are all completely different than the types in `bdk_wallet`.
+pub async fn run() -> Result<(), anyhow::Error> {
+    let dave = utils::home(&"dave".to_string());
+    let sammy = utils::home(&"sammy".to_string());
+    let dave_key = bitcoin::keys::load_from_file(&dave).unwrap();
+    let sammy_key = bitcoin::keys::load_from_file(&sammy).unwrap();
+
+    let dave_wallet = create_wallet(dave_key)?;
+    let sammy_wallet = create_wallet(sammy_key)?;
+
+    let dave_address = dave_wallet.get_address(AddressIndex::Peek(0))?.to_string();
+    let sammy_address = sammy_wallet.get_address(AddressIndex::Peek(0))?.to_string();
+
+    println!("Dave's address: {}", dave_address);
+    println!("Sammy's address: {}", sammy_address);
+
+    let blockchain = ElectrumBlockchain::from(electrum_client::Client::new(
+        "ssl://electrum.blockstream.info:60002",
+    )?);
+
+    println!("Syncing...");
+    dave_wallet.sync(&blockchain, SyncOptions::default())?;
+
+    display_balance(&dave_wallet);
+    display_balance(&sammy_wallet);
+
+    let (mut psbt, details) =
+        build_sending_tx(&dave_wallet, sammy_wallet.get_address(New)?).expect("psbt build error");
+
+    println!("About to sign the transaction: {:?}", details);
+
+    dave_wallet.sign(&mut psbt, SignOptions::default())?;
+    let _signed_tx = psbt.extract_tx();
+
+    // println!("Broadcasting...");
+    // blockchain.broadcast(&signed_tx).expect("broadcast error");
+    // println!("Transaction ID: {:?}", signed_tx.txid());
+    Ok(())
+}
+
+/// Create a BDK wallet using BIP 84 descriptor ("m/84h/1h/0h/0" and "m/84h/1h/0h/1")
+pub fn create_wallet(xkey: ExtendedKey) -> anyhow::Result<Wallet<MemoryDatabase>> {
+    let xprv = xkey
+        .into_xprv(Network::Testnet)
+        .expect("couldn't turn xkey into xprv");
+
+    let external_descriptor = Bip84(xprv, KeychainKind::External);
+    let internal_descriptor = Some(Bip84(xprv, KeychainKind::Internal));
+
+    let wallet = Wallet::new(
+        external_descriptor,
+        internal_descriptor,
+        Network::Testnet,
+        MemoryDatabase::default(),
+    )?;
+
+    Ok(wallet)
+}
+
+fn display_balance(wallet: &Wallet<MemoryDatabase>) {
+    println!(
+        "Wallet balance for {} after syncing: {:?} sats on network {}",
+        wallet
+            .get_address(bdk::wallet::AddressIndex::Peek(0))
+            .expect("couldn't get address"),
+        wallet.get_balance().expect("couldn't show balance"),
+        wallet.network(),
+    );
+}
+
+fn build_sending_tx(
+    wallet: &Wallet<MemoryDatabase>,
+    recipient: AddressInfo,
+) -> anyhow::Result<(PartiallySignedTransaction, TransactionDetails), anyhow::Error> {
+    let mut builder = wallet.build_tx();
+    builder
+        .add_recipient(recipient.script_pubkey(), 1000)
+        .enable_rbf()
+        .do_not_spend_change()
+        .fee_rate(FeeRate::from_sat_per_vb(7.0));
+    Ok(builder.finish()?)
+}

side-node/src/bitcoin/clients/esplora.rs

@@ -0,0 +1,188 @@
+use std::{collections::BTreeSet, fs, io::Write};
+
+use bdk::keys::bip39::Mnemonic;
+use bdk_esplora::{
+    esplora_client::{self, AsyncClient},
+    EsploraAsyncExt,
+};
+use bdk_wallet::{
+    bitcoin::{Address, Amount, Network, Script},
+    chain::ConfirmationTimeHeightAnchor,
+    keys::{DerivableKey, ExtendedKey},
+    wallet::AddressInfo,
+    KeychainKind, SignOptions, Wallet,
+};
+
+use bdk_sqlite::{rusqlite::Connection, Store};
+
+use crate::utils;
+
+const STOP_GAP: usize = 50;
+const PARALLEL_REQUESTS: usize = 5;
+
+/// A wallet that uses the Esplora client to interact with the Bitcoin network.
+pub struct EsploraWallet {
+    client: AsyncClient,
+    db: Store<KeychainKind, ConfirmationTimeHeightAnchor>,
+    name: String,
+    wallet: Wallet,
+}
+
+impl EsploraWallet {
+    /// Builds and signs a send transaction to send coins between addresses.
+    ///
+    /// Does NOT send it, you must call `broadcast` to do that.
+    ///
+    /// We could split the creation and signing easily if needed.
+    pub(crate) fn build_and_sign_send_tx(
+        &mut self,
+        recipient: Address,
+        amount: Amount,
+    ) -> Result<bitcoin::Transaction, anyhow::Error> {
+        let mut tx_builder = self.wallet.build_tx();
+        tx_builder
+            .add_recipient(recipient.script_pubkey(), amount)
+            .enable_rbf();
+        let mut psbt = tx_builder.finish()?;
+        let finalized = self.wallet.sign(&mut psbt, SignOptions::default())?;
+        assert!(finalized);
+        let tx = psbt.extract_tx()?;
+        Ok(tx)
+    }
+
+    /// Syncs the wallet with the latest state of the Bitcoin blockchain
+    pub(crate) async fn sync(&mut self) -> Result<(), anyhow::Error> {
+        print!("Syncing...");
+
+        fn generate_inspect(
+            kind: KeychainKind,
+        ) -> impl FnMut(u32, &Script) + Send + Sync + 'static {
+            let mut once = Some(());
+            let mut stdout = std::io::stdout();
+            move |spk_i, _| {
+                match once.take() {
+                    Some(_) => print!("\nScanning keychain [{:?}]", kind),
+                    None => print!(" {:<3}", spk_i),
+                };
+                stdout.flush().expect("must flush");
+            }
+        }
+        let request = self
+            .wallet
+            .start_full_scan()
+            .inspect_spks_for_all_keychains({
+                let mut once = BTreeSet::<KeychainKind>::new();
+                move |keychain, spk_i, _| {
+                    match once.insert(keychain) {
+                        true => print!("\nScanning keychain [{:?}]", keychain),
+                        false => print!(" {:<3}", spk_i),
+                    }
+                    std::io::stdout().flush().expect("must flush")
+                }
+            })
+            .inspect_spks_for_keychain(
+                KeychainKind::External,
+                generate_inspect(KeychainKind::External),
+            )
+            .inspect_spks_for_keychain(
+                KeychainKind::Internal,
+                generate_inspect(KeychainKind::Internal),
+            );
+        let mut update = self
+            .client
+            .full_scan(request, STOP_GAP, PARALLEL_REQUESTS)
+            .await?;
+        let now = std::time::UNIX_EPOCH.elapsed().unwrap().as_secs();
+        let _ = update.graph_update.update_last_seen_unconfirmed(now);
+        self.wallet.apply_update(update)?;
+        self.persist_local()?;
+        println!("Sync complete for {}", self.name);
+        Ok(())
+    }
+
+    fn persist_local(&mut self) -> Result<(), anyhow::Error> {
+        Ok(if let Some(changeset) = self.wallet.take_staged() {
+            self.db.write(&changeset)?;
+        })
+    }
+
+    /// Gets the next unused address from the wallet.
+    pub(crate) fn next_unused_address(&mut self) -> Result<AddressInfo, anyhow::Error> {
+        let address = self.wallet.next_unused_address(KeychainKind::External);
+        self.persist_local()?;
+        println!(
+            "Generated address: https://mutinynet.com/address/{}",
+            address
+        );
+        Ok(address)
+    }
+
+    /// Returns the balance of the wallet.
+    pub(crate) fn balance(&self) -> bdk_wallet::wallet::Balance {
+        self.wallet.balance()
+    }
+
+    /// Broadcasts a signed transaction to the network.
+    pub(crate) async fn broadcast(
+        &self,
+        tx: &bitcoin::Transaction,
+    ) -> Result<(), esplora_client::Error> {
+        println!(
+            "{} broadcasting tx https://mutinynet.com/tx/{}",
+            self.name,
+            tx.compute_txid()
+        );
+        self.client.broadcast(tx).await
+    }
+}
+
+/// Creates a Bitcoin descriptor wallet with the mnemonic in the given user directory.
+pub(crate) fn create_wallet(name: &str, network: Network) -> anyhow::Result<EsploraWallet> {
+    let keys_dir = utils::home(name);
+
+    let mnemonic_path = crate::utils::side_paths(keys_dir).1; // TODO: this tuple stinks
+    let mnemonic_words = fs::read_to_string(mnemonic_path).expect("couldn't read bitcoin key file");
+
+    println!("Creating wallet from mnemonic: {mnemonic_words}");
+    let mnemonic = Mnemonic::parse(mnemonic_words).unwrap();
+
+    // Generate the extended key
+    let xkey: ExtendedKey = mnemonic
+        .into_extended_key()
+        .expect("couldn't turn mnemonic into xkey");
+
+    let xprv = xkey
+        .into_xprv(Network::Signet)
+        .expect("problem converting xkey to xprv")
+        .to_string();
+
+    println!("Setting up esplora database for {name}");
+
+    let db_path = format!("/tmp/{name}-bdk-esplora-async-example.sqlite");
+    let conn = Connection::open(db_path)?;
+    let mut db = Store::new(conn)?;
+    let external_descriptor = format!("wpkh({xprv}/84'/1'/0'/0/*)");
+    let internal_descriptor = format!("wpkh({xprv}/84'/1'/0'/1/*)");
+    let changeset = db.read().expect("couldn't read esplora database");
+
+    let wallet = Wallet::new_or_load(
+        &external_descriptor,
+        &internal_descriptor,
+        changeset,
+        network,
+    )
+    .expect("problem setting up wallet");
+
+    let client = esplora_client::Builder::new("https://mutinynet.com/api")
+        .build_async()
+        .expect("couldn't build esplora client");
+
+    let esplora = EsploraWallet {
+        name: name.to_string(),
+        wallet,
+        db,
+        client,
+    };
+
+    Ok(esplora)
+}

side-node/src/bitcoin/clients/mod.rs

@@ -0,0 +1,2 @@
+pub mod electrum;
+pub mod esplora;

side-node/src/bitcoin/driver.rs

@@ -0,0 +1,62 @@
+use std::str::FromStr;
+
+use bdk_wallet::bitcoin::{Address, Amount, Network};
+
+use crate::bitcoin::clients;
+
+/// Demonstrates the use of bdk with the Esplora client.
+///
+/// This is more complex than the bare `bdk` crate, but the esplora client works.
+///
+/// Also, it very handily works with the mutinynet.com esplora server, which is configured
+/// with 30 second block times.
+pub(crate) async fn run() -> Result<(), anyhow::Error> {
+    simple_transfer().await
+}
+
+async fn simple_transfer() -> Result<(), anyhow::Error> {
+    let mut dave = clients::esplora::create_wallet("dave", Network::Signet)?;
+    let mut sammy = clients::esplora::create_wallet("sammy", Network::Signet)?;
+
+    let _next_address = dave.next_unused_address()?;
+
+    let dave_balance = dave.balance();
+    println!(
+        "Dave wallet balance before syncing: {} sats",
+        dave_balance.total()
+    );
+
+    dave.sync().await?;
+
+    let dave_balance = dave.balance();
+    println!("Wallet balance after syncing: {} sats", dave_balance);
+
+    let sammy_address = sammy.next_unused_address()?.address;
+    println!("Sammy's address: {}", sammy_address);
+
+    let sammy_balance = sammy.balance();
+    println!(
+        "Sammy wallet balance before syncing: {} sats",
+        sammy_balance
+    );
+
+    sammy.sync().await?;
+
+    let sammy_balance = sammy.balance();
+    println!("Sammy wallet balance after syncing: {} sats", sammy_balance);
+
+    let send_amount = Amount::from_sat(500);
+
+    if dave_balance.total() < send_amount {
+        println!(
+            "Please send at least {} sats to the receiving address",
+            send_amount
+        );
+        std::process::exit(0);
+    }
+
+    let tx = dave.build_and_sign_send_tx(sammy_address, send_amount)?;
+    dave.broadcast(&tx).await?;
+
+    Ok(())
+}

side-node/src/bitcoin/keys.rs

@@ -0,0 +1,50 @@
+use bdk::{
+    keys::{
+        bip39::{Language, Mnemonic, WordCount},
+        DerivableKey, ExtendedKey, GeneratableKey, GeneratedKey,
+    },
+    miniscript,
+};
+
+use std::{
+    fs::{self, File},
+    io::Write,
+    path::PathBuf,
+};
+
+pub fn make_mnemonic() -> String {
+    let mnemonic: GeneratedKey<_, miniscript::Segwitv0> =
+        Mnemonic::generate((WordCount::Words12, Language::English)).unwrap();
+    mnemonic.to_string()
+}
+
+/// Write the mnemonic to a file in the node's side directory
+///
+/// TODO: obviously spitting the mnemonic out to the console is not for production
+pub(crate) fn write(mnemonic_path: &PathBuf) -> Result<(), std::io::Error> {
+    let mnemonic = make_mnemonic();
+    let mut file = File::create(mnemonic_path)?;
+    println!("mnemonic: {mnemonic}");
+    file.write(mnemonic.as_bytes())?;
+
+    Ok(())
+}
+
+/// Creates Signet Bitcoin descriptors from a mnemonic
+pub fn get(mnemonic_words: String) -> anyhow::Result<ExtendedKey> {
+    let mnemonic = Mnemonic::parse(mnemonic_words).unwrap();
+
+    // Generate the extended key
+    let xkey: ExtendedKey = mnemonic
+        .into_extended_key()
+        .expect("couldn't turn mnemonic into xkey");
+
+    Ok(xkey)
+}
+
+pub(crate) fn load_from_file(side_dir: &PathBuf) -> anyhow::Result<ExtendedKey> {
+    let mnemonic_path = crate::utils::side_paths(side_dir.clone()).1; // TODO: this tuple stinks
+    let mnemonic_words = fs::read_to_string(mnemonic_path).expect("couldn't read bitcoin key file");
+    println!("Creating wallet from mnemonic: {mnemonic_words}");
+    get(mnemonic_words)
+}

side-node/src/bitcoin/mod.rs

@@ -0,0 +1,3 @@
+pub mod clients;
+pub mod driver;
+pub mod keys;

side-node/src/cli/mod.rs

@@ -17,6 +17,9 @@ pub(crate) struct Args {
 
 #[derive(Subcommand)]
 pub(crate) enum Commands {
+    /// Placeholder for future BTC commands
+    Btc {},
+
     /// runs the Side Node
     Run { name: String },
 

side-node/src/init/mod.rs

@@ -2,16 +2,19 @@ use std::path::PathBuf;
 
 use config::SideNodeConfig;
 
-use crate::{keys, utils};
+use crate::{bft_crdt, bitcoin, utils};
 
 pub(crate) mod config;
 
 pub(crate) fn init(home: PathBuf, config: SideNodeConfig) -> Result<(), std::io::Error> {
     ensure_side_directory_exists(&home)?;
-    let (key_path, config_path) = utils::side_paths(home.clone());
+    let (bft_crdt_key_path, bitcoin_key_path, config_path) = utils::side_paths(home.clone());
 
-    println!("Writing key to: {:?}", key_path);
+    println!("Writing bft bft-crdt key to: {:?}", bft_crdt_key_path);
-    keys::write(key_path)?;
+    bft_crdt::keys::write(&bft_crdt_key_path)?;
+
+    println!("Writing bitcoin key to: {:?}", bitcoin_key_path);
+    bitcoin::keys::write(&bitcoin_key_path)?;
 
     println!("Writing config to: {:?}", config_path);
     config::write_toml(&config, &config_path).expect("unable to write config file");
@@ -20,7 +23,7 @@ pub(crate) fn init(home: PathBuf, config: SideNodeConfig) -> Result<(), std::io:
 }
 
 /// Ensures that the directory at side_dir exists, so we have a place
-/// to store our key file and config file.
+/// to store our key files and config file.
 fn ensure_side_directory_exists(side_dir: &PathBuf) -> Result<(), std::io::Error> {
     if side_dir.exists() {
         return Ok(());
@@ -53,6 +56,24 @@ mod tests {
         (SideNodeConfig { name: name.clone() }, name)
     }
 
+    #[test]
+    fn creates_bitcoin_keys() {
+        let (config, name) = side_node_config();
+        let side_dir = format!("/tmp/side/{name}");
+
+        let mut bitcoin_keys_path = PathBuf::new();
+        bitcoin_keys_path.push(side_dir.clone());
+        bitcoin_keys_path.push(utils::BITCOIN_KEY_FILE);
+
+        let _ = init(PathBuf::from_str(&side_dir).unwrap(), config);
+        assert!(bitcoin_keys_path.exists());
+
+        // check that the pem is readable
+        // let data = fs::read_to_string(bitcoin_keys_path).expect("couldn't read key file");
+        // let keys = Ed25519KeyPair::decode_base64(&data).expect("couldn't load keypair from file");
+        // assert_eq!(keys.public().as_bytes().len(), 32);
+    }
+
     #[test]
     fn creates_side_node_directory() {
         let (config, name) = side_node_config();
@@ -67,13 +88,13 @@ mod tests {
     }
 
     #[test]
-    fn creates_key_file() {
+    fn creates_bft_crdt_key_file() {
         let (config, name) = side_node_config();
         let side_dir = format!("/tmp/side/{name}");
 
         let mut key_file_path = PathBuf::new();
         key_file_path.push(side_dir.clone());
-        key_file_path.push(utils::KEY_FILE);
+        key_file_path.push(utils::BFT_CRDT_KEY_FILE);
 
         let _ = init(PathBuf::from_str(&side_dir).unwrap(), config);
         assert!(key_file_path.exists());

side-node/src/lib.rs

@@ -1,18 +1,17 @@
+use bft_crdt::websocket;
+use bft_crdt::TransactionList;
 use bft_json_crdt::json_crdt::{BaseCrdt, SignedOp};
 use cli::{parse_args, Commands};
-use crdt::TransactionList;
 use node::SideNode;
 use tokio::{sync::mpsc, task};
-use websocket::WebSocketClient;
 
+pub mod bft_crdt;
+pub mod bitcoin;
 pub(crate) mod cli;
-pub mod crdt;
 pub(crate) mod init;
-pub mod keys;
 pub mod node;
 pub(crate) mod stdin;
 pub mod utils;
-pub mod websocket;
 
 #[tokio::main]
 pub async fn run() {
@@ -30,16 +29,21 @@ pub async fn run() {
             let mut node = setup(name).await;
             node.start().await;
         }
+        Some(Commands::Btc {}) => {
+            let _ = bitcoin::driver::run().await;
+        }
         None => println!("No command provided. Exiting. See --help for more information."),
     }
 }
 
-/// Wire everything up outside the application so we can test more easily later
+/// Wire everything up outside the application so that we can test more easily later
 async fn setup(name: &String) -> SideNode {
-    // First, load up the keys and create a bft-crdt
+    // First, load up the keys and create a bft-bft-crdt
     let side_dir = utils::home(name);
-    let keys = keys::load_from_file(side_dir);
+    let bft_crdt_keys = bft_crdt::keys::load_from_file(&side_dir);
-    let crdt = BaseCrdt::<TransactionList>::new(&keys);
+    let keys = bitcoin::keys::load_from_file(&side_dir).unwrap();
+    let bitcoin_wallet = bitcoin::clients::electrum::create_wallet(keys).unwrap();
+    let crdt = BaseCrdt::<TransactionList>::new(&bft_crdt_keys);
 
     // Channels for internal communication, and a tokio task for stdin input
     let (incoming_sender, incoming_receiver) = mpsc::channel::<SignedOp>(32);
@@ -49,8 +53,15 @@ async fn setup(name: &String) -> SideNode {
     });
 
     // Finally, create the node and return it
-    let handle = WebSocketClient::new(incoming_sender).await;
+    let handle = websocket::Client::new(incoming_sender).await;
-    let node = SideNode::new(crdt, keys, incoming_receiver, stdin_receiver, handle);
+    let node = SideNode::new(
+        crdt,
+        bft_crdt_keys,
+        bitcoin_wallet,
+        incoming_receiver,
+        stdin_receiver,
+        handle,
+    );
     println!("Node setup complete.");
     node
 }

side-node/src/node.rs

@@ -1,28 +1,32 @@
+use bdk::database::MemoryDatabase;
 use bft_json_crdt::json_crdt::{BaseCrdt, SignedOp};
 use fastcrypto::ed25519::Ed25519KeyPair;
 use tokio::sync::mpsc;
 
-use crate::{crdt::TransactionList, utils, websocket::WebSocketClient};
+use crate::{bft_crdt::websocket::Client, bft_crdt::TransactionList, utils};
 
 pub struct SideNode {
     crdt: BaseCrdt<TransactionList>,
-    keys: fastcrypto::ed25519::Ed25519KeyPair,
+    bft_crdt_keys: fastcrypto::ed25519::Ed25519KeyPair,
+    bitcoin_wallet: bdk::Wallet<MemoryDatabase>,
     incoming_receiver: mpsc::Receiver<SignedOp>,
     stdin_receiver: std::sync::mpsc::Receiver<String>,
-    handle: ezsockets::Client<WebSocketClient>,
+    handle: ezsockets::Client<Client>,
 }
 
 impl SideNode {
     pub fn new(
         crdt: BaseCrdt<TransactionList>,
-        keys: Ed25519KeyPair,
+        bft_crdt_keys: Ed25519KeyPair,
+        bitcoin_wallet: bdk::Wallet<MemoryDatabase>,
         incoming_receiver: mpsc::Receiver<SignedOp>,
         stdin_receiver: std::sync::mpsc::Receiver<String>,
-        handle: ezsockets::Client<WebSocketClient>,
+        handle: ezsockets::Client<Client>,
     ) -> Self {
         let node = Self {
             crdt,
-            keys,
+            bft_crdt_keys,
+            bitcoin_wallet,
             incoming_receiver,
             stdin_receiver,
             handle,
@@ -36,7 +40,7 @@ impl SideNode {
         loop {
             match self.stdin_receiver.try_recv() {
                 Ok(stdin) => {
-                    let transaction = utils::fake_transaction_json(stdin);
+                    let transaction = utils::fake_generic_transaction_json(stdin);
                     let json = serde_json::to_value(transaction).unwrap();
                     let signed_op = self.add_transaction_local(json);
                     println!("STDIN: {}", utils::shappy(signed_op.clone()));
@@ -80,7 +84,7 @@ impl SideNode {
             .doc
             .list
             .insert(last.id, transaction)
-            .sign(&self.keys);
+            .sign(&self.bft_crdt_keys);
         // self.trace_crdt();
         signed_op
     }

side-node/src/stdin.rs

@@ -5,7 +5,6 @@ pub(crate) fn input(stdin_sender: std::sync::mpsc::Sender<String>) {
     let stdin = std::io::stdin();
     let lines = stdin.lock().lines();
     for line in lines {
-        println!("We're in stdin_input");
         let line = line.unwrap();
         stdin_sender.send(line).unwrap();
     }

side-node/src/utils.rs

@@ -1,23 +1,27 @@
-use std::path::PathBuf;
-
 use bft_json_crdt::json_crdt::SignedOp;
 use serde_json::{json, Value};
+use std::path::PathBuf;
 
-pub(crate) const KEY_FILE: &str = "keys.pem";
+pub(crate) const BITCOIN_KEY_FILE: &str = "bitcoin_keys.pem";
+pub(crate) const BFT_CRDT_KEY_FILE: &str = "keys.pem";
 pub(crate) const CONFIG_FILE: &str = "config.toml";
 
 /// Returns the path to the key file and config for this host OS.
-pub(crate) fn side_paths(prefix: PathBuf) -> (PathBuf, PathBuf) {
+pub(crate) fn side_paths(prefix: PathBuf) -> (PathBuf, PathBuf, PathBuf) {
-    let mut key_path = prefix.clone();
+    let mut bft_crdt_key_path = prefix.clone();
-    key_path.push(KEY_FILE);
+    bft_crdt_key_path.push(BFT_CRDT_KEY_FILE);
+
+    let mut bitcoin_key_path = prefix.clone();
+    bitcoin_key_path.push(BITCOIN_KEY_FILE);
 
     let mut config_path = prefix.clone();
     config_path.push(CONFIG_FILE);
 
-    (key_path, config_path)
+    (bft_crdt_key_path, bitcoin_key_path, config_path)
 }
 
-pub(crate) fn home(name: &String) -> std::path::PathBuf {
+/// Returns the path to the home directory for this host OS and the given node name
+pub(crate) fn home(name: &str) -> std::path::PathBuf {
     let mut path = dirs::home_dir().unwrap();
     path.push(".side");
     path.push(name);
@@ -25,7 +29,7 @@ pub(crate) fn home(name: &String) -> std::path::PathBuf {
 }
 
 /// Generate a fake transaction with customizable from_pubkey String
-pub fn fake_transaction_json(from: String) -> Value {
+pub fn fake_generic_transaction_json(from: String) -> Value {
     json!({
         "from": from,
         "to": "Bob",

side-node/tests/crdt.rs

@@ -1,19 +1,19 @@
 use bft_json_crdt::json_crdt::BaseCrdt;
 use bft_json_crdt::keypair::make_keypair;
 use bft_json_crdt::op::ROOT_ID;
-use side_node::crdt::TransactionList;
+use side_node::bft_crdt::TransactionList;
 
 // case 1 - send valid updates
 #[test]
 fn test_valid_updates() {
-    // Insert to crdt.doc on local node, test applying the same operation to a remote node
+    // Insert to bft-crdt.doc on local node, test applying the same operation to a remote node
     // and check that the view is the same
     let keypair1 = make_keypair();
     let mut crdt1 = BaseCrdt::<TransactionList>::new(&keypair1);
 
-    let val_a = side_node::utils::fake_transaction_json(String::from("a"));
+    let val_a = side_node::utils::fake_generic_transaction_json(String::from("a"));
-    let val_b = side_node::utils::fake_transaction_json(String::from("b"));
+    let val_b = side_node::utils::fake_generic_transaction_json(String::from("b"));
-    let val_c = side_node::utils::fake_transaction_json(String::from("c"));
+    let val_c = side_node::utils::fake_generic_transaction_json(String::from("c"));
 
     let _a = crdt1
         .doc

side-node/tests/side_node.rs

@@ -2,7 +2,9 @@ use bft_json_crdt::{
     json_crdt::{BaseCrdt, SignedOp},
     keypair::make_keypair,
 };
-use side_node::{crdt::TransactionList, node::SideNode, utils, websocket::WebSocketClient};
+use side_node::{
+    bft_crdt::websocket::Client, bft_crdt::TransactionList, bitcoin, node::SideNode, utils,
+};
 use tokio::sync::mpsc;
 
 #[tokio::test]
@@ -12,19 +14,19 @@ async fn test_distribute_via_websockets() {
 
     assert_eq!(node1.current_sha(), node2.current_sha());
 
-    let transaction = utils::fake_transaction_json("from_alice".to_string());
+    let transaction = utils::fake_generic_transaction_json("from_alice".to_string());
     let signed_op = node1.add_transaction_local(transaction);
     node2.handle_incoming(signed_op);
 
     assert_eq!(node1.current_sha(), node2.current_sha());
 
-    let transaction = utils::fake_transaction_json("from_alice2".to_string());
+    let transaction = utils::fake_generic_transaction_json("from_alice2".to_string());
     let signed_op = node1.add_transaction_local(transaction);
     node2.handle_incoming(signed_op);
 
     assert_eq!(node1.current_sha(), node2.current_sha());
 
-    let transaction = utils::fake_transaction_json("from_alice3".to_string());
+    let transaction = utils::fake_generic_transaction_json("from_alice3".to_string());
     let signed_op = node1.add_transaction_local(transaction);
     node2.handle_incoming(signed_op);
 
@@ -33,16 +35,26 @@ async fn test_distribute_via_websockets() {
 
 /// Wire everything up, ignoring things we are not using in the test
 async fn setup(_: &str) -> SideNode {
-    // First, load up the keys and create a bft-crdt
+    // First, load up the keys and create a bft-bft-crdt
-    let keys = make_keypair();
+    let bft_crdt_keys = make_keypair();
-    let crdt = BaseCrdt::<TransactionList>::new(&keys);
+    let mnemonic_words = bitcoin::keys::make_mnemonic();
+    let keys = bitcoin::keys::get(mnemonic_words).unwrap();
+    let bitcoin_wallet = bitcoin::clients::electrum::create_wallet(keys).unwrap();
+    let crdt = BaseCrdt::<TransactionList>::new(&bft_crdt_keys);
 
     // Channels for internal communication, and a tokio task for stdin input
     let (incoming_sender, incoming_receiver) = mpsc::channel::<SignedOp>(32);
     let (_, stdin_receiver) = std::sync::mpsc::channel();
 
     // Finally, create the node and return it
-    let handle = WebSocketClient::new(incoming_sender).await;
+    let handle = Client::new(incoming_sender).await;
-    let node = SideNode::new(crdt, keys, incoming_receiver, stdin_receiver, handle);
+    let node = SideNode::new(
+        crdt,
+        bft_crdt_keys,
+        bitcoin_wallet,
+        incoming_receiver,
+        stdin_receiver,
+        handle,
+    );
     node
 }