@gabox-labs/sdk 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,90 @@
 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

package/README.md

@@ -1,8 +1,8 @@
 # @gabox-labs/sdk
 
 Kit-only TypeScript client for Gabox on Solana. A Gabox machine is a prize pool bound to a brand-new
-Raydium LaunchLab coin. The coin trades on its LaunchLab curve until it raises the pinned amount,
-then Raydium migrates it into a Raydium CPMM pool and it trades there.
+Raydium LaunchLab coin. The coin trades on its LaunchLab curve until it raises its target, then
+Raydium migrates it into a Raydium CPMM pool and it trades there.
 
 Devnet today. Mainnet addresses are pinned and tested, but the program is not deployed there yet.
 
@@ -21,16 +21,55 @@ this SDK shows is the venue's own price with the venue's own fees already inside
 Those shares come out of Raydium's revenue, not out of an extra charge Gabox adds. The creator
 collects theirs with `raydium.claimCreatorFee` and `raydium.collectCreatorFee`.
 
-## WSOL, not SOL
+## The quote asset
 
-Both venues settle in wrapped SOL. So every builder here does the same three things around its
-Gabox instruction: create the wallet's WSOL account, move the lamports it needs into it, and close
-the account again afterwards. Whatever the trade did not spend, and whatever a sale paid in, comes
-back to the wallet as SOL.
+A machine is priced in one quote asset, fixed when the pool is created. It defaults to wrapped SOL.
+Any quote Raydium enabled on LaunchLab works: USDC, a stock token, anything Raydium wrote a
+`GlobalConfig` for. There is no list in the program or in this SDK; the account itself is the proof.
 
-**Closing unwraps everything.** A wallet that already held WSOL in that account gets it back as SOL
-too. Nothing is lost, but the balance moves. Build your own instructions if you keep a WSOL position
-on purpose.
+```ts
+const config = await raydium.fetchQuoteConfig(client, someMint);
+// null when Raydium enabled no such quote. `raydium.isQuoteSupported` is the boolean version.
+```
+
+The quote mint may be classic SPL Token or Token-2022. The coin is always classic SPL Token.
+
+## Paying in SOL
+
+Buyers pay in SOL whatever the pool is priced in.
+
+- **A WSOL pool.** Every builder creates the wallet's WSOL account, moves the lamports it needs into
+  it, and closes the account again afterwards. Whatever the trade did not spend, and whatever a sale
+  paid in, comes back as SOL.
+- **Any other pool.** A route provider swaps SOL into the quote token **in the same transaction** as
+  the Gabox instruction, and back again after a sale. One signature, one transaction; the SDK never
+  splits the two, because a swap that settled on its own would leave the buyer holding a token they
+  never asked for.
+
+```ts
+import { createClient, raydiumCpmmRoute } from '@gabox-labs/sdk';
+
+// Mainnet gets Jupiter by default. Devnet has no router, so name a CPMM pool for the SOL pair.
+const client = createClient({
+  cluster: 'devnet',
+  route: raydiumCpmmRoute(devnetSolUsdcPool),
+});
+```
+
+`payWith: 'quote'` on `buyPack` and `createMachine` skips the swap and spends the token the wallet
+already holds. `receive: 'quote'` does the same for a sale. A WSOL pool ignores both: its quote
+token is SOL.
+
+The swap has to fit in the same 1,232-byte transaction as the buy. When it does not, the builder
+fails with a clear error rather than splitting the work; supply more address lookup tables, or pay
+in the quote token. It also runs on the same compute budget, so a builder adds `route.computeUnits`
+to its own limit and caps the total at the 1,400,000-unit ceiling. Jupiter states that number with
+the route it returns; the CPMM provider uses a measured one, because it is always a single pool.
+Pass `computeUnitLimit` to override it.
+
+**Closing a WSOL account unwraps everything.** A wallet that already held WSOL in that account gets
+it back as SOL too. Nothing is lost, but the balance moves. Build your own instructions if you keep
+a WSOL position on purpose.
 
 ## Create a machine
 
