lightning-splice_update -- Command to initiate a channel to a peer

SYNOPSIS

(WARNING: experimental-splicing only)

splice_update channel_id psbt

DESCRIPTION

Command added in v23.08.

splice_update is a low level RPC command which updates the active channel splice associated with channel_id.

splice_update must be called repeatidly until the result commitments_secured is true. Each time splice_update is called, it will return a new PSBT that may have changes. In the simplest case, you take the returned psbt and pass it back into splice_update for the incoming psbt field.

For more complex use cases, you may modify the psbt both before calling splice_update and inbetween subsequent calls until commitments_secured is true. After which point you can no long make modifications to the PSBT (beyond signing, which comes later with splice_signed).

Each splice_update result may include changes to the PSBT specified by your channel peer. You can review these changes between calls to splice_update to perform additional validation or strategy adjustment.

Typically, splice_update will return commitments_secured true after one call but you should assume it will need multiple calls.

channel_id (hash): The channel id of the channel to be spliced.
psbt (string): The base 64 encoded PSBT returned from splice_init with any changes added by the user.

USAGE

Here is an example way to call splice_update

RESULT={"commitments_secured":false}
while [[ $(echo $RESULT | jq -r ".commitments_secured") == "false" ]]
do
  RESULT=$(lightning-cli splice_update $CHANNEL_ID $PSBT)
  PSBT=$(echo $RESULT | jq -r ".psbt")
  echo $RESULT
done

Before each call to splice_update you have the opportunity to make additional changes.

Here is an example set of splice commands that will splice in 100,000 sats to the first channel that comes out of listpeerchannels.

The example assumes you already have at least one confirmed channel.

1: Get the channel id of the first channel.

CHANNEL_ID=$(echo $(lightning-cli listpeerchannels) | jq -r ".channels[0].channel_id")

2: Get the PSBT from fundpsbt.

INITIALPSBT=$(echo $(lightning-cli fundpsbt -k satoshi=100000sat feerate=urgent startweight=800 excess_as_change=true) | jq -r ".psbt")

3: Initiate the splice by passing channel id and initialpsbt received from above steps.

PSBT_SPLICE_INIT=$(echo $(lightning-cli splice_init $CHANNEL_ID 100000 $INITIALPSBT) | jq -r ".psbt")

4: Update PSBTs with the splice_update command.

RESULT={"commitments_secured":false}
while [[ $(echo $RESULT | jq -r ".commitments_secured") == "false" ]]
do
  PSBT_SPLICE_UPDATE=$(echo $(lightning-cli splice_update $CHANNEL_ID $PSBT_SPLICE_INIT) | jq -r ".psbt")
  echo $PSBT_SPLICE_UPDATE
done

5: Sign the updated PSBT.

SIGNPSBT=$(echo $(lightning-cli signpsbt -k psbt="$PSBT_SPLICE_UPDATE") | jq -r ".signed_psbt")

6: Finally, call splice_signed with channel id and signed PSBT parameters.

lightning-cli splice_signed $CHANNEL_ID $SIGNPSBT

RETURN VALUE

On success, an object is returned, containing:

psbt (string): The (incomplete) PSBT of the splice transaction.
commitments_secured (boolean): Whether or not the commitments were secured.
signatures_secured (boolean): whether or not the peer sent us their signatures for this splice (added v24.11)

AUTHOR

Dusty <@dusty\_daemon> is mainly responsible.

RESOURCES

Main web site: https://github.com/ElementsProject/lightning

EXAMPLES

Example 1:

Request:

lightning-cli splice_update -k "channel_id"="channelid0780000780000780000780000780000780000780000780000780000" "psbt"="cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000"

{
  "id": "example:splice_update#1",
  "method": "splice_update",
  "params": {
    "channel_id": "channelid0780000780000780000780000780000780000780000780000780000",
    "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000"
  }
}

Response:

{
  "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200",
  "commitments_secured": true,
  "signatures_secured": true
}

Example 2: