System Architecture

// contracts/Folio.sol (excerpt)
contract Folio is 
    IFolio,
    ERC20Upgradeable,
    AccessControlEnumerableUpgradeable,
    ReentrancyGuardUpgradeable,
    Versioned
{
    // Basket of ERC20 tokens
    EnumerableSet.AddressSet private basket;
    
    // Fee configuration
    FeeRecipient[] public feeRecipients;
    uint256 public tvlFee;  // D18{1/s}
    uint256 public mintFee; // D18{1}
    
    // Rebalancing state
    Rebalance private rebalance;
    Auction private auction;
    uint256 public maxAuctionLength; // {s}
    
    // ...
}

// contracts/governance/FolioGovernor.sol (excerpt)
contract FolioGovernor is 
    Governor,
    GovernorSettings,
    GovernorCountingSimple,
    GovernorVotes,
    GovernorVotesQuorumFraction,
    GovernorTimelockControl
{
    // Time-based governance with timelock
}

// contracts/staking/StakingVault.sol (excerpt)
contract StakingVault is 
    ERC4626Upgradeable,
    ERC20VotesUpgradeable,
    OwnableUpgradeable
{
    struct RewardInfo {
        uint256 payoutLastPaid;    // {s}
        uint256 rewardIndex;       // D18+decimals{reward/share}
        uint256 balanceAccounted;  // {reward}
        uint256 totalClaimed;      // {reward}
    }
    
    mapping(address => RewardInfo) public rewardTrackers;
    
    // Multi-reward system with exponential decay
}

Price(t) = startPrice * (endPrice/startPrice)^(t/duration)

Where:
- startPrice: Most optimistic exchange rate
- endPrice: Most pessimistic exchange rate  
- t: Time elapsed since auction start
- duration: Total auction length

uint256 constant AUCTION_WARMUP = 30; // {s}

// For surplus tokens (selling):
surplus = balance - (high_limit * high_weight * totalShares)

// For deficit tokens (buying):
deficit = (low_limit * low_weight * totalShares) - balance

// Sell amount is the minimum that satisfies both constraints
sellAmount = min(
    surplus_of_sell_token,
    deficit_of_buy_token * price
)

For tokens [A, B, C] in an auction:
- A→B, A→C (if A is surplus)
- B→A, B→C (if B is surplus)  
- C→A, C→B (if C is surplus)

// Complete rebalance conditions:
rebalanceLimits.low == rebalanceLimits.spot == rebalanceLimits.high

for each token:
    weight.low == weight.spot == weight.high
    // (prices don't need to converge)

struct WeightRange {
    uint256 low;   // D27{tok/BU} - buy up to this weight
    uint256 spot;  // D27{tok/BU} - point estimate
    uint256 high;  // D27{tok/BU} - sell down to this weight
}

struct FolioFlags {
    bool trustedFillerEnabled;
    RebalanceControl rebalanceControl;
    bool bidsEnabled;
}

// Disable permissionless bids (v5.0.0+)
folio.setBidsEnabled(false);

User pays fee → Split between DAO and Folio recipients
              |
              ├─→ DAO: minimum 15 bps (configurable)
              └─→ Folio recipients: remaining portion

// Applied once every 24 hours
uint256 constant ONE_DAY = 86400; // {s}

// Supply inflation calculation
if (block.timestamp >= lastPoke + ONE_DAY) {
    uint256 periods = (block.timestamp - lastPoke) / ONE_DAY;
    uint256 inflation = totalSupply * tvlFee * periods;
    
    // Split between DAO and fee recipients
    uint256 daoShares = inflation * daoFeeFraction;
    uint256 folioShares = inflation - daoShares;
}

// Applied during mint()
uint256 sharesBeforeFee = calculateShares(assets);
uint256 feeAmount = sharesBeforeFee * mintFee / D18;
uint256 sharesAfterFee = sharesBeforeFee - feeAmount;

// Fee distributed to DAO and recipients (no inflation)

modifier nonReentrant() {
    require(_status != _ENTERED, "ReentrancyGuard: reentrant call");
    _status = _ENTERED;
    _;
    _status = _NOT_ENTERED;
}

// contracts/folio/FolioProxy.sol
function _authorizeUpgrade(address newImplementation) internal override {
    require(
        IFolioVersionRegistry(versionRegistry).isVersionValid(newImplementation),
        "Invalid version"
    );
}

NO_REBALANCE
    ↓ startRebalance()
RESTRICTED_PERIOD (only AUCTION_LAUNCHER can act)
    ↓ time passes OR AUCTION_LAUNCHER inactive
UNRESTRICTED_PERIOD (anyone can act)
    ↓ TTL expires OR endRebalance() called
NO_REBALANCE

UNINITIALIZED (startTime == 0, endTime == 0)
    ↓ openAuction() / openAuctionUnrestricted()
PENDING (block.timestamp < startTime)
    ↓ time passes
OPEN (startTime ≤ block.timestamp ≤ endTime)
    ↓ time passes OR closeAuction()
CLOSED (block.timestamp > endTime)
    ↓ openAuction() [if rebalance still active]
OPEN ...

function deprecateFolio() external onlyRole(DEFAULT_ADMIN_ROLE) {
    isDeprecated = true;
    emit FolioDeprecated();
}

interface IFolioLens {
    function getBasketValues(address folio) external view returns (...);
    function getRebalanceStatus(address folio) external view returns (...);
    function getAuctionDetails(address folio, uint256 auctionId) external view returns (...);
}