Liquidity Framework

The Unified Liquidity Pool serves as the foundation of Herafi's liquidity architecture, employing innovative mechanisms designed to maintain balanced liquidity across all supported tokens while using oracle-based pricing. This document outlines the key aspects of Herafi's liquidity framework.

Unified Pool Concept

Unlike traditional Automated Market Makers (AMMs) that utilize separate pools for each trading pair, Herafi consolidates all supported tokens into a single unified pool. This approach offers several advantages:

Traditional AMMs vs. Unified Liquidity Pool

Key Benefits of the Unified Pool

1. Improved Capital Efficiency: Liquidity is shared across all token pairs rather than being fragmented across multiple pools. This means the same liquidity can serve multiple trading pairs simultaneously.

2. Reduced Slippage: Enables single-hop trades between any supported tokens, eliminating the need for multi-hop routes that increase slippage and fees.

3. Simplified Liquidity Provision: Users can deposit any supported token and receive LP tokens representing ownership in the entire pool, rather than needing to provide balanced pairs.

4. Adaptive Liquidity: The pool automatically adjusts incentives to address imbalances, encouraging the provision of tokens that are most needed.

Oracle-Based Pricing

Unlike traditional AMMs that use mathematical formulas (like constant product x*y=k) to determine exchange rates, the Unified Liquidity Pool relies on oracle price feeds.

Price Determination Mechanism

1. External Price Oracles: Token prices are derived from trusted oracle providers rather than being determined solely by pool ratios.

2. Swap Calculation Process:

   • When a user swaps Token A for Token B:
     1. The protocol obtains oracle prices for both tokens
     2. Converts the Token A amount to USD value
     3. Applies applicable fees based on token scarcity
     4. Converts the remaining USD value to Token B amount

3. Example Calculation:

   Input: 1 ETH
   Oracle Price: 1 ETH = $2,000, 1 USDC = $1
   
   USD Value: 1 ETH × $2,000 = $2,000
   Fee (assuming 0.3%): $2,000 × 0.003 = $6
   Remaining Value: $2,000 - $6 = $1,994
   
   Output: $1,994 ÷ $1 = 1,994 USDC

Advantages of Oracle-Based Pricing

• Market Alignment: Token prices in the pool reflect broader market consensus rather than localized pool conditions.
• Reduced Arbitrage Vulnerability: Minimizes opportunities for arbitrage against the pool since prices are aligned with external markets.
• Consistent Pricing: Provides more predictable and stable prices regardless of pool composition.
• Capital Efficiency: Allows the pool to operate with less idle capital while maintaining effective pricing.

Oracle Safety Measures

To ensure reliable pricing, the protocol implements several safety measures:

1. Multiple Oracle Sources: Primary and fallback oracle options for each asset.
2. Staleness Checks: Verification that price data is recent enough to be reliable.
3. Deviation Limits: Alerts and potential pauses if price changes exceed predefined thresholds.
4. Smoothing Functions: Gradual adjustment mechanisms to prevent abrupt price changes.

Dynamic Scarcity-Based Fee System

Herafi employs a sophisticated fee system that adjusts based on relative token scarcity. Unlike traditional AMMs where fees are fixed, Herafi's fees dynamically respond to supply and demand conditions.

Token Demand and Supply Measurement

1. Token Demand Calculation:

   • For each token, demand is calculated based on its usage across all derivative tokens.
   • This represents how much of each token would be needed to fully collateralize all derivative tokens directly.

   Demand_token = Σ(Supply_d × BaseValue_d × Weight_token × 10^TokenDecimals)
                 / (10^DerivativeDecimals × 10^18 × Price_token)

   Where:

   • Supply_d is the total supply of a derivative token
   • BaseValue_d is the calculated value of the derivative token
   • Weight_token is the weight of the token in the derivative
   • TokenDecimals is the decimal precision of the token
   • Price_token is the current price of the token

2. Token Supply Measurement:

   • The actual balance of each token in the liquidity pool represents its supply.

3. Scarcity Multiplier:

   • The ratio of demand to supply, subject to defined constraints.

   Multiplier_raw = Demand_token / Supply_token
   
   Multiplier_uncapped = Multiplier_raw (if Demand_token > Supply_token)
   Multiplier_uncapped = 0.9 (if Demand_token ≤ Supply_token)
   
   Multiplier_capped = min(Multiplier_uncapped, 1.2)

