> 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/contracts/keeper.md).

# Keeper

## Overview

The `Keeper` is an authorized operator contract that manages the lifecycle of capital within Gremlix vaults. It is the only entity permitted to call privileged vault functions.

## Role in the Protocol

```
Off-chain Bot
     │
     │  reads real PnL from DEX API
     ▼
Keeper Contract  ←── only whitelisted operators can call
     │
     ├── vault.allocate(strategy, amount)
     ├── vault.deallocate(strategy, amount)
     └── vault.harvest(strategy)  ← via reconcileAndHarvest
```

## Key Functions

```solidity
// Register a new authorized operator
function addOperator(address operator) external onlyOwner

// Remove an operator
function removeOperator(address operator) external onlyOwner

// Allocate capital from vault to strategy
function allocate(address vault, address strategy, uint256 amount) external onlyOperator

// Deallocate capital from strategy back to vault
function deallocate(address vault, address strategy, uint256 amount) external onlyOperator

// Withdraw all available capital from a strategy
function deallocateAllAvailable(address vault, address strategy) external onlyOperator

// Update strategy value and trigger harvest in one transaction
function reconcileAndHarvest(
    address vault,
    address strategy,
    uint256 newStrategyValue
) external onlyOperator

// Batch reconcile multiple vaults/strategies
function batchReconcileAndHarvest(
    ReconcileParams[] calldata params
) external onlyOperator
```

## Access Control

The Keeper uses a two-level access control:

| Role             | Permissions                                   |
| ---------------- | --------------------------------------------- |
| Owner (multisig) | Add/remove operators, change keeper ownership |
| Operator (bot)   | Allocate, deallocate, reconcile, harvest      |

Operators are typically automated bots running 24/7. The owner is a multisig controlled by the protocol team.

## Batch Reconciliation

The Keeper supports atomic batch operations across multiple vaults:

```solidity
struct ReconcileParams {
    address vault;
    address strategy;
    uint256 newValue;
}

keeper.batchReconcileAndHarvest([
    { vault: usdcVault, strategy: usdcStrategy, newValue: 1_050_000e6 },
    { vault: btcVault,  strategy: btcStrategy,  newValue: 15_2e18 }
]);
```

Benefits:

* Atomic update of all vault share prices
* Single transaction, lower gas
* Consistent snapshot across vaults

## Security Considerations

The Keeper is a privileged contract. If an operator key is compromised, an attacker could:

* Report inflated strategy values (overstating yield)
* Drain vault capital by misrouting allocations

Mitigations:

* Staleness window prevents large historical value claims
* Operator keys should be stored in HSM or secure enclave
* Multisig ownership for emergency response
* Audit trail via on-chain events for all keeper actions