@floorlaunchpad/sdk-solana 0.0.0-stage → 0.1.0

package/src/stateView.ts

@@ -0,0 +1,289 @@
+/**
+ * `stateView`: FLOOR's reads (`floor_hook`, `floor_launch`, `floor_holders`) beside `@floorlaunchpad/carpenter-sdk`'s — `stateView`
+ * here spreads Carpenter's object. Every helper takes an `AccountSource` and returns the decoded value WITH the slot it
+ * was read at.
+ *
+ * ⛔ Inside a hooked flow, pool state comes from instruction data or post-state, never from a stale account: these
+ *    helpers are for UIs and for building transactions.
+ * ⛔ Every account is checked for its OWNER program as well as its discriminator; a lookalike account owned by another
+ *    program is `null`, never decoded.
+ */
+
+import {
+  stateView as carpenterStateView,
+  type AtSlot,
+  TOKEN_2022_PROGRAM_ID,
+  hasDiscriminator,
+  type LayoutDef,
+  type AccountSource,
+  type RawAccount,
+  decodeTokenAccount,
+} from '@floorlaunchpad/carpenter-sdk';
+
+import {
+  BUYER_POSITION,
+  decodeBuyerPosition,
+  decodeFloorPool,
+  decodeHookConfig,
+  decodeLaunch,
+  decodeLaunchConfig,
+  decodePlatformTreasury,
+  decodeQuotePolicy,
+  decodeRegistryEntry,
+  QUOTE_POLICY,
+  REGISTRY_ENTRY,
+  type BuyerPosition,
+  type FloorPool,
+  type HookConfig,
+  type Launch,
+  type LaunchConfig,
+  type PlatformTreasury,
+  type QuotePolicy,
+  type RegistryEntry,
+
+  
+
+  
+  decodeStairState,
+  type StairState,
+} from './layouts.ts';
+import {
+  DEFAULT_PROGRAM_IDS,
+  findBuyerPosition,
+  findFloorPool,
+  findHookConfig,
+  findPlatformTreasury,
+  findTeamTreasury,
+  findLaunch,
+  findLaunchConfig,
+  findQuotePolicy,
+  findRegistryEntry,
+  type ProgramIds,
+  findStairState,
+} from './pda.ts';
+
+import type { Address } from '@solana/kit';
+
+function ownedBy(a: RawAccount | null, program: Address): RawAccount | null {
+  return a && a.owner === program ? a : null;
+}
+
+async function readOwned<T>(src: AccountSource, address: Address, program: Address, decode: (d: Uint8Array) => T): Promise<AtSlot<T | null>> {
+  const { slot, account } = await src.getAccount(address);
+  const a = ownedBy(account, program);
+  return { slot, value: a ? decode(a.data) : null };
+}
+
+function decodeAll<T>(rows: { address: Address; account: RawAccount }[], layout: LayoutDef, decode: (d: Uint8Array) => T): [Address, T][] {
+  const out: [Address, T][] = [];
+  for (const { address, account } of rows) {
+    if (!hasDiscriminator(layout, account.data)) continue;
+    out.push([address, decode(account.data)]);
+  }
+  return out;
+}
+// ---- FLOOR --------------------------------------------------------------------------------------
+
+export async function getHookConfig(src: AccountSource, ids: ProgramIds = DEFAULT_PROGRAM_IDS): Promise<AtSlot<HookConfig | null>> {
+  return readOwned(src, (await findHookConfig(ids)).address, ids.floorHook, decodeHookConfig);
+}
+
+/**
+ *  the program-owned platform treasury (`["platform_treasury"]` under
+ * `floor_hook`) — its governance and any pending handover. `null` before `initialize_hook_config` has run.
+ */
+export async function getPlatformTreasury(src: AccountSource, ids: ProgramIds = DEFAULT_PROGRAM_IDS): Promise<AtSlot<PlatformTreasury | null>> {
+  return readOwned(src, (await findPlatformTreasury(ids)).address, ids.floorHook, decodePlatformTreasury);
+}
+
+/**
+ *  the program-owned TEAM treasury (`["team_treasury"]` under
+ * `floor_hook`, `PlatformTreasury`'s layout) — its governance and any pending handover. `null` until
+ * `initialize_team_treasury` has run; until then every sweep skips its team leg and the pool keeps `team_owed`.
+ */
+export async function getTeamTreasury(src: AccountSource, ids: ProgramIds = DEFAULT_PROGRAM_IDS): Promise<AtSlot<PlatformTreasury | null>> {
+  return readOwned(src, (await findTeamTreasury(ids)).address, ids.floorHook, decodePlatformTreasury);
+}
+
+/**
+ *  presence for the FLOOR quote roster entry.
+ * `null` means "not on the FLOOR roster" — and wSOL is NEVER on it: it is admitted by construction
+ * with compiled-in terms (`quote_policy.rs`: `list_quote` refuses it `QuoteAlreadyListed`), so a
+ * `null` for wSOL is the expected answer, not a missing listing. `retired === 1` blocks NEW pools
+ * only; there is no un-retire. Owner, length and discriminator are all checked, as `getQuoteMint`
+ * does for the AMM's entry: a lamport at the address never means presence.
+ */
+export async function getQuotePolicy(src: AccountSource, quoteMint: Address, ids: ProgramIds = DEFAULT_PROGRAM_IDS): Promise<AtSlot<QuotePolicy | null>> {
+  const { slot, account } = await src.getAccount((await findQuotePolicy(quoteMint, ids)).address);
+  const a = ownedBy(account, ids.floorHook);
+  const present = a && a.data.length === 8 + QUOTE_POLICY.size && hasDiscriminator(QUOTE_POLICY, a.data);
+  return { slot, value: present ? decodeQuotePolicy(a.data) : null };
+}
+
+export async function getFloorPool(src: AccountSource, ammPool: Address, ids: ProgramIds = DEFAULT_PROGRAM_IDS): Promise<AtSlot<FloorPool | null>> {
+  return readOwned(src, (await findFloorPool(ammPool, ids)).address, ids.floorHook, decodeFloorPool);
+}
+
+/**
+ * A staircase pool's `StairState`
+ * (`["stair", floor_pool]` under `floor_hook`), or `null` — on every pool without a staircase, and on a staircase launch
+ * before `prepare_positions` / its graduating buy created it. `floorPool` is the `FloorPool` ADDRESS (`findFloorPool(amm)`).
+ * The ratchet of a graduated staircase pool needs it (`buildRatchet({ stairState })`).
+ */
+export async function getStairState(src: AccountSource, floorPool: Address, ids: ProgramIds = DEFAULT_PROGRAM_IDS): Promise<AtSlot<StairState | null>> {
+  return readOwned(src, (await findStairState(floorPool, ids)).address, ids.floorHook, decodeStairState);
+}
+
+export async function getLaunchConfig(src: AccountSource, ids: ProgramIds = DEFAULT_PROGRAM_IDS): Promise<AtSlot<LaunchConfig | null>> {
+  return readOwned(src, (await findLaunchConfig(ids)).address, ids.floorLaunch, decodeLaunchConfig);
+}
+
+export async function getLaunch(src: AccountSource, mint: Address, ids: ProgramIds = DEFAULT_PROGRAM_IDS): Promise<AtSlot<Launch | null>> {
+  return readOwned(src, (await findLaunch(mint, ids)).address, ids.floorLaunch, decodeLaunch);
+}
+
+export async function getBuyerPosition(src: AccountSource, launch: Address, buyer: Address, ids: ProgramIds = DEFAULT_PROGRAM_IDS): Promise<AtSlot<BuyerPosition | null>> {
+  const { slot, account } = await src.getAccount((await findBuyerPosition(launch, buyer, ids)).address);
+  const a = ownedBy(account, ids.floorLaunch);
+  return { slot, value: a && hasDiscriminator(BUYER_POSITION, a.data) ? decodeBuyerPosition(a.data) : null };
+}
+
+/**
+ * One launch as a multi-source reader merges it:
+ * keyed `(chainKey, id)`, where `chainKey` is `solana:<genesis32>` and `id` is the MINT address
+ * (the one key a Solana launch is known by everywhere: the Launch PDA and the registry entry
+ * both derive from or point at it).
+ * ⛔ Name and symbol are chain-only; they are not in these accounts (Token-2022 metadata carries
+ *    them) and this row does not invent them.
+ */
+export interface LaunchRow {
+  readonly chainKey: string;
+  readonly id: Address;
+  readonly registryIndex: bigint;
+  readonly launch: Address;
+  readonly mint: Address;
+  readonly ammPool: Address;
+  readonly mode: number;
+  readonly createdSlot: bigint;
+  /** `null` when the Launch account was not readable (it never should be, once registered). */
+  readonly state: Launch | null;
+}
+
+/**
+ * Every launch, newest first, over `RegistryEntry`. Two strategies, both exact:
+ * - `mode: 'index'` (default, browser-safe): read `LaunchConfig.registry_count`, then entries
+ *   `[count-1 … count-limit]` by PDA with `getMultipleAccounts`; no `getProgramAccounts`.
+ * - `mode: 'scan'` (server-side): one `getProgramAccounts` on the discriminator.
+ * `nextBefore` is where the next page starts (pass it as `before`), or `null` at the end. In `index` mode it is the
+ * lowest registry index this page PROBED, so an entry that is missing or unreadable never ends paging early: a page can
+ * hold fewer than `limit` rows and still have a next one.
+ * ⛔ The listing is UNFILTERED, with the risk stated: anyone can create a launch, with any name and symbol.
+ */
+export async function listLaunches(
+  src: AccountSource,
+  chainKey: string,
+  opts: { before?: bigint; limit?: number; mode?: 'index' | 'scan'; withState?: boolean } = {},
+  ids: ProgramIds = DEFAULT_PROGRAM_IDS,
+): Promise<AtSlot<LaunchRow[]> & { nextBefore: bigint | null }> {
+  if (!/^solana:[1-9A-HJ-NP-Za-km-z]{32}$/.test(chainKey)) throw new Error(`listLaunches: chainKey must be solana:<genesis32>, got ${chainKey}`);
+  const limit = opts.limit ?? 50;
+  let entries: RegistryEntry[];
+  let slot: bigint;
+  let nextBefore: bigint | null;
+  if (opts.mode === 'scan') {
+    const r = await src.getProgramAccounts(ids.floorLaunch, [
+      { memcmp: { offset: 0, bytes: REGISTRY_ENTRY.discriminator } },
+      { dataSize: 8 + REGISTRY_ENTRY.size },
+    ]);
+    slot = r.slot;
+    entries = decodeAll(r.accounts, REGISTRY_ENTRY, decodeRegistryEntry)
+      .map(([, e]) => e)
+      .filter((e) => opts.before === undefined || e.index < opts.before)
+      .sort((a, b) => (a.index < b.index ? 1 : a.index > b.index ? -1 : 0))
+      .slice(0, limit);
+    const last = entries[entries.length - 1];
+    nextBefore = entries.length === limit && last && last.index > 0n ? last.index : null;
+  } else {
+    const cfg = await getLaunchConfig(src, ids);
+    if (!cfg.value) throw new Error('listLaunches: LaunchConfig is not initialized on this cluster');
+    const top = opts.before === undefined || opts.before > cfg.value.registryCount ? cfg.value.registryCount : opts.before;
+    const indices: bigint[] = [];
+    for (let i = top - 1n; i >= 0n && indices.length < limit; i--) indices.push(i);
+    const lowest = indices[indices.length - 1];
+    nextBefore = lowest !== undefined && lowest > 0n ? lowest : null;
+    const addrs = await Promise.all(indices.map(async (i) => (await findRegistryEntry(i, ids)).address));
+    const r = await src.getMultipleAccounts(addrs);
+    slot = r.slot < cfg.slot ? r.slot : cfg.slot;
+    entries = [];
+    r.accounts.forEach((a, i) => {
+      const owned = ownedBy(a, ids.floorLaunch);
+      if (owned && hasDiscriminator(REGISTRY_ENTRY, owned.data)) {
+        const e = decodeRegistryEntry(owned.data);
+        if (e.index === indices[i]) entries.push(e);
+      }
+    });
+  }
+  let states: (Launch | null)[] = entries.map(() => null);
+  if (opts.withState !== false && entries.length > 0) {
+    const r = await src.getMultipleAccounts(entries.map((e) => e.launch));
+    slot = r.slot < slot ? r.slot : slot;
+    states = r.accounts.map((a) => {
+      const owned = ownedBy(a, ids.floorLaunch);
+      return owned ? decodeLaunch(owned.data) : null;
+    });
+  }
+  return {
+    slot,
+    nextBefore,
+    value: entries.map((e, i) => ({
+      chainKey,
+      id: e.mint,
+      registryIndex: e.index,
+      launch: e.launch,
+      mint: e.mint,
+      ammPool: e.ammPool,
+      mode: e.mode,
+      createdSlot: e.createdSlot,
+      state: states[i] ?? null,
+    })),
+  };
+}
+
+/** The named `stateView` object: Carpenter's reads, then FLOOR's. */
+export const stateView = {
+  ...carpenterStateView,
+  getHookConfig,
+  getQuotePolicy,
+  getFloorPool,
+  getLaunchConfig,
+  listLaunches,
+  getLaunch,
+  getBuyerPosition,
+} as const;
+
+export async function getHolderPayoutInputs(src: AccountSource, a: {
+  owner: Address; mint: Address; floorPool: Address; ids?: ProgramIds;
+}) {
+  const ids = a.ids ?? DEFAULT_PROGRAM_IDS;
+  const { findHolderBook, findHolderRecord } = await import('./holders.ts');
+  const { findAta } = await import('@floorlaunchpad/carpenter-sdk');
+  const { decodeHolderBook, decodeHolderRecord } = await import('./layouts.ts');
+  const tokenAccount = (await findAta(a.owner, a.mint, TOKEN_2022_PROGRAM_ID)).address;
+  const [book, record] = await Promise.all([findHolderBook(a.mint, ids), findHolderRecord(a.mint, tokenAccount, ids)]);
+  const { slot, accounts } = await src.getMultipleAccounts([book.address, record.address, a.floorPool, tokenAccount]);
+  const b = ownedBy(accounts[0] ?? null, ids.floorHolders);
+  const r = ownedBy(accounts[1] ?? null, ids.floorHolders);
+  const p = ownedBy(accounts[2] ?? null, ids.floorHook);
+  if (!b || !r || !p) return { slot, value: null };
+  const bookState = decodeHolderBook(b.data);
+  const recordState = decodeHolderRecord(r.data);
+  const pool = decodeFloorPool(p.data);
+  if (bookState.mint !== a.mint || bookState.floorPool !== a.floorPool || bookState.quoteMint !== pool.quoteMint
+    || pool.baseMint !== a.mint || recordState.mint !== a.mint || recordState.tokenAccount !== tokenAccount
+    || recordState.owner !== a.owner) return { slot, value: null };
+  const t = ownedBy(accounts[3] ?? null, TOKEN_2022_PROGRAM_ID);
+  const token = t ? decodeTokenAccount(t.data) : null;
+  const liveBalance = token?.mint === a.mint ? token.amount : 0n;
+  return { slot, value: { book: b.data, record: r.data, floorPool: p.data, liveBalance,
+    ammPool: pool.ammPool, quoteMint: pool.quoteMint, tokenAccount, recordAddress: record.address } };
+}

