@bordrless/shared 0.8.0 → 0.9.0

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,6 @@
 export * from './api.ts';
+export * from './explorer.ts';
 export * from './policy.ts';
 export * from './programs.ts';
 export * from './studio.ts';
+export * from './workshop.ts';

package/dist/index.js

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

package/dist/policy.d.ts

@@ -6,7 +6,7 @@
  * `programs/tests/vectors/launch-fees.json`, which the Rust tests render from the reference the
  * programs are held to, and requires exact equality.
  */
-import type { CompanionSplitBps, CompanionTemplate, GameKindName, GameRequest, GameRolloverReason, JackpotRequest, LaunchRules, LaunchRulesInput, LotteryRequest, Side, StreakRequest } from './api.ts';
+import type { CompanionSplitBps, CompanionTemplate, GameKindName, GameRequest, GameRolloverReason, JackpotRequest, LaunchRules, LaunchRulesInput, LotteryRequest, ScriptRequest, Side, SnowballRequest, SnowballTerms, StreakRequest } from './api.ts';
 import type { StudioGameSettings } from './studio.ts';
 export declare const BPS = 10000n;
 export declare const WAD: bigint;
@@ -24,6 +24,15 @@ export declare const CURVE_BPS = 7500n;
 export declare const LP_FEE_BPS = 30;
 /** Protocol fee of an ordinary DEX pool (anyone's pool), in basis points of the quote side: the flat model (§3.1). */
 export declare const PROTOCOL_FEE_BPS = 100;
+/**
+ * The LP fee tiers the create-pool form offers for an ordinary pool (docs/dex.md decision 2): 0.25%
+ * (the default, for bridged pairs), 1% and 2% (memecoins). The program takes any value from 0 to 90%;
+ * three tiers keep the number of duplicate pools per pair down (§3.5).
+ */
+export declare const POOL_FEE_TIERS_BPS: readonly [25, 100, 200];
+export declare const POOL_FEE_TIER_DEFAULT_BPS = 25;
+export type PoolFeeTierBps = (typeof POOL_FEE_TIERS_BPS)[number];
+export declare const isPoolFeeTier: (bps: unknown) => bps is PoolFeeTierBps;
 /**
  * Bordrless's take on a launch pool (its curve and the same pool after graduation), the share
  * model of §3.1 (2026-10-07: "we earn 25% of their total fees, not 0.25%"): a quarter of what the
@@ -35,6 +44,8 @@ export declare const PROTOCOL_FEE_BPS = 100;
 export declare const LAUNCH_PROTOCOL_SHARE_BPS = 2500;
 /** The largest share the DEX config may set (`MAX_PROTOCOL_SHARE_BPS`): all of the cuts. */
 export declare const MAX_PROTOCOL_SHARE_BPS = 10000;
+/** The largest flat protocol fee the DEX config may set (`bordrless_swap::constants::MAX_PROTOCOL_FEE_BPS`): 10% of the quote side. */
+export declare const MAX_PROTOCOL_FEE_BPS = 1000;
 /** Largest creator fee a launch may choose. */
 export declare const MAX_CREATOR_FEE_BPS = 200;
 /** The creator fee choices offered on the launch form. */
