/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/nirholas/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 grew to `BONDING_CURVE_NEW_SIZE` (166 bytes) in the October 2026 upgrade. The program grows a pre-upgrade curve on its first new-style trade. An instruction that reads the new fields without growing the account first needs:

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

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 a pre-upgrade account only in front of an instruction that does not grow it itself

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