@bordrless/shared 0.8.0 → 0.9.0

package/README.md

@@ -21,14 +21,19 @@ npm install @bordrless/shared
 ```ts
 import { PROGRAM_IDS, FIXED_ADDRESSES, TOKEN_HOOK_FLAGS, POOL_HOOK_FLAGS, RULE_BOUNDS } from '@bordrless/shared';
 
-PROGRAM_IDS.token; // the token program (devnet and localnet; mainnet gets its own keys at deploy time)
+PROGRAM_IDS.token; // the token program (one set of ids on every cluster)
 TOKEN_HOOK_FLAGS.BEFORE_TRANSFER | TOKEN_HOOK_FLAGS.TRANSFER_RETURNS_DELTA;
 ```
 
+A hook of your own launches from a config only when nobody outside Bordrless can upgrade it:
+immutable, or held by one of `HOOK_UPGRADE_AUTHORITIES` (Bordrless Studio's key or the protocol's),
+as the launch program checks. `hookFinalCommand(programId)` gives the `solana program
+set-upgrade-authority --final` command that makes it immutable after deploying, and
+`hookAuthorityAccepted` is the same check off chain.
+
 ## Where to read more
 
 - The SDK page: https://bordrless.app/sdk
 - The standard in full: https://bordrless.app/docs
 
-Status: the programs run on localnet and devnet until they are deployed to mainnet; they keep an
-upgrade authority until audited.
+Status: the programs are live on mainnet; they keep an upgrade authority until audited.

package/dist/api.d.ts

@@ -3,6 +3,7 @@
  * (`Amount`), dollar figures as numbers, times as unix seconds. A figure the backend could not
  * read is null, never zero.
  */
+import type { WorkshopReading } from './workshop.ts';
 export type Address = string;
 /** Base units, as a decimal string. */
 export type Amount = string;
