Skip to content

Funding transaction withholding support #8546

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 15 commits into
base: master
Choose a base branch
from
Open

Funding transaction withholding support #8546

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
d539b4e
lightningd: allow another gossip state transition.
rustyrussell Oct 22, 2025
1316ec3
pytest: test case where we crash before bitcoind gets the opening tx.
rustyrussell Oct 22, 2025
daa0729
lightningd: save funding_psbt in channel, database.
rustyrussell Oct 22, 2025
3ccb45c
sendpsbt: update channel psbts if this is a channel PSBT.
rustyrussell Oct 22, 2025
097c8e5
lightningd: re-xmit funding txs on startup.
rustyrussell Oct 22, 2025
7d0b822
pytest: test failure if we crash after fundchannel_complete but befor…
rustyrussell Oct 22, 2025
7900ea9
lightningd: expose funding PSBT (if we have it) in JSON API.
rustyrussell Oct 22, 2025
43c97fe
spender: look for unsigned PSBT on awaiting channels on startup, and …
rustyrussell Oct 22, 2025
36a767b
lightningd: save funding PSBT to database if we're to withhold it.
rustyrussell Oct 22, 2025
59af586
lightningd: add withheld flag to listpeerchannels and listclosedchann…
rustyrussell Oct 22, 2025
26cfd2b
lightningd: immediately close without broadcast whenever we close a w…
rustyrussell Oct 22, 2025
3bfce29
lightningd: don't rebroadcast withheld channels' funding_psbt on rest…
rustyrussell Oct 22, 2025
a9285d3
lightningd: add withhold option to fundchannel_complete.
rustyrussell Oct 22, 2025
1a7a26a
lightningd: remove withheld flag when we see sendpsbt.
rustyrussell Oct 22, 2025
bbc860d
pytest: test withhold parameter to fundchannel_complete.
rustyrussell Oct 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 27 additions & 2 deletions .msggen.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1658,7 +1658,8 @@
},
"FundchannelCompleteRequest": {
"FundChannel_Complete.id": 1,
"FundChannel_Complete.psbt": 2
"FundChannel_Complete.psbt": 2,
"FundChannel_Complete.withhold": 3
},
"FundchannelCompleteResponse": {
"FundChannel_Complete.channel_id": 1,
Expand Down Expand Up @@ -2035,8 +2036,10 @@
"ListClosedChannels.closedchannels[].funding_fee_paid_msat": 15,
"ListClosedChannels.closedchannels[].funding_fee_rcvd_msat": 16,
"ListClosedChannels.closedchannels[].funding_outnum": 13,
"ListClosedChannels.closedchannels[].funding_psbt": 26,
"ListClosedChannels.closedchannels[].funding_pushed_msat": 17,
"ListClosedChannels.closedchannels[].funding_txid": 12,
"ListClosedChannels.closedchannels[].funding_withheld": 27,
"ListClosedChannels.closedchannels[].last_commitment_fee_msat": 23,
"ListClosedChannels.closedchannels[].last_commitment_txid": 22,
"ListClosedChannels.closedchannels[].last_stable_connection": 25,
Expand Down Expand Up @@ -2804,8 +2807,10 @@
"ListPeerChannels.channels[].funding.fee_paid_msat": 4,
"ListPeerChannels.channels[].funding.fee_rcvd_msat": 5,
"ListPeerChannels.channels[].funding.local_funds_msat": 2,
"ListPeerChannels.channels[].funding.psbt": 6,
"ListPeerChannels.channels[].funding.pushed_msat": 1,
"ListPeerChannels.channels[].funding.remote_funds_msat": 3
"ListPeerChannels.channels[].funding.remote_funds_msat": 3,
"ListPeerChannels.channels[].funding.withheld": 7
},
"ListpeerchannelsChannelsHtlcs": {
"ListPeerChannels.channels[].htlcs[].amount_msat": 3,
Expand Down Expand Up @@ -7172,6 +7177,10 @@
"added": "pre-v0.10.1",
"deprecated": null
},
"FundChannel_Complete.withhold": {
"added": "v25.12",
"deprecated": null
},
"FundChannel_Start": {
"added": "pre-v0.10.1",
"deprecated": null
Expand Down Expand Up @@ -8204,6 +8213,10 @@
"added": "pre-v0.10.1",
"deprecated": null
},
"ListClosedChannels.closedchannels[].funding_psbt": {
"added": "v25.12",
"deprecated": null
},
"ListClosedChannels.closedchannels[].funding_pushed_msat": {
"added": "pre-v0.10.1",
"deprecated": null
Expand All @@ -8212,6 +8225,10 @@
"added": "pre-v0.10.1",
"deprecated": null
},
"ListClosedChannels.closedchannels[].funding_withheld": {
"added": "v25.12",
"deprecated": null
},
"ListClosedChannels.closedchannels[].last_commitment_fee_msat": {
"added": "pre-v0.10.1",
"deprecated": null
Expand Down Expand Up @@ -10196,6 +10213,10 @@
"added": "v23.02",
"deprecated": null
},
"ListPeerChannels.channels[].funding.psbt": {
"added": "v25.12",
"deprecated": null
},
"ListPeerChannels.channels[].funding.pushed_msat": {
"added": "v23.02",
"deprecated": null
Expand All @@ -10204,6 +10225,10 @@
"added": "v23.02",
"deprecated": null
},
"ListPeerChannels.channels[].funding.withheld": {
"added": "v25.12",
"deprecated": null
},
"ListPeerChannels.channels[].funding_outnum": {
"added": "v23.02",
"deprecated": null
Expand Down
5 changes: 5 additions & 0 deletions cln-grpc/proto/node.proto
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions cln-grpc/src/convert.rs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 10 additions & 0 deletions cln-rpc/src/model.rs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

40 changes: 39 additions & 1 deletion contrib/msggen/msggen/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13092,6 +13092,13 @@
"description": [
"Transaction to use for funding (does not need to be signed but must be otherwise complete)."
]
},
"withhold": {
"type": "boolean",
"added": "v25.12",
"description": [
"Mark this channel 'withheld' so we know we haven't broadcast the funding transaction. If the channel is closed before we call `sendpsbt` on this psbt, it will simply be closed immediately."
]
}
}
},
Expand Down Expand Up @@ -17348,6 +17355,8 @@
"total_htlcs_sent",
"funding_txid",
"funding_outnum",
"funding_psbt",
"funding_withheld",
"leased",
"final_to_us_msat",
"min_to_us_msat",
Expand Down Expand Up @@ -17493,6 +17502,20 @@
"The 0-based output number of the funding transaction which opens the channel."
]
},
"funding_psbt": {
"type": "string",
"added": "v25.12",
"description": [
"The PSBT (may be non-final or unsigned) we should use to open the channel, if any"
]
},
"funding_withheld": {
"type": "boolean",
"added": "v25.12",
"description": [
"True if we have not broadcast the funding transaction (see fundchannel_complete)."
]
},
"leased": {
"type": "boolean",
"description": [
Expand Down Expand Up @@ -23050,6 +23073,7 @@
"type": "object",
"additionalProperties": false,
"required": [
"psbt",
"local_funds_msat",
"remote_funds_msat"
],
Expand Down Expand Up @@ -23083,6 +23107,20 @@
"description": [
"Amount we were paid by peer at open."
]
},
"psbt": {
"type": "string",
"added": "v25.12",
"description": [
"The PSBT (may be non-final or unsigned) we should use to open the channel, if any. This is initially from `fundchannel_complete`, but will be updated with if `sendpsbt` is called with an updated PSBT."
]
},
"withheld": {
"type": "boolean",
"added": "v25.12",
"description": [
"True if `fundchannel_complete` told us it will not broadcast the funding transaction (so we know not to bother with any other onchain transactions in the case of this channel). This is set to false if `sendpsbt` is send on the above PSBT."
]
}
}
},
Expand Down Expand Up @@ -31056,7 +31094,7 @@
"rpc": "sendpsbt",
"title": "Command to finalize, extract and send a partially signed bitcoin transaction (PSBT).",
"description": [
"The **sendpsbt** is a low-level RPC command which sends a fully-signed PSBT."
"The **sendpsbt** is a low-level RPC command which sends a fully-signed PSBT. If the PSBT is the same one promised by a channel (via fundchannel_complete) it will also be associated with that channel and re-transmitted if necessary on restart."
],
"request": {
"required": [
Expand Down
3 changes: 2 additions & 1 deletion contrib/pyln-client/pyln/client/lightning.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -847,13 +847,14 @@ def fundchannel_cancel(self, node_id):
}
return self.call("fundchannel_cancel", payload)

def fundchannel_complete(self, node_id, psbt):
def fundchannel_complete(self, node_id, psbt, withhold=True):
"""
Complete channel establishment with {id}, using {psbt}.
"""
payload = {
"id": node_id,
"psbt": psbt,
"withhold": withhold,
}
return self.call("fundchannel_complete", payload)

Expand Down
1,568 changes: 784 additions & 784 deletions contrib/pyln-grpc-proto/pyln/grpc/node_pb2.py
View file
Open in desktop

Large diffs are not rendered by default.

4 changes: 4 additions & 0 deletions contrib/pyln-testing/pyln/testing/grpc2py.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -915,8 +915,10 @@ def listpeerchannels_channels_funding2py(m):
"fee_paid_msat": amount2msat(m.fee_paid_msat), # PrimitiveField in generate_composite
"fee_rcvd_msat": amount2msat(m.fee_rcvd_msat), # PrimitiveField in generate_composite
"local_funds_msat": amount2msat(m.local_funds_msat), # PrimitiveField in generate_composite
"psbt": m.psbt, # PrimitiveField in generate_composite
"pushed_msat": amount2msat(m.pushed_msat), # PrimitiveField in generate_composite
"remote_funds_msat": amount2msat(m.remote_funds_msat), # PrimitiveField in generate_composite
"withheld": m.withheld, # PrimitiveField in generate_composite
})


