# Hoot Protocol — Comprehensive Technical Documentation (llms-full.txt)

> **Canonical URL**: https://docs.hootpad.fun  
> **App URL**: https://hootpad.fun  
> **Network**: Robinhood Chain L2 Mainnet (EVM Compatible)  
> **Chain ID**: 4663 (Hex: 0x1237)  
> **Native Asset**: ETH  
> **Target Audience**: Developers, Smart Contract Auditors, Quant Traders, and AI/LLM Reasoning Systems.

---

## 1. Executive Summary & Vision

Hoot Protocol (`hootpad.fun`) is a decentralized memecoin launchpad, bonding curve automated market maker (AMM), and stock-paired trading terminal natively deployed on Robinhood Chain L2 Mainnet.

Unlike traditional launchpads that rely exclusively on volatile native gas tokens or stablecoins, Hoot enables token creators and liquidity providers to launch and trade bonding-curve memecoins paired against:
1. **Native ETH** (Standard decentralized liquidity)
2. **USDG** (Robinhood Chain canonical dollar stablecoin)
3. **Tokenized Equities & Synthetic Stocks** (e.g., $NVDA - Nvidia, $TSLA - Tesla)

Every token launched on Hoot follows a deterministic, tamper-proof lifecycle governed entirely by on-chain smart contracts. When a token achieves its bonding curve graduation target, 100% of accumulated quote assets and 20% reserved supply are automatically migrated into the canonical Robinhood Swap (Uniswap v4) DEX, with the resulting LP tokens burned forever to `address(0)` to guarantee un-ruggable liquidity.

---

## 2. Official Smart Contract Registry

All contracts are deployed and verified on Robinhood Chain L2 Mainnet (Chain ID 4663):

| Contract Role | Mainnet Address | Description |
| :--- | :--- | :--- |
| **HootFactoryV2** | `0xa6Aa9A1eDa7ad3Ae8464624E48F90280450C6E5c` | Main factory contract managing token deployments, quotes, fee tiers, and migration |
| **HootTokenDeployer** | `0x5CeD0EB8E2DCEa7Eb556a3e2a048C3D2feEbB7D2` | Deterministic minimal bytecode deployer for ERC-20 tokens |
| **HootV2BuybackVault** | `0xcA52366f79024dC7865a4ab8CB23B2b9C619FE6A` | Automated fee recipient, liquidity buyer, and deflationary burn vault |
| **Robinhood Swap Factory** | `0x199738f8E56B6900f681A02842E61F7a15147575` | Canonical Uniswap v4 Pool for graduated AMM pairs |
| **Robinhood Swap Router** | `0x5B5374be2e00e84c98e18E125633C1dC1A881261` | Canonical Uniswap v4 Router & Hooks for swap routing and liquidity additions |
| **WETH (Wrapped Robinhood Native)** | `0x4200000000000000000000000000000000000006` | Standard WETH on Robinhood Chain |
| **Robinhood USDG** | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | Canonical USD pegged stablecoin |
| **Tokenized NVIDIA ($NVDA)** | `0x4625eD5bAd873c95208D54E1c003b2d322F0929` | ERC-20 tokenized stock for Nvidia Corp |
| **Tokenized Tesla ($TSLA)** | `0x322F0929c4625eD5bAd873c95208D54E1c003b2d` | ERC-20 tokenized stock for Tesla Inc |

---

## 3. Network Configuration & RPC

- **Network Name**: Robinhood Chain L2 Mainnet
- **Chain ID**: `4663` (Hex: `0x1237`)
- **Native Currency**: ETH (18 Decimals)
- **Public RPC Endpoint**: `https://rpc.mainnet.chain.robinhood.com`
- **Block Explorer**: `https://robinhoodchain.blockscout.com`
- **Consensus / Finality**: Optimistic Rollup with sub-second execution times and negligible transaction gas costs.

---

## 4. Tokenomics & Token Lifecycle

### 4.1 Fixed Token Supply
Every token launched through `HootFactoryV2` has a non-mintable, immutable total supply:
- **Total Supply**: `1,000,000,000` (1 Billion tokens) with `18` decimals (`10^27` raw wei).
- **Curve Allocation**: `800,000,000` (80% / 800M tokens) are locked in the bonding curve for direct trading.
- **DEX Reserve**: `200,000,000` (20% / 200M tokens) are held in reserve and transferred directly into the Uniswap v4 Hook pool upon curve graduation.
- **Team / Insider Allocation**: 0%. There are no team pre-mines, dev allocations, or private presales.