@@ -100,6 +101,29 @@ export interface LaunchRulesInput {
  * token hook flags, and who can upgrade that program (null when it cannot be upgraded, or when it
  * has not been read). The site labels such a token "Custom hook, unverified" on every surface.
  */
+/** A hook's code, upgrade authority and attestations read from the chain. checkedAt is Unix seconds. */
+export interface HookRiskStatus {
+    status: 'available' | 'unavailable';
+    checkedAt: number;
+    class?: 'immutable' | 'timelocked' | 'managed' | 'author' | 'missing';
+    delaySecs?: number | null;
+    pending?: {
+        hash: string;
+        eta: number;
+    } | null;
+    audited?: 'current' | 'stale' | false;
+    blocked?: boolean;
+    provenance?: 'protocol' | 'studio' | 'unattested' | 'none';
+    studio?: {
+        buildHash: string;
+        simPass: boolean;
+        cutMaxBps: number;
+        current: boolean;
+        revoked?: boolean;
+    } | null;
+    severity: 'low' | 'medium' | 'high';
+    words: string;
+}
 export interface CustomHookInfo {
     program: Address;
     flags: number;
@@ -109,6 +133,42 @@ export interface CustomHookInfo {
     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;
+    /** Live code and attestation status, including hooks built outside Studio. */
+    risk?: HookRiskStatus | null;
+    /**
+     * Bordrless's own words for a Workshop hook (`HookReading`), filled on a launch's own page
+     * (`LaunchDetail`): null for a hook deployed outside the Workshop; absent from older servers and
+     * from lists.
+     */
+    workshop?: HookReading | null;
+}
+/**
+ * Bordrless's own words for a custom hook or companion that came through the Workshop, wherever a
+ * launcher or a buyer meets it (the owner, 2026-10-12: the site reads and puts official wording from
+ * Bordrless's checks, like "it takes 2% of every sell by a wallet over $1,000"): the item (its page
+ * is /workshop/<id>), the AI's reading of its source (what it does, the most it takes, what to
+ * watch), the largest cut of one transfer the trading test measured (a hook; null for a companion,
+ * which has no trading test) and the security review's verdict (`pass`: no finding above low;
+ * `warn`: passed with notes; `fail`: only in the reading lane, where the words are shown anyway).
+ * Served for an item that is approved and deployed (the Workshop lane), or matched (the reading
+ * lane, docs/workshop.md "The reading lane": the builder deployed the program themselves, and the
+ * words show while the code on chain stays the build Bordrless checked).
+ */
+export interface HookReading {
+    workshopId: string;
+    name: string;
+    author: Address;
+    /** A hook on trades (a hook item, or a pair's hook half), or a companion on the creator fee (a companion item, or a pair's script half). */
+    kind: 'hook' | 'companion';
+    reading: WorkshopReading | null;
+    measuredCutBps: number | null;
+    verdict: 'pass' | 'warn' | 'fail' | null;
+    /** Who approved it: the checks ('auto', a clean pass) or the operator; null for items approved before that was kept, and for the reading lane (nothing is approved). */
+    approvedBy?: 'auto' | 'operator' | null;
+    /** `workshop`: Bordrless deployed it under its own key; `reading`: its builder deployed it, and Bordrless read the source that matches it. Absent from older servers: `workshop`. */
+    lane?: 'workshop' | 'reading';
+    /** With a `fail` verdict: the titles of the review's first findings (the most severe first), for the site to say what failed. Absent otherwise. */
+    findings?: string[];
 }
 /**
  * Bordrless's official summary of a hook Studio deployed: written once by the assistant from the
@@ -139,6 +199,7 @@ export interface HookMeasured {
  */
 export interface HookAbout {
     program: Address;
+    risk?: HookRiskStatus | null;
     /** 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). */
@@ -178,6 +239,7 @@ export interface LaunchConfigData {
         program: Address;
         flags: number; /** As `CustomHookInfo.about`. */
         about?: HookAbout | null;
+        risk?: HookRiskStatus | null;
     } | null;
     label: string;
 }
@@ -209,10 +271,49 @@ export interface ConfigInspection {
     /**
      * The hook is a game hook made in Studio (docs/games.md "Phase 2"): its kind and the constants
      * its source fixes. The config then launches a jackpot or streak coin through the companion
-     * (`companion.game` of that kind); null or absent for any other hook.
+     * (`companion.game` of that kind); null or absent for any other hook, and for a Workshop pair's
+     * hook (its own script stands in for the game companion: `requiredCompanion`).
      */
     game?: import('./studio.ts').StudioGameSettings | null;
+    /**
+     * The companion a launch of this config must come with (the shape the on-chain `LaunchConfig`
+     * field will take, docs/HANDOFF-2026-10-12.md §4.5): `game` when the config's hook is a game hook
+     * (what `game` says), `script` when its hook belongs to a Workshop pair (docs/workshop.md
+     * "Pairs": the launch sends `companion.script` with that program, or is refused
+     * `companion_required`), else `none`. Absent from older servers.
+     */
+    requiredCompanion?: RequiredCompanion;
+    /**
+     * Bordrless's own words for the config's custom hook (`HookReading`) when it is a Workshop hook
+     * (or a pair's hook) that is approved and deployed; null for a hook deployed outside the
+     * Workshop, or one no longer approved. Absent from older servers.
+     */
+    hook?: HookReading | null;
 }
+/** What a config's launch must come with: nothing in particular, a game of a kind, or a Workshop pair's script. */
+export type RequiredCompanion = {
+    kind: 'none';
+} | {
+    kind: 'game';
+    game: GameKindName;
+} | {
+    kind: 'script';
+    /** The pair's companion script program: what `companion.script.program` must be (a preset's: the script its launch request names, `companion.lossCover` for Lossback). */
+    program: Address;
+    /** The pair's Workshop item (its page is /workshop/<id>), its name, its reading's title and its author. A Bordrless preset (`preset`) has no item and no author: both null. */
+    workshopId: string | null;
+    name: string;
+    title: string | null;
+    author: Address | null;
+    /** A Bordrless preset the config's hook belongs to: `lossCover` (docs/loss-cover.md; the site says Lossback), whose launch request is `companion.lossCover`, not `companion.script`. Absent for a pair and from older servers. */
+    preset?: 'lossCover';
+    /** Bordrless's reading of the pair (one for both halves), as `HookReading.reading`. Absent from older servers. */
+    reading?: WorkshopReading | null;
+    /** A companion script has no trading test: never a measured cut. */
+    measuredCutBps?: null;
+    /** The script half's security review verdict, as `HookReading.verdict`. Absent from older servers. */
+    verdict?: 'pass' | 'warn' | null;
+};
 /** Live figures of a launch's token rules; each null when the launch lacks the rule or it is not tracked. */
 export interface RuleStats {
     /** Lamports distributed to holders as holder rewards, all time. */
@@ -257,6 +358,8 @@ export interface ProgramInfo {
     /** Phase 3a: present (true) when the upgrade authority is the program's own `hook_timelock` account. */
     timelocked?: boolean;
 }
+/** Who a launch's creator fee goes to, read from the chain (docs/companions.md "Who may hold a launch's creator fee on the site"): a wallet, the companion program's pot, a program nobody can upgrade (shown, labelled), or a program someone can still upgrade (the launch is hidden). Null until read. */
+export type CreatorKind = 'wallet' | 'companion' | 'program' | 'program-immutable';
 export interface LaunchSummary {
     mint: Address;
     name: string;
@@ -264,6 +367,8 @@ export interface LaunchSummary {
     image: string | null;
     description: string;
     creator: Address;
+    /** Who the creator fee goes to; absent from older servers. */
+    creatorKind?: CreatorKind | null;
     pool: Address;
     status: LaunchStatus;
     createdAt: number;
@@ -305,6 +410,8 @@ export interface LaunchSummary {
     config: Address | null;
     /** The creator's own token hook (§5.8); null when the mint's hook is the kit or none. */
     customHook: CustomHookInfo | null;
+    /** The program that is this launch's creator (docs/companions.md), as a list names it: null for a launch whose creator is a wallet; absent from an older backend. `LaunchDetail.companion` has its live figures. */
+    companionTag?: CompanionTag | null;
     /** How Bordrless is paid on this launch's pool: 'share' (a share of what the rules collect, `protocolShareBps`) or 'flat' (`protocolFeeBps` of the quote). */
     protocolModel: ProtocolModel;
     /** Under the share model, Bordrless's share of the cuts in basis points (2,500 = a quarter); null under the flat model. */
@@ -352,7 +459,8 @@ export interface LaunchDetail extends LaunchSummary {
 /** `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';
 /** `GET /v1/launches?rules=a,b`: only launches that have every rule listed (`custom_hook`: launched with a creator's own hook). */
-export type RuleFilter = 'rewards' | 'burn' | 'max_wallet' | 'creator_lock' | 'early_lock' | 'custom_hook';
+/** The board's filters: kit rules, and the pre-built hooks by name (2026-10-12: Snowball, the Jackpot draw, Half-Life, buy back & burn, the Workshop's last-buyer and streak games, Lossback as `loss_cover`). `custom_hook` stays for older links. */
+export type RuleFilter = 'rewards' | 'burn' | 'max_wallet' | 'creator_lock' | 'early_lock' | 'custom_hook' | 'snowball' | 'jackpot' | 'last_buyer' | 'streak' | 'half_life' | 'buyback' | 'loss_cover';
 export interface LaunchList {
     launches: LaunchSummary[];
     total: number;
@@ -587,10 +695,238 @@ export type CompanionRequest = {
     split: CompanionSplitBps;
     vestDays?: number;
     game?: GameRequest;
+    snowball?: SnowballRequest;
+    script?: ScriptRequest;
+    lossCover?: LossCoverRequest;
 } | {
     template: CompanionTemplate;
     vestDays?: number;
 };
+/**
+ * A Lossback coin as the launch request names it (docs/loss-cover.md; the programs and the policy
+ * say Loss cover): the companion's pot pays every holder under water the same share of what they
+ * are down, in rounds of `roundSecs`, once the pot holds `minPotLamports`; a holding counts from
+ * `minHolding` base units and gets `coverBps` of its loss covered when the pot can. The split's
+ * buyback and holders' parts are 0; the pot's part is what the split's launcher part leaves
+ * (10,000 with a launcher part of 0). Everything else (the step, the shares per step, holding and
+ * round, the least loss, the wait after a buy) is fixed by `LOSS_COVER_DEFAULTS`. Bounds:
+ * `lossCoverProblem`. Refused (`companion_rules`) beside a game, a Snowball or a script, and
+ * (`loss_cover_off`) while Lossback launches are closed or the creator fee has no config.
+ */
+export interface LossCoverRequest {
+    roundSecs: number;
+    minPotLamports: Amount;
+    coverBps: number;
+    minHolding: Amount;
+}
+/**
+ * The terms a Lossback coin runs on, as the chain holds them: the script's six (`CoverState`:
+ * `coverBps`, `minHolding`, `minLossLamports`, `minAgeSecs`, `roundSecs`, `minPotLamports`), the
+ * companion's payout terms (`PayoutTerms`: `stepBps`, `holdingBps`, `roundBps` is `window_bps`,
+ * the window is the round) and the step (`Script.interval`).
+ */
+export interface LossCoverTerms {
+    roundSecs: number;
+    stepSecs: number;
+    stepBps: number;
+    holdingBps: number;
+    roundBps: number;
+    coverBps: number;
+    minHolding: Amount;
+    minLossLamports: Amount;
+    minAgeSecs: number;
+    minPotLamports: Amount;
+}
+/** A Lossback coin's figures as its token page shows them (`CompanionSummary.lossCover`), read from the chain and the indexer's payouts. */
+export interface LossCoverSummary {
+    /** The hook program, its state for the mint (`["state", mint]`), the script program, its state (`["script-state", mint]`) and the payout terms (`["payout-terms", mint]`). */
+    hook: Address;
+    hookState: Address;
+    script: Address;
+    scriptState: Address;
+    termsAddress: Address;
+    /** The pot (`Companion.pendingPot`), lamports. */
+    pot: Amount;
+    /** Lamports paid to holders all time, and entries recorded all time (touches included), the terms'. */
+    paidTotal: Amount;
+    payouts: number;
+    /** Distinct holdings paid above 0 so far (the indexer's `script_payouts`). */
+    holdersCovered: number;
+    /** The round the script last stepped in (0 before the first), and the round the clock is in now. */
+    round: number;
+    currentRound: number;
+    /** The share of its uncovered loss each holder is paid this round: `min(10,000, b / l_prev)` in basis points; 0 in a round that only measures. */
+    roundShareBps: number;
+    /** The round's budget (the pot at its first step), what it has paid and what is left. */
+    roundBudget: Amount;
+    roundPaid: Amount;
+    roundBudgetLeft: Amount;
+    /** The uncovered loss measured over the previous round (what this round's share is computed from) and so far this round. */
+    lossPrev: Amount;
+    lossCur: Amount;
+    /** Holdings measured this round, and rounds stepped so far. */
+    measured: number;
+    rounds: number;
+    /** When the round the script last stepped in began (0 before the first), when the current round ends, when a holder was last paid (0: never), when the next step may run. */
+    lastRoundAt: number;
+    nextRoundAt: number;
+    lastPaidAt: number;
+    nextStepAt: number;
+    /** Whether the pot holds the least a round starts with. */
+    minPotMet: boolean;
+    terms: LossCoverTerms;
+}
+/**
+ * `GET /v1/companion/:mint/cover/:owner`: one holder's own cover on a Lossback coin, from the
+ * holding's record (the hook data), the pool's price now and the script's round.
+ */
+export interface LossCoverHoldingSummary {
+    owner: Address;
+    holding: Address;
+    /** Whether the owner holds the token (a holding with a record); every figure is 0 without one. */
+    holds: boolean;
+    /** Tokens held, base units; the tokens the record covers (the balance as of its last write). */
+    balance: Amount;
+    recorded: Amount;
+    /** The average entry price (lamports per base unit times 10^12) and in SOL per whole token; the pool's price now the same way. */
+    entry: Amount;
+    entrySolPerToken: number;
+    spot: Amount;
+    spotSolPerToken: number;
+    /** Lamports the holding is down (0 above water), the part the cover applies to, what it has been paid, and what it is still owed. */
+    loss: Amount;
+    covered: Amount;
+    paid: Amount;
+    owed: Amount;
+    /** What the current round would pay it at the round's share, lamports (0 in a measuring round, or when not eligible). */
+    payNow: Amount;
+    /** Whether a step would take it now, and why not in one sentence. */
+    eligible: boolean;
+    reason: string | null;
+    /** The round it was last measured or paid in (0: never), whether that is the current round, and when the holding's wait after its last buy ends. */
+    lastRound: number;
+    paidThisRound: boolean;
+    countsFrom: number;
+    /** The current round, and when it ends. */
+    round: number;
+    nextRoundAt: number;
+}
+/**
+ * A custom companion as the launch request names it (2026-10-12, docs/scripts.md): a Workshop
+ * script (`program`, a companion item that Bordrless approved, deployed and approved on chain)
+ * decides what the companion's pot does. The pot is `potBps` of every creator-fee claim (with the
+ * split's parts it adds up to 10,000); the companion calls the script's `companion_step` at most
+ * once every `interval` seconds (10 to a day), from a minute after the launch; `initData` is what
+ * the script's `companion_init` gets once (base64 or hex, at most 512 bytes; empty for none) and
+ * `stateLen` the size of the state the companion makes for it (0 to 10,240 bytes; the Workshop
+ * item's reading says what the script needs). Bounds: `scriptProblem`. Refused (`companion_rules`)
+ * beside a game or a Snowball, and (`script_not_approved`) when the program is not an approved,
+ * deployed Workshop companion whose on-chain approval holds.
+ */
+export interface ScriptRequest {
+    potBps: number;
+    program: Address;
+    interval: number;
+    initData: string;
+    stateLen: number;
+}
+/** A custom companion's script as its token page shows it (`CompanionSummary.script`), read from the chain and the Workshop. */
+export interface ScriptSummary {
+    /** Its account, `PDA(["script", mint])` under the companion program. */
+    address: Address;
+    /** The script program (a Workshop companion item's, deployed under Bordrless's key). */
+    program: Address;
+    /** Its author, paid half of what every fee claim takes from the launch; null when none (or the author launched it themselves: no extra share). */
+    author: Address | null;
+    /** The least time between steps, seconds. */
+    interval: number;
+    /** When it last stepped (unix seconds; 0: not yet). */
+    lastAt: number;
+    /** When the next step may run (a minute after the launch at the earliest). */
+    nextStepAt: number;
+    /** Steps run so far. */
+    steps: number;
+    /** SOL the script may spend (the companion's pot), lamports. */
+    pot: Amount;
+    /** The pot's part of every fee claim. */
+    potBps: number;
+    /** What the author has been paid so far, lamports. */
+    authorPaid: Amount;
+    /** The size of the script's state the companion made, bytes (0: none). */
+    stateLen: number;
+    /** The Workshop item it came from: its id (its page is /workshop/<id>), name and the AI reading's title; null for a script approved outside the Workshop. */
+    workshopId: string | null;
+    name: string | null;
+    title: string | null;
+    /**
+     * Whether Bordrless checked and approved the code: a Workshop script. False for an immutable
+     * program launched unreviewed (docs/scripts.md "Unreviewed scripts": no Workshop item, no author,
+     * no author's share), which the site names "Custom hook (unreviewed)". Absent from older servers.
+     */
+    reviewed?: boolean;
+    /** Bordrless's reading of the Workshop item it came from (`HookReading.reading`); null for a script outside the Workshop. Absent from older servers. */
+    reading?: WorkshopReading | null;
+    /** The security review's verdict of that item (`HookReading.verdict`; `fail` only in the reading lane); null for a script outside the Workshop. Absent from older servers. */
+    verdict?: 'pass' | 'warn' | 'fail' | null;
+    /**
+     * `reading` when the script was deployed by its builder (immutable, outside the Workshop) and a
+     * reading-lane item matches its code: Bordrless's words show with `reviewed` false. Absent for a
+     * Workshop script and from older servers.
+     */
+    lane?: 'workshop' | 'reading';
+}
+/**
+ * A Snowball companion as the launch request names it (2026-10-12): the companion's part of every
+ * creator fee claim (`potBps`; with the split's parts it adds up to 10,000) fills a pot that makes
+ * volume in the token on its own pool, once every `interval` seconds: a buy of `buyBps` of the pot
+ * when the price falls `buyStepBps` below its reference, a sell of `sellBps` of its tokens when it
+ * rises `sellStepBps` above, and with `flatTrades` a trade anyway when it hasn't moved (on the side
+ * that rebalances what it holds). One trade moves at most `poolBps` of the pool's SOL side. The
+ * presets are `SNOWBALL_PRESETS`; bounds `snowballProblem`.
+ */
+export interface SnowballRequest {
+    potBps: number;
+    buyStepBps: number;
+    sellStepBps: number;
+    buyBps: number;
+    sellBps: number;
+    poolBps: number;
+    interval: number;
+    flatTrades: boolean;
+}
+/** A Snowball's terms without its part of the fee: what a preset sets and the custom controls change. */
+export type SnowballTerms = Omit<SnowballRequest, 'potBps'>;
+/** A Snowball's market maker as its token page shows it (`CompanionSummary.snowball`), read from the chain. */
+export interface SnowballSummary {
+    /** Its account, `PDA(["snowball", mint])` under the companion program. */
+    address: Address;
+    buyStepBps: number;
+    sellStepBps: number;
+    buyBps: number;
+    sellBps: number;
+    /** The most one trade moves, as a share of the pool's SOL side. */
+    poolBps: number;
+    /** The least time between trades, seconds. */
+    interval: number;
+    /** It trades every interval even when the price hasn't moved. */
+    flatTrades: boolean;
+    /** SOL it holds to buy with (the companion's pot), lamports. */
+    pot: Amount;
+    /** Tokens it holds to sell, base units. */
+    tokensHeld: Amount;
+    /** The next buy waits for the price at or below `buyBelow`, the next sell at or above `sellAbove` (SOL per whole token). */
+    buyBelow: number;
+    sellAbove: number;
+    buys: number;
+    sells: number;
+    /** SOL spent on buys and received from sells, lamports; tokens bought and sold, base units. */
+    solSpent: Amount;
+    solReceived: Amount;
+    tokensBought: Amount;
+    tokensSold: Amount;
+    /** When it last traded or followed the price (unix seconds; 0: not yet). */
+    lastAt: number;
+}
 /** The kinds of game a companion runs (the companion's `GameKind`): the lottery (phase 1), the last-buyer jackpot and the holding streak (phase 2). */
 export type GameKindName = 'lottery' | 'jackpot' | 'streak' | 'strategy';
 /**
@@ -864,6 +1200,24 @@ export interface CompanionSplitBps {
     /** Paid to the launcher (the beneficiary), in SOL. */
     beneficiaryBps: number;
 }
+/**
+ * A launch's companion as a list names it (2026-10-12): what takes its creator fee, fixed at launch, without
+ * the live figures (`CompanionSummary` has those), so a card can say "Snowball 2%" without reading the chain.
+ */
+export interface CompanionTag {
+    split: CompanionSplitBps;
+    /** The game it runs and the pot's part of every fee claim; null without a game. */
+    game: {
+        kind: GameKindName;
+        potBps: number;
+    } | null;
+    /** A Snowball: its pot makes a market in the token (its part of the fee is what the split leaves). */
+    snowball: boolean;
+    /** A custom companion (2026-10-12): a Workshop script spends its pot. Absent from tags stored before scripts. */
+    script?: boolean;
+    /** A Lossback coin (docs/loss-cover.md): its script is the Loss cover script. Absent from tags stored before Lossback, and from every other tag. */
+    lossCover?: boolean;
+}
 /** 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. */
@@ -900,6 +1254,12 @@ export interface CompanionSummary {
     nextBuybackAt: number | null;
     /** The lottery this companion runs (docs/games.md): its settings and the hook's terms; null for a companion without a game. */
     game: GameSummary | null;
+    /** A Snowball's market maker (2026-10-12); null for any other companion. */
+    snowball: SnowballSummary | null;
+    /** A custom companion's script (2026-10-12, docs/scripts.md); null for any other companion; absent from older servers. */
+    script?: ScriptSummary | null;
+    /** A Lossback coin's figures (docs/loss-cover.md); null for any other companion (a Lossback coin's `script` is set too); absent from older servers. */
+    lossCover?: LossCoverSummary | null;
 }
 /**
  * `GET /v1/companion/:mint`: a mint's companion as a launch that may not have finished needs it.
@@ -915,6 +1275,10 @@ export interface CompanionStatus {
     refundable: Amount | null;
     /** The lottery this companion runs, live (docs/games.md), the caller's tickets with `?wallet=`; null for a companion without a game (absent from older servers). */
     game?: GameStatus | null;
+    /** A custom companion's script, once launched (docs/scripts.md); null for any other companion (absent from older servers, and before the launch). */
+    script?: ScriptSummary | null;
+    /** A Lossback coin's figures, once launched (docs/loss-cover.md); null for any other companion (absent from older servers, and before the launch). */
+    lossCover?: LossCoverSummary | 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 {
@@ -1135,6 +1499,140 @@ export interface LiquidityPrepareResponse {
     transactions: PreparedTx[];
     quote: LiquidityQuote;
 }
+/** Which of a mint's four authorities (`set_authority`'s kinds). */
+export type MintAuthorityKind = 'mint' | 'freeze' | 'hook' | 'metadata';
+/** One fact of a mint's risk label (docs/dex.md §6.2), in the words every surface uses. */
+export interface MintRiskReason {
+    kind: 'hook_missing' | 'hook_authority' | 'freeze_authority' | 'mint_authority' | 'hook' | 'metadata_authority' | 'fixed';
+    severity: 'low' | 'medium' | 'high';
+    words: string;
+}
+/** A mint's risk label: the highest severity, its first sentence, every reason, and the authorities still held (and by whom). */
+export interface MintRisk {
+    severity: 'low' | 'medium' | 'high';
+    words: string;
+    reasons: MintRiskReason[];
+    /** The authorities still set on the mint, each with its key. */
+    held: {
+        kind: MintAuthorityKind;
+        authority: Address;
+    }[];
+}
+/** The base token of a pool to be created, as the mint account has it. */
+export interface PoolCreateToken {
+    mint: Address;
+    symbol: string;
+    name: string;
+    decimals: number;
+    image: string | null;
+    supply: Amount;
+    /** 0 when unlimited. */
+    maxSupply: Amount;
+    creator: Address;
+    hookProgram: Address | null;
+    /** How the site names it (from addresses, never from names): a launch of the launchpad, a bridged asset, or a free mint. */
+    identity: 'launch' | 'bridged' | 'free';
+}
+/** A pool of the same pair that exists already: the depth, the price and the tier. */
+export interface ExistingPool {
+    pool: Address;
+    lpFeeBps: number;
+    hookProgram: Address | null;
+    /** The launchpad made it: its launch pool. */
+    launch: boolean;
+    curve: boolean;
+    baseReserve: Amount;
+    quoteReserve: Amount;
+    /** Whole quote per whole token; null while the pool has no reserves. */
+    priceQuote: number | null;
+    tvlUsd: number | null;
+}
+export interface PoolCreateQuoteRequest {
+    baseMint: Address;
+    /** One of `POOL_FEE_TIERS_BPS`. */
+    lpFeeBps: number;
+    /** The wallet, for its balances; the quote stands without one. */
+    owner?: Address;
+    /** Base units of the token to deposit. */
+    baseAmount?: Amount;
+    /** Lamports of SOL (bridged in the same transaction) to deposit. */
+    quoteAmount?: Amount;
+}
+/** The first deposit as quoted: the price it sets, the LP it mints and the FDV it implies. */
+export interface PoolCreateDeposit {
+    baseAmount: Amount;
+    quoteAmount: Amount;
+    /** `isqrt(base · quote) − 1,000`, 9 decimals. */
+    lpAmount: Amount;
+    /** Whole SOL per whole token. */
+    priceQuote: number;
+    /** Fully diluted value in lamports (the price times `maxSupply`, or `supply` when unlimited), as a decimal string. */
+    fdvLamports: Amount;
+    fdvUsd: number | null;
+}
+export interface PoolCreateQuote {
+    token: PoolCreateToken;
+    quoteMint: Address;
+    quoteSymbol: string;
+    quoteDecimals: number;
+    lpFeeBps: number;
+    /** The DEX config's flat protocol rate of the quote side, which the new pool copies at creation. */
+    protocolFeeBps: number;
+    /** The pool this pair, tier and no hook would live at. */
+    pool: Address;
+    lpMint: Address;
+    /** That pool, when it exists already (the form then offers to add liquidity instead). */
+    exists: ExistingPool | null;
+    /** Every other pool of the pair (the launch pool, other tiers, hooked ones), deepest first. */
+    otherPools: ExistingPool[];
+    /** The wallet's balances, with an owner. */
+    balances: {
+        lamports: Amount;
+        base: Amount;
+        bridgedSol: Amount;
+    } | null;
+    deposit: PoolCreateDeposit | null;
+    risk: MintRisk;
+    /** Rent the creator pays for the new accounts (the pool, the LP mint, two vaults, the LP holding, and the quote holding when missing). */
+    rentLamports: Amount;
+    solUsd: number | null;
+}
+export interface PoolCreatePrepareRequest {
+    owner: Address;
+    baseMint: Address;
+    lpFeeBps: number;
+    baseAmount: Amount;
+    quoteAmount: Amount;
+    /** Burn the LP in a second transaction, a permanent lock (docs/dex.md §5.1). */
+    burnLp?: boolean;
+}
+export interface PoolCreatePrepareResponse {
+    transactions: PreparedTx[];
+    quote: PoolCreateQuote;
+    pool: Address;
+    lpMint: Address;
+}
+/** Burn LP of a pool the wallet holds: all of it, or `amount` (9 decimals). */
+export interface LpBurnPrepareRequest {
+    owner: Address;
+    pool: Address;
+    amount?: Amount;
+}
+export interface LpBurnPrepareResponse {
+    transactions: PreparedTx[];
+    /** LP burned, 9 decimals. */
+    amount: Amount;
+}
+/** Revoke authorities the wallet holds on a mint, for ever (`set_authority(kind, None)` for each). */
+export interface AuthorityPrepareRequest {
+    owner: Address;
+    mint: Address;
+    kinds: MintAuthorityKind[];
+}
+export interface AuthorityPrepareResponse {
+    transactions: PreparedTx[];
+    kinds: MintAuthorityKind[];
+}
 export interface ApiErrorBody {
     error: string;
     code?: string;

package/dist/api.js

@@ -1,8 +1,3 @@
-/**
- * The HTTP API between the site and the backend. Amounts in base units travel as decimal strings
- * (`Amount`), dollar figures as numbers, times as unix seconds. A figure the backend could not
- * read is null, never zero.
- */
 /** "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. */

package/dist/explorer.d.ts

@@ -0,0 +1,21 @@
+import type { ExplorerProgram } from './api.ts';
+/** Which group a program id belongs to: the five of Bordrless, or any other program the indexer follows (a token hook). */
+export declare function explorerProgramOf(programId: string): ExplorerProgram;
+/** The groups' names, as the explorer's filter and its chips print them. */
+export declare const EXPLORER_PROGRAM_NAMES: Readonly<Record<ExplorerProgram, string>>;
+/** A program's name: one of the five, a hook Bordrless wrote, or "Hook" for any other. */
+export declare function programLabel(programId: string): string;
+/** The IDL's PascalCase name from whatever case the coder stored (`transferred` -> `Transferred`). */
+export declare const eventName: (raw: string) => string;
+interface EventWords {
+    label: string;
+    /** The payload key naming the account the event is mostly about; null when it has none worth linking. */
+    subject: string | null;
+}
+/** Every event of the IDLs, by its PascalCase name (`ConfigSet` is three programs' and reads the same). */
+export declare const EVENT_WORDS: Readonly<Record<string, EventWords>>;
+/** An event's label in plain words; an unknown event's name with its words spaced (`SomethingNew` -> "Something new"). */
+export declare function eventLabel(name: string): string;
+/** The account an event is mostly about, read from its payload; null when the table names none or the payload lacks it. */
+export declare function eventSubject(name: string, payload: Record<string, unknown>): string | null;
+export {};