[bug]: inbound fee documentation issues

[AndySchroder]

https://lightning.engineering/api-docs/api/lnd/lightning/update-channel-policy/index.html says

   --inbound_base_fee_msat value  the base inbound fee in milli-satoshis that will be charged for each forwarded HTLC, regardless of payment size. Its value must be zero or negative - it is a discount for using a particular incoming channel. Note that forwards will be rejected if the discount exceeds the outbound fee (forward at a loss), and lead to penalization by the sender (default: 0)
   --inbound_fee_rate_ppm value   the inbound fee rate that will be charged proportionally based on the value of each forwarded HTLC and the outbound fee. Fee rate is expressed in parts per million and must be zero or negative - it is a discount for using a particular incoming channel. Note that forwards will be rejected if the discount exceeds the outbound fee (forward at a loss), and lead to penalization by the sender (default: 0)

and

base_fee_msat: The inbound base fee charged regardless of the number of milli-satoshis received in the channel. By default, only negative values are accepted.

fee_rate_ppm: The effective inbound fee rate in micro-satoshis (parts per million). By default, only negative values are accepted.

However, https://docs.lightning.engineering/lightning-network-tools/lnd/inbound-channel-fees says

"Positive inbound channel fees can optionally be set as well. However, as these positive inbound channel fees can only be understood by upgraded nodes, setting positive inbound channel fees is risky, as it can lead to routing failures among older nodes.

To be able to set positive inbound channel fees, add the following to your lnd.conf file:
accept-positive-inbound-fees=true"

Why does the API documentation say that inbound fees can only be negative, but then general documentation says they can be positive if enabled on the config? Seems like there should be consistency across documentation.

On https://lightning.engineering/api-docs/api/lnd/lightning/update-channel-policy/index.html for avoiding forwarding at a loss, you say "Note that forwards will be rejected if the discount exceeds the outbound fee (forward at a loss), and lead to penalization by the sender". This sounds like a good policy. If someone tries to route a payment in a channel and out a channel that would result in a negative net fee, is an LND node try to send that payment going to be smart enough to limit the fee to 0 to avoid being rejected and penalized? I think this should be clarified in the documentation. The reason I care is because I'm wondering if I can set very negative inbound fees on certain private channels I want to give free routing to anywhere and have different fees on other public channels that I want to charge the public to route through?

Also, https://docs.lightning.engineering/lightning-network-tools/lnd/inbound-channel-fees says "To allow for safe usage of inbound channel fees, the discount is only applied as long as the total fee is larger than the combined fee of incoming and outgoing channel". I think you mean "To allow for safe usage of inbound channel fees, the discount is only applied as long as the net fee of the incoming and outgoing channel is zero or greater."?

[starius]

I think there are several sub-questions in this issue:

1. can inbound fee be positive?
2. If someone tries to route a payment in a channel and out a channel that would result in a negative net fee, is an LND node try to send that payment going to be smart enough to limit the fee to 0 to avoid being rejected and penalized?
3. Fix docs in "To allow for safe usage of inbound channel fees, the discount is only applied as long as the total fee is larger than the combined fee of incoming and outgoing channel"

I think, the answers are:

1. Yes, BUT this should only be used in testing. So the option should not be enabled in prod!
2. I believe that the description of the option is clear that forwards at a loss are rejected: "Note that forwards will be rejected if the discount exceeds the outbound fee (forward at a loss), and lead to penalization by the sender". I haven't found any contradicting information in the referenced docs.
3. I like the proposed change in the docs. I think the fix is correct. The page is built from this repo: https://github.com/lightninglabs/docs.lightning.engineering/blob/master/lightning-network-tools/lnd/inbound-channel-fees.md Can you send a PR with the fix, please?

[AndySchroder]

2. I believe that the description of the option is clear that forwards at a loss are rejected

Not saying it is unclear that forwards at a loss will be rejected, but my question was "Is an LND node try to send that payment going to be smart enough to limit the fee to 0 to avoid being rejected and penalized?"

[bitromortac]

Not saying it is unclear that forwards at a loss will be rejected, but my question was "Is an LND node try to send that payment going to be smart enough to limit the fee to 0 to avoid being rejected and penalized?"

Yes, negative total fees are capped to zero here:
https://github.com/lightningnetwork/lnd/blob/master/routing/pathfind.go#L264-L267

[AndySchroder]

Good to know. Would be nice if this were clarified in the documentation too.