@gabox-labs/sdk 0.7.1 → 0.9.0

package/llms.txt

@@ -20,6 +20,10 @@
 - `createClient({ cluster: 'devnet' })` once; pass it to every function.
 - Builders return a kit transaction message. You sign and send.
 - All amounts are bigint. The coin has 6 decimals. A pack is 1,000,000 tokens.
+- One purchase opens 1 to 5 packs in one trade, with one draw and one randomness request; the
+  callback settles them in order. `buyPacks` returns the draw address and its nonce.
+- A prize the callback cannot pay is owed, never lost: `claimPrize` pays it later, and `settle`
+  reproduces every pack's result from the published randomness.
 - Gabox charges no fee. Every price already includes Raydium's own fees.
 - A machine is priced in one quote asset, wrapped SOL by default; any quote Raydium enabled works.
 - Buyers pay in SOL either way: a WSOL pool wraps it, any other pool swaps it in the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gabox-labs/sdk",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "type": "module",
   "description": "The Solana Kit SDK for gabox: generated instruction builders, PDAs, Raydium LaunchLab and CPMM venue accounts, and the pack flow.",
   "license": "MIT",

package/skills/gabox-sdk/SKILL.md

@@ -7,8 +7,9 @@ description: Integrate Gabox machines on Solana with @gabox-labs/sdk and @solana
 
 Gabox binds a prize machine 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. Gabox
-delivers awards and closes draw accounts itself; there is no Ready, claim or sell-prize flow, and no
-referral program.
+settles every pack of a purchase in the oracle's callback and pays the purchaser's coin account
+itself; a claim exists only for a prize the callback could not pay (`paid: false`). There is no
+sell-prize flow and no referral program.
 
 Use only devnet clients today. Pass `GaboxClient` first to every chain function; all amounts are
 `bigint`.
@@ -32,24 +33,30 @@ machine's seed is always paid by its creator, in the machine's own quote token,
 has no `payWith` and the creator must hold `maxSeedQuoteIn` of that token first.
 
 ```ts
-import { buyPack, createClient, getOffer } from '@gabox-labs/sdk';
+import { buyPacks, createClient, getOffer } from '@gabox-labs/sdk';
 
 const gabox = createClient({ cluster: 'devnet' });
-const offer = await getOffer(gabox, mint, { user: purchaser.address });
-const message = await buyPack(gabox, {
+const offer = await getOffer(gabox, mint, { user: purchaser.address, count: 3 });
+const { message, draw } = await buyPacks(gabox, {
   mint,
   purchaser,
+  count: 3,
   maxQuoteIn: (offer.quoteAmount * 102n) / 100n,
-  minMaximum: (offer.maximum * 98n) / 100n,
+  minFirstMaximum: (offer.maximum * 98n) / 100n,
   maxNativeDebit: 100_000_000n,
 });
 ```
 
