keysmanager: support phantom payments with PhantomKeysManager

To support the feature of generating invoices that can be paid to any of
multiple nodes, a key manager need to be able to share an inbound_payment_key
and phantom secret key. This is because a phantom payment may be received by
any node participating in the invoice, so all nodes must be able to decrypt the
phantom payment (and therefore must share decryption key(s)) in the act of
pretending to be the phantom node. Thus we add a new `PhantomKeysManager` that
supports these features.

To be more specific, the inbound payment key must be shared because it is used
to decrypt the payment details for verification (LDK avoids storing inbound
payment data by encrypting payment metadata in the payment hash and/or payment
secret).

The phantom secret must be shared because enables any real node included in the
phantom invoice to decrypt the final layer of the onion packet, since the onion
is encrypted by the sender using the phantom public key provided in the
invoice.

Author: valentinewallace

lightning/src/chain/keysinterface.rs

@@ -31,6 +31,7 @@ use bitcoin::secp256k1::recovery::RecoverableSignature;
 use bitcoin::secp256k1;
 
 use util::{byte_utils, transaction_utils};
+use util::crypto::hkdf_extract_expand_twice;
 use util::ser::{Writeable, Writer, Readable, ReadableArgs};
 
 use chain::transaction::OutPoint;
@@ -427,7 +428,16 @@ pub trait KeysInterface {
 
 	/// Get secret key material as bytes for use in encrypting and decrypting inbound payment data.
 	///
+	/// If the implementor of this trait supports [phantom node payments], then every node that is
+	/// intended to be included in the phantom invoice route hints must return the same value from
+	/// this method.
+	//  This is because LDK avoids storing inbound payment data by encrypting payment data in the
+	//  payment hash and/or payment secret, therefore for a payment to be receivable by multiple
+	//  nodes, they must share the key that encrypts this payment data.
+	///
 	/// This method must return the same value each time it is called.
+	///
+	/// [phantom node payments]: PhantomKeysManager
 	fn get_inbound_payment_key_material(&self) -> KeyMaterial;
 }
 
