Glossary

Terms and definitions for Reserve Folio protocol

Core Concepts

Folio

A portfolio of ERC20-compliant assets managed onchain. Folios are represented as ERC20 tokens themselves, with each token representing a proportional share of the underlying basket of assets.

Example: A “DeFi Blue Chip” Folio might hold ETH, WBTC, and stablecoins in specific proportions.

Basket

The collection of ERC20 tokens held by a Folio, along with their target weights or proportions.

Composition: Can be changed through governance

Rebalancing: Adjusted through dutch auctions

Basket Unit (BU)

A standardized unit representing the ideal composition of the basket. Used to calculate surpluses and deficits during rebalancing.

Unit: Often expressed as quantities like D27{tok/BU} (tokens per basket unit)

Collateral

The underlying ERC20 tokens held in a Folio’s basket. Users deposit collateral when minting Folio shares and receive collateral when redeeming.

Share

An ERC20 token representing proportional ownership of a Folio’s assets. Users receive shares when minting and burn shares when redeeming.

Pro-rata: Claims to the underlying basket are always proportional to share ownership

Rebalancing Terms

Rebalance

The process of adjusting a Folio’s basket composition to match target weights. Executed through a series of dutch auctions over a defined period.

Initiated by: REBALANCE_MANAGER role

Duration: Controlled by TTL (time-to-live)

Rebalance Target

A set of tokens with target weights that the Folio aims to achieve through rebalancing.

Components:

• Target tokens list
• Weight ranges (low, spot, high)
• Price ranges for each token
• Rebalance limits

Rebalance Limits

Range of basket units per share that define the rebalancing path.

Structure:

struct RebalanceLimits {
  uint256 low;  // D18{BU/share} Buy up to this level
  uint256 spot; // D18{BU/share} Point estimate
  uint256 high; // D18{BU/share} Sell down to this level
}

Weight Range

The acceptable range of weights for a token in the basket.

Structure:

struct WeightRange {
  uint256 low;  // D27{tok/BU} Minimum weight
  uint256 spot; // D27{tok/BU} Point estimate  
  uint256 high; // D27{tok/BU} Maximum weight
}

Control: If weightControl is enabled, AUCTION_LAUNCHER can adjust within range

TTL (Time-to-Live)

The maximum duration a rebalance can remain active. After TTL expires, no new auctions can be started (though existing auctions can complete).

Extension: Can be extended by AUCTION_LAUNCHER near expiration

Surplus

When the Folio holds more of a token than the target basket composition requires. Surpluses are sold during rebalancing.

Calculation: Relative to RebalanceLimits.high

Deficit

When the Folio holds less of a token than the target basket composition requires. Deficits are bought during rebalancing.

Calculation: Relative to RebalanceLimits.low

Auction Terms

Dutch Auction

An auction mechanism where the price starts high and decreases over time until a buyer accepts. Used for all token swaps during rebalancing.

Curve: Exponential decay from start price to end price

Termination: When fully filled or time expires

Auction

A specific instance of trading during rebalancing where participants can exchange tokens with the Folio at dynamically decreasing prices.

Limitation: Only one auction can be active at a time per Folio

Participation: Generally permissionless (unless restricted to trusted fillers)

Start Price

The initial (most optimistic) price at the beginning of a dutch auction. Calculated from the extreme bounds of the provided price ranges.

Direction: Favorable to the Folio (typically above or below market depending on buy/sell)

End Price

The final (most pessimistic) price at the end of a dutch auction. Calculated from the opposite extreme of the price ranges.

Direction: Less favorable to the Folio but still within acceptable bounds

Price Range

The acceptable range of prices for a token during an auction.

Structure:

struct PriceRange {
  uint256 low;  // D27{UoA/tok} Lower bound
  uint256 high; // D27{UoA/tok} Upper bound
}

Maximum Range: 100x (1e2) - auction can span at most 4 orders of magnitude

Lot Size / Sell Amount

The quantity of sell token available in an auction. Determined by the limiting factor between surplus and deficit.

Dynamic: Can increase or decrease over time depending on which side is limiting

Bid

