@gabox-labs/sdk 0.6.0 → 0.7.0

package/skills/gabox-sdk/SKILL.md

@@ -17,9 +17,17 @@ Gabox charges no fee at all. Every price the SDK shows already includes Raydium'
 curve, 0.5% to the Gabox platform wallet and 0.5% to the coin creator plus Raydium's trade fee; after
 graduation, the CPMM pool fee and the pool creator fee.
 
-Both venues settle in wrapped SOL. Every builder wraps the SOL its trade needs and closes the WSOL
-account afterwards, so the wallet spends and receives plain SOL. That close also unwraps any WSOL the
-wallet already held.
+A machine is priced in one quote asset, fixed when the pool is created. It defaults to wrapped SOL,
+and any quote Raydium enabled on LaunchLab works; `raydium.fetchQuoteConfig(client, mint)` says
+whether a mint is one of them, and `raydium.isQuoteSupported` is the boolean version. The quote may
+be classic SPL Token or Token-2022; the coin is always classic SPL Token.
+
+Buyers pay in SOL either way. On a WSOL pool every builder wraps the SOL its trade needs and closes
+the WSOL account afterwards, so the wallet spends and receives plain SOL; that close also unwraps any
+WSOL the wallet already held. On any other pool a route provider swaps SOL into the quote token **in
+the same transaction** as the Gabox instruction, and back after a sale. `createClient` gives mainnet
+`jupiterRoute()`; devnet has no router, so pass `route: raydiumCpmmRoute(pool)` with a CPMM pool for
+the SOL pair. `payWith: 'quote'` and `receive: 'quote'` skip the swap.
 
 ```ts
 import { buyPack, createClient, getOffer } from '@gabox-labs/sdk';
@@ -35,24 +43,29 @@ const message = await buyPack(gabox, {
 });
 ```
 
-`offer.quoteAmount` is the exact venue price for one pack. `maxQuoteIn` is the slippage cap and the
-number of lamports wrapped first. `maxNativeDebit` is a separate cap on the lamports the handler
-watches: the VRF request and any venue account rent.
+`offer.quoteAmount` is the exact venue price for one pack, in the pool's quote token;
+`offer.solAmount` is the same price in lamports, with `offer.quoteDecimals` and `offer.quoteSymbol`
+for showing it. `maxQuoteIn` is the slippage cap in the quote token, and the amount put in the
+buyer's quote account first. `maxNativeDebit` is a separate cap on the lamports the handler watches:
+the VRF request and any venue account rent.
 
 For creation use `createMachine` with `name`, `symbol`, `uri`, `maxSeedQuoteIn` and
-`maxSeedNativeDebit`. Metaplex limits the three strings to 32, 10 and 200 UTF-8 bytes. Everything
-else about the launch is pinned. It buys a mandatory seed: enough for a 3x top prize on the first
-pack, or the table's full top prize when that pays less than 3x. A table's top tier can be at most
-20x. Pass `extraSeedTokens` to buy more seed in the same trade, and read `seedCostEstimate` for the
-mandatory, extra and total amounts plus the exact cost.
+`maxSeedNativeDebit`. Metaplex limits the three strings to 32, 10 and 200 UTF-8 bytes. Add
+`quote: { mint }` and `raise` for a machine priced in another token: `raise` is
+`total_quote_fund_raising` in that token's base units, and a WSOL pool uses the raise the program
+pins instead. Everything else about the launch is pinned. It buys a mandatory seed: enough for a 3x
+top prize on the first pack, or the table's full top prize when that pays less than 3x. A table's
+top tier can be at most 20x. Pass `extraSeedTokens` to buy more seed in the same trade, and read
+`seedCostEstimate` for the mandatory, extra and total amounts plus the exact cost.
 
 `raydium.resolveVenue(client, { mint, user })` says which venue is live. It throws while a coin is
 migrating, which on devnet lasts under a minute. A migrated CPMM pool can sit at any address, so the
 SDK proves it from its own data and reads its fee tier, vaults and oracle out of the pool account.
 
-Creators collect their share with `raydium.claimCreatorFee(client, { creator })`, which sweeps every
-coin they launched on the curve, and `raydium.collectCreatorFee(client, { mint, creator })` for one
-graduated coin. `raydium.fetchCreatorFees` reads both.
+Creators collect their share with `raydium.claimCreatorFee(client, { creator, quoteMint })`, which
+sweeps every coin they launched against that quote, and
+`raydium.collectCreatorFee(client, { mint, creator })` for one graduated coin.
+`raydium.fetchCreatorFees` reads both, per quote asset.
 
 `buyPack` keeps a per-wallet `WalletActivity` account (`fetchWalletActivity(client, wallet)`, `null`
 before a wallet's first purchase); it resolves the account itself.

package/skills/gabox-sdk/references/api.md

@@ -2,7 +2,7 @@
 
 All chain-touching functions take `client: GaboxClient` first. Addresses use `Address`; all token
 amounts use base-unit `bigint`. Every venue is Raydium: LaunchLab before a coin graduates, Raydium
-CPMM after. Both settle in WSOL.
+CPMM after. Both settle in the pool's own quote asset, which defaults to wrapped SOL.
 
 ## Client and reads
 
@@ -15,13 +15,15 @@ CPMM after. Both settle in WSOL.
 | `listPools(client)` / `listDrawsByPurchaser(client, wallet)` | current account scans |
 | `fetchWalletActivity(client, wallet)` | `WalletActivity \| null`, a buyer's lifetime `packsBought`/`nativeSpent` |
 
-`Pool` records `creator`, `mint`, `vault`, `quoteMint` (always WSOL), `packTokens`,
-`seedQuoteAmount`, `tiers`, `nextSeq` and `reserved`. It stores no token program, because classic
-SPL Token owns both sides, and no fee, because Gabox charges none.
+`Pool` records `creator`, `mint`, `vault`, `quoteMint`, `packTokens`, `seedQuoteAmount`, `tiers`,
+`nextSeq`, `reserved`, `quoteConfig` (LaunchLab's global config for the quote) and
+`quoteTokenProgram` (classic SPL Token or Token-2022). It stores no base token program, because the
+coin is always classic SPL Token, and no fee, because Gabox charges none.
 
-`PackOffer` gives `quoteAmount` (the whole pack price, the venue's fees included), `venue`
-(`'launchlab'` or `'cpmm'`), the frozen prize table, `maximum`, `minimum`, `uncapped`, the inventory
-numbers and `isSeeded`.
+`PackOffer` gives `quoteAmount` (the whole pack price in the quote token, the venue's fees
+included), `quoteMint`, `quoteDecimals`, `quoteSymbol`, `solAmount` (the same price in lamports
+through the route provider, or `null`), `venue` (`'launchlab'` or `'cpmm'`), the frozen prize table,
+`maximum`, `minimum`, `uncapped`, the inventory numbers and `isSeeded`.
 
 ## Builders
 
@@ -29,17 +31,22 @@ Each returns a kit transaction message. Nothing here signs or sends.
 
 | Function | Input highlights |
 | --- | --- |
-| `createMachine` | `name`, `symbol`, `uri`, `tiers?`, `maxSeedQuoteIn`, `maxSeedNativeDebit`, `extraSeedTokens?` |
-| `buyPack` | `maxQuoteIn`, `minMaximum`, `maxNativeDebit`, `venue?`, `seq?` |
+| `createMachine` | `name`, `symbol`, `uri`, `tiers?`, `quote?`, `raise?`, `payWith?`, `maxSeedQuoteIn`, `maxSeedNativeDebit`, `extraSeedTokens?` |
+| `buyPack` | `maxQuoteIn`, `minMaximum`, `maxNativeDebit`, `payWith?`, `venue?`, `seq?` |
 | `fundPrizes` | donate coins the funder already holds into the prize vault |
-| `sellTokens` | `amount`, `minQuoteOutput`, `maxNativeDebit`, `venue?` |
+| `sellTokens` | `amount`, `minQuoteOutput`, `maxNativeDebit`, `receive?`, `venue?` |
 | `retryDraw` / `expireDraw` | permissionless recovery |
-| `raydium.claimCreatorFee` | `creator`; sweeps every coin that wallet launched on the curve |
+| `raydium.claimCreatorFee` | `creator`, `quoteMint?`; sweeps every coin that wallet launched against that quote |
 | `raydium.collectCreatorFee` | `mint`, `creator`; one graduated coin's CPMM creator fee |
 
-Every builder wraps the SOL its trade needs into the wallet's WSOL account and closes that account
-afterwards, so the wallet spends and receives plain SOL. Closing unwraps any WSOL the wallet already
-held.
+On a WSOL pool every builder wraps the SOL its trade needs into the wallet's WSOL account and closes
+that account afterwards, so the wallet spends and receives plain SOL. Closing unwraps any WSOL the
+wallet already held.
+
+On any other pool the wallet's quote account is created if missing, and `payWith: 'sol'` (the
+default) prepends a swap that turns SOL into the quote token. `receive: 'sol'` appends the reverse
+after a sale. `payWith: 'quote'` and `receive: 'quote'` skip the swap. The swap and the Gabox
+instruction always share one transaction.
 
 `createMachine` builds one transaction with LaunchLab's `initialize_v2` first and `initialize_pool`
 second. The mint keypair and the creator both sign. It buys a mandatory seed,
@@ -53,9 +60,16 @@ top prize when that pays less than 3x. A table's top tier can be at most 20x. `e
 either: the program declares it `init_if_needed`, so Anchor does that and the purchaser pays its rent
 once.
 
-`maxQuoteIn` and `maxSeedQuoteIn` are venue slippage caps in WSOL, and each is also the amount
-wrapped before the trade. `maxNativeDebit` and `maxSeedNativeDebit` are separate lamport caps for
-what the handler watches: venue account rent, and the VRF request on a pack buy.
+`maxQuoteIn` and `maxSeedQuoteIn` are venue slippage caps in the quote token, and each is also the
+amount put in the wallet's quote account before the trade. `maxNativeDebit` and
+`maxSeedNativeDebit` are separate lamport caps for what the handler watches: venue account rent, and
+the VRF request on a pack buy.
+
+`createMachine` takes `quote: { mint }` and `raise`. The quote defaults to wrapped SOL, whose raise
+the program pins per cluster; any other quote needs a `raise` in its own base units, at or above
+`min_quote_fund_raising` in its config. `seedCostEstimate(client, tiers?, { extraSeedTokens?,
+quote?, raise? })` reports the seed cost in the quote token, its decimals and symbol, the raise, and
+`solAmount` through the route provider.
 
 ## The venue
 
@@ -64,11 +78,18 @@ what the handler watches: venue account rent, and the VRF request on a pack buy.
 | `raydium.resolveVenue(client, { mint, user, venue? })` | `ResolvedVenue`: `kind`, `program`, `poolState`, `status`, `creator`, `ammConfig`, `remainingCurveBase`, `buyAccounts`, `sellAccounts`, `quoteBuy`, `quoteSell` |
 | `raydium.curveQuote(client, mint, tokens)` | the buy price, for a display |
 | `raydium.sellQuote(client, mint, tokens)` | the sale proceeds |
-| `raydium.newCurveBuyCost(client, tokens)` | what a buy costs on a curve that does not exist yet |
-| `raydium.findCpmmPool(client, { mint, creator, cpswapConfig })` | the migrated CPMM pool, proved from its own data |
-| `raydium.fetchCurveSettings(client)` | the fee rates, the migrate fee and the CPMM fee tier, read from chain |
-| `raydium.fetchCreatorFees(client, { creator, mint? })` | `{ curveLamports, cpmmLamports, cpmmTokens }` |
-| `raydium.wsolAccountFor(user)` | the WSOL account every venue settles in |
+| `raydium.newCurveBuyCost(client, tokens, { quoteConfig, raise })` | what a buy costs on a curve that does not exist yet |
+| `raydium.findCpmmPool(client, { mint, creator, cpswapConfig, quoteMint? })` | the migrated CPMM pool, proved from its own data |
+| `raydium.fetchCurveSettings(client, quoteConfig)` | the fee rates, the migrate fee and the CPMM fee tier, read from chain |
+| `raydium.fetchCreatorFees(client, { creator, mint?, quoteMint? })` | `{ quoteMint, curveQuote, cpmmQuote, cpmmTokens }` |
+| `raydium.fetchQuoteConfig(client, mint)` | LaunchLab's global config for a quote, or `null` |
+| `raydium.isQuoteSupported(client, mint)` | can a machine be priced in this mint? |
+| `raydium.fetchQuoteAsset(client, mint)` | the config, token program, decimals, symbol and minimum raise |
+| `raydium.quoteAccountFor(user, quoteMint, quoteTokenProgram)` | the account both venues settle in |
+| `raydium.wsolAccountFor(user)` | the same, for a WSOL pool |
+
+`resolveVenue` takes an optional `quote: { mint, config, tokenProgram }`. Left out, it reads the
+Gabox pool for it, so a caller that already holds a `Pool` saves a round trip by passing it.
 
 `resolveVenue` follows the LaunchLab pool's `status`: `0` routes to the curve, `2` to the CPMM pool,
 and `1` throws because the coin is migrating right now. A migrated CPMM pool does not have to sit at
@@ -90,16 +111,47 @@ Raydium's.
 shape. `raydium.getCurveBuyExactInInstruction(client, input, ids?)` builds a plain curve buy that
 Gabox never makes itself; the devnet end-to-end test uses it to buy a curve out and force graduation.
 
+`initialize_pool`'s `venue` account has no generated default, because LaunchLab has a different
+address on each cluster and a default would be wrong on one of them. Every builder here passes it
+from `raydiumIds(client.cluster)`; a caller using the generated builder directly has to do the same.
+
 `raydiumIds(cluster)` gives one cluster's Raydium deployment. Mainnet and devnet run different
-programs and PDAs, and devnet raises 3 SOL where mainnet raises 85. `localnet` uses the mainnet set,
-which is what the program's default build pins.
+programs and PDAs, and a WSOL launch raises 3 SOL on devnet where mainnet raises 85. `localnet` uses
+the mainnet set, which is what the program's default build pins.
+
+## Routes
+
+A route provider swaps SOL into a pool's quote token, and back. `createClient` gives mainnet
+`jupiterRoute()` and every other cluster `null`; pass `route` to override, or `null` to switch the
+swap leg off.
+
+| Function | Result |
+| --- | --- |
+| `jupiterRoute({ url?, slippageBps? })` | a `RouteProvider` over Jupiter's swap API, for mainnet |
+| `raydiumCpmmRoute(poolAddress)` | a `RouteProvider` over one Raydium CPMM pool, for devnet |
+| `routeQuoteIn(client, provider, { quoteMint, amount, user })` | a swap that buys at least `amount`, exact-out first |
+| `routeQuoteOut(client, provider, { quoteMint, amount, user })` | a swap that turns `amount` into SOL |
+| `solPriceOf(client, quoteMint, amount)` | the exact-out SOL cost of `amount`, or `null` |
+| `assertRouteIsSafe(route, { forbidden, settlesIn })` | refuse a route that touches Gabox state or settles elsewhere |
+
+A `Route` is `{ instructions, lookupTables, inAmount, outAmount, mode, computeUnits }`. `mode` is
+`'exactOut'` or `'exactIn'`: the amounts are bounds, so an exact-out route states the most it spends
+and an exact-in route the least it pays out.
+
+`computeUnits` is what the swap costs on top of the Gabox instruction, because the two share one
+budget. A builder adds it to its own limit and caps the total at `MAX_COMPUTE_UNIT_LIMIT`; an
+explicit `computeUnitLimit` still wins. Jupiter returns the number with the route, falling back to
+`JUPITER_DEFAULT_COMPUTE_UNITS` when its response carries none; `raydiumCpmmRoute` uses
+`CPMM_ROUTE_COMPUTE_UNITS`, measured on devnet, which holds because it is always one pool. Jupiter answers `NO_ROUTES_FOUND` for exact-out whenever the best route
+has more than one hop, which is why `routeQuoteIn` falls back to exact-in and leaves the change in
+the buyer's quote account.
 
 ## Events
 
 `decodeEvents` and `fetchEvents` return only `PoolCreated`, `PrizesFunded`, `PackBought`,
 `RandomnessRetried`, `DrawResolved` and `TokensSold`. None carries a Gabox fee field any more.
-`PackBought` reports `quoteDebit` (what the venue charged), `nativeDebit` (venue account rent),
-`vrfNativeDebit` and `totalNativeDebit`.
+`PackBought` reports `quoteMint`, `quoteDebit` (what the venue charged, in that token),
+`nativeDebit` (venue account rent), `vrfNativeDebit` and `totalNativeDebit`.
 
 Delivery closes a draw atomically; use `findResolvedDraw` rather than a Ready or claim flow. It
 searches a bounded recent signature history, so production indexers should persist `DrawResolved`