Frequently Asked Questions

Common questions about Reserve Folio protocol

General Questions

What is Reserve Folio?

Reserve Folio is a protocol for creating and managing portfolios of ERC20-compliant assets entirely onchain. Folios are designed to be used as a single source of truth for asset allocations, enabling composability of complex, multi-asset portfolios.

Think of it as an onchain index fund or ETF, but fully decentralized and programmable.

How is Folio different from other index protocols?

Key Differentiators:

1. Sophisticated Rebalancing: Dutch auction system with configurable price ranges and basket-level optimization
2. Governance Flexibility: Three-tier role system allowing different levels of control and time sensitivity
3. High Fidelity: Designed to maintain precise allocations even under timelock delays
4. MEV Protection: Integration with trusted fillers (CoW Swap) for better execution
5. Composability: Can be used as collateral or building block in other DeFi protocols

What chains does Folio support?

Folio works on any EVM-compatible chain with block times ≤ 30 seconds.

Commonly targeted chains:

• Ethereum Mainnet
• Base
• Arbitrum
• Optimism
• Polygon

See Chain Assumptions for details.

Is Reserve Folio audited?

Yes! Multiple comprehensive audits by leading firms:

• Trust Security (v1.0.0)
• Cantina Competition (multiple versions)
• Trail of Bits (v2.0.0, v4.0.0)
• Pashov Audit Group (v4.0.0+)

See Security Audits for full details.

Using Folios

How do I mint Folio tokens?

To mint Folio tokens:

1. Approve each collateral token for the Folio contract
2. Call mint(uint256 shares, uint256 minAmountOut) with desired share amount
3. The Folio calculates required token amounts pro-rata
4. Tokens are transferred from your wallet
5. Folio shares are minted to your address

Fees: Mint fee applies (configurable, minimum 15 bps)

See the Minting & Redeeming guide for details.

How do I redeem Folio tokens?

To redeem Folio tokens:

1. Call redeem(uint256 shares) with the amount to redeem
2. The Folio calculates token amounts pro-rata to your share
3. Your Folio shares are burned
4. Collateral tokens are sent to your address

Fees: No redemption fee (only mint and TVL fees)

Note: You receive all tokens in the basket proportionally.

What fees do I pay?

Two types of fees:

1. TVL Fee (Management Fee):
   • Charged continuously on AUM
   • Minimum: 15 bps annually
   • Maximum: 10% annually
   • Implemented as share inflation
2. Mint Fee:
   • Charged on minting
   • Minimum: 15 bps
   • Maximum: 5%
   • No redemption fee

DAO Fee Floor: 15 bps goes to ecosystem DAO (can be lowered by DAO)

See Fee Structure for details.

Can I use Folio tokens as collateral?

Yes! Folio tokens are standard ERC20 tokens and can be used as collateral in other DeFi protocols.

Considerations:

• Check for read-only reentrancy with stateChangeActive()
• Folio composition can change through rebalancing
• Value should be calculated based on underlying assets

Rebalancing & Auctions

How does rebalancing work?

Rebalancing follows a structured process:

1. Start Rebalance: REBALANCE_MANAGER sets target weights and price ranges
2. Open Auction: AUCTION_LAUNCHER or anyone (after delay) opens an auction
3. Bidding: Anyone can bid on token pairs during the auction
4. Repeat: Multiple auctions can run during the rebalance
5. Complete: Rebalance completes when targets are met or TTL expires

See Rebalancing for comprehensive details.

What is a Dutch auction?

A Dutch auction starts at a high price and decreases over time until a buyer accepts.

In Reserve Folio:

• Price decays exponentially from startPrice to endPrice
• Designed so ideal clearing price (with slippage) lies between bounds
• First bidder to accept current price wins
• Can be filled partially or fully

Benefits:

• Price discovery
• No order book needed
• MEV-resistant (with tight ranges)

Can I participate in auctions?

Yes! Auctions are permissionless by default.

To participate:

1. Call getBid() to see current auction state
2. Call bid() with desired fill amount
3. Send buy tokens, receive sell tokens

