@bordrless/shared 0.6.0 → 0.7.0

package/dist/api.d.ts

@@ -570,14 +570,136 @@ export interface LaunchPrepareRequest {
      */
     companion?: CompanionRequest;
 }
-/** A launch's companion as the launch request names it: a split of the creator fee, or one of the preset splits by name. */
+/**
+ * A launch's companion as the launch request names it: a split of the creator fee, or one of the
+ * preset splits by name; with `game`, a lottery coin (docs/games.md): the split's holders' share is
+ * then 0 and the pot's part (`game.potBps`) makes the four add up to 10,000.
+ */
 export type CompanionRequest = {
     split: CompanionSplitBps;
     vestDays?: number;
+    game?: LotteryRequest;
 } | {
     template: CompanionTemplate;
     vestDays?: number;
 };
+/**
+ * A lottery coin's game as the launch request names it (docs/games.md "The companion's game"):
+ * every setting `create_game` fixes before the launch. Bounds: `LOTTERY_LIMITS` (`lotteryProblem`).
+ */
+export interface LotteryRequest {
+    kind: 'lottery';
+    /** A round's length, seconds: an hour to 30 days. Every holder's tokens held since a round began are their tickets in it. */
+    roundSecs: number;
+    /** The pot's part of every creator fee claim, basis points: with the split's buyback and launcher parts it adds up to 10,000. */
+    potBps: number;
+    /** No draw while the pot holds less, lamports: 0.1 to 1,000 SOL. */
+    minPotLamports: Amount;
+    /** The part of the pot one draw pays, basis points: 10% to 100%. */
+    prizeBps: number;
+    /** How long each claim attempt stays open, seconds: 5 minutes to a day. */
+    claimWindowSecs: number;
+    /** Attempts a draw makes before it rolls over, 1 to 16; all of them within half a round. */
+    maxAttempts: number;
+}
+/** A lottery coin's settings as its token page shows them (`CompanionSummary.game`): fixed at the launch, and the hook's terms. */
+export interface GameSummary {
+    kind: 'lottery';
+    /** The game's account, `PDA(["game", mint])` under the companion program. */
+    address: Address;
+    /** The coin's token hook, which keeps the tickets (the lottery hook). */
+    hook: Address;
+    roundSecs: number;
+    potBps: number;
+    minPot: Amount;
+    prizeBps: number;
+    claimWindowSecs: number;
+    maxAttempts: number;
+    /** The most the pot may hold while the hook is not audited (lamports); null for an audited hook. */
+    potCap: Amount | null;
+    audited: boolean;
+    /** Bordrless stopped this hook's games: the pot and its share go to the buyback and are burned. */
+    blocked: boolean;
+    /** Prizes paid so far, lamports, and how many. */
+    prizesTotal: Amount;
+    prizesPaid: number;
+}
+/** Why a round paid no prize (the companion's `RolloverReason`). */
+export type GameRolloverReason = 'noTickets' | 'roundForgotten' | 'noClaim' | 'oracleSilent' | 'blocked' | 'late' | 'oracleUnreadable' | 'oracleUnpaid';
+/** One round's draw as the indexer saw it (`GameStatus.draws`), newest first. */
+export interface GameDraw {
+    round: number;
+    /** When the round ended (its tickets final), unix seconds. */
+    roundEndsAt: number;
+    /** `requested`: ORAO asked; `revealed`: its answer stored, claims open; `paid`: the prize paid; `rolledOver`: no prize. */
+    status: 'requested' | 'revealed' | 'paid' | 'rolledOver';
+    /** The round's ticket total, base units. */
+    total: Amount;
+    /** ORAO's request account for the round's seed; null when no seed was committed. */
+    request: Address | null;
+    winner: Address | null;
+    /** Lamports paid; null unless paid. */
+    prize: Amount | null;
+    /** The ticket attempt that paid, 0-based; null unless paid. */
+    attempt: number | null;
+    reason: GameRolloverReason | null;
+    /** The transaction of the draw's last step, and when it landed. */
+    signature: string;
+    at: number | null;
+}
+/** The caller's place in the current round (`GameStatus.you`, with `?wallet=`). */
+export interface GameYou {
+    wallet: Address;
+    /** Tokens the wallet holds, base units. */
+    balance: Amount;
+    /** Its tickets in the current round, base units (its range's weight); 0 until it is written this round. */
+    tickets: Amount;
+    /** The wallet's holding has been written this round (it traded, or was entered): its tickets are registered. */
+    entered: boolean;
+    /** Its share of the round's tickets so far, 0 to 1; null without tickets. */
+    odds: number | null;
+    /** Its tickets in the round before (the one a draw may be for now). */
+    previousTickets: Amount;
+}
+/** A lottery coin's live state (`CompanionStatus.game`, docs/games.md): the pot, the round, the draw, the caller's tickets and the draw history. */
+export interface GameStatus extends GameSummary {
+    /** Bridged SOL the pot holds, lamports. */
+    pot: Amount;
+    /** Chain time the status was read at, unix seconds. */
+    now: number;
+    /** The current round (`floor(now / roundSecs)`) and when it ends. */
+    round: number;
+    roundEndsAt: number;
+    /** Tickets registered in the current round so far, base units (the hook's header). */
+    tickets: Amount;
+    /** The round before, and its tickets: what the next draw is for once the round ends. */
+    previousRound: number;
+    previousTickets: Amount;
+    /** The least the pot must hold for a round to be drawn (the minimum, or the cap when lower; 0.1 SOL once dormant). */
+    drawThreshold: Amount;
+    /** The draw in progress, when one is. */
+    draw: {
+        round: number;
+        status: 'requested' | 'revealed';
+        request: Address;
+        prize: Amount;
+        revealedAt: number | null;
+        claimsEndAt: number;
+    } | null;
+    lastWinner: Address | null;
+    you: GameYou | null;
+    draws: GameDraw[];
+}
+/** `POST /v1/game/enter/prepare`: a holder's own `enter` (docs/games.md): their whole balance registered as tickets for the current round, when the holding was not written this round yet. */
+export interface GameEnterRequest {
+    wallet: Address;
+    mint: Address;
+}
+export interface GameEnterResponse {
+    transactions: PreparedTx[];
+    /** The round the tickets count in. */
+    round: number;
+}
 /** The companion templates (`COMPANION_SPLITS`; `COMPANION_TEMPLATES` in the SDK). */
 export type CompanionTemplate = 'buysItself' | 'rugProofDev' | 'buybackAndReward';
 /** What a companion does with every creator fee it claims, in basis points summing to 10,000. */
