1 // This file is Copyright its original authors, visible in version control
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
10 //! Keys used to generate commitment transactions.
11 //! See: <https://github.com/lightning/bolts/blob/master/03-transactions.md#keys>
13 use bitcoin::hashes::Hash;
14 use bitcoin::hashes::HashEngine;
15 use bitcoin::secp256k1::Scalar;
16 use bitcoin::secp256k1::SecretKey;
17 use bitcoin::secp256k1::Secp256k1;
18 use bitcoin::secp256k1;
19 use crate::ln::msgs::DecodeError;
20 use crate::util::ser::Readable;
22 use crate::util::ser::Writer;
23 use crate::util::ser::Writeable;
24 use bitcoin::secp256k1::PublicKey;
25 use bitcoin::hashes::sha256::Hash as Sha256;
27 macro_rules! doc_comment {
28 ($x:expr, $($tt:tt)*) => {
33 macro_rules! basepoint_impl {
36 /// Get inner Public Key
37 pub fn to_public_key(&self) -> PublicKey {
42 impl From<PublicKey> for $BasepointT {
43 fn from(value: PublicKey) -> Self {
50 macro_rules! key_impl {
51 ($BasepointT:ty, $KeyName:expr) => {
53 concat!("Generate ", $KeyName, " using per_commitment_point"),
54 pub fn from_basepoint<T: secp256k1::Signing>(
55 secp_ctx: &Secp256k1<T>,
56 basepoint: &$BasepointT,
57 per_commitment_point: &PublicKey,
59 Self(derive_public_key(secp_ctx, per_commitment_point, &basepoint.0))
64 concat!("Generate ", $KeyName, " from privkey"),
65 pub fn from_secret_key<T: secp256k1::Signing>(secp_ctx: &Secp256k1<T>, sk: &SecretKey) -> Self {
66 Self(PublicKey::from_secret_key(&secp_ctx, &sk))
70 /// Get inner Public Key
71 pub fn to_public_key(&self) -> PublicKey {
76 macro_rules! key_read_write {
78 impl Writeable for $SelfT {
79 fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
80 self.0.serialize().write(w)
84 impl Readable for $SelfT {
85 fn read<R: io::Read>(r: &mut R) -> Result<Self, DecodeError> {
86 let key: PublicKey = Readable::read(r)?;
95 /// Master key used in conjunction with per_commitment_point to generate [`local_delayedpubkey`](https://github.com/lightning/bolts/blob/master/03-transactions.md#key-derivation) for the latest state of a channel.
96 /// A watcher can be given a [DelayedPaymentBasepoint] to generate per commitment [DelayedPaymentKey] to create justice transactions.
97 #[derive(PartialEq, Eq, Clone, Copy, Debug, Hash)]
98 pub struct DelayedPaymentBasepoint(pub PublicKey);
99 basepoint_impl!(DelayedPaymentBasepoint);
100 key_read_write!(DelayedPaymentBasepoint);
102 /// [delayedpubkey](https://github.com/lightning/bolts/blob/master/03-transactions.md#localpubkey-local_htlcpubkey-remote_htlcpubkey-local_delayedpubkey-and-remote_delayedpubkey-derivation)
103 /// To allow a counterparty to contest a channel state published by a node, Lightning protocol sets delays for some of the outputs, before can be spend.
104 /// For example a commitment transaction has to_local output encumbered by a delay, negotiated at the channel establishment flow.
105 /// To spend from such output a node has to generate a script using, among others, a local delayed payment key.
106 #[derive(PartialEq, Eq, Clone, Copy, Debug)]
107 pub struct DelayedPaymentKey(pub PublicKey);
109 impl DelayedPaymentKey {
110 key_impl!(DelayedPaymentBasepoint, "delayedpubkey");
112 key_read_write!(DelayedPaymentKey);
114 /// Master key used in conjunction with per_commitment_point to generate a [localpubkey](https://github.com/lightning/bolts/blob/master/03-transactions.md#key-derivation) for the latest state of a channel.
115 /// Also used to generate a commitment number in a commitment transaction or as a Payment Key for a remote node (not us) in an anchor output if `option_static_remotekey` is enabled.
116 /// Shared by both nodes in a channel establishment message flow.
117 #[derive(PartialEq, Eq, Clone, Copy, Debug, Hash)]
118 pub struct PaymentBasepoint(pub PublicKey);
119 basepoint_impl!(PaymentBasepoint);
120 key_read_write!(PaymentBasepoint);
123 /// [localpubkey](https://github.com/lightning/bolts/blob/master/03-transactions.md#localpubkey-local_htlcpubkey-remote_htlcpubkey-local_delayedpubkey-and-remote_delayedpubkey-derivation) is a child key of a payment basepoint,
124 /// that enables a secure hash-lock for off-chain payments without risk of funds getting stuck or stolen. A payment key is normally shared with a counterparty so that it can generate
125 /// a commitment transaction's to_remote ouput, which our node can claim in case the counterparty force closes the channel.
126 #[derive(PartialEq, Eq, Clone, Copy, Debug)]
127 pub struct PaymentKey(pub PublicKey);
130 key_impl!(PaymentBasepoint, "localpubkey");
132 key_read_write!(PaymentKey);
134 /// Master key used in conjunction with per_commitment_point to generate [htlcpubkey](https://github.com/lightning/bolts/blob/master/03-transactions.md#key-derivation) for the latest state of a channel.
135 #[derive(PartialEq, Eq, Clone, Copy, Debug, Hash)]
136 pub struct HtlcBasepoint(pub PublicKey);
137 basepoint_impl!(HtlcBasepoint);
138 key_read_write!(HtlcBasepoint);
141 /// [htlcpubkey](https://github.com/lightning/bolts/blob/master/03-transactions.md#localpubkey-local_htlcpubkey-remote_htlcpubkey-local_delayedpubkey-and-remote_delayedpubkey-derivation) is a child key of an htlc basepoint,
142 /// that enables secure routing of payments in onion scheme without a risk of them getting stuck or diverted. It is used to claim the funds in successful or timed out htlc outputs.
143 #[derive(PartialEq, Eq, Clone, Copy, Debug)]
144 pub struct HtlcKey(pub PublicKey);
147 key_impl!(HtlcBasepoint, "htlcpubkey");
149 key_read_write!(HtlcKey);
151 /// Derives a per-commitment-transaction public key (eg an htlc key or a delayed_payment key)
152 /// from the base point and the per_commitment_key. This is the public equivalent of
153 /// derive_private_key - using only public keys to derive a public key instead of private keys.
154 fn derive_public_key<T: secp256k1::Signing>(secp_ctx: &Secp256k1<T>, per_commitment_point: &PublicKey, base_point: &PublicKey) -> PublicKey {
155 let mut sha = Sha256::engine();
156 sha.input(&per_commitment_point.serialize());
157 sha.input(&base_point.serialize());
158 let res = Sha256::from_engine(sha).to_byte_array();
161 let hashkey = PublicKey::from_secret_key(&secp_ctx,
162 &SecretKey::from_slice(&res).expect("Hashes should always be valid keys unless SHA-256 is broken"));
163 base_point.combine(&hashkey)
164 .expect("Addition only fails if the tweak is the inverse of the key. This is not possible when the tweak contains the hash of the key.")
167 /// Master key used in conjunction with per_commitment_point to generate [htlcpubkey](https://github.com/lightning/bolts/blob/master/03-transactions.md#key-derivation) for the latest state of a channel.
168 /// A watcher can be given a [RevocationBasepoint] to generate per commitment [RevocationKey] to create justice transactions.
169 #[derive(PartialEq, Eq, Clone, Copy, Debug, Hash)]
170 pub struct RevocationBasepoint(pub PublicKey);
171 basepoint_impl!(RevocationBasepoint);
172 key_read_write!(RevocationBasepoint);
175 /// [htlcpubkey](https://github.com/lightning/bolts/blob/master/03-transactions.md#localpubkey-local_htlcpubkey-remote_htlcpubkey-local_delayedpubkey-and-remote_delayedpubkey-derivation) is a child key of a revocation basepoint,
176 /// that enables a node to create a justice transaction punishing a counterparty for an attempt to steal funds. Used to in generation of commitment and htlc outputs.
177 #[derive(PartialEq, Eq, Clone, Copy, Debug, Hash)]
178 pub struct RevocationKey(pub PublicKey);
181 /// Derives a per-commitment-transaction revocation public key from its constituent parts. This is
182 /// the public equivalend of derive_private_revocation_key - using only public keys to derive a
183 /// public key instead of private keys.
185 /// Only the cheating participant owns a valid witness to propagate a revoked
186 /// commitment transaction, thus per_commitment_point always come from cheater
187 /// and revocation_base_point always come from punisher, which is the broadcaster
188 /// of the transaction spending with this key knowledge.
190 /// Note that this is infallible iff we trust that at least one of the two input keys are randomly
191 /// generated (ie our own).
192 pub fn from_basepoint<T: secp256k1::Verification>(
193 secp_ctx: &Secp256k1<T>,
194 basepoint: &RevocationBasepoint,
195 per_commitment_point: &PublicKey,
197 let rev_append_commit_hash_key = {
198 let mut sha = Sha256::engine();
199 sha.input(&basepoint.to_public_key().serialize());
200 sha.input(&per_commitment_point.serialize());
202 Sha256::from_engine(sha).to_byte_array()
204 let commit_append_rev_hash_key = {
205 let mut sha = Sha256::engine();
206 sha.input(&per_commitment_point.serialize());
207 sha.input(&basepoint.to_public_key().serialize());
209 Sha256::from_engine(sha).to_byte_array()
212 let countersignatory_contrib = basepoint.to_public_key().mul_tweak(&secp_ctx, &Scalar::from_be_bytes(rev_append_commit_hash_key).unwrap())
213 .expect("Multiplying a valid public key by a hash is expected to never fail per secp256k1 docs");
214 let broadcaster_contrib = (&per_commitment_point).mul_tweak(&secp_ctx, &Scalar::from_be_bytes(commit_append_rev_hash_key).unwrap())
215 .expect("Multiplying a valid public key by a hash is expected to never fail per secp256k1 docs");
216 let pk = countersignatory_contrib.combine(&broadcaster_contrib)
217 .expect("Addition only fails if the tweak is the inverse of the key. This is not possible when the tweak commits to the key.");
221 /// Get inner Public Key
222 pub fn to_public_key(&self) -> PublicKey {
226 key_read_write!(RevocationKey);
232 use bitcoin::secp256k1::{Secp256k1, SecretKey, PublicKey};
233 use bitcoin::hashes::hex::FromHex;
234 use super::derive_public_key;
237 fn test_key_derivation() {
238 // Test vectors from BOLT 3 Appendix E:
239 let secp_ctx = Secp256k1::new();
241 let base_secret = SecretKey::from_slice(&<Vec<u8>>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f").unwrap()[..]).unwrap();
242 let per_commitment_secret = SecretKey::from_slice(&<Vec<u8>>::from_hex("1f1e1d1c1b1a191817161514131211100f0e0d0c0b0a09080706050403020100").unwrap()[..]).unwrap();
244 let base_point = PublicKey::from_secret_key(&secp_ctx, &base_secret);
245 assert_eq!(base_point.serialize()[..], <Vec<u8>>::from_hex("036d6caac248af96f6afa7f904f550253a0f3ef3f5aa2fe6838a95b216691468e2").unwrap()[..]);
247 let per_commitment_point = PublicKey::from_secret_key(&secp_ctx, &per_commitment_secret);
248 assert_eq!(per_commitment_point.serialize()[..], <Vec<u8>>::from_hex("025f7117a78150fe2ef97db7cfc83bd57b2e2c0d0dd25eaf467a4a1c2a45ce1486").unwrap()[..]);
250 assert_eq!(derive_public_key(&secp_ctx, &per_commitment_point, &base_point).serialize()[..],
251 <Vec<u8>>::from_hex("0235f2dbfaa89b57ec7b055afe29849ef7ddfeb1cefdb9ebdc43f5494984db29e5").unwrap()[..]);