# evU - tower

## CW4626 Escher Vault – Overview

### Purpose

The **CW4626 Escher Vault** is a CosmWasm vault (ERC-4626 inspired) designed for the **U token** as its underlying.\
It automates liquidity provisioning, staking, incentive claiming, and redemptions, while exposing a familiar **deposit/mint/withdraw/redeem** interface.

***

### Roles

* **Manager**
  * Bonds underlying U into LP/staking.
  * Executes add/remove liquidity.
  * Swaps and claims incentives.
* **Oracle**
  * Updates the price map for LP other-side assets and incentive tokens.
* **Marketing**
  * Uses CW20-base’s built-in marketing messages (e.g., name, symbol, logo).

***

### Key Components

* **Underlying Token** – Native **U**, basis for deposits/withdrawals and accounting.
* **Share Token** – CW20 vault shares (same decimals as U).
* **Pool** – The vault strategy centers on the **eU pool**, where U is converted to eU and deployed for liquidity and staking.
* **Incentives** – The vault earns rewards in **U, eU, and BABY**.
* **Oracle Prices** – Map of `token_address → Decimal price` in terms of U.
  * Must include:
    * eU
    * U
    * BABY

***

### Fees

* **Entry Fee** – Applied on `deposit`/`mint`.
  * A percentage of gross shares is minted to the **fee recipient**.
  * `PreviewDeposit` returns **net user shares** after fee deduction.

***

### Core Flows

#### Deposit / Mint

1. User deposits **U**.
2. Vault calculates gross shares from `total_assets / total_shares`.
3. Shares are split into:
   * `user_shares` → depositor.
   * `fee_shares` → fee recipient.

#### Bond

* Manager moves a portion of U into the **eU pool** (via hub).
* Converts U into eU and LP positions with slippage control and unique salt.

#### Add Liquidity

* Manager pairs U/eU as needed.
* Mints LP shares and deposits them into the incentives contract.

#### Claim Incentives

* Manager claims accumulated rewards (**U, eU, BABY**) back into the vault.

#### Redemption (Two-Step)

1. **`request_redeem`**
   * Locks user shares.
   * Returns preview of expected asset distribution (U + eU + BABY), valued via oracle.
2. **`complete_redemption`**
   * Manager unwinds positions.
   * Assets distributed to user.
   * Locked shares burned.

***

### Queries

* **Standard:**
  * `Asset`, `TotalAssets`, `ConvertToShares/Assets`, `MaxDeposit/Mint/Withdraw/Redeem`
  * `PreviewDeposit` (net), `PreviewMint`, `ExchangeRate`
* **Oracle:**
  * `OraclePrices`, `OracleTokensList`
* **Positions & Incentives:**
  * `LPPosition`, `AllPendingIncentives`
* **Redemptions:**
  * Request by ID
  * User redemption requests
  * Redemption stats

***

### Exchange Rate

```
exchange_rate = total_assets / total_shares
```

* Includes U + eU + BABY rewards (valued via oracle).
* Excludes locked shares to maintain fair PPS.

***

### Access Control

* **manager** and **oracle** role vectors maintained on-chain.
* Only authorized addresses may call privileged endpoints.

***

### Safety & Validation

* Oracle prices must be strictly positive and cover U, eU, and BABY.
* Slippage tolerance enforced in liquidity operations.
* `salt` validated to prevent replay.

***

### Instantiate Fields (Examples)

* `managers`, `oracles`
* `underlying_token` = U
* `share_name/symbol/marketing`
* `pool` = eU
* `incentives[]` = \[U, eU, BABY]
* `tower_incentives`, `lp`, `slippage_tolerance`, `staking_contract`
* `entry_fee_rate`, `entry_fee_recipient`

***

### Events (Examples)

* `oracle_update_prices`
* `deposit` (with `user_shares_minted`, `fee_shares_minted`, `entry_fee_rate`)
* `bond` / `add_liquidity` / `remove_liquidity`
* `request_redemption` / `complete_redemption`
* `claim_incentives`

***

### Operational Notes

* Oracle must initialize prices for **U, eU, and BABY** before vault operations.
* Preview endpoints simulate expected outcomes; real results may differ slightly.
* If `entry_fee_recipient` = depositor, all shares accrue to the same account.

***