package/src/tickmath.ts

@@ -0,0 +1,120 @@
+/**
+ * FLOOR's tick arithmetic: `open_tick`, the staircase edges, the tranche price and the quote lineage's conversions.
+ * The AMM's tick math (`getSqrtPriceAtTick`, `getTickAtSqrtPrice`, the spacing snaps, tick-array starts) is
+ * `@floorlaunchpad/carpenter-sdk`'s.
+ */
+
+import {
+  getSqrtPriceAtTick,
+  getTickAtSqrtPrice,
+  isqrt,
+  MAX_TICK,
+  MIN_TICK,
+  MAX_SQRT_PRICE_X64,
+  MIN_SQRT_PRICE_X64,
+  ceilToSpacing,
+} from '@floorlaunchpad/carpenter-sdk';
+
+/**
+ *  `open_tick(price_x64)`: `sqrt = isqrt(2^192 / price_x64)` (U256), then
+ * `tick_at_sqrt_price`. The pool is initialized at `sqrt_price_at_tick(open_tick)`.
+ */
+export function openTick(priceX64: bigint): number {
+  if (priceX64 <= 0n) throw new RangeError('price_x64 must be positive');
+  return getTickAtSqrtPrice(isqrt((1n << 192n) / priceX64));
+}
+
+/**
+ * `floor_math::stair::doubling_ticks(i)`:
+ * ticks for `i` doublings of the token price, `get_tick_at_sqrt_price(sqrt_price_from_ratio(1, 2^i)) + 1` =
+ * `ceil(i · ln 2 / ln 1.0001)`, computed per `i` (never `i · 6,932`). 0 for 0.
+ */
+export function doublingTicks(i: number): number {
+  if (!Number.isInteger(i) || i < 0 || i > 64) throw new RangeError(`doublingTicks: ${i}`);
+  if (i === 0) return 0;
+  let sqrt = isqrt(1n << BigInt(96 + i)) << 16n;
+  if (sqrt < MIN_SQRT_PRICE_X64) sqrt = MIN_SQRT_PRICE_X64;
+  if (sqrt >= MAX_SQRT_PRICE_X64) sqrt = MAX_SQRT_PRICE_X64 - 1n;
+  return getTickAtSqrtPrice(sqrt) + 1;
+}
+
+/** `floor_math::stair::stair_edge`: the staircase's cheap edge `i` doublings above `openEdge`, on the grid. Step i is
+ *  `[stairEdge(i + 1), stairEdge(i)]`; the reserve from step `f` is `[stairEdge(steps), stairEdge(f)]`; the tail
+ *  `[ceilToSpacing(MIN_TICK), stairEdge(steps)]`. */
+export function stairEdge(openEdge: number, i: number, spacing: number): number {
+  return openEdge - ceilToSpacing(doublingTicks(i), spacing);
+}
+
+/**
+ * `floor_math::stair::cushion_home_top`, step for step: the top a cushion takes when `min(spot, TWAP)` has no
+ * range above the bid band — the CHEAPEST full-depth range just above the band, `[dear − ceilToSpacing(width), dear]`
+ * (`dear = floorTick − ceilToSpacing(BID_BAND_TICKS)`), or the spot when the spot is cheaper still (in ticks the HIGHER).
+ */
+export function cushionHomeTop(spotTick: number, floorTick: number, spacing: number, width: number, bandTicks = 120): number {
+  const dear = floorTick - ceilToSpacing(bandTicks, spacing);
+  return Math.max(spotTick, dear - ceilToSpacing(width, spacing) - 1);
+}
+
+/** `floor_math::stair::stair_fits`: a staircase of `steps` from `openEdge` leaves at least one spacing for the open tail
+ *  above it (`stairEdge(steps) − spacing ≥ ceilToSpacing(MIN_TICK)`). `resolve_config` refuses a launch that does not
+ *  (`StairDoesNotFit`, 6059) — a quote and a cap whose open tick sits too near the top of the range. */
+export function stairFits(openEdge: number, steps: number, spacing: number): boolean {
+  return stairEdge(openEdge, steps, spacing) - spacing >= ceilToSpacing(MIN_TICK, spacing);
+}
+
+/** The admissible decimals of a launch's QUOTE mint, inclusive — the twin of `floor_math::constants::MIN/MAX_QUOTE_DECIMALS`;
+ * `floor_hook::list_quote` refuses a mint outside it and `tranche_price_x64` refuses to price one. The only thing the
+ * arithmetic bounds is the tranche price itself, `0 < p < 2^77`: past `d = 36` no (cap, quote price) a u64 can carry
+ * prices a launch (`p_min(d) = 100·10^d·2^64/(u64::MAX·SUPPLY) >= 2^77` from 37 up), so 36 is derived, not chosen.
+ * ⚠ The EFFECTIVE ceiling for a given launch is far lower and value-shaped: {@link tranchePriceX64} throws
+ * `tranche price out of range` once `mcap·100·10^d/(cents·SUPPLY) >= 2^13` — `d <= 14` at a $30k cap against a $1.00
+ * quote. */
+export const MIN_QUOTE_DECIMALS = 0;
+export const MAX_QUOTE_DECIMALS = 36;
+
+/**
+ * `tranche_price_x64(mcap_usd, quote_usd_cents, quote_decimals)`:
+ * `floor(mcap_usd·100·10^d·2^64 / (quote_usd_cents·SUPPLY))`, required `0 < price < 2^77`.
+ *
+ * ⛔ The quote price is in CENTS and the quote's decimals are explicit, so a $1.00 quote prices exactly. This is the ONE
+ * place a decimals count enters the mechanism: everything downstream (`openTick`, the sale walk, the fee split) is raw
+ * base units and Q64.64 and reads no decimals at all.
+ */
+export function tranchePriceX64(mcapUsd: bigint, quoteUsdCents: bigint, quoteDecimals: number): bigint {
+  if (mcapUsd <= 0n || quoteUsdCents <= 0n) throw new RangeError('mcap_usd and quote_usd_cents must be positive');
+  if (!Number.isInteger(quoteDecimals) || quoteDecimals < MIN_QUOTE_DECIMALS || quoteDecimals > MAX_QUOTE_DECIMALS) {
+    throw new RangeError(`quote decimals out of range: ${quoteDecimals} (must be ${MIN_QUOTE_DECIMALS}..${MAX_QUOTE_DECIMALS})`);
+  }
+  const unit = 10n ** BigInt(quoteDecimals);
+  const p = (mcapUsd * 100n * unit * (1n << 64n)) / (quoteUsdCents * 1_000_000_000_000_000n);
+  if (p <= 0n || p >= 1n << 77n) throw new RangeError(`tranche price out of range: ${p}`);
+  return p;
+}
+
+/**
+ * The twins of `floor_math::lineage`.
+ * `minBidFor(d)` = `ceil(10^d / 1,000)`, at least 1, saturating at u64::MAX: the default `min_bid` of a quote no
+ * governance roster names. `quoteAmountAtTick(amount, t)` = `amount · sqrt(t)^2 / 2^128` in two `>> 64` steps,
+ * rounded down, saturating at u64::MAX, 0 off the tick range: the smart tip cap's conversion (the parent's raw
+ * `max_bounty` → raw units of the parent's base, at the parent's 1,800 s TWAP tick).
+ */
+export const SMART_CAP_TWAP_WINDOW_SECS = 1_800;
+const U64_MAX = (1n << 64n) - 1n;
+export function minBidFor(decimals: number): bigint {
+  if (!Number.isInteger(decimals) || decimals < 0) throw new RangeError(`decimals: ${decimals}`);
+  if (decimals > 38) return U64_MAX;
+  const unit = 10n ** BigInt(decimals);
+  const v = (unit + 999n) / 1000n;
+  const r = v < 1n ? 1n : v;
+  return r > U64_MAX ? U64_MAX : r;
+}
+export function quoteAmountAtSqrt(amount: bigint, sqrtPriceX64: bigint): bigint {
+  if (amount === 0n || sqrtPriceX64 === 0n) return 0n;
+  const a = (amount * sqrtPriceX64) >> 64n;
+  const v = (a * sqrtPriceX64) >> 64n;
+  return v > U64_MAX ? U64_MAX : v;
+}
+export function quoteAmountAtTick(amount: bigint, tick: number): bigint {
+  if (!Number.isInteger(tick) || tick < MIN_TICK || tick > MAX_TICK) return 0n;
+  return quoteAmountAtSqrt(amount, getSqrtPriceAtTick(tick));
+}

