@bordrless/shared 0.8.0 → 0.10.0

package/dist/programs.d.ts

@@ -34,6 +34,22 @@ export declare const PROGRAM_IDS: {
      * permissionless crank under the companion's buyback guards. Not deployed yet (2026-10-09).
      */
     readonly hookVault: "5cojoUStG7WFhHJiSncCUEwTqDuhDLKu4a9BqTbF8jzG";
+    /**
+     * The Loss cover hook (programs/loss_cover_hook, docs/loss-cover.md §2; the site says Lossback):
+     * a Lossback coin's token hook, which keeps each holding's average entry price, the cover it was
+     * paid and the round it was last recorded in. Keypair generated 2026-10-12.
+     */
+    readonly lossCoverHook: "6KMdXC3Fxovp3pnUsdQuUbderPzZtTA4t6R1jacYJWQr";
+    /**
+     * The Loss cover script (programs/loss_cover_script, docs/loss-cover.md §3): the companion script
+     * of a Lossback coin, which names the holders under water and what each gets; the companion pays.
+     */
+    readonly lossCoverScript: "9mRXU9gpWY3B13AyuCCtNjHnKt1pUFBQ6vJDLTwgakhm";
+    /**
+     * The router (programs/bordrless_router, docs/router.md, 2026-10-13): an app's integrator fee on
+     * any DEX swap, at most 1% of the quote side, 20% of it to the DEX treasury.
+     */
+    readonly router: "7M5GTuzhByzBbrJURzLtbBrFjcsC8aHu816qWTXAYD85";
 };
 /**
  * Bordrless Studio's attester (phase 3a, docs/phase3a.md §6): a hot key of Studio's build worker,
@@ -64,6 +80,67 @@ export declare const LOTTERY_HOOK: {
 };
 /** The creator fees (basis points) a lottery coin can launch with: those with a `LaunchConfig` in `LOTTERY_HOOK.launchConfigs`. */
 export declare const lotteryFeeChoices: () => number[];
