# System Overview

USDREFI is a tokenized vault on Celo that accepts USDC deposits and issues USDREFI receipt tokens at a fixed 1:1 rate. The underlying capital is manually deployed by the Foundation multisig Safe into curated regenerative credit pools, generating real-world yield distributed to holders through Merkl.

## Design Principles

* **Manual capital management** over automated strategy wrappers (POC simplicity)
* **Identity-gated access** via API-assigned tiers, not on-chain identity checks
* **Swap-only exit** — no direct vault withdrawals; Uniswap pool is the sole exit path
* **Separate reward streams** for holders and LPs
* **Foundation Safe retains full admin control** with emergency overrides
* **ERC-4626 compliance** for ecosystem tooling compatibility

## Component Map

| Component             | Type                      | Admin              | Status       |
| --------------------- | ------------------------- | ------------------ | ------------ |
| USDREFI Vault         | ERC-4626 (Solidity)       | Foundation Safe    | To deploy    |
| TierRegistry          | Custom mapping (Solidity) | Foundation Safe    | To deploy    |
| Foundation Safe       | Gnosis Safe 2-of-3        | Signers: M + L + 1 | To deploy    |
| Reward Safe           | Gnosis Safe 2-of-3        | Signers: M + L + 1 | To deploy    |
| Tier Assignment API   | Off-chain service         | Foundation         | To build     |
| Merkl Holder Campaign | Merkl protocol            | Reward Safe        | To configure |
| Merkl LP Campaign     | Merkl protocol            | Reward Safe        | To configure |
| Uniswap V4 Pool       | Concentrated Liquidity    | Permissionless     | To deploy    |
| Frontend App          | React / Next.js           | L                  | To build     |
| Dune Dashboard        | Dune Analytics            | M                  | To build     |

## Separation of Concerns

The system is designed around clear boundaries:

* **Vault contract** → deposits and share accounting
* **Foundation Safe** → capital allocation and governance parameters
* **Reward Safe** → funds reward distributions
* **TierRegistry** → access control
* **Merkl** → reward computation and claims
* **Uniswap pool** → secondary liquidity and exit

## POC Simplifications

Several components are intentionally deferred for the proof-of-concept. These are documented upgrade paths, not missing features:

| Removed for POC          | Replaced by                           | Upgrade path               |
| ------------------------ | ------------------------------------- | -------------------------- |
| Strategy wrapper         | Manual Safe deposits to Textile/Quipu | On-chain strategy adapter  |
| Yield router contract    | Reward Safe + Merkl campaigns         | Automated split logic      |
| Harvest keeper bot       | Monthly off-chain snapshots           | Automated harvest          |
| Direct vault withdrawals | Uniswap swap-to-exit                  | Emergency toggle available |
| Dynamic pricePerShare    | Fixed 1:1 + side-stream rewards       | Accruing share price       |