@bordrless/shared 0.5.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;
 }
@@ -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,94 @@ 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;
 }
-/** The companion templates (`COMPANION_TEMPLATES` in the SDK). */
+/** 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;
     mint: Address;
@@ -619,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 {

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

@@ -16,6 +16,25 @@ 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";
 };
 /**
  * Half-Life, Bordrless's own token hook (programs/half_life/README.md): the `LaunchConfig` the

package/dist/programs.js

@@ -16,6 +16,25 @@ 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',
 };
 /**
  * Half-Life, Bordrless's own token hook (programs/half_life/README.md): the `LaunchConfig` the

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.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",