@@ -810,6 +820,12 @@ impl ReadableArgs<SecretKey> for InMemorySigner {
 /// ChannelMonitor closes may use seed/1'
 /// Cooperative closes may use seed/2'
 /// The two close keys may be needed to claim on-chain funds!
+///
+/// This struct cannot be used for nodes that wish to support receiving phantom payments;
+/// [`PhantomKeysManager`] must be used instead.
+///
+/// Note that switching between this struct and [`PhantomKeysManager`] will invalidate any
+/// previously issued invoices and attempts to pay previous invoices will fail.
 pub struct KeysManager {
 	secp_ctx: Secp256k1<secp256k1::All>,
 	node_secret: SecretKey,
@@ -964,7 +980,7 @@ impl KeysManager {
 	/// transaction will have a feerate, at least, of the given value.
 	///
 	/// Returns `Err(())` if the output value is greater than the input value minus required fee,
-	/// if a descriptor was duplicated, or if an output descriptor script_pubkey 
+	/// if a descriptor was duplicated, or if an output descriptor `script_pubkey`
 	/// does not match the one we can spend.
 	///
 	/// We do not enforce that outputs meet the dust limit or that any output scripts are standard.
@@ -1139,6 +1155,102 @@ impl KeysInterface for KeysManager {
 	}
 }
 
+/// Similar to [`KeysManager`], but allows the node using this struct to receive phantom node
+/// payments.
+///
+/// A phantom node payment is a payment made to a phantom invoice, which is an invoice that can be
+/// paid to one of multiple nodes. This works because we encode the invoice route hints such that
+/// LDK will recognize an incoming payment as destined for a phantom node, and collect the payment
+/// itself without ever needing to forward to this fake node.
+///
+/// Phantom node payments are useful for load balancing between multiple LDK nodes. They also
+/// provide some fault tolerance, because payers will automatically retry paying other provided
+/// nodes in the case that one node goes down.
+///
+/// Note that multi-path payments are not supported in phantom invoices for security reasons.
+//  In the hypothetical case that we did support MPP phantom payments, there would be no way for
+//  nodes to know when the full payment has been received (and the preimage can be released) without
+//  significantly compromising on our safety guarantees. I.e., if we expose the ability for the user
+//  to tell LDK when the preimage can be released, we open ourselves to attacks where the preimage
+//  is released too early.
+//
+/// Switching between this struct and [`KeysManager`] will invalidate any previously issued
+/// invoices and attempts to pay previous invoices will fail.
+pub struct PhantomKeysManager {
+	inner: KeysManager,
+	inbound_payment_key: KeyMaterial,
+	phantom_secret: SecretKey,
+}
+
+impl KeysInterface for PhantomKeysManager {
+	type Signer = InMemorySigner;
+
+	fn get_node_secret(&self) -> SecretKey {
+		self.inner.get_node_secret()
+	}
+
+	fn get_inbound_payment_key_material(&self) -> KeyMaterial {
+		self.inbound_payment_key.clone()
+	}
+
+	fn get_destination_script(&self) -> Script {
+		self.inner.get_destination_script()
+	}
+
+	fn get_shutdown_scriptpubkey(&self) -> ShutdownScript {
+		self.inner.get_shutdown_scriptpubkey()
+	}
+
+	fn get_channel_signer(&self, inbound: bool, channel_value_satoshis: u64) -> Self::Signer {
+		self.inner.get_channel_signer(inbound, channel_value_satoshis)
+	}
+
+	fn get_secure_random_bytes(&self) -> [u8; 32] {
+		self.inner.get_secure_random_bytes()
+	}
+
+	fn read_chan_signer(&self, reader: &[u8]) -> Result<Self::Signer, DecodeError> {
+		self.inner.read_chan_signer(reader)
+	}
+
+	fn sign_invoice(&self, hrp_bytes: &[u8], invoice_data: &[u5]) -> Result<RecoverableSignature, ()> {
+		let preimage = construct_invoice_preimage(&hrp_bytes, &invoice_data);
+		Ok(self.inner.secp_ctx.sign_recoverable(&hash_to_message!(&Sha256::hash(&preimage)), &self.get_node_secret()))
+	}
+}
+
+impl PhantomKeysManager {
+	/// Constructs a `PhantomKeysManager` given a 32-byte seed and an additional `cross_node_seed`
+	/// that is shared across all nodes that intend to participate in [phantom node payments] together.
+	///
+	/// See [`KeysManager::new`] for more information on `seed`, `starting_time_secs`, and
+	/// `starting_time_nanos`.
+	///
+	/// `cross_node_seed` must be the same across all phantom payment-receiving nodes and also the
+	/// same across restarts, or else inbound payments may fail.
+	///
+	/// [phantom node payments]: PhantomKeysManager
+	pub fn new(seed: &[u8; 32], starting_time_secs: u64, starting_time_nanos: u32, cross_node_seed: &[u8; 32]) -> Self {
+		let inner = KeysManager::new(seed, starting_time_secs, starting_time_nanos);
+		let (inbound_key, phantom_key) = hkdf_extract_expand_twice(b"LDK Inbound and Phantom Payment Key Expansion", cross_node_seed);
+		Self {
+			inner,
+			inbound_payment_key: KeyMaterial(inbound_key),
+			phantom_secret: SecretKey::from_slice(&phantom_key).unwrap(),
+		}
+	}
+
+	/// See [`KeysManager::spend_spendable_outputs`] for documentation on this method.
+	pub fn spend_spendable_outputs<C: Signing>(&self, descriptors: &[&SpendableOutputDescriptor], outputs: Vec<TxOut>, change_destination_script: Script, feerate_sat_per_1000_weight: u32, secp_ctx: &Secp256k1<C>) -> Result<Transaction, ()> {
+		self.inner.spend_spendable_outputs(descriptors, outputs, change_destination_script, feerate_sat_per_1000_weight, secp_ctx)
+	}
+
+	/// See [`KeysManager::derive_channel_keys`] for documentation on this method.
+	pub fn derive_channel_keys(&self, channel_value_satoshis: u64, params: &[u8; 32]) -> InMemorySigner {
+		self.inner.derive_channel_keys(channel_value_satoshis, params)
+	}
+}
+
 // Ensure that BaseSign can have a vtable
 #[test]
 pub fn dyn_sign() {