> For the complete documentation index, see [llms.txt](https://docs.vesper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vesper.finance/vesper-2/architecture.md).

# Architecture

Vesper 2 uses a modular smart-contract architecture that separates user interactions, asset management, staking, and yield generation.

Each product has its own deployment of the core protocol contracts, enabling Vesper USD and Vesper ETH to operate independently with separate assets, configurations, and underlying strategies. Vesper BTC is planned as an additional product.

The architecture consists of seven primary components: Gateway, Treasury, PeggedToken, StakingVault, YieldDistributor, YieldManager, and YieldVaults.

#### Core Contracts

**Gateway**

The Gateway is the primary entry and exit point for Vesper 2, managing deposits and redemptions between underlying assets and Vesper tokens.

During deposits, it validates the supplied asset against the product's configured requirements before coordinating the minting of USDv or ETHv.

For redemptions, the process is reversed. The corresponding Vesper tokens are burned and the underlying asset is returned, subject to available liquidity and withdrawal controls.

The Gateway also supports configurable deposit and redemption fees, minimum-output protection, and an optional withdrawal-delay mechanism separate from the cooldown period used when unstaking.

**Treasury**

The Treasury manages the assets backing each Vesper 2 product and coordinates capital allocation into the underlying YieldVaults.

Assets can remain idle to support redemptions or be deposited into authorized YieldVaults, with the Treasury receiving shares representing its positions.

The Treasury also maintains product-level configurations, including supported assets, price adapters, price tolerances, and operational permissions.

As underlying strategies generate returns, the Treasury tracks excess reserve value and provides the harvesting mechanism through which generated yield enters the distribution system.

**PeggedToken**

The PeggedToken contract implements USDv and ETHv as ERC-20 tokens with Permit support. These tokens represent the liquid, unstaked position within each product and serve as the underlying assets for their corresponding StakingVaults.

Minting and burning occur through the Gateway during normal protocol operations, ensuring issuance and redemption remain subject to the product's configured controls.

The contract also includes owner-controlled permissions for updating the Gateway and Treasury addresses and managing an address blacklist. Blacklisted addresses are restricted from transferring or receiving tokens. PeggedToken is non-upgradeable.

**StakingVault**

The StakingVault implements sUSDv and sETHv as ERC-4626 vault shares.

It manages staking, share issuance and conversion, cooldown and instant unstaking, and the accounting required to distribute yield to stakers.

The StakingVault receives accrued yield through the YieldDistributor, increasing the underlying value represented by each existing share without increasing the number of shares held by users.

When a cooldown unstaking request is submitted, the corresponding shares are burned and the assets are reserved for withdrawal. These assets stop earning yield during the cooldown period.

**YieldDistributor**

The YieldDistributor manages the gradual release of harvested yield into the corresponding StakingVault.

Rather than distributing yield in a single transaction, it maintains a configurable distribution schedule and tracks accrued and undistributed amounts.

When additional yield is harvested during an active distribution, the remaining balance can be combined with the new amount and incorporated into an updated schedule.

The StakingVault retrieves accrued yield through `pullYield`, incorporating it into its ERC-4626 share accounting.

If the StakingVault has no shares outstanding, yield accrual pauses and the remaining distribution schedule is shifted forward.

**YieldManager**

The YieldManager coordinates the harvesting and distribution of yield generated by the underlying strategies.

An authorized keeper can trigger `harvestAndDistribute`, which performs three operations:

1. **Harvest:** Retrieve excess underlying assets from the Treasury.
2. **Mint:** Deposit those assets through the Gateway to mint the corresponding Vesper tokens.
3. **Distribute:** Forward the minted tokens to the YieldDistributor for gradual distribution to stakers.

YieldManager uses role-based permissions to control harvesting operations and administrative recovery functions. Each live product has its own YieldManager deployment.

**YieldVault**

YieldVaults form the strategy-execution layer underneath Vesper 2. Each YieldVault is an ERC-4626 multi-strategy vault capable of allocating capital across configured strategies interacting with external DeFi protocols.

The Treasury interacts with these vaults on behalf of the corresponding product, while users interact with the Gateway and StakingVault. This separation allows underlying strategies to be adjusted or replaced without requiring users to migrate their Vesper token positions.

#### Roles & Permissions

Vesper 2 uses role-based access control and contract-specific ownership permissions to separate protocol administration, product configuration, capital management, and harvesting.

The Treasury defines the following roles:

| Role                 | Responsibility                                                                                 |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| `DEFAULT_ADMIN_ROLE` | High-level administration, including asset whitelist management and administrative permissions |
| `MAINTAINER_ROLE`    | Configuration of price adapters, price tolerances, and related operational settings            |
| `KEEPER_ROLE`        | Capital movement between Treasury and YieldVaults, and selected asset operation controls       |
| `UMM_ROLE`           | Harvesting excess Treasury reserves                                                            |

YieldManager has its own `KEEPER_ROLE`, which authorizes execution of the harvesting and distribution process, and `DEFAULT_ADMIN_ROLE` for administrative recovery operations.

Other contracts maintain their own administrative permissions. PeggedToken uses ownership controls for managing contract references and address blacklisting, while StakingVault and YieldDistributor have permissions governing their respective operational settings. Treasury also uses a three-day delay for transfers of its default administrator role.

#### Contract Upgradeability

Vesper 2 uses transparent upgradeable proxies for selected contracts, allowing authorized implementation upgrades without migrating existing contract state or changing proxy addresses.

Under this model, a proxy maintains the contract's address and stored state while delegating execution to an implementation contract. Upgrades are managed through a separate ProxyAdmin contract.

The deployed contracts use the following architecture:

| Contract         | Upgradeability                |
| ---------------- | ----------------------------- |
| Gateway          | Transparent upgradeable proxy |
| Treasury         | Non-upgradeable               |
| PeggedToken      | Non-upgradeable               |
| StakingVault     | Transparent upgradeable proxy |
| YieldDistributor | Transparent upgradeable proxy |
| YieldManager     | Non-upgradeable               |

YieldVaults are separate strategy-layer contracts with their own implementation and administrative arrangements.

Control over upgrades and contract administration forms an important part of Vesper 2's security model.

#### Protocol Parameters

Each Vesper 2 product supports configurable parameters to accommodate differences in its underlying assets, liquidity requirements, and strategies.

These include:

* StakingVault cooldown durations
* Instant-unstake fees (10 bps) and fee receivers
* Gateway deposit and redemption fees
* Supported assets and operational whitelists
* Price adapter configurations and price tolerances
* Gateway withdrawal-delay settings
* Yield distribution durations
* Treasury capital allocation and withdrawal permissions

Parameters can differ between products. Vesper USD and Vesper ETH maintain independent configurations for their respective underlying assets and yield strategies.

All configurations remain subject to the permissions and bounds defined by the deployed contracts.

#### Composability

Vesper 2 uses established Ethereum token standards to support integration with other DeFi applications.

USDv and ETHv implement ERC-20 with Permit support, allowing them to function as standard transferable assets within compatible protocols.

Their staked counterparts, sUSDv and sETHv, implement ERC-4626, providing standardized vault-share accounting and interfaces for interacting with yield-bearing positions. This enables external applications to integrate Vesper tokens without needing to manage or understand the underlying strategies.

For example, a protocol integrating sUSDv can interact with its ERC-4626 interface while Vesper manages capital allocation, harvesting, and yield distribution across the underlying strategies.
