forked from ElementsProject/lightning
-
Notifications
You must be signed in to change notification settings - Fork 0
/
wallet.h
1580 lines (1432 loc) · 47.3 KB
/
wallet.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#ifndef LIGHTNING_WALLET_WALLET_H
#define LIGHTNING_WALLET_WALLET_H
#include "config.h"
#include "db.h"
#include <common/penalty_base.h>
#include <common/utxo.h>
#include <common/wallet.h>
#include <lightningd/bitcoind.h>
#include <lightningd/log.h>
#include <lightningd/peer_htlcs.h>
struct amount_msat;
struct invoices;
struct channel;
struct channel_inflight;
struct lightningd;
struct node_id;
struct oneshot;
struct peer;
struct timers;
enum channel_state;
enum state_change;
struct wallet {
struct lightningd *ld;
struct db *db;
struct log *log;
struct ext_key *bip32_base;
struct invoices *invoices;
struct list_head unstored_payments;
u64 max_channel_dbid;
/* Filter matching all outpoints corresponding to our owned outputs,
* including all spent ones */
struct outpointfilter *owned_outpoints;
/* Filter matching all outpoints that might be a funding transaction on
* the blockchain. This is currently all P2WSH outputs */
struct outpointfilter *utxoset_outpoints;
/* How many keys should we look ahead at most? */
u64 keyscan_gap;
};
static inline enum output_status output_status_in_db(enum output_status s)
{
switch (s) {
case OUTPUT_STATE_AVAILABLE:
BUILD_ASSERT(OUTPUT_STATE_AVAILABLE == 0);
return s;
case OUTPUT_STATE_RESERVED:
BUILD_ASSERT(OUTPUT_STATE_RESERVED == 1);
return s;
case OUTPUT_STATE_SPENT:
BUILD_ASSERT(OUTPUT_STATE_SPENT == 2);
return s;
/* This one doesn't go into db */
case OUTPUT_STATE_ANY:
break;
}
fatal("%s: %u is invalid", __func__, s);
}
/* Enumeration of all known output types. These include all types that
* could ever end up on-chain and we may need to react upon. Notice
* that `to_local`, `htlc_offer`, and `htlc_recv` may need immediate
* action since they are encumbered with a CSV. */
/* /!\ This is a DB ENUM, please do not change the numbering of any
* already defined elements (adding is ok) /!\ */
enum wallet_output_type {
p2sh_wpkh = 0,
to_local = 1,
htlc_offer = 3,
htlc_recv = 4,
our_change = 5,
p2wpkh = 6
};
static inline enum wallet_output_type wallet_output_type_in_db(enum wallet_output_type w)
{
switch (w) {
case p2sh_wpkh:
BUILD_ASSERT(p2sh_wpkh == 0);
return w;
case to_local:
BUILD_ASSERT(to_local == 1);
return w;
case htlc_offer:
BUILD_ASSERT(htlc_offer == 3);
return w;
case htlc_recv:
BUILD_ASSERT(htlc_recv == 4);
return w;
case our_change:
BUILD_ASSERT(our_change == 5);
return w;
case p2wpkh:
BUILD_ASSERT(p2wpkh == 6);
return w;
}
fatal("%s: %u is invalid", __func__, w);
}
/**
* Possible states for forwards
*
*/
/* /!\ This is a DB ENUM, please do not change the numbering of any
* already defined elements (adding is ok) /!\ */
enum forward_status {
FORWARD_OFFERED = 0,
FORWARD_SETTLED = 1,
FORWARD_FAILED = 2,
FORWARD_LOCAL_FAILED = 3,
/* Special status used to express that we don't care in
* queries */
FORWARD_ANY = 255
};
static inline enum forward_status wallet_forward_status_in_db(enum forward_status s)
{
switch (s) {
case FORWARD_OFFERED:
BUILD_ASSERT(FORWARD_OFFERED == 0);
return s;
case FORWARD_SETTLED:
BUILD_ASSERT(FORWARD_SETTLED == 1);
return s;
case FORWARD_FAILED:
BUILD_ASSERT(FORWARD_FAILED == 2);
return s;
case FORWARD_LOCAL_FAILED:
BUILD_ASSERT(FORWARD_LOCAL_FAILED == 3);
return s;
case FORWARD_ANY:
break;
}
fatal("%s: %u is invalid", __func__, s);
}
static inline const char* forward_status_name(enum forward_status status)
{
switch(status) {
case FORWARD_OFFERED:
return "offered";
case FORWARD_SETTLED:
return "settled";
case FORWARD_FAILED:
return "failed";
case FORWARD_LOCAL_FAILED:
return "local_failed";
case FORWARD_ANY:
return "any";
}
abort();
}
bool string_to_forward_status(const char *status_str, enum forward_status *status);
/* DB wrapper to check htlc_state */
static inline enum htlc_state htlc_state_in_db(enum htlc_state s)
{
switch (s) {
case SENT_ADD_HTLC:
BUILD_ASSERT(SENT_ADD_HTLC == 0);
return s;
case SENT_ADD_COMMIT:
BUILD_ASSERT(SENT_ADD_COMMIT == 1);
return s;
case RCVD_ADD_REVOCATION:
BUILD_ASSERT(RCVD_ADD_REVOCATION == 2);
return s;
case RCVD_ADD_ACK_COMMIT:
BUILD_ASSERT(RCVD_ADD_ACK_COMMIT == 3);
return s;
case SENT_ADD_ACK_REVOCATION:
BUILD_ASSERT(SENT_ADD_ACK_REVOCATION == 4);
return s;
case RCVD_REMOVE_HTLC:
BUILD_ASSERT(RCVD_REMOVE_HTLC == 5);
return s;
case RCVD_REMOVE_COMMIT:
BUILD_ASSERT(RCVD_REMOVE_COMMIT == 6);
return s;
case SENT_REMOVE_REVOCATION:
BUILD_ASSERT(SENT_REMOVE_REVOCATION == 7);
return s;
case SENT_REMOVE_ACK_COMMIT:
BUILD_ASSERT(SENT_REMOVE_ACK_COMMIT == 8);
return s;
case RCVD_REMOVE_ACK_REVOCATION:
BUILD_ASSERT(RCVD_REMOVE_ACK_REVOCATION == 9);
return s;
case RCVD_ADD_HTLC:
BUILD_ASSERT(RCVD_ADD_HTLC == 10);
return s;
case RCVD_ADD_COMMIT:
BUILD_ASSERT(RCVD_ADD_COMMIT == 11);
return s;
case SENT_ADD_REVOCATION:
BUILD_ASSERT(SENT_ADD_REVOCATION == 12);
return s;
case SENT_ADD_ACK_COMMIT:
BUILD_ASSERT(SENT_ADD_ACK_COMMIT == 13);
return s;
case RCVD_ADD_ACK_REVOCATION:
BUILD_ASSERT(RCVD_ADD_ACK_REVOCATION == 14);
return s;
case SENT_REMOVE_HTLC:
BUILD_ASSERT(SENT_REMOVE_HTLC == 15);
return s;
case SENT_REMOVE_COMMIT:
BUILD_ASSERT(SENT_REMOVE_COMMIT == 16);
return s;
case RCVD_REMOVE_REVOCATION:
BUILD_ASSERT(RCVD_REMOVE_REVOCATION == 17);
return s;
case RCVD_REMOVE_ACK_COMMIT:
BUILD_ASSERT(RCVD_REMOVE_ACK_COMMIT == 18);
return s;
case SENT_REMOVE_ACK_REVOCATION:
BUILD_ASSERT(SENT_REMOVE_ACK_REVOCATION == 19);
return s;
case HTLC_STATE_INVALID:
/* Not in db! */
break;
}
fatal("%s: %u is invalid", __func__, s);
}
struct forwarding {
struct short_channel_id channel_in, channel_out;
struct amount_msat msat_in, msat_out, fee;
struct sha256 *payment_hash;
enum forward_status status;
enum onion_wire failcode;
struct timeabs received_time;
/* May not be present if the HTLC was not resolved yet. */
struct timeabs *resolved_time;
};
/* A database backed shachain struct. The datastructure is
* writethrough, reads are performed from an in-memory version, all
* writes are passed through to the DB. */
struct wallet_shachain {
u64 id;
struct shachain chain;
};
/* Possible states for a wallet_payment. Payments start in
* `PENDING`. Outgoing payments are set to `PAYMENT_COMPLETE` once we
* get the preimage matching the rhash, or to
* `PAYMENT_FAILED`. */
/* /!\ This is a DB ENUM, please do not change the numbering of any
* already defined elements (adding is ok but you should append the
* test case test_wallet_payment_status_enum() ) /!\ */
enum wallet_payment_status {
PAYMENT_PENDING = 0,
PAYMENT_COMPLETE = 1,
PAYMENT_FAILED = 2
};
struct tx_annotation {
enum wallet_tx_type type;
struct short_channel_id channel;
};
static inline enum wallet_payment_status wallet_payment_status_in_db(enum wallet_payment_status w)
{
switch (w) {
case PAYMENT_PENDING:
BUILD_ASSERT(PAYMENT_PENDING == 0);
return w;
case PAYMENT_COMPLETE:
BUILD_ASSERT(PAYMENT_COMPLETE == 1);
return w;
case PAYMENT_FAILED:
BUILD_ASSERT(PAYMENT_FAILED == 2);
return w;
}
fatal("%s: %u is invalid", __func__, w);
}
/* Outgoing payments. A simple persisted representation
* of a payment we initiated. This can be used by
* a UI (alongside invoices) to display the balance history.
*/
struct wallet_payment {
/* If it's in unstored_payments */
struct list_node list;
u64 id;
u32 timestamp;
/* The combination of these three fields is unique: */
struct sha256 payment_hash;
u64 partid;
u64 groupid;
enum wallet_payment_status status;
/* The destination may not be known if we used `sendonion` */
struct node_id *destination;
struct amount_msat msatoshi;
struct amount_msat msatoshi_sent;
struct amount_msat total_msat;
/* If and only if PAYMENT_COMPLETE */
struct preimage *payment_preimage;
/* Needed for recovering from routing failures. */
struct secret *path_secrets;
struct node_id *route_nodes;
struct short_channel_id *route_channels;
/* bolt11/bolt12 string; NULL for old payments. */
const char *invstring;
/* The label of the payment. Must support `tal_len` */
const char *label;
/* If we could not decode the fail onion, just add it here. */
const u8 *failonion;
/* If we are associated with an internal offer */
struct sha256 *local_offer_id;
};
struct outpoint {
struct bitcoin_outpoint outpoint;
u32 blockheight;
u32 txindex;
struct amount_sat sat;
u8 *scriptpubkey;
u32 spendheight;
};
/* Statistics for a channel */
struct channel_stats {
u64 in_payments_offered, in_payments_fulfilled;
struct amount_msat in_msatoshi_offered, in_msatoshi_fulfilled;
u64 out_payments_offered, out_payments_fulfilled;
struct amount_msat out_msatoshi_offered, out_msatoshi_fulfilled;
};
struct channeltx {
u32 channel_id;
int type;
u32 blockheight;
struct bitcoin_txid txid;
struct bitcoin_tx *tx;
u32 input_num;
u32 depth;
};
struct wallet_transaction {
struct bitcoin_txid id;
u32 blockheight;
u32 txindex;
u8 *rawtx;
/* Fully parsed transaction */
const struct bitcoin_tx *tx;
struct tx_annotation annotation;
/* tal_arr containing the annotation types, if any, for the respective
* inputs and outputs. 0 if there are no annotations for the
* element. */
struct tx_annotation *input_annotations;
struct tx_annotation *output_annotations;
};
/**
* wallet_new - Constructor for a new DB based wallet
*
* This is guaranteed to either return a valid wallet, or abort with
* `fatal` if it cannot be initialized.
*/
struct wallet *wallet_new(struct lightningd *ld, struct timers *timers,
struct ext_key *bip32_base);
/**
* wallet_confirm_tx - Confirm a tx which contains a UTXO.
*/
void wallet_confirm_tx(struct wallet *w,
const struct bitcoin_txid *txid,
const u32 confirmation_height);
/**
* wallet_update_output_status - Perform an output state transition
*
* Change the current status of an output we are tracking in the
* database. Returns true if the output exists with the @oldstatus and
* was successfully updated to @newstatus. May fail if either the
* output does not exist, or it does not have the expected
* @oldstatus. In case we don't care about the previous state use
* `output_state_any` as @oldstatus.
*/
bool wallet_update_output_status(struct wallet *w,
const struct bitcoin_outpoint *outpoint,
enum output_status oldstatus,
enum output_status newstatus);
/**
* wallet_get_utxos - Retrieve all utxos matching a given state
*
* Returns a `tal_arr` of `utxo` structs. Double indirection in order
* to be able to steal individual elements onto something else.
*/
struct utxo **wallet_get_utxos(const tal_t *ctx, struct wallet *w,
const enum output_status state);
/**
* wallet_get_unconfirmed_closeinfo_utxos - Retrieve any unconfirmed utxos w/ closeinfo
*
* Returns a `tal_arr` of `utxo` structs. Double indirection in order
* to be able to steal individual elements onto something else.
*/
struct utxo **wallet_get_unconfirmed_closeinfo_utxos(const tal_t *ctx,
struct wallet *w);
/**
* wallet_find_utxo - Select an available UTXO (does not reserve it!).
* @ctx: tal context
* @w: wallet
* @current_blockheight: current chain length.
* @amount_we_are_short: optional amount.
* @feerate_per_kw: feerate we are using.
* @maxheight: zero (if caller doesn't care) or maximum blockheight to accept.
* @excludes: UTXOs not to consider.
*
* If @amount_we_are_short is not NULL, we try to get something very close
* (i.e. when we add this input, we will add => @amount_we_are_short, but
* less than @amount_we_are_short + dustlimit).
*
* Otherwise we give a random UTXO.
*/
struct utxo *wallet_find_utxo(const tal_t *ctx, struct wallet *w,
unsigned current_blockheight,
struct amount_sat *amount_we_are_short,
unsigned feerate_per_kw,
u32 maxheight,
const struct utxo **excludes);
/**
* wallet_add_onchaind_utxo - Add a UTXO with spending info from onchaind.
*
* Usually we add UTXOs by looking at transactions, but onchaind tells
* us about other UTXOs we can spend with some extra metadata.
*
* Returns false if we already have it in db (that's fine).
*/
bool wallet_add_onchaind_utxo(struct wallet *w,
const struct bitcoin_outpoint *outpoint,
const u8 *scriptpubkey,
u32 blockheight,
struct amount_sat amount,
const struct channel *chan,
/* NULL if option_static_remotekey */
const struct pubkey *commitment_point,
/* option_will_fund makes the csv_lock variable */
u32 csv_lock);
/**
* wallet_reserve_utxo - set a reservation on a UTXO.
*
* If the reservation is already reserved:
* refreshes the reservation by @reserve, return true.
* Otherwise if it's available:
* reserves until @current_height + @reserve, returns true.
* Otherwise:
* returns false.
*/
bool wallet_reserve_utxo(struct wallet *w,
struct utxo *utxo,
u32 current_height,
u32 reserve);
/* wallet_unreserve_utxo - make a reserved UTXO available again.
*
* Must be reserved.
*/
void wallet_unreserve_utxo(struct wallet *w, struct utxo *utxo,
u32 current_height, u32 unreserve);
/** wallet_utxo_get - Retrive a utxo.
*
* Returns a utxo, or NULL if not found.
*/
struct utxo *wallet_utxo_get(const tal_t *ctx, struct wallet *w,
const struct bitcoin_outpoint *outpoint);
/**
* wallet_can_spend - Do we have the private key matching this scriptpubkey?
*
* FIXME: This is very slow with lots of inputs!
*
* @w: (in) wallet holding the pubkeys to check against (privkeys are on HSM)
* @script: (in) the script to check
* @index: (out) the bip32 derivation index that matched the script
* @output_is_p2sh: (out) whether the script is a p2sh, or p2wpkh
*/
bool wallet_can_spend(struct wallet *w, const u8 *script,
u32 *index, bool *output_is_p2sh);
/**
* wallet_get_newindex - get a new index from the wallet.
* @ld: (in) lightning daemon
*
* Returns -1 on error (key exhaustion).
*/
s64 wallet_get_newindex(struct lightningd *ld);
/**
* wallet_shachain_add_hash -- wallet wrapper around shachain_add_hash
*/
bool wallet_shachain_add_hash(struct wallet *wallet,
struct wallet_shachain *chain,
uint64_t index,
const struct secret *hash);
/**
* wallet_get_uncommitted_channel_dbid -- get a unique channel dbid
*
* @wallet: the wallet
*/
u64 wallet_get_channel_dbid(struct wallet *wallet);
/**
* wallet_channel_save -- Upsert the channel into the database
*
* @wallet: the wallet to save into
* @chan: the instance to store (not const so we can update the unique_id upon
* insert)
*/
void wallet_channel_save(struct wallet *w, struct channel *chan);
/**
* wallet_channel_insert -- Insert the initial channel into the database
*
* @wallet: the wallet to save into
* @chan: the instance to store
*/
void wallet_channel_insert(struct wallet *w, struct channel *chan);
/**
* Save an inflight transaction for a channel
*/
void wallet_inflight_add(struct wallet *w, struct channel_inflight *inflight);
/**
* Update an existing inflight channel transaction
*/
void wallet_inflight_save(struct wallet *w,
struct channel_inflight *inflight);
/**
* Remove all the inflights from a channel. Also cleans up
* the channel's inflight list
*/
void wallet_channel_clear_inflights(struct wallet *w,
struct channel *chan);
/**
* After fully resolving a channel, only keep a lightweight stub
*/
void wallet_channel_close(struct wallet *w, u64 wallet_id);
/**
* Adds a channel state change history entry into the database
*/
void wallet_state_change_add(struct wallet *w,
const u64 channel_id,
struct timeabs *timestamp,
enum channel_state old_state,
enum channel_state new_state,
enum state_change cause,
char *message);
/**
* Gets all state change history entries for a channel from the database
*/
struct state_change_entry *wallet_state_change_get(struct wallet *w,
const tal_t *ctx,
u64 channel_id);
/**
* wallet_peer_delete -- After no more channels in peer, forget about it
*/
void wallet_peer_delete(struct wallet *w, u64 peer_dbid);
/**
* wallet_init_channels -- Loads active channels into peers
* and inits the dbid counter for next channel.
*
* @w: wallet to load from
*
* Be sure to call this only once on startup since it'll append peers
* loaded from the database to the list without checking.
*/
bool wallet_init_channels(struct wallet *w);
/**
* wallet_channel_stats_incr_* - Increase channel statistics.
*
* @w: wallet containing the channel
* @cdbid: channel database id
* @msatoshi: amount in msatoshi being transferred
*/
void wallet_channel_stats_incr_in_offered(struct wallet *w, u64 cdbid, struct amount_msat msatoshi);
void wallet_channel_stats_incr_in_fulfilled(struct wallet *w, u64 cdbid, struct amount_msat msatoshi);
void wallet_channel_stats_incr_out_offered(struct wallet *w, u64 cdbid, struct amount_msat msatoshi);
void wallet_channel_stats_incr_out_fulfilled(struct wallet *w, u64 cdbid, struct amount_msat msatoshi);
/**
* wallet_channel_stats_load - Load channel statistics
*
* @w: wallet containing the channel
* @cdbid: channel database id
* @stats: location to load statistics to
*/
void wallet_channel_stats_load(struct wallet *w, u64 cdbid, struct channel_stats *stats);
/**
* Retrieve the blockheight of the last block processed by lightningd.
*
* Will set min/max either the minimal/maximal blockheight or the default value
* if the wallet was never used before.
*
* @w: wallet to load from.
* @def: the default value to return if we've never used the wallet before
* @min(out): height of the first block we track
* @max(out): height of the last block we added
*/
void wallet_blocks_heights(struct wallet *w, u32 def, u32 *min, u32 *max);
/**
* wallet_extract_owned_outputs - given a tx, extract all of our outputs
*/
int wallet_extract_owned_outputs(struct wallet *w, const struct wally_tx *tx,
const u32 *blockheight,
struct amount_sat *total);
/**
* wallet_htlc_save_in - store an htlc_in in the database
*
* @wallet: wallet to store the htlc into
* @chan: the channel this HTLC is associated with
* @in: the htlc_in to store
*
* This will store the contents of the `struct htlc_in` in the
* database. Since `struct htlc_in` commonly only change state after
* being created we do not support updating arbitrary fields and this
* function will fail when attempting to call it multiple times for
* the same `struct htlc_in`. Instead `wallet_htlc_update` may be used
* for state transitions or to set the `payment_key` for completed
* HTLCs.
*/
void wallet_htlc_save_in(struct wallet *wallet,
const struct channel *chan, struct htlc_in *in);
/**
* wallet_htlc_save_out - store an htlc_out in the database
*
* See comment for wallet_htlc_save_in.
*/
void wallet_htlc_save_out(struct wallet *wallet,
const struct channel *chan,
struct htlc_out *out);
/**
* wallet_htlc_update - perform state transition or add payment_key
*
* @wallet: the wallet containing the HTLC to update
* @htlc_dbid: the database ID used to identify the HTLC
* @new_state: the state we should transition to
* @payment_key: the `payment_key` which hashes to the `payment_hash`,
* or NULL if unknown.
* @max_commit_num: maximum of local and remote commitment numbers.
* @badonion: the current BADONION failure code, or 0.
* @failonion: the current failure onion message (from peer), or NULL.
* @failmsg: the current local failure message, or NULL.
* @we_filled: for htlc-ins, true if we originated the preimage.
*
* Used to update the state of an HTLC, either a `struct htlc_in` or a
* `struct htlc_out` and optionally set the `payment_key` should the
* HTLC have been settled, or `failcode`/`failonion` if failed.
*/
void wallet_htlc_update(struct wallet *wallet, const u64 htlc_dbid,
const enum htlc_state new_state,
const struct preimage *payment_key,
u64 max_commit_num,
enum onion_wire badonion,
const struct onionreply *failonion,
const u8 *failmsg,
bool *we_filled);
/**
* wallet_htlcs_load_in_for_channel - Load incoming HTLCs associated with chan from DB.
*
* @wallet: wallet to load from
* @chan: load HTLCs associated with this channel
* @htlcs_in: htlc_in_map to store loaded htlc_in in
*
* This function looks for incoming HTLCs that are associated with the given
* channel and loads them into the provided map.
*/
bool wallet_htlcs_load_in_for_channel(struct wallet *wallet,
struct channel *chan,
struct htlc_in_map *htlcs_in);
/**
* wallet_htlcs_load_out_for_channel - Load outgoing HTLCs associated with chan from DB.
*
* @wallet: wallet to load from
* @chan: load HTLCs associated with this channel
* @htlcs_out: htlc_out_map to store loaded htlc_out in.
* @remaining_htlcs_in: htlc_in_map with unconnected htlcs (removed as we progress)
*
* We populate htlc_out->in by looking up in remaining_htlcs_in. It's
* possible that it's still NULL, since we can have outgoing HTLCs
* outlive their corresponding incoming.
*/
bool wallet_htlcs_load_out_for_channel(struct wallet *wallet,
struct channel *chan,
struct htlc_out_map *htlcs_out,
struct htlc_in_map *remaining_htlcs_in);
/**
* wallet_announcement_save - Save remote announcement information with channel.
*
* @wallet: wallet to load from
* @id: channel database id
* @remote_ann_node_sig: location to load remote_ann_node_sig to
* @remote_ann_bitcoin_sig: location to load remote_ann_bitcoin_sig to
*
* This function is only used to save REMOTE announcement information into DB
* when the channel has set the announce_channel bit and don't send the shutdown
* message(BOLT#7).
*/
void wallet_announcement_save(struct wallet *wallet, u64 id,
secp256k1_ecdsa_signature *remote_ann_node_sig,
secp256k1_ecdsa_signature *remote_ann_bitcoin_sig);
/* /!\ This is a DB ENUM, please do not change the numbering of any
* already defined elements (adding is ok) /!\ */
enum invoice_status {
UNPAID,
PAID,
EXPIRED,
};
static inline enum invoice_status invoice_status_in_db(enum invoice_status s)
{
switch (s) {
case UNPAID:
BUILD_ASSERT(UNPAID == 0);
return s;
case PAID:
BUILD_ASSERT(PAID == 1);
return s;
case EXPIRED:
BUILD_ASSERT(EXPIRED == 2);
return s;
}
fatal("%s: %u is invalid", __func__, s);
}
/* The information about an invoice */
struct invoice_details {
/* Current invoice state */
enum invoice_status state;
/* Preimage for this invoice */
struct preimage r;
/* Hash of preimage r */
struct sha256 rhash;
/* Label assigned by user */
const struct json_escape *label;
/* NULL if they specified "any" */
struct amount_msat *msat;
/* Absolute UNIX epoch time this will expire */
u64 expiry_time;
/* Set if state == PAID; order to be returned by waitanyinvoice */
u64 pay_index;
/* Set if state == PAID; amount received */
struct amount_msat received;
/* Set if state == PAID; time paid */
u64 paid_timestamp;
/* BOLT11 or BOLT12 encoding for this invoice */
const char *invstring;
/* The description of the payment. */
char *description;
/* The features, if any (tal_arr) */
u8 *features;
/* The offer this refers to, if any. */
struct sha256 *local_offer_id;
};
/* An object that handles iteration over the set of invoices */
struct invoice_iterator {
/* The contents of this object is subject to change
* and should not be depended upon */
void *p;
};
struct invoice {
/* Internal, rest of lightningd should not use */
/* Database ID */
u64 id;
};
#define INVOICE_MAX_LABEL_LEN 128
/**
* wallet_invoice_create - Create a new invoice.
*
* @wallet - the wallet to create the invoice in.
* @pinvoice - pointer to location to load new invoice in.
* @msat - the amount the invoice should have, or
* NULL for any-amount invoices.
* @label - the unique label for this invoice. Must be
* non-NULL.
* @expiry - the number of seconds before the invoice
* expires
*
* Returns false if label already exists or expiry is 0.
* Returns true if created invoice.
* FIXME: Fallback addresses
*/
bool wallet_invoice_create(struct wallet *wallet,
struct invoice *pinvoice,
const struct amount_msat *msat TAKES,
const struct json_escape *label TAKES,
u64 expiry,
const char *b11enc,
const char *description,
const u8 *features,
const struct preimage *r,
const struct sha256 *rhash,
const struct sha256 *local_offer_id);
/**
* wallet_invoice_find_by_label - Search for an invoice by label
*
* @wallet - the wallet to search.
* @pinvoice - pointer to location to load found invoice in.
* @label - the label to search for.
*
* Returns false if no invoice with that label exists.
* Returns true if found.
*/
bool wallet_invoice_find_by_label(struct wallet *wallet,
struct invoice *pinvoice,
const struct json_escape *label);
/**
* wallet_invoice_find_by_rhash - Search for an invoice by payment_hash
*
* @wallet - the wallet to search.
* @pinvoice - pointer to location to load found invoice in.
* @rhash - the payment_hash to search for.
*
* Returns false if no invoice with that rhash exists.
* Returns true if found.
*/
bool wallet_invoice_find_by_rhash(struct wallet *wallet,
struct invoice *pinvoice,
const struct sha256 *rhash);
/**
* wallet_invoice_find_unpaid - Search for an unpaid, unexpired invoice by
* payment_hash
*
* @wallet - the wallet to search.
* @pinvoice - pointer to location to load found invoice in.
* @rhash - the payment_hash to search for.
*
* Returns false if no unpaid invoice with that rhash exists.
* Returns true if found.
*/
bool wallet_invoice_find_unpaid(struct wallet *wallet,
struct invoice *pinvoice,
const struct sha256 *rhash);
/**
* wallet_invoice_delete - Delete an invoice
*
* @wallet - the wallet to delete the invoice from.
* @invoice - the invoice to delete.
*
* Return false on failure.
*/
bool wallet_invoice_delete(struct wallet *wallet,
struct invoice invoice);
/**
* wallet_invoice_delete_expired - Delete all expired invoices
* with expiration time less than or equal to the given.
*
* @wallet - the wallet to delete invoices from.
* @max_expiry_time - the maximum expiry time to delete.
*/
void wallet_invoice_delete_expired(struct wallet *wallet,
u64 max_expiry_time);
/**
* wallet_invoice_iterate - Iterate over all existing invoices
*
* @wallet - the wallet whose invoices are to be iterated over.
* @iterator - the iterator object to use.
*
* Return false at end-of-sequence, true if still iterating.
* Usage:
*
* struct invoice_iterator it;
* memset(&it, 0, sizeof(it))
* while (wallet_invoice_iterate(wallet, &it)) {
* ...
* }
*/
bool wallet_invoice_iterate(struct wallet *wallet,
struct invoice_iterator *it);
/**
* wallet_invoice_iterator_deref - Read the details of the
* invoice currently pointed to by the given iterator.
*
* @ctx - the owner of the label and msatoshi fields returned.
* @wallet - the wallet whose invoices are to be iterated over.
* @iterator - the iterator object to use.
* @return pointer to the invoice details allocated off of `ctx`.
*/
const struct invoice_details *wallet_invoice_iterator_deref(const tal_t *ctx,
struct wallet *wallet,
const struct invoice_iterator *it);
/**
* wallet_invoice_resolve - Mark an invoice as paid
*
* @wallet - the wallet containing the invoice.
* @invoice - the invoice to mark as paid.
* @received - the actual amount received.
*
* If the invoice is not UNPAID, returns false.
*/
bool wallet_invoice_resolve(struct wallet *wallet,
struct invoice invoice,
struct amount_msat received);
/**
* wallet_invoice_waitany - Wait for any invoice to be paid.
*
* @ctx - the owner of the callback. If the owner is freed,
* the callback is cancelled.
* @wallet - the wallet to query.
* @lastpay_index - wait for invoices after the specified
* pay_index. Use 0 to wait for the first invoice.
* @cb - the callback to invoke. If an invoice is already
* paid with pay_index greater than lastpay_index, this
* is called immediately, otherwise it is called during
* an invoices_resolve call. Will never be given a NULL
* pointer-to-invoice.
* @cbarg - the callback data.
*/
void wallet_invoice_waitany(const tal_t *ctx,
struct wallet *wallet,
u64 lastpay_index,
void (*cb)(const struct invoice *, void*),
void *cbarg);
/**
* wallet_invoice_waitone - Wait for a specific invoice to be paid,
* deleted, or expired.
*
* @ctx - the owner of the callback. If the owner is freed,
* the callback is cancelled.
* @wallet - the wallet to query.
* @invoice - the invoice to wait on.
* @cb - the callback to invoice. If invoice is already paid
* or expired, this is called immediately, otherwise it is
* called during an invoices_resolve or invoices_delete call.
* If the invoice was deleted, the callback is given a NULL
* invoice.
* @cbarg - the callback data.
*
*/
void wallet_invoice_waitone(const tal_t *ctx,
struct wallet *wallet,
struct invoice invoice,
void (*cb)(const struct invoice *, void*),
void *cbarg);
/**
* wallet_invoice_details - Get the invoice_details of an invoice.
*
* @ctx - the owner of the label and msatoshi fields returned.
* @wallet - the wallet to query.
* @invoice - the invoice to get details on.
* @return pointer to the invoice details allocated off of `ctx`.