@gabox-labs/sdk 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,68 @@
 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.9.0] - 2026-09-19
+
+**Breaking.** The program now sells packs in purchases of one to five, and pays a prize it cannot
+deliver into an owed balance instead of failing. Every earlier devnet pool is abandoned by this
+program version, so nothing this release reads existed before its deploy.
+
+### Added
+
+- `buyPacks(client, { count, nonce?, maxQuoteIn, minFirstMaximum, maxNativeDebit, ... })` opens
+  `count` packs (1 to `MAX_BATCH_SIZE`, which is 5) in one venue trade with one draw and one
+  randomness request. It returns `{ message, draw, nonce, seqStart, count }`. `buyPack` stays as
+  the one-pack form with `minMaximum`, and returns the same shape.
+- `getOffer(client, mint, { count })` prices the whole purchase and adds `count`, `perPackCaps`
+  (the worst-case top prize of each pack), `batchReserved` and `freeSnapshot`.
+- `settle`, `settleDraw` and `ticketFor` reproduce a purchase's settlement from the oracle's
+  randomness, the way the program does it. `reserveFor`, `settleWith`, `perPackCaps`,
+  `chooseIndex`, `uncappedAmounts` and `minTier` are the pure parts.
+- `claimPrize` and `claimPrizeTo` pay an owed prize; `fetchOwedDraws` lists what a wallet is owed;
+  `drawAvailability` reports `settled`, `owed`, `canDeliver` and `canClaim`.
+- `randomNonce`, and `drawAddress(pool, purchaser, nonce)`.
+- Events `PacksBought` and `PrizeClaimed`. `DrawResolved` carries `draw`, `seqStart`, `count`,
+  `total`, `paid` and one `results` entry per pack. `RandomnessRetried` names the draw.
+- `CLAIM_PRIZE_COMPUTE_UNITS`.
+
+### Changed
+
+- `drawAddress` takes the purchaser and a nonce; the pool's sequence counter is no longer in the
+  address. `findResolvedDraw` matches the event's own `draw` field.
+- `Draw` has a new layout and discriminator: a snapshot of the tiers, the pack size and the free
+  inventory, plus `settled`, `randomness`, `timedOut` and `owed`. `Pool` has a new discriminator.
+- `expireDraw` refuses a settled draw before sending; the program pays every pack of an expired
+  purchase its smallest tier.
+
+### Removed
+
+- `PackBought`; `PacksBought` replaces it.
+
+## [0.8.0] - 2026-09-19
+
+The platform's own fees, so the app can show them and claim them.
+
+### Added
+
+- `raydium.fetchPlatformFees(client, { quoteMint })` reads the LaunchLab platform fee vault for one
+  quote asset, and `raydium.claimPlatformFee(client, { feeWallet, quoteMint })` claims it with
+  `claim_platform_fee_from_vault`. Only the wallet the platform config names can sign it.
+- `raydium.fetchLockedPositions(client, owner)` lists every locked CPMM position a wallet holds the
+  fee NFT of, with the pool behind it and what it may withdraw now. `raydium.harvestLockedFees`
+  builds the lock program's `collect_cp_fees` for one of them. `raydium.lockedFeeLp` is the math,
+  checked against the lock program's own event on devnet.
+- `raydiumIds` now carries Raydium's lock program and its authority per cluster, as `lock` and
+  `lockAuthority`. `decodeLockedCpLiquidity` reads a lock record, and `CpmmPoolState` gains
+  `lpMint` and `lpSupply`.
+- `HARVEST_COMPUTE_UNITS`, measured at `102,221` on devnet.
+
+### Changed
+
+- `RaydiumIds` is now the generated cluster table plus the lock ids. A caller that passed
+  `RAYDIUM_DEVNET_IDS` straight from `abi.ts` into a builder passes `raydiumIds('devnet')` instead.
+
 ## [0.7.1] - 2026-09-18
 
 A product correction. Paying in SOL is for buyers, not for creators.

package/README.md

