Informational 13 Bitcoin Committed Mar 17, 2026 · 03:24 UTC

common: add a new WILL_SEND flag to HTLC states.

795b4bc7 View source ↗

Public commit record

What the developer wrote

Authored by Rusty Russell

68/100 · Adequate

common: add a new WILL_SEND flag to HTLC states.

This is useful for splicing: given an HTLC state, do we need to send
more messages to get it into a non-pending state?

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

✓ Descriptive subject✓ Names a concrete action or component✓ Provides detailed explanatory context

The short version

What changed, and why it matters

This commit is a straightforward internal code change in Core Lightning's bookkeeping for payment commitments (HTLCs). It adds a new flag called WILL_SEND to track whether more messages still need to be exchanged before a payment update is fully settled. The change is described by the developer as groundwork for the 'splicing' feature and contains no obvious security fix or vulnerability.

Recommended action

No security action required. Treat as normal feature/refactoring commit. Review follow-up commits that actually consume HTLC_F_WILL_SEND for splicing logic.

Security signals we found

No security-relevant keywords in commit title or message

No bug fix, bounds check, input validation, or memory-safety change visible

New flag is purely additive and not used by any logic in the diff

Commit explicitly states it is infrastructure for the splicing feature

Technical analysis

Evidence from the diff

The patch introduces HTLC_F_WILL_SEND (0x20) and shifts the per-side flag layout from 5 bits to 6 bits, moving HTLC_ADDING/HTLC_REMOVING masks accordingly. It updates the per-state bit tables in common/htlc_state.c to set WILL_SEND on states where additional protocol messages are still pending. No logic consuming this new flag is present in the diff, and no existing behavior is changed beyond the flag definitions.

Changed components

common/htlc.hcommon/htlc_state.c

Inspect captured patch +51 / −19

diff --git a/common/htlc.h b/common/htlc.h
index b933e07c..19e62b4a 100644
--- a/common/htlc.h
+++ b/common/htlc.h
@@ -12,8 +12,8 @@ enum side {
 };
 
 /* What are we doing: adding or removing? */
-#define HTLC_ADDING			0x400
-#define HTLC_REMOVING			0x800
+#define HTLC_ADDING			0x1000
+#define HTLC_REMOVING			0x2000
 
 /* Uncommitted change is pending */
 #define HTLC_F_PENDING			0x01
