_ Git - rust-lightning/blob - lightning/src/util/scid_utils.rs

   1 // This file is Copyright its original authors, visible in version control
   2 // history.
   3 //
   4 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
   5 // or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   6 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
   7 // You may not use this file except in accordance with one or both of these
   8 // licenses.
   9
  10 //! Utilities for creating and parsing short channel ids.
  11
  12 /// Maximum block height that can be used in a `short_channel_id`. This
  13 /// value is based on the 3-bytes available for block height.
  14 pub const MAX_SCID_BLOCK: u64 = 0x00ffffff;
  15
  16 /// Maximum transaction index that can be used in a `short_channel_id`.
  17 /// This value is based on the 3-bytes available for tx index.
  18 pub const MAX_SCID_TX_INDEX: u64 = 0x00ffffff;
  19
  20 /// Maximum vout index that can be used in a `short_channel_id`. This
  21 /// value is based on the 2-bytes available for the vout index.
  22 pub const MAX_SCID_VOUT_INDEX: u64 = 0xffff;
  23
  24 /// A `short_channel_id` construction error
  25 #[derive(Debug, PartialEq, Eq)]
  26 pub enum ShortChannelIdError {
  27         /// Block height too high
  28         BlockOverflow,
  29         /// Tx index too high
  30         TxIndexOverflow,
  31         /// Vout index too high
  32         VoutIndexOverflow,
  33 }
  34
  35 /// Extracts the block height (most significant 3-bytes) from the `short_channel_id`
  36 pub fn block_from_scid(short_channel_id: u64) -> u32 {
  37         return (short_channel_id >> 40) as u32;
  38 }
  39
  40 /// Extracts the tx index (bytes [2..4]) from the `short_channel_id`
  41 pub fn tx_index_from_scid(short_channel_id: u64) -> u32 {
  42         return ((short_channel_id >> 16) & MAX_SCID_TX_INDEX) as u32;
  43 }
  44
  45 /// Extracts the vout (bytes [0..2]) from the `short_channel_id`
  46 pub fn vout_from_scid(short_channel_id: u64) -> u16 {
  47         return ((short_channel_id) & MAX_SCID_VOUT_INDEX) as u16;
  48 }
  49
  50 /// Constructs a `short_channel_id` using the components pieces. Results in an error
  51 /// if the block height, tx index, or vout index overflow the maximum sizes.
  52 pub fn scid_from_parts(block: u64, tx_index: u64, vout_index: u64) -> Result<u64, ShortChannelIdError> {
  53         if block > MAX_SCID_BLOCK {
  54                 return Err(ShortChannelIdError::BlockOverflow);
  55         }
  56
  57         if tx_index > MAX_SCID_TX_INDEX {
  58                 return Err(ShortChannelIdError::TxIndexOverflow);
  59         }
  60
  61         if vout_index > MAX_SCID_VOUT_INDEX {
  62                 return Err(ShortChannelIdError::VoutIndexOverflow);
  63         }
  64
  65         Ok((block << 40) | (tx_index << 16) | vout_index)
  66 }
  67
  68 /// LDK has multiple reasons to generate fake short channel ids:
  69 /// 1) outbound SCID aliases we use for private channels
  70 /// 2) phantom node payments, to get an scid for the phantom node's phantom channel
  71 /// 3) payments intended to be intercepted will route using a fake scid (this is typically used so
  72 ///    the forwarding node can open a JIT channel to the next hop)
  73 pub(crate) mod fake_scid {
  74         use bitcoin::blockdata::constants::ChainHash;
  75         use bitcoin::network::constants::Network;
  76         use crate::sign::EntropySource;
  77         use crate::crypto::chacha20::ChaCha20;
  78         use crate::util::scid_utils;
  79
  80         use core::convert::TryInto;
  81         use core::ops::Deref;
  82
  83         const TEST_SEGWIT_ACTIVATION_HEIGHT: u32 = 1;
  84         const MAINNET_SEGWIT_ACTIVATION_HEIGHT: u32 = 481_824;
  85         const MAX_TX_INDEX: u32 = 2_500;
  86         const MAX_NAMESPACES: u8 = 8; // We allocate 3 bits for the namespace identifier.
  87         const NAMESPACE_ID_BITMASK: u8 = 0b111;
  88
  89         const BLOCKS_PER_MONTH: u32 = 144 /* blocks per day */ * 30 /* days per month */;
  90         pub(crate) const MAX_SCID_BLOCKS_FROM_NOW: u32 = BLOCKS_PER_MONTH;
  91
  92
  93         /// Fake scids are divided into namespaces, with each namespace having its own identifier between
  94         /// [0..7]. This allows us to identify what namespace a fake scid corresponds to upon HTLC
  95         /// receipt, and handle the HTLC accordingly. The namespace identifier is encrypted when encoded
  96         /// into the fake scid.
  97         #[derive(Copy, Clone)]
  98         pub(crate) enum Namespace {
  99                 /// Phantom nodes namespace
 100                 Phantom,
 101                 /// SCID aliases for outbound private channels
 102                 OutboundAlias,
 103                 /// Payment interception namespace
 104                 Intercept
 105         }
 106
 107         impl Namespace {
 108                 /// We generate "realistic-looking" random scids here, meaning the scid's block height is
 109                 /// between segwit activation and the current best known height, and the tx index and output
 110                 /// index are also selected from a "reasonable" range. We add this logic because it makes it
 111                 /// non-obvious at a glance that the scid is fake, e.g. if it appears in invoice route hints.
 112                 pub(crate) fn get_fake_scid<ES: Deref>(&self, highest_seen_blockheight: u32, chain_hash: &ChainHash, fake_scid_rand_bytes: &[u8; 32], entropy_source: &ES) -> u64
 113                         where ES::Target: EntropySource,
 114                 {
 115                         // Ensure we haven't created a namespace that doesn't fit into the 3 bits we've allocated for
 116                         // namespaces.
 117                         assert!((*self as u8) < MAX_NAMESPACES);
 118                         let rand_bytes = entropy_source.get_secure_random_bytes();
 119
 120                         let segwit_activation_height = segwit_activation_height(chain_hash);
 121                         let mut blocks_since_segwit_activation = highest_seen_blockheight.saturating_sub(segwit_activation_height);
 122
 123                         // We want to ensure that this fake channel won't conflict with any transactions we haven't
 124                         // seen yet, in case `highest_seen_blockheight` is updated before we get full information
 125                         // about transactions confirmed in the given block.
 126                         blocks_since_segwit_activation = blocks_since_segwit_activation.saturating_sub(MAX_SCID_BLOCKS_FROM_NOW);
 127
 128                         let rand_for_height = u32::from_be_bytes(rand_bytes[..4].try_into().unwrap());
 129                         let fake_scid_height = segwit_activation_height + rand_for_height % (blocks_since_segwit_activation + 1);
 130
 131                         let rand_for_tx_index = u32::from_be_bytes(rand_bytes[4..8].try_into().unwrap());
 132                         let fake_scid_tx_index = rand_for_tx_index % MAX_TX_INDEX;
 133
 134                         // Put the scid in the given namespace.
 135                         let fake_scid_vout = self.get_encrypted_vout(fake_scid_height, fake_scid_tx_index, fake_scid_rand_bytes);
 136                         scid_utils::scid_from_parts(fake_scid_height as u64, fake_scid_tx_index as u64, fake_scid_vout as u64).unwrap()
 137                 }
 138
 139                 /// We want to ensure that a 3rd party can't identify a payment as belong to a given
 140                 /// `Namespace`. Therefore, we encrypt it using a random bytes provided by `ChannelManager`.
 141                 fn get_encrypted_vout(&self, block_height: u32, tx_index: u32, fake_scid_rand_bytes: &[u8; 32]) -> u8 {
 142                         let mut salt = [0 as u8; 8];
 143                         let block_height_bytes = block_height.to_be_bytes();
 144                         salt[0..4].copy_from_slice(&block_height_bytes);
 145                         let tx_index_bytes = tx_index.to_be_bytes();
 146                         salt[4..8].copy_from_slice(&tx_index_bytes);
 147
 148                         let mut chacha = ChaCha20::new(fake_scid_rand_bytes, &salt);
 149                         let mut vout_byte = [*self as u8];
 150                         chacha.process_in_place(&mut vout_byte);
 151                         vout_byte[0] & NAMESPACE_ID_BITMASK
 152                 }
 153         }
 154
 155         fn segwit_activation_height(chain_hash: &ChainHash) -> u32 {
 156                 if *chain_hash == ChainHash::using_genesis_block(Network::Bitcoin) {
 157                         MAINNET_SEGWIT_ACTIVATION_HEIGHT
 158                 } else {
 159                         TEST_SEGWIT_ACTIVATION_HEIGHT
 160                 }
 161         }
 162
 163         /// Returns whether the given fake scid falls into the phantom namespace.
 164         pub fn is_valid_phantom(fake_scid_rand_bytes: &[u8; 32], scid: u64, chain_hash: &ChainHash) -> bool {
 165                 let block_height = scid_utils::block_from_scid(scid);
 166                 let tx_index = scid_utils::tx_index_from_scid(scid);
 167                 let namespace = Namespace::Phantom;
 168                 let valid_vout = namespace.get_encrypted_vout(block_height, tx_index, fake_scid_rand_bytes);
 169                 block_height >= segwit_activation_height(chain_hash)
 170                         && valid_vout == scid_utils::vout_from_scid(scid) as u8
 171         }
 172
 173         /// Returns whether the given fake scid falls into the intercept namespace.
 174         pub fn is_valid_intercept(fake_scid_rand_bytes: &[u8; 32], scid: u64, chain_hash: &ChainHash) -> bool {
 175                 let block_height = scid_utils::block_from_scid(scid);
 176                 let tx_index = scid_utils::tx_index_from_scid(scid);
 177                 let namespace = Namespace::Intercept;
 178                 let valid_vout = namespace.get_encrypted_vout(block_height, tx_index, fake_scid_rand_bytes);
 179                 block_height >= segwit_activation_height(chain_hash)
 180                         && valid_vout == scid_utils::vout_from_scid(scid) as u8
 181         }
 182
 183         #[cfg(test)]
 184         mod tests {
 185                 use bitcoin::blockdata::constants::ChainHash;
 186                 use bitcoin::network::constants::Network;
 187                 use crate::util::scid_utils::fake_scid::{is_valid_intercept, is_valid_phantom, MAINNET_SEGWIT_ACTIVATION_HEIGHT, MAX_TX_INDEX, MAX_NAMESPACES, Namespace, NAMESPACE_ID_BITMASK, segwit_activation_height, TEST_SEGWIT_ACTIVATION_HEIGHT};
 188                 use crate::util::scid_utils;
 189                 use crate::util::test_utils;
 190                 use crate::sync::Arc;
 191
 192                 #[test]
 193                 fn namespace_identifier_is_within_range() {
 194                         let phantom_namespace = Namespace::Phantom;
 195                         assert!((phantom_namespace as u8) < MAX_NAMESPACES);
 196                         assert!((phantom_namespace as u8) <= NAMESPACE_ID_BITMASK);
 197
 198                         let intercept_namespace = Namespace::Intercept;
 199                         assert!((intercept_namespace as u8) < MAX_NAMESPACES);
 200                         assert!((intercept_namespace as u8) <= NAMESPACE_ID_BITMASK);
 201                 }
 202
 203                 #[test]
 204                 fn test_segwit_activation_height() {
 205                         let mainnet_genesis = ChainHash::using_genesis_block(Network::Bitcoin);
 206                         assert_eq!(segwit_activation_height(&mainnet_genesis), MAINNET_SEGWIT_ACTIVATION_HEIGHT);
 207
 208                         let testnet_genesis = ChainHash::using_genesis_block(Network::Testnet);
 209                         assert_eq!(segwit_activation_height(&testnet_genesis), TEST_SEGWIT_ACTIVATION_HEIGHT);
 210
 211                         let signet_genesis = ChainHash::using_genesis_block(Network::Signet);
 212                         assert_eq!(segwit_activation_height(&signet_genesis), TEST_SEGWIT_ACTIVATION_HEIGHT);
 213
 214                         let regtest_genesis = ChainHash::using_genesis_block(Network::Regtest);
 215                         assert_eq!(segwit_activation_height(&regtest_genesis), TEST_SEGWIT_ACTIVATION_HEIGHT);
 216                 }
 217
 218                 #[test]
 219                 fn test_is_valid_phantom() {
 220                         let namespace = Namespace::Phantom;
 221                         let fake_scid_rand_bytes = [0; 32];
 222                         let testnet_genesis = ChainHash::using_genesis_block(Network::Testnet);
 223                         let valid_encrypted_vout = namespace.get_encrypted_vout(0, 0, &fake_scid_rand_bytes);
 224                         let valid_fake_scid = scid_utils::scid_from_parts(1, 0, valid_encrypted_vout as u64).unwrap();
 225                         assert!(is_valid_phantom(&fake_scid_rand_bytes, valid_fake_scid, &testnet_genesis));
 226                         let invalid_fake_scid = scid_utils::scid_from_parts(1, 0, 12).unwrap();
 227                         assert!(!is_valid_phantom(&fake_scid_rand_bytes, invalid_fake_scid, &testnet_genesis));
 228                 }
 229
 230                 #[test]
 231                 fn test_is_valid_intercept() {
 232                         let namespace = Namespace::Intercept;
 233                         let fake_scid_rand_bytes = [0; 32];
 234                         let testnet_genesis = ChainHash::using_genesis_block(Network::Testnet);
 235                         let valid_encrypted_vout = namespace.get_encrypted_vout(0, 0, &fake_scid_rand_bytes);
 236                         let valid_fake_scid = scid_utils::scid_from_parts(1, 0, valid_encrypted_vout as u64).unwrap();
 237                         assert!(is_valid_intercept(&fake_scid_rand_bytes, valid_fake_scid, &testnet_genesis));
 238                         let invalid_fake_scid = scid_utils::scid_from_parts(1, 0, 12).unwrap();
 239                         assert!(!is_valid_intercept(&fake_scid_rand_bytes, invalid_fake_scid, &testnet_genesis));
 240                 }
 241
 242                 #[test]
 243                 fn test_get_fake_scid() {
 244                         let mainnet_genesis = ChainHash::using_genesis_block(Network::Bitcoin);
 245                         let seed = [0; 32];
 246                         let fake_scid_rand_bytes = [1; 32];
 247                         let keys_manager = Arc::new(test_utils::TestKeysInterface::new(&seed, Network::Testnet));
 248                         let namespace = Namespace::Phantom;
 249                         let fake_scid = namespace.get_fake_scid(500_000, &mainnet_genesis, &fake_scid_rand_bytes, &keys_manager);
 250
 251                         let fake_height = scid_utils::block_from_scid(fake_scid);
 252                         assert!(fake_height >= MAINNET_SEGWIT_ACTIVATION_HEIGHT);
 253                         assert!(fake_height <= 500_000);
 254
 255                         let fake_tx_index = scid_utils::tx_index_from_scid(fake_scid);
 256                         assert!(fake_tx_index <= MAX_TX_INDEX);
 257
 258                         let fake_vout = scid_utils::vout_from_scid(fake_scid);
 259                         assert!(fake_vout < MAX_NAMESPACES as u16);
 260                 }
 261         }
 262 }
 263
 264 #[cfg(test)]
 265 mod tests {
 266         use super::*;
 267
 268         #[test]
 269         fn test_block_from_scid() {
 270                 assert_eq!(block_from_scid(0x000000_000000_0000), 0);
 271                 assert_eq!(block_from_scid(0x000001_000000_0000), 1);
 272                 assert_eq!(block_from_scid(0x000001_ffffff_ffff), 1);
 273                 assert_eq!(block_from_scid(0x800000_ffffff_ffff), 0x800000);
 274                 assert_eq!(block_from_scid(0xffffff_ffffff_ffff), 0xffffff);
 275         }
 276
 277         #[test]
 278         fn test_tx_index_from_scid() {
 279                 assert_eq!(tx_index_from_scid(0x000000_000000_0000), 0);
 280                 assert_eq!(tx_index_from_scid(0x000000_000001_0000), 1);
 281                 assert_eq!(tx_index_from_scid(0xffffff_000001_ffff), 1);
 282                 assert_eq!(tx_index_from_scid(0xffffff_800000_ffff), 0x800000);
 283                 assert_eq!(tx_index_from_scid(0xffffff_ffffff_ffff), 0xffffff);
 284         }
 285
 286         #[test]
 287         fn test_vout_from_scid() {
 288                 assert_eq!(vout_from_scid(0x000000_000000_0000), 0);
 289                 assert_eq!(vout_from_scid(0x000000_000000_0001), 1);
 290                 assert_eq!(vout_from_scid(0xffffff_ffffff_0001), 1);
 291                 assert_eq!(vout_from_scid(0xffffff_ffffff_8000), 0x8000);
 292                 assert_eq!(vout_from_scid(0xffffff_ffffff_ffff), 0xffff);
 293         }
 294
 295         #[test]
 296         fn test_scid_from_parts() {
 297                 assert_eq!(scid_from_parts(0x00000000, 0x00000000, 0x0000).unwrap(), 0x000000_000000_0000);
 298                 assert_eq!(scid_from_parts(0x00000001, 0x00000002, 0x0003).unwrap(), 0x000001_000002_0003);
 299                 assert_eq!(scid_from_parts(0x00111111, 0x00222222, 0x3333).unwrap(), 0x111111_222222_3333);
 300                 assert_eq!(scid_from_parts(0x00ffffff, 0x00ffffff, 0xffff).unwrap(), 0xffffff_ffffff_ffff);
 301                 assert_eq!(scid_from_parts(0x01ffffff, 0x00000000, 0x0000).err().unwrap(), ShortChannelIdError::BlockOverflow);
 302                 assert_eq!(scid_from_parts(0x00000000, 0x01ffffff, 0x0000).err().unwrap(), ShortChannelIdError::TxIndexOverflow);
 303                 assert_eq!(scid_from_parts(0x00000000, 0x00000000, 0x010000).err().unwrap(), ShortChannelIdError::VoutIndexOverflow);
 304         }
 305 }