@@ -286,27 +297,32 @@ export declare const COMPANION_MAX_VEST_DAYS = 365;
 /** The whole creator fee to the launcher: an ordinary launch, with no companion. */
 export declare const LAUNCHER_SPLIT: Readonly<CompanionSplitBps>;
 /**
- * The companion program's game limits (`constants.rs`; `GAME_LIMITS` in the SDK, the same numbers):
- * a round's length, the minimum pot, the prize's least share, a claim window's bounds, the most
- * attempts, and the half of a round the attempts may take. The launch form holds its choices to
- * them and the backend refuses anything outside them (`lotteryProblem`).
+ * The Jackpot's limits as the site offers them: the round's length (the programs take rounds from 5
+ * minutes since the five-minute rounds upgrade of 2026-10-12; the owner set the site's floor at 15
+ * minutes, which is also its default), the minimum pot, the prize's least share, a claim window's
+ * bounds (`MIN_CLAIM_WINDOW` in the companion, a minute), the most attempts, and the half of a round
+ * the attempts may take. The launch form holds its choices to them and the backend refuses anything
+ * outside them (`lotteryProblem`). `GAME_LIMITS` in the SDK is the programs' own.
  */
 export declare const LOTTERY_LIMITS: {
-    readonly minRoundSecs: 3600;
+    readonly minRoundSecs: 900;
     readonly maxRoundSecs: number;
     readonly minMinPotLamports: 100000000n;
     readonly maxMinPotLamports: 1000000000000n;
     readonly minPrizeBps: 1000;
-    readonly minClaimWindowSecs: 300;
+    readonly minClaimWindowSecs: 60;
     readonly maxClaimWindowSecs: 86400;
     readonly maxAttempts: 16;
     readonly claimsPerRound: 2;
+    /** A streak's epoch and its claim window keep the programs' older floors (`MIN_EPOCH_SECS`, `MIN_EPOCH_CLAIM_WINDOW`). */
+    readonly minEpochSecs: 3600;
+    readonly minEpochClaimWindowSecs: 300;
     /** The most a pot holds while its hook is not audited: 10 SOL, the rest of the pot's share bought back. */
     readonly potCapLamports: 10000000000n;
     /** Lamports the setup pays for the hook's state and registry and the game's account (mainnet rent, 2026-10-08). */
     readonly rentLamports: bigint;
 };
