← Watch feed
bwatch: add skeleton and makefile
Public commit record
68/100 · Adequate
What the developer wrote
Authored by Sangbida Chaudhuri
bwatch: add skeleton and makefile
bwatch is an async block scanner that consumes blocks from bcli or any
other bitcoind interface and communicates with lightningd by sending
it updates. In this commit we're only introducing the plugin and some
files that we will populate in future commits.
Changelog-Added: bwatch plugin, this is to handle block processing outside of lightningd. Not yet hooked up to lightningd.
✓ Descriptive subject✓ Names a concrete action or component✓ Provides detailed explanatory context
What changed, and why it matters
This commit adds a brand-new, empty plugin called 'bwatch' to the Core Lightning build system. It contains only placeholder files, a basic plugin entry point, and no actual block-scanning logic. It is not yet connected to the main lightningd process. There is no security issue here—this is just the first scaffolding commit for a future feature.
Recommended action
No security action required. Treat as routine feature scaffolding. Review the follow-up commits that populate bwatch_interface, bwatch_scanner, and bwatch_store for actual security-relevant behavior once they land.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff introduces plugins/bwatch/ with skeleton C/H files (bwatch.c, bwatch_interface.c, bwatch_scanner.c, bwatch_store.c and their headers) and wires them into plugins/Makefile. bwatch.c registers a plugin_main with an empty command table and a single option ‘bwatch-poll-interval’ defaulting to 30000 ms. The headers explicitly state that all functional logic (watch hash tables, matchers, notifications, RPC commands, persistence) will be added in later commits. No network-facing, cryptographic, or privilege-sensitive code is present.
Changed components
plugins/Makefileplugins/bwatch/bwatch.cplugins/bwatch/bwatch.hplugins/bwatch/bwatch_interface.cplugins/bwatch/bwatch_interface.hplugins/bwatch/bwatch_scanner.cplugins/bwatch/bwatch_scanner.hplugins/bwatch/bwatch_store.cplugins/bwatch/bwatch_store.hInspect captured patch +128 / −1
diff --git a/plugins/Makefile b/plugins/Makefile
index cc3cf0db..866b2d47 100644
--- a/plugins/Makefile
+++ b/plugins/Makefile
@@ -17,6 +17,16 @@ PLUGIN_TXPREPARE_OBJS := $(PLUGIN_TXPREPARE_SRC:.c=.o)
PLUGIN_BCLI_SRC := plugins/bcli.c
PLUGIN_BCLI_OBJS := $(PLUGIN_BCLI_SRC:.c=.o)
+PLUGIN_BWATCH_SRC := plugins/bwatch/bwatch.c \
+ plugins/bwatch/bwatch_store.c \
+ plugins/bwatch/bwatch_scanner.c \
+ plugins/bwatch/bwatch_interface.c
+PLUGIN_BWATCH_HEADER := plugins/bwatch/bwatch.h \
+ plugins/bwatch/bwatch_store.h \
+ plugins/bwatch/bwatch_scanner.h \
+ plugins/bwatch/bwatch_interface.h
+PLUGIN_BWATCH_OBJS := $(PLUGIN_BWATCH_SRC:.c=.o)
+
PLUGIN_COMMANDO_SRC := plugins/commando.c
PLUGIN_COMMANDO_OBJS := $(PLUGIN_COMMANDO_SRC:.c=.o)
@@ -82,6 +92,7 @@ PLUGIN_ALL_SRC := \
$(PLUGIN_AUTOCLEAN_SRC) \
$(PLUGIN_chanbackup_SRC) \
$(PLUGIN_BCLI_SRC) \
+ $(PLUGIN_BWATCH_SRC) \
$(PLUGIN_COMMANDO_SRC) \
$(PLUGIN_FUNDER_SRC) \
$(PLUGIN_TOPOLOGY_SRC) \
@@ -102,12 +113,14 @@ PLUGIN_ALL_HEADER := \
$(PLUGIN_FUNDER_HEADER) \
$(PLUGIN_PAY_LIB_HEADER) \
$(PLUGIN_OFFERS_HEADER) \
- $(PLUGIN_SPENDER_HEADER)
+ $(PLUGIN_SPENDER_HEADER) \
+ $(PLUGIN_BWATCH_HEADER)
C_PLUGINS := \
plugins/autoclean \
plugins/chanbackup \
plugins/bcli \
+ plugins/bwatch/bwatch \
plugins/commando \
plugins/funder \
plugins/topology \
@@ -185,6 +198,12 @@ plugins/exposesecret: $(PLUGIN_EXPOSESECRET_OBJS) $(PLUGIN_LIB_OBJS) libcommon.a
plugins/bcli: $(PLUGIN_BCLI_OBJS) $(PLUGIN_LIB_OBJS) libcommon.a
+plugins/bwatch/bwatch.o: $(PLUGIN_BWATCH_HEADER)
+plugins/bwatch/bwatch_store.o: $(PLUGIN_BWATCH_HEADER)
+plugins/bwatch/bwatch_scanner.o: $(PLUGIN_BWATCH_HEADER)
+plugins/bwatch/bwatch_interface.o: $(PLUGIN_BWATCH_HEADER)
+plugins/bwatch/bwatch: $(PLUGIN_BWATCH_OBJS) $(PLUGIN_LIB_OBJS) libcommon.a
+
plugins/keysend: $(PLUGIN_KEYSEND_OBJS) $(PLUGIN_LIB_OBJS) $(PLUGIN_PAY_LIB_OBJS) libcommon.a
$(PLUGIN_KEYSEND_OBJS): $(PLUGIN_PAY_LIB_HEADER) libcommon.a
diff --git a/plugins/bwatch/bwatch.c b/plugins/bwatch/bwatch.c
new file mode 100644
index 00000000..0c3935a8
--- /dev/null
+++ b/plugins/bwatch/bwatch.c
@@ -0,0 +1,44 @@
+#include "config.h"
+#include <ccan/array_size/array_size.h>
+#include <plugins/bwatch/bwatch.h>
+#include <plugins/bwatch/bwatch_interface.h>
+#include <plugins/bwatch/bwatch_scanner.h>
+#include <plugins/bwatch/bwatch_store.h>
+
+struct bwatch *bwatch_of(struct plugin *plugin)
+{
+ return plugin_get_data(plugin, struct bwatch);
+}
+
+static const char *init(struct command *cmd,
+ const char *buf UNUSED,
+ const jsmntok_t *config UNUSED)
+{
+ struct bwatch *bwatch = bwatch_of(cmd->plugin);
+
+ bwatch->plugin = cmd->plugin;
+ return NULL;
+}
+
+static const struct plugin_command commands[] = {
+ /* Subsequent commits register addwatch / delwatch / listwatch here. */
+};
+
+int main(int argc, char *argv[])
+{
+ struct bwatch *bwatch;
+
+ setup_locale();
+ bwatch = tal(NULL, struct bwatch);
+ bwatch->poll_interval_ms = 30000;
+
+ plugin_main(argv, init, take(bwatch), PLUGIN_RESTARTABLE, true, NULL,
+ commands, ARRAY_SIZE(commands),
+ NULL, 0,
+ NULL, 0,
+ NULL, 0,
+ plugin_option("bwatch-poll-interval", "int",
+ "Milliseconds between chain polls (default: 30000)",
+ u32_option, u32_jsonfmt, &bwatch->poll_interval_ms),
+ NULL);
+}
diff --git a/plugins/bwatch/bwatch.h b/plugins/bwatch/bwatch.h
new file mode 100644
index 00000000..f307e09e
--- /dev/null
+++ b/plugins/bwatch/bwatch.h
@@ -0,0 +1,21 @@
+#ifndef LIGHTNING_PLUGINS_BWATCH_BWATCH_H
+#define LIGHTNING_PLUGINS_BWATCH_BWATCH_H
+
+#include "config.h"
+#include <plugins/libplugin.h>
+
+/* Main bwatch state.
+ *
+ * bwatch is an out-of-process block scanner: it polls bitcoind, parses each
+ * new block, and notifies lightningd (via the watchman RPCs) about chain
+ * activity that lightningd has registered watches for. Subsequent commits
+ * add the watch hash tables, block history, and polling timer fields. */
+struct bwatch {
+ struct plugin *plugin;
+ u32 poll_interval_ms;
+};
+
+/* Helper: retrieve the bwatch state from a plugin handle. */
+struct bwatch *bwatch_of(struct plugin *plugin);
+
+#endif /* LIGHTNING_PLUGINS_BWATCH_BWATCH_H */
diff --git a/plugins/bwatch/bwatch_interface.c b/plugins/bwatch/bwatch_interface.c
new file mode 100644
index 00000000..aba4a221
--- /dev/null
+++ b/plugins/bwatch/bwatch_interface.c
@@ -0,0 +1,2 @@
+#include "config.h"
+#include <plugins/bwatch/bwatch_interface.h>
diff --git a/plugins/bwatch/bwatch_interface.h b/plugins/bwatch/bwatch_interface.h
new file mode 100644
index 00000000..944a66f0
--- /dev/null
+++ b/plugins/bwatch/bwatch_interface.h
@@ -0,0 +1,12 @@
+#ifndef LIGHTNING_PLUGINS_BWATCH_BWATCH_INTERFACE_H
+#define LIGHTNING_PLUGINS_BWATCH_BWATCH_INTERFACE_H
+
+#include "config.h"
+#include <plugins/bwatch/bwatch.h>
+
+/* Outward-facing interface from bwatch to lightningd.
+ *
+ * Subsequent commits add the watch_found / watch_revert / block_processed
+ * notifications and the addwatch / delwatch / listwatch RPC commands. */
+
+#endif /* LIGHTNING_PLUGINS_BWATCH_BWATCH_INTERFACE_H */
diff --git a/plugins/bwatch/bwatch_scanner.c b/plugins/bwatch/bwatch_scanner.c
new file mode 100644
index 00000000..9eff5964
--- /dev/null
+++ b/plugins/bwatch/bwatch_scanner.c
@@ -0,0 +1,2 @@
+#include "config.h"
+#include <plugins/bwatch/bwatch_scanner.h>
diff --git a/plugins/bwatch/bwatch_scanner.h b/plugins/bwatch/bwatch_scanner.h
new file mode 100644
index 00000000..ac4e62d1
--- /dev/null
+++ b/plugins/bwatch/bwatch_scanner.h
@@ -0,0 +1,12 @@
+#ifndef LIGHTNING_PLUGINS_BWATCH_BWATCH_SCANNER_H
+#define LIGHTNING_PLUGINS_BWATCH_BWATCH_SCANNER_H
+
+#include "config.h"
+#include <plugins/bwatch/bwatch.h>
+
+/* Block scanning layer for bwatch.
+ *
+ * Subsequent commits add per-watch-type matchers that walk a block's
+ * transactions and fire watch_found notifications back to lightningd. */
+
+#endif /* LIGHTNING_PLUGINS_BWATCH_BWATCH_SCANNER_H */
diff --git a/plugins/bwatch/bwatch_store.c b/plugins/bwatch/bwatch_store.c
new file mode 100644
index 00000000..2d7742e2
--- /dev/null
+++ b/plugins/bwatch/bwatch_store.c
@@ -0,0 +1,2 @@
+#include "config.h"
+#include <plugins/bwatch/bwatch_store.h>
diff --git a/plugins/bwatch/bwatch_store.h b/plugins/bwatch/bwatch_store.h
new file mode 100644
index 00000000..566c0ff8
--- /dev/null
+++ b/plugins/bwatch/bwatch_store.h
@@ -0,0 +1,13 @@
+#ifndef LIGHTNING_PLUGINS_BWATCH_BWATCH_STORE_H
+#define LIGHTNING_PLUGINS_BWATCH_BWATCH_STORE_H
+
+#include "config.h"
+#include <plugins/bwatch/bwatch.h>
+
+/* Block-history and watch storage layer for bwatch.
+ *
+ * Subsequent commits populate this with hash tables for each watch type
+ * (scriptpubkey, outpoint, scid, blockdepth) plus the lightningd datastore
+ * persistence helpers. */
+
+#endif /* LIGHTNING_PLUGINS_BWATCH_BWATCH_STORE_H */
Risk score
Our methodology →Why this scored 15/100
Human-validated context
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
No validated notes yet.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.