Unit System

Understanding the unit system used throughout Reserve Folio

Overview

Reserve Folio uses a comprehensive unit system documented with curly brackets ({}) throughout the codebase. The system includes precision multipliers (D18 and D27) to handle ratios, percentages, and prices with high accuracy.

Base Units

Token Units

{tok}, {share}, {reward} represent token balances in their native quanta

Time Units

{s} represents time in seconds

Precision Multipliers

Multiplier	Value	Description
D18	1e18	Standard 18-decimal precision
D27	1e27	Extended 27-decimal precision

Common Unit Patterns

Percentages and Ratios

D18{1} - Percentage Values

Percentage values with 18 decimals of precision.

Example: Fee portions, allocation percentages

// {share} = {share} * D18{1} / D18
uint256 shares = (pendingFeeShares * feeRecipients[i].portion) / D18;

D27{tok/share} - Token-to-Share Ratios

Ratio of token quanta to Folio share quanta with 27 decimals of precision.

Used in: Rebalance limits, basket unit calculations

D27{tok/BU} - Basket Unit Weights

Weight of a token in the basket unit definition with 27 decimals of precision.

Range: [0, 1e54]

Price Units

D27{UoA/tok} - Token Prices

Price in nanoUSD (Unit of Account) per token quanta, with 27 decimals of precision.

Valid Range: (0, 1e45]

The Unit of Account can be anything as long as it’s consistent; nanoUSD is most common.

Exchange Rates

D27{tok1/tok2} - Token Exchange Rates

Ratio of two token balances with 27 decimals of precision.

Used in: Auction pricing, token pair exchanges

Rebalance-Specific Units

Rebalance Limits

struct RebalanceLimits {
  uint256 low;  // D18{BU/share} (0, 1e27]
  uint256 spot; // D18{BU/share} (0, 1e27]
  uint256 high; // D18{BU/share} (0, 1e27]
}

• low: Basket units per share to buy assets up to
• spot: Point estimate for unrestricted callers
• high: Basket units per share to sell assets down to

Weight Ranges

struct WeightRange {
  uint256 low;  // D27{tok/BU} [0, 1e54]
  uint256 spot; // D27{tok/BU} [0, 1e54]
  uint256 high; // D27{tok/BU} [0, 1e54]
}

Price Ranges

struct PriceRange {
  uint256 low;  // D27{UoA/tok} (0, 1e45]
  uint256 high; // D27{UoA/tok} (0, 1e45]
}

Unit Conversion Examples

Calculating Shares from Portion

// {share} = {share} * D18{1} / D18
uint256 shares = (pendingFeeShares * feeRecipients[i].portion) / D18;

Best Practices

Precision Loss: Always perform multiplication before division to minimize precision loss in fixed-point arithmetic.

When working with units:

1. Always document units in comments using the standard notation
2. Use D27 for ratios and prices to maintain precision
3. Use D18 for percentages and simple ratios
4. Verify unit consistency in calculations

Related Documentation

Valid Ranges

Learn about valid ranges for different units

Rebalancing

Understand how units are used in rebalancing