@mania-labs/mania-sdk 1.0.0

package/src/index.ts

@@ -0,0 +1,71 @@
+// Main SDK class
+export { ManiaSDK } from "./mania.js";
+
+// Bonding curve utilities
+export { 
+  BondingCurve,
+  calculateBuyAmount,
+  calculateSellAmount,
+} from "./bondingCurve.js";
+
+// Types
+export type {
+  BondingCurveState,
+  GlobalState,
+  SetParamsInput,
+  CreateTokenParams,
+  CreateAndBuyParams,
+  BuyParams,
+  SellParams,
+  MigrateParams,
+  BuyQuote,
+  SellQuote,
+  TokenInfo,
+  TransactionResult,
+  CreateEvent,
+  TradeEvent,
+  CompleteEvent,
+  MigrationEvent,
+  ManiaSDKConfig,
+  SlippageConfig,
+} from "./types.js";
+
+// Constants
+export {
+  PROTOCOL_FEE_BASIS_POINTS,
+  CREATOR_FEE_BASIS_POINTS,
+  TOTAL_FEE_BASIS_POINTS,
+  MAX_FEE_BASIS_POINTS,
+  MIGRATION_THRESHOLD,
+  TOKENS_FOR_LP,
+  MAX_MIGRATE_FEES,
+  UNISWAP_FEE_TIER,
+  TICK_LOWER,
+  TICK_UPPER,
+  DEFAULT_SLIPPAGE_BPS,
+  BPS_DENOMINATOR,
+  CHAIN_CONFIGS,
+  getChainConfig,
+  type ChainConfig,
+} from "./constants.js";
+
+// Utility functions
+export {
+  formatEthValue,
+  formatTokenAmount,
+  parseEthValue,
+  calculateWithSlippage,
+  calculateMigrationProgress,
+  formatPrice,
+  formatMarketCap,
+  isValidAddress,
+  truncateAddress,
+  bpsToPercent,
+  percentToBps,
+  calculatePriceImpact,
+  sleep,
+  withRetry,
+} from "./utils.js";
+
+// ABIs
+export { MANIA_FACTORY_ABI, ERC20_ABI } from "./abi.js";

package/src/mania.ts

