> For the complete documentation index, see [llms.txt](https://gremlix.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gremlix.gitbook.io/docs/protocol/keeper-harvesting.md).

# Keeper Harvesting

## What is the Keeper?

The **Keeper** is an authorized on-chain operator contract that bridges the off-chain world (Perpetual DEX positions, external strategy state) with the on-chain vault accounting.

Since grid trading happens on external Perpetual DEX platforms, the vault cannot directly read the current PnL of positions. The Keeper solves this by periodically **reconciling** the real strategy value with what is recorded on-chain, then triggering a **harvest** to update the vault's share price.

## Keeper Responsibilities

| Action                       | Description                                            |
| ---------------------------- | ------------------------------------------------------ |
| `allocate()`                 | Move capital from vault → strategy (deploy to DEX)     |
| `deallocate()`               | Move capital from strategy → vault (withdraw from DEX) |
| `reconcileAndHarvest()`      | Update strategy value + trigger vault harvest          |
| `updateTotalTrackedAssets()` | Report current real-world strategy value               |

## Harvest Flow

```
Off-chain monitor detects new PnL
             │
             ▼
Keeper calls reconcileAndHarvest(vault, strategy, newValue)
             │
             ├── 1. updateTotalTrackedAssets(newValue)
             │         └── Strategy records new asset value
             │
             ├── 2. vault.harvest()
             │         └── Vault computes yield = newValue - lastValue
             │                  └── Accrues performance fee
             │                  └── Accrues management fee
             │                  └── Updates totalTrackedAssets
             │
             └── 3. Share price increases
                       └── All existing shareholders benefit
```

## Staleness Protection

To prevent the Keeper from reporting stale (outdated) values, the vault enforces a **staleness window**:

* Each harvest records a timestamp
* If the next harvest is called too late (exceeds `harvestStalenessWindow`), the transaction reverts
* This prevents accumulated stale yield from being recognized all at once, which could be exploited

Operators can configure the staleness window per vault.

## Batch Operations

The Keeper supports **batch reconciliation** across multiple vaults and strategies in a single transaction:

```javascript
keeper.batchReconcileAndHarvest([
  { vault: usdcVault, strategy: usdcStrategy, newValue: ... },
  { vault: btcVault,  strategy: btcStrategy,  newValue: ... },
])
```

This reduces gas costs and ensures atomic multi-vault updates.

## Operator Access Control

The Keeper maintains an **operator whitelist**. Only authorized addresses can call keeper functions. The keeper owner can add/remove operators.

```
Owner (multisig)
    │
    └── Keeper Contract
            │
            ├── Operator 1 (automated bot)
            ├── Operator 2 (backup bot)
            └── ...
```

## Harvest Frequency

Harvests are triggered by off-chain monitoring bots whenever:

* A meaningful change in strategy PnL is detected (above a threshold)
* The maximum time between harvests approaches the staleness window
* Manual operator trigger

More frequent harvests = more accurate share price, but higher gas costs. The frequency is tuned per vault.