# Core

### Purpose

* **Unified Management:** Centralizes interactions between users, adapters, and underlying DeFi protocols.
* **Yield Optimization:** Automates asset allocation, yield harvesting, reward distribution, and fee handling.
* **Protocol Flexibility:** Allows dynamic registration, removal, and switching of underlying DeFi protocols.

### Key Contracts and Responsibilities

#### [`ProtocolRegistry.sol`](https://github.com/polystream-core/polystream-contracts/blob/main/src/core/ProtocolRegistry.sol)

**Role:**

* Manages and stores information about registered DeFi protocols and their adapters.
* Allows adding or removing protocols and adapters dynamically.

**Functions:**

* `registerProtocol`: Add new protocols.
* `registerAdapter`: Link specific adapters to protocols and assets.
* `removeAdapter`: Remove adapters from registry.
* `setActiveProtocol`: Set the currently active protocol for asset deposits and yield harvesting.

**Interactions:**

* Utilized by the `CombinedVault` to query and interact with appropriate adapters based on registered protocols.

#### [`CombinedVault.sol`](https://github.com/polystream-core/polystream-contracts/blob/main/src/core/CombinedVault.sol)

**Role:**

* Handles user asset deposits, withdrawals, and yield harvesting.
* Implements time-weighted accounting to fairly distribute harvested rewards.
* Allocates funds evenly across registered DeFi protocols.

**Key Features:**

* **Epoch-based harvesting:** Harvests and distributes yields to users periodically (every epoch).
* **Time-weighted rewards:** Ensures fair yield distribution based on how long funds were deposited during each epoch.
* **Protocol flexibility:** Dynamically adds/removes underlying protocols and redistributes funds accordingly.

**Main Functionalities:**

* `deposit`: Users deposit assets into the vault, automatically allocated to registered protocols.
* `withdraw`: Users withdraw assets, applying fees if withdrawn prematurely within the same epoch.
* `checkAndHarvest`: Periodically harvests yields from all active protocols, distributing earnings based on users' time-weighted shares.

**Important Accounting Details:**

* Tracks individual user deposits, balances, and entry times.
* Maintains total user and adapter balances, ensuring accuracy in rewards and withdrawals.
* Manages early withdrawal fees, converting these fees into additional rewards for long-term users.

#### Interfaces ([`IRegistry.sol`](https://github.com/polystream-core/polystream-contracts/blob/main/src/core/interfaces/IRegistry.sol), [`IVault.sol`](https://github.com/polystream-core/polystream-contracts/blob/main/src/core/interfaces/IVault.sol))

* **`IRegistry` Interface:** Standardizes registry functionalities for protocol and adapter management, allowing consistency across implementations.
* **`IVault` Interface:** Defines essential vault functions such as deposits, withdrawals, yield harvesting, and user balance tracking, ensuring consistent behavior across implementations.