@mania-labs/mania-sdk

Official SDK for interacting with Mania Fun - an EVM-based token launchpad using bonding curves.

Overview

Mania Protocol enables anyone to create and trade tokens on a bonding curve. When a token's bonding curve reaches the migration threshold (4 ETH), liquidity is automatically migrated to Uniswap V3, providing deep liquidity for the token.

Key Features

• Bonding Curve Trading: Buy and sell tokens on a constant product AMM
• Fair Launch: Every token starts with the same bonding curve parameters
• Automatic Migration: Liquidity migrates to Uniswap V3 when threshold is reached
• Creator Rewards: Token creators earn 0.30% of all trading fees

Important Notes

Tokens will be non-transferrable until migration. This is a critical security feature to prevent pre-initialisation of Uniswap pools at unfavourable prices. This ensures all tokens migrate with equal reserves, in a ratio of 4 ETH : 206.9M tokens.

The Mania Factory contract is upgradeable via a UUPS proxy pattern. Updates will be pushed sparingly, with significant notice for all integrators and SDK users. To stay informed about any upcoming updates, please join our Telegram channel at https://t.me/maniaFunDevelopers

Installation

npm install @mania-labs/mania-sdk viem
# or
yarn add @mania-labs/mania-sdk viem
# or
pnpm add @mania-labs/mania-sdk viem

Quick Start

import { ManiaSDK } from "@mania-labs/mania-sdk";
import { parseEther } from "viem";
import { base } from "viem/chains";

// Initialize the SDK
const sdk = new ManiaSDK({
  factoryAddress: "0x...", // ManiaFactory contract address
  rpcUrl: "https://megaeth-testnet-v2.blockscout.com",
  chainId: 6543,
});

// Connect a wallet for transactions
sdk.connectWallet(process.env.PRIVATE_KEY!, base);

// Get token information
const tokenInfo = await sdk.getTokenInfo("0x...");
console.log("Current Price:", tokenInfo.currentPrice);
console.log("Migration Progress:", tokenInfo.migrationProgress, "%");

Usage

Creating a Token

// Create a new token
const result = await sdk.create({
  name: "My Token",
  symbol: "MTK",
  uri: "ipfs://...", // Metadata URI
  creator: "0x...", // Creator address (receives fees)
});

console.log("Token created:", result.tokenAddress);
console.log("Transaction:", result.hash);

Create and Buy in One Transaction

// Create token and buy in a single transaction
const result = await sdk.createAndBuy({
  name: "My Token",
  symbol: "MTK",
  uri: "ipfs://...",
  creator: "0x...",
  buyAmountEth: parseEther("0.1"), // Buy with 0.1 ETH
  minTokensOut: 0n, // Set minimum for slippage protection
});

Buying Tokens

import { parseEther } from "viem";

// Buy with manual slippage
const quote = await sdk.getBuyQuote(tokenAddress, parseEther("0.1"));
const minTokensOut = (quote * 99n) / 100n; // 1% slippage

await sdk.buy({
  token: tokenAddress,
  amountEth: parseEther("0.1"),
  minTokensOut,
});

// Or use built-in slippage calculation
await sdk.buyWithSlippage(
  tokenAddress,
  parseEther("0.1"),
  100 // 1% slippage in basis points
);

Selling Tokens

// Sell tokens
const tokenAmount = parseEther("1000"); // 1000 tokens
const quote = await sdk.getSellQuote(tokenAddress, tokenAmount);
const minEthOut = (quote * 99n) / 100n; // 1% slippage

await sdk.sell({
  token: tokenAddress,
  amountTokens: tokenAmount,
  minEthOut,
});

// Or use built-in slippage calculation
await sdk.sellWithSlippage(tokenAddress, tokenAmount, 100);

Working with Bonding Curves

import { BondingCurve } from "@mania-labs/mania-sdk";

// Get bonding curve instance for calculations
const curve = await sdk.getBondingCurveInstance(tokenAddress);

// Get current state
const state = curve.getState();
console.log("Virtual Token Reserves:", state.virtualTokenReserves);
console.log("Virtual ETH Reserves:", state.virtualEthReserves);

// Check status
console.log("Is Complete:", curve.isComplete());
console.log("Is Migrated:", curve.isMigrated());

// Get quotes locally (no RPC call)
const buyQuote = curve.getBuyQuote(parseEther("0.1"));
console.log("Tokens Out:", buyQuote.tokensOut);
console.log("Fee:", buyQuote.fee);
console.log("Price per Token:", buyQuote.pricePerToken);

// Calculate price impact
const priceImpact = curve.calculateBuyPriceImpact(parseEther("1"));
console.log("Price Impact:", priceImpact, "%");

// Get migration progress
console.log("Migration Progress:", curve.getMigrationProgress(), "%");
console.log("ETH Until Migration:", curve.getEthUntilMigration());

Migration to Uniswap V3

// Check if curve is complete
const isComplete = await sdk.isComplete(tokenAddress);

if (isComplete) {
  // Migrate liquidity to Uniswap V3
  // Note: Caller pays the migration fee (poolMigrationFee)
  const result = await sdk.migrate({ token: tokenAddress });
  console.log("Pool Address:", result.poolAddress);
}

Watching Events

// Watch for new token creations
const unwatch = sdk.watchCreateEvents((event) => {
  console.log("New token created:", event.mint);
  console.log("Name:", event.name);
  console.log("Symbol:", event.symbol);
  console.log("Creator:", event.creator);
});

