cln-plugin 0.7.0

A CLN plugin library. Write your plugin in Rust.
Documentation 
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

#ifndef LIGHTNING_PLUGINS_BWATCH_BWATCH_H
#define LIGHTNING_PLUGINS_BWATCH_BWATCH_H

#include "config.h"
#include <bitcoin/block.h>
#include <bitcoin/short_channel_id.h>
#include <bitcoin/tx.h>
#include <plugins/libplugin.h>
#include <wire/wire.h>

/* Forward declare hash table types (defined in bwatch_store.h) */
struct scriptpubkey_watches;
struct outpoint_watches;
struct scid_watches;
struct blockdepth_watches;

/* Timer handle returned by global_timer; defined in libplugin. */
struct plugin_timer;

/* Wire-format block record stored in lightningd's datastore.
 * Defined by bwatch_wiregen.h; forward-declared here to avoid pulling
 * the generated header into every consumer of bwatch.h. */
struct block_record_wire;

/* Watch type discriminator. */
enum watch_type {
	WATCH_SCRIPTPUBKEY,
	WATCH_OUTPOINT,
	WATCH_SCID,
	WATCH_BLOCKDEPTH,
};

/* Scriptpubkey wrapper: tal-allocated bytes don't carry a length, so we
 * keep them in a struct with an explicit length for hashing/equality. */
struct scriptpubkey {
	const u8 *script;
	size_t len;
};

/* A single watch: one key plus the set of owner ids that registered it. */
struct watch {
	enum watch_type type;
	u32 start_block;
	wirestring **owners;
	union {
		struct scriptpubkey scriptpubkey;
		struct bitcoin_outpoint outpoint;
		struct short_channel_id scid;
	} key;
};

/* Main bwatch state.
 *
 * The four watch hash tables are typed (see bwatch_store.h) so each
 * lookup hits the right key shape (script bytes / outpoint / scid /
 * confirm-height) without dispatching on type at every call site. */
struct bwatch {
	struct plugin *plugin;
	u32 current_height;
	struct bitcoin_blkid current_blockhash;
	/* Oldest first, most recent last. Used to replay a reorg by
	 * peeling tips off until the parent hash matches the new chain. */
	struct block_record_wire *block_history;

	struct scriptpubkey_watches *scriptpubkey_watches;
	struct outpoint_watches *outpoint_watches;
	struct scid_watches *scid_watches;
	struct blockdepth_watches *blockdepth_watches;

	/* Active poll timer; rescheduled at the end of every poll cycle. */
	struct plugin_timer *poll_timer;
	u32 poll_interval_ms;

	/* Opt-in: bwatch is loaded but stays inert (no chain polling, no
	 * watch processing) unless the user passes --experimental-bwatch. */
	bool experimental;
};

/* Helper: get last block_history (or NULL) */
const struct block_record_wire *bwatch_last_block(const struct bwatch *bwatch);

/* Helper: retrieve the bwatch state from a plugin handle. */
struct bwatch *bwatch_of(struct plugin *plugin);

/* Timer callback: kicks off one chain-poll cycle (getchaininfo →
 * getrawblockbyheight → persist → reschedule).  Exposed so other modules
 * can schedule a poll from their own callbacks. */
struct command_result *bwatch_poll_chain(struct command *cmd, void *unused);

/* Pop the current tip from in-memory + persisted history.  Exposed so the
 * startup chaininfo path can roll back when bitcoind's chain is shorter
 * than what we have stored. */
void bwatch_remove_tip(struct command *cmd, struct bwatch *bwatch);

/* Per-rescan cursor: which block we're on and how far to go. */
struct rescan_state {
	const struct watch *watch;	/* NULL = rescan all watches, non-NULL = single watch */
	u32 current_block;		/* Next block to fetch */
	u32 target_block;		/* Stop after this block */
};

/* Replay historical blocks for `w` (or all watches if w==NULL) from
 * `start_block` up to `target_block` inclusive.  Runs asynchronously:
 * fetch -> process -> fetch the next block. */
void bwatch_start_rescan(struct command *cmd,
			 const struct watch *w,
			 u32 start_block,
			 u32 target_block);

#endif /* LIGHTNING_PLUGINS_BWATCH_BWATCH_H */