@bordrless/shared 0.8.0 → 0.10.0

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

package/dist/explorer.js

@@ -0,0 +1,94 @@
+/**
+ * The explorer's words for the chain: each program's name, each IDL event's label in plain words
+ * and the account it is mostly about, in one table the backend and the site both read (the backend
+ * picks an event's subject with it; the site prints its label with the raw name as a title).
+ *
+ * Event names are the IDLs' (`packages/sdk/idl/*.json`), PascalCase; the SDK's coder gives them
+ * camelCase, which `eventName` undoes. An event the table does not know keeps its raw name, spaced.
+ */
+import { PROGRAM_IDS } from "./programs.js";
+/** Which group a program id belongs to: the five of Bordrless, or any other program the indexer follows (a token hook). */
+export function explorerProgramOf(programId) {
+    switch (programId) {
+        case PROGRAM_IDS.token:
+            return 'token';
+        case PROGRAM_IDS.swap:
+            return 'swap';
+        case PROGRAM_IDS.bridge:
+            return 'bridge';
+        case PROGRAM_IDS.launch:
+            return 'launch';
+        case PROGRAM_IDS.kit:
+            return 'kit';
+        default:
+            return 'hook';
+    }
+}
+/** The groups' names, as the explorer's filter and its chips print them. */
+export const EXPLORER_PROGRAM_NAMES = { token: 'Token', swap: 'DEX', bridge: 'Bridge', launch: 'Launchpad', kit: 'Kit', hook: 'Hook' };
+/** A program's name: one of the five, a hook Bordrless wrote, or "Hook" for any other. */
+export function programLabel(programId) {
+    if (programId === PROGRAM_IDS.taxHook)
+        return 'Tax hook';
+    if (programId === PROGRAM_IDS.halfLife)
+        return 'Half-Life';
+    return EXPLORER_PROGRAM_NAMES[explorerProgramOf(programId)];
+}
+/** The IDL's PascalCase name from whatever case the coder stored (`transferred` -> `Transferred`). */
+export const eventName = (raw) => (raw ? `${raw.charAt(0).toUpperCase()}${raw.slice(1)}` : raw);
+/** Every event of the IDLs, by its PascalCase name (`ConfigSet` is three programs' and reads the same). */
+export const EVENT_WORDS = {
+    // token
+    MintCreated: { label: 'Mint created', subject: 'mint' },
+    HoldingCreated: { label: 'Holding opened', subject: 'holding' },
+    Transferred: { label: 'Transfer', subject: 'mint' },
+    Minted: { label: 'Mint', subject: 'mint' },
+    Burned: { label: 'Burn', subject: 'mint' },
+    HookSet: { label: 'Hook set', subject: 'mint' },
+    AuthoritySet: { label: 'Authority set', subject: 'mint' },
+    MetadataUpdated: { label: 'Metadata updated', subject: 'mint' },
+    HoldingClosed: { label: 'Holding closed', subject: 'holding' },
+    DelegateSet: { label: 'Delegate set', subject: 'holding' },
+    FrozenSet: { label: 'Freeze changed', subject: 'holding' },
+    HookDataWritten: { label: 'Hook data written', subject: 'holding' },
+    // swap
+    PoolCreated: { label: 'Pool created', subject: 'pool' },
+    Swapped: { label: 'Swap', subject: 'pool' },
+    LiquidityAdded: { label: 'Liquidity added', subject: 'pool' },
+    LiquidityRemoved: { label: 'Liquidity removed', subject: 'pool' },
+    CurveFinalized: { label: 'Curve finalized', subject: 'pool' },
+    ProtocolFeesCollected: { label: 'Protocol fees collected', subject: 'pool' },
+    ConfigSet: { label: 'Config set', subject: 'admin' },
+    // launch
+    LaunchCreated: { label: 'Launch created', subject: 'mint' },
+    Graduated: { label: 'Graduated', subject: 'mint' },
+    CreatorFeesClaimed: { label: 'Creator fees claimed', subject: 'mint' },
+    LaunchConfigCreated: { label: 'Launch config created', subject: 'config' },
+    // kit
+    KitInstalled: { label: 'Rules installed', subject: 'mint' },
+    KitGraduated: { label: 'Rules graduated', subject: 'mint' },
+    RewardsClaimed: { label: 'Rewards claimed', subject: 'mint' },
+    RewardsShared: { label: 'Rewards shared', subject: 'mint' },
+    // bridge
+    WrapperRegistered: { label: 'Wrapper registered', subject: 'wrappedMint' },
+    Wrapped: { label: 'Bridged in', subject: 'wrappedMint' },
+    Unwrapped: { label: 'Bridged out', subject: 'wrappedMint' },
+    // half_life
+    Stoked: { label: 'Exit fee burned', subject: 'mint' },
+};
+/** An event's label in plain words; an unknown event's name with its words spaced (`SomethingNew` -> "Something new"). */
+export function eventLabel(name) {
+    const known = EVENT_WORDS[eventName(name)];
+    if (known)
+        return known.label;
+    const spaced = eventName(name).replace(/([a-z0-9])([A-Z])/g, '$1 $2');
+    return `${spaced.charAt(0)}${spaced.slice(1).toLowerCase()}`;
+}
+/** The account an event is mostly about, read from its payload; null when the table names none or the payload lacks it. */
+export function eventSubject(name, payload) {
+    const key = EVENT_WORDS[eventName(name)]?.subject;
+    if (!key)
+        return null;
+    const value = payload[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}

package/dist/index.d.ts

@@ -1,4 +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,4 +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[];