@@ -25,21 +25,25 @@ enum side {
 #define HTLC_F_OWNER			0x08
 /* HTLC was ever in a commit_tx */
 #define HTLC_F_WAS_COMMITTED		0x10
+/* We need to send more messages to reach steady state */
+#define HTLC_F_WILL_SEND		0x20
 
 /* Each of the above flags applies to both sides */
-#define HTLC_FLAG(side,flag)		((flag) << ((side) * 5))
+#define HTLC_FLAG(side,flag)		((flag) << ((side) * 6))
 
 #define HTLC_REMOTE_F_PENDING		HTLC_FLAG(REMOTE,HTLC_F_PENDING)
 #define HTLC_REMOTE_F_COMMITTED		HTLC_FLAG(REMOTE,HTLC_F_COMMITTED)
 #define HTLC_REMOTE_F_REVOKED		HTLC_FLAG(REMOTE,HTLC_F_REVOKED)
 #define HTLC_REMOTE_F_OWNER		HTLC_FLAG(REMOTE,HTLC_F_OWNER)
 #define HTLC_REMOTE_F_WAS_COMMITTED	HTLC_FLAG(REMOTE,HTLC_F_WAS_COMMITTED)
+#define HTLC_REMOTE_F_WILL_SEND		HTLC_FLAG(REMOTE,HTLC_F_WILL_SEND)
 
 #define HTLC_LOCAL_F_PENDING		HTLC_FLAG(LOCAL,HTLC_F_PENDING)
 #define HTLC_LOCAL_F_COMMITTED		HTLC_FLAG(LOCAL,HTLC_F_COMMITTED)
 #define HTLC_LOCAL_F_REVOKED		HTLC_FLAG(LOCAL,HTLC_F_REVOKED)
 #define HTLC_LOCAL_F_OWNER		HTLC_FLAG(LOCAL,HTLC_F_OWNER)
 #define HTLC_LOCAL_F_WAS_COMMITTED	HTLC_FLAG(LOCAL,HTLC_F_WAS_COMMITTED)
+#define HTLC_LOCAL_F_WILL_SEND		HTLC_FLAG(LOCAL,HTLC_F_WILL_SEND)
 
 const char *htlc_state_name(enum htlc_state s);
 int htlc_state_flags(enum htlc_state state);
diff --git a/common/htlc_state.c b/common/htlc_state.c
index 52d0edc0..2be0fc90 100644
--- a/common/htlc_state.c
+++ b/common/htlc_state.c
@@ -17,24 +17,31 @@ const char *htlc_state_name(enum htlc_state s)
 /* This is the flags for each state. */
 static const int per_state_bits[] = {
 	[SENT_ADD_HTLC] = HTLC_ADDING + HTLC_LOCAL_F_OWNER
-	+ HTLC_REMOTE_F_PENDING,
+	+ HTLC_REMOTE_F_PENDING
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[SENT_ADD_COMMIT] = HTLC_ADDING + HTLC_LOCAL_F_OWNER
 	+ HTLC_REMOTE_F_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[RCVD_ADD_REVOCATION] = HTLC_ADDING + HTLC_LOCAL_F_OWNER
 	+ HTLC_REMOTE_F_COMMITTED
 	+ HTLC_REMOTE_F_REVOKED
 	+ HTLC_LOCAL_F_PENDING
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[RCVD_ADD_ACK_COMMIT] = HTLC_ADDING + HTLC_LOCAL_F_OWNER
 	+ HTLC_REMOTE_F_COMMITTED
 	+ HTLC_REMOTE_F_REVOKED
 	+ HTLC_LOCAL_F_COMMITTED
 	+ HTLC_LOCAL_F_WAS_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[SENT_ADD_ACK_REVOCATION] = HTLC_LOCAL_F_OWNER
 	+ HTLC_REMOTE_F_COMMITTED
@@ -48,24 +55,31 @@ static const int per_state_bits[] = {
 	+ HTLC_LOCAL_F_PENDING + HTLC_LOCAL_F_COMMITTED
 	+ HTLC_REMOTE_F_COMMITTED
 	+ HTLC_LOCAL_F_WAS_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[RCVD_REMOVE_COMMIT] = HTLC_REMOVING + HTLC_LOCAL_F_OWNER
 	+ HTLC_REMOTE_F_COMMITTED
 	+ HTLC_LOCAL_F_WAS_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[SENT_REMOVE_REVOCATION] = HTLC_REMOVING + HTLC_LOCAL_F_OWNER
 	+ HTLC_REMOTE_F_COMMITTED
 	+ HTLC_LOCAL_F_REVOKED
 	+ HTLC_REMOTE_F_PENDING
 	+ HTLC_LOCAL_F_WAS_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[SENT_REMOVE_ACK_COMMIT] = HTLC_REMOVING + HTLC_LOCAL_F_OWNER
 	+ HTLC_LOCAL_F_REVOKED
 	+ HTLC_LOCAL_F_WAS_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND,
 
 	[RCVD_REMOVE_ACK_REVOCATION] = HTLC_LOCAL_F_OWNER
 	+ HTLC_LOCAL_F_REVOKED
@@ -74,24 +88,31 @@ static const int per_state_bits[] = {
 	+ HTLC_REMOTE_F_WAS_COMMITTED,
 
 	[RCVD_ADD_HTLC] = HTLC_ADDING + HTLC_REMOTE_F_OWNER
-	+ HTLC_LOCAL_F_PENDING,
+	+ HTLC_LOCAL_F_PENDING
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[RCVD_ADD_COMMIT] = HTLC_ADDING + HTLC_REMOTE_F_OWNER
 	+ HTLC_LOCAL_F_COMMITTED
-	+ HTLC_LOCAL_F_WAS_COMMITTED,
+	+ HTLC_LOCAL_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[SENT_ADD_REVOCATION] = HTLC_ADDING + HTLC_REMOTE_F_OWNER
 	+ HTLC_LOCAL_F_COMMITTED
 	+ HTLC_LOCAL_F_REVOKED
 	+ HTLC_REMOTE_F_PENDING
-	+ HTLC_LOCAL_F_WAS_COMMITTED,
+	+ HTLC_LOCAL_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[SENT_ADD_ACK_COMMIT] = HTLC_ADDING + HTLC_REMOTE_F_OWNER
 	+ HTLC_LOCAL_F_COMMITTED
 	+ HTLC_LOCAL_F_REVOKED
 	+ HTLC_REMOTE_F_COMMITTED
 	+ HTLC_LOCAL_F_WAS_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND,
 
 	[RCVD_ADD_ACK_REVOCATION] = HTLC_REMOTE_F_OWNER
 	+ HTLC_LOCAL_F_COMMITTED
@@ -106,24 +127,31 @@ static const int per_state_bits[] = {
 	+ HTLC_LOCAL_F_COMMITTED
 	+ HTLC_REMOTE_F_COMMITTED
 	+ HTLC_LOCAL_F_WAS_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[SENT_REMOVE_COMMIT] = HTLC_REMOVING + HTLC_REMOTE_F_OWNER
 	+ HTLC_LOCAL_F_COMMITTED
 	+ HTLC_LOCAL_F_WAS_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[RCVD_REMOVE_REVOCATION] = HTLC_REMOVING + HTLC_REMOTE_F_OWNER
 	+ HTLC_LOCAL_F_COMMITTED
 	+ HTLC_REMOTE_F_REVOKED
 	+ HTLC_LOCAL_F_PENDING
 	+ HTLC_LOCAL_F_WAS_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_REMOTE_F_WILL_SEND
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[RCVD_REMOVE_ACK_COMMIT] = HTLC_REMOVING + HTLC_REMOTE_F_OWNER
 	+ HTLC_REMOTE_F_REVOKED
 	+ HTLC_LOCAL_F_WAS_COMMITTED
-	+ HTLC_REMOTE_F_WAS_COMMITTED,
+	+ HTLC_REMOTE_F_WAS_COMMITTED
+	+ HTLC_LOCAL_F_WILL_SEND,
 
 	[SENT_REMOVE_ACK_REVOCATION] = HTLC_REMOTE_F_OWNER
 	+ HTLC_REMOTE_F_REVOKED

Risk score

Why this scored 13/100

Our methodology →

Potential impact 0/30

Exploitability 0/25

Stealth signal 0/15

Affected reach 0/15

Confidence 9/10

Evidence quality 4/5

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.

What the developer wrote

What changed, and why it matters

Security signals we found

Evidence from the diff

Changed components

Why this scored 13/100

Community notes

Related watches

contrib: add jaonoctus's signing key

wallet: fixed timestamps for invented bookkeeper deposits

docs: document missing and fix erroneous JSON-RPC error codes