@gabox-labs/sdk 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -3,6 +3,54 @@
 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.1] - 2026-09-19
+
+### Changed
+
+- `DEFAULT_TIERS` is now Common 80% at 0.5126x, Rare 15% at 2x, Epic 4% at 3.5x, Mythic 1% at
+  10x. The average payout stays 9,499 bps and the mandatory seed stays 2 packs. Every win at least
+  doubles the pack, and the top tier halves so one hit pays 1% of the supply instead of 2%. Pools
+  created before this release keep the table they were created with.
+
+## [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.

package/README.md

@@ -61,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
@@ -123,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
@@ -145,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
 
@@ -245,18 +264,35 @@ that LP and pays both sides of the pair into the owner's accounts, closing the W
 
 ## 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
 
@@ -266,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. |