@bordrless/shared 0.7.0 → 0.9.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,22 +490,126 @@ 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). */
+export const GAME_KIND_LIMITS = { minTimerSecs: 300, maxTimerSecs: 30 * DAY_SECS, maxMinStreakSecs: 365 * DAY_SECS };
+/** A jackpot as the launch form starts it (spec example 2, `JACKPOT_DEFAULTS` in the SDK): 70% of the fee to the pot, 30% bought back, half the pot to the last buyer from 0.5 SOL. */
+export const JACKPOT_REQUEST_DEFAULTS = { kind: 'jackpot', potBps: 7_000, minPotLamports: '500000000', prizeBps: 5_000 };
+/** A streak as the launch form starts it (spec example 3, `STREAK_DEFAULTS` in the SDK): 70% of the fee to the pot, 30% bought back, the whole pot shared each epoch from 0.1 SOL, an hour at least for claims. */
+export const STREAK_REQUEST_DEFAULTS = { kind: 'streak', potBps: 7_000, minPotLamports: '100000000', prizeBps: 10_000, claimWindowSecs: 3_600 };
+/** The least a streak's close leaves for claims, as the form offers it (seconds); each must fit half the hook's epoch. */
+export const STREAK_CLAIM_WINDOW_CHOICES = [
+    { secs: 1_800, label: '30 min' },
+    { secs: 3_600, label: '1 hour' },
+    { secs: 21_600, label: '6 hours' },
+    { secs: DAY_SECS, label: '1 day' },
+];
+/** The game a launch request's `companion.game` names, of any kind, each field a whole number; null when malformed (bounds are `gameProblem`'s). */
+export function gameRequestOf(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const r = raw;
+    if (r.kind === 'lottery')
+        return lotteryRequestOf(raw);
+    if (r.kind !== 'jackpot' && r.kind !== 'streak')
+        return null;
+    if (!isWhole(r.potBps, 0, 10_000) || !isWhole(r.prizeBps, 0, 10_000))
+        return null;
+    if (typeof r.minPotLamports !== 'string' || !/^\d{1,20}$/.test(r.minPotLamports))
+        return null;
+    if (r.kind === 'jackpot')
+        return { kind: 'jackpot', potBps: r.potBps, minPotLamports: r.minPotLamports, prizeBps: r.prizeBps };
+    if (!isWhole(r.claimWindowSecs, 0, 2 ** 32 - 1))
+        return null;
+    return { kind: 'streak', potBps: r.potBps, minPotLamports: r.minPotLamports, prizeBps: r.prizeBps, claimWindowSecs: r.claimWindowSecs };
+}
+/**
+ * Why `create_game_v2` (or the launch) would refuse this game with this split on these rules at
+ * this fee, with `hook` the Studio game hook the config names (`ConfigInspection.game`; null: the
+ * config names none), in one sentence; null when it would not. A lottery is `lotteryProblem`'s.
+ * The program's own checks (`gameArgsProblem` in the SDK, the same sentences) and what a game
+ * coin's launch needs besides: a creator fee, no token rules, no holders' share, and a hook of the
+ * game's kind.
+ */
+export function gameProblem(game, split, rules, creatorFeeBps, hook = null) {
+    if (game.kind === 'lottery')
+        return lotteryProblem(game, split, rules, creatorFeeBps);
+    const L = LOTTERY_LIMITS;
+    const word = GAME_KIND_NAMES[game.kind];
+    if (!hook)
+        return `A ${word} coin launches from a game hook made in Studio: open your ${word} project there and press Launch with it.`;
+    if (hook.kind !== game.kind)
+        return `This config’s hook keeps a ${GAME_KIND_NAMES[hook.kind]}’s score, not a ${word}’s.`;
+    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 ${word} coin has no other token rules: its hook keeps the score.`;
+    if (split.holdersBps !== 0)
+        return 'A game coin runs its own hook, so it has no holder rewards: no holders’ part.';
+    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.';
+    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 game pays 10% to 100% of the pot at a time.';
+    if (game.kind === 'jackpot') {
+        if (hook.timerSecs < GAME_KIND_LIMITS.minTimerSecs || hook.timerSecs > GAME_KIND_LIMITS.maxTimerSecs)
+            return 'A jackpot’s timer lasts 5 minutes to 30 days.';
+        if (BigInt(hook.minTokens) < 1n)
+            return 'A qualifying buy is at least one base unit.';
+        return null;
+    }
+    if (hook.roundSecs < L.minEpochSecs || hook.roundSecs > L.maxRoundSecs)
+        return 'An epoch lasts an hour to 30 days.';
+    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.';
+    if (BigInt(hook.minWeight) < 1n)
+        return 'The least weight that shares is at least one base unit.';
+    return null;
+}
+/** Each game kind in a word: "jackpot". */
+export const GAME_KIND_NAMES = { lottery: 'lottery', jackpot: 'jackpot', streak: 'streak', strategy: 'strategy' };
+/**
+ * The copy rules of a jackpot and a streak coin (docs/games.md "Phase 2", "Site"): said on the
+ * launch form, the review step and the token page. The pot is held by the companion and paid by
+ * code (no randomness in either kind), the 10 SOL cap until the hook is audited, "Bordrless can
+ * stop this game"; never "provably fair", "guaranteed" or "audited".
+ */
+export const JACKPOT_COPY = {
+    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 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;
@@ -532,6 +661,132 @@ 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';
+    return { potBps: r.potBps, program: r.program, interval: r.interval, initData, stateLen: r.stateLen };
+}
+/**
+ * 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 (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;
+}
 /** The template whose split this is, or null for any other split. */
 export function companionTemplateOf(split) {
     return COMPANION_TEMPLATE_LIST.find((t) => {

package/dist/programs.d.ts

@@ -22,7 +22,25 @@ export declare const PROGRAM_IDS: {
      * (2026-10-08): companion v2 and this hook go live together, after their audit.
      */
     readonly lotteryHook: "HqFWsCBQ416DAfevJ9TspyT5yXGGoYTCpcreiGkCgWcr";
+    /**
+     * `hook_timelock` (phase 3a, bordrless-programs docs/phase3a.md §3): a hook's or a strategy's
+     * upgrade authority behind a public delay of at least 3 days; its only exit is "immutable". Not
+     * deployed yet (2026-10-09).
+     */
+    readonly hookTimelock: "BBUzaamchPWZpKENmn7bopiuQWvRGm2Vg8TqLLgzgGGZ";
+    /**
+     * `hook_vault` (phase 3a, §5): where a hook's cuts go, each slot with a policy fixed before the
+     * launch (burn, sell for SOL to a fixed wallet, sell and buy-and-burn another token), run by a
+     * permissionless crank under the companion's buyback guards. Not deployed yet (2026-10-09).
+     */
+    readonly hookVault: "5cojoUStG7WFhHJiSncCUEwTqDuhDLKu4a9BqTbF8jzG";
 };
+/**
+ * Bordrless Studio's attester (phase 3a, docs/phase3a.md §6): a hot key of Studio's build worker,
+ * the only signer of the companion's `HookAttestation` ("Bordrless rebuilt this source, its hash is
+ * the code on chain, the checks, the simulator and the review passed"). Not Studio's upgrade key.
+ */
+export declare const STUDIO_ATTESTER = "3uGLsTJNse7vE3pgRkAf6aKKBoKmCyPUcNNu1bw3KvP2";
 /**
  * The lottery hook's fixed facts (programs/lottery_hook/README.md): the flags a `LaunchConfig`
  * names for it (`BEFORE_TRANSFER | BEFORE_BURN | WRITES_HOOK_DATA`, exactly what a companion game

package/dist/programs.js

@@ -22,7 +22,25 @@ export const PROGRAM_IDS = {
      * (2026-10-08): companion v2 and this hook go live together, after their audit.
      */
     lotteryHook: 'HqFWsCBQ416DAfevJ9TspyT5yXGGoYTCpcreiGkCgWcr',
+    /**
+     * `hook_timelock` (phase 3a, bordrless-programs docs/phase3a.md §3): a hook's or a strategy's
+     * upgrade authority behind a public delay of at least 3 days; its only exit is "immutable". Not
+     * deployed yet (2026-10-09).
+     */
+    hookTimelock: 'BBUzaamchPWZpKENmn7bopiuQWvRGm2Vg8TqLLgzgGGZ',
+    /**
+     * `hook_vault` (phase 3a, §5): where a hook's cuts go, each slot with a policy fixed before the
+     * launch (burn, sell for SOL to a fixed wallet, sell and buy-and-burn another token), run by a
+     * permissionless crank under the companion's buyback guards. Not deployed yet (2026-10-09).
+     */
+    hookVault: '5cojoUStG7WFhHJiSncCUEwTqDuhDLKu4a9BqTbF8jzG',
 };
+/**
+ * Bordrless Studio's attester (phase 3a, docs/phase3a.md §6): a hot key of Studio's build worker,
+ * the only signer of the companion's `HookAttestation` ("Bordrless rebuilt this source, its hash is
+ * the code on chain, the checks, the simulator and the review passed"). Not Studio's upgrade key.
+ */
+export const STUDIO_ATTESTER = '3uGLsTJNse7vE3pgRkAf6aKKBoKmCyPUcNNu1bw3KvP2';
 /**
  * The lottery hook's fixed facts (programs/lottery_hook/README.md): the flags a `LaunchConfig`
  * names for it (`BEFORE_TRANSFER | BEFORE_BURN | WRITES_HOOK_DATA`, exactly what a companion game