@bordrless/shared 0.9.0 → 0.10.0

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 {};