Requirements:

• Must meet the current price ratio
• Must have approved buy token
• Some Folios may restrict to trusted fillers only

Profit opportunity: Buy at better prices than secondary markets during rebalancing.

What are trusted fillers?

Trusted fillers are whitelisted entities that can provide async fills for auctions.

Current Implementation: CoW Swap integration

Benefits:

• Better prices through professional market makers
• MEV protection
• Access to off-chain liquidity

Configuration: Can be enabled/disabled per Folio by governance

Restrictions: Some Folios may disable permissionless bids and only allow trusted fillers.

Why did the rebalance fail?

Common reasons:

1. TTL Expired: Rebalance time-to-live ran out
2. Price Excursion: Market prices moved outside approved ranges
3. Auction Launcher Offline: No one opened auctions during restricted period
4. Insufficient Liquidity: No bidders at auction prices
5. Governance Action: Rebalance manually ended

Recovery: Start a new rebalance with updated parameters.

Governance

What are the three roles?

Folios have a three-tier governance system:

1. DEFAULT_ADMIN_ROLE:
   • Expected: Timelock of Slow Folio Governor
   • Powers: Add/remove assets, set fees, configure roles
   • Use: Major structural changes
2. REBALANCE_MANAGER:
   • Expected: Timelock of Fast Folio Governor
   • Powers: Start/end rebalances, set rebalance parameters
   • Use: Operational rebalancing decisions
3. AUCTION_LAUNCHER:
   • Expected: EOA or multisig
   • Powers: Open auctions within approved ranges
   • Use: Timely auction execution with market awareness

See Roles for details.

How do I propose changes?

Changes are proposed through the governance system:

1. Create Proposal: Submit proposal to appropriate governor
2. Voting Period: Token holders vote
3. Timelock: Successful proposals enter timelock
4. Execution: After delay, proposal can be executed

Which Governor?

• Slow Governor: Structural changes (add/remove tokens, fees)
• Fast Governor: Rebalancing operations
• Direct: AUCTION_LAUNCHER for auction timing

What is the AUCTION_LAUNCHER role?

The AUCTION_LAUNCHER is a semi-trusted role that opens auctions.

Responsibilities:

• Open auctions promptly when rebalancing is needed
• Provide up-to-date price estimates (if price control enabled)
• Optimize basket weights (if weight control enabled)
• End rebalances if market conditions become dangerous

Limitations:

• Can only operate within governance-approved ranges
• Cannot prevent permissionless auctions (after delay)
• Cannot steal funds (but can cause value leakage in some configurations)

Fallback: If offline, anyone can open auctions after restricted period.

Can governance rugpull users?

Short answer: Not immediately, but governance has significant power.

Protections:

• Timelock delays on major changes
• Cannot directly steal user funds
• Users can redeem during timelock period

Risks:

• Can add malicious tokens (users should redeem before they’re added)
• Can set unfavorable rebalance parameters
• Can change fees (within limits)

Best Practice: Monitor governance proposals and redeem if you disagree with changes.

Staking

What is the StakingVault?

The StakingVault holds staked Folio tokens and distributes rewards.

Features:

• Stake Folio tokens
• Earn multiple reward tokens simultaneously
• Voting power for governance
• Configurable unstaking delay

Use: Central voting token for all Folio governance types.

How do rewards work?

Rewards are distributed continuously based on staked balances.

Mechanism:

• Rewards drip at a configurable rate
• Rate decays with a half-life (exponential decay)
• Multiple reward tokens supported simultaneously
• Claim anytime

Configuration: Controlled by StakingVault owner (Community Governor).

What is the unstaking delay?

An optional delay before staked tokens can be withdrawn.

Purpose:

• Prevent governance attacks (stake, vote, unstake)
• Align long-term interests
• Security for optimistic governance

Configuration: Set by StakingVault owner, can be 0 (no delay).

Can I lose my staked tokens?

In v5.0.0+, yes - through optimistic governance slashing.

