@forgekit-labs/launchpad 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeKit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @forgekit-labs/launchpad
+
+Create Raydium CPMM liquidity pools in one call. Validation, idempotency, and fee config included.
+
+## Install
+
+```bash
+npm install @forgekit-labs/launchpad
+```
+
+## Usage
+
+```js
+import { launch } from '@forgekit-labs/launchpad';
+
+const { poolId, lpMint, signature } = await launch('my-pool')
+  .mint('J1rNqz1...')
+  .decimals(6)
+  .tokens(500_000_000)
+  .seed(0.65)
+  .feeTier(1)
+  .wallet(keypair.secretKey)
+  .rpc('https://api.mainnet-beta.solana.com')
+  .send();
+```
+
+Mainnet and devnet are auto-detected from the RPC URL. Program IDs and fee configs switch automatically.
+
+`seed()` enforces the 0.65 SOL minimum: 0.15 SOL is consumed by Raydium as the pool creation fee, leaving 0.50 SOL as the minimum pool liquidity. Anything below this is rejected by Raydium on-chain with no useful error message, so it is caught synchronously before the network call.
+
+## Idempotency
+
+The Raydium pool PDA is deterministic. If a pool for this token already exists, `.send()` throws `ForgePoolExistsError` with the existing `poolId` attached:
+
+```js
+import { launch, ForgePoolExistsError } from '@forgekit-labs/launchpad';
+
+try {
+  await launch('my-pool').mint(mint).decimals(6).tokens(500_000_000).seed(0.65).wallet(secretKey).send();
+} catch (err) {
+  if (err instanceof ForgePoolExistsError) {
+    console.log('Pool already exists:', err.poolId);
+  }
+}
+```
+
+## Error Handling
+
+```js
+import { launch, ForgeTxError, ForgeRpcError } from '@forgekit-labs/launchpad';
+
+try {
+  await launch('my-pool')./* ... */.send();
+} catch (err) {
+  if (err instanceof ForgeTxError) {
+    console.error(err.message, err.cause);
+  }
+  if (err.retry) {
+    // safe to retry
+  }
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@forgekit-labs/launchpad",
+  "version": "0.1.0",
+  "description": "Create Raydium CPMM liquidity pools in one call. Validation, idempotency, and fee config included.",
+  "author": "Res <support@crxcible.io> (https://github.com/solDEv0)",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solDEv0/forgekit.git",
+    "directory": "packages/launchpad"
+  },
+  "homepage": "https://github.com/solDEv0/forgekit/tree/main/packages/launchpad#readme",
+  "bugs": "https://github.com/solDEv0/forgekit/issues",
+  "keywords": [
+    "solana",
+    "raydium",
+    "cpmm",
+    "launchpad",
+    "liquidity",
+    "pool"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@forgekit-labs/errors": "^0.1.0",
+    "@solana/web3.js": "^1.98.0",
+    "@solana/spl-token": "^0.4.9",
+    "@raydium-io/raydium-sdk-v2": "0.2.44-alpha",
+    "bn.js": "^5.2.1"
+  }
+}

package/src/fees.js

@@ -0,0 +1,62 @@
+// Raydium CPMM fee config accounts. Stable on-chain addresses.
+// Hardcoded to avoid an API round-trip on every launch and remove
+// an external dependency from the critical path.
+//
+// tradeFeeRate denominator: 1,000,000
+//   10_000 = 1%
+//   20_000 = 2%
+//
+// createPoolFee: 150_000_000 lamports = 0.15 SOL (paid to Raydium at creation)
+//
+// Devnet has no 2% config. Both tiers fall back to 1% (index 3).
+
+export const CPMM_FEE_CONFIGS = {
+  mainnet: {
+    1: {
+      id:              'G95xxie3XbkCqtE39GgQ9Ggc7xBC8Uceve7HFDEFApkc',
+      index:           1,
+      protocolFeeRate: 120_000,
+      tradeFeeRate:    10_000,
+      fundFeeRate:     40_000,
+      createPoolFee:   '150000000',
+      creatorFeeRate:  500,
+    },
+    2: {
+      id:              '2fGXL8uhqxJ4tpgtosHZXT4zcQap6j62z3bMDxdkMvy5',
+      index:           2,
+      protocolFeeRate: 120_000,
+      tradeFeeRate:    20_000,
+      fundFeeRate:     40_000,
+      createPoolFee:   '150000000',
+      creatorFeeRate:  500,
+    },
+  },
+  devnet: {
+    1: {
+      id:              'EsTevfacYXpuho5VBuzBjDZi8dtWidGnXoSYAr8krTvz',
+      index:           3,
+      protocolFeeRate: 120_000,
+      tradeFeeRate:    10_000,
+      fundFeeRate:     40_000,
+      createPoolFee:   '150000000',
+      creatorFeeRate:  2_500,
+    },
+    2: {
+      id:              'EsTevfacYXpuho5VBuzBjDZi8dtWidGnXoSYAr8krTvz',
+      index:           3,
+      protocolFeeRate: 120_000,
+      tradeFeeRate:    10_000,
+      fundFeeRate:     40_000,
+      createPoolFee:   '150000000',
+      creatorFeeRate:  2_500,
+    },
+  },
+};
+
+export const VALID_FEE_TIERS = new Set([1, 2]);
+
+// 0.15 SOL creation fee + 0.50 SOL minimum pool liquidity
+export const MIN_SEED_SOL    = 0.65;
+export const MIN_SEED_LAMPORTS = BigInt(650_000_000);
+
+export const WSOL_MINT = 'So11111111111111111111111111111111111111112';

package/src/index.js

@@ -0,0 +1,9 @@
+export { launch } from './launch.js';
+export { CPMM_FEE_CONFIGS } from './fees.js';
+export {
+  ForgeError,
+  ForgeValidationError,
+  ForgeTxError,
+  ForgeRpcError,
+  ForgePoolExistsError,
+} from '@forgekit-labs/errors';

package/src/launch.js

@@ -0,0 +1,283 @@
+import { Connection, Keypair, PublicKey } from '@solana/web3.js';
+import {
+  Raydium,
+  TxVersion,
+  CREATE_CPMM_POOL_PROGRAM,
+  CREATE_CPMM_POOL_FEE_ACC,
+  DEVNET_PROGRAM_ID,
+  DEV_API_URLS,
+  API_URLS,
+} from '@raydium-io/raydium-sdk-v2';
+import { TOKEN_PROGRAM_ID } from '@solana/spl-token';
+import BN from 'bn.js';
+import {
+  CPMM_FEE_CONFIGS,
+  VALID_FEE_TIERS,
+  MIN_SEED_SOL,
+  WSOL_MINT,
+} from './fees.js';
+import {
+  ForgeValidationError,
+  ForgeTxError,
+  ForgeRpcError,
+  ForgePoolExistsError,
+} from '@forgekit-labs/errors';
+
+const LAMPORTS_PER_SOL = 1_000_000_000n;
+
+class LaunchBuilder {
+  #name;
+  #mintAddress  = null;
+  #mintDecimals = null;
+  #tokenAmount  = null;
+  #seedSol      = null;
+  #feeTier      = 1;
+  #secretKey    = null;
+  #rpcUrl       = 'https://api.mainnet-beta.solana.com';
+
+  constructor(name) {
+    if (typeof name !== 'string' || !name.trim()) {
+      throw new ForgeValidationError(
+        'launch() requires a name string.',
+        'Pass a unique identifier, e.g. launch("my-pool").',
+      );
+    }
+    this.#name = name;
+  }
+
+  // Token mint address to pair with SOL
+  mint(address) {
+    if (typeof address !== 'string') {
+      throw new ForgeValidationError(
+        'mint() requires a string address.',
+        'Pass the token mint address as a base-58 Solana public key.',
+      );
+    }
+    try { new PublicKey(address); } catch {
+      throw new ForgeValidationError(
+        `mint() received an invalid address: "${address}"`,
+        'The mint address must be a valid base-58 Solana public key.',
+      );
+    }
+    this.#mintAddress = address;
+    return this;
+  }
+
+  // Token decimals, required to calculate raw amounts correctly
+  decimals(d) {
+    if (typeof d !== 'number' || d < 0 || d > 9 || !Number.isInteger(d)) {
+      throw new ForgeValidationError(
+        'decimals() requires an integer between 0 and 9.',
+      );
+    }
+    this.#mintDecimals = d;
+    return this;
+  }
+
+  // Number of tokens (in human units) to seed into the pool
+  tokens(amount) {
+    if (typeof amount !== 'number' || amount <= 0 || !Number.isFinite(amount)) {
+      throw new ForgeValidationError(
+        'tokens() requires a positive number.',
+        'e.g. .tokens(500_000_000) to seed 500M tokens into the pool.',
+      );
+    }
+    this.#tokenAmount = amount;
+    return this;
+  }
+
+  // SOL to seed the pool. Minimum 0.65 (0.15 creation fee + 0.50 liquidity).
+  seed(sol) {
+    if (typeof sol !== 'number' || !Number.isFinite(sol)) {
+      throw new ForgeValidationError('seed() requires a number.');
+    }
+    if (sol < MIN_SEED_SOL) {
+      throw new ForgeValidationError(
+        `seed() received ${sol} SOL. Below the minimum of ${MIN_SEED_SOL} SOL.`,
+        `Raydium CPMM requires at least ${MIN_SEED_SOL} SOL: 0.15 SOL is consumed as ` +
+        `the pool creation fee, leaving 0.50 SOL as the minimum pool liquidity. ` +
+        `Anything below this will be rejected on-chain.`,
+      );
+    }
+    this.#seedSol = sol;
+    return this;
+  }
+
+  // Swap fee tier: 1 (1%) or 2 (2%). Devnet only supports 1%.
+  feeTier(pct) {
+    if (!VALID_FEE_TIERS.has(pct)) {
+      throw new ForgeValidationError(
+        `feeTier() received ${pct}. Only 1 and 2 are valid Raydium CPMM fee tiers.`,
+        'Use .feeTier(1) for 1% swap fee or .feeTier(2) for 2% swap fee.',
+      );
+    }
+    this.#feeTier = pct;
+    return this;
+  }
+
+  wallet(secretKey) {
+    if (!(secretKey instanceof Uint8Array)) {
+      throw new ForgeValidationError(
+        'wallet() expects a Uint8Array (your keypair.secretKey).',
+        'e.g. .wallet(keypair.secretKey)',
+      );
+    }
+    this.#secretKey = secretKey;
+    return this;
+  }
+
+  rpc(url) {
+    if (typeof url !== 'string' || (!url.startsWith('http://') && !url.startsWith('https://'))) {
+      throw new ForgeValidationError(
+        'rpc() requires a valid HTTP or HTTPS URL.',
+      );
+    }
+    this.#rpcUrl = url;
+    return this;
+  }
+
+  async send() {
+    if (!this.#mintAddress) {
+      throw new ForgeValidationError(
+        'No mint address provided.',
+        'Call .mint("your-token-mint-address") before .send().',
+      );
+    }
+    if (this.#mintDecimals === null) {
+      throw new ForgeValidationError(
+        'No decimals provided.',
+        'Call .decimals(6) before .send().',
+      );
+    }
+    if (this.#tokenAmount === null) {
+      throw new ForgeValidationError(
+        'No token amount provided.',
+        'Call .tokens(500_000_000) before .send().',
+      );
+    }
+    if (this.#seedSol === null) {
+      throw new ForgeValidationError(
+        'No SOL seed amount provided.',
+        `Call .seed(${MIN_SEED_SOL}) before .send().`,
+      );
+    }
+    if (!this.#secretKey) {
+      throw new ForgeValidationError(
+        'No wallet provided.',
+        'Call .wallet(keypair.secretKey) before .send().',
+      );
+    }
+
+    const isDevnet  = this.#rpcUrl.toLowerCase().includes('devnet');
+    const network   = isDevnet ? 'devnet' : 'mainnet';
+    const feeConfig = CPMM_FEE_CONFIGS[network][this.#feeTier];
+
+    const owner      = Keypair.fromSecretKey(Buffer.from(this.#secretKey));
+    const connection = new Connection(this.#rpcUrl, 'confirmed');
+
+    // Load Raydium SDK
+    let raydium;
+    try {
+      raydium = await Raydium.load({
+        connection,
+        owner,
+        cluster:             isDevnet ? 'devnet' : 'mainnet',
+        disableFeatureCheck: true,
+        disableLoadToken:    true,
+        blockhashCommitment: 'confirmed',
+        urlConfigs:          isDevnet ? DEV_API_URLS : API_URLS,
+      });
+      await raydium.account.fetchWalletTokenAccounts();
+    } catch (err) {
+      throw new ForgeRpcError(
+        `Failed to initialise Raydium SDK: ${err?.message ?? String(err)}`,
+        err,
+      );
+    }
+
+    const programIds = isDevnet
+      ? {
+          programId:      new PublicKey(DEVNET_PROGRAM_ID.CREATE_CPMM_POOL_PROGRAM),
+          poolFeeAccount: new PublicKey(DEVNET_PROGRAM_ID.CREATE_CPMM_POOL_FEE_ACC),
+        }
+      : {
+          programId:      CREATE_CPMM_POOL_PROGRAM,
+          poolFeeAccount: CREATE_CPMM_POOL_FEE_ACC,
+        };
+
+    const rawTokenAmount = BigInt(Math.round(this.#tokenAmount * (10 ** this.#mintDecimals)));
+    const rawSolLamports = BigInt(Math.round(this.#seedSol * Number(LAMPORTS_PER_SOL)));
+
+    const mintA = {
+      address:   this.#mintAddress,
+      decimals:  this.#mintDecimals,
+      programId: TOKEN_PROGRAM_ID.toBase58(),
+    };
+    const mintB = {
+      address:   WSOL_MINT,
+      decimals:  9,
+      programId: TOKEN_PROGRAM_ID.toBase58(),
+    };
+
+    // Build the pool creation transaction
+    let txData;
+    try {
+      txData = await raydium.cpmm.createPool({
+        programId:           programIds.programId,
+        poolFeeAccount:      programIds.poolFeeAccount,
+        mintA,
+        mintB,
+        mintAAmount:         new BN(rawTokenAmount.toString()),
+        mintBAmount:         new BN(rawSolLamports.toString()),
+        startTime:           new BN(0),
+        feeConfig,
+        associatedOnly:      false,
+        checkCreateATAOwner: false,
+        ownerInfo: { useSOLBalance: true },
+        txVersion:           TxVersion.V0,
+      });
+    } catch (err) {
+      throw new ForgeTxError(
+        `Failed to build pool transaction: ${err?.message ?? String(err)}`,
+        err,
+      );
+    }
+
+    const { execute, extInfo } = txData;
+    const poolId = extInfo.address.poolId.toBase58();
+    const lpMint = extInfo.address.lpMint.toBase58();
+
+    // Idempotency. Pool PDA is deterministic; if it exists we surface it clearly.
+    let existingPool;
+    try {
+      existingPool = await connection.getAccountInfo(extInfo.address.poolId);
+    } catch (err) {
+      throw new ForgeRpcError(
+        `Failed to check for existing pool: ${err?.message ?? String(err)}`,
+        err,
+      );
+    }
+
+    if (existingPool !== null) {
+      throw new ForgePoolExistsError(poolId);
+    }
+
+    // Submit
+    let txId;
+    try {
+      const result = await execute({ sendAndConfirm: true });
+      txId = result.txId;
+    } catch (err) {
+      throw new ForgeTxError(
+        `Pool creation transaction failed: ${err?.message ?? String(err)}`,
+        err,
+      );
+    }
+
+    return { poolId, lpMint, signature: txId };
+  }
+}
+
+export function launch(name) {
+  return new LaunchBuilder(name);
+}