Adds bitcoin-rpc-client example

Author: Conor Okus

Cargo.toml

@@ -7,6 +7,7 @@ members = [
     "lightning-net-tokio",
     "lightning-persister",
     "lightning-background-processor",
+    "examples/*"
 ]
 
 # Our tests do actual crypo and lots of work, the tradeoff for -O1 is well worth it.

examples/bitcoind-rpc-client/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "bitcoind-rpc-client"
+version = "0.1.0"
+authors = ["Conor Okus <conor@squarecrypto.org>"]
+license = "MIT OR Apache-2.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+lightning = { version = "0.0.104" }
+lightning-block-sync = { version = "0.0.104", features = ["rpc-client"]}
+lightning-net-tokio = { version = "0.0.104" }
+
+base64 = { version = "0.13.0" }
+bitcoin = { version = "0.27.1" }
+bitcoin-bech32 = { version = "0.12.1" }
+bech32 = { version = "0.8.1" }
+hex = { version = "0.4.3" }
+
+serde_json = { version = "1.0.73" }
+tokio = { version = "1.15.0", features = [ "io-util", "macros", "rt", "rt-multi-thread", "sync", "net", "time" ] }
+
+[profile.release]
+panic = "abort"
+
+[profile.dev]
+panic = "abort"
+
+

examples/bitcoind-rpc-client/README.md

