# HyperFunFactory

## VaultFactory (HyperFunFactory.sol)

`HyperFunFactory.sol` is the UUPS upgradeable factory for deploying HyperFun Vaults and managing global settings.

### Inheritance

```solidity
contract HyperFunFactory is
    Initializable,
    UUPSUpgradeable,
    OwnableUpgradeable
```

### Constants

```solidity
uint256 public constant MAX_PERFORMANCE_FEE = 3000;  // 30%
uint256 public constant MAX_EXIT_FEE = 5000;         // 50%
uint256 public constant L1_INIT_FEE = 1000000;       // 1 USDC (6 decimals)
```

### State Variables

#### Implementation Contracts

```solidity
address public coreImplementation;      // HyperFunToken implementation
address public tradingImplementation;   // HyperFunTrading implementation
```

#### Platform Settings

```solidity
address public treasury;        // Protocol treasury
address public usdc;            // USDC token address
uint256 public creationFee;     // Fee to create vault (0 = free)
bool public paused;             // Pause vault creation
```

#### Default BC Parameters

```solidity
uint256 public defaultBcVirtualBase;     // Default 2,000,000 * 1e18
uint256 public defaultBcVirtualTokens;   // Default 2,000,000 * 1e18
uint256 public defaultInitialAssets;     // Default 100,000 * 1e18
```

#### Builder Fee Settings

```solidity
address public defaultBuilder;           // Default builder for new vaults
uint64 public defaultBuilderFeeRate;     // Fee rate in decibps (50 = 0.05%)
```

#### Vault Registry

```solidity
address[] public allVaults;
mapping(address => address[]) public vaultsByLeader;
mapping(address => bool) public isVault;
mapping(address => bool) public isVerified;
mapping(address => VaultInfo) public vaultInfo;

struct VaultInfo {
    address core;
    address trading;
    address leader;
    string name;
    string symbol;
    uint256 performanceFeeBps;
    uint256 createdAt;
    bool verified;
}
```

***

### Global Vault Settings

All vaults read these settings via `getGlobalSettings()` and `getGlobalSettingsExt()`.

#### Core Settings

```solidity
uint256 public globalTradingFeeBps;      // Default 100 (1%)
uint256 public globalMaxPremiumBps;      // Default 10000 (100%)
uint256 public globalMaxDiscountBps;     // Default 5000 (50%)
uint256 public globalMinDepositUsdc;     // Default 5 * 1e6 (5 USDC)
```

#### Rebalance Settings

```solidity
uint256 public globalRebalanceLowBps;    // Default 4800 (48%)
uint256 public globalRebalanceHighBps;   // Default 5200 (52%)
uint256 public globalReserveRatioBps;    // Default 5000 (50%)
uint256 public globalMinReserveRatioBps; // Default 3000 (30%)
```

#### Buy Limit

```solidity
uint256 public globalMaxBuyBps;          // Default 100 (1% of vault per tx)
```

#### NAV Virtual (Legacy)

```solidity
uint256 public globalNavVirtualAssets;   // Default 500,000 * 1e18
uint256 public globalNavVirtualShares;   // Default 500,000 * 1e18
```

#### Exit Fee

```solidity
bool public globalExitFeeEnabled;        // Default true

struct ExitFeeTier {
    uint256 daysHeld;    // Minimum days held
    uint256 feeBps;      // Fee in bps
}
ExitFeeTier[] public globalExitFeeTiers;

// Default tiers:
// <7 days:   15%
// 7-30 days:  8%
// 30-90 days: 3%
// >90 days:   0%
```

#### BC Virtual Settings

```solidity
uint256 public globalBcVirtualMinimumBps;  // Default 500 (5% floor)
uint256 public globalMaxBcRatioBps;        // Default 0 (disabled), or 18000-50000
```

#### Dynamic NAV Virtual (V35-V36)

```solidity
uint256 public globalNavVirtualMode;              // 0=fixed, 1=dynamic, 2=auto-dynamic
uint256 public globalNavVirtualMultiplierBps;     // Min multiplier (mode 2)
uint256 public globalNavVirtualMaxMultiplierBps;  // Max multiplier (mode 2)
uint256 public globalNavVirtualTargetAssets;      // Target for max multiplier
uint256 public globalNavVirtualMinimum;           // Minimum NAV Virtual value
```

#### Graduation Tiers (V37-V38)

```solidity
struct GraduationTier {
    uint256 threshold;        // Asset threshold (18 decimals)
    uint256 bcVirtual;        // BC Virtual pool size
    uint256 navMinMulBps;     // NAV min multiplier (2000 = 0.2x)
    uint256 navMaxMulBps;     // NAV max multiplier (5000 = 0.5x)
    uint256 squaredRatioBps;  // Squared effect (10000=100%, 0=linear)
}
GraduationTier[] public graduationTiers;
bool public graduationTieredMode;
```

