@gabox-labs/sdk 0.1.1

package/skills/gabox-sdk/references/api.md

@@ -0,0 +1,149 @@
+# `@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 |
+| --- | --- |
+| `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 |
+| --- | --- |
+| `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 |
+| --- | --- |
+| `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`.