@forgedevv/core 0.1.0 → 0.3.0

package/dist/pool.d.ts

@@ -33,12 +33,28 @@
  *
  * `buildUserCoinLaunchTx` is the same launch for a coin created by a user on the client's
  * launchpad config: the user is pool creator, rent payer, fee payer and buyer, the mint is the
- * only other signer.
+ * only other signer. Its first buy pays the FORGE platform fee (0.3%, rounded up) like any swap
+ * built by core: one SOL transfer to `FORGE_PLATFORM_FEE_WALLET`, the last instruction.
+ *
+ * Both builders compare the on-chain config with what core builds for it, field by field
+ * (`onchainConfigMismatches` in config.ts), before building anything.
+ *
+ * Priority fee (`priority` setting, priority-fee.ts): the price is read from the recent fees of
+ * the launch's writable accounts and bounded by the setting. The compute budget instructions come
+ * right after the nonce advance: `setComputeUnitLimit` then `setComputeUnitPrice`. The launchpad
+ * coin launch is tight (`LAUNCH_METADATA_BUDGET_BYTES`): when both do not fit in 1,232 bytes, the
+ * price goes alone (4 bytes more than the limit it replaces; the fee is then bounded for
+ * `MAX_TRANSACTION_COMPUTE_UNITS`, the most the runtime can apply without a limit), and when even
+ * that does not fit, the launch keeps its shape without a price (`priorityFeePlacement`
+ * `omitted_for_size`): the metadata budget accepted at `/v1/configs` never shrinks. That launch
+ * uses a durable nonce, so it stays valid until it lands. The user coin launch always fits both.
  */
 import { type PoolConfig, type SwapQuoteConfig } from '@meteora-ag/dynamic-bonding-curve-sdk';
 import { PublicKey, Transaction, type Connection } from '@solana/web3.js';
-import type { OwnerTransactionSummary } from '@forge/shared';
-import type { AddressEnv } from './addresses.js';
+import type { LaunchpadSpec, OwnerTransactionSummary } from '@forge/shared';
+import { type AddressEnv } from './addresses.js';
+import { type OnchainConfigExpectation } from './config.js';
+import { type PriorityFeeQuote, type PriorityFeeSetting } from './priority-fee.js';
 export { LAUNCH_METADATA_BUDGET_BYTES, LaunchCoinError, MAX_FIRST_BUY_LAMPORTS, METADATA_LIMITS, assertFirstBuyLamports, assertLaunchMetadata, assertSpecLaunchable, launchMetadataBytes, type LaunchCoinErrorCode, } from './launch-metadata.js';
 /**
  * Compute unit limit of the launch transaction: 190,840 CU measured on devnet with the durable
@@ -96,6 +112,12 @@ export interface BuildLaunchCoinTxParams {
     slippageBps?: number;
     /** Durable nonce: the transaction then stays valid until the nonce advances. */
     durableNonce?: DurableNonceParam;
+    /**
+     * The launchpad spec the coin config was built from. When given, the on-chain config must be
+     * exactly `buildLaunchpadCoinConfig(spec)` (`assertLaunchCoinConfig`); without it, its trading
+     * fee and anti-sniper flag are only bounded. Recommended.
+     */
+    spec?: LaunchpadSpec;
     /**
      * Who pays the pool, mint, metadata and vault accounts and the pool creation fee (default
      * `owner`; `creator` only on a config whose pool creation fee is 0).
@@ -115,7 +137,19 @@ export interface BuildLaunchCoinTxParams {
     computeUnitLimit?: number;
     /** Priority fee, micro-lamports per compute unit (default 0). */
     computeUnitPriceMicroLamports?: number;
+    /**
+     * Priority fee read from the cluster and bounded by this setting (`{}` = the defaults, at most
+     * 0.0005 SOL), see the top of this file for its placement. Not with
+     * `computeUnitPriceMicroLamports`.
+     */
+    priority?: PriorityFeeSetting;
 }
+/**
+ * Where the priority fee went: with the unit limit (`limit_and_price`, also the shape without a
+ * priority fee), alone because both did not fit (`price_only`), or left out because even the
+ * price alone did not fit (`omitted_for_size`).
+ */
+export type PriorityFeePlacement = 'limit_and_price' | 'price_only' | 'omitted_for_size';
 /** Lamport amounts, as bigint. */
 export interface LaunchCoinCosts {
     /** SOL swapped into the pool by the first buy. */
@@ -137,6 +171,11 @@ export interface LaunchCoinCosts {
     ownerTemporaryLamports: bigint;
     /** Signature fees + priority fee (paid by the owner, the fee payer). */
     networkFeeLamports: bigint;
+    /**
+     * FORGE platform fee on the first buy (`PLATFORM_FEE_BPS` of it, rounded up), paid by the owner
+     * to `FORGE_PLATFORM_FEE_WALLET`. Only set by `buildUserCoinLaunchTx`.
+     */
+    platformFeeLamports?: bigint;
     /** `cluster` = `getFeeForMessage`; `estimate` = signatures x 5000 + priority fee. */
     networkFeeSource: 'cluster' | 'estimate';
     /** Everything the owner's balance decreases by. */
@@ -179,8 +218,15 @@ export interface LaunchCoinSummary {
     recentBlockhash: string;
     /** Null with a durable nonce (it does not expire with block height). */
     lastValidBlockHeight: number | null;
+    /**
+     * Compute unit limit requested; the transaction sets it unless `priorityFeePlacement` is
+     * `price_only` (the runtime default then applies, bounded by `MAX_TRANSACTION_COMPUTE_UNITS`).
+     */
     computeUnitLimit: number;
     computeUnitPriceMicroLamports: number;
+    /** The priority fee (price, fee, cap; `fixed` without a `priority` setting). */
+    priorityFee: PriorityFeeQuote;
+    priorityFeePlacement: PriorityFeePlacement;
     /** Signers on the signer side (creator, mint, nonce authority if distinct), then the owner. */
     signerSideSigners: PublicKey[];
     ownerSigner: PublicKey;
@@ -193,13 +239,21 @@ export interface LaunchCoinTx {
 }
 /**
  * Checks that an on-chain config is the launchpad coin config of `owner` and that it is safe to
- * launch the coin on it: SOL quote, SPL token, fee claimer = owner, FORGE creator share, creator
- * locked liquidity, first swap at the minimum fee (otherwise the client's first buy would pay
- * the anti-sniper fee), fee scheduler base fee, DAMM v2 migration at exactly 10 SOL.
+ * launch the coin on it. Besides the essential checks (SOL quote, SPL token, first swap at the
+ * minimum fee, fee scheduler, DAMM v2 at exactly 10 SOL), EVERY field is compared with what core
+ * builds for a launchpad coin config (`onchainConfigMismatches`): fee claimer and leftover
+ * receiver = owner, FORGE creator share, the 75 / 25 permanently locked liquidity, no pool
+ * creation fee, immutable metadata, the exact fee schedule, no migration fee, no locked vesting,
+ * FORGE's supply and curve, timestamp activation.
+ *
+ * With `spec` (the spec the config was built from), the reference is exactly
+ * `buildLaunchpadCoinConfig(spec)`; without it, the trading fee and the anti-sniper flag are read
+ * from the config and only have to be values a FORGE spec can hold (linear schedule, whole fee of
+ * 50..200 bps). Pass the spec whenever it is known.
  *
  * @throws LaunchCoinError `CONFIG_MISMATCH` listing every mismatch.
  */
-export declare function assertLaunchCoinConfig(config: PoolConfig, owner: PublicKey): void;
+export declare function assertLaunchCoinConfig(config: PoolConfig, owner: PublicKey, spec?: LaunchpadSpec): void;
 /** The quote inputs of a pool config, for a pool that does not exist yet. */
 export declare function quoteConfigFromPoolConfig(config: PoolConfig): SwapQuoteConfig;
 /**
@@ -229,13 +283,34 @@ export interface BuildUserCoinLaunchTxParams {
     /** Slippage on the first buy (default 100 bps, at most 1000). */
     slippageBps?: number;
     /**
-     * Accepted for symmetry with `buildLaunchCoinTx`; not read: a user coin launch involves no
-     * FORGE address (no referral on the first buy, no platform fee on the creation).
+     * Environment to read `FORGE_PLATFORM_FEE_WALLET` from (defaults to `process.env`; a browser
+     * passes its public copy explicitly). Read only when a platform fee is charged.
      */
     env?: AddressEnv;
+    /**
+     * Charge the FORGE platform fee on the first buy (default `true`): `PLATFORM_FEE_BPS` (30 bps)
+     * of `firstBuyLamports`, rounded up to the lamport (`platformFeeLamports`), as ONE SystemProgram
+     * transfer from the wallet to `FORGE_PLATFORM_FEE_WALLET`, the last instruction. Nothing is
+     * added when there is no first buy. `false` only for tools that must reproduce a launch without
+     * it.
+     */
+    chargePlatformFee?: boolean;
+    /**
+     * What the on-chain launchpad config must be, compared field by field
+     * (`assertUserCoinConfig`): the owner wallet (fee claimer and leftover receiver), the pool
+     * creation fee, or the full spec. Without it, every fixed FORGE setting is still compared and
+     * the spec fields only have to be within the client bounds.
+     */
+    expectedConfig?: OnchainConfigExpectation;
     computeUnitLimit?: number;
     /** Priority fee, micro-lamports per compute unit (default 0). */
     computeUnitPriceMicroLamports?: number;
+    /**
+     * Priority fee read from the cluster and bounded by this setting (`{}` = the defaults, at most
+     * 0.0005 SOL): `setComputeUnitLimit` then `setComputeUnitPrice`, first. Not with
+     * `computeUnitPriceMicroLamports`.
+     */
+    priority?: PriorityFeeSetting;
 }
 export interface UserCoinLaunchSummary {
     config: PublicKey;
@@ -252,16 +327,24 @@ export interface UserCoinLaunchSummary {
     expectedTokensOut: bigint;
     minimumTokensOut: bigint;
     slippageBps: number;
+    /** FORGE platform fee transferred by the wallet (0 without a first buy or when not charged). */
+    platformFeeLamports: bigint;
+    /** Recipient of the platform fee transfer, or null when there is none. */
+    platformFeeWallet: PublicKey | null;
     /**
      * Same figures as `LaunchCoinCosts`, read the same way: the `owner*` fields are the wallet's
-     * (it pays everything, including the pool accounts and the pool creation fee);
-     * `creatorTotalLamports` is 0 because no separate creator wallet pays anything.
+     * (it pays everything, including the pool accounts, the pool creation fee and the platform
+     * fee); `creatorTotalLamports` is 0 because no separate creator wallet pays anything.
      */
     costs: LaunchCoinCosts;
     recentBlockhash: string;
     lastValidBlockHeight: number;
     computeUnitLimit: number;
     computeUnitPriceMicroLamports: number;
+    /** The priority fee (price, fee, cap; `fixed` without a `priority` setting). */
+    priorityFee: PriorityFeeQuote;
+    /** `limit_and_price`, or `omitted_for_size` if a priced launch would not fit (it always does). */
+    priorityFeePlacement: PriorityFeePlacement;
     /** Required signers in message order: the wallet (fee payer) then the mint. */
     signers: PublicKey[];
     txBytes: number;
@@ -272,20 +355,28 @@ export interface UserCoinLaunchTx {
     summary: UserCoinLaunchSummary;
 }
 /**
- * Checks that an on-chain config can launch a user coin with a first buy at the minimum fee: SOL
- * quote, SPL token program for both tokens, `enableFirstSwapWithMinFee`. Nothing about who owns
- * the config or the creator share: the template checks the config address itself.
+ * Checks that an on-chain config is a FORGE launchpad config a user coin can be launched on:
+ * the essential checks (SOL quote, SPL token program for both tokens, `enableFirstSwapWithMinFee`,
+ * fee scheduler, DAMM v2 at exactly 10 SOL), then EVERY field compared with what core builds for
+ * a launchpad config (`onchainConfigMismatches`): liquidity split following the creator share,
+ * immutable metadata, the exact fee schedule, no migration fee, no locked vesting, FORGE's supply
+ * and curve, timestamp activation. `expected` pins the owner wallet (fee claimer and leftover
+ * receiver), the pool creation fee, or the whole spec; without it the spec fields only have to be
+ * within the client bounds and the leftover receiver must be the fee claimer.
  *
  * @throws LaunchCoinError `CONFIG_MISMATCH` listing every mismatch.
  */
-export declare function assertUserCoinConfig(config: PoolConfig): void;
+export declare function assertUserCoinConfig(config: PoolConfig, expected?: OnchainConfigExpectation): void;
 /**
  * Builds the launch transaction of a coin created by a user on the client's launchpad config:
  * pool creation + the user's first buy at the minimum fee (no referral), with a compute unit limit
  * (and a priority fee when given) and a recent blockhash. The user is pool creator, rent payer,
- * fee payer and buyer; the mint is the only other signer. Rent is read from the cluster.
+ * fee payer and buyer; the mint is the only other signer. Rent is read from the cluster. With a
+ * first buy, the last instruction transfers the platform fee (`platformFeeLamports(firstBuy)`) to
+ * `FORGE_PLATFORM_FEE_WALLET` (see `chargePlatformFee`).
  *
- * @throws LaunchCoinError (typed `code`).
+ * @throws LaunchCoinError (typed `code`; `PLATFORM_FEE_WALLET_NOT_READY` when the fee wallet is
+ *   not rent-exempt), or ForgeAddressError when `FORGE_PLATFORM_FEE_WALLET` is missing.
  */
 export declare function buildUserCoinLaunchTx(params: BuildUserCoinLaunchTxParams): Promise<UserCoinLaunchTx>;
 /**