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

# Vault

## Overview

Gremlix vaults implement the **ERC4626 Tokenized Vault Standard** — a widely adopted Ethereum standard for yield-bearing vaults. This means:

* Any ERC4626-compatible wallet, aggregator, or DeFi protocol can integrate Gremlix vaults without custom adapters
* Deposits and redemptions follow a predictable, auditable interface
* Share accounting is standardized and transparent

## Key Functions

### User-Facing

```solidity
// Deposit assets, receive shares
function deposit(uint256 assets, address receiver) external returns (uint256 shares)

// Mint exact shares by depositing required assets
function mint(uint256 shares, address receiver) external returns (uint256 assets)

// Redeem shares, receive assets
function redeem(uint256 shares, address receiver, address owner) external returns (uint256 assets)

// Withdraw exact assets by burning required shares
function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares)

// Preview functions (no state change)
function previewDeposit(uint256 assets) external view returns (uint256 shares)
function previewRedeem(uint256 shares) external view returns (uint256 assets)
function previewWithdraw(uint256 assets) external view returns (uint256 shares)
function previewMint(uint256 shares) external view returns (uint256 assets)

// Current share price
function convertToAssets(uint256 shares) external view returns (uint256)
function convertToShares(uint256 assets) external view returns (uint256)

// Total assets under management
function totalAssets() external view returns (uint256)
```

### Keeper Only (Operator)

```solidity
// Deploy capital to a strategy
function allocate(address strategy, uint256 amount) external onlyKeeper

// Withdraw capital from a strategy
function deallocate(address strategy, uint256 amount) external onlyKeeper

// Withdraw all available capital from a strategy
function deallocateAllAvailable(address strategy) external onlyKeeper

// Record new yield and accrue fees
function harvest(address strategy) external onlyKeeper
```

## Share Price Mechanics

The vault tracks a share price denominated in the underlying asset:

```
sharePrice = totalTrackedAssets / totalShares
```

Where `totalTrackedAssets` = vault balance + sum of all strategy deployed values.

On each harvest:

1. New yield is recognized (strategy reports higher asset value)
2. Performance fee shares are minted to fee recipient
3. Management fee shares are minted to fee recipient
4. Remaining yield increases share price for all shareholders

## Inflation Attack Protection

The vault uses a **virtual shares offset** mechanism (inspired by Morpho Vault V2):

* On initialization, virtual shares and virtual assets are added to the accounting
* This makes the initial share price meaningful even before first deposit
* Prevents first-depositor inflation attacks where an attacker could manipulate the share price before other users deposit

## Donation Attack Protection

Unlike naive ERC4626 implementations, the Gremlix vault uses **explicit asset tracking** (`_totalTrackedAssets`) rather than reading `asset.balanceOf(address(this))`. This means:

* Tokens sent directly to the vault contract (donations) **do not affect share price**
* Share price only changes through legitimate `deposit()` and `harvest()` operations
* Prevents donation-based share price manipulation

## Pause Mechanism

The vault owner can independently pause:

* `depositsPaused` — stop new deposits (existing positions unaffected)
* `withdrawalsPaused` — stop redemptions (lock liqudity etc.)

## Events

```solidity
event Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares)
event Withdraw(address indexed sender, address indexed receiver, address indexed owner, uint256 assets, uint256 shares)
event Harvest(address indexed strategy, uint256 yield, uint256 performanceFee, uint256 managementFee)
event Allocated(address indexed strategy, uint256 amount)
event Deallocated(address indexed strategy, uint256 amount)
```