@bordrless/shared 0.5.0 → 0.7.0

package/dist/api.d.ts

@@ -107,7 +107,63 @@ export interface CustomHookInfo {
     upgradeAuthority: Address | null;
     /** True: `upgradeAuthority` can upgrade it. False: nobody can (final). Null: not read, so nothing is claimed either way. */
     upgradeable: boolean | null;
+    /** What the hook does, for a hook Studio built (`HookAbout`); null (or absent) for any other, which the site describes from its flags. */
+    about?: HookAbout | null;
 }
+/**
+ * Bordrless's official summary of a hook Studio deployed: written once by the assistant from the
+ * deployed source (comments and strings blanked), its flags and its review, then never changed and
+ * never the author's to edit. A new build is a new program, with a summary of its own.
+ */
+export interface HookSummary {
+    /** At most `HOOK_SUMMARY_LIMITS.title` characters. */
+    title: string;
+    /** One or two plain sentences: what the hook does to transfers, buys and sells. */
+    text: string;
+    /** The build it was written for (sha256 of the deployed binary); null when the build had none. */
+    buildHash: string | null;
+    at: number;
+}
+/** Figures the behaviour simulator measured on a hook (numbers, never model text). Reserved: not filled yet. */
+export interface HookMeasured {
+    /** The largest cut seen on one transfer, bps of it. */
+    maxCutBps: number | null;
+    /** Transfers it refused, of `runs`. */
+    refusals: number | null;
+    runs: number | null;
+}
+/**
+ * What a token hook Studio built does (`GET /v1/hooks/:program/about`, and on `CustomHookInfo.about`,
+ * `LaunchConfigData.customHook.about`, `MarketplaceListing.hookAbout`): Bordrless's official summary
+ * first, the author's own words second. Null for a hook Studio didn't build.
+ */
+export interface HookAbout {
+    program: Address;
+    /** The Studio project's name, as its author called it. */
+    title: string;
+    /** Bordrless's summary; null until it is written (the site then says what the flags allow). */
+    summary: HookSummary | null;
+    /** "What your hook does", in the author's words (at most `HOOK_ABOUT_CHARS`); empty when none was written. */
+    about: string;
+    studioProject: string;
+    /** The worst verdict of Studio's automated checks of the deployed source (not an audit); null when none is kept. */
+    reviewVerdict: 'pass' | 'warn' | null;
+    /** sha256 of the deployed binary. */
+    buildHash: string | null;
+    /** Studio keeps its source for anyone to read. */
+    sourceAvailable: boolean;
+    /** The marketplace listing that shows its source (its Studio config, when listed); null when not listed. */
+    listing: Address | null;
+    /** Reserved for the behaviour simulator's figures; absent for now. */
+    measured?: HookMeasured | null;
+}
+/** "What your hook does": the most an author writes, in characters (the Studio field and what is served). */
+export declare const HOOK_ABOUT_CHARS = 280;
+/** The official summary's limits, in characters. */
+export declare const HOOK_SUMMARY_LIMITS: {
+    readonly title: 40;
+    readonly text: 320;
+};
 /** How a pool's protocol fee is taken (§3.1): a flat rate of the quote (`protocolFeeBps`, ordinary pools), or a share of what the hooks cut (`protocolShareBps`, launch pools). */
 export type ProtocolModel = 'flat' | 'share';
 /**
@@ -120,7 +176,8 @@ export interface LaunchConfigData {
     creatorFeeBps: number;
     customHook: {
         program: Address;
-        flags: number;
+        flags: number; /** As `CustomHookInfo.about`. */
+        about?: HookAbout | null;
     } | null;
     label: string;
 }