An offer to exchange tokens with the Folio at the current auction price. Participants send buy tokens and receive sell tokens.

Partial Fills: Allowed - can fill any amount up to sellAmount

Restricted Period

The initial period of a rebalance when only the AUCTION_LAUNCHER can open auctions. Provides the trusted launcher time to act before permissionless participation.

Duration: Typically includes a 120s buffer minimum

Extension: Gets bumped when AUCTION_LAUNCHER actively uses it

Permissionless Period

The period after the restricted period when anyone can open auctions with default parameters.

Purpose: Ensures liveness even if AUCTION_LAUNCHER is offline

Parameters: Uses spot values from rebalance configuration

Role Terms

DEFAULT_ADMIN_ROLE

The primary administrative role with full control over Folio configuration.

Expected: Timelock of Slow Folio Governor

Powers:

• Add/remove tokens from basket
• Set fees
• Configure auction parameters
• Manage roles
• Close auctions

Security: Highest trust level, longest timelock

REBALANCE_MANAGER

The role responsible for initiating and managing rebalances.

Expected: Timelock of Fast Folio Governor

Powers:

• Start rebalances with parameters
• End rebalances
• Close auctions
• Set rebalance limits

Security: Medium trust level, shorter timelock

AUCTION_LAUNCHER

A semi-trusted role that opens auctions and provides market-aware parameters.

Expected: EOA or multisig

Powers:

• Open auctions within approved ranges
• Select price subranges (if priceControl enabled)
• Adjust basket weights (if weightControl enabled)
• Perform atomic swaps (if ATOMIC_SWAP mode)
• End rebalances

Limitations: Can only operate within bounds set by REBALANCE_MANAGER

Risk: Can cause value leakage if malicious, but cannot guarantee they benefit (except in ATOMIC_SWAP mode)

Price Control Modes

PriceControl.FULL

The AUCTION_LAUNCHER has no control over prices and must use governance-provided ranges.

Security: Highest - no price manipulation possible

Execution: May be less optimal due to stale prices

Best for: Folios with untrusted or public launchers

PriceControl.PARTIAL

The AUCTION_LAUNCHER can select a subset of the governance-approved price range for each auction.

Security: Medium - can start auctions at suboptimal prices

Risk: Value leakage to MEV searchers possible

Execution: Better price precision, improved execution

Best for: Folios with semi-trusted launchers

PriceControl.ATOMIC_SWAP

The AUCTION_LAUNCHER can perform atomic swaps at fixed prices within the approved range.

Security: Lowest - full price control

Risk: Can cause value leakage AND be the beneficiary

Execution: Best possible - no MEV leakage, optimal prices

Best for: Highly trusted, sophisticated launchers

Fee Terms

TVL Fee / Management Fee

A continuous fee charged on assets under management (AUM), implemented as share inflation.

Rate: Expressed annually (e.g., 50 bps = 0.5% per year)

Minimum: 15 basis points

Maximum: 10% annually

Accrual: Every 24 hours (as of v4.0.0)

DAO Cut: Minimum 15 bps goes to ecosystem DAO

Mint Fee

A one-time fee charged when minting Folio shares.

Minimum: 15 basis points

Maximum: 5%

DAO Cut: Minimum 15 bps goes to ecosystem DAO

Note: No redemption fee

Fee Floor

The minimum fee that must be charged, with the minimum going to the ecosystem DAO.

Default: 15 basis points

Adjustment: Can be lowered by DAO globally or per-Folio

Purpose: Ensures sustainable funding for protocol development

Fee Recipient

An address that receives a portion of collected fees.

Configuration: Set by governance

Multiple Recipients: Supported - fees split by configured portions

Staking Terms

StakingVault

A contract that holds staked Folio tokens and distributes rewards.

Purpose:

• Earn rewards in multiple tokens
• Gain voting power for governance
• Align long-term incentives

Owner: Community Governor

Staked Token

The underlying token (typically Folio shares) deposited into the StakingVault.

Voting Power: Staked tokens provide governance voting rights

Reward Token

A token distributed to stakers as rewards.

Multiple Rewards: StakingVault supports simultaneous distribution of multiple reward tokens