-/** The lottery the launch form starts with (docs/games.md, spec example 1): 6-hour rounds, 70% of the fee to the pot, 30% bought back, draws from 0.5 SOL paying the whole pot, 8 claim attempts of 10 minutes. */
+/** The lottery the launch form starts with (the owner, 2026-10-12): 15-minute rounds, 70% of the fee to the pot, 30% bought back, draws from 0.5 SOL paying the whole pot, 3 claim attempts of 2 minutes (`lotteryClaimsFor`). */
 export declare const LOTTERY_DEFAULTS: Readonly<LotteryRequest>;
 /** The round lengths the form offers (seconds), each with its label. */
 export declare const LOTTERY_ROUND_CHOICES: readonly {
@@ -323,8 +339,10 @@ export declare const LOTTERY_PRIZE_CHOICES_BPS: readonly [10000, 5000, 2500];
 /** The pot's share moves in steps of 10%, like the Split control's. */
 export declare const LOTTERY_POT_STEP_BPS = 1000;
 /**
- * The claim windows and attempts the form fixes for a round length: 8 attempts of 10 minutes for a
- * round of 6 hours or more, 6 of 5 minutes for an hour (the attempts must fit in half a round).
+ * The claim windows and attempts the form fixes for a round length (the attempts must fit in half a
+ * round, `claimsPerRound`): 8 attempts of 10 minutes from 6 hours, 6 of 5 minutes from an hour, 3 of
+ * 2 minutes from 15 minutes, and 2 of a minute under that (the programs' 5-minute rounds, which the
+ * site does not offer).
  */
 export declare function lotteryClaimsFor(roundSecs: number): {
     claimWindowSecs: number;
@@ -342,11 +360,11 @@ export declare function lotteryRequestOf(raw: unknown): LotteryRequest | null;
 export declare function lotteryProblem(game: LotteryRequest, split: CompanionSplitBps, rules: LaunchRulesInput, creatorFeeBps: number): string | null;
 /** The copy rules of a lottery coin (docs/games.md): said on the launch form, the review step and the token page, never "provably fair", "guaranteed" or "audited". */
 export declare const LOTTERY_COPY: {
-    readonly held: "The pot is held by the companion program and paid out by code. Randomness by ORAO VRF.";
-    readonly odds: "Your odds = your tokens in the round. Sell before the payout and you forfeit.";
-    readonly stop: "Bordrless can stop this game: its pot would be bought back and burned. Nobody is paid.";
-    readonly cap: "Pot capped at 10 SOL until the game’s hook is audited.";
-    readonly oracle: "Randomness by ORAO VRF: ORAO’s three signers produce it. They could withhold or bias a draw; Bordrless can’t.";
+    readonly held: "The pot is held by code, not by a person. Each round, one holder is picked at random and paid in SOL.";
+    readonly odds: "Your odds are your share of the tokens held through the round. Tokens you buy count from the next round, and selling during a round takes you out of it.";
+    readonly stop: "Bordrless can stop the game. If it does, the pot buys back and burns the token and no one is paid.";
+    readonly cap: "The pot holds at most 10 SOL for now. Anything above that buys back and burns the token.";
+    readonly oracle: "The random numbers come from ORAO, an outside service. Neither Bordrless nor the launcher can pick the winner.";
 };
 /** The jackpot's timer and the streak's minimum streak: the companion's bounds (`GAME_LIMITS` in the SDK). */
 export declare const GAME_KIND_LIMITS: {
@@ -383,20 +401,20 @@ export declare const GAME_KIND_NAMES: Readonly<Record<GameKindName, string>>;
  * stop this game"; never "provably fair", "guaranteed" or "audited".
  */
 export declare const JACKPOT_COPY: {
-    readonly held: "The pot is held by the companion program and paid out by code. No randomness: the last buyer wins.";
-    readonly rule: "The last buyer wins if they keep every token they bought: any sale or transfer forfeits.";
-    readonly unfunded: "If the pot is below its minimum when a round is settled, the round pays nothing and the pot carries on.";
-    readonly curve: "Buys count while the coin is on its curve: the jackpot ends at graduation (the round under way is still paid).";
-    readonly cap: "Pot capped at 10 SOL until the game’s hook is audited.";
-    readonly stop: "Bordrless can stop this game: its pot would be bought back and burned. Nobody is paid.";
+    readonly held: "The pot is held by code, not by a person. No luck involved: the last buyer wins.";
+    readonly rule: "The last buyer wins when the timer runs out, as long as they still hold what they bought. Selling or sending any of it forfeits.";
+    readonly unfunded: "If the pot is under its minimum when the timer runs out, no prize is paid and the pot keeps growing.";
+    readonly curve: "The game runs while the coin is on its curve and ends at graduation. A round under way is still paid.";
+    readonly cap: "The pot holds at most 10 SOL for now. Anything above that buys back and burns the token.";
+    readonly stop: "Bordrless can stop the game. If it does, the pot buys back and burns the token and no one is paid.";
 };
 export declare const STREAK_COPY: {
-    readonly held: "The pot is held by the companion program and paid out by code. No randomness: holders share in proportion to what they held.";
-    readonly rule: "Send anything, to anyone, and you lose this epoch’s and last epoch’s share. Claim before you sell.";
-    readonly weight: "Your weight is what you held since the epoch began: tokens that arrive during an epoch count from the next.";
-    readonly claims: "Shares are claimed during the next epoch; the keeper claims for everyone whose share covers the fee, the rest claim here. What is not claimed rolls over.";
-    readonly cap: "Pot capped at 10 SOL until the game’s hook is audited.";
-    readonly stop: "Bordrless can stop this game: its pot would be bought back and burned. Nobody is paid.";
+    readonly held: "The pot is held by code, not by a person. No luck involved: holders share it in proportion to what they held.";
+    readonly rule: "Hold through the epoch without sending anything. Any sale or transfer drops you out of this epoch and the last one.";
+    readonly weight: "Your share is based on what you held when the epoch began. Tokens you buy during an epoch count from the next one.";
+    readonly claims: "Shares are paid out during the next epoch. Most are paid automatically; small ones are claimed here. Unclaimed shares stay in the pot.";
+    readonly cap: "The pot holds at most 10 SOL for now. Anything above that buys back and burns the token.";
+    readonly stop: "Bordrless can stop the game. If it does, the pot buys back and burns the token and no one is paid.";
 };
 /** Why a round paid no prize, in a few words each (`GameRolloverReason`). */
 export declare const ROLLOVER_WORDS: Readonly<Record<GameRolloverReason, string>>;
@@ -422,6 +440,61 @@ export declare function companionRequestSplit(raw: unknown): CompanionSplitBps |
  * `CreatorLockUnsupported`, `HolderRewardsOff`), and a creator fee for it to run.
  */
 export declare function companionSplitProblem(split: CompanionSplitBps, rules: Pick<LaunchRulesInput, 'holderFeeBuyBps' | 'holderFeeSellBps' | 'creatorLockDays'>, creatorFeeBps: number): string | null;
+/** The presets the launch form offers. Every one spends the pot on volume and trades even when the price is flat; they differ in how fast and how big. */
+export type SnowballPreset = 'conservative' | 'normal' | 'aggressive';
+export declare const SNOWBALL_PRESETS: Readonly<Record<SnowballPreset, Readonly<SnowballTerms>>>;
+export declare const SNOWBALL_PRESET_LIST: readonly SnowballPreset[];
+export declare const SNOWBALL_DEFAULT_PRESET: SnowballPreset;
+/** The custom controls' choices. The program takes anything within `SNOWBALL_BOUNDS`. */
+export declare const SNOWBALL_STEP_CHOICES_BPS: readonly [50, 100, 200, 300, 500, 1000];
+export declare const SNOWBALL_SIZE_CHOICES_BPS: readonly [1000, 2500, 5000, 7500, 10000];
+export declare const SNOWBALL_POOL_CHOICES_BPS: readonly [100, 200, 500, 1000];
+export declare const SNOWBALL_INTERVAL_CHOICES_SECS: readonly [10, 30, 60, 300];
+/** The program's bounds (`create_snowball`). */
+export declare const SNOWBALL_BOUNDS: {
+    readonly minStepBps: 50;
+    readonly maxStepBps: 2000;
+    readonly minSizeBps: 100;
+    readonly maxSizeBps: 10000;
+    readonly minPoolBps: 25;
+    readonly maxPoolBps: 1000;
+    readonly minInterval: 10;
+    readonly maxInterval: 86400;
+};
+/** The Snowball a launch request's `companion` names; null without one; `'malformed'` when it is there and not whole numbers and a flag. */
+export declare function snowballRequestOf(companion: unknown): SnowballRequest | null | 'malformed';
+/**
+ * Why a Snowball with this split can't run these rules at this fee, in the words the launch form and
+ * the backend use (`companion_rules`); null when it can: the market maker's part with the split adds up
+ * to 10,000, its terms are within the program's bounds, and what any companion needs
+ * (`companionSplitProblem`'s rules).
+ */
+export declare function snowballProblem(s: SnowballRequest, split: CompanionSplitBps, rules: Pick<LaunchRulesInput, 'holderFeeBuyBps' | 'holderFeeSellBps' | 'creatorLockDays'>, creatorFeeBps: number): string | null;
+/** The companion program's script bounds (`create_script`): steps 10 seconds to a day apart, at most 512 bytes of init data, at most 10,240 bytes of state. */
+export declare const SCRIPT_BOUNDS: {
+    readonly minInterval: 10;
+    readonly maxInterval: 86400;
+    readonly maxInitLen: 512;
+    readonly maxStateLen: 10240;
+};
+/** The interval choices the launch form offers (seconds): a minute, five, fifteen, an hour, a day. */
+export declare const SCRIPT_INTERVAL_CHOICES_SECS: readonly [60, 300, 900, 3600, 86400];
+/**
+ * How many bytes a script's init data holds, as the request writes it: hex (an even number of hex
+ * digits, `0x` or not) or base64; the empty string is no data. Null when it is neither. Hex is tried
+ * first: a text that reads as both (`abcd`) is read as hex.
+ */
+export declare function scriptInitDataLength(raw: string): number | null;
+/** The custom companion's script a launch request's `companion` names; null without one; `'malformed'` when it is there and not the fields `ScriptRequest` takes. */
+export declare function scriptRequestOf(companion: unknown): ScriptRequest | null | 'malformed';
+/**
+ * Why a custom companion with this split can't run these rules at this fee, in the words the launch
+ * form and the backend use (`companion_rules`); null when it can: the pot's part with the split adds
+ * up to 10,000, the interval, the init data and the state are within the program's bounds, and what
+ * any companion needs (`companionSplitProblem`'s rules). Whether the script is approved is the
+ * backend's to check (`script_not_approved`).
+ */
+export declare function scriptProblem(s: ScriptRequest, split: CompanionSplitBps, rules: Pick<LaunchRulesInput, 'holderFeeBuyBps' | 'holderFeeSellBps' | 'creatorLockDays'>, creatorFeeBps: number): string | null;
 /** The template whose split this is, or null for any other split. */
 export declare function companionTemplateOf(split: CompanionSplitBps): CompanionTemplate | null;
 /** Kit module bits (§4.2). */