@gabox-labs/sdk 0.1.1 → 0.6.0

package/skills/gabox-sdk/SKILL.md

@@ -1,163 +1,62 @@
 ---
 name: gabox-sdk
-description: Integrate gabox machines on Solana with @gabox-labs/sdk (TypeScript, @solana/kit 7). Create a machine on a new Pump.fun coin, price and buy packs, watch a draw resolve, sell the prize, handle referrals and stuck draws. Use when a task mentions gabox, machines, packs, draws, prize pools on Pump.fun coins, or @gabox-labs/sdk.
+description: Integrate Gabox machines on Solana with @gabox-labs/sdk and @solana/kit. Use for Gabox pools, packs, Raydium LaunchLab and CPMM venues, draws, prizes, creator fees, and SDK integration.
 ---
 
-# gabox SDK
+# Gabox SDK
 
-`@gabox-labs/sdk` is the TypeScript client for gabox machines. A **machine** is a prize pool tied to a
-new Pump.fun coin. A **pack** is 1,000,000 tokens of that coin; its price follows the coin. Buying
-a pack creates a **draw** with a frozen prize table; verifiable randomness picks the prize and the
-tokens land in the buyer's wallet. Full docs: `README.md` in the package. Every exported
-function and type: `references/api.md`.
+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.
 
-## Setup
+Use only devnet clients today. Pass `GaboxClient` first to every chain function; all amounts are
+`bigint`.
 
-```sh
-npm install @gabox-labs/sdk @solana/kit
-```
-
-ESM only. Node 24+. `@solana/kit` is a peer dependency. The program is on **devnet only** today.
-
-```ts
-import { createClient } from '@gabox-labs/sdk';
-const gabox = createClient({ cluster: 'devnet' });           // public devnet RPC
-const gabox = createClient({ cluster: 'devnet', url: RPC });  // your provider; wsUrl follows
-```
+Gabox charges no fee at all. Every price the SDK shows already includes Raydium's own fees: on the
+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.
 
-Pass `gabox` as the first argument to every SDK function. `cluster` is required and the URL must
-agree with it: a devnet client refuses a URL without `devnet` in it. This throws at
-`createClient`, before any request.
-
-## Conventions that trip people up
-
-- **All amounts are `bigint`.** Lamports for SOL, base units for tokens (6 decimals: one pack is
-  `1_000_000n * 1_000_000n`). Never mix `number` into arithmetic. Basis points are `number`.
-- **Builders return a message, not a signature.** Sign with kit's
-  `signTransactionMessageWithSigners` and send with `sendAndConfirmTransactionFactory({ rpc:
-  gabox.rpc, rpcSubscriptions: gabox.rpcSubscriptions })`. The SDK never signs or sends.
-- **Build right before signing.** The message carries a blockhash that expires in about a minute.
-- **Address derivation is async.** `await poolAddress(mint)`, `await drawAddress(pool, seq)`.
-- **Low-level `generated.*` functions take `gabox.rpc`**, not the client.
-- **Keep the surface kit-only.** Do not import `@solana/web3.js` to talk to this SDK.
-
-## Flow 1: price and buy a pack
+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.
 
 ```ts
-import { buyPack, drawAddress, fetchPoolByMint, getOffer, share, watchDraw } from '@gabox-labs/sdk';
+import { buyPack, createClient, getOffer } from '@gabox-labs/sdk';
 
+const gabox = createClient({ cluster: 'devnet' });
 const offer = await getOffer(gabox, mint, { user: purchaser.address });
-// offer.quoteLamports  the pack price now (venue fees included)
-// offer.prizes         [{ amount, tickets }], amounts in tokens, already capped by inventory
-// offer.maximum        top prize; offer.isSeeded === false means the cap is biting: warn the user
-
-const pool = await fetchPoolByMint(gabox, mint);
-const seq = pool!.nextSeq;                                   // pin the draw
-const maxQuoteIn = (offer.quoteLamports * 102n) / 100n;     // 2% slippage
 const message = await buyPack(gabox, {
   mint,
-  purchaser,                                                 // TransactionSigner, the only signer
-  seq,
-  maxQuoteIn,
-  minMaximum: offer.maximum,
-  maxTotalDebit: maxQuoteIn + share(maxQuoteIn, 200n) + 20_000_000n,
-});
-// ...sign and send...
-const draw = await drawAddress(offer.pool, seq);
-const resolved = await watchDraw(gabox, draw, { signal: AbortSignal.timeout(180_000) });
-// resolved.amount = tokens won, already in the purchaser's associated token account
-```
-
-The three limits the buyer signs:
-
-| limit           | caps                                                                 | set it to                              |
-| --------------- | -------------------------------------------------------------------- | -------------------------------------- |
-| `maxQuoteIn`    | the venue price in lamports                                          | `quoteLamports` + your slippage        |
-| `minMaximum`    | the top prize in tokens; fails if inventory dropped                  | `offer.maximum`                        |
-| `maxTotalDebit` | price + creator fee + protocol fee + randomness fee (both fees ≈ 1%) | `maxQuoteIn + share(maxQuoteIn, 200n) + margin` |
-
-`maxTotalDebit` excludes rent and the transaction fee. Add ~0.02 SOL of margin. Always pass `seq`
-so a retry after a stale blockhash cannot buy a second pack.
-
-## Flow 2: keep or sell
-
-Keeping needs no transaction. Selling routes through the SDK:
-
-```ts
-import { pump, sellTokens } from '@gabox-labs/sdk';
-const gross = await pump.sellQuote(gabox, mint, amount, { user: seller.address });
-const message = await sellTokens(gabox, {
-  mint, seller, amount,
-  minQuoteOutput: (gross * 95n) / 100n,   // must be > 0
+  purchaser,
+  maxQuoteIn: (offer.quoteAmount * 102n) / 100n,
+  minMaximum: (offer.maximum * 98n) / 100n,
+  maxNativeDebit: 100_000_000n,
 });
 ```
 
-On the Pump route the seller gets SOL. On PumpSwap (a graduated coin) the seller gets WSOL.
+`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.
 
-## Flow 3: create a machine
-
-```ts
-import { createMachine, seedCostEstimate } from '@gabox-labs/sdk';
-import { generateKeyPairSigner } from '@solana/kit';
+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.
 
-const mintKeypair = await generateKeyPairSigner();
-const seed = await seedCostEstimate(gabox, 50_000, 'balanced');
-const message = await createMachine(gabox, {
-  creator, mintKeypair,                       // two signers
-  name, symbol, uri,                          // Pump metadata
-  feeBps: 100,                                // creator fee, 0..100 (max 1%)
-  riskProfile: 'balanced',                    // 'conservative' | 'balanced' | 'jackpot'
-  jackpotBps: 50_000,                         // top prize = 5 packs
-  maxSeedLamports: (seed.lamports * 105n) / 100n,
-});
-```
-
-The creator buys the **seed** that backs the jackpot: a 5× jackpot needs four extra packs of
-tokens, 10× needs nine, 1× needs none. Preview the table with `jackpotTiers(jackpotBps, profile)`.
-
-## Flow 4: stuck draws (permissionless)
-
-```ts
-import { drawAvailability, expireDraw, retryDraw } from '@gabox-labs/sdk';
-const s = await drawAvailability(gabox, draw);
-if (s?.canRetry)  await retryDraw(gabox, { payer, pool, draw, maxVrfDebit: 5_000_000n });
-if (s?.canExpire) await expireDraw(gabox, { payer, pool, draw });
-```
-
-Retry: 300 slots after the last attempt, 3 attempts total. Expire: after 216,000 slots (~1 day);
-pays the **smallest** prize, not a refund. Show `slotsUntilRetry` / `slotsUntilExpiry` as a countdown.
-
-## Referrals
-
-```ts
-await bindReferrer(gabox, referee, referrerAddress);          // referee signs, permanent
-await buyPack(gabox, { ...input, referrer: referrerAddress }); // or bind + buy in one tx
-await claimReferral(gabox, referrer, poolAddress);            // referrer collects
-```
-
-The referrer earns 1% of the creator's fee per pack. The buyer pays nothing extra.
-
-## Reading state
-
-`fetchPoolByMint`, `fetchPoolInventory`, `fetchDraw`, `listPools`, `listDraws({ pool?, purchaser? })`,
-`fetchEvents(gabox, signature)`. `list*` uses `getProgramAccounts`: cache it. Events:
-`PoolCreated`, `PackBought`, `DrawResolved`, `TokensSold`, `PrizesFunded`, `RandomnessRetried`.
-
-## Errors
-
-```ts
-import { generated } from '@gabox-labs/sdk';
-if (generated.isGaboxV2Error(error, message, generated.GABOX_V2_ERROR__SLIPPAGE_EXCEEDED)) { /* widen maxQuoteIn */ }
-if (generated.isGaboxV2Error(error, message)) console.log(generated.getGaboxV2ErrorMessage(error.context.code));
-```
+`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.
 
