pumpfun-bonkfun-bot_github/docs/pumpfun-protocol.md

Pump.fun protocol notes

The IDLs under idl/ are vendored verbatim from github.com/pump-fun/pump-public-docs (idl/pump.json → pump_fun_idl.json, pump_amm.json → pump_swap_idl.json, pump_fees.json). Refresh them from upstream rather than hand-editing.

Quote assets and the v2 trade instructions (current path)

• pump.fun supports quote assets other than SOL, and no longer just SOL and USDC. BondingCurve.quote_mint is Pubkey::default() (all zeros) for SOL-paired coins; USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) is one whitelisted entry in Global, but coins paired with Token-2022 quote mints are live on chain too. Legacy buy/sell cannot trade non-SOL-paired coins at all.
• Two registries are live and neither contains the other. A QuoteControl account (PDA ["quote-control"]) carries its own mint list, which is how a coin pairs with a mint Global never lists. But Global.whitelisted_quote_mints is not merely a subset: USDC is in Global and not in QuoteControl, so validating against either alone refuses a mint the program accepts. Their opening reserves come from different fields too — a QuoteControl entry carries its own, while a Global-only mint takes Global.initial_virtual_quote_reserves. Error 6064 accepts SPL Token or Token-2022.
• Mayhem mode and a non-SOL quote asset are mutually exclusive. The program rejects the pairing with MayhemModeQuoteMintNotAllowed (6071), so a mayhem coin is always SOL-paired and can never carry a creator fee.
• The opening reserve is per quote mint, by orders of magnitude. Across the QuoteControl entries the figure runs from the low millions to the high trillions of raw units, so no default approximates a missing one — an unlisted mint has to be refused rather than priced.
• The quote mint's token program is resolved from chain, not assumed. resolve_quote_token_program (src/core/pubkeys.py) reads a mint's owner once — pre-seeded with WSOL/USDC so those stay free — and caches it for the process; cached_quote_token_program is the hot-path read used by event parsing and address resolution. The bot warms the cache at startup for every configured quote mint, so extreme_fast_mode's zero-RPC contract still holds.
• The decimals come from the same read. Amounts like max_sol_cost and min_sol_output are in the quote mint's raw units, so assuming 9 decimals for a 6-decimal mint overstates the cap by 1000x and effectively disables slippage protection. getAccountInfo returns the owner and the mint data together, so decimals cost no extra call; they are cached alongside the token program and pre-seeded for WSOL (9) and USDC (6). A quote mint whose decimals cannot be resolved fails at startup rather than silently mis-scaling a trade. The decimals byte sits at offset 44 in both SPL Token and Token-2022 mints — extensions are appended after the base struct and never move it.
• The bot uses buy_v2 (27 accounts) and sell_v2 (26 accounts). Every account is mandatory and the order is identical for every coin — whatever quote mint, mayhem or not, cashback or not. sell_v2 is buy_v2 minus global_volume_accumulator. Layouts live in _BUY_V2_ACCOUNTS / _SELL_V2_ACCOUNTS in platforms/pumpfun/instruction_builder.py and are machine-checked against the IDL by tests/regression/verify_v2_account_layout.py.
• v2 args carry no track_volume OptionBool (24-byte data: discriminator + two u64). Volume tracking is unconditional now that user_volume_accumulator is mandatory. max_sol_cost/min_sol_output are in the quote mint's raw units — lamports for SOL, 1e-6 for USDC.
• Even for SOL-paired coins you must pass wrapped SOL as quote_mint, not Pubkey::default(). Transfers still happen in native SOL, and the associated_quote_* accounts are only seed-constrained — do not create the user's WSOL ATA, it would burn ~0.002 SOL of rent for nothing.
• Fee recipients: 24 total, in three sets of 8 (NORMAL_FEE_RECIPIENTS, RESERVED_FEE_RECIPIENTS for mayhem coins, BUYBACK_FEE_RECIPIENTS). Every v2 buy/sell needs a fee_recipient and a buyback_fee_recipient, randomized per tx to spread program throughput.
• sharing_config (PDA ["sharing-config", base_mint]) lives under the pump fees program, not the pump program. Easy to derive against the wrong program.