package/src/twap.ts

@@ -0,0 +1,130 @@
+/**
+ * The pool-price TWAP's arithmetic, off chain — a line-for-line twin of `floor_types::twap::TwapOracle` (`observe`,
+ * `twap_tick`, `settled_tick`) over the oracle tail of a `FloorPool` account (`decodeFloorPoolTwap`).
+ * ⛔ Arithmetic wraps exactly as the program's: the cumulative is an `i64` (`BigInt.asIntN(64, …)`), times are `u32`
+ *    (`>>> 0`), and a write whose clock reads BEHIND the stored timestamp is a no-op.
+ * ⚠ A simulated `twap_tick` reads before any write in the same transaction and refuses a ring younger than the window
+ *   (`TwapWindowTooLong`), where `settled_tick` answers over the oldest checkpoint.
+ */
+import { CUSHION_TWAP_WINDOW_SECS } from './constants.ts';
+import { TWAP_CHECKPOINT_SPACING_SECS, TWAP_CHECKPOINTS, type TwapCheckpointView, type TwapOracleView } from './layouts.ts';
+
+/** `floor_types::twap::TWAP_VERSION`: the oracle's version once written. */
+export const TWAP_VERSION = 1;
+
+/** Why a window read has no answer (`floor_types::twap::TwapError`). */
+export type TwapReadError = 'Uninitialized' | 'WindowTooLong';
+/** A window read: the tick, or why there is none. */
+export type TwapRead = { readonly tick: number } | { readonly error: TwapReadError };
+
+const u32 = (x: number): number => x >>> 0;
+const i64 = (x: bigint): bigint => BigInt.asIntN(64, x);
+const I32_MIN = -(2 ** 31);
+const I32_MAX = 2 ** 31 - 1;
+
+/** `a / b` rounded toward negative infinity (`b > 0`), `floor_types::twap::floor_div`. */
+export function twapFloorDiv(a: bigint, b: bigint): bigint {
+  const q = a / b;
+  return a % b !== 0n && a < 0n !== b < 0n ? q - 1n : q;
+}
+
+function initialized(o: TwapOracleView): boolean {
+  return o.version !== 0 && o.count !== 0;
+}
+
+function ring(o: TwapOracleView, i: number): TwapCheckpointView {
+  return o.checkpoints[i % TWAP_CHECKPOINTS] ?? { tickCumulative: 0n, timestamp: 0 };
+}
+
+/** The oracle a zero tail decodes to: never written. */
+export function emptyTwapOracle(): TwapOracleView {
+  return {
+    version: 0,
+    newest: 0,
+    count: 0,
+    current: { tickCumulative: 0n, timestamp: 0, lastTick: 0 },
+    checkpoints: Array.from({ length: TWAP_CHECKPOINTS }, () => ({ tickCumulative: 0n, timestamp: 0 })),
+    olderSurplusHeld: 0,
+    cushionTopSet: 0,
+    cushionTopTick: 0,
+    netFlow: { a: 0n, b: 0n },
+  };
+}
+
+/** The cushion-top cache and the net-flow meter: carried through every oracle write as the program does
+ *  (`TwapOracle::observe` keeps both; the meter is `after_swap`'s, the cache the ratchet's). */
+function keptCache(o: TwapOracleView): { cushionTopSet?: number; cushionTopTick?: number; netFlow?: { a: bigint; b: bigint } } {
+  return {
+    ...(o.cushionTopSet === undefined ? {} : { cushionTopSet: o.cushionTopSet, cushionTopTick: o.cushionTopTick ?? 0 }),
+    ...(o.netFlow === undefined ? {} : { netFlow: { a: o.netFlow.a, b: o.netFlow.b } }),
+  };
+}
+
+/**
+ * THE WRITE (`TwapOracle::observe`): `tick` is the pool's tick BEFORE whatever is about to move it, at unix second `now`.
+ * Returns the oracle after the write (the input is never mutated); the same object when the write is a no-op (the same
+ * second, or a clock behind the last write).
+ */
+export function twapObserve(o: TwapOracleView, now: number, tick: number): TwapOracleView {
+  const t = u32(now);
+  if (!initialized(o)) {
+    const checkpoints = emptyTwapOracle().checkpoints.slice();
+    checkpoints[0] = { tickCumulative: 0n, timestamp: t };
+    return { version: TWAP_VERSION, newest: 0, count: 1, current: { tickCumulative: 0n, timestamp: t, lastTick: tick }, checkpoints, olderSurplusHeld: o.olderSurplusHeld ?? 0, ...keptCache(o) };
+  }
+  const elapsed = u32(t - o.current.timestamp);
+  if (elapsed === 0 || (elapsed | 0) < 0) return o;
+  const cum = i64(o.current.tickCumulative + i64(BigInt(tick) * BigInt(elapsed)));
+  const checkpoints = o.checkpoints.slice();
+  let { newest, count } = o;
+  if (u32(t - ring(o, o.newest).timestamp) >= TWAP_CHECKPOINT_SPACING_SECS) {
+    newest = (o.newest + 1) % TWAP_CHECKPOINTS;
+    checkpoints[newest] = { tickCumulative: cum, timestamp: t };
+    count = Math.min(o.count + 1, TWAP_CHECKPOINTS);
+  }
+  return { version: o.version, newest, count, current: { tickCumulative: cum, timestamp: t, lastTick: tick }, checkpoints, olderSurplusHeld: o.olderSurplusHeld ?? 0, ...keptCache(o) };
+}
+
+/** The cumulative at `now`, the span since the last write extrapolated with `liveTick` (`cumulative_at`). */
+function cumulativeAt(o: TwapOracleView, now: number, liveTick: number): bigint {
+  return i64(o.current.tickCumulative + i64(BigInt(liveTick) * BigInt(u32(now - o.current.timestamp))));
+}
+
+/**
+ * THE WINDOW READ (`TwapOracle::twap_tick`, the `twap_tick` instruction's answer): the time-weighted mean RAW tick over
+ * the newest checkpoint at least `window` seconds old to now; window 0 is the live tick; the live tick exactly when nothing
+ * has written for the whole window.
+ */
+export function twapTickAt(o: TwapOracleView, now: number, liveTick: number, window: number): TwapRead {
+  if (window === 0) return { tick: liveTick };
+  if (!initialized(o)) return { error: 'Uninitialized' };
+  const t = u32(now);
+  if (u32(t - o.current.timestamp) >= window) return { tick: liveTick };
+  const cumNow = cumulativeAt(o, t, liveTick);
+  const count = Math.min(o.count, TWAP_CHECKPOINTS);
+  for (let back = 0; back < count; back++) {
+    const cp = ring(o, o.newest + TWAP_CHECKPOINTS - back);
+    const age = u32(t - cp.timestamp);
+    if (age >= window) {
+      const avg = twapFloorDiv(i64(cumNow - cp.tickCumulative), BigInt(age));
+      return { tick: Number(avg < BigInt(I32_MIN) ? BigInt(I32_MIN) : avg > BigInt(I32_MAX) ? BigInt(I32_MAX) : avg) };
+    }
+  }
+  return { error: 'WindowTooLong' };
+}
+
+/**
+ * THE SETTLED TICK (`TwapOracle::settled_tick`, what the staircase's cushion reads): {@link twapTickAt} over `window`, and
+ * when the ring is younger than `window`, over its OLDEST checkpoint's age; when even that is 0, the tick at the start of
+ * this second (`current.lastTick`).
+ */
+export function settledTickAt(o: TwapOracleView, now: number, liveTick: number, window: number = CUSHION_TWAP_WINDOW_SECS): TwapRead {
+  const r = twapTickAt(o, now, liveTick, window);
+  if ('error' in r && r.error === 'WindowTooLong') {
+    const count = Math.min(Math.max(o.count, 1), TWAP_CHECKPOINTS);
+    const oldest = ring(o, o.newest + TWAP_CHECKPOINTS + 1 - count);
+    const age = u32(u32(now) - oldest.timestamp);
+    return age > 0 && (age | 0) > 0 ? twapTickAt(o, now, liveTick, age) : { tick: o.current.lastTick };
+  }
+  return r;
+}