@@ -52,14 +91,42 @@ One transaction, two signers: the mint keypair and the creator. `initialize_pool
 unless the same transaction also carries a LaunchLab `initialize_v2` for the same mint with the
 pinned launch arguments, so the two cannot be separated.
 
-The creator picks the name, the symbol, the metadata URI and the prize table. Everything else is
-fixed: 6 decimals, 1,000,000,000 coins, 793,100,000 of them sold on the curve, 85 SOL raised on
-mainnet or 3 SOL on devnet, graduate into a CPMM pool, no vesting, the CPMM creator fee paid in
-WSOL. Metaplex limits the three strings to 32, 10 and 200 UTF-8 bytes.
+The creator picks the name, the symbol, the metadata URI, the prize table and the quote asset.
+Everything else is fixed: 6 decimals, 1,000,000,000 coins, 793,100,000 of them sold on the curve,
+graduate into a CPMM pool, no vesting, the CPMM creator fee paid in the quote token. Metaplex limits
+the three strings to 32, 10 and 200 UTF-8 bytes.
 
-`maxSeedQuoteIn` is both the slippage cap on the seed buy and the number of lamports wrapped before
-it. `maxSeedNativeDebit` is separate and small: it caps the lamports of rent LaunchLab charges for
-the fee vaults it creates on a coin's first trade.
+`maxSeedQuoteIn` is both the slippage cap on the seed buy and the amount of the quote token put in
+the creator's quote account before it. `maxSeedNativeDebit` is separate and small: it caps the
+lamports of rent LaunchLab charges for the fee vaults it creates on a coin's first trade.
+
+### Another quote asset
+
+```ts
+const estimate = await seedCostEstimate(client, undefined, { quote: { mint: usdc }, raise });
+const message = await createMachine(client, {
+  creator,
+  mintKeypair,
+  name: 'Gabox',
+  symbol: 'GBX',
+  uri: 'https://example.com/metadata.json',
+  quote: { mint: usdc },
+  raise,                       // total_quote_fund_raising, in USDC base units
+  payWith: 'sol',              // the default: the seed is bought with a swap
+  maxSeedQuoteIn: (estimate.quoteAmount * 110n) / 100n,
+  maxSeedNativeDebit: 100_000_000n,
+});
+```
+
+`raise` is how much the curve must take in before the coin graduates, in the quote's own base units.
+A WSOL pool has it pinned by the program — 85 SOL on mainnet, 3 SOL on devnet — so leave it out
+there. Any other quote has no default, because the same number means a different amount in every
+token. LaunchLab refuses a raise below `min_quote_fund_raising` in that quote's config, and
+`createMachine` checks the same thing before it builds anything.
+
+`seedCostEstimate` reports `quoteAmount` in the quote token, `quoteDecimals`, `quoteSymbol`, the
+`raise` it would use, and `solAmount`: the same cost in lamports through the route provider, or
+`null` when nothing can price it.
 
 ### The seed
 
@@ -84,13 +151,15 @@ const message = await buyPack(client, {
 });
 ```
 
-`offer.quoteAmount` is the exact price the venue will charge for one pack right now, fees included.
-The curve math is a port of Raydium's own, not an estimate, so the `PackBought` event reports the
-same number unless somebody trades in between.
+`offer.quoteAmount` is the exact price the venue will charge for one pack right now, fees included,
+in the pool's quote token. The curve math is a port of Raydium's own, not an estimate, so the
+`PackBought` event reports the same number unless somebody trades in between. `offer.solAmount` is
+the same price in lamports through the route provider, with `offer.quoteDecimals` and
+`offer.quoteSymbol` for showing it.
 
-`maxQuoteIn` is the slippage cap, in WSOL, and the number of lamports wrapped before the buy.
-`maxNativeDebit` is separate: it caps the lamports the handler watches, which are the VRF request
-and any venue account rent. Gabox adds nothing to either.
+`maxQuoteIn` is the slippage cap, in the quote token, and the amount put in the buyer's quote
+account before the buy. `maxNativeDebit` is separate: it caps the lamports the handler watches,
+which are the VRF request and any venue account rent. Gabox adds nothing to either.
 
 ## Sell
 
