x402agent/pump-solana-architecture

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