4. Smoothed Updates:

   • To prevent abrupt fee changes, a smoothing function is applied:

   Multiplier_new = (Multiplier_capped × 800 + Multiplier_current × 200) / 1000

Fee Adjustment Based on Scarcity

The dynamic fee system applies different adjustments depending on the operation:

1. Swap Fees

Base swap fee: 0.3%

The fee is adjusted based on the scarcity of both input and output tokens:

Fee_swap = Fee_base + Adjustment_output_scarcity - Discount_output_abundance
          - Discount_input_scarcity + Adjustment_input_abundance

Component calculations:

• Adjustment_output_scarcity = (Percentage_scarcity(out) × 0.2) / 10
• Discount_output_abundance = (Percentage_abundance(out) × 0.2) / 20
• Discount_input_scarcity = (Percentage_scarcity(in) × 0.2) / 15
• Adjustment_input_abundance = (Percentage_abundance(in) × 0.2) / 30

This creates economic incentives:

• Higher fees for acquiring scarce tokens (protecting limited supply)
• Lower fees for acquiring abundant tokens (encouraging balance)
• Lower fees when providing scarce tokens (rewarding helpful behavior)
• Higher fees when providing abundant tokens (discouraging imbalance)

2. Single-Token Redemption Fees

Base fee: 1%

Higher fees apply when redeeming for scarce tokens to protect the pool from imbalances.

3. Multi-Token Redemption Fees

Base fee: 0.2%

With tiered scarcity adjustments based on the level of scarcity:

Adjustment_scarcity = (Multiplier_token - 1.0) × 2% (if scarcity ≤ 5%)
Adjustment_scarcity = (Multiplier_token - 1.0) × 2% × 1.5 (if 5% < scarcity ≤ 10%)
Adjustment_scarcity = (Multiplier_token - 1.0) × 2% × 2.0 (if scarcity > 10%)

These adjustments ensure that the pool maintains balanced liquidity while still offering flexibility to users.

Fee Distribution

Fees collected by the protocol are distributed according to a predefined split:

• 80% accrues to liquidity providers
• 20% goes to the protocol treasury

The fee split ratio is configurable by governance but defaults to:

Where:

• FeeSplitLPs = 8000 (80%)
• FEE_PRECISION = 10000

LP Token Mechanics

Liquidity providers receive LP tokens representing their ownership share in the Unified Liquidity Pool.

LP Token Issuance

Unlike traditional AMMs where LP tokens represent specific token pairs, Herafi LP tokens represent ownership of the entire pool based on USD value:

For the first deposit (empty pool):

For subsequent deposits:

Where Value_USD is calculated based on oracle prices.

Scarcity Bonus for LP Providers

When providing scarce tokens (those with demand exceeding supply), liquidity providers receive a bonus in LP token issuance:

This creates a natural economic incentive to supply tokens that are most needed by the protocol.

LP Token Valuation

The value of LP tokens is calculated based on the total USD value of all tokens in the pool:

This ensures that LP tokens maintain a fair representation of the holder's ownership percentage in the pool.

Liquidity Provision

Users can provide liquidity to the Unified Liquidity Pool in multiple ways:

Single-Token Liquidity Provision

1. User selects a single token to provide
2. The token value is calculated based on oracle price
3. Any scarcity bonus is applied if the token has high demand
4. LP tokens are minted representing the user's share of the pool

This simplifies the liquidity provision process compared to traditional AMMs that require balanced pairs.

Multi-Token Liquidity Provision

1. User selects multiple tokens to provide
2. The combined value is calculated based on oracle prices
3. Any scarcity bonuses are applied to relevant tokens
4. LP tokens are minted representing the user's share of the pool

This allows users to provide liquidity across multiple assets in a single transaction.

Liquidity Removal Options

The UnifiedLiquidityPool offers users multiple options for redeeming their LP tokens:

1. Single-Token Removal

Users can withdraw their entire share in a single token of choice:

