@gabox-labs/sdk 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gabox-labs/sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "The Solana Kit SDK for gabox-v2: generated instruction builders, PDAs, Pump/PumpSwap venue accounts, and the pack flow.",
   "license": "MIT",

package/skills/gabox-sdk/SKILL.md

@@ -97,23 +97,23 @@ On the Pump route the seller gets SOL. On PumpSwap (a graduated coin) the seller
 ## Flow 3: create a machine
 
 ```ts
-import { createMachine, seedCostEstimate } from '@gabox-labs/sdk';
+import { createMachine, DEFAULT_TIERS, seedCostEstimate } from '@gabox-labs/sdk';
 import { generateKeyPairSigner } from '@solana/kit';
 
 const mintKeypair = await generateKeyPairSigner();
-const seed = await seedCostEstimate(gabox, 50_000, 'balanced');
+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%)
-  riskProfile: 'balanced',                    // 'conservative' | 'balanced' | 'jackpot'
-  jackpotBps: 50_000,                         // top prize = 5 packs
+  tiers: DEFAULT_TIERS,                        // optional; default top prize = 20 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)`.
+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)
 
@@ -124,8 +124,9 @@ if (s?.canRetry)  await retryDraw(gabox, { payer, pool, draw, maxVrfDebit: 5_000
 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.
+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
 
@@ -152,7 +153,7 @@ if (generated.isGaboxV2Error(error, message)) console.log(generated.getGaboxV2Er
 ```
 
 Common: `SlippageExceeded`, `PrizeCapChanged` (refresh the offer), `RetryTooSoon`,
-`RetryUnavailable`, `NotExpired`, `InvalidReferral`, `ZeroAmount`.
+`RetryUnavailable`, `NotExpired`, `NotPending`, `InvalidReferral`, `ZeroAmount`.
 
 ## Do not
 

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

@@ -36,14 +36,14 @@ blockhash set, ready for `signTransactionMessageWithSigners`. All amounts are `b
 
 | 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 |
+| `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) |
+| `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 |
@@ -95,10 +95,10 @@ Also the generated `findPoolPda`, `findDrawPda`, `findReferralLinkPda`, `findIde
 
 ## Math (`src/math.ts`), pure
 
-| function | signature |
-| --- | --- |
+| function | signature | notes |
+| --- | --- | --- |
 | `share` | `(amount: bigint, bps: bigint) => bigint` |
-| `jackpotTiers` | `(jackpotBps: number, profile: RiskProfile) => Tier[]` |
+| `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` |
@@ -108,8 +108,7 @@ Also the generated `findPoolPda`, `findDrawPda`, `findReferralLinkPda`, `findIde
 | `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`,
+`Offer = { prizes: Prize[]; maximum: bigint; minimum: bigint }`. Constants `BPS = 10_000n`, `TICKETS = 65_536`,
 `TIERS = 8`.
 
 ## Constants (`src/ids.ts`)