@gabox-labs/sdk 0.2.0 → 0.7.0

package/README.md

@@ -1,513 +1,248 @@
-# `@gabox-labs/sdk`
+# @gabox-labs/sdk
 
-The TypeScript SDK for gabox machines on Solana. Built on [`@solana/kit`](https://github.com/anza-xyz/kit) 7.
+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 its target, then
+Raydium migrates it into a Raydium CPMM pool and it trades there.
 
-With it you can create a machine, price a pack, buy one, wait for the draw, and sell the prize.
-Every function returns plain kit values: `Address`, `bigint`, and transaction messages your wallet
-signs. The SDK never signs or sends anything itself.
+Devnet today. Mainnet addresses are pinned and tested, but the program is not deployed there yet.
 
-```sh
-npm install @gabox-labs/sdk @solana/kit
-```
-
-ESM only. Node 24 or newer, or any bundler. `@solana/kit` is a peer dependency, so your app keeps
-one copy of it.
-
-> **Devnet only, for now.** The program runs on Solana devnet. A mainnet client is supported by the
-> SDK, but there is nothing to talk to there yet. See [Status](#status).
-
-**Using an AI coding agent?** This repo ships a skill. See [For AI agents](#for-ai-agents).
-
----
-
-## What is a machine?
+## What it costs
 
-A **machine** is a prize pool tied to a brand-new [Pump.fun](https://pump.fun) coin. Creating a
-machine launches the coin and the pool in one transaction.
+Gabox charges nothing. No pack fee, no creator fee inside the program, no referrals. Every price
+this SDK shows is the venue's own price with the venue's own fees already inside it:
 
-A **pack** is a fixed number of tokens: 1,000,000, which is 0.1% of the coin's supply. The coin's
-market decides what a pack costs, so the pack price follows the coin. A pack is bought at the
-venue (Pump's bonding curve, or PumpSwap after graduation), and its tokens go into the pool's
-vault.
+| | On the curve | After graduation |
+| --- | --- | --- |
+| venue | Raydium LaunchLab | Raydium CPMM |
+| trade fee | Raydium's `trade_fee_rate` | the pool's `trade_fee_rate` |
+| Gabox platform | 0.5% of every trade | none |
+| coin creator | 0.5% of every trade | the pool's `creator_fee_rate` |
 
-Each pack creates a **draw**. The draw freezes a **prize table**: up to 8 prizes, each a multiple of
-one pack, each with a number of tickets out of 65,536. Verifiable randomness (MagicBlock VRF) picks
-one prize, and the tokens are sent straight to the buyer's wallet. The buyer signs once, at
-purchase. Keeping the prize needs nothing else. Selling it later is one more transaction.
+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`.
 
-The **creator** chooses an eight-row prize table, or uses `DEFAULT_TIERS`. The creator buys the
-tokens that back the table's top prize at creation, and earns a fee on every pack.
+## The quote asset
 
----
-
-## Quick start
+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.
 
 ```ts
-import {
-  createClient,
-  drawAddress,
-  fetchPoolByMint,
-  getOffer,
-  buyPack,
-  share,
-  watchDraw,
-} from '@gabox-labs/sdk';
-import {
-  address,
-  getSignatureFromTransaction,
-  sendAndConfirmTransactionFactory,
-  signTransactionMessageWithSigners,
-} from '@solana/kit';
-
-// The RPC endpoint goes here. Leave `url` out to use Solana's public devnet endpoint.
-const gabox = createClient({
-  cluster: 'devnet',
-  url: 'https://devnet.helius-rpc.com/?api-key=…', // your provider; wsUrl is derived
-});
-const mint = address('…the coin…');
-const purchaser = /* a TransactionSigner from your wallet */;
-
-// 1. What does a pack cost, and what can it win?
-const offer = await getOffer(gabox, mint, { user: purchaser.address });
-console.log(offer.quoteLamports, offer.prizes, offer.maximum);
-
-// 2. Build the purchase. Pin the draw's sequence number so you know its address.
-const pool = await fetchPoolByMint(gabox, mint);
-const seq = pool!.nextSeq;
-const maxQuoteIn = (offer.quoteLamports * 102n) / 100n; // 2% slippage
-const message = await buyPack(gabox, {
-  mint,
-  purchaser,
-  seq,
-  maxQuoteIn,
-  minMaximum: offer.maximum,
-  maxTotalDebit: maxQuoteIn + share(maxQuoteIn, 200n) + 20_000_000n,
-});
-
-// 3. Sign and send with kit.
-const transaction = await signTransactionMessageWithSigners(message);
-const send = sendAndConfirmTransactionFactory({
-  rpc: gabox.rpc,
-  rpcSubscriptions: gabox.rpcSubscriptions,
-});
-await send(transaction, { commitment: 'confirmed' });
-console.log('bought:', getSignatureFromTransaction(transaction));
-
-// 4. Wait for the prize.
-const draw = await drawAddress(offer.pool, seq);
-const resolved = await watchDraw(gabox, draw, {
-  onChange: (d) => console.log('status', d.status),
-});
-console.log('won', resolved.amount, 'tokens');
+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.
 
-## The client
+## Paying in SOL
 
-`createClient` is the one setup step. Call it once, and pass the result to every SDK function that
-reads or writes the chain.
+Buyers pay in SOL whatever the pool is priced in.
 
-```ts
-import { createClient } from '@gabox-labs/sdk';
+- **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.
 
-const gabox = createClient({ cluster: 'devnet' });
+```ts
+import { createClient, raydiumCpmmRoute } from '@gabox-labs/sdk';
 
-// Your own RPC provider:
-const gabox = createClient({
+// Mainnet gets Jupiter by default. Devnet has no router, so name a CPMM pool for the SOL pair.
+const client = createClient({
   cluster: 'devnet',
-  url: 'https://devnet.helius-rpc.com/?api-key=…',
-  // wsUrl is optional. It follows `url` with `wss://` when left out.
+  route: raydiumCpmmRoute(devnetSolUsdcPool),
 });
 ```
 
-| field                 | required | default                                                                                          |
-| --------------------- | -------- | ------------------------------------------------------------------------------------------------ |
-| `cluster`             | yes      | none. One of `'devnet'`, `'mainnet-beta'`, `'localnet'`                                          |
-| `url`                 | no       | the cluster's public endpoint. `http://127.0.0.1:8899` for `localnet`                           |
-| `wsUrl`               | no       | `url` with `https` → `wss`. The cluster's default WebSocket endpoint when `url` is also left out |
-| `addressLookupTables` | no       | the shared lookup table on `devnet`; none on other clusters. Pass `{}` to turn compression off  |
-
-The client is a plain object with `cluster`, `url`, `wsUrl`, `rpc`, `rpcSubscriptions`, and
-`addressLookupTables`. If you need a custom transport, spread it and replace `rpc`:
-
-```ts
-const gabox = { ...createClient({ cluster: 'devnet' }), rpc: myRpc };
-```
-
-### The URL is checked against the cluster
+`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.
 
-`cluster` has no default, and the URL must agree with it. This is on purpose: every address the
-SDK uses exists on every cluster, so a wrong URL does not fail. It sends a real transaction to the
-wrong network.
+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.
 
-- `devnet` needs a URL that contains `devnet`. A URL that names no cluster is refused too.
-- `mainnet-beta` and `localnet` refuse a URL that names a different cluster. A URL that names no
-  cluster is fine, because private endpoints and local validators often do not say.
+**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.
 
-Both `url` and `wsUrl` are checked. A mismatch throws from `createClient`, before any request.
-
----
-
-## Flows
-
-Every builder returns a `GaboxTransactionMessage`: a version 0 message with the fee payer and a
-fresh blockhash already set. Sign it with `signTransactionMessageWithSigners` and send it with kit.
-A blockhash lasts about a minute, so build the message when the user is ready to sign, not when the
-page loads.
-
-Every builder also accepts `computeUnitLimit`, `computeUnitPrice` (a priority fee, in micro-lamports
-per unit), and `addressLookupTables`. The defaults are generous.
-
-### Create a machine
+## Create a machine
 
 ```ts
-import { createMachine, DEFAULT_TIERS, seedCostEstimate } from '@gabox-labs/sdk';
-import { generateKeyPairSigner } from '@solana/kit';
-
-const mintKeypair = await generateKeyPairSigner();
-const seed = await seedCostEstimate(gabox); // DEFAULT_TIERS
-
-const message = await createMachine(gabox, {
-  creator,                  // TransactionSigner. Pays for everything.
-  mintKeypair,              // Signs once, for the new coin.
-  name: 'Lucky Cat',
-  symbol: 'CAT',
-  uri: 'https://…/metadata.json',
-  feeBps: 100,              // the creator's fee per pack, 0–100 bps (max 1%)
-  tiers: DEFAULT_TIERS,     // optional; the default is a 20× top prize
-  maxSeedLamports: (seed.lamports * 105n) / 100n,
+const client = createClient({ cluster: 'devnet' });
+const estimate = await seedCostEstimate(client);
+const message = await createMachine(client, {
+  creator,
+  mintKeypair,
+  name: 'Gabox',
+  symbol: 'GBX',
+  uri: 'https://example.com/metadata.json',
+  maxSeedQuoteIn: (estimate.quoteAmount * 110n) / 100n,
+  maxSeedNativeDebit: 100_000_000n,
 });
 ```
 
-One transaction, two signers: the creator and the new mint. The creator pays for the coin, the
-pool, and the **seed**.
+One transaction, two signers: the mint keypair and the creator. `initialize_pool` refuses to run
+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 seed is the inventory that backs the top prize. The first pack must be able to pay that prize in
-full. `DEFAULT_TIERS` has 75%, 20%, 4%, and 1% odds at 0.52×, 1.2×, 3×, and 20× respectively, and
-needs nineteen extra packs in the vault. `seedCostEstimate` tells you what that costs on a fresh
-Pump curve, in lamports and tokens. `maxSeedLamports` is the creator's slippage cap on that buy.
+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.
 
-`tiers` is optional and defaults to `DEFAULT_TIERS`, the table the Gabox app creates pools with. A
-creator may instead supply an eight-row `Tier[]`. The SDK validates it locally and the program
-validates it again: ticket counts must total 65,536, unused rows must be all-zero, expected payout
-cannot exceed one pack, each live tier must pay at least one token, and the largest prize must be at
-least one pack. `seedCostEstimate(gabox, tiers)` previews the exact custom table before creating.
+`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.
 
-### Price a pack
+### Another quote asset
 
 ```ts
-import { getOffer } from '@gabox-labs/sdk';
-
-const offer = await getOffer(gabox, mint, { user: buyer.address });
-```
-
-`getOffer` reads the pool, the vault, and the venue, and returns everything a buy screen needs:
-
-| field                                  | meaning                                                                       |
-| -------------------------------------- | ----------------------------------------------------------------------------- |
-| `quoteLamports`                        | the pack price right now: what the venue charges for one pack, venue fees included |
-| `feeLamports`                          | the creator's fee, paid on top                                                |
-| `protocolLamports`                     | the protocol's 1%, paid on top                                                |
-| `prizes`                               | the prize table this pack would get: `{ amount, tickets }`, amounts in tokens |
-| `maximum`, `minimum`                   | the largest and smallest prize on that table                                  |
-| `uncapped`                             | the jackpot with no inventory cap. Equal to `maximum` when the pool is healthy |
-| `isSeeded`                             | `maximum === uncapped`. Show a warning when this is `false`                    |
-| `venue`                                | `'pump'` or `'pumpswap'`: where the buy would route right now                 |
-| `inventory`, `reserved`, `free`        | vault balance, tokens reserved by open draws, and the difference              |
-| `maxMultiplierBps`, `averageMultiplierBps` | the table's top and ticket-weighted average multipliers                   |
-
-Prizes can be capped. The table is fixed, but a prize can never exceed what the vault holds beyond
-what open draws already reserve. When the cap bites, `maximum < uncapped` and `isSeeded` is
-`false`. The pack still sells. It just pays less than the table says, and a buyer should see that.
-
-`offerFromState` does the same computation from values you already fetched, with no network call.
-
-### Buy a pack
-
-```ts
-import { buyPack, share } from '@gabox-labs/sdk';
-
-const maxQuoteIn = (offer.quoteLamports * 102n) / 100n;
-const message = await buyPack(gabox, {
-  mint,
-  purchaser,                // TransactionSigner. The only signer.
-  maxQuoteIn,
-  minMaximum: offer.maximum,
-  maxTotalDebit: maxQuoteIn + share(maxQuoteIn, 200n) + 20_000_000n,
-  seq: pool.nextSeq,        // optional, see below
-  referrer,                 // optional, see Referrals
+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,
 });
 ```
 
-The buyer signs three limits:
-
-| limit           | what it caps                                                                                                            |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `maxQuoteIn`    | the venue price, in lamports. The token count is fixed, so the price is the only thing that moves. Add your slippage. |
-| `minMaximum`    | the top prize, in tokens. Fails if inventory dropped so far that the top prize is now smaller than this.               |
-| `maxTotalDebit` | venue price + creator fee + protocol fee + the randomness request fee, all together. Both fees are ~1% of the price.    |
+`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.
 
-`maxTotalDebit` does not include account rent or the transaction fee. Budget a few million lamports
-on top; the example above adds 0.02 SOL.
+`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.
 
-**`seq` pins the draw.** Every draw has a sequence number, and its address is derived from it. Pass
-`seq: pool.nextSeq` so you know the draw's address before the transaction lands, and so that a
-retry after a stale blockhash cannot buy a second pack by accident. Then `drawAddress(pool, seq)`
-gives you the address to watch.
+### The seed
 
-On the PumpSwap route, `buyPack` also adds the instructions that wrap SOL into WSOL for the buyer.
-You do not need to handle that.
+Pool creation buys a mandatory seed: enough tokens to make a 3x top prize payable on the first pack,
+or the full top prize when the table's top tier is below 3x. `math.seedTokens` computes it. A creator
+can add more with `extraSeedTokens` (default `0n`), which the program adds to the same seed trade.
+`seedCostEstimate` reports the mandatory `seedTokens`, the `extraSeedTokens` passed in, their
+`totalSeedTokens`, and the exact cost of buying the total on a fresh curve. A table's top tier can be
+at most 20x; seed beyond what a 20x prize needs stays in the vault as backup for the draws after a
+top-tier hit.
 
-### Wait for the draw
+## Buy a pack
 
 ```ts
-import { watchDraw } from '@gabox-labs/sdk';
-
-const resolved = await watchDraw(gabox, draw, {
-  signal: AbortSignal.timeout(180_000),
-  onChange: (d) => console.log(d.status, d.attempts),
+const offer = await getOffer(client, mint, { user: purchaser.address });
+const message = await buyPack(client, {
+  mint,
+  purchaser,
+  maxQuoteIn: (offer.quoteAmount * 102n) / 100n,
+  minMaximum: (offer.maximum * 98n) / 100n,
+  maxNativeDebit: 100_000_000n,
 });
-// resolved.amount: tokens won, already in the buyer's wallet
 ```
 
-`watchDraw` subscribes to the draw account and resolves when the prize is delivered. A draw that
-was already delivered resolves at once. There is no built-in timeout; pass a `signal` with the
-patience your UI wants. Randomness usually arrives within a few seconds.
-
-### Keep or sell
+`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.
 
-Keeping the prize needs nothing. The tokens are already in the buyer's associated token account.
+`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.
 
-Selling goes through the SDK, so the sale routes to the right venue:
+## Sell
 
 ```ts
-import { sellTokens, pump } from '@gabox-labs/sdk';
-
-const grossOutput = await pump.sellQuote(gabox, mint, resolved.amount, { user: purchaser.address });
-const message = await sellTokens(gabox, {
+const venue = await resolveVenue(client, { mint, user: seller.address });
+const message = await sellTokens(client, {
   mint,
-  seller: purchaser,
-  amount: resolved.amount,
-  minQuoteOutput: (grossOutput * 95n) / 100n, // 5% slippage. Must be > 0.
+  seller,
+  amount,
+  minQuoteOutput: (venue.quoteSell(amount) * 98n) / 100n,
+  maxNativeDebit: 100_000_000n,
 });
 ```
 
-`minQuoteOutput` is the floor on what the venue pays, before the protocol's 1% of the proceeds. On
-the Pump route the seller receives SOL. On the PumpSwap route the seller receives WSOL in their
-WSOL account; add an unwrap if they want lamports.
+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.
 
-### Fund a machine's prizes
+## Which venue
 
-Anyone can add tokens to a machine's vault. This raises the cap, which uncaps prizes.
+`resolveVenue(client, { mint, user })` reads the LaunchLab pool's `status` and follows it:
 
-```ts
-import { fundPrizes, fundPrizesWithBuy, seedShortfall } from '@gabox-labs/sdk';
+- `0`: the curve is still selling, so the trade routes to LaunchLab.
+- `1`: the raise is finished and Raydium is migrating the coin. Nothing trades. This throws, and the
+  message says to retry. On devnet the move usually finishes within a minute.
+- `2`: the coin graduated, so the trade routes to its CPMM pool.
 
-// Tokens the donor already holds:
-await fundPrizes(gabox, { mint, funder, amount });
+A migrated CPMM pool is usually at `["pool", cpswap_config, token_0, token_1]`, but not always:
+Raydium picks a fresh address when that one is taken. So the pool has to prove itself from its own
+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, both token
+programs and the oracle out of the pool account rather than deriving them.
 
-// Or buy them and donate in one transaction. `seedShortfall(offer)` is the amount that
-// uncaps the top prize right now.
-await fundPrizesWithBuy(gabox, { mint, funder, tokens: seedShortfall(offer), maxQuoteIn });
-```
-
-Donations cannot be withdrawn.
-
-### Referrals
-
-A wallet can bind itself to a referrer, once and permanently. After that, every pack it buys pays
-the referrer 1% of the creator's fee on that pack. The buyer pays nothing extra.
-
-```ts
-import { bindReferrer, claimReferral, fetchReferralReward } from '@gabox-labs/sdk';
+`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.
 
-// The referred wallet signs the binding:
-await bindReferrer(gabox, referee, referrerAddress);
-
-// Or bind and buy in one transaction. Ignored when the wallet is already bound:
-await buyPack(gabox, { ...input, referrer: referrerAddress });
-
-// The referrer reads and claims what a pool owes them:
-const owed = await fetchReferralReward(gabox, poolAddress, referrer.address);
-await claimReferral(gabox, referrer, poolAddress);
-```
-
-### Stuck draws
-
-Randomness can fail to arrive. Two permissionless transactions keep a draw moving. Anyone can send
-them.
+## Creator fees
 
 ```ts
-import { drawAvailability, retryDraw, expireDraw } from '@gabox-labs/sdk';
-
-const state = await drawAvailability(gabox, draw);
-// { canRetry, canExpire, slotsUntilRetry, slotsUntilExpiry, attempts, status }
+const owed = await raydium.fetchCreatorFees(client, { creator: creator.address, mint });
+// owed.quoteMint, owed.curveQuote, owed.cpmmQuote, owed.cpmmTokens
 
-if (state?.canRetry) await retryDraw(gabox, { payer, pool, draw, maxVrfDebit: 5_000_000n });
-if (state?.canExpire) await expireDraw(gabox, { payer, pool, draw });
+await raydium.claimCreatorFee(client, { creator });          // every SOL coin on the curve, at once
+await raydium.collectCreatorFee(client, { mint, creator });  // one graduated coin
 ```
 
-- `retryDraw` asks for randomness again. Allowed 300 slots after the last attempt, up to 3 attempts
-  in total. The payer covers the request fee, capped by `maxVrfDebit`.
-- `expireDraw` settles a **pending** draw that never received randomness, 216,000 slots (about one
-  day) after the purchase. It pays the **smallest prize** on the draw's table. It is not a refund.
-  It rejects a `Ready` draw: randomness has already resolved that outcome and the normal delivery
-  path must pay it. Tell buyers this before they pay.
+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.
 
-Use `drawAvailability` to show a countdown instead of sending a transaction that fails.
+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
 
-## Reading state
+`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, 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.
 
-| function                                  | returns                                                       |
-| ----------------------------------------- | ------------------------------------------------------------- |
-| `fetchPoolByMint(gabox, mint)`            | the machine's `Pool`, or `null`                               |
-| `fetchPoolAt(gabox, poolAddress)`         | the same, by pool address                                     |
-| `fetchPoolInventory(gabox, mint)`         | the pool plus live `inventory`, `reserved`, `free`            |
-| `fetchDraw(gabox, drawAddress)`           | a `Draw`, or `null` once it is delivered and closed           |
-| `listPools(gabox)`                        | every machine                                                 |
-| `listDraws(gabox, { pool?, purchaser? })` | open draws, filtered by machine, by buyer, or both            |
-| `listDrawsByPurchaser(gabox, wallet)`     | "what am I still waiting on"                                  |
-| `listReferralLinksByReferrer(gabox, ref)` | every wallet bound to a referrer                              |
-| `fetchEvents(gabox, signature)`           | the SDK events one transaction emitted                        |
+## Draws
 
-The `list*` functions use `getProgramAccounts`. Public RPC endpoints rate-limit that call, so cache
-the result in your app rather than calling it on every page view.
-
-Addresses are derived, not looked up: `poolAddress(mint)`, `drawAddress(pool, seq)`,
-`vaultAddress(mint)`, `referralLinkAddress(wallet)`, `referralAddress(pool, referrer)`, and
-`associatedTokenAddress(owner, mint)`.
-
-## Events
-
-Every transaction emits typed events. Decode them from a confirmed signature:
-
-```ts
-import { fetchEvents } from '@gabox-labs/sdk';
-
-for (const event of await fetchEvents(gabox, signature)) {
-  if (event.name === 'PackBought') console.log(event.data.venueDebit, event.data.prizes);
-  if (event.name === 'DrawResolved') console.log(event.data.amount, event.data.timedOut);
-}
-```
-
-Event names: `PoolCreated`, `PackBought`, `DrawResolved`, `TokensSold`, `PrizesFunded`,
-`RandomnessRetried`, `PrizeRedeemed`. `decodeEvents(logs)` does the same from log lines you already
-have.
+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`.
 
 ## Errors
 
-A failed transaction carries a program error code. The generated namespace decodes it:
-
-```ts
-import { generated } from '@gabox-labs/sdk';
-
-try {
-  await send(transaction, { commitment: 'confirmed' });
-} catch (error) {
-  // `message` is the GaboxTransactionMessage you built. It tells the check which instruction is ours.
-  if (generated.isGaboxV2Error(error, message, generated.GABOX_V2_ERROR__SLIPPAGE_EXCEEDED)) {
-    // ask the user to widen maxQuoteIn and rebuild
-  } else if (generated.isGaboxV2Error(error, message)) {
-    console.log(generated.getGaboxV2ErrorMessage(error.context.code));
-  } else {
-    throw error;
-  }
-}
-```
-
-`getGaboxV2ErrorMessage` returns a readable message in development builds and a placeholder when
-`NODE_ENV` is `production`, to keep bundles small.
-
-The ones a UI will meet:
-
-| error                | when                                                                       |
-| -------------------- | -------------------------------------------------------------------------- |
-| `SlippageExceeded`   | the venue price moved past `maxQuoteIn`, or the sale returned less than `minQuoteOutput` |
-| `PrizeCapChanged`    | the top prize fell below `minMaximum` between quote and send                |
-| `RetryTooSoon`       | `retryDraw` before 300 slots passed                                        |
-| `RetryUnavailable`   | `retryDraw` after 3 attempts, or on a draw that is no longer pending       |
-| `NotExpired`         | `expireDraw` before the deadline                                           |
-| `NotPending`         | `expireDraw` on a draw whose randomness has already resolved               |
-| `InvalidReferral`    | a self-referral, or a link that does not match                             |
-| `ZeroAmount`         | a zero `amount` or a zero `minQuoteOutput`                                 |
-
-The SDK also throws plain `Error`s before building, for example when a mint has no machine, when
-`maxQuoteIn` is not positive, or when a message would exceed Solana's 1,232-byte limit.
-
----
-
-## Units and conventions
-
-- **Tokens** are in base units. Every Pump coin has 6 decimals, so `1_000_000n` is one whole token
-  and a pack (`PACK_TOKENS`) is `1_000_000n * 1_000_000n`.
-- **SOL** is in lamports. WSOL is used on the PumpSwap route, and the SDK handles the wrapping.
-- **Every amount is a `bigint`.** Basis points are `number`. `share(amount, bps)` computes a share.
-- **Addresses** are kit `Address` strings. The SDK never exposes `PublicKey` or `BN`.
-- **Async by default.** Address derivation is async, because kit's PDA derivation is.
-
-## Constants
-
-| constant                | value                              | meaning                                                   |
-| ----------------------- | ---------------------------------- | --------------------------------------------------------- |
-| `PACK_TOKENS`           | `1_000_000n * 1_000_000n`          | tokens in one pack. Prefer `pool.packTokens` when you have a pool |
-| `PROTOCOL_FEE_BPS`      | `100n`                             | the protocol's 1% on every purchase and every sale         |
-| `MAX_FEE_BPS`           | `100`                              | the largest creator fee: 1% of the venue price             |
-| `REFERRAL_FEE_BPS`      | `100n`                             | the referrer's 1% of the creator fee                       |
-| `RETRY_SLOTS`           | `300n`                             | slots between randomness attempts                          |
-| `MAX_ATTEMPTS`          | `3`                                | randomness attempts per draw, counting the first           |
-| `TIMEOUT_SLOTS`         | `216_000n`                         | slots until a draw can be expired                          |
-| `TIERS`, `TICKETS`      | `8`, `65_536`                      | rows in a prize table, and tickets per table               |
-| `GABOX_PROGRAM_ID`      | `GaBoxR9nYcK1zeu8EvSJVHV3SrYpCFmvbh2MLgobMcUA` | the program                                    |
-
-## Entry points
-
-| import                    | what                                                                                     |
-| ------------------------- | ---------------------------------------------------------------------------------------- |
-| `@gabox-labs/sdk`           | everything above: the client, builders, readers, math, events, constants                 |
-| `@gabox-labs/sdk/generated` | the low-level generated client: instruction builders, account and event codecs, error codes. Also available as the `generated` namespace |
-| `@gabox-labs/sdk/pump`      | the venue layer: `resolveVenue`, `curveQuote`, `sellQuote`, and the Pump/PumpSwap account lists. Also available as the `pump` namespace |
-
-The `generated` functions take a kit `Rpc` (`gabox.rpc`), not the client.
-
----
-
-## For AI agents
-
-This repository is agent-ready.
-
-- **[`skills/gabox-sdk/SKILL.md`](skills/gabox-sdk/SKILL.md)** teaches an agent how to integrate the
-  SDK: setup, the flows, the limits a buyer signs, and the mistakes to avoid. It follows the
-  [Agent Skills](https://agentskills.io) format, so it installs into Claude Code, Cursor, Codex,
-  and others:
-
-  ```sh
-  npx skills add gabox-labs/gabox-sdk
-  ```
-
-- **[`skills/gabox-sdk/references/api.md`](skills/gabox-sdk/references/api.md)** is a compact
-  reference of every exported function and type.
-- **[`llms.txt`](llms.txt)** points a model at the right files.
-- **[`AGENTS.md`](AGENTS.md)** is for agents working on this repository itself.
-
-## Status
-
-- **Devnet only.** Mainnet is not live.
-- The devnet program revision this SDK targets is live and verified at slot `497869792`; see the
-  [0.2.0 changelog](CHANGELOG.md).
-  Machines from the previous account layout remain incompatible: `fetchPoolByMint` excludes them,
-  and direct reads report an "older devnet account layout" migration requirement.
-- The Pump bonding-curve route has an end-to-end test on devnet (`GABOX_DEVNET_E2E=1`). The
-  PumpSwap route (coins that graduated off the curve) has unit coverage only.
-- The API is `0.x`. Breaking changes bump the minor version and are listed in the changelog.
-
-## Contributing
-
-See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development setup and the checks that run before
-a release.
+The generated client decodes the program's own errors by name. The ones a client meets most:
 
-## License
+| Error | What to do |
+| --- | --- |
+| `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. |
+| `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. |
 
-[MIT](LICENSE)
+See [the API reference](skills/gabox-sdk/references/api.md).