This implements the interactive construction protocol described at
78e5a6b066/02-peer-protocol.md (L92).
Our implementation includes a state machine with typed states and transitions
to ensure consumers have compile-time assurances that the protocol is upheld.
States are tracked as in the `StateMachine` enum and can take on all
possible states during the negotiation.
The states are further divided into two categories, namely by the two traits
they implement, either `ReceivedMsgState` or `SentMsgState`.
The defined `StateTransitions` enforce the transitions that `ReceivedMsgState`,
`SentMsgState`, and the `_TxComplete`s can go through.
Co-authored-by: Wilmer Paulino <9447167+wpaulino@users.noreply.github.com>
Co-authored-by: Duncan Dean <git@dunxen.dev>
Co-authored-by: Jurvis Tan <5944973+jurvis@users.noreply.github.com>
This resolves an issue where offer and refund payments get delayed
while we wait for the `invoice_request`/`invoice` onion messages to
get sent. It further ensures we're likely to have the
`ChannelManager` persisted with the new payment info after
initiating the send/receive.
The `Debug` serialization of `PublicKey`s includes both the X and Y
coordinate, which isn't something most of our users deal with.
Instead, logging using `Display` gives users the keys they're used
to.
If a Refund has an unsupported chain, ChannelManager should not send an
invoice as it can't be paid on that chain. Instead, return an error when
calling ChannelManager::request_refund_payment for such refunds.
In testing, we use channel updates to construct blinded paths and the
{Forward,Receive}Tlvs encoded within. Given a blinded path from node A > B > C,
we currently use channel_update_A->B to construct the payment constraints for
A’s blinded payload.
This is incorrect for setting A's PaymentConstraints::htlc_minimum_msat,
because channel_update_A->B contains the minimum value that *B* will accept,
and we want the constraints to contain the min value that *A* will accept.
This never caused test failures before because min/max htlc values were always
identical in both channel directions.
Therefore, set A’s htlc min/max values to the min/max that A will accept.
SignError allows implementors of SignFunction to return a custom error
type. Drop this as an unconstrained type causes problems with bindings
and isn't useful unless the caller can take some sort of action based on
different errors.
Replace the Fn trait bound on signing methods with a dedicated trait
since Fn is not supported in bindings. Implement the trait for Fn so
that closures can still be used in Rust.
Use the macros introduced in the previous commit to define two builders
for each type parameterization of InvoiceBuilder
- InvoiceWithExplicitSigningPubkeyBuilder
- InvoiceWithDerivedSigningPubkeyBuilder
The difference between these and InvoiceBuilder is that these have
methods that take `self` by mutable reference instead of by value and
don't return anything instead returning the modified builder. This is
required because bindings don't support move semantics nor impl blocks
specific to a certain type parameterization. Because of this, the
builder's contents must be cloned when building a Bolt12Invoice.
Keeps InvoiceBuilder defined so that it can be used internally in
ChannelManager's OffersMessageHandler even when compiled for c_bindings.
We add custom implementations based on comparing the `bytes` for
`Offer`/`Refund` themselves as this is sufficient and should be faster
than comapring all fields in the worst case.
InvoiceBuilder is not exported to bindings because it has methods that
take `self` by value and are only implemented for certain type
parameterizations. Define these methods using macros such that different
builders and related methods can be defined for c_bindings.
Use the macros introduced in the previous commit to define two builders
for each type parameterization of InvoiceRequestBuilder
- InvoiceRequestWithExplicitPayerIdBuilder
- InvoiceRequestWithDerivedPayerIdBuilder
The difference between these and InvoiceRequestBuilder is that these
have methods that take `self` by mutable reference instead of by value
and don't return anything instead returning the modified builder. This
is required because bindings don't support move semantics nor impl
blocks specific to a certain type parameterization. Because of this, the
builder's contents must be cloned when building an InvoiceRequest.
Keeps InvoiceRequestBuilder defined so that it can be used internally in
ChannelManager::pay_for_offer even when compiled for c_bindings.
InvoiceRequestBuilder is not exported to bindings because it has methods
that take `self` by value and are only implemented for certain type
parameterizations. Define these methods using macros such that different
builders and related methods can be defined for c_bindings.
Use the macros introduced in the previous commit to define a builder
called RefundMaybeWithDerivedMetadataBuilder.
The difference between this and RefundBuilder is that this has methods
that take `self` by mutable reference instead of by value and don't
return anything instead returning the modified builder. This is required
because bindings don't support move semantics. Because of this, the
builder's contents must be cloned when building a Refund.
Keeps RefundBuilder defined so that it can be used internally in
ChannelManager::create_refund_builder even when compiled for c_bindings.
RefundBuilder is not exported to bindings because it has methods that
take `self` by value. Define these methods using macros such that
different builders and related methods can be defined for c_bindings.
Use the macros introduced in the previous commit to define two builders
for each type parameterization of OfferBuilder
- OfferWithExplicitMetadataBuilder
- OfferWithDerivedMetadataBuilder
The difference between these and OfferBuilder is that these have methods
that take `self` by mutable reference instead of by value and don't
return anything instead returning the modified builder. This is required
because bindings don't support move semantics nor impl blocks specific
to a certain type parameterization. Because of this, the builder's
contents must be cloned when building an Offer.
Keeps OfferBuilder defined so that it can be used internally in
ChannelManager::create_offer_builder even when compiled for c_bindings.
.. as the std library docs state that implementing Into should be avoided:
"One should avoid implementing Into and implement From instead.
Implementing From automatically provides one with an implementation of
Into thanks to the blanket implementation in the standard library."
tnull noted on discord that its somewhat unclear to users what
`RouteNotFound` actually means - that we ran out of routes, rather
than could not find a route at all - so the docs are updated here.
If a node is announced, prefer using a one-hop blinded path with it as
the introduction node to using a two-hop blinded path with a Tor-only
introduction node. The one-hop blinded path is more reliable, thus only
use Tor-only nodes if the recipient is unannounced. And then, prefer
non-Tor-only nodes.
When forming blinded paths, using a reliable node as the introduction
node is important to ensure onion message reliability. Order blinded
paths by how well-connected the introduction node is as a proxy for
reliability.
For short paths (e.g., when the sender and recipient share an LSP), this
may also result in a scenario where initiating a direct connection isn't
necessary. That is helpful when using RGS since it currently doesn't
include node announcements and thus cannot initiate a direct connection.
