pump-solana-architecture

name	pump-solana-architecture
description	Design and derive Program Derived Addresses (PDAs) and account layouts across the Pump ecosystem's four Solana programs — global singletons, per-token accounts, per-user accumulators, and cross-program coordination patterns.
metadata	{"openclaw":{"homepage":"https://github.com/8bitsats/pump-fun-sdk"}}

Solana Program Architecture — PDAs, Accounts & Multi-Program Coordination

Design, derive, and manage Program Derived Addresses (PDAs) and account layouts across the Pump ecosystem's four Solana programs with cross-program invocation patterns.

On-Chain Programs

Program	ID	Purpose
Pump	6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P	Bonding curve operations
PumpAMM	pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA	Graduated AMM pools
PumpFees	pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ	Fee sharing
Mayhem	MAyhSmzXzV1pTf7LsNkrNwkWKTo4ougAJ1PPg47MD4e	Mayhem-mode tokens

PDA Categories

Global Singletons

• GLOBAL_PDA — ["global"] on Pump — protocol-wide config
• FEE_CONFIG_PDA — ["fee-config"] on Pump — tiered fee settings
• GLOBAL_VOLUME_ACCUMULATOR_PDA — ["global_volume_accumulator"] — protocol-wide volume

Per-Token PDAs

• bondingCurvePda(mint) — ["bonding-curve", mint] — token bonding curve state
• bondingCurveTokenAccountPda(mint) — ["bonding-curve-token-account", mint]
• feeSharingConfigPda(mint) — ["sharing-config", mint] on PumpFees
• canonicalPumpPoolPda(mint) — AMM pool for graduated token

Per-User PDAs

• creatorVaultPda(creator) — ["creator-vault", creator] on Pump
• ammCreatorVaultPda(creator) — ["creator_vault", creator] on PumpAMM
• userVolumeAccumulatorPda(user) — ["user_volume_accumulator", user]

Mayhem PDAs

• mayhemMetadataPda(mint) — ["mayhem_metadata", mint] on Mayhem
• mayhemWsolPda() — ["mayhem_wsol"] on Mayhem

BothPrograms Pattern

Many operations span both Pump and PumpAMM — the SDK provides aggregation:

Method	Description
getCreatorVaultBalanceBothPrograms	Sum balance from both vaults
collectCoinCreatorFeeInstructions	Collect from both programs
fetchUserVolumeAccumulatorTotalStats	Aggregate volume across programs
claimTokenIncentivesBothPrograms	Claim rewards from both

Token Lifecycle Cross-Program Flow

Pump Program                    PumpAMM Program
┌─────────────┐                 ┌──────────────────┐
│ create      │                 │                  │
│ buy / sell  │ ── migrate ──►  │ AMM trading      │
│ graduate    │                 │ fee collection   │
└─────────────┘                 └──────────────────┘
       │                                │
       └──── PumpFees Program ──────────┘
             (fee sharing)

Account Extension

Bonding curve accounts may need extension to BONDING_CURVE_NEW_SIZE (151 bytes) before certain operations:

const extendIx = await PUMP_SDK.extendAccountInstruction({
    bondingCurvePda: bondingCurvePda(mint),
    bondingCurveAccountInfo
});

Patterns to Follow

• Use findProgramAddressSync for all PDA derivation — never manually compute bump seeds
• Group related account fetches into a single getMultipleAccountsInfo call
• Always check account existence before decoding — use nullable decoders
• Extend accounts before migration or setCreator operations

Common Pitfalls

• Creator vault PDA seeds differ: "creator-vault" (Pump, hyphen) vs "creator_vault" (AMM, underscore)
• canonicalPumpPoolPda uses the external pump-swap-sdk, not the Pump program
• Mayhem PDAs are on a separate program (MAyhSm...)
• PDA derivation failures indicate an invalid bump — the address is off the Ed25519 curve