// Watch trades on a specific token
sdk.watchTradeEvents(tokenAddress, (event) => {
  console.log(event.isBuy ? "Buy" : "Sell");
  console.log("ETH Amount:", event.ethAmount);
  console.log("Token Amount:", event.tokenAmount);
  console.log("User:", event.user);
});

// Watch for curve completions
sdk.watchCompleteEvents((event) => {
  console.log("Curve complete:", event.mint);
});

// Watch for migrations
sdk.watchMigrationEvents((event) => {
  console.log("Token migrated:", event.mint);
  console.log("Pool:", event.pool);
});

// Stop watching
unwatch();

Reading Global State

const globalState = await sdk.getGlobalState();

console.log("Fee Basis Points:", globalState.feeBasisPoints); // 100 = 1%
console.log("Migration Enabled:", globalState.enableMigrate);
console.log("Pool Migration Fee:", globalState.poolMigrationFee);
console.log("Token Total Supply:", globalState.tokenTotalSupply);

Utility Functions

import {
  formatEthValue,
  formatTokenAmount,
  parseEthValue,
  calculateWithSlippage,
  formatPrice,
  formatMarketCap,
  truncateAddress,
  bpsToPercent,
} from "@mania-labs/mania-sdk";

// Format values for display
console.log(formatEthValue(parseEther("1.234567"))); // "1.2346"
console.log(formatTokenAmount(parseEther("1234567890"))); // "1.23B"
console.log(formatPrice(1234567890123456n)); // "0.0012"
console.log(formatMarketCap(parseEther("1500"))); // "1.50K ETH"

// Calculate slippage
const minOut = calculateWithSlippage(parseEther("100"), 100); // 1% slippage

// Format addresses
console.log(truncateAddress("0x1234...5678")); // "0x1234...5678"

// Convert basis points
console.log(bpsToPercent(100)); // 1

Constants

import {
  MIGRATION_THRESHOLD,
  TOKENS_FOR_LP,
  PROTOCOL_FEE_BASIS_POINTS,
  CREATOR_FEE_BASIS_POINTS,
  DEFAULT_SLIPPAGE_BPS,
  UNISWAP_FEE_TIER,
} from "@mania-labs/mania-sdk";

// Migration threshold: 4 ETH
console.log(MIGRATION_THRESHOLD); // 4000000000000000000n

// Tokens allocated for LP: 206.9M
console.log(TOKENS_FOR_LP);

// Fee breakdown
console.log(PROTOCOL_FEE_BASIS_POINTS); // 70 (0.70%)
console.log(CREATOR_FEE_BASIS_POINTS); // 30 (0.30%)

// Default slippage: 1%
console.log(DEFAULT_SLIPPAGE_BPS); // 100

// Uniswap V3 fee tier: 0.3%
console.log(UNISWAP_FEE_TIER); // 3000

Chain Configuration

import { getChainConfig, CHAIN_CONFIGS } from "@mania-labs/mania-sdk";

// Get config for a specific chain
const baseConfig = getChainConfig(8453);
console.log(baseConfig?.factoryAddress);
console.log(baseConfig?.wethAddress);

// Or create SDK from chain ID
const sdk = ManiaSDK.fromChainId(8453, "https://mainnet.base.org");

Advanced Usage

Custom Viem Clients

import { createPublicClient, createWalletClient, http } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

const publicClient = createPublicClient({
  chain: base,
  transport: http("https://mainnet.base.org"),
});

const walletClient = createWalletClient({
  account: privateKeyToAccount("0x..."),
  chain: base,
  transport: http("https://mainnet.base.org"),
});

const sdk = new ManiaSDK({
  factoryAddress: "0x...",
  chainId: 8453,
});

sdk.setPublicClient(publicClient);
sdk.setWalletClient(walletClient);

Direct ABI Access

import { MANIA_FACTORY_ABI, ERC20_ABI } from "@mania-labs/mania-sdk";
import { getContract } from "viem";

// Use ABIs directly with viem
const contract = getContract({
  address: factoryAddress,
  abi: MANIA_FACTORY_ABI,
  client: publicClient,
});

Protocol Details

Bonding Curve Formula

The protocol uses a constant product formula with virtual reserves:

tokensOut = (virtualTokenReserves * netEth) / (virtualEthReserves + netEth)
ethOut = (tokenAmount * virtualEthReserves) / (virtualTokenReserves + tokenAmount)

Fee Structure

• Total Trading Fee: 1.00% (100 basis points)
  • Protocol Fee: 0.70%
  • Creator Fee: 0.30%

Migration

When realEthReserves reaches 4 ETH:

1. Bonding curve is marked as complete
2. Anyone can call migrate() (paying poolMigrationFee)
3. Token trading is enabled (unlocked)
4. Liquidity (206.9M tokens + 4 ETH) is added to Uniswap V3
5. LP NFT is sent to dead address (locked forever)

TypeScript Support

This package is written in TypeScript and includes full type definitions.

import type {
  BondingCurveState,
  GlobalState,
  CreateTokenParams,
  BuyParams,
  SellParams,
  TokenInfo,
  TransactionResult,
} from "@mania-labs/mania-sdk";

Error Handling

try {
  await sdk.buy({
    token: tokenAddress,
    amountEth: parseEther("10"), // Too much ETH
    minTokensOut: 0n,
  });
} catch (error) {
  // Common errors:
  // - BuyExceedsMigrationThreshold: Buy would exceed 4 ETH threshold
  // - BondingCurveComplete: Trading has ended
  // - TooLittleTokensReceived: Slippage exceeded
  console.error("Transaction failed:", error);
}

License

MIT