@@ -281,6 +338,8 @@ export interface LaunchDetail extends LaunchSummary {
     ruleStats: RuleStats;
     /** The bridged-SOL holding holder rewards are paid from; null without holder rewards. */
     holderVault: Address | null;
+    /** The program that is this launch's creator (docs/companions.md), read live; null for a launch whose creator is a wallet. */
+    companion: CompanionSummary | null;
 }
 /** `GET /v1/launches?sort=`: newest first by default; `rewards24h` most paid to holders in 24 h first; `fees` lowest buy-then-sell fee first. */
 export type LaunchSort = 'new' | 'mcap' | 'volume' | 'trending' | 'graduated' | 'rewards24h' | 'fees';
@@ -500,19 +559,220 @@ export interface LaunchPrepareRequest {
      */
     config?: Address;
     /**
-     * A companion (docs/companions.md): the launch's creator is a program, so its creator fees are
-     * bought back and burned, streamed to holders or paid to the launcher by code, with no keeper.
-     * The launcher is the beneficiary; a first buy is then the companion's, vesting to them over
-     * `vestDays`. Not with the creator wallet lock or a custom hook; the holders' templates need
-     * holder rewards.
+     * Where the creator fee goes when it isn't all paid to the launcher (docs/companions.md): the
+     * launch's creator is then a program, a companion, that buys the token back and burns it,
+     * streams to holders or pays the launcher, by `split` (basis points summing to 10,000), with no
+     * keeper. A `template` names one of the three preset splits (kept for older clients). The
+     * launcher is the beneficiary; a first buy is then the companion's, vesting to them over
+     * `vestDays` (0 to 365, default 30). Refused (`companion_rules`) with the creator wallet lock, a
+     * launch config (listed or not, with or without a hook), no creator fee, a share for holders
+     * without holder rewards, or a split that doesn't add up.
      */
-    companion?: {
-        template: CompanionTemplate;
-        vestDays?: number;
-    };
+    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; 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_TEMPLATES` in the SDK). */
+/** 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. */
+export interface CompanionSplitBps {
+    /** Bought back on the token's own pool and burned. */
+    buybackBps: number;
+    /** Streamed to holders through the kit (the launch has holder rewards). */
+    holdersBps: number;
+    /** Paid to the launcher (the beneficiary), in SOL. */
+    beneficiaryBps: number;
+}
+/** A launch's companion as its token page shows it (`LaunchDetail.companion`): lamports and token base units as strings. */
+export interface CompanionSummary {
+    /** The companion's account, `PDA(["companion", mint])` under the companion program. */
+    address: Address;
+    /** The wallet that launched it: paid its part of the fees, and the dev bag as it vests. */
+    beneficiary: Address;
+    /** The template whose split this is; null for another split. */
+    template: CompanionTemplate | null;
+    split: CompanionSplitBps;
+    /** Creator fees the companion has claimed, all time. */
+    claimed: Amount;
+    /** Spent buying the token back on its pool. */
+    boughtBack: Amount;
+    /** Tokens those buybacks burned. */
+    burned: Amount;
+    /** Shared with holders through the kit. */
+    shared: Amount;
+    /** Paid to the launcher. */
+    paidToLauncher: Amount;
+    /** Claimed and waiting for its step: the next buyback, the next share, the launcher's next payout. */
+    pending: {
+        buyback: Amount;
+        holders: Amount;
+        launcher: Amount;
+    };
+    /** The launcher's first buy, held by the companion: its tokens, the part vested now, the part sent to the launcher, and when the vest ends; null without one. */
+    devBag: {
+        total: Amount;
+        vested: Amount;
+        released: Amount;
+        vestEndsAt: number;
+    } | 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.
+ * `none`: no companion was set up for the mint; `set-up`: set up, its launch not made (its funding
+ * can be taken back, `refundable`); `launched`.
+ */
+export interface CompanionStatus {
+    mint: Address;
+    state: 'none' | 'set-up' | 'launched';
+    /** The wallet it pays; null with none. */
+    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 {
+    wallet: Address;
+    mint: Address;
+}
+export interface CompanionRefundResponse {
+    transaction: PreparedTx;
+    /** Lamports it returns. */
+    refundable: Amount;
+}
 export interface LaunchPrepareResponse {
     intentId: string;
     mint: Address;
@@ -619,6 +879,13 @@ export interface BridgeAsset {
      * opened. Absent from backends that predate it.
      */
     pool?: BridgePool | null;
+    /**
+     * The platform token on the overview only: base units bought back from protocol revenue and held
+     * by the treasury (docs page /docs/tokenomics): its holding of the bridged version, plus the SPL
+     * version it holds that is still to be bridged. Read live from the chain; null when it could not
+     * be read. Absent from backends that predate it and from any other asset.
+     */
+    boughtBack?: Amount | null;
 }
 /** A bridged token's pool on the DEX (`BridgeAsset.pool`): where it is, since when, and its last price. */
 export interface BridgePool {

package/dist/api.js

@@ -3,4 +3,7 @@
  * (`Amount`), dollar figures as numbers, times as unix seconds. A figure the backend could not
  * read is null, never zero.
  */
-export {};
+/** "What your hook does": the most an author writes, in characters (the Studio field and what is served). */
+export const HOOK_ABOUT_CHARS = 280;
+/** The official summary's limits, in characters. */
+export const HOOK_SUMMARY_LIMITS = { title: 40, text: 320 };

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 { 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. */
@@ -270,6 +270,109 @@ export declare const RULE_PATHS: readonly RulePath[];
 export declare const DEFAULT_RULE_PRESET: RulePresetName;
 /** The preset of this name. */
 export declare function presetNamed(name: RulePresetName): RulePreset;
+/**
+ * The companion templates' splits of every creator fee claim: the one list the launch form, the
+ * token page and the backend read (`COMPANION_TEMPLATES` in the SDK is this object).
+ */
+export declare const COMPANION_SPLITS: Readonly<Record<CompanionTemplate, Readonly<CompanionSplitBps>>>;
+/** The templates in the order the launch form offers them. */
+export declare const COMPANION_TEMPLATE_LIST: readonly CompanionTemplate[];
+/** How long the launcher's first buy vests over, as the launch form offers it (days), and the default (the backend's too). */
+export declare const COMPANION_VEST_CHOICES_DAYS: readonly [7, 30, 90];
+export declare const COMPANION_DEFAULT_VEST_DAYS = 30;
+/** The longest a first buy may vest over, days (the program's limit is a year). */
+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. */
+export declare const splitPaysHolders: (s: CompanionSplitBps) => boolean;
+/** Whether a split takes a first buy: every fee bought back and burned means no dev at all. */
+export declare const splitTakesFirstBuy: (s: CompanionSplitBps) => boolean;
+/** A template that pays holders needs holder rewards on. */
+export declare const companionPaysHolders: (template: CompanionTemplate) => boolean;
+/** Whether a template takes a first buy: the token that buys itself has no dev at all. */
+export declare const companionTakesFirstBuy: (template: CompanionTemplate) => boolean;
+/**
+ * The split a launch request's `companion` names: its own `split` (each share a whole number of
+ * basis points, 0 to 10,000; their sum is checked by `companionSplitProblem`), or a template's;
+ * `null` when it names neither (a malformed request).
+ */
+export declare function companionRequestSplit(raw: unknown): CompanionSplitBps | null;
+/**
+ * Why a companion with this split can't run these rules, in the words the launch form and the
+ * backend use (`companion_rules`); null when it can. The program's own checks (`BadSplit`,
+ * `CreatorLockUnsupported`, `HolderRewardsOff`), and a creator fee for it to run.
+ */
+export declare function companionSplitProblem(split: CompanionSplitBps, rules: Pick<LaunchRulesInput, 'holderFeeBuyBps' | 'holderFeeSellBps' | 'creatorLockDays'>, creatorFeeBps: number): string | null;
+/** The template whose split this is, or null for any other split. */
+export declare function companionTemplateOf(split: CompanionSplitBps): CompanionTemplate | null;
 /** Kit module bits (§4.2). */
 export declare const KIT_MODULES: {
     readonly HOLDER_REWARDS: 1;

package/dist/policy.js

@@ -346,6 +346,199 @@ export const DEFAULT_RULE_PRESET = 'Plain';
 export function presetNamed(name) {
     return RULE_PRESETS.find((p) => p.name === name) ?? RULE_PRESETS[0];
 }
+// ---- companions (docs/companions.md) -----------------------------------------------------------------
+/**
+ * The companion templates' splits of every creator fee claim: the one list the launch form, the
+ * token page and the backend read (`COMPANION_TEMPLATES` in the SDK is this object).
+ */
+export const COMPANION_SPLITS = {
+    /** No dev at all: every creator fee buys the token back and burns it. */
+    buysItself: { buybackBps: 10_000, holdersBps: 0, beneficiaryBps: 0 },
+    /** Half to holders through the kit, half to the launcher, whose first buy vests (holder rewards needed). */
+    rugProofDev: { buybackBps: 0, holdersBps: 5_000, beneficiaryBps: 5_000 },
+    /** Half bought back and burned, half to holders (holder rewards needed). */
+    buybackAndReward: { buybackBps: 5_000, holdersBps: 5_000, beneficiaryBps: 0 },
+};
+/** The templates in the order the launch form offers them. */
+export const COMPANION_TEMPLATE_LIST = ['buysItself', 'rugProofDev', 'buybackAndReward'];
+/** How long the launcher's first buy vests over, as the launch form offers it (days), and the default (the backend's too). */
+export const COMPANION_VEST_CHOICES_DAYS = [7, 30, 90];
+export const COMPANION_DEFAULT_VEST_DAYS = 30;
+/** The longest a first buy may vest over, days (the program's limit is a year). */
+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. */
+export const splitPaysHolders = (s) => s.holdersBps > 0;
+/** Whether a split takes a first buy: every fee bought back and burned means no dev at all. */
+export const splitTakesFirstBuy = (s) => s.buybackBps < 10_000;
+/** A template that pays holders needs holder rewards on. */
+export const companionPaysHolders = (template) => splitPaysHolders(COMPANION_SPLITS[template]);
+/** Whether a template takes a first buy: the token that buys itself has no dev at all. */
+export const companionTakesFirstBuy = (template) => splitTakesFirstBuy(COMPANION_SPLITS[template]);
+const isShare = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= 10_000;
+/**
+ * The split a launch request's `companion` names: its own `split` (each share a whole number of
+ * basis points, 0 to 10,000; their sum is checked by `companionSplitProblem`), or a template's;
+ * `null` when it names neither (a malformed request).
+ */
+export function companionRequestSplit(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const r = raw;
+    if (r.split !== undefined) {
+        if (typeof r.split !== 'object' || r.split === null)
+            return null;
+        const s = r.split;
+        if (!isShare(s.buybackBps) || !isShare(s.holdersBps) || !isShare(s.beneficiaryBps))
+            return null;
+        return { buybackBps: s.buybackBps, holdersBps: s.holdersBps, beneficiaryBps: s.beneficiaryBps };
+    }
+    if (typeof r.template === 'string' && Object.hasOwn(COMPANION_SPLITS, r.template))
+        return { ...COMPANION_SPLITS[r.template] };
+    return null;
+}
+/**
+ * Why a companion with this split can't run these rules, in the words the launch form and the
+ * backend use (`companion_rules`); null when it can. The program's own checks (`BadSplit`,
+ * `CreatorLockUnsupported`, `HolderRewardsOff`), and a creator fee for it to run.
+ */
+export function companionSplitProblem(split, rules, creatorFeeBps) {
+    if (![split.buybackBps, split.holdersBps, split.beneficiaryBps].every(isShare))
+        return 'Each share of the creator fee is a whole number of basis points, 0 to 10,000.';
+    if (split.buybackBps + split.holdersBps + split.beneficiaryBps !== 10_000)
+        return 'The creator fee’s shares must add up to 100% (10,000 basis points).';
+    if (rules.creatorLockDays > 0)
+        return 'A creator fee run by a program can’t come with the creator wallet lock: the program vests your first buy instead.';
+    if (creatorFeeBps === 0)
+        return 'There is no creator fee for a program to run: set one.';
+    if (splitPaysHolders(split) && !rewardsOn(rules))
+        return 'A share of the creator fee for holders needs holder rewards on.';
+    return null;
+}
+/** The template whose split this is, or null for any other split. */
+export function companionTemplateOf(split) {
+    return COMPANION_TEMPLATE_LIST.find((t) => {
+        const s = COMPANION_SPLITS[t];
+        return s.buybackBps === split.buybackBps && s.holdersBps === split.holdersBps && s.beneficiaryBps === split.beneficiaryBps;
+    }) ?? null;
+}
 /** Kit module bits (§4.2). */
 export const KIT_MODULES = { HOLDER_REWARDS: 1, MAX_WALLET: 2, CREATOR_LOCK: 4, EARLY_LOCK: 8 };
 /** The kit modules a launch with these rules installs (§5.1); 0 means no hook at all (a burn alone runs in the pool hook). */

package/dist/programs.d.ts

@@ -16,7 +16,36 @@ export declare const PROGRAM_IDS: {
     readonly halfLife: "53SpmtkdPWQ63mWoDeXk8P9tuwiT4ed2Wx4fwfy5NSF8";
     /** Companions (programs/bordrless_companion, docs/companions.md): a launch whose creator is a program, its fees bought back, shared with holders or vested by code. */
     readonly companion: "6ZUM1gWBH9hBBNoJoaVAGwSftyZ6CUda6vUZTW9MsJuo";
+    /**
+     * The lottery hook (programs/lottery_hook, docs/companions.md "Games"): a lottery coin's token
+     * hook under the game ticket standard; its companion holds the pot and draws. Not deployed yet
+     * (2026-10-08): companion v2 and this hook go live together, after their audit.
+     */
+    readonly lotteryHook: "HqFWsCBQ416DAfevJ9TspyT5yXGGoYTCpcreiGkCgWcr";
 };
+/**
+ * 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
+ * launch accepts), the token program's signer of its callbacks (`["hook-authority", hook]` under
+ * the token program) and its own `["hook-authority"]`, which signs `write_hook_data` in `enter`.
+ */
+export declare const LOTTERY_HOOK: {
+    readonly program: "HqFWsCBQ416DAfevJ9TspyT5yXGGoYTCpcreiGkCgWcr";
+    readonly flags: 145;
+    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

@@ -16,7 +16,40 @@ export const PROGRAM_IDS = {
     halfLife: '53SpmtkdPWQ63mWoDeXk8P9tuwiT4ed2Wx4fwfy5NSF8',
     /** Companions (programs/bordrless_companion, docs/companions.md): a launch whose creator is a program, its fees bought back, shared with holders or vested by code. */
     companion: '6ZUM1gWBH9hBBNoJoaVAGwSftyZ6CUda6vUZTW9MsJuo',
+    /**
+     * The lottery hook (programs/lottery_hook, docs/companions.md "Games"): a lottery coin's token
+     * hook under the game ticket standard; its companion holds the pot and draws. Not deployed yet
+     * (2026-10-08): companion v2 and this hook go live together, after their audit.
+     */
+    lotteryHook: 'HqFWsCBQ416DAfevJ9TspyT5yXGGoYTCpcreiGkCgWcr',
 };
+/**
+ * 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
+ * launch accepts), the token program's signer of its callbacks (`["hook-authority", hook]` under
+ * the token program) and its own `["hook-authority"]`, which signs `write_hook_data` in `enter`.
+ */
+export const LOTTERY_HOOK = {
+    program: PROGRAM_IDS.lotteryHook,
+    flags: 145,
+    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/dist/studio.d.ts

@@ -13,7 +13,7 @@
  * for a new mint without knowing its code. The backend refuses source that leaves the template's
  * limits (`StaticCheck`) before it is built, reviewed or paid for.
  */
-import type { Address, PreparedTx } from './api.ts';
+import type { Address, HookAbout, PreparedTx } from './api.ts';
 /** One source file of a hook. Only `src/**.rs` files; `Cargo.toml` is the template's and never sent. */
 export interface StudioFile {
     /** Relative path, e.g. `src/lib.rs`. */
@@ -167,9 +167,15 @@ export interface ReviewFinding {
     /** `src/lib.rs:42`, when it points at a line. */
     location: string | null;
 }
-/** `POST /v1/studio/projects/:id/review`: the static checks, then the assistant's security review. */
+/**
+ * `POST /v1/studio/projects/:id/review`: the static checks, then the automated security review (two
+ * independent model runs, the worse kept). Every run of a source (and the hook flags read from it,
+ * `detectHookFlags`) is kept: the review shown is the worst of them, its findings merged, and a
+ * source that failed once stays failed (only a change to the source clears it). Automated checks,
+ * not an audit.
+ */
 export interface StudioReview {
-    /** `fail`: a static check failed or a critical/high finding; deploy is refused. */
+    /** `fail`: a static check failed or a critical/high finding; deploy is refused. The worst of every run of this source and these flags. */
     verdict: 'pass' | 'warn' | 'fail';
     checks: StaticCheck[];
     findings: ReviewFinding[];
@@ -177,6 +183,10 @@ export interface StudioReview {
     summary: string;
     /** sha256 of the source reviewed. */
     sourceHash: string;
+    /** The hook flags the source was reviewed with, read from the source itself (`detectHookFlags`). Absent on reviews made before flags were recorded. */
+    hookFlags?: number;
+    /** How many review runs of this source and these flags the verdict and findings merge. */
+    runs?: number;
     at: number;
 }
 /** `POST /v1/studio/projects/:id/build`: compiled by the build worker in the verifiable-build image. */
@@ -191,6 +201,21 @@ export interface StudioBuild {
     log: string;
     sourceHash: string;
     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 simulator's verdict on a build: launched, bought, sold and sent by several wallets over a simulated year. */
+export interface StudioSim {
+    pass: boolean;
+    /** Why it failed, in the simulator's words (the first few). */
+    reasons: string[];
+    /** The most the hook took from one transfer, in bps, and the cap it was held to. */
+    cutMaxBps: number | null;
+    capBps: number | null;
+    /** Operations the hook refused. */
+    refusedTotal: number;
+    /** What the test can't see (amount triggers, wallets it never used, after a year). */
+    notes: string[];
 }
 /** `POST /v1/studio/projects/:id/deploy/quote`: what deploying the built hook costs, in lamports. */
 export interface StudioDeployQuote {
@@ -272,8 +297,13 @@ export interface MarketplaceListing {
     studioSource: boolean;
     /** Who can upgrade the hook now (null: final, or no hook). */
     hookUpgradeAuthority: Address | null;
-    /** The source passed review when it was deployed. */
-    reviewVerdict: 'pass' | 'warn' | null;
+    /**
+     * The worst verdict of the automated checks over every review run of the deployed source (not an
+     * audit, and not a seal); null when Studio did not build the hook or has no review of it.
+     */
+    reviewVerdict: 'pass' | 'warn' | 'fail' | null;
+    /** What its hook does, when Studio built it: Bordrless's summary and the author's words (`HookAbout`); null or absent otherwise. */
+    hookAbout?: HookAbout | null;
     launches: number;
     /** Paid to the author so far, lamports. */
     authorEarned: string;
@@ -326,6 +356,25 @@ export declare const PROTOCOL_UPGRADE_AUTHORITY = "5xsibKwtiN6ruxsYrEyWVpV3Kcwuz
  * may hold a custom hook's upgrade authority for `create_config` to accept it (docs/hooks-v2.md §5.8).
  */
 export declare const HOOK_UPGRADE_AUTHORITIES: readonly string[];
+/** The one sentence the site gives a config whose hook someone outside Bordrless can upgrade. */
+export declare const HOOK_AUTHORITY_PROBLEM = "This config\u2019s hook can be upgraded by someone outside Bordrless, so it can\u2019t launch here.";
+/** The error code the backend refuses such a config with (`POST /v1/launch/prepare`). */
+export declare const HOOK_AUTHORITY_CODE = "hook_upgrade_authority";
+/** The Solana CLI command that makes a deployed hook immutable (signed by its current upgrade authority): the way a hook built outside Studio can launch. */
+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
+ * 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
+ * (`customHook` null: the launchpad's and the kit's own programs) passes.
+ */
+export declare function hookAuthorityAccepted(customHook: string | null, hook: {
+    upgradeAuthority: string | null;
+    upgradeable: boolean | null;
+} | 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;
 /**
@@ -357,3 +406,16 @@ export declare const STUDIO_STARTERS: readonly {
     name: string;
     blurb: 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)
+ * when before_transfer runs and the code builds a `Delta` or fills `deltas`; hook data
+ * (WRITES_HOOK_DATA) when the code sets a holding's `source_hook_data`/`destination_hook_data`
+ * (reading `args.…_hook_data` needs no flag). It leans to including a bit: a flag the code doesn't
+ * use is harmless, a missing one makes the token program refuse the hook's answer. 0: the hook does
+ * nothing yet.
+ */
+export declare function detectHookFlags(files: readonly {
+    path: string;
+    content: string;
+}[]): number;

package/dist/studio.js

@@ -1,3 +1,4 @@
+import { TOKEN_HOOK_FLAGS as HOOK_FLAG_BITS } from "./programs.js";
 /** 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');
@@ -14,6 +15,26 @@ export const PROTOCOL_UPGRADE_AUTHORITY = '5xsibKwtiN6ruxsYrEyWVpV3KcwuzSPbQd1n2
  * may hold a custom hook's upgrade authority for `create_config` to accept it (docs/hooks-v2.md §5.8).
  */
 export const HOOK_UPGRADE_AUTHORITIES = [STUDIO_UPGRADE_AUTHORITY, PROTOCOL_UPGRADE_AUTHORITY];
+/** The one sentence the site gives a config whose hook someone outside Bordrless can upgrade. */
+export const HOOK_AUTHORITY_PROBLEM = 'This config’s hook can be upgraded by someone outside Bordrless, so it can’t launch here.';
+/** The error code the backend refuses such a config with (`POST /v1/launch/prepare`). */
+export const HOOK_AUTHORITY_CODE = 'hook_upgrade_authority';
+/** The Solana CLI command that makes a deployed hook immutable (signed by its current upgrade authority): the way a hook built outside Studio can launch. */
+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
+ * 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
+ * (`customHook` null: the launchpad's and the kit's own programs) passes.
+ */
+export function hookAuthorityAccepted(customHook, hook) {
+    if (customHook === null || hook === null || hook.upgradeable !== true || hook.upgradeAuthority === null)
+        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. */
 export const MAX_AUTHOR_SHARE_BPS = 5_000;
 /**
@@ -38,3 +59,112 @@ export const STUDIO_STARTERS = [
     { 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.' },
 ];
+// ---- the hook's flags, read from its source ---------------------------------------------------------
+/** Comments, string and char literals blanked (newlines kept), so only code is read. */
+function codeOnly(src) {
+    let out = '';
+    let i = 0;
+    while (i < src.length) {
+        const c = src[i];
+        const n = src[i + 1];
+        if (c === '/' && n === '/') {
+            while (i < src.length && src[i] !== '\n')
+                i += 1;
+        }
+        else if (c === '/' && n === '*') {
+            let depth = 1;
+            i += 2;
+            while (i < src.length && depth > 0) {
+                if (src[i] === '/' && src[i + 1] === '*')
+                    (depth += 1), (i += 2);
+                else if (src[i] === '*' && src[i + 1] === '/')
+                    (depth -= 1), (i += 2);
+                else {
+                    if (src[i] === '\n')
+                        out += '\n';
+                    i += 1;
+                }
+            }
+        }
+        else if (c === 'r' && (n === '"' || n === '#') && !/[A-Za-z0-9_]/.test(src[i - 1] ?? '')) {
+            let j = i + 1;
+            let hashes = 0;
+            while (src[j] === '#')
+                (hashes += 1), (j += 1);
+            if (src[j] !== '"') {
+                out += c;
+                i += 1;
+                continue;
+            }
+            const end = '"' + '#'.repeat(hashes);
+            const close = src.indexOf(end, j + 1);
+            i = close < 0 ? src.length : close + end.length;
+            out += ' ';
+        }
+        else if (c === '"') {
+            i += 1;
+            while (i < src.length && src[i] !== '"')
+                i += src[i] === '\\' ? 2 : 1;
+            i += 1;
+            out += ' ';
+        }
+        else {
+            out += c;
+            i += 1;
+        }
+    }
+    return out;
+}
+/** A function's body (between its braces), or null when it isn't there. */
+function bodyOf(code, name) {
+    const m = new RegExp(`\\bfn\\s+${name}\\s*\\(`).exec(code);
+    if (!m)
+        return null;
+    const open = code.indexOf('{', m.index);
+    if (open < 0)
+        return null;
+    let depth = 0;
+    for (let k = open; k < code.length; k += 1) {
+        if (code[k] === '{')
+            depth += 1;
+        else if (code[k] === '}') {
+            depth -= 1;
+            if (depth === 0)
+                return code.slice(open + 1, k);
+        }
+    }
+    return null;
+}
+/** The Studio template's untouched callbacks: a callback left like this does nothing, so it isn't subscribed. */
+const STUB_BODIES = new Set(['check_call(&ctx,&args)?;Ok(HookReturn::default())', 'check_call(&ctx,&args)']);
+const CALLBACK_FLAGS = [
+    ['before_transfer', HOOK_FLAG_BITS.BEFORE_TRANSFER],
+    ['after_transfer', HOOK_FLAG_BITS.AFTER_TRANSFER],
+    ['before_mint', HOOK_FLAG_BITS.BEFORE_MINT],
+    ['after_mint', HOOK_FLAG_BITS.AFTER_MINT],
+    ['before_burn', HOOK_FLAG_BITS.BEFORE_BURN],
+    ['after_burn', HOOK_FLAG_BITS.AFTER_BURN],
+];
+/**
+ * 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)
+ * when before_transfer runs and the code builds a `Delta` or fills `deltas`; hook data
+ * (WRITES_HOOK_DATA) when the code sets a holding's `source_hook_data`/`destination_hook_data`
+ * (reading `args.…_hook_data` needs no flag). It leans to including a bit: a flag the code doesn't
+ * use is harmless, a missing one makes the token program refuse the hook's answer. 0: the hook does
+ * nothing yet.
+ */
+export function detectHookFlags(files) {
+    const code = files.filter((f) => f.path.endsWith('.rs')).map((f) => codeOnly(f.content)).join('\n');
+    let flags = 0;
+    for (const [name, bit] of CALLBACK_FLAGS) {
+        const body = bodyOf(code, name);
+        if (body !== null && !STUB_BODIES.has(body.replace(/\s+/g, '')))
+            flags |= bit;
+    }
+    if (flags & HOOK_FLAG_BITS.BEFORE_TRANSFER && (/\bDelta\s*\{/.test(code) || /\bdeltas\s*:/.test(code) || /\.deltas\b/.test(code)))
+        flags |= HOOK_FLAG_BITS.TRANSFER_RETURNS_DELTA;
+    if (flags && /(?<!args\.)\b(source|destination)_hook_data\b/.test(code))
+        flags |= HOOK_FLAG_BITS.WRITES_HOOK_DATA;
+    return flags;
+}

package/package.json

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