Expand Down Expand Up @@ -1072,8 +1074,10 @@ def listclosedchannels_closedchannels2py(m):
"funding_fee_paid_msat": amount2msat(m.funding_fee_paid_msat), # PrimitiveField in generate_composite
"funding_fee_rcvd_msat": amount2msat(m.funding_fee_rcvd_msat), # PrimitiveField in generate_composite
"funding_outnum": m.funding_outnum, # PrimitiveField in generate_composite
"funding_psbt": m.funding_psbt, # PrimitiveField in generate_composite
"funding_pushed_msat": amount2msat(m.funding_pushed_msat), # PrimitiveField in generate_composite
"funding_txid": hexlify(m.funding_txid), # PrimitiveField in generate_composite
"funding_withheld": m.funding_withheld, # PrimitiveField in generate_composite
"last_commitment_fee_msat": amount2msat(m.last_commitment_fee_msat), # PrimitiveField in generate_composite
"last_commitment_txid": hexlify(m.last_commitment_txid), # PrimitiveField in generate_composite
"last_stable_connection": m.last_stable_connection, # PrimitiveField in generate_composite
Expand Down
7 changes: 7 additions & 0 deletions doc/schemas/fundchannel_complete.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,13 @@
"description": [
"Transaction to use for funding (does not need to be signed but must be otherwise complete)."
]
},
"withhold": {
"type": "boolean",
"added": "v25.12",
"description": [
"Mark this channel 'withheld' so we know we haven't broadcast the funding transaction. If the channel is closed before we call `sendpsbt` on this psbt, it will simply be closed immediately."
]
}
}
},
Expand Down
16 changes: 16 additions & 0 deletions doc/schemas/listclosedchannels.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@
"total_htlcs_sent",
"funding_txid",
"funding_outnum",
"funding_psbt",
"funding_withheld",
"leased",
"final_to_us_msat",
"min_to_us_msat",
Expand Down Expand Up @@ -188,6 +190,20 @@
"The 0-based output number of the funding transaction which opens the channel."
]
},
"funding_psbt": {
"type": "string",
"added": "v25.12",
"description": [
"The PSBT (may be non-final or unsigned) we should use to open the channel, if any"
]
},
"funding_withheld": {
"type": "boolean",
"added": "v25.12",
"description": [
"True if we have not broadcast the funding transaction (see fundchannel_complete)."
]
},
"leased": {
"type": "boolean",
"description": [
Expand Down
15 changes: 15 additions & 0 deletions doc/schemas/listpeerchannels.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -469,6 +469,7 @@
"type": "object",
"additionalProperties": false,
"required": [
"psbt",
"local_funds_msat",
"remote_funds_msat"
],
Expand Down Expand Up @@ -502,6 +503,20 @@
"description": [
"Amount we were paid by peer at open."
]
},
"psbt": {
"type": "string",
"added": "v25.12",
"description": [
"The PSBT (may be non-final or unsigned) we should use to open the channel, if any. This is initially from `fundchannel_complete`, but will be updated with if `sendpsbt` is called with an updated PSBT."
]
},
"withheld": {
"type": "boolean",
"added": "v25.12",
"description": [
"True if `fundchannel_complete` told us it will not broadcast the funding transaction (so we know not to bother with any other onchain transactions in the case of this channel). This is set to false if `sendpsbt` is send on the above PSBT."
]
}
}
},
Expand Down
2 changes: 1 addition & 1 deletion doc/schemas/sendpsbt.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"rpc": "sendpsbt",
"title": "Command to finalize, extract and send a partially signed bitcoin transaction (PSBT).",
"description": [
"The **sendpsbt** is a low-level RPC command which sends a fully-signed PSBT."
"The **sendpsbt** is a low-level RPC command which sends a fully-signed PSBT. If the PSBT is the same one promised by a channel (via fundchannel_complete) it will also be associated with that channel and re-transmitted if necessary on restart."
],
"request": {
"required": [
Expand Down
2 changes: 1 addition & 1 deletion lightningd/bitcoind.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ void bitcoind_sendrawtx_(const tal_t *ctx,
const char *id_prefix TAKES,
const char *hextx,
bool allowhighfees,
void (*cb)(struct bitcoind *bitcoind,
void (*cb)(struct bitcoind *,
bool success, const char *msg, void *),
void *arg);
#define bitcoind_sendrawtx(ctx, bitcoind_, id_prefix, hextx, allowhighfees, cb, arg) \
Expand Down
Loading
Loading