BondingCurve account layout

• create_v2 allocates 125 bytes. The 36 reserved padding bytes are gone and three fields follow quote_mint: creator_fee_bps (u64), can_edit_creator_fee (bool, reserved — always false) and is_holder_reward (bool). Every field the bot reads sits before where the padding used to start.

• extend_account can grow a curve past 125 bytes, and a length allowlist is whack-a-mole against that. Don't filter on account length — decode any length at or above 125 the same way:

  Length	What it is
  125 bytes	What create_v2 allocates
  151 bytes	The old allocation size; still reachable via extend_account
  256 bytes	A rarer extend_account target

  tests/regression/verify_curve_account_sizes.py checks that all three decode and that the graduating-token examples don't filter on length.

• The SOL-named fields were renamed: virtual_sol_reserves → virtual_quote_reserves, real_sol_reserves → real_quote_reserves. The curve manager exposes the old names as aliases, so callers keep working for SOL-paired coins — but anything doing arithmetic must scale by the quote mint's decimals (quote_units_per_token), not a hardcoded 1e9.

• PumpSwap Pool gained a trailing virtual_quote_reserves: i128 (16 bytes, offset 245). Pool fields end at 261; live accounts are 301 bytes with trailing padding. Quote against effective reserves: pool_quote_token_account.amount + virtual_quote_reserves. Upstream's release note claims it is 0 on all pools — that is out of date, and quoting off the raw vault balance under-prices any pool carrying some. It is i128, not u64; reading 8 bytes works only while the high half is zero.

• pump-amm has no buy_v2/sell_v2. The AMM instruction names are unchanged; only the pool layout and quoting moved.

• Pool.coin_creator tells you whether a pool is canonical, i.e. graduated from a pump.fun bonding curve. It is Pubkey::default() on every other pool. Two things follow:

  • pool-v2 is sent only for a canonical pool. The buyback fee recipient and its quote ATA are always the last two accounts and are read positionally, so adding pool-v2 on a non-canonical pool shifts them and the program rejects the pool-v2 PDA with BuybackFeeRecipientNotAuthorized (6053). Upstream's BREAKING_FEE_RECIPIENT.md says the pair goes after pool-v2 "for coins that graduate from bonding curve", and separately that the pair is needed either way — the qualifier is the whole rule. Account counts: buy 26/27 canonical, 25/26 not; sell 24/26 canonical, 23/25 not.
  • Do not assume 6 base-token decimals. Every graduated coin has 6, but non-canonical pools routinely carry 9, and a factor of 1000 scales the quote and the slippage floor together, so a sell reverts ExceededSlippage (6004) rather than just mispricing. Resolve the mint's owner and decimals from the same getAccountInfo, as get_mint_info does.

• The vendored pump_swap_idl.json under-reports these accounts and is byte-identical to upstream, so it cannot be the reference: it lists 23 for buy against 25-26 on chain, and 21 for sell against 23-26.

Coin creation