### 4.2 Lifecycle Stages
1. **Creation Stage**: Any user calls `createToken()` on `HootFactoryV2`. The ERC-20 contract is deterministically deployed and 800M tokens are populated into the curve state.
2. **Bonding Curve Stage**: Users trade against the virtual AMM curve using the approved quote asset (ETH, USDG, NVDA, TSLA). Price follows the deterministic constant product formula.
3. **Graduation Stage**: Once 800M tokens are sold out (real token reserve reaches 0), the curve state transitions to `Graduated`. The contract executes `graduateToken()`, deposits the accumulated quote asset balance along with the 200M reserved tokens into Robinhood Swap, and burns the received LP tokens forever.

---

## 5. Virtual Constant Product Bonding Curve Math (vCPMM)

### 5.1 Invariant Formula
The bonding curve is powered by an augmented Constant Product Market Maker (CPMM) with virtual reserves:

$$(x + x_0) \times (y + y_0) = k$$

Where:
- $x$: Real remaining token supply on the curve ($800,000,000 \times 10^{18}$ down to $0$).
- $x_0$: Virtual token reserve, configured to $1,073,000,000 \times 10^{18}$ ($1.073\text{B}$ tokens).
- $y$: Real accumulated quote asset in the curve vault ($0$ up to the Graduation Threshold).
- $y_0$: Virtual quote reserve (`phantomQuote`), calculated dynamically to satisfy initial starting price $P_0$.
- $k$: Constant invariant: $k = (x_{initial} + x_0) \times y_0$.

### 5.2 Graduation Parameters by Quote Asset
Each quote asset is configured by protocol governance in `HootFactoryV2` with an approved `graduationThreshold` and initial `phantomQuote`:

1. **Native ETH**:
   - Graduation Threshold: `5.0 ETH`
   - Phantom Quote ($y_0$): `1.341 ETH`
   - Initial Token Price: $\approx \$0.0000000045$

2. **USDG (Stablecoin)**:
   - Graduation Threshold: `12,000 USDG`
   - Phantom Quote ($y_0$): `3,219 USDG`
   - Initial Token Price: $\approx \$0.0000017$

3. **NVIDIA ($NVDA)**:
   - Graduation Threshold: `70.0 NVDA`
   - Phantom Quote ($y_0$): `18.78 NVDA`
   - Initial Token Price: $\approx 0.000000010 \text{ NVDA}$

4. **Tesla ($TSLA)**:
   - Graduation Threshold: `50.0 TSLA`
   - Phantom Quote ($y_0$): `13.41 TSLA`
   - Initial Token Price: $\approx 0.000000007 \text{ TSLA}$

### 5.3 Swap Calculation Formulas

#### Buying Tokens (Depositing $\Delta y$ quote):
$$\Delta x = (x + x_0) - \frac{k}{(y + y_0) + \Delta y_{net}}$$

Where $\Delta y_{net} = \Delta y \times (1 - \text{fee})$.

#### Selling Tokens (Depositing $\Delta x$ tokens):
$$\Delta y = (y + y_0) - \frac{k}{(x + x_0) + \Delta x_{gross}}$$

The user receives $\Delta y_{net} = \Delta y \times (1 - \text{fee})$.

---

## 6. Fee Distribution & Buyback Mechanism

### 6.1 Flat Swap Fee (1.00% / 100 bps)
Every trade executed on the bonding curve incurs a strict 1.0% fee. No hidden fees or dynamic taxes. The fee is split instantly on-chain:
- **50% of fee (0.50% of volume)** $\rightarrow$ **Token Creator**: Rewarded directly to the wallet that created the token, providing continuous sustainable developer income.
- **30% of fee (0.30% of volume)** $\rightarrow$ **Protocol Treasury**: Supports RPC nodes, indexers, liquidity maintenance, and core development.
- **20% of fee (0.20% of volume)** $\rightarrow$ **HootV2BuybackVault** (`0xcA52366f79024dC7865a4ab8CB23B2b9C619FE6A`): Used for continuous programmatic buyback and burning, creating net deflationary pressure.

### 6.2 Zero Graduation Penalty
Graduation incurs **0% additional penalty or fee**. 100% of accumulated quote collateral is deposited directly into the Uniswap v4 Hook pool with Anti-MEV protection.