Mechanism: StakingVault.burn() function

Use Case: Slash malicious governance proposers in optimistic governance systems

Risk: Only applies if the Folio uses optimistic governance patterns

Mitigation: Don’t propose malicious governance actions.

Technical Questions

What tokens are supported?

Supported:

• Standard ERC20 tokens
• Tokens with missing return values
• Tokens that revert on zero-value transfers
• Flash mintable tokens
• Rebasing tokens (Folio only, with caveats)

NOT Supported:

• Multiple entrypoints
• Pausable / blocklist (USDC, USDT risky)
• Fee-on-transfer
• ERC777 / callback tokens
• Rebasing tokens (StakingVault)

See Token Compatibility for details.

What are the decimal limits?

Folio Collateral: ≤ 27 decimals

StakingVault Tokens: ≤ 21 decimals

Reason: Prevents overflow with D18/D27 precision multipliers.

See Valid Ranges for more limits.

How do I check for reentrancy?

Before relying on Folio state in external contracts:

(bool rebalanceActive, bool asyncActionActive) = folio.stateChangeActive();
require(!rebalanceActive && !asyncActionActive, "State change active");

Why: Protects against read-only reentrancy

When: Before reading Folio balances or using Folio tokens as collateral

What is the unit system?

Folio uses a comprehensive unit system with precision multipliers:

• D18: 1e18 precision (percentages, ratios)
• D27: 1e27 precision (prices, exchange rates)
• , , : Token amounts
• : Seconds

Examples:

• D18{1}: Percentage with 18 decimals
• D27{tok/share}: Token per share ratio
• D27{UoA/tok}: Price in nanoUSD per token

See Unit System for details.

Can I fork/deploy my own Folio?

Yes! Reserve Folio is open source.

Steps:

1. Clone the repository
2. Review deployment scripts
3. Configure parameters
4. Deploy via governance deployer
5. Initialize with tokens and settings

Requirements:

• RoleRegistry deployment
• FolioDAOFeeRegistry setup
• Governance structure

See Development for details.

Troubleshooting

Why did my mint fail?

Common reasons:

1. Insufficient Allowance: Approve all collateral tokens first
2. Insufficient Balance: Don’t have enough of one or more tokens
3. Below Minimum: Output below minAmountOut parameter
4. Zero Output: Would receive 0 shares (add more tokens)
5. Token Transfer Failed: One of the collateral tokens reverted

Solution: Check allowances, balances, and token compatibility.

Why can't I redeem?

Possible reasons:

1. Insufficient Balance: Don’t have enough Folio shares
2. Token Removed: A token was removed from basket (rare, governance action)
3. Rebalancing Issue: Temporary issue during rebalance (unlikely)

Solution: Check your share balance and Folio basket composition.

Where is my token?

If a token doesn’t appear after redeeming:

1. Check Balance: View token balance in wallet
2. Add to Wallet: Manually add token contract address to wallet
3. Check Basket: Verify token is still in Folio basket
4. Check Transaction: Review transaction logs for transfers

Remember: Redemptions are pro-rata - you get small amounts of each token.

My transaction is expensive!

Gas costs vary significantly by chain:

• Ethereum Mainnet: $50-200+ (high)
• Base/Optimism: $1-5 (low)
• Arbitrum: $0.50-2 (very low)
• Polygon: under $0.50 (very low)

Tips:

• Use L2s for lower costs
• Wait for low gas periods (weekends, late night UTC)
• Batch operations when possible

Getting Help

Need More Help?

Resources:

• 📚 Full Documentation - Comprehensive guides
• 💬 Community Discord - Ask questions
• 🐛 GitHub Issues - Report bugs
• 🛡️ Security - Report vulnerabilities

Before asking:

1. Search this FAQ
2. Check relevant documentation section
3. Review example transactions on block explorer
4. Provide details: transaction hash, wallet address, error message

Related Documentation

Glossary

Terms and definitions

Quickstart

Get started quickly

Examples

Code examples and tutorials

API Reference

Contract documentation