@floorlaunchpad/sdk-solana 0.0.0-stage → 0.1.1

package/src/adapters.ts

@@ -0,0 +1,138 @@
+/**
+ * Glue for the deployment rows and the quoter: a joined deployment row → `ProgramIds`, and an `AccountSource` → the
+ * quoter's inputs for a FLOOR pool (a plain pool's read is `@floorlaunchpad/carpenter-sdk`'s `readSwapQuoteAccounts`).
+ *
+ * ⛔ The quoter takes RAW ACCOUNT BYTES (pool, bitmap, tick arrays, floor_pool, launch), never decoded structs: it
+ *    decodes them itself with the same layouts the programs use, so a field cannot be mis-transcribed between a read and
+ *    a quote. These helpers gather the bytes in as few RPC calls as possible and tag them with the OLDEST slot read.
+ * ⛔ Program ids come from `deployments.json`, never a constant; `DEFAULT_PROGRAM_IDS` exists for tests and scripts.
+ */
+
+import type { ClusterDeployment } from './deployments.ts';
+import type { SwapQuoteInput } from './quote/quoter.ts';
+import {
+  addressToBytes,
+  decodePool,
+  decodeTickArrayBitmap,
+  TICK_ARRAY_LEN,
+  TICK_ARRAY_RENT_OWNER_OFFSET,
+  findBitmap,
+  findTickArray,
+  type AccountSource,
+  type RawAccount,
+  type AtSlot,
+  initializedArrayStarts,
+  tickArrayStartIndex,
+  decodeMint,
+} from '@floorlaunchpad/carpenter-sdk';
+import { address, type Address } from '@solana/kit';
+
+import { DEFAULT_PROGRAM_IDS, findFloorPool, type ProgramIds } from './pda.ts';
+/**
+ * A deployment row's program ids. Every one is read off the row, never a compiled-in default: a row for another
+ * cluster names that cluster's programs, and a row that lacks one is refused by name.
+ */
+export function programIdsFromDeployment(row: ClusterDeployment): ProgramIds {
+  const p = row.programs as ClusterDeployment['programs'] & { floorHolders?: string | null };
+  for (const k of ['carpenterAmm', 'floorHook', 'floorLaunch', 'floorHolders'] as const) {
+    if (!p[k]) throw new Error(`programIdsFromDeployment: the ${row.name} row (${row.chainKey ?? 'local'}) names no programs.${k}`);
+  }
+  return {
+    carpenterAmm: address(p.carpenterAmm),
+    floorHook: address(p.floorHook),
+    floorLaunch: address(p.floorLaunch),
+    floorHolders: address(p.floorHolders!),
+  };
+}
+
+/** Everything `quoteSwap` needs for one pool, as bytes, plus what was found. */
+export interface SwapQuoteAccounts extends Omit<SwapQuoteInput, 'zeroForOne' | 'amountSpecified' | 'sqrtPriceLimitX64'> {
+  poolKey: Uint8Array;
+  pool: Uint8Array;
+  bitmap: Uint8Array;
+  /** Each the 3,888-byte BODY of a 3,920-byte array account — its rent owner is not a quote input. */
+  tickArrays: Uint8Array[];
+  /** The start index of each entry of `tickArrays`, in the same order. */
+  tickArrayStarts: number[];
+  /** `null` on a plain pool. */
+  floorPool: Uint8Array | null;
+  /** The base mint's supply (currency1) on a FLOOR pool; `null` on a plain pool. */
+  supply1: bigint | null;
+  isFloor: boolean;
+}
+
+/**
+ * Read a pool's quoting accounts: the pool, its bitmap, the initialized tick arrays within
+ * `radius` arrays of the current tick on both sides (or exactly `starts`), and on a FLOOR pool its
+ * `FloorPool` and the base mint. Two round trips (pool + bitmap, then the rest).
+ * ⚠ A walk that leaves the window fails `TickArrayMissing{start_index}`; widen `radius` or pass
+ *    the named start in `starts` and read again. The quoter says which array it needs.
+ */
+export async function readSwapQuoteAccounts(
+  src: AccountSource,
+  pool: Address,
+  opts: { radius?: number; starts?: readonly number[]; ids?: ProgramIds } = {},
+): Promise<AtSlot<SwapQuoteAccounts>> {
+  const ids = opts.ids ?? DEFAULT_PROGRAM_IDS;
+  const bitmapAddr = (await findBitmap(pool, ids)).address;
+  const first = await src.getMultipleAccounts([pool, bitmapAddr]);
+  const poolRaw = owned(first.accounts[0], ids.carpenterAmm);
+  const bitmapRaw = owned(first.accounts[1], ids.carpenterAmm);
+  if (!poolRaw) throw new Error(`readSwapQuoteAccounts: no pool at ${pool}`);
+  if (!bitmapRaw) throw new Error(`readSwapQuoteAccounts: no bitmap for ${pool}`);
+  const p = decodePool(poolRaw.data);
+  const bm = decodeTickArrayBitmap(bitmapRaw.data);
+  const s = p.tickSpacing;
+  const isFloor = p.hook === ids.floorHook;
+
+  let starts: number[];
+  if (opts.starts) {
+    starts = [...new Set(opts.starts)].sort((a, b) => a - b);
+  } else {
+    const radius = opts.radius ?? 3;
+    const here = tickArrayStartIndex(p.tickCurrent, s);
+    const span = 60 * s;
+    starts = initializedArrayStarts(bm.words, s).filter((st) => Math.abs(st - here) <= radius * span);
+  }
+  const arrayAddrs = await Promise.all(starts.map(async (st) => (await findTickArray(pool, st, ids)).address));
+  const extra: Address[] = isFloor ? [(await findFloorPool(pool, ids)).address, p.mint1] : [];
+  const second = await src.getMultipleAccounts([...arrayAddrs, ...extra]);
+
+  const tickArrays: Uint8Array[] = [];
+  const tickArrayStarts: number[] = [];
+  starts.forEach((st, i) => {
+    const a = owned(second.accounts[i], ids.carpenterAmm);
+    // An array is the 3,920-byte account — the program refuses a 3,888-byte V1 account, so it is skipped here like
+    // any other length, never truncated. The quoter is handed the 3,888-byte BODY (`TICK_ARRAY_BODY_LEN`).
+    if (a && a.data.length === TICK_ARRAY_LEN) {
+      tickArrays.push(a.data.subarray(0, TICK_ARRAY_RENT_OWNER_OFFSET));
+      tickArrayStarts.push(st);
+    }
+  });
+  let floorPool: Uint8Array | null = null;
+  let supply1: bigint | null = null;
+  if (isFloor) {
+    const fp = owned(second.accounts[starts.length], ids.floorHook);
+    if (!fp) throw new Error(`readSwapQuoteAccounts: no FloorPool for ${pool}`);
+    floorPool = fp.data;
+    const mint = second.accounts[starts.length + 1];
+    if (!mint) throw new Error(`readSwapQuoteAccounts: no base mint ${p.mint1}`);
+    supply1 = decodeMint(mint.data).supply;
+  }
+  const slot = first.slot < second.slot ? first.slot : second.slot;
+  return {
+    slot,
+    value: { poolKey: addressToBytes(pool), pool: poolRaw.data, bitmap: bitmapRaw.data, tickArrays, tickArrayStarts, floorPool, supply1, isFloor },
+  };
+}
+
+/** `saleBuy` / `saleSellBack` take the raw `Launch` (and `BuyerPosition`); read them as bytes. */
+export async function readRawOwned(src: AccountSource, addr: Address, program: Address): Promise<AtSlot<Uint8Array | null>> {
+  const { slot, account } = await src.getAccount(addr);
+  const a = owned(account, program);
+  return { slot, value: a ? a.data : null };
+}
+
+function owned(a: RawAccount | null | undefined, program: Address): RawAccount | null {
+  return a && a.owner === program ? a : null;
+}

