> ## 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.

# Quick Start Guide

> Get started with Reserve Folio by deploying your first portfolio and understanding the core operations.

## Prerequisites

Before you begin, ensure you have the following:

<CardGroup cols={2}>
  <Card title="Development Tools" icon="toolbox">
    * Foundry (for Solidity development)
    * Node.js v20+
    * Yarn package manager
  </Card>

  <Card title="Knowledge Requirements" icon="book">
    * Understanding of ERC20 tokens
    * Basic Solidity knowledge
    * Familiarity with Dutch auctions
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/reserve-protocol/reserve-index-dtf
    cd reserve-index-dtf
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    yarn install
    ```
  </Step>

  <Step title="Build the Project">
    ```bash theme={null}
    yarn compile
    ```
  </Step>

  <Step title="Run Tests">
    Verify everything is working correctly:

    ```bash theme={null}
    # Run basic tests
    yarn test

    # Run extreme edge case tests
    yarn test:extreme

    # Run all tests
    yarn test:all

    # Generate coverage report
    forge coverage
    ```
  </Step>
</Steps>

## Deploying Your First Folio

### Step 1: Configure Folio Parameters

Define your Folio's initial configuration:

```solidity theme={null}
IFolio.FolioBasicDetails memory basicDetails = IFolio.FolioBasicDetails({
    name: "My Portfolio",
    symbol: "MYPORT",
    assets: [address(tokenA), address(tokenB), address(tokenC)],
    amounts: [1000e18, 2000e6, 500e18], // Initial amounts
    initialShares: 1000e18 // Initial supply
});
```

<Warning>
  Ensure token decimals are handled correctly. The amounts array should reflect actual token quantum (e.g., USDC with 6 decimals uses 1e6 for 1 USDC).
</Warning>

### Step 2: Set Fee Configuration

```solidity theme={null}
IFolio.FeeRecipient[] memory recipients = new IFolio.FeeRecipient[](1);
recipients[0] = IFolio.FeeRecipient({
    recipient: feeRecipientAddress,
    portion: 1e18 // 100% of non-DAO fees (D18 format)
});

IFolio.FolioAdditionalDetails memory additionalDetails = IFolio.FolioAdditionalDetails({
    maxAuctionLength: 1 hours,
    feeRecipients: recipients,
    tvlFee: 100e18 / 365 days, // 100 bps annually (D18{1/s})
    mintFee: 50e15, // 50 bps (D18{1})
    folioFeeForSelf: 0, // No self-burning
    mandate: "A diversified crypto portfolio"
});
```

<Info>
  TVL fees are specified as per-second rates. The example shows 100 bps annually: `100e18 / 365 days`.
</Info>

### Step 3: Configure Rebalance Control

```solidity theme={null}
IFolio.FolioFlags memory flags = IFolio.FolioFlags({
    trustedFillerEnabled: false,
    rebalanceControl: IFolio.RebalanceControl({
        weightControl: true,
        priceControl: IFolio.PriceControl.PARTIAL
    }),
    bidsEnabled: true
});
```

<Note>
  **Price Control Levels:**

  * `NONE`: AUCTION\_LAUNCHER cannot adjust prices
  * `PARTIAL`: Can narrow price ranges within bounds
  * `ATOMIC_SWAP`: Can execute instant swaps at fixed prices (highest trust required)
</Note>

### Step 4: Deploy the Folio

```solidity theme={null}
address[] memory basketManagers = new address[](1);
basketManagers[0] = rebalanceManagerAddress;

address[] memory auctionLaunchers = new address[](1);
auctionLaunchers[0] = auctionLauncherAddress;

address[] memory brandManagers = new address[](0);

(Folio folio, address proxyAdmin) = folioDeployer.deployFolio(
    basicDetails,
    additionalDetails,
    flags,
    adminAddress, // DEFAULT_ADMIN_ROLE
    basketManagers,
    auctionLaunchers,
    brandManagers,
    keccak256("deployment_salt")
);
```

### Step 5: Deploy via Command Line

For production deployment:

```bash theme={null}
yarn deploy --rpc-url <RPC_URL> --verify --verifier etherscan
```

<Warning>
  Set the `ETHERSCAN_API_KEY` environment variable to your API key for the target network (Basescan, Etherscan, Arbiscan, etc.).
</Warning>

## Core Operations

### Minting Folio Shares

Users can mint Folio shares by depositing the required basket of assets:

```solidity theme={null}
// 1. Approve all basket tokens
for (uint256 i = 0; i < basket.length; i++) {
    IERC20(basket[i]).approve(address(folio), type(uint256).max);
}

