Technical Integration Guide

Protocol Overview

The Panda factory Protocol implements a novel token launch mechanism using bonding curves with automatic liquidity provision. This guide will help you understand and integrate with the protocol's smart contracts.

Core Architecture

The protocol is built on three primary components that work together to provide token launch and trading functionality:

1. PandaFactory

The factory contract is the main entry point for deploying new tokens and pools. It:

• Manages protocol configurations

• Controls implementation versions

• Handles deployment permissions

• Manages protocol fees and incentives

⚠️ Important

Always check if your implementation contract is approved by the factory using isImplementationAllowed() before attempting deployment.

2. PandaToken

Extends standard ERC20 functionality with bonding curve mechanics. Key features:

• ERC20 compliance with permit functionality

• Integrated bonding curve trading

• Automatic graduation to DEX trading

• Transfer restrictions pre-graduation

💡 Note on Transfers

Transfers to the DEX pair address are blocked until graduation to maintain price curve integrity.

3. PandaPool

Implements the core bonding curve mechanics:

• Single-sided liquidity provisioning

• Price discovery mechanism

• Trading functionality

• Graduation handling

Protocol Mechanics

Bonding Curve Mechanism

The protocol uses a square root price model similar to Uniswap V3, but simplified for single-sided liquidity provision. The curve is defined by:

1. Price Range

   • sqrtPa: Lower bound of price range

   • sqrtPb: Upper bound of price range

   • Current price moves between these bounds

1. Token Distribution

   • tokensInPool: Tokens available for bonding curve

   • tokensForLp: Tokens reserved for DEX liquidity

   • Distribution must satisfy pool share constraints

ℹ️ Mathematical Model

The price calculation follows: P = (sqrtP)² where sqrtP ranges from sqrtPa to sqrtPb Liquidity (L) remains constant: L = tokensInPool * (sqrtPa * sqrtPb) / (sqrtPb - sqrtPa)

Graduation Process

Graduation is the automatic transition from bonding curve to DEX trading. This occurs when:

1. Remaining tokens in pool ≤ 0.25% of initial pool tokens

2. Final price is used to set DEX pool ratio

3. Remaining tokens plus LP tokens are added to DEX

⚠️ Critical

After graduation:

• Trading switches to DEX pair

• Bonding curve functions are disabled

• Transfer restrictions are lifted

Getting Started

Prerequisites

Before integrating with the protocol, ensure you have:

1. Development Environment

   • Solidity compiler v0.8.19

   • Web3 provider

   • Access to Berachain RPC

2. Required Permissions

   • Access to approved implementation contracts

   • Sufficient base tokens for deployment

   • Required approvals for trading

3. Base Token Requirements

   interface IERC20 {
       function approve(address spender, uint256 amount) external returns (bool);
       function transfer(address to, uint256 amount) external returns (bool);
       function transferFrom(address from, address to, uint256 amount) external returns (bool);
   }

   Base tokens must:

   • Be ERC20 compliant

   • Return boolean for transfers/approvals

   • Have sufficient decimals (18 recommended)

⚠️ Base Token Warning

Non-standard ERC20 tokens (e.g., fee-on-transfer, rebasing) are not supported and may cause unexpected behavior.

Network Requirements

Requirement	Description
Gas Limit	Standard EVM operations
Chain ID	Berachain Mainnet/Testnet
RPC Support	Standard Web3 endpoints

Key Concepts

Price Configuration

The protocol enforces strict bounds on price ranges to ensure proper functioning.

Price Range Requirements

MIN_SQRTP_MULTIPLE = 11_000    // 1.1x minimum range
MAX_SQRTP_MULTIPLE = 100_000   // 10x maximum range

These translate to:

• Minimum price range: 1.21x (1.1² x)

• Maximum price range: 100x (10² x)

💡 Price Range Tip

Choose price ranges that make sense for your token's economics. Wider ranges allow more price discovery but require more capital to complete.

Example Price Calculations

// Convert display price to sqrt price
function displayToSqrtPrice(displayPrice) {
    return Math.sqrt(displayPrice * 1e18);
}

// Example price range setup
const minPrice = 1;   // 1 BASE per TOKEN
const maxPrice = 10;  // 10 BASE per TOKEN

const sqrtPa = displayToSqrtPrice(minPrice);
const sqrtPb = displayToSqrtPrice(maxPrice);

// Verify range is valid
const multiple = (sqrtPb * 10000) / sqrtPa;
if (multiple < MIN_SQRTP_MULTIPLE || multiple > MAX_SQRTP_MULTIPLE) {
    throw new Error('Invalid price range');
}

Token Distribution Parameters

The protocol enforces constraints on token distribution to ensure proper liquidity.

Pool Share Requirements

MIN_TOKENSINPOOL_SHARE = 5000  // 50% minimum in pool
MAX_TOKENSINPOOL_SHARE = 9000  // 90% maximum in pool

Distribution visualization:

Total Supply (1B tokens)
|-------------------------------------------|
|    Pool Tokens     |     LP Tokens        |
|    (50-90%)       |     (10-50%)         |
|-------------------------------------------|

ℹ️ Pool Share Information

• Pool tokens: Available for bonding curve trading

