@gabox-labs/sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,823 @@
+import { DRAW_DISCRIMINATOR, Draw, DrawResolvedEvent, DrawStatus, POOL_DISCRIMINATOR, PackBoughtEvent, Pool, PoolCreatedEvent, PrizeRedeemedEvent, PrizesFundedEvent, RandomnessRetriedEvent, Referral, ReferralLink, TokensSoldEvent, decodeDraw, decodePool, findDrawPda, findIdentityPda, findPoolPda, findReferralLinkPda, t as index_d_exports } from "./generated/index.js";
+import { At as ClientConfig, Bt as websocketUrlFor, Ct as PUMP_SWAP_PROGRAM_ADDRESS, Et as SYSTEM_PROGRAM_ADDRESS, Ft as GaboxRpc, It as GaboxRpcSubscriptions, Lt as assertClusterUrl, Mt as DEVNET_HTTP, Nt as DEVNET_WS, Pt as GaboxClient, Rt as clusterNamedBy, bt as PUMP_FEE_PROGRAM_ADDRESS, ct as VenueKind, gt as MAYHEM_PROGRAM_ADDRESS, ht as ASSOCIATED_TOKEN_PROGRAM_ADDRESS, jt as Cluster, kt as CLUSTER_ENDPOINTS, t as index_d_exports$1, xt as PUMP_PROGRAM_ADDRESS, zt as createClient } from "./index-BxvSkzCO.js";
+import { AccountMeta, Address, AddressesByLookupTableAddress, Instruction, InstructionWithData, ProgramDerivedAddress, ReadonlyUint8Array, TransactionMessage, TransactionMessageWithBlockhashLifetime, TransactionMessageWithFeePayerSigner, TransactionSigner } from "@solana/kit";
+//#region src/math.d.ts
+/**
+ * A bigint port of `programs/gabox-v2/src/math.rs`.
+ *
+ * The point is that a client can show a buyer the exact prize table the program will freeze into
+ * their `Draw`, before they pay. Every rounding step here matches the Rust, including the direction
+ * of each division. `test/math.test.ts` runs the same vectors as `programs/gabox-v2/tests/
+ * economics.rs`.
+ *
+ * All amounts are `bigint`, in the mint's smallest unit. `multiplierBps` and `tickets` are numbers
+ * because both are `u32` in the program and both stay small.
+ */
+/** Basis points. A multiplier of 10_000 pays back exactly one pack. */
+export declare const BPS = 10000n;
+/** `math::share`. `bps` basis points of `amount`, rounded down. */
+export declare function share(amount: bigint, bps: bigint): bigint;
+/** Ticket counts must sum to this. A uniform 16-bit word then maps with no modulo bias. */
+export declare const TICKETS = 65536;
+/** The prize table has exactly this many slots. Unused slots are all-zero. */
+export declare const TIERS = 8;
+/** One row of the immutable prize table. Counts, not cumulative thresholds. */
+export type Tier = {
+  /** `floor(base * multiplierBps / 10_000)` tokens. `0` only on an unused row. */
+  multiplierBps: number;
+  /** Out of 65,536. `0` marks the row unused, and then `multiplierBps` must be `0` too. */
+  tickets: number;
+};
+/** One row of a frozen offer: a real token amount, already capped by inventory. */
+export type Prize = {
+  amount: bigint;
+  tickets: number;
+};
+/** What `buy_pack` writes into the `Draw`. `minimum` is also the timeout payout. */
+export type Offer = {
+  prizes: Prize[];
+  maximum: bigint;
+  minimum: bigint;
+};
+/** Thrown by every function here. `code` matches a `GaboxError` variant name. */
+export declare class GaboxMathError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+/** Creator-facing presets. The creator picks the jackpot size; the profile chooses its odds. */
+export type RiskProfile = "conservative" | "balanced" | "jackpot";
+/** `math::tokens`. Floor division, and an overflow past u64 is an error, not a wrap. */
+export declare function tierAmount(base: bigint, multiplierBps: number): bigint;
+/**
+ * `math::validate`. Checks the table alone, with no base.
+ *
+ * Three rules, and each one closes a way to sell a bad ticket:
+ *   - ticket counts sum to exactly 65,536, so the 16-bit draw is uniform;
+ *   - an unused row is all-zero, so a hidden multiplier cannot ride along;
+ *   - the expected multiplier over all tickets is at most 1x, so the table cannot promise more
+ *     tokens than a pack buys. This bounds tokens, not cash value.
+ */
+export declare function validateTiers(tiers: readonly Tier[]): void;
+/**
+ * `math::validate_pack`. Every ticketed tier must pay at least one token for a pack of this size.
+ *
+ * The program checks this once at creation. At `PACK_TOKENS` no sane table fails it; it exists so
+ * a table cannot sell a ticket that can only win zero.
+ */
+export declare function validatePack(packTokens: bigint, tiers: readonly Tier[]): void;
+/**
+ * `math::seed_tokens`. The seed a table needs, in tokens.
+ *
+ * The first pack must be able to pay the largest tier in full. The pack itself brings `packTokens`
+ * into the vault, so the vault has to hold the rest beforehand:
+ *
+ *     seedTokens = uncappedMaximum(packTokens, tiers) - packTokens
+ *
+ * A 5x jackpot on a 1M-token pack needs a 4M-token seed. A table whose top tier pays exactly one
+ * pack needs no seed. A top tier below one pack is refused: every ticket would lose.
+ *
+ * `initialize_pool` computes this number itself and buys exactly that many tokens on the curve.
+ * The creator only signs a maximum SOL cost.
+ */
+export declare function seedTokens(packTokens: bigint, tiers: readonly Tier[]): bigint;
+/**
+ * Derive a fully valid four-outcome rarity ladder from a jackpot multiplier and a risk preset.
+ *
+ * Mythic is exactly `jackpotBps`. Rare and Epic interpolate between sub-1x launch values
+ * and Mythic as the jackpot grows, so the four payouts remain strictly ordered even at 1x.
+ * The profile assigns fixed slices of one pack's EV budget to the three higher rarities. Whatever
+ * remains of the 95% target becomes Common. Integer rounding is always downward, so the result
+ * cannot cross the program's 100% expected-value ceiling.
+ *
+ * The seed this table needs is `seedTokens(packTokens, tiers)`: `(jackpotBps - 10_000)` bps of
+ * one pack.
+ */
+export declare function jackpotTiers(jackpotBps: number, profile: RiskProfile): Tier[];
+/**
+ * `math::uncapped_maximum`. The largest tier's award for this base, before any inventory cap.
+ *
+ * At `packTokens` this is the jackpot in tokens. `seedTokens` is this minus one pack.
+ */
+export declare function uncappedMaximum(base: bigint, tiers: readonly Tier[]): bigint;
+/**
+ * `math::quote`. The offer a pack of `base` tokens would freeze right now. `base` is always
+ * `pool.packTokens`; the parameter stays general so the vectors can use small numbers.
+ *
+ * `inventory` is the vault's token balance and `reserved` is `pool.reserved`. The difference is
+ * free inventory. This pack's own `base` is added to it, because the purchase and the offer are
+ * one transaction — the tokens are in the vault before the draw is written.
+ *
+ * Every amount is capped at what is actually available. A tier that rounds to zero tokens is an
+ * error: the pool must not sell a ticket that can only win nothing.
+ */
+export declare function quote(base: bigint, tiers: readonly Tier[], inventory: bigint, reserved: bigint): Offer;
+/**
+ * `math::choose`. Which prize a 16-bit ticket wins.
+ *
+ * The rows are consecutive ranges in table order, so this is a running total and a comparison.
+ * A ticket past the last row returns `0`, which cannot happen for a validated table.
+ */
+export declare function choose(prizes: readonly Prize[], ticket: number): bigint;
+/** `math::resolve_reservation`. Release the unwon part of a maximum, keep the award reserved. */
+export declare function resolveReservation(reserved: bigint, maximum: bigint, award: bigint): bigint;
+/** The largest `multiplierBps` on any ticketed row. `0` for a table with no rows. */
+export declare function maxMultiplierBps(tiers: readonly Tier[]): number;
+/**
+ * The expected multiplier over all 65,536 tickets, in basis points. Rounded down.
+ *
+ * `validateTiers` caps this at 10,000. A table at 9,800 keeps 2% of every pack's tokens in the
+ * vault on average, which is what lets a pool survive a run of top-tier wins.
+ */
+export declare function averageMultiplierBps(tiers: readonly Tier[]): number;
+//#endregion
+//#region src/accounts.d.ts
+/** `Draw.pool` sits straight after the discriminator. */
+export declare const DRAW_POOL_OFFSET = 8;
+/** `Draw.purchaser` sits after the discriminator and `pool`. */
+export declare const DRAW_PURCHASER_OFFSET: number;
+/** `Pool.creator` sits straight after the discriminator. */
+export declare const POOL_CREATOR_OFFSET = 8;
+/** `Pool.mint` sits after the discriminator and `creator`. */
+export declare const POOL_MINT_OFFSET: number;
+/** `ReferralLink.referrer` sits after the discriminator and `referee`. */
+export declare const REFERRAL_LINK_REFERRER_OFFSET: number;
+/** The pool for a coin, or `null` when the coin has no machine. */
+export declare function fetchPoolByMint(client: GaboxClient, mint: Address): Promise<Pool | null>;
+/**
+ * A pool by its own address, or `null`.
+ *
+ * `fetchPoolByMint` is the usual way in, because a coin's mint is the natural key. This one is for
+ * the other direction: a `Draw` names its pool and not its mint, so a client holding a draw reads
+ * the pool to learn which coin it belongs to.
+ */
+export declare function fetchPoolAt(client: GaboxClient, address: Address): Promise<Pool | null>;
+/** A draw by address, or `null`. Delivered and legacy-claimed draws are closed. */
+export declare function fetchDraw(client: GaboxClient, address: Address): Promise<Draw | null>;
+/** Accrued referral reward for one referrer and pool, or zero when no referred pack has settled. */
+export declare function fetchReferralReward(client: GaboxClient, pool: Address, referrer: Address): Promise<Referral | null>;
+export type PoolRecord = {
+  address: Address;
+  data: Pool;
+};
+export type DrawRecord = {
+  address: Address;
+  data: Draw;
+};
+/**
+ * Every current-layout machine, by discriminator and account size. Older devnet
+ * pools predate seed fields and must not be decoded with the current schema.
+ *
+ * There is no on-chain registry — the design says so on purpose — so discovery is this scan plus
+ * the `PoolCreated` event. Public RPCs limit `getProgramAccounts`, so an app that lists machines
+ * for users should cache the result rather than call this per page view.
+ */
+export declare function listPools(client: GaboxClient): Promise<PoolRecord[]>;
+/** Every draw of one pool, pending or ready. Closed draws are gone and never appear. */
+export declare function listDrawsByPool(client: GaboxClient, pool: Address): Promise<DrawRecord[]>;
+/**
+ * Every open draw of one wallet, across all pools. This is the "what am I owed" query.
+ *
+ * An address is already base58, so it goes into the filter unchanged.
+ */
+export declare function listDrawsByPurchaser(client: GaboxClient, purchaser: Address): Promise<DrawRecord[]>;
+export type DrawQuery = {
+  /** A pool PDA. */
+  pool?: Address;
+  /** A buyer's wallet. */
+  purchaser?: Address;
+};
+/**
+ * Open draws, narrowed by pool, by purchaser, or by both.
+ *
+ * Both filters in one scan, because a UI asks for exactly that: "my pulls on this machine". Two
+ * separate scans and an intersection in the client would move twice the bytes and could disagree
+ * with itself, since the two reads happen at different slots. With neither filter this lists every
+ * open draw of every machine.
+ */
+export declare function listDraws(client: GaboxClient, query?: DrawQuery): Promise<DrawRecord[]>;
+export type ReferralLinkRecord = {
+  address: Address;
+  data: ReferralLink;
+};
+/**
+ * Every wallet bound to one referrer. This is the "who did I refer" query.
+ *
+ * A scan, because a link is seeded on the referee and nothing on chain indexes it by referrer.
+ * The list is small in practice, and a dashboard reads it once per load, not per poll.
+ */
+export declare function listReferralLinksByReferrer(client: GaboxClient, referrer: Address): Promise<ReferralLinkRecord[]>;
+/** The vault's token balance. `0` when the vault does not exist yet. */
+export declare function fetchVaultBalance(client: GaboxClient, mint: Address, tokenProgram?: Address): Promise<bigint>;
+export type PoolInventory = {
+  pool: Pool;
+  poolAddress: Address;
+  vault: Address;
+  /** The vault's whole token balance. */
+  inventory: bigint;
+  /** `pool.reserved`: maximum awards reserved by pending draws. */
+  reserved: bigint;
+  /** `inventory - reserved`. What a new pack's prizes can be paid from, besides its own tokens. */
+  free: bigint;
+};
+/**
+ * A pool with its live inventory. This is the pair every price display needs: the tiers are
+ * immutable, but what they actually pay depends on what is free in the vault right now.
+ *
+ * # Why one request reads both accounts
+ *
+ * The oracle callback lowers the vault and `pool.reserved` in one transaction, a few seconds after
+ * a buy. Two separate reads can land on either side of it: the old `reserved` with the new, smaller
+ * vault. That pair looks insolvent, and `quote` rightly refuses it. One `getMultipleAccounts` call
+ * returns both accounts from the same slot, so the pair is always one the chain actually held.
+ */
+export declare function fetchPoolInventory(client: GaboxClient, mint: Address): Promise<PoolInventory | null>;
+/** The generated `Tier` uses the same field names as `math.ts`, so this is only a widening. */
+export declare const tiersOf: (pool: Pool) => Tier[];
+/**
+ * The offer a pack of `base` tokens would freeze against this inventory. Pure — the same
+ * computation `buy_pack` performs, and the reason a client can show real amounts before paying.
+ */
+export declare const offerFor: (inventory: PoolInventory, base: bigint) => Offer;
+//#endregion
+//#region src/compute.d.ts
+export declare const COMPUTE_BUDGET_PROGRAM_ADDRESS: Address;
+/** The runtime's per-transaction ceiling. A larger request is rejected outright. */
+export declare const MAX_COMPUTE_UNIT_LIMIT = 1400000;
+/** What an instruction gets when no `SetComputeUnitLimit` is present. */
+export declare const DEFAULT_COMPUTE_UNIT_LIMIT = 200000;
+/**
+ * UNVERIFIED: none of the three figures below has been measured on chain. They are headroom, chosen
+ * above what these instruction mixes plausibly cost. Measure them on devnet before they matter: the
+ * prioritisation fee is `price x requested limit`, so a request three times too large costs three
+ * times too much on every pack.
+ */
+/** Pump `create_v2` plus `initialize_pool` plus a seed buy, in one transaction. */
+export declare const CREATE_MACHINE_COMPUTE_UNITS = 600000;
+/** A venue buy, an escrow transfer, a draw init and a VRF request. */
+export declare const BUY_PACK_COMPUTE_UNITS = 500000;
+/** A vault transfer, or a vault transfer plus a venue sale. */
+export declare const REDEEM_COMPUTE_UNITS = 300000;
+/** `bind_referrer` riding ahead of a pack: one small account init. */
+export declare const BIND_REFERRER_COMPUTE_UNITS = 50000;
+/** An instruction for the compute budget program: no accounts, all of it in the data. */
+export type ComputeBudgetInstruction = Instruction<string, readonly []> & InstructionWithData<ReadonlyUint8Array>;
+export declare function getSetComputeUnitLimitInstruction(units: number): ComputeBudgetInstruction;
+/**
+ * `SetComputeUnitPrice(microLamports)` — the priority fee, per compute unit.
+ *
+ * No default, deliberately. The fee that lands a transaction is a property of the network at the
+ * moment you send it. A hardcoded price is either money burnt on an idle chain or a transaction
+ * that quietly stops landing under load. Sample `getRecentPrioritizationFees`, or take it from
+ * config.
+ */
+export declare function getSetComputeUnitPriceInstruction(microLamports: number | bigint): ComputeBudgetInstruction;
+/** The compute budget prefix a builder prepends: a limit, and a price only when one is asked for. */
+export declare function computeBudgetInstructions(units: number, microLamports?: number | bigint): ComputeBudgetInstruction[];
+//#endregion
+//#region src/ids.d.ts
+/** `declare_id!` in `programs/gabox-v2/src/lib.rs`. */
+export declare const GABOX_PROGRAM_ID: Address<"GaBoxR9nYcK1zeu8EvSJVHV3SrYpCFmvbh2MLgobMcUA">;
+/** Classic SPL Token. The quote side of every Pump trade uses it, because the quote is WSOL. */
+export declare const TOKEN_PROGRAM_ADDRESS: Address;
+/**
+ * Token-2022. Pump `create_v2` mints here, so every coin a machine is built on is a Token-2022
+ * mint and the pool vault ATA lives under this program.
+ */
+export declare const TOKEN_2022_PROGRAM_ADDRESS: Address;
+/** Wrapped SOL. The quote mint on both venues. */
+export declare const WSOL_MINT: Address;
+/** MagicBlock's ephemeral VRF program. `vrf.rs` pins it and refuses any other. */
+export declare const VRF_PROGRAM_ADDRESS: Address;
+/**
+ * MagicBlock's default oracle queue. The program pins this one address, so a pool creator cannot
+ * point a draw at an oracle they control.
+ */
+export declare const VRF_DEFAULT_QUEUE: Address;
+/** The seed of both identity PDAs. See `pdas.ts` — there are two, under different programs. */
+export declare const IDENTITY_SEED: Uint8Array<ArrayBuffer>;
+export declare const SLOT_HASHES_SYSVAR: Address;
+export declare const INSTRUCTIONS_SYSVAR: Address;
+/** `state.rs`. A retry may not run sooner than this after the last attempt. */
+export declare const RETRY_SLOTS = 300n;
+/** `state.rs`. After this many slots from the purchase, anyone may expire the draw. */
+export declare const TIMEOUT_SLOTS = 216000n;
+/** `state.rs`. Three requests in total, counting the one `buy_pack` makes. */
+export declare const MAX_ATTEMPTS = 3;
+/**
+ * `state.rs`. Tokens in one pack, in base units: 1,000,000 tokens at Pump's fixed 6 decimals, or
+ * 0.1% of the 1,000,000,000 supply. Every pool sells packs of this size. The venue decides what a
+ * pack costs, so the pack price follows the coin. Read `pool.packTokens` rather than this when a
+ * pool is at hand: a later program version may change the constant.
+ */
+export declare const PACK_TOKENS: bigint;
+/** `state.rs`. The creator's per-pack fee, in bps of what the venue charged, may not exceed this. */
+export declare const MAX_FEE_BPS = 100;
+/** Referral reward: 1% of the creator fee, deducted from that fee. */
+export declare const REFERRAL_FEE_BPS = 100n;
+/** `state.rs`. The protocol's share of every pack's venue cost and of every sale's proceeds, in bps. */
+export declare const PROTOCOL_FEE_BPS = 100n;
+/**
+ * `PROTOCOL_FEE_COLLECTOR` in `state.rs`. Every pack pays 1% of its venue cost here, on top of
+ * that cost. Every sale through the program pays 1% of its proceeds here: SOL on Pump, WSOL (into the
+ * collector's WSOL ATA) on PumpSwap. The same key holds the program's upgrade authority.
+ *
+ * The generated instructions pin it as an `address` constraint, and `test/instruction-data.test.ts`
+ * checks this copy against the IDL.
+ */
+export declare const PROTOCOL_FEE_COLLECTOR: Address;
+//#endregion
+//#region src/events.d.ts
+export type GaboxEvent = {
+  name: 'PoolCreated';
+  data: PoolCreatedEvent;
+} | {
+  name: 'PrizesFunded';
+  data: PrizesFundedEvent;
+} | {
+  name: 'PackBought';
+  data: PackBoughtEvent;
+} | {
+  name: 'RandomnessRetried';
+  data: RandomnessRetriedEvent;
+} | {
+  name: 'DrawResolved';
+  data: DrawResolvedEvent;
+} | {
+  name: 'PrizeRedeemed';
+  data: PrizeRedeemedEvent;
+} | {
+  name: 'TokensSold';
+  data: TokensSoldEvent;
+};
+/** Decode one `Program data:` payload, or `null` when it is not one of ours. */
+export declare function decodeEvent(data: Uint8Array): GaboxEvent | null;
+/**
+ * Every gabox event in a transaction's logs, in order.
+ *
+ * A log line that is not `Program data:`, or whose payload matches no discriminator, is skipped
+ * rather than reported. Another program in the same transaction emits its own events, and they are
+ * not an error here.
+ */
+export declare function decodeEvents(logs: readonly string[]): GaboxEvent[];
+/** Fetch a transaction and decode the gabox events it emitted. */
+export declare function fetchEvents(client: GaboxClient, signature: string): Promise<GaboxEvent[]>;
+export type WatchDrawOptions = {
+  /** Stop watching. The returned promise then rejects with the abort reason. */
+  signal?: AbortSignal;
+  /** Called on every account change, including the ones that are still `Pending`. */
+  onChange?: (draw: Draw) => void;
+};
+/**
+ * Watch one draw and resolve when its callback delivers the prize.
+ *
+ * The first notification is the account as it is now, so a draw that resolved before the call
+ * resolves the promise immediately. Automatic delivery closes the account, so the watcher rebuilds
+ * the resolved snapshot from the purchase and resolution events when it sees that closure.
+ *
+ * There is no timeout here on purpose. The program's own deadline is 216,000 slots, which is about
+ * a day, and a UI should decide its own patience rather than inherit one.
+ */
+export declare function watchDraw(client: GaboxClient, address: Address, options?: WatchDrawOptions): Promise<Draw>;
+//#endregion
+//#region src/lookupTables.d.ts
+export declare const DEVNET_LOOKUP_TABLE_ADDRESS: Address<"Cx4ri1BU2bnDXPjnJykF3nbY2u4MD5pPvzFCJtNizWFa">;
+export declare const DEVNET_LOOKUP_TABLE_ADDRESSES: readonly Address[];
+export declare const DEVNET_ADDRESS_LOOKUP_TABLES: AddressesByLookupTableAddress;
+/**
+ * The tables a client compresses with when its config names none.
+ *
+ * Only devnet has a shared table today. Mainnet gets one when the program is deployed there; until
+ * then a mainnet or localnet client compresses with nothing, and a message over 1,232 bytes fails
+ * in `buildMessage` with a request for tables. Pass `addressLookupTables` to `createClient` to
+ * supply your own.
+ */
+export declare function defaultAddressLookupTables(cluster: Cluster): AddressesByLookupTableAddress;
+//#endregion
+//#region src/offer.d.ts
+export type PackOffer = {
+  mint: Address;
+  pool: Address;
+  /** The fixed token count of one pack. Every prize is a multiple of this. */
+  packTokens: bigint;
+  /** What the venue charges for `packTokens` right now, its own fees included. The pack price. */
+  quoteLamports: bigint;
+  /** The creator's fee, in bps of `quoteLamports`. */
+  feeBps: number;
+  /** The creator's fee at this price, paid on top of `quoteLamports`. */
+  feeLamports: bigint;
+  /** The protocol's 1% of `quoteLamports`, also paid on top. */
+  protocolLamports: bigint;
+  /** What the seed cost the creator at creation. Display only. */
+  seedLamports: bigint;
+  /** Tokens the seed locked in the vault: `(maxMultiplier - 1x)` packs. */
+  seedTokens: bigint;
+  /** Which venue the buy would route to right now. */
+  venue: VenueKind;
+  /** The frozen prize table this pack would get: real amounts, already capped by inventory. */
+  prizes: Prize[];
+  /** The top prize, after the cap. Sign `minMaximum` just below this. */
+  maximum: bigint;
+  /** The smallest prize. Also what a timed-out draw pays. */
+  minimum: bigint;
+  /** The top prize with no inventory cap: the jackpot in tokens. Equal to `maximum` unless the
+   *  inventory cap bites. */
+  uncapped: bigint;
+  /** Vault balance, `pool.reserved`, and the difference. */
+  inventory: bigint;
+  reserved: bigint;
+  free: bigint;
+  /** `pool.nextSeq === 0`. No pack has been sold yet. */
+  isFirstPack: boolean;
+  /**
+   * Does the pool pay the whole table right now?
+   *
+   * `offer.maximum === uncapped`. The seed guarantees this for the first pack. Later it is a
+   * quality signal: a capped top prize is legal and the pool still sells the pack. It just pays
+   * less than the table says, and a buyer should see that.
+   */
+  isSeeded: boolean;
+  /** The largest and the ticket-weighted average multiplier of the immutable table, in bps. */
+  maxMultiplierBps: number;
+  averageMultiplierBps: number;
+};
+export type GetOfferOptions = {
+  /** Force a venue instead of reading the bonding curve's `complete` flag. */
+  venue?: VenueKind;
+  /** The buyer, when you already know it. Only changes the account list, never the numbers. */
+  user?: Address;
+};
+/**
+ * The full offer for one machine. Two round trips: the pool and its vault, then the venue.
+ *
+ * Throws when the coin has no pool.
+ */
+export declare function getOffer(client: GaboxClient, mint: Address, options?: GetOfferOptions): Promise<PackOffer>;
+/**
+ * The same computation with the reads already done. Useful when a caller holds a `ResolvedVenue`
+ * and wants to re-price without touching the network. `quoteLamports` is
+ * `venue.quoteBuy(pool.packTokens)`.
+ */
+export declare function offerFromState(inventory: PoolInventory, venue: VenueKind, quoteLamports: bigint): PackOffer;
+/**
+ * How short of the top prize a pool is, in tokens. `0` when it pays the whole table.
+ *
+ * The pack brings its own `packTokens` into the vault before the offer is computed, so the vault
+ * only has to hold `uncapped - packTokens` beforehand. Anything already reserved by another draw
+ * does not count. A donation of this size through `fund_prizes` uncaps the top prize again.
+ */
+export declare function seedShortfall(offer: PackOffer): bigint;
+//#endregion
+//#region src/pdas.d.ts
+/** `['referral', referee]`. A wallet's permanent referral binding. */
+export declare function referralLinkAddress(referee: Address): Promise<Address>;
+/** `['referral', pool, referrer]`. A referrer's accrued rewards for one pool. */
+export declare function referralAddress(pool: Address, referrer: Address): Promise<Address>;
+/** `["pool", mint]`. One pool per coin, and the mint alone is the seed. */
+export declare function poolAddress(mint: Address): Promise<Address>;
+/** `["draw", pool, seq_u64_le]`. `seq` is `pool.nextSeq` at the moment of the purchase. */
+export declare function drawAddress(pool: Address, seq: bigint): Promise<Address>;
+/**
+ * `["identity"]` under gabox. This is the PDA gabox signs the VRF request with — the `identity`
+ * account of the `Oracle` group on `buy_pack` and `retry_draw`.
+ */
+export declare function vrfIdentityAddress(): Promise<Address>;
+/**
+ * `["identity", gabox_program_id]` under the **VRF program**. A different address from
+ * `vrfIdentityAddress`, and it belongs to the other side: MagicBlock signs the `deliver_draw`
+ * callback with it. A client never puts it in an instruction. It is here so a client can recognise
+ * the signer on a callback transaction.
+ */
+export declare function scopedVrfIdentityAddress(): Promise<ProgramDerivedAddress>;
+/**
+ * An associated token account. The seed order is `[owner, token_program, mint]`, which is the ATA
+ * program's own order and not the argument order most callers remember.
+ */
+export declare function associatedTokenAddress(owner: Address, mint: Address, tokenProgram?: Address): Promise<Address>;
+/**
+ * The protocol fee collector's WSOL ATA, under classic SPL Token. A sale on PumpSwap pays its
+ * protocol fee here. The account must exist before the first PumpSwap sale; see `DEPLOYMENT.md`.
+ */
+export declare function feeCollectorWsolAddress(): Promise<Address>;
+/**
+ * The pool's prize inventory: the pool PDA's ATA for the mint's own token program.
+ *
+ * `tokenProgram` defaults to Token-2022 because Pump `create_v2` mints there, and every machine is
+ * built on a coin Pump created. Pass the mint's real owner if you have it.
+ */
+export declare function vaultAddress(mint: Address, tokenProgram?: Address): Promise<Address>;
+//#endregion
+//#region src/tx/message.d.ts
+/**
+ * What every builder returns: a version 0 message with a fee-payer signer and a blockhash
+ * lifetime, ready for `signTransactionMessageWithSigners`.
+ *
+ * Named, and built only from types `@solana/kit` exports, so the published declaration file
+ * refers to kit's types instead of copying them. `pipe`'s inferred type is a long intersection
+ * of kit-internal brands, and a copy of a branded type is not assignable to the original.
+ */
+export type GaboxTransactionMessage = Extract<TransactionMessage, {
+  version: 0;
+}> & TransactionMessageWithFeePayerSigner & TransactionMessageWithBlockhashLifetime;
+export type BuildOptions = {
+  /** Compute units to request. Each builder passes its own default. */
+  computeUnitLimit: number;
+  /** Priority fee in micro-lamports per compute unit. Left out, no price instruction is added. */
+  computeUnitPrice?: number | bigint;
+  /** Defaults to the client's tables, which the cluster chose. Pass `{}` to disable compression. */
+  addressLookupTables?: AddressesByLookupTableAddress;
+};
+/**
+ * Build the message. One RPC read, for the blockhash.
+ *
+ * The blockhash expires in about a minute, so build the message when the user is ready to sign
+ * rather than when the page loads.
+ */
+export declare function buildMessage(client: GaboxClient, feePayer: TransactionSigner, instructions: Instruction[], options: BuildOptions): Promise<GaboxTransactionMessage>;
+/** Append `remainingAccounts` to a generated instruction, which is how a venue's list is passed. */
+export declare function withRemainingAccounts<T extends Instruction>(instruction: T, remaining: readonly NonNullable<T['accounts']>[number][]): T;
+//#endregion
+//#region src/tx/buyPack.d.ts
+export type BuyPackInput = {
+  mint: Address;
+  /** Pays for everything and signs. Becomes `draw.purchaser`. */
+  purchaser: TransactionSigner;
+  /** Slippage cap on the venue trade, in lamports (WSOL on PumpSwap). Must be positive. */
+  maxQuoteIn: bigint;
+  /** Floor on the top prize, in tokens. */
+  minMaximum: bigint;
+  /** Cap on venue debit + creator fee + protocol fee + VRF request, in lamports. Rent and tx fee
+   *  are extra. */
+  maxTotalDebit: bigint;
+  /** Force a venue. Left out, the bonding curve's `complete` flag decides. */
+  venue?: VenueKind;
+  /**
+   * Pin the draw's sequence number instead of reading `pool.nextSeq` now.
+   *
+   * The draw's address is `["draw", pool, seq]`, so a caller that has already told somebody which
+   * draw this purchase will create has to keep that promise if it rebuilds the message - after a
+   * stale blockhash, say. Rebuilding without a pin reads `nextSeq` again, and if the first attempt
+   * actually landed, the second one buys a **second pack** at the next sequence number rather than
+   * failing. With the pin it fails on the `init` constraint, which is the right outcome.
+   */
+  seq?: bigint;
+  /**
+   * Lamports to wrap into the buyer's WSOL account on the PumpSwap route. Left out, the builder
+   * wraps `maxQuoteIn`: the venue never takes more than that, and any surplus stays in the buyer's
+   * own WSOL account.
+   */
+  wrapLamports?: bigint;
+  /** Append PumpSwap's optional cashback account. Only for a cashback coin. */
+  cashback?: boolean;
+  /**
+   * A referrer to bind before the purchase, in the same transaction.
+   *
+   * A share link leaves the referrer's wallet in a cookie, and the first pack is where it matters:
+   * `bind_referrer` runs one instruction ahead of `buy_pack`, so the pack that converts the buyer
+   * is the pack that pays. Ignored when the buyer already has a link (the chain wins), when it
+   * names the buyer, or when it is the all-zero address. The link's rent is extra, on top of
+   * `maxTotalDebit`.
+   */
+  referrer?: Address;
+} & Partial<BuildOptions>;
+export declare function buyPack(client: GaboxClient, input: BuyPackInput): Promise<GaboxTransactionMessage>;
+//#endregion
+//#region src/tx/createMachine.d.ts
+export type CreateMachineInput = {
+  /** Pays for everything and signs both instructions. Becomes `pool.creator`. */
+  creator: TransactionSigner;
+  /** A fresh keypair for the coin. Signs `create_v2` and is never needed again. */
+  mintKeypair: TransactionSigner;
+  name: string;
+  symbol: string;
+  /** The metadata URI Pump writes onto the mint. */
+  uri: string;
+  /** The creator's fee per pack, in bps of what the venue charges. `0` to `MAX_FEE_BPS`. Immutable. */
+  feeBps: number;
+  /** Controls how much probability moves from Common into Rare, Epic, and Mythic. */
+  riskProfile: RiskProfile;
+  /**
+   * The jackpot: the largest tier's multiplier, in bps. `10_000` is 1x and needs no seed;
+   * `50_000` is 5x and seeds four packs of tokens. Immutable.
+   */
+  jackpotBps: number;
+  /**
+   * The creator's slippage cap on the seed buy, in lamports. Pump fails the buy above it.
+   * Take `seedCostEstimate` and add a margin. Ignored for a 1x jackpot, which buys nothing.
+   */
+  maxSeedLamports: bigint;
+  /** Which Pump fee recipient to use, as an index. Left out, one is picked at random. */
+  feeRecipientIndex?: number;
+  /** Same, for the buyback recipient list. */
+  buybackRecipientIndex?: number;
+} & Partial<BuildOptions>;
+/**
+ * Build the transaction message. Sign it with both `creator` and `mintKeypair`.
+ *
+ * Reads Pump's `Global` account, because two of the buy accounts — the fee recipient and the
+ * buyback fee recipient — are chosen from lists held there. Nothing else needs the chain: the coin
+ * does not exist yet, so every other account is a derivation.
+ */
+export declare function createMachine(client: GaboxClient, input: CreateMachineInput): Promise<GaboxTransactionMessage>;
+/**
+ * What the seed for this jackpot costs, fees included, and how many tokens it is.
+ *
+ * The coin does not exist yet, so the price is Pump's default new curve. Nothing else trades on
+ * it before `initialize_pool` runs in the same transaction, so this is exact up to a change in
+ * Pump's fee settings between the read and the send. Add a small margin for `maxSeedLamports`.
+ */
+export declare function seedCostEstimate(client: GaboxClient, jackpotBps: number, riskProfile: RiskProfile): Promise<{
+  tiers: Tier[];
+  seedTokens: bigint;
+  lamports: bigint;
+}>;
+/**
+ * The Pump buy accounts for the seed, built without reading the bonding curve.
+ *
+ * The curve does not exist yet — `create_v2` in the same transaction is what creates it — so
+ * `resolveVenue` cannot be used here. Everything the account list needs is known anyway: the
+ * creator vault follows from the `creator` argument that `create_v2` records on the curve, and the
+ * two fee recipients come from `Global`.
+ */
+export declare function pumpSeedBuyAccounts(client: GaboxClient, options: {
+  mint: Address;
+  user: Address;
+  feeRecipientIndex?: number;
+  buybackRecipientIndex?: number;
+}): Promise<AccountMeta[]>;
+//#endregion
+//#region src/tx/draw.d.ts
+export type RetryDrawInput = {
+  /** Pays the oracle fee and the transaction fee. Any wallet. */
+  payer: TransactionSigner;
+  pool: Address;
+  draw: Address;
+  /** Cap on what the oracle request may take from `payer`, in lamports. */
+  maxVrfDebit: bigint;
+} & Partial<BuildOptions>;
+export declare function retryDraw(client: GaboxClient, input: RetryDrawInput): Promise<GaboxTransactionMessage>;
+export type ExpireDrawInput = {
+  /** Only pays the transaction fee. `expire_draw` itself has no signer account. */
+  payer: TransactionSigner;
+  pool: Address;
+  draw: Address;
+} & Partial<BuildOptions>;
+export declare function expireDraw(client: GaboxClient, input: ExpireDrawInput): Promise<GaboxTransactionMessage>;
+export type DrawAvailability = {
+  status: DrawStatus;
+  attempts: number;
+  /** Slots remaining before a retry is allowed. `0` when it is allowed now. */
+  slotsUntilRetry: bigint;
+  /** Slots remaining before the draw can be expired. `0` when it can be expired now. */
+  slotsUntilExpiry: bigint;
+  /** All three conditions the program checks for `retry_draw`, together. */
+  canRetry: boolean;
+  /** The one condition `expire_draw` checks. */
+  canExpire: boolean;
+};
+/**
+ * What a client may do to a draw right now.
+ *
+ * Reads the draw and the current slot, and reproduces the program's three retry conditions and its
+ * one expiry condition. Showing a disabled button with a countdown beats sending a transaction that
+ * fails with `RetryTooSoon`.
+ */
+export declare function drawAvailability(client: GaboxClient, draw: Address): Promise<DrawAvailability | null>;
+//#endregion
+//#region src/tx/fundPrizes.d.ts
+export type FundPrizesInput = {
+  mint: Address;
+  /** The donor. Signs, and the tokens leave its account. */
+  funder: TransactionSigner;
+  /** Tokens to donate, in the mint's smallest unit. Must be positive. */
+  amount: bigint;
+  /**
+   * The account the tokens come from. Defaults to the funder's associated token account, which is
+   * where a wallet holds them. Any token account the funder is the authority of works.
+   */
+  source?: Address;
+} & Partial<BuildOptions>;
+export declare function fundPrizes(client: GaboxClient, input: FundPrizesInput): Promise<GaboxTransactionMessage>;
+export type FundPrizesWithBuyInput = {
+  mint: Address;
+  /** The donor. Buys the tokens, then gives them away. Signs both instructions. */
+  funder: TransactionSigner;
+  /** Exact tokens to buy and donate. `seedShortfall(offer)` is the amount that uncaps the top prize. */
+  tokens: bigint;
+  /** The donor's slippage cap on the buy, in lamports (WSOL on PumpSwap). */
+  maxQuoteIn: bigint;
+  /** Force a venue. Left out, the bonding curve's `complete` flag decides. */
+  venue?: VenueKind;
+  /**
+   * Lamports to wrap on the PumpSwap route. Left out, `maxQuoteIn`. The venue never takes more
+   * than that, and any surplus stays in the donor's own WSOL account.
+   */
+  wrapLamports?: bigint;
+} & Partial<BuildOptions>;
+/**
+ * Buy tokens at the venue with SOL and donate them to the vault, in one transaction.
+ *
+ * This is what a donor with SOL and no coins needs. `fundPrizes` moves tokens the donor already
+ * holds; this one buys them first. Both are irrevocable — there is no withdrawal instruction, and
+ * no authority can move vault tokens.
+ *
+ * Three instructions on the curve route: create the donor's token account if it is missing, buy,
+ * donate. Pump creates the account itself, but the idempotent instruction costs nothing when it
+ * already exists and it makes the transaction correct on its own terms. The PumpSwap route adds the
+ * WSOL create/fund/sync prefix, for the same reason `buyPack` does: PumpSwap spends WSOL.
+ */
+export declare function fundPrizesWithBuy(client: GaboxClient, input: FundPrizesWithBuyInput): Promise<GaboxTransactionMessage>;
+//#endregion
+//#region src/tx/redeem.d.ts
+export type SellTokensInput = {
+  mint: Address;
+  /** Wallet that owns the tokens and signs the venue sale. */
+  seller: TransactionSigner;
+  /** Exact token amount to sell. Must be positive. */
+  amount: bigint;
+  /** Floor on the venue's net output, in lamports or WSOL, before the protocol fee. Must be
+   *  positive: the program rejects zero, because a zero floor is not slippage protection. */
+  minQuoteOutput: bigint;
+  /** Force a venue. Left out, the bonding curve's `complete` flag decides. */
+  venue?: VenueKind;
+} & Partial<BuildOptions>;
+/**
+ * Sell a prize that the VRF callback already delivered to the wallet, through `sell_tokens`.
+ *
+ * The program needs the coin's pool: it keeps the vault out of the venue's account list. A mint
+ * with no pool cannot be sold this way; use a plain venue trade for that.
+ */
+export declare function sellTokens(client: GaboxClient, input: SellTokensInput): Promise<GaboxTransactionMessage>;
+export type ClaimPrizeInput = {
+  mint: Address;
+  /** The wallet that bought the legacy pack. Only it can settle the draw. */
+  purchaser: TransactionSigner;
+  /** The draw to redeem. */
+  draw: Address;
+} & Partial<BuildOptions>;
+/** Transfer a legacy resolve-only award into the purchaser's token account and close the draw. */
+export declare function claimPrize(client: GaboxClient, input: ClaimPrizeInput): Promise<GaboxTransactionMessage>;
+export type SellPrizeInput = ClaimPrizeInput & {
+  /**
+   * The seller's floor on the venue's net output, in lamports or WSOL. Must be positive: the
+   * program rejects zero, because a zero floor is not slippage protection.
+   *
+   * This is the venue's own net quote, before the protocol fee. It is not net of the transaction
+   * fee or of any rent the transaction pays.
+   */
+  minQuoteOutput: bigint;
+  /** Force a venue. Left out, the bonding curve's `complete` flag decides. */
+  venue?: VenueKind;
+};
+/**
+ * Claim and sell a legacy resolve-only draw in one transaction.
+ *
+ * The award is read off the draw so the caller can price the sale before signing. A draw that has
+ * not resolved has no award yet, and this throws rather than building a sale of zero tokens.
+ */
+export declare function sellPrize(client: GaboxClient, input: SellPrizeInput): Promise<GaboxTransactionMessage>;
+/**
+ * Quote the award held by a legacy open draw before the seller signs a floor.
+ *
+ * Read the draw, ask the venue, and subtract your own slippage tolerance to get `minQuoteOutput`.
+ */
+export declare function quoteSellPrize(client: GaboxClient, mint: Address, draw: Address, user: Address): Promise<{
+  award: bigint;
+  grossOutput: bigint;
+}>;
+//#endregion
+//#region src/referral.d.ts
+export type ReferralResolution = Readonly<{
+  link: Address;
+  referrer: Address;
+  referral: Address;
+}>;
+/** Resolve the purchaser's permanent referral binding for a pack purchase. */
+export declare function resolveReferral(client: GaboxClient, purchaser: Address, pool: Address): Promise<ReferralResolution | null>;
+/** Bind a wallet to a referrer. The purchaser signs and the binding is permanent. */
+export declare function bindReferrer(client: GaboxClient, referee: TransactionSigner, referrer: Address, options?: Partial<BuildOptions>): Promise<GaboxTransactionMessage>;
+/** Claim all accrued referral rewards for one pool. */
+export declare function claimReferral(client: GaboxClient, referrer: TransactionSigner, pool: Address, options?: Partial<BuildOptions>): Promise<GaboxTransactionMessage>;
+//#endregion
+//#region src/vrf.d.ts
+/** The four accounts, named as the generated client names them. */
+export type OracleAccounts = {
+  /** `["identity"]` under gabox. The PDA gabox signs the randomness request with. */
+  identity: Address;
+  /** MagicBlock's default queue. Writable. */
+  queue: Address;
+  /** The VRF program itself. */
+  program: Address;
+  /** The slot-hashes sysvar, which seeds the request. */
+  slotHashes: Address;
+};
+/**
+ * Build the group. Nothing here reads the chain, so it is safe to call on every render.
+ *
+ * The generated instruction builders default `queue`, `program` and `slotHashes` on their own, so
+ * passing this whole object is belt and braces. It is worth having anyway: a caller can show the
+ * four accounts a draw request will touch before asking for a signature.
+ */
+export declare function oracleAccounts(): Promise<OracleAccounts>;
+//#endregion
+export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, CLUSTER_ENDPOINTS, ClientConfig, Cluster, DEVNET_HTTP, DEVNET_WS, DRAW_DISCRIMINATOR, type Draw, GaboxClient, GaboxRpc, GaboxRpcSubscriptions, MAYHEM_PROGRAM_ADDRESS, POOL_DISCRIMINATOR, PUMP_FEE_PROGRAM_ADDRESS, PUMP_PROGRAM_ADDRESS, PUMP_SWAP_PROGRAM_ADDRESS, type Pool, type Referral, type ReferralLink, SYSTEM_PROGRAM_ADDRESS, assertClusterUrl, clusterNamedBy, createClient, decodeDraw, decodePool, findDrawPda, findIdentityPda, findPoolPda, findReferralLinkPda, index_d_exports as generated, index_d_exports$1 as pump, websocketUrlFor };
+//# sourceMappingURL=index.d.ts.map