You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

342 lines
11 KiB

  1. package loop
  2. import (
  3. "time"
  4. "github.com/btcsuite/btcutil"
  5. "github.com/lightninglabs/loop/loopdb"
  6. "github.com/lightninglabs/loop/swap"
  7. "github.com/lightningnetwork/lnd/lntypes"
  8. "github.com/lightningnetwork/lnd/routing/route"
  9. )
  10. // OutRequest contains the required parameters for a loop out swap.
  11. type OutRequest struct {
  12. // Amount specifies the requested swap amount in sat. This does not
  13. // include the swap and miner fee.
  14. Amount btcutil.Amount
  15. // Destination address for the swap.
  16. DestAddr btcutil.Address
  17. // MaxSwapRoutingFee is the maximum off-chain fee in msat that may be
  18. // paid for payment to the server. This limit is applied during path
  19. // finding. Typically this value is taken from the response of the
  20. // LoopOutQuote call.
  21. MaxSwapRoutingFee btcutil.Amount
  22. // MaxPrepayRoutingFee is the maximum off-chain fee in msat that may be
  23. // paid for payment to the server. This limit is applied during path
  24. // finding. Typically this value is taken from the response of the
  25. // LoopOutQuote call.
  26. MaxPrepayRoutingFee btcutil.Amount
  27. // MaxSwapFee is the maximum we are willing to pay the server for the
  28. // swap. This value is not disclosed in the swap initiation call, but
  29. // if the server asks for a higher fee, we abort the swap. Typically
  30. // this value is taken from the response of the LoopOutQuote call. It
  31. // includes the prepay amount.
  32. MaxSwapFee btcutil.Amount
  33. // MaxPrepayAmount is the maximum amount of the swap fee that may be
  34. // charged as a prepayment.
  35. MaxPrepayAmount btcutil.Amount
  36. // MaxMinerFee is the maximum in on-chain fees that we are willing to
  37. // spent. If we want to sweep the on-chain htlc and the fee estimate
  38. // turns out higher than this value, we cancel the swap. If the fee
  39. // estimate is lower, we publish the sweep tx.
  40. //
  41. // If the sweep tx isn't confirmed, we are forced to ratchet up fees
  42. // until it is swept. Possibly even exceeding MaxMinerFee if we get
  43. // close to the htlc timeout. Because the initial publication revealed
  44. // the preimage, we have no other choice. The server may already have
  45. // pulled the off-chain htlc. Only when the fee becomes higher than the
  46. // swap amount, we can only wait for fees to come down and hope - if we
  47. // are past the timeout - that the server isn't publishing the
  48. // revocation.
  49. //
  50. // MaxMinerFee is typically taken from the response of the
  51. // LoopOutQuote call.
  52. MaxMinerFee btcutil.Amount
  53. // SweepConfTarget specifies the targeted confirmation target for the
  54. // client sweep tx.
  55. SweepConfTarget int32
  56. // HtlcConfirmations specifies the number of confirmations we require
  57. // for on chain loop out htlcs.
  58. HtlcConfirmations int32
  59. // OutgoingChanSet optionally specifies the short channel ids of the
  60. // channels that may be used to loop out.
  61. OutgoingChanSet loopdb.ChannelSet
  62. // SwapPublicationDeadline can be set by the client to allow the server
  63. // delaying publication of the swap HTLC to save on chain fees.
  64. SwapPublicationDeadline time.Time
  65. // Expiry is the absolute expiry height of the on-chain htlc.
  66. Expiry int32
  67. // Label contains an optional label for the swap.
  68. Label string
  69. // Initiator is an optional string that identifies what software
  70. // initiated the swap (loop CLI, autolooper, LiT UI and so on) and is
  71. // appended to the user agent string.
  72. Initiator string
  73. }
  74. // Out contains the full details of a loop out request. This includes things
  75. // like the payment hash, the total value, and the final CTLV delay of the
  76. // swap. We'll use this to track an active swap throughout that various swap
  77. // stages.
  78. type Out struct {
  79. // LoopOutContract describes the details of this loop.Out. Using these
  80. // details,the full swap can be executed.
  81. loopdb.LoopOutContract
  82. // State is the current state of the target swap.
  83. State loopdb.SwapState
  84. // SwapInfoKit contains shared data amongst all swap types.
  85. SwapInfoKit
  86. }
  87. // LoopOutQuoteRequest specifies the swap parameters for which a quote is
  88. // requested.
  89. type LoopOutQuoteRequest struct {
  90. // Amount specifies the requested swap amount in sat. This does not
  91. // include the swap and miner fee.
  92. Amount btcutil.Amount
  93. // SweepConfTarget specifies the targeted confirmation target for the
  94. // client sweep tx.
  95. SweepConfTarget int32
  96. // SwapPublicationDeadline can be set by the client to allow the server
  97. // delaying publication of the swap HTLC to save on chain fees.
  98. SwapPublicationDeadline time.Time
  99. // TODO: Add argument to specify confirmation target for server
  100. // publishing htlc. This may influence the swap fee quote, because the
  101. // server needs to pay more for faster confirmations.
  102. //
  103. // TODO: Add arguments to specify maximum total time locks for the
  104. // off-chain swap payment and prepayment. This may influence the
  105. // available routes and off-chain fee estimates. To apply these maximum
  106. // values properly, the server needs to be queried for its required
  107. // final cltv delta values for the off-chain payments.
  108. }
  109. // LoopOutTerms are the server terms on which it executes swaps.
  110. type LoopOutTerms struct {
  111. // MinSwapAmount is the minimum amount that the server requires for a
  112. // swap.
  113. MinSwapAmount btcutil.Amount
  114. // MaxSwapAmount is the maximum amount that the server accepts for a
  115. // swap.
  116. MaxSwapAmount btcutil.Amount
  117. // MinCltvDelta is the minimum expiry delta for loop out swaps.
  118. MinCltvDelta int32
  119. // MaxCltvDelta is the maximum expiry delta for loop out swaps.
  120. MaxCltvDelta int32
  121. }
  122. // LoopOutQuote contains estimates for the fees making up the total swap cost
  123. // for the client.
  124. type LoopOutQuote struct {
  125. // SwapFee is the fee that the swap server is charging for the swap.
  126. SwapFee btcutil.Amount
  127. // PrepayAmount is the part of the swap fee that is requested as a
  128. // prepayment.
  129. PrepayAmount btcutil.Amount
  130. // MinerFee is an estimate of the on-chain fee that needs to be paid to
  131. // sweep the htlc.
  132. MinerFee btcutil.Amount
  133. // SwapPaymentDest is the node pubkey where to swap payment needs to be
  134. // sent to.
  135. SwapPaymentDest [33]byte
  136. }
  137. // LoopInRequest contains the required parameters for the swap.
  138. type LoopInRequest struct {
  139. // Amount specifies the requested swap amount in sat. This does not
  140. // include the swap and miner fee.
  141. Amount btcutil.Amount
  142. // MaxSwapFee is the maximum we are willing to pay the server for the
  143. // swap. This value is not disclosed in the swap initiation call, but if
  144. // the server asks for a higher fee, we abort the swap. Typically this
  145. // value is taken from the response of the LoopInQuote call. It
  146. // includes the prepay amount.
  147. MaxSwapFee btcutil.Amount
  148. // MaxMinerFee is the maximum in on-chain fees that we are willing to
  149. // spent. If we publish the on-chain htlc and the fee estimate turns out
  150. // higher than this value, we cancel the swap.
  151. //
  152. // MaxMinerFee is typically taken from the response of the LoopInQuote
  153. // call.
  154. MaxMinerFee btcutil.Amount
  155. // HtlcConfTarget specifies the targeted confirmation target for the
  156. // client htlc tx.
  157. HtlcConfTarget int32
  158. // LastHop optionally specifies the last hop to use for the loop in
  159. // payment.
  160. LastHop *route.Vertex
  161. // ExternalHtlc specifies whether the htlc is published by an external
  162. // source.
  163. ExternalHtlc bool
  164. // Label contains an optional label for the swap.
  165. Label string
  166. // Initiator is an optional string that identifies what software
  167. // initiated the swap (loop CLI, autolooper, LiT UI and so on) and is
  168. // appended to the user agent string.
  169. Initiator string
  170. }
  171. // LoopInTerms are the server terms on which it executes loop in swaps.
  172. type LoopInTerms struct {
  173. // MinSwapAmount is the minimum amount that the server requires for a
  174. // swap.
  175. MinSwapAmount btcutil.Amount
  176. // MaxSwapAmount is the maximum amount that the server accepts for a
  177. // swap.
  178. MaxSwapAmount btcutil.Amount
  179. }
  180. // In contains status information for a loop in swap.
  181. type In struct {
  182. loopdb.LoopInContract
  183. SwapInfoKit
  184. // State where the swap is in.
  185. State loopdb.SwapState
  186. }
  187. // LoopInQuoteRequest specifies the swap parameters for which a quote is
  188. // requested.
  189. type LoopInQuoteRequest struct {
  190. // Amount specifies the requested swap amount in sat. This does not
  191. // include the swap and miner fee.
  192. Amount btcutil.Amount
  193. // HtlcConfTarget specifies the targeted confirmation target for the
  194. // client sweep tx.
  195. HtlcConfTarget int32
  196. // ExternalHtlc specifies whether the htlc is published by an external
  197. // source.
  198. ExternalHtlc bool
  199. }
  200. // LoopInQuote contains estimates for the fees making up the total swap cost
  201. // for the client.
  202. type LoopInQuote struct {
  203. // SwapFee is the fee that the swap server is charging for the swap.
  204. SwapFee btcutil.Amount
  205. // MinerFee is an estimate of the on-chain fee that needs to be paid to
  206. // sweep the htlc.
  207. MinerFee btcutil.Amount
  208. // Time lock delta relative to current block height that swap server
  209. // will accept on the swap initiation call.
  210. CltvDelta int32
  211. }
  212. // LoopInSwapInfo contains essential information of a loop-in swap after the
  213. // swap is initiated.
  214. type LoopInSwapInfo struct { // nolint
  215. // SwapHash contains the sha256 hash of the swap preimage.
  216. SwapHash lntypes.Hash
  217. // HtlcAddressP2WSH contains the native segwit swap htlc address,
  218. // where the loop-in funds may be paid.
  219. HtlcAddressP2WSH btcutil.Address
  220. // HtlcAddressNP2WSH contains the nested segwit swap htlc address,
  221. // where the loop-in funds may be paid.
  222. HtlcAddressNP2WSH btcutil.Address
  223. // ServerMessages is the human-readable message received from the loop
  224. // server.
  225. ServerMessage string
  226. }
  227. // LoopOutSwapInfo contains essential information of a loop-out swap after the
  228. // swap is initiated.
  229. type LoopOutSwapInfo struct { // nolint:golint
  230. // SwapHash contains the sha256 hash of the swap preimage.
  231. SwapHash lntypes.Hash
  232. // HtlcAddressP2WSH contains the native segwit swap htlc address that
  233. // the server will publish to.
  234. HtlcAddressP2WSH btcutil.Address
  235. // ServerMessages is the human-readable message received from the loop
  236. // server.
  237. ServerMessage string
  238. }
  239. // SwapInfoKit contains common swap info fields.
  240. type SwapInfoKit struct {
  241. // Hash is the sha256 hash of the preimage that unlocks the htlcs. It
  242. // is used to uniquely identify this swap.
  243. Hash lntypes.Hash
  244. // LastUpdateTime is the time of the last update of this swap.
  245. LastUpdateTime time.Time
  246. }
  247. // SwapInfo exposes common info fields for loop in and loop out swaps.
  248. type SwapInfo struct {
  249. loopdb.SwapStateData
  250. loopdb.SwapContract
  251. // LastUpdateTime is the time of the last state change.
  252. LastUpdate time.Time
  253. // SwapHash stores the swap preimage hash.
  254. SwapHash lntypes.Hash
  255. // SwapType describes whether this is a loop in or loop out swap.
  256. SwapType swap.Type
  257. // HtlcAddressP2WSH stores the address of the P2WSH (native segwit)
  258. // swap htlc. This is used for both loop-in and loop-out.
  259. HtlcAddressP2WSH btcutil.Address
  260. // HtlcAddressNP2WSH stores the address of the NP2WSH (nested segwit)
  261. // swap htlc. This is only used for external loop-in.
  262. HtlcAddressNP2WSH btcutil.Address
  263. // ExternalHtlc is set to true for external loop-in swaps.
  264. ExternalHtlc bool
  265. }
  266. // LastUpdate returns the last update time of the swap
  267. func (s *In) LastUpdate() time.Time {
  268. return s.LastUpdateTime
  269. }
  270. // SwapHash returns the swap hash.
  271. func (s *In) SwapHash() lntypes.Hash {
  272. return s.Hash
  273. }