_ Git - ldk-c-bindings/blob - lightning-c-bindings/src/c_types/mod.rs

   1 //! This module contains standard C-mapped types for types not in the original crate.
   2
   3 /// Auto-generated C-mapped types for templated containers
   4 pub mod derived;
   5
   6 use bitcoin::Script as BitcoinScript;
   7 use bitcoin::Transaction as BitcoinTransaction;
   8 use bitcoin::hashes::Hash;
   9 use bitcoin::secp256k1::key::PublicKey as SecpPublicKey;
  10 use bitcoin::secp256k1::key::SecretKey as SecpSecretKey;
  11 use bitcoin::secp256k1::Signature as SecpSignature;
  12 use bitcoin::secp256k1::Error as SecpError;
  13
  14 use std::convert::TryInto; // Bindings need at least rustc 1.34
  15
  16 #[derive(Clone)]
  17 #[repr(C)]
  18 /// Represents a valid secp256k1 public key serialized in "compressed form" as a 33 byte array.
  19 pub struct PublicKey {
  20         /// The bytes of the public key
  21         pub compressed_form: [u8; 33],
  22 }
  23 impl PublicKey {
  24         pub(crate) fn from_rust(pk: &SecpPublicKey) -> Self {
  25                 Self {
  26                         compressed_form: pk.serialize(),
  27                 }
  28         }
  29         pub(crate) fn into_rust(&self) -> SecpPublicKey {
  30                 SecpPublicKey::from_slice(&self.compressed_form).unwrap()
  31         }
  32         pub(crate) fn is_null(&self) -> bool { self.compressed_form[..] == [0; 33][..] }
  33         pub(crate) fn null() -> Self { Self { compressed_form: [0; 33] } }
  34 }
  35
  36 #[repr(C)]
  37 /// Represents a valid secp256k1 secret key serialized as a 32 byte array.
  38 pub struct SecretKey {
  39         /// The bytes of the secret key
  40         pub bytes: [u8; 32],
  41 }
  42 impl SecretKey {
  43         // from_rust isn't implemented for a ref since we just return byte array refs directly
  44         pub(crate) fn from_rust(sk: SecpSecretKey) -> Self {
  45                 let mut bytes = [0; 32];
  46                 bytes.copy_from_slice(&sk[..]);
  47                 Self { bytes }
  48         }
  49         pub(crate) fn into_rust(&self) -> SecpSecretKey {
  50                 SecpSecretKey::from_slice(&self.bytes).unwrap()
  51         }
  52 }
  53
  54 #[repr(C)]
  55 #[derive(Clone)]
  56 /// Represents a secp256k1 signature serialized as two 32-byte numbers
  57 pub struct Signature {
  58         /// The bytes of the signature in "compact" form
  59         pub compact_form: [u8; 64],
  60 }
  61 impl Signature {
  62         pub(crate) fn from_rust(pk: &SecpSignature) -> Self {
  63                 Self {
  64                         compact_form: pk.serialize_compact(),
  65                 }
  66         }
  67         pub(crate) fn into_rust(&self) -> SecpSignature {
  68                 SecpSignature::from_compact(&self.compact_form).unwrap()
  69         }
  70         // The following are used for Option<Signature> which we support, but don't use anymore
  71         #[allow(unused)] pub(crate) fn is_null(&self) -> bool { self.compact_form[..] == [0; 64][..] }
  72         #[allow(unused)] pub(crate) fn null() -> Self { Self { compact_form: [0; 64] } }
  73 }
  74
  75 #[repr(C)]
  76 /// Represents an error returned from libsecp256k1 during validation of some secp256k1 data
  77 pub enum Secp256k1Error {
  78         /// Signature failed verification
  79         IncorrectSignature,
  80         /// Badly sized message ("messages" are actually fixed-sized digests; see the MESSAGE_SIZE constant)
  81         InvalidMessage,
  82         /// Bad public key
  83         InvalidPublicKey,
  84         /// Bad signature
  85         InvalidSignature,
  86         /// Bad secret key
  87         InvalidSecretKey,
  88         /// Bad recovery id
  89         InvalidRecoveryId,
  90         /// Invalid tweak for add_assign or mul_assign
  91         InvalidTweak,
  92         /// tweak_add_check failed on an xonly public key
  93         TweakCheckFailed,
  94         /// Didn't pass enough memory to context creation with preallocated memory
  95         NotEnoughMemory,
  96 }
  97 impl Secp256k1Error {
  98         pub(crate) fn from_rust(err: SecpError) -> Self {
  99                 match err {
 100                         SecpError::IncorrectSignature => Secp256k1Error::IncorrectSignature,
 101                         SecpError::InvalidMessage => Secp256k1Error::InvalidMessage,
 102                         SecpError::InvalidPublicKey => Secp256k1Error::InvalidPublicKey,
 103                         SecpError::InvalidSignature => Secp256k1Error::InvalidSignature,
 104                         SecpError::InvalidSecretKey => Secp256k1Error::InvalidSecretKey,
 105                         SecpError::InvalidRecoveryId => Secp256k1Error::InvalidRecoveryId,
 106                         SecpError::InvalidTweak => Secp256k1Error::InvalidTweak,
 107                         SecpError::TweakCheckFailed => Secp256k1Error::TweakCheckFailed,
 108                         SecpError::NotEnoughMemory => Secp256k1Error::NotEnoughMemory,
 109                 }
 110         }
 111 }
 112
 113 #[repr(C)]
 114 /// A serialized transaction, in (pointer, length) form.
 115 ///
 116 /// This type optionally owns its own memory, and thus the semantics around access change based on
 117 /// the `data_is_owned` flag. If `data_is_owned` is set, you must call `Transaction_free` to free
 118 /// the underlying buffer before the object goes out of scope. If `data_is_owned` is not set, any
 119 /// access to the buffer after the scope in which the object was provided to you is invalid. eg,
 120 /// access after you return from the call in which a `!data_is_owned` `Transaction` is provided to
 121 /// you would be invalid.
 122 ///
 123 /// Note that, while it may change in the future, because transactions on the Rust side are stored
 124 /// in a deserialized form, all `Transaction`s generated on the Rust side will have `data_is_owned`
 125 /// set. Similarly, while it may change in the future, all `Transaction`s you pass to Rust may have
 126 /// `data_is_owned` either set or unset at your discretion.
 127 pub struct Transaction {
 128         /// The serialized transaction data.
 129         ///
 130         /// This is non-const for your convenience, an object passed to Rust is never written to.
 131         pub data: *mut u8,
 132         /// The length of the serialized transaction
 133         pub datalen: usize,
 134         /// Whether the data pointed to by `data` should be freed or not.
 135         pub data_is_owned: bool,
 136 }
 137 impl Transaction {
 138         pub(crate) fn into_bitcoin(&self) -> BitcoinTransaction {
 139                 if self.datalen == 0 { panic!("0-length buffer can never represent a valid Transaction"); }
 140                 ::bitcoin::consensus::encode::deserialize(unsafe { std::slice::from_raw_parts(self.data, self.datalen) }).unwrap()
 141         }
 142         pub(crate) fn from_vec(v: Vec<u8>) -> Self {
 143                 let datalen = v.len();
 144                 let data = Box::into_raw(v.into_boxed_slice());
 145                 Self {
 146                         data: unsafe { (*data).as_mut_ptr() },
 147                         datalen,
 148                         data_is_owned: true,
 149                 }
 150         }
 151 }
 152 impl Drop for Transaction {
 153         fn drop(&mut self) {
 154                 if self.data_is_owned && self.datalen != 0 {
 155                         let _ = derived::CVec_u8Z { data: self.data as *mut u8, datalen: self.datalen };
 156                 }
 157         }
 158 }
 159 #[no_mangle]
 160 /// Frees the data buffer, if data_is_owned is set and datalen > 0.
 161 pub extern "C" fn Transaction_free(_res: Transaction) { }
 162
 163 pub(crate) fn bitcoin_to_C_outpoint(outpoint: ::bitcoin::blockdata::transaction::OutPoint) -> crate::lightning::chain::transaction::OutPoint {
 164         crate::lightning::chain::transaction::OutPoint_new(ThirtyTwoBytes { data: outpoint.txid.into_inner() }, outpoint.vout.try_into().unwrap())
 165 }
 166
 167 #[repr(C)]
 168 #[derive(Clone)]
 169 /// A transaction output including a scriptPubKey and value.
 170 /// This type *does* own its own memory, so must be free'd appropriately.
 171 pub struct TxOut {
 172         /// The script_pubkey in this output
 173         pub script_pubkey: derived::CVec_u8Z,
 174         /// The value, in satoshis, of this output
 175         pub value: u64,
 176 }
 177
 178 impl TxOut {
 179         pub(crate) fn into_rust(mut self) -> ::bitcoin::blockdata::transaction::TxOut {
 180                 ::bitcoin::blockdata::transaction::TxOut {
 181                         script_pubkey: self.script_pubkey.into_rust().into(),
 182                         value: self.value,
 183                 }
 184         }
 185         pub(crate) fn from_rust(txout: ::bitcoin::blockdata::transaction::TxOut) -> Self {
 186                 Self {
 187                         script_pubkey: derived::CVec_u8Z::from(txout.script_pubkey.into_bytes()),
 188                         value: txout.value
 189                 }
 190         }
 191 }
 192 #[no_mangle]
 193 /// Frees the data pointed to by script_pubkey.
 194 pub extern "C" fn TxOut_free(_res: TxOut) { }
 195 #[no_mangle]
 196 /// Creates a new TxOut which has the same data as `orig` but with a new script buffer.
 197 pub extern "C" fn TxOut_clone(orig: &TxOut) -> TxOut { orig.clone() }
 198
 199 #[repr(C)]
 200 /// A "slice" referencing some byte array. This is simply a length-tagged pointer which does not
 201 /// own the memory pointed to by data.
 202 pub struct u8slice {
 203         /// A pointer to the byte buffer
 204         pub data: *const u8,
 205         /// The number of bytes pointed to by `data`.
 206         pub datalen: usize
 207 }
 208 impl u8slice {
 209         pub(crate) fn from_slice(s: &[u8]) -> Self {
 210                 Self {
 211                         data: s.as_ptr(),
 212                         datalen: s.len(),
 213                 }
 214         }
 215         pub(crate) fn to_slice(&self) -> &[u8] {
 216                 if self.datalen == 0 { return &[]; }
 217                 unsafe { std::slice::from_raw_parts(self.data, self.datalen) }
 218         }
 219 }
 220
 221 #[repr(C)]
 222 #[derive(Copy, Clone)]
 223 /// Arbitrary 32 bytes, which could represent one of a few different things. You probably want to
 224 /// look up the corresponding function in rust-lightning's docs.
 225 pub struct ThirtyTwoBytes {
 226         /// The thirty-two bytes
 227         pub data: [u8; 32],
 228 }
 229 impl ThirtyTwoBytes {
 230         pub(crate) fn null() -> Self {
 231                 Self { data: [0; 32] }
 232         }
 233 }
 234
 235 #[repr(C)]
 236 /// A 3-byte byte array.
 237 pub struct ThreeBytes { /** The three bytes */ pub data: [u8; 3], }
 238 #[derive(Clone)]
 239 #[repr(C)]
 240 /// A 4-byte byte array.
 241 pub struct FourBytes { /** The four bytes */ pub data: [u8; 4], }
 242 #[derive(Clone)]
 243 #[repr(C)]
 244 /// A 10-byte byte array.
 245 pub struct TenBytes { /** The ten bytes */ pub data: [u8; 10], }
 246 #[derive(Clone)]
 247 #[repr(C)]
 248 /// A 16-byte byte array.
 249 pub struct SixteenBytes { /** The sixteen bytes */ pub data: [u8; 16], }
 250
 251 pub(crate) struct VecWriter(pub Vec<u8>);
 252 impl lightning::util::ser::Writer for VecWriter {
 253         fn write_all(&mut self, buf: &[u8]) -> Result<(), ::std::io::Error> {
 254                 self.0.extend_from_slice(buf);
 255                 Ok(())
 256         }
 257         fn size_hint(&mut self, size: usize) {
 258                 self.0.reserve_exact(size);
 259         }
 260 }
 261 pub(crate) fn serialize_obj<I: lightning::util::ser::Writeable>(i: &I) -> derived::CVec_u8Z {
 262         let mut out = VecWriter(Vec::new());
 263         i.write(&mut out).unwrap();
 264         derived::CVec_u8Z::from(out.0)
 265 }
 266 pub(crate) fn deserialize_obj<I: lightning::util::ser::Readable>(s: u8slice) -> Result<I, lightning::ln::msgs::DecodeError> {
 267         I::read(&mut s.to_slice())
 268 }
 269 pub(crate) fn deserialize_obj_arg<A, I: lightning::util::ser::ReadableArgs<A>>(s: u8slice, args: A) -> Result<I, lightning::ln::msgs::DecodeError> {
 270         I::read(&mut s.to_slice(), args)
 271 }
 272
 273 #[repr(C)]
 274 #[derive(Copy, Clone)]
 275 /// A Rust str object, ie a reference to a UTF8-valid string.
 276 /// This is *not* null-terminated so cannot be used directly as a C string!
 277 pub struct Str {
 278         /// A pointer to the string's bytes, in UTF8 encoding
 279         pub chars: *const u8,
 280         /// The number of bytes (not characters!) pointed to by `chars`
 281         pub len: usize
 282 }
 283 impl Into<Str> for &'static str {
 284         fn into(self) -> Str {
 285                 Str { chars: self.as_ptr(), len: self.len() }
 286         }
 287 }
 288 impl Into<&'static str> for Str {
 289         fn into(self) -> &'static str {
 290                 if self.len == 0 { return ""; }
 291                 std::str::from_utf8(unsafe { std::slice::from_raw_parts(self.chars, self.len) }).unwrap()
 292         }
 293 }
 294
 295 // Note that the C++ headers memset(0) all the Templ types to avoid deallocation!
 296 // Thus, they must gracefully handle being completely null in _free.
 297
 298 // TODO: Integer/bool primitives should avoid the pointer indirection for underlying types
 299 // everywhere in the containers.
 300
 301 #[repr(C)]
 302 pub(crate) union CResultPtr<O, E> {
 303         pub(crate) result: *mut O,
 304         pub(crate) err: *mut E,
 305 }
 306 #[repr(C)]
 307 pub(crate) struct CResultTempl<O, E> {
 308         pub(crate) contents: CResultPtr<O, E>,
 309         pub(crate) result_ok: bool,
 310 }
 311 impl<O, E> CResultTempl<O, E> {
 312         pub(crate) extern "C" fn ok(o: O) -> Self {
 313                 CResultTempl {
 314                         contents: CResultPtr {
 315                                 result: Box::into_raw(Box::new(o)),
 316                         },
 317                         result_ok: true,
 318                 }
 319         }
 320         pub(crate) extern "C" fn err(e: E) -> Self {
 321                 CResultTempl {
 322                         contents: CResultPtr {
 323                                 err: Box::into_raw(Box::new(e)),
 324                         },
 325                         result_ok: false,
 326                 }
 327         }
 328 }
 329 impl<O, E> Drop for CResultTempl<O, E> {
 330         fn drop(&mut self) {
 331                 if self.result_ok {
 332                         if unsafe { !self.contents.result.is_null() } {
 333                                 unsafe { Box::from_raw(self.contents.result) };
 334                         }
 335                 } else if unsafe { !self.contents.err.is_null() } {
 336                         unsafe { Box::from_raw(self.contents.err) };
 337                 }
 338         }
 339 }
 340
 341 /// Utility to make it easy to set a pointer to null and get its original value in line.
 342 pub(crate) trait TakePointer<T> {
 343         fn take_ptr(&mut self) -> T;
 344 }
 345 impl<T> TakePointer<*const T> for *const T {
 346         fn take_ptr(&mut self) -> *const T {
 347                 let ret = *self;
 348                 *self = std::ptr::null();
 349                 ret
 350         }
 351 }
 352 impl<T> TakePointer<*mut T> for *mut T {
 353         fn take_ptr(&mut self) -> *mut T {
 354                 let ret = *self;
 355                 *self = std::ptr::null_mut();
 356                 ret
 357         }
 358 }