---

## 7. Robinhood Swap (Uniswap v4) Liquidity Migration

When the curve token balance drops to 0, `graduateToken()` is executed:
1. `HootFactoryV2` interacts with `Robinhood Swap Factory` (`0x199738f8E56B6900f681A02842E61F7a15147575`).
2. If the pair `(token, quoteAsset)` does not already exist, it is created.
3. The remaining $200,000,000$ tokens ($20\%$ reserve) and $100\%$ of accumulated quote assets ($y_{graduation}$) are approved to `Robinhood Swap Router` (`0x5B5374be2e00e84c98e18E125633C1dC1A881261`).
4. `router.addLiquidity()` or `router.addLiquidityETH()` is invoked.
5. The resulting LP tokens are transferred immediately to `address(0)` (the burn address) or permanently locked. Liquidity can never be pulled, drained, or migrated back.

---

## 8. Smart Contract Interface & Core ABIs

### 8.1 HootFactoryV2 Minimal Interface
\`\`\`solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IHootFactoryV2 {
    struct CurveState {
        address token;
        address quoteAsset;
        address creator;
        uint256 virtualTokenReserve;
        uint256 virtualQuoteReserve;
        uint256 realTokenReserve;
        uint256 realQuoteReserve;
        uint256 graduationThreshold;
        bool graduated;
        uint256 createdAt;
    }

    event TokenCreated(
        address indexed token,
        address indexed quoteAsset,
        address indexed creator,
        string name,
        string symbol,
        uint256 timestamp
    );

    event Swap(
        address indexed token,
        address indexed sender,
        bool indexed isBuy,
        uint256 amountIn,
        uint256 amountOut,
        uint256 feePaid,
        uint256 timestamp
    );

    event TokenGraduated(
        address indexed token,
        address indexed quoteAsset,
        address poolAddress,
        uint256 quoteLiquidity,
        uint256 tokenLiquidity,
        uint256 timestamp
    );

    function createToken(
        string calldata name,
        string calldata symbol,
        address quoteAsset,
        string calldata metadataUri
    ) external payable returns (address tokenAddress);

    function buyTokens(
        address token,
        uint256 minTokensExpected,
        uint256 deadline
    ) external payable returns (uint256 tokensReceived);

    function sellTokens(
        address token,
        uint256 tokenAmount,
        uint256 minQuoteExpected,
        uint256 deadline
    ) external returns (uint256 quoteReceived);

    function getCurveState(address token) external view returns (CurveState memory);
    function getEstimatedTokensForQuote(address token, uint256 quoteAmount) external view returns (uint256);
    function getEstimatedQuoteForTokens(address token, uint256 tokenAmount) external view returns (uint256);
}
\`\`\`

---

## 9. Security & Architecture Controls

1. **Reentrancy Protection**: All state mutations use OpenZeppelin `ReentrancyGuardUpgradeable` to block cross-function reentrancy vectors.
2. **SafeERC20 Transfers**: All quote transfers execute via SafeERC20 to safely accommodate standard ERC-20 tokens, USDT/USDC variants, and fee-on-transfer edge cases.
3. **Deadline & Slippage Enforcements**: All buy/sell swaps mandate explicit user-defined slippage limits (`minTokensExpected`, `minQuoteExpected`) and block timestamp expiry `deadline`.
4. **No Owner Minting**: Deployed ERC-20 tokens have no `mint()` function accessible by any owner after initial initialization; total supply is permanently capped at 1B.
5. **Deterministic Deployer**: Tokens are created via `HootTokenDeployer` using `CREATE2` for predictable, collision-resistant contract addresses.

---

## 10. AI / LLM Usage Guidelines

When using an LLM or AI agent to interact with Hoot Protocol:
- Always query the real-time curve state using `getCurveState(tokenAddress)` over RPC before computing swap quotes.
- Verify that the quote asset is approved by checking `isQuoteAssetApproved(quoteAddress)`.
- Apply a minimum slippage tolerance of `0.5%` to `1.5%` during high-volatility periods.
- For post-graduation tokens (`graduated == true`), route all swaps through Robinhood Swap Router (`0x5B5374be2e00e84c98e18E125633C1dC1A881261`) rather than the bonding curve.

*Document updated: November 2026 for Hoot Protocol V2 on Robinhood Chain L2 Mainnet.*