# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.polystream.xyz/smart-contracts/core.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.