@bordrless/shared 0.7.0 → 0.8.0

package/dist/api.d.ts

@@ -206,6 +206,12 @@ export interface ConfigInspection {
     authorShareBps: number;
     /** The hook was built and deployed by Studio: the launch prepares it for the mint itself (its standard `prepare`). */
     studioHook?: boolean;
+    /**
+     * The hook is a game hook made in Studio (docs/games.md "Phase 2"): its kind and the constants
+     * its source fixes. The config then launches a jackpot or streak coin through the companion
+     * (`companion.game` of that kind); null or absent for any other hook.
+     */
+    game?: import('./studio.ts').StudioGameSettings | null;
 }
 /** Live figures of a launch's token rules; each null when the launch lacks the rule or it is not tracked. */
 export interface RuleStats {
@@ -248,6 +254,8 @@ export interface ProgramInfo {
     upgradeAuthority: Address | null;
     /** Whether the program can still be upgraded; null when unknown. */
     upgradeable: boolean | null;
+    /** Phase 3a: present (true) when the upgrade authority is the program's own `hook_timelock` account. */
+    timelocked?: boolean;
 }
 export interface LaunchSummary {
     mint: Address;
@@ -578,11 +586,40 @@ export interface LaunchPrepareRequest {
 export type CompanionRequest = {
     split: CompanionSplitBps;
     vestDays?: number;
-    game?: LotteryRequest;
+    game?: GameRequest;
 } | {
     template: CompanionTemplate;
     vestDays?: number;
 };
+/** The kinds of game a companion runs (the companion's `GameKind`): the lottery (phase 1), the last-buyer jackpot and the holding streak (phase 2). */
+export type GameKindName = 'lottery' | 'jackpot' | 'streak' | 'strategy';
+/**
+ * A game coin's game as the launch request names it: a lottery on Bordrless's lottery hook, or a
+ * jackpot or a streak on a game hook made in Studio (docs/games.md "Phase 2"), whose config the
+ * request's `config` must name (the kind's settings are the hook's constants: the timer and the
+ * minimum buy, the epoch, the minimum streak and weight; `ConfigInspection.game` shows them).
+ */
+export type GameRequest = LotteryRequest | JackpotRequest | StreakRequest;
+/** A jackpot coin's game as the launch request names it (`create_game_v2`): the pot's part, the minimum pot and what a settle pays; the timer and the minimum buy are the hook's. */
+export interface JackpotRequest {
+    kind: 'jackpot';
+    potBps: number;
+    /** A round is paid only while the pot holds at least this, lamports: 0.1 to 1,000 SOL (a round settled below it pays nothing). */
+    minPotLamports: Amount;
+    /** The part of the pot a settle pays the last buyer, basis points: 10% to 100%. */
+    prizeBps: number;
+}
+/** A streak coin's game as the launch request names it (`create_game_v2`): the pot's part, the minimum pot, what an epoch shares and the least a close leaves for claims; the epoch, the minimum streak and weight are the hook's. */
+export interface StreakRequest {
+    kind: 'streak';
+    potBps: number;
+    /** An epoch is closed only while the pot holds at least this, lamports: 0.1 to 1,000 SOL. */
+    minPotLamports: Amount;
+    /** The part of the pot an epoch shares among its holders, basis points: 10% to 100%. */
+    prizeBps: number;
+    /** The least a close leaves for claims, seconds: 5 minutes to a day, at most half an epoch. */
+    claimWindowSecs: 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`).
@@ -602,19 +639,28 @@ export interface LotteryRequest {
     /** 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. */
+/** A game coin's settings as its token page shows them (`CompanionSummary.game`): fixed at the launch, and the hook's terms. A jackpot's and a streak's kind settings (phase 2) are the hook's. */
 export interface GameSummary {
-    kind: 'lottery';
+    kind: GameKindName;
     /** 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). */
+    /** The coin's token hook, which keeps the tickets (the lottery hook, or a game hook made in Studio). */
     hook: Address;
+    /** A lottery's round, a streak's epoch; 0 for a jackpot. */
     roundSecs: number;
     potBps: number;
     minPot: Amount;
     prizeBps: number;
+    /** A lottery's claim attempt window, the least a streak's close leaves for claims; 0 for a jackpot. */
     claimWindowSecs: number;
+    /** A lottery's attempts per draw; 0 otherwise. */
     maxAttempts: number;
+    /** Jackpot: a round ends this long after its last qualifying buy, and the least a qualifying buy delivers (base units). Absent or 0 for the other kinds. */
+    timerSecs?: number;
+    minTokens?: Amount;
+    /** Streak: by an epoch's end a holding must have sent nothing for this long, and the least weight that shares (base units). Absent or 0 for the other kinds. */
+    minStreakSecs?: number;
+    minWeight?: Amount;
     /** The most the pot may hold while the hook is not audited (lamports); null for an audited hook. */
     potCap: Amount | null;
     audited: boolean;
@@ -660,8 +706,100 @@ export interface GameYou {
     odds: number | null;
     /** Its tickets in the round before (the one a draw may be for now). */
     previousTickets: Amount;
+    /** A jackpot (phase 2): the wallet's place in it. Absent for the other kinds. */
+    jackpot?: JackpotYou | null;
+    /** A streak (phase 2): the wallet's weight and share. Absent for the other kinds. */
+    streak?: StreakYou | null;
+}
+/** The caller's place in a jackpot (`GameYou.jackpot`). */
+export interface JackpotYou {
+    /** The number of the wallet's first qualifying buy since it last sent anything; '0' after any send (the mark). */
+    mark: Amount;
+    /** The wallet is the current round's last qualifying buyer. */
+    lastBuyer: boolean;
+    /** Among the rounds over and not settled, those this wallet would be paid for if settled now (it still holds what it bought). */
+    wins: number;
+}
+/** The caller's place in a streak (`GameYou.streak`). */
+export interface StreakYou {
+    /** The wallet's weight in the current epoch, base units ('0' until registered: `enter` registers it, a trade writes it). */
+    weight: Amount;
+    /** Whether a holding that sends nothing until the epoch's end will share (it has held long enough, at least the minimum weight). */
+    qualifies: boolean;
+    /** The claim epoch (the one open for claims): the wallet's weight in it and the share it can claim now, lamports; '0' after a claim or a send. */
+    claimWeight: Amount;
+    claimShare: Amount;
+    /** The wallet's receipt of the claim epoch exists: its share was paid. */
+    claimed: boolean;
+}
+/** A jackpot round as the status lists it (`JackpotStatus.open`, `JackpotStatus.rounds`): its number, buyer, the amount bought and when, and what became of it. */
+export interface JackpotRound {
+    /** The round's number: that of its last qualifying buy. */
+    number: number;
+    buyer: Address;
+    amount: Amount;
+    /** When its last qualifying buy landed (its timer ran out `timerSecs` later). */
+    boughtAt: number;
+    /** `open`: over, not settled yet; `paid`; `unfunded`: closed paying nothing (the pot below its minimum); `forfeited`: the buyer sold or sent, or can't be paid. */
+    status: 'open' | 'paid' | 'unfunded' | 'forfeited';
+    prize: Amount | null;
+    reason: 'notHeld' | 'unpayable' | 'stale' | null;
+    signature: string | null;
+    at: number | null;
+}
+/** A jackpot coin's live state (`GameStatus.jackpot`, docs/games.md "The jackpot"). */
+export interface JackpotStatus {
+    /** The current round's last qualifying buyer, what they bought and when; null before the first qualifying buy. */
+    lastBuyer: Address | null;
+    lastAmount: Amount;
+    lastBuyAt: number | null;
+    /** When the current round's timer runs out (the last buyer is paid if they still hold); null without a buy. */
+    timerEndsAt: number | null;
+    /** Qualifying buys so far (the current round's number), and the last round settled. */
+    buys: number;
+    paidBuys: number;
+    /** Buys count only while the coin is on its curve: once graduated, the jackpot ends (the round under way is still paid). */
+    onCurve: boolean;
+    /** Rounds over and not settled yet, oldest first (a keeper settles them within seconds). */
+    open: JackpotRound[];
+    /** Rounds settled, as the indexer saw them, newest first. */
+    rounds: JackpotRound[];
+}
+/** A streak epoch as the status lists it (`StreakStatus.epochs`): what the indexer saw of it. */
+export interface StreakEpoch {
+    epoch: number;
+    epochEndsAt: number;
+    /** `closed`: its pot fixed, claims open; `ended`: claims over; `rolledOver`: no pot (no weight, or closed too late). */
+    status: 'closed' | 'ended' | 'rolledOver';
+    /** Its weight total and its pot, lamports. */
+    total: Amount;
+    pot: Amount;
+    /** Paid out so far, lamports, and how many claims. */
+    paid: Amount;
+    claims: number;
+    signature: string | null;
+    at: number | null;
 }
-/** 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. */
+/** A streak coin's live state (`GameStatus.streak`, docs/games.md "The streak"). */
+export interface StreakStatus {
+    /** The claim epoch: the one whose claims are open, its pot, total, what it paid so far and when its claims end; null while none is open. */
+    claim: {
+        epoch: number;
+        pot: Amount;
+        total: Amount;
+        paid: Amount;
+        claimsEndAt: number;
+    } | null;
+    /** The epoch before the current one: over, not closed yet (a keeper closes it); null once closed or rolled over. */
+    closing: {
+        epoch: number;
+        total: Amount;
+        closeBy: number;
+    } | null;
+    /** Epochs closed, ended or rolled over, as the indexer saw them, newest first. */
+    epochs: StreakEpoch[];
+}
+/** A game coin's live state (`CompanionStatus.game`, docs/games.md): the pot, the round (a streak's epoch), the caller's place in it and the history. A lottery's draw and draws; a jackpot's and a streak's under their own names. */
 export interface GameStatus extends GameSummary {
     /** Bridged SOL the pot holds, lamports. */
     pot: Amount;
@@ -689,6 +827,21 @@ export interface GameStatus extends GameSummary {
     lastWinner: Address | null;
     you: GameYou | null;
     draws: GameDraw[];
+    /** A jackpot's live state (phase 2); absent or null for the other kinds. */
+    jackpot?: JackpotStatus | null;
+    /** A streak's live state (phase 2); absent or null for the other kinds. */
+    streak?: StreakStatus | null;
+}
+/** `POST /v1/game/claim/prepare`: a streak holder's own `claim_share` of the claim epoch (docs/games.md "The streak"): paid to the wallet, which pays its receipt's rent (back once the epoch's claims end, `close_receipt`). */
+export interface GameClaimRequest {
+    wallet: Address;
+    mint: Address;
+}
+export interface GameClaimResponse {
+    transactions: PreparedTx[];
+    /** The epoch claimed and the share it pays, lamports (before the sender's bounty, which is the wallet's own here). */
+    epoch: number;
+    share: Amount;
 }
 /** `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 {
@@ -1247,3 +1400,65 @@ export interface HookInspection {
     /** Why it can't be launched with yet, one sentence each. */
     problems: string[];
 }
+/** Trading wallets an account may have registered at once. */
+export declare const MAX_TRADING_WALLETS = 5;
+/** The header the account session travels in, browser → site proxy → backend. The same token serves Studio (`STUDIO_SESSION_HEADER`). */
+export declare const ACCOUNT_SESSION_HEADER = "x-studio-session";
+/** The message a wallet signs to sign in to Bordrless: no transaction, nothing moves. */
+export declare function accountSignInMessage(wallet: Address, nonce: string, issuedAt: string): string;
+/** The message a trading wallet signs to be registered under an account: proof the key exists and is held by whoever holds the account. */
+export declare function tradingWalletMessage(account: Address, publicKey: Address): string;
+export interface AccountSessionRequest {
+    wallet: Address;
+    /** The exact message signed (`accountSignInMessage`). */
+    message: string;
+    /** Base58 ed25519 signature of the message's UTF-8 bytes. */
+    signature: string;
+}
+export interface AccountSessionResponse {
+    token: string;
+    wallet: Address;
+    /** Unix seconds. */
+    expiresAt: number;
+}
+export interface AccountWallet {
+    publicKey: Address;
+    label: string;
+    /** Unix seconds. */
+    createdAt: number;
+    revokedAt: number | null;
+}
+export interface AccountWallets {
+    account: Address;
+    /** Active registrations, oldest first. */
+    wallets: AccountWallet[];
+    max: number;
+}
+export interface AccountWalletRegisterRequest {
+    publicKey: Address;
+    /** At most 32 characters. */
+    label: string;
+    /** Base58 ed25519 signature by `publicKey` of `tradingWalletMessage(account, publicKey)`. */
+    signature: string;
+}
+/** A plain SOL transfer out of a registered trading wallet (to the signup wallet, usually). */
+export interface AccountWithdrawPrepareRequest {
+    /** The trading wallet that pays and signs. */
+    wallet: Address;
+    to: Address;
+    lamports: Amount;
+}
+export interface AccountWithdrawPrepareResponse {
+    transactions: PreparedTx[];
+    /** The network fee the transfer pays, lamports. */
+    feeLamports: Amount;
+}
+export interface AccountWithdrawSendRequest {
+    /** Base64 of the signed transaction from `AccountWithdrawPrepareResponse`. */
+    transaction: string;
+}
+export interface AccountWithdrawSendResponse {
+    signature: string;
+    state: 'confirmed' | 'failed' | 'expired' | 'pending';
+    error: string | null;
+}

package/dist/api.js

@@ -7,3 +7,26 @@
 export const HOOK_ABOUT_CHARS = 280;
 /** The official summary's limits, in characters. */
 export const HOOK_SUMMARY_LIMITS = { title: 40, text: 320 };
+// ---- accounts and trading wallets --------------------------------------------------------------------
+//   POST /v1/account/session                 -> AccountSessionResponse        the signup wallet signs `accountSignInMessage`
+//   GET  /v1/account/wallets                  -> AccountWallets                the session's trading wallets (public keys only)
+//   POST /v1/account/wallets                  -> AccountWallets                register one; the trading wallet co-signs `tradingWalletMessage`
+//   POST /v1/account/wallets/:pubkey/revoke   -> AccountWallets
+//   POST /v1/account/withdraw/prepare         -> AccountWithdrawPrepareResponse a plain SOL transfer from a registered trading wallet
+//   POST /v1/account/withdraw/send            -> AccountWithdrawSendResponse    the signed transfer, sent and followed
+//
+// An account is a wallet: the one a visitor connected (their signup wallet), or, without one, a
+// trading wallet generated in their browser. Trading wallets are keypairs made and kept in the
+// browser; Bordrless stores their public keys and labels under the account, never a secret.
+/** Trading wallets an account may have registered at once. */
+export const MAX_TRADING_WALLETS = 5;
+/** The header the account session travels in, browser → site proxy → backend. The same token serves Studio (`STUDIO_SESSION_HEADER`). */
+export const ACCOUNT_SESSION_HEADER = 'x-studio-session';
+/** The message a wallet signs to sign in to Bordrless: no transaction, nothing moves. */
+export function accountSignInMessage(wallet, nonce, issuedAt) {
+    return ['Sign in to Bordrless', '', 'This signature proves you own this wallet. It does not move funds or approve any transaction.', '', `Wallet: ${wallet}`, `Nonce: ${nonce}`, `Issued: ${issuedAt}`].join('\n');
+}
+/** The message a trading wallet signs to be registered under an account: proof the key exists and is held by whoever holds the account. */
+export function tradingWalletMessage(account, publicKey) {
+    return ['Bordrless trading wallet', '', 'This wallet was generated in your browser for trading on Bordrless and belongs to the account below.', '', `Account: ${account}`, `Wallet: ${publicKey}`].join('\n');
+}

package/dist/policy.d.ts

@@ -6,7 +6,8 @@
  * `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, GameRolloverReason, LaunchRules, LaunchRulesInput, LotteryRequest, Side } from './api.ts';
+import type { CompanionSplitBps, CompanionTemplate, GameKindName, GameRequest, GameRolloverReason, JackpotRequest, LaunchRules, LaunchRulesInput, LotteryRequest, Side, StreakRequest } from './api.ts';
+import type { StudioGameSettings } from './studio.ts';
 export declare const BPS = 10000n;
 export declare const WAD: bigint;
 /** The largest u64, where the programs' checked arithmetic stops. */
@@ -347,6 +348,56 @@ export declare const LOTTERY_COPY: {
     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.";
 };
+/** The jackpot's timer and the streak's minimum streak: the companion's bounds (`GAME_LIMITS` in the SDK). */
+export declare const GAME_KIND_LIMITS: {
+    readonly minTimerSecs: 300;
+    readonly maxTimerSecs: number;
+    readonly maxMinStreakSecs: number;
+};
+/** A jackpot as the launch form starts it (spec example 2, `JACKPOT_DEFAULTS` in the SDK): 70% of the fee to the pot, 30% bought back, half the pot to the last buyer from 0.5 SOL. */
+export declare const JACKPOT_REQUEST_DEFAULTS: Readonly<JackpotRequest>;
+/** A streak as the launch form starts it (spec example 3, `STREAK_DEFAULTS` in the SDK): 70% of the fee to the pot, 30% bought back, the whole pot shared each epoch from 0.1 SOL, an hour at least for claims. */
+export declare const STREAK_REQUEST_DEFAULTS: Readonly<StreakRequest>;
+/** The least a streak's close leaves for claims, as the form offers it (seconds); each must fit half the hook's epoch. */
+export declare const STREAK_CLAIM_WINDOW_CHOICES: readonly {
+    secs: number;
+    label: string;
+}[];
+/** The game a launch request's `companion.game` names, of any kind, each field a whole number; null when malformed (bounds are `gameProblem`'s). */
+export declare function gameRequestOf(raw: unknown): GameRequest | null;
+/**
+ * Why `create_game_v2` (or the launch) would refuse this game with this split on these rules at
+ * this fee, with `hook` the Studio game hook the config names (`ConfigInspection.game`; null: the
+ * config names none), in one sentence; null when it would not. A lottery is `lotteryProblem`'s.
+ * The program's own checks (`gameArgsProblem` in the SDK, the same sentences) and what a game
+ * coin's launch needs besides: a creator fee, no token rules, no holders' share, and a hook of the
+ * game's kind.
+ */
+export declare function gameProblem(game: GameRequest, split: CompanionSplitBps, rules: LaunchRulesInput, creatorFeeBps: number, hook?: StudioGameSettings | null): string | null;
+/** Each game kind in a word: "jackpot". */
+export declare const GAME_KIND_NAMES: Readonly<Record<GameKindName, string>>;
+/**
+ * The copy rules of a jackpot and a streak coin (docs/games.md "Phase 2", "Site"): said on the
+ * launch form, the review step and the token page. The pot is held by the companion and paid by
+ * code (no randomness in either kind), the 10 SOL cap until the hook is audited, "Bordrless can
+ * stop this game"; never "provably fair", "guaranteed" or "audited".
+ */
+export declare const JACKPOT_COPY: {
+    readonly held: "The pot is held by the companion program and paid out by code. No randomness: the last buyer wins.";
+    readonly rule: "The last buyer wins if they keep every token they bought: any sale or transfer forfeits.";
+    readonly unfunded: "If the pot is below its minimum when a round is settled, the round pays nothing and the pot carries on.";
+    readonly curve: "Buys count while the coin is on its curve: the jackpot ends at graduation (the round under way is still paid).";
+    readonly cap: "Pot capped at 10 SOL until the game’s hook is audited.";
+    readonly stop: "Bordrless can stop this game: its pot would be bought back and burned. Nobody is paid.";
+};
+export declare const STREAK_COPY: {
+    readonly held: "The pot is held by the companion program and paid out by code. No randomness: holders share in proportion to what they held.";
+    readonly rule: "Send anything, to anyone, and you lose this epoch’s and last epoch’s share. Claim before you sell.";
+    readonly weight: "Your weight is what you held since the epoch began: tokens that arrive during an epoch count from the next.";
+    readonly claims: "Shares are claimed during the next epoch; the keeper claims for everyone whose share covers the fee, the rest claim here. What is not claimed rolls over.";
+    readonly cap: "Pot capped at 10 SOL until the game’s hook is audited.";
+    readonly stop: "Bordrless can stop this game: its pot would be bought back and burned. Nobody is paid.";
+};
 /** 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). */

package/dist/policy.js

@@ -471,6 +471,110 @@ export const LOTTERY_COPY = {
     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.',
 };
+// ---- jackpot and streak coins (docs/games.md "Phase 2"), on game hooks made in Studio -----------------
+/** The jackpot's timer and the streak's minimum streak: the companion's bounds (`GAME_LIMITS` in the SDK). */
+export const GAME_KIND_LIMITS = { minTimerSecs: 300, maxTimerSecs: 30 * DAY_SECS, maxMinStreakSecs: 365 * DAY_SECS };
+/** A jackpot as the launch form starts it (spec example 2, `JACKPOT_DEFAULTS` in the SDK): 70% of the fee to the pot, 30% bought back, half the pot to the last buyer from 0.5 SOL. */
+export const JACKPOT_REQUEST_DEFAULTS = { kind: 'jackpot', potBps: 7_000, minPotLamports: '500000000', prizeBps: 5_000 };
+/** A streak as the launch form starts it (spec example 3, `STREAK_DEFAULTS` in the SDK): 70% of the fee to the pot, 30% bought back, the whole pot shared each epoch from 0.1 SOL, an hour at least for claims. */
+export const STREAK_REQUEST_DEFAULTS = { kind: 'streak', potBps: 7_000, minPotLamports: '100000000', prizeBps: 10_000, claimWindowSecs: 3_600 };
+/** The least a streak's close leaves for claims, as the form offers it (seconds); each must fit half the hook's epoch. */
+export const STREAK_CLAIM_WINDOW_CHOICES = [
+    { secs: 1_800, label: '30 min' },
+    { secs: 3_600, label: '1 hour' },
+    { secs: 21_600, label: '6 hours' },
+    { secs: DAY_SECS, label: '1 day' },
+];
+/** The game a launch request's `companion.game` names, of any kind, each field a whole number; null when malformed (bounds are `gameProblem`'s). */
+export function gameRequestOf(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const r = raw;
+    if (r.kind === 'lottery')
+        return lotteryRequestOf(raw);
+    if (r.kind !== 'jackpot' && r.kind !== 'streak')
+        return null;
+    if (!isWhole(r.potBps, 0, 10_000) || !isWhole(r.prizeBps, 0, 10_000))
+        return null;
+    if (typeof r.minPotLamports !== 'string' || !/^\d{1,20}$/.test(r.minPotLamports))
+        return null;
+    if (r.kind === 'jackpot')
+        return { kind: 'jackpot', potBps: r.potBps, minPotLamports: r.minPotLamports, prizeBps: r.prizeBps };
+    if (!isWhole(r.claimWindowSecs, 0, 2 ** 32 - 1))
+        return null;
+    return { kind: 'streak', potBps: r.potBps, minPotLamports: r.minPotLamports, prizeBps: r.prizeBps, claimWindowSecs: r.claimWindowSecs };
+}
+/**
+ * Why `create_game_v2` (or the launch) would refuse this game with this split on these rules at
+ * this fee, with `hook` the Studio game hook the config names (`ConfigInspection.game`; null: the
+ * config names none), in one sentence; null when it would not. A lottery is `lotteryProblem`'s.
+ * The program's own checks (`gameArgsProblem` in the SDK, the same sentences) and what a game
+ * coin's launch needs besides: a creator fee, no token rules, no holders' share, and a hook of the
+ * game's kind.
+ */
+export function gameProblem(game, split, rules, creatorFeeBps, hook = null) {
+    if (game.kind === 'lottery')
+        return lotteryProblem(game, split, rules, creatorFeeBps);
+    const L = LOTTERY_LIMITS;
+    const word = GAME_KIND_NAMES[game.kind];
+    if (!hook)
+        return `A ${word} coin launches from a game hook made in Studio: open your ${word} project there and press Launch with it.`;
+    if (hook.kind !== game.kind)
+        return `This config’s hook keeps a ${GAME_KIND_NAMES[hook.kind]}’s score, not a ${word}’s.`;
+    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 ${word} coin has no other token rules: its hook keeps the score.`;
+    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.';
+    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 game pays 10% to 100% of the pot at a time.';
+    if (game.kind === 'jackpot') {
+        if (hook.timerSecs < GAME_KIND_LIMITS.minTimerSecs || hook.timerSecs > GAME_KIND_LIMITS.maxTimerSecs)
+            return 'A jackpot’s timer lasts 5 minutes to 30 days.';
+        if (BigInt(hook.minTokens) < 1n)
+            return 'A qualifying buy is at least one base unit.';
+        return null;
+    }
+    if (hook.roundSecs < L.minRoundSecs || hook.roundSecs > L.maxRoundSecs)
+        return 'An epoch lasts an hour to 30 days.';
+    if (game.claimWindowSecs < L.minClaimWindowSecs || game.claimWindowSecs > L.maxClaimWindowSecs || game.claimWindowSecs * L.claimsPerRound > hook.roundSecs)
+        return 'A streak leaves claims 5 minutes to a day, at most half an epoch.';
+    if (hook.minStreakSecs > GAME_KIND_LIMITS.maxMinStreakSecs)
+        return 'A streak asks at most a year without sending.';
+    if (BigInt(hook.minWeight) < 1n)
+        return 'The least weight that shares is at least one base unit.';
+    return null;
+}
+/** Each game kind in a word: "jackpot". */
+export const GAME_KIND_NAMES = { lottery: 'lottery', jackpot: 'jackpot', streak: 'streak', strategy: 'strategy' };
+/**
+ * The copy rules of a jackpot and a streak coin (docs/games.md "Phase 2", "Site"): said on the
+ * launch form, the review step and the token page. The pot is held by the companion and paid by
+ * code (no randomness in either kind), the 10 SOL cap until the hook is audited, "Bordrless can
+ * stop this game"; never "provably fair", "guaranteed" or "audited".
+ */
+export const JACKPOT_COPY = {
+    held: 'The pot is held by the companion program and paid out by code. No randomness: the last buyer wins.',
+    rule: 'The last buyer wins if they keep every token they bought: any sale or transfer forfeits.',
+    unfunded: 'If the pot is below its minimum when a round is settled, the round pays nothing and the pot carries on.',
+    curve: 'Buys count while the coin is on its curve: the jackpot ends at graduation (the round under way is still paid).',
+    cap: LOTTERY_COPY.cap,
+    stop: LOTTERY_COPY.stop,
+};
+export const STREAK_COPY = {
+    held: 'The pot is held by the companion program and paid out by code. No randomness: holders share in proportion to what they held.',
+    rule: 'Send anything, to anyone, and you lose this epoch’s and last epoch’s share. Claim before you sell.',
+    weight: 'Your weight is what you held since the epoch began: tokens that arrive during an epoch count from the next.',
+    claims: 'Shares are claimed during the next epoch; the keeper claims for everyone whose share covers the fee, the rest claim here. What is not claimed rolls over.',
+    cap: LOTTERY_COPY.cap,
+    stop: LOTTERY_COPY.stop,
+};
 /** Why a round paid no prize, in a few words each (`GameRolloverReason`). */
 export const ROLLOVER_WORDS = {
     noTickets: 'Nobody held tickets',

package/dist/programs.d.ts

@@ -22,7 +22,25 @@ export declare const PROGRAM_IDS: {
      * (2026-10-08): companion v2 and this hook go live together, after their audit.
      */
     readonly lotteryHook: "HqFWsCBQ416DAfevJ9TspyT5yXGGoYTCpcreiGkCgWcr";
+    /**
+     * `hook_timelock` (phase 3a, bordrless-programs docs/phase3a.md §3): a hook's or a strategy's
+     * upgrade authority behind a public delay of at least 3 days; its only exit is "immutable". Not
+     * deployed yet (2026-10-09).
+     */
+    readonly hookTimelock: "BBUzaamchPWZpKENmn7bopiuQWvRGm2Vg8TqLLgzgGGZ";
+    /**
+     * `hook_vault` (phase 3a, §5): where a hook's cuts go, each slot with a policy fixed before the
+     * launch (burn, sell for SOL to a fixed wallet, sell and buy-and-burn another token), run by a
+     * permissionless crank under the companion's buyback guards. Not deployed yet (2026-10-09).
+     */
+    readonly hookVault: "5cojoUStG7WFhHJiSncCUEwTqDuhDLKu4a9BqTbF8jzG";
 };
+/**
+ * Bordrless Studio's attester (phase 3a, docs/phase3a.md §6): a hot key of Studio's build worker,
+ * the only signer of the companion's `HookAttestation` ("Bordrless rebuilt this source, its hash is
+ * the code on chain, the checks, the simulator and the review passed"). Not Studio's upgrade key.
+ */
+export declare const STUDIO_ATTESTER = "3uGLsTJNse7vE3pgRkAf6aKKBoKmCyPUcNNu1bw3KvP2";
 /**
  * The lottery hook's fixed facts (programs/lottery_hook/README.md): the flags a `LaunchConfig`
  * names for it (`BEFORE_TRANSFER | BEFORE_BURN | WRITES_HOOK_DATA`, exactly what a companion game

package/dist/programs.js

@@ -22,7 +22,25 @@ export const PROGRAM_IDS = {
      * (2026-10-08): companion v2 and this hook go live together, after their audit.
      */
     lotteryHook: 'HqFWsCBQ416DAfevJ9TspyT5yXGGoYTCpcreiGkCgWcr',
+    /**
+     * `hook_timelock` (phase 3a, bordrless-programs docs/phase3a.md §3): a hook's or a strategy's
+     * upgrade authority behind a public delay of at least 3 days; its only exit is "immutable". Not
+     * deployed yet (2026-10-09).
+     */
+    hookTimelock: 'BBUzaamchPWZpKENmn7bopiuQWvRGm2Vg8TqLLgzgGGZ',
+    /**
+     * `hook_vault` (phase 3a, §5): where a hook's cuts go, each slot with a policy fixed before the
+     * launch (burn, sell for SOL to a fixed wallet, sell and buy-and-burn another token), run by a
+     * permissionless crank under the companion's buyback guards. Not deployed yet (2026-10-09).
+     */
+    hookVault: '5cojoUStG7WFhHJiSncCUEwTqDuhDLKu4a9BqTbF8jzG',
 };
+/**
+ * Bordrless Studio's attester (phase 3a, docs/phase3a.md §6): a hot key of Studio's build worker,
+ * the only signer of the companion's `HookAttestation` ("Bordrless rebuilt this source, its hash is
+ * the code on chain, the checks, the simulator and the review passed"). Not Studio's upgrade key.
+ */
+export const STUDIO_ATTESTER = '3uGLsTJNse7vE3pgRkAf6aKKBoKmCyPUcNNu1bw3KvP2';
 /**
  * The lottery hook's fixed facts (programs/lottery_hook/README.md): the flags a `LaunchConfig`
  * names for it (`BEFORE_TRANSFER | BEFORE_BURN | WRITES_HOOK_DATA`, exactly what a companion game

package/dist/studio.d.ts

@@ -20,8 +20,65 @@ export interface StudioFile {
     path: string;
     content: string;
 }
-/** What a project becomes: a config of existing rules alone, or a config with its own hook program. */
+/**
+ * What a project becomes: a config of existing rules alone, or a config with its own hook program.
+ * A hook project whose state starts with the game ticket standard's header is a game hook
+ * (docs/games.md "Phase 2"): read from its source (`detectGameSettings`), never chosen, and its
+ * config launches a jackpot, streak or lottery coin through the companion.
+ */
 export type StudioKind = 'config' | 'hook';
+/** The kinds of game a game hook keeps the score of (the companion's `GameKind`). */
+export type StudioGameKind = 'lottery' | 'jackpot' | 'streak';
+export declare const STUDIO_GAME_KINDS: readonly StudioGameKind[];
+/**
+ * A game hook's companion draft (docs/games.md "The companion's game", phase 2): what the launch
+ * fixes with `create_game_v2` besides the hook's own constants. The split with the pot: the pot's
+ * part and the buyback's, the launcher's what is left (no holders' part: a game coin has no kit).
+ * The kind's settings (the timer, the minimum buy; the epoch, the minimum streak and weight; a
+ * lottery's rounds) are the hook's constants, read from its source (`detectGameSettings`), never
+ * typed: the companion checks them against the hook's kind header.
+ */
+export interface StudioGameDraft {
+    potBps: number;
+    buybackBps: number;
+    /** No settle, close or draw while the pot holds less: 0.1 to 1,000 SOL. */
+    minPotLamports: string;
+    /** The part of the pot a settle, an epoch or a draw pays: 10% to 100%. */
+    prizeBps: number;
+    /** Streak: the least a close leaves for claims (5 minutes to a day, at most half an epoch); lottery: each attempt's window; 0 for a jackpot. */
+    claimWindowSecs: number;
+    /** Lottery only: attempts per draw (1 to 16); 0 otherwise. */
+    maxAttempts: number;
+}
+/**
+ * A game hook's kind and settings as its source fixes them (p2-n: the starters' settings are their
+ * code's): the state struct's first field is the crate's `GameHeader`, its second the kind header
+ * (`JackpotHeader` / `StreakHeader`; neither: a lottery), and the settings are what the headers are
+ * made with (`JackpotHeader::new(timer, min_tokens)`, `StreakHeader::new(min_streak, min_weight)`,
+ * `GameHeader::new(mint, round_secs, now)`). Amounts are base units as strings.
+ */
+export interface StudioGameSettings {
+    kind: StudioGameKind;
+    /** Jackpot: a round ends this long after its last qualifying buy. 0 otherwise. */
+    timerSecs: number;
+    /** Jackpot: the least a qualifying buy delivers. '0' otherwise. */
+    minTokens: string;
+    /** Streak: the epoch; lottery: the round. 0 for a jackpot. */
+    roundSecs: number;
+    /** Streak: by an epoch's end a holding must have sent nothing for this long. 0 otherwise. */
+    minStreakSecs: number;
+    /** Streak: the least weight that shares. '0' otherwise. */
+    minWeight: string;
+}
+/** The hook flags every game hook runs on: `BEFORE_TRANSFER | BEFORE_BURN | WRITES_HOOK_DATA` (`GameKind::hook_flags`, 145), the only set the companion's launch accepts. */
+export declare const GAME_HOOK_FLAGS = 145;
+/**
+ * The companion draft a game hook starts with (the docs' examples: 70% of the fee to the pot, 30%
+ * bought back; a jackpot paying half the pot from 0.5 SOL; a streak sharing the whole pot from 0.1
+ * SOL with an hour at least for claims; a lottery paying the whole pot from 0.5 SOL, 8 attempts of
+ * 10 minutes).
+ */
+export declare function gameDraftDefaults(kind: StudioGameKind): StudioGameDraft;
 /** The launch config a project makes (the arguments of `create_config` / `create_listed_config`). */
 export interface StudioConfigDraft {
     /** At most 32 bytes. */
@@ -38,8 +95,10 @@ export interface StudioConfigDraft {
     earlyLockSecs: number;
     /** `TOKEN_HOOK_FLAGS` the hook runs on, for a `hook` project; 0 for a `config` project. */
     hookFlags: number;
-    /** List it on the marketplace (made with `create_listed_config`). */
+    /** List it on the marketplace (made with `create_listed_config`). Never for a game hook: the companion refuses a config that pays an author. */
     listed: boolean;
+    /** A game hook's companion draft (the split with the pot, the minimum pot, the prize, the claim window); null or absent otherwise. The backend fills it with the kind's defaults when the source becomes a game hook. */
+    game?: StudioGameDraft | null;
     /**
      * The author's share of the creator fee on others' launches, bps of it. Not the author's to choose:
      * the backend holds it at `AUTHOR_SHARE_BPS` when listed and 0 when not, whatever is sent.
@@ -65,6 +124,12 @@ export interface StudioProject extends StudioProjectSummary {
     description: string;
     files: StudioFile[];
     draft: StudioConfigDraft;
+    /**
+     * A hook project's game, as its source reads (`detectGameSettings`): its kind and the constants
+     * the companion will check against the hook's kind header. Null when the source is not a game
+     * hook (no `GameHeader` state, or settings that can't be read); absent for a config project.
+     */
+    game?: StudioGameSettings | null;
     /** The last review of the current source; null when the source changed since. */
     review: StudioReview | null;
     /** The last build of the current source; null when the source changed since. */
@@ -75,7 +140,7 @@ export interface StudioProject extends StudioProjectSummary {
 export interface StudioProjectCreateRequest {
     name: string;
     kind: StudioKind;
-    /** Start from a template (`STUDIO_STARTERS`), or blank. */
+    /** Start from a template (`STUDIO_STARTERS`), or blank; the game starters make a game hook. */
     starter?: string;
 }
 /** A save: any of the fields; files replace the whole set. Changing files drops the review and the build. */
@@ -203,6 +268,12 @@ export interface StudioBuild {
     at: number;
     /** Studio's trading test of what was built (the worker's simulator): a deploy needs `pass`. Absent on builds from before it. */
     sim?: StudioSim | null;
+    /**
+     * The Studio template's commit the worker built against (40 hex characters; the worker's
+     * `STUDIO_TEMPLATE_COMMIT`). Studio's attestation records it, so anyone can rebuild the hook.
+     * Absent on builds from before it, or from a worker that does not report it.
+     */
+    templateCommit?: string | null;
 }
 /** The simulator's verdict on a build: launched, bought, sold and sent by several wallets over a simulated year. */
 export interface StudioSim {
@@ -214,8 +285,23 @@ export interface StudioSim {
     capBps: number | null;
     /** Operations the hook refused. */
     refusedTotal: number;
+    /** The simulator's version (recorded in Studio's attestation); absent from workers that don't report it. */
+    version?: number | null;
     /** What the test can't see (amount triggers, wallets it never used, after a year). */
     notes: string[];
+    /** A game hook's scenarios (the jackpot's or the streak's, docs/games-handover.md phase 2 item 4): absent on a hook that is not a game's, or on builds from before them. */
+    game?: StudioSimGame | null;
+}
+/** The simulator's game scenarios on a game hook: the header and the marks or weights checked against a plain model of the rules, and the fairness of the payouts the rules would make. */
+export interface StudioSimGame {
+    kind: StudioGameKind;
+    pass: boolean;
+    /** Each check that failed, in the simulator's words (the first few). */
+    failed: string[];
+    /** Rounds (a jackpot) or epochs (a streak) the scenario ran. */
+    periods: number;
+    /** The largest difference between a wallet's share of the payouts and its share of what it held, in bps, over the fairness run; null when it did not run. */
+    fairnessMaxBps: number | null;
 }
 /** `POST /v1/studio/projects/:id/deploy/quote`: what deploying the built hook costs, in lamports. */
 export interface StudioDeployQuote {
@@ -364,8 +450,10 @@ export declare const HOOK_AUTHORITY_CODE = "hook_upgrade_authority";
 export declare const hookFinalCommand: (program?: string) => string;
 /**
  * The launch program's rule for a config's own hook (`create_config`, docs/hooks-v2.md §5.8), on its
- * upgrade info: accepted when nobody can upgrade it (`upgradeable: false`), or when its upgrade
- * authority is one of `HOOK_UPGRADE_AUTHORITIES` (Bordrless Studio's key or the protocol's). Only a
+ * upgrade info: accepted when nobody can upgrade it (`upgradeable: false`), when its upgrade
+ * authority is one of `HOOK_UPGRADE_AUTHORITIES` (Bordrless Studio's key or the protocol's), or when
+ * it is its own `hook_timelock` account (`timelocked`, phase 3a: the caller derives
+ * `PDA(["timelock", hook], hook_timelock)` and compares; the launch program also checks the delay). Only a
  * hook some other key is known to be able to upgrade is refused: one whose upgrade info could not be
  * read is not (the launch program checked it when the config was made; the SDK's
  * `hookAuthorityProblem` and the marketplace watch read it the same way). A config without a hook
@@ -374,6 +462,7 @@ export declare const hookFinalCommand: (program?: string) => string;
 export declare function hookAuthorityAccepted(customHook: string | null, hook: {
     upgradeAuthority: string | null;
     upgradeable: boolean | null;
+    timelocked?: boolean;
 } | null): boolean;
 /** `bordrless_launch::constants::MAX_AUTHOR_SHARE_BPS`: half the creator fee, the most the program lets a listed config pay its author. */
 export declare const MAX_AUTHOR_SHARE_BPS = 5000;
@@ -400,12 +489,20 @@ export declare const STUDIO_LIMITS: {
     readonly bytes: 120000;
     readonly messageChars: 8000;
 };
-/** Starters a new hook project can begin from (the template's `src/lib.rs` variants). */
+/**
+ * Starters a new hook project can begin from (the template's `src/lib.rs` variants). Those with
+ * `game` make a game hook (the reference game hooks of docs/games.md "Studio game hooks", written on
+ * the `bordrless-game` crate). A Studio lottery starter is not written yet (it would be
+ * `lottery_hook`'s rules with the standard `prepare` and `ROUND_SECS` as a constant).
+ */
 export declare const STUDIO_STARTERS: readonly {
     id: string;
     name: string;
     blurb: string;
+    game?: StudioGameKind;
 }[];
+/** What each game kind is called on the site: "Jackpot coin". */
+export declare const GAME_KIND_WORDS: Readonly<Record<StudioGameKind | 'strategy', string>>;
 /**
  * The token hook flags a Studio hook needs, read from its own source (never chosen by hand): each
  * callback whose body the author changed from the template's stub; cuts (TRANSFER_RETURNS_DELTA)
@@ -419,3 +516,17 @@ export declare function detectHookFlags(files: readonly {
     path: string;
     content: string;
 }[]): number;
+/**
+ * A game hook's kind and settings from its source (docs/games.md "Studio game hooks", p2-n):
+ * the state struct whose first field is the crate's `GameHeader` names the kind by its second
+ * field (`JackpotHeader`, `StreakHeader`; neither: a lottery), and the settings are the arguments
+ * the headers are made with in `prepare`: `JackpotHeader::new(timer_secs, min_tokens)`,
+ * `StreakHeader::new(min_streak_secs, min_weight)` and `GameHeader::new(mint, round_secs, now)`,
+ * each a constant expression (`const` names followed). Null when the source is not a game hook, or
+ * a setting can't be read from it (the backend then refuses the config: the companion would check
+ * the setting against the hook's header and refuse the setup).
+ */
+export declare function detectGameSettings(files: readonly {
+    path: string;
+    content: string;
+}[]): StudioGameSettings | null;

package/dist/studio.js

@@ -1,4 +1,20 @@
 import { TOKEN_HOOK_FLAGS as HOOK_FLAG_BITS } from "./programs.js";
+export const STUDIO_GAME_KINDS = ['lottery', 'jackpot', 'streak'];
+/** The hook flags every game hook runs on: `BEFORE_TRANSFER | BEFORE_BURN | WRITES_HOOK_DATA` (`GameKind::hook_flags`, 145), the only set the companion's launch accepts. */
+export const GAME_HOOK_FLAGS = 145;
+/**
+ * The companion draft a game hook starts with (the docs' examples: 70% of the fee to the pot, 30%
+ * bought back; a jackpot paying half the pot from 0.5 SOL; a streak sharing the whole pot from 0.1
+ * SOL with an hour at least for claims; a lottery paying the whole pot from 0.5 SOL, 8 attempts of
+ * 10 minutes).
+ */
+export function gameDraftDefaults(kind) {
+    if (kind === 'jackpot')
+        return { potBps: 7_000, buybackBps: 3_000, minPotLamports: '500000000', prizeBps: 5_000, claimWindowSecs: 0, maxAttempts: 0 };
+    if (kind === 'streak')
+        return { potBps: 7_000, buybackBps: 3_000, minPotLamports: '100000000', prizeBps: 10_000, claimWindowSecs: 3_600, maxAttempts: 0 };
+    return { potBps: 7_000, buybackBps: 3_000, minPotLamports: '500000000', prizeBps: 10_000, claimWindowSecs: 600, maxAttempts: 8 };
+}
 /** The message a wallet signs to use Studio: no transaction, nothing moves. */
 export function studioSignInMessage(wallet, nonce, issuedAt) {
     return ['Sign in to Bordrless Studio', '', 'This signature proves you own this wallet. It does not move funds or approve any transaction.', '', `Wallet: ${wallet}`, `Nonce: ${nonce}`, `Issued: ${issuedAt}`].join('\n');
@@ -23,8 +39,10 @@ export const HOOK_AUTHORITY_CODE = 'hook_upgrade_authority';
 export const hookFinalCommand = (program = '<PROGRAM_ID>') => `solana program set-upgrade-authority ${program} --final`;
 /**
  * The launch program's rule for a config's own hook (`create_config`, docs/hooks-v2.md §5.8), on its
- * upgrade info: accepted when nobody can upgrade it (`upgradeable: false`), or when its upgrade
- * authority is one of `HOOK_UPGRADE_AUTHORITIES` (Bordrless Studio's key or the protocol's). Only a
+ * upgrade info: accepted when nobody can upgrade it (`upgradeable: false`), when its upgrade
+ * authority is one of `HOOK_UPGRADE_AUTHORITIES` (Bordrless Studio's key or the protocol's), or when
+ * it is its own `hook_timelock` account (`timelocked`, phase 3a: the caller derives
+ * `PDA(["timelock", hook], hook_timelock)` and compares; the launch program also checks the delay). Only a
  * hook some other key is known to be able to upgrade is refused: one whose upgrade info could not be
  * read is not (the launch program checked it when the config was made; the SDK's
  * `hookAuthorityProblem` and the marketplace watch read it the same way). A config without a hook
@@ -33,6 +51,9 @@ export const hookFinalCommand = (program = '<PROGRAM_ID>') => `solana program se
 export function hookAuthorityAccepted(customHook, hook) {
     if (customHook === null || hook === null || hook.upgradeable !== true || hook.upgradeAuthority === null)
         return true;
+    // Phase 3a: a hook behind its own `hook_timelock` (a public delay of at least 3 days) is accepted too.
+    if (hook.timelocked === true)
+        return true;
     return HOOK_UPGRADE_AUTHORITIES.includes(hook.upgradeAuthority);
 }
 /** `bordrless_launch::constants::MAX_AUTHOR_SHARE_BPS`: half the creator fee, the most the program lets a listed config pay its author. */
@@ -53,12 +74,21 @@ export const AUTHOR_SHARE_BPS = 5_000;
 export const STUDIO_PREPARE = { instruction: 'prepare', stateSeed: 'state' };
 /** Limits of a project's source. */
 export const STUDIO_LIMITS = { files: 8, bytes: 120_000, messageChars: 8_000 };
-/** Starters a new hook project can begin from (the template's `src/lib.rs` variants). */
+/**
+ * Starters a new hook project can begin from (the template's `src/lib.rs` variants). Those with
+ * `game` make a game hook (the reference game hooks of docs/games.md "Studio game hooks", written on
+ * the `bordrless-game` crate). A Studio lottery starter is not written yet (it would be
+ * `lottery_hook`'s rules with the standard `prepare` and `ROUND_SECS` as a constant).
+ */
 export const STUDIO_STARTERS = [
     { id: 'blank', name: 'Blank hook', blurb: 'The template: every callback stubbed, nothing taken, nothing refused.' },
     { id: 'sell-tax', name: 'Sell tax to a wallet', blurb: 'A cut of every sell sent to a wallet you choose; buys and transfers pass free.' },
     { id: 'cooldown', name: 'Transfer cooldown', blurb: 'A holding that received tokens cannot send them on for a while, stamped in its hook data.' },
+    { id: 'jackpot', game: 'jackpot', name: 'Last-buyer jackpot', blurb: 'Every buy of at least MIN_TOKENS restarts a TIMER_SECS countdown; when it runs out, the last buyer who still holds is paid a share of the pot.' },
+    { id: 'streak', game: 'streak', name: 'Diamond-hands streak', blurb: 'Each epoch, part of the pot is shared among the holders who held through it without sending a token, in proportion to what they held.' },
 ];
+/** What each game kind is called on the site: "Jackpot coin". */
+export const GAME_KIND_WORDS = { lottery: 'Lottery coin', jackpot: 'Jackpot coin', streak: 'Streak coin', strategy: 'Strategy coin' };
 // ---- the hook's flags, read from its source ---------------------------------------------------------
 /** Comments, string and char literals blanked (newlines kept), so only code is read. */
 function codeOnly(src) {
@@ -168,3 +198,169 @@ export function detectHookFlags(files) {
         flags |= HOOK_FLAG_BITS.WRITES_HOOK_DATA;
     return flags;
 }
+// ---- a game hook's kind and settings, read from its source --------------------------------------------
+/** The index just past the bracket matching the one at `open`, or the end. */
+function closeOf(code, open) {
+    let depth = 0;
+    for (let j = open; j < code.length; j += 1) {
+        const ch = code[j];
+        if (ch === '(' || ch === '[' || ch === '{')
+            depth += 1;
+        else if (ch === ')' || ch === ']' || ch === '}') {
+            depth -= 1;
+            if (depth === 0)
+                return j + 1;
+        }
+    }
+    return code.length;
+}
+/** The arguments of the call whose opening parenthesis is at `open`, as written (split on commas at depth 0). */
+function argsOf(code, open) {
+    const inner = code.slice(open + 1, closeOf(code, open) - 1);
+    const out = [];
+    let depth = 0;
+    let from = 0;
+    for (let j = 0; j < inner.length; j += 1) {
+        const ch = inner[j];
+        if (ch === '(' || ch === '[' || ch === '{')
+            depth += 1;
+        else if (ch === ')' || ch === ']' || ch === '}')
+            depth -= 1;
+        else if (ch === ',' && depth === 0) {
+            out.push(inner.slice(from, j));
+            from = j + 1;
+        }
+    }
+    if (inner.slice(from).trim())
+        out.push(inner.slice(from));
+    return out.map((a) => a.trim());
+}
+/**
+ * A constant expression of the source, evaluated: integer literals (with `_` and a type suffix),
+ * `+ - * /` and parentheses, and the names of other `const`s (followed up to a depth of 8). Null
+ * for anything else (a call, a runtime value, an unknown name, a division by zero).
+ */
+function evalConst(code, expr, depth = 0) {
+    const text = expr.replace(/\s+/g, '');
+    if (!text || depth > 8)
+        return null;
+    let i = 0;
+    const peek = () => text[i] ?? '';
+    const primary = () => {
+        if (peek() === '(') {
+            i += 1;
+            const v = sum();
+            if (peek() !== ')')
+                return null;
+            i += 1;
+            return v;
+        }
+        if (peek() === '-') {
+            i += 1;
+            const v = primary();
+            return v === null ? null : -v;
+        }
+        const lit = /^(0x[0-9a-fA-F_]+|\d[\d_]*)(u8|u16|u32|u64|u128|i8|i16|i32|i64|i128|usize|isize)?/.exec(text.slice(i));
+        if (lit) {
+            i += lit[0].length;
+            try {
+                return BigInt(lit[1].replace(/_/g, ''));
+            }
+            catch {
+                return null;
+            }
+        }
+        const name = /^(?:(?:crate|self|super)::)*([A-Za-z_][A-Za-z0-9_]*)/.exec(text.slice(i));
+        if (!name)
+            return null;
+        i += name[0].length;
+        const def = new RegExp(`\\bconst\\s+${name[1]}\\s*:\\s*[A-Za-z0-9_:<>]+\\s*=([^;]*);`).exec(code);
+        if (!def)
+            return null;
+        return evalConst(code, def[1], depth + 1);
+    };
+    const product = () => {
+        let v = primary();
+        while (v !== null && (peek() === '*' || peek() === '/')) {
+            const op = peek();
+            i += 1;
+            const r = primary();
+            if (r === null)
+                return null;
+            if (op === '/') {
+                if (r === 0n)
+                    return null;
+                v /= r;
+            }
+            else
+                v *= r;
+        }
+        return v;
+    };
+    const sum = () => {
+        let v = product();
+        while (v !== null && (peek() === '+' || peek() === '-')) {
+            const op = peek();
+            i += 1;
+            const r = product();
+            if (r === null)
+                return null;
+            v = op === '+' ? v + r : v - r;
+        }
+        return v;
+    };
+    const v = sum();
+    return i === text.length ? v : null;
+}
+/** The arguments `Name::new(…)` is called with in `code` (the first call), evaluated; null when there is none or one can't be read. */
+function newArgs(code, name, count) {
+    const m = new RegExp(`\\b${name}\\s*::\\s*new\\s*\\(`).exec(code);
+    if (!m)
+        return null;
+    const args = argsOf(code, m.index + m[0].length - 1);
+    if (args.length !== count)
+        return null;
+    return args.map((a) => evalConst(code, a));
+}
+const within = (v, max) => v !== null && v >= 0n && v <= max;
+const U32 = 0xffffffffn;
+const U64 = 0xffffffffffffffffn;
+/**
+ * A game hook's kind and settings from its source (docs/games.md "Studio game hooks", p2-n):
+ * the state struct whose first field is the crate's `GameHeader` names the kind by its second
+ * field (`JackpotHeader`, `StreakHeader`; neither: a lottery), and the settings are the arguments
+ * the headers are made with in `prepare`: `JackpotHeader::new(timer_secs, min_tokens)`,
+ * `StreakHeader::new(min_streak_secs, min_weight)` and `GameHeader::new(mint, round_secs, now)`,
+ * each a constant expression (`const` names followed). Null when the source is not a game hook, or
+ * a setting can't be read from it (the backend then refuses the config: the companion would check
+ * the setting against the hook's header and refuse the setup).
+ */
+export function detectGameSettings(files) {
+    const code = files.filter((f) => f.path.endsWith('.rs')).map((f) => codeOnly(f.content)).join('\n');
+    const state = /\bstruct\s+\w+\s*(?:<[^>{]*>)?\s*\{\s*(?:#\s*\[[^\]]*\]\s*)*(?:pub(?:\s*\([^)]*\))?\s+)?\w+\s*:\s*(?:(?:::)?bordrless_game\s*::\s*)?GameHeader\s*,\s*(?:#\s*\[[^\]]*\]\s*)*(?:(?:pub(?:\s*\([^)]*\))?\s+)?\w+\s*:\s*(?:(?:::)?bordrless_game\s*::\s*)?(JackpotHeader|StreakHeader)\b)?/.exec(code);
+    if (!state)
+        return null;
+    const kind = state[1] === 'JackpotHeader' ? 'jackpot' : state[1] === 'StreakHeader' ? 'streak' : 'lottery';
+    const header = newArgs(code, 'GameHeader', 3);
+    if (!header)
+        return null;
+    const roundSecs = header[1] ?? null;
+    if (!within(roundSecs, U32))
+        return null;
+    const out = { kind, timerSecs: 0, minTokens: '0', roundSecs: Number(roundSecs), minStreakSecs: 0, minWeight: '0' };
+    if (kind === 'jackpot') {
+        const j = newArgs(code, 'JackpotHeader', 2);
+        if (!j || !within(j[0] ?? null, U32) || !within(j[1] ?? null, U64))
+            return null;
+        out.timerSecs = Number(j[0]);
+        out.minTokens = j[1].toString();
+    }
+    else if (kind === 'streak') {
+        const s = newArgs(code, 'StreakHeader', 2);
+        if (!s || !within(s[0] ?? null, U32) || !within(s[1] ?? null, U64))
+            return null;
+        out.minStreakSecs = Number(s[0]);
+        out.minWeight = s[1].toString();
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bordrless/shared",
-  "version": "0.7.0",
+  "version": "0.8.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",