@@ -0,0 +1,37 @@
+# Creates a basic bitcoind client
+
+This is example shows how you could create a client that directly communicates with bitcoind from LDK. The API is flexible and allows for different ways to implement the interface.
+
+It implements some basic RPC methods that allow you to create a core wallet and print it's balance to stdout.
+
+To run with this example you need to have a bitcoin core node running in regtest mode. Get the bitcoin core binary either from the [bitcoin core repo](https://bitcoincore.org/bin/bitcoin-core-0.22.0/) or [build from source](https://github.com/bitcoin/bitcoin/blob/v0.21.1/doc/build-unix.md).
+
+Then configure the node with the following `bitcoin.conf`
+
+```
+regtest=1
+fallbackfee=0.0001
+server=1
+txindex=1
+rpcuser=admin
+rpcpassword=password
+```
+
+## How to use 
+
+```
+Cargo run
+```
+
+## Notes
+
+`RpcClient` is a simple RPC client for calling methods using HTTP POST. It is implemented in [rust-lightning/lightning-block-sync/rpc.rs](https://github.com/lightningdevkit/rust-lightning/blob/61341df39e90de9d650851a624c0644f5c9dd055/lightning-block-sync/src/rpc.rs)
+
+The purpose of `RpcClient` is to create a new RPC client connected to the given endpoint with the provided credentials. The credentials should be a base64 encoding of a user name and password joined by a colon, as is required for HTTP basic access authentication.
+
+It implements [BlockSource](https://github.com/rust-bitcoin/rust-lightning/blob/61341df39e90de9d650851a624c0644f5c9dd055/lightning-block-sync/src/lib.rs#L55) against a Bitcoin Core RPC. It is an asynchronous interface for retrieving block headers and data.
+
+Check out our [LDK sample node](https://github.com/lightningdevkit/ldk-sample) for an integrated example.
+
+
+

examples/bitcoind-rpc-client/src/bitcoind_client.rs

@@ -0,0 +1,118 @@
+use std::{sync::{Arc}};
+
+use bitcoin::{BlockHash, Block};
+use lightning_block_sync::{rpc::RpcClient, http::{HttpEndpoint}, BlockSource, AsyncBlockSourceResult, BlockHeaderData};
+use tokio::sync::Mutex;
+
+use crate::convert::{CreateWalletResponse, BlockchainInfoResponse, NewAddressResponse, GetBalanceResponse, GenerateToAddressResponse};
+
+
+pub struct BitcoindClient {
+    bitcoind_rpc_client: Arc<Mutex<RpcClient>>,
+    host: String,
+    port: u16,
+    rpc_user: String,
+    rpc_password: String,
+}
+
+impl BlockSource for &BitcoindClient {
+	fn get_header<'a>(
+		&'a mut self, header_hash: &'a BlockHash, height_hint: Option<u32>,
+	) -> AsyncBlockSourceResult<'a, BlockHeaderData> {
+		Box::pin(async move {
+			let mut rpc = self.bitcoind_rpc_client.lock().await;
+			rpc.get_header(header_hash, height_hint).await
+		})
+	}
+
+	fn get_block<'a>(
+		&'a mut self, header_hash: &'a BlockHash,
+	) -> AsyncBlockSourceResult<'a, Block> {
+		Box::pin(async move {
+			let mut rpc = self.bitcoind_rpc_client.lock().await;
+			rpc.get_block(header_hash).await
+		})
+	}
+
+	fn get_best_block<'a>(&'a mut self) -> AsyncBlockSourceResult<(BlockHash, Option<u32>)> {
+		Box::pin(async move {
+			let mut rpc = self.bitcoind_rpc_client.lock().await;
+			rpc.get_best_block().await
+		})
+	}
+}
+
+impl BitcoindClient {
+    pub async fn new(host: String, port: u16, rpc_user: String, rpc_password: String) -> std::io::Result<Self> {
+        let http_endpoint = HttpEndpoint::for_host(host.clone()).with_port(port);
+        let rpc_creditials = 
+            base64::encode(format!("{}:{}", rpc_user.clone(), rpc_password.clone()));
+        let mut bitcoind_rpc_client = RpcClient::new(&rpc_creditials, http_endpoint)?;
+        let _dummy = bitcoind_rpc_client
+			.call_method::<BlockchainInfoResponse>("getblockchaininfo", &vec![])
+			.await
+			.map_err(|_| {
+				std::io::Error::new(std::io::ErrorKind::PermissionDenied,
+				"Failed to make initial call to bitcoind - please check your RPC user/password and access settings")
+			})?;
+
+        let client = Self {
+            bitcoind_rpc_client: Arc::new(Mutex::new(bitcoind_rpc_client)),
+            host,
+            port,
+            rpc_user,
+            rpc_password,
+        };
+       
+        Ok(client)
+    }
+
+    pub fn get_new_rpc_client(&self) -> std::io::Result<RpcClient> {
+		let http_endpoint = HttpEndpoint::for_host(self.host.clone()).with_port(self.port);
+		let rpc_credentials =
+			base64::encode(format!("{}:{}", self.rpc_user.clone(), self.rpc_password.clone()));
+		RpcClient::new(&rpc_credentials, http_endpoint)
+	}
+
+    pub async fn get_blockchain_info(&self) -> BlockchainInfoResponse {
+		let mut rpc = self.bitcoind_rpc_client.lock().await;
+		rpc.call_method::<BlockchainInfoResponse>("getblockchaininfo", &vec![]).await.unwrap()
+	}
+
+    pub async fn create_wallet(&self) -> CreateWalletResponse {
+        let mut rpc = self.bitcoind_rpc_client.lock().await;
+        let create_wallet_args = vec![serde_json::json!("test-wallet")];
+
+        rpc.call_method::<CreateWalletResponse>("createwallet", &create_wallet_args).await.unwrap()
+    }
+
+    pub async fn get_new_address(&self) -> String {
+		let mut rpc = self.bitcoind_rpc_client.lock().await;
+
+		let addr_args = vec![serde_json::json!("LDK output address")];
+		let addr = rpc.call_method::<NewAddressResponse>("getnewaddress", &addr_args).await.unwrap();
+		addr.0.to_string()
+	}
+
+    pub async fn get_balance(&self) -> GetBalanceResponse {
+        let mut rpc = self.bitcoind_rpc_client.lock().await;
+        
+        rpc.call_method::<GetBalanceResponse>("getbalance", &vec![]).await.unwrap()
+    }
+
+    pub async fn generate_to_address(&self, block_num: u64, address: &str) -> GenerateToAddressResponse {
+		let mut rpc = self.bitcoind_rpc_client.lock().await;
+
+		let generate_to_address_args = vec![serde_json::json!(block_num), serde_json::json!(address)];
+
+
+		rpc.call_method::<GenerateToAddressResponse>("generatetoaddress", &generate_to_address_args).await.unwrap()
+	}
+}
+
+
+
+
+
+
+

examples/bitcoind-rpc-client/src/convert.rs

