@gabox-labs/sdk 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to `@gabox-labs/sdk`. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project uses [Semantic Versioning](https://semver.org/) with the `0.x` rule from `CONTRIBUTING.md`.
+
+## [Unreleased]
+
+## [0.1.1] - 2026-09-11
+
+Same content as 0.1.0. That version was published and then unpublished on the same day, and npm
+does not allow a version number to be reused, so the first installable release is 0.1.1.
+
+### Added
+
+- `npm run check:program` and `RELEASE.md`: the program → SDK → npm → app release workflow.
+
+## [0.1.0] - 2026-09-11
+
+First public release.
+
+### Added
+
+- `createClient({ cluster, url?, wsUrl?, addressLookupTables? })`: the one setup step. Every
+  chain-touching function takes the client it returns.
+- Builders: `createMachine`, `buyPack`, `sellTokens`, `fundPrizes`, `fundPrizesWithBuy`,
+  `retryDraw`, `expireDraw`, `bindReferrer`, `claimReferral`.
+- Readers: `getOffer`, `fetchPoolByMint`, `fetchPoolInventory`, `fetchDraw`, `listPools`,
+  `listDraws`, `fetchEvents`, `watchDraw`, `drawAvailability`, and the referral readers.
+- The prize-table math as pure `bigint` functions: `jackpotTiers`, `quote`, `seedTokens`, `share`.
+- The `generated` namespace (instruction builders, codecs, error codes) and the `pump` namespace
+  (venue routing and quotes).
+- An agent skill at `skills/gabox-sdk/`.
+
+### Notes
+
+- Devnet only. The devnet program upgrade to the build this SDK targets is pending; see the
+  README's Status section.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabox Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,511 @@
+# `@gabox-labs/sdk`
+
+The TypeScript SDK for gabox machines on Solana. Built on [`@solana/kit`](https://github.com/anza-xyz/kit) 7.
+
+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.
+
+```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?
+
+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.
+
+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.
+
+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.
+
+The **creator** chooses the jackpot size (for example 5×) and a risk profile. The creator buys the
+tokens that back the jackpot at creation, and earns a fee on every pack.
+
+---
+
+## Quick start
+
+```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');
+```
+
+---
+
+## The client
+
+`createClient` is the one setup step. Call it once, and pass the result to every SDK function that
+reads or writes the chain.
+
+```ts
+import { createClient } from '@gabox-labs/sdk';
+
+const gabox = createClient({ cluster: 'devnet' });
+
+// Your own RPC provider:
+const gabox = createClient({
+  cluster: 'devnet',
+  url: 'https://devnet.helius-rpc.com/?api-key=…',
+  // wsUrl is optional. It follows `url` with `wss://` when left out.
+});
+```
+
+| 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
+
+`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.
+
+- `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.
+
+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
+
+```ts
+import { createMachine, seedCostEstimate } from '@gabox-labs/sdk';
+import { generateKeyPairSigner } from '@solana/kit';
+
+const mintKeypair = await generateKeyPairSigner();
+const seed = await seedCostEstimate(gabox, 50_000, 'balanced');
+
+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%)
+  riskProfile: 'balanced',  // 'conservative' | 'balanced' | 'jackpot'
+  jackpotBps: 50_000,       // the top prize: 5× one pack
+  maxSeedLamports: (seed.lamports * 105n) / 100n,
+});
+```
+
+One transaction, two signers: the creator and the new mint. The creator pays for the coin, the
+pool, and the **seed**.
+
+The seed is the inventory that backs the jackpot. The first pack must be able to pay the top prize
+in full. A 5× jackpot needs four extra packs of tokens in the vault; a 10× jackpot needs nine. A 1×
+jackpot needs no seed. `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.
+
+- `jackpotBps` is the largest prize, in basis points of one pack. `10_000` is 1×. `50_000` is 5×.
+- `riskProfile` decides how the odds are spread. Every profile returns 95% of a pack's value on
+  average. `conservative` keeps more of it in the common prize; `jackpot` moves more into the rare
+  ones. See `jackpotTiers(jackpotBps, profile)` to preview the table before creating.
+
+### Price a pack
+
+```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
+});
+```
+
+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.    |
+
+`maxTotalDebit` does not include account rent or the transaction fee. Budget a few million lamports
+on top; the example above adds 0.02 SOL.
+
+**`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.
+
+On the PumpSwap route, `buyPack` also adds the instructions that wrap SOL into WSOL for the buyer.
+You do not need to handle that.
+
+### Wait for the draw
+
+```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),
+});
+// 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
+
+Keeping the prize needs nothing. The tokens are already in the buyer's associated token account.
+
+Selling goes through the SDK, so the sale routes to the right venue:
+
+```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, {
+  mint,
+  seller: purchaser,
+  amount: resolved.amount,
+  minQuoteOutput: (grossOutput * 95n) / 100n, // 5% slippage. Must be > 0.
+});
+```
+
+`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.
+
+### Fund a machine's prizes
+
+Anyone can add tokens to a machine's vault. This raises the cap, which uncaps prizes.
+
+```ts
+import { fundPrizes, fundPrizesWithBuy, seedShortfall } from '@gabox-labs/sdk';
+
+// Tokens the donor already holds:
+await fundPrizes(gabox, { mint, funder, amount });
+
+// 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';
+
+// 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.
+
+```ts
+import { drawAvailability, retryDraw, expireDraw } from '@gabox-labs/sdk';
+
+const state = await drawAvailability(gabox, draw);
+// { canRetry, canExpire, slotsUntilRetry, slotsUntilExpiry, attempts, status }
+
+if (state?.canRetry) await retryDraw(gabox, { payer, pool, draw, maxVrfDebit: 5_000_000n });
+if (state?.canExpire) await expireDraw(gabox, { payer, pool, draw });
+```
+
+- `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 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. Tell buyers
+  this before they pay.
+
+Use `drawAvailability` to show a countdown instead of sending a transaction that fails.
+
+---
+
+## Reading state
+
+| 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                        |
+
+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.
+
+## 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                                           |
+| `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 is being upgraded to the build this SDK targets. Until that upgrade lands,
+  transactions built by this SDK do not match the deployed program, and `fetchPoolByMint` reports
+  machines from the previous build as an "older devnet account layout". Watch the
+  [changelog](CHANGELOG.md) for the release that marks the upgrade done.
+- 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.
+
+## License
+
+[MIT](LICENSE)