-Common: `SlippageExceeded`, `PrizeCapChanged` (refresh the offer), `RetryTooSoon`,
-`RetryUnavailable`, `NotExpired`, `InvalidReferral`, `ZeroAmount`.
+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.
 
-## Do not
+`buyPack` keeps a per-wallet `WalletActivity` account (`fetchWalletActivity(client, wallet)`, `null`
+before a wallet's first purchase); it resolves the account itself.
 
-- Do not guess the draw address: derive it with `drawAddress(pool, seq)` from the `seq` you pinned.
-- Do not set `minQuoteOutput` or `maxQuoteIn` to `0n`. The program rejects them.
-- Do not call `getOffer` once and reuse it for minutes. Prices move with the coin.
-- Do not point a `'devnet'` client at any other URL. Use `cluster: 'localnet'` for a test validator.
-- Do not run against mainnet. The program is not deployed there.
+Use `fetchEvents` and `findResolvedDraw` for final delivery, 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

@@ -1,149 +1,106 @@
-# `@gabox-labs/sdk` API reference
-
-Every function that reads or writes the chain takes `client: GaboxClient` first. Every builder
-returns `Promise<GaboxTransactionMessage>`: a version 0 kit message with the fee payer and a fresh
-blockhash set, ready for `signTransactionMessageWithSigners`. All amounts are `bigint`.
-
-## Client (`src/rpc.ts`)
-
-| function / type | signature | notes |
-| --- | --- | --- |
-| `createClient` | `(config: ClientConfig) => GaboxClient` | the init step. Throws if the URL contradicts the cluster |
-| `ClientConfig` | `{ cluster: Cluster; url?: string; wsUrl?: string; addressLookupTables?: AddressesByLookupTableAddress }` | `cluster` is required |
-| `GaboxClient` | `{ cluster; url; wsUrl; rpc: GaboxRpc; rpcSubscriptions: GaboxRpcSubscriptions; addressLookupTables }` | a plain object; spread to replace `rpc` |
-| `Cluster` | `'devnet' \| 'mainnet-beta' \| 'localnet'` | |
-| `CLUSTER_ENDPOINTS` | `Record<Cluster, { url; wsUrl }>` | the defaults |
-| `clusterNamedBy` | `(url: string) => Cluster \| 'testnet' \| null` | substring check |
-| `assertClusterUrl` | `(cluster: Cluster, url: string) => void` | the guard, exported for scripts |
-| `websocketUrlFor` | `(url: string) => string` | `https`→`wss`, `http`→`ws` |
-| `defaultAddressLookupTables` | `(cluster: Cluster) => AddressesByLookupTableAddress` | devnet's shared table; `{}` elsewhere |
-| `GaboxRpc`, `GaboxRpcSubscriptions` | kit `Rpc<SolanaRpcApi>`, `RpcSubscriptions<SolanaRpcSubscriptionsApi>` | |
-
-## Offers and prices (`src/offer.ts`)
-
-| function | signature | notes |
-| --- | --- | --- |
-| `getOffer` | `(client, mint: Address, options?: { user?: Address; venue?: VenueKind }) => Promise<PackOffer>` | two reads: pool + vault, then the venue. Throws if the mint has no machine |
-| `offerFromState` | `(inventory: PoolInventory, venue: VenueKind, quoteLamports: bigint) => PackOffer` | pure |
-| `seedShortfall` | `(offer: PackOffer) => bigint` | tokens that would uncap the top prize |
-
-`PackOffer` fields: `mint`, `pool`, `packTokens`, `quoteLamports`, `feeBps`, `feeLamports`,
-`protocolLamports`, `seedLamports`, `seedTokens`, `venue`, `prizes: Prize[]`, `maximum`, `minimum`,
-`uncapped`, `inventory`, `reserved`, `free`, `isFirstPack`, `isSeeded`, `maxMultiplierBps`,
-`averageMultiplierBps`.
-
-## Transaction builders (`src/tx/`, `src/referral.ts`)
-
-| function | input | signers |
-| --- | --- | --- |
-| `createMachine` | `{ creator; mintKeypair; name; symbol; uri; feeBps: number; riskProfile: RiskProfile; jackpotBps: number; maxSeedLamports: bigint; feeRecipientIndex?; buybackRecipientIndex? }` | creator, mintKeypair |
-| `seedCostEstimate` | `(client, jackpotBps: number, riskProfile: RiskProfile) => Promise<{ tiers: Tier[]; seedTokens: bigint; lamports: bigint }>` | read only |
-| `buyPack` | `{ mint; purchaser; maxQuoteIn: bigint; minMaximum: bigint; maxTotalDebit: bigint; seq?: bigint; venue?; wrapLamports?; cashback?; referrer?: Address }` | purchaser |
-| `sellTokens` | `{ mint; seller; amount: bigint; minQuoteOutput: bigint; venue? }` | seller |
-| `fundPrizes` | `{ mint; funder; amount: bigint; source?: Address }` | funder |
-| `fundPrizesWithBuy` | `{ mint; funder; tokens: bigint; maxQuoteIn: bigint; venue?; wrapLamports? }` | funder |
-| `retryDraw` | `{ payer; pool; draw; maxVrfDebit: bigint }` | payer (anyone) |
-| `expireDraw` | `{ payer; pool; draw }` | payer (anyone) |
-| `bindReferrer` | `(client, referee: TransactionSigner, referrer: Address, options?) ` | referee |
-| `claimReferral` | `(client, referrer: TransactionSigner, pool: Address, options?)` | referrer |
-| `claimPrize`, `sellPrize`, `quoteSellPrize` | legacy draws only (created before automatic delivery) | purchaser |
-| `buildMessage` | `(client, feePayer, instructions: Instruction[], options: BuildOptions)` | assemble your own |
-
-Every input also accepts `BuildOptions`: `computeUnitLimit?: number`, `computeUnitPrice?: number | bigint`
-(micro-lamports per unit), `addressLookupTables?`.
-
-`drawAvailability(client, draw) => Promise<DrawAvailability | null>` returns
-`{ status, attempts, slotsUntilRetry, slotsUntilExpiry, canRetry, canExpire }`.
-
-## Readers (`src/accounts.ts`, `src/events.ts`)
-
-| function | returns |
+# Gabox SDK API
+
+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.
+
+## Client and reads
+
+| Function | Result |
 | --- | --- |
+| `createClient({ cluster: 'devnet', ... })` | `GaboxClient` |
 | `fetchPoolByMint(client, mint)` | `Pool \| null` |
-| `fetchPoolAt(client, poolAddress)` | `Pool \| null` |
-| `fetchPoolInventory(client, mint)` | `{ pool, poolAddress, vault, inventory, reserved, free } \| null` |
-| `fetchVaultBalance(client, mint)` | `bigint` |
-| `fetchDraw(client, drawAddress)` | `Draw \| null` (null once delivered and closed) |
-| `fetchReferralReward(client, pool, referrer)` | `Referral \| null` |
-| `listPools(client)` | `{ address, data: Pool }[]` |
-| `listDraws(client, { pool?, purchaser? })` | `{ address, data: Draw }[]` |
-| `listDrawsByPool(client, pool)`, `listDrawsByPurchaser(client, wallet)` | same |
-| `listReferralLinksByReferrer(client, referrer)` | `{ address, data: ReferralLink }[]` |
-| `resolveReferral(client, purchaser, pool)` | `{ link, referrer, referral } \| null` |
-| `fetchEvents(client, signature)` | `GaboxEvent[]` |
-| `decodeEvents(logs: string[])`, `decodeEvent(bytes)` | pure |
-| `watchDraw(client, drawAddress, { signal?, onChange? })` | `Promise<Draw>` resolves on delivery |
-
-`Pool` fields: `creator`, `mint`, `tokenProgram`, `vault`, `bump`, `packTokens`, `feeBps`,
-`seedLamports`, `seedTokens`, `tiers: Tier[]`, `nextSeq`, `reserved`.
-
-`Draw` fields: `pool`, `purchaser`, `seq`, `status: DrawStatus` (`Pending | Ready`), `requestSlot`,
-`lastAttemptSlot`, `attempts`, `maximum`, `minimum`, `prizes`, `amount`, `randomness`, `timedOut`.
-
-`GaboxEvent` is a union on `name`: `PoolCreated`, `PrizesFunded`, `PackBought`, `RandomnessRetried`,
-`DrawResolved`, `PrizeRedeemed`, `TokensSold`. `PackBought.data` has `pool`, `seq`, `purchaser`,
-`venue`, `tokensBought`, `venueDebit`, `feeLamports`, `referralLamports`, `protocolLamports`,
-`vrfDebit`, `prizes`. `DrawResolved.data` has `pool`, `seq`, `purchaser`, `amount`, `randomness`,
-`timedOut`.
-
-## Addresses (`src/pdas.ts`), all async
-
-`poolAddress(mint)`, `drawAddress(pool, seq)`, `vaultAddress(mint, tokenProgram?)`,
-`associatedTokenAddress(owner, mint, tokenProgram?)`, `referralLinkAddress(referee)`,
-`referralAddress(pool, referrer)`, `feeCollectorWsolAddress()`, `vrfIdentityAddress()`.
-Also the generated `findPoolPda`, `findDrawPda`, `findReferralLinkPda`, `findIdentityPda`.
-
-## Math (`src/math.ts`), pure
-
-| function | signature |
+| `fetchPoolInventory(client, mint)` | pool, vault inventory, reservations, free inventory |
+| `getOffer(client, mint, options?)` | current `PackOffer` |
+| `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.
+
+`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`.
+
+## Builders
+
+Each returns a kit transaction message. Nothing here signs or sends.
+
+| Function | Input highlights |
 | --- | --- |
-| `share` | `(amount: bigint, bps: bigint) => bigint` |
-| `jackpotTiers` | `(jackpotBps: number, profile: RiskProfile) => Tier[]` |
-| `seedTokens` | `(packTokens: bigint, tiers: Tier[]) => bigint` |
-| `quote` | `(base: bigint, tiers: Tier[], inventory: bigint, reserved: bigint) => Offer` |
-| `uncappedMaximum` | `(base: bigint, tiers: Tier[]) => bigint` |
-| `tierAmount` | `(base: bigint, multiplierBps: number) => bigint` |
-| `choose` | `(prizes: Prize[], ticket: number) => bigint` |
-| `maxMultiplierBps`, `averageMultiplierBps` | `(tiers: Tier[]) => number` |
-| `validateTiers`, `validatePack` | throw `GaboxMathError` on a bad table |
-
-Types: `Tier = { multiplierBps: number; tickets: number }`, `Prize = { amount: bigint; tickets: number }`,
-`Offer = { prizes: Prize[]; maximum: bigint; minimum: bigint }`,
-`RiskProfile = 'conservative' | 'balanced' | 'jackpot'`. Constants `BPS = 10_000n`, `TICKETS = 65_536`,
-`TIERS = 8`.
-
-## Constants (`src/ids.ts`)
-
-`GABOX_PROGRAM_ID`, `PACK_TOKENS`, `PROTOCOL_FEE_BPS` (`100n`), `MAX_FEE_BPS` (`100`),
-`REFERRAL_FEE_BPS` (`100n`), `RETRY_SLOTS` (`300n`), `MAX_ATTEMPTS` (`3`), `TIMEOUT_SLOTS`
-(`216_000n`), `WSOL_MINT`, `TOKEN_PROGRAM_ADDRESS`, `TOKEN_2022_PROGRAM_ADDRESS`,
-`ASSOCIATED_TOKEN_PROGRAM_ADDRESS`, `PUMP_PROGRAM_ADDRESS`, `PUMP_SWAP_PROGRAM_ADDRESS`,
-`VRF_PROGRAM_ADDRESS`, `VRF_DEFAULT_QUEUE`.
-
-## Venue layer (`pump` namespace, `@gabox-labs/sdk/pump`)
-
-| function | signature |
+| `createMachine` | `name`, `symbol`, `uri`, `tiers?`, `maxSeedQuoteIn`, `maxSeedNativeDebit`, `extraSeedTokens?` |
+| `buyPack` | `maxQuoteIn`, `minMaximum`, `maxNativeDebit`, `venue?`, `seq?` |
+| `fundPrizes` | donate coins the funder already holds into the prize vault |
+| `sellTokens` | `amount`, `minQuoteOutput`, `maxNativeDebit`, `venue?` |
+| `retryDraw` / `expireDraw` | permissionless recovery |
+| `raydium.claimCreatorFee` | `creator`; sweeps every coin that wallet launched on the curve |
+| `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.
+
+`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,
+`seedTokens(PACK_TOKENS, tiers)`: 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. `extraSeedTokens`
+(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
+`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.
+
+`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.
+
+## The venue
+
+| Function | Result |
 | --- | --- |
-| `resolveVenue` | `(client, { mint; user; venue?; feeRecipientIndex?; buybackRecipientIndex? }) => Promise<ResolvedVenue>` |
-| `curveQuote` | `(client, mint, tokens: bigint, { user?, venue? }?) => Promise<bigint>` lamports to buy `tokens` |
-| `sellQuote` | `(client, mint, tokens: bigint, { user?, venue? }?) => Promise<bigint>` lamports a sale returns |
-| `newCurveBuyCost` | `(client, tokens: bigint) => Promise<bigint>` on a fresh curve |
-| `wsolAccountFor` | `(user: Address) => Address` |
-| `tokenAccountAmount` | `(data: Uint8Array) => bigint` |
-
-`ResolvedVenue`: `{ kind: 'pump' | 'pumpswap'; program; mint; tokenProgram; complete; creator;
-buyAccounts; sellAccounts; quoteBuy(tokens); quoteSell(tokens) }`. `VenueKind = 'pump' | 'pumpswap'`.
-
-## Generated client (`generated` namespace, `@gabox-labs/sdk/generated`)
-
-Codama output for `@solana/kit`: `get*Instruction` builders, `fetch*` / `decode*` account readers
-(these take a kit `Rpc`, i.e. `gabox.rpc`), event codecs, PDAs, and errors:
-
-- `isGaboxV2Error(error, transactionMessage, code?)` — narrows a kit `SolanaError`.
-- `getGaboxV2ErrorMessage(code)` — readable outside `NODE_ENV=production`.
-- `GABOX_V2_ERROR__*` codes, from `6000`: `ARITHMETIC`, `INVALID_DISTRIBUTION`,
-  `UNFUNDED_EXPECTATION`, `UNSUPPORTED_MINT`, `INSOLVENT_INVENTORY`, `PRIZE_CAP_CHANGED`,
-  `PACK_TOO_SMALL`, `JACKPOT_BELOW_ONE_PACK`, `INVALID_VENUE`, `INCORRECT_TOKEN_DELTA`,
-  `SLIPPAGE_EXCEEDED`, `NOT_PENDING`, `NOT_READY`, `RETRY_TOO_SOON`, `RETRY_UNAVAILABLE`,
-  `NOT_EXPIRED`, `ZERO_AMOUNT`, `INVALID_FEE`, `COIN_NOT_CREATED_HERE`, `INVALID_REFERRAL`,
-  `NOTHING_OWED_TO_REFERRER`, `INVALID_FEE_COLLECTOR`.
+| `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 |
+
+`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
+a derived address, so it proves itself from its own data, and its fee tier, its two vaults and its
+oracle are read out of the pool account. The program checks the same things.
+
+`quoteBuy` on the curve throws when the amount is larger than the curve has left to sell. That is not
+a price failure: the program requires an exact one-pack delta, so such a buy cannot succeed until the
+coin graduates.
+
+## Math and low-level builders
+
+`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
+Raydium's.
+
+`raydium.getLaunchInstruction(input, ids)` builds LaunchLab's `initialize_v2` with the pinned launch
+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.
+
+`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.
+
+## 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`.
+
+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.