@bordrless/shared 0.1.0 → 0.3.0

package/README.md

@@ -27,8 +27,8 @@ TOKEN_HOOK_FLAGS.BEFORE_TRANSFER | TOKEN_HOOK_FLAGS.TRANSFER_RETURNS_DELTA;
 
 ## Where to read more
 
-- The SDK page: https://bordrless.xyz/sdk
-- The standard in full: https://bordrless.xyz/docs
+- The SDK page: https://bordrless.app/sdk
+- The standard in full: https://bordrless.app/docs
 
 Status: the programs run on localnet and devnet until they are deployed to mainnet; they keep an
 upgrade authority until audited.

package/dist/api.d.ts

@@ -143,6 +143,12 @@ export interface ConfigInspection {
     /** As `CustomHookInfo.upgradeable`; null without a hook or when its program could not be read. */
     hookUpgradeable: boolean | null;
     registryReady: boolean | null;
+    /** The hook is Half-Life: the launch prepares it for the mint and lights its furnace itself. */
+    halfLife?: boolean;
+    /** A listed config's author share of the creator fee (bps of it), paid on a launch by anyone but its author; 0 for a plain config. */
+    authorShareBps: number;
+    /** The hook was built and deployed by Studio: the launch prepares it for the mint itself (its standard `prepare`). */
+    studioHook?: boolean;
 }
 /** Live figures of a launch's token rules; each null when the launch lacks the rule or it is not tracked. */
 export interface RuleStats {
@@ -351,12 +357,27 @@ export interface PortfolioEntry {
     /** For a launch token with a creator's own hook (§5.8): the hook, so the row can say so; null otherwise (absent from backends that predate it). */
     customHook?: CustomHookInfo | null;
 }
+/** A launch the wallet created, with the creator fee waiting for it (`Portfolio.created`). */
+export interface CreatedLaunch {
+    mint: Address;
+    symbol: string;
+    name: string;
+    image: string | null;
+    status: LaunchStatus;
+    creatorFeeBps: number;
+    /** Lamports of bridged SOL accrued and not yet claimed (the launch's quote holding, what a claim pays); null when the chain could not be read. */
+    claimable: Amount | null;
+    /** Lamports claimed here, all time; null when not known. */
+    claimedTotal?: Amount | null;
+}
 export interface Portfolio {
     owner: Address;
     lamports: Amount;
     /** What the wallet holds, plus launches it no longer holds when it has holder rewards to claim there. */
     entries: PortfolioEntry[];
     totalUsd: number | null;
+    /** The launches this wallet created, those with fees to claim first (absent from backends that predate it). */
+    created: CreatedLaunch[];
 }
 /** Native SOL (bridged on the way in, unbridged on the way out) or bridged SOL already held. */
 export type SolMode = 'SOL' | 'BSOL';
@@ -518,6 +539,11 @@ export interface RewardsPrepareRequest {
     /** Unwrap the bridged SOL to SOL and close the temporary holding. */
     unwrap: boolean;
 }
+/** Claim the creator fees of launches the owner created: up to about 4 mints per transaction, paid as SOL. */
+export interface CreatorPrepareRequest {
+    owner: Address;
+    mints: Address[];
+}
 /** Share with holders: send SOL that every holder of the token receives pro rata. */
 export interface SharePrepareRequest {
     owner: Address;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './api.ts';
 export * from './policy.ts';
 export * from './programs.ts';
+export * from './studio.ts';

package/dist/index.js

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

package/dist/policy.d.ts

@@ -230,9 +230,14 @@ export declare const rewardsOn: (r: Pick<LaunchRulesInput, "holderFeeBuyBps" | "
 export declare const defaultCreatorFeeBps: (r: LaunchRulesInput) => number;
 /** The four presets of §7.1 (2026-10-07: Holders first, Fair start, Scorched and Community are gone). */
 export type RulePresetName = 'Plain' | 'Diamond hands' | 'Burn' | 'Paid to hold';
-/** The two ways beside the presets (§7.1): Custom mixes the rules by hand with the form's controls; Build your own launches from a `LaunchConfig` a creator made with the SDK (§5.7). */
-export type RulePathName = 'Custom' | 'Build your own';
-/** What the launch form's rules row can be set to: a preset, or one of the two paths. */
+/**
+ * The ways beside the presets (§7.1): Half-Life launches from Bordrless's own `LaunchConfig` with
+ * the Half-Life hook (programs/half_life), prepared and lit for the mint by the launch itself;
+ * Custom mixes the rules by hand with the form's controls; Build your own launches from a
+ * `LaunchConfig` a creator made with the SDK (§5.7).
+ */
+export type RulePathName = 'Half-Life' | 'Custom' | 'Build your own';
+/** What the launch form's rules row can be set to: a preset, or one of the paths. */
 export type RuleModeName = RulePresetName | RulePathName;
 export interface RulePreset {
     name: RulePresetName;
@@ -259,7 +264,7 @@ export interface RulePath {
  * every one). Holder rewards set "both sides" take the same rate on buys and sells.
  */
 export declare const RULE_PRESETS: readonly RulePreset[];
-/** The two paths beside the presets, in order, with the words the home console and the launch form print. */
+/** The paths beside the presets, in order, with the words the home console and the launch form print. */
 export declare const RULE_PATHS: readonly RulePath[];
 /** The preset the launch form starts on. */
 export declare const DEFAULT_RULE_PRESET: RulePresetName;
@@ -332,7 +337,7 @@ export declare function launchBeforeSwap(side: Side, amountIn: bigint, p: Launch
 export declare function launchAfterSwap(side: Side, amountOut: bigint, p: LaunchFeeParams): HookCut;
 /** A swap on a launch pool, step by step. */
 export interface LaunchSwap {
-    /** Bridged SOL to the creator: from a buy's input, or from a sell's output after the protocol fee. */
+    /** Bridged SOL to the creator: from a buy's input, or from a sell's output after the LP fee. */
     creatorFee: bigint;
     /** Bridged SOL to holders, likewise. */
     holderFee: bigint;
@@ -342,13 +347,13 @@ export interface LaunchSwap {
     holderFeeOn: boolean;
     /** What reached the input vault. */
     received: bigint;
-    /** The LP fee, in the input token, on what reached the vault. */
+    /** The LP fee, Bordrless's in bridged SOL (it never stays in a launch pool): on a buy from what reached the vault, on a sell from the curve's output. The DEX's event reports it inside `protocol_fee` with `lp_fee` 0. */
     lpFee: bigint;
     /** Bordrless's share of the creator and holder fees (`LAUNCH_PROTOCOL_SHARE_BPS` of them, rounded up; 0 when they are 0), always in bridged SOL: on a buy from what reached the vault, before the curve; on a sell held back from the delivery. */
     protocolFee: bigint;
-    /** What went into the curve: `received` less the LP fee (and, on a buy, the protocol fee); negative when the fees take more than arrived. */
+    /** What went into the curve: on a buy `received` less the LP fee and the protocol fee (negative when they take more than arrived); on a sell `received`. */
     netIn: bigint;
-    /** What the curve gave (on a sell, before the protocol fee and the creator and holder fees); null when the swap fails. */
+    /** What the curve gave (on a sell, before the LP fee, the creator and holder fees and the protocol fee); null when the swap fails. */
     amountOut: bigint | null;
     /** What reaches the recipient; null when the swap fails. */
     delivered: bigint | null;
@@ -362,21 +367,26 @@ export declare function curveOutput(r: Reserves, side: Side, netIn: bigint): big
  * §5.4; the Rust reference is `bordrless_program_tests::launch::quote_launch_swap`): Bordrless
  * takes `protocolShareBps` of the creator and holder fees (the hooks' cuts; the kit takes none of
  * its own, so the cuts are exactly those fees), in bridged SOL, and nothing when they are nothing.
- * A buy: the creator and holder fees from the input, Bordrless's share of them and the LP fee on
- * what reached the vault, the curve, the burn from the output. A sell: the burn from the input, the
- * LP fee on what reached the vault, the curve, then the creator and holder fees from the output and
- * Bordrless's share of them held back from the delivery. A sell takes its input out of the kit's
- * eligible count before `after_swap` reads it (every seller is a holder: the pool and the launch
- * never sell). An ordinary pool's flat rate is `quoteSwap`.
+ * A buy: the creator and holder fees from the input, Bordrless's share of them and the LP fee (both
+ * Bordrless's, in SOL) on what reached the vault, the curve, the burn from the output. A sell: the
+ * burn from the input, the curve on all the rest, the LP fee (Bordrless's) from the curve's output,
+ * then the creator and holder fees from what is left and Bordrless's share of them held back from the
+ * delivery. A launch pool's LP fee never stays in the pool (its LP is locked for ever). A sell takes
+ * its input out of the kit's eligible count before `after_swap` reads it (every seller is a holder:
+ * the pool and the launch never sell). An ordinary pool's flat rate is `quoteSwap`.
  */
 export declare function quoteLaunchSwap(r: Reserves, side: Side, amountIn: bigint, lpFeeBps: number, protocolShareBps: number, p: LaunchFeeParams): LaunchSwap;
-/** What a launch-pool swap adds to its input reserve (the Rust reference's `to_reserve_in`): what reached the vault, less a buy's protocol fee. */
-export declare const launchSwapToReserve: (side: Side, q: Pick<LaunchSwap, "received" | "protocolFee">) => bigint;
 /**
- * Whether a buy that lands leaves the pool's quote reserve at or above the graduation threshold, so
- * `graduate` can follow it in the same transaction (§8.2: the input after the creator and holder
- * fees, less the protocol fee, joins the reserve; the launch graduates once `quote_reserve >=
- * graduation_quote`).
+ * What a launch-pool swap adds to its input reserve (the Rust reference's `to_reserve_in`): on a buy
+ * what goes into the curve (what reached the vault less the LP fee and the share, both Bordrless's;
+ * 0 when they take it all), on a sell what reached the vault.
+ */
+export declare const launchSwapToReserve: (side: Side, q: Pick<LaunchSwap, "received" | "netIn">) => bigint;
+/**
+ * Whether a buy that lands leaves the launch ready to graduate, so `graduate` can follow it in the
+ * same transaction: the pool's quote reserve at or above the graduation threshold, or the curve sold
+ * out (the buy takes every token it has left). The LP fee does not compound, so the two come
+ * together, and a hook's cut on buys can keep the reserve just short of the threshold.
  */
 export declare function buyGraduates(r: Reserves, q: LaunchSwap, graduationQuote: bigint): boolean;
 /**

package/dist/policy.js

@@ -334,8 +334,9 @@ export const RULE_PRESETS = [
     { name: 'Burn', slug: 'burn', description: 'Burn 0.5% on buys and sells, holder rewards 0.5%, creator fee 0.5%.', creatorFeeBps: 50, rules: { ...NO_RULES, holderFeeBuyBps: 50, holderFeeSellBps: 50, burnBuyBps: 50, burnSellBps: 50 } },
     { name: 'Paid to hold', slug: 'paid-to-hold', description: 'Holder rewards 2% on sells only, creator wallet lock 30 d, creator fee 0.5%.', creatorFeeBps: 50, rules: { ...NO_RULES, holderFeeSellBps: 200, creatorLockDays: 30 } },
 ];
-/** The two paths beside the presets, in order, with the words the home console and the launch form print. */
+/** The paths beside the presets, in order, with the words the home console and the launch form print. */
 export const RULE_PATHS = [
+    { name: 'Half-Life', slug: 'half-life', description: 'An exit fee that halves every 6 hours held: 20% to sell at once, 0% after 2 days, burned. Buys are free.' },
     { name: 'Custom', slug: 'custom', description: 'Mix the rules by hand; holder rewards and burn can differ on buys and sells.' },
     { name: 'Build your own', slug: 'build-your-own', description: 'Write a hook with the SDK, make a launch config, paste its key.' },
 ];
@@ -482,23 +483,25 @@ export function curveOutput(r, side, netIn) {
  * §5.4; the Rust reference is `bordrless_program_tests::launch::quote_launch_swap`): Bordrless
  * takes `protocolShareBps` of the creator and holder fees (the hooks' cuts; the kit takes none of
  * its own, so the cuts are exactly those fees), in bridged SOL, and nothing when they are nothing.
- * A buy: the creator and holder fees from the input, Bordrless's share of them and the LP fee on
- * what reached the vault, the curve, the burn from the output. A sell: the burn from the input, the
- * LP fee on what reached the vault, the curve, then the creator and holder fees from the output and
- * Bordrless's share of them held back from the delivery. A sell takes its input out of the kit's
- * eligible count before `after_swap` reads it (every seller is a holder: the pool and the launch
- * never sell). An ordinary pool's flat rate is `quoteSwap`.
+ * A buy: the creator and holder fees from the input, Bordrless's share of them and the LP fee (both
+ * Bordrless's, in SOL) on what reached the vault, the curve, the burn from the output. A sell: the
+ * burn from the input, the curve on all the rest, the LP fee (Bordrless's) from the curve's output,
+ * then the creator and holder fees from what is left and Bordrless's share of them held back from the
+ * delivery. A launch pool's LP fee never stays in the pool (its LP is locked for ever). A sell takes
+ * its input out of the kit's eligible count before `after_swap` reads it (every seller is a holder:
+ * the pool and the launch never sell). An ordinary pool's flat rate is `quoteSwap`.
  */
 export function quoteLaunchSwap(r, side, amountIn, lpFeeBps, protocolShareBps, p) {
     const before = launchBeforeSwap(side, amountIn, p);
     const received = amountIn - before.creatorFee - before.holderFee - before.burn;
     const eligibleAtFees = side === 'sell' ? (p.eligible > amountIn ? p.eligible - amountIn : 0n) : p.eligible;
     const holderFeeOn = (side === 'buy' ? p.holderFeeBuyBps : p.holderFeeSellBps) > 0 && eligibleAtFees >= p.minEligible;
-    const lpFee = feeAmount(received, lpFeeBps);
+    // A buy's LP fee is on the SOL that reached the vault; a sell's on the curve's output.
+    const buyLpFee = side === 'buy' ? feeAmount(received, lpFeeBps) : 0n;
     // A buy's cuts are the hook's quote fees; a sell's input side cuts nothing (the burn is not a cut), so its share is taken from the output.
     const inputProtocolFee = side === 'buy' ? protocolShare(before.creatorFee + before.holderFee, protocolShareBps) : 0n;
-    const netIn = received - lpFee - inputProtocolFee;
-    const failed = (failure, protocolFee = inputProtocolFee) => ({ ...before, holderFeeOn, received, lpFee, protocolFee, netIn, amountOut: null, delivered: null, failure });
+    const netIn = received - buyLpFee - inputProtocolFee;
+    const failed = (failure, protocolFee = inputProtocolFee, carried = {}) => ({ ...before, holderFeeOn, received, lpFee: buyLpFee, protocolFee, netIn, amountOut: null, delivered: null, failure, ...carried });
     if (received <= 0n || netIn <= 0n)
         return failed('fees_exceed_input');
     const out = curveOutput(r, side, netIn);
@@ -508,24 +511,33 @@ export function quoteLaunchSwap(r, side, amountIn, lpFeeBps, protocolShareBps, p
         return failed('insufficient_liquidity');
     if (side === 'buy') {
         const after = launchAfterSwap('buy', out, p);
-        return { ...before, burn: after.burn, holderFeeOn, received, lpFee, protocolFee: inputProtocolFee, netIn, amountOut: out, delivered: out - after.burn, failure: null };
+        return { ...before, burn: after.burn, holderFeeOn, received, lpFee: buyLpFee, protocolFee: inputProtocolFee, netIn, amountOut: out, delivered: out - after.burn, failure: null };
     }
-    const after = launchAfterSwap('sell', out, { ...p, eligible: eligibleAtFees });
+    // A sell: the LP fee leaves the curve's output before the hook is told the rest.
+    const lpFee = feeAmount(out, lpFeeBps);
+    if (lpFee >= out)
+        return failed('no_output', 0n, { lpFee });
+    const told = out - lpFee;
+    const after = launchAfterSwap('sell', told, { ...p, eligible: eligibleAtFees });
     const protocolFee = protocolShare(after.creatorFee + after.holderFee, protocolShareBps);
-    if (after.creatorFee + after.holderFee + protocolFee >= out)
-        return failed('no_output', protocolFee);
-    return { creatorFee: after.creatorFee, holderFee: after.holderFee, burn: before.burn, holderFeeOn, received, lpFee, protocolFee, netIn, amountOut: out, delivered: out - after.creatorFee - after.holderFee - protocolFee, failure: null };
+    if (after.creatorFee + after.holderFee + protocolFee >= told)
+        return failed('no_output', protocolFee, { creatorFee: after.creatorFee, holderFee: after.holderFee, lpFee });
+    return { creatorFee: after.creatorFee, holderFee: after.holderFee, burn: before.burn, holderFeeOn, received, lpFee, protocolFee, netIn, amountOut: out, delivered: told - after.creatorFee - after.holderFee - protocolFee, failure: null };
 }
-/** What a launch-pool swap adds to its input reserve (the Rust reference's `to_reserve_in`): what reached the vault, less a buy's protocol fee. */
-export const launchSwapToReserve = (side, q) => (side === 'buy' ? q.received - q.protocolFee : q.received);
 /**
- * Whether a buy that lands leaves the pool's quote reserve at or above the graduation threshold, so
- * `graduate` can follow it in the same transaction (§8.2: the input after the creator and holder
- * fees, less the protocol fee, joins the reserve; the launch graduates once `quote_reserve >=
- * graduation_quote`).
+ * What a launch-pool swap adds to its input reserve (the Rust reference's `to_reserve_in`): on a buy
+ * what goes into the curve (what reached the vault less the LP fee and the share, both Bordrless's;
+ * 0 when they take it all), on a sell what reached the vault.
+ */
+export const launchSwapToReserve = (side, q) => (side === 'buy' ? (q.netIn > 0n ? q.netIn : 0n) : q.received);
+/**
+ * Whether a buy that lands leaves the launch ready to graduate, so `graduate` can follow it in the
+ * same transaction: the pool's quote reserve at or above the graduation threshold, or the curve sold
+ * out (the buy takes every token it has left). The LP fee does not compound, so the two come
+ * together, and a hook's cut on buys can keep the reserve just short of the threshold.
  */
 export function buyGraduates(r, q, graduationQuote) {
-    return q.failure === null && r.quoteReserve + launchSwapToReserve('buy', q) >= graduationQuote;
+    return q.failure === null && (r.quoteReserve + launchSwapToReserve('buy', q) >= graduationQuote || q.amountOut === r.baseReserve);
 }
 /**
  * §8.2 `maxAmountIn` on a curve pool: the largest buy the curve can still fill with these fees (one

package/dist/programs.d.ts

@@ -12,7 +12,33 @@ export declare const PROGRAM_IDS: {
     readonly taxHook: "8tjnVSreJGBRQFyDBf1SyyhBgLsdBxa2rHYh9sbxFyX7";
     /** The v2 token-rules hook (docs/hooks-v2.md §4): holder rewards, max wallet and the two locks. */
     readonly kit: "14RJQXPdJfkehit6ezktjd3xujamf8nVSKw2shKamaEH";
+    /** Half-Life (programs/half_life): an exit fee that halves every six hours a token is held, burned. */
+    readonly halfLife: "53SpmtkdPWQ63mWoDeXk8P9tuwiT4ed2Wx4fwfy5NSF8";
 };
+/**
+ * Half-Life, Bordrless's own token hook (programs/half_life/README.md): the `LaunchConfig` the
+ * launch form's Half-Life path launches from (no kit rules, creator fee 1%, the hook with
+ * `flags`), and the fee curve the program has fixed: `maxFeePpm` for tokens that just arrived,
+ * halved every `halfLifeSecs`, linear within each, zero from `zeroAfterSecs`.
+ */
+export declare const HALF_LIFE: {
+    readonly program: "53SpmtkdPWQ63mWoDeXk8P9tuwiT4ed2Wx4fwfy5NSF8";
+    readonly launchConfig: "ABz5Je9FznnotUQxxaj28vn18t1Wv9SsDzEfDxGLRJY";
+    /** `BEFORE_TRANSFER | TRANSFER_RETURNS_DELTA | WRITES_HOOK_DATA`. */
+    readonly flags: 193;
+    readonly creatorFeeBps: 100;
+    readonly maxFeePpm: 200000;
+    readonly halfLifeSecs: 21600;
+    readonly zeroAfterSecs: 172800;
+    /** The token program's signer of the hook's callbacks (`["hook-authority", half_life]`). */
+    readonly tokenHookSigner: "FBZPj9PmV9dXL8U4qmRffXdXm11e23KEBnNgEVXxhfhF";
+    readonly readme: "https://github.com/BordrlessDex/bordrless-programs/tree/main/programs/half_life";
+};
+/**
+ * Half-Life's exit fee, in parts per million, for tokens `ageSecs` old: the program's `fee_ppm`
+ * (20% at 0, halved every six hours, linear within each, 0 from 48 h).
+ */
+export declare function halfLifeFeePpm(ageSecs: number): number;
 /** The wSOL mint, which stands for native SOL on the bridge. */
 export declare const NATIVE_MINT = "So11111111111111111111111111111111111111112";
 export declare const TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";

package/dist/programs.js

@@ -12,7 +12,43 @@ export const PROGRAM_IDS = {
     taxHook: '8tjnVSreJGBRQFyDBf1SyyhBgLsdBxa2rHYh9sbxFyX7',
     /** The v2 token-rules hook (docs/hooks-v2.md §4): holder rewards, max wallet and the two locks. */
     kit: '14RJQXPdJfkehit6ezktjd3xujamf8nVSKw2shKamaEH',
+    /** Half-Life (programs/half_life): an exit fee that halves every six hours a token is held, burned. */
+    halfLife: '53SpmtkdPWQ63mWoDeXk8P9tuwiT4ed2Wx4fwfy5NSF8',
 };
+/**
+ * Half-Life, Bordrless's own token hook (programs/half_life/README.md): the `LaunchConfig` the
+ * launch form's Half-Life path launches from (no kit rules, creator fee 1%, the hook with
+ * `flags`), and the fee curve the program has fixed: `maxFeePpm` for tokens that just arrived,
+ * halved every `halfLifeSecs`, linear within each, zero from `zeroAfterSecs`.
+ */
+export const HALF_LIFE = {
+    program: PROGRAM_IDS.halfLife,
+    launchConfig: 'ABz5Je9FznnotUQxxaj28vn18t1Wv9SsDzEfDxGLRJY',
+    /** `BEFORE_TRANSFER | TRANSFER_RETURNS_DELTA | WRITES_HOOK_DATA`. */
+    flags: 193,
+    creatorFeeBps: 100,
+    maxFeePpm: 200_000,
+    halfLifeSecs: 21_600,
+    zeroAfterSecs: 172_800,
+    /** The token program's signer of the hook's callbacks (`["hook-authority", half_life]`). */
+    tokenHookSigner: 'FBZPj9PmV9dXL8U4qmRffXdXm11e23KEBnNgEVXxhfhF',
+    readme: 'https://github.com/BordrlessDex/bordrless-programs/tree/main/programs/half_life',
+};
+/**
+ * Half-Life's exit fee, in parts per million, for tokens `ageSecs` old: the program's `fee_ppm`
+ * (20% at 0, halved every six hours, linear within each, 0 from 48 h).
+ */
+export function halfLifeFeePpm(ageSecs) {
+    if (!(ageSecs > 0))
+        return HALF_LIFE.maxFeePpm;
+    const halvings = Math.floor(ageSecs / HALF_LIFE.halfLifeSecs);
+    if (halvings >= HALF_LIFE.zeroAfterSecs / HALF_LIFE.halfLifeSecs)
+        return 0;
+    const into = Math.floor(ageSecs) % HALF_LIFE.halfLifeSecs;
+    const hi = Math.floor(HALF_LIFE.maxFeePpm / 2 ** halvings);
+    const lo = Math.floor(HALF_LIFE.maxFeePpm / 2 ** (halvings + 1));
+    return hi - Math.floor(((hi - lo) * into) / HALF_LIFE.halfLifeSecs);
+}
 /** The wSOL mint, which stands for native SOL on the bridge. */
 export const NATIVE_MINT = 'So11111111111111111111111111111111111111112';
 export const TOKEN_PROGRAM_ID = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';

package/dist/studio.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Studio and the config marketplace: the shapes the site and the backend exchange.
+ *
+ * Studio is where anyone designs a launch config, and optionally a token hook of their own, with an
+ * assistant that knows the Bordrless programs; has it reviewed; pays the rent for Bordrless to build
+ * and deploy the hook (its upgrade authority then handed to them); makes the config; and may list it
+ * on the marketplace, where every launch someone else makes from it pays them their share of the
+ * creator fee (`create_listed_config`, docs/hooks-v2.md §5.7).
+ *
+ * A Studio hook is written against one template (`STUDIO_TEMPLATE`): an Anchor program with a fixed
+ * `Cargo.toml` and the standard `prepare` (`STUDIO_PREPARE`), so the site can prepare any Studio hook
+ * for a new mint without knowing its code. The backend refuses source that leaves the template's
+ * limits (`StaticCheck`) before it is built, reviewed or paid for.
+ */
+import type { Address, PreparedTx } from './api.ts';
+/** One source file of a hook. Only `src/**.rs` files; `Cargo.toml` is the template's and never sent. */
+export interface StudioFile {
+    /** Relative path, e.g. `src/lib.rs`. */
+    path: string;
+    content: string;
+}
+/** What a project becomes: a config of existing rules alone, or a config with its own hook program. */
+export type StudioKind = 'config' | 'hook';
+/** The launch config a project makes (the arguments of `create_config` / `create_listed_config`). */
+export interface StudioConfigDraft {
+    /** At most 32 bytes. */
+    label: string;
+    creatorFeeBps: number;
+    burnBuyBps: number;
+    burnSellBps: number;
+    /** Kit rules, for a `config` project only (a hook of one's own excludes them). */
+    holderFeeBuyBps: number;
+    holderFeeSellBps: number;
+    maxWalletBps: number;
+    creatorLockDays: number;
+    earlyWindowSecs: number;
+    earlyLockSecs: number;
+    /** `TOKEN_HOOK_FLAGS` the hook runs on, for a `hook` project; 0 for a `config` project. */
+    hookFlags: number;
+    /** List it on the marketplace (made with `create_listed_config`). */
+    listed: boolean;
+    /** The author's share of the creator fee on others' launches, bps of it: 1 to `MAX_AUTHOR_SHARE_BPS`. */
+    authorShareBps: number;
+}
+/** Where a project stands, in the order the Studio walks it. */
+export type StudioStage = 'draft' | 'reviewed' | 'built' | 'paid' | 'deploying' | 'deployed' | 'configured' | 'listed';
+export interface StudioProjectSummary {
+    id: string;
+    owner: Address;
+    name: string;
+    kind: StudioKind;
+    stage: StudioStage;
+    /** The deployed hook, once deployed. */
+    programId: Address | null;
+    /** The config made from it, once made. */
+    config: Address | null;
+    updatedAt: number;
+}
+export interface StudioProject extends StudioProjectSummary {
+    /** A one-paragraph description, shown on the marketplace when listed. */
+    description: string;
+    files: StudioFile[];
+    draft: StudioConfigDraft;
+    /** The last review of the current source; null when the source changed since. */
+    review: StudioReview | null;
+    /** The last build of the current source; null when the source changed since. */
+    build: StudioBuild | null;
+    deploy: StudioDeploy | null;
+    createdAt: number;
+}
+export interface StudioProjectCreateRequest {
+    name: string;
+    kind: StudioKind;
+    /** Start from a template (`STUDIO_STARTERS`), or blank. */
+    starter?: string;
+}
+/** A save: any of the fields; files replace the whole set. Changing files drops the review and the build. */
+export interface StudioProjectUpdateRequest {
+    name?: string;
+    description?: string;
+    files?: StudioFile[];
+    draft?: Partial<StudioConfigDraft>;
+}
+/** `POST /v1/studio/session`: the wallet signs `message` (from `studioSignInMessage`), the backend answers a session token. */
+export interface StudioSessionRequest {
+    wallet: Address;
+    /** The exact message signed. */
+    message: string;
+    /** Base58 ed25519 signature of the message's UTF-8 bytes. */
+    signature: string;
+}
+export interface StudioSessionResponse {
+    token: string;
+    wallet: Address;
+    expiresAt: number;
+    /** What the assistant still allows this wallet today. */
+    quota: StudioQuota;
+}
+export interface StudioQuota {
+    /** Assistant messages left today (UTC). */
+    messagesLeft: number;
+    messagesPerDay: number;
+    /** The assistant is off for everyone (no key, or today's budget spent). */
+    assistantOff: boolean;
+}
+/** The message a wallet signs to use Studio: no transaction, nothing moves. */
+export declare function studioSignInMessage(wallet: Address, nonce: string, issuedAt: string): string;
+/** The header the session token travels in, browser → site proxy → backend. */
+export declare const STUDIO_SESSION_HEADER = "x-studio-session";
+export interface StudioMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    /** Markdown. An assistant message may carry proposals (below) as fenced blocks. */
+    content: string;
+    at: number;
+    /** For an assistant message: the changes it proposes, parsed from its fenced blocks. */
+    proposal: StudioProposal | null;
+}
+/**
+ * What an assistant reply proposes: whole files (```rust file=src/lib.rs fences) and config
+ * fields (a ```json studio-config fence). The Studio shows them as a diff to apply or dismiss.
+ */
+export interface StudioProposal {
+    files: StudioFile[];
+    draft: Partial<StudioConfigDraft> | null;
+    /** Applied by the user (the project's files or draft were replaced by it). */
+    applied: boolean;
+}
+/** `POST /v1/studio/projects/:id/chat`: one user message; the reply is produced in the background. */
+export interface StudioChatRequest {
+    content: string;
+}
+export interface StudioChatResponse {
+    job: string;
+    /** The user's message as stored. */
+    message: StudioMessage;
+    quota: StudioQuota;
+}
+/** `GET /v1/studio/chat/:job`: the reply so far; poll until `state` is not `running`. */
+export interface StudioChatJob {
+    job: string;
+    state: 'running' | 'done' | 'failed';
+    /** The reply's text so far (all of it once done). */
+    text: string;
+    /** Once done: the stored message, its proposal parsed. */
+    message: StudioMessage | null;
+    error: string | null;
+}
+/** One of the template's limits, checked on the source before anything else (no model involved). */
+export interface StaticCheck {
+    id: string;
+    ok: boolean;
+    /** What is checked, in words. */
+    label: string;
+    /** Where it failed: `src/lib.rs:42` and the offending text. */
+    detail: string | null;
+}
+export type FindingSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+export interface ReviewFinding {
+    severity: FindingSeverity;
+    title: string;
+    detail: string;
+    /** `src/lib.rs:42`, when it points at a line. */
+    location: string | null;
+}
+/** `POST /v1/studio/projects/:id/review`: the static checks, then the assistant's security review. */
+export interface StudioReview {
+    /** `fail`: a static check failed or a critical/high finding; deploy is refused. */
+    verdict: 'pass' | 'warn' | 'fail';
+    checks: StaticCheck[];
+    findings: ReviewFinding[];
+    /** A short paragraph: what the hook does, as the reviewer read it. */
+    summary: string;
+    /** sha256 of the source reviewed. */
+    sourceHash: string;
+    at: number;
+}
+/** `POST /v1/studio/projects/:id/build`: compiled by the build worker in the verifiable-build image. */
+export interface StudioBuild {
+    state: 'queued' | 'building' | 'ok' | 'failed';
+    /** The program id the source was built for (its `declare_id!`), reserved for this project. */
+    programId: Address;
+    /** sha256 of the program binary (what `solana-verify get-executable-hash` prints). */
+    hash: string | null;
+    bytes: number | null;
+    /** The compiler's output, its tail. */
+    log: string;
+    sourceHash: string;
+    at: number;
+}
+/** `POST /v1/studio/projects/:id/deploy/quote`: what deploying the built hook costs, in lamports. */
+export interface StudioDeployQuote {
+    /** Rent of the program's data account (the binary plus room to upgrade: `maxDataLen`). */
+    programDataRent: string;
+    /** Rent of the program account. */
+    programRent: string;
+    /** Transaction fees of writing and deploying it. */
+    fees: string;
+    /** Bordrless's service fee. */
+    service: string;
+    total: string;
+    maxDataLen: number;
+    /** The wallet the payment goes to (Studio's deployer). */
+    payTo: Address;
+    /** The payment transaction: a plain SOL transfer of `total` with a memo naming this deploy. */
+    transactions: PreparedTx[];
+    /** The quote holds until then (unix seconds). */
+    expiresAt: number;
+}
+export interface StudioDeployRequest {
+    /** The confirmed payment transaction. */
+    paymentSignature: string;
+    /** Hand the upgrade authority to the owner (default), or make the program final. */
+    authority: 'owner' | 'final';
+}
+export type StudioDeployState = 'awaiting_payment' | 'paid' | 'writing' | 'deploying' | 'handing_over' | 'deployed' | 'failed' | 'refunded';
+export interface StudioDeploy {
+    state: StudioDeployState;
+    programId: Address;
+    /** Lamports paid, and the payment. */
+    paid: string | null;
+    paymentSignature: string | null;
+    /** Bytes written of the binary, while writing. */
+    written: number;
+    bytes: number;
+    deploySignature: string | null;
+    /** Who can upgrade it now: the owner, or null once final. */
+    upgradeAuthority: Address | null;
+    error: string | null;
+    refundSignature: string | null;
+    at: number;
+}
+/** `POST /v1/studio/projects/:id/config/prepare`: `create_config` or `create_listed_config` for the draft. */
+export interface StudioConfigPrepareRequest {
+    /** A fresh keypair's address the browser made; it signs after the wallet. */
+    config: Address;
+}
+export interface StudioConfigPrepareResponse {
+    config: Address;
+    transactions: PreparedTx[];
+}
+export interface MarketplaceListing {
+    config: Address;
+    author: Address;
+    /** The config's on-chain label. */
+    label: string;
+    /** The author's title and description (from Studio), or the label alone. */
+    title: string;
+    description: string;
+    authorShareBps: number;
+    creatorFeeBps: number;
+    burnBuyBps: number;
+    burnSellBps: number;
+    holderFeeBuyBps: number;
+    holderFeeSellBps: number;
+    maxWalletBps: number;
+    customHook: Address | null;
+    customHookFlags: number;
+    /** The hook was built and deployed by Studio from source anyone can read. */
+    studioSource: boolean;
+    /** Who can upgrade the hook now (null: final, or no hook). */
+    hookUpgradeAuthority: Address | null;
+    /** The source passed review when it was deployed. */
+    reviewVerdict: 'pass' | 'warn' | null;
+    launches: number;
+    /** Paid to the author so far, lamports. */
+    authorEarned: string;
+    volumeUsd: number | null;
+    createdAt: number;
+}
+export interface MarketplaceListResponse {
+    listings: MarketplaceListing[];
+    total: number;
+}
+export interface MarketplaceDetail extends MarketplaceListing {
+    /** The hook's source when Studio built it. */
+    files: StudioFile[] | null;
+    buildHash: string | null;
+    review: StudioReview | null;
+    /** Launches made from it, newest first. */
+    recentLaunches: {
+        mint: Address;
+        symbol: string;
+        name: string;
+        image: string | null;
+        createdAt: number;
+    }[];
+}
+/** `POST /v1/author/prepare`: a config author's claims of their share, on up to four launches a transaction, paid as SOL. */
+export interface AuthorPrepareRequest {
+    author: Address;
+    /** The launches to claim on; all with something to claim when absent. */
+    mints?: Address[];
+}
+export interface AuthorEarnings {
+    author: Address;
+    /** Waiting to be claimed on each launch: the author's part of what the launch holds. */
+    launches: {
+        mint: Address;
+        symbol: string;
+        config: Address;
+        claimable: string;
+        paid: string;
+    }[];
+    claimable: string;
+    paid: string;
+}
+/** `bordrless_launch::constants::MAX_AUTHOR_SHARE_BPS`: half the creator fee. */
+export declare const MAX_AUTHOR_SHARE_BPS = 5000;
+/** The share the Studio suggests. */
+export declare const DEFAULT_AUTHOR_SHARE_BPS = 2000;
+/**
+ * The standard `prepare` of a Studio hook: `prepare()` (no arguments) with the accounts
+ * `[payer (signer, writable), mint, state = PDA(["state", mint], hook) (writable), registry =
+ * PDA(["bordrless-hook-accounts", mint], hook) (writable), system program]`. It creates the hook's
+ * state for the mint and writes its registry; anyone may send it, once per mint.
+ */
+export declare const STUDIO_PREPARE: {
+    readonly instruction: "prepare";
+    readonly stateSeed: "state";
+};
+/** Limits of a project's source. */
+export declare const STUDIO_LIMITS: {
+    readonly files: 8;
+    readonly bytes: 120000;
+    readonly messageChars: 8000;
+};
+/** Starters a new hook project can begin from (the template's `src/lib.rs` variants). */
+export declare const STUDIO_STARTERS: readonly {
+    id: string;
+    name: string;
+    blurb: string;
+}[];

package/dist/studio.js

@@ -0,0 +1,26 @@
+/** The message a wallet signs to use Studio: no transaction, nothing moves. */
+export function studioSignInMessage(wallet, nonce, issuedAt) {
+    return ['Sign in to Bordrless Studio', '', 'This signature proves you own this wallet. It does not move funds or approve any transaction.', '', `Wallet: ${wallet}`, `Nonce: ${nonce}`, `Issued: ${issuedAt}`].join('\n');
+}
+/** The header the session token travels in, browser → site proxy → backend. */
+export const STUDIO_SESSION_HEADER = 'x-studio-session';
+// ---- constants ----------------------------------------------------------------------------------------
+/** `bordrless_launch::constants::MAX_AUTHOR_SHARE_BPS`: half the creator fee. */
+export const MAX_AUTHOR_SHARE_BPS = 5_000;
+/** The share the Studio suggests. */
+export const DEFAULT_AUTHOR_SHARE_BPS = 2_000;
+/**
+ * The standard `prepare` of a Studio hook: `prepare()` (no arguments) with the accounts
+ * `[payer (signer, writable), mint, state = PDA(["state", mint], hook) (writable), registry =
+ * PDA(["bordrless-hook-accounts", mint], hook) (writable), system program]`. It creates the hook's
+ * state for the mint and writes its registry; anyone may send it, once per mint.
+ */
+export const STUDIO_PREPARE = { instruction: 'prepare', stateSeed: 'state' };
+/** Limits of a project's source. */
+export const STUDIO_LIMITS = { files: 8, bytes: 120_000, messageChars: 8_000 };
+/** Starters a new hook project can begin from (the template's `src/lib.rs` variants). */
+export const STUDIO_STARTERS = [
+    { id: 'blank', name: 'Blank hook', blurb: 'The template: every callback stubbed, nothing taken, nothing refused.' },
+    { id: 'sell-tax', name: 'Sell tax to a wallet', blurb: 'A cut of every sell sent to a wallet you choose; buys and transfers pass free.' },
+    { id: 'cooldown', name: 'Transfer cooldown', blurb: 'A holding that received tokens cannot send them on for a while, stamped in its hook data.' },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bordrless/shared",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Bordrless policy (the same math as crates/bordrless-core), program addresses and the API types shared by the server and the site. No Solana dependencies.",
   "license": "Apache-2.0",