Configuration: Added/removed by vault owner

Reward Half-Life

The time period over which unclaimed rewards decay by half.

Purpose: Creates time preference for claiming rewards

Configuration: Set per reward token by vault owner

Unstaking Delay

A waiting period between initiating unstaking and being able to withdraw tokens.

Purpose:

• Prevent governance attacks (stake-vote-unstake)
• Support optimistic governance patterns
• Align long-term interests

Configuration: Set by vault owner, can be 0

Governance Terms

FolioGovernor

The canonical governance contract for Folios.

Type: Time-based governor using OpenZeppelin Governor framework

Voting Token: Typically staked Folio shares from StakingVault

Types:

• Slow Governor (long timelock)
• Fast Governor (shorter timelock)

Timelock

A delay between when a governance proposal passes and when it can be executed.

Purpose: Gives users time to react to governance decisions (e.g., redeem before unfavorable changes)

Duration: Varies by governor type and urgency of powers

Optimistic Governance

A governance pattern where actions take effect immediately but can be challenged and reverted.

Slashing: v5.0.0 adds StakingVault.burn() to enable slashing malicious proposers

Trade-off: Faster execution vs. risk of malicious actions

Community Governor

The governor that controls the StakingVault.

Powers:

• Add/remove reward tokens
• Set reward parameters
• Configure unstaking delay

Separate from: Folio governors (different scope of control)

Technical Terms

D18

A precision multiplier representing 1e18 (18 decimals).

Usage: Percentages, simple ratios

Example: D18{1} is a percentage value with 18 decimal precision

D27

A precision multiplier representing 1e27 (27 decimals).

Usage: Prices, exchange rates, high-precision ratios

Example: D27{UoA/tok} is a price with 27 decimal precision

Unit of Account (UoA)

A standardized unit for expressing prices and values.

Common: nanoUSD (1 billionth of a USD)

Flexibility: Can be any consistent unit

nanoUSD

One billionth of a USD (1e-9 USD), commonly used as the Unit of Account.

Why: Provides precision for assets with very low or very high USD values

Quanta / Quantum

The smallest indivisible unit of a token, considering its decimals.

Example: For USDC (6 decimals), 1 quantum = 0.000001 USDC

Read-Only Reentrancy

A vulnerability where external contracts read Folio state during a state change and rely on inconsistent data.

Protection: Check stateChangeActive() before reading state

Note: Folio itself is protected; consuming protocols must check

Trusted Fillers

Whitelisted entities that can provide async fills for auctions.

Implementation: CoW Swap integration

Benefits: Better prices, MEV protection

Configuration: Enabled per Folio by governance

MEV (Maximal Extractable Value)

Profit that can be extracted by reordering, inserting, or censoring transactions.

In Auctions: Searchers can extract value by bidding at optimal moments

Mitigation: Tight price ranges, trusted fillers, atomic swaps

DAO Terms

FolioDAOFeeRegistry

Contract that manages fees paid to the broader ecosystem DAO.

Responsibilities:

• Set fee floors
• Collect DAO portion of fees
• Configure per-Folio fee overrides

Owner: Ecosystem DAO

FolioVersionRegistry

Contract that tracks approved versions of FolioDeployer implementations.

Purpose: Ensure Folios can upgrade to vetted implementations

Owner: Ecosystem DAO

RoleRegistry

External contract that manages role assignments across the ecosystem.

Interface: Must implement IRoleRegistry

Dependency: Required for Folio deployment

Contract Terms

FolioDeployer

Contract that deploys new Folio instances.

Versioning: Multiple versions can exist, tracked by FolioVersionRegistry

Upgrades: New versions deployed by DAO

FolioProxy

A proxy contract that delegates calls to Folio implementation.

Purpose: Enable upgrades while maintaining storage and address

Validation: Checks upgrades against FolioVersionRegistry

GovernanceDeployer

Contract that deploys governance systems (staking tokens and governors).

Deploys:

• StakingVault
• FolioGovernor instances
• Associated contracts

Related Documentation

FAQ

Frequently asked questions

Unit System

Detailed unit documentation

Architecture

System architecture overview

API Reference

Contract API documentation