atomic-v2-migration — V1 → V2 USDC pool migration assistant
Pump.fun shipped a V2 program upgrade in May 2026 that changes the quote-mint from SOL to USDC on new launches, adds accounts to existing instructions, and modifies event layouts. Code written against V1 will fail in distinct, diagnosable ways. This skill is the navigation aid: identifies which docs to read for which symptom, lists the breaking changes by impact area, and recommends a migration order.
The repo already contains a comprehensive reference in docs/v2-usdc-rollout/ — this skill points there rather than duplicating it. Treat this skill as the index + decision guide for that reference set.
Decision flow — "is my code affected?"
| Question |
If YES |
| Does your code parse pump.fun events (Create, Buy, Sell, Swap, Complete)? |
Affected. See 02-event-layouts.md |
| Does your code build pump.fun instructions directly (not via pump-sdk)? |
Affected. See 01-discriminators.md |
| Does your code use pump-sdk at a version < 1.30? |
Probably affected. Bump to ≥ 1.30; check the changelog |
| Does your code assume the quote-mint is SOL (e.g. parses lamports from "amount in")? |
Affected. See 03-quote-mint-handling.md |
| Does your code consume creator-fee payouts? |
Affected — V2 payouts can be USDC, not SOL. Check downstream wallet handling |
Does your code only launch / buy / collect via the scripts in src/ (this repo)? |
Mostly safe — the scripts have been updated. But read 04-pumpkit-changes.md for caveats |
| Does your code subscribe to pump.fun program logs and decode them? |
Affected (event layouts changed). See 02-event-layouts.md |
Does your code only audit wallets (check-pump-funding)? |
Not affected — provenance check doesn't depend on pool layout |
What changed (high-level summary)
V2 is not a hard fork — V1 coins still trade on the V1 program. V2 is a new program with new instructions/events. The breaking points for migrating code:
- New quote-mint. V1 used SOL as the quote-mint of every pump.fun coin. V2 introduces USDC-quoted coins. Any code that hardcodes the quote-mint as
So111... or expects amounts in lamports will mis-handle V2.
- New discriminators. Anchor-style instruction and event discriminators changed for several instructions, with V2-specific variants (e.g.
createV2, swapV2). Code that hardcodes the V1 discriminator bytes will silently skip V2 events. Full table: 01-discriminators.md.
- New required accounts. Several instructions added accounts (e.g.
BuybackFeeRecipient on buy in a V1 patch; further accounts in V2). pump-sdk < 1.30 emits the old account set; the program rejects with MissingAccount.
- Event layouts changed. V2 events have additional fields (quote-mint, USDC-specific math) and re-ordered fields in some cases. Byte-level layouts in 02-event-layouts.md.
- Creator-fee payout currency. V2 USDC-quoted coins pay creator fees in USDC, not SOL. Downstream code that assumed SOL payouts to the creator vault will see USDC ATAs accumulate instead.
- Pool-state PDA derivation may have changed for V2-USDC pools. Check the rollout reference if you derive PDAs manually.
Migration order
If you maintain a downstream codebase that consumes pump.fun events or builds pump.fun txs, migrate in this order. Each step is gated by tests in the next.
- Bump pump-sdk to ≥ 1.30 (or the latest at the time you migrate). Run typecheck. Fix any new required arguments.
- Update discriminator tables if you hardcode them. Anchor-style code typically uses the SDK's generated coder — that's safe if the SDK is bumped. Raw byte-level decoders need updating.
- Add a quote-mint branch to every parser that handles amounts: if
quoteMint === USDC, treat as USDC decimals (6); if SOL, lamports (9). 03-quote-mint-handling.md has the conversion patterns.
- Update event handlers to read the new fields. Old handlers will work on V1 events but ignore V2 events (or worse, mis-parse them).
- Update downstream display — UIs, dashboards, alerts. Showing a USDC amount as "SOL" misleads users.
- Regression-test against fixtures. 08-testing-strategy.md describes the fixture set: V1 events, V2-SOL events, V2-USDC events, edge cases.
- Audit creator-fee handlers. If you have downstream auto-sweeping or accounting on creator vaults, ensure USDC ATAs are recognized.
- Bump dependent libraries. See 05-cross-repo-audit.md for the user's other pump-fun repos and their V2 status.
Symptoms → fix
| Symptom |
Cause |
Fix |
buy ix builds but tx fails with MissingAccount |
pump-sdk < 1.30 missing BuybackFeeRecipient or other V2 account |
Bump pump-sdk; or route via Jupiter (atomic-buy) |
Event decoder returns null or undefined for fresh launches |
Hardcoded V1 discriminator filters out V2 events |
Update discriminator table per 01-discriminators.md |
| "Amount in" displayed as 1e9× too small |
Code divides by 1e9 (SOL) but amount is in USDC (1e6) |
Branch on quote-mint; use correct decimals |
| Creator vault is empty but coin has trade volume |
Coin is V2-USDC; fees pay to USDC ATA, not SOL |
Sweep the USDC ATA, not the SOL vault PDA |
collectCoinCreatorFee lands but transfers 0 lamports |
Same as above — wrong currency assumption |
Update the collector to handle both currencies |
| Event has unexpected extra bytes after decode |
V2 event has new trailing fields; old layout misses them |
Extend the layout struct per 02-event-layouts.md |
| Dashboard shows V2 launches as "no quote mint" or "unknown" |
Code defaults quote-mint to SOL when field is missing in V1 events; V2 events have it explicitly and the parser doesn't read it |
Read the new quoteMint field |
Reference index
The rollout reference under docs/v2-usdc-rollout/ is exhaustive. Quick navigation:
| File |
What it covers |
| 00-context.md |
Why V2, what changed at the program level |
| 01-discriminators.md |
Canonical V1 + V2 ix and event discriminators |
| 02-event-layouts.md |
Byte-by-byte event record layouts |
| 03-quote-mint-handling.md |
Parser, conversion, and display patterns for mixed-currency pools |
| 04-pumpkit-changes.md |
What changed in pumpkit specifically |
| 05-cross-repo-audit.md |
V2 readiness of related repos (pump-fun-sdk, pump-swap-sdk, pumpfun-claims-bot, pumpfun-creator-rewards, three.ws) |
| 06-prompts-summary.md |
Summary of the executor prompts under prompts/v2-usdc-rollout/ |
| 07-migration-guide.md |
Per-scenario recipes |
| 08-testing-strategy.md |
Fixtures, regressions, CI matrix |
| 09-glossary.md |
Terminology: quote-mint, bonding curve, graduation, BuybackFeeRecipient, etc. |
Executor prompts (for running migration agents):
When you don't need to migrate
If your code only:
- Audits wallet provenance via
check-pump-funding.ts — unaffected.
- Runs this repo's scripts (
npm run launch / collect / buy / rescue / consolidate / distribute) — the scripts have been updated. Read 04-pumpkit-changes.md for any version-specific caveats.
- Manipulates Solana primitives below pump.fun (raw SPL transfers, SOL transfers, ATA creation) — unaffected.
If you exclusively trade on V1 coins (i.e. coins that launched before May 2026 and never migrated) and your tooling doesn't touch V2 coins, you can defer migration. But V1 launches are now rare; the V1 ecosystem is decaying.
Related
1---2name: atomic-v2-migration3description: Use when the user wants to migrate code, scripts, or downstream consumers from pump.fun's V1 (SOL-pool) layout to V2 (USDC-pool) layout, or is debugging an issue caused by the V2 USDC rollout. Triggers on "V2 USDC", "pump V2", "V1 to V2 migration", "USDC pool", "quote mint", "new discriminator", "BuybackFeeRecipient", "event layout changed", "pump-sdk doesn't decode", "creator fees in USDC now", or any V1→V2 migration question. The rollout happened 2026-05; code written before that date may need updates.4---56# atomic-v2-migration — V1 → V2 USDC pool migration assistant78Pump.fun shipped a V2 program upgrade in May 2026 that changes the quote-mint from SOL to USDC on new launches, adds accounts to existing instructions, and modifies event layouts. Code written against V1 will fail in distinct, diagnosable ways. This skill is the navigation aid: identifies which docs to read for which symptom, lists the breaking changes by impact area, and recommends a migration order.910The repo already contains a comprehensive reference in [`docs/v2-usdc-rollout/`](../../docs/v2-usdc-rollout/) — this skill points there rather than duplicating it. Treat this skill as the index + decision guide for that reference set.1112## Decision flow — "is my code affected?"1314| Question | If YES |15|---|---|16| Does your code parse pump.fun **events** (Create, Buy, Sell, Swap, Complete)? | Affected. See [02-event-layouts.md](../../docs/v2-usdc-rollout/02-event-layouts.md) |17| Does your code build pump.fun **instructions** directly (not via pump-sdk)? | Affected. See [01-discriminators.md](../../docs/v2-usdc-rollout/01-discriminators.md) |18| Does your code use **pump-sdk** at a version < 1.30? | Probably affected. Bump to ≥ 1.30; check the changelog |19| Does your code assume the **quote-mint is SOL** (e.g. parses lamports from "amount in")? | Affected. See [03-quote-mint-handling.md](../../docs/v2-usdc-rollout/03-quote-mint-handling.md) |20| Does your code consume creator-fee payouts? | Affected — V2 payouts can be USDC, not SOL. Check downstream wallet handling |21| Does your code only **launch / buy / collect** via the scripts in `src/` (this repo)? | Mostly safe — the scripts have been updated. But read [04-pumpkit-changes.md](../../docs/v2-usdc-rollout/04-pumpkit-changes.md) for caveats |22| Does your code subscribe to pump.fun program logs and decode them? | Affected (event layouts changed). See [02-event-layouts.md](../../docs/v2-usdc-rollout/02-event-layouts.md) |23| Does your code only audit wallets (`check-pump-funding`)? | Not affected — provenance check doesn't depend on pool layout |2425## What changed (high-level summary)2627V2 is not a hard fork — V1 coins still trade on the V1 program. V2 is a new program with new instructions/events. The breaking points for migrating code:28291. **New quote-mint.** V1 used SOL as the quote-mint of every pump.fun coin. V2 introduces USDC-quoted coins. Any code that hardcodes the quote-mint as `So111...` or expects amounts in lamports will mis-handle V2.302. **New discriminators.** Anchor-style instruction and event discriminators changed for several instructions, with V2-specific variants (e.g. `createV2`, `swapV2`). Code that hardcodes the V1 discriminator bytes will silently skip V2 events. Full table: [01-discriminators.md](../../docs/v2-usdc-rollout/01-discriminators.md).313. **New required accounts.** Several instructions added accounts (e.g. `BuybackFeeRecipient` on `buy` in a V1 patch; further accounts in V2). pump-sdk < 1.30 emits the old account set; the program rejects with `MissingAccount`.324. **Event layouts changed.** V2 events have additional fields (quote-mint, USDC-specific math) and re-ordered fields in some cases. Byte-level layouts in [02-event-layouts.md](../../docs/v2-usdc-rollout/02-event-layouts.md).335. **Creator-fee payout currency.** V2 USDC-quoted coins pay creator fees in USDC, not SOL. Downstream code that assumed SOL payouts to the creator vault will see USDC ATAs accumulate instead.346. **Pool-state PDA derivation may have changed** for V2-USDC pools. Check the rollout reference if you derive PDAs manually.3536## Migration order3738If you maintain a downstream codebase that consumes pump.fun events or builds pump.fun txs, migrate in this order. Each step is gated by tests in the next.39401. **Bump pump-sdk to ≥ 1.30** (or the latest at the time you migrate). Run typecheck. Fix any new required arguments.412. **Update discriminator tables** if you hardcode them. Anchor-style code typically uses the SDK's generated coder — that's safe if the SDK is bumped. Raw byte-level decoders need updating.423. **Add a quote-mint branch** to every parser that handles amounts: if `quoteMint === USDC`, treat as USDC decimals (6); if `SOL`, lamports (9). [03-quote-mint-handling.md](../../docs/v2-usdc-rollout/03-quote-mint-handling.md) has the conversion patterns.434. **Update event handlers** to read the new fields. Old handlers will work on V1 events but ignore V2 events (or worse, mis-parse them).445. **Update downstream display** — UIs, dashboards, alerts. Showing a USDC amount as "SOL" misleads users.456. **Regression-test against fixtures.** [08-testing-strategy.md](../../docs/v2-usdc-rollout/08-testing-strategy.md) describes the fixture set: V1 events, V2-SOL events, V2-USDC events, edge cases.467. **Audit creator-fee handlers.** If you have downstream auto-sweeping or accounting on creator vaults, ensure USDC ATAs are recognized.478. **Bump dependent libraries.** See [05-cross-repo-audit.md](../../docs/v2-usdc-rollout/05-cross-repo-audit.md) for the user's other pump-fun repos and their V2 status.4849## Symptoms → fix5051| Symptom | Cause | Fix |52|---|---|---|53| `buy` ix builds but tx fails with `MissingAccount` | pump-sdk < 1.30 missing `BuybackFeeRecipient` or other V2 account | Bump pump-sdk; or route via Jupiter ([atomic-buy](../buy/SKILL.md)) |54| Event decoder returns `null` or `undefined` for fresh launches | Hardcoded V1 discriminator filters out V2 events | Update discriminator table per [01-discriminators.md](../../docs/v2-usdc-rollout/01-discriminators.md) |55| "Amount in" displayed as 1e9× too small | Code divides by 1e9 (SOL) but amount is in USDC (1e6) | Branch on quote-mint; use correct decimals |56| Creator vault is empty but coin has trade volume | Coin is V2-USDC; fees pay to USDC ATA, not SOL | Sweep the USDC ATA, not the SOL vault PDA |57| `collectCoinCreatorFee` lands but transfers 0 lamports | Same as above — wrong currency assumption | Update the collector to handle both currencies |58| Event has unexpected extra bytes after decode | V2 event has new trailing fields; old layout misses them | Extend the layout struct per [02-event-layouts.md](../../docs/v2-usdc-rollout/02-event-layouts.md) |59| Dashboard shows V2 launches as "no quote mint" or "unknown" | Code defaults quote-mint to SOL when field is missing in V1 events; V2 events have it explicitly and the parser doesn't read it | Read the new `quoteMint` field |6061## Reference index6263The rollout reference under [`docs/v2-usdc-rollout/`](../../docs/v2-usdc-rollout/) is exhaustive. Quick navigation:6465| File | What it covers |66|---|---|67| [00-context.md](../../docs/v2-usdc-rollout/00-context.md) | Why V2, what changed at the program level |68| [01-discriminators.md](../../docs/v2-usdc-rollout/01-discriminators.md) | Canonical V1 + V2 ix and event discriminators |69| [02-event-layouts.md](../../docs/v2-usdc-rollout/02-event-layouts.md) | Byte-by-byte event record layouts |70| [03-quote-mint-handling.md](../../docs/v2-usdc-rollout/03-quote-mint-handling.md) | Parser, conversion, and display patterns for mixed-currency pools |71| [04-pumpkit-changes.md](../../docs/v2-usdc-rollout/04-pumpkit-changes.md) | What changed in pumpkit specifically |72| [05-cross-repo-audit.md](../../docs/v2-usdc-rollout/05-cross-repo-audit.md) | V2 readiness of related repos (pump-fun-sdk, pump-swap-sdk, pumpfun-claims-bot, pumpfun-creator-rewards, three.ws) |73| [06-prompts-summary.md](../../docs/v2-usdc-rollout/06-prompts-summary.md) | Summary of the executor prompts under `prompts/v2-usdc-rollout/` |74| [07-migration-guide.md](../../docs/v2-usdc-rollout/07-migration-guide.md) | Per-scenario recipes |75| [08-testing-strategy.md](../../docs/v2-usdc-rollout/08-testing-strategy.md) | Fixtures, regressions, CI matrix |76| [09-glossary.md](../../docs/v2-usdc-rollout/09-glossary.md) | Terminology: quote-mint, bonding curve, graduation, BuybackFeeRecipient, etc. |7778Executor prompts (for running migration agents):7980- [01-pump-fun-sdk.md](../../prompts/v2-usdc-rollout/01-pump-fun-sdk.md) — migrate the upstream SDK81- [02-pump-swap-sdk.md](../../prompts/v2-usdc-rollout/02-pump-swap-sdk.md) — migrate the swap SDK82- [03-pumpfun-claims-bot.md](../../prompts/v2-usdc-rollout/03-pumpfun-claims-bot.md) — port the claims bot83- [04-pumpfun-creator-rewards.md](../../prompts/v2-usdc-rollout/04-pumpfun-creator-rewards.md) — update creator-rewards display84- [05-three-ws-sync.md](../../prompts/v2-usdc-rollout/05-three-ws-sync.md) — re-sync vendored files8586## When you don't need to migrate8788If your code only:89- Audits wallet provenance via `check-pump-funding.ts` — unaffected.90- Runs this repo's scripts (`npm run launch / collect / buy / rescue / consolidate / distribute`) — the scripts have been updated. Read [04-pumpkit-changes.md](../../docs/v2-usdc-rollout/04-pumpkit-changes.md) for any version-specific caveats.91- Manipulates Solana primitives below pump.fun (raw SPL transfers, SOL transfers, ATA creation) — unaffected.9293If you exclusively trade on V1 coins (i.e. coins that launched before May 2026 and never migrated) and your tooling doesn't touch V2 coins, you can defer migration. But V1 launches are now rare; the V1 ecosystem is decaying.9495## Related9697- [atomic-buy](../buy/SKILL.md) — uses Jupiter to dodge most V1/V2 SDK drift98- [atomic-launch](../launch/SKILL.md) — `createV2` is the post-migration launch path99- [atomic-bundle-debug](../bundle-debug/SKILL.md) — for `MissingAccount`-style migration symptoms100- [docs/v2-usdc-rollout/](../../docs/v2-usdc-rollout/) — full reference101- [prompts/v2-usdc-rollout/](../../prompts/v2-usdc-rollout/) — executor prompts
nirholas