@@ -0,0 +1,78 @@
+use bitcoin::{BlockHash, hashes::hex::FromHex};
+use lightning_block_sync::http::JsonResponse;
+
+pub struct BlockchainInfoResponse {
+    pub latest_height: usize,
+    pub latest_blockhash: BlockHash,
+    pub chain: String,
+}
+
+impl TryInto<BlockchainInfoResponse> for JsonResponse {
+    type Error = std::io::Error;
+    fn try_into(self) -> std::io::Result<BlockchainInfoResponse> {
+        Ok(BlockchainInfoResponse { 
+            latest_height: self.0["blocks"].as_u64().unwrap() as usize,
+			latest_blockhash: BlockHash::from_hex(self.0["bestblockhash"].as_str().unwrap())
+				.unwrap(),
+			chain: self.0["chain"].as_str().unwrap().to_string(),
+        })
+    }
+}
+
+pub struct CreateWalletResponse {
+    pub name: String,
+    pub warning: String,
+}
+
+impl TryInto<CreateWalletResponse> for JsonResponse {
+    type Error = std::io::Error;
+    fn try_into(self) -> std::io::Result<CreateWalletResponse> {
+        Ok(CreateWalletResponse {
+            name: self.0["name"].as_str().unwrap().to_string(),
+            warning: self.0["warning"].as_str().unwrap().to_string(),
+        })
+    }
+}
+pub struct GetBalanceResponse(pub usize);
+
+impl TryInto<GetBalanceResponse> for JsonResponse {
+    type Error = std::io::Error;
+    fn try_into(self) -> std::io::Result<GetBalanceResponse> {
+        Ok(GetBalanceResponse(self.0.as_f64().unwrap() as usize))
+    }
+}
+
+pub struct GenerateToAddressResponse(pub Vec<BlockHash>);
+
+impl TryInto<GenerateToAddressResponse> for JsonResponse {
+    type Error = std::io::Error;
+    fn try_into(self) -> std::io::Result<GenerateToAddressResponse> {
+        let mut x: Vec<BlockHash> = Vec::new();
+
+        for item in self.0.as_array().unwrap() {
+            x.push(BlockHash::from_hex(item.as_str().unwrap())
+            .unwrap());
+        }
+
+        Ok(GenerateToAddressResponse(x))
+    }
+}
+
+
+pub struct NewAddressResponse(pub String); 
+
+impl TryInto<NewAddressResponse> for JsonResponse {
+    type Error = std::io::Error;
+    fn try_into(self) -> std::io::Result<NewAddressResponse> {
+        Ok(NewAddressResponse(self.0.as_str().unwrap().to_string()))
+    }
+}
+
+
+
+
+
+
+
+
+

examples/bitcoind-rpc-client/src/main.rs

@@ -0,0 +1,53 @@
+pub mod bitcoind_client;
+
+use std::sync::Arc;
+
+use crate::bitcoind_client::BitcoindClient;
+
+mod convert;
+
+#[tokio::main]
+pub async fn main() {
+    start_ldk().await;
+}
+
+async fn start_ldk() {
+    // Initialize our bitcoind client
+    let bitcoind_client = match BitcoindClient::new(
+        String::from("127.0.0.1"),
+        18443,
+        String::from("admin"),
+        String::from("password")
+    )
+    .await 
+    {
+        Ok(client) => {
+            println!("Successfully connected to bitcoind client");
+            Arc::new(client)
+        },
+        Err(e) => {
+            println!("Failed to connect to bitcoind client: {}", e);
+			return;
+        }
+    };
+
+    // Check we connected to the expected network
+    let bitcoind_blockchain_info = bitcoind_client.get_blockchain_info().await;
+    println!("Chain network: {}", bitcoind_blockchain_info.chain);
+    println!("Latest block height: {}", bitcoind_blockchain_info.latest_height);
+
+    // Create a named bitcoin core wallet
+    let bitcoind_wallet = bitcoind_client.create_wallet().await;
+    println!("Successfully created wallet with name: {}", bitcoind_wallet.name);
+
+    // Generate a new address 
+    let bitcoind_new_address = bitcoind_client.get_new_address().await;
+    println!("Address: {}", bitcoind_new_address);
+
+    // Generate 101 blocks and use the above address as coinbase
+    bitcoind_client.generate_to_address(101, &bitcoind_new_address).await;
+
+    // Show balance
+    let balance = bitcoind_client.get_balance().await;
+    println!("Balance: {}", balance.0);
+}