📝Developer Documentation v0.3.1

LitvmSwap ProtocolSmart Contract Architecture

Full technical documentation of the LitVM token launcher: Litvmswap V3 pool creation, LP locking, vaulting, fee distribution, and cross‑chain compatibility.

🏭Core Architecture

📝
LitVM Token

✅100B fixed supply (18 decimals)
✅ERC20 + Permit + Votes + Burnable
✅Metadata: image, description, context
✅Admin controls: updateImage, updateMetadata, verify()

🔒
LpLockerv2

✅Receives LP NFT from factory (ERC721 callback)
✅Collects Litvmswap V3 fees via positions().collect()
✅Distributes fees: team 20%, creator up to 80%, interface remainder
✅Overridable team reward recipient per token

🔐
LitvmSwapVault

✅Time‑locked allocation per token
✅Min vault duration enforced
✅Only vault admin can withdraw after endTime
✅Single allocation per token

Deployment Flow

1. Token Creation

LitvmswapDeployer.deployToken(tokenConfig, admin, TOKEN_SUPPLY)

2. (Optional) Vault

vault.deposit(token, vaultSupply, endTime, admin)

3. Pool Creation

uniswapV3Factory.createPool(token, pairedToken, 10000)

4. Initialise & Mint Position

pool.initialize(sqrtPriceX96) + positionManager.mint(...)

5. Lock LP & Set Rewards

liquidityLocker.addTokenReward(info)

6. Optional Initial Buy

swapRouter.exactInputSingle(...)

🧮Pool & Pricing Mathematics

√Starting Price (sqrtPriceX96)

Formula

sqrtPriceX96 = TickMath.getSqrtRatioAtTick(tick)

Tick → Price

price = (sqrtPriceX96 / 2^96)^2

Tick Constraints

- Multiple of 200 (TICK_SPACING)
- Strictly negative (tickIfToken0IsNewToken < 0)
- Above -887200 (MAX_TICK)

➗Liquidity Position Minting

The initial position is minted with the full pool supply as token0, using a one‑sided (non‑fungible) range based on the starting tick.

Range Logic