***

### Vault Creation

#### Simple Creation

```solidity
function createVault(
    string calldata _name,
    string calldata _symbol,
    uint256 _performanceFeeBps
) external returns (address core, address trading);
```

Creates vault with default BC parameters.

#### Advanced Creation (Owner Only)

```solidity
function createVaultAdvanced(
    string calldata _name,
    string calldata _symbol,
    uint256 _performanceFeeBps,
    uint256 _bcVirtualBase,
    uint256 _bcVirtualTokens,
    uint256 _initialAssets
) external onlyOwner returns (address core, address trading);
```

Creates vault with custom BC parameters.

#### Creation Flow

1. Validate parameters (name, symbol, fee <= 30%)
2. Collect creation fee (if set)
3. Collect L1 init fee (1 USDC) from leader
4. Deploy Trading proxy (ERC1967)
5. Deploy Token proxy (ERC1967)
6. Initialize Trading with Token reference
7. Initialize Token with:
   * Leader = msg.sender
   * Admin = Factory (temporary)
   * Trading module
   * BC parameters
8. Approve builder fee (if configured)
9. Set admin to factory owner
10. Initialize L1 account (deposit 1 USDC)
11. Register vault in registry
12. Emit `VaultCreated` event

***

### View Functions

#### Vault Registry

```solidity
function totalVaults() external view returns (uint256);

function getVaults(uint256 offset, uint256 limit) external view returns (address[] memory);

function getAllVaults() external view returns (address[] memory);

function getVaultsByLeader(address leader) external view returns (address[] memory);

function getVaultCountByLeader(address leader) external view returns (uint256);

function getVaultInfo(address vault) external view returns (VaultInfo memory);

function getVerifiedVaults() external view returns (address[] memory);
```

#### Global Settings

```solidity
function getGlobalSettings() external view returns (
    uint256 tradingFeeBps,
    uint256 maxPremiumBps,
    uint256 maxDiscountBps,
    uint256 minDepositUsdc,
    uint256 rebalanceLowBps,
    uint256 rebalanceHighBps,
    uint256 reserveRatioBps,
    uint256 minReserveRatioBps
);

function getGlobalSettingsExt() external view returns (
    uint256 maxBuyBps,
    uint256 navVirtualAssets,
    uint256 navVirtualShares,
    bool exitFeeEnabled
);

function getGlobalExitFeeTiers() external view returns (ExitFeeTier[] memory);

function getGlobalMaxBcRatio() external view returns (uint256);
```

#### Default Parameters

```solidity
function getDefaultBcParams() external view returns (
    uint256 bcVirtualBase,
    uint256 bcVirtualTokens,
    uint256 initialAssets
);
```

#### NAV Virtual Parameters

```solidity
function getGlobalNavVirtualDynamic() external view returns (
    uint256 mode,
    uint256 multiplierBps,
    uint256 minimum
);

function getGlobalNavVirtualParams() external view returns (
    uint256 mode,
    uint256 minMultiplierBps,
    uint256 maxMultiplierBps,
    uint256 targetAssets,
    uint256 minimum
);
```

#### Graduation Tiers

```solidity
function getGraduationTiers() external view returns (GraduationTier[] memory);

function getGraduationTierCount() external view returns (uint256);

function getGraduationTier(uint256 index) external view returns (
    uint256 threshold,
    uint256 bcVirtual,
    uint256 navMinMulBps,
    uint256 navMaxMulBps,
    uint256 squaredRatioBps
);

function isGraduationTieredMode() external view returns (bool);
```

***

### Admin Functions (Owner Only)

#### Implementation Management

```solidity
function setImplementations(address _core, address _trading) external;
```

Updates implementations for future vaults. Existing vaults unaffected until upgraded.

#### Platform Settings

```solidity
function setCreationFee(uint256 _fee) external;
function setTreasury(address _treasury) external;
function setPaused(bool _paused) external;
```

#### Default Parameters

```solidity
function setDefaults(
    uint256 _bcVirtualBase,
    uint256 _bcVirtualTokens,
    uint256 _initialAssets
) external;
```

#### Builder Fee

```solidity
function setDefaultBuilder(address _builder, uint64 _feeRate) external;

function approveBuilderFeeForVault(address vault, address builder, uint64 feeRate) external;

function batchApproveBuilderFee(address[] calldata vaults, address builder, uint64 feeRate) external;
```

#### Vault Verification

```solidity
function setVaultVerified(address vault, bool verified) external;

function batchSetVaultVerified(address[] calldata vaults, bool verified) external;
```

#### Global Settings