@@ -0,0 +1,652 @@
+import {
+  createPublicClient,
+  createWalletClient,
+  http,
+  type Address,
+  type PublicClient,
+  type WalletClient,
+  type Chain,
+  parseEventLogs,
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import type {
+  BondingCurveState,
+  GlobalState,
+  CreateTokenParams,
+  CreateAndBuyParams,
+  BuyParams,
+  SellParams,
+  MigrateParams,
+  TokenInfo,
+  TransactionResult,
+  CreateEvent,
+  TradeEvent,
+  CompleteEvent,
+  MigrationEvent,
+  ManiaSDKConfig,
+} from "./types.js";
+import { BondingCurve } from "./bondingCurve.js";
+import {
+  DEFAULT_SLIPPAGE_BPS,
+  getChainConfig,
+} from "./constants.js";
+import { MANIA_FACTORY_ABI } from "./abi.js";
+
+/**
+ * ManiaSDK - Official SDK for interacting with the Mania Protocol
+ * 
+ * Mania is an EVM-based token launchpad using bonding curves. Tokens are created
+ * with an initial bonding curve that allows trading until a migration threshold
+ * (4 ETH) is reached. Once complete, liquidity is migrated to Uniswap V3.
+ */
+export class ManiaSDK {
+  public publicClient: PublicClient;
+  public walletClient: WalletClient | null = null;
+  public readonly factoryAddress: Address;
+  public readonly chainId: number;
+
+  /**
+   * Create a new ManiaSDK instance
+   * 
+   * @param config - SDK configuration
+   * @param config.factoryAddress - ManiaFactory contract address
+   * @param config.rpcUrl - RPC URL for the chain
+   * @param config.chainId - Chain ID (optional, will be fetched if not provided)
+   */
+  constructor(config: ManiaSDKConfig) {
+    this.factoryAddress = config.factoryAddress;
+    this.chainId = config.chainId ?? 1;
+
+    this.publicClient = createPublicClient({
+      transport: http(config.rpcUrl),
+    });
+  }
+
+  /**
+   * Create SDK instance from chain ID using default configuration
+   * 
+   * @param chainId - Chain ID
+   * @param rpcUrl - RPC URL (optional, uses public RPC if not provided)
+   * @returns ManiaSDK instance
+   */
+  static fromChainId(chainId: number, rpcUrl?: string): ManiaSDK {
+    const chainConfig = getChainConfig(chainId);
+    if (!chainConfig) {
+      throw new Error(`Unsupported chain ID: ${chainId}`);
+    }
+
+    return new ManiaSDK({
+      factoryAddress: chainConfig.factoryAddress,
+      rpcUrl,
+      chainId,
+    });
+  }
+
+  /**
+   * Connect a wallet for signing transactions
+   * 
+   * @param privateKey - Private key (with or without 0x prefix)
+   * @param chain - Viem chain object
+   */
+  connectWallet(privateKey: string, chain: Chain): void {
+    const account = privateKeyToAccount(
+      privateKey.startsWith("0x") ? (privateKey as `0x${string}`) : (`0x${privateKey}` as `0x${string}`)
+    );
+
+    this.walletClient = createWalletClient({
+      account,
+      chain,
+      transport: http(),
+    });
+  }
+
+  /**
+   * Connect an existing wallet client
+   * 
+   * @param walletClient - Viem wallet client
+   */
+  setWalletClient(walletClient: WalletClient): void {
+    this.walletClient = walletClient;
+  }
+
+  /**
+   * Set a custom public client
+   * 
+   * @param publicClient - Viem public client
+   */
+  setPublicClient(publicClient: PublicClient): void {
+    this.publicClient = publicClient;
+  }
+
+  /**
+   * Get the connected wallet address
+   */
+  getWalletAddress(): Address | undefined {
+    return this.walletClient?.account?.address;
+  }
+
+  // ========== READ METHODS ==========
+
+  /**
+   * Get global protocol configuration
+   */
+  async getGlobalState(): Promise<GlobalState> {
+    const result = await this.publicClient.readContract({
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "global",
+    });
+
+    const [
+      initialized,
+      authority,
+      feeRecipient,
+      initialVirtualTokenReserves,
+      initialVirtualEthReserves,
+      initialRealTokenReserves,
+      tokenTotalSupply,
+      feeBasisPoints,
+      withdrawAuthority,
+      enableMigrate,
+      poolMigrationFee,
+    ] = result as [boolean, Address, Address, bigint, bigint, bigint, bigint, bigint, Address, boolean, bigint];
+
+    return {
+      initialized,
+      authority,
+      feeRecipient,
+      initialVirtualTokenReserves,
+      initialVirtualEthReserves,
+      initialRealTokenReserves,
+      tokenTotalSupply,
+      feeBasisPoints,
+      withdrawAuthority,
+      enableMigrate,
+      poolMigrationFee,
+    };
+  }
+
+  /**
+   * Get bonding curve state for a token
+   * 
+   * @param token - Token address
+   */
+  async getBondingCurve(token: Address): Promise<BondingCurveState> {
+    const result = await this.publicClient.readContract({
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "getBondingCurve",
+      args: [token],
+    });
+
+    const curve = result as {
+      virtualTokenReserves: bigint;
+      virtualEthReserves: bigint;
+      realTokenReserves: bigint;
+      realEthReserves: bigint;
+      tokenTotalSupply: bigint;
+      complete: boolean;
+      trackVolume: boolean;
+    };
+
+    return {
+      virtualTokenReserves: curve.virtualTokenReserves,
+      virtualEthReserves: curve.virtualEthReserves,
+      realTokenReserves: curve.realTokenReserves,
+      realEthReserves: curve.realEthReserves,
+      tokenTotalSupply: curve.tokenTotalSupply,
+      complete: curve.complete,
+      trackVolume: curve.trackVolume,
+    };
+  }
+
+  /**
+   * Get a BondingCurve instance for calculations
+   * 
+   * @param token - Token address
+   */
+  async getBondingCurveInstance(token: Address): Promise<BondingCurve> {
+    const [curveState, globalState] = await Promise.all([
+      this.getBondingCurve(token),
+      this.getGlobalState(),
+    ]);
+
+    return new BondingCurve(curveState, globalState.feeBasisPoints);
+  }
+
+  /**
+   * Get comprehensive token information
+   * 
+   * @param token - Token address
+   */
+  async getTokenInfo(token: Address): Promise<TokenInfo> {
+    const curve = await this.getBondingCurveInstance(token);
+    const state = curve.getState();
+
+    return {
+      address: token,
+      bondingCurve: state,
+      currentPrice: curve.getCurrentPrice(),
+      marketCapEth: curve.getMarketCapEth(),
+      migrationProgress: curve.getMigrationProgress(),
+    };
+  }
+
+  /**
+   * Get buy quote from contract
+   * 
+   * @param token - Token address
+   * @param ethAmount - ETH amount in wei
+   */
+  async getBuyQuote(token: Address, ethAmount: bigint): Promise<bigint> {
+    const result = await this.publicClient.readContract({
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "getBuyQuote",
+      args: [token, ethAmount],
+    });
+
+    return result as bigint;
+  }
+
+  /**
+   * Get sell quote from contract
+   * 
+   * @param token - Token address
+   * @param tokenAmount - Token amount
+   */
+  async getSellQuote(token: Address, tokenAmount: bigint): Promise<bigint> {
+    const result = await this.publicClient.readContract({
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "getSellQuote",
+      args: [token, tokenAmount],
+    });
+
+    return result as bigint;
+  }
+
+  /**
+   * Get fee for a given amount
+   * 
+   * @param amount - Amount in wei
+   */
+  async getFee(amount: bigint): Promise<bigint> {
+    const result = await this.publicClient.readContract({
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "getFee",
+      args: [amount],
+    });
+
+    return result as bigint;
+  }
+
+  /**
+   * Get user volume
+   * 
+   * @param user - User address
+   */
+  async getUserVolume(user: Address): Promise<bigint> {
+    const result = await this.publicClient.readContract({
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "userVolume",
+      args: [user],
+    });
+
+    return result as bigint;
+  }
+
+  // ========== WRITE METHODS ==========
+
+  private getConnectedWallet(): WalletClient {
+    if (!this.walletClient?.account) {
+      throw new Error("Wallet not connected. Call connectWallet() first.");
+    }
+    return this.walletClient;
+  }
+
+  /**
+   * Create a new token with bonding curve
+   * 
+   * @param params - Token creation parameters
+   * @returns Transaction result with token address
+   */
+  async create(params: CreateTokenParams): Promise<TransactionResult & { tokenAddress?: Address }> {
+    const wallet = this.getConnectedWallet();
+
+    const hash = await wallet.writeContract({
+      chain: null,
+      account: null,
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "create",
+      args: [params.name, params.symbol, params.uri, params.creator],
+    });
+
+    const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+
+    // Parse CreateEvent to get token address
+    const logs = parseEventLogs({
+      abi: MANIA_FACTORY_ABI,
+      logs: receipt.logs,
+      eventName: "CreateEvent",
+    });
+
+    const tokenAddress = logs[0]?.args?.mint as Address | undefined;
+
+    return {
+      hash,
+      success: receipt.status === "success",
+      tokenAddress,
+    };
+  }
+
+  /**
+   * Create a new token and buy in a single transaction
+   * 
+   * @param params - Creation and buy parameters
+   * @returns Transaction result with token address
+   */
+  async createAndBuy(params: CreateAndBuyParams): Promise<TransactionResult & { tokenAddress?: Address }> {
+    const wallet = this.getConnectedWallet();
+
+    const hash = await wallet.writeContract({
+      chain: null,
+      account: null,
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "createAndBuy",
+      args: [params.name, params.symbol, params.uri, params.creator, params.minTokensOut],
+      value: params.buyAmountEth,
+    });
+
+    const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+
+    // Parse CreateEvent to get token address
+    const logs = parseEventLogs({
+      abi: MANIA_FACTORY_ABI,
+      logs: receipt.logs,
+      eventName: "CreateEvent",
+    });
+
+    const tokenAddress = logs[0]?.args?.mint as Address | undefined;
+
+    return {
+      hash,
+      success: receipt.status === "success",
+      tokenAddress,
+    };
+  }
+
+  /**
+   * Buy tokens from bonding curve
+   * 
+   * @param params - Buy parameters
+   * @returns Transaction result
+   */
+  async buy(params: BuyParams): Promise<TransactionResult> {
+    const wallet = this.getConnectedWallet();
+
+    const recipient = params.recipient ?? wallet.account!.address;
+
+    const hash = await wallet.writeContract({
+      chain: null,
+      account: null,
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "buy",
+      args: [params.token, params.minTokensOut, recipient],
+      value: params.amountEth,
+    });
+
+    const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+
+    return {
+      hash,
+      success: receipt.status === "success",
+    };
+  }
+
+  /**
+   * Buy tokens with automatic slippage calculation
+   * 
+   * @param token - Token address
+   * @param ethAmount - ETH amount to spend
+   * @param slippageBps - Slippage tolerance in basis points (default: 100 = 1%)
+   */
+  async buyWithSlippage(
+    token: Address,
+    ethAmount: bigint,
+    slippageBps: number = DEFAULT_SLIPPAGE_BPS
+  ): Promise<TransactionResult> {
+    const curve = await this.getBondingCurveInstance(token);
+    const minTokensOut = curve.calculateMinTokensOut(ethAmount, slippageBps);
+
+    return this.buy({
+      token,
+      amountEth: ethAmount,
+      minTokensOut,
+    });
+  }
+
+  /**
+   * Sell tokens to bonding curve
+   * 
+   * @param params - Sell parameters
+   * @returns Transaction result
+   */
+  async sell(params: SellParams): Promise<TransactionResult> {
+    const wallet = this.getConnectedWallet();
+
+    const hash = await wallet.writeContract({
+      chain: null,
+      account: null,
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "sell",
+      args: [params.token, params.amountTokens, params.minEthOut],
+    });
+
+    const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+
+    return {
+      hash,
+      success: receipt.status === "success",
+    };
+  }
+
+  /**
+   * Sell tokens with automatic slippage calculation
+   * 
+   * @param token - Token address
+   * @param tokenAmount - Token amount to sell
+   * @param slippageBps - Slippage tolerance in basis points (default: 100 = 1%)
+   */
+  async sellWithSlippage(
+    token: Address,
+    tokenAmount: bigint,
+    slippageBps: number = DEFAULT_SLIPPAGE_BPS
+  ): Promise<TransactionResult> {
+    const curve = await this.getBondingCurveInstance(token);
+    const minEthOut = curve.calculateMinEthOut(tokenAmount, slippageBps);
+
+    return this.sell({
+      token,
+      amountTokens: tokenAmount,
+      minEthOut,
+    });
+  }
+
+  /**
+   * Migrate liquidity to Uniswap V3
+   * 
+   * @param params - Migration parameters
+   * @returns Transaction result with pool address
+   */
+  async migrate(params: MigrateParams): Promise<TransactionResult & { poolAddress?: Address }> {
+    const wallet = this.getConnectedWallet();
+
+    const globalState = await this.getGlobalState();
+
+    const hash = await wallet.writeContract({
+      chain: null,
+      account: null,
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      functionName: "migrate",
+      args: [params.token],
+      value: globalState.poolMigrationFee,
+    });
+
+    const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+
+    // Parse migration event to get pool address
+    const logs = parseEventLogs({
+      abi: MANIA_FACTORY_ABI,
+      logs: receipt.logs,
+      eventName: "CompleteManiaAmmMigrationEvent",
+    });
+
+    const poolAddress = logs[0]?.args?.pool as Address | undefined;
+
+    return {
+      hash,
+      success: receipt.status === "success",
+      poolAddress,
+    };
+  }
+
+  // ========== EVENT WATCHING ==========
+
+  /**
+   * Watch for new token creation events
+   * 
+   * @param callback - Callback function for each event
+   * @returns Unwatch function
+   */
+  watchCreateEvents(callback: (event: CreateEvent) => void): () => void {
+    return this.publicClient.watchContractEvent({
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      eventName: "CreateEvent",
+      onLogs: (logs) => {
+        for (const log of logs) {
+          const args = log.args as unknown as CreateEvent;
+          callback(args);
+        }
+      },
+    });
+  }
+
+  /**
+   * Watch for trade events on a specific token
+   * 
+   * @param token - Token address (optional, watches all if not provided)
+   * @param callback - Callback function for each event
+   * @returns Unwatch function
+   */
+  watchTradeEvents(token: Address | undefined, callback: (event: TradeEvent) => void): () => void {
+    return this.publicClient.watchContractEvent({
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      eventName: "TradeEvent",
+      args: token ? { mint: token } : undefined,
+      onLogs: (logs) => {
+        for (const log of logs) {
+          const args = log.args as unknown as TradeEvent;
+          callback(args);
+        }
+      },
+    });
+  }
+
+  /**
+   * Watch for bonding curve completion events
+   * 
+   * @param callback - Callback function for each event
+   * @returns Unwatch function
+   */
+  watchCompleteEvents(callback: (event: CompleteEvent) => void): () => void {
+    return this.publicClient.watchContractEvent({
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      eventName: "CompleteEvent",
+      onLogs: (logs) => {
+        for (const log of logs) {
+          const args = log.args as unknown as CompleteEvent;
+          callback(args);
+        }
+      },
+    });
+  }
+
+  /**
+   * Watch for migration events
+   * 
+   * @param callback - Callback function for each event
+   * @returns Unwatch function
+   */
+  watchMigrationEvents(callback: (event: MigrationEvent) => void): () => void {
+    return this.publicClient.watchContractEvent({
+      address: this.factoryAddress,
+      abi: MANIA_FACTORY_ABI,
+      eventName: "CompleteManiaAmmMigrationEvent",
+      onLogs: (logs) => {
+        for (const log of logs) {
+          const args = log.args as unknown as MigrationEvent;
+          callback(args);
+        }
+      },
+    });
+  }
+
+  // ========== UTILITY METHODS ==========
+
+  /**
+   * Check if a token's bonding curve is complete
+   * 
+   * @param token - Token address
+   */
+  async isComplete(token: Address): Promise<boolean> {
+    const curve = await this.getBondingCurve(token);
+    return curve.complete;
+  }
+
+  /**
+   * Check if a token has been migrated
+   * 
+   * @param token - Token address
+   */
+  async isMigrated(token: Address): Promise<boolean> {
+    const curve = await this.getBondingCurve(token);
+    return (
+      curve.realEthReserves === 0n &&
+      curve.virtualEthReserves === 0n &&
+      curve.realTokenReserves === 0n &&
+      curve.virtualTokenReserves === 0n
+    );
+  }
+
+  /**
+   * Get the factory contract address
+   */
+  getFactoryAddress(): Address {
+    return this.factoryAddress;
+  }
+
+  /**
+   * Get the public client
+   */
+  getPublicClient(): PublicClient {
+    return this.publicClient;
+  }
+
+  /**
+   * Get the wallet client
+   */
+  getWalletClient(): WalletClient | null {
+    return this.walletClient;
+  }
+}