@bordrless/shared 0.8.0 → 0.10.0

package/dist/policy.js

@@ -15,6 +15,14 @@ export const CURVE_BPS = 7500n;
 export 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 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 const POOL_FEE_TIERS_BPS = [25, 100, 200];
+export const POOL_FEE_TIER_DEFAULT_BPS = 25;
+export const isPoolFeeTier = (bps) => POOL_FEE_TIERS_BPS.includes(bps);
 /**
  * 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
@@ -26,6 +34,8 @@ export const PROTOCOL_FEE_BPS = 100;
 export const LAUNCH_PROTOCOL_SHARE_BPS = 2_500;
 /** The largest share the DEX config may set (`MAX_PROTOCOL_SHARE_BPS`): all of the cuts. */
 export const MAX_PROTOCOL_SHARE_BPS = 10_000;
+/** The largest flat protocol fee the DEX config may set (`bordrless_swap::constants::MAX_PROTOCOL_FEE_BPS`): 10% of the quote side. */
+export const MAX_PROTOCOL_FEE_BPS = 1_000;
 /** Largest creator fee a launch may choose. */
 export const MAX_CREATOR_FEE_BPS = 200;
 /** The creator fee choices offered on the launch form. */
@@ -370,30 +380,37 @@ export const COMPANION_MAX_VEST_DAYS = 365;
 export const LAUNCHER_SPLIT = { buybackBps: 0, holdersBps: 0, beneficiaryBps: 10_000 };
 // ---- lottery coins (docs/games.md) -----------------------------------------------------------------
 /**
- * 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 const LOTTERY_LIMITS = {
-    minRoundSecs: 3_600,
+    minRoundSecs: 900,
     maxRoundSecs: 30 * DAY_SECS,
     minMinPotLamports: 100000000n,
     maxMinPotLamports: 1000000000000n,
     minPrizeBps: 1_000,
-    minClaimWindowSecs: 300,
+    minClaimWindowSecs: 60,
     maxClaimWindowSecs: DAY_SECS,
     maxAttempts: 16,
     claimsPerRound: 2,
+    /** A streak's epoch and its claim window keep the programs' older floors (`MIN_EPOCH_SECS`, `MIN_EPOCH_CLAIM_WINDOW`). */
+    minEpochSecs: 3_600,
+    minEpochClaimWindowSecs: 300,
     /** The most a pot holds while its hook is not audited: 10 SOL, the rest of the pot's share bought back. */
     potCapLamports: 10000000000n,
     /** Lamports the setup pays for the hook's state and registry and the game's account (mainnet rent, 2026-10-08). */
     rentLamports: 3515360n + 3119120n,
 };
-/** 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. */
-export const LOTTERY_DEFAULTS = { kind: 'lottery', roundSecs: 21_600, potBps: 7_000, minPotLamports: '500000000', prizeBps: 10_000, claimWindowSecs: 600, maxAttempts: 8 };
+/** 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 const LOTTERY_DEFAULTS = { kind: 'lottery', roundSecs: 900, potBps: 7_000, minPotLamports: '500000000', prizeBps: 10_000, claimWindowSecs: 120, maxAttempts: 3 };
 /** The round lengths the form offers (seconds), each with its label. */
 export const LOTTERY_ROUND_CHOICES = [
+    { secs: 900, label: '15 min' },
+    { secs: 1_800, label: '30 min' },
     { secs: 3_600, label: '1 hour' },
     { secs: 21_600, label: '6 hours' },
     { secs: DAY_SECS, label: '1 day' },
@@ -411,11 +428,19 @@ export const LOTTERY_PRIZE_CHOICES_BPS = [10_000, 5_000, 2_500];
 /** The pot's share moves in steps of 10%, like the Split control's. */
 export const LOTTERY_POT_STEP_BPS = 1_000;
 /**
- * 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 function lotteryClaimsFor(roundSecs) {
-    return roundSecs >= 21_600 ? { claimWindowSecs: 600, maxAttempts: 8 } : { claimWindowSecs: 300, maxAttempts: 6 };
+    if (roundSecs >= 21_600)
+        return { claimWindowSecs: 600, maxAttempts: 8 };
+    if (roundSecs >= 3_600)
+        return { claimWindowSecs: 300, maxAttempts: 6 };
+    if (roundSecs >= 900)
+        return { claimWindowSecs: 120, maxAttempts: 3 };
+    return { claimWindowSecs: 60, maxAttempts: 2 };
 }
 const isWhole = (v, min, max) => typeof v === 'number' && Number.isInteger(v) && v >= min && v <= max;
 /** The lottery a launch request's `companion.game` names, each field a whole number; null when it is malformed (bounds are `lotteryProblem`'s). */
@@ -449,14 +474,14 @@ export function lotteryProblem(game, split, rules, creatorFeeBps) {
     if (!(game.potBps > 0) || split.buybackBps + split.holdersBps + split.beneficiaryBps + game.potBps !== 10_000)
         return 'The pot’s part and the split must add up to 10,000 basis points, with a pot.';
     if (game.roundSecs < L.minRoundSecs || game.roundSecs > L.maxRoundSecs)
-        return 'A round lasts an hour to 30 days.';
+        return 'A round lasts 15 minutes to 30 days.';
     const minPot = BigInt(game.minPotLamports);
     if (minPot < L.minMinPotLamports || minPot > L.maxMinPotLamports)
         return 'The minimum pot is 0.1 to 1,000 SOL.';
     if (game.prizeBps < L.minPrizeBps || game.prizeBps > 10_000)
         return 'A draw pays 10% to 100% of the pot.';
     if (game.claimWindowSecs < L.minClaimWindowSecs || game.claimWindowSecs > L.maxClaimWindowSecs)
-        return 'A claim window lasts 5 minutes to a day.';
+        return 'A claim window lasts a minute to a day.';
     if (!(game.maxAttempts >= 1 && game.maxAttempts <= L.maxAttempts))
         return 'A draw makes 1 to 16 attempts.';
     if (game.claimWindowSecs * game.maxAttempts * L.claimsPerRound > game.roundSecs)
@@ -465,11 +490,11 @@ export function lotteryProblem(game, split, rules, creatorFeeBps) {
 }
 /** 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 const LOTTERY_COPY = {
-    held: 'The pot is held by the companion program and paid out by code. Randomness by ORAO VRF.',
-    odds: 'Your odds = your tokens in the round. Sell before the payout and you forfeit.',
-    stop: 'Bordrless can stop this game: its pot would be bought back and burned. Nobody is paid.',
-    cap: 'Pot capped at 10 SOL until the game’s hook is audited.',
-    oracle: 'Randomness by ORAO VRF: ORAO’s three signers produce it. They could withhold or bias a draw; Bordrless can’t.',
+    held: 'The pot is held by code, not by a person. Each round, one holder is picked at random and paid in SOL.',
+    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.',
+    stop: 'Bordrless can stop the game. If it does, the pot buys back and burns the token and no one is paid.',
+    cap: 'The pot holds at most 10 SOL for now. Anything above that buys back and burns the token.',
+    oracle: 'The random numbers come from ORAO, an outside service. Neither Bordrless nor the launcher can pick the winner.',
 };
 // ---- jackpot and streak coins (docs/games.md "Phase 2"), on game hooks made in Studio -----------------
 /** The jackpot's timer and the streak's minimum streak: the companion's bounds (`GAME_LIMITS` in the SDK). */
@@ -541,9 +566,9 @@ export function gameProblem(game, split, rules, creatorFeeBps, hook = null) {
             return 'A qualifying buy is at least one base unit.';
         return null;
     }
-    if (hook.roundSecs < L.minRoundSecs || hook.roundSecs > L.maxRoundSecs)
+    if (hook.roundSecs < L.minEpochSecs || hook.roundSecs > L.maxRoundSecs)
         return 'An epoch lasts an hour to 30 days.';
-    if (game.claimWindowSecs < L.minClaimWindowSecs || game.claimWindowSecs > L.maxClaimWindowSecs || game.claimWindowSecs * L.claimsPerRound > hook.roundSecs)
+    if (game.claimWindowSecs < L.minEpochClaimWindowSecs || game.claimWindowSecs > L.maxClaimWindowSecs || game.claimWindowSecs * L.claimsPerRound > hook.roundSecs)
         return 'A streak leaves claims 5 minutes to a day, at most half an epoch.';
     if (hook.minStreakSecs > GAME_KIND_LIMITS.maxMinStreakSecs)
         return 'A streak asks at most a year without sending.';
@@ -560,31 +585,31 @@ export const GAME_KIND_NAMES = { lottery: 'lottery', jackpot: 'jackpot', streak:
  * stop this game"; never "provably fair", "guaranteed" or "audited".
  */
 export const JACKPOT_COPY = {
-    held: 'The pot is held by the companion program and paid out by code. No randomness: the last buyer wins.',
-    rule: 'The last buyer wins if they keep every token they bought: any sale or transfer forfeits.',
-    unfunded: 'If the pot is below its minimum when a round is settled, the round pays nothing and the pot carries on.',
-    curve: 'Buys count while the coin is on its curve: the jackpot ends at graduation (the round under way is still paid).',
+    held: 'The pot is held by code, not by a person. No luck involved: the last buyer wins.',
+    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.',
+    unfunded: 'If the pot is under its minimum when the timer runs out, no prize is paid and the pot keeps growing.',
+    curve: 'The game runs while the coin is on its curve and ends at graduation. A round under way is still paid.',
     cap: LOTTERY_COPY.cap,
     stop: LOTTERY_COPY.stop,
 };
 export const STREAK_COPY = {
-    held: 'The pot is held by the companion program and paid out by code. No randomness: holders share in proportion to what they held.',
-    rule: 'Send anything, to anyone, and you lose this epoch’s and last epoch’s share. Claim before you sell.',
-    weight: 'Your weight is what you held since the epoch began: tokens that arrive during an epoch count from the next.',
-    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.',
+    held: 'The pot is held by code, not by a person. No luck involved: holders share it in proportion to what they held.',
+    rule: 'Hold through the epoch without sending anything. Any sale or transfer drops you out of this epoch and the last one.',
+    weight: 'Your share is based on what you held when the epoch began. Tokens you buy during an epoch count from the next one.',
+    claims: 'Shares are paid out during the next epoch. Most are paid automatically; small ones are claimed here. Unclaimed shares stay in the pot.',
     cap: LOTTERY_COPY.cap,
     stop: LOTTERY_COPY.stop,
 };
 /** Why a round paid no prize, in a few words each (`GameRolloverReason`). */
 export const ROLLOVER_WORDS = {
-    noTickets: 'Nobody held tickets',
-    roundForgotten: 'The round was forgotten',
-    noClaim: 'No winner claimed in time',
-    oracleSilent: 'ORAO never answered',
+    noTickets: 'No tickets yet: tokens count from the round after they are bought',
+    roundForgotten: 'The round was skipped',
+    noClaim: 'The winner did not claim in time',
+    oracleSilent: 'The random number never arrived',
     blocked: 'Stopped by Bordrless',
     late: 'Drawn too late',
-    oracleUnreadable: 'ORAO’s answer unreadable',
-    oracleUnpaid: 'The pot could not pay ORAO',
+    oracleUnreadable: 'The random number could not be read',
+    oracleUnpaid: 'The pot could not pay for the random number',
 };
 /** Whether a split is the whole fee to the launcher (no companion needed). */
 export const isLauncherSplit = (s) => s.buybackBps === 0 && s.holdersBps === 0 && s.beneficiaryBps === 10_000;
@@ -636,6 +661,366 @@ export function companionSplitProblem(split, rules, creatorFeeBps) {
         return 'A share of the creator fee for holders needs holder rewards on.';
     return null;
 }
+export const SNOWBALL_PRESETS = {
+    conservative: { buyStepBps: 300, sellStepBps: 300, buyBps: 1_000, sellBps: 1_000, poolBps: 100, interval: 60, flatTrades: true },
+    normal: { buyStepBps: 200, sellStepBps: 200, buyBps: 2_500, sellBps: 2_500, poolBps: 200, interval: 30, flatTrades: true },
+    aggressive: { buyStepBps: 100, sellStepBps: 100, buyBps: 5_000, sellBps: 5_000, poolBps: 500, interval: 10, flatTrades: true },
+};
+export const SNOWBALL_PRESET_LIST = ['conservative', 'normal', 'aggressive'];
+export const SNOWBALL_DEFAULT_PRESET = 'normal';
+/** The custom controls' choices. The program takes anything within `SNOWBALL_BOUNDS`. */
+export const SNOWBALL_STEP_CHOICES_BPS = [50, 100, 200, 300, 500, 1_000];
+export const SNOWBALL_SIZE_CHOICES_BPS = [1_000, 2_500, 5_000, 7_500, 10_000];
+export const SNOWBALL_POOL_CHOICES_BPS = [100, 200, 500, 1_000];
+export const SNOWBALL_INTERVAL_CHOICES_SECS = [10, 30, 60, 300];
+/** The program's bounds (`create_snowball`). */
+export const SNOWBALL_BOUNDS = { minStepBps: 50, maxStepBps: 2_000, minSizeBps: 100, maxSizeBps: 10_000, minPoolBps: 25, maxPoolBps: 1_000, minInterval: 10, maxInterval: 86_400 };
+/** The Snowball a launch request's `companion` names; null without one; `'malformed'` when it is there and not whole numbers and a flag. */
+export function snowballRequestOf(companion) {
+    if (typeof companion !== 'object' || companion === null)
+        return null;
+    const raw = companion.snowball;
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'object')
+        return 'malformed';
+    const r = raw;
+    if (![r.potBps, r.buyStepBps, r.sellStepBps, r.buyBps, r.sellBps, r.poolBps].every(isShare))
+        return 'malformed';
+    if (typeof r.interval !== 'number' || !Number.isInteger(r.interval) || typeof r.flatTrades !== 'boolean')
+        return 'malformed';
+    return { potBps: r.potBps, buyStepBps: r.buyStepBps, sellStepBps: r.sellStepBps, buyBps: r.buyBps, sellBps: r.sellBps, poolBps: r.poolBps, interval: r.interval, flatTrades: r.flatTrades };
+}
+/**
+ * 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 function snowballProblem(s, split, rules, creatorFeeBps) {
+    const B = SNOWBALL_BOUNDS;
+    const within = (v, lo, hi) => Number.isInteger(v) && v >= lo && v <= hi;
+    if (!(s.potBps > 0) || split.buybackBps + split.holdersBps + split.beneficiaryBps + s.potBps !== 10_000)
+        return 'The market maker’s part and the rest of the creator fee must add up to 100%.';
+    if (!within(s.buyStepBps, B.minStepBps, B.maxStepBps) || !within(s.sellStepBps, B.minStepBps, B.maxStepBps))
+        return 'A buy or a sell triggers on a move of 0.5% to 20%.';
+    if (!within(s.buyBps, B.minSizeBps, B.maxSizeBps) || !within(s.sellBps, B.minSizeBps, B.maxSizeBps))
+        return 'Each trade uses 1% to 100% of its SOL or its tokens.';
+    if (!within(s.poolBps, B.minPoolBps, B.maxPoolBps))
+        return 'A trade can be up to 0.25% to 10% of the pool.';
+    if (!within(s.interval, B.minInterval, B.maxInterval))
+        return 'Trades are 10 seconds to a day apart.';
+    if (rules.creatorLockDays > 0)
+        return 'A creator fee run by a program can’t come with the creator wallet lock: the program vests your first buy instead.';
+    if (creatorFeeBps === 0)
+        return 'There is no creator fee to fill the market maker with: set one.';
+    if (splitPaysHolders(split) && !rewardsOn(rules))
+        return 'A share of the creator fee for holders needs holder rewards on.';
+    return null;
+}
+// ---- Custom companions (2026-10-12): a Workshop script spends the pot (docs/scripts.md) --------------
+/** 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 const SCRIPT_BOUNDS = { minInterval: 10, maxInterval: 86_400, maxInitLen: 512, maxStateLen: 10_240 };
+/** The interval choices the launch form offers (seconds): a minute, five, fifteen, an hour, a day. */
+export const SCRIPT_INTERVAL_CHOICES_SECS = [60, 300, 900, 3_600, 86_400];
+const BASE58_ADDRESS = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const HEX_BYTES = /^(?:0x)?(?:[0-9a-fA-F]{2})*$/;
+const BASE64_TEXT = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/**
+ * 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 function scriptInitDataLength(raw) {
+    if (raw === '')
+        return 0;
+    if (HEX_BYTES.test(raw))
+        return (raw.startsWith('0x') ? raw.length - 2 : raw.length) / 2;
+    if (BASE64_TEXT.test(raw))
+        return (raw.length / 4) * 3 - (raw.endsWith('==') ? 2 : raw.endsWith('=') ? 1 : 0);
+    return 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 function scriptRequestOf(companion) {
+    if (typeof companion !== 'object' || companion === null)
+        return null;
+    const raw = companion.script;
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'object')
+        return 'malformed';
+    const r = raw;
+    if (!isShare(r.potBps) || typeof r.program !== 'string' || !BASE58_ADDRESS.test(r.program))
+        return 'malformed';
+    if (typeof r.interval !== 'number' || !Number.isInteger(r.interval) || typeof r.stateLen !== 'number' || !Number.isInteger(r.stateLen))
+        return 'malformed';
+    const initData = r.initData === undefined || r.initData === null ? '' : r.initData;
+    if (typeof initData !== 'string' || scriptInitDataLength(initData) === null)
+        return 'malformed';
+    const payout = payoutTermsRequestOf(r.payout);
+    if (payout === 'malformed')
+        return 'malformed';
+    return { potBps: r.potBps, program: r.program, interval: r.interval, initData, stateLen: r.stateLen, ...(payout ? { payout } : {}) };
+}
+/** 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 const PAYOUT_TERMS_BOUNDS = { minWindowSecs: 10, maxWindowSecs: 86_400 };
+/** A script's payout terms as a request names them (`script.payout`); null without them; `'malformed'` when they are there and not four whole numbers. */
+function payoutTermsRequestOf(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'object')
+        return 'malformed';
+    const r = raw;
+    if (![r.stepBps, r.holdingBps, r.windowBps].every(isShare) || typeof r.windowSecs !== 'number' || !Number.isInteger(r.windowSecs))
+        return 'malformed';
+    return { stepBps: r.stepBps, holdingBps: r.holdingBps, windowBps: r.windowBps, windowSecs: r.windowSecs };
+}
+/** Whether payout terms are within the companion program's bounds (`create_script_v2` refuses them otherwise, `BadPayoutTerms`). */
+export function payoutTermsWithin(t) {
+    const share = (v) => Number.isInteger(v) && v >= 1 && v <= 10_000;
+    return share(t.stepBps) && share(t.holdingBps) && share(t.windowBps) && Number.isInteger(t.windowSecs) && t.windowSecs >= PAYOUT_TERMS_BOUNDS.minWindowSecs && t.windowSecs <= PAYOUT_TERMS_BOUNDS.maxWindowSecs;
+}
+/**
+ * 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 function scriptProblem(s, split, rules, creatorFeeBps) {
+    const B = SCRIPT_BOUNDS;
+    if (!(s.potBps > 0) || split.buybackBps + split.holdersBps + split.beneficiaryBps + s.potBps !== 10_000)
+        return 'The script’s part and the rest of the creator fee must add up to 100%.';
+    if (!Number.isInteger(s.interval) || s.interval < B.minInterval || s.interval > B.maxInterval)
+        return 'Steps are 10 seconds to a day apart.';
+    const initLen = scriptInitDataLength(s.initData);
+    if (initLen === null)
+        return 'The script’s init data is hex or base64.';
+    if (initLen > B.maxInitLen)
+        return `The script’s init data is at most ${B.maxInitLen} bytes.`;
+    if (!Number.isInteger(s.stateLen) || s.stateLen < 0 || s.stateLen > B.maxStateLen)
+        return `The script’s state is 0 to ${B.maxStateLen.toLocaleString('en-US')} bytes.`;
+    if (s.payout && !payoutTermsWithin(s.payout))
+        return 'The script’s payout limits are each 0.01% to 100%, over a window of 10 seconds to a day.';
+    if (rules.creatorLockDays > 0)
+        return 'A creator fee run by a program can’t come with the creator wallet lock: the program vests your first buy instead.';
+    if (creatorFeeBps === 0)
+        return 'There is no creator fee for the script to spend: set one.';
+    if (splitPaysHolders(split) && !rewardsOn(rules))
+        return 'A share of the creator fee for holders needs holder rewards on.';
+    return null;
+}
+// ---- Payees and wallet payouts (2026-10-13, docs/payees-and-wallet-payouts.md) ---------------------
+/** The most wallets that share a launcher's part (`set_payees`; the SDK's `MAX_PAYEES`). */
+export const MAX_PAYEES = 10;
+/** The system program's id, the default key: never a payee. */
+const DEFAULT_KEY = '11111111111111111111111111111111';
+/** 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 function payeesRequestOf(companion) {
+    if (typeof companion !== 'object' || companion === null)
+        return null;
+    const raw = companion.payees;
+    if (raw === undefined || raw === null)
+        return null;
+    if (!Array.isArray(raw))
+        return 'malformed';
+    if (raw.length === 0)
+        return null;
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== 'object' || entry === null)
+            return 'malformed';
+        const e = entry;
+        if (typeof e.wallet !== 'string' || !BASE58_ADDRESS.test(e.wallet) || typeof e.bps !== 'number' || !Number.isInteger(e.bps))
+            return 'malformed';
+        out.push({ wallet: e.wallet, bps: e.bps });
+    }
+    return out;
+}
+/** What the payees leave the launcher of their part, basis points of it (10,000 with none). */
+export const payeesLeaveBps = (payees) => 10_000 - payees.reduce((sum, p) => sum + p.bps, 0);
+/**
+ * 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 function payeesProblem(payees, split, beneficiary, reserved = []) {
+    if (payees.length === 0 || payees.length > MAX_PAYEES)
+        return `Up to ${MAX_PAYEES} wallets can share your part.`;
+    if (split.beneficiaryBps <= 0)
+        return 'The wallets share your part of the creator fee, and this split leaves you none.';
+    if (payees.some((p) => !Number.isInteger(p.bps) || p.bps < 1 || p.bps > 10_000))
+        return 'Each wallet gets 0.01% to 100% of your part.';
+    if (payeesLeaveBps(payees) < 0)
+        return 'The wallets’ shares add up to more than 100% of your part.';
+    const seen = new Set();
+    for (const p of payees) {
+        if (!BASE58_ADDRESS.test(p.wallet) || p.wallet === DEFAULT_KEY)
+            return `${p.wallet} is not a wallet.`;
+        if (seen.has(p.wallet))
+            return 'Name each wallet once.';
+        seen.add(p.wallet);
+        if (p.wallet === beneficiary)
+            return 'You keep what the wallets don’t take: name wallets other than your own.';
+        if (reserved.includes(p.wallet))
+            return 'A wallet can’t be the hook’s own account.';
+    }
+    return 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 function walletPayoutsProblem(allow, script) {
+    if (!allow)
+        return null;
+    if (!script)
+        return 'Only a custom hook’s script can pay wallets.';
+    if (!script.payout)
+        return 'A script pays wallets only within payout limits: set them.';
+    return null;
+}
+// ---- Loss cover (2026-10-12; the site says Lossback): the pot pays holders who are under water (docs/loss-cover.md) ----
+/**
+ * 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 const LOSS_COVER_LIMITS = {
+    minRoundSecs: 60,
+    maxRoundSecs: DAY_SECS,
+    minStepSecs: 10,
+    maxStepSecs: 3_600,
+    /** The step is at most this part of the round: a round has at least four steps. */
+    stepsPerRoundMin: 4,
+    minBps: 100,
+    maxBps: 10_000,
+    minCoverBps: 1_000,
+    maxCoverBps: 10_000,
+    /** The least holding that counts, at most this part of the supply (basis points). */
+    maxMinHoldingBps: 100,
+    minMinLossLamports: 100000n,
+    maxMinAgeSecs: DAY_SECS,
+    maxMinPotLamports: 100000000000n,
+    batchPaying: 7,
+    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 function ageWords(secs) {
+    if (secs % 60 !== 0 || secs < 60)
+        return `${secs} second${secs === 1 ? '' : 's'}`;
+    const m = secs / 60;
+    return `${m} minute${m === 1 ? '' : 's'}`;
+}
+export const LOSS_COVER_DEFAULTS = {
+    potBps: 10_000,
+    roundSecs: 300,
+    stepSecs: 15,
+    roundBps: 10_000,
+    stepBps: 10_000,
+    holdingBps: 10_000,
+    coverBps: 10_000,
+    minHolding: '100000000000',
+    minLossLamports: '1000000',
+    minAgeSecs: 60,
+    minPotLamports: '1000000000',
+};
+/** The round lengths the launch form offers (seconds): 5, 10, 30 and 60 minutes. */
+export const LOSS_COVER_ROUND_CHOICES_SECS = [300, 600, 1_800, 3_600];
+/** The cover shares the launch form offers: the whole loss, half, a quarter. */
+export const LOSS_COVER_COVER_CHOICES_BPS = [10_000, 5_000, 2_500];
+/** The minimum pots the launch form offers, lamports: none, 0.5, 1, 5 SOL. */
+export const LOSS_COVER_MIN_POT_CHOICES_LAMPORTS = ['0', '500000000', '1000000000', '5000000000'];
+const LAMPORTS = /^\d{1,20}$/;
+/** 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 function lossCoverRequestOf(companion) {
+    if (typeof companion !== 'object' || companion === null)
+        return null;
+    const raw = companion.lossCover;
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'object')
+        return 'malformed';
+    const r = raw;
+    if (typeof r.roundSecs !== 'number' || !Number.isInteger(r.roundSecs) || !isShare(r.coverBps))
+        return 'malformed';
+    if (typeof r.minPotLamports !== 'string' || !LAMPORTS.test(r.minPotLamports) || typeof r.minHolding !== 'string' || !LAMPORTS.test(r.minHolding))
+        return 'malformed';
+    return { roundSecs: r.roundSecs, minPotLamports: r.minPotLamports, coverBps: r.coverBps, minHolding: r.minHolding };
+}
+/** The full terms a request launches with: what it names, the rest from `LOSS_COVER_DEFAULTS`. */
+export function lossCoverTermsOf(s) {
+    const D = LOSS_COVER_DEFAULTS;
+    return { roundSecs: s.roundSecs, stepSecs: D.stepSecs, stepBps: D.stepBps, holdingBps: D.holdingBps, roundBps: D.roundBps, coverBps: s.coverBps, minHolding: s.minHolding, minLossLamports: D.minLossLamports, minAgeSecs: D.minAgeSecs, minPotLamports: s.minPotLamports };
+}
+/** 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 const lossCoverPotBps = (split) => 10_000 - split.buybackBps - split.holdersBps - split.beneficiaryBps;
+/**
+ * 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 function lossCoverProblem(s, split, rules, creatorFeeBps, supply = TOKEN_SUPPLY) {
+    const L = LOSS_COVER_LIMITS;
+    const D = LOSS_COVER_DEFAULTS;
+    if (creatorFeeBps === 0)
+        return 'There is no creator fee to fill the pot with: set one.';
+    if (Object.keys(NO_RULES).some((k) => rules[k] !== 0))
+        return 'A Lossback coin has no other token rules: its hook keeps each holding’s entry price.';
+    if (split.buybackBps !== 0 || split.holdersBps !== 0)
+        return 'A Lossback coin’s creator fee goes to its pot and to the launcher: nothing bought back, no holders’ part.';
+    const potBps = lossCoverPotBps(split);
+    if (!(potBps > 0) || !isShare(split.beneficiaryBps))
+        return 'The pot’s part and the launcher’s must add up to 100%, with a part for the pot.';
+    if (!Number.isInteger(s.roundSecs) || s.roundSecs < L.minRoundSecs || s.roundSecs > L.maxRoundSecs)
+        return 'A round lasts a minute to a day.';
+    if (s.roundSecs < D.stepSecs * L.stepsPerRoundMin)
+        return `A round holds at least ${L.stepsPerRoundMin} steps of ${D.stepSecs} seconds.`;
+    if (!Number.isInteger(s.coverBps) || s.coverBps < L.minCoverBps || s.coverBps > L.maxCoverBps)
+        return 'The pot covers 10% to 100% of a loss.';
+    const minHolding = BigInt(s.minHolding);
+    if (minHolding < 1n || minHolding > (supply * BigInt(L.maxMinHoldingBps)) / BPS)
+        return 'The least holding that counts is at least one base unit and at most 1% of the supply.';
+    const minPot = BigInt(s.minPotLamports);
+    if (minPot > L.maxMinPotLamports)
+        return 'The minimum pot is at most 100 SOL.';
+    return 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 function lossCoverSentence(s, decimals = TOKEN_DECIMALS) {
+    const D = LOSS_COVER_DEFAULTS;
+    const minutes = Math.round(s.roundSecs / 60);
+    const pot = Number(BigInt(s.minPotLamports)) / 1e9;
+    const holding = Number(BigInt(s.minHolding)) / 10 ** decimals;
+    const loss = Number(BigInt(D.minLossLamports)) / 1e9;
+    const share = s.coverBps === 10_000 ? 'the same share of what they are down' : `the same share of ${s.coverBps / 100}% of what they are down`;
+    const once = pot > 0 ? `, once the pot holds ${pot} SOL,` : '';
+    return `Every ${minutes} minutes${once} it pays every holder under water ${share}, as much as the pot allows, in steps of ${D.stepSecs} seconds; a holding counts from ${holding.toLocaleString('en-US')} tokens and ${loss} SOL of loss, ${ageWords(D.minAgeSecs)} after it bought.`;
+}
 /** The template whose split this is, or null for any other split. */
 export function companionTemplateOf(split) {
     return COMPANION_TEMPLATE_LIST.find((t) => {