```solidity
function setGlobalTradingFee(uint256 _feeBps) external;  // Max 5%

function setGlobalPriceLimits(uint256 _maxPremiumBps, uint256 _maxDiscountBps) external;

function setGlobalMinDeposit(uint256 _minUsdc) external;

function setGlobalRebalanceThresholds(uint256 _lowBps, uint256 _highBps) external;

function setGlobalReserveRatio(uint256 _ratioBps, uint256 _minRatioBps) external;

function setGlobalMaxBuyBps(uint256 _maxBuyBps) external;  // 0.1%-10%

function setGlobalBcVirtualMinimum(uint256 _minimumBps) external;  // 1%-50%

function setGlobalMaxBcRatio(uint256 _ratioBps) external;  // 0 or 1x-5x

function setGlobalNavVirtual(uint256 _assets, uint256 _shares) external;

function setGlobalExitFeeEnabled(bool _enabled) external;

function setGlobalExitFeeTiers(
    uint256[] calldata _daysHeld,
    uint256[] calldata _feeBps
) external;
```

#### Dynamic NAV Virtual

```solidity
// Mode 0 or 1
function setGlobalNavVirtualDynamic(
    uint256 _mode,
    uint256 _multiplierBps,
    uint256 _minimum
) external;

// Mode 2 (auto-dynamic)
function setGlobalNavVirtualAutoDynamic(
    uint256 _minMultiplierBps,
    uint256 _maxMultiplierBps,
    uint256 _targetAssets,
    uint256 _minimum
) external;
```

#### Graduation Tiers

```solidity
function setGraduationTiers(
    uint256[] calldata _thresholds,
    uint256[] calldata _bcVirtuals,
    uint256[] calldata _navMinMuls,
    uint256[] calldata _navMaxMuls,
    uint256[] calldata _squaredRatios
) external;

function setGraduationMode(bool _tiered) external;
```

#### Emergency Functions

```solidity
function emergencyWithdrawL1SpotToEVM(address vault, uint256 amount6) external;

function emergencyWithdrawEVM(address vault, uint256 amount6) external;

function rescueTokens(address token, uint256 amount) external;
```

***

### Events

```solidity
event VaultCreated(
    address indexed leader,
    address indexed core,
    address indexed trading,
    string name,
    string symbol,
    uint256 performanceFeeBps
);

event ImplementationUpdated(address newCore, address newTrading);

event VaultVerified(address indexed vault, bool verified);

event CreationFeeUpdated(uint256 oldFee, uint256 newFee);

event DefaultsUpdated(uint256 bcVirtualBase, uint256 bcVirtualTokens, uint256 initialAssets);
```

***

### Upgrade Authority

```solidity
function _authorizeUpgrade(address) internal override onlyOwner {}
```

Only factory owner can upgrade the factory itself.

***

### Default Values Summary

| Setting                     | Default | Description               |
| --------------------------- | ------- | ------------------------- |
| `globalTradingFeeBps`       | 100     | 1% trading fee            |
| `globalMaxPremiumBps`       | 10000   | Max 100% premium over NAV |
| `globalMaxDiscountBps`      | 5000    | Max 50% discount from NAV |
| `globalMinDepositUsdc`      | 5 USDC  | Minimum buy amount        |
| `globalRebalanceLowBps`     | 4800    | Rebalance when EVM < 48%  |
| `globalRebalanceHighBps`    | 5200    | Rebalance when EVM > 52%  |
| `globalReserveRatioBps`     | 5000    | Target 50% EVM reserve    |
| `globalMinReserveRatioBps`  | 3000    | Warning at 30%            |
| `globalMaxBuyBps`           | 100     | Max 1% of vault per buy   |
| `globalBcVirtualMinimumBps` | 500     | 5% BC Virtual floor       |
| `globalMaxBcRatioBps`       | 0       | Disabled (0) or ratio cap |
| `defaultBcVirtualBase`      | 2M      | Virtual USDC pool         |
| `defaultBcVirtualTokens`    | 2M      | Virtual token pool        |
| `defaultInitialAssets`      | 100K    | BC scaling baseline       |
| `L1_INIT_FEE`               | 1 USDC  | L1 account init fee       |

***

### Exit Fee Tiers (Default)

| Days Held  | Fee |
| ---------- | --- |
| < 7 days   | 15% |
| 7-30 days  | 8%  |
| 30-90 days | 3%  |
| > 90 days  | 0%  |

***

### Related Contracts

| Contract          | Role                                     |
| ----------------- | ---------------------------------------- |
| `HyperFunToken`   | Core vault, reads global settings        |
| `HyperFunTrading` | Trading module, reads rebalance settings |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hyper-fun.gitbook.io/hypers.fun/smart-contracts/hyperfunfactory.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.