Developer Spec

Developers testing Nest Vaults can get pUSD (ERC-20 stablecoin like token on Plume's devnet), PLUME or WPLUME here: https://test-faucet.plumenetwork.xyz/)

Overview

Nest implements the Nucleus BoringVault architecture, which was inspired by the Se7enSeas team's open-source framework. This architecture provides a flexible and secure vault system that allows for intricate yield-generating strategies while maintaining robust security measures.

Nest is utilizing this architecture to enable users to deposit stablecoins (like pUSD) and earn yield through strategically deployed assets.

Architecture Components

The Nest implementation consists of four core components that work together to provide a secure and efficient vault system:

1. BoringVault

The BoringVault is the ERC20 token contract that serves as the foundation of the system:

• Acts as the custodian for all deposited assets

• Implements ERC20 token standard for vault shares

• Exposes permissions for minting and burning vault shares

• Delegates complex functionality to external components

• Represents ownership shares in the underlying asset pool

2. Teller

The Teller facilitates user interactions with the vault:

• Defines logic for minting shares upon deposit

• Validates assets against a supported asset whitelist

• Queries asset values via the Accountant

• Calculates appropriate share amounts for deposits

• Can support different types of bridges (e.g., LayerZero)

• Implements protection against MEV exploitation:

  • Locks shares to depositor accounts for a set period

  • Enables permissioned refunds during the lock period

Deposit Example

For a deposit with the Teller:

1. User deposits an approved asset (e.g., 1 wstETH)

2. Teller converts the asset to ETH denomination using Accountant rates (e.g., 1 wstETH * 1.2 ETH/wstETH = 1.2 ETH)

3. Teller calculates shares based on vault exchange rate (e.g., 1.2 ETH / 1.5 ETH/Share = 0.8 Shares)

4. Shares are minted to the user's address but locked for the shareLockPeriod

3. Accountant

The Accountant provides essential price data:

• Serves as the source of truth for vault exchange rates

• Maintains valuation for each whitelisted deposit asset

• Enables multi-asset support by providing conversion rates

• Can enter a paused state to protect the vault if conditions are violated

• Relies on off-chain oracles for price data

4. Manager

The Manager ensures vault security for deployed strategies:

• Restricts possible vault strategies using a merkle tree system

• Assigns a merkle root to each strategist address

• Each leaf in the merkle tree defines permissible actions

• Verifies all transactions against the merkle proof

• Can support different merkle trees for different strategist roles

Security Example

For a lending operation on a protocol:

1. Strategist attempts to call a lending function

2. Manager verifies the call against the merkle tree

3. Verification checks:

   • Target contract address

   • Function selector

   • Sensitive parameters (e.g., ensuring recipient is the vault)

   • Whether ETH transfer is permitted

4. Transaction reverts if any requirements aren't met

Developer Specification

Testing Environment

Developers testing Nest should get pUSD (ERC-20 stablecoin) from Plume's devnet:

• Test faucet: https://test-faucet.plumenetwork.xyz/

Vault Properties

• Implementation: ERC20 (BoringVault)

• Assets Accepted: pUSD and other whitelisted assets determined by the Teller

• Vault Token: nRWA (represents ownership shares)

Functional Requirements

Deposit Process

• User deposits pUSD through the Teller

• Receives nRWA shares based on current exchange rate

• User must approve the BoringVault to transfer pUSD

• Note: Shares might be subject to a lock period for security depending on the Vault.

Withdrawal Process

• User submit a AtomicRequest transaction to AtomicQueue.

• User must approve the AtomicQueue to transfer nRWA

• Withdrawal amount is calculated based on current exchange rate

Exchange Rate Management

• Accountant maintains exchange rates

• Rates determine deposit and withdrawal values

• Protection mechanisms prevent manipulation

Strategy Management

• Manager controls deployment of vault assets into protocols

• Strategists execute approved transactions defined by merkle trees

• Security mechanisms verify all sensitive operations

View Functions

• Vault properties: name(), symbol(), totalAssets()

• Deposit/withdrawal previews

• Share ownership and valuation

• Current exchange rates

Security Considerations

• Share lock periods prevent flash loan attacks

• Permissioned refunds during lock periods

• Accountant pause functionality

• Merkle-based transaction validation

• Separate merkle trees for different strategist roles

Credit Attribution

Nest utilizes the Nucleus BoringVault architecture, which was inspired by the Se7enSeas team's open-source BoringVault repository. We acknowledge and credit Se7enSeas for creating this architecture and allowing its free distribution.

Audit Information

Previous audit reports for the Nucleus BoringVault implementation are available at: https://github.com/Ion-Protocol/nucleus-boring-vault/tree/master/audit