@bordrless/shared 0.9.0 → 0.10.0

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 { RulesReadout } from './rules.ts';
 import type { WorkshopReading } from './workshop.ts';
 export type Address = string;
 /** Base units, as a decimal string. */
@@ -141,6 +142,32 @@ export interface CustomHookInfo {
      * from lists.
      */
     workshop?: HookReading | null;
+    /**
+     * A composed hook's rule set (docs/rules-lane.md §4): the hook is the rules engine and the set is
+     * the `RuleSet` bound to the launch's config, as the chain holds it (`RulesReadout`: its bytes and
+     * what they say). The one place the set travels: `workshop` beside it is the synthetic reading
+     * (`lane: 'rules'`, the words alone). Null for any other hook, or a set that could not be read;
+     * absent from older servers and from lists.
+     */
+    rules?: RulesReadout | null;
+    /**
+     * Its SOL cut (`QuoteCutInfo`), read live from the launch on a launch's own page (`LaunchDetail`):
+     * null when the launch takes none or could not be read; absent from older servers and from lists.
+     */
+    quoteCut?: QuoteCutInfo | null;
+}
+/**
+ * A custom hook's SOL cut (the launchpad of 13 Oct: a config made with `create_quote_cut_config`): on
+ * a trade the launchpad asks the hook for a rate, at most its side's cap, and takes it from the
+ * trade's SOL with the creator fee (a buy's SOL in, a sell's SOL out). It takes no tokens, and a send
+ * pays none of it.
+ */
+export interface QuoteCutInfo {
+    /** The caps, basis points of the trade's SOL (each at most 1,000). */
+    maxBuyBps: number;
+    maxSellBps: number;
+    /** SOL the cut has taken so far, lamports (part of the creator fees); '0' for a config, which has taken nothing. */
+    takenLamports: Amount;
 }
 /**
  * Bordrless's own words for a custom hook or companion that came through the Workshop, wherever a
@@ -152,7 +179,10 @@ export interface CustomHookInfo {
  * `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).
+ * words show while the code on chain stays the build Bordrless checked). A composed hook
+ * (docs/rules-lane.md §4) answers a synthetic one: `lane` and `verdict` `rules`, its words read
+ * from the rule set bound to the config (the set itself is `customHook.rules`), no measured cut,
+ * and `workshopId` '' while it is not listed.
  */
 export interface HookReading {
     workshopId: string;
@@ -162,11 +192,12 @@ export interface HookReading {
     kind: 'hook' | 'companion';
     reading: WorkshopReading | null;
     measuredCutBps: number | null;
-    verdict: 'pass' | 'warn' | 'fail' | null;
+    /** `rules`: a composed hook's, read from its rules (no review, no build, no trading test). */
+    verdict: 'pass' | 'warn' | 'fail' | 'rules' | 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';
+    /** `workshop`: Bordrless deployed it under its own key; `reading`: its builder deployed it, and Bordrless read the source that matches it; `rules`: composed from Bordrless rules and run by the rules engine. Absent from older servers: `workshop`. */
+    lane?: 'workshop' | 'reading' | 'rules';
     /** 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[];
 }
@@ -237,9 +268,12 @@ export interface LaunchConfigData {
     creatorFeeBps: number;
     customHook: {
         program: Address;
-        flags: number; /** As `CustomHookInfo.about`. */
+        flags: number;
+        /** As `CustomHookInfo.about`. */
         about?: HookAbout | null;
         risk?: HookRiskStatus | null;
+        /** As `CustomHookInfo.rules`: a composed hook's rule set, read from the `RuleSet` bound to this config; null for any other hook or an unbound one. Absent from older servers. */
+        rules?: RulesReadout | null;
     } | null;
     label: string;
 }