@@ -105,7 +174,9 @@ const message = await sellTokens(client, {
 });
 ```
 
-The seller keeps the whole venue proceeds. `minQuoteOutput` is the venue's own floor.
+The seller keeps the whole venue proceeds. `minQuoteOutput` is the venue's own floor, in the quote
+token. On a pool that is not quoted in SOL, `receive: 'sol'` (the default) swaps that floor into SOL
+in the same transaction; anything the venue paid above the floor stays in the quote account.
 
 ## Which venue
 
@@ -121,30 +192,37 @@ Raydium picks a fresh address when that one is taken. So the pool has to prove i
 data — CPMM owns it, it carries the `PoolState` discriminator, its `pool_creator` is the coin
 creator, its two mints are the sorted pair, and `enable_creator_fee` is true. That last flag is the
 one that cannot be forged: plain CPMM `initialize` always leaves it false. The program checks the
-same five things before it forwards a trade, and reads the fee tier, both vaults and the oracle out
-of the pool account rather than deriving them.
+same five things before it forwards a trade, and reads the fee tier, both vaults, both token
+programs and the oracle out of the pool account rather than deriving them.
+
+`resolveVenue` needs the pool's quote asset. It reads the Gabox pool for it, or takes a
+`quote: { mint, config, tokenProgram }` when the caller already has one.
 
 ## Creator fees
 
 ```ts
 const owed = await raydium.fetchCreatorFees(client, { creator: creator.address, mint });
-// owed.curveLamports, owed.cpmmLamports, owed.cpmmTokens
+// owed.quoteMint, owed.curveQuote, owed.cpmmQuote, owed.cpmmTokens
 
-await raydium.claimCreatorFee(client, { creator });          // every coin on the curve, at once
+await raydium.claimCreatorFee(client, { creator });          // every SOL coin on the curve, at once
 await raydium.collectCreatorFee(client, { mint, creator });  // one graduated coin
 ```
 
-LaunchLab keeps one creator fee vault per wallet per quote asset, so a single claim sweeps every coin
-that wallet launched. A CPMM pool keeps its creator fee inside the pool account, so that one is per
-coin. Both pay into the creator's WSOL account, and both builders close it so the creator receives
-SOL.
+LaunchLab keeps one creator fee vault per wallet **per quote asset**, so a single claim sweeps every
+coin that wallet launched against that quote. A creator with a SOL machine and a USDC machine claims
+twice: `claimCreatorFee(client, { creator, quoteMint })`, and `fetchCreatorFees` takes the same
+argument. A CPMM pool keeps its creator fee inside the pool account, so that one is per coin and
+reads the quote off the Gabox pool itself.
+
+Both pay into the creator's account for the quote mint. When that is WSOL the builders close it, so
+the creator receives SOL; any other quote arrives as that token.
 
 ## Wallet activity
 
 `buyPack` keeps a `WalletActivity` account per buyer, at the PDA `findActivityPda({ purchaser })`
 (also `activityAddress(wallet)`). It tracks `packsBought` and `nativeSpent` across every pool.
-`nativeSpent` is what the venue charged in WSOL, which is SOL; Gabox's own rent and the VRF fee are
-not counted. The buyer pays its rent once, on the first purchase, and `buyPack` resolves the account
+`nativeSpent` is what the venue charged in WSOL, which is SOL; Gabox's own rent, the VRF fee and a
+pack bought in any other quote token are not counted. The buyer pays its rent once, on the first purchase, and `buyPack` resolves the account
 itself. Read it with `fetchWalletActivity(client, wallet)`, which returns `null` before a wallet's
 first purchase.
 
@@ -165,5 +243,6 @@ The generated client decodes the program's own errors by name. The ones a client
 | `PrizeCapChanged` | The top prize fell below `minMaximum`. Refresh the offer. |
 | `IncorrectTokenDelta` | The venue did not deliver exactly one pack. Usually a curve with less than a pack left; wait for graduation. |
 | `InvalidLaunch` | The LaunchLab create instruction was missing or did not match the pinned shape. |
+| `InvalidQuote` | The quote mint is not one Raydium enabled, or its Token-2022 profile is one the program refuses. |
 
 See [the API reference](skills/gabox-sdk/references/api.md).