home | help 
LIGHTNING-SETCHANNEL(7) 				 LIGHTNING-SETCHANNEL(7)

NAME
     setchannel  --  Command  for configuring fees / htlc range advertized for a
     channel

SYNOPSIS
     setchannel id [feebase] [feeppm] [htlcmin]  [htlcmax]  [enforcedelay]  [ig-
     norefeelimits]

DESCRIPTION
     The  setchannel  RPC  command  sets  channel  specific  routing  fees,  and
     htlc_minimum_msat or htlc_maximum_msat as defined in BOLT #7.  The  channel
     has to be in normal or awaiting state. This can be checked by listpeers re-
     porting  a  state	of  CHANNELD_NORMAL  or CHANNELD_AWAITING_LOCKIN for the
     channel.

     These changes (for a public channel) will be broadcast to the rest  of  the
     network (though many nodes limit the rate of such changes they will accept:
     we allow 2 a day, with a few extra occasionally).

     *	id  (string):  Should  contain	a scid (short channel ID), channel id or
	peerid (pubkey) of the channel to be modified. If id is set to all,  the
	updates  are  applied  to  all	channels in states CHANNELD_NORMAL CHAN-
	NELD_AWAITING_LOCKIN or DUALOPEND_AWAITING_LOCKIN. If id  is  a  peerid,
	all channels with the +peer in those states are changed.
     *	feebase  (msat,  optional):  Value in millisatoshi that is added as base
	fee to any routed payment: if omitted, it is  unchanged.  It  can  be  a
	whole  number, or a whole number ending in msat or sat, or a number with
	three decimal places ending in sat, or a number with  1  to  11  decimal
	places ending in btc.
     *	feeppm	(u32,  optional):  Value  that	is added proportionally per-mil-
	lionths to any routed payment volume in satoshi. For example, if ppm  is
	1,000 and 1,000,000 satoshi is being routed through the channel, an pro-
	portional fee of 1,000 satoshi is added, resulting in a 0.1% fee.
     *	htlcmin  (msat,  optional):  Value that limits how small an HTLC we will
	forward: if omitted, it is unchanged. It can be a  whole  number,  or  a
	whole  number  ending  in  msat  or  sat, or a number with three decimal
	places ending in sat, or a number with 1 to 11 decimal places ending  in
	btc. Note that the peer also enforces a minimum for the channel: setting
	it below that will simply set it to that value with a warning. Also note
	that  htlcmin only applies to forwarded HTLCs: we can still send smaller
	payments ourselves. The default is no lower limit.
     *	htlcmax (msat, optional): Value that limits how large an  HTLC	we  will
	forward:  if  omitted,	it  is unchanged. It can be a whole number, or a
	whole number ending in msat or sat,  or  a  number  with  three  decimal
	places	ending in sat, or a number with 1 to 11 decimal places ending in
	btc. Note that htlcmax only applies to forwarded  HTLCs:  we  can  still
	send larger payments ourselves. The default is no effective limit.
     *	enforcedelay  (u32, optional): Number of seconds to delay before enforc-
	ing the new fees/htlc max. This gives the network a chance to  catch  up
	with  the new rates and avoids rejecting HTLCs before they do. This only
	has an effect if rates are increased (we always allow users  to  overpay
	fees)  or  htlcmax  is	decreased, and only applied to a single rate in-
	crease per channel (we don't remember an arbitrary number of prior feer-
	ates) and if the node is restarted the updated configuration is enforced
	immediately. The default is 600, which is ten minutes.
     *	ignorefeelimits (boolean, optional): If set to True means to  allow  the
	peer  to  set  the  commitment	transaction fees (or closing transaction
	fees) to any value they want. This is dangerous: they could set an exor-
	bitant fee (so HTLCs are unenforcable), or a tiny fee (so  that  commit-
	ment  transactions  cannot  be	relayed), but avoids channel breakage in
	case of feerate disagreements. (Note: the global ignore_fee_limits  set-
	ting overrides this). (added v23.08)

RETURN VALUE
     On  success,  an  object containing channels is returned. It is an array of
     objects, where each object contains:

     *	peer_id (pubkey): The node_id of the peer.
     *	channel_id (hash): The channel_id of the channel.
     *	fee_base_msat (msat): The resulting feebase (this is the BOLT #7 name).
     *	fee_proportional_millionths (u32): The resulting  feeppm  (this  is  the
	BOLT #7 name).
     *	ignore_fee_limits  (boolean): If we are now allowing peer to set feerate
	on commitment transaction without restriction. (added v23.08)
     *	minimum_htlc_out_msat (msat): The resulting htlcmin  we  will  advertize
	(the BOLT #7 name is htlc_minimum_msat).
     *	maximum_htlc_out_msat  (msat):	The  resulting htlcmax we will advertize
	(the BOLT #7 name is htlc_maximum_msat).
     *	short_channel_id (short_channel_id, optional): The short_channel_id  (if
	locked in).
     *	the following warnings are possible:
	*  warning_htlcmin_too_low:  The  requested htlcmin was too low for this
	   peer, so we set it to the minimum they will allow.
	*  warning_htlcmax_too_high: The requested htlcmax was greater than  the
	   channel capacity, so we set it to the channel capacity.

ERRORS
     The following error codes may occur:

     *	-1: Channel is in incorrect state, i.e. Catchall nonspecific error.
     *	-32602:  JSONRPC2_INVALID_PARAMS,  i.e.  Given id is not a channel ID or
	short channel ID.

AUTHOR
     Michael Schmoock michael@schmoock.net is the author of this feature.

SEE ALSO
     lightningd-config(5), lightning-fundchannel(7),  lightning-listchannels(7),
     lightning-listpeers(7)

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

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli setchannel -k "id"="123x1x1" "ignorefeelimits"=True

     {
       "id": "example:setchannel#1",
       "method": "setchannel",
       "params": {
	 "id": "123x1x1",
	 "ignorefeelimits": true
       }
     }

     Response:

     {
       "channels": [
	 {
	   "peer_id": "nodeid030303030303030303030303030303030303030303030303030303030303",
	   "channel_id": "channelid0230200230200230200230200230200230200230200230200230200",
	   "short_channel_id": "123x1x1",
	   "fee_base_msat": 1,
	   "fee_proportional_millionths": 10,
	   "minimum_htlc_out_msat": 0,
	   "maximum_htlc_out_msat": 990000000,
	   "ignore_fee_limits": true
	 }
       ]
     }

     Example 2:

     Request:

     $ lightning-cli setchannel -k "id"="115x1x1" "feebase"=4000 "feeppm"=300 "enforcedelay"=0

     {
       "id": "example:setchannel#2",
       "method": "setchannel",
       "params": {
	 "id": "115x1x1",
	 "feebase": 4000,
	 "feeppm": 300,
	 "enforcedelay": 0
       }
     }

     Response:

     {
       "channels": [
	 {
	   "peer_id": "nodeid050505050505050505050505050505050505050505050505050505050505",
	   "channel_id": "channelid0250000250000250000250000250000250000250000250000250000",
	   "short_channel_id": "115x1x1",
	   "fee_base_msat": 4000,
	   "fee_proportional_millionths": 300,
	   "minimum_htlc_out_msat": 0,
	   "maximum_htlc_out_msat": 990000000,
	   "ignore_fee_limits": false
	 }
       ]
     }

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