@gabox-labs/sdk 0.1.1 → 0.6.0

package/CHANGELOG.md

@@ -3,7 +3,255 @@
 All notable changes to `@gabox-labs/sdk`. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project uses [Semantic Versioning](https://semver.org/) with the `0.x` rule from `CONTRIBUTING.md`.
 
-## [Unreleased]
+## [0.6.0] - 2026-09-18
+
+The venue moved from Pump and PumpSwap to Raydium LaunchLab and Raydium CPMM. The program changed
+with it, so the IDL changed: this is a breaking release for every caller. It matches the devnet
+program deployed at slot `500223264`, and a live devnet run exercised the whole life of one coin.
+
+### Changed
+
+- **Breaking.** A Gabox coin is now created on Raydium LaunchLab and graduates into a Raydium CPMM
+  pool. `createMachine` builds LaunchLab's `initialize_v2` instead of Pump's `create_v2`, with the
+  pinned launch shape: 6 decimals, 1,000,000,000 coins, 793,100,000 sold on the curve, 85 SOL raised
+  on mainnet or 3 SOL on devnet, migrate into CPMM, no vesting, the CPMM creator fee paid in WSOL.
+  The creator picks only the name, the symbol, the URI and the prize table.
+- **Breaking.** Both venues settle in wrapped SOL, and no flow settles in native SOL any more. Every
+  builder now creates the wallet's WSOL account, wraps the lamports its trade needs, and closes the
+  account afterwards. That close also unwraps any WSOL the wallet already held.
+- **Breaking.** `buyPack` takes `{ mint, purchaser, maxQuoteIn, minMaximum, maxNativeDebit, venue?,
+  seq? }`. `maxTotalQuoteDebit` is gone, because there is no Gabox fee to cover.
+- **Breaking.** `createMachine` lost `feeBps`, `quote`, `feeRecipientIndex` and
+  `buybackRecipientIndex`. `initialize_pool` takes `(tiers, max_seed_quote_in,
+  max_seed_native_debit, extra_seed_tokens)`.
+- **Breaking.** `Pool` lost `tokenProgram`, `quoteTokenProgram` and `feeBps`. Both venues use classic
+  SPL Token, and Gabox charges nothing. `Pool` also has a new discriminator, so a pool from the Pump
+  build now fails to decode rather than being read with shifted fields.
+- **Breaking.** `PoolCreated`, `PackBought` and `TokensSold` lost every fee field.
+- **Breaking.** `vaultAddress(mint)` and `associatedTokenAddress(owner, mint)` no longer take a token
+  program. `fetchVaultBalance(client, mint)` lost its third argument.
+- `PackOffer` lost `feeBps`, `creatorFeeQuote`, `packFeeQuote`, `quoteTokenProgram` and
+  `nativeOnPumpCurve`. `quoteAmount` is the whole pack price, the venue's fees included, and `venue`
+  is now `'launchlab'` or `'cpmm'`.
+- `createClient({ cluster })` now decides every Raydium address. Mainnet and devnet run different
+  Raydium deployments, so nothing Raydium is a module constant any more; `raydiumIds(cluster)` gives
+  one cluster's set.
+
+### Added
+
+- `src/raydium/`, replacing `src/pump/`, exported as the `raydium` namespace and as
+  `@gabox-labs/sdk/raydium`.
+- `raydium.curve`: exact bigint ports of Raydium's own price math, for both venues. `initialCurve`
+  reproduces the starting reserves Raydium publishes for the Gabox launch shape, to the base unit.
+- `raydium.claimCreatorFee(client, { creator })` collects the LaunchLab creator fee for every coin a
+  wallet launched, and `raydium.collectCreatorFee(client, { mint, creator })` collects one graduated
+  coin's CPMM creator fee. Both close the WSOL account, so the creator receives SOL.
+  `raydium.fetchCreatorFees` reads what is owed in both places.
+- `raydium.cpmmCreatorFeeShare(cpmm, creator, ammConfig)` derives
+  `PDA(["creator_fee_share", creator, amm_config])`. `collect_creator_fee` takes that account after
+  the fourteen Raydium's mainnet IDL lists. The IDL snapshot is CPMM 0.2.0 and predates it, while
+  the devnet build declares it and stops with `AccountNotEnoughKeys` (3005) without it. Raydium's
+  own SDK appends it unconditionally, and a program that does not declare it ignores a trailing
+  account, so the SDK sends it on both clusters.
+- `raydium.findCpmmPool`: a migrated CPMM pool does not have to sit at a derived address, so this
+  tries the derived one and falls back to a filtered scan. Either way the pool proves itself from its
+  own data, including `enable_creator_fee`, which only Raydium's permissioned migration can set.
+- `raydium.getCurveBuyExactInInstruction`: a plain curve buy, which Gabox never makes itself. The
+  devnet end-to-end test uses it to buy a curve out and force graduation.
+- `fundWsol` and `unwrapWsol` in `src/tx/wsol.ts`, for a caller building its own transaction.
+
+### Removed
+
+- **Breaking.** Everything Pump: `src/pump/`, the `pump` namespace, the `./pump` export,
+  `getPumpCreateInstruction`, `resolvePumpQuote`, `fetchPumpSupportedQuoteMints`,
+  `assertPumpQuoteSupported`, `venueBuyInstruction`, `venueSellInstruction`, and every `PUMP_*`,
+  `AMM_*` and `MAYHEM_*` constant.
+- **Breaking.** `packFee`, `maxTotalQuoteDebitFor`, `share`, `shareCeil`, `PROTOCOL_FEE_BPS`,
+  `PROTOCOL_FEE_COLLECTOR`, `MAX_FEE_BPS`, `TOKEN_2022_PROGRAM_ADDRESS` and `DEVNET_USDC_MINT`.
+  Gabox charges no fee, and WSOL is the only quote.
+- The `@pump-fun/pump-sdk`, `@pump-fun/pump-swap-sdk`, `@solana/spl-token`, `bn.js` and `buffer`
+  dependencies. `@solana/web3.js` moved to a development dependency; only the lookup-table script
+  uses it. The public surface is `@solana/kit` and nothing else.
+
+## [0.5.0] - 2026-09-17
+
+Program commit `e1666f8`: referrals removed. The IDL changed, so this is a minor bump. 0.4.x buys
+fail against this build.
+
+### Removed
+
+- **Breaking.** `bindReferrer`, `fetchReferralLink`, `listReferralLinks`, `linkAddress`,
+  `findLinkPda`, `splitPackFee`, `shareFloor`, `REFERRAL_FEE_BPS`, the `ReferralBound` event and
+  `BuyPackInput.referralLink`. `buyPack` no longer passes a link or a referrer destination.
+- `PackBought.referrer`, `referralFee*` and `collectorFee*`; the pack fee is reported as
+  `protocolFeeQuote` / `protocolFeeNative` again.
+
+### Unchanged
+
+- The 70 bps Gabox pack fee (`PROTOCOL_FEE_BPS`, `packFee`, `maxTotalQuoteDebitFor`,
+  `PackOffer.packFeeQuote`) stays and goes to `PROTOCOL_FEE_COLLECTOR` in full.
+
+## [0.4.0] - 2026-09-15
+
+Program commit `3605925`: the 70 bps Gabox pack fee and instant referral payouts. The IDL changed,
+so this is a minor bump. `buyPack` transactions built with 0.3.x no longer pass the program.
+
+### Added
+
+- `bindReferrer(client, { referee, referrer })`: bind a wallet to a referrer once, in a permanent
+  `ReferralLink` PDA (`linkAddress(wallet)`, `findLinkPda`). `fetchReferralLink(client, wallet)`
+  and `listReferralLinks(client, referrer)` read the links. `ReferralBound` event.
+- `PROTOCOL_FEE_BPS` (70) and `REFERRAL_FEE_BPS` (50); `packFee`, `splitPackFee`, `shareFloor`
+  and `maxTotalQuoteDebitFor` in the math module; `PackOffer.packFeeQuote`.
+- `PackBought` carries `collectorFeeQuote`, `collectorFeeNative`, `referrer`, `referralFeeQuote`
+  and `referralFeeNative`. Collector plus referral is the whole pack fee.
+
+### Changed
+
+- **Breaking.** `buy_pack` charges a 70 bps Gabox pack fee again, on top of the creator fee, in
+  the pool's quote asset. `maxTotalQuoteDebit` must cover it; build it with
+  `maxTotalQuoteDebitFor(maxQuoteIn, feeBps)`. A referral splits the fee (50 bps to the referrer,
+  20 to the collector); it never changes the total.
+- **Breaking.** `buyPack` passes the collector's quote destination again, the buyer's
+  `ReferralLink` PDA on every buy (the program reads it and enforces the referral), and the
+  referrer's destination when the link exists. It fetches the link itself; `referralLink: null`
+  skips the lookup. It uses the sync generated instruction so nothing is derived behind its back.
+- `sellTokens` still charges nothing.
+
+## [0.3.2] - 2026-09-14
+
+### Fixed
+
+- `decodeBondingCurve` reports `WSOL_MINT` for a curve that quotes in plain SOL. Pump stores an
+  all-zero key there, and its own SDK treats that value as SOL. Before this fix `resolveVenue`
+  compared the pool's WSOL quote against the zero key and threw
+  `pool quote So1111… does not match Pump curve quote 1111…` for every SOL machine once its curve
+  existed. That broke indexing and pack buys for those machines.
+
+## [0.3.1] - 2026-09-14
+
+### Fixed
+
+- The shared devnet lookup table now holds the fixed accounts of a token-quoted machine: the
+  USDC mint, Pump's quote-control PDA, the protocol creator vault, and the USDC and WSOL ATAs of
+  that vault and of every Pump fee recipient. A USDC create was 1,243 bytes or more and failed in
+  `buildMessage`; it is now about 120 bytes smaller. The table grew from 74 to 103 addresses.
+  Existing indices did not move.
+- `scripts/deploy-lookup-table.ts` extends the live table instead of creating a new one each run,
+  and `--dry-run` prints the plan.
+
+## [0.3.0] - 2026-09-14
+
+### Breaking
+
+- Replaced the legacy ABI surface with Gabox-only builders, accounts, events, and generated
+  codecs. Legacy pools, markets, referrals, claims, and prize-sale helpers are not supported.
+- `createMachine` now resolves a Pump quote mint, its owning token program, and QuoteControl
+  admission from live Pump state. Callers provide only `{ kind: 'sol' }` or `{ kind: 'token', mint }`.
+- Pack buys use separate quote and native debit caps; fee previews now use the program's ceiling
+  rounding so `maxTotalQuoteDebit` can safely be built from an offer.
+- The program crate and module are renamed `gabox-v2`/`gabox_v2` -> `gabox`. The program id is
+  unchanged. The IDL snapshot moved from `idl/gabox_v2.json` to `idl/gabox.json`.
+- Every generated `V2`-suffixed name lost the suffix: instructions (`initializePoolV2` ->
+  `initializePool`, `buyPackV2` -> `buyPack`, `sellTokensV2` -> `sellTokens`), events
+  (`PoolCreatedV2` -> `PoolCreated`, `PackBoughtV2` -> `PackBought`, `TokensSoldV2` -> `TokensSold`),
+  and their decoders, discriminators, and input types. The error `CoinNotCreatedHere` is now
+  `InvalidPumpCreate`.
+- Holder rewards are gone. `initialize_pool` no longer takes an `expectedHolderReward` argument,
+  `createMachine`/`getPumpCreateInstruction` no longer take a `holderReward` option, and Gabox's
+  Pump `create_v2` builder always sends the standard launch: no trailing holder-reward flag set to
+  `true`. The program itself now refuses a `create_v2` with that flag on.
+- The `Pool` account dropped `holderReward`, `seedTokens`, `seedNativeDebit`, and
+  `nativeOnPumpCurve`. A pool's curve settles natively in SOL exactly when `pool.quoteMint` equals
+  `WSOL_MINT`; there is no separate stored flag any more. `PackOffer.seedTokens` is now derived
+  from the live tier table instead of read from the account, and `PackOffer.seedNativeDebit` is
+  removed (the account no longer stores it). The `PoolCreated` event still carries `seedTokens` and
+  `seedNativeDebit` as a one-time creation record, but lost `holderReward`.
+- Pool account size changed to match the smaller layout. `check:program` and `codegen` read the
+  IDL at its new path automatically.
+- `Pool` and `Draw` now use fixed custom discriminators instead of Anchor's default
+  name-derived ones, so an account from the previous, shorter layout fails a discriminator check
+  instead of being decoded with its fields shifted into the wrong meaning. `fetchPoolByMint`,
+  `fetchDraw`, `listPools`, and `listDraws` all read the new discriminators from the generated
+  client; nothing in the SDK hard-codes the old bytes.
+- Gabox charges no protocol fee any more. `buyPack` only adds the pool creator's own fee on top of
+  the venue spend, and `sellTokens` keeps the full venue proceeds for the seller. The `fee_collector`
+  and `fee_collector_quote_destination` accounts are gone from both `buyPack` and `sellTokens`, and
+  `sellTokens` also lost its `system_program` account; `buyPack`/`sellTokens` callers that built the
+  account list by hand must drop them. The `PackBought` and `TokensSold` events lost
+  `protocolFeeQuote` and `protocolFeeNative`. `PROTOCOL_FEE_BPS` is removed and `PackOffer` no
+  longer has a `protocolFeeQuote` field.
+- `PROTOCOL_FEE_COLLECTOR` no longer collects a fee. It is now the address every Gabox coin's Pump
+  `create_v2` names as the coin creator, so Pump's own per-trade creator fee for the coin pays out
+  there. `getPumpCreateInstruction` and `createMachine` no longer take a `creator` or
+  `creatorFeeBps` option: the creator is always `PROTOCOL_FEE_COLLECTOR` and its Pump creator fee
+  bps is always zero.
+- The error `InvalidFeeCollector` is removed, so the numeric codes of `InvalidPumpCreate`,
+  `InvalidQuote`, and `InvalidQuoteAccount` (and any later variant) each shifted down by one. Do
+  not hard-code the old numbers.
+- The mandatory seed a pool creation buys now has a minimum instead of always matching the top
+  tier exactly: it makes a 3x top prize payable on the first pack, or the table's full top prize
+  when that pays less than 3x. `math.seedTokens` carries the rule; `MIN_SEED_MULTIPLIER_BPS`
+  (`30_000`) is exported. A jackpot above 3x still shows in full once later packs grow the free
+  vault; `math::quote` already caps every prize at what the vault holds. A creator adds more seed
+  up front through `extraSeedTokens` (below).
+- `validateTiers` now refuses a ticketed tier's `multiplierBps` above `MAX_MULTIPLIER_BPS`
+  (`200_000`, 20x) with `InvalidDistribution`. A table's top tier can be at most 20x; seed beyond
+  what a 20x prize needs stays in the vault as backup for the draws after a top-tier hit.
+- `initializePool` (the generated instruction and `createMachine`) takes a new last argument,
+  `extraSeedTokens: bigint`, so a creator can buy more seed on top of the mandatory amount in the
+  same trade. `createMachine`'s `CreateMachineInput` gained the matching optional
+  `extraSeedTokens` (default `0n`, must not be negative), and `maxSeedQuoteIn`/`maxSeedNativeDebit`
+  now bound `mandatory + extraSeedTokens` together. `seedCostEstimate` takes the same option and
+  now returns `seedTokens` (mandatory), `extraSeedTokens`, and `totalSeedTokens` as separate
+  fields, instead of one combined `seedTokens`. `PoolCreated` gained `extraSeedTokens`, right after
+  `seedTokens`.
+- `buyPack` (the generated instruction) takes a new writable account, `activity`, right after
+  `draw`: the buyer's `WalletActivity` PDA, `init_if_needed`. The generated async builder resolves
+  it itself from `purchaser`, so `buyPack` needed no change and existing callers are unaffected.
+  The new error `WalletActivityMismatch` is appended after `InvalidQuoteAccount`, so later error
+  codes each shifted down by one; do not hard-code the old numbers.
+
+### Added
+
+- SOL, Pump-supported token quote, custom QuoteControl quote, and quote-aware seed estimation
+  support. The new estimate returns quote base units and resolved quote metadata.
+- Exact Pump and PumpSwap account routing, including quote-aware canonical PumpSwap PDAs.
+- `WalletActivity`: a per-wallet account tracking lifetime `packsBought` and `nativeSpent`
+  (SOL-quoted pools only). Read it with `fetchWalletActivity(client, wallet)` (`null` before a
+  wallet's first purchase) or `fetchMaybeWalletActivity`/`decodeWalletActivity` from `generated`.
+  Its PDA is `findActivityPda({ purchaser })`, also exported as `activityAddress(wallet)`.
+
+### Security
+
+- Pool inventory and reservations now use one RPC snapshot, quote admission cannot be supplied by
+  Jupiter metadata, and resolved-draw events are bound to the queried draw PDA.
+- Pump SDK dependencies are exact-pinned because their PDA, decoder, and fee-math behavior is in
+  the transaction trust boundary.
+
+## [0.2.0] - 2026-09-13
+
+### Breaking
+
+- `createMachine` now accepts an optional `tiers` table instead of required `riskProfile` and
+  `jackpotBps` inputs. `seedCostEstimate` now takes the same optional table. Both default to
+  `DEFAULT_TIERS`, the Gabox app's 20× top-prize table.
+- Removed `jackpotTiers` and `RiskProfile`. Pass an explicit validated eight-row `Tier[]` to use a
+  different prize table.
+
+### Security
+
+- `expireDraw` is documented and generated from the program revision that only permits expiry of
+  an expired `Pending` draw. A `Ready` draw is rejected with `NotPending`, preserving its resolved
+  award for normal delivery.
+
+### Changed
+
+- Code generation validates the complete program IDL and Pump ABI before replacing generated code
+  or committed IDL snapshots. A failed ABI cross-check now leaves the SDK unchanged.
+- The matching devnet program upgrade is verified at slot `497869792`. Its first 586,304 deployed
+  bytes match the reviewed SBF SHA-256 `fdbbed4161a9f2f22ce02547dc3e9ec67a22020ab58be9403d04e31464dadf89`;
+  its 595,976-byte allocation has only zero padding beyond that build.
 
 ## [0.1.1] - 2026-09-11