@bordrless/shared 0.8.0 → 0.10.0

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, LossCoverRequest, LossCoverTerms, LotteryRequest, PayeeRequest, PayoutTermsRequest, 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,168 @@ 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';
+/** The companion program's bounds on payout terms (`PayoutTermsArgs::valid`): each share 1 to 10,000 basis points, the window 10 seconds to a day. */
+export declare const PAYOUT_TERMS_BOUNDS: {
+    readonly minWindowSecs: 10;
+    readonly maxWindowSecs: 86400;
+};
+/** Whether payout terms are within the companion program's bounds (`create_script_v2` refuses them otherwise, `BadPayoutTerms`). */
+export declare function payoutTermsWithin(t: PayoutTermsRequest): boolean;
+/**
+ * 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 most wallets that share a launcher's part (`set_payees`; the SDK's `MAX_PAYEES`). */
+export declare const MAX_PAYEES = 10;
+/** The payees a launch request's `companion` names (`companion.payees`); null without any (absent, null or empty); `'malformed'` when they are there and not a list of `{ wallet, bps }` with an address and a whole number. */
+export declare function payeesRequestOf(companion: unknown): PayeeRequest[] | null | 'malformed';
+/** What the payees leave the launcher of their part, basis points of it (10,000 with none). */
+export declare const payeesLeaveBps: (payees: readonly Pick<PayeeRequest, "bps">[]) => number;
+/**
+ * Why `set_payees` would refuse these payees (`BadPayees`), in the words the launch form and the
+ * backend use (`companion_rules`); null when it would take them: 1 to 10 wallets, each named once,
+ * each 0.01% to 100% of the launcher's part and 100% in all at most; none the default key, the
+ * launcher (`beneficiary`) or one of `reserved` (the companion and its creator address, which the
+ * backend derives for the mint). A split with no part for the launcher has nothing to share.
+ */
+export declare function payeesProblem(payees: readonly PayeeRequest[], split: Pick<CompanionSplitBps, 'beneficiaryBps'>, beneficiary: string, reserved?: readonly string[]): string | null;
+/**
+ * Why a request's `allowWalletPayouts` can't be taken (`companion_rules`); null when it can, or it
+ * is off: only a custom hook's script with payout terms (`script.payout`, `create_script_v2`) may
+ * pay wallets, never Lossback's (its script pays holders under water, and nothing else).
+ */
+export declare function walletPayoutsProblem(allow: boolean, script: Pick<ScriptRequest, 'payout'> | null): string | null;
+/**
+ * The bounds a Lossback coin's terms keep within, as the site offers them: the programs' own
+ * (`loss_cover_script::CoverTerms::valid`, the companion's `PayoutTermsArgs::valid`) and the
+ * policy's tighter ones (the step at least 10 s and at most a quarter of the round, a holding of
+ * at most 1% of the supply, a loss of at least 0.0001 SOL, a wait of at most a day). The keeper's
+ * batches (`batchPaying`, `batchMeasuring`) are what one step carries within the runtime's
+ * instruction trace, measured by the programs' `loss_cover_vectors` (a measuring step carries one
+ * fewer on a coin's first step, when the creator's holding is made on the way).
+ */
+export declare const LOSS_COVER_LIMITS: {
+    readonly minRoundSecs: 60;
+    readonly maxRoundSecs: 86400;
+    readonly minStepSecs: 10;
+    readonly maxStepSecs: 3600;
+    /** The step is at most this part of the round: a round has at least four steps. */
+    readonly stepsPerRoundMin: 4;
+    readonly minBps: 100;
+    readonly maxBps: 10000;
+    readonly minCoverBps: 1000;
+    readonly maxCoverBps: 10000;
+    /** The least holding that counts, at most this part of the supply (basis points). */
+    readonly maxMinHoldingBps: 100;
+    readonly minMinLossLamports: 100000n;
+    readonly maxMinAgeSecs: 86400;
+    readonly maxMinPotLamports: 100000000000n;
+    readonly batchPaying: 7;
+    readonly batchMeasuring: 13;
+};
+/**
+ * The terms the site launches a Lossback coin with: rounds of 5 minutes stepped every 15 seconds,
+ * the whole pot available to each step, each holding and each round, the whole loss covered when
+ * the pot can, a holding of 100,000 tokens (6 decimals: base units) and a loss of 0.001 SOL at
+ * least, a minute after its last buy (the owner, 2026-10-12; the first coin, LIFEVEST, was made with
+ * half an hour, fixed in its script state), a round only once the pot holds 1 SOL, the hook's whole
+ * fee row to the pot (the launcher's row 0: `potBps` is 10,000 less the launcher's part). The
+ * launcher sets `roundSecs`, `minPotLamports`, `coverBps` and `minHolding` (`LossCoverRequest`);
+ * the rest is fixed here. There is no cooldown: a holding is measured or paid once a round.
+ */
+/** A holding's wait in words: "45 seconds", "1 minute", "30 minutes". */
+export declare function ageWords(secs: number): string;
+export declare const LOSS_COVER_DEFAULTS: {
+    readonly potBps: 10000;
+    readonly roundSecs: 300;
+    readonly stepSecs: 15;
+    readonly roundBps: 10000;
+    readonly stepBps: 10000;
+    readonly holdingBps: 10000;
+    readonly coverBps: 10000;
+    readonly minHolding: "100000000000";
+    readonly minLossLamports: "1000000";
+    readonly minAgeSecs: 60;
+    readonly minPotLamports: "1000000000";
+};
+/** The round lengths the launch form offers (seconds): 5, 10, 30 and 60 minutes. */
+export declare const LOSS_COVER_ROUND_CHOICES_SECS: readonly [300, 600, 1800, 3600];
+/** The cover shares the launch form offers: the whole loss, half, a quarter. */
+export declare const LOSS_COVER_COVER_CHOICES_BPS: readonly [10000, 5000, 2500];
+/** The minimum pots the launch form offers, lamports: none, 0.5, 1, 5 SOL. */
+export declare const LOSS_COVER_MIN_POT_CHOICES_LAMPORTS: readonly ["0", "500000000", "1000000000", "5000000000"];
+/** The Lossback terms a launch request's `companion` names (`companion.lossCover`); null without them; `'malformed'` when they are there and not whole numbers and lamport strings. */
+export declare function lossCoverRequestOf(companion: unknown): LossCoverRequest | null | 'malformed';
+/** The full terms a request launches with: what it names, the rest from `LOSS_COVER_DEFAULTS`. */
+export declare function lossCoverTermsOf(s: LossCoverRequest): LossCoverTerms;
+/** The pot's part of every fee claim for a Lossback coin: what the launcher's part of the split leaves (the hook's whole fee row). */
+export declare const lossCoverPotBps: (split: CompanionSplitBps) => number;
+/**
+ * Why a Lossback coin with these terms can't launch with this split on these rules at this fee, in
+ * the words the launch form and the backend use (`companion_rules`); null when it can: a creator
+ * fee to fill the pot, no other token rules (it launches from Bordrless's Loss cover config, which
+ * has none, and runs its own hook in the kit's place), nothing bought back and no holders' part (the
+ * pot and the launcher only), a part for the pot, and the terms within `LOSS_COVER_LIMITS` (the
+ * programs refuse anything outside their own bounds at the setup's dry run). `supply` is the
+ * launch's, for the least holding's cap.
+ */
+export declare function lossCoverProblem(s: LossCoverRequest, split: CompanionSplitBps, rules: LaunchRulesInput, creatorFeeBps: number, supply?: bigint): string | null;
+/**
+ * The review step's sentence for a Lossback coin, in numbers: what it does, never that it protects
+ * anyone (docs/loss-cover.md §5).
+ */
+export declare function lossCoverSentence(s: LossCoverRequest, decimals?: number): string;
 /** 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). */