# What can we learn about liquidity from lightning send_onion

# What can we learn from lightning send_onion about liquidity

When we look at a channel in the Lightning Network for the first time, we actually know nothing. Or at least next to nothing - we can get information on the total capacity in the two channels, from A to B and in reverse. We can extract this information from the gossip protocol. But we don’t know about the two parties’ balances and their ability to forward payments. This brings with it the risk that when we try to send a payment in the Lightning Network, we include a channel that does not provide for the necessary liquidity, and the chain of channels needed for delivery breaks. Our payment does not arrive at the intended destination. The probability for this to happen can be reduced through learning. There are two ways for us to gather information about the channels in the lightning network.

- One way is to establish the state of reality, to learn about the actual ability of a channel to forward payments.
- The other way is to develop estimates about channel balances, that are derived from gossip information and assumptions on the probability distribution function for the channel capacities. From this we can already see, that there are two layers involved. The former can be considered the real world information (represented by the ‚OracleLightningNetwork‘), the latter is a Network Graph containing estimates (represented by the ‚UncertaintyNetwork‘). Sending onions and thus probing channels is our only way to learn about the real world (and only at exact this point in time). The results will then influence our estimate about the probabilities to send a particular amount of satoshi between parties.

This send_onion call has three possible outcomes.:

- receiving a payment hash
- returning an error
- no return value

## failing onion, returning an error

The onion routing protocol includes a simple mechanism for returning encrypted error messages to the origin node. The returned error messages may be failures reported by any hop, including the final node. With the returned error message the origin node can detect the sender of the error message. This allows the origin node (the sending node) to infer, that

- all channels along the path to the failing channel contained enough liquidity to forward the payment.
- And - assuming that the error message is about not enough funds and not e.g. an unavailable node - that the failing channel did not.
This is immediate knowledge about the channels, information of high reliability, because they are based on the „real world“ network, the OracleLightningNetwork. But there’s more information in this. Once we know that a channel A-B can provide an amount of (at least) m, then we know about the maximum amount of satoshi that is available in the return channel B-A. When outbound liquidity of A is
*at least*m, then the inbound liquidity from B to A is*at most*the total capacity of the channels minus m. This knowledge can be applied to all channels along the path up to the failing channel. The situation is different for the channel, where the onion failed. Here we don’t know exactly what the liquidity in the channel is. But we know that the liquidity is*less than*m. And regarding the return channel, we can consequently deduce that the liquidity in this direction is*at least*m. The information about the unavailability is of high reliability. Based on the information that we receive with high reliability, we can then progress to estimate the available liquidity in both channels.## successful onion, receiving a payment hash

When the owner of a node sends an onion for a payment to another node and the onion successfully passes all channels to its intended recipient, the recipient can acknowledge receipt of the payment by returning the payment hash to the sender. Through the arrival of the (correct) payment hash, the sender has learnt that all channels provided enough liquidity at the time of the request, at least the payment amount. And due to the fact that the payment was delivered, the owner can now conclude that the channels’ liquidity was reduced by the payment amount. Which leaves him with no knowledge about the remaining liquidity (in absence of any prior knowledge). While a successful onion does not provide information about minimum liquidity in the channel, we can infer, however, that the maximum liquidity cannot be higher than the channels’ capacity minus the payment amount. And we learnt that the liquidity in the return channel now increased by the payment amount. Thus, the minimum liquidity is at least the payment amount and an estimate of a maximum liquidity could now be increased by that same amount. How reliable is the information about maximum liquidity in the channel? We do know that liquidity has been reduced, and thus we know reliably that it cannot be higher than capacity minus the payment amount. But let’s assume that we had some prior knowledge about a maximum liquidity in the channel - how does it impact our prior knowledge about the maximum liquidity? In my opinion, for as long as I cannot assess, how this maximum liquidity estimate was derived, it might be unreliable to reduce the maximum liquidity estimate by the payment amount. This is at least for as long as we have to admit that we don’t possess all information about payments in the network. Thus a maximum liquidity of „capacity minus all payment amounts of the onions of this payment“ is the only reliable estimate. How about the return channel? We know that now there is more liquidity available in the return channel, as we just moved it there. How does this affect the knowledge about the minimum liquidity in the return channel? Well, it’s at least the payment amount. But similar to the prior considerations about the maximum liquidity, it would be unsafe to just lift the minimum liquidity by this amount. This treatment is rather conservative, but when it comes to increasing reliability of the network it seems warranted to err on the side of caution. Especially as a misjudgment will lead to a failed payment and an unnecessary jamming of payment channels by unnecessarily locking liquidity.

## successful onion, but no return message

For multi-part payments, a payment is broken down into several attempts and all partial payments must succeed for the total payment to complete and the receiver to pass on the payment hash. The sender initially does not know how many attempts a payment will take and if it will succeed at all. This might lead to the situation that a lightning send_onion call is successful in that all channels can pass on the partial payment amount (plus fees), but the sender does not receive any information about it. So it is debatable how this situation should be treated from an information perspective. It can be assumed that no payment hash will be sent until the last partial payment has been tried. This means that it makes sense to decide on a cutoff-time following the last send_onion call, before the onions have to be declared failed.All onions without a return value would need to be resent, until at least the payment amount has reached the receiver and the payment hash is released. By then at the latest, the send_onion calls without return values can be considered as failed. But even then there is no information that can be extracted, as to what lead to failure. Consequently it would be unsafe to base any learning about channel balances on these onions.