1 //! Various utilities for building scripts and deriving keys related to channels. These are
2 //! largely of interest for those implementing chain::keysinterface::ChannelKeys message signing
5 use bitcoin::blockdata::script::{Script,Builder};
6 use bitcoin::blockdata::opcodes;
7 use bitcoin::blockdata::transaction::{TxIn,TxOut,OutPoint,Transaction, SigHashType};
8 use bitcoin::consensus::encode::{self, Decodable, Encodable};
9 use bitcoin::util::bip143;
11 use bitcoin_hashes::{Hash, HashEngine};
12 use bitcoin_hashes::sha256::Hash as Sha256;
13 use bitcoin_hashes::ripemd160::Hash as Ripemd160;
14 use bitcoin_hashes::hash160::Hash as Hash160;
15 use bitcoin_hashes::sha256d::Hash as Sha256dHash;
17 use ln::channelmanager::{PaymentHash, PaymentPreimage};
18 use ln::msgs::DecodeError;
19 use util::ser::{Readable, Writeable, Writer, WriterWriteAdaptor};
21 use secp256k1::key::{SecretKey,PublicKey};
22 use secp256k1::{Secp256k1, Signature};
25 pub(super) const HTLC_SUCCESS_TX_WEIGHT: u64 = 703;
26 pub(super) const HTLC_TIMEOUT_TX_WEIGHT: u64 = 663;
28 // Various functions for key derivation and transaction creation for use within channels. Primarily
29 // used in Channel and ChannelMonitor.
31 pub(super) fn build_commitment_secret(commitment_seed: &[u8; 32], idx: u64) -> [u8; 32] {
32 let mut res: [u8; 32] = commitment_seed.clone();
35 if idx & (1 << bitpos) == (1 << bitpos) {
36 res[bitpos / 8] ^= 1 << (bitpos & 7);
37 res = Sha256::hash(&res).into_inner();
43 /// Derives a per-commitment-transaction private key (eg an htlc key or payment key) from the base
44 /// private key for that type of key and the per_commitment_point (available in TxCreationKeys)
45 pub fn derive_private_key<T: secp256k1::Signing>(secp_ctx: &Secp256k1<T>, per_commitment_point: &PublicKey, base_secret: &SecretKey) -> Result<SecretKey, secp256k1::Error> {
46 let mut sha = Sha256::engine();
47 sha.input(&per_commitment_point.serialize());
48 sha.input(&PublicKey::from_secret_key(&secp_ctx, &base_secret).serialize());
49 let res = Sha256::from_engine(sha).into_inner();
51 let mut key = base_secret.clone();
52 key.add_assign(&res)?;
56 pub(super) fn derive_public_key<T: secp256k1::Signing>(secp_ctx: &Secp256k1<T>, per_commitment_point: &PublicKey, base_point: &PublicKey) -> Result<PublicKey, secp256k1::Error> {
57 let mut sha = Sha256::engine();
58 sha.input(&per_commitment_point.serialize());
59 sha.input(&base_point.serialize());
60 let res = Sha256::from_engine(sha).into_inner();
62 let hashkey = PublicKey::from_secret_key(&secp_ctx, &SecretKey::from_slice(&res)?);
63 base_point.combine(&hashkey)
66 /// Derives a revocation key from its constituent parts.
67 /// Note that this is infallible iff we trust that at least one of the two input keys are randomly
68 /// generated (ie our own).
69 pub(super) fn derive_private_revocation_key<T: secp256k1::Signing>(secp_ctx: &Secp256k1<T>, per_commitment_secret: &SecretKey, revocation_base_secret: &SecretKey) -> Result<SecretKey, secp256k1::Error> {
70 let revocation_base_point = PublicKey::from_secret_key(&secp_ctx, &revocation_base_secret);
71 let per_commitment_point = PublicKey::from_secret_key(&secp_ctx, &per_commitment_secret);
73 let rev_append_commit_hash_key = {
74 let mut sha = Sha256::engine();
75 sha.input(&revocation_base_point.serialize());
76 sha.input(&per_commitment_point.serialize());
78 Sha256::from_engine(sha).into_inner()
80 let commit_append_rev_hash_key = {
81 let mut sha = Sha256::engine();
82 sha.input(&per_commitment_point.serialize());
83 sha.input(&revocation_base_point.serialize());
85 Sha256::from_engine(sha).into_inner()
88 let mut part_a = revocation_base_secret.clone();
89 part_a.mul_assign(&rev_append_commit_hash_key)?;
90 let mut part_b = per_commitment_secret.clone();
91 part_b.mul_assign(&commit_append_rev_hash_key)?;
92 part_a.add_assign(&part_b[..])?;
96 pub(super) fn derive_public_revocation_key<T: secp256k1::Verification>(secp_ctx: &Secp256k1<T>, per_commitment_point: &PublicKey, revocation_base_point: &PublicKey) -> Result<PublicKey, secp256k1::Error> {
97 let rev_append_commit_hash_key = {
98 let mut sha = Sha256::engine();
99 sha.input(&revocation_base_point.serialize());
100 sha.input(&per_commitment_point.serialize());
102 Sha256::from_engine(sha).into_inner()
104 let commit_append_rev_hash_key = {
105 let mut sha = Sha256::engine();
106 sha.input(&per_commitment_point.serialize());
107 sha.input(&revocation_base_point.serialize());
109 Sha256::from_engine(sha).into_inner()
112 let mut part_a = revocation_base_point.clone();
113 part_a.mul_assign(&secp_ctx, &rev_append_commit_hash_key)?;
114 let mut part_b = per_commitment_point.clone();
115 part_b.mul_assign(&secp_ctx, &commit_append_rev_hash_key)?;
116 part_a.combine(&part_b)
119 /// The set of public keys which are used in the creation of one commitment transaction.
120 /// These are derived from the channel base keys and per-commitment data.
121 pub struct TxCreationKeys {
122 /// The per-commitment public key which was used to derive the other keys.
123 pub per_commitment_point: PublicKey,
124 /// The revocation key which is used to allow the owner of the commitment transaction to
125 /// provide their counterparty the ability to punish them if they broadcast an old state.
126 pub revocation_key: PublicKey,
128 pub a_htlc_key: PublicKey,
130 pub b_htlc_key: PublicKey,
131 /// A's Payment Key (which isn't allowed to be spent from for some delay)
132 pub a_delayed_payment_key: PublicKey,
134 pub b_payment_key: PublicKey,
137 impl TxCreationKeys {
138 pub(super) fn new<T: secp256k1::Signing + secp256k1::Verification>(secp_ctx: &Secp256k1<T>, per_commitment_point: &PublicKey, a_delayed_payment_base: &PublicKey, a_htlc_base: &PublicKey, b_revocation_base: &PublicKey, b_payment_base: &PublicKey, b_htlc_base: &PublicKey) -> Result<TxCreationKeys, secp256k1::Error> {
140 per_commitment_point: per_commitment_point.clone(),
141 revocation_key: derive_public_revocation_key(&secp_ctx, &per_commitment_point, &b_revocation_base)?,
142 a_htlc_key: derive_public_key(&secp_ctx, &per_commitment_point, &a_htlc_base)?,
143 b_htlc_key: derive_public_key(&secp_ctx, &per_commitment_point, &b_htlc_base)?,
144 a_delayed_payment_key: derive_public_key(&secp_ctx, &per_commitment_point, &a_delayed_payment_base)?,
145 b_payment_key: derive_public_key(&secp_ctx, &per_commitment_point, &b_payment_base)?,
150 /// Gets the "to_local" output redeemscript, ie the script which is time-locked or spendable by
151 /// the revocation key
152 pub(super) fn get_revokeable_redeemscript(revocation_key: &PublicKey, to_self_delay: u16, delayed_payment_key: &PublicKey) -> Script {
153 Builder::new().push_opcode(opcodes::all::OP_IF)
154 .push_slice(&revocation_key.serialize())
155 .push_opcode(opcodes::all::OP_ELSE)
156 .push_int(to_self_delay as i64)
157 .push_opcode(opcodes::all::OP_CSV)
158 .push_opcode(opcodes::all::OP_DROP)
159 .push_slice(&delayed_payment_key.serialize())
160 .push_opcode(opcodes::all::OP_ENDIF)
161 .push_opcode(opcodes::all::OP_CHECKSIG)
165 #[derive(Clone, PartialEq)]
166 /// Information about an HTLC as it appears in a commitment transaction
167 pub struct HTLCOutputInCommitment {
168 /// Whether the HTLC was "offered" (ie outbound in relation to this commitment transaction).
169 /// Note that this is not the same as whether it is ountbound *from us*. To determine that you
170 /// need to compare this value to whether the commitment transaction in question is that of
171 /// the remote party or our own.
173 /// The value, in msat, of the HTLC. The value as it appears in the commitment transaction is
174 /// this divided by 1000.
175 pub amount_msat: u64,
176 /// The CLTV lock-time at which this HTLC expires.
177 pub cltv_expiry: u32,
178 /// The hash of the preimage which unlocks this HTLC.
179 pub payment_hash: PaymentHash,
180 /// The position within the commitment transactions' outputs. This may be None if the value is
181 /// below the dust limit (in which case no output appears in the commitment transaction and the
182 /// value is spent to additional transaction fees).
183 pub transaction_output_index: Option<u32>,
187 pub(super) fn get_htlc_redeemscript_with_explicit_keys(htlc: &HTLCOutputInCommitment, a_htlc_key: &PublicKey, b_htlc_key: &PublicKey, revocation_key: &PublicKey) -> Script {
188 let payment_hash160 = Ripemd160::hash(&htlc.payment_hash.0[..]).into_inner();
190 Builder::new().push_opcode(opcodes::all::OP_DUP)
191 .push_opcode(opcodes::all::OP_HASH160)
192 .push_slice(&Hash160::hash(&revocation_key.serialize())[..])
193 .push_opcode(opcodes::all::OP_EQUAL)
194 .push_opcode(opcodes::all::OP_IF)
195 .push_opcode(opcodes::all::OP_CHECKSIG)
196 .push_opcode(opcodes::all::OP_ELSE)
197 .push_slice(&b_htlc_key.serialize()[..])
198 .push_opcode(opcodes::all::OP_SWAP)
199 .push_opcode(opcodes::all::OP_SIZE)
201 .push_opcode(opcodes::all::OP_EQUAL)
202 .push_opcode(opcodes::all::OP_NOTIF)
203 .push_opcode(opcodes::all::OP_DROP)
205 .push_opcode(opcodes::all::OP_SWAP)
206 .push_slice(&a_htlc_key.serialize()[..])
208 .push_opcode(opcodes::all::OP_CHECKMULTISIG)
209 .push_opcode(opcodes::all::OP_ELSE)
210 .push_opcode(opcodes::all::OP_HASH160)
211 .push_slice(&payment_hash160)
212 .push_opcode(opcodes::all::OP_EQUALVERIFY)
213 .push_opcode(opcodes::all::OP_CHECKSIG)
214 .push_opcode(opcodes::all::OP_ENDIF)
215 .push_opcode(opcodes::all::OP_ENDIF)
218 Builder::new().push_opcode(opcodes::all::OP_DUP)
219 .push_opcode(opcodes::all::OP_HASH160)
220 .push_slice(&Hash160::hash(&revocation_key.serialize())[..])
221 .push_opcode(opcodes::all::OP_EQUAL)
222 .push_opcode(opcodes::all::OP_IF)
223 .push_opcode(opcodes::all::OP_CHECKSIG)
224 .push_opcode(opcodes::all::OP_ELSE)
225 .push_slice(&b_htlc_key.serialize()[..])
226 .push_opcode(opcodes::all::OP_SWAP)
227 .push_opcode(opcodes::all::OP_SIZE)
229 .push_opcode(opcodes::all::OP_EQUAL)
230 .push_opcode(opcodes::all::OP_IF)
231 .push_opcode(opcodes::all::OP_HASH160)
232 .push_slice(&payment_hash160)
233 .push_opcode(opcodes::all::OP_EQUALVERIFY)
235 .push_opcode(opcodes::all::OP_SWAP)
236 .push_slice(&a_htlc_key.serialize()[..])
238 .push_opcode(opcodes::all::OP_CHECKMULTISIG)
239 .push_opcode(opcodes::all::OP_ELSE)
240 .push_opcode(opcodes::all::OP_DROP)
241 .push_int(htlc.cltv_expiry as i64)
242 .push_opcode(opcodes::all::OP_CLTV)
243 .push_opcode(opcodes::all::OP_DROP)
244 .push_opcode(opcodes::all::OP_CHECKSIG)
245 .push_opcode(opcodes::all::OP_ENDIF)
246 .push_opcode(opcodes::all::OP_ENDIF)
251 /// note here that 'a_revocation_key' is generated using b_revocation_basepoint and a's
252 /// commitment secret. 'htlc' does *not* need to have its previous_output_index filled.
254 pub fn get_htlc_redeemscript(htlc: &HTLCOutputInCommitment, keys: &TxCreationKeys) -> Script {
255 get_htlc_redeemscript_with_explicit_keys(htlc, &keys.a_htlc_key, &keys.b_htlc_key, &keys.revocation_key)
258 /// Gets the redeemscript for a funding output from the two funding public keys.
259 /// Note that the order of funding public keys does not matter.
260 pub fn make_funding_redeemscript(a: &PublicKey, b: &PublicKey) -> Script {
261 let our_funding_key = a.serialize();
262 let their_funding_key = b.serialize();
264 let builder = Builder::new().push_opcode(opcodes::all::OP_PUSHNUM_2);
265 if our_funding_key[..] < their_funding_key[..] {
266 builder.push_slice(&our_funding_key)
267 .push_slice(&their_funding_key)
269 builder.push_slice(&their_funding_key)
270 .push_slice(&our_funding_key)
271 }.push_opcode(opcodes::all::OP_PUSHNUM_2).push_opcode(opcodes::all::OP_CHECKMULTISIG).into_script()
274 /// panics if htlc.transaction_output_index.is_none()!
275 pub fn build_htlc_transaction(prev_hash: &Sha256dHash, feerate_per_kw: u64, to_self_delay: u16, htlc: &HTLCOutputInCommitment, a_delayed_payment_key: &PublicKey, revocation_key: &PublicKey) -> Transaction {
276 let mut txins: Vec<TxIn> = Vec::new();
278 previous_output: OutPoint {
279 txid: prev_hash.clone(),
280 vout: htlc.transaction_output_index.expect("Can't build an HTLC transaction for a dust output"),
282 script_sig: Script::new(),
287 let total_fee = if htlc.offered {
288 feerate_per_kw * HTLC_TIMEOUT_TX_WEIGHT / 1000
290 feerate_per_kw * HTLC_SUCCESS_TX_WEIGHT / 1000
293 let mut txouts: Vec<TxOut> = Vec::new();
295 script_pubkey: get_revokeable_redeemscript(revocation_key, to_self_delay, a_delayed_payment_key).to_v0_p2wsh(),
296 value: htlc.amount_msat / 1000 - total_fee //TODO: BOLT 3 does not specify if we should add amount_msat before dividing or if we should divide by 1000 before subtracting (as we do here)
301 lock_time: if htlc.offered { htlc.cltv_expiry } else { 0 },
307 /// Signs a transaction created by build_htlc_transaction. If the transaction is an
308 /// HTLC-Success transaction (ie htlc.offered is false), preimage must be set!
309 pub(crate) fn sign_htlc_transaction<T: secp256k1::Signing>(tx: &mut Transaction, their_sig: &Signature, preimage: &Option<PaymentPreimage>, htlc: &HTLCOutputInCommitment, a_htlc_key: &PublicKey, b_htlc_key: &PublicKey, revocation_key: &PublicKey, per_commitment_point: &PublicKey, htlc_base_key: &SecretKey, secp_ctx: &Secp256k1<T>) -> Result<(Signature, Script), ()> {
310 if tx.input.len() != 1 { return Err(()); }
311 if tx.input[0].witness.len() != 0 { return Err(()); }
313 let htlc_redeemscript = get_htlc_redeemscript_with_explicit_keys(&htlc, a_htlc_key, b_htlc_key, revocation_key);
315 let our_htlc_key = derive_private_key(secp_ctx, per_commitment_point, htlc_base_key).map_err(|_| ())?;
316 let sighash = hash_to_message!(&bip143::SighashComponents::new(&tx).sighash_all(&tx.input[0], &htlc_redeemscript, htlc.amount_msat / 1000)[..]);
317 let local_tx = PublicKey::from_secret_key(&secp_ctx, &our_htlc_key) == *a_htlc_key;
318 let our_sig = secp_ctx.sign(&sighash, &our_htlc_key);
320 tx.input[0].witness.push(Vec::new()); // First is the multisig dummy
322 if local_tx { // b, then a
323 tx.input[0].witness.push(their_sig.serialize_der().to_vec());
324 tx.input[0].witness.push(our_sig.serialize_der().to_vec());
326 tx.input[0].witness.push(our_sig.serialize_der().to_vec());
327 tx.input[0].witness.push(their_sig.serialize_der().to_vec());
329 tx.input[0].witness[1].push(SigHashType::All as u8);
330 tx.input[0].witness[2].push(SigHashType::All as u8);
333 tx.input[0].witness.push(Vec::new());
334 assert!(preimage.is_none());
336 tx.input[0].witness.push(preimage.unwrap().0.to_vec());
339 tx.input[0].witness.push(htlc_redeemscript.as_bytes().to_vec());
341 Ok((our_sig, htlc_redeemscript))
345 /// We use this to track local commitment transactions and put off signing them until we are ready
346 /// to broadcast. Eventually this will require a signer which is possibly external, but for now we
347 /// just pass in the SecretKeys required.
348 pub(crate) struct LocalCommitmentTransaction {
351 impl LocalCommitmentTransaction {
353 pub fn dummy() -> Self {
354 Self { tx: Transaction {
362 pub fn new_missing_local_sig(mut tx: Transaction, their_sig: &Signature, our_funding_key: &PublicKey, their_funding_key: &PublicKey) -> LocalCommitmentTransaction {
363 if tx.input.len() != 1 { panic!("Tried to store a commitment transaction that had input count != 1!"); }
364 if tx.input[0].witness.len() != 0 { panic!("Tried to store a signed commitment transaction?"); }
366 tx.input[0].witness.push(Vec::new()); // First is the multisig dummy
368 if our_funding_key.serialize()[..] < their_funding_key.serialize()[..] {
369 tx.input[0].witness.push(Vec::new());
370 tx.input[0].witness.push(their_sig.serialize_der().to_vec());
371 tx.input[0].witness[2].push(SigHashType::All as u8);
373 tx.input[0].witness.push(their_sig.serialize_der().to_vec());
374 tx.input[0].witness[1].push(SigHashType::All as u8);
375 tx.input[0].witness.push(Vec::new());
381 pub fn txid(&self) -> Sha256dHash {
385 pub fn has_local_sig(&self) -> bool {
386 if self.tx.input.len() != 1 { panic!("Commitment transactions must have input count == 1!"); }
387 if self.tx.input[0].witness.len() == 4 {
388 assert!(!self.tx.input[0].witness[1].is_empty());
389 assert!(!self.tx.input[0].witness[2].is_empty());
392 assert_eq!(self.tx.input[0].witness.len(), 3);
393 assert!(self.tx.input[0].witness[0].is_empty());
394 assert!(self.tx.input[0].witness[1].is_empty() || self.tx.input[0].witness[2].is_empty());
399 pub fn add_local_sig<T: secp256k1::Signing>(&mut self, funding_key: &SecretKey, funding_redeemscript: &Script, channel_value_satoshis: u64, secp_ctx: &Secp256k1<T>) {
400 if self.has_local_sig() { return; }
401 let sighash = hash_to_message!(&bip143::SighashComponents::new(&self.tx)
402 .sighash_all(&self.tx.input[0], funding_redeemscript, channel_value_satoshis)[..]);
403 let our_sig = secp_ctx.sign(&sighash, funding_key);
405 if self.tx.input[0].witness[1].is_empty() {
406 self.tx.input[0].witness[1] = our_sig.serialize_der().to_vec();
407 self.tx.input[0].witness[1].push(SigHashType::All as u8);
409 self.tx.input[0].witness[2] = our_sig.serialize_der().to_vec();
410 self.tx.input[0].witness[2].push(SigHashType::All as u8);
413 self.tx.input[0].witness.push(funding_redeemscript.as_bytes().to_vec());
416 pub fn without_valid_witness(&self) -> &Transaction { &self.tx }
417 pub fn with_valid_witness(&self) -> &Transaction {
418 assert!(self.has_local_sig());
422 impl PartialEq for LocalCommitmentTransaction {
423 // We dont care whether we are signed in equality comparison
424 fn eq(&self, o: &Self) -> bool {
425 self.txid() == o.txid()
428 impl Writeable for LocalCommitmentTransaction {
429 fn write<W: Writer>(&self, writer: &mut W) -> Result<(), ::std::io::Error> {
430 if let Err(e) = self.tx.consensus_encode(&mut WriterWriteAdaptor(writer)) {
432 encode::Error::Io(e) => return Err(e),
433 _ => panic!("local tx must have been well-formed!"),
439 impl<R: ::std::io::Read> Readable<R> for LocalCommitmentTransaction {
440 fn read(reader: &mut R) -> Result<Self, DecodeError> {
441 let tx = match Transaction::consensus_decode(reader.by_ref()) {
444 encode::Error::Io(ioe) => return Err(DecodeError::Io(ioe)),
445 _ => return Err(DecodeError::InvalidValue),
449 if tx.input.len() != 1 {
450 // Ensure tx didn't hit the 0-input ambiguity case.
451 return Err(DecodeError::InvalidValue);