@gabox-labs/sdk 0.2.0 → 0.7.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@gabox-labs/sdk",
-  "version": "0.2.0",
+  "version": "0.7.0",
   "type": "module",
-  "description": "The Solana Kit SDK for gabox-v2: generated instruction builders, PDAs, Pump/PumpSwap venue accounts, and the pack flow.",
+  "description": "The Solana Kit SDK for gabox: generated instruction builders, PDAs, Raydium LaunchLab and CPMM venue accounts, and the pack flow.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,8 +16,9 @@
     "solana",
     "solana-kit",
     "gabox",
-    "pump.fun",
-    "pumpswap",
+    "raydium",
+    "launchlab",
+    "cpmm",
     "anchor"
   ],
   "engines": {
@@ -40,10 +41,10 @@
       "import": "./dist/generated/index.js",
       "default": "./dist/generated/index.js"
     },
-    "./pump": {
-      "types": "./dist/pump/index.d.ts",
-      "import": "./dist/pump/index.js",
-      "default": "./dist/pump/index.js"
+    "./raydium": {
+      "types": "./dist/raydium/index.d.ts",
+      "import": "./dist/raydium/index.js",
+      "default": "./dist/raydium/index.js"
     },
     "./package.json": "./package.json"
   },
@@ -68,15 +69,9 @@
     "prepublishOnly": "npm run typecheck && npm test && npm run check:surface && npm run build && npm run check:package"
   },
   "dependencies": {
-    "@pump-fun/pump-sdk": "1.36.0",
-    "@pump-fun/pump-swap-sdk": "1.19.0",
     "@solana-program/system": "^0.13.0",
     "@solana-program/token": "^0.15.0",
-    "@solana/program-client-core": "^7.0.0",
-    "@solana/spl-token": "^0.4.15",
-    "@solana/web3.js": "^1.99.0",
-    "bn.js": "^5.2.5",
-    "buffer": "^6.0.3"
+    "@solana/program-client-core": "^7.0.0"
   },
   "peerDependencies": {
     "@solana/kit": "^7.0.0"
@@ -86,7 +81,7 @@
     "@codama/nodes-from-anchor": "^1.5.3",
     "@codama/renderers-js": "^2.3.1",
     "@solana/kit": "^7.0.0",
-    "@types/bn.js": "^5.2.0",
+    "@solana/web3.js": "^1.99.0",
     "@types/node": "^24.3.0",
     "codama": "^1.10.0",
     "publint": "0.3.24",

package/skills/gabox-sdk/SKILL.md

@@ -1,164 +1,75 @@
 ---
 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
-```
-
-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.
+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.
 
-## Conventions that trip people up
+A machine is priced in one quote asset, fixed when the pool is created. It defaults to wrapped SOL,
+and any quote Raydium enabled on LaunchLab works; `raydium.fetchQuoteConfig(client, mint)` says
+whether a mint is one of them, and `raydium.isQuoteSupported` is the boolean version. The quote may
+be classic SPL Token or Token-2022; the coin is always classic SPL Token.
 
-- **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
+Buyers pay in SOL either way. On a WSOL pool 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. On any other pool a route provider swaps SOL into the quote token **in
+the same transaction** as the Gabox instruction, and back after a sale. `createClient` gives mainnet
+`jupiterRoute()`; devnet has no router, so pass `route: raydiumCpmmRoute(pool)` with a CPMM pool for
+the SOL pair. `payWith: 'quote'` and `receive: 'quote'` skip the swap.
 
 ```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.
-
-## Flow 3: 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, mintKeypair,                       // two signers
-  name, symbol, uri,                          // Pump metadata
-  feeBps: 100,                                // creator fee, 0..100 (max 1%)
-  tiers: DEFAULT_TIERS,                        // optional; default top prize = 20 packs
-  maxSeedLamports: (seed.lamports * 105n) / 100n,
-});
-```
-
-The creator buys the **seed** that backs the top prize. `DEFAULT_TIERS` needs nineteen extra packs
-of tokens. Pass a custom eight-row `Tier[]` only after validating its odds and seed with
-`seedCostEstimate(gabox, tiers)`; the SDK and program both validate it.
-
-## 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),
-only while the draw is `Pending`; it pays the **smallest** prize, not a refund. A `Ready` draw must
-go through normal delivery. 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));
-```
-
-Common: `SlippageExceeded`, `PrizeCapChanged` (refresh the offer), `RetryTooSoon`,
-`RetryUnavailable`, `NotExpired`, `NotPending`, `InvalidReferral`, `ZeroAmount`.
-
-## Do not
-
-- 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.
+`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.
+
+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
+`quote: { mint }` and `raise` for a machine priced in another token: `raise` is
+`total_quote_fund_raising` in that token's base units, and a WSOL pool uses the raise the program
+pins instead. 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.
+
+`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.
+
+Creators collect their share with `raydium.claimCreatorFee(client, { creator, quoteMint })`, which
+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`
+before a wallet's first purchase); it resolves the account itself.
+
+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,148 +1,158 @@
-# `@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; tiers?: readonly Tier[]; maxSeedLamports: bigint; feeRecipientIndex?; buybackRecipientIndex? }` | creator, mintKeypair |
-| `seedCostEstimate` | `(client, tiers?: readonly Tier[]) => Promise<{ tiers: readonly 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); only for an expired `Pending` draw |
-| `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 the pool's own quote asset, which defaults to wrapped SOL.
+
+## 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 | notes |
-| --- | --- | --- |
-| `share` | `(amount: bigint, bps: bigint) => bigint` |
-| `DEFAULT_TIERS` | `readonly Tier[]` | 75% / 20% / 4% / 1% odds at 0.52× / 1.2× / 3× / 20× |
-| `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 }`. 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 |
+| `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`, `packTokens`, `seedQuoteAmount`, `tiers`,
+`nextSeq`, `reserved`, `quoteConfig` (LaunchLab's global config for the quote) and
+`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`.
+
+## Builders
+
+Each returns a kit transaction message. Nothing here signs or sends.
+
+| Function | Input highlights |
+| --- | --- |
+| `createMachine` | `name`, `symbol`, `uri`, `tiers?`, `quote?`, `raise?`, `payWith?`, `maxSeedQuoteIn`, `maxSeedNativeDebit`, `extraSeedTokens?` |
+| `buyPack` | `maxQuoteIn`, `minMaximum`, `maxNativeDebit`, `payWith?`, `venue?`, `seq?` |
+| `fundPrizes` | donate coins the funder already holds into the prize vault |
+| `sellTokens` | `amount`, `minQuoteOutput`, `maxNativeDebit`, `receive?`, `venue?` |
+| `retryDraw` / `expireDraw` | permissionless recovery |
+| `raydium.claimCreatorFee` | `creator`, `quoteMint?`; sweeps every coin that wallet launched against that quote |
+| `raydium.collectCreatorFee` | `mint`, `creator`; one graduated coin's CPMM creator fee |
+
+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 `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.
+
+`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 the quote token, and each is also the
+amount put in the wallet's quote account 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.
+
+`createMachine` takes `quote: { mint }` and `raise`. The quote defaults to wrapped SOL, whose raise
+the program pins per cluster; any other quote needs a `raise` in its own base units, at or above
+`min_quote_fund_raising` in its config. `seedCostEstimate(client, tiers?, { extraSeedTokens?,
+quote?, raise? })` reports the seed cost in the quote token, its decimals and symbol, the raise, and
+`solAmount` through the route provider.
+
+## The venue
+
+| Function | Result |
+| --- | --- |
+| `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, { quoteConfig, raise })` | what a buy costs on a curve that does not exist yet |
+| `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.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 |
+| `raydium.quoteAccountFor(user, quoteMint, quoteTokenProgram)` | the account both venues settle in |
+| `raydium.wsolAccountFor(user)` | the same, for a WSOL pool |
+
+`resolveVenue` takes an optional `quote: { mint, config, tokenProgram }`. Left out, it reads the
+Gabox pool for it, so a caller that already holds a `Pool` saves a round trip by passing it.
+
+`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.
+
+`initialize_pool`'s `venue` account has no generated default, because LaunchLab has a different
+address on each cluster and a default would be wrong on one of them. Every builder here passes it
+from `raydiumIds(client.cluster)`; a caller using the generated builder directly has to do the same.
+
+`raydiumIds(cluster)` gives one cluster's Raydium deployment. Mainnet and devnet run different
+programs and PDAs, and a WSOL launch raises 3 SOL on devnet where mainnet raises 85. `localnet` uses
+the mainnet set, which is what the program's default build pins.
+
+## Routes
+
+A route provider swaps SOL into a pool's quote token, and back. `createClient` gives mainnet
+`jupiterRoute()` and every other cluster `null`; pass `route` to override, or `null` to switch the
+swap leg off.
+
+| 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`.
+| `jupiterRoute({ url?, slippageBps? })` | a `RouteProvider` over Jupiter's swap API, for mainnet |
+| `raydiumCpmmRoute(poolAddress)` | a `RouteProvider` over one Raydium CPMM pool, for devnet |
+| `routeQuoteIn(client, provider, { quoteMint, amount, user })` | a swap that buys at least `amount`, exact-out first |
+| `routeQuoteOut(client, provider, { quoteMint, amount, user })` | a swap that turns `amount` into SOL |
+| `solPriceOf(client, quoteMint, amount)` | the exact-out SOL cost of `amount`, or `null` |
+| `assertRouteIsSafe(route, { forbidden, settlesIn })` | refuse a route that touches Gabox state or settles elsewhere |
+
+A `Route` is `{ instructions, lookupTables, inAmount, outAmount, mode, computeUnits }`. `mode` is
+`'exactOut'` or `'exactIn'`: the amounts are bounds, so an exact-out route states the most it spends
+and an exact-in route the least it pays out.
+
+`computeUnits` is what the swap costs on top of the Gabox instruction, because the two share one
+budget. A builder adds it to its own limit and caps the total at `MAX_COMPUTE_UNIT_LIMIT`; an
+explicit `computeUnitLimit` still wins. Jupiter returns the number with the route, falling back to
+`JUPITER_DEFAULT_COMPUTE_UNITS` when its response carries none; `raydiumCpmmRoute` uses
+`CPMM_ROUTE_COMPUTE_UNITS`, measured on devnet, which holds because it is always one pool. Jupiter answers `NO_ROUTES_FOUND` for exact-out whenever the best route
+has more than one hop, which is why `routeQuoteIn` falls back to exact-in and leaves the change in
+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.