• create_v2 takes eight args: name (str), symbol (str), uri (str), creator (pubkey), is_mayhem_mode (bool), is_cashback_enabled (OptionBool), creator_fee_bps (OptionU64), is_holder_reward (OptionBool). OptionBool and OptionU64 are single-field Anchor structs with no presence tag — each serializes as its bare inner value, 1 byte and 8 bytes, never a discriminated Option.
• is_cashback_enabled = [true] is rejected with 6082 CashbackDeprecated: create_v2 can no longer mint a new cashback coin. Existing cashback coins keep trading, accruing and claiming, so every cashback code path in this repo (the legacy sell path's cashback branch, is_cashback_coin on TokenInfo) stays live and must not be treated as dead.
• The trailing args are positional, not independently optional. Reaching is_holder_reward (arg 8) means sending is_cashback_enabled (6) and creator_fee_bps (7) first, even when both are false/zero. The committed fixtures show three wire lengths: all trailing args omitted (0 bytes after is_mayhem_mode), is_cashback_enabled only (1 byte), and is_cashback_enabled + creator_fee_bps (9 bytes); the three-arg form is sent too. Because the args are positional, a shorter form cannot have set a later one — a truncated instruction is proof the coin is not holder-reward, not merely silence about it, which is what lets a pre-execution listener classify every coin. A decoder that reads a fixed number of trailing bytes raises IndexError on the shorter forms, so decode defensively and report a missing arg as unset; utils/idl_parser.py does, and tests/regression/verify_create_v2_optional_args.py checks it.
• create_v2 accounts 1-16 are in the IDL; accounts 17-20 are remaining accounts (quote_mint, associated_quote_bonding_curve, quote_token_program, quote_control), all four or none. The fourth is the QuoteControl PDA (["quote-control"]), and it is easy to miss because the IDL does not list any of them. They are appended for SOL-paired coins too, carrying wrapped SOL, so a 20-account create_v2 is not proof of a non-SOL quote asset. Read quote_mint off the curve instead.
• Omitting them is accepted. A 16-account create_v2 lands and produces a SOL-paired coin, so nothing tells you the accounts were missing. What it also does is silently drop creator_fee_bps, because:
• A creator fee is applied only on a coin priced in a QuoteControl mint. Anywhere else the program accepts creator_fee_bps, emits CreateEvent.creator_fee_bps = 0 and stores 0 on the curve, with no error. Measured on mainnet: the fee lands on a QuoteControl mint whether that mint is SPL Token or Token-2022, and does not land on wrapped SOL or on USDC — which the older Global.whitelisted_quote_mints carries and QuoteControl does not. So the deciding property is registry membership, not the token program and not merely "something other than SOL".
• The associated bonding curve is an ordinary ATA, so its address depends on which token program owns the mint: Token2022 for create_v2 coins, SPL Token for legacy create. Deriving with the wrong program returns a valid-looking address that does not exist on chain.
• extreme_fast_mode skips the curve-state price fetch. Whether it also reads the curve for mayhem/cashback/creator/quote_mint depends on provenance (see the Invariants in CLAUDE.md): CreateEvent-sourced tokens (state_from_event) trade on the event data with zero RPC calls, while instruction-parsed and incomplete-event tokens refresh from chain — the wrong quote mint means spending the wrong balance entirely. Event parsers populate quote_mint from CreateEvent, which carries quote_mint and virtual_quote_reserves as trailing fields.

Holder reward coins

create_v2 can set is_holder_reward so the creator fee is set aside for holders instead of paid to a creator wallet. On such a coin BondingCurve.creator holds a pump.fun address rather than the actual creator's; the creator_vault derivation is unchanged and still correct, since it derives from whatever creator the curve carries.

That substituted address is PDA(["holder-rewards", mint]) under the pump program — the same account the IDL declares for holder_rewards on distribute_fee_to_holders, which is how the ordinary creator-vault route delivers the fee to the holder pool without a second payout path. It depends on nothing but the mint, so args.creator being unusable on these coins costs no RPC call to work around: PumpFunAddresses.find_holder_reward_creator derives it. No trade instruction changed: buy, sell, buy_v2, sell_v2 and the PumpSwap instructions take identical accounts and arguments either way. Global.is_holder_reward_enabled can switch creation off globally.

TokenInfo.is_holder_reward and TokenInfo.creator_fee_bps surface this to the bot — see the field comments on TokenInfo in src/interfaces/core.py. SOL- and USDC-paired coins keep creator_fee_bps at 0; custom-pair coins carry a nonzero value.

Legacy instructions (fallback only)

Retained behind PumpFunInstructionBuilder(..., use_legacy_instructions=True). The IDL under-reports these: buy is 18 accounts on-chain (IDL lists 16) and sell is 16 non-cashback / 17 cashback (IDL lists 14). The extras are bonding-curve-v2 (PDA ["bonding-curve-v2", mint]) followed by a mutable buyback fee recipient; the cashback sell path also inserts user_volume_accumulator before bonding-curve-v2. On the PumpSwap side the legacy path needs pool-v2 (PDA ["pool-v2", base_mint] under pump-amm) — without it pump-amm throws AnchorError 6023 (Overflow) after the transfers complete, a misleading code for a missing account. Prefer v2 — it is the interface pump.fun maintains.