@@ -623,6 +745,8 @@ export interface CompanionSummary {
     } | null;
     /** When the next buyback may run while SOL waits for one (it also waits while the price runs above its reference); null otherwise. */
     nextBuybackAt: number | null;
+    /** The lottery this companion runs (docs/games.md): its settings and the hook's terms; null for a companion without a game. */
+    game: GameSummary | null;
 }
 /**
  * `GET /v1/companion/:mint`: a mint's companion as a launch that may not have finished needs it.
@@ -636,6 +760,8 @@ export interface CompanionStatus {
     beneficiary: Address | null;
     /** Lamports a refund returns now; null unless `set-up`. */
     refundable: Amount | null;
+    /** The lottery this companion runs, live (docs/games.md), the caller's tickets with `?wallet=`; null for a companion without a game (absent from older servers). */
+    game?: GameStatus | null;
 }
 /** `POST /v1/companion/refund/prepare`: a companion's funding back to the wallet that set it up, for a launch that never happened. The mint's key signs it after the wallet. */
 export interface CompanionRefundRequest {

package/dist/policy.d.ts

@@ -6,7 +6,7 @@
  * `programs/tests/vectors/launch-fees.json`, which the Rust tests render from the reference the
  * programs are held to, and requires exact equality.
  */
-import type { CompanionSplitBps, CompanionTemplate, LaunchRules, LaunchRulesInput, Side } from './api.ts';
+import type { CompanionSplitBps, CompanionTemplate, GameRolloverReason, LaunchRules, LaunchRulesInput, LotteryRequest, Side } from './api.ts';
 export declare const BPS = 10000n;
 export declare const WAD: bigint;
 /** The largest u64, where the programs' checked arithmetic stops. */
@@ -284,6 +284,71 @@ export declare const COMPANION_DEFAULT_VEST_DAYS = 30;
 export declare const COMPANION_MAX_VEST_DAYS = 365;
 /** The whole creator fee to the launcher: an ordinary launch, with no companion. */
 export declare const LAUNCHER_SPLIT: Readonly<CompanionSplitBps>;
+/**
+ * The companion program's game limits (`constants.rs`; `GAME_LIMITS` in the SDK, the same numbers):
+ * a round's length, the minimum pot, the prize's least share, a claim window's bounds, the most
+ * attempts, and the half of a round the attempts may take. The launch form holds its choices to
+ * them and the backend refuses anything outside them (`lotteryProblem`).
+ */
+export declare const LOTTERY_LIMITS: {
+    readonly minRoundSecs: 3600;
+    readonly maxRoundSecs: number;
+    readonly minMinPotLamports: 100000000n;
+    readonly maxMinPotLamports: 1000000000000n;
+    readonly minPrizeBps: 1000;
+    readonly minClaimWindowSecs: 300;
+    readonly maxClaimWindowSecs: 86400;
+    readonly maxAttempts: 16;
+    readonly claimsPerRound: 2;
+    /** The most a pot holds while its hook is not audited: 10 SOL, the rest of the pot's share bought back. */
+    readonly potCapLamports: 10000000000n;
+    /** Lamports the setup pays for the hook's state and registry and the game's account (mainnet rent, 2026-10-08). */
+    readonly rentLamports: bigint;
+};
+/** The lottery the launch form starts with (docs/games.md, spec example 1): 6-hour rounds, 70% of the fee to the pot, 30% bought back, draws from 0.5 SOL paying the whole pot, 8 claim attempts of 10 minutes. */
+export declare const LOTTERY_DEFAULTS: Readonly<LotteryRequest>;
+/** The round lengths the form offers (seconds), each with its label. */
+export declare const LOTTERY_ROUND_CHOICES: readonly {
+    secs: number;
+    label: string;
+}[];
+/** The least a pot holds before a round is drawn, as the form offers it (lamports). */
+export declare const LOTTERY_MIN_POT_CHOICES: readonly {
+    lamports: string;
+    label: string;
+}[];
+/** What one draw pays of the pot, as the form offers it. */
+export declare const LOTTERY_PRIZE_CHOICES_BPS: readonly [10000, 5000, 2500];
+/** The pot's share moves in steps of 10%, like the Split control's. */
+export declare const LOTTERY_POT_STEP_BPS = 1000;
+/**
+ * The claim windows and attempts the form fixes for a round length: 8 attempts of 10 minutes for a
+ * round of 6 hours or more, 6 of 5 minutes for an hour (the attempts must fit in half a round).
+ */
+export declare function lotteryClaimsFor(roundSecs: number): {
+    claimWindowSecs: number;
+    maxAttempts: number;
+};
+/** The lottery a launch request's `companion.game` names, each field a whole number; null when it is malformed (bounds are `lotteryProblem`'s). */
+export declare function lotteryRequestOf(raw: unknown): LotteryRequest | null;
+/**
+ * Why `create_game` would refuse this lottery with this split on these rules, in the words the
+ * launch form and the backend use (`companion_rules`); null when it would not. The program's own
+ * checks (`gameArgsProblem` in the SDK, the same sentences), and what a lottery coin's launch
+ * needs besides: a creator fee, no token rules (it launches from Bordrless's lottery config, which
+ * has none, and runs its own hook in the kit's place), and no holders' share.
+ */
+export declare function lotteryProblem(game: LotteryRequest, split: CompanionSplitBps, rules: LaunchRulesInput, creatorFeeBps: number): string | null;
+/** The copy rules of a lottery coin (docs/games.md): said on the launch form, the review step and the token page, never "provably fair", "guaranteed" or "audited". */
+export declare const LOTTERY_COPY: {
+    readonly held: "The pot is held by the companion program and paid out by code. Randomness by ORAO VRF.";
+    readonly odds: "Your odds = your tokens in the round. Sell before the payout and you forfeit.";
+    readonly stop: "Bordrless can stop this game: its pot would be bought back and burned. Nobody is paid.";
+    readonly cap: "Pot capped at 10 SOL until the game’s hook is audited.";
+    readonly oracle: "Randomness by ORAO VRF: ORAO’s three signers produce it. They could withhold or bias a draw; Bordrless can’t.";
+};
+/** Why a round paid no prize, in a few words each (`GameRolloverReason`). */
+export declare const ROLLOVER_WORDS: Readonly<Record<GameRolloverReason, string>>;
 /** Whether a split is the whole fee to the launcher (no companion needed). */
 export declare const isLauncherSplit: (s: CompanionSplitBps) => boolean;
 /** A split with a share for holders needs holder rewards on. */

package/dist/policy.js

@@ -368,6 +368,120 @@ export const COMPANION_DEFAULT_VEST_DAYS = 30;
 export const COMPANION_MAX_VEST_DAYS = 365;
 /** The whole creator fee to the launcher: an ordinary launch, with no companion. */
 export const LAUNCHER_SPLIT = { buybackBps: 0, holdersBps: 0, beneficiaryBps: 10_000 };
+// ---- lottery coins (docs/games.md) -----------------------------------------------------------------
+/**
+ * The companion program's game limits (`constants.rs`; `GAME_LIMITS` in the SDK, the same numbers):
+ * a round's length, the minimum pot, the prize's least share, a claim window's bounds, the most
+ * attempts, and the half of a round the attempts may take. The launch form holds its choices to
+ * them and the backend refuses anything outside them (`lotteryProblem`).
+ */
+export const LOTTERY_LIMITS = {
+    minRoundSecs: 3_600,
+    maxRoundSecs: 30 * DAY_SECS,
+    minMinPotLamports: 100000000n,
+    maxMinPotLamports: 1000000000000n,
+    minPrizeBps: 1_000,
+    minClaimWindowSecs: 300,
+    maxClaimWindowSecs: DAY_SECS,
+    maxAttempts: 16,
+    claimsPerRound: 2,
+    /** The most a pot holds while its hook is not audited: 10 SOL, the rest of the pot's share bought back. */
+    potCapLamports: 10000000000n,
+    /** Lamports the setup pays for the hook's state and registry and the game's account (mainnet rent, 2026-10-08). */
+    rentLamports: 3515360n + 3119120n,
+};
+/** The lottery the launch form starts with (docs/games.md, spec example 1): 6-hour rounds, 70% of the fee to the pot, 30% bought back, draws from 0.5 SOL paying the whole pot, 8 claim attempts of 10 minutes. */
+export const LOTTERY_DEFAULTS = { kind: 'lottery', roundSecs: 21_600, potBps: 7_000, minPotLamports: '500000000', prizeBps: 10_000, claimWindowSecs: 600, maxAttempts: 8 };
+/** The round lengths the form offers (seconds), each with its label. */
+export const LOTTERY_ROUND_CHOICES = [
+    { secs: 3_600, label: '1 hour' },
+    { secs: 21_600, label: '6 hours' },
+    { secs: DAY_SECS, label: '1 day' },
+    { secs: 7 * DAY_SECS, label: '7 days' },
+];
+/** The least a pot holds before a round is drawn, as the form offers it (lamports). */
+export const LOTTERY_MIN_POT_CHOICES = [
+    { lamports: '100000000', label: '0.1 SOL' },
+    { lamports: '500000000', label: '0.5 SOL' },
+    { lamports: '1000000000', label: '1 SOL' },
+    { lamports: '5000000000', label: '5 SOL' },
+];
+/** What one draw pays of the pot, as the form offers it. */
+export const LOTTERY_PRIZE_CHOICES_BPS = [10_000, 5_000, 2_500];
+/** The pot's share moves in steps of 10%, like the Split control's. */
+export const LOTTERY_POT_STEP_BPS = 1_000;
+/**
+ * The claim windows and attempts the form fixes for a round length: 8 attempts of 10 minutes for a
+ * round of 6 hours or more, 6 of 5 minutes for an hour (the attempts must fit in half a round).
+ */
+export function lotteryClaimsFor(roundSecs) {
+    return roundSecs >= 21_600 ? { claimWindowSecs: 600, maxAttempts: 8 } : { claimWindowSecs: 300, maxAttempts: 6 };
+}
+const isWhole = (v, min, max) => typeof v === 'number' && Number.isInteger(v) && v >= min && v <= max;
+/** The lottery a launch request's `companion.game` names, each field a whole number; null when it is malformed (bounds are `lotteryProblem`'s). */
+export function lotteryRequestOf(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const r = raw;
+    if (r.kind !== 'lottery')
+        return null;
+    if (!isWhole(r.roundSecs, 0, 2 ** 32 - 1) || !isWhole(r.potBps, 0, 10_000) || !isWhole(r.prizeBps, 0, 10_000) || !isWhole(r.claimWindowSecs, 0, 2 ** 32 - 1) || !isWhole(r.maxAttempts, 0, 255))
+        return null;
+    if (typeof r.minPotLamports !== 'string' || !/^\d{1,20}$/.test(r.minPotLamports))
+        return null;
+    return { kind: 'lottery', roundSecs: r.roundSecs, potBps: r.potBps, minPotLamports: r.minPotLamports, prizeBps: r.prizeBps, claimWindowSecs: r.claimWindowSecs, maxAttempts: r.maxAttempts };
+}
+/**
+ * Why `create_game` would refuse this lottery with this split on these rules, in the words the
+ * launch form and the backend use (`companion_rules`); null when it would not. The program's own
+ * checks (`gameArgsProblem` in the SDK, the same sentences), and what a lottery coin's launch
+ * needs besides: a creator fee, no token rules (it launches from Bordrless's lottery config, which
+ * has none, and runs its own hook in the kit's place), and no holders' share.
+ */
+export function lotteryProblem(game, split, rules, creatorFeeBps) {
+    const L = LOTTERY_LIMITS;
+    if (creatorFeeBps === 0)
+        return 'There is no creator fee to fill the pot with: set one.';
+    if (Object.keys(NO_RULES).some((k) => rules[k] !== 0))
+        return 'A lottery coin has no other token rules: its hook keeps the tickets.';
+    if (split.holdersBps !== 0)
+        return 'A game coin runs its own hook, so it has no holder rewards: no holders’ part.';
+    if (!(game.potBps > 0) || split.buybackBps + split.holdersBps + split.beneficiaryBps + game.potBps !== 10_000)
+        return 'The pot’s part and the split must add up to 10,000 basis points, with a pot.';
+    if (game.roundSecs < L.minRoundSecs || game.roundSecs > L.maxRoundSecs)
+        return 'A round lasts an hour to 30 days.';
+    const minPot = BigInt(game.minPotLamports);
+    if (minPot < L.minMinPotLamports || minPot > L.maxMinPotLamports)
+        return 'The minimum pot is 0.1 to 1,000 SOL.';
+    if (game.prizeBps < L.minPrizeBps || game.prizeBps > 10_000)
+        return 'A draw pays 10% to 100% of the pot.';
+    if (game.claimWindowSecs < L.minClaimWindowSecs || game.claimWindowSecs > L.maxClaimWindowSecs)
+        return 'A claim window lasts 5 minutes to a day.';
+    if (!(game.maxAttempts >= 1 && game.maxAttempts <= L.maxAttempts))
+        return 'A draw makes 1 to 16 attempts.';
+    if (game.claimWindowSecs * game.maxAttempts * L.claimsPerRound > game.roundSecs)
+        return 'A draw’s attempts must fit in half a round.';
+    return null;
+}
+/** The copy rules of a lottery coin (docs/games.md): said on the launch form, the review step and the token page, never "provably fair", "guaranteed" or "audited". */
+export const LOTTERY_COPY = {
+    held: 'The pot is held by the companion program and paid out by code. Randomness by ORAO VRF.',
+    odds: 'Your odds = your tokens in the round. Sell before the payout and you forfeit.',
+    stop: 'Bordrless can stop this game: its pot would be bought back and burned. Nobody is paid.',
+    cap: 'Pot capped at 10 SOL until the game’s hook is audited.',
+    oracle: 'Randomness by ORAO VRF: ORAO’s three signers produce it. They could withhold or bias a draw; Bordrless can’t.',
+};
+/** Why a round paid no prize, in a few words each (`GameRolloverReason`). */
+export const ROLLOVER_WORDS = {
+    noTickets: 'Nobody held tickets',
+    roundForgotten: 'The round was forgotten',
+    noClaim: 'No winner claimed in time',
+    oracleSilent: 'ORAO never answered',
+    blocked: 'Stopped by Bordrless',
+    late: 'Drawn too late',
+    oracleUnreadable: 'ORAO’s answer unreadable',
+    oracleUnpaid: 'The pot could not pay ORAO',
+};
 /** Whether a split is the whole fee to the launcher (no companion needed). */
 export const isLauncherSplit = (s) => s.buybackBps === 0 && s.holdersBps === 0 && s.beneficiaryBps === 10_000;
 /** A split with a share for holders needs holder rewards on. */

package/dist/programs.d.ts

@@ -35,7 +35,17 @@ export declare const LOTTERY_HOOK: {
     readonly tokenHookSigner: "CFyuaxvKmpgnSMCoNqDKCcwxnTUeW8Mm1go1t3UMsvLH";
     readonly hookAuthority: "6oZ9LkAfgmhmPYjXj3okjYK5sderddEo8fp8MR4H6Gx1";
     readonly readme: "https://github.com/BordrlessDex/bordrless-programs/tree/main/programs/lottery_hook";
+    /**
+     * The `LaunchConfig`s a lottery coin launches from, one per creator fee (basis points): each
+     * names this hook with `flags`, no token rules and that creator fee, made by the protocol with
+     * `pnpm admin lottery-configs` (which prints the lines to paste here). A creator fee without a
+     * config can't launch a lottery coin yet: the launch form says so, the backend refuses it
+     * (`lottery_off`). Created on mainnet 2026-10-09 by `pnpm admin lottery-configs`.
+     */
+    readonly launchConfigs: Readonly<Partial<Record<number, string>>>;
 };
+/** The creator fees (basis points) a lottery coin can launch with: those with a `LaunchConfig` in `LOTTERY_HOOK.launchConfigs`. */
+export declare const lotteryFeeChoices: () => number[];
 /**
  * Half-Life, Bordrless's own token hook (programs/half_life/README.md): the `LaunchConfig` the
  * launch form's Half-Life path launches from (no kit rules, creator fee 1%, the hook with

package/dist/programs.js

@@ -35,7 +35,21 @@ export const LOTTERY_HOOK = {
     tokenHookSigner: 'CFyuaxvKmpgnSMCoNqDKCcwxnTUeW8Mm1go1t3UMsvLH',
     hookAuthority: '6oZ9LkAfgmhmPYjXj3okjYK5sderddEo8fp8MR4H6Gx1',
     readme: 'https://github.com/BordrlessDex/bordrless-programs/tree/main/programs/lottery_hook',
+    /**
+     * The `LaunchConfig`s a lottery coin launches from, one per creator fee (basis points): each
+     * names this hook with `flags`, no token rules and that creator fee, made by the protocol with
+     * `pnpm admin lottery-configs` (which prints the lines to paste here). A creator fee without a
+     * config can't launch a lottery coin yet: the launch form says so, the backend refuses it
+     * (`lottery_off`). Created on mainnet 2026-10-09 by `pnpm admin lottery-configs`.
+     */
+    launchConfigs: {
+        50: 'CYm9FNY49gV7wjukpYFqkm9u7FQLrjp2GexeHwbncf1L',
+        100: 'GViQSt6znkGdiCrUYNTo3dJKMgfGS8eBHPSBjxfN2VS9',
+        200: 'Ejo4Ehg4x16MeBKn3Y2f1NU31CoBjnby4kv75azUD8hU',
+    },
 };
+/** The creator fees (basis points) a lottery coin can launch with: those with a `LaunchConfig` in `LOTTERY_HOOK.launchConfigs`. */
+export const lotteryFeeChoices = () => Object.keys(LOTTERY_HOOK.launchConfigs).map(Number).filter((bps) => bps > 0);
 /**
  * Half-Life, Bordrless's own token hook (programs/half_life/README.md): the `LaunchConfig` the
  * launch form's Half-Life path launches from (no kit rules, creator fee 1%, the hook with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bordrless/shared",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Bordrless policy (the same math as crates/bordrless-core), program addresses and the API types shared by the server and the site. No Solana dependencies.",
   "license": "Apache-2.0",