lightning/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.
14pub 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.
18pub 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.
22pub const MAX_SCID_VOUT_INDEX: u64 = 0xffff;
23
24/// A `short_channel_id` construction error
25#[derive(Debug, PartialEq, Eq)]
26pub 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`
36pub 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`
41pub 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`
46pub 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.
52pub 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)
73pub(crate) mod fake_scid {
74	use bitcoin::constants::ChainHash;
75	use bitcoin::Network;
76	use crate::sign::EntropySource;
77	use crate::crypto::chacha20::ChaCha20;
78	use crate::util::scid_utils;
79	use crate::prelude::*;
80
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::constants::ChainHash;
186		use bitcoin::network::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)]
265mod 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}
lightning/util/scid_utils.rs

lightning/util/
scid_utils.rs