@@ -19,7 +19,9 @@ this SDK shows is the venue's own price with the venue's own fees already inside
 | coin creator | 0.5% of every trade | the pool's `creator_fee_rate` |
 
 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`.
+collects theirs with `raydium.claimCreatorFee` and `raydium.collectCreatorFee`. The platform
+collects its curve share with `raydium.claimPlatformFee`, and after graduation it holds the locked
+LP of every pool, whose trade fees `raydium.harvestLockedFees` pays out.
 
 ## The quote asset
 
@@ -59,7 +61,7 @@ const client = createClient({
 });
 ```
 
-`payWith: 'quote'` on `buyPack` skips the swap and spends the token the wallet already holds.
+`payWith: 'quote'` on `buyPacks` 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
@@ -121,7 +123,7 @@ const message = await createMachine(client, {
 
 **The creator pays the seed, in the machine's own quote token.** There is no swap here: a machine
 quoted in USDC needs the creator to hold at least `maxSeedQuoteIn` of USDC before this transaction
-runs. Only a buyer arrives holding SOL alone, so only `buyPack` and `sellTokens` swap.
+runs. Only a buyer arrives holding SOL alone, so only `buyPacks` and `sellTokens` swap.
 
 `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
@@ -143,28 +145,47 @@ can add more with `extraSeedTokens` (default `0n`), which the program adds to th
 at most 20x; seed beyond what a 20x prize needs stays in the vault as backup for the draws after a
 top-tier hit.
 
-## Buy a pack
+## Buy packs
 
 ```ts
-const offer = await getOffer(client, mint, { user: purchaser.address });
-const message = await buyPack(client, {
+const offer = await getOffer(client, mint, { user: purchaser.address, count: 3 });
+const { message, draw, nonce } = await buyPacks(client, {
   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 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
+One purchase opens `count` packs, 1 to `MAX_BATCH_SIZE` (5): one venue trade for all of them, one
+draw, one randomness request. `buyPack` is the same with `count: 1` and `minMaximum` in place of
+`minFirstMaximum`. Both return the message, the draw's address and its nonce, so the caller can
+watch the draw without deriving anything.
+
+`offer.quoteAmount` is the exact price the venue will charge for the whole purchase 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 `PacksBought` 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 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.
+`offer.prizes` and `offer.maximum` are the first pack's table, capped by the vault as it is now. The
+later packs settle in order: each one is capped at what the vault can pay after the packs before
+it, counting the purchase's own tokens as they arrive. `offer.perPackCaps` is the worst case per
+pack, the top prize it keeps if every earlier pack won its own; on a thin vault the later entries
+fall towards one pack, and a screen should show that next to the first table.
+
+The draw's address is `["draw", pool, purchaser, nonce]`. The builder draws a random nonce unless
+you pass one, so purchases from several buyers, or several from one buyer sent together, never
+collide. A nonce still in use fails at the program; a nonce whose draw already closed opens a new
+purchase, so never reuse the nonce of a purchase that may have landed.
+
+`maxQuoteIn` is the slippage cap for the whole purchase, in the quote token, and the amount put in
+the buyer's quote account before the buy. `minFirstMaximum` is the floor on the first pack's top
+prize; refresh the offer when `PrizeCapChanged` refuses it. `maxNativeDebit` is separate: it caps
+the lamports the handler watches, which are the VRF request and any venue account rent. Gabox adds
+nothing to any of them.
 
 ## Sell
 
@@ -222,20 +243,56 @@ 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.
 
+## Platform fees
+
+```ts
+const owed = await raydium.fetchPlatformFees(client, { quoteMint });   // owed.curveQuote
+await raydium.claimPlatformFee(client, { feeWallet, quoteMint });      // every coin on that quote
+
+const positions = await raydium.fetchLockedPositions(client, feeWallet.address);
+// position.poolAddress, position.claimableLp, position.claimableToken0, position.claimableToken1
+await raydium.harvestLockedFees(client, { owner: feeWallet, position });  // one graduated coin
+```
+
+The platform's curve share waits in one LaunchLab vault per quote asset, and only the wallet the
+platform config names as `platform_fee_wallet` can claim it. At graduation LaunchLab locks the
+whole CPMM pool's LP under Raydium's lock program and mints one fee NFT to the platform NFT wallet.
+`fetchLockedPositions` finds every such NFT in a wallet, reads the lock record and the pool behind
+each, and computes what the position may withdraw now: the LP growth since the last harvest, as
+`lockedFeeLp` works it out from the pool's `x * y` and LP supply. `harvestLockedFees` withdraws
+that LP and pays both sides of the pair into the owner's accounts, closing the WSOL one.
+
 ## Wallet activity
 
-`buyPack` keeps a `WalletActivity` account per buyer, at the PDA `findActivityPda({ purchaser })`
+`buyPacks` 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, 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.
+pack bought in any other quote token are not counted. The buyer pays its rent once, on the first
+purchase, and `buyPacks` resolves the account itself. Read it with
+`fetchWalletActivity(client, wallet)`, which returns `null` before a wallet's first purchase.
 
 ## Draws
 
-Gabox delivers awards and closes draws atomically. Use `fetchEvents`, `decodeEvents` and
-`findResolvedDraw` for final state. There is no Ready, claim or sell-prize flow. Existing base tokens
-can be donated irrevocably with `fundPrizes`; a stalled draw uses `retryDraw` or `expireDraw`.
+The oracle's callback settles every pack of a purchase from one randomness and pays the total into
+the purchaser's coin account, then closes the draw and returns its rent. `findResolvedDraw(client,
+draw)` finds that `DrawResolved` event: `total`, one `results` entry per pack with its tier and
+amount, the `randomness`, and `paid`.
+
+`paid: false` means the callback could not use the purchaser's coin account, because it was
+missing, closed, or no longer the purchaser's. The outcome is still fixed: the draw stays open with
+`settled: true` and the total in `owed`, and nothing can reopen it. `claimPrize(client, { payer,
+draw })` pays it to the purchaser's ATA, creating the account if needed, and anyone may send it.
+`claimPrizeTo(client, { purchaser, draw, destination })` is the purchaser's own way out when they
+changed their ATA's owner: it pays any coin account they own. `fetchOwedDraws(client, purchaser)`
+lists what a wallet is still owed. This path exists so that a buyer cannot make the callback fail,
+read its randomness, and try again; honest buyers never see it.
+
+Anyone can check what a purchase won. `settle({ tiers, packTokens, freeSnapshot, count, pool,
+seqStart, randomness })` recomputes every pack's result the way the program does, and
+`settleDraw(draw)` does it from an owed draw's account alone. `drawAvailability(client, draw)` says
+what can still happen to a draw. A stalled draw uses `retryDraw`, and `expireDraw` fixes it at every
+pack's smallest tier after `TIMEOUT_SLOTS`. Existing base tokens can be donated irrevocably with
+`fundPrizes`.
 
 ## Errors
 
@@ -245,8 +302,13 @@ The generated client decodes the program's own errors by name. The ones a client
 | --- | --- |
 | `InvalidVenue` | The account list did not match. Resolve the venue again and rebuild. |
 | `SlippageExceeded` | The price moved past `maxQuoteIn`, or a cost went past `maxNativeDebit`. |
-| `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. |
+| `PrizeCapChanged` | The first pack's top prize fell below `minFirstMaximum`. Refresh the offer. |
+| `IncorrectTokenDelta` | The venue did not deliver exactly `count` packs. Usually a curve with fewer whole packs left; buy fewer or wait for graduation. |
+| `TooManyPacks` / `ZeroAmount` | `count` is above `MAX_BATCH_SIZE` or zero. The builder refuses these before sending. |
+| `DrawAlreadySettled` | A retry, an expiry or a second callback reached a draw whose outcome is fixed. Nothing to do. |
+| `DrawNotSettled` | A claim on a draw that is still pending. Wait for the callback. |
+| `DrawExpired` | A callback arrived after the deadline; only `expireDraw` remains. |
+| `WrongDestination` | `claimPrizeTo` was given an account that is not the purchaser's, or not for this coin. |
 | `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. |