// 2. Calculate required amounts for desired shares
uint256 desiredShares = 100e18;
uint256[] memory requiredAmounts = folio.getRequiredAmounts(desiredShares);

// 3. Mint with slippage protection
uint256 minSharesOut = desiredShares * 99 / 100; // 1% slippage tolerance
folio.mint(desiredShares, minSharesOut);
```

<Note>
  Mint fees are automatically deducted. Specify `minSharesOut` to protect against fee changes between transaction submission and execution.
</Note>

### Redeeming Folio Shares

Redeem Folio shares to receive the underlying assets pro-rata:

```solidity theme={null}
// Redeem 50 shares
uint256 sharesToRedeem = 50e18;
folio.redeem(sharesToRedeem);

// Assets are transferred directly to msg.sender
```

### Starting a Rebalance

Only the `REBALANCE_MANAGER` can initiate rebalances:

```solidity theme={null}
// Define rebalance parameters for each token
IFolio.TokenRebalanceParams[] memory tokens = new IFolio.TokenRebalanceParams[](3);

tokens[0] = IFolio.TokenRebalanceParams({
    token: address(tokenA),
    weight: IFolio.WeightRange({
        low: 30e25,  // D27{tok/BU} - buy up to this weight
        spot: 33e25, // Point estimate
        high: 36e25  // Sell down to this weight
    }),
    price: IFolio.PriceRange({
        low: 0.95e27,  // D27{UoA/tok} - most pessimistic
        high: 1.05e27  // D27{UoA/tok} - most optimistic
    }),
    maxAuctionSize: 10000e18, // Maximum tokens per auction
    inRebalance: true
});

// ... configure other tokens ...

IFolio.RebalanceLimits memory limits = IFolio.RebalanceLimits({
    low: 0.95e18,   // D18{BU/share} - buy up to
    spot: 1e18,     // Point estimate
    high: 1.05e18   // D18{BU/share} - sell down to
});

folio.startRebalance(
    tokens,
    limits,
    2 days // TTL: rebalance available for 2 days
);
```

<Info>
  **Basket Units (BU):**
  A Basket Unit is typically defined 1:1 with shares (1e18 BU = 1e18 shares). The limits define the target range for rebalancing.
</Info>

### Opening an Auction

The `AUCTION_LAUNCHER` can open auctions during the restricted period:

```solidity theme={null}
// Select tokens to include in auction
address[] memory auctionTokens = new address[](2);
auctionTokens[0] = address(tokenA); // Surplus token (selling)
auctionTokens[1] = address(tokenB); // Deficit token (buying)

// Optionally narrow price ranges (if priceControl != NONE)
IFolio.PriceRange[] memory prices = new IFolio.PriceRange[](2);
prices[0] = IFolio.PriceRange({
    low: 0.98e27,
    high: 1.02e27 // Narrowed from original 0.95-1.05
});
prices[1] = IFolio.PriceRange({
    low: 1.98e27,
    high: 2.02e27
});

// Open the auction
folio.openAuction(
    auctionTokens,
    limits,      // Can narrow from original
    new IFolio.WeightRange[](0), // Empty if not using weightControl
    prices
);
```

### Bidding in an Auction

Anyone can bid in an active auction:

```solidity theme={null}
// 1. Get current bid information
(uint256 sellAmount, uint256 bidAmount, uint256 price) = folio.getBid(
    auctionId,
    IERC20(tokenA), // Sell token
    IERC20(tokenB), // Buy token
    block.timestamp,
    type(uint256).max // No max limit
);

// 2. Approve buy token
IERC20(tokenB).approve(address(folio), bidAmount);

// 3. Submit bid
folio.bid(
    auctionId,
    tokenA,
    tokenB,
    sellAmount,
    bidAmount
);

