@forgedevv/core 0.1.0 → 0.3.0

package/dist/claims.js

@@ -25,13 +25,21 @@
  *   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
  * idempotently by the payer: the first claim of each pool costs the payer that account's rent
  * (~0.00204 SOL), which stays in an account owned by the receiver (recoverable by closing it).
+ *
+ * Priority fee (`ClaimOptions.priority`, priority-fee.ts): two compute budget instructions come
+ * first, `setComputeUnitLimit` (`CLAIM_COMPUTE_UNITS`, or `POOL_CREATION_FEE_CLAIM_COMPUTE_UNITS`)
+ * then `setComputeUnitPrice`, priced from the recent fees of the claim's writable accounts and
+ * bounded by the setting; the costs (network fee, worthwhile check) count it. Without the option
+ * the claims carry no compute budget instruction, as before.
  */
 import { ACCOUNT_SIZE, NATIVE_MINT, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID, createAssociatedTokenAccountIdempotentInstruction, createCloseAccountInstruction, createTransferInstruction, getAssociatedTokenAddressSync, unpackAccount, } from '@solana/spl-token';
 import { PublicKey, SystemProgram, Transaction, } from '@solana/web3.js';
@@ -39,9 +47,18 @@ import { CreatorService, DYNAMIC_BONDING_CURVE_PROGRAM_ID, PartnerService, Token
 import BN from 'bn.js';
 import { getMultisigVault } from './addresses.js';
 import { SOL_QUOTE_MINT } from './constants.js';
+import { estimatePriorityFee, priorityFeeInstructions, resolvePriorityFeePolicy, writableAccountsOf, } from './priority-fee.js';
 import { READ_COMMITMENT, feeMetrics, getDbcPoolState, poolCreationFeeStatus, retryRpc, } from './reads.js';
-/** Base fee per signature (lamports); claims set no priority fee. */
+/** Base fee per signature (lamports); a priority fee comes on top with `ClaimOptions.priority`. */
 export const CLAIM_LAMPORTS_PER_SIGNATURE = 5000n;
+/**
+ * Compute unit limit of a trading fee claim with a priority fee: two idempotent token account
+ * creations (about 25,000 CU each when they create), the DBC claim (two token transfers and its
+ * event), a token self-transfer, a close and a SOL transfer, about 100,000 CU at most: 2x margin.
+ */
+export const CLAIM_COMPUTE_UNITS = 200_000;
+/** Compute unit limit of a pool creation fee claim (one DBC instruction moving lamports). */
+export const POOL_CREATION_FEE_CLAIM_COMPUTE_UNITS = 100_000;
 // Pool creation fee helpers live in reads.ts (CoinOfConfig uses them); re-exported here.
 export { PARTNER_POOL_CREATION_FEE_CLAIMED_BIT, partnerPoolCreationFeeShare } from './reads.js';
 export class ClaimError extends Error {
@@ -52,6 +69,23 @@ export class ClaimError extends Error {
         this.code = code;
     }
 }
+/** Checks `options.priority` before any network call. @throws RangeError. */
+export function assertClaimPriority(options) {
+    if (options.priority !== undefined)
+        resolvePriorityFeePolicy(options.priority);
+}
+/** The priced compute budget of a claim, or nothing without `priority`. */
+export async function claimPriorityFee(connection, instructions, computeUnitLimit, priority) {
+    if (priority === undefined)
+        return { quote: null, instructions: [] };
+    const quote = await estimatePriorityFee({
+        connection,
+        writableAccounts: writableAccountsOf(instructions),
+        computeUnitLimit,
+        setting: priority,
+    });
+    return { quote, instructions: priorityFeeInstructions(quote) };
+}
 // ---------------------------------------------------------------------------------------------
 // Pure helpers
 // ---------------------------------------------------------------------------------------------
@@ -66,12 +100,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 +116,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 +149,14 @@ 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,
+                priorityFee: null,
+            },
         };
     }
     const baseMint = state.virtualPool.poolState.baseMint;
