> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lfg.rich/llms.txt
> Use this file to discover all available pages before exploring further.

# Bonding Curve

> How LFG.RICH V5 token pricing works through the Hook-managed bonding curve.

Official LFG.RICH tokens trade through a Hook-managed bonding-curve flow instead of a creator-managed liquidity pool.

<CardGroup cols={2}>
  <Card title="Hook-managed price" icon="chart-line">
    The Hook calculates buy and sell outcomes using token-specific `poolId` state.
  </Card>

  <Card title="Official Router" icon="route">
    Users and integrations execute swaps through the Swap Router, not arbitrary third-party pools.
  </Card>

  <Card title="Floor-aware sells" icon="shield-halved">
    The effective sell price cannot move below the current protocol floor.
  </Card>

  <Card title="Indexable state" icon="database">
    Price, reserve, floor, ATH, volume, and activity can be read from protocol state and events.
  </Card>
</CardGroup>

The bonding curve defines how much token supply is minted when BNB enters the pool and how much BNB is returned when tokens are burned through a sell. In V5, this logic is enforced inside the Uniswap V4 Hook and routed through the Uniswap V4 Pool Manager.

## Buy flow

When a user buys an official V5 token:

<Steps>
  <Step title="BNB enters the Swap Router">
    The user sends BNB to `buy(key, minTokensOut)` with the token-specific PoolKey.
  </Step>

  <Step title="Router enters the Uniswap V4 flow">
    The Router uses the Pool Manager unlock/callback flow.
  </Step>

  <Step title="Pool Manager calls the Hook">
    The Hook receives the pool context and applies LFG.RICH protocol logic.
  </Step>

  <Step title="Hook reads poolId state">
    The Hook reads the token's `poolId` state for price, floor, reserve, fee, and referral rules.
  </Step>

  <Step title="Fee is deducted and curve output is calculated">
    The V5 trading fee is deducted, then the curve calculates token output from net BNB.
  </Step>

  <Step title="Tokens are minted and state updates">
    Tokens are minted to the buyer, and price, reserve, floor, ATH, volume, and trade history can be indexed from events and state.
  </Step>
</Steps>

## Sell flow

When a user sells an official V5 token:

<Steps>
  <Step title="Approve the Swap Router">
    The seller approves the official Swap Router to spend the token amount.
  </Step>

  <Step title="Call sell with the PoolKey">
    The user calls `sell(key, tokenAmount, minEthOut)`.
  </Step>

  <Step title="Router routes through Uniswap V4">
    The Router enters the same Pool Manager and Hook flow.
  </Step>

  <Step title="Hook calculates BNB output">
    The Hook calculates gross BNB return from the bonding curve and applies the V5 fee.
  </Step>

  <Step title="Tokens burn and BNB is paid out">
    Tokens are burned and the seller receives BNB after fees.
  </Step>

  <Step title="Floor protection applies">
    The sell cannot be priced below the protocol floor.
  </Step>
</Steps>

## V5 estimate functions

V5 estimate functions include the wallet address. This matters because referral state can change the fee recipient split.

```solidity theme={null}
function estimateBuy(
    bytes32 poolId,
    uint256 ethIn,
    address buyer
)
    view
    returns (uint256 tokensOut, uint256 platformFee, uint256 inviterFee);

function estimateSell(
    bytes32 poolId,
    uint256 tokenAmount,
    address seller
)
    view
    returns (uint256 ethOut, uint256 platformFee, uint256 inviterFee);
```

Use these estimates before sending a transaction and apply slippage protection:

```txt theme={null}
minTokensOut = estimatedTokensOut * (10000 - slippageBps) / 10000
minEthOut    = estimatedEthOut    * (10000 - slippageBps) / 10000
```

## Price and floor interaction

The effective sell price is never allowed to move below the token's floor price. The current effective price is exposed by:

```solidity theme={null}
function getEffectivePrice(bytes32 poolId) view returns (uint256);
```

The exact internal curve parameter can be inspected with:

```solidity theme={null}
function getTokenK(bytes32 poolId) view returns (uint256);
```

## Native BNB naming

Some contract fields and events use `ETH` in their names, such as `realETH`, `virtualETH`, or `borrowedETH`. On BNB Smart Chain these values represent native BNB. The naming follows Solidity contract conventions but the economic asset is BNB.