scoin/scoin.ln.transactions/Transactions

Transactions

object Transactions
Source:
Transactions.scala
class Object
trait Matchable
class Any

Type members

Classlikes

case object AmountBelowDustLimit extends TxGenerationSkipped
object AnchorOutputsCommitmentFormat
Companion:
class
Source:
Transactions.scala
sealed trait AnchorOutputsCommitmentFormat extends CommitmentFormat

Commitment format that adds anchor outputs to the commitment transaction and uses custom sighash flags for HTLC transactions to allow unilateral fee bumping (https://github.com/lightningnetwork/lightning-rfc/pull/688).

Commitment format that adds anchor outputs to the commitment transaction and uses custom sighash flags for HTLC transactions to allow unilateral fee bumping (https://github.com/lightningnetwork/lightning-rfc/pull/688).

Companion:
object
Source:
Transactions.scala
sealed trait ClaimAnchorOutputTx extends TransactionWithInputInfo
case class ClaimHtlcDelayedOutputPenaltyTx(input: InputInfo, tx: Transaction) extends TransactionWithInputInfo
case class ClaimHtlcSuccessTx(input: InputInfo, tx: Transaction, paymentHash: ByteVector32, htlcId: Long, confirmBefore: BlockHeight) extends ClaimHtlcTx
case class ClaimHtlcTimeoutTx(input: InputInfo, tx: Transaction, htlcId: Long, confirmBefore: BlockHeight) extends ClaimHtlcTx
sealed trait ClaimHtlcTx extends ReplaceableTransactionWithInputInfo
case class ClaimLocalAnchorOutputTx(input: InputInfo, tx: Transaction, confirmBefore: BlockHeight) extends ClaimAnchorOutputTx with ReplaceableTransactionWithInputInfo
case class ClaimLocalDelayedOutputTx(input: InputInfo, tx: Transaction) extends TransactionWithInputInfo
case class ClaimP2WPKHOutputTx(input: InputInfo, tx: Transaction) extends ClaimRemoteCommitMainOutputTx
case class ClaimRemoteAnchorOutputTx(input: InputInfo, tx: Transaction) extends ClaimAnchorOutputTx
sealed trait ClaimRemoteCommitMainOutputTx extends TransactionWithInputInfo
case class ClaimRemoteDelayedOutputTx(input: InputInfo, tx: Transaction) extends ClaimRemoteCommitMainOutputTx
case class ClosingTx(input: InputInfo, tx: Transaction, toLocalOutput: Option[OutputInfo]) extends TransactionWithInputInfo
case class CommitTx(input: InputInfo, tx: Transaction) extends TransactionWithInputInfo
sealed trait CommitmentFormat
case class CommitmentOutputLink[T <: CommitmentOutput](output: TxOut, redeemScript: Seq[ScriptElt], commitmentOutput: T)

Represent a link between a commitment spec item (to-local, to-remote, anchors, htlc) and the actual output in the commit tx

Represent a link between a commitment spec item (to-local, to-remote, anchors, htlc) and the actual output in the commit tx

Value parameters:
commitmentOutput

commitment spec item this output is built from

output

transaction output

redeemScript

redeem script that matches this output (most of them are p2wsh)

Companion:
object
Source:
Transactions.scala
object CommitmentOutputLink
Companion:
class
Source:
Transactions.scala
case object DefaultCommitmentFormat extends CommitmentFormat

Commitment format as defined in the v1.0 specification (https://github.com/lightningnetwork/lightning-rfc/tree/v1.0).

Commitment format as defined in the v1.0 specification (https://github.com/lightningnetwork/lightning-rfc/tree/v1.0).

Source:
Transactions.scala
case class HtlcDelayedTx(input: InputInfo, tx: Transaction) extends TransactionWithInputInfo
case class HtlcPenaltyTx(input: InputInfo, tx: Transaction) extends TransactionWithInputInfo
case class HtlcSuccessTx(input: InputInfo, tx: Transaction, paymentHash: ByteVector32, htlcId: Long, confirmBefore: BlockHeight) extends HtlcTx
case class HtlcTimeoutTx(input: InputInfo, tx: Transaction, htlcId: Long, confirmBefore: BlockHeight) extends HtlcTx
sealed trait HtlcTx extends ReplaceableTransactionWithInputInfo

It's important to note that htlc transactions with the default commitment format are not actually replaceable: only anchor outputs htlc transactions are replaceable. We should have used different types for these different kinds of htlc transactions, but we introduced that before implementing the replacement strategy. Unfortunately, if we wanted to change that, we would have to update the codecs and implement a migration of channel data, which isn't trivial, so we chose to temporarily live with that inconsistency (and have the transaction replacement logic abort when non-anchor outputs htlc transactions are provided). Ideally, we'd like to implement a dynamic commitment format upgrade mechanism and depreciate the pre-anchor outputs format soon, which will get rid of this inconsistency. The next time we introduce a new type of commitment, we should avoid repeating that mistake and define separate types right from the start.

It's important to note that htlc transactions with the default commitment format are not actually replaceable: only anchor outputs htlc transactions are replaceable. We should have used different types for these different kinds of htlc transactions, but we introduced that before implementing the replacement strategy. Unfortunately, if we wanted to change that, we would have to update the codecs and implement a migration of channel data, which isn't trivial, so we chose to temporarily live with that inconsistency (and have the transaction replacement logic abort when non-anchor outputs htlc transactions are provided). Ideally, we'd like to implement a dynamic commitment format upgrade mechanism and depreciate the pre-anchor outputs format soon, which will get rid of this inconsistency. The next time we introduce a new type of commitment, we should avoid repeating that mistake and define separate types right from the start.

Source:
Transactions.scala
case class InputInfo(outPoint: OutPoint, txOut: TxOut, redeemScript: ByteVector)
Companion:
object
Source:
Transactions.scala
object InputInfo
Companion:
class
Source:
Transactions.scala
case class LegacyClaimHtlcSuccessTx(input: InputInfo, tx: Transaction, htlcId: Long, confirmBefore: BlockHeight) extends ClaimHtlcTx
case class MainPenaltyTx(input: InputInfo, tx: Transaction) extends TransactionWithInputInfo
case class OutputInfo(index: Long, amount: Satoshi, publicKeyScript: ByteVector)
case object OutputNotFound extends TxGenerationSkipped
sealed trait ReplaceableTransactionWithInputInfo extends TransactionWithInputInfo
sealed trait TransactionWithInputInfo
sealed trait TxGenerationSkipped
object TxOwner
Companion:
class
Source:
Transactions.scala
sealed trait TxOwner

Owner of a given transaction (local/remote).

Owner of a given transaction (local/remote).

Companion:
object
Source:
Transactions.scala
case object UnsafeLegacyAnchorOutputsCommitmentFormat extends AnchorOutputsCommitmentFormat

This commitment format may be unsafe where you're fundee, as it exposes you to a fee inflating attack. Don't use this commitment format unless you know what you're doing! See https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html for details.

This commitment format may be unsafe where you're fundee, as it exposes you to a fee inflating attack. Don't use this commitment format unless you know what you're doing! See https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html for details.

Source:
Transactions.scala
case object ZeroFeeHtlcTxAnchorOutputsCommitmentFormat extends AnchorOutputsCommitmentFormat

This commitment format removes the fees from the pre-signed 2nd-stage htlc transactions to fix the fee inflating attack against UnsafeLegacyAnchorOutputsCommitmentFormat.

This commitment format removes the fees from the pre-signed 2nd-stage htlc transactions to fix the fee inflating attack against UnsafeLegacyAnchorOutputsCommitmentFormat.

Source:
Transactions.scala

Types

type CommitmentOutputs = Seq[CommitmentOutputLink[CommitmentOutput]]

Type alias for a collection of commitment output links

Type alias for a collection of commitment output links

Source:
Transactions.scala

Value members

Concrete methods

def addSigs(commitTx: CommitTx, localFundingPubkey: PublicKey, remoteFundingPubkey: PublicKey, localSig: ByteVector64, remoteSig: ByteVector64): CommitTx
def addSigs(mainPenaltyTx: MainPenaltyTx, revocationSig: ByteVector64): MainPenaltyTx
def addSigs(htlcPenaltyTx: HtlcPenaltyTx, revocationSig: ByteVector64, revocationPubkey: PublicKey): HtlcPenaltyTx
def addSigs(htlcSuccessTx: HtlcSuccessTx, localSig: ByteVector64, remoteSig: ByteVector64, paymentPreimage: ByteVector32, commitmentFormat: CommitmentFormat): HtlcSuccessTx
def addSigs(htlcTimeoutTx: HtlcTimeoutTx, localSig: ByteVector64, remoteSig: ByteVector64, commitmentFormat: CommitmentFormat): HtlcTimeoutTx
def addSigs(claimHtlcSuccessTx: ClaimHtlcSuccessTx, localSig: ByteVector64, paymentPreimage: ByteVector32): ClaimHtlcSuccessTx
def addSigs(claimP2WPKHOutputTx: ClaimP2WPKHOutputTx, localPaymentPubkey: PublicKey, localSig: ByteVector64): ClaimP2WPKHOutputTx
def addSigs(htlcDelayedTx: HtlcDelayedTx, localSig: ByteVector64): HtlcDelayedTx
def addSigs(closingTx: ClosingTx, localFundingPubkey: PublicKey, remoteFundingPubkey: PublicKey, localSig: ByteVector64, remoteSig: ByteVector64): ClosingTx
def checkSig(txinfo: TransactionWithInputInfo, sig: ByteVector64, pubKey: PublicKey, txOwner: TxOwner, commitmentFormat: CommitmentFormat): Boolean
def commitTxFeeMsat(dustLimit: Satoshi, spec: CommitmentSpec, commitmentFormat: CommitmentFormat): MilliSatoshi

Fee paid by the commit tx (depends on which HTLCs will be trimmed).

Fee paid by the commit tx (depends on which HTLCs will be trimmed).

Source:
Transactions.scala
def commitTxTotalCost(dustLimit: Satoshi, spec: CommitmentSpec, commitmentFormat: CommitmentFormat): Satoshi
def commitTxTotalCostMsat(dustLimit: Satoshi, spec: CommitmentSpec, commitmentFormat: CommitmentFormat): MilliSatoshi

While on-chain amounts are generally computed in Satoshis (since this is the smallest on-chain unit), it may be useful in some cases to calculate it in MilliSatoshi to avoid rounding issues. If you are adding multiple fees together for example, you should always add them in MilliSatoshi and then round down to Satoshi.

While on-chain amounts are generally computed in Satoshis (since this is the smallest on-chain unit), it may be useful in some cases to calculate it in MilliSatoshi to avoid rounding issues. If you are adding multiple fees together for example, you should always add them in MilliSatoshi and then round down to Satoshi.

Source:
Transactions.scala
def decodeTxNumber(sequence: Long, locktime: Long): Long
def encodeTxNumber(txnumber: Long): (Long, Long)

This is a trick to split and encode a 48-bit txnumber into the sequence and locktime fields of a tx

This is a trick to split and encode a 48-bit txnumber into the sequence and locktime fields of a tx

Value parameters:
txnumber

commitment number

Returns:

(sequence, locktime)

Source:
Transactions.scala
def fee2rate(fee: Satoshi, weight: Int): FeeratePerKw
Value parameters:
fee

tx fee

weight

tx weight

Returns:

the fee rate (in Satoshi/Kw) for this tx

Source:
Transactions.scala
def getCommitTxNumber(commitTx: Transaction, isInitiator: Boolean, localPaymentBasePoint: PublicKey, remotePaymentBasePoint: PublicKey): Long
Value parameters:
commitTx

commit tx

isInitiator

true if local node initiated the channel open

localPaymentBasePoint

local payment base point

remotePaymentBasePoint

remote payment base point

Returns:

the actual commit tx number that was blinded and stored in locktime and sequence fields

Source:
Transactions.scala
def htlcOutputFee(feeratePerKw: FeeratePerKw, commitmentFormat: CommitmentFormat): MilliSatoshi

Fee for an un-trimmed HTLC.

Fee for an un-trimmed HTLC.

Source:
Transactions.scala
def makeClaimHtlcDelayedOutputPenaltyTxs(htlcTx: Transaction, localDustLimit: Satoshi, localRevocationPubkey: PublicKey, toLocalDelay: CltvExpiryDelta, localDelayedPaymentPubkey: PublicKey, localFinalScriptPubKey: ByteVector, feeratePerKw: FeeratePerKw): Seq[Either[TxGenerationSkipped, ClaimHtlcDelayedOutputPenaltyTx]]
def makeClaimHtlcSuccessTx(commitTx: Transaction, outputs: CommitmentOutputs, localDustLimit: Satoshi, localHtlcPubkey: PublicKey, remoteHtlcPubkey: PublicKey, remoteRevocationPubkey: PublicKey, localFinalScriptPubKey: ByteVector, htlc: UpdateAddHtlc, feeratePerKw: FeeratePerKw, commitmentFormat: CommitmentFormat): Either[TxGenerationSkipped, ClaimHtlcSuccessTx]
def makeClaimHtlcTimeoutTx(commitTx: Transaction, outputs: CommitmentOutputs, localDustLimit: Satoshi, localHtlcPubkey: PublicKey, remoteHtlcPubkey: PublicKey, remoteRevocationPubkey: PublicKey, localFinalScriptPubKey: ByteVector, htlc: UpdateAddHtlc, feeratePerKw: FeeratePerKw, commitmentFormat: CommitmentFormat): Either[TxGenerationSkipped, ClaimHtlcTimeoutTx]
def makeClaimLocalDelayedOutputTx(commitTx: Transaction, localDustLimit: Satoshi, localRevocationPubkey: PublicKey, toLocalDelay: CltvExpiryDelta, localDelayedPaymentPubkey: PublicKey, localFinalScriptPubKey: ByteVector, feeratePerKw: FeeratePerKw): Either[TxGenerationSkipped, ClaimLocalDelayedOutputTx]
def makeClaimP2WPKHOutputTx(commitTx: Transaction, localDustLimit: Satoshi, localPaymentPubkey: PublicKey, localFinalScriptPubKey: ByteVector, feeratePerKw: FeeratePerKw): Either[TxGenerationSkipped, ClaimP2WPKHOutputTx]
def makeClaimRemoteDelayedOutputTx(commitTx: Transaction, localDustLimit: Satoshi, localPaymentPubkey: PublicKey, localFinalScriptPubKey: ByteVector, feeratePerKw: FeeratePerKw): Either[TxGenerationSkipped, ClaimRemoteDelayedOutputTx]
def makeClosingTx(commitTxInput: InputInfo, localScriptPubKey: ByteVector, remoteScriptPubKey: ByteVector, localIsInitiator: Boolean, dustLimit: Satoshi, closingFee: Satoshi, spec: CommitmentSpec): ClosingTx
def makeCommitTx(commitTxInput: InputInfo, commitTxNumber: Long, localPaymentBasePoint: PublicKey, remotePaymentBasePoint: PublicKey, localIsInitiator: Boolean, outputs: CommitmentOutputs): CommitTx
def makeCommitTxOutputs(localIsInitiator: Boolean, localDustLimit: Satoshi, localRevocationPubkey: PublicKey, toLocalDelay: CltvExpiryDelta, localDelayedPaymentPubkey: PublicKey, remotePaymentPubkey: PublicKey, localHtlcPubkey: PublicKey, remoteHtlcPubkey: PublicKey, localFundingPubkey: PublicKey, remoteFundingPubkey: PublicKey, spec: CommitmentSpec, commitmentFormat: CommitmentFormat): CommitmentOutputs
def makeHtlcDelayedTx(htlcTx: Transaction, localDustLimit: Satoshi, localRevocationPubkey: PublicKey, toLocalDelay: CltvExpiryDelta, localDelayedPaymentPubkey: PublicKey, localFinalScriptPubKey: ByteVector, feeratePerKw: FeeratePerKw): Either[TxGenerationSkipped, HtlcDelayedTx]
def makeHtlcPenaltyTx(commitTx: Transaction, htlcOutputIndex: Int, redeemScript: ByteVector, localDustLimit: Satoshi, localFinalScriptPubKey: ByteVector, feeratePerKw: FeeratePerKw): Either[TxGenerationSkipped, HtlcPenaltyTx]

We already have the redeemScript, no need to build it

We already have the redeemScript, no need to build it

Source:
Transactions.scala
def makeHtlcSuccessTx(commitTx: Transaction, output: CommitmentOutputLink[InHtlc], outputIndex: Int, localDustLimit: Satoshi, localRevocationPubkey: PublicKey, toLocalDelay: CltvExpiryDelta, localDelayedPaymentPubkey: PublicKey, feeratePerKw: FeeratePerKw, commitmentFormat: CommitmentFormat): Either[TxGenerationSkipped, HtlcSuccessTx]
def makeHtlcTimeoutTx(commitTx: Transaction, output: CommitmentOutputLink[OutHtlc], outputIndex: Int, localDustLimit: Satoshi, localRevocationPubkey: PublicKey, toLocalDelay: CltvExpiryDelta, localDelayedPaymentPubkey: PublicKey, feeratePerKw: FeeratePerKw, commitmentFormat: CommitmentFormat): Either[TxGenerationSkipped, HtlcTimeoutTx]
def makeHtlcTxs(commitTx: Transaction, localDustLimit: Satoshi, localRevocationPubkey: PublicKey, toLocalDelay: CltvExpiryDelta, localDelayedPaymentPubkey: PublicKey, feeratePerKw: FeeratePerKw, outputs: CommitmentOutputs, commitmentFormat: CommitmentFormat): Seq[HtlcTx]
def makeMainPenaltyTx(commitTx: Transaction, localDustLimit: Satoshi, remoteRevocationPubkey: PublicKey, localFinalScriptPubKey: ByteVector, toRemoteDelay: CltvExpiryDelta, remoteDelayedPaymentPubkey: PublicKey, feeratePerKw: FeeratePerKw): Either[TxGenerationSkipped, MainPenaltyTx]
def obscuredCommitTxNumber(commitTxNumber: Long, isInitiator: Boolean, localPaymentBasePoint: PublicKey, remotePaymentBasePoint: PublicKey): Long
Value parameters:
commitTxNumber

commit tx number

isInitiator

true if local node initiated the channel open

localPaymentBasePoint

local payment base point

remotePaymentBasePoint

remote payment base point

Returns:

the obscured tx number as defined in BOLT #3 (a 48 bits integer)

Source:
Transactions.scala
def offeredHtlcTrimThreshold(dustLimit: Satoshi, spec: CommitmentSpec, commitmentFormat: CommitmentFormat): Satoshi

Offered HTLCs below this amount will be trimmed.

Offered HTLCs below this amount will be trimmed.

Source:
Transactions.scala
def offeredHtlcTrimThreshold(dustLimit: Satoshi, feerate: FeeratePerKw, commitmentFormat: CommitmentFormat): Satoshi
def receivedHtlcTrimThreshold(dustLimit: Satoshi, spec: CommitmentSpec, commitmentFormat: CommitmentFormat): Satoshi

Received HTLCs below this amount will be trimmed.

Received HTLCs below this amount will be trimmed.

Source:
Transactions.scala
def receivedHtlcTrimThreshold(dustLimit: Satoshi, feerate: FeeratePerKw, commitmentFormat: CommitmentFormat): Satoshi
def sign(txinfo: TransactionWithInputInfo, key: PrivateKey, txOwner: TxOwner, commitmentFormat: CommitmentFormat): ByteVector64
def weight2fee(feeratePerKw: FeeratePerKw, weight: Int): Satoshi

Concrete fields

val PlaceHolderPubKey: PublicKey

Default public key used for fee estimation

Default public key used for fee estimation

Source:
Transactions.scala
val PlaceHolderSig: ByteVector64

This default sig takes 72B when encoded in DER (incl. 1B for the trailing sig hash), it is used for fee estimation It is 72 bytes because our signatures are normalized (low-s) and will take up 72 bytes at most in DER format

This default sig takes 72B when encoded in DER (incl. 1B for the trailing sig hash), it is used for fee estimation It is 72 bytes because our signatures are normalized (low-s) and will take up 72 bytes at most in DER format

Source:
Transactions.scala
val claimP2WPKHOutputWitnessWeight: Int

these values are specific to us (not defined in the specification) and used to estimate fees

these values are specific to us (not defined in the specification) and used to estimate fees

Source:
Transactions.scala