> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infinifi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Liquid keeper reserve

> How infiniFi keeps its liquid USDC reserve near the configured target

The liquid keeper reserve automatically keeps the protocol's **liquid USDC reserve** near its target reserve factor. It works alongside the rebalancer and farm keeper.

## Why it exists

The rebalancer allocates capital between liquid and illiquid farms based on votes and lock durations. User redemptions can cause the liquid share to fall below the target reserve factor.

The liquid keeper reserve:

1. **Unwinds** eligible illiquid farms when the reserve is too low.
2. **Pauses new wrapping** on those farms until the reserve reaches the target.
3. Lets the **rebalancer** move the released USDC to the liquid side.

## Key concepts

| Term                      | Meaning                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Liquid reserve factor** | Share of protocol USDC held in liquid farms and the mint controller, relative to total liquid deposits. |
| **Target**                | Desired liquid reserve ratio, such as 25%.                                                              |
| **Lower bound**           | Threshold below which automatic withdrawals activate, such as 20% when the target is 25%.               |
| **Hysteresis band**       | Range between the lower bound and target where automatic withdrawals remain inactive.                   |
| **Run rate**              | How often the system runs, such as every six hours.                                                     |
| **Per-run cap**           | Configurable limit on the amount unwound in one cycle, such as 1 million USDC.                          |

For example, with a **25%** target and **20%** lower bound:

| Ratio   | Behavior                                                                                                                                                  |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ≥ 25%   | The rebalancer can allocate USDC to the illiquid side.                                                                                                    |
| 20%–25% | No automatic withdrawal. The farm keeper skips wrapping in selected farms. The rebalancer moves idle USDC to the liquid side and rebalances liquid farms. |
| \< 20%  | Automatic withdrawals are enabled for eligible farms.                                                                                                     |

The hysteresis band prevents repeated withdrawals and reallocations when the reserve is slightly below the target.

## Rebalancer integration

At the start of each rebalancer run, before the main allocation algorithm:

1. The rebalancer calculates the current liquid reserve ratio.
2. If the ratio is **below the lower bound**, the rebalancer:
   * Selects the eligible illiquid farm with the lowest 48-hour APY.
   * Calls `automaticWithdraw` to release USDC on that farm.
   * Withdraws the amount needed to reach the target, subject to the per-run cap.
3. The standard rebalancer movements transfer the released USDC from the farm to liquid destinations, such as the mint controller or liquid farms.

`automaticWithdraw` runs before the standard movements so the released USDC is available to the allocation algorithm.

## Farm keeper integration

When the liquid reserve ratio is in the **hysteresis band**:

* The farm keeper does not wrap incoming USDC into the farm's target asset. For example, Morpho Prime does not swap USDC for PYUSD or deposit PYUSD into the Morpho vault.
* USDC remains idle on the farm until the ratio recovers or a rebalancer run moves it.

Wrapping resumes when the ratio reaches or exceeds the target.

## Farm eligibility

Automatic withdrawals apply only to farms that opt in through configuration:

| Parameter             | Description                                                                         |
| --------------------- | ----------------------------------------------------------------------------------- |
| `autoWithdrawEnabled` | When `true`, the rebalancer can use the farm as a source for automatic withdrawals. |

The rebalancer ignores farms without this flag. It also skips paused farms and farms with withdrawals disabled.

## `automaticWithdraw` farm integration

Each eligible farm type implements `automaticWithdraw` on its farm manager. The rebalancer calls it before standard movements.

The method converts deployed positions back to USDC on the farm without sending funds to the mint controller. The rebalancer handles the subsequent transfer.

For example, Morpho Prime:

1. Unwraps vault shares to PYUSD.
2. Swaps PYUSD for USDC.
3. Leaves USDC on the farm.

The rebalancer then pulls that USDC through its standard liquid-side movements.

Only farm integrations that can safely unwind to USDC onchain implement `automaticWithdraw`.

## Configuration

| Parameter                 | Description                                           | Example          |
| ------------------------- | ----------------------------------------------------- | ---------------- |
| `liquidReserveTarget`     | Target liquid reserve ratio.                          | `0.25` (25%)     |
| `liquidReserveLowerBound` | Ratio below which automatic withdrawals activate.     | `0.20` (20%)     |
| `maxAutoWithdrawPerRun`   | Maximum USDC released in one rebalancer run.          | `1_000_000` USDC |
| `autoWithdrawEnabled`     | Whether a farm is eligible for automatic withdrawals. | `true`           |

Set the lower bound below the target to create the hysteresis band. Both values are configurable.

## Execution flow

```text theme={null}
Rebalancer run starts
        │
        ▼
Calculate liquid reserve ratio
        │
        ├─ ratio ≥ target ──────────────────► Normal rebalance
        │
        ├─ lower bound ≤ ratio < target ────► Skip automatic withdrawal
        │                                      Farm keeper also skips wrapping
        │
        └─ ratio < lower bound
                │
                ▼
        Select the lowest-yielding eligible illiquid farm
        and call automaticWithdraw
                │
                ▼
        Run the main allocation algorithm
        Pull USDC to liquid farms or the mint controller
                │
                ▼
        End rebalancer run
```

## Safety

* The **per-run cap** limits how much the system can unwind in one cycle.
* The **hysteresis band** prevents oscillation between wrapping and unwrapping near the target.
* **Per-farm opt-in** limits participation to configured farms.
* Existing rebalancer guards still apply, including cooldowns, minimum and maximum movements, paused farms, and fake mode.