home | help 
LIGHTNING-DEV-SPLICE(7) 				 LIGHTNING-DEV-SPLICE(7)

NAME
     dev-splice -- Command to initiate a channel to a peer

SYNOPSIS
     dev-splice script_or_json [dryrun] [force_feerate] [debug_log] [dev-wetrun]

DESCRIPTION
     Command added in v24.11.

     splice  is the command to move funds into or out of a channel. Multiple ac-
     tions can be combined together resulting in a single  onchain  transaction.
     Funds  may be moved out of a channel and into another in a single batch en-
     abling cross-channel movement.

     *	script_or_json (string): The splice script to execute or json equivilent
     *	dryrun (boolean, optional): Don't execute any actions and output a tran-
	script of what would have been done
     *	force_feerate (boolean, optional): By default splices will fail  if  the
	fee  provided  looks  too  high. This is to protect against accidentally
	setting your fee higher than intended. Set force_feerate to true to skip
	this saftey check
     *	debug_log (boolean, optional): Adds a verbose log of each splice  calcu-
	lation step to the result
     *	dev-wetrun  (boolean,  optional): Executes the splice up until the point
	signatures would be sent and then aborts

RETURN VALUE
     On success, an object is returned, containing:

     *	dryrun (array of strings, optional): The transcript of what  the  script
	would have done:
	*  (string, optional): One action line of the splice script result
     *	psbt (string, optional): The final psbt
     *	tx (string, optional): The final transaction in hex
     *	txid (string, optional): The txid of the final transaction
     *	log  (array  of strings, optional): A verbose log of each step of splice
	calcuations:
	*  (string, optional): A line of detail about splice calcuations

AUTHOR
     Dusty @dusty_daemon is mainly responsible.

SEE ALSO
     lightning-splice_signed(7), lightning-splice_update(7)

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

USAGE
     The primary method is to make a script containing one or  more  splice  ac-
     tions that will be merged into a single transaction. If possible the entire
     operation will be completed and broadcast to the mempool.

     However  if you specified your own inputs using psbt, then the command will
     return a psbt that you must sign and then pass to splice_signed.

     It is required to pass script_or_json.

     It is recommended you first do a dryrun to confirm your  script  does  what
     you expect it to do.

     script The splice script to execute

     dryrun Don't execute any actions and output a transcript of what would have
     been done

     psbt An initial psbt to begin the splice with

     user_provided_sats The amount of sats being contributed by the initial psbt

     force_feerate  By	default  splices will fail if the fee provided looks too
     high.  This is to protect against accidentally setting your fee higher than
     intended.	Set to true to skip this saftey check

     json A json payload of instructions can be passed instead of script

     debug_log Adds a verbose log of each splice calculation step to the result

     dev-wetrun Executes the splice up until the point signatures would be  sent
     and then aborts

     The primary purpose of splice script is to execute all types of splices us-
     ing  a single command. You can perform all these actions manually using the
     lower level api (see splice_init) however this splice command interface  is
     much  simpler  to	use  and it provides some security against signing mali-
     ciously inserted inputs.

