LN Toolkit Command

update-channel-policies’ command

update-channel-policies allows you to adapt your channels fee policy based on its fullness. The main use-case is run this command regularly via cron to update channel policies as balance flows in and out.

Caveats

There are several ways you could adapt fees for each channel. This command just takes a simplistic view based on percent-fullness. It may not be the right approach for you.

Example

Here’s a simple example of dry-running the command:

lntoolkit update-channel-policies \
    --policy-above-percent-0 "m㋛5000 + mm㋛10 / 40" \
    --policy-above-percent-5 "m㋛2500 + mm㋛10 / 40" \
    --policy-above-percent-10 "m㋛1000 + mm㋛10 / 40" \
    --policy-above-percent-15 "m㋛500 + mm㋛10 / 40" \
    --policy-above-percent-20 "m㋛250 + mm㋛10 / 40" \
    --policy-above-percent-25 "m㋛0 + mm㋛10 / 40" \
    --policy-above-percent-75 "m㋛0 + mm㋛5 / 40" \
    --policy-above-percent-85 "m㋛0 + mm㋛2 / 40" \
    --policy-above-percent-95 "m㋛0 + mm㋛0 / 40" \
    --dry-run

If any channels have policies that don't match, the command output will tell you:

2019/05/30 14:35:02 📄 Channel 634877805264961537 policy has ratio 75% so updated from m㋛0 + mm㋛10/40 to m㋛0 + mm㋛5/40
2019/05/30 14:35:02 📄 Channel 632050960773152769 policy has ratio 18% so updated from m㋛0 + mm㋛10/40 to m㋛500 + mm㋛10/40
2019/05/30 14:35:02 📄 Channel 634859113565847553 policy has ratio 82% so updated from m㋛0 + mm㋛10/40 to m㋛0 + mm㋛5/40
2019/05/30 14:35:02 📄 No tip to send. That's OK, I still love you! 🥰

Usage

update-channel-policies takes many policy descriptions as parameters but they all share the same format: ‘feebase+feerate/timelockdelta’, where:

So a policy with a fee base of 1000millisats plus 100microsats per satoshi forwarded and a timelock of 40 blocks could be written as a parameter as: "1000+100/40". (It’s worth explicitly putting quotes around these parameters when you’re using this command.) Spaces around separators are ignored, so you can also specify it as "1000 + 100 / 40" if you prefer. Millisatoshi and microsatoshi specifiers are also ignored if they’ used correctly so you can use this format as well if you want your cron task to be clearer: "m㋛1000 + mm㋛100 / 40".

Policies are specified for 5% ‘buckets’, but if you don’t specify one then the next-lower one applies. And if the next-lower one isn’t specified, the next-lower below it applies. (As a result, the first policy for the 0% bucket is a mandatory parameter.)

For example, if we want to specify our default fee policy of m㋛100+mm㋛10/40, but have a higher fee policy of m㋛5000+mm㋛10/40 if the channel was nearly empty (less than 5% full), and a cheap rate of m㋛0+mm㋛0/40 if the channel was nearly full (over 95% full) we could use this command:

lntoolkit update-channel-policies \
    --policy-above-percent-0 "m㋛5000 + mm㋛10 / 40" \
    --policy-above-percent-5 "m㋛100 + mm㋛10 / 40" \
    --policy-above-percent-95 "m㋛0 + mm㋛0 / 40" \
    --verbose

The verbose output will show you all the ‘buckets’ so you can see exactly what policy will be applied:

2019/05/30 18:26:46 📜 Policy tier 0%: m㋛5,000 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 5%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 10%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 15%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 20%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 25%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 30%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 35%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 40%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 45%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 50%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 55%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 60%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 65%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 70%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 75%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 80%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 85%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 90%: m㋛100 + mm㋛10/40
2019/05/30 18:26:46 📜 Policy tier 95%: m㋛0 + mm㋛0/40

And of course you can use the --dry-run parameter to see what the command will do without making any changes to your system.

Here’s the list of parameters it can take:

Usage of update-channel-policies:
  -certificate string
    	path and filename of the TLS certificate to use when connecting to LND. (default "~/.lnd/tls.cert")
  -dry-run
    	if specified, route(s) will be calculated but no funds will be transferred.
  -exclude value
    	specific channel IDs to exclude from updates.
  -macaroon string
    	path and filename of the macaroon to use when connecting to LND. (default "~/.lnd/data/chain/bitcoin/testnet/admin.macaroon")
  -policy-above-percent-0 value
    	policy to apply to all channels with local balances over 0%, unless overridden
  -policy-above-percent-10 value
    	policy to apply to all channels with local balances over 10%, unless overridden
  -policy-above-percent-15 value
    	policy to apply to all channels with local balances over 15%, unless overridden
  -policy-above-percent-20 value
    	policy to apply to all channels with local balances over 20%, unless overridden
  -policy-above-percent-25 value
    	policy to apply to all channels with local balances over 25%, unless overridden
  -policy-above-percent-30 value
    	policy to apply to all channels with local balances over 30%, unless overridden
  -policy-above-percent-35 value
    	policy to apply to all channels with local balances over 35%, unless overridden
  -policy-above-percent-40 value
    	policy to apply to all channels with local balances over 40%, unless overridden
  -policy-above-percent-45 value
    	policy to apply to all channels with local balances over 45%, unless overridden
  -policy-above-percent-5 value
    	policy to apply to all channels with local balances over 5%, unless overridden
  -policy-above-percent-50 value
    	policy to apply to all channels with local balances over 50%, unless overridden
  -policy-above-percent-55 value
    	policy to apply to all channels with local balances over 55%, unless overridden
  -policy-above-percent-60 value
    	policy to apply to all channels with local balances over 60%, unless overridden
  -policy-above-percent-65 value
    	policy to apply to all channels with local balances over 65%, unless overridden
  -policy-above-percent-70 value
    	policy to apply to all channels with local balances over 70%, unless overridden
  -policy-above-percent-75 value
    	policy to apply to all channels with local balances over 75%, unless overridden
  -policy-above-percent-80 value
    	policy to apply to all channels with local balances over 80%, unless overridden
  -policy-above-percent-85 value
    	policy to apply to all channels with local balances over 85%, unless overridden
  -policy-above-percent-90 value
    	policy to apply to all channels with local balances over 90%, unless overridden
  -policy-above-percent-95 value
    	policy to apply to all channels with local balances over 95%
  -quiet
    	only show errors and critical messages.
  -server string
    	hostname and port to use when connecting to LND. (default "localhost:10009")
  -timeout duration
    	timeout to use when connecting to LND. (default 30s)
  -tip value
    	tip amount (in satoshis) to the developer as a thank-you (Tip is only paid if an action is performed.)
  -verbose
    	show additional logging information.
  -version
    	report the version being used.

Like all LN Toolkit commands, update-channel-policies can take a --verbose flag to greatly increase the amount of diagnostic output it creates. It can also take a --tip <amount> parameter if you want to tip me some satoshis.