+/**
+ * The Loss cover hook's fixed facts (programs/loss_cover_hook, docs/loss-cover.md §2; the site
+ * says Lossback): the flags a `LaunchConfig` names for it (`BEFORE_TRANSFER | BEFORE_BURN |
+ * WRITES_HOOK_DATA`, the lottery hook's), the token program's signer of its callbacks
+ * (`["hook-authority", hook]` under the token program), its own `["hook-authority"]` (which signs
+ * the token program's `write_hook_data` in `record_payout`) with its bump, and the `LaunchConfig`s
+ * a Lossback coin launches from, one per creator fee, made by `pnpm admin loss-cover-configs`
+ * (which prints the lines to paste here); the backend lays
+ * `LOSS_COVER_LAUNCH_CONFIGS` over it.
+ */
+export declare const LOSS_COVER_HOOK: {
+    readonly program: "6KMdXC3Fxovp3pnUsdQuUbderPzZtTA4t6R1jacYJWQr";
+    readonly flags: 145;
+    readonly tokenHookSigner: "A2WKjdKC4PurtabNwhvKJvWdxKXLvt79qrzre7GE8XTe";
+    readonly hookAuthority: "J7duBVXCMbN1BLp4mt7myzVvRsvXRPU3BAhFyksDSPAm";
+    readonly hookAuthorityBump: 252;
+    readonly readme: "https://github.com/BordrlessDex/bordrless-programs/tree/main/programs/loss_cover_hook";
+    readonly launchConfigs: Readonly<Partial<Record<number, string>>>;
+};
+/**
+ * The rules engine's program id (`programs/rules_hook`, its keypair `keys/mainnet/rules_hook-keypair.json`):
+ * BUILT, NOT DEPLOYED YET (2026-10-12). The SDK builds `bind` and `prepare` for it; the lane opens
+ * only when `RULES_HOOK_PROGRAM` below is set to it, after the deploy lands.
+ */
+export declare const RULES_HOOK_PROGRAM_ID_MAINNET = "AfDhsethmkoimbyoSWnRfLtjFXZteRNtbFMioR9qWMjD";
+/**
+ * The rules engine (`programs/rules_hook`, docs/rules-lane.md): Bordrless's one token hook that
+ * runs a composed rule set bound to a launch config (`RuleSet` at `["rules", config]` under it).
+ * The lane's switch: a placeholder, the system program's id, until the engine is deployed, so
+ * nothing can name it as a hook (the launch program refuses the protocol's own programs), every
+ * check that compares a hook with it is false and the API answers `rules_closed`. Set to
+ * `RULES_HOOK_PROGRAM_ID_MAINNET` once the deploy lands; `RULES_HOOK.flags` are per rule set
+ * (`rulesFlagsOf`), never fixed.
+ */
+export declare const RULES_HOOK_PROGRAM: string;
+/** The engine's fixed facts, as the other hooks have them; `deployed` tells the site and the API whether the lane is live on chain (false while the id is the placeholder, the system program's). */
+export declare const RULES_HOOK: {
+    readonly program: string;
+    readonly deployed: boolean;
+    /** `RuleSet` seed under the engine, with the launch config. */
+    readonly ruleSetSeed: "rules";
+    /** The per-mint state seed, the template's. */
+    readonly stateSeed: "state";
+    /** The engine's id once deployed (`RULES_HOOK_PROGRAM_ID_MAINNET`), and its PDAs: the token program's signer of its callbacks, and its `["hook-authority"]` (signs `write_hook_data` in `record_payout`). */
+    readonly programId: "AfDhsethmkoimbyoSWnRfLtjFXZteRNtbFMioR9qWMjD";
+    readonly tokenHookSigner: "FaU6drNBY2nayBkXiirtk5c29Hw3rqXMtv2K1La5V4cG";
+    readonly hookAuthority: "9SydDjwfgWaG8akwwsEpTpRpdoVZCtMYSeiqf6EkMdkK";
+    readonly hookAuthorityBump: 254;
+    /** The accounts' sizes: the `RuleSet` and the per-mint state. */
+    readonly ruleSetLen: 447;
+    readonly stateLen: 628;
+    readonly readme: "https://github.com/BordrlessDex/bordrless-programs/tree/main/programs/rules_hook";
+};
+/** The Loss cover script's fixed facts (programs/loss_cover_script, docs/loss-cover.md §3): its program and the size of the state `create_script_v2` must ask for. */
+export declare const LOSS_COVER_SCRIPT: {
+    readonly program: "9mRXU9gpWY3B13AyuCCtNjHnKt1pUFBQ6vJDLTwgakhm";
+    readonly stateLen: 128;
+    readonly readme: "https://github.com/BordrlessDex/bordrless-programs/tree/main/programs/loss_cover_script";
+};
+/** The creator fees (basis points) a Lossback coin can launch with: those with a `LaunchConfig` in `LOSS_COVER_HOOK.launchConfigs` (the backend's env adds to them). */
+export declare const lossCoverFeeChoices: () => number[];
 /**
  * Half-Life, Bordrless's own token hook (programs/half_life/README.md): the `LaunchConfig` the
  * launch form's Half-Life path launches from (no kit rules, creator fee 1%, the hook with
@@ -160,6 +237,8 @@ export declare const FIXED_ADDRESSES: {
     readonly kitHookAuthority: "2repKA1JgDkBo4AffscVee342dcBcH6c2yfpUTRrAiEN";
     /** `["__event_authority"]` under the companion program. */
     readonly companionEventAuthority: "7QuoYRuD9MHzX5EN7qqj62iwNPVqfy74RzmwJ524cgDt";
+    /** `["payout-authority"]` under the companion program (bump 251): the one signer of a hook's `record_payout` (docs/loss-cover.md §1); it signs nothing else. */
+    readonly companionPayoutAuthority: "8XJcBCYmYyggTQBNvK3RausfyRMpmtjJTjKd53W3StkG";
 };
 /**
  * The protocol lookup table (docs/hooks-v2.md §6; programs-summary §2.7): the 22 fixed addresses

package/dist/programs.js

@@ -34,6 +34,22 @@ export const PROGRAM_IDS = {
      * permissionless crank under the companion's buyback guards. Not deployed yet (2026-10-09).
      */
     hookVault: '5cojoUStG7WFhHJiSncCUEwTqDuhDLKu4a9BqTbF8jzG',
+    /**
+     * The Loss cover hook (programs/loss_cover_hook, docs/loss-cover.md §2; the site says Lossback):
+     * a Lossback coin's token hook, which keeps each holding's average entry price, the cover it was
+     * paid and the round it was last recorded in. Keypair generated 2026-10-12.
+     */
+    lossCoverHook: '6KMdXC3Fxovp3pnUsdQuUbderPzZtTA4t6R1jacYJWQr',
+    /**
+     * The Loss cover script (programs/loss_cover_script, docs/loss-cover.md §3): the companion script
+     * of a Lossback coin, which names the holders under water and what each gets; the companion pays.
+     */
+    lossCoverScript: '9mRXU9gpWY3B13AyuCCtNjHnKt1pUFBQ6vJDLTwgakhm',
+    /**
+     * The router (programs/bordrless_router, docs/router.md, 2026-10-13): an app's integrator fee on
+     * any DEX swap, at most 1% of the quote side, 20% of it to the DEX treasury.
+     */
+    router: '7M5GTuzhByzBbrJURzLtbBrFjcsC8aHu816qWTXAYD85',
 };
 /**
  * Bordrless Studio's attester (phase 3a, docs/phase3a.md §6): a hot key of Studio's build worker,
@@ -68,6 +84,72 @@ export const LOTTERY_HOOK = {
 };
 /** The creator fees (basis points) a lottery coin can launch with: those with a `LaunchConfig` in `LOTTERY_HOOK.launchConfigs`. */
 export const lotteryFeeChoices = () => Object.keys(LOTTERY_HOOK.launchConfigs).map(Number).filter((bps) => bps > 0);