SCRIPT
     A splice script is a series of 'segments' that are separated by newlines or
     semicolons. Each segment represents one splice action  which  is  typically
     adding  to  or  removing  from a channel. The funds are designated as going
     into the channel or coming out of the channel by which  side  of  an  arrow
     "->"  the channel identifier is placed on. The amount of funds is placed on
     the other side of the arrow.

     Take this example:

     8338aef0 -> 10000sat

     This is how we take 10,000 sats out of channel 8338aef0.

     To put 10,000 sats into the channel, we make the arrow point into the chan-
     nel like so:

     10000sat -> 8338aef0

     In the last two examples we specified the first 8	digits	of  the  channel
     identifier.  You  can  specify  as  few as 4 digits of the beginning of the
     channel identifier and it will be autocompleted to the matching channel. If
     the code matches more than one channel or node id,  the  script  will  fail
     with an error.

     In  order	to  put funds into a channel however, we need get the funds from
     somewhere. The simplest place to get them is the built in	onchain  wallet.
     The  "wallet"  operator can be placed just like channel identifiers. We can
     take funds out of the wallet like so:

     wallet -> 10000sat

     We can put funds back into the wallet like so:

     10000sat -> wallet

     Now that we know how to take funds out of a wallet, let's combine them into
     an individual script:

     wallet -> 10000sat
     10000sat -> 8338aef0

     The first line withdraws 10,000 sats from the wallet and puts them  in  the
     script's "general script funds." The second line takes 10,000 sats from the
     "general  script funds" and places them into channel 8338aef0. This example
     is called a "splice in."

     In order for this script to work, we need one more thing. Onchain fees must
     be funded from somewhere. The simplest way to pay the fee from the "general
     script funds." If we change the amount going into the channel to a percent-
     age, the fee will automatically be taken from the	"general  script  funds"
     like so:

     wallet -> 10000sat
     100% -> 8338aef0

     When  specifying a percentage instead of an amount, it means take that per-
     centage out of the "general script fund."

     This will take 10,000 sats from the onchain wallet and put that amount less
     any onchain fees into channel 8338aef0. The feerate used will be the node's
     standard opening feerate. In order to use your own feerate you must us  the
     fee operator.

     The fee operator is attached to an amount. If you want to take out extra to
     cover  the  fee, use "+fee" and if you want to reduce the amount being sent
     somewhere use the "-fee" suffix. Take this example:

     wallet -> 10000sat+fee
     10000sat -> 8338aef0

     In this example we add precisely 10,000 sats to channel 8338aef0 and  with-
     draw enough from the wallet to cover the 10,000 sats and the onchain fee.

     To  control  the  amount of fee, you can specify a fee-rate with the use of
     the at "@" symbol after fee. After the at symbol, specify a number of  sats
     to pay per kiloweight (aka. perkw) like so:

     wallet -> 10000sat+fee@300
     10000sat -> 8338aef0

     This example pays a fee rate of 300 sats per thousand weight units. To view
     this amount in other units (ie. sats/vbyte) execute a dryrun of the script.

     Instead  of withdrawing extra from the wallet, we can reduce the amount go-
     ing to channel 8338aef0 using the "-fee" operator like so:

     wallet -> 10000sat
     10000sat-fee -> 8338aef0

     This example withdraws 10,000 sats from the onchain wallet,  pays	the  on-
     chain fee from that amount, and puts the rest into channel 8338aef0.

     You can also specify the feerate here like so:

     wallet -> 10000sat
     10000sat-fee@300 -> 8338aef0

     Now  let's  build	a script that takes funds out of a channel and puts them
     into the onchain wallet:

     8338aef0 -> 10000sat
     100% -> wallet

     By default however, scripts that leave sats in the "general  script  fund,"
     will be automatically sent to the wallet. So the second line is not needed,
     we can simplify the script to:

     8338aef0 -> 10000sat

     We can can also move sats to a specific bitcoin address like so:

     8338aef0 -> 10000sat+fee
     100% -> 1JfbZRwdDHKZmuiZgYArJZhcuuzuw2HuMu

     This  example  pays  10,000  sats to the address 1JfbZRwdDHKZmuiZgYArJZhcu-
     uzuw2HuMu out of your channel balance in 8338aef0.

     Percentages on the right side take out that amount of available funds  from
     a channel. For example:

     8338aef0 -> 100%

     This  takes  all available funds out of channel 8338aef0 and puts them into
     the onchain wallet. Note that available  funds  is  restricted  by  pending
     HTLCs  and  the  1%  reserve  requirement. To get all the funds you need to
     close the channel.  More useful would be something like this:

     8338aef0 -> 50%
     100% -> 07bfddea

     This example takes half the available funds from channel 8338aef0 and  puts
     them into channel 07bfddea.

     We can also split this amount like so:

     8338aef0 -> 50%
     50% -> 07bfddea
     50% -> 09ad6278

     This example takes half the funds in 8338aef0 and splits them between chan-
     nels 07bfddea and 09ad6278.

     If  we  want to send funds to more channels calculating percentages can get
     unwieldy so we can use the asterisk operator "*" which divides the "general
     script funds" amongst all destinations using it, like so:

     8338aef0 -> 50%
     * -> 07bfddea
     * -> 09ad6278
     * -> efc2a7ff

     This example takes half the available funds in  8338aef0  and  splits  them
     evenly among three achannels.

     Sats  can	be specified with multiple suffixes including sat, msat, btc, M,
     or K.  The M suffix is shorthand for a million satoshis and the K suffix is
     shorthand for a thousand satoshis. These can be  combined	with  a  decimal
     point like so:

     07bfddea -> 1.23M
     09ad6278 -> 900K
     efc2a7ff -> 0.01btc

     This  example  takes  1,230,000  sats  from  07bfddea,  900,000  sats  from
     09ad6278, and 1,000,000 sats from efc2a7ff and puts  them	in  the  onchain
     wallet.

     Another  way to specify channel ids is a channel query. These take the form
     of a node id, a colon, and a number or symbol (ie. "034645dc:0") which  re-
     sults  in	your  first  channel  with  the  peer  whose node id starts with
     034645dc. Change the number after the colon to get a different  index  like
     so:

     034645dc:0 -> 10K
     034645dc:1 -> 10K
     034645dc:2 -> 10K

     This  example  takes  10,000 sats out of the first three channels with peer
     034645dc and puts the total minus fees into the onchain wallet.

     In addition to index numbers, the symbol after the colon can be a	question
     mark  "?"	or  an asterisk "*" which mean match the first unused channel or
     all the remaining channels respectively like so:

     * -> 034645dc:?
     * -> 03e3d03e:0
     03e3d03e:* -> 100%

     This example takes 100% of available funds from all of 03e3d03e's	channels
     except  the  first one and splits them between 03e3d03e's first channel and
     034645dc's first channel.

     The node id prefix can also be replaced with the asterisk "*"  which  means
     match  all  nodes.  This can be combined with the asterisk "*" that matches
     all unused channels like so:

     wallet -> 10000sat
     100% -> *:*

     This example takes 10,000 sats from the onchain wallet and divides them be-
     tween all channels.

     It is possible to request a peer to add funds to a channel with a lease re-
     quest.  This is done using the pipe "|" symbol  and  optionally  specifying
     the  maximum  fee you authorize using the at "@" symbol. After the pipe you
     specify the amount of sats you would like to lease, followed by the at sym-
     bol and a percentage value like so:

     wallet -> 10M+fee
     100%|10M@1% -> 8338aef0

     This example splices 10,000,000 sats into channel and  requests  your  peer
     also add 10,000,000 sats to the channel. If they fee they demand is over 1%
     or  the  lease  amount is too small the operation will be aborted. Whatever
     lease fee they do charge will come out of the 10,000,000  sats  going  into
     the channel balance. The onchain fee will be paid by taking extra funds out
     of the onchain wallet.

     Lease  requests do not need to combined with splicing in funds but you must
     pay the onchain fee from somewhere. One simple location to  take  the  fees
     from  is  your existing channel balance. Doing so requires using two arrows
     since funds are going into and out of the channel at the  same  time,  like
     so:

     |10M@1% -> 8338aef0 -> 0+fee

     This  example  makes  a  lease  request  from  your  peer	on  8338aef0 for
     10,000,000 sats and pays the onchain fee using the channel balance. This is
     a particularly elegant way to pay the onchain fee without adding any inputs
     or outputs beyond the channel funding itself.

     When passing via the command line using semicolons can be	simpler  instead
     of newlines. Here are some command line examples:

     Splice out 10 million satoshis to the onchain wallet

     $ lightning-cli splice "8338aef0 -> 10M"

     Splice in 10 thousand satoshis from the onchain wallet

     $ lightning-cli splice "wallet -> 10K; 100% -> 8338aef0"

     Send 900 thousand satoshis from a channel to an onchain address

     $ lightning-cli splice "8338aef0 -> 0.9M+fee; 0.9M -> 1JfbZRwdDHKZmuiZgYArJZhcuuzuw2HuMu"

     Move 1 bitcoin between two channels

     $ lightning-cli splice "8338aef0 -> 1btc; 100% -> 07bfddea"

     Splice in 100 thousand sats to the first channel with peer id 034645dc

     $ lightning-cli splice "wallet -> 0.1M; 100% -> 034645dc:?"

     Splice in 100 thousand sats split across all channels with peer id 034645dc

     $ lightning-cli splice "wallet -> 100000; 100% -> 034645dc:*"

     Take  the	maximum  out  of  one  chanel  and  split  the value across peer
     034645dc's channel plus one more channel

     $ lightning-cli splice "8338aef0 -> 100%; * -> 034645dc:*; * -> 07bfddea"

Core Lightning v26.06.1 				 LIGHTNING-DEV-SPLICE(7)
home | help