@@ -136,9 +181,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 +194,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;
@@ -173,12 +222,13 @@ async function buildTradingClaim(connection, input, options) {
     if (exact && quote > 0n) {
         instructions.push(SystemProgram.transfer({ fromPubkey: payer, toPubkey: receiver, lamports: quote }));
     }
+    const priority = await claimPriorityFee(connection, instructions, CLAIM_COMPUTE_UNITS, options.priority);
     const { blockhash, lastValidBlockHeight } = await retryRpc(() => connection.getLatestBlockhash(commitment), options.retry);
     const transaction = new Transaction({ feePayer: payer, blockhash, lastValidBlockHeight });
-    transaction.add(...instructions);
+    transaction.add(...priority.instructions, ...instructions);
     // 4. Costs and net.
     const signatures = BigInt(transaction.compileMessage().header.numRequiredSignatures);
-    const networkFeeLamports = signatures * CLAIM_LAMPORTS_PER_SIGNATURE;
+    const networkFeeLamports = signatures * CLAIM_LAMPORTS_PER_SIGNATURE + (priority.quote?.priorityFeeLamports ?? 0n);
     const receiverTokenAccountRentLamports = receiverBaseInfo ? 0n : BigInt(tokenAccountRent);
     const temporaryLamports = claimerWsolInfo ? 0n : BigInt(tokenAccountRent);
     const payerTotalLamports = networkFeeLamports + receiverTokenAccountRentLamports;
@@ -189,11 +239,14 @@ 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,
+        priorityFee: priority.quote,
     };
     if (options.minNetLamports !== undefined && !isClaimWorthwhile(summary, options.minNetLamports)) {
         return { transaction: null, lastValidBlockHeight: null, skipReason: 'not_worthwhile', summary };
@@ -209,6 +262,7 @@ async function buildTradingClaim(connection, input, options) {
 export async function buildCreatorClaimTx(connection, params, options = {}) {
     const commitment = options.commitment ?? READ_COMMITMENT;
     assertReceiver(params.receiver);
+    assertClaimPriority(options);
     if (params.expectedReceiver && !params.expectedReceiver.equals(params.receiver)) {
         throw new ClaimError('receiver_mismatch', `Creator fees of pool ${params.pool.toBase58()} must go to ${params.expectedReceiver.toBase58()}, not ${params.receiver.toBase58()}`);
     }
@@ -260,6 +314,7 @@ export async function buildPartnerClaimTx(connection, params, options = {}) {
     const commitment = options.commitment ?? READ_COMMITMENT;
     const receiver = params.receiver ?? params.feeClaimer;
     assertReceiver(receiver);
+    assertClaimPriority(options);
     const state = await getDbcPoolState(connection, params.pool, {
         commitment,
         retry: options.retry,
@@ -299,6 +354,7 @@ export async function buildPartnerPoolCreationFeeClaimTx(connection, params, opt
     const commitment = options.commitment ?? READ_COMMITMENT;
     const receiver = params.receiver ?? params.feeClaimer;
     assertReceiver(receiver);
+    assertClaimPriority(options);
     const state = await getDbcPoolState(connection, params.pool, {
         commitment,
         retry: options.retry,
@@ -323,6 +379,7 @@ export async function buildPartnerPoolCreationFeeClaimTx(connection, params, opt
         claimableLamports: 0n,
         networkFeeLamports: 0n,
         netLamports: 0n,
+        priorityFee: null,
     };
     if (partnerShareLamports === 0n || alreadyClaimed) {
         return {
@@ -348,11 +405,12 @@ export async function buildPartnerPoolCreationFeeClaimTx(connection, params, opt
         !claimIx.keys.some((k) => k.isWritable && k.pubkey.equals(receiver))) {
         throw new ClaimError('unexpected_sdk_instructions', 'The SDK pool creation fee claim does not have the expected instruction');
     }
+    const priority = await claimPriorityFee(connection, [claimIx], POOL_CREATION_FEE_CLAIM_COMPUTE_UNITS, options.priority);
     const { blockhash, lastValidBlockHeight } = await retryRpc(() => connection.getLatestBlockhash(commitment), options.retry);
     const transaction = new Transaction({ feePayer: payer, blockhash, lastValidBlockHeight });
-    transaction.add(claimIx);
+    transaction.add(...priority.instructions, claimIx);
     const signatures = BigInt(transaction.compileMessage().header.numRequiredSignatures);
-    const networkFeeLamports = signatures * CLAIM_LAMPORTS_PER_SIGNATURE;
+    const networkFeeLamports = signatures * CLAIM_LAMPORTS_PER_SIGNATURE + (priority.quote?.priorityFeeLamports ?? 0n);
     return {
         transaction,
         lastValidBlockHeight,
@@ -362,6 +420,7 @@ export async function buildPartnerPoolCreationFeeClaimTx(connection, params, opt
             claimableLamports: partnerShareLamports,
             networkFeeLamports,
             netLamports: partnerShareLamports - networkFeeLamports,
+            priorityFee: priority.quote,
         },
     };
 }

package/dist/config.d.ts

@@ -25,41 +25,11 @@
  * `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;
+import { type PriorityFeeQuote, type PriorityFeeSetting } from './priority-fee.js';
+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 +39,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 +67,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 +90,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;
@@ -167,6 +171,11 @@ export interface BuildCreateConfigTxParams {
     payer: PublicKey;
     /** Priority fee, in micro-lamports per compute unit (default 0). */
     computeUnitPriceMicroLamports?: number;
+    /**
+     * Priority fee read from the cluster for the payer and the config account, bounded by this
+     * setting (priority-fee.ts). Not with `computeUnitPriceMicroLamports`.
+     */
+    priority?: PriorityFeeSetting;
     /** Blockhash to use; fetched from the cluster when absent. */
     recentBlockhash?: {
         blockhash: string;
@@ -184,6 +193,8 @@ export interface CreateConfigTx {
     lastValidBlockHeight: number;
     /** Who must sign: the payer (fee payer) and the config keypair. */
     signers: PublicKey[];
+    /** The priority fee (price, fee, cap; `fixed` without a `priority` setting). */
+    priorityFee: PriorityFeeQuote;
 }
 /**
  * Unsigned transaction creating one of the two configs (`createConfig`). The parameters are