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.

501 lines
14 KiB

  1. syntax = "proto3";
  2. import "google/api/annotations.proto";
  3. package looprpc;
  4. /**
  5. SwapClient is a service that handles the client side process of onchain/offchain
  6. swaps. The service is designed for a single client.
  7. */
  8. service SwapClient {
  9. /** loop: `out`
  10. LoopOut initiates an loop out swap with the given parameters. The call
  11. returns after the swap has been set up with the swap server. From that
  12. point onwards, progress can be tracked via the SwapStatus stream that is
  13. returned from Monitor().
  14. */
  15. rpc LoopOut (LoopOutRequest) returns (SwapResponse) {
  16. option (google.api.http) = {
  17. post: "/v1/loop/out"
  18. body: "*"
  19. };
  20. }
  21. /** loop: `in`
  22. LoopIn initiates a loop in swap with the given parameters. The call
  23. returns after the swap has been set up with the swap server. From that
  24. point onwards, progress can be tracked via the SwapStatus stream
  25. that is returned from Monitor().
  26. */
  27. rpc LoopIn (LoopInRequest) returns (SwapResponse) {
  28. option (google.api.http) = {
  29. post: "/v1/loop/in"
  30. body: "*"
  31. };
  32. }
  33. /** loop: `monitor`
  34. Monitor will return a stream of swap updates for currently active swaps.
  35. */
  36. rpc Monitor (MonitorRequest) returns (stream SwapStatus);
  37. /** loop: `listswaps`
  38. ListSwaps returns a list of all currently known swaps and their current
  39. status.
  40. */
  41. rpc ListSwaps (ListSwapsRequest) returns (ListSwapsResponse) {
  42. option (google.api.http) = {
  43. get: "/v1/loop/swaps"
  44. };
  45. }
  46. /** loop: `swapinfo`
  47. SwapInfo returns all known details about a single swap.
  48. */
  49. rpc SwapInfo (SwapInfoRequest) returns (SwapStatus) {
  50. option (google.api.http) = {
  51. get: "/v1/loop/swap/{id}"
  52. };
  53. }
  54. /** loop: `terms`
  55. LoopOutTerms returns the terms that the server enforces for a loop out swap.
  56. */
  57. rpc LoopOutTerms (TermsRequest) returns (TermsResponse) {
  58. option (google.api.http) = {
  59. get: "/v1/loop/out/terms"
  60. };
  61. }
  62. /** loop: `quote`
  63. LoopOutQuote returns a quote for a loop out swap with the provided
  64. parameters.
  65. */
  66. rpc LoopOutQuote (QuoteRequest) returns (QuoteResponse) {
  67. option (google.api.http) = {
  68. get: "/v1/loop/out/quote/{amt}"
  69. };
  70. }
  71. /** loop: `terms`
  72. GetTerms returns the terms that the server enforces for swaps.
  73. */
  74. rpc GetLoopInTerms (TermsRequest) returns (TermsResponse) {
  75. option (google.api.http) = {
  76. get: "/v1/loop/in/terms"
  77. };
  78. }
  79. /** loop: `quote`
  80. GetQuote returns a quote for a swap with the provided parameters.
  81. */
  82. rpc GetLoopInQuote (QuoteRequest) returns (QuoteResponse) {
  83. option (google.api.http) = {
  84. get: "/v1/loop/in/quote/{amt}"
  85. };
  86. }
  87. /** loop: `listauth`
  88. GetLsatTokens returns all LSAT tokens the daemon ever paid for.
  89. */
  90. rpc GetLsatTokens (TokensRequest) returns (TokensResponse) {
  91. option (google.api.http) = {
  92. get: "/v1/lsat/tokens"
  93. };
  94. }
  95. }
  96. message LoopOutRequest {
  97. /**
  98. Requested swap amount in sat. This does not include the swap and miner fee.
  99. */
  100. int64 amt = 1;
  101. /**
  102. Base58 encoded destination address for the swap.
  103. */
  104. string dest = 2;
  105. /**
  106. Maximum off-chain fee in msat that may be paid for payment to the server.
  107. This limit is applied during path finding. Typically this value is taken
  108. from the response of the GetQuote call.
  109. */
  110. int64 max_swap_routing_fee = 3;
  111. /**
  112. Maximum off-chain fee in msat that may be paid for payment to the server.
  113. This limit is applied during path finding. Typically this value is taken
  114. from the response of the GetQuote call.
  115. */
  116. int64 max_prepay_routing_fee = 4;
  117. /**
  118. Maximum we are willing to pay the server for the swap. This value is not
  119. disclosed in the swap initiation call, but if the server asks for a
  120. higher fee, we abort the swap. Typically this value is taken from the
  121. response of the GetQuote call. It includes the prepay amount.
  122. */
  123. int64 max_swap_fee = 5;
  124. /**
  125. Maximum amount of the swap fee that may be charged as a prepayment.
  126. */
  127. int64 max_prepay_amt = 6;
  128. /**
  129. Maximum in on-chain fees that we are willing to spent. If we want to
  130. sweep the on-chain htlc and the fee estimate turns out higher than this
  131. value, we cancel the swap. If the fee estimate is lower, we publish the
  132. sweep tx.
  133. If the sweep tx is not confirmed, we are forced to ratchet up fees until it
  134. is swept. Possibly even exceeding max_miner_fee if we get close to the htlc
  135. timeout. Because the initial publication revealed the preimage, we have no
  136. other choice. The server may already have pulled the off-chain htlc. Only
  137. when the fee becomes higher than the swap amount, we can only wait for fees
  138. to come down and hope - if we are past the timeout - that the server is not
  139. publishing the revocation.
  140. max_miner_fee is typically taken from the response of the GetQuote call.
  141. */
  142. int64 max_miner_fee = 7;
  143. /**
  144. The channel to loop out, the channel to loop out is selected based on the
  145. lowest routing fee for the swap payment to the server.
  146. */
  147. uint64 loop_out_channel = 8;
  148. /**
  149. The number of blocks from the on-chain HTLC's confirmation height that it
  150. should be swept within.
  151. */
  152. int32 sweep_conf_target = 9;
  153. /**
  154. The latest time (in unix seconds) we allow the server to wait before
  155. publishing the HTLC on chain. Setting this to a larger value will give the
  156. server the opportunity to batch multiple swaps together, and wait for
  157. low-fee periods before publishing the HTLC, potentially resulting in a
  158. lower total swap fee.
  159. */
  160. uint64 swap_publication_deadline = 10;
  161. }
  162. message LoopInRequest {
  163. /**
  164. Requested swap amount in sat. This does not include the swap and miner
  165. fee.
  166. */
  167. int64 amt = 1;
  168. /**
  169. Maximum we are willing to pay the server for the swap. This value is not
  170. disclosed in the swap initiation call, but if the server asks for a
  171. higher fee, we abort the swap. Typically this value is taken from the
  172. response of the GetQuote call.
  173. */
  174. int64 max_swap_fee = 2;
  175. /**
  176. Maximum in on-chain fees that we are willing to spent. If we want to
  177. publish the on-chain htlc and the fee estimate turns out higher than this
  178. value, we cancel the swap.
  179. max_miner_fee is typically taken from the response of the GetQuote call.
  180. */
  181. int64 max_miner_fee = 3;
  182. /**
  183. The last hop to use for the loop in swap. If empty, the last hop is selected
  184. based on the lowest routing fee for the swap payment from the server.
  185. */
  186. bytes last_hop = 4;
  187. /**
  188. If external_htlc is true, we expect the htlc to be published by an external
  189. actor.
  190. */
  191. bool external_htlc = 5;
  192. }
  193. message SwapResponse {
  194. /**
  195. Swap identifier to track status in the update stream that is returned from
  196. the Start() call. Currently this is the hash that locks the htlcs.
  197. DEPRECATED: To make the API more consistent, this field is deprecated in
  198. favor of id_bytes and will be removed in a future release.
  199. */
  200. string id = 1 [deprecated = true];
  201. /**
  202. Swap identifier to track status in the update stream that is returned from
  203. the Start() call. Currently this is the hash that locks the htlcs.
  204. */
  205. bytes id_bytes = 3;
  206. /**
  207. The address of the on-chain htlc.
  208. */
  209. string htlc_address = 2;
  210. }
  211. message MonitorRequest {
  212. }
  213. message SwapStatus {
  214. /**
  215. Requested swap amount in sat. This does not include the swap and miner
  216. fee.
  217. */
  218. int64 amt = 1;
  219. /**
  220. Swap identifier to track status in the update stream that is returned from
  221. the Start() call. Currently this is the hash that locks the htlcs.
  222. DEPRECATED: To make the API more consistent, this field is deprecated in
  223. favor of id_bytes and will be removed in a future release.
  224. */
  225. string id = 2 [deprecated = true];
  226. /**
  227. Swap identifier to track status in the update stream that is returned from
  228. the Start() call. Currently this is the hash that locks the htlcs.
  229. */
  230. bytes id_bytes = 11;
  231. /**
  232. Swap type
  233. */
  234. SwapType type = 3;
  235. /**
  236. State the swap is currently in, see State enum.
  237. */
  238. SwapState state = 4;
  239. /**
  240. Initiation time of the swap.
  241. */
  242. int64 initiation_time = 5;
  243. /**
  244. Initiation time of the swap.
  245. */
  246. int64 last_update_time = 6;
  247. /**
  248. Htlc address.
  249. */
  250. string htlc_address = 7;
  251. /// Swap server cost
  252. int64 cost_server = 8;
  253. // On-chain transaction cost
  254. int64 cost_onchain = 9;
  255. // Off-chain routing fees
  256. int64 cost_offchain = 10;
  257. }
  258. enum SwapType {
  259. // LOOP_OUT indicates an loop out swap (off-chain to on-chain)
  260. LOOP_OUT = 0;
  261. // LOOP_IN indicates a loop in swap (on-chain to off-chain)
  262. LOOP_IN = 1;
  263. }
  264. enum SwapState {
  265. /**
  266. INITIATED is the initial state of a swap. At that point, the initiation
  267. call to the server has been made and the payment process has been started
  268. for the swap and prepayment invoices.
  269. */
  270. INITIATED = 0;
  271. /**
  272. PREIMAGE_REVEALED is reached when the sweep tx publication is first
  273. attempted. From that point on, we should consider the preimage to no
  274. longer be secret and we need to do all we can to get the sweep confirmed.
  275. This state will mostly coalesce with StateHtlcConfirmed, except in the
  276. case where we wait for fees to come down before we sweep.
  277. */
  278. PREIMAGE_REVEALED = 1;
  279. /**
  280. HTLC_PUBLISHED is reached when the htlc tx has been published in a loop in
  281. swap.
  282. */
  283. HTLC_PUBLISHED = 2;
  284. /**
  285. SUCCESS is the final swap state that is reached when the sweep tx has
  286. the required confirmation depth.
  287. */
  288. SUCCESS = 3;
  289. /**
  290. FAILED is the final swap state for a failed swap with or without loss of
  291. the swap amount.
  292. */
  293. FAILED = 4;
  294. /**
  295. INVOICE_SETTLED is reached when the swap invoice in a loop in swap has been
  296. paid, but we are still waiting for the htlc spend to confirm.
  297. */
  298. INVOICE_SETTLED = 5;
  299. }
  300. message ListSwapsRequest {
  301. }
  302. message ListSwapsResponse {
  303. /**
  304. The list of all currently known swaps and their status.
  305. */
  306. repeated SwapStatus swaps = 1;
  307. }
  308. message SwapInfoRequest {
  309. /**
  310. The swap identifier which currently is the hash that locks the HTLCs. When
  311. using REST, this field must be encoded as URL safe base64.
  312. */
  313. bytes id = 1;
  314. }
  315. message TermsRequest {
  316. }
  317. message TermsResponse {
  318. reserved 1, 2, 3, 4, 7;
  319. /**
  320. Minimum swap amount (sat)
  321. */
  322. int64 min_swap_amount = 5;
  323. /**
  324. Maximum swap amount (sat)
  325. */
  326. int64 max_swap_amount = 6;
  327. }
  328. message QuoteRequest {
  329. /**
  330. The amount to swap in satoshis.
  331. */
  332. int64 amt = 1;
  333. /**
  334. The confirmation target that should be used either for the sweep of the
  335. on-chain HTLC broadcast by the swap server in the case of a Loop Out, or for
  336. the confirmation of the on-chain HTLC broadcast by the swap client in the
  337. case of a Loop In.
  338. */
  339. int32 conf_target = 2;
  340. /**
  341. If external_htlc is true, we expect the htlc to be published by an external
  342. actor.
  343. */
  344. bool external_htlc = 3;
  345. /**
  346. The latest time (in unix seconds) we allow the server to wait before
  347. publishing the HTLC on chain. Setting this to a larger value will give the
  348. server the opportunity to batch multiple swaps together, and wait for
  349. low-fee periods before publishing the HTLC, potentially resulting in a
  350. lower total swap fee.
  351. */
  352. uint64 swap_publication_deadline = 4;
  353. }
  354. message QuoteResponse {
  355. /**
  356. The fee that the swap server is charging for the swap.
  357. */
  358. int64 swap_fee = 1;
  359. /**
  360. The part of the swap fee that is requested as a prepayment.
  361. */
  362. int64 prepay_amt = 2;
  363. /**
  364. An estimate of the on-chain fee that needs to be paid to sweep the HTLC.
  365. */
  366. int64 miner_fee = 3;
  367. /**
  368. The node pubkey where the swap payment needs to be paid
  369. to. This can be used to test connectivity before initiating the swap.
  370. */
  371. bytes swap_payment_dest = 4;
  372. /**
  373. On-chain cltv expiry delta
  374. */
  375. int32 cltv_delta = 5;
  376. }
  377. message TokensRequest {
  378. }
  379. message TokensResponse {
  380. /**
  381. List of all tokens the daemon knows of, including old/expired tokens.
  382. */
  383. repeated LsatToken tokens = 1;
  384. }
  385. message LsatToken {
  386. /**
  387. The base macaroon that was baked by the auth server.
  388. */
  389. bytes base_macaroon = 1;
  390. /**
  391. The payment hash of the payment that was paid to obtain the token.
  392. */
  393. bytes payment_hash = 2;
  394. /**
  395. The preimage of the payment hash, knowledge of this is proof that the
  396. payment has been paid. If the preimage is set to all zeros, this means the
  397. payment is still pending and the token is not yet fully valid.
  398. */
  399. bytes payment_preimage = 3;
  400. /**
  401. The amount of millisatoshis that was paid to get the token.
  402. */
  403. int64 amount_paid_msat = 4;
  404. /**
  405. The amount of millisatoshis paid in routing fee to pay for the token.
  406. */
  407. int64 routing_fee_paid_msat = 5;
  408. /**
  409. The creation time of the token as UNIX timestamp in seconds.
  410. */
  411. int64 time_created = 6;
  412. /**
  413. Indicates whether the token is expired or still valid.
  414. */
  415. bool expired = 7;
  416. /**
  417. Identifying attribute of this token in the store. Currently represents the
  418. file name of the token where it's stored on the file system.
  419. */
  420. string storage_name = 8;
  421. }