• LP tokens: Reserved for DEX liquidity after graduation

• Ratios affect final DEX liquidity depth

Fee Structure

The protocol implements a comprehensive fee structure:

struct PandaFees {
    uint16 buyFee;           // Fee on buy operations
    uint16 sellFee;          // Fee on sell operations
    uint16 graduationFee;    // Fee at graduation
    uint16 deployerFeeShare; // Share of fees to deployer
}

Fee considerations:

1. Buy/Sell Fees

   • Taken in base token

   • Calculated on input amount

   • Sent to treasury

2. Graduation Fee

   • Taken from final base token balance

   • Split between treasury and deployer

   • Affects final DEX liquidity

💡 Fee Calculation Tip

When calculating required inputs, account for fees:

const totalInput = desiredAmount * (1 + buyFee / 10000);

Integration Guide

1. Token Deployment

Deploying a new token requires careful preparation and parameter selection.

Pre-Deployment Checklist

• Verify implementation is allowed

• Calculate valid price range

• Determine token distribution

• Prepare token metadata

• Check base token configuration

Deployment Process

1. Calculate Parameters

const params = {
    baseToken: baseTokenAddress,
    sqrtPa: calculateSqrtPrice(minPrice),
    sqrtPb: calculateSqrtPrice(maxPrice),
    vestingPeriod: 0  // No vesting for standard deployment
};

1. Deploy Token

// For ERC20 base tokens
const tx = await factory.deployPandaToken(
    implementation,
    params,
    "Token Name",
    "SYMBOL",
    deployerSupplyBps  // Optional deployer allocation
);

// For native BERA
const tx = await factory.deployPandaTokenWithBera(
    implementation,
    params,
    "Token Name",
    "SYMBOL",
    deployerSupplyBps,
    { value: beraAmount }
);

⚠️ Deployment Warning

• Verify all parameters before deployment

• Deployment cannot be reversed

• Parameters cannot be changed after deployment

2. Trading Integration

Pre-Trading Requirements

1. Base token approvals

2. Minimum trade size check

3. Price impact calculations

4. Slippage protection

Trading Functions

1. Buy Tokens

// Calculate expected output
const [amountOut, fee, sqrtP] = await pandaToken.getAmountOutBuy(amountIn);

// Apply slippage tolerance
const minOut = amountOut * (1 - slippageTolerance);

// Execute trade
const tx = await pandaToken.buyTokens(amountIn, minOut, recipient);

1. Sell Tokens

// Calculate expected output
const [amountOut, fee, sqrtP] = await pandaToken.getAmountOutSell(amountIn);

// Apply slippage tolerance
const minOut = amountOut * (1 - slippageTolerance);

// Execute trade
const tx = await pandaToken.sellTokens(amountIn, minOut, recipient);

💡 Trading Tips

• Always use getAmountOut functions to estimate outputs

• Include reasonable slippage tolerance

• Monitor price impact on larger trades

Price Monitoring

// Get current price
const currentPrice = await pandaToken.getCurrentPrice();

// Get remaining tokens
const remaining = await pandaToken.remainingTokensInPool();

// Check graduation proximity
const graduationThreshold = remaining * 25 / 10000;  // 0.25%

3. Graduation Handling

Graduation Detection

1. Event Monitoring

pandaToken.on('LiquidityMoved', (amountPanda, amountBase) => {
    // Handle graduation
    switchToDexTrading();
});

1. State Checking

const graduated = await pandaToken.graduated();
if (graduated) {
    const dexPair = await pandaToken.dexPair();
    // Update trading logic
}

Post-Graduation Integration

After graduation:

1. Switch to DEX pair for trading

2. Update price feeds

3. Remove pre-graduation restrictions

ℹ️ Graduation Information

Graduation is permanent and irreversible. Always check graduated() state before operations.

Error Handling

Common Errors

Error	Description	Solution
INVALID_IMPLEMENTATION	Implementation not allowed	Verify implementation address
PRICES_TOO_CLOSE	Invalid price range	Increase price range
PRICES_TOO_FAR	Invalid price range	Decrease price range
INSUFFICIENT_OUTPUT_AMOUNT	Slippage check failed	Increase slippage tolerance
TRADE_BELOW_MIN	Trade size too small	Increase trade size
GRADUATED	Pool already graduated	Switch to DEX trading

Error Recovery Strategies

1. Deployment Failures

   • Verify all parameters

   • Check implementation status

   • Ensure base token configuration

2. Trading Failures

   • Refresh price data

   • Adjust slippage tolerance

   • Check trade size requirements

3. Graduation Issues

   • Monitor graduation events

   • Handle state transitions

   • Update integration logic

⚠️ Error Handling Best Practices

• Always wrap interactions in try-catch

• Implement proper error recovery

• Monitor transaction status

• Handle reverted transactions

Security Considerations

Important Checks

1. Pre-deployment

   • Implementation verification

   • Parameter validation

   • Base token compatibility

2. Trading

   • Slippage protection

   • Price impact monitoring

   • Balance checks

3. Post-graduation

   • State verification

   • DEX pair validation

   • Trading updates

⚠️ Security Warnings

• Never expose private keys

• Validate all input parameters

• Monitor for unexpected state changes

• Implement proper access controls