> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/reserve-protocol/reserve-index-dtf/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="Token Units" icon="coins">
    `{tok}`, `{share}`, `{reward}` represent token balances in their native quanta
  </Card>

  <Card title="Time Units" icon="clock">
    `{s}` represents time in seconds
  </Card>
</CardGroup>

## Precision Multipliers

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

## Common Unit Patterns

### Percentages and Ratios

<AccordionGroup>
  <Accordion title="D18{1} - Percentage Values">
    Percentage values with 18 decimals of precision.

    **Example:** Fee portions, allocation percentages

    ```solidity theme={null}
    // {share} = {share} * D18{1} / D18
    uint256 shares = (pendingFeeShares * feeRecipients[i].portion) / D18;
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="D27{tok/BU} - Basket Unit Weights">
    Weight of a token in the basket unit definition with 27 decimals of precision.

    **Range:** `[0, 1e54]`
  </Accordion>
</AccordionGroup>

### Price Units

<Card title="D27{UoA/tok} - Token Prices" icon="dollar-sign">
  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.
</Card>

### Exchange Rates

<Card title="D27{tok1/tok2} - Token Exchange Rates" icon="arrow-right-arrow-left">
  Ratio of two token balances with 27 decimals of precision.

  **Used in:** Auction pricing, token pair exchanges
</Card>

## Rebalance-Specific Units

### Rebalance Limits

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
struct PriceRange {
  uint256 low;  // D27{UoA/tok} (0, 1e45]
  uint256 high; // D27{UoA/tok} (0, 1e45]
}
```

## Unit Conversion Examples

<CodeGroup>
  ```solidity Calculating Shares from Portion theme={null}
  // {share} = {share} * D18{1} / D18
  uint256 shares = (pendingFeeShares * feeRecipients[i].portion) / D18;
  ```

  ```solidity Token Amount Calculations theme={null}
  // {tok} = {share} * D27{tok/share} / D27
  uint256 tokenAmount = (shareAmount * tokenToShareRatio) / D27;
  ```

  ```solidity Price Calculations theme={null}
  // {UoA} = {tok} * D27{UoA/tok} / D27
  uint256 valueInUoA = (tokenAmount * tokenPrice) / D27;
  ```
</CodeGroup>

## Best Practices

<Warning>
  **Precision Loss:** Always perform multiplication before division to minimize precision loss in fixed-point arithmetic.
</Warning>

<Tip>
  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
</Tip>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Valid Ranges" icon="ruler" href="/resources/valid-ranges">
    Learn about valid ranges for different units
  </Card>

  <Card title="Rebalancing" icon="balance-scale" href="/essentials/rebalancing">
    Understand how units are used in rebalancing
  </Card>
</CardGroup>