@gabox-labs/sdk 0.2.0 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,316 @@
 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`.
 
+## [0.7.0] - 2026-09-18
+
+Any quote token Raydium enabled, a price shown in SOL, and payment in SOL through a swap that runs
+in the same transaction as `buy_pack`. It matches the devnet program deployed at slot `500297753`,
+and a live devnet run exercised both a SOL-quoted coin and a USDC-quoted one paid for in SOL.
+
+### Changed
+
+- **Breaking.** A machine is priced in one quote asset, chosen at creation. It still defaults to
+  wrapped SOL, and any quote Raydium enabled on LaunchLab now works too. `createMachine` takes
+  `quote: { mint }` and `raise`; `initialize_pool` takes the quote's LaunchLab `GlobalConfig`
+  account, which is what proves the quote, and the quote's own token program.
+- **Breaking.** `Pool` gained `quoteConfig` and `quoteTokenProgram`, and a new discriminator. A pool
+  from the first LaunchLab build now fails to decode instead of being read with shifted fields.
+- **Breaking.** `raise` is the client's choice for every quote but wrapped SOL, where the program
+  still pins it: 85 SOL on mainnet, 3 SOL on devnet. A non-SOL pool has no default, because the same
+  number means a different amount in every token. `createMachine` refuses a raise below
+  `min_quote_fund_raising` in the quote's own config, before it builds anything.
+- **Breaking.** `RaydiumClusterIds` lost `solGlobalConfig`. Nothing pins a quote config any more:
+  derive it from the quote mint with `raydium.launchlabGlobalConfig`, or read it with
+  `raydium.fetchQuoteConfig`.
+- **Breaking.** `fetchCurveSettings(client, quoteConfig, ids?)` takes the quote's config address.
+  `newCurveBuyCost(client, tokens, { quoteConfig, raise })` and `newCurveReserves(raise, migrateFee)`
+  take the raise, because the starting reserves follow it.
+- **Breaking.** `fetchCreatorFees` takes `quoteMint` and answers
+  `{ quoteMint, curveQuote, cpmmQuote, cpmmTokens }`. `curveLamports` and `cpmmLamports` are gone:
+  the amounts are in the quote token, which is not always SOL. `claimCreatorFee` takes `quoteMint`
+  too, because LaunchLab keeps one vault per wallet per quote asset.
+- **Breaking.** `getLaunchInstruction` takes `quoteMint`, `quoteConfig`, `quoteTokenProgram` and
+  `raise`. `LaunchlabTradeAccountsInput` takes `quoteTokenProgram`, and `CpmmTradeAccountsInput`
+  takes `baseTokenProgram` and `quoteTokenProgram`; a migrated CPMM pool records both in its own
+  data, and the program checks them.
+- `GaboxClient` gained `route`, and `createClient` gained a `route` option. Mainnet defaults to
+  `jupiterRoute()`; devnet and localnet default to `null`.
+- `PackOffer` gained `quoteDecimals`, `quoteSymbol` and `solAmount`. `quoteAmount` is still the whole
+  pack price, now in the pool's quote token. `SeedCostEstimate` gained the same three plus `raise`.
+- `resolveVenue` takes an optional `quote` binding and reads the Gabox pool for it otherwise. It also
+  reports `quoteTokenProgram` and `userQuoteToken`.
+
+### Added
+
+- `payWith: 'sol' | 'quote'` on `buyPack` and `createMachine`, and `receive: 'sol' | 'quote'` on
+  `sellTokens`. Both default to `'sol'`. On a pool that is not quoted in SOL, the default prepends a
+  swap before `buy_pack` and appends one after `sell_tokens`, in the same transaction. The SDK never
+  splits the two: a message over the 1,232-byte limit fails with a clear error instead.
+- `src/route/`: `Route`, `RouteProvider`, `jupiterRoute(options)` for mainnet and
+  `raydiumCpmmRoute(poolAddress)` for devnet, plus `routeQuoteIn`, `routeQuoteOut`, `solPriceOf` and
+  `assertRouteIsSafe`. Neither provider adds a package: Jupiter is plain HTTP and JSON, and the CPMM
+  provider reuses this SDK's own swap builders and price math.
+- Exact-out first, exact-in as the fallback. Jupiter answers `NO_ROUTES_FOUND` for exact-out whenever
+  the best route has more than one hop, which is the normal case for a stock token. The fallback
+  works out the SOL that buys the amount at the exact-in price, adds a margin, and leaves the change
+  in the buyer's own quote account. A `Route` reports which mode it used.
+- `raydium.fetchQuoteConfig`, `raydium.isQuoteSupported`, `raydium.fetchQuoteAsset` and
+  `raydium.fetchQuoteDisplay`: whether Raydium enabled a quote, and its token program, decimals and
+  symbol. The symbol comes from the Token-2022 metadata extension when the mint has one, and from
+  Metaplex otherwise.
+- `raydium.quoteAccountFor(user, quoteMint, quoteTokenProgram)`: the account both venues settle in,
+  derived under the quote's own token program. A Token-2022 quote has a different ATA from a classic
+  one, and the program pins the one the pool records.
+- `TOKEN_2022_PROGRAM_ADDRESS`, generated from Raydium's own IDL.
+- `fetchAddressLookupTables(client, addresses)`: a route names its tables by address, and the message
+  has to carry them.
+- `Route.computeUnits`. A swap runs on the same compute budget as the Gabox instruction, so a
+  builder with a swap leg adds the route's own figure to its limit: Jupiter's `SetComputeUnitLimit`
+  from its `swap-instructions` response (400,000 when absent), or the measured 75,000 of the
+  Raydium CPMM route. The sum is capped at the 1,400,000 ceiling; a caller's `computeUnitLimit`
+  still wins.
+- Cluster-neutral `initializePool`. The program pins `venue` to LaunchLab's address, which differs
+  between the mainnet and devnet builds, so the generated builder no longer carries a default for
+  it and `createMachine` passes the cluster's address. `check:program` treats the two IDLs as in
+  sync.
+
+### Security
+
+- A route is built outside this SDK and runs with the buyer's signature, so every leg is checked
+  before it is composed: no instruction may name the Gabox program or any Gabox account the
+  transaction uses, and the swap has to settle in the user's own quote associated token account,
+  which is the account the program binds and measures the delta in.
+- A route's instructions carry account roles and no signer objects. Kit refuses to sign a message
+  that holds two distinct signer objects for one address, and the wallet paying for the transaction
+  is the same wallet a route names, so a signer object there would make every such message
+  unsignable. Both providers and both new test suites check it.
+
+## [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