// 4. Tokens are swapped atomically
```

<Note>
  Auctions use an exponential decay curve. Prices improve over time, starting at the most optimistic price and moving toward the most pessimistic price.
</Note>

### Checking Auction Status

```solidity theme={null}
// Get current auction price at any timestamp
(uint256 sellAmount, uint256 buyAmount, uint256 currentPrice) = folio.getBid(
    auctionId,
    sellToken,
    buyToken,
    block.timestamp,
    maxSellAmount
);

// Check if rebalance is active
bool isRebalancing = folio.stateChangeActive();
```

## Understanding Units

Folio uses a precise unit notation system:

| Unit                           | Description            | Example           |
| ------------------------------ | ---------------------- | ----------------- |
| `{tok}`, `{share}`, `{reward}` | Token balances         | `1000e18`         |
| `D18{1}`                       | 18-decimal percentage  | `5e16` = 5%       |
| `D27{tok/share}`               | Token-to-share ratio   | `1e27` = 1:1      |
| `D27{UoA/tok}`                 | Price in nanoUSD       | `2e27` = \$2      |
| `D18{BU/share}`                | Basket Units per share | `1e18` = 1 BU     |
| `D18{1/s}`                     | Per-second rate        | `100e18/365 days` |

<Warning>
  **Important:** All percentages and ratios use fixed-point arithmetic. A value of `1e18` represents 100% or 1:1 ratio, NOT 1e18%.
</Warning>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Read-Only Reentrancy Protection">
    Always check `stateChangeActive()` returns false before relying on view function data:

    ```solidity theme={null}
    (bool isRebalancing, bool isAuction) = folio.stateChangeActive();
    require(!isRebalancing && !isAuction, "State change active");

    // Now safe to use view functions
    uint256 value = folio.someViewFunction();
    ```
  </Accordion>

  <Accordion title="Token Removal Considerations">
    If removing a token via `removeFromBasket()`, users have limited time to redeem before the token becomes inaccessible. Only remove tokens that are malicious or compromised.
  </Accordion>

  <Accordion title="Price Range Safety">
    Set price ranges conservatively to account for:

    * Timelock delays
    * Block-to-block price volatility
    * MEV searcher exploitation

    If prices move outside ranges, `AUCTION_LAUNCHER` must end the rebalance to prevent value leakage.
  </Accordion>

  <Accordion title="Auction Launcher Trust">
    With `PARTIAL` or `ATOMIC_SWAP` price control, the `AUCTION_LAUNCHER` can cause value leakage. Choose trusted operators and consider using `NONE` for maximum security.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Folio__InvalidAssetAmount Error">
    This occurs when depositing incorrect amounts during minting. Ensure:

    * All basket tokens are approved
    * Amounts match current basket ratios
    * Account for token decimals correctly
  </Accordion>

  <Accordion title="Folio__AuctionCannotBeOpenedWithoutRestriction">
    The restricted period has not ended. Either:

    * Wait for the restricted period to expire
    * Have the `AUCTION_LAUNCHER` open the auction
    * Have the `REBALANCE_MANAGER` end the rebalance
  </Accordion>

  <Accordion title="Folio__InsufficientSharesOut Error">
    Mint fee changed between transaction submission and execution. Increase your slippage tolerance in the `minSharesOut` parameter.
  </Accordion>

  <Accordion title="Interactive Commands Not Working">
    Never use interactive git commands (like `git rebase -i` or `git add -i`) as they require user input. Use non-interactive alternatives instead.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="System Architecture" icon="sitemap" href="/architecture">
    Learn about the rebalancing mechanism, auction curves, and lot sizing
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore all available functions and their parameters
  </Card>
</CardGroup>

## Additional Resources

<CardGroup cols={3}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/reserve-protocol/reserve-index-dtf">
    View source code and examples
  </Card>

  <Card title="Release Notes" icon="tag" href="https://github.com/reserve-protocol/reserve-index-dtf/releases">
    Track version history and updates
  </Card>

  <Card title="Trusted Fillers" icon="handshake" href="https://github.com/reserve-protocol/trusted-fillers">
    Learn about CoW Swap integration
  </Card>
</CardGroup>