+/**
+ * The Loss cover hook's fixed facts (programs/loss_cover_hook, docs/loss-cover.md §2; the site
+ * says Lossback): the flags a `LaunchConfig` names for it (`BEFORE_TRANSFER | BEFORE_BURN |
+ * WRITES_HOOK_DATA`, the lottery hook's), the token program's signer of its callbacks
+ * (`["hook-authority", hook]` under the token program), its own `["hook-authority"]` (which signs
+ * the token program's `write_hook_data` in `record_payout`) with its bump, and the `LaunchConfig`s
+ * a Lossback coin launches from, one per creator fee, made by `pnpm admin loss-cover-configs`
+ * (which prints the lines to paste here); the backend lays
+ * `LOSS_COVER_LAUNCH_CONFIGS` over it.
+ */
+export const LOSS_COVER_HOOK = {
+    program: PROGRAM_IDS.lossCoverHook,
+    flags: 145,
+    tokenHookSigner: 'A2WKjdKC4PurtabNwhvKJvWdxKXLvt79qrzre7GE8XTe',
+    hookAuthority: 'J7duBVXCMbN1BLp4mt7myzVvRsvXRPU3BAhFyksDSPAm',
+    hookAuthorityBump: 252,
+    readme: 'https://github.com/BordrlessDex/bordrless-programs/tree/main/programs/loss_cover_hook',
+    // Made 2026-10-12 22:26 UTC by `pnpm admin loss-cover-configs --send` (5xsib), no token rules, the Loss cover hook with flags 145.
+    launchConfigs: {
+        50: 'DCNLF3jvZvo6SMTa9dG8y2E7CgB7VZr2C5tQrs83HR84',
+        100: '8E1UWZ8PXYrWvfBNRxVSzceR4ywLmHQYAXvWZ4JkUhQZ',
+        200: '8PLEsXW4hbEfYXgtRWxZhe7nTvjeYR1XdY5ehKj8z3Xr',
+    },
+};
+/**
+ * The rules engine's program id (`programs/rules_hook`, its keypair `keys/mainnet/rules_hook-keypair.json`):
+ * BUILT, NOT DEPLOYED YET (2026-10-12). The SDK builds `bind` and `prepare` for it; the lane opens
+ * only when `RULES_HOOK_PROGRAM` below is set to it, after the deploy lands.
+ */
+export const RULES_HOOK_PROGRAM_ID_MAINNET = 'AfDhsethmkoimbyoSWnRfLtjFXZteRNtbFMioR9qWMjD';
+/**
+ * The rules engine (`programs/rules_hook`, docs/rules-lane.md): Bordrless's one token hook that
+ * runs a composed rule set bound to a launch config (`RuleSet` at `["rules", config]` under it).
+ * The lane's switch: a placeholder, the system program's id, until the engine is deployed, so
+ * nothing can name it as a hook (the launch program refuses the protocol's own programs), every
+ * check that compares a hook with it is false and the API answers `rules_closed`. Set to
+ * `RULES_HOOK_PROGRAM_ID_MAINNET` once the deploy lands; `RULES_HOOK.flags` are per rule set
+ * (`rulesFlagsOf`), never fixed.
+ */
+export const RULES_HOOK_PROGRAM = RULES_HOOK_PROGRAM_ID_MAINNET;
+/** The engine's fixed facts, as the other hooks have them; `deployed` tells the site and the API whether the lane is live on chain (false while the id is the placeholder, the system program's). */
+export const RULES_HOOK = {
+    program: RULES_HOOK_PROGRAM,
+    deployed: RULES_HOOK_PROGRAM !== '11111111111111111111111111111111',
+    /** `RuleSet` seed under the engine, with the launch config. */
+    ruleSetSeed: 'rules',
+    /** The per-mint state seed, the template's. */
+    stateSeed: 'state',
+    /** The engine's id once deployed (`RULES_HOOK_PROGRAM_ID_MAINNET`), and its PDAs: the token program's signer of its callbacks, and its `["hook-authority"]` (signs `write_hook_data` in `record_payout`). */
+    programId: RULES_HOOK_PROGRAM_ID_MAINNET,
+    tokenHookSigner: 'FaU6drNBY2nayBkXiirtk5c29Hw3rqXMtv2K1La5V4cG',
+    hookAuthority: '9SydDjwfgWaG8akwwsEpTpRpdoVZCtMYSeiqf6EkMdkK',
+    hookAuthorityBump: 254,
+    /** The accounts' sizes: the `RuleSet` and the per-mint state. */
+    ruleSetLen: 447,
+    stateLen: 628,
+    readme: 'https://github.com/BordrlessDex/bordrless-programs/tree/main/programs/rules_hook',
+};
+/** The Loss cover script's fixed facts (programs/loss_cover_script, docs/loss-cover.md §3): its program and the size of the state `create_script_v2` must ask for. */
+export const LOSS_COVER_SCRIPT = {
+    program: PROGRAM_IDS.lossCoverScript,
+    stateLen: 128,
+    readme: 'https://github.com/BordrlessDex/bordrless-programs/tree/main/programs/loss_cover_script',
+};
+/** The creator fees (basis points) a Lossback coin can launch with: those with a `LaunchConfig` in `LOSS_COVER_HOOK.launchConfigs` (the backend's env adds to them). */
+export const lossCoverFeeChoices = () => Object.keys(LOSS_COVER_HOOK.launchConfigs).map(Number).filter((bps) => bps > 0);
 /**
  * Half-Life, Bordrless's own token hook (programs/half_life/README.md): the `LaunchConfig` the
  * launch form's Half-Life path launches from (no kit rules, creator fee 1%, the hook with
@@ -176,6 +258,8 @@ export const FIXED_ADDRESSES = {
     kitHookAuthority: '2repKA1JgDkBo4AffscVee342dcBcH6c2yfpUTRrAiEN',
     /** `["__event_authority"]` under the companion program. */
     companionEventAuthority: '7QuoYRuD9MHzX5EN7qqj62iwNPVqfy74RzmwJ524cgDt',
+    /** `["payout-authority"]` under the companion program (bump 251): the one signer of a hook's `record_payout` (docs/loss-cover.md §1); it signs nothing else. */
+    companionPayoutAuthority: '8XJcBCYmYyggTQBNvK3RausfyRMpmtjJTjKd53W3StkG',
 };
 /**
  * The protocol lookup table (docs/hooks-v2.md §6; programs-summary §2.7): the 22 fixed addresses

package/dist/rules.d.ts

@@ -0,0 +1,353 @@
+/**
+ * The rules lane (docs/rules-lane.md): a custom hook composed as data and run by Bordrless's one
+ * rules engine (`rules_hook`). A rule set is a header and 1 to 6 rules of 48 bytes, little-endian,
+ * every field fixed-width (§1). This module is the lane's one reading of the bytes, shared by the
+ * SDK, the site, the API and the engine's own tests (`vectors/rules.json`):
+ *
+ * - the types and the enums as the doc numbers them (`RULE_VALUE_IDS`, `RULE_OP_IDS`, ...);
+ * - `encodeRules` / `decodeRules`, the exact byte layout of §1.2;
+ * - `validateRules`, every bound of §1 and §2.6 as a code and a plain sentence: the same codes the
+ *   engine's `bind` refuses with (`RULES_ERROR_TEXT` lists them);
+ * - `renderRules`, the pure reading of §3: the sentences, "the most it takes" per side (summed from
+ *   the rules, never measured), the flags and the generated watch lines;
+ * - `rulesFlagsOf`, the token hook flags a set needs; `rulesHookReading`, the synthetic reading in
+ *   the shape of `HookReading` (`lane: 'rules'`, `verdict: 'rules'`) every surface already shows.
+ *
+ * Wording follows the site's: numbers only, the site's units, no reassurance. Nothing here touches
+ * a chain: the SDK builds the instructions, the API reads the accounts.
+ */
+import type { HookReading } from './api.ts';
+import type { WorkshopReading } from './workshop.ts';
+export declare const RULES_VERSION = 1;
+/** The header, then each rule, then each atom slot (§1.2). */
+export declare const RULES_HEADER_BYTES = 8;
+export declare const RULE_BYTES = 48;
+export declare const ATOM_BYTES = 10;
+export declare const RULE_ATOM_SLOTS = 4;
+export declare const RULES_LIMITS: {
+    /** Rules in a set. */
+    readonly rules: 6;
+    /** `when` atoms a rule may have; `unless` atoms. */
+    readonly when: 3;
+    readonly unless: 1;
+    /** A cut, basis points of the amount; the cuts of one side summed. */
+    readonly cutBps: 1500;
+    readonly sideCutBps: 1500;
+    /** `entry_cap_bps` (§1.2): checked by `bind`, applied nowhere (a buy's entry is what it paid). */
+    readonly entryCapBps: 5000;
+    /** A set's bytes: `8 + 48 * 6`. */
+    readonly bytes: 296;
+    /** Composed hooks one wallet may list in a day (the Workshop's allowance). */
+    readonly perDay: 6;
+    /** Literals, by unit (§1.2). A price is any u64. */
+    readonly literal: {
+        readonly bps: 10000n;
+        readonly seconds: 31536000n;
+        readonly lamports: 10000000000000n;
+        readonly baseUnits: bigint;
+        readonly count: 65535n;
+        readonly flag: 1n;
+        readonly price: bigint;
+    };
+};
+export type RuleSide = 'sell' | 'buy' | 'send' | 'receive' | 'burn';
+export declare const RULE_SIDES: readonly RuleSide[];
+/** `on`'s bits. */
+export declare const RULE_SIDE_BITS: Record<RuleSide, number>;
+export type RuleValueName = 'amount' | 'amountShare' | 'balanceBefore' | 'balanceAfter' | 'shareAfter' | 'tradePrice' | 'spotPrice' | 'gain' | 'loss' | 'valueBefore' | 'valueAfter' | 'sinceReceived' | 'sinceSent' | 'age' | 'firstAfterLaunch' | 'sinceLaunch' | 'counter' | 'graduated' | 'hasEntry' | 'flag0' | 'flag1' | 'flag2' | 'flag3';
+/** The values a rule can see (§1.1), by id. */
+export declare const RULE_VALUE_IDS: Record<RuleValueName, number>;
+export type RuleUnit = 'baseUnits' | 'bps' | 'price' | 'lamports' | 'seconds' | 'count' | 'flag';
+/** Each value's unit, which bounds its literal. */
+export declare const RULE_VALUE_UNITS: Record<RuleValueName, RuleUnit>;
+export type RuleKeep = 'entry' | 'times' | 'count';
+/** The header's `keeps` bits. */
+export declare const RULE_KEEP_BITS: Record<RuleKeep, number>;
+/** What each value needs the engine to keep (§2.3); null for one computed from the operation, the pool or the clock alone. */
+export declare const RULE_VALUE_KEEPS: Record<RuleValueName, RuleKeep | null>;
+export type RuleOpName = 'lt' | 'le' | 'gt' | 'ge' | 'eq' | 'ne';
+export declare const RULE_OP_IDS: Record<RuleOpName, number>;
+export type RuleActionKind = 'cut' | 'refuse' | 'count' | 'flag';
+export declare const RULE_ACTION_IDS: Record<RuleActionKind, number>;
+export type RefuseReason = 'cooling' | 'cap' | 'locked' | 'rule';
+export declare const REFUSE_REASON_IDS: Record<RefuseReason, number>;
+export type CountWhat = 'add' | 'reset';
+export declare const COUNT_ARG_IDS: Record<CountWhat, number>;
+/** A FLAG's `arg`: bits 0..1 which flag, bit 4 set (1) or clear (0). */
+export declare const FLAG_SET_BIT = 16;
+export type RuleDestination = 'none' | 'burn' | 'creator' | 'named';
+export declare const RULE_DESTINATION_IDS: Record<RuleDestination, number>;
+export interface Atom {
+    value: RuleValueName;
+    op: RuleOpName;
+    /** Unsigned 64-bit, in the value's unit. */
+    literal: bigint;
+}
+export type Action = {
+    kind: 'cut';
+    bps: number;
+} | {
+    kind: 'refuse';
+    reason: RefuseReason;
+} | {
+    kind: 'count';
+    what: CountWhat;
+} | {
+    kind: 'flag';
+    flag: 0 | 1 | 2 | 3;
+    set: boolean;
+};
+export interface Rule {
+    on: RuleSide[];
+    when: Atom[];
+    unless: Atom | null;
+    then: Action;
+    /** Ends the walk when this rule fires. */
+    stop: boolean;
+}
+export interface RuleKeeps {
+    entry: boolean;
+    times: boolean;
+    count: boolean;
+}
+export interface RuleSet {
+    version: number;
+    keeps: RuleKeeps;
+    /** 0, or 1 to 5,000 with an entry kept: checked by `bind` and kept in the bytes, applied nowhere (the engine records a buy's entry at the trade's own price, uncapped). */
+    entryCapBps: number;
+    destination: RuleDestination;
+    rules: Rule[];
+}
+/** Every refusal of the engine's `bind` (§2.6), by code; `RULES_ERROR_TEXT` says each in a sentence. */
+export type RulesErrorCode = 'length' | 'version' | 'rule_count' | 'keeps' | 'destination' | 'side' | 'value' | 'op' | 'action' | 'arg' | 'when_count' | 'unless_count' | 'slot' | 'literal' | 'cut_bps' | 'cut_on_burn' | 'cut_destination' | 'side_total' | 'keeps_entry' | 'keeps_times' | 'keeps_count' | 'entry_cap' | 'refuse_when' | 'refuse_marks' | 'destination_wallet' | 'config_hook' | 'config_flags' | 'config_kit_rules' | 'config_creator';
+export declare const RULES_ERROR_TEXT: Record<RulesErrorCode, string>;
+export declare const RULES_ERROR_CODES: readonly RulesErrorCode[];
+/** One refusal: its code, the rule it is about (0-based; null for the set), and the sentence. */
+export interface RulesProblem {
+    code: RulesErrorCode;
+    rule: number | null;
+    text: string;
+}
+export declare class RulesError extends Error {
+    readonly code: RulesErrorCode;
+    readonly rule: number | null;
+    constructor(code: RulesErrorCode, rule?: number | null);
+}
+export declare const rulesBytesLength: (ruleCount: number) => number;
+/** `on` as its mask. */
+export declare const sideMask: (on: readonly RuleSide[]) => number;
+/** A mask as its sides, in the doc's order; unknown bits are dropped (the validator refuses them). */
+export declare const sidesOf: (mask: number) => RuleSide[];
+export declare const keepsMask: (k: RuleKeeps) => number;
+/** An action's `(action, arg, bps)` bytes. */
+export declare function actionBytes(a: Action): {
+    action: number;
+    arg: number;
+    bps: number;
+};
+/**
+ * The set's bytes (§1.2): the header, then each rule, its `when` atoms in the first slots and its
+ * `unless` in the next, the rest zero. Encodes what it is given; `validateRules` says whether the
+ * engine will take it. Throws `RulesError` only for what has no encoding (more atoms than slots, a
+ * literal past u64, more than 255 rules).
+ */
+export declare function encodeRules(set: RuleSet): Uint8Array;
+/**
+ * A set from its bytes, refusing with the engine's own code what the layout cannot hold: the
+ * length, the version, the count, unknown keeps bits, an unknown destination, side, value, op,
+ * action or arg, counts past 3 and 1, a filled slot beyond them, a `bps` on an action that is not a
+ * cut. The bounds that need the whole set (`validateRules`) are checked after; `checkRulesBytes`
+ * does both.
+ */
+export declare function decodeRules(bytes: Uint8Array): RuleSet;
+export declare const rulesToHex: (bytes: Uint8Array) => string;
+export declare function rulesFromHex(hex: string): Uint8Array;
+/** The bound a value's literal keeps to. */
+export declare const literalBound: (value: RuleValueName) => bigint;
+/** Whether a value turns on a holding's own marks (a flag or the counter): never enough for a refusal of a sell, a send or a burn (§2.6). */
+export declare const isMarkValue: (value: RuleValueName) => boolean;
+/**
+ * Every refusal of §2.6 that the bytes alone do not catch, in order, each once per rule: the codes
+ * the engine's `bind` answers with. Empty when the engine will take the set. `validateRules` reads
+ * a typed set; `checkRulesBytes` decodes first.
+ */
+export declare function validateRules(set: RuleSet): RulesProblem[];
+/** Decodes and validates: the problems, or the set. */
+export declare function checkRulesBytes(bytes: Uint8Array): {
+    set: RuleSet;
+    problems: RulesProblem[];
+} | {
+    set: null;
+    problems: RulesProblem[];
+};
+/** The set, or the first refusal thrown (the builder's `build`). */
+export declare function assertRules(set: RuleSet): RuleSet;
+/**
+ * The token hook flags a set needs (`flags_for`, §2): `BEFORE_TRANSFER` always;
+ * `TRANSFER_RETURNS_DELTA` with any cut; `BEFORE_BURN` with any rule on burns (so a burn rule runs
+ * even in a set that keeps nothing); `BEFORE_BURN | WRITES_HOOK_DATA` with any keeps bit, a count
+ * or a mark. The config must name exactly these (`config_flags`).
+ */
+export declare function rulesFlagsOf(set: RuleSet): number;
+/** A fixed-point value with `decimals`, rounded half up to `places`, trailing zeros trimmed, the whole part grouped. */
+export declare function decimalWords(value: bigint, decimals: number, places: number): string;
+/** Basis points as a percent: 500 -> 5%, 25 -> 0.25%, 1,500 -> 15%. */
+export declare const pctWords: (bps: bigint | number) => string;
+/** Lamports as SOL, to three places: 6,500,000,000 -> 6.5. */
+export declare const solWords: (lamports: bigint) => string;
+/** Base units as whole tokens (to six places when not whole), with the ticker, or "tokens". */
+export declare const tokenWords: (base: bigint, symbol: string | null | undefined) => string;
+/** A price (lamports per base unit times 10^12) as SOL per whole token: `p * 10^decimals / 10^21`. */
+export declare const priceWords: (price: bigint) => string;
+/** A length of time in a sentence: a minute, 10 minutes, an hour, 6 hours, a day, 30 days, 30 seconds. With `article` false, the noun alone for one unit: "the first minute", "the first day". */
+export declare function durationWords(secs: bigint | number, article?: boolean): string;
+/** A wallet address shortened for a sentence. */
+export declare const shortWallet: (wallet: string) => string;
+/** The words of a rule's sides: one ("sell or transfer"), many ("sells or transfers"), the verbs of a refusal ("sell or send"). */
+export interface SideWords {
+    one: string;
+    many: string;
+    verbs: string;
+}
+export declare function sideWords(on: readonly RuleSide[]): SideWords;
+interface Phrase {
+    /** After "every sell": "by a holder in profit". */
+    when: string;
+    /** After "A wallet": "that received tokens less than an hour ago". */
+    relative: string;
+    /** After "cannot sell or send": "until an hour after launch" (the launch clock alone); null otherwise. */
+    trailing: string | null;
+    /** As an unless clause: "unless in profit", "until graduation". */
+    unless: string;
+    /** The second sentence of a cut with this one condition; null when there is none to say. */
+    complement: ((w: SideWords) => string) | null;
+}
+/** The phrases of one atom (the table of §3, every value and op given a reading so the function is total). */
+export declare function phraseOf(atom: Atom, symbol: string | null | undefined): Phrase;
+export interface RenderOptions {
+    /** The named destination's wallet, for the sentence; absent: "a named wallet". */
+    destinationWallet?: string | null;
+    /** The ticker, for amounts; absent: "tokens". */
+    symbol?: string | null;
+}
+/** The most a set takes per side, basis points of the amount, summed over every cut rule on the side, conditions and `stop` ignored (§3). */
+export interface MostTakes {
+    sell: number;
+    buy: number;
+    /** A transfer's sender and receiver cuts together (both sides answer in one return). */
+    transfer: number;
+    /** The largest of the three. */
+    bps: number;
+    /** "5% of a sell; nothing from buys or transfers", or "Takes nothing." */
+    text: string;
+}
+/** What `renderRules` gives: the sentences in rule order (one or two per rule), the worst case, the flags, the generated notes and what the set keeps. */
+export interface RulesWords {
+    sentences: string[];
+    mostTakes: MostTakes;
+    flags: number;
+    watch: WorkshopReading['watch'];
+    /** What the engine keeps per holding for this set, in words; empty when nothing. */
+    keeps: string[];
+}
+/** One rule's sentences (one or two), per §3's templates. */
+export declare function renderRule(r: Rule, set: RuleSet, opts?: RenderOptions): string[];
+/** The most a set takes per side (§3): summed, never measured. */
+export declare function mostTakesOf(set: RuleSet): MostTakes;
+/** What the engine keeps for a set, in words. */
+export declare function keepsWords(set: RuleSet): string[];
+/**
+ * The reading of a set (§3): the sentences in rule order, the most it takes, the flags and the
+ * generated notes. Total and deterministic: the same bytes give the same words in the SDK, on the
+ * site, in the API and in the engine's tests.
+ */
+export declare function renderRules(set: RuleSet, opts?: RenderOptions): RulesWords;
+/** The lane's own words on the site: the lane, its verdict word and the line over a composed hook's sentences. */
+export declare const RULES_LANE = "rules";
+export declare const RULES_VERDICT_WORD = "Read from its rules";
+export declare const RULES_COMPOSED_LINE = "Composed from Bordrless rules";
+/** What the inspection says of a config that names the engine with no rules bound (§4). */
+export declare const RULES_UNBOUND_PROBLEM = "This config names the rules engine but has no rules bound: it cannot launch.";
+/** The set as the API carries it beside the sentences (`RulesReadout`): the bytes (hex) and what they say. */
+export interface RulesReadout {
+    version: number;
+    bytes: string;
+    sentences: string[];
+    mostTakes: MostTakes;
+    flags: number;
+    destination: RuleDestination;
+    destinationWallet: string | null;
+    keeps: RuleKeep[];
+    entryCapBps: number;
+}
+/**
+ * The reading of a composed hook in the shape every surface already shows (`HookReading`), with the
+ * lane's own lane and verdict words: `reading.does` the sentences, `total` the computed figure (never
+ * measured: `measuredCutBps` null), `watch` the generated notes, and `rules` the set itself. The API
+ * serves the words alone (`rulesReadingWords`) and the set once, as `customHook.rules`.
+ */
+export interface RulesHookReading extends Omit<HookReading, 'verdict' | 'lane' | 'measuredCutBps' | 'kind' | 'reading'> {
+    kind: 'hook';
+    /** Always present: the words are the bytes. */
+    reading: WorkshopReading;
+    verdict: 'rules';
+    lane: 'rules';
+    measuredCutBps: null;
+    rules: RulesReadout;
+}
+export interface RulesReadingOptions extends RenderOptions {
+    /** The config's label, else "Composed hook". */
+    name?: string | null;
+    /** Who bound the set. */
+    author?: string | null;
+    /** The Workshop item it is listed as, when it is; '' otherwise. */
+    workshopId?: string | null;
+    /** When it was bound, unix seconds. */
+    at?: number | null;
+}
+export declare function rulesReadout(set: RuleSet, opts?: RenderOptions): RulesReadout;
+export declare function rulesHookReading(set: RuleSet, opts?: RulesReadingOptions): RulesHookReading;
+/** Whether a reading the API answered is the lane's synthetic one (served without the set: `rulesReadingWords`). */
+export declare const isRulesReading: (r: unknown) => r is HookReading & {
+    lane: "rules";
+    verdict: "rules";
+};
+/** The reading as the API serves it (`ConfigInspection.hook`, `CustomHookInfo.workshop`): the words alone; the set itself travels once, as `customHook.rules`. */
+export declare function rulesReadingWords(r: RulesHookReading): HookReading;
+/**
+ * A `REFUSE` rule fails the operation with its reason's error (`1 cooling, 2 cap, 3 locked, 4 rule`).
+ * `RULES_REFUSAL_ERRORS` are the engine's error names, the ones the starter's `HookError` spells too
+ * (held to the engine's IDL by the SDK's tests); the API names a trade or a send the engine refused
+ * by `RULES_REFUSAL_CODES`, with `RULES_REFUSAL_TEXT`; the site's trade panel says its own line from
+ * the token's own rules (`rulesRefusalLine`).
+ */
+export declare const RULES_REFUSAL_ERRORS: Readonly<Record<RefuseReason, string>>;
+export declare const RULES_REFUSAL_CODES: Readonly<Record<RefuseReason, string>>;
+export declare const RULES_REFUSAL_TEXT: Readonly<Record<RefuseReason, string>>;
+/** The reason of an engine error by its name (`CoolingDown`); null for any other error. */
+export declare const refuseReasonOfError: (name: string | null | undefined) => RefuseReason | null;
+/** The reason of an API error code (`rules_cooling`); null for any other code. */
+export declare const refuseReasonOfCode: (code: string | null | undefined) => RefuseReason | null;
+/**
+ * The engine's errors by number, as its IDL lists them: `bind`'s refusals first, 6000 plus their
+ * place in `RULES_ERROR_CODES` (`length` 6000 ... `config_creator` 6028), then the four reasons
+ * (`CoolingDown` 6029, `OverCap` 6030, `Locked` 6031, `Refused` 6032), then its own. A log names
+ * the error too (`Error Code: CoolingDown`), which `refuseReasonOfError` reads.
+ */
+export declare const RULES_ENGINE_ERRORS: Readonly<Record<number, string>>;
+/** The engine's error number of a refusal of `bind` (`config_flags` -> 6026). */
+export declare const rulesErrorNumber: (code: RulesErrorCode) => number;
+/** The refusal of `bind` an engine error number stands for; null for any other number. */
+export declare function rulesErrorCodeOfNumber(n: number): RulesErrorCode | null;
+/** The engine's error numbers of the four reasons. */
+export declare const RULES_REFUSAL_NUMBERS: Readonly<Record<RefuseReason, number>>;
+/** The reason of an engine error number (6029 -> `cooling`); null for any other number. */
+export declare const refuseReasonOfNumber: (n: number) => RefuseReason | null;
+/**
+ * What a refused operation says, from the set that refused it: the first `REFUSE` rule with that
+ * reason on that side (else on any side). A cooldown on the time since tokens arrived says it the
+ * trade panel's way ("Tokens that arrived less than an hour ago can’t be sold yet."); any other is
+ * the rule's own sentence. Null when the set has no such rule.
+ */
+export declare function rulesRefusalLine(set: RuleSet, reason: RefuseReason, side: RuleSide, opts?: RenderOptions): string | null;
+export {};