@bordrless/shared 0.4.0 → 0.6.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;
 }
@@ -244,6 +301,8 @@ export interface LaunchSummary {
     protocolModel: ProtocolModel;
     /** Under the share model, Bordrless's share of the cuts in basis points (2,500 = a quarter); null under the flat model. */
     protocolShareBps: number | null;
+    /** The pool's LP fee (the sniper fee included) goes to Bordrless in SOL: a launch pool created at or after the DEX upgrade of 2026-10-08 (`LP_FEE_TO_PROTOCOL_FROM_SLOT`). False on one created before it, whose LP fee stays in the pool. */
+    lpFeeToProtocol: boolean;
     /** Total fee of a buy by the §7.3 formula, outside the sniper window. */
     buyFeeBps: number;
     /** Total fee of a sell by the §7.3 formula, outside the sniper window. */
@@ -279,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';
@@ -447,7 +508,8 @@ export interface PreparedTx {
     stage: number;
     label: string;
     /** Keys the browser holds that must also sign (a launch's fresh mint). */
-    extraSigners: ('mint')[];
+    /** Keys the browser holds that sign after the wallet: a launch's fresh mint, a new launch config. */
+    extraSigners: ('mint' | 'config')[];
 }
 export interface SwapPrepareResponse {
     transactions: PreparedTx[];
@@ -496,6 +558,94 @@ export interface LaunchPrepareRequest {
      * (what the site showed is what launches), and a custom hook's accounts are resolved for `mint`.
      */
     config?: Address;
+    /**
+     * 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?: 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. */
+export type CompanionRequest = {
+    split: CompanionSplitBps;
+    vestDays?: number;
+} | {
+    template: CompanionTemplate;
+    vestDays?: number;
+};
+/** The companion templates (`COMPANION_SPLITS`; `COMPANION_TEMPLATES` in the SDK). */
+export type CompanionTemplate = 'buysItself' | 'rugProofDev' | 'buybackAndReward';
+/** What a companion does with every creator fee it claims, in basis points summing to 10,000. */
+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;
+}
+/**
+ * `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;
+}
+/** `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;
@@ -539,6 +689,24 @@ export interface RewardsPrepareRequest {
     /** Unwrap the bridged SOL to SOL and close the temporary holding. */
     unwrap: boolean;
 }
+/**
+ * Send `amount` of `mint` from the owner's holding to `to`'s (made on the way when missing, the
+ * sender paying its rent). Wallets cannot build this themselves: the token program's transfer takes
+ * the mint's hook accounts, which the backend resolves. A holding under the creator lock or the
+ * early-buyer lock is refused with the lock (code `locked`), as the program would refuse it.
+ */
+export interface TransferPrepareRequest {
+    owner: Address;
+    mint: Address;
+    to: Address;
+    /** Base units of the token. */
+    amount: Amount;
+}
+export interface TransferPrepareResponse {
+    transactions: PreparedTx[];
+    /** Lamports the sender pays for the recipient's holding; 0 when it already exists. */
+    rentLamports: Amount;
+}
 /** Claim the creator fees of launches the owner created: up to about 4 mints per transaction, paid as SOL. */
 export interface CreatorPrepareRequest {
     owner: Address;
@@ -585,6 +753,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 {
@@ -600,6 +775,8 @@ export interface BridgePool {
     lpFeeBps: number;
     /** The flat protocol rate of the quote on this pool (ordinary pools; 0 under the share model). */
     protocolFeeBps: number;
+    /** The LP fee goes to Bordrless in SOL (a launch pool since the upgrade of 2026-10-08, `LP_FEE_TO_PROTOCOL_FROM_SLOT`); false when it stays in the pool, as an ordinary pool's always does. */
+    lpFeeToProtocol: boolean;
     baseReserve: Amount;
     quoteReserve: Amount;
     volume24hUsd: number | null;
@@ -639,6 +816,8 @@ export interface PoolSummary {
     protocolModel?: ProtocolModel;
     /** Under the share model, Bordrless's share of what the hooks cut, in basis points; null (or absent) under the flat model. */
     protocolShareBps?: number | null;
+    /** The LP fee goes to Bordrless in SOL (a launch pool since the upgrade of 2026-10-08); false when it stays in the pool. Absent from backends that predate it. */
+    lpFeeToProtocol?: boolean;
     hookProgram: Address | null;
     /** The base token's creator-written hook (§5.8), for a launch pool whose token has one; null or absent otherwise. */
     customHook?: CustomHookInfo | null;
@@ -681,3 +860,264 @@ export interface ApiErrorBody {
     error: string;
     code?: string;
 }
+/** Which of the standard's programs emitted an event: the five of Bordrless, or any hook program (`hook`). */
+export type ExplorerProgram = 'token' | 'swap' | 'bridge' | 'launch' | 'kit' | 'hook';
+/** What an address turned out to be, in the order the backend looks: a mint, a pool, a bridge wrapper, a holding, a program, a wallet, a launch config, or nothing it knows. */
+export type ExplorerKind = 'mint' | 'pool' | 'wrapper' | 'holding' | 'program' | 'wallet' | 'config' | 'unknown';
+export interface ExplorerStats {
+    /** Mints of the standard the indexer has seen. */
+    mints: number;
+    /** Holdings with a balance. */
+    holdings: number;
+    /** Transactions indexed (distinct signatures), all time and in the last 24 hours. */
+    transactions: number;
+    transactions24h: number;
+    /** The newest slot indexed; null before the first event. */
+    newestSlot: number | null;
+}
+/** A token an event's amounts are in. */
+export interface ExplorerToken {
+    mint: Address;
+    symbol: string;
+    decimals: number;
+}
+/** One decoded event of `chain_events`, as the explorer shows it. */
+export interface ExplorerEvent {
+    signature: string;
+    ordinal: number;
+    slot: number;
+    blockTime: number | null;
+    /** The program id that emitted it. */
+    program: Address;
+    /** The IDL's event name in PascalCase (`Transferred`, `Swapped`, `KitInstalled`). */
+    name: string;
+    /** The account the event is mostly about (the mint, the pool, the holding, ...); null when it has none. */
+    subject: Address | null;
+    /** The decoded fields: keys as the SDK's coder gives them (camelCase), pubkeys as base58, integers as decimal strings. */
+    payload: Record<string, unknown>;
+    /** The tokens its amounts are in, where the indexer knows them: the event's own mint (or the pool's base), and the pool's quote. */
+    base: ExplorerToken | null;
+    quote: ExplorerToken | null;
+}
+export interface ExplorerEvents {
+    events: ExplorerEvent[];
+    /** The cursor for the page after this one (`before=`); null on the last page. */
+    next: string | null;
+}
+/** `GET /v1/explorer/tx/:signature`: a transaction the indexer has, with every event it decoded, in order. */
+export interface ExplorerTx {
+    signature: string;
+    slot: number;
+    blockTime: number | null;
+    /** The program ids its events came from, first seen first. */
+    programs: Address[];
+    events: ExplorerEvent[];
+}
+export interface ExplorerMint {
+    mint: Address;
+    name: string;
+    symbol: string;
+    image: string | null;
+    decimals: number;
+    supply: Amount;
+    maxSupply: Amount;
+    creator: Address;
+    createdAt: number;
+    kind: 'launch' | 'bridged' | 'lp' | 'other';
+    mintAuthority: Address | null;
+    freezeAuthority: Address | null;
+    hookAuthority: Address | null;
+    metadataAuthority: Address | null;
+    hookProgram: Address | null;
+    hookFlags: number;
+    /** Holdings with a balance. */
+    holders: number;
+}
+export interface ExplorerHolder {
+    owner: Address;
+    holding: Address;
+    amount: Amount;
+    /** Of the supply, 0 to 1. */
+    share: number;
+}
+/** A pool as the explorer lists it on a mint's page, or shows it on its own. */
+export interface ExplorerPool {
+    pool: Address;
+    baseMint: Address;
+    quoteMint: Address;
+    baseSymbol: string;
+    quoteSymbol: string;
+    baseDecimals: number;
+    quoteDecimals: number;
+    baseReserve: Amount;
+    quoteReserve: Amount;
+    lpMint: Address;
+    lpSupply: Amount;
+    lpFeeBps: number;
+    protocolFeeBps: number;
+    protocolModel: ProtocolModel;
+    protocolShareBps: number | null;
+    /** The LP fee goes to Bordrless in SOL (a launch pool since the upgrade of 2026-10-08); false when it stays in the pool. */
+    lpFeeToProtocol: boolean;
+    hookProgram: Address | null;
+    hookFlags: number;
+    curve: boolean;
+    creator: Address;
+    createdAt: number;
+    swapCount: number;
+    volume24hUsd: number | null;
+    /** The launch this is the pool of, if any. */
+    launchMint: Address | null;
+}
+export interface ExplorerHolding {
+    holding: Address;
+    mint: Address;
+    owner: Address;
+    amount: Amount;
+    symbol: string;
+    name: string;
+    image: string | null;
+    decimals: number;
+    /** Dollars, where the token has a pool against bridged SOL and SOL has a price. */
+    valueUsd: number | null;
+}
+export interface ExplorerProgramInfo extends ProgramInfo {
+    /** The program's name on the standard ("Token", "DEX", "Half-Life"); a hook the site does not know is "Hook". */
+    name: string;
+    /** Events indexed, by event name, most first. */
+    counts: {
+        name: string;
+        count: number;
+    }[];
+}
+export interface ExplorerWrapper {
+    wrapper: Address;
+    underlyingMint: Address;
+    underlyingProgram: Address;
+    wrappedMint: Address;
+    vault: Address;
+    decimals: number;
+    native: boolean;
+    totalWrapped: Amount;
+    name: string;
+    symbol: string;
+    image: string | null;
+    registrar: Address;
+    registeredAt: number;
+}
+/** A `LaunchConfig` (docs/hooks-v2.md §5.7) as its `LaunchConfigCreated` event told it, and the launches made from it. */
+export interface ExplorerConfig {
+    config: Address;
+    creator: Address | null;
+    label: string | null;
+    creatorFeeBps: number | null;
+    customHook: Address | null;
+    customHookFlags: number | null;
+    rules: Record<string, unknown> | null;
+    launches: {
+        mint: Address;
+        name: string;
+        symbol: string;
+        image: string | null;
+    }[];
+}
+/** A short reference to a token, for lists. */
+export interface ExplorerTokenRef {
+    mint: Address;
+    name: string;
+    symbol: string;
+    image: string | null;
+}
+/** `GET /v1/explorer/address/:address`: what lives at an address, by kind. Every kind carries the newest events touching it. */
+export type ExplorerAddress = {
+    address: Address;
+    events: ExplorerEvent[];
+} & ({
+    kind: 'mint';
+    mint: ExplorerMint;
+    launch: {
+        status: LaunchStatus;
+    } | null;
+    wrapper: {
+        underlyingMint: Address;
+        native: boolean;
+    } | null;
+    pools: ExplorerPool[];
+    holders: ExplorerHolder[];
+} | {
+    kind: 'pool';
+    pool: ExplorerPool;
+    trades: Trade[];
+} | {
+    kind: 'wrapper';
+    wrapper: ExplorerWrapper;
+} | {
+    kind: 'holding';
+    holding: ExplorerHolding;
+} | {
+    kind: 'program';
+    program: ExplorerProgramInfo;
+} | {
+    kind: 'wallet';
+    holdings: ExplorerHolding[];
+    totalUsd: number | null;
+    created: ExplorerTokenRef[];
+} | {
+    kind: 'config';
+    config: ExplorerConfig;
+} | {
+    kind: 'unknown';
+});
+/** One answer to a search: an address resolved to its kind, a transaction, or a mint whose name or ticker matched. */
+export interface ExplorerHit {
+    kind: ExplorerKind | 'tx';
+    address: Address;
+    name: string | null;
+    symbol: string | null;
+    image: string | null;
+}
+export interface ExplorerSearch {
+    query: string;
+    hits: ExplorerHit[];
+}
+/**
+ * `POST /v1/config/prepare`: a `LaunchConfig` made from the launch page (Build your own, §5.7), for a
+ * hook program of the creator's own. `config` is the address of a keypair the browser made; it signs
+ * after the wallet. The kit's rules can't go with a hook of one's own, so a config carries burn and a
+ * creator fee only.
+ */
+export interface ConfigPrepareRequest {
+    creator: Address;
+    config: Address;
+    customHook: Address;
+    /** `TOKEN_HOOK_FLAGS`: at least one callback, no unknown bit. */
+    customHookFlags: number;
+    burnBuyBps: number;
+    burnSellBps: number;
+    creatorFeeBps: number;
+    /** At most 32 bytes. */
+    label: string;
+}
+export interface ConfigPrepareResponse {
+    config: Address;
+    transactions: PreparedTx[];
+}
+/** `GET /v1/hooks/:program?mint=`: a hook program as the launch page checks it, and whether it is prepared for the mint. */
+export interface HookInspection {
+    program: Address;
+    /** Deployed as a program on this cluster. */
+    executable: boolean;
+    /** None of Bordrless's own programs. */
+    ownProgram: boolean;
+    upgradeAuthority: Address | null;
+    upgradeable: boolean | null;
+    /** With a mint: the registry it must write for that mint, `["bordrless-hook-accounts", mint]` under the program. */
+    registry: Address | null;
+    /** With a mint: whether that registry exists and decodes. */
+    registryReady: boolean | null;
+    /** The registry's extra accounts, once it exists; a launch fits at most `maxExtras`. */
+    extras: number | null;
+    maxExtras: number;
+    /** Why it can't be launched with yet, one sentence each. */
+    problems: string[];
+}

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, LaunchRules, LaunchRulesInput, 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,44 @@ 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>;
+/** 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,85 @@ 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 };
+/** 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

@@ -14,6 +14,27 @@ export declare const PROGRAM_IDS: {
     readonly kit: "14RJQXPdJfkehit6ezktjd3xujamf8nVSKw2shKamaEH";
     /** Half-Life (programs/half_life): an exit fee that halves every six hours a token is held, burned. */
     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";
 };
 /**
  * Half-Life, Bordrless's own token hook (programs/half_life/README.md): the `LaunchConfig` the
@@ -39,6 +60,26 @@ export declare const HALF_LIFE: {
  * (20% at 0, halved every six hours, linear within each, 0 from 48 h).
  */
 export declare function halfLifeFeePpm(ageSecs: number): number;
+/**
+ * The DEX upgrade of 2026-10-08 (docs/hooks-v2.md §3.1, "The LP fee of a launch pool is
+ * Bordrless's"): from this slot on mainnet a launch pool's LP fee (the sniper fee included) is
+ * taken in SOL and paid to Bordrless with the protocol fee; a launch pool created before it keeps
+ * its LP fee in the pool, compounding, as its traders were told. The slot is the DEX program's
+ * last upgrade, read from its ProgramData account; the time is that slot's block time
+ * (`getBlockTime`, unix seconds), which the backend compares a pool's `created_at` against (the
+ * pools table keeps a timestamp, not a slot). Devnet and localnet were deployed after the rule:
+ * every launch pool there pays Bordrless.
+ */
+export declare const LP_FEE_TO_PROTOCOL_FROM_SLOT = 454439142;
+export declare const LP_FEE_TO_PROTOCOL_FROM_TIME = 1791434238;
+/**
+ * Whether a pool's LP fee goes to Bordrless (`LaunchSummary.lpFeeToProtocol`): every launch pool's
+ * (the share model), whenever it was created. The upgraded DEX keys the fee's destination on the
+ * pool's fee model alone, so a launch pool opened before the upgrade compounded its LP fee until
+ * that slot and pays Bordrless since. An ordinary pool's LP fee is its liquidity's. `createdAt`
+ * and `cluster` are kept for the record of when the rule began (the constants above).
+ */
+export declare function lpFeeToProtocol(shareModel: boolean, _createdAt: number, _cluster: 'mainnet' | 'devnet' | 'localnet'): boolean;
 /** The wSOL mint, which stands for native SOL on the bridge. */
 export declare const NATIVE_MINT = "So11111111111111111111111111111111111111112";
 export declare const TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
@@ -89,9 +130,11 @@ export declare const FIXED_ADDRESSES: {
     readonly kitEventAuthority: "9abhxVTuwck5Ux79act3e2Vkfem7Q4zBwATMctUvHvuE";
     /** `["hook-authority"]` under the kit: it signs the token program's `write_hook_data` in `claim`. */
     readonly kitHookAuthority: "2repKA1JgDkBo4AffscVee342dcBcH6c2yfpUTRrAiEN";
+    /** `["__event_authority"]` under the companion program. */
+    readonly companionEventAuthority: "7QuoYRuD9MHzX5EN7qqj62iwNPVqfy74RzmwJ524cgDt";
 };
 /**
- * The protocol lookup table (docs/hooks-v2.md §6; programs-summary §2.7): the 18 fixed addresses
+ * The protocol lookup table (docs/hooks-v2.md §6; programs-summary §2.7): the 22 fixed addresses
  * no top-level instruction invokes, in the order the programs' tests load them and `pnpm admin
  * init` must write them (a v0 message names table entries by index). Programs a transaction
  * invokes at top level (the kit for claims and shares) are kept in the static keys by the v0

package/dist/programs.js

@@ -14,6 +14,27 @@ export const PROGRAM_IDS = {
     kit: '14RJQXPdJfkehit6ezktjd3xujamf8nVSKw2shKamaEH',
     /** Half-Life (programs/half_life): an exit fee that halves every six hours a token is held, burned. */
     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',
 };
 /**
  * Half-Life, Bordrless's own token hook (programs/half_life/README.md): the `LaunchConfig` the
@@ -49,6 +70,28 @@ export function halfLifeFeePpm(ageSecs) {
     const lo = Math.floor(HALF_LIFE.maxFeePpm / 2 ** (halvings + 1));
     return hi - Math.floor(((hi - lo) * into) / HALF_LIFE.halfLifeSecs);
 }
+/**
+ * The DEX upgrade of 2026-10-08 (docs/hooks-v2.md §3.1, "The LP fee of a launch pool is
+ * Bordrless's"): from this slot on mainnet a launch pool's LP fee (the sniper fee included) is
+ * taken in SOL and paid to Bordrless with the protocol fee; a launch pool created before it keeps
+ * its LP fee in the pool, compounding, as its traders were told. The slot is the DEX program's
+ * last upgrade, read from its ProgramData account; the time is that slot's block time
+ * (`getBlockTime`, unix seconds), which the backend compares a pool's `created_at` against (the
+ * pools table keeps a timestamp, not a slot). Devnet and localnet were deployed after the rule:
+ * every launch pool there pays Bordrless.
+ */
+export const LP_FEE_TO_PROTOCOL_FROM_SLOT = 454_439_142;
+export const LP_FEE_TO_PROTOCOL_FROM_TIME = 1_791_434_238;
+/**
+ * Whether a pool's LP fee goes to Bordrless (`LaunchSummary.lpFeeToProtocol`): every launch pool's
+ * (the share model), whenever it was created. The upgraded DEX keys the fee's destination on the
+ * pool's fee model alone, so a launch pool opened before the upgrade compounded its LP fee until
+ * that slot and pays Bordrless since. An ordinary pool's LP fee is its liquidity's. `createdAt`
+ * and `cluster` are kept for the record of when the rule began (the constants above).
+ */
+export function lpFeeToProtocol(shareModel, _createdAt, _cluster) {
+    return shareModel;
+}
 /** The wSOL mint, which stands for native SOL on the bridge. */
 export const NATIVE_MINT = 'So11111111111111111111111111111111111111112';
 export const TOKEN_PROGRAM_ID = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
@@ -99,9 +142,11 @@ export const FIXED_ADDRESSES = {
     kitEventAuthority: '9abhxVTuwck5Ux79act3e2Vkfem7Q4zBwATMctUvHvuE',
     /** `["hook-authority"]` under the kit: it signs the token program's `write_hook_data` in `claim`. */
     kitHookAuthority: '2repKA1JgDkBo4AffscVee342dcBcH6c2yfpUTRrAiEN',
+    /** `["__event_authority"]` under the companion program. */
+    companionEventAuthority: '7QuoYRuD9MHzX5EN7qqj62iwNPVqfy74RzmwJ524cgDt',
 };
 /**
- * The protocol lookup table (docs/hooks-v2.md §6; programs-summary §2.7): the 18 fixed addresses
+ * The protocol lookup table (docs/hooks-v2.md §6; programs-summary §2.7): the 22 fixed addresses
  * no top-level instruction invokes, in the order the programs' tests load them and `pnpm admin
  * init` must write them (a v0 message names table entries by index). Programs a transaction
  * invokes at top level (the kit for claims and shares) are kept in the static keys by the v0
@@ -126,6 +171,12 @@ export const PROTOCOL_LOOKUP_TABLE_ADDRESSES = [
     FIXED_ADDRESSES.bridgedSolMint,
     SYSTEM_PROGRAM_ID,
     ASSOCIATED_TOKEN_PROGRAM_ID,
+    // Appended 2026-10-08 for launches through a companion (docs/companions.md): the companion's event
+    // authority and the programs it invokes, so its launch transaction fits (1,142 bytes instead of 1,266).
+    FIXED_ADDRESSES.companionEventAuthority,
+    PROGRAM_IDS.launch,
+    PROGRAM_IDS.swap,
+    PROGRAM_IDS.token,
 ];
 /** Token hook flags (`Mint.hookFlags`). */
 export const TOKEN_HOOK_FLAGS = {

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.4.0",
+  "version": "0.6.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",