@@ -285,8 +319,9 @@ export interface ConfigInspection {
     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.
+     * (or a pair's hook) that is approved and deployed, or a composed hook's synthetic reading
+     * (`lane: 'rules'`; its set is `config.customHook.rules`); null for a hook deployed outside the
+     * Workshop, one no longer approved, or the rules engine with no set bound. Absent from older servers.
      */
     hook?: HookReading | null;
 }
@@ -691,7 +726,7 @@ export interface LaunchPrepareRequest {
  * preset splits by name; with `game`, a lottery coin (docs/games.md): the split's holders' share is
  * then 0 and the pot's part (`game.potBps`) makes the four add up to 10,000.
  */
-export type CompanionRequest = {
+export type CompanionRequest = ({
     split: CompanionSplitBps;
     vestDays?: number;
     game?: GameRequest;
@@ -701,7 +736,35 @@ export type CompanionRequest = {
 } | {
     template: CompanionTemplate;
     vestDays?: number;
-};
+}) & CompanionExtras;
+/**
+ * What any companion request may add (2026-10-13, docs/payees-and-wallet-payouts.md), each set once
+ * before the launch, the mint signing:
+ * - `payees`: up to 10 wallets that share the launcher's part of the creator fee (the split's
+ *   `beneficiaryBps`), each a fixed share of that part (1 to 10,000 basis points, 10,000 in all at
+ *   most); the launcher keeps the rest. Not the launcher, the companion or its creator address, each
+ *   named once. Bounds: `payeesProblem`. The setup carries `set_payees`, in its own transaction when
+ *   the setup leaves no room (a Lossback or custom hook's setup).
+ * - `allowWalletPayouts`: a custom hook's script with payout terms (`script.payout`, made with
+ *   `create_script_v2`) may also pay any wallet SOL from the pot, within those terms. Refused
+ *   (`companion_rules`) on any other companion: `walletPayoutsProblem`.
+ */
+export interface CompanionExtras {
+    payees?: PayeeRequest[];
+    allowWalletPayouts?: boolean;
+}
+/** A wallet that shares the launcher's part of the creator fee (`set_payees`): its share of that part, basis points. */
+export interface PayeeRequest {
+    wallet: Address;
+    bps: number;
+}
+/** A payee as the token page shows it (`CompanionSummary.payees`): its share of the launcher's part, what it was paid and what it is owed (its account could not take it yet), lamports. */
+export interface PayeeSummary {
+    wallet: Address;
+    bps: number;
+    paid: Amount;
+    owed: Amount;
+}
 /**
  * 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
@@ -744,7 +807,7 @@ export interface LossCoverSummary {
     hookState: Address;
     script: Address;
     scriptState: Address;
-    termsAddress: Address;
+    payoutTerms: Address;
     /** The pot (`Companion.pendingPot`), lamports. */
     pot: Amount;
     /** Lamports paid to holders all time, and entries recorded all time (touches included), the terms'. */
@@ -829,6 +892,20 @@ export interface ScriptRequest {
     interval: number;
     initData: string;
     stateLen: number;
+    /** Payout terms (2026-10-13): the script is made with `create_script_v2`, its payouts bound by them; absent, `create_script` (no payouts). Bounds: `scriptProblem`. */
+    payout?: PayoutTermsRequest;
+}
+/**
+ * A script's payout terms as a launch request names them (the companion's `PayoutTerms`, made by
+ * `create_script_v2`): the most one step pays (`stepBps` of the pot at the step's start), the most
+ * one holding or wallet gets of a step's budget (`holdingBps`), and the most a window pays
+ * (`windowBps` of the pot at the window's first step), the window `windowSecs` long (10 s to a day).
+ */
+export interface PayoutTermsRequest {
+    stepBps: number;
+    holdingBps: number;
+    windowBps: number;
+    windowSecs: number;
 }
 /** A custom companion's script as its token page shows it (`CompanionSummary.script`), read from the chain and the Workshop. */
 export interface ScriptSummary {
@@ -874,6 +951,8 @@ export interface ScriptSummary {
      * Workshop script and from older servers.
      */
     lane?: 'workshop' | 'reading';
+    /** Its payout terms let it pay any wallet SOL from the pot (`allow_wallet_payouts`, `PayoutTerms.reserved[0]`, 2026-10-13); absent otherwise and from older servers. */
+    walletPayouts?: true;
 }
 /**
  * A Snowball companion as the launch request names it (2026-10-12): the companion's part of every
@@ -1260,6 +1339,8 @@ export interface CompanionSummary {
     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;
+    /** The wallets that share the launcher's part (`set_payees`, 2026-10-13); null for a companion without payees (or whose payees can't be read); absent from older servers. */
+    payees?: PayeeSummary[] | null;
 }
 /**
  * `GET /v1/companion/:mint`: a mint's companion as a launch that may not have finished needs it.

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from './api.ts';
 export * from './explorer.ts';
+export * from './keeper.ts';
 export * from './policy.ts';
 export * from './programs.ts';
+export * from './rules.ts';
 export * from './studio.ts';
 export * from './workshop.ts';

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from "./api.js";
 export * from "./explorer.js";
+export * from "./keeper.js";
 export * from "./policy.js";
 export * from "./programs.js";
+export * from "./rules.js";
 export * from "./studio.js";
 export * from "./workshop.js";

package/dist/keeper.d.ts

@@ -0,0 +1,139 @@
+/** The file, at the root of the submitted source (beside `src/`): a companion script's, or a pair's companion half's. */
+export declare const KEEPER_FILE = "keeper.json";
+/** The schema's version: the only one there is. */
+export declare const KEEPER_VERSION = 1;
+/** The bounds a declaration is held to. */
+export declare const KEEPER_LIMITS: {
+    /** The file's bytes (UTF-8). */
+    readonly bytes: 4096;
+    /** Holdings one step may bring (the keeper brings fewer when a step would not fit one transaction). */
+    readonly perStep: 16;
+    /** A round or an epoch, seconds: from the shortest step interval to a year. */
+    readonly minSecs: 10;
+    readonly maxSecs: 31536000;
+    /** The unit a hook-data field counts time in, seconds (an epoch's stamp: 300 for five minutes). */
+    readonly maxUnitSecs: 31536000;
+    /** Wallets a step may bring (about 12 fit one transaction beside the protocol's lookup table on a plain coin; the keeper brings fewer when they do not). */
+    readonly wallets: 12;
+};
+/** Bytes of an unsigned little-endian field. */
+export type KeeperWidth = 1 | 2 | 4 | 8;
+/** An unsigned little-endian field of the script's own state account (`PDA(["script-state", mint])` under the companion), read fresh at each step. */
+export interface KeeperStateField {
+    offset: number;
+    width: KeeperWidth;
+}
+/** A balance or a constant in base units: a string of digits, or a field of the script's state. */
+export type KeeperAmount = string | {
+    state: KeeperStateField;
+};
+/** A length of time in seconds: a whole number, or a field of the script's state. */
+export type KeeperSeconds = number | {
+    state: KeeperStateField;
+};
+export type KeeperCompare = 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte';
+export declare const KEEPER_COMPARES: readonly KeeperCompare[];
+/**
+ * What a hook-data field is compared with: the pool's price now (the companion's scale, 10^12 per
+ * token unit, as `companionSpotPrice` reads it), a constant, or the current epoch, floor(now / secs).
+ * With `fieldUnitSecs`, the field counts units of that many seconds (a hook that stamps
+ * floor(now / 300)) and is compared in the epoch's own units: floor(field × fieldUnitSecs / secs).
+ */
+export type KeeperAgainst = 'poolPrice' | {
+    const: string;
+} | {
+    epoch: {
+        secs: KeeperSeconds;
+        fieldUnitSecs: number | null;
+    };
+};
+/** A filter on each holding's hook data: the unsigned little-endian field of `width` bytes at `offset`, compared with `against`. A holding passes when `field <compare> against` holds. */
+export interface KeeperHookDataFilter {
+    offset: number;
+    width: KeeperWidth;
+    compare: KeeperCompare;
+    against: KeeperAgainst;
+}
+/**
+ * Where each holding a step brings is paid: `owner` (its owner's wallet, writable, after the
+ * holding), `ownerQuoteHolding` (its owner's bridged-SOL holding under the Bordrless token program,
+ * `holdingAddress(BRIDGED_SOL_MINT, owner)`, writable, after the holding; a holder without one is
+ * passed over), or `none` (the holding alone).
+ */
+export type KeeperPayTo = 'none' | 'owner' | 'ownerQuoteHolding';
+export declare const KEEPER_PAY_TO: readonly KeeperPayTo[];
+export interface KeeperHoldings {
+    /** The least balance that counts, base units (at least 1). */
+    minBalance: KeeperAmount;
+    /** The most balance that counts, base units, inclusive; null: no most. */
+    maxBalance: KeeperAmount | null;
+    hookData: KeeperHookDataFilter | null;
+    payTo: KeeperPayTo;
+    /** Holdings a step brings when it carries the swap accounts, and when it does not (the one `swapAccounts` names is required; null: not said). */
+    perStep: {
+        withSwapAccounts: number | null;
+        withoutSwapAccounts: number | null;
+    };
+}
+/**
+ * A wallet a step brings for the script's wallet answers: a fixed address (base58), or the public key
+ * in the 32 bytes at `offset` of the script's state, read fresh at each step (all zeros: none that step).
+ */
+export type KeeperWallet = string | {
+    state: {
+        offset: number;
+    };
+};
+/** A declaration in its normal form: what `parseKeeperDeclaration` answers, what the Workshop stores and hashes, what the keeper reads. */
+export interface KeeperDeclaration {
+    version: 1;
+    /** Which holdings a step brings; null: none (only beside `wallets`: a script that pays wallets alone). */
+    holdings: KeeperHoldings | null;
+    /** Each step carries the launch pool's swap accounts (what trading the pot needs; they hold the token's hook accounts too). */
+    swapAccounts: boolean;
+    /** A step without the swap accounts carries the token's custom hook accounts (its program, the token program's signer for it, its registry's extras): what moving the token inside a step needs. */
+    hookAccounts: boolean;
+    /** Each step carries the companion's payout accounts (`companion.payoutAccounts`): a script whose answers the companion pays and its hook records. */
+    payouts: boolean;
+    /** The round the keeper's cursor rotates by; null: none (the cursor never starts over). */
+    roundSecs: KeeperSeconds | null;
+    /**
+     * The wallets each step brings (writable, with the payout terms) while the script's terms allow
+     * wallet payouts (`allowWalletPayouts`), at most `KEEPER_LIMITS.wallets`. Absent when none: left out
+     * of the normal form, so a declaration approved before wallets existed hashes as it did.
+     */
+    wallets?: KeeperWallet[];
+}
+export type KeeperParse = {
+    ok: true;
+    declaration: KeeperDeclaration;
+} | {
+    ok: false;
+    problem: string;
+};
+/** Whether a text is a public key in base58: exactly 32 bytes, as `new PublicKey` reads it (each leading "1" a zero byte). */
+export declare function isBase58Key(text: string): boolean;
+/** The declaration in a parsed JSON value, held to the schema and its bounds: its normal form, or why not, in one sentence. */
+export declare function keeperDeclarationOf(value: unknown): KeeperParse;
+/** Bytes of a text in UTF-8 (a lone surrogate counts as its replacement character, 3). */
+export declare function utf8Length(text: string): number;
+/** A `keeper.json` as submitted: within its size, JSON, then the schema (`keeperDeclarationOf`). */
+export declare function parseKeeperDeclaration(text: string): KeeperParse;
+/** The declaration in a canonical text (keys sorted, no spaces): what its hash is taken of, so the same declaration hashes the same however it was written. */
+export declare function canonicalKeeperJson(d: KeeperDeclaration): string;
+/** Whether a file of a submission is the declaration. */
+export declare const isKeeperFile: (path: string) => boolean;
+/** How many holdings a step brings as declared: with the swap accounts when it carries them, else without; 0 without holdings (a script that pays wallets alone). */
+export declare const keeperPerStep: (d: KeeperDeclaration) => number;
+/**
+ * The declaration in one plain sentence, for the item's page, the reading and the operator: "Each
+ * step brings up to 3 holders with under 20M tokens not yet paid this 5-minute epoch, paid to their
+ * SOL holding." An epoch whose length the script's state sets is "this epoch". The wallets a step
+ * brings follow in a sentence of their own.
+ */
+export declare function keeperWords(d: KeeperDeclaration, decimals?: number): string;
+/**
+ * The rest of the declaration, a sentence each, for the review and the operator: what else each
+ * step carries, and where a round's or an epoch's length comes from.
+ */
+export declare function keeperDetails(d: KeeperDeclaration): string[];