if (token0IsNewToken) { // newToken < pairedToken → token0 = newToken lowerTick = tick; // e.g. -20000 upperTick = MAX_TICK; // 887200 amount0 = poolSupply; // newToken amount amount1 = 0; } else { // token1 is newToken lowerTick = -MAX_TICK; upperTick = tick; amount0 = 0; amount1 = poolSupply; // newToken amount }

Effect

The position acts as a “fair launch” sell‑only liquidity wall until the price crosses the starting tick. This prevents immediate sell‑offs below the starting price.

💲Fee Distribution System

Team Reward (fixed 20%)

Recipient

teamRecipient (or token‑specific override)

• 20% of all collected fees
• Sent directly to team address
• Overridable per token by factory owner

Creator Reward (up to 80%)

Calculation

creatorFee = (collected * creatorReward) / 100

• Set at deployment, cannot exceed MAX_CREATOR_REWARD (80)
• Admin can change recipient at any time
• If creatorReward == 80, interface gets 0

Interface Reward (remainder)

Calculation

interfaceFee = collected - teamFee - creatorFee

• Sent to interface admin’s recipient
• Only exists if creatorReward < 80%
• Example: creatorReward = 60% → interface = 20%

LpLockerv2.collectRewards() – simplified

(uint256 amount0, uint256 amount1) = nonfungiblePositionManager.collect(...);
// team (20%)
uint256 team0 = amount0 * 20 / 100;
uint256 team1 = amount1 * 20 / 100;
rewardToken0.transfer(teamRecipient, team0);
rewardToken1.transfer(teamRecipient, team1);

if (creatorReward == 80) {
    // creator gets everything else
    rewardToken0.transfer(creatorRecipient, amount0 - team0);
    rewardToken1.transfer(creatorRecipient, amount1 - team1);
} else {
    uint256 creator0 = amount0 * creatorReward / 100;
    uint256 creator1 = amount1 * creatorReward / 100;
    uint256 interface0 = amount0 - team0 - creator0;
    uint256 interface1 = amount1 - team1 - creator1;
    rewardToken0.transfer(interfaceRecipient, interface0);
    rewardToken1.transfer(interfaceRecipient, interface1);
    rewardToken0.transfer(creatorRecipient, creator0);
    rewardToken1.transfer(creatorRecipient, creator1);
}

🛡️Security & Access Control

🛡️

Reentrancy Guards

All external state‑changing functions in LitvmSwap, Vault, and Locker use OpenZeppelin’s nonReentrant modifier.

🛡️

Ownership & Admins

LitvmSwap Launchpad is Ownable; a separate admins mapping allows granular admin rights for custom deployments.

🛡️

Deprecated Flag

Owner can pause new deployments via deprecated = true, while existing pools remain unaffected.

🛡️

ERC721 Receiver Check

LpLockerv2 only accepts LP NFTs from the factory address (from == factory).

🛡️

Reward Caps

Creator reward capped at MAX_CREATOR_REWARD (80), vault percentage at MAX_VAULT_PERCENTAGE (30).

🛡️

Vault Time Constraint

Vault deposits enforce endTime >= block.timestamp + minimumVaultTime (configurable by owner).

🛡️

Unauthorized Protection

Only factory can call addTokenReward and deposit; only vault admin can withdraw.

🛡️

Non‑Upgradeable (mostly)

Core logic is immutable except for targeted address updates (locker, vault) by owner.

🛡️

Precision‑Safe

Uses TickMath and OpenZeppelin’s SafeCast for all critical calculations.

📊Technical Comparison

Feature	pump.fun	flaunch	LitvmSwap Launchpad
Liquidity Model	Bonding curve → Raydium	Fixed price launch	Full Litvmswap V3 range position
LP Ownership	Burnt	Unlocked after time	Permanently locked in LpLockerv2
Fee Distribution	Simple fee share	Developer fee only	Team 20%, Creator up to 80%, Interface remainder
Vault / Lockup	None	None	Up to 30% time‑locked LitvmVault
Cross‑chain	No	No	Native IERC7802 support
Token Standard	SPL token	ERC20	ERC20 + Permit + Votes + Burnable + Metadata
Initial Buy	First buy triggers curve	No	Built‑in ETH swap during deployment
Security	Audited?	Basic	OpenZeppelin, reentrancy guards, admin roles

📝Integration Examples

Deploy a Token with Default Rewards

// Frontend calls litvm.deployToken(...)
DeploymentConfig memory config = DeploymentConfig({
    tokenConfig: TokenConfig({
        name: "MyToken",
        symbol: "MTK",
        originatingChainId: block.chainid,
        salt: "random_salt",
        image: "ipfs://...",
        metadata: "ipfs://...",
        context: ""
    }),
    poolConfig: PoolConfig({
        pairedToken: WETH,
        tickIfToken0IsNewToken: -20000  // starting price ≈ 0.0001 ETH
    }),
    rewardsConfig: RewardsConfig({
        creatorReward: 70,
        creatorAdmin: msg.sender,
        creatorRewardRecipient: msg.sender,
        interfaceAdmin: address(0),
        interfaceRewardRecipient: address(0)
    }),
    vaultConfig: VaultConfig({ vaultPercentage: 0, vaultDuration: 0 }),
    initialBuyConfig: InitialBuyConfig({
        pairedTokenPoolFee: 3000,
        pairedTokenSwapAmountOutMinimum: 0
    })
});
// Send ETH for initial buy if desired
// litvm.deployToken{value: 0.1 ether}(config);

Collect Fees for a Position

// Anyone can trigger fee collection
litvm.claimRewards(tokenAddress);

// Internally:
// 1. Reads deploymentInfoForToken[token] to get locker address & positionId
// 2. Calls liquidityLocker.collectRewards(positionId)
// 3. LpLockerv2.collectRewards calls INonfungiblePositionManager.collect
//    then distributes tokens to team, creator, interface

Update Creator Reward Recipient

// Only the creator admin can call this
lpLocker.updateCreatorRewardRecipient(positionId, newRecipient);

Summary

Litvmswap Launchpad Advantages

• Full Litvmswap V3 integration with custom starting price
• Permanent LP lock with automated fee distribution
• Optional token vaulting for controlled supply release
• Immutable contracts with granular admin controls

For Developers

• All contracts are verified and auditable
• Clean separation of concerns (token, locker, vault, factory)
• OpenZeppelin patterns ensure reliability
• Predictable CREATE2 token addresses
• Event‑rich for easy off‑chain indexing

Litvmswap Launchpad is a fair launch protocol that combines the maturity of Litvmswap V3 with transparent on‑chain reward mechanics – no bonding curves, no hidden fees.