-`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.
+One purchase opens 1 to 5 packs (`MAX_BATCH_SIZE`) in one trade with one draw and one randomness
+request; `buyPack` is the one-pack form. `offer.quoteAmount` is the exact venue price for the whole
+purchase, in the pool's quote token; `offer.solAmount` is the same price in lamports, with
+`offer.quoteDecimals` and `offer.quoteSymbol` for showing it. `offer.prizes` and `offer.maximum`
+are the first pack's table; `offer.perPackCaps` is the top prize each later pack keeps in the worst
+case, and a screen should show it. `maxQuoteIn` is the slippage cap in the quote token, and the
+amount put in the buyer's quote account first. `minFirstMaximum` is the floor on the first pack's
+top prize. `maxNativeDebit` is a separate cap on the lamports the handler watches: the VRF request
+and any venue account rent. The draw is named by a random nonce the builder returns; never reuse
+the nonce of a purchase that may have landed.
 
 For creation use `createMachine` with `name`, `symbol`, `uri`, `maxSeedQuoteIn` and
 `maxSeedNativeDebit`. Metaplex limits the three strings to 32, 10 and 200 UTF-8 bytes. Add
@@ -69,9 +76,10 @@ 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`
+`buyPacks` keeps a per-wallet `WalletActivity` account (`fetchWalletActivity(client, wallet)`, `null`
 before a wallet's first purchase); it resolves the account itself.
 
-Use `fetchEvents` and `findResolvedDraw` for final delivery, and `retryDraw` or `expireDraw` for
+Use `fetchEvents` and `findResolvedDraw` for final delivery (`paid: false` means the prize waits in the
+vault: `claimPrize` pays it, `fetchOwedDraws` lists it, `settleDraw` proves it), and `retryDraw` or `expireDraw` for
 permissionless recovery. `fundPrizes` moves coins a funder already holds into the irrevocable prize
 vault. See `references/api.md` and the package README for complete signatures.

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

@@ -11,8 +11,9 @@ CPMM after. Both settle in the pool's own quote asset, which defaults to wrapped
 | `createClient({ cluster: 'devnet', ... })` | `GaboxClient` |
 | `fetchPoolByMint(client, mint)` | `Pool \| null` |
 | `fetchPoolInventory(client, mint)` | pool, vault inventory, reservations, free inventory |
-| `getOffer(client, mint, options?)` | current `PackOffer` |
-| `listPools(client)` / `listDrawsByPurchaser(client, wallet)` | current account scans |
+| `getOffer(client, mint, { count?, user?, venue? })` | current `PackOffer` for `count` packs (default 1) |
+| `listPools(client)` / `listDrawsByPurchaser(client, wallet)` / `fetchOwedDraws(client, wallet)` | current account scans; the last one lists settled draws a wallet is still owed |
+| `drawAvailability(client, draw)` | `settled`, `owed`, and which of deliver, retry, expire and claim can still happen |
 | `fetchWalletActivity(client, wallet)` | `WalletActivity \| null`, a buyer's lifetime `packsBought`/`nativeSpent` |
 
 `Pool` records `creator`, `mint`, `vault`, `quoteMint`, `packTokens`, `seedQuoteAmount`, `tiers`,
@@ -20,10 +21,16 @@ CPMM after. Both settle in the pool's own quote asset, which defaults to wrapped
 `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 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`.
+`PackOffer` gives `count`, `quoteAmount` (the whole purchase 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 first
+pack's prize table with `maximum`, `minimum` and `uncapped`, `perPackCaps` (the worst-case top
+prize of each pack), `batchReserved` (what the purchase adds to `pool.reserved`), the inventory
+numbers with `freeSnapshot`, and `isSeeded`.
+
+`Draw` records the purchase: `purchaser`, `nonce`, `seqStart`, `count`, the snapshot (`tiers`,
+`packTokens`, `freeSnapshot`, `reserved`), the attempt slots, and after settlement `settled`,
+`randomness`, `timedOut` and `owed`.
 
 ## Builders
 
@@ -32,18 +39,23 @@ Each returns a kit transaction message. Nothing here signs or sends.
 | Function | Input highlights |
 | --- | --- |
 | `createMachine` | `name`, `symbol`, `uri`, `tiers?`, `quote?`, `raise?`, `maxSeedQuoteIn`, `maxSeedNativeDebit`, `extraSeedTokens?` |
-| `buyPack` | `maxQuoteIn`, `minMaximum`, `maxNativeDebit`, `payWith?`, `venue?`, `seq?` |
+| `buyPacks` | `count` (1 to 5), `nonce?`, `maxQuoteIn`, `minFirstMaximum`, `maxNativeDebit`, `payWith?`, `venue?`; returns `{ message, draw, nonce, seqStart, count }` |
+| `buyPack` | the same with `count: 1` and `minMaximum`; same result shape |
 | `fundPrizes` | donate coins the funder already holds into the prize vault |
 | `sellTokens` | `amount`, `minQuoteOutput`, `maxNativeDebit`, `receive?`, `venue?` |
-| `retryDraw` / `expireDraw` | permissionless recovery |
+| `retryDraw` / `expireDraw` | permissionless recovery of a pending draw |
+| `claimPrize` | `payer`, `draw`; pays an owed prize to the purchaser's ATA, creating it if needed; anyone may send it |
+| `claimPrizeTo` | `purchaser`, `draw`, `destination`; the purchaser pays their own owed prize to a coin account they own |
 | `raydium.claimCreatorFee` | `creator`, `quoteMint?`; sweeps every coin that wallet launched against that quote |
 | `raydium.collectCreatorFee` | `mint`, `creator`; one graduated coin's CPMM creator fee |
+| `raydium.claimPlatformFee` | `feeWallet`, `quoteMint?`; the platform's curve share on that quote, signed by the platform fee wallet |
+| `raydium.harvestLockedFees` | `owner`, `position`, `feeLp?`; one graduated coin's locked-LP fees, signed by the fee NFT holder |
 
 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 `buyPack`'s `payWith: 'sol'`
+On any other pool the wallet's quote account is created if missing, and `buyPacks`'s `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.
@@ -58,7 +70,7 @@ top prize when that pays less than 3x. A table's top tier can be at most 20x. `e
 (default `0n`) adds more in the same trade. `seedCostEstimate` returns `seedTokens`,
 `extraSeedTokens`, `totalSeedTokens` and the exact `quoteAmount` a fresh curve would charge.
 
-`buyPack` also resolves a per-wallet `WalletActivity` account (`findActivityPda({ purchaser })` or
+`buyPacks` also resolves a per-wallet `WalletActivity` account (`findActivityPda({ purchaser })` or
 `activityAddress(wallet)`); callers do not pass it. It does not create the purchaser's coin account
 either: the program declares it `init_if_needed`, so Anchor does that and the purchaser pays its rent
 once.
@@ -86,6 +98,9 @@ route provider, for a display.
 | `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.fetchPlatformFees(client, { quoteMint? })` | `{ quoteMint, curveQuote }`, the platform's LaunchLab vault for that quote |
+| `raydium.fetchLockedPositions(client, owner)` | `LockedPosition[]`: one per fee NFT the wallet holds, with `poolAddress`, `pool`, `claimableLp`, `claimableToken0`, `claimableToken1` |
+| `raydium.lockedFeeLp(lock, pool)` | the LP a locked position may withdraw now, from `lastK`, `lastLp`, the vaults and the LP supply |
 | `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 |
@@ -106,6 +121,15 @@ coin graduates.
 
 ## Math and low-level builders
 
+The batch settlement is a port of `programs/gabox/src/math.rs`. `reserveFor(count, packTokens,
+uncappedMax, free)` is what a purchase adds to `pool.reserved`; `perPackCaps(tiers, packTokens,
+free, count)` is the worst-case top prize of each pack; `chooseIndex(tiers, ticket)` maps a 16-bit
+ticket to a tier; `settleWith(tiers, packTokens, freeSnapshot, count, tickets, timedOut)` settles a
+batch in order from explicit tickets. `settle({ tiers, packTokens, freeSnapshot, count, pool,
+seqStart, randomness, timedOut? })` derives the tickets from the oracle's randomness (`ticketFor`,
+sha256 through WebCrypto, so it is async), and `settleDraw(draw)` runs it from an owed draw's
+account alone. `MAX_BATCH_SIZE` is 5.
+
 `raydium.curve` exports exact bigint ports of Raydium's own math: `curveBuyExactOut`,
 `curveBuyExactIn`, `curveSellExactIn`, `initialCurve`, `cpmmSwapBaseOutput`, `cpmmSwapBaseInput`, and
 the `ceilDivRate` / `preFeeAmount` helpers they are built from. Every rounding step matches
@@ -152,11 +176,16 @@ 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 `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`
-events as the authoritative history.
+`decodeEvents` and `fetchEvents` return only `PoolCreated`, `PrizesFunded`, `PacksBought`,
+`RandomnessRetried`, `DrawResolved`, `PrizeClaimed` and `TokensSold`. None carries a Gabox fee
+field. `PacksBought` reports the `draw`, `seqStart` and `count` of the purchase, `quoteMint`,
+`quoteDebit` (what the venue charged for the whole batch, in that token), `nativeDebit` (venue
+account rent), `vrfNativeDebit`, `totalNativeDebit`, `freeSnapshot`, `reserved` and the first
+pack's table as `firstPrizes`. `DrawResolved` reports `total`, one `results` entry per pack (`tier`,
+`amount`), the `randomness`, `timedOut` and `paid`. `PrizeClaimed` reports the `amount`, the
+`payer` and the `destination`.
+
+A paid delivery closes the draw atomically; an owed one (`paid: false`) leaves it open and settled
+until a claim closes it. `findResolvedDraw` finds a draw's `DrawResolved` event through the draw
+address's own history. It searches a bounded recent signature history, so production indexers
+should persist the events as the authoritative history, and `settle` lets anyone check them.