@forgedevv/core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,9 +3,149 @@
 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.2.0 — unreleased
+## 0.3.0 — 2026-10-17
 
-Everything below was added after 0.1.0 was published. Publish `@forgedevv/shared` 0.2.0 with it.
+Changes after 0.2.0. Publish `@forgedevv/shared` 0.3.0 with it (new kill switch `revenue_paused` in `FlagKey`).
+
+### Changed (Jupiter fixes)
+
+- **Jupiter referral fee.** `FEES.jupiterIntegratorFeeBps` (re-exported from `@forge/shared`) is
+  50 bps, was 30: the Jupiter Plugin passes `referralFee` to Ultra `/order`, which refuses any
+  value outside 50..255 bps, so every swap of a graduated coin failed. Jupiter keeps 20% of it.
+  `FEES.platformFeeBps` (30 bps, `PLATFORM_FEE_BPS` on swaps built by core) is unchanged.
+- **Jupiter referral claims.** `buildJupiterReferralClaimTx` refuses a referral account of another
+  project than Jupiter's Ultra project (`project_mismatch`; the new `expectedProject` parameter
+  overrides the default `JUPITER_ULTRA_REFERRAL_PROJECT`). A funded v2 collection account is only
+  claimed for a named referral account at the PDA `["referral", project, name]`, the only kind
+  `claim_v2` accepts: `referral_account_unnamed` or `referral_account_not_pda` otherwise (new
+  `JupiterReferralErrorCode` values; the whole build is refused). With an empty v2 account, an
+  unnamed account still claims its v1 collection account. Devnet is unchanged: any cluster but
+  mainnet-beta is still refused (`wrong_cluster`) before these reads.
+
+### Added (Jupiter fixes)
+
+- `JUPITER_REFERRAL_FEE_BPS_RANGE` (`{ min: 50, max: 255 }`) and
+  `assertJupiterReferralFeeBps(bps)` (constants.ts): returns a whole number of bps within the range
+  Jupiter Ultra accepts, throws a `RangeError` otherwise. The launchpad template runs the plugin
+  fee through it and fails closed outside it.
+- `JUPITER_ULTRA_REFERRAL_PROJECT` (`DkiqsTrw1u1bYFumumC7sCG2S8K25qc2vemJFHyW2wJc`) and
+  `deriveJupiterReferralAccount(project, name, programId?)` (jupiter-referral.ts).
+
+### Added (revenue wallet referral accounts setup)
+
+Pure builders of the two accounts the revenue wallet must hold (docs/MAINNET.md section 5), for
+the signer's one-off `--setup-revenue-referrals` command. Only the payer signs: neither the
+revenue wallet nor the new accounts do.
+
+- **`meteora-referral.ts`** (re-exported by the index): `deriveMeteoraReferralAccount(payer,
+  seed?)` (`createWithSeed(payer, seed, SPL Token)`, default seed
+  `METEORA_REFERRAL_ACCOUNT_SEED` = `forge-meteora-referral`), `buildCreateMeteoraReferralAccountIxs`
+  / `buildCreateMeteoraReferralAccountTx({ payer, owner, seed?, rentLamports, blockhash,
+  lastValidBlockHeight, priorityFee? })`: System `createAccountWithSeed` (from = base = payer,
+  the rent of 165 bytes, SPL Token owned) then SPL Token `InitializeAccount3` (wrapped SOL,
+  owner = the revenue wallet, no owner signature), the compute budget pair first when the quote
+  has a price (`METEORA_REFERRAL_SETUP_COMPUTE_UNITS` = 30,000); `inspectMeteoraReferralAccount`
+  (pure: `absent`, `ready`, or `mismatch` with a reason: not a token account, wrong mint or owner,
+  the owner's associated account, frozen, delegated, closable by someone else) and
+  `readMeteoraReferralAccount` (any cluster); `MeteoraReferralError` (`invalid_params`).
+- **Jupiter referral setup** (jupiter-referral.ts), verified against the program source
+  (`initialize_referral_account_with_name.rs`, `lib.rs`, `claim_v2.rs`) and the SDK 0.3.0 IDL:
+  `JUPITER_INITIALIZE_REFERRAL_ACCOUNT_WITH_NAME_DISCRIMINATOR`, `JUPITER_REFERRAL_ACCOUNT_SIZE`
+  (274), `JUPITER_REFERRAL_NAME_MAX_CHARS` (19: the program requires fewer than 20 characters)
+  and `JUPITER_REFERRAL_NAME_MAX_BYTES` (32: a PDA seed), `assertJupiterReferralName` (also
+  refuses whitespace and control characters), `encodeJupiterReferralName` (Borsh),
+  `buildJupiterInitializeReferralAccountWithNameIx({ payer, partner, project, referralAccount },
+  name)` (the IDL's accounts: payer the only signer, partner read-only and not a signer, the
+  referral account the PDA `["referral", project, name]`),
+  `buildJupiterReferralTokenAccountV2Ix({ payer, referralAccount, mint, tokenProgram })` (the v2
+  collection account `claim_v2` empties is the referral account's associated token account: an
+  idempotent creation, what the SDK's `initializeReferralTokenAccountV2` sends),
+  `buildJupiterReferralSetupTx({ payer, partner, project?, name, createReferralAccount,
+  tokenAccounts, blockhash, lastValidBlockHeight, priorityFee? })` (Ultra project by default,
+  `JUPITER_REFERRAL_SETUP_COMPUTE_UNITS` = 150,000), `inspectJupiterReferralAccount` /
+  `inspectJupiterReferralTokenAccountV2` (pure statuses with mismatch reasons: partner, project,
+  name, owner, mint) and `readJupiterReferralSetup({ connection, partner, name, mints })`
+  (mainnet-beta only, `wrong_cluster` before any read; reads the project, the mints' token
+  programs, the referral account and its collection accounts).
+
+### Changed (revenue wallet, docs/DECISIONS.md D34)
+
+- **New address `FORGE_REVENUE_WALLET`** (`FORGE_ADDRESS_NAMES`, `getRevenueWallet`): the
+  signer-held wallet where the non-native trading revenue lands before the signer converts it to
+  SOL and forwards it to the multisig vault. It replaces the vault as the holder of the Meteora
+  referral account and as the partner of the Jupiter referral account; the platform fee goes to
+  it too (`FORGE_PLATFORM_FEE_WALLET` must be that wallet).
+- **Swaps.** `swapFeeAddresses` returns `revenueWallet` (was `multisigVault`), read from
+  `FORGE_REVENUE_WALLET` (optional, as before): when set, the Meteora referral token account must
+  be held by it (`REFERRAL_ACCOUNT_INVALID`, `assertReferralAccountReady(..., expectedOwner?)`)
+  and `FORGE_PLATFORM_FEE_WALLET` must be it (`PLATFORM_FEE_WALLET_MISMATCH`, checked before any
+  network call by `buildBuyTx`, `buildSellTx` and `assertSwapFeeAccountsReady`). Client sites
+  receive `NEXT_PUBLIC_FORGE_REVENUE_WALLET` instead of `NEXT_PUBLIC_FORGE_MULTISIG_VAULT`.
+- `buildJupiterReferralClaimTx` is unchanged: `expectedPartner` is now the revenue wallet.
+
+### Added (priority fees)
+
+- **`priority-fee.ts`** (browser-safe, re-exported by the index): `computePriorityFee` (pure: the
+  nearest-rank `percentile` of `getRecentPrioritizationFees`, at least `floorMicroLamports`, at
+  most `maxMicroLamports` per CU and `maxLamports` for the whole transaction; an empty list or a
+  failed read prices at the floor, reported in `source`), `estimatePriorityFee` (reads the fees
+  for the transaction's writable accounts, at most `MAX_PRIORITY_FEE_ACCOUNTS` = 32),
+  `readRecentPriorityFees`, `resolvePriorityFeePolicy`, `feePercentile`, `maxPriceForBudget`,
+  `maxPriorityFeeLamports` (the worst case of a setting, to show before building),
+  `fixedPriorityFee`, `priorityFeeInstructions` (unit limit then price; `priceOnly`),
+  `writableAccountsOf`, and `checkComputeBudgetInstructions` / `ComputeBudgetCheckError` for
+  transaction policies (no account, `SetComputeUnitLimit` / `SetComputeUnitPrice` only, at most
+  one of each, bounded values and fee; without a limit the fee is counted for 1.4M CU).
+  `DEFAULT_PRIORITY_FEE_POLICY`: 75th percentile, floor 10,000 micro-lamports per CU, at most
+  1,000,000 per CU and 500,000 lamports (0.0005 SOL) per transaction; hard ceilings
+  `MAX_PRIORITY_FEE_MICRO_LAMPORTS` (10 lamports per CU) and `MAX_PRIORITY_FEE_LAMPORTS`
+  (0.01 SOL). Types `PriorityFeeSetting`, `PriorityFeePolicy`, `PriorityFeeQuote`,
+  `PriorityFeeSource`, `RecentPrioritizationFee`.
+- **Builders accept an optional `priority` setting** (exclusive with their fixed price, if any),
+  which puts `setComputeUnitLimit` then `setComputeUnitPrice` first (after the nonce advance):
+  `buildBuyTx` / `buildSellTx` (`SwapBuildOptions.priority`; the pure `buildSwapTransaction`
+  refuses it), `buildPaymentTx` (`PaymentTxOptions.priority`, limit `PAYMENT_COMPUTE_UNITS` =
+  50,000), `buildLaunchCoinTx` and `buildUserCoinLaunchTx`, `buildCreateConfigTx`, the creator,
+  partner and pool creation fee claims (`ClaimOptions.priority`, limits `CLAIM_COMPUTE_UNITS` =
+  200,000 and `POOL_CREATION_FEE_CLAIM_COMPUTE_UNITS` = 100,000), the DAMM v2 position claim
+  (`positionClaimComputeUnits`) and `buildJupiterReferralClaimTx`
+  (`JUPITER_REFERRAL_CLAIM_COMPUTE_UNITS` = 300,000). Their results report the quote
+  (`priorityFee`), and the claim costs count the fee. `CREATE_NONCE_ACCOUNT_COMPUTE_UNITS`
+  (10,000) names the limit of the nonce account builders.
+- **Launch sizes.** The launchpad coin launch keeps the 148-byte metadata budget: with a priority
+  fee it carries the unit limit and the price up to 136 bytes of metadata, the price alone up to
+  144 (priced for `MAX_TRANSACTION_COMPUTE_UNITS`), and no price beyond
+  (`LaunchCoinSummary.priorityFeePlacement`: `limit_and_price`, `price_only`,
+  `omitted_for_size`). A priced swap or user coin launch is 12 bytes larger.
+
+### Changed (priority fees)
+
+- `BuiltSwapTransaction.priorityFee`, `PaymentTxResult.priorityFee`, `CreateConfigTx.priorityFee`,
+  `ClaimSummary.priorityFee`, `PoolCreationFeeClaimSummary.priorityFee`,
+  `PositionClaimSummary.priorityFee`, `JupiterReferralClaimTx.priorityFee` and
+  `LaunchCoinSummary` / `UserCoinLaunchSummary` `.priorityFee` and `.priorityFeePlacement` are new
+  required fields: code that builds these objects itself (test fakes) must set them. Without a
+  `priority` setting every transaction is byte for byte what 0.2.0 built.
+- `ClaimCosts.networkFeeLamports` and `PositionClaimCosts.networkFeeLamports` include the
+  priority fee (0 without a setting).
+- Consumers: the launchpad template prices its trades, coin creations and creator fee claims with
+  the defaults, so client sites need this version, and the FORGE RPC relay must serve
+  `getRecentPrioritizationFees` (apps/web, same release).
+
+### Added (on-chain fallback of the coin data)
+
+- `listPoolStatesOfConfig(connection, config, options?)` (reads.ts): the decoded pools of a config
+  with the config state (`DbcPoolState[]`, sorted by pool address), from the SDK's
+  `getPoolsByConfig`; a pool whose decoded config differs is dropped. `listCoinsOfConfig` now
+  summarizes its result (unchanged output). The launchpad template lists its coins with it when
+  the Jupiter data API is unavailable (and always on devnet).
+- `poolSpotPrice(sqrtPrice, baseDecimals, quoteDecimals = 9)` (reads.ts): display price of one
+  whole coin in whole quote tokens from the pool's Q64.64 `sqrtPrice` (same value as the SDK's
+  `getPriceFromSqrtPrice`, as a float).
+
+## 0.2.0 — 2026-10-17
+
+Everything below was added after 0.1.0 and published on npm on 2026-10-17 with `@forgedevv/shared` 0.2.0.
 
 ### Changed (security review)
 

package/dist/addresses.d.ts

@@ -9,14 +9,20 @@
  * Validation choice: a value is valid when the `PublicKey` constructor accepts it (base58 that
  * decodes to exactly 32 bytes) and it re-encodes to the same string. Being on the ed25519 curve is
  * NOT required, because some of these addresses are token accounts or PDAs (e.g. the Meteora
- * referral account, which is a WSOL token account held by the multisig, or a Squads vault PDA).
+ * referral account, which is a WSOL token account held by the revenue wallet, or a Squads vault
+ * PDA).
+ *
+ * The revenue wallet (`FORGE_REVENUE_WALLET`, docs/DECISIONS.md D34) is the signer-held wallet
+ * where the non-native trading revenue lands: the platform fee (`FORGE_PLATFORM_FEE_WALLET` must
+ * be that wallet), the Meteora referral WSOL account it holds, and the Jupiter referral claims
+ * (it is the referral account's partner). The signer converts and forwards it to the vault.
  * The all-zero key (`11111111111111111111111111111111`, the System Program) is rejected: fees
  * sent there would be lost.
  *
  * 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", "FORGE_SQUADS_MULTISIG", "FORGE_SQUADS_SPENDING_LIMIT"];
+export declare const FORGE_ADDRESS_NAMES: readonly ["FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_REVENUE_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; the Squads
@@ -48,17 +54,30 @@ export declare function requireAddresses<N extends ForgeAddressName>(names: read
  * 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).
+ * account, `FORGE_REVENUE_WALLET`, 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. */
+/**
+ * Squads multisig vault: receives the creator fees, the cashbox sweeps and the revenue wallet's
+ * forwards (the converted trading revenue).
+ */
 export declare function getMultisigVault(env?: AddressEnv): PublicKey;
-/** Meteora referral token account (WSOL, held by the multisig), passed as `referralTokenAccount`. */
+/** Meteora referral token account (WSOL, held by the revenue wallet), passed as `referralTokenAccount`. */
 export declare function getMeteoraReferralAccount(env?: AddressEnv): PublicKey;
-/** Wallet receiving the 0.3% platform fee on swaps built by @forge/core. */
+/**
+ * Wallet receiving the 0.3% platform fee on swaps built by @forge/core: the revenue wallet
+ * (`FORGE_REVENUE_WALLET`, D34). Kept as its own variable so the fee destination stays explicit;
+ * `swapFeeAddresses` refuses an environment where the two differ.
+ */
 export declare function getPlatformFeeWallet(env?: AddressEnv): PublicKey;
+/**
+ * Revenue wallet (D34): held by the signer (keystore role `revenue`), it receives the platform
+ * fee, holds the Meteora referral WSOL account and is the partner of the Jupiter referral
+ * account. The signer regularly converts what it holds to SOL and forwards it to the vault.
+ */
+export declare function getRevenueWallet(env?: AddressEnv): PublicKey;
 /** Jupiter referral account (integrator fee after graduation). */
 export declare function getJupiterReferralAccount(env?: AddressEnv): PublicKey;
 /** Cashbox wallet (held by the signer) receiving client payments. */

package/dist/addresses.js

@@ -9,7 +9,13 @@
  * Validation choice: a value is valid when the `PublicKey` constructor accepts it (base58 that
  * decodes to exactly 32 bytes) and it re-encodes to the same string. Being on the ed25519 curve is
  * NOT required, because some of these addresses are token accounts or PDAs (e.g. the Meteora
- * referral account, which is a WSOL token account held by the multisig, or a Squads vault PDA).
+ * referral account, which is a WSOL token account held by the revenue wallet, or a Squads vault
+ * PDA).
+ *
+ * The revenue wallet (`FORGE_REVENUE_WALLET`, docs/DECISIONS.md D34) is the signer-held wallet
+ * where the non-native trading revenue lands: the platform fee (`FORGE_PLATFORM_FEE_WALLET` must
+ * be that wallet), the Meteora referral WSOL account it holds, and the Jupiter referral claims
+ * (it is the referral account's partner). The signer converts and forwards it to the vault.
  * The all-zero key (`11111111111111111111111111111111`, the System Program) is rejected: fees
  * sent there would be lost.
  *
@@ -20,6 +26,7 @@ export const FORGE_ADDRESS_NAMES = [
     'FORGE_MULTISIG_VAULT',
     'FORGE_METEORA_REFERRAL_ACCOUNT',
     'FORGE_PLATFORM_FEE_WALLET',
+    'FORGE_REVENUE_WALLET',
     'FORGE_JUPITER_REFERRAL_ACCOUNT',
     'FORGE_CASHBOX_WALLET',
     'FORGE_MINT',
@@ -112,7 +119,7 @@ export function requireAddresses(names, env = defaultEnv()) {
  * 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).
+ * account, `FORGE_REVENUE_WALLET`, in a browser that was not given it).
  *
  * @throws ForgeAddressError (invalid value; names only).
  */
@@ -122,18 +129,33 @@ export function readOptionalAddress(name, env = defaultEnv()) {
         return null;
     return requireAddresses([name], env)[name];
 }
-/** Squads multisig vault: receives the creator fees, the Meteora referral and the cashbox sweeps. */
+/**
+ * Squads multisig vault: receives the creator fees, the cashbox sweeps and the revenue wallet's
+ * forwards (the converted trading revenue).
+ */
 export function getMultisigVault(env) {
     return requireAddresses(['FORGE_MULTISIG_VAULT'], env).FORGE_MULTISIG_VAULT;
 }
-/** Meteora referral token account (WSOL, held by the multisig), passed as `referralTokenAccount`. */
+/** Meteora referral token account (WSOL, held by the revenue wallet), passed as `referralTokenAccount`. */
 export function getMeteoraReferralAccount(env) {
     return requireAddresses(['FORGE_METEORA_REFERRAL_ACCOUNT'], env).FORGE_METEORA_REFERRAL_ACCOUNT;
 }
-/** Wallet receiving the 0.3% platform fee on swaps built by @forge/core. */
+/**
+ * Wallet receiving the 0.3% platform fee on swaps built by @forge/core: the revenue wallet
+ * (`FORGE_REVENUE_WALLET`, D34). Kept as its own variable so the fee destination stays explicit;
+ * `swapFeeAddresses` refuses an environment where the two differ.
+ */
 export function getPlatformFeeWallet(env) {
     return requireAddresses(['FORGE_PLATFORM_FEE_WALLET'], env).FORGE_PLATFORM_FEE_WALLET;
 }
+/**
+ * Revenue wallet (D34): held by the signer (keystore role `revenue`), it receives the platform
+ * fee, holds the Meteora referral WSOL account and is the partner of the Jupiter referral
+ * account. The signer regularly converts what it holds to SOL and forwards it to the vault.
+ */
+export function getRevenueWallet(env) {
+    return requireAddresses(['FORGE_REVENUE_WALLET'], env).FORGE_REVENUE_WALLET;
+}
 /** Jupiter referral account (integrator fee after graduation). */
 export function getJupiterReferralAccount(env) {
     return requireAddresses(['FORGE_JUPITER_REFERRAL_ACCOUNT'], env).FORGE_JUPITER_REFERRAL_ACCOUNT;

package/dist/claims.d.ts

@@ -1,8 +1,17 @@
-import { PublicKey, Transaction, type Commitment, type Connection } from '@solana/web3.js';
+import { PublicKey, Transaction, type Commitment, type Connection, type TransactionInstruction } from '@solana/web3.js';
 import { type AddressEnv } from './addresses.js';
+import { type PriorityFeeQuote, type PriorityFeeSetting } from './priority-fee.js';
 import { type DbcPoolState, type RetryOptions, type TokenAmounts } 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 declare 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 declare const CLAIM_COMPUTE_UNITS = 200000;
+/** Compute unit limit of a pool creation fee claim (one DBC instruction moving lamports). */
+export declare const POOL_CREATION_FEE_CLAIM_COMPUTE_UNITS = 100000;
 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' | 'not_migrated' | 'damm_pool_not_found' | 'damm_pool_mismatch' | 'position_not_found' | 'position_mismatch' | 'position_not_owned';
 export declare class ClaimError extends Error {
@@ -12,7 +21,7 @@ export declare class ClaimError extends Error {
 export type ClaimKind = 'creator' | 'partner';
 /** Lamport costs of a trading fee claim, as bigint. */
 export interface ClaimCosts {
-    /** Signature fees (signers x 5000 lamports; no priority fee), paid by the payer. */
+    /** Signature fees (signers x 5000 lamports) plus the priority fee, if any; paid by the payer. */
     networkFeeLamports: bigint;
     /**
      * Rent of the receiver's coin account, created on the first claim of a pool (paid by the payer,
@@ -56,6 +65,8 @@ export interface ClaimSummary {
      * costs are paid (negative when it costs more than it collects). Base tokens are not valued.
      */
     netLamports: bigint;
+    /** The priority fee of the transaction (price, fee, cap), or null without one. */
+    priorityFee: PriorityFeeQuote | null;
 }
 export type ClaimSkipReason = 'nothing_to_claim' | 'not_worthwhile';
 export interface ClaimTxResult {
@@ -75,7 +86,21 @@ export interface ClaimOptions {
      * than this many lamports (see `isClaimWorthwhile`). Default: never skip a non-empty claim.
      */
     minNetLamports?: bigint;
+    /**
+     * Priority fee read from the cluster for the claim's writable accounts, bounded by this setting
+     * (`{}` = `DEFAULT_PRIORITY_FEE_POLICY`, at most 0.0005 SOL). Default: none.
+     */
+    priority?: PriorityFeeSetting;
 }
+/** Checks `options.priority` before any network call. @throws RangeError. */
+export declare function assertClaimPriority(options: {
+    priority?: PriorityFeeSetting;
+}): void;
+/** The priced compute budget of a claim, or nothing without `priority`. */
+export declare function claimPriorityFee(connection: Connection, instructions: readonly TransactionInstruction[], computeUnitLimit: number, priority: PriorityFeeSetting | undefined): Promise<{
+    quote: PriorityFeeQuote | null;
+    instructions: TransactionInstruction[];
+}>;
 export interface CreatorClaimParams {
     pool: PublicKey;
     /** Pool creator (must match the pool state); signs the claim. */
@@ -163,10 +188,12 @@ export interface PoolCreationFeeClaimSummary {
     alreadyClaimed: boolean;
     /** SOL the receiver gets from the transaction (0 when there is none), lamports. */
     claimableLamports: bigint;
-    /** Signature fees of the transaction (0 when there is none), paid by the payer. */
+    /** Signature fees plus the priority fee of the transaction (0 when there is none). */
     networkFeeLamports: bigint;
     /** `claimableLamports - networkFeeLamports` (0 when there is no transaction). */
     netLamports: bigint;
+    /** The priority fee of the transaction (price, fee, cap), or null without one. */
+    priorityFee: PriorityFeeQuote | null;
 }
 export type PoolCreationFeeSkipReason = 'no_pool_creation_fee' | 'already_claimed';
 export interface PoolCreationFeeClaimTxResult {

package/dist/claims.js

@@ -34,6 +34,12 @@
  * 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';
@@ -41,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 {
@@ -54,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
 // ---------------------------------------------------------------------------------------------
@@ -123,6 +155,7 @@ async function buildTradingClaim(connection, input, options) {
                 existingWsolLamports: 0n,
                 costs: ZERO_COSTS,
                 netLamports: 0n,
+                priorityFee: null,
             },
         };
     }
@@ -189,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;
@@ -212,6 +246,7 @@ async function buildTradingClaim(connection, input, options) {
         existingWsolLamports,
         costs,
         netLamports: receiverQuoteLamports - payerTotalLamports,
+        priorityFee: priority.quote,
     };
     if (options.minNetLamports !== undefined && !isClaimWorthwhile(summary, options.minNetLamports)) {
         return { transaction: null, lastValidBlockHeight: null, skipReason: 'not_worthwhile', summary };
@@ -227,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()}`);
     }
@@ -278,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,
@@ -317,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,
@@ -341,6 +379,7 @@ export async function buildPartnerPoolCreationFeeClaimTx(connection, params, opt
         claimableLamports: 0n,
         networkFeeLamports: 0n,
         netLamports: 0n,
+        priorityFee: null,
     };
     if (partnerShareLamports === 0n || alreadyClaimed) {
         return {
@@ -366,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,
@@ -380,6 +420,7 @@ export async function buildPartnerPoolCreationFeeClaimTx(connection, params, opt
             claimableLamports: partnerShareLamports,
             networkFeeLamports,
             netLamports: partnerShareLamports - networkFeeLamports,
+            priorityFee: priority.quote,
         },
     };
 }

package/dist/config.d.ts

@@ -28,6 +28,7 @@
 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';
+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
@@ -170,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;
@@ -187,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

package/dist/config.js

@@ -32,7 +32,7 @@ import { LaunchpadSpec } from '@forge/shared';
 import { CLIENT_BOUNDS, CLIENT_POOL_CREATION_FEE_LAMPORTS, FEES, LAMPORTS_PER_SOL_BIGINT, SOL_QUOTE_MINT, solToLamports, } from './constants.js';
 import { LaunchCoinError, assertSpecLaunchable } from './launch-metadata.js';
 import { ANTI_SNIPER_FEE_SCHEDULE, FORGE_ACTIVATION_TYPE, FORGE_MIGRATION_SETTINGS, FORGE_TOKEN_SETTINGS, forgeFeeSchedulerParam, } from './settings.js';
-import { computeBudgetInstructions } from './tx.js';
+import { estimatePriorityFee, fixedPriorityFee, priorityFeeInstructions, resolvePriorityFeePolicy, } from './priority-fee.js';
 import { ValidationError, assertValid, validateLaunchpadCoinConfigParams, validateLaunchpadConfigParams, } from './validate.js';
 // ---------------------------------------------------------------------------------------------
 // Settings
@@ -570,6 +570,12 @@ export class CreateConfigError extends Error {
  */
 export async function buildCreateConfigTx(params) {
     const configAddress = params.config instanceof PublicKey ? params.config : params.config.publicKey;
+    if (params.priority !== undefined) {
+        if (params.computeUnitPriceMicroLamports !== undefined) {
+            throw new RangeError('pass either priority or computeUnitPriceMicroLamports, not both');
+        }
+        resolvePriorityFeePolicy(params.priority);
+    }
     const configParams = buildConfigParams(params.spec, params.kind, params.metadataUri !== undefined ? { metadataUri: params.metadataUri } : {});
     if (configAddress.equals(params.payer) ||
         configAddress.equals(configParams.feeClaimer) ||
@@ -588,11 +594,16 @@ export async function buildCreateConfigTx(params) {
     });
     const rentLamports = BigInt(await connection.getMinimumBalanceForRentExemption(client.partner.getProgram().account.poolConfig.size));
     const { blockhash, lastValidBlockHeight } = params.recentBlockhash ?? (await connection.getLatestBlockhash('confirmed'));
+    const priorityFee = params.priority === undefined
+        ? fixedPriorityFee(CREATE_CONFIG_COMPUTE_UNITS, params.computeUnitPriceMicroLamports ?? 0)
+        : await estimatePriorityFee({
+            connection,
+            writableAccounts: [params.payer, configAddress],
+            computeUnitLimit: CREATE_CONFIG_COMPUTE_UNITS,
+            setting: params.priority,
+        });
     const transaction = new Transaction({ feePayer: params.payer, blockhash, lastValidBlockHeight });
-    transaction.add(...computeBudgetInstructions({
-        units: CREATE_CONFIG_COMPUTE_UNITS,
-        microLamports: params.computeUnitPriceMicroLamports ?? 0,
-    }), ...sdkTx.instructions);
+    transaction.add(...priorityFeeInstructions(priorityFee), ...sdkTx.instructions);
     return {
         transaction,
         configAddress,
@@ -600,5 +611,6 @@ export async function buildCreateConfigTx(params) {
         rentLamports,
         lastValidBlockHeight,
         signers: [params.payer, configAddress],
+        priorityFee,
     };
 }

package/dist/constants.d.ts

@@ -45,3 +45,19 @@ export declare const CLIENT_POOL_CREATION_FEE_LAMPORTS: {
     readonly max: bigint;
     readonly allowZero: true;
 };
+/**
+ * Referral fee range of Jupiter Ultra, in bps. The Jupiter Plugin passes `referralFee` as is to
+ * Ultra `/order`, which refuses any value outside 50..255 ("must be between 50 and 255
+ * (inclusive)", checked on 2026-10-17); Jupiter keeps 20% of the fee.
+ * @see https://developers.jup.ag/docs/swap/fees
+ */
+export declare const JUPITER_REFERRAL_FEE_BPS_RANGE: {
+    readonly min: 50;
+    readonly max: 255;
+};
+/**
+ * Returns `bps` when Jupiter Ultra accepts it as a referral fee: a whole number of bps within
+ * `JUPITER_REFERRAL_FEE_BPS_RANGE`. Throws a `RangeError` otherwise: with such a fee Jupiter
+ * refuses every swap, so it must never reach the plugin.
+ */
+export declare function assertJupiterReferralFeeBps(bps: number): number;

package/dist/constants.js

@@ -68,3 +68,23 @@ export const CLIENT_POOL_CREATION_FEE_LAMPORTS = {
     max: solToLamports(CLIENT_BOUNDS.poolCreationFeeSol.max),
     allowZero: CLIENT_BOUNDS.poolCreationFeeSol.allowZero,
 };
+/**
+ * Referral fee range of Jupiter Ultra, in bps. The Jupiter Plugin passes `referralFee` as is to
+ * Ultra `/order`, which refuses any value outside 50..255 ("must be between 50 and 255
+ * (inclusive)", checked on 2026-10-17); Jupiter keeps 20% of the fee.
+ * @see https://developers.jup.ag/docs/swap/fees
+ */
+export const JUPITER_REFERRAL_FEE_BPS_RANGE = { min: 50, max: 255 };
+/**
+ * Returns `bps` when Jupiter Ultra accepts it as a referral fee: a whole number of bps within
+ * `JUPITER_REFERRAL_FEE_BPS_RANGE`. Throws a `RangeError` otherwise: with such a fee Jupiter
+ * refuses every swap, so it must never reach the plugin.
+ */
+export function assertJupiterReferralFeeBps(bps) {
+    const { min, max } = JUPITER_REFERRAL_FEE_BPS_RANGE;
+    if (!Number.isInteger(bps) || bps < min || bps > max) {
+        throw new RangeError(`Jupiter referral fee must be a whole number of bps between ${min} and ${max} ` +
+            `(Jupiter Ultra refuses any other value), got ${String(bps)}`);
+    }
+    return bps;
+}