1. User specifies the token they wish to receive
2. The system calculates the user's share of the pool in USD
3. The equivalent amount of the selected token is calculated
4. The applicable fee is determined (base fee + scarcity adjustment)
5. The token is transferred to the user minus the fee

Base fee: 1% + additional scarcity-based fee (up to 2% total)

This option offers maximum convenience but incurs higher fees, especially for scarce tokens.

2. Multi-Token Removal

Users can withdraw in multiple tokens with a specified distribution:

1. User specifies multiple tokens and their desired distribution percentages
2. The system calculates the user's share of the pool in USD
3. The equivalent amount of each selected token is calculated based on the specified distribution
4. The applicable fees are determined for each token (lower than single-token fees)
5. The tokens are transferred to the user minus the fees

Base fee: 0.2% + smaller scarcity-based fee

This option offers flexibility in token selection while incurring lower fees than single-token removal.

3. Proportional Removal

Users can withdraw in proportion to the current pool composition:

1. The system calculates the user's share of the pool in USD
2. The equivalent amount of each token is calculated based on its proportion in the pool
3. The applicable fee is determined (lowest of all options)
4. The tokens are transferred to the user minus the fee

Base fee: 0.1%

This option offers the lowest fees but requires the user to accept all tokens in their current pool proportions.

Token Swap Mechanism

The Unified Liquidity Pool enables direct swaps between any supported tokens:

Swap Process

1. HeraPool specifies input token, output token, and input amount
2. The system calculates the input value in USD based on oracle price
3. The dynamic fee is calculated based on token scarcity factors
4. The fee is deducted from the USD value
5. The remaining USD value is converted to the output token amount
6. The output token is transferred to the user

Note: This swaps is executed in the HeraPool contract. No external contract can call this function.

Slippage Protection

To protect users from unexpected price movements:

1. User specifies minimum acceptable output for the swap
2. If the calculated output falls below this minimum due to price changes between transaction submission and execution, the transaction reverts
3. This ensures users have control over the maximum slippage they're willing to accept

Default slippage tolerance: 1% (configurable by user)

Liquidity Pool Rebalancing Incentives

The dynamic fee system naturally encourages balanced liquidity without requiring explicit rebalancing mechanisms:

1. Economic Signals: Higher fees for scarce tokens and lower fees for abundant tokens signal to the market which tokens the pool needs.

2. LP Incentives: Enhanced LP token issuance for providing scarce tokens creates a direct incentive to supply tokens in high demand.

3. Arbitrage Opportunities: If pool prices diverge from external markets due to extreme imbalances, arbitrageurs can profit by correcting the imbalance through trades.

4. User Behavior Alignment: The fee system aligns user behavior with pool health - users are incentivized to provide scarce tokens and remove abundant tokens.

This market-driven approach to liquidity balancing is more capital efficient than traditional methods and adapts automatically to changing market conditions.

Price Impact and Liquidity Depth

Although Herafi uses oracle pricing, large trades can still impact effective prices through the dynamic fee mechanism:

Fee-Based Price Impact

1. As trade size increases for scarce tokens, the effective price becomes less favorable due to:

   • Base fee percentage applied to larger amounts
   • Potential increases in scarcity-based fee components

2. For very large trades, additional protections may be activated:

   • Maximum trade size limits relative to pool liquidity
   • Incremental fee increases for trades exceeding certain thresholds
   • Circuit breakers for extreme market conditions

Liquidity Depth Assessment

Users can assess liquidity depth before trading:

1. Estimated Output: The interface shows expected output amount including all applicable fees
2. Fee Breakdown: Transparent display of base fee and any scarcity adjustments
3. Price Impact: Visualization of how increasing trade size affects effective price
4. Maximum Trade Size: Indication of maximum advisable trade size based on current liquidity

These features ensure users can make informed decisions based on current liquidity conditions.

Conclusion

Herafi's liquidity framework represents a significant innovation in DeFi liquidity management. By combining a unified pool structure, oracle-based pricing, and dynamic scarcity-based fees, the protocol creates a capital-efficient system that adapts to market conditions while providing users with flexible options for participating in the ecosystem.

This approach addresses key challenges in traditional AMM designs while opening new possibilities for derivative token issuance, multi-asset exposure, and optimized trading experiences.