update

Author: joemphilips

bindings/Cargo.toml

@@ -9,10 +9,15 @@ crate-type=["staticlib", "cdylib"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[features]
+debug_assertions = ["hex"]
+
 [dependencies]
 lightning = { path = "../lightning" }
 secp256k1 = "0.15"
 bitcoin = "0.21"
+bitcoin_hashes = "0.7"
+hex = { version = "0.3", optional = true }
 
 [build-dependencies]
 cbindgen = "0.13.1"

bindings/README.md

@@ -0,0 +1,22 @@
+# FFI binding interface for rust-lighting
+
+Currently, it only supports C#, other languages are untested.
+
+## General strategy
+
+
+## Type interoperability
+
+Some types can not pass FFI boundary directly, so it has to be converted to FFI-safe type.
+The famous example of this is that array has to be passed as a pair of two items.
+
+1. pointer to the first element of the array.
+2. length of the array.
+
+For other rust-lightning and rust-bitcoin types, the conversion could be done in several ways.
+Here are the conversion tables for those types.
+
+1. tuple ... analogous plain struct.
+1. `Transaction` ... ``
+
+

bindings/src/adaptors/mod.rs

@@ -1,8 +1,9 @@
 use std::sync::{Arc};
 
 use secp256k1::constants::{SECRET_KEY_SIZE, PUBLIC_KEY_SIZE};
-use bitcoin::blockdata::transaction::{Transaction};
 use bitcoin::util::key::PrivateKey;
+use bitcoin::blockdata::transaction::Transaction;
+use bitcoin::consensus::encode::serialize;
 
 use lightning::util::logger::{Logger, Record};
 
@@ -22,56 +23,6 @@ struct SecretKey([u8; SECRET_KEY_SIZE]);
 #[repr(transparent)]
 struct PublicKey([u8; PUBLIC_KEY_SIZE]);
 
-/*
-#[repr(C)]
-pub struct ChannelPublicKeys{
-	/// The public key which is used to sign all commitment transactions, as it appears in the
-	/// on-chain channel lock-in 2-of-2 multisig output.
-	pub funding_pubkey: PublicKey,
-	/// The base point which is used (with derive_public_revocation_key) to derive per-commitment
-	/// revocation keys. The per-commitment revocation private key is then revealed by the owner of
-	/// a commitment transaction so that their counterparty can claim all available funds if they
-	/// broadcast an old state.
-	pub revocation_basepoint: PublicKey,
-	/// The base point which is used (with derive_public_key) to derive a per-commitment payment
-	/// public key which receives immediately-spendable non-HTLC-encumbered funds.
-	pub payment_basepoint: PublicKey,
-	/// The base point which is used (with derive_public_key) to derive a per-commitment payment
-	/// public key which receives non-HTLC-encumbered funds which are only available for spending
-	/// after some delay (or can be claimed via the revocation path).
-	pub delayed_payment_basepoint: PublicKey,
-	/// The base point which is used (with derive_public_key) to derive a per-commitment public key
-	/// which is used to encumber HTLC-in-flight outputs.
-	pub htlc_basepoint: PublicKey,
-};
-
-*/
-
-#[repr(C)]
-struct FFIInMemoryChannelKeys {
-	/// Private key of anchor tx
-	funding_key: SecretKey,
-	/// Local secret key for blinded revocation pubkey
-	revocation_base_key: SecretKey,
-	/// Local secret key used in commitment tx htlc outputs
-	payment_base_key: SecretKey,
-	/// Local secret key used in HTLC tx
-	delayed_payment_base_key: SecretKey,
-	/// Local htlc secret key used in commitment tx htlc outputs
-	htlc_base_key: SecretKey,
-	/// Commitment seed
-	commitment_seed: [u8; 32],
-	/// Local public keys and basepoints
-	pub(crate) local_channel_pubkeys: ChannelPublicKeys,
-	/// Remote public keys and base points
-	pub(crate) remote_channel_pubkeys: Option<ChannelPublicKeys>,
-	/// The total value of this channel
-    channel_value_satoshis: u64,
-}
-
-// #[repr(c)]
-// struct FFIChannelMonitor {
-// }
 #[repr(C)]
 struct FFIOutPoint {
     txid: [u8; 32],
@@ -80,9 +31,9 @@ struct FFIOutPoint {
 
 #[repr(C)]
 pub struct FFIManyChannelMonitor {
-    add_monitor_ptr: extern "C" fn(&Self, funding_txo: OutPoint, monitor: ChannelMonitor<InMemoryChannelKeys>) -> i32,
-    update_monitor_ptr: extern "C" fn(&Self, funding_txo: OutPoint, monitor: ChannelMonitorUpdate) -> i32,
-    get_and_clear_pending_htlcs_updated_ptr: extern "C" fn(&Self) -> Vec<HTLCUpdate>,
+    add_monitor_ptr: extern "cdecl" fn(&Self, funding_txo: OutPoint, monitor: ChannelMonitor<InMemoryChannelKeys>) -> i32,
+    update_monitor_ptr: extern "cdecl" fn(&Self, funding_txo: OutPoint, monitor: ChannelMonitorUpdate) -> i32,
+    get_and_clear_pending_htlcs_updated_ptr: extern "cdecl" fn(&Self) -> Vec<HTLCUpdate>,
 }
 impl FFIManyChannelMonitor {
     fn errorcode_to_result(errorcode: i32) -> Result<(), ChannelMonitorUpdateErr> {
@@ -115,18 +66,19 @@ impl ManyChannelMonitor<InMemoryChannelKeys> for FFIManyChannelMonitor {
 
 #[repr(C)]
 pub struct FFIBroadCaster {
-  broadcast_transaction_ptr: extern "C" fn(&Self, tx: &Transaction),
+  broadcast_transaction_ptr: extern "cdecl" fn(tx: *const u8, tx_len: u64),
 }
 
 impl BroadcasterInterface for FFIBroadCaster {
     fn broadcast_transaction(&self, tx: &Transaction) {
-        (self.broadcast_transaction_ptr)(self, tx)
+        let b_tx = serialize(tx);
+        (self.broadcast_transaction_ptr)(b_tx.as_ptr(), b_tx.len() as u64)
     }
 }
 
 #[repr(C)]
 pub struct FFIFeeEstimator {
-    get_est_sat_per_1000_weight_ptr: extern "C" fn (&Self, ConfirmationTarget) -> u64,
+    get_est_sat_per_1000_weight_ptr: extern "cdecl" fn (&Self, ConfirmationTarget) -> u64,
 }
 
 impl FeeEstimator for FFIFeeEstimator {

bindings/src/channelmanager.rs

@@ -1,9 +1,11 @@
+use bitcoin::blockdata::transaction::Transaction;
 use std::sync::Arc;
 use std::time::{SystemTime, UNIX_EPOCH};
 
 use lightning::util::config::UserConfig;
 use lightning::chain::keysinterface::{KeysManager, InMemoryChannelKeys};
 use lightning::ln::channelmanager::{ChannelManager};
+use lightning::chain::chaininterface::{BroadcasterInterface};
 
 use crate::handle::{Out, Ref, RefMut,HandleShared};
 use crate::error::FFIResult;
@@ -45,3 +47,14 @@ ffi_no_catch!{
         FFIResult::ok()
     }
 }
+
+
+#[cfg(feature = "debug_assertions")]
+ffi! {
+    fn test_broadcaster(broadcaster_ptr: Ref<FFIBroadCaster>) -> FFIResult {
+        let broadcaster = unsafe_block!("" => broadcaster_ptr.as_ref());
+        let tx: Transaction = bitcoin::consensus::deserialize(&hex::decode("020000000001031cfbc8f54fbfa4a33a30068841371f80dbfe166211242213188428f437445c91000000006a47304402206fbcec8d2d2e740d824d3d36cc345b37d9f65d665a99f5bd5c9e8d42270a03a8022013959632492332200c2908459547bf8dbf97c65ab1a28dec377d6f1d41d3d63e012103d7279dfb90ce17fe139ba60a7c41ddf605b25e1c07a4ddcb9dfef4e7d6710f48feffffff476222484f5e35b3f0e43f65fc76e21d8be7818dd6a989c160b1e5039b7835fc00000000171600140914414d3c94af70ac7e25407b0689e0baa10c77feffffffa83d954a62568bbc99cc644c62eb7383d7c2a2563041a0aeb891a6a4055895570000000017160014795d04cc2d4f31480d9a3710993fbd80d04301dffeffffff06fef72f000000000017a91476fd7035cd26f1a32a5ab979e056713aac25796887a5000f00000000001976a914b8332d502a529571c6af4be66399cd33379071c588ac3fda0500000000001976a914fc1d692f8de10ae33295f090bea5fe49527d975c88ac522e1b00000000001976a914808406b54d1044c429ac54c0e189b0d8061667e088ac6eb68501000000001976a914dfab6085f3a8fb3e6710206a5a959313c5618f4d88acbba20000000000001976a914eb3026552d7e3f3073457d0bee5d4757de48160d88ac0002483045022100bee24b63212939d33d513e767bc79300051f7a0d433c3fcf1e0e3bf03b9eb1d70220588dc45a9ce3a939103b4459ce47500b64e23ab118dfc03c9caa7d6bfc32b9c601210354fd80328da0f9ae6eef2b3a81f74f9a6f66761fadf96f1d1d22b1fd6845876402483045022100e29c7e3a5efc10da6269e5fc20b6a1cb8beb92130cc52c67e46ef40aaa5cac5f0220644dd1b049727d991aece98a105563416e10a5ac4221abac7d16931842d5c322012103960b87412d6e169f30e12106bdf70122aabb9eb61f455518322a18b920a4dfa887d30700")?)?;
+        broadcaster.broadcast_transaction(&tx);
+        FFIResult::ok()
+    }
+}

bindings/src/channelmonitor.rs

@@ -0,0 +1,81 @@
+use std::sync::Arc;
+
+use bitcoin::blockdata::script::Script;
+use bitcoin::blockdata::transaction::Transaction;
+use bitcoin::blockdata::block::Block;
+use bitcoin_hashes::sha256d::Hash as Sha256dHash;
+
+use lightning::chain::transaction::OutPoint;
+use lightning::chain::chaininterface::{ChainWatchInterface, ChainError};
+use lightning::chain::keysinterface::{InMemoryChannelKeys};
+use lightning::ln::channelmonitor::SimpleManyChannelMonitor;
+
+use crate::adaptors::{FFIBroadCaster, FFIFeeEstimator, FFILogger};
+use crate::error::FFIResult;
+use crate::handle::{Ref, HandleShared};
+
+#[repr(C)]
+pub struct FFIOutPoint {
+	pub txid: Sha256dHash,
+	pub index: u16,
+}
+
+mod ChainWatchInterfaceFn {
+    use super::{FFIChainWatchInterface, FFIOutPoint};
+    pub type install_watch_tx_ptr = extern "cdecl" fn(*const FFIChainWatchInterface, script_pub_key_ptr: *const u8, script_pub_key_len: u64);
+    pub type install_watch_outpoint_ptr = extern "cdecl" fn(*const FFIChainWatchInterface, outpoint: FFIOutPoint, out_script_ptr: *const u8, out_script_len: u64);
+    pub type watch_all_txn = extern "cdecl" fn(*const FFIChainWatchInterface);
+    // pub type get_chain_utxo = extern "cdecl" fn(*const FFIChainWatchInterface, genesis_hash: );
+}
+
+#[repr(C)]
+pub struct FFIChainWatchInterface {
+    install_watch_tx_ptr: ChainWatchInterfaceFn::install_watch_tx_ptr,
+    install_watch_outpoint_ptr: ChainWatchInterfaceFn::install_watch_tx_ptr,
+}
+
+impl ChainWatchInterface for FFIChainWatchInterface {
+	fn install_watch_tx(&self, txid: &Sha256dHash, script_pub_key: &Script) {
+        unimplemented!()
+    }
+	fn install_watch_outpoint(&self, outpoint: (Sha256dHash, u32), out_script: &Script) {
+        unimplemented!()
+    }
+	fn watch_all_txn(&self) {
+        unimplemented!()
+    }
+	fn get_chain_utxo(&self, genesis_hash: Sha256dHash, unspent_tx_output_identifier: u64) -> Result<(Script, u64), ChainError> {
+        unimplemented!()
+    }
+	fn filter_block<'a>(&self, block: &'a Block) -> (Vec<&'a Transaction>, Vec<u32>) {
+        unimplemented!()
+    }
+	fn reentered(&self) -> usize {
+        unimplemented!()
+    }
+}
+
+type FFIManyChannelMonitor = SimpleManyChannelMonitor<FFIOutPoint, InMemoryChannelKeys, Arc<FFIBroadCaster>, Arc<FFIFeeEstimator>>;
+type FFIManyChannelMonitorHandle<'a> = HandleShared<'a, FFIManyChannelMonitor>;
+
+
+ffi_no_catch! {
+    fn create_ffi_channel_monitor(
+        chainwather: Ref<FFIChainWatchInterface>,
+        broadcaster: Ref<FFIBroadCaster>,
+        logger: Ref<FFILogger>,
+        fee_est: Ref<FFIFeeEstimator>
+    ) -> FFIResult {
+        // FFIManyChannelMonitor::new();
+        FFIResult::ok()
+    }
+}
+
+ffi! {
+    fn release_ffi_channel_monitor(handle: FFIManyChannelMonitorHandle) -> FFIResult {
+        unsafe_block!("The upstream caller guarantees the handle will not be accessed after being freed" => FFIManyChannelMonitorHandle::dealloc(handle, |mut handle| {
+            FFIResult::ok()
+        }))
+    }
+
+}

bindings/src/ffi_test_utils.rs

@@ -0,0 +1,106 @@
+use std::sync::Arc;
+use crate::error::FFIResult;
+
+use crate::handle::{Out, Ref, HandleShared};
+
+/// Lower level items for debugging wrapper library.
+/// When the FFI crashes without error messages, testing with these might be useful to understand
+/// what is the exact cause of the crash.
+
+/// These tests should be used for asserting that the wrapper code can see the expected
+/// error messages when it fails (or succeeds).
+ffi! {
+    fn ffi_test_error() -> FFIResult {
+        use std::io;
+
+        FFIResult::internal_error().context(io::Error::new(io::ErrorKind::Other, "A test error."))
+    }
+
+    fn ffi_test_ok() -> FFIResult {
+        FFIResult::ok()
+    }
+}
+
+
+#[repr(C)]
+pub struct FFITestInputStructWithPtr {
+    fn_ptr: extern "cdecl" fn(*const Self),
+}
+impl FFITestInputStructWithPtr {
+    pub fn call(&self) {
+        (self.fn_ptr)(self as *const _)
+    }
+}
+
+pub struct FFITestOutputStruct {
+    field: Arc<FFITestInputStructWithPtr>
+}
+
+impl FFITestOutputStruct {
+    fn complete(&self) {
+        println!("finished!");
+        self.field.call();
+    }
+}
+
+type FFITestOutputStructHandle<'a> = HandleShared<'a, FFITestOutputStruct>;
+
+type FFIFunctionPointer = extern "cdecl" fn (input: *const FFITestInputStructWithPtr);
+type FFIFunctionPointerWithReturn = extern "cdecl" fn (input: i32) -> i32;
+type FFIFunctionPointerWithReturnRef = extern "cdecl" fn (input: *const i32) -> *const i32;
+
+ffi! {
+    fn ffi_test_function_ptr(struct_arg_ptr: Ref<FFITestInputStructWithPtr>, fn_ptr: Ref<FFIFunctionPointer>) -> FFIResult {
+        // verify that if we pass functoin pointer and wrapper object separately and only calls the formar, it works.
+        let func = unsafe_block!("" => fn_ptr.as_ref());
+        let struct_arg = unsafe_block!("" => struct_arg_ptr.as_ref());
+        (func)(struct_arg);
+        FFIResult::ok()
+    }
+
+    fn ffi_simple_nested_struct(input: Ref<FFIFunctionPointer>, output: Out<FFITestOutputStructHandle>) -> FFIResult {
+        // verify that function pointer can be a member of other object.
+        let input_ref = unsafe_block!(" " => input.as_ref());
+        let result = FFITestOutputStruct { field: Arc::new(FFITestInputStructWithPtr{ fn_ptr: *input_ref }) };
+        result.complete();
+        unsafe_block!("" => output.init(HandleShared::alloc(result)));
+        FFIResult::ok()
+    }
+
+    fn ffi_simple_nested_struct_with_return_value(val_return_fn: Ref<FFIFunctionPointerWithReturn>, ref_return_fn: Ref<FFIFunctionPointerWithReturnRef>) -> FFIResult {
+        // verify that functoin pointer can return value. and it could be seen in wrapper lang side.
+        let val_return_fn_ref = unsafe_block!("" => val_return_fn.as_ref());
+        let ref_return_fn_ref = unsafe_block!("" => ref_return_fn.as_ref());
+
+        let val = (val_return_fn_ref)(33);
+        let r_ptr = (ref_return_fn_ref)(&44);
+        let r = unsafe_block!("" => *r_ptr);
+        println!("val was {}", val);
+        println!("ref was {}", r);
+        FFIResult::ok()
+    }
+
+    fn ffi_test_simple_struct_with_function_pointer(
+        input: Ref<FFITestInputStructWithPtr>,
+        output: Out<FFITestOutputStructHandle>
+    ) -> FFIResult {
+        // this test does not work, it seems that calling a function passed by wrapper struct will cause program to crash.
+        let input_ref = unsafe_block!(" " => input.as_ref());
+        // input_ref.call();
+        let input_arc = unsafe_block!(" " => input.as_arc());
+        // input_arc.call();
+        // let result = FFITestOutputStruct{ field: input_arc };
+        // result.field.call();
+        // unsafe_block!("We know output is not null by wrapper macro. And we know `Out` is writable" => output.init(HandleShared::alloc(result)));
+        FFIResult::ok()
+    }
+
+    fn ffi_test_release(handle: FFITestOutputStructHandle) -> FFIResult {
+        unsafe_block!("The upstream caller guarantees the handle will not be accessed after being freed" => FFITestOutputStructHandle::dealloc(handle, |mut handle| {
+            handle.complete();
+
+            FFIResult::ok()
+        }))
+    }
+
+}