Appendix C of BOLT 03 contains a series of test vectors asserting that
commitment, HTLC success, and HTLC timeout transactions are created
correctly. Here the test cases are transcribed to Go structs and
verified.
We also break out some logic need to tests that bypass the constructor
and remove some redundant fields.
In this commit, we add the second level witness script to the
HtlcRetribution struct. We do this as it’s possible that we when
attempt to sweep funds after a channel breach, then the remote party
has already gone to the second layer. In this case, we’ll then need to
update our SignDesc and also the witness, in order to do that we need
this script that’ll get us pass the second layer P2WSH check.
In this commit, we add a new function that allows a caller to create a
UnilateralCloseSummary with the proper materials. This will be used
within a new sub-system to be added in a later commit to properly
dispatch notifications when on-chain events happen for a channel.
In this PR, we entirely remove the closeObserver from the channel state
machine. It was added very early on before most of the other aspects of
the daemon were built out. This goroutine was responsible for
dispatching notifications to outside parties if the commitment
transaction was spent at all. This had several issues, since it was
linked to the *lifetime* of the channel state machine itself. As a
result of this linkage, we had to do weird stuff like hand off in
memory pointers to the state machine in order to ensure notifications
were properly dispatched.
In this commit, we’ve added a new HtlcResolutions struct to house both
the incoming and outgoing HTLC resolutions. This struct will now be
coupled with the object that returns when we detect that a commitment
transaction was closed on chain. For incoming HTLC’s, we’ll check the
preimage cache to see if we can claim the HTLC on-chain. If we can,
then we’ll copy of the preimage, and make a proper incoming HTLC
resolution.
In this commit, we modify the OutgoingHtlcResolution struct to detect
if this is the remote party’s commitment transaction or not. With this
change, we’ll now be able to properly time out an HTLC that was
detected on the commitment transaction of the remote peer.
Additionally, we now populate the CsvDelay (if local commitment) and
the ClaimOutpoint (as we may be sweeping directly from the commitment
transaction now.
In this commit, we add a new IncomingHtlcResolution struct. This is the
opposite of the existing OutgoingHtlcResolution struct. The items in
this new struct allow callers to sweep an incoming HTLC that we know
the preimage to. These will always be created when a commitment goes
on-chain. However, if we know the preimage, then that will be populated
in place of all zeroes in the Preimage field.
In this commit, we modify both the ForceCloseSummary, and the
UnilateralClosureSummary to return the items needed to sweep the
commitment output distinctly. By doing this, it’s now possible to pass
a dedicated struct to a sub-system in order to allow it to sweep a
commitment output. As the maturity delay is a part of this new struct,
this tells the caller if this was on the local commitment (CSV
required) or on the remote commitment (no CSV required).
In this commit, we’ve added a new method to the channel state machine:
ActiveHtlcs. This method will allow callers to poll the state of the
channel to retrieve the set of HTLC’s active on *both* commitment
transactions.
In this commit, we modify the RevokeCurrentCommitment method to now
return the set of active HTLC’s. This will be used by callers in the
future to update other sub-systems when the set of HTLC’s on the
commitment changes, and can also be used on the RPC level to
synchronize systems level integration tests.
This commit fixes a nasty bug that has been lingering within lnd, and
has been noticed due to the added retransmission logic. Before this
commit, upon a restart, if we had an active HTLC and received a new
commitment update, then we would re-forward ALL active HTLC’s. This
could at times lead to a nasty cycle:
* We re-forward an HTLC already processed.
* We then notice that the time-lock is out of date (retransmitted
HTLC), so we go to fail it.
* This is detected as a replay attack, so we send an
UpdateMalformedHTLC
* This second failure ends up creating a nil entry in the log,
leading to a panic.
* Remote party disconnects.
* Upon reconnect we send again as we need to retransmit the changes,
this goes on forever.
In order to fix this, we now ensure that we only forward HTLC’s that
have been newly locked in at this next state. With this, we now avoid
the loop described above, and also ensure that we don’t accidentally
attempt an HTLC replay attack on our selves.
Fixes#528.
Fixes#545.
In this commit, we add a new detailed error that’s to be returned
when/if the remote peer sends us an invalid commit signature. The new
error contains the transaction that we attempted to validate the
signature over, the sighs, and the state number. Returning this
additional information will serve to aide in debugging any
cross-implementation issues.
In this commit, add an additional return value to
CompleteCooperativeClose. We’ll now report to the caller our final
balance in the cooperative closure transaction. We report this as
depending on if we’re the initiator or not, our final balance may not
exactly match the balance we had in the last state.
This commit fixes a lingering bug that could at times cause
incompatibilities with other implementations when attempting a
cooperative channel close. Before this commit, we would use a pointer
to the funding txin everywhere. As a result, each time we made a new
state, or verified one, we would modify the sequence field of the main
txin of the commitment transaction. Due to this if we updated the
channel, then went to do a cooperative channel closure, the sequence of
the txin would still be set to the value we used as the state hint.
To remedy this, we now copy the txin each time when making the
commitment transaction, and also the cooperative closure transaction.
This avoids accidentally mutating the txin itself.
Fixes#502.
Previously, some methods on a LightningChannel like SettleHTLC and
FailHTLC would identify HTLCs by payment hash. This would not always
work correctly if there are multiple HTLCs with the same payment hash,
so instead we change these methods to identify HTLCs by their unique
identifiers instead.
In this commit, we extend the ProcessChanSyncMsg to detect a case where
we don’t have the necessary revocation window to send out a new commit.
This can arise if the remote party sends us a new state, but we haven’t
yet fully processed their FundingLocked message yet, so we would be
unable to create a new commitment state.
We fix this by enumerating each of our actions in the case of an error.
If we get ErrNoWindow, then this indicates that we can’t give the
remote party the commitment we would like to optimistically send over.
This isn’t an issue though, as in the next round, we’ll resynchronize
our state.
In this commit, we fix an existing bug that would cause issues within
the switch due to a value not being properly set. Before this commit we
would copy a byte array into a slice without first creating the
necessary capacity for that slice. To fix this, we’ll now ensure that
the blob has the proper capacity before copying over. Several tests
have been updated to always set a fake onion blob.
In this commit, we extend the initial check within SignNextCommitment
to bail out early if we don’t yet know the commitment point of the
remote party. This prevents a class of nil pointer panics if we attempt
to create a new state without yet having received the FundingLocked
message.
In this commit, we fix an existing bug within our cooperative channel
closing transaction generation. Before this commit, we wouldn’t account
for the fee already allocated within the commitment transaction. As a
result, we would calculate the evaluated balance considering the fee
incorrectly. In this commit, we fix this by adding the commitment fee
to the balance of the initiator when crafting the closing transaction
In this commit, we fix an existing bug, as only the initiator needs to
validate any new fee updates. If the initiator sends an invalid fee,
then it will be rejected by the responder as it may put them below
their required reserve.
In this commit, we ensure that we reject any UpdateFee messages if
after applying the update, the initiator doesn’t have enough funds to
actually pay for the new commitment state.
A test has been added to exercise this new behavior.
In this commit, we update the retransmission logic to ensure that we
properly retransmit any sent UpdateFee messages as part of a state
transition. When creating a CommitDiff, if we have a pending fee
update, then we’ll add that to the set of logs updates. When restoring
the commit diff from disk, if we encounter an UpdateFee entry, then
we’ll apply that as waiting to be ACK’d and skip adding it as a log
entry.
A new test has been added to excessive this new behavior.
In this commit, we add a new ResetState method to the channel state
machine which will reset the state of the channel to `channelOpen`. We
add this as before this commit, it was possible for a channel to shift
into the closing state, the closing negotiation be cancelled for
whatever reason, resulting the the channel held by the breachArbiter
unable to act to potential on-chain events.
In this commit, we fix an existing bug that had ramifications within
the operation of the lnd daemon. Before this commit, if the Stop()
method was called, then the closeObserver would exit as well. This
means that would no longer be watching for channel breaches on-chain,
and could miss either a cooperative channel closure or an actual
contract breach.
To fix this, we now introduce a new method to stop for closeObserver:
CancelObserver(). This should ONLY be called once either: the contract
has been fully settled on-chain, or whom ever is watching the relevant
signals has a newer version of the channel that it will watch instead.
In this commit, we modify CreateCloseProposal to no longer return the
same fee passed in. In the past, this method accepted a fee rat rather
than an absolute fee, and would return the computed absolute fee. Now
that the method takes the absolute fee directly, this is unnecessary.
In this commit, we add fully verification (other than checking the
commitment point matches after the fact) of the new optional fields
added to the lnwire.ChannelReestablish message. Two scenarios can
arise: we realize the remote party is on a prior state (and possibly
lost data), or we realize that *we* are on a prior state with the
remote party verifiably proving that they’re on a newer state.
In this commit we extend the set of fields populated within the
returned lnwire.ChannelReestablish to populate the optional data loss
fields. This entails included the commitment secret of the most
recently revoked remote commitment transaction and also our current
unrevoked commitment point.
In this commit, we update all the key derivation within the state
machine to account for the recent spec change which introduces a
distinct key for usages within all HTLC scripts. This change means that
the commitment payment and delay base points, are only required to be
online in the case that a party is forced to go to chain.
We introduce an additional local tweak to the keyring for the HTLC
tweak. Additionally, two new keys have been added: a local and a remote
HTLC key. Generation of sender/receiver HTLC scripts now use the local
and remote HTLC keys rather than the “payment” key for each party.
Finally, when creating/verifying signatures for second-level HTLC
transactions, we use these the distinct HTLC keys, rather than re-using
the payment keys.
In this method we fix an existing deadlock within the unit tests when
running with the race condition detector on. We don’t need to grab the
mutex within the ProcessChanSyncMsg method as this should be the very
first method called when initializing the channel if a channel state
sync is needed.
In this commit we ensure that the channel is always able to exit by
adding a select statement with a quit case when we’re waiting on the
result of a job that was previously sent into the sigPool.
In this commit we do away with the existing availableLocalBalance
attribute and instead add a new, more accurate AvailableBalance method.
The new method will compute the available balance within the channel ,
assuming a new state was created at the instance the method was called.
This new method will now properly account for HTLC fees.
AvailableBalance is now called within AddHTLC in order to ensure we
don’t add any HTLC’s that are unable to be paid for from the PoV of the
fees on the commitment transaction.
We no longer need to manually pass in the channel delta to
AppendToRevocationLog (now called AdvanceCommitChainTail) as the
pointers on-disk will be updated atomically.
In this commit we update the RevokeCurrentCommitment method to properly
use the new database UpdateCommitment method along with properly
converting the in-memory commitment to its corresponding on-disk
format.
In this commit we complete the partially completed ReceiveReestablish
method and rename it to ProcessChanSyncMsg. The new version now
properly implements retransmission as defined within BOLT#2.
Additionally, we’ve added a new case which will optimistically try and
force a resynchronization of the commitment states if we detect we can
deliver a new commitment signature sooner than later after realizing
that we need to retransmit our last revocation message when we recevied
a new state transition.
This commit adds a new method: createCommitDiff. The method will, given
a newly constructed commitment, its signature, and HTLC signatures will
create a channeldb.CommitDiff. The CommitDiff created is to be stored
on disk, as it can be used in the case that the remote party didn’t
receive our CommitSig message and also forgot all the updates that we
queued with the update.
In this commit we complexly revamp the process of restoring all channel
state back into memory after a restart. We’ll now properly do the
following: restore the pending “dangling” commit of the remote party
into the in-memory commitment chain, re-populate all active HTLC’s back
into their respective update logs with the proper indexes/counters, and
properly restore the current commitment of the remote party back in
memory.
This commit adds a new method to the updateLog which will be used when
restoring the state of a channel from disk after a restart. This new
method will add an entry to the updateLog without incrementing either
of the counters as the HTLC already comes pre populated with its
historical index.
With these new fields, we’ll be able to properly reconstruct the log
state after a restart, as each commitment will now note both the
current HTLC and log index.
After addition of the retransmission logic in the channel link, we
should make the onion blobs persistant, the proper way to do this is
include the onion blobs in the payment descriptor rather than storing
them in the distinct struct in the channel link.
In this commit BOLT№2 retranmission logic for the channel link have
been added. Now if channel link have been initialised with the
'SyncState' field than it will send the lnwire.ChannelReestablish
message and will be waiting for receiving the same message from remote
side. Exchange of this message allow both sides understand which
updates they should exchange with each other in order sync their
states.
In this commit, we fix an existing derivation from the commitment state
machine as defined within the specification. Before this commit, we
only kept a single counter which both HTLC adds and fails/settles would
share. This was valid in the prior pre-spec iteration of the state
machine. However in the current draft of the spec, only a distinct
counter for HTLCs are used throughout.
This would cause an incompatibility, as if we mixed adds and settles
during an exchange, then our counter values would differ with other
implementations. To remedy this, we now introduce a distinct HTLC
counter and index within the updateLog.
Each Add will increment both the log counter, and the HTLC counter.
Each Settle/Fail will only increment the log counter. Inbound
Settle/Fails will index into the HTLC index as to target the proper
HTLC. The PaymentDescriptor type has been extended with an additional
field (HltcIndex) which itself tracks the index of an incoming/outgoing
HTLC.
This moves the commitment transaction generation code out of
fetchCommitmentView into createCommitmentTx. Aside from being a pretty
clean logical split, this allows the transaction generation code to be
unit tested more effectively.
Use binary.Read/Write in functions to serialize and deserialize
channel close summary and HTLC boolean data, as well as in
methods to put and fetch channel funding info. Remove lnd
implementations of readBool and writeBool as they are no
longer needed. Also fix a few minor typos.
Use sort.Slice in SignNextCommitment function in lnwallet/channel.go,
as part of the move to use new language features. Remove
sortableSignBatch type wrapper for slice of signJobs since it is
no longer needed to sort jobs according to their output indices.
Also fix a few minor typos in channel.go and sigpool.go.
This commit fixes an existing bug where we attempted to re-use the same
commitTweak value when creating an HTLC resolution. Instead, we now
create the commit tweak value factoring the key that is to be used for
signing.
This commit fixes an existing bug within extractHtlcResolutions. The
prior code would use an index to assign the returned
OutgoingHtlcResolutions into a single slice. However, this is invalid
as there are two cases where an HTLC might be skipped: if it’s an
incoming HTLC, or if the HLTC itself is dust from the PoV of the
commitment chain.
To fix this, we now instead use append to add items to the slice. This
ensure that we don’t have any “empty” items in between fully populated
items.
This commit fixes a bug wherein we would use the incorrect csvDelay
when crafting HTLC resolutions after a unilateral channel closure.
Previously, we would always use the csvDelay of the local party, as in
the force close case that’s the correct value. However, a unilateral
channel closure instead requires the _remote_ delay.
This commit fixes an existing bug when crafting the HTLC resolution in
the face of a commitment broadcast. Previously, we we’re using the
localKey which is incorrect, as directly below we properly use the
delayKey when crafting the secondLevelHtlcScript to sign.
This commit adds a new field: MaturityDelay, to the
UnilateralCloseSummary struct. This new field will be required, in an
upcoming update as it’s needed in order to properly sweep the
second-level HTLC outputs after MaturityDelay blocks has passed since
confirmation.
This commit fixes a minor bug (that doesn’t affect anything atm) when
crafting the SignDesc for sweeping breached outputs. Previously, we
would take the p2wkh script and then p2wsh-ify that, placing that into
the SignDesc. This is incorrect as the p2wkh script is “injected” into
the sighash when signing, and thus doesn’t need another encoding layer.
This commit adds an additional return value to SettleHTLC in order to
make way for an upcoming change to modify the way bandwidth status from
the link to the switch is reported.
This commit removes the current active LocalAvailableBalance method
from the channel state machine itself. We still maintain the internal
availableLocalBalance method locally as this is used to ensure that we
don’t add an HTLC which puts our available balance below zero.
This commit also adds an incoming flag to
HtlcRetribution struct to allow the breach arbiter to
generate the appropriate witness based on the htlc's
directionality.
It also ensures that the size of the htlc retribution
slice is now determined by the size of the number of
htlcs present in the revoked snapshot, which fixes a
minor bug that could lead to nil pointer deferences.
This commit fixes a bug within the HTLC construction and commitment
transaction construction that would result in HTLC _values_ within the
commitment transaction being off by a factor of 1000. This was due to
the fact that we failed to convert the amount of an HTLC, in mSAT, to
SAT before placing it as an output within the commitment transaction.
When attempt to locate the output index of a particular half, we use
the unconverted amount, meaning it was unnoticed.
This commit adds a new assertion within the TestSimpleAddSettleWorkflow
test to ensure that the HTLC is found within the commitment transaction
with the proper value in satoshi.
This commit fixes a lingering bug in the way the internal channel state
machine handled fee calculation. Previously, we would count the dust
HTLC’s that were trimmed towards the fee that the initiator paid. This
is invalid as otherwise, the initiator would always benefit from dust
HTLC’s. Instead, we now simply “donate” the dust HTLC’s to the miner in
the commitment transaction. This change puts us in compliance with
BOLT-0003.
This commit modifies the closeObserver code to populate the signDesc in
the case we have a non-trimmed balance. Additionally, we now also add a
*wire.OutPoint field to the struct in order to allow receivers of the
message to construct a witness that can spend the newly created output
to their wallet.
This commit modifies the methods that transition the state of the
channel into an active closing state. With the new commitment design,
the delivery scripts are no longer pre-committed to the initial funding
messages. Instead, the scripts are sent at the instant that either side
decides to shutdown within the Shutdown message.
This commit adds a new companion struct: OutgoingHtlcResolution to the
commitment state machine. The purpose of this struct is the provide the
caller with the information necessary to sweep all outgoing HTLC’s in
the case of a broadcast up-to-date commitment transaction.
The HTLC resolutions allow a caller to sweep an outgoing HTLC into
their wallet after the absolute timeout of the HTLc has passed. This is
a two step process, with the first portion consisting of broadcasting
the HTLC timeout transaction itself, and the second portion consisting
of claiming the HTLC itself after a CSV delay.
This commit adds awareness of active HTLC outputs to the
BreachRetribution struct. Previously, in the case of a breach, the
struct was only populated with enough information to sweep the two
commitment outputs. With this commit, the struct now has enough
information to sweep _all_ outputs within the commitment transaction.
This commit updates the central fetchCommitmentView method to manage
and derive the necessary easy required to create new commitments due to
the new state machine design within the specification. Each state now
requires us to derive a number of keys for each commitment state:
localDelay, remoteDelay, localKey, remoteKey, the commitment point, and
finally the revocation key itself.
This commit updates the set of functions tasked with generating HTLC’s
scripts for new commitments to now adhere to the new commitment
transaction design. With this change, the process of claiming an HTLC
now requires a second-level HTLC transaction, which solves a prior
issues due to the tight coupling of the timeout and delay clauses when
claiming an HTLC.
This commit adds a new method to the commitment struct:
populateHtlcIndexes. populateHtlcIndexes modifies the set of HTLC's
locked-into the target view to have full indexing information
populated. This information is required as we need to keep track of the
indexes of each HTLC in order to properly write the current state to
disk, and also to locate the PaymentDescriptor corresponding to HTLC
outputs in the commitment transaction.
We also modify toChannelDelta to take not of these new changes, and
access the appropriate index directly.
This commit modifies the way we account for dust HTLC’s within the
commitment state machine when creating and validating new states.
Previously, an HTLC was dust if the amount of the HTLC was below the
dustLimit of the commitment chain. Now, with the HTLC covenant
transaction, the value of the HTLC also needs to cover the required fee
of the HTLC covenant transaction at the specified fee rate of the
commitment chain.
As a result, we now determine if an HTLC is dust or not, only at the
commitment site, using the new htlcIsDust function.
This commit modifies the current core channel state machine in order to
may a step towards BOLT-0002 and BOLT-0003 compliance. In this change,
we abandon the prior revocation window, in favor of a fixed revocation
window of size two. The revocation window will be filled at the start
of the lifetime of the channel, and never extended from there until the
channel has been fully closed.
We now maintain two variables, the current un-revoked commitment point,
and the next commitment point to use when creating a new state. The
next commitment point must initially be inserted into the channel state
with the InitNextRevocation method.
A major difference between the prior revocation key handling is that
the remote party now instead sends us the _commitment point_ in
isolation, which we then use locally (with our revocation base point)
to create the next full revocation key for _their_ commitment
transaction.
This commit updates much of the state interaction within the
LightningChannel structure to account for the recent changes within the
chanenldb involving the OpenChannel struct, namely the introduction of
ChannelConfig and ChannelConstraints.
This commit adds the possibility for the initiator of a
channel to send the update_fee message, as specified
in BOLT#2. After the message is sent and both parties
have committed to the updated fee, all new commitment
messages in the channel will use the specified fee.
If an HTLC’s value is below a node’s dust limit, the amount for that
HTLC should be applied to to the fee used for the channel’s commitment
transaction.
This commit fixes a race condition that would at times occur in the
htlcswitch.TestChannelLinkBidirectionalOneHopPayments test case. A race
condition would occur in the goroutine running ReceiveNewCommitment
compared with the grouting that would obtain the snapshot in order to
make a forwarding decision.
We fix this by creating a new public key for each new commitment
transaction such that we complete avoid the read/write race condition.
This commit fixes a race condition that was discovered as a result of
the new htlcswitch package. The StateSnapshot method and all of the
other methods which mutate the state of the channel state machine were
using distinct mutexes. The fix is trivial: all methods accessing the
internal channel state variable now use the same mutex.
add rhash to the payment descriptor when receiving the settle htlc in
order to be able to pass it during settle htlc packet generation and
later find the user pending payment by rhash without additional hashing.
In this commit we made state machine to be responsible for returning
proper available balance - amount of satoshi which we able to use at
current moment. This will help us in constrction channel link
abstraction.
In this commit severe bug have been fixed which allows the state of the
nodes to be desychnorinesed in the moments of high htlc flow. We limit
the number of the htlc which we can add to commitment transaction
to half of the available capcity. This change fixes the bug when
commimtment transaction on the verge of being full, in this case race
condition might occures and remote htlc will be rejected, but at the
same time they will be added on remote side, the same situiation will
happen with htlc we have added, which cause the commitment transactions
to be different.
This commit changes the cooperative channel close workflow to comply
with the latest spec. This adds steps to handle and send shutdown
messages as well as moving responsibility for sending the channel close
message from the initiator to the responder.
This commit modifies the fee calculation logic when creating or
accepting a new commitment transaction to use the set FeePerKw within
the channel rather then re-query the estimator each time. The prior
behavior was benign as we currently use a static fee estimator, but the
dynamic setting this could’ve caused a state divergence.
This commit replaces the hard-coded 5000 satoshi fees with calls to the
FeeEstimator interface. This should provide a way to cleanly plug in
additional fee calculation algorithms in the future. This change
affected quite a few tests. When possible, the tests were changed to
assert amounts sent rather than balances so that fees wouldn't need to
be taken into account. There were several tests for which this wasn't
possible, so calls to the static fee calculator were made.
This commit adds the FeeEstimator interface, which can be used for
future fee calculation implementations. Currently, there is only the
StaticFeeEstimator implementation, which returns the same fee rate for
any transaction.
In order to cleanly handle shutdowns and restarts during state machine operation, the fee for the current
commitment transaction must be persisted. This allows the fee to be
reapplied when the current state is reloaded.
This commit modifies the actions of the closeObserver goroutine to
utilize a _new_ channel to send channel close details over. The
original close signal channel is still used to notify observers that a
channel _has_ been closed, but this new channel will provide a single
observer with details w.r.t _how_ a channel was closed.
This commit adds an additional field to the ForceCloseSummary that
allows observers of the channel that sends this struct to track _which_
channel the force close came from.
This commit improves the channel state machine by converting the
objective PendingUpdates method to a subjective FullySynced method
which is to be used in place of PendingUpdates. The new FullySynced
method is fully encompassing and replaces any upper state required by
the state machine which wraps this one.
The new FullySynced method is identical to PendingUpdates aside from
the fact that: it now also factors in the log message index of the
remote commitment chain, and also introduces a concept of an “owed
commitment”. A commitment chain owes a commitment if the height of the
local commitment chain is higher than that of the remote chain.
This commit removes the theirPrevPkScript field from the
LightningChannel struct all together. It’s no longer needed as the more
fundamental mutation bug has been fixed within the channel state
machine.
This commit fixes a class of bug that can arise in the channel state
machine when a very high throughput workflow is attempted. Since the
PaymentDescriptor’s within a commitment pointed directly into the log,
any changes to a payment descriptor would also be reflected in all
other ones. Due to this mutation possibility, at times, the
locateOutputIndex method would fail since the HTLC’s pkScript was
modified, causing the channel to fail.
We fix this class of bug by simply ensure that once an HTLC has been
associated with a particular commitment, then it becomes immutable.
