Module chan_utils

Various utilities for building scripts related to channels. These are largely of interest for those implementing the traits on crate::sign by hand.

Structs

BuiltCommitmentTransaction

A pre-built Bitcoin commitment transaction and its txid.

ChannelPublicKeys

One counterparty’s public keys which do not change over the life of a channel.

ChannelTransactionParameters

Per-channel data used to build transactions in conjunction with the per-commitment data (CommitmentTransaction). The fields are organized by holder/counterparty.

ClosingTransaction

This class tracks the per-transaction information needed to build a closing transaction and will actually build it and sign.

CommitmentTransaction

This class tracks the per-transaction information needed to build a commitment transaction and will actually build it and sign. It is used for holder transactions that we sign only when needed and for transactions we sign for the counterparty.

CounterpartyChannelTransactionParameters

Late-bound per-channel counterparty data used to build transactions.

CounterpartyCommitmentSecrets

Implements the per-commitment secret storage scheme from BOLT 3.

DirectedChannelTransactionParameters

Static channel fields used to build transactions given per-commitment fields, organized by broadcaster/countersignatory.

HTLCOutputInCommitment

Information about an HTLC as it appears in a commitment transaction

HolderCommitmentTransaction

Information needed to build and sign a holder’s commitment transaction.

TrustedClosingTransaction

A wrapper on ClosingTransaction indicating that the built bitcoin transaction is trusted.

TrustedCommitmentTransaction

A wrapper on CommitmentTransaction indicating that the derived fields (the built bitcoin transaction and the transaction creation keys) are trusted.

TxCreationKeys

The set of public keys which are used in the creation of one commitment transaction. These are derived from the channel base keys and per-commitment data.

Enums

HTLCClaim

Describes the type of HTLC claim as determined by analyzing the witness.

Constants

ANCHOR_INPUT_WITNESS_WEIGHT

The upper bound weight of an anchor input.

EMPTY_WITNESS_WEIGHT

The weight of an empty witness; used to spend a P2A output.

FUNDING_TRANSACTION_WITNESS_WEIGHT

The weight of a funding transaction input (2-of-2 P2WSH).

HTLC_SUCCESS_INPUT_KEYED_ANCHOR_WITNESS_WEIGHT

The upper bound weight of an HTLC success input from a commitment transaction with keyed anchor outputs.

HTLC_SUCCESS_INPUT_P2A_ANCHOR_WITNESS_WEIGHT

The upper bound weight of an HTLC success input from a commitment transaction with a p2a anchor output. Note the corresponding outputs no longer have the 1 CSV lock.

HTLC_TIMEOUT_INPUT_KEYED_ANCHOR_WITNESS_WEIGHT

The upper bound weight of an HTLC timeout input from a commitment transaction with keyed anchor outputs.

HTLC_TIMEOUT_INPUT_P2A_ANCHOR_WITNESS_WEIGHT

The upper bound weight of an HTLC timeout input from a commitment transaction with a p2a anchor output. Note the corresponding outputs no longer have the 1 CSV lock.

MAX_ACCEPTED_HTLC_SCRIPT_WEIGHT

The weight of a BIP141 witnessScript for a BOLT3’s “received HTLC output” can vary in function of its CLTV argument value. We define a range that encompasses both its non-anchors and anchors variants. This is the maximum post-anchor value.

OFFERED_HTLC_SCRIPT_WEIGHT

The weight of a BIP141 witnessScript for a BOLT3’s “offered HTLC output” on a commitment transaction, non-anchor and p2a anchor variant.

OFFERED_HTLC_SCRIPT_WEIGHT_KEYED_ANCHORS

The weight of a BIP141 witnessScript for a BOLT3’s “offered HTLC output” on a commitment transaction, keyed anchor variant.

P2A_MAX_VALUE

The maximum value of a P2A anchor.

REVOKEABLE_REDEEMSCRIPT_MAX_LENGTH

The maximum length of a script returned by get_revokeable_redeemscript.

TRUC_CHILD_MAX_WEIGHT

The maximum weight of a TRUC transaction with an unconfirmed TRUC ancestor, see BIP431.

TRUC_MAX_WEIGHT

The maximum weight of a TRUC transaction, see BIP431.

Functions

aggregated_htlc_success_input_output_pair_weight

Gets the weight of a single input-output pair in externally funded HTLC-success transactions

aggregated_htlc_timeout_input_output_pair_weight

Gets the weight of a single input-output pair in externally funded HTLC-timeout transactions

build_closing_transaction

Build a closing transaction

build_commitment_secret

Build the commitment secret from the seed and the commitment number

build_htlc_input_witness

Returns the witness required to satisfy and spend a HTLC input.

build_htlc_transaction

Builds an unsigned HTLC-Success or HTLC-Timeout transaction from the given channel and HTLC parameters. This is used by TrustedCommitmentTransaction::get_htlc_sigs to fetch the transaction which needs signing, and can be used to construct an HTLC transaction which is broadcastable given a counterparty HTLC signature.

build_keyed_anchor_input_witness

Returns the witness required to satisfy and spend a keyed anchor (non-zero-fee-commitments) input.

derive_private_key

Derives a per-commitment-transaction private key (eg an htlc key or delayed_payment key) from the base secret and the per_commitment_point.

derive_private_revocation_key

Derives a per-commitment-transaction revocation key from its constituent parts.

get_commitment_transaction_number_obscure_factor

Commitment transaction numbers which appear in the transactions themselves are XOR’d with a shared secret first. This prevents on-chain observers from discovering how many commitment transactions occurred in a channel before it was closed.

get_countersigner_payment_script

Returns the script for the countersigner’s (i.e. non-broadcaster’s) output on a commitment transaction based on the channel type.

get_htlc_redeemscript

Gets the witness redeemscript for an HTLC output in a commitment transaction. Note that htlc does not need to have its previous_output_index filled.

get_keyed_anchor_redeemscript

Gets the witnessScript for a keyed anchor (non-zero-fee-commitments) output from the funding public key.

get_revokeable_redeemscript

A script either spendable by the revocation key or the broadcaster_delayed_payment_key and satisfying the relative-locktime OP_CSV constrain. Encumbering a to_holder output on a commitment transaction or 2nd-stage HTLC transactions.

get_to_countersigner_keyed_anchor_redeemscript

Gets the witnessScript for the to_remote output when anchors are enabled.

htlc_success_tx_weight

Gets the weight for an HTLC-Success transaction.

htlc_timeout_tx_weight

Gets the weight for an HTLC-Timeout transaction.

make_funding_redeemscript

Gets the redeemscript for a funding output from the two funding public keys. Note that the order of funding public keys does not matter.

max_htlcs

Maximum number of in-flight HTLCs in each direction allowed by the lightning protocol.

shared_anchor_script_pubkey

Gets the script_pubkey for a shared anchor