Liquid keeper reserve

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:

Unwinds eligible illiquid farms when the reserve is too low.
Pauses new wrapping on those farms until the reserve reaches the target.
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:

The rebalancer calculates the current liquid reserve ratio.
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.
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:

Unwraps vault shares to PYUSD.
Swaps PYUSD for USDC.
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

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.

Overview

Risk

Why it exists

Key concepts

Rebalancer integration

Farm keeper integration

Farm eligibility

`automaticWithdraw` farm integration

Configuration

Execution flow

Safety

​Why it exists

​Key concepts

​Rebalancer integration

​Farm keeper integration

​Farm eligibility

​automaticWithdraw farm integration

​Configuration

​Execution flow

​Safety

Why it exists

Key concepts

Rebalancer integration

Farm keeper integration

Farm eligibility

`automaticWithdraw` farm integration

Configuration

Execution flow

Safety