package/src/constants.ts

@@ -0,0 +1,265 @@
+/**
+ * FLOOR's constants shared with the `floor_hook` / `floor_launch` / `floor_holders` / `floor_vesting` programs: ids,
+ * seeds, the account and fee constants a reader or a trade needs, and the compute-unit rows. Every value is a copy of the
+ * programs' Rust constants (`crates/floor-types`); `test/rust-parity.test.ts` checks them when the program source is
+ * present.
+ * ⚠ `SEEDS` and `CU_LIMITS` here are the UNION — `@floorlaunchpad/carpenter-sdk`'s rows spread first, then FLOOR's — so one table
+ *   serves every builder.
+ */
+
+import { address, type Address } from '@solana/kit';
+
+import { CU_LIMITS as CARPENTER_CU_LIMITS, SEEDS as CARPENTER_SEEDS, MAX_TICK, MIN_TICK } from '@floorlaunchpad/carpenter-sdk';
+
+// ---- program ids ----------------
+export const FLOOR_HOOK_PROGRAM_ID: Address = address('9uXLyyZginMWdUeu22kp7XV7cpV8183xfsVqUxKi5Viy');
+export const FLOOR_LAUNCH_PROGRAM_ID: Address = address('8vfdPWfaA3b9GtJoFUwc36JKDaMfVCJ4oT9HrCrQ6Tdi');
+/** `floor_holders` — the Token-2022 TRANSFER-HOOK holder tally. Equal to `floor_types::holders::FLOOR_HOLDERS_ID`. */
+export const FLOOR_HOLDERS_PROGRAM_ID: Address = address('2EUkJXSwCdRAuhesw2D9FXyGfbi6Kw2yZDyQUnCwc7te');
+/** `floor_vesting`, for reading its accounts. */
+export const FLOOR_VESTING_PROGRAM_ID: Address = address('HHiwbXs3egRwtgEPEKx1PHpBU8gq5VSbhfrGrcCd4CSC');
+
+// ---- seeds ---------------------------------------------------------
+const utf8 = (s: string): Uint8Array => new TextEncoder().encode(s);
+export const SEEDS = {
+  ...CARPENTER_SEEDS,
+  hookConfig: utf8('hook_config'),
+  floorPool: utf8('floor_pool'),
+  launchConfig: utf8('launch_config'),
+  registryEntry: utf8('entry'),
+  launch: utf8('launch'),
+  saleVault: utf8('sale_vault'),
+  buyer: utf8('buyer'),
+  mint: utf8('mint'),
+  mintAuthority: utf8('mint_authority'),
+  lockAuthority: utf8('lock_authority'),
+  launchAuthority: utf8('launch_authority'),
+  /** `["quote", quote_mint]` under `floor_hook` — the FLOOR quote roster entry a launch on any quote but wSOL is
+   * created against. */
+  quotePolicy: utf8('quote'),
+  // `["grad_rent", launch]`, the launch's graduation rent reserve.
+  gradRent: utf8('grad_rent'),
+  /** `["stair_rent", amm_pool]` under floor_hook. */
+  stairRent: utf8('stair_rent'),
+  /** `["stair", floor_pool]` under `floor_hook`, a staircase pool's
+   *  `StairState` — created by `prepare_positions` (or inside the graduating buy), filled by graduation. */
+  stair: utf8('stair'),
+  /** `["platform_treasury"]` under `floor_hook` — the program-owned PLATFORM TREASURY. Its ADDRESS owns every token
+   * account the 2.5 % `$FLOOR` cut is swept into (`ATA(treasury, quote)`, one per quote); its DATA is the governance that
+   * alone may withdraw. No private key exists for it. */
+  platformTreasury: utf8('platform_treasury'),
+  /** `["team_treasury"]` under `floor_hook` — the program-owned
+   * TEAM treasury, `PlatformTreasury`'s layout. Its ADDRESS owns every token account the platform fee
+   * is swept into (`ATA(team, quote)`, opened by the first sweep that moves a team fee in that quote);
+   * its DATA is the governance that alone may `withdraw_team`. Never crosses the platform treasury. */
+  teamTreasury: utf8('team_treasury'),
+  /** `["floor_platform_pool"]`
+   * under `floor_hook` — the ONE record of `$FLOOR`'s pool (`FloorPlatformPool`), set once by
+   * `designate_floor_pool`; its ADDRESS owns the wSOL TRANSIT account `credit_floor_pool` stages a cut
+   * through (`ATA(record, wSOL)`, zero at rest). Never a treasury. */
+  floorPlatformPool: utf8('floor_platform_pool'),
+  /** `["trader_link", trader]` under `floor_launch`. */
+  traderLink: utf8('trader_link'),
+  /** `["trader_ref", trader, quote_mint]` under `floor_hook` — a trader's bucket in one quote. */
+  traderRef: utf8('trader_ref'),
+  /** `["trader_ref_vault"]` under `floor_hook` — the shared vault's authority (one ATA per quote). */
+  traderRefVault: utf8('trader_ref_vault'),
+  /** `["trader_ref_sale", launch]` under `floor_launch` — a launch's sale-path referral account. */
+  traderRefSale: utf8('trader_ref_sale'),
+} as const;
+
+/**
+ * `floor_holders`' seeds, every one under `FLOOR_HOLDERS_PROGRAM_ID`.
+ * ⚠ `extraAccountMetas` is the Token-2022 transfer-hook INTERFACE's own seed, `["extra-account-metas", mint]` with a
+ *   HYPHEN — `spl_transfer_hook_interface::get_extra_account_metas_address` derives it under the hook program, and
+ *   Token-2022 looks the account up by exactly that address.
+ */
+export const HOLDERS_SEEDS = {
+  /** `["holders_authority"]` — signs `floor_hook::pay_holder` (the only door holder money leaves by). */
+  holdersAuthority: utf8('holders_authority'),
+  /** `["holder_book", mint]` — one launch's tally (acc, eligible, indexed, unallocated, paid). */
+  holderBook: utf8('holder_book'),
+  /** `["extra-account-metas", mint]` — the transfer-hook interface's validation account. */
+  extraAccountMetas: utf8('extra-account-metas'),
+  /** `["holder", mint, token_account]` — ONE holder's record, keyed by its ATA, never its wallet. */
+  holderRecord: utf8('holder'),
+} as const;
+
+/** `0x20CC | 0x4000`. */
+export const FLOOR_HOOK_FLAGS = 0x60cc;
+/**
+ * The accounts every FLOOR hook callback takes (`ApprovedHook.callback_accounts`, copied into each pool as
+ * `Pool.hook_callback_accounts`): `[floor_pool w, trader_bucket w, floor_hook event_authority r, floor_hook r]`. The
+ * program set this SDK builds for carries 4; an older set carries fewer, and `createSolanaAdapter` refuses to build
+ * trades against it (`program_version`).
+ */
+export const FLOOR_CALLBACK_ACCOUNTS = 4;
+
+// ---- FLOOR --------------------------------------
+export const FLOOR_TICK_SPACING = 60;
+export const TOKEN_DECIMALS = 6;
+export const SUPPLY = 1_000_000_000_000_000n;
+/** The standard supply split: 30 / 10 / 60 (sale / POL / ladder). */
+export const SALE_TOKENS = 300_000_000_000_000n;
+export const POL_TOKENS = 100_000_000_000_000n;
+export const LADDER_TOKENS = 600_000_000_000_000n;
+export const TICKS_PER_DOUBLING = 6_932;
+/**
+ * The bid is a BAND `[floor_tick − W, floor_tick]`, `W = ceil_to_spacing(BID_BAND_TICKS, s)` — 120 at
+ * spacing 60 (`floor_types::constants::BID_BAND_TICKS`, `floor_math::band`). The SDK reads it to
+ * predict the bid's arrays at graduation.
+ */
+export const BID_BAND_TICKS = 120;
+export const LP_FEE_PIPS = 2_500;
+export const PLATFORM_BPS = 250;
+/**
+ * THE FLOOR PLATFORM FEE ("team fee" in code): a SALE rate and a POOL rate, each a governance-set CURRENT SETTING in
+ * `LaunchConfig` under a cap, COPIED into each launch / pool at its creation and kept for life. ⛔ Informational: every
+ * figure uses the ACCOUNT's own `Launch.teamBps` / `FloorPool.teamFeeBps` (0 on older accounts), and "what a new launch
+ * pays now" is `launchConfigTeamSaleBps` / `launchConfigTeamPoolBps` on the decoded config — never these defaults.
+ */
+/** The sale's default, on every bonding-sale buy AND sell-back — 1 %. */
+export const TEAM_SALE_FEE_BPS_DEFAULT = 100;
+/** The most `set_team_fees` may set for the sale — 1 %. */
+export const TEAM_SALE_FEE_BPS_MAX = 100;
+/** The pool's default, on every swap after graduation — 0.25 %. */
+export const TEAM_POOL_FEE_BPS_DEFAULT = 25;
+/** The most `set_team_fees` may set for a pool — 0.5 %. */
+export const TEAM_POOL_FEE_BPS_MAX = 50;
+/** The FAR skim cap per side, 10 %. The sell skim ramps to its at-floor endpoint (`skimSellAtFloorBps`). */
+export const MAX_SKIM_FAR_BPS = 1_000;
+/** The creator fee cap per side: 5 %. */
+export const MAX_CREATOR_BPS = 500;
+/** The holder rate cap per side: 10 %. */
+export const MAX_HOLDER_BPS = 1_000;
+
+export const SALT_BID = 1n;
+export const SALT_SEED = 3n;
+/** The staircase's position salts (`floor_types::constants`): the open tail
+ *  above the staircase, the cushion, the POL re-list, the RESERVE and step i's `SALT_STAIR_STEP0 + i`. Found BY KEY. */
+export const SALT_STAIR_TAIL = 102n;
+export const SALT_CUSHION = 103n;
+export const SALT_POL_RELIST = 104n;
+export const SALT_STAIR_RESERVE = 105n;
+export const SALT_STAIR_STEP0 = 110n;
+export const MAX_STAIR_STEPS = 16;
+/** One staircase operation per ratchet (the compute budget); what is left sets `FloorPool.needsRatchet`. */
+export const STAIR_STEPS_PER_RATCHET = 1;
+
+/** `Launch.state`: the bonding sale, then graduated. Any other value is a launch that is not trading (read as `pending`). */
+export const LAUNCH_STATE_BONDING = 0;
+export const LAUNCH_STATE_GRADUATED = 1;
+// ---- the PayeeSlots tail ----
+// A launch names up to five creator-fee recipients and up to five team-buy payees; each slot is an ADDRESS (platform 0)
+// or a PENDING HANDLE id (platform 1..=4).
+
+/** At most five slots in a list. */
+export const MAX_SLOTS = 5;
+/** A list's shares sum to exactly this. */
+export const SLOTS_TOTAL_BPS = 10_000;
+/** 1 X / twitter, 2 github, 3 discord, 4 telegram; 0 = an address slot. */
+export const MAX_SLOT_PLATFORM = 4;
+/** The `PayeeSlots` tail's ACCOUNT offset in a `FloorPool` account: straight after the TWAP oracle (1,008). */
+export const PAYEE_SLOTS_OFFSET = 1_008;
+/** `size_of::<PayeeSlot>()`. */
+export const PAYEE_SLOT_SIZE = 56;
+/** `size_of::<PayeeSlots>()`. */
+export const PAYEE_SLOTS_SIZE = 568;
+/** The `FloorPool` account `register_pool` creates: 1,008 + 568 = 1,576 bytes. */
+export const FLOOR_POOL_ACCOUNT_LEN_WITH_SLOTS = PAYEE_SLOTS_OFFSET + PAYEE_SLOTS_SIZE;
+/**
+ * The team's per-slot books (`floor_types::slots::TeamParts`), the `FloorPool` account's tail after the slots —
+ * `out_mask` u128 @0 (bit 5·i + s: slot s exited step i), `part_tokens` @16, `part_quote` @24, `token_credit[5]` @32,
+ * `quote_credit[5]` @72, `pending_ask[5]` @112.
+ */
+export const TEAM_PARTS_OFFSET = FLOOR_POOL_ACCOUNT_LEN_WITH_SLOTS;
+/** `size_of::<TeamParts>()`. */
+export const TEAM_PARTS_SIZE = 152;
+/** The `FloorPool` account `register_pool` creates: 1,576 + 152 = 1,728 bytes. */
+export const FLOOR_POOL_ACCOUNT_LEN_WITH_PARTS = TEAM_PARTS_OFFSET + TEAM_PARTS_SIZE;
+/** `PayeeSlots.version` once `register_pool` wrote the lists. */
+export const PAYEE_SLOTS_VERSION = 1;
+/** `PayeeSlot.state`: an address slot from creation. */
+export const SLOT_STATE_WALLET = 0;
+/** A handle slot still waiting for its claim (`key` is the pending id; the share is HELD). */
+export const SLOT_STATE_PENDING = 1;
+/** A handle slot claimed (`key` is the claimed wallet; the pending id is in the `PayeeSlotsSet` event). */
+export const SLOT_STATE_RESOLVED = 2;
+/** Which list (`PayeeSlotsSet`'s `creator` / `team` list). */
+export const SLOT_KIND_CREATOR = 0;
+export const SLOT_KIND_TEAM = 1;
+/** `FloorPool.stair_kind`: the staircase's parameter set — the presets' (0) or `$FLOOR`'s (1). */
+export const STAIR_KIND_PRESET = 0;
+export const STAIR_KIND_GENESIS = 1;
+
+/**
+ * The mode byte (`Launch.mode`, `FloorPool.mode`): 0 Custom, 1 Moonshot, 2 Cook, 3 Bluechip — the EVM's `FloorModes.Mode`
+ * ordinals too. A zeroed byte is Custom.
+ * ⛔ A DECODER MUST REFUSE AN ORDINAL IT CANNOT PLACE, never fall through to a default. Further modes append (4..=31).
+ */
+export const MODE_CUSTOM = 0;
+export const MODE_MOONSHOT = 1;
+export const MODE_COOK = 2;
+export const MODE_BLUECHIP = 3;
+/** Every mode byte the programs define, in `floor_math::Mode` order. */
+export const MODES = [MODE_CUSTOM, MODE_MOONSHOT, MODE_COOK, MODE_BLUECHIP] as const;
+
+export const PENDING_PLATFORM_NONE = 0;
+export const PENDING_PLATFORM_TWITTER = 1;
+export const PENDING_PLATFORM_GITHUB = 2;
+export const PENDING_PLATFORM_DISCORD = 3;
+export const PENDING_PLATFORM_TELEGRAM = 4;
+
+/** Ticks from the price down to 0.9 × the price (`floor_math::stair::CUSHION_TICKS`): the cushion's width. */
+export const CUSHION_TICKS = 1_054;
+/** No protocol listing within ~3 % above the floor: `floor_math::stair::STAIR_CLEAR_TICKS`. */
+export const STAIR_CLEAR_TICKS = 254;
+/** The cushion's re-list cost markup, 1.03× in ticks (`floor_math::stair::RELIST_COST_MARKUP_TICKS`). */
+export const RELIST_COST_MARKUP_TICKS = 296;
+/** `floor_types::twap::CUSHION_TWAP_WINDOW_SECS`: the cushion sits under min(spot, the pool's TWAP over this window). */
+export const CUSHION_TWAP_WINDOW_SECS = 900;
+/** The cushion follows net buying: the net-flow meter's memory H in bps of the market cap
+ *  (`floor_math::netflow::STAIR_CUSHION_NETFLOW_BPS`); 0 would be off. */
+export const STAIR_CUSHION_NETFLOW_BPS: number = 130;
+/** The meter's catch-up by volume K (`floor_math::netflow::STAIR_CUSHION_NETFLOW_RELAX_BPS`); 0 = none. */
+export const STAIR_CUSHION_NETFLOW_RELAX_BPS: number = 0;
+/** The half rule: a buy is remembered by its own last slice of quote, and one buy takes at most half of a meter that
+ *  holds anything. */
+export const STAIR_CUSHION_NETFLOW_HALF_RULE: boolean = true;
+/**
+ * `SetComputeUnitLimit` values: each an estimate (`[est.]`) or a measured figure × 1.5, capped at the 1.4 M
+ * per-transaction limit. ⛔ Every builder prepends one: an unset limit is 0 under v1 transactions.
+ */
+export const CU_LIMITS = {
+  ...CARPENTER_CU_LIMITS,
+  // A graduated BUY on a HOOKED pool, the transfer-hook accounts appended (Token-2022's `execute` CPI into
+  // floor_holders on the base leg): measured 144,895 CU; × 1.5 rounded up. Unhooked it measured 91,007.
+  swapFloorBuy: 218_000,
+  // A SELL: the in-swap bid re-place (up to 3 rounds + bisection) plus the hooked base leg's `execute`. A hooked sell
+  // measured 243,762 CU (× 1.5 = 365,643); 520,000 [est.] is kept as the ceiling for the re-place's worst case.
+  swapFloorSell: 520_000,
+  buyFinal: 1_400_000, // 1.0M [est.] × 1.5, capped at the 1.4M tx limit. ⛔ EVERY sale buy uses it.
+  // `initialize_pool` + up to four `initialize_tick_array` + four `initialize_position` [est.], deliberately generous:
+  // the instruction is idempotent, so a call that runs out of compute is re-run rather than lost.
+  prepareGraduation: 900_000,
+  sellBack: 60_000, // 40k [est.] × 1.5
+  closeBuyerPosition: 20_000, // [est.]
+  /** `touch` / `open_record`: catch_up, a prefund-safe record create, one settle, emit_cpi [est.]. */
+  holdersTouch: 60_000,
+  /** `sync`: catch_up + one settle; no create, no CPI [est.]. */
+  holdersSync: 40_000,
+  // The trader link: Ed25519 read + the TraderLink create + the open_trader_bucket CPI + emit_cpi [est.].
+  linkTrader: 90_000,
+  saleTraderRef: 30_000, // a referred sale trade's extra: the credit_trader_bucket CPI + a transfer + emit_cpi [est.]
+} as const;
+export type CuLimitKey = keyof typeof CU_LIMITS;
+
+/**
+ * `RequestHeapFrame` sizes, in bytes (a multiple of 1,024, from 32 KiB to 256 KiB). `finalize` places one right after the
+ * `SetComputeUnitLimit` of every builder whose `CU_LIMITS` key is listed here; none of this package's builders needs
+ * more than the default 32 KiB.
+ */
+export const HEAP_FRAMES: Readonly<Partial<Record<CuLimitKey, number>>> = {};
+
+/** The Instructions sysvar, which `link_trader` introspects for the attestor's Ed25519 signature. */
+export const INSTRUCTIONS_SYSVAR_ID = address('Sysvar1nstructions1111111111111111111111111');

package/src/deployments.ts

@@ -0,0 +1,144 @@
+/**
+ * FLOOR's deployments on Solana: `floor_hook` / `floor_launch` / `floor_holders` / `floor_vesting` per cluster, keyed by
+ * CAIP-2 id, with FLOOR's singleton accounts, the deployment address lookup table and the hook roster's quote terms.
+ * `carpenter_amm`'s rows are `@floorlaunchpad/carpenter-sdk`'s `deployments.json`.
+ *
+ * ⛔ `deploymentFor` returns the JOINED row — Carpenter's row and FLOOR's for the same cluster (`programs.carpenterAmm`
+ *    beside FLOOR's ids) — because every FLOOR builder names the AMM it is hooked on. It throws BY NAME when EITHER file
+ *    lacks the cluster: a missing row must never read as a cluster with no launches.
+ * ⛔ Program ids come from these files, never a constant in an app. A row may name program ids other than the shipped
+ *    IDLs' `address` (another cluster's deployment); every builder, PDA and read takes the ids it is given
+ *    (`programIdsFromDeployment(row)`). The devnet and local rows are the ones generation pins to the IDLs.
+ * ⛔ `alt` is FLOOR's deployment lookup table (FLOOR's programs, configs and PDAs beside the AMM's); read its contents
+ *    from the chain.
+ * ⛔ A `quotes` entry is a RECORD of a listing, never an authority: the rosters on chain are.
+ */
+
+import {
+  DEPLOYMENTS as CARPENTER_DEPLOYMENTS,
+  type ClusterDeployment as CarpenterClusterDeployment,
+  type DeploymentsFile as CarpenterDeploymentsFile,
+} from '@floorlaunchpad/carpenter-sdk';
+
+import { DEPLOYMENTS } from './generated/deployments.ts';
+
+export type { AnchorIdl, AnchorIdlAccountItem, AnchorIdlInstruction } from '@floorlaunchpad/carpenter-sdk';
+export { DEPLOYMENTS };
+
+/**
+ * FLOOR's four deployable programs, by their Anchor crate name (the IDL file stem).
+ */
+export type ProgramName = 'floor_hook' | 'floor_launch' | 'floor_holders' | 'floor_vesting';
+
+export const PROGRAM_NAMES: readonly ProgramName[] = ['floor_hook', 'floor_launch', 'floor_holders', 'floor_vesting'];
+
+/** One cluster's FLOOR row in this package's `deployments.json`. */
+export interface FloorClusterDeployment {
+  readonly name: 'mainnet' | 'devnet' | 'testnet' | 'local';
+  readonly chainKey: string | null;
+  readonly programs: {
+    readonly floorHook: string;
+    readonly floorLaunch: string;
+    readonly floorHolders: string;
+    readonly floorVesting: string;
+  };
+  readonly accounts: {
+    readonly hookConfig: string;
+    readonly launchConfig: string;
+    /** The team treasury PDA, where a row records it. */
+    readonly teamTreasury?: string;
+  };
+  /** The per-deployment address lookup table; `null` until created. */
+  readonly alt: string | null;
+  /** Each deployed ProgramData's EXECUTABLE hash; `null` until recorded. */
+  readonly programDataHash: {
+    readonly floorHook: string | null;
+    readonly floorLaunch: string | null;
+    readonly floorHolders: string | null;
+    readonly floorVesting: string | null;
+  };
+  /** The quote mints listed on the HOOK's roster (`["quote", mint]`), with their terms (raw units, decimal strings). */
+  readonly quotes?: Readonly<Record<string, HookQuoteListingRecord>>;
+}
+
+/** One quote on the hook's roster: the listing state, the terms and the hook's `QuotePolicy` account. */
+export interface HookQuoteListingRecord {
+  /** `listed` on both rosters, `retired` on both, or the split the script could only half-finish. */
+  readonly state: 'listed' | 'retired' | 'amm-only' | 'hook-only';
+  readonly decimals: number;
+  readonly tokenProgram: string;
+  readonly terms: { readonly minBidFloor: string; readonly minBidCeil: string; readonly maxBountyCeil: string; readonly minBid: string; readonly maxBounty: string };
+  readonly hook: { readonly policy: string };
+}
+
+export interface DeploymentsFile {
+  readonly version: 1;
+  readonly clusters: Readonly<Record<string, FloorClusterDeployment>>;
+}
+
+/** One listed quote, both rosters' records joined: the AMM's `QuoteMint` entry and caps beside the hook's terms. */
+export interface QuoteListingRecord extends HookQuoteListingRecord {
+  readonly caps: number;
+  readonly capNames: readonly string[];
+  readonly amm: { readonly entry: string; readonly listedSlot: string | null };
+}
+
+/** The JOINED row: Carpenter's and FLOOR's for one cluster. */
+export interface ClusterDeployment {
+  readonly name: 'mainnet' | 'devnet' | 'testnet' | 'local';
+  readonly chainKey: string | null;
+  readonly programs: { readonly carpenterAmm: string } & FloorClusterDeployment['programs'];
+  readonly accounts: CarpenterClusterDeployment['accounts'] & FloorClusterDeployment['accounts'];
+  readonly alt: string | null;
+  readonly programDataHash: { readonly carpenterAmm: string | null } & FloorClusterDeployment['programDataHash'];
+  readonly quotes?: Readonly<Record<string, QuoteListingRecord>>;
+}
+
+/**
+ * Join one cluster's Carpenter row and FLOOR row. ⛔ Refuses rows of two different clusters by name (a `chainKey` or
+ * `name` mismatch), and a quote the hook's roster records that the AMM's does not (the hook refuses a listing the AMM
+ * has not made, so such a record is a half-finished script run the joined shape cannot express — it keeps the hook's
+ * half and reads `caps` 0, `capNames` [] and an empty `amm`).
+ */
+export function joinDeployment(carpenter: CarpenterClusterDeployment, floor: FloorClusterDeployment): ClusterDeployment {
+  if (carpenter.chainKey !== floor.chainKey || carpenter.name !== floor.name) {
+    throw new Error(`joinDeployment: the Carpenter row is ${carpenter.name} (${carpenter.chainKey}) but the FLOOR row is ${floor.name} (${floor.chainKey})`);
+  }
+  let quotes: Record<string, QuoteListingRecord> | undefined;
+  if (floor.quotes) {
+    quotes = {};
+    for (const [mint, q] of Object.entries(floor.quotes)) {
+      const a = carpenter.quotes?.[mint];
+      quotes[mint] = {
+        state: q.state, decimals: q.decimals, tokenProgram: q.tokenProgram,
+        caps: a?.caps ?? 0, capNames: a?.capNames ?? [], terms: q.terms,
+        amm: { entry: a?.amm.entry ?? '', listedSlot: a?.amm.listedSlot ?? null }, hook: { policy: q.hook.policy },
+      };
+    }
+  }
+  return {
+    name: floor.name,
+    chainKey: floor.chainKey,
+    programs: { carpenterAmm: carpenter.programs.carpenterAmm, ...floor.programs },
+    accounts: { ...carpenter.accounts, ...floor.accounts },
+    alt: floor.alt,
+    programDataHash: { carpenterAmm: carpenter.programDataHash.carpenterAmm, ...floor.programDataHash },
+    ...(quotes ? { quotes } : {}),
+  };
+}
+
+/**
+ * The JOINED deployment for a cluster key, over both shipped files by default. Throws BY NAME on a key either file
+ * lacks: a missing row must never read as a cluster with no launches.
+ */
+export function deploymentFor(clusterKey: string, file: DeploymentsFile = DEPLOYMENTS, carpenterFile: CarpenterDeploymentsFile = CARPENTER_DEPLOYMENTS): ClusterDeployment {
+  const row = file.clusters[clusterKey];
+  if (!row) {
+    throw new Error(`@floorlaunchpad/sdk-solana: no deployment for cluster "${clusterKey}" (known: ${Object.keys(file.clusters).join(', ')})`);
+  }
+  const amm = carpenterFile.clusters[clusterKey];
+  if (!amm) {
+    throw new Error(`@floorlaunchpad/sdk-solana: @floorlaunchpad/carpenter-sdk has no deployment for cluster "${clusterKey}" (known: ${Object.keys(carpenterFile.clusters).join(', ')})`);
+  }
+  return joinDeployment(amm, row);
+}