FolioLens Contract

Read-only interface for analyzing Folio state, auctions, and balances off-chain

Overview

The FolioLens contract provides convenient read-only functions for analyzing Folio state. It’s designed for off-chain use by frontends, analytics tools, and indexers. These functions are gas-intensive and should not be called on-chain.

Key Features

• Spot Weight Calculation: Compute current token weights from balances
• Batch Bid Queries: Get all auction bids at once
• Surplus/Deficit Analysis: Calculate which tokens need buying or selling
• Off-Chain Optimized: Not intended for on-chain calls

FolioLens functions are designed for off-chain analysis only. Do not call these functions from other smart contracts as they may consume excessive gas.

Analysis Functions

Get Spot Weights

Calculate token weights based on current Folio balances.

folio · Folio

Folio contract to analyze

FolioLens.sol

function getSpotWeights(
    Folio folio
) external view returns (
    address[] memory tokens,
    uint256[] memory weights
)

Returns:

• tokens: Array of token addresses in the basket
• weights: Token weights in D27 format (tokens per share)

Weights are calculated as: (D27 * tokenBalance) / totalSupply. This gives the actual composition by current holdings, which may differ from target weights during rebalancing.

Get All Bids

Retrieve all possible bids for an auction in a single call.

folio · Folio

Folio contract with active auction

auctionId · uint256

ID of the auction to query

FolioLens.sol

function getAllBids(
    Folio folio,
    uint256 auctionId
) external view returns (SingleBid[] memory bids)

Returns:

• Array of SingleBid structs for all valid token pairs

This function attempts to call getBid() for all N² token pairs. Invalid pairs (those that would revert) are filtered out. Only returns bids with non-zero amounts.

Surpluses and Deficits

Calculate which tokens are over/under the target limits.

folio · Folio

Folio contract to analyze

sellLimit · uint256

Upper BU limit for selling (D18 format)

buyLimit · uint256

Lower BU limit for buying (D18 format)

FolioLens.sol

function surplusesAndDeficits(
    Folio folio,
    uint256 sellLimit,
    uint256 buyLimit
) external view returns (
    address[] memory tokens,
    uint256[] memory surpluses,
    uint256[] memory deficits
)

Returns:

• tokens: Array of token addresses
• surpluses: Amount above sell limit for each token (0 if not surplus)
• deficits: Amount below buy limit for each token (0 if not deficit)

Requires sellLimit >= buyLimit. A token cannot have both a surplus and deficit - if one is non-zero, the other is always zero.

Data Structures

SingleBid

Represents a single auction bid for a token pair.

sellToken · address

Token being sold by the Folio

buyToken · address

Token being bought by the Folio

sellAmount · uint256

Amount of sell token available

bidAmount · uint256

Amount of buy token required

price · uint256

Price in D27 format (buyTok/sellTok)

struct SingleBid {
    address sellToken;
    address buyToken;
    uint256 sellAmount;  // {sellTok}
    uint256 bidAmount;   // {buyTok}
    uint256 price;       // D27{buyTok/sellTok}
}

Usage Examples

Analyze Current Composition

// Get current token weights
(address[] memory tokens, uint256[] memory weights) = 
    lens.getSpotWeights(folio);

for (uint256 i = 0; i < tokens.length; i++) {
    // weights[i] is in D27 format
    // Divide by 1e27 to get tokens per share
    uint256 tokensPerShare = weights[i] / 1e27;
}

Find Best Auction Bids

// Get all bids for current auction
FolioLens.SingleBid[] memory bids = lens.getAllBids(folio, auctionId);

for (uint256 i = 0; i < bids.length; i++) {
    FolioLens.SingleBid memory bid = bids[i];
    
    // Calculate price impact
    uint256 priceImpact = calculatePriceImpact(
        bid.sellToken,
        bid.buyToken,
        bid.price
    );
    
    // Execute profitable bids
    if (isProfitable(priceImpact)) {
        folio.bid(
            auctionId,
            IERC20(bid.sellToken),
            IERC20(bid.buyToken),
            bid.sellAmount,
            bid.bidAmount,
            false,
            ""
        );
    }
}

Calculate Rebalancing Needs

// Get current rebalance limits
(, , , IFolio.RebalanceLimits memory limits, , ) = folio.getRebalance();

// Calculate surpluses and deficits
(
    address[] memory tokens,
    uint256[] memory surpluses,
    uint256[] memory deficits
) = lens.surplusesAndDeficits(folio, limits.high, limits.low);

for (uint256 i = 0; i < tokens.length; i++) {
    if (surpluses[i] > 0) {
        // Token needs to be sold
        console.log("Sell", surpluses[i], "of", tokens[i]);
    } else if (deficits[i] > 0) {
        // Token needs to be bought
        console.log("Buy", deficits[i], "of", tokens[i]);
    }
}

Constants

D18 · uint256 · default: "1e18"

18-decimal fixed point scaling factor

D27 · uint256 · default: "1e27"

27-decimal fixed point scaling factor (used for weights and prices)

Integration Notes

Frontend Integration: Use these functions via eth_call (read-only RPC calls). Never send transactions to FolioLens.

Indexing: These functions are useful for building subgraphs or analytics dashboards. Call them periodically to track Folio state changes.

The getAllBids() function may be expensive for Folios with many tokens (N² complexity). Consider using pagination or filtering for large baskets.

Error Handling

Functions use try/catch to gracefully handle invalid states:

try folio.getBid(...) returns (...) {
    // Process valid bid
} catch {
    // Skip invalid pair
}

This ensures functions don’t revert on temporary invalid states (e.g., ended auctions, removed tokens).