@forgedevv/core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,13 +3,96 @@
 All notable changes to `@forge/core`. Versions follow semantic versioning. Consumers (the
 launchpad template, the signer, the web app) pin an exact version, never a range.
 
-## 0.1.0 — unreleased
-
-First version meant for publication on npm as `@forgedevv/core` (with `@forgedevv/shared`), through
-`node scripts/publish-core.mjs --publish`. Not published yet.
+## 0.2.0 — unreleased
+
+Everything below was added after 0.1.0 was published. Publish `@forgedevv/shared` 0.2.0 with it.
+
+### Changed (security review)
+
+- **On-chain configs compared field by field.** New `onchainConfigMismatches(config, kind,
+  { spec?, owner?, poolCreationFeeLamports? })` (config.ts) compares a decoded config with the
+  parameters core builds for it: accounts, token, base fee (cliff, periods, period, reduction,
+  mode), dynamic fee, creator share, pool creation fee, first swap at the minimum fee, activation,
+  liquidity split and vesting, migration option / fee option / threshold, migration fee
+  percentages, migrated pool fee, locked vesting, token supply, start price and curve. Without a
+  spec, the spec fields are read from the config and must be values a FORGE spec can hold.
+  - `assertLaunchCoinConfig(config, owner, spec?)`: runs it (optional `spec`, recommended).
+    `BuildLaunchCoinTxParams.spec?` passes it. A coin config with a pool creation fee is now
+    `CONFIG_MISMATCH` (the current builder sets none).
+  - `assertUserCoinConfig(config, expected?)`: runs it against the launchpad config;
+    `BuildUserCoinLaunchTxParams.expectedConfig?` passes the expectation.
+- **validate.ts pins every value-moving field to FORGE's settings**: no migration fee
+  (`MIGRATION_FEE_NOT_ALLOWED`), no locked vesting (`LOCKED_VESTING_NOT_ALLOWED`), the fixed supply
+  of `FORGE_TOKEN_SETTINGS` (`TOKEN_SUPPLY_MISMATCH`), FORGE's curve and start price
+  (`CURVE_MISMATCH`, they decide the leftover), SPL token with 6 decimals, timestamp activation,
+  and the anti-sniper schedule exactly `ANTI_SNIPER_FEE_SCHEDULE` (a flat linear fee when
+  `spec.antiSniper` is off): an exponential schedule, another starting fee or one 300 s period at
+  99% are refused.
+- The fixed settings moved to `settings.ts` (re-exported by config.ts, unchanged values), with
+  `FORGE_TOKEN_SUPPLY_RAW`, `forgeFeeSchedulerParam`, `forgeBaseFee`, `forgeReferenceCurve`.
+  `curveParamsFor`, `creatorTradingFeePercentageFor` and `poolCreationFeeSolFor` accept just the
+  spec fields they read (`ConfigSpecFields`); a full `LaunchpadSpec` still fits.
+- **Platform fee on a user coin's first buy.** `buildUserCoinLaunchTx` adds ONE SystemProgram
+  transfer of `platformFeeLamports(firstBuyLamports)` (30 bps, rounded up) to
+  `FORGE_PLATFORM_FEE_WALLET` (read from `env`), as the last instruction; `chargePlatformFee:
+  false` turns it off. The wallet must be rent-exempt (`PLATFORM_FEE_WALLET_NOT_READY`). The
+  summary gains `platformFeeLamports` and `platformFeeWallet`; `LaunchCoinCosts.platformFeeLamports`
+  (optional) is set and counted in `ownerTotalLamports`.
+- **Swaps.** `MAX_SWAP_SLIPPAGE_BPS` is 2,500 (25%, was 50%). `buildBuyTx`, `buildSellTx`,
+  `quoteSwap`, `fetchSwapContext` and `fetchSwapPoolState` take an optional `allowedConfigs`: a
+  pool whose on-chain config is not listed is refused (`POOL_NOT_ALLOWED`) before its config is
+  read. The builders now require the platform fee wallet to be exactly `FORGE_PLATFORM_FEE_WALLET`
+  and a system account (`PLATFORM_FEE_WALLET_MISMATCH`), and, when the environment has
+  `FORGE_MULTISIG_VAULT`, the Meteora referral token account to be held by it
+  (`REFERRAL_ACCOUNT_INVALID`). `buildSwapTransaction(ctx, request, expected?)`,
+  `assertPlatformFeeWalletReady(..., expectedWallet?)`, `assertReferralAccountReady(...,
+  expectedOwner?)`, new `assertPoolConfigAllowed`, `readOptionalAddress` (addresses.ts);
+  `swapFeeAddresses` also returns `multisigVault`.
+- `checkPaymentTransaction` / `verifyPayment`: `transferLamports` on `amount_mismatch` when the transfer amount differs.
+- Jupiter referral fee claim (`jupiter-referral.ts`, mainnet-beta only): `buildJupiterReferralClaimTx`
+  reads the referral account, its project and the two collection accounts of a mint (classic
+  `referral_ata` PDA and the referral account's associated token account) and builds the
+  permissionless `claim` / `claim_v2` instructions to the referral account's partner (the FORGE
+  multisig vault, asserted with `expectedPartner`). Raw instructions from the referral program IDL
+  (no Anchor dependency), with the pure pieces exported (`decodeJupiterReferralAccount`,
+  `decodeJupiterProject`, `deriveJupiterReferralTokenAccount[V2]`, `buildJupiterReferralClaimIx`,
+  `buildJupiterCreateAdminTokenAccountIx`). Any cluster but mainnet-beta is refused
+  (`JupiterReferralError` `wrong_cluster`). The summary also carries the project's `admin` and
+  `projectAuthority`, so a caller can pin every account of the built claim.
+- Squads accounts of the buyback read in addresses.ts (PLANEXECUTE rule 7): `FORGE_SQUADS_MULTISIG`
+  and `FORGE_SQUADS_SPENDING_LIMIT` join `FORGE_ADDRESS_NAMES` as optional names;
+  `readSquadsAddresses(env)` returns them with `FORGE_SQUADS_VAULT_INDEX` (default 0) or `null`
+  when both are absent, and refuses half a configuration, an index without them, an index outside
+  0..255 or a spending limit equal to the multisig (`ForgeSquadsConfigError`). Deriving the vault
+  needs the Squads program id: the signer keeps that check.
+
+### Added (DAMM v2 position fee claims)
+
+- `position-claims.ts`: after a launchpad coin migrates, the FORGE creator wallet keeps a
+  permanently locked DAMM v2 position that earns the migrated pool's trading fees.
+  `buildCreatorPositionFeeClaimTx` builds the unsigned `claim_position_fee` of the creator's
+  position(s) to a receiver (`buildForgeCreatorPositionFeeClaimTx`: the multisig vault), creator
+  signing, optional fee payer: coin fees to the receiver's associated account, SOL fees to the
+  creator's temporary WSOL account closed to the receiver (fees plus rent as lamports). The
+  transaction never removes liquidity nor closes, locks or transfers the position or its NFT.
+  Summary, costs (`PositionClaimCosts`), skip reasons (`no_position`, `nothing_to_claim`,
+  `not_worthwhile`), `isPositionClaimWorthwhile`. Pure helpers: `migratedDammV2Pool` (the DAMM v2
+  pool of a migrated DBC pool, derived like the SDK migration), `positionPendingFees`,
+  `summarizePosition`, `sumPendingFees`; reads: `findCreatorDammV2Positions` (the creator's
+  positions, NFT ownership re-checked), `getDammV2PoolState`. Constants for policies:
+  `DAMM_V2_PROGRAM_ID`, `CLAIM_POSITION_FEE_DISCRIMINATOR`, `CLAIM_POSITION_FEE_ACCOUNTS`.
+  New `ClaimError` codes: `not_migrated`, `damm_pool_not_found`, `damm_pool_mismatch`,
+  `position_not_found`, `position_mismatch`, `position_not_owned`.
+- Dependency: `@meteora-ag/cp-amm-sdk` 1.5.1 (exact pin, like the DBC SDK).
+- Fixtures: `__fixtures__/cp-amm-devnet-accounts.json`, the devnet test 2 migration captured
+  read-only (`scripts/devnet-tests` `fixtures:cp-amm`).
+
+## 0.1.0 — 2026-10-14
+
+First version published on npm as `@forgedevv/core` (with `@forgedevv/shared`), through
+`node scripts/publish-core.mjs --publish`.
 
 - `listCoinsOfCreator` (creator pools through SDK `getPoolsByCreator`), `DBC_POOL_CREATOR_OFFSET`, `DBC_POOL_CONFIG_OFFSET`.
-- `checkPaymentTransaction` / `verifyPayment`: `transferLamports` on `amount_mismatch` when the transfer amount differs.
 
 ### Changed (wave 5 review)
 

package/README.md

@@ -1,9 +1,10 @@
 # @forgedevv/core
 
 The FORGE transaction core: it builds the Meteora Dynamic Bonding Curve configs, the launchpad coin
-launch, buys and sells with the FORGE platform fee and referral, creator fee claims, payment checks
-and the read helpers used by FORGE launchpad sites. Every function that builds a transaction
-returns it **unsigned**: the user signs in their wallet.
+launch, buys and sells with the FORGE platform fee and referral, creator fee claims (bonding curve
+share, and the DAMM v2 position fees of a migrated pool), payment checks and the read helpers used
+by FORGE launchpad sites. Every function that builds a transaction returns it **unsigned**: the
+user signs in their wallet.
 
 Inside the FORGE monorepo this package is `@forge/core`. It is published on the public npm registry
 as `@forgedevv/core` (with its contracts package `@forgedevv/shared`), and client projects install

package/dist/addresses.d.ts

@@ -16,10 +16,13 @@
  * Error messages list variable names only, never values.
  */
 import { PublicKey } from '@solana/web3.js';
-export declare const FORGE_ADDRESS_NAMES: readonly ["FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_JUPITER_REFERRAL_ACCOUNT", "FORGE_CASHBOX_WALLET", "FORGE_MINT"];
+export declare const FORGE_ADDRESS_NAMES: readonly ["FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_JUPITER_REFERRAL_ACCOUNT", "FORGE_CASHBOX_WALLET", "FORGE_MINT", "FORGE_SQUADS_MULTISIG", "FORGE_SQUADS_SPENDING_LIMIT"];
 export type ForgeAddressName = (typeof FORGE_ADDRESS_NAMES)[number];
-/** Addresses that may be absent. `FORGE_MINT` is absent before the $FORGE launch. */
-export declare const OPTIONAL_FORGE_ADDRESS_NAMES: readonly ["FORGE_MINT"];
+/**
+ * Addresses that may be absent. `FORGE_MINT` is absent before the $FORGE launch; the Squads
+ * accounts are absent while the buyback stays in simulation (see `readSquadsAddresses`).
+ */
+export declare const OPTIONAL_FORGE_ADDRESS_NAMES: readonly ["FORGE_MINT", "FORGE_SQUADS_MULTISIG", "FORGE_SQUADS_SPENDING_LIMIT"];
 export type OptionalForgeAddressName = (typeof OPTIONAL_FORGE_ADDRESS_NAMES)[number];
 /** Environment object to read from (defaults to `process.env`; injectable for tests). */
 export type AddressEnv = Readonly<Record<string, string | undefined>>;
@@ -41,6 +44,15 @@ export declare class ForgeAddressError extends Error {
  * @throws ForgeAddressError listing the missing and invalid names (never the values).
  */
 export declare function requireAddresses<N extends ForgeAddressName>(names: readonly N[], env?: AddressEnv): ForgeAddresses<N>;
+/**
+ * One FORGE address when it is set, `null` when it is absent or empty. A value that is set but is
+ * not a valid public key is refused, exactly as `requireAddresses` does. For checks that run
+ * wherever the address is known and are skipped elsewhere (e.g. the owner of the Meteora referral
+ * account, `FORGE_MULTISIG_VAULT`, in a browser that was not given it).
+ *
+ * @throws ForgeAddressError (invalid value; names only).
+ */
+export declare function readOptionalAddress(name: ForgeAddressName, env?: AddressEnv): PublicKey | null;
 /** Squads multisig vault: receives the creator fees, the Meteora referral and the cashbox sweeps. */
 export declare function getMultisigVault(env?: AddressEnv): PublicKey;
 /** Meteora referral token account (WSOL, held by the multisig), passed as `referralTokenAccount`. */
@@ -53,3 +65,38 @@ export declare function getJupiterReferralAccount(env?: AddressEnv): PublicKey;
 export declare function getCashboxWallet(env?: AddressEnv): PublicKey;
 /** $FORGE mint, or `null` before the $FORGE launch (token-gating off, buyback simulated). */
 export declare function getForgeMint(env?: AddressEnv): PublicKey | null;
+/** Squads v4 accounts the buyback withdraws through, read from the environment. */
+export interface SquadsAddresses {
+    /** FORGE_SQUADS_MULTISIG: the multisig account. */
+    multisig: PublicKey;
+    /** FORGE_SQUADS_SPENDING_LIMIT: the spending limit account of the buyback wallet. */
+    spendingLimit: PublicKey;
+    /** FORGE_SQUADS_VAULT_INDEX (default 0): the vault index of the treasury vault. */
+    vaultIndex: number;
+}
+export type SquadsAddressProblem = 
+/** One of the two addresses without the other. */
+'incomplete'
+/** FORGE_SQUADS_VAULT_INDEX other than the default 0 without the addresses. */
+ | 'index_without_multisig'
+/** FORGE_SQUADS_VAULT_INDEX is not an integer between 0 and 255. */
+ | 'invalid_index'
+/** The spending limit account is the multisig account. */
+ | 'not_distinct';
+/** Thrown by `readSquadsAddresses` on a rule the names alone cannot express. Names only. */
+export declare class ForgeSquadsConfigError extends Error {
+    readonly problem: SquadsAddressProblem;
+    constructor(problem: SquadsAddressProblem, message: string);
+}
+/**
+ * FORGE_SQUADS_MULTISIG, FORGE_SQUADS_SPENDING_LIMIT and FORGE_SQUADS_VAULT_INDEX. Returns `null`
+ * when both addresses are absent (no withdrawer: the buyback stays in simulation). Rules: the
+ * two addresses are set together or not at all; an index other than the default `0` needs them
+ * (a lone `0` is the default spelled out, not a configuration); the index is an integer between
+ * 0 and 255 (default 0); the spending limit is a distinct account. Deriving the vault from the
+ * multisig and the index, and comparing it with FORGE_MULTISIG_VAULT, needs the Squads program
+ * id (pinned SDK): the caller (the signer) does it.
+ *
+ * @throws ForgeAddressError (invalid address, names only), ForgeSquadsConfigError (other rules).
+ */
+export declare function readSquadsAddresses(env?: AddressEnv): SquadsAddresses | null;

package/dist/addresses.js

@@ -23,10 +23,17 @@ export const FORGE_ADDRESS_NAMES = [
     'FORGE_JUPITER_REFERRAL_ACCOUNT',
     'FORGE_CASHBOX_WALLET',
     'FORGE_MINT',
+    'FORGE_SQUADS_MULTISIG',
+    'FORGE_SQUADS_SPENDING_LIMIT',
 ];
-/** Addresses that may be absent. `FORGE_MINT` is absent before the $FORGE launch. */
+/**
+ * Addresses that may be absent. `FORGE_MINT` is absent before the $FORGE launch; the Squads
+ * accounts are absent while the buyback stays in simulation (see `readSquadsAddresses`).
+ */
 export const OPTIONAL_FORGE_ADDRESS_NAMES = [
     'FORGE_MINT',
+    'FORGE_SQUADS_MULTISIG',
+    'FORGE_SQUADS_SPENDING_LIMIT',
 ];
 /** Thrown when required addresses are missing or invalid. Holds names only, never values. */
 export class ForgeAddressError extends Error {
@@ -101,6 +108,20 @@ export function requireAddresses(names, env = defaultEnv()) {
         throw new ForgeAddressError(missing, invalid);
     return result;
 }
+/**
+ * One FORGE address when it is set, `null` when it is absent or empty. A value that is set but is
+ * not a valid public key is refused, exactly as `requireAddresses` does. For checks that run
+ * wherever the address is known and are skipped elsewhere (e.g. the owner of the Meteora referral
+ * account, `FORGE_MULTISIG_VAULT`, in a browser that was not given it).
+ *
+ * @throws ForgeAddressError (invalid value; names only).
+ */
+export function readOptionalAddress(name, env = defaultEnv()) {
+    const value = env[name];
+    if (value === undefined || value === '')
+        return null;
+    return requireAddresses([name], env)[name];
+}
 /** Squads multisig vault: receives the creator fees, the Meteora referral and the cashbox sweeps. */
 export function getMultisigVault(env) {
     return requireAddresses(['FORGE_MULTISIG_VAULT'], env).FORGE_MULTISIG_VAULT;
@@ -125,3 +146,51 @@ export function getCashboxWallet(env) {
 export function getForgeMint(env) {
     return requireAddresses(['FORGE_MINT'], env).FORGE_MINT;
 }
+/** Thrown by `readSquadsAddresses` on a rule the names alone cannot express. Names only. */
+export class ForgeSquadsConfigError extends Error {
+    problem;
+    constructor(problem, message) {
+        super(message);
+        this.name = 'ForgeSquadsConfigError';
+        this.problem = problem;
+    }
+}
+const VAULT_INDEX_RE = /^(0|[1-9][0-9]?|1[0-9]{2}|2[0-4][0-9]|25[0-5])$/;
+/**
+ * FORGE_SQUADS_MULTISIG, FORGE_SQUADS_SPENDING_LIMIT and FORGE_SQUADS_VAULT_INDEX. Returns `null`
+ * when both addresses are absent (no withdrawer: the buyback stays in simulation). Rules: the
+ * two addresses are set together or not at all; an index other than the default `0` needs them
+ * (a lone `0` is the default spelled out, not a configuration); the index is an integer between
+ * 0 and 255 (default 0); the spending limit is a distinct account. Deriving the vault from the
+ * multisig and the index, and comparing it with FORGE_MULTISIG_VAULT, needs the Squads program
+ * id (pinned SDK): the caller (the signer) does it.
+ *
+ * @throws ForgeAddressError (invalid address, names only), ForgeSquadsConfigError (other rules).
+ */
+export function readSquadsAddresses(env = defaultEnv()) {
+    const multisigRaw = env.FORGE_SQUADS_MULTISIG ?? '';
+    const limitRaw = env.FORGE_SQUADS_SPENDING_LIMIT ?? '';
+    const indexRaw = env.FORGE_SQUADS_VAULT_INDEX ?? '';
+    if (multisigRaw === '' && limitRaw === '') {
+        if (indexRaw !== '' && indexRaw !== '0') {
+            throw new ForgeSquadsConfigError('index_without_multisig', 'FORGE_SQUADS_VAULT_INDEX needs FORGE_SQUADS_MULTISIG');
+        }
+        return null;
+    }
+    if (multisigRaw === '' || limitRaw === '') {
+        throw new ForgeSquadsConfigError('incomplete', 'FORGE_SQUADS_MULTISIG and FORGE_SQUADS_SPENDING_LIMIT must be set together');
+    }
+    const multisig = readOptionalAddress('FORGE_SQUADS_MULTISIG', env);
+    const spendingLimit = readOptionalAddress('FORGE_SQUADS_SPENDING_LIMIT', env);
+    let vaultIndex = 0;
+    if (indexRaw !== '') {
+        if (!VAULT_INDEX_RE.test(indexRaw)) {
+            throw new ForgeSquadsConfigError('invalid_index', 'FORGE_SQUADS_VAULT_INDEX must be an integer between 0 and 255');
+        }
+        vaultIndex = Number(indexRaw);
+    }
+    if (spendingLimit.equals(multisig)) {
+        throw new ForgeSquadsConfigError('not_distinct', 'FORGE_SQUADS_SPENDING_LIMIT must be a distinct account');
+    }
+    return { multisig, spendingLimit, vaultIndex };
+}

package/dist/claims.d.ts

@@ -1,10 +1,10 @@
 import { PublicKey, Transaction, type Commitment, type Connection } from '@solana/web3.js';
 import { type AddressEnv } from './addresses.js';
-import { type RetryOptions, type TokenAmounts } from './reads.js';
+import { type DbcPoolState, type RetryOptions, type TokenAmounts } from './reads.js';
 /** Base fee per signature (lamports); claims set no priority fee. */
 export declare const CLAIM_LAMPORTS_PER_SIGNATURE = 5000n;
 export { PARTNER_POOL_CREATION_FEE_CLAIMED_BIT, partnerPoolCreationFeeShare } from './reads.js';
-export type ClaimErrorCode = 'not_pool_creator' | 'not_fee_claimer' | 'unsupported_quote_mint' | 'invalid_receiver' | 'receiver_mismatch' | 'receiver_not_rent_exempt' | 'claimer_wsol_not_empty' | 'unexpected_sdk_instructions';
+export type ClaimErrorCode = 'not_pool_creator' | 'not_fee_claimer' | 'unsupported_quote_mint' | 'invalid_receiver' | 'receiver_mismatch' | 'receiver_not_rent_exempt' | 'claimer_wsol_not_empty' | 'unexpected_sdk_instructions' | 'not_migrated' | 'damm_pool_not_found' | 'damm_pool_mismatch' | 'position_not_found' | 'position_mismatch' | 'position_not_owned';
 export declare class ClaimError extends Error {
     readonly code: ClaimErrorCode;
     constructor(code: ClaimErrorCode, message: string);
@@ -43,6 +43,12 @@ export interface ClaimSummary {
      */
     receiverQuoteLamports: bigint;
     quoteIsExact: boolean;
+    /**
+     * WSOL the claimer's temporary account already held when the transaction was built and that
+     * the close hands to the receiver (counted in `receiverQuoteLamports`). Zero when the account
+     * is empty or new, and when the close returns it to a claimer paying its own claim.
+     */
+    existingWsolLamports: bigint;
     /** Zero costs when there is no transaction. */
     costs: ClaimCosts;
     /**
@@ -100,6 +106,10 @@ export declare function minimumWorthwhileClaimLamports(costs: ClaimCosts, minNet
  * callers skip claims below it. Base tokens are not valued (FORGE configs collect SOL fees only).
  */
 export declare function isClaimWorthwhile(summary: ClaimSummary, minNetLamports?: bigint): boolean;
+/** @throws ClaimError `unsupported_quote_mint` unless the pool is quoted in SOL. */
+export declare function assertSolQuotedPool(state: DbcPoolState): void;
+/** @throws ClaimError `invalid_receiver` for anything but a usable wallet address. */
+export declare function assertClaimReceiver(receiver: PublicKey): void;
 /**
  * Builds the creator claim of `pool` to `receiver` (see the module comment for the transaction).
  * @throws ClaimError when `creator` is not the pool creator, the pool is not SOL-quoted, the

package/dist/claims.js

@@ -25,8 +25,10 @@
  *   exactly that amount of SOL to the receiver.
  * So the payer's balance only decreases by the network fee and the one-time rent below, and the
  * claimer's balance does not change at all when the claimer is not the payer (read-only signer).
- * A claimer WSOL account that already holds WSOL is refused when the claimer is not the payer
- * (`claimer_wsol_not_empty`): closing it would hand that WSOL to the payer.
+ * A claimer WSOL account that already holds WSOL (anyone can send some to it) goes with the
+ * close: to the receiver when the receiver pays (accepted and counted in the summary as
+ * received, `existingWsolLamports`), back to the claimer when it pays its own claim (accepted).
+ * It is refused when the close would hand it to a payer that is neither (`claimer_wsol_not_empty`).
  *
  * Base side (the coin): the program needs a base token account even when there is nothing to
  * claim (FORGE configs collect fees in SOL only). It is the receiver's associated account, created
@@ -66,12 +68,15 @@ export function minimumWorthwhileClaimLamports(costs, minNetLamports = 0n) {
 export function isClaimWorthwhile(summary, minNetLamports = 0n) {
     return summary.receiverQuoteLamports > 0n && summary.netLamports > minNetLamports;
 }
-function assertSolQuote(state) {
+/** @throws ClaimError `unsupported_quote_mint` unless the pool is quoted in SOL. */
+export function assertSolQuotedPool(state) {
     if (!state.config.quoteMint.equals(SOL_QUOTE_MINT)) {
         throw new ClaimError('unsupported_quote_mint', `Pool ${state.address.toBase58()} is not quoted in SOL: FORGE pools are SOL-quoted only`);
     }
 }
-function assertReceiver(receiver) {
+const assertSolQuote = assertSolQuotedPool;
+/** @throws ClaimError `invalid_receiver` for anything but a usable wallet address. */
+export function assertClaimReceiver(receiver) {
     if (!(receiver instanceof PublicKey)) {
         throw new ClaimError('invalid_receiver', 'Claim receiver must be a PublicKey');
     }
@@ -79,6 +84,7 @@ function assertReceiver(receiver) {
         throw new ClaimError('invalid_receiver', 'Claim receiver is not a valid wallet');
     }
 }
+const assertReceiver = assertClaimReceiver;
 function isEmpty(amounts) {
     return amounts.base === 0n && amounts.quote === 0n;
 }
@@ -111,7 +117,13 @@ async function buildTradingClaim(connection, input, options) {
             transaction: null,
             lastValidBlockHeight: null,
             skipReason: 'nothing_to_claim',
-            summary: { ...baseSummary, receiverQuoteLamports: 0n, costs: ZERO_COSTS, netLamports: 0n },
+            summary: {
+                ...baseSummary,
+                receiverQuoteLamports: 0n,
+                existingWsolLamports: 0n,
+                costs: ZERO_COSTS,
+                netLamports: 0n,
+            },
         };
     }
     const baseMint = state.virtualPool.poolState.baseMint;
@@ -136,9 +148,11 @@ async function buildTradingClaim(connection, input, options) {
         retryRpc(() => connection.getMinimumBalanceForRentExemption(ACCOUNT_SIZE, commitment), options.retry),
     ]);
     const [receiverBaseInfo, claimerWsolInfo, receiverInfo] = infos;
-    // The temporary WSOL account is closed to the payer: when it already holds WSOL of a claimer
-    // that is not the payer, that WSOL would move to the payer. Refuse instead.
-    if (claimerWsolInfo && !claimer.equals(payer) && claimerWsolInfo.owner.equals(TOKEN_PROGRAM_ID)) {
+    // The temporary WSOL account is closed to the payer. WSOL it already holds (anyone can send
+    // some, 1 lamport is enough) goes with the close: fine when the payer is the receiver (it is
+    // received) or the claimer itself (its own); refused when it would reach a third-party payer.
+    let existingWsolLamports = 0n;
+    if (claimerWsolInfo && claimerWsolInfo.owner.equals(TOKEN_PROGRAM_ID)) {
         let amount;
         try {
             amount = unpackAccount(claimerWsol, claimerWsolInfo, TOKEN_PROGRAM_ID).amount;
@@ -147,9 +161,11 @@ async function buildTradingClaim(connection, input, options) {
             // Not a token account (e.g. lamports sent to the address): the idempotent creation takes it.
             amount = 0n;
         }
-        if (amount > 0n) {
+        if (amount > 0n && !claimer.equals(payer) && !receiver.equals(payer)) {
             throw new ClaimError('claimer_wsol_not_empty', `The claimer's WSOL account ${claimerWsol.toBase58()} holds ${amount} lamports of WSOL: unwrap it before claiming with another payer`);
         }
+        if (receiver.equals(payer))
+            existingWsolLamports = amount;
     }
     if (exact && quote > 0n) {
         const size = receiverInfo?.data.length ?? 0;
@@ -189,11 +205,13 @@ async function buildTradingClaim(connection, input, options) {
         payerTotalLamports,
         payerRequiredBalanceLamports: payerTotalLamports + temporaryLamports,
     };
+    const receiverQuoteLamports = quote + existingWsolLamports;
     const summary = {
         ...baseSummary,
-        receiverQuoteLamports: quote,
+        receiverQuoteLamports,
+        existingWsolLamports,
         costs,
-        netLamports: quote - payerTotalLamports,
+        netLamports: receiverQuoteLamports - payerTotalLamports,
     };
     if (options.minNetLamports !== undefined && !isClaimWorthwhile(summary, options.minNetLamports)) {
         return { transaction: null, lastValidBlockHeight: null, skipReason: 'not_worthwhile', summary };

package/dist/config.d.ts

@@ -25,41 +25,10 @@
  * `buildLaunchpadConfig` / `buildLaunchpadCoinConfig` are pure and deterministic. Every result
  * passes `validate.ts` before it is returned; otherwise a `ValidationError` is thrown.
  */
-import { ActivationType, BaseFeeMode, MigrationFeeOption, MigrationOption, TokenAuthorityOption, TokenDecimal, TokenType, type BuildCurveParams, type ConfigParameters, type SwapQuoteConfig } from '@meteora-ag/dynamic-bonding-curve-sdk';
+import { type BuildCurveParams, type ConfigParameters, type PoolConfig, type SwapQuoteConfig } from '@meteora-ag/dynamic-bonding-curve-sdk';
 import { PublicKey, Transaction, type Connection } from '@solana/web3.js';
 import { LaunchpadSpec } from '@forge/shared';
-/** Token of every coin: SPL token, 1,000,000,000 tokens with 6 decimals, immutable metadata. */
-export declare const FORGE_TOKEN_SETTINGS: {
-    readonly tokenType: TokenType.SPLToken;
-    readonly tokenBaseDecimal: TokenDecimal.SIX;
-    readonly tokenQuoteDecimal: 9;
-    readonly tokenAuthorityOption: TokenAuthorityOption.Immutable;
-    readonly totalTokenSupply: 1000000000;
-    readonly leftover: 0;
-};
-/**
- * Anti-sniper fee schedule (`spec.antiSniper`): the fee starts at `startingFeeBps` and decreases
- * linearly, in `numberOfPeriod` equal steps over `totalDurationSeconds`, to `spec.tradingFeeBps`.
- * Within the validate.ts bounds (starting fee <= 9900 bps, duration <= 300 s).
- */
-export declare const ANTI_SNIPER_FEE_SCHEDULE: {
-    readonly baseFeeMode: BaseFeeMode.FeeSchedulerLinear;
-    readonly startingFeeBps: 9900;
-    readonly numberOfPeriod: 10;
-    readonly totalDurationSeconds: 60;
-};
-/** Migration: DAMM v2, migrated pool fee 0.25%, no migration fee, 20% of the supply migrated. */
-export declare const FORGE_MIGRATION_SETTINGS: {
-    readonly migrationOption: MigrationOption.MET_DAMM_V2;
-    readonly migrationFeeOption: MigrationFeeOption.FixedBps25;
-    readonly migrationFee: {
-        readonly feePercentage: 0;
-        readonly creatorFeePercentage: 0;
-    };
-    readonly percentageSupplyOnMigration: 20;
-};
-/** Fee scheduler periods are counted in seconds. */
-export declare const FORGE_ACTIVATION_TYPE = ActivationType.Timestamp;
+export { ANTI_SNIPER_FEE_SCHEDULE, FORGE_ACTIVATION_TYPE, FORGE_MIGRATION_SETTINGS, FORGE_TOKEN_SETTINGS, FORGE_TOKEN_SUPPLY_RAW, forgeBaseFee, forgeFeeSchedulerParam, forgeReferenceCurve, type ForgeReferenceCurve, } from './settings.js';
 /**
  * Pool creation fee of the launchpad coin config: none. The only pool ever created on it is the
  * client's own coin, paid by the client: a fee would only move the client's SOL to its own fee
@@ -69,9 +38,14 @@ export declare const FORGE_ACTIVATION_TYPE = ActivationType.Timestamp;
  */
 export declare const LAUNCHPAD_COIN_POOL_CREATION_FEE_SOL = 0;
 /** Pool creation fee of a config kind, in SOL. */
-export declare function poolCreationFeeSolFor(spec: LaunchpadSpec, kind: ConfigKind): number;
+export declare function poolCreationFeeSolFor(spec: Pick<LaunchpadSpec, 'poolCreationFeeSol'>, kind: ConfigKind): number;
 /** Which of the two configs. */
 export type ConfigKind = 'launchpad' | 'launchpadCoin';
+/**
+ * The spec fields a config depends on, besides the owner wallet (a full `LaunchpadSpec` fits).
+ * Everything else in a FORGE config is a fixed setting (settings.ts).
+ */
+export type ConfigSpecFields = Pick<LaunchpadSpec, 'tradingFeeBps' | 'antiSniper' | 'coinCreatorSharePct' | 'poolCreationFeeSol'>;
 /**
  * What `createConfig` needs besides the config keypair and the payer: the SDK
  * `ConfigParameters` plus the accounts that decide where the money goes.
@@ -92,9 +66,9 @@ export type LaunchpadConfigParams = ConfigParameters & {
  */
 export declare function parseLaunchpadSpec(spec: unknown): LaunchpadSpec;
 /** Creator share of the trading fees for each config kind. */
-export declare function creatorTradingFeePercentageFor(spec: LaunchpadSpec, kind: ConfigKind): number;
-/** The `buildCurve` input for a spec and a config kind (pure). */
-export declare function curveParamsFor(spec: LaunchpadSpec, kind: ConfigKind): BuildCurveParams;
+export declare function creatorTradingFeePercentageFor(spec: Pick<LaunchpadSpec, 'coinCreatorSharePct'>, kind: ConfigKind): number;
+/** The `buildCurve` input for a spec (or just its config fields) and a config kind (pure). */
+export declare function curveParamsFor(spec: ConfigSpecFields, kind: ConfigKind): BuildCurveParams;
 export interface ConfigParamsOptions {
     /**
      * Metadata URI the launchpad coin will be launched with, when known (the signer knows it from
@@ -115,6 +89,35 @@ export declare function buildConfigParams(spec: LaunchpadSpec, kind: ConfigKind,
 export declare function buildLaunchpadConfig(spec: LaunchpadSpec): LaunchpadConfigParams;
 /** Launchpad coin config: the launchpad's own coin, FORGE is the creator (25%). */
 export declare function buildLaunchpadCoinConfig(spec: LaunchpadSpec): LaunchpadConfigParams;
+/** What an on-chain config is expected to be, besides its kind. */
+export interface OnchainConfigExpectation {
+    /**
+     * The spec the config was built from. Every field is then compared with
+     * `buildConfigParams(spec, kind)`, exactly what `buildCreateConfigTx` sent.
+     */
+    spec?: LaunchpadSpec;
+    /** Fee claimer and leftover receiver (`spec.ownerWallet` when a spec is given). */
+    owner?: PublicKey;
+    /** Pool creation fee in lamports (launchpad config; the coin config never has one). */
+    poolCreationFeeLamports?: bigint;
+}
+/**
+ * Compares a config read from the chain with the parameters core builds for it, field by field:
+ * accounts, token, base fee (cliff, periods, period, reduction, mode), dynamic fee, creator share,
+ * pool creation fee, first swap at the minimum fee, activation, liquidity split and vesting,
+ * migration (option, fee option, threshold, migration fee percentages, migrated pool fee), locked
+ * vesting, token supply, start price and curve. The values the program derives from these
+ * (`swapBaseAmount`, `migrationBaseThreshold`, `migrationSqrtPrice`) are not compared.
+ *
+ * With `expected.spec`, the reference is `buildConfigParams(spec, kind)`. Without it, the spec
+ * fields are read from the config itself (`inferSpecFields`: they must be values a FORGE spec can
+ * hold) and every other field must be FORGE's fixed setting; the fee claimer and leftover receiver
+ * must be `expected.owner` (or, without it, the same key).
+ *
+ * @returns every mismatch, as readable messages (on-chain values are public); empty when the config
+ *   is exactly a FORGE config of this kind.
+ */
+export declare function onchainConfigMismatches(config: PoolConfig, kind: ConfigKind, expected?: OnchainConfigExpectation): string[];
 export interface FirstBuyQuote {
     /** Raw base units (6 decimals) delivered by the first buy. */
     tokensOut: bigint;