# Auto Liquidity

Liquidity management is fully automated.

It is based on the existing on-the-fly channel feature of Phoenix Wallet, with two additional mechanisms:
- `auto liquidity`: every time a channel increase is needed, a large amount of liquidity is requested
- `fee credit`: to facilitate bootstrapping, small payments (too small to pay for a channel creation by themselves) are paid directly to the LSP, instead of being rejected, and will be deducted from future fees. The [fee credit is non-refundable](#important-note-about-the-fee-credit).

In other words, when receiving a payment, depending on the situation, the funds either:
- go to your balance (normal scenario)
- are used to purchase inbound liquidity immediately (once in a while)
- are set aside to purchase inbound liquidity later (for small payments at bootstrapping).

From the outside, `phoenixd` is **always** accepting payments, resulting in **seemingly infinite inbound liquidity, with no threshold effect**. You do not have to worry about setting up liquidity, or minimal payment size.

By requesting liquidity in large chunks, the number of on-chain operations is reduced and mining fees are taken out of the equation, in exchange for higher upfront costs.

The default requested liquidity amount is **2m sat**, configurable with `--auto-liquidity`. The higher the amount, the higher the upfront cost, but the lower the mining fees in relative terms.

# Fees

The cost of liquidity is 1% + mining fees.

Depending on the current mining feerate, the effective average receive feerate is:

| mining feerate | 2m sat (default)          | 5m sat | 10m sat
|----------------|---------------------------|--------|-----------
|      1 sat/B   |     1.01%                 |  1.01% |  1.00%
|     10 sat/B   |     1.14%                 |  1.05% |  1.03%
|     20 sat/B   |     1.27%                 |  1.11% |  1.05%
|     30 sat/B   |     1.41%                 |  1.16% |  1.08%
|     50 sat/B   |     1.68%                 |  1.27% |  1.14%
|     70 sat/B   |     1.95%                 |  1.38% |  1.19%

Keep in mind that **fees are paid upfront**, so this is the effective feerate after you have consumed the entire liquidity that was purchased. If you are uncertain about your expected receive volume, we recommend leaving the default value for auto-liquidity.

Note: this is a worst case estimate, for receive-only use cases.

# Examples

With the default settings (**2m sat** auto-liquidity), and assuming that current mining fees are **10k sat**, the total fee for a
liquidity operation will be: **10k sat** (mining fee) + **20k sat** (1% service fee for the liquidity) = **30k sat**.

### Continuous stream of tiny 100 sat incoming payments

1. the first 299 incoming payments will be added to your fee credit
2. when receiving the 300th payment, your credit reaches 30k sat and will immediately be used to create a 2m sat channel, with balance 0 sat on your side
3. the next 20 thousand payments will be received in your channel and added to your balance, which ends up at 2m sat
4. back to 1.

### Continuous stream of 50k sat incoming payments

1. when receiving the first payment, a 2m sat channel will be created with balance 50k-30k=20k sat on your side
2. the next next 40 payments will be received in your channel, at that point the balance is 2m sat on your side
3. back to 1.

# Important note about the fee credit

The fee credit is **not** part of your balance. It is **non-refundable**. It cannot be used for anything else than paying mining/service fee.

During normal operation, your fee credit will be zero. Its only purpose is to act as a buffer when the size of your incoming payments is low compared to the cost of on-chain operations.