@sly-rentals/core 1.1.2 → 2.0.0

package/dist/esm/utils/contestChain.js

@@ -0,0 +1,191 @@
+/**
+ * @purpose Pure-math chain-of-contests simulator.
+ *
+ * Walks a sequence of reservation events (calc defender + user-added
+ * takeovers) and produces per-row floor / bonus / owner-take values
+ * plus the segment breakdown UIs use to render piecewise curves.
+ *
+ * No React, no IO, no RPC. Feeds a calculator/visualization layer
+ * (`@sly-rentals/core/react/calculator`) but is callable standalone
+ * from any environment.
+ */
+import { computeMinimumBid } from './bidMath';
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}
+/**
+ * Convert a stardust value into the caller's display currency.
+ *
+ * ATLAS: stardust / stardustPerAtlas.
+ * POINTS: stardust / (stardustPerAtlas × atlasPerPoint), with a
+ * min-capture floor since the on-chain threshold rejects sub-floor bids.
+ */
+export function stardustToDisplay(stardust, cur, stardustPerAtlas, atlasPerPoint, minCaptureThresholdPoints) {
+    const atlas = Number(stardust) / stardustPerAtlas;
+    if (cur === 'ATLAS')
+        return atlas;
+    return Math.max(atlas / atlasPerPoint, minCaptureThresholdPoints);
+}
+/**
+ * Walk a chain of contest events and produce per-contest math + segment
+ * breakdown.
+ *
+ * The chain begins with an optional calc defender row (the simulator's
+ * "your bid" entry). Subsequent takeover knobs are computed via
+ * `computeMinimumBid` against the previous row's bid.
+ *
+ * v1 assumes same-currency ATLAS knockoffs; tier-upgrade compensation
+ * is not modeled.
+ */
+export function computeContestChain(args) {
+    const { cfg, rateStardust, activeDays, userDefender, takeoverKnobs, displayCur, stardustPerAtlas, atlasPerPoint, minCaptureThresholdPoints, contestedThreshold, contestedCountStart, } = args;
+    const safeSpan = Math.max(0.0001, activeDays);
+    const sorted = [...takeoverKnobs].sort((a, b) => a.atDay - b.atDay);
+    const rows = [];
+    const segments = [];
+    const toDisplay = (s) => stardustToDisplay(s, displayCur, stardustPerAtlas, atlasPerPoint, minCaptureThresholdPoints);
+    const callMinBid = (closeness, defenderBidStardust) => computeMinimumBid({
+        rateStardust,
+        defenderBidStardust,
+        contestedMultiplierMaxBps: cfg.contestedMultiplierMaxBps,
+        captureRateBps: cfg.captureRateBps,
+        closenessFraction: closeness,
+    });
+    const tmp = [];
+    if (userDefender) {
+        tmp.push({
+            id: '__calc',
+            atDay: userDefender.atDay,
+            bidStardust: userDefender.bidStardust,
+            bidDisplay: toDisplay(userDefender.bidStardust),
+            defenderBidStardust: 0n,
+            defenderAtDay: 0,
+            source: 'calc',
+        });
+    }
+    const firstEventAt = tmp[0]?.atDay ?? 0;
+    if (firstEventAt > 0) {
+        segments.push({
+            startDay: 0,
+            endDay: firstEventAt,
+            defenderBidStardust: 0n,
+            hasDefender: false,
+        });
+    }
+    let cursorBid = userDefender?.bidStardust ?? 0n;
+    let cursorAt = userDefender?.atDay ?? 0;
+    for (const k of sorted) {
+        segments.push({
+            startDay: cursorAt,
+            endDay: k.atDay,
+            defenderBidStardust: cursorBid,
+            hasDefender: true,
+        });
+        const closeness = clamp(k.atDay / safeSpan, 0, 1);
+        const floor = callMinBid(closeness, cursorBid);
+        tmp.push({
+            id: k.id,
+            atDay: k.atDay,
+            bidStardust: floor,
+            bidDisplay: toDisplay(floor),
+            defenderBidStardust: cursorBid,
+            defenderAtDay: cursorAt,
+            source: 'knob',
+        });
+        cursorBid = floor;
+        cursorAt = k.atDay;
+    }
+    if (tmp.length > 0) {
+        segments.push({
+            startDay: cursorAt,
+            endDay: activeDays,
+            defenderBidStardust: cursorBid,
+            hasDefender: true,
+        });
+    }
+    // Bonus multiplier — config knob, scales the same-cur knockoff bonus.
+    // 100 bps = 1× = no-op (current on-chain formula).
+    // TODO(bonus_multiplier_bps): drop the `?? 100` fallback once the
+    // on-chain field is guaranteed present.
+    const bonusMult = (cfg.bonusMultiplierBps ?? 100) / 100;
+    const bonusByIdx = tmp.map((_, i) => {
+        const next = tmp[i + 1];
+        if (!next)
+            return 0;
+        const closeness = clamp((next.atDay - tmp[i].atDay) / safeSpan, 0, 1);
+        const raw = Math.max(0, (next.bidDisplay - tmp[i].bidDisplay) * closeness * bonusMult);
+        // Match on-chain `b.min(bid_atlas)` — bonus capped at challenger's bid.
+        return Math.min(next.bidDisplay, raw);
+    });
+    // Owner-take is realized only by the LAST contester in the chain — every
+    // earlier contester gets their bid back as refund when outbid, plus a
+    // bonus from the next challenger's bid. Net contract escrow at end of
+    // chain = bid_last − Σ bonuses paid across the chain (the deficit on
+    // each refund is covered by the next challenger's bid). Intermediate
+    // rows therefore contribute 0 to owner take.
+    const totalBonusForOwner = bonusByIdx.reduce((acc, b) => acc + b, 0);
+    const lastIdx = tmp.length - 1;
+    let contestedCount = contestedCountStart;
+    let bumpFlagged = false;
+    for (let i = 0; i < tmp.length; i++) {
+        const t = tmp[i];
+        const bonusEarned = bonusByIdx[i];
+        const ownerTake = i === lastIdx ? Math.max(0, t.bidDisplay - totalBonusForOwner) : 0;
+        contestedCount = contestedCount + 1;
+        const isInitial = i === 0;
+        const triggersRateBump = !bumpFlagged && contestedThreshold > 0 && contestedCount >= contestedThreshold && !isInitial;
+        if (triggersRateBump)
+            bumpFlagged = true;
+        rows.push({
+            id: t.id,
+            idx: i + 1,
+            atDay: t.atDay,
+            floorStardust: t.bidStardust,
+            floorDisplay: t.bidDisplay,
+            bonusDisplay: bonusEarned,
+            ownerTakeDisplay: ownerTake,
+            defenderBidStardust: t.defenderBidStardust,
+            defenderAtDay: t.defenderAtDay,
+            source: t.source,
+            isInitial,
+            contestedCountAfter: contestedCount,
+            triggersRateBump,
+        });
+    }
+    const baselineAtlas = (Number(rateStardust) / stardustPerAtlas) * activeDays;
+    const baselineDisplay = displayCur === 'ATLAS'
+        ? baselineAtlas
+        : Math.max(baselineAtlas / atlasPerPoint, minCaptureThresholdPoints);
+    const totalOwnerDisplay = rows.reduce((acc, r) => acc + r.ownerTakeDisplay, 0);
+    const totalBonusDisplay = rows.reduce((acc, r) => acc + r.bonusDisplay, 0);
+    const multiplier = baselineDisplay > 0 ? totalOwnerDisplay / baselineDisplay : 0;
+    return {
+        segments,
+        rows,
+        totalOwnerDisplay,
+        totalBonusDisplay,
+        baselineDisplay,
+        multiplier,
+    };
+}
+/** Even spacing across [from, to] excluding endpoints. */
+export function distributeEven(count, from, to) {
+    if (count <= 0 || to <= from)
+        return [];
+    const step = (to - from) / (count + 1);
+    return Array.from({ length: count }, (_, i) => from + step * (i + 1));
+}
+/** Quadratic bias toward `to` — clusters knobs near the snipe window. */
+export function distributeSnipeHeavy(count, from, to) {
+    if (count <= 0 || to <= from)
+        return [];
+    const span = to - from;
+    return Array.from({ length: count }, (_, i) => {
+        const t = (i + 1) / (count + 1);
+        const skewed = 1 - Math.pow(1 - t, 2);
+        return from + span * skewed;
+    });
+}
+let knobCounter = 0;
+export const nextKnobId = () => `k${++knobCounter}`;
+//# sourceMappingURL=contestChain.js.map

package/dist/esm/utils/contestChain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contestChain.js","sourceRoot":"","sources":["../../../src/utils/contestChain.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/contractSnapshot.js

@@ -0,0 +1,201 @@
+/**
+ * @purpose Aggregated point-in-time view of a contract and its rentals
+ *
+ * One-shot fetch that pulls every on-chain account relevant to a single
+ * contract — `ConfigState`, `ContractState`, and the active / queued
+ * `RentalState`s (when they exist) — and also computes the contest
+ * minimum-bid floor evaluated at "now". The raw account states are
+ * exposed verbatim so callers decide what matters; `minimumBid` is the
+ * one piece of derived data that nearly every consumer of this snapshot
+ * needs.
+ *
+ * Granular `fetchConfig` / `fetchContract` / `fetchRental` remain
+ * available for narrow lookups that don't need the whole picture.
+ */
+import { address } from '@solana/kit';
+import { fetchConfig } from '../accounts/config';
+import { fetchContract } from '../accounts/contract';
+import { fetchRental } from '../accounts/rental';
+import { deriveActiveRental, deriveQueuedRental } from '../pda/srsly';
+import { getRpcUrl } from './config';
+import { computeMinimumBid } from './bidMath';
+const SYSTEM_PROGRAM_ID = '11111111111111111111111111111111';
+/**
+ * Fetch a contract and every account directly attached to it in one shot,
+ * then derive the contest minimum-bid floor at "now".
+ *
+ * Strategy: fetch `ConfigState` and `ContractState` in parallel, then read
+ * the contract's `activeRental` / `queuedRental` pointers and fetch
+ * whichever ones exist (in parallel). Pointers that equal SystemProgram
+ * are skipped without an RPC call. The bid floor is computed locally
+ * once all states are in.
+ *
+ * @example
+ * ```ts
+ * const snap = await getContractSnapshot({ contractAddress: 'Abc...' });
+ * const rate = snap.contract.data.rate;
+ * const defenderBid = snap.queuedRental?.data.bidAtlas ?? 0n;
+ * const floorNow = snap.minimumBid.minBidStardust;
+ *
+ * // Project the floor 4 hours forward without re-fetching:
+ * const floorLater = computeMinimumBidFromSnapshot(snap, {
+ *   delaySeconds: 4 * 60 * 60,
+ * });
+ * ```
+ */
+export async function getContractSnapshot(args) {
+    const rpcUrl = args.rpcUrl ?? getRpcUrl();
+    const [config, contract] = await Promise.all([
+        fetchConfig(rpcUrl),
+        fetchContract(args.contractAddress, rpcUrl),
+    ]);
+    const contractData = contract.data;
+    const activePromise = contractData.activeRental && contractData.activeRental.toString() !== SYSTEM_PROGRAM_ID
+        ? deriveActiveRental(contract.address)
+            .then(addr => fetchRental(addr, rpcUrl))
+            .catch(() => null)
+        : Promise.resolve(null);
+    const queuedPromise = contractData.queuedRental && contractData.queuedRental.toString() !== SYSTEM_PROGRAM_ID
+        ? deriveQueuedRental(contract.address)
+            .then(addr => fetchRental(addr, rpcUrl))
+            .catch(() => null)
+        : Promise.resolve(null);
+    const [activeRental, queuedRental] = await Promise.all([activePromise, queuedPromise]);
+    const partialSnap = { config, contract, activeRental, queuedRental };
+    const minimumBid = computeMinimumBidFromSnapshot(partialSnap);
+    return { ...partialSnap, minimumBid };
+}
+/**
+ * Resolve a `ContractSnapshot` from caller-supplied data or fetch fresh.
+ *
+ * Designed for callers (e.g. UIs) that already have a snapshot in hand and
+ * want to skip the RPC roundtrip when building an instruction. Behavior:
+ *
+ *   1. If no snapshot is supplied → fetch a fresh one.
+ *   2. If snapshot's contract address doesn't match `contractAddress` →
+ *      throw immediately (programmer error).
+ *   3. If snapshot's rental fields are stale relative to the contract's
+ *      pointers (contract says a rental exists but snapshot has `null` —
+ *      typical when the snapshot was fetched mid-state-change) → lazy
+ *      refetch the snapshot once.
+ *   4. If still stale after the refetch → throw. The on-chain reality
+ *      conflicts with itself; let the caller decide how to recover.
+ */
+export async function resolveContractSnapshot(args) {
+    if (!args.snapshot) {
+        return getContractSnapshot({
+            contractAddress: args.contractAddress,
+            rpcUrl: args.rpcUrl,
+        });
+    }
+    const requested = address(args.contractAddress);
+    if (args.snapshot.contract.address !== requested) {
+        throw new Error(`Provided snapshot is for contract ${args.snapshot.contract.address}, expected ${requested}`);
+    }
+    if (!isSnapshotStale(args.snapshot)) {
+        return args.snapshot;
+    }
+    const fresh = await getContractSnapshot({
+        contractAddress: args.contractAddress,
+        rpcUrl: args.rpcUrl,
+    });
+    if (isSnapshotStale(fresh)) {
+        throw new Error(`Contract ${requested} has a rental pointer set but the rental account could not be loaded after lazy refetch`);
+    }
+    return fresh;
+}
+function isSnapshotStale(snap) {
+    const activeStale = snap.contract.data.activeRental.toString() !== SYSTEM_PROGRAM_ID && !snap.activeRental;
+    const queuedStale = snap.contract.data.queuedRental.toString() !== SYSTEM_PROGRAM_ID && !snap.queuedRental;
+    return activeStale || queuedStale;
+}
+/**
+ * Pure derivation of `MinimumBid` from an already-fetched snapshot. No RPC.
+ *
+ * Use when the caller has a snapshot and wants the floor at a custom time
+ * projection (`delaySeconds` / `nowSeconds`) or with an overridden
+ * `atlasPerPoint` ratio. For the at-fetch-time floor, read
+ * `snap.minimumBid` directly.
+ */
+export function computeMinimumBidFromSnapshot(snap, opts = {}) {
+    const cfgData = snap.config.data;
+    const contractData = snap.contract.data;
+    const rateStardust = BigInt(contractData.rate);
+    const atlasPerPoint = opts.atlasPerPoint ?? BigInt(cfgData.atlasPerPoint);
+    const stardustPerAtlas = BigInt(cfgData.stardustToAtlas);
+    const activeStart = snap.activeRental ? Number(snap.activeRental.data.startTime) : null;
+    const activeEnd = snap.activeRental ? Number(snap.activeRental.data.endTime) : null;
+    let defenderBidStardust = 0n;
+    if (snap.queuedRental) {
+        const q = snap.queuedRental.data;
+        const bidAtlas = BigInt(q.bidAtlas);
+        const bidPoints = BigInt(q.bidPoints);
+        // Points are 8-decimal dust; converting to stardust requires the same
+        // 8-decimal precision: stardust = points_dust * atlasPerPoint *
+        // stardustPerAtlas / 1e8. With both at 1e8 precision this collapses
+        // to points_dust * atlasPerPoint.
+        const pointsAsStardust = bidPoints > 0n ? (bidPoints * atlasPerPoint * stardustPerAtlas) / 100000000n : 0n;
+        defenderBidStardust = bidAtlas + pointsAsStardust;
+    }
+    const evaluatedAtSeconds = opts.nowSeconds !== undefined
+        ? Math.floor(opts.nowSeconds)
+        : Math.floor(Date.now() / 1000) + Math.max(0, opts.delaySeconds ?? 0);
+    let closeness = 0;
+    if (activeStart !== null && activeEnd !== null && activeEnd > activeStart) {
+        const span = activeEnd - activeStart;
+        const elapsed = evaluatedAtSeconds - activeStart;
+        closeness = Math.max(0, Math.min(1, elapsed / span));
+    }
+    const minBidStardust = computeMinimumBid({
+        rateStardust,
+        defenderBidStardust,
+        contestedMultiplierMaxBps: cfgData.contestedMultiplierMaxBps,
+        captureRateBps: BigInt(cfgData.captureRateBps),
+        closenessFraction: closeness,
+    });
+    const baseStardust = rateStardust > defenderBidStardust ? rateStardust : defenderBidStardust;
+    const rampMultiplier = baseStardust > 0n ? Number(minBidStardust) / Number(baseStardust) : 1;
+    return {
+        minBidStardust,
+        defenderBidStardust,
+        rateStardust,
+        closenessFraction: closeness,
+        rampMultiplier,
+        evaluatedAtSeconds,
+        activeEndSeconds: activeEnd,
+        activeStartSeconds: activeStart,
+    };
+}
+/**
+ * Convenience wrapper: fetch a snapshot and return only its `minimumBid`.
+ *
+ * Same fetches as `getContractSnapshot` — if you need the contract / rental
+ * states too, call `getContractSnapshot` directly so you don't fetch twice.
+ *
+ * For time-projected floors, pass `delaySeconds` or `nowSeconds`; the
+ * underlying fetch is identical.
+ */
+export async function getMinimumBid(args) {
+    if (args.snapshot) {
+        return computeMinimumBidFromSnapshot(args.snapshot, {
+            delaySeconds: args.delaySeconds,
+            nowSeconds: args.nowSeconds,
+            atlasPerPoint: args.atlasPerPoint,
+        });
+    }
+    const snap = await getContractSnapshot({
+        contractAddress: args.contractAddress,
+        rpcUrl: args.rpcUrl,
+    });
+    if (args.delaySeconds === undefined &&
+        args.nowSeconds === undefined &&
+        args.atlasPerPoint === undefined) {
+        return snap.minimumBid;
+    }
+    return computeMinimumBidFromSnapshot(snap, {
+        delaySeconds: args.delaySeconds,
+        nowSeconds: args.nowSeconds,
+        atlasPerPoint: args.atlasPerPoint,
+    });
+}
+//# sourceMappingURL=contractSnapshot.js.map

package/dist/esm/utils/contractSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contractSnapshot.js","sourceRoot":"","sources":["../../../src/utils/contractSnapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAgB,MAAM,aAAa,CAAC;AAIpD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAmB,MAAM,WAAW,CAAC;AAE/D,MAAM,iBAAiB,GAAG,kCAAkC,CAAC;AAmB7D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAGzC;IACC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;IAE1C,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC3C,WAAW,CAAC,MAAM,CAAC;QACnB,aAAa,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC;KAC5C,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC;IAEnC,MAAM,aAAa,GACjB,YAAY,CAAC,YAAY,IAAI,YAAY,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,iBAAiB;QACrF,CAAC,CAAC,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC;aACjC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;aACvC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;QACtB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B,MAAM,aAAa,GACjB,YAAY,CAAC,YAAY,IAAI,YAAY,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,iBAAiB;QACrF,CAAC,CAAC,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC;aACjC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;aACvC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;QACtB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC;IAEvF,MAAM,WAAW,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;IACrE,MAAM,UAAU,GAAG,6BAA6B,CAAC,WAAW,CAAC,CAAC;IAE9D,OAAO,EAAE,GAAG,WAAW,EAAE,UAAU,EAAE,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,IAI7C;IACC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnB,OAAO,mBAAmB,CAAC;YACzB,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,eAA0B,CAAC,CAAC;IAC3D,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CACb,qCAAqC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,cAAc,SAAS,EAAE,CAC7F,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC;QACtC,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;IAEH,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,YAAY,SAAS,yFAAyF,CAC/G,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,IAAsB;IAC7C,MAAM,WAAW,GACf,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,iBAAiB,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;IACzF,MAAM,WAAW,GACf,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,iBAAiB,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;IACzF,OAAO,WAAW,IAAI,WAAW,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,6BAA6B,CAC3C,IAA0C,EAC1C,OAII,EAAE;IAEN,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IACjC,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAExC,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1E,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAEzD,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxF,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEpF,IAAI,mBAAmB,GAAG,EAAE,CAAC;IAC7B,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;QACjC,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QACpC,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACtC,sEAAsE;QACtE,gEAAgE;QAChE,oEAAoE;QACpE,kCAAkC;QAClC,MAAM,gBAAgB,GACpB,SAAS,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,aAAa,GAAG,gBAAgB,CAAC,GAAG,UAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QACtF,mBAAmB,GAAG,QAAQ,GAAG,gBAAgB,CAAC;IACpD,CAAC;IAED,MAAM,kBAAkB,GACtB,IAAI,CAAC,UAAU,KAAK,SAAS;QAC3B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC;QAC7B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC;IAE1E,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,WAAW,KAAK,IAAI,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,GAAG,WAAW,EAAE,CAAC;QAC1E,MAAM,IAAI,GAAG,SAAS,GAAG,WAAW,CAAC;QACrC,MAAM,OAAO,GAAG,kBAAkB,GAAG,WAAW,CAAC;QACjD,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,cAAc,GAAG,iBAAiB,CAAC;QACvC,YAAY;QACZ,mBAAmB;QACnB,yBAAyB,EAAE,OAAO,CAAC,yBAAyB;QAC5D,cAAc,EAAE,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC;QAC9C,iBAAiB,EAAE,SAAS;KAC7B,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,YAAY,GAAG,mBAAmB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,mBAAmB,CAAC;IAC7F,MAAM,cAAc,GAAG,YAAY,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7F,OAAO;QACL,cAAc;QACd,mBAAmB;QACnB,YAAY;QACZ,iBAAiB,EAAE,SAAS;QAC5B,cAAc;QACd,kBAAkB;QAClB,gBAAgB,EAAE,SAAS;QAC3B,kBAAkB,EAAE,WAAW;KAChC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAcnC;IACC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,OAAO,6BAA6B,CAAC,IAAI,CAAC,QAAQ,EAAE;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,aAAa,EAAE,IAAI,CAAC,aAAa;SAClC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,mBAAmB,CAAC;QACrC,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;IAEH,IACE,IAAI,CAAC,YAAY,KAAK,SAAS;QAC/B,IAAI,CAAC,UAAU,KAAK,SAAS;QAC7B,IAAI,CAAC,aAAa,KAAK,SAAS,EAChC,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,OAAO,6BAA6B,CAAC,IAAI,EAAE;QACzC,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,aAAa,EAAE,IAAI,CAAC,aAAa;KAClC,CAAC,CAAC;AACL,CAAC"}

package/dist/esm/utils/contractSnapshot.test.js

@@ -0,0 +1,245 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+vi.mock('../accounts/config', () => ({
+    fetchConfig: vi.fn(),
+}));
+vi.mock('../accounts/contract', () => ({
+    fetchContract: vi.fn(),
+}));
+vi.mock('../accounts/rental', () => ({
+    fetchRental: vi.fn(),
+}));
+vi.mock('../pda/srsly', () => ({
+    deriveActiveRental: vi.fn(),
+    deriveQueuedRental: vi.fn(),
+}));
+vi.mock('./config', () => ({
+    getRpcUrl: () => 'http://localhost:8899',
+}));
+import { fetchConfig } from '../accounts/config';
+import { fetchContract } from '../accounts/contract';
+import { fetchRental } from '../accounts/rental';
+import { deriveActiveRental, deriveQueuedRental } from '../pda/srsly';
+import { getContractSnapshot, resolveContractSnapshot, computeMinimumBidFromSnapshot, } from './contractSnapshot';
+const SYSTEM = '11111111111111111111111111111111';
+// Real validated 32-byte base58 addresses for test fixtures.
+const CONTRACT_ADDR = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const ACTIVE_ADDR = 'So11111111111111111111111111111111111111112';
+const QUEUED_ADDR = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+const OTHER_ADDR = 'BPFLoader2111111111111111111111111111111111';
+const VAULT_ADDR = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
+const makeConfig = (overrides = {}) => ({
+    stardustToAtlas: 100000000n,
+    atlasPerPoint: 100n,
+    captureRateBps: 10500n,
+    contestedMultiplierMaxBps: 465,
+    slyvault: VAULT_ADDR,
+    atlasMint: VAULT_ADDR,
+    ...overrides,
+});
+const makeContract = (overrides = {}) => ({
+    rate: 100000000n,
+    activeRental: SYSTEM,
+    queuedRental: SYSTEM,
+    fleet: VAULT_ADDR,
+    gameId: VAULT_ADDR,
+    thread: SYSTEM,
+    ...overrides,
+});
+const makeRental = (overrides = {}) => ({
+    bidAtlas: 0n,
+    bidPoints: 0n,
+    startTime: 0n,
+    endTime: 0n,
+    ...overrides,
+});
+beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(deriveActiveRental).mockResolvedValue(ACTIVE_ADDR);
+    vi.mocked(deriveQueuedRental).mockResolvedValue(QUEUED_ADDR);
+});
+describe('getContractSnapshot', () => {
+    it('returns null rentals when contract pointers are SystemProgram', async () => {
+        vi.mocked(fetchConfig).mockResolvedValue({ data: makeConfig(), address: 'CFG' });
+        vi.mocked(fetchContract).mockResolvedValue({
+            data: makeContract(),
+            address: CONTRACT_ADDR,
+        });
+        const snap = await getContractSnapshot({ contractAddress: CONTRACT_ADDR });
+        expect(snap.activeRental).toBeNull();
+        expect(snap.queuedRental).toBeNull();
+        expect(fetchRental).not.toHaveBeenCalled();
+        expect(snap.minimumBid).toBeDefined();
+    });
+    it('fetches active + queued when contract pointers are set', async () => {
+        vi.mocked(fetchConfig).mockResolvedValue({ data: makeConfig(), address: 'CFG' });
+        vi.mocked(fetchContract).mockResolvedValue({
+            data: makeContract({ activeRental: ACTIVE_ADDR, queuedRental: QUEUED_ADDR }),
+            address: CONTRACT_ADDR,
+        });
+        vi.mocked(fetchRental).mockImplementation(async (addr) => ({
+            data: makeRental(),
+            address: addr,
+        }));
+        const snap = await getContractSnapshot({ contractAddress: CONTRACT_ADDR });
+        expect(snap.activeRental?.address).toBe(ACTIVE_ADDR);
+        expect(snap.queuedRental?.address).toBe(QUEUED_ADDR);
+        expect(fetchRental).toHaveBeenCalledTimes(2);
+    });
+    it('returns null when pointer is set but fetchRental throws (stale pointer)', async () => {
+        vi.mocked(fetchConfig).mockResolvedValue({ data: makeConfig(), address: 'CFG' });
+        vi.mocked(fetchContract).mockResolvedValue({
+            data: makeContract({ activeRental: ACTIVE_ADDR }),
+            address: CONTRACT_ADDR,
+        });
+        vi.mocked(fetchRental).mockRejectedValue(new Error('not found'));
+        const snap = await getContractSnapshot({ contractAddress: CONTRACT_ADDR });
+        expect(snap.activeRental).toBeNull();
+        expect(snap.queuedRental).toBeNull();
+    });
+});
+describe('computeMinimumBidFromSnapshot', () => {
+    const buildSnap = (parts) => ({
+        config: { data: makeConfig(), address: 'CFG' },
+        contract: {
+            data: makeContract({
+                rate: parts.rate ?? 100000000n,
+                activeRental: parts.activeStart !== undefined ? ACTIVE_ADDR : SYSTEM,
+                queuedRental: parts.queuedBidAtlas !== undefined || parts.queuedBidPoints !== undefined
+                    ? QUEUED_ADDR
+                    : SYSTEM,
+            }),
+            address: CONTRACT_ADDR,
+        },
+        activeRental: parts.activeStart !== undefined
+            ? {
+                data: makeRental({
+                    startTime: parts.activeStart,
+                    endTime: parts.activeEnd ?? parts.activeStart + 86400n,
+                }),
+                address: ACTIVE_ADDR,
+            }
+            : null,
+        queuedRental: parts.queuedBidAtlas !== undefined || parts.queuedBidPoints !== undefined
+            ? {
+                data: makeRental({
+                    bidAtlas: parts.queuedBidAtlas ?? 0n,
+                    bidPoints: parts.queuedBidPoints ?? 0n,
+                }),
+                address: QUEUED_ADDR,
+            }
+            : null,
+    });
+    it('no defender → floor = rate × captureRate cap', async () => {
+        const snap = buildSnap({ rate: 100000000n });
+        const bid = computeMinimumBidFromSnapshot(snap);
+        expect(bid.defenderBidStardust).toBe(0n);
+        // rate * captureRateBps / baseBps = 100M * 10500 / 10000 = 105M
+        expect(bid.minBidStardust).toBe(105000000n);
+        expect(bid.closenessFraction).toBe(0);
+    });
+    it('defender ATLAS bid raises floor above rate when bid > rate', async () => {
+        const snap = buildSnap({ rate: 100000000n, queuedBidAtlas: 200000000n });
+        const bid = computeMinimumBidFromSnapshot(snap);
+        expect(bid.defenderBidStardust).toBe(200000000n);
+        // base = max(rate, defender) = 200M, ramp at closeness=0 capped to 10500/10000 = 1.05x
+        expect(bid.minBidStardust).toBe(210000000n);
+    });
+    it('closeness ramps from 1× to maxMult as active rental nears end', async () => {
+        const now = 1_000_000;
+        const start = BigInt(now - 50);
+        const end = BigInt(now + 50);
+        const snap = buildSnap({
+            rate: 100000000n,
+            queuedBidAtlas: 100000000n,
+            activeStart: start,
+            activeEnd: end,
+        });
+        const bid = computeMinimumBidFromSnapshot(snap, { nowSeconds: now });
+        // closeness = 50/100 = 0.5
+        expect(bid.closenessFraction).toBeCloseTo(0.5, 5);
+        // ramp_bps = 10000 + (465 - 100) * 5000 / 100 = 10000 + 18250 = 28250 → 2.825×
+        // floor = 100M * 28250 / 10000 = 282_500_000
+        expect(bid.minBidStardust).toBe(282500000n);
+    });
+    it('delaySeconds projects closeness forward without RPC', async () => {
+        const start = 1000000n;
+        const end = 1000100n;
+        const snap = buildSnap({
+            rate: 100000000n,
+            queuedBidAtlas: 100000000n,
+            activeStart: start,
+            activeEnd: end,
+        });
+        const now = computeMinimumBidFromSnapshot(snap, { nowSeconds: 1_000_000 });
+        const later = computeMinimumBidFromSnapshot(snap, { nowSeconds: 1_000_050 });
+        expect(now.closenessFraction).toBe(0);
+        expect(later.closenessFraction).toBeCloseTo(0.5, 5);
+        expect(later.minBidStardust).toBeGreaterThan(now.minBidStardust);
+    });
+});
+describe('resolveContractSnapshot', () => {
+    it('fetches fresh when no snapshot provided', async () => {
+        vi.mocked(fetchConfig).mockResolvedValue({ data: makeConfig(), address: 'CFG' });
+        vi.mocked(fetchContract).mockResolvedValue({
+            data: makeContract(),
+            address: CONTRACT_ADDR,
+        });
+        await resolveContractSnapshot({ contractAddress: CONTRACT_ADDR });
+        expect(fetchContract).toHaveBeenCalledTimes(1);
+    });
+    it('returns provided snapshot as-is when address matches and no staleness', async () => {
+        vi.mocked(fetchConfig).mockResolvedValue({ data: makeConfig(), address: 'CFG' });
+        vi.mocked(fetchContract).mockResolvedValue({
+            data: makeContract(),
+            address: CONTRACT_ADDR,
+        });
+        const snap = await getContractSnapshot({ contractAddress: CONTRACT_ADDR });
+        vi.clearAllMocks();
+        const resolved = await resolveContractSnapshot({
+            contractAddress: CONTRACT_ADDR,
+            snapshot: snap,
+        });
+        expect(resolved).toBe(snap);
+        expect(fetchContract).not.toHaveBeenCalled();
+    });
+    it('throws when snapshot contract address does not match', async () => {
+        vi.mocked(fetchConfig).mockResolvedValue({ data: makeConfig(), address: VAULT_ADDR });
+        vi.mocked(fetchContract).mockResolvedValue({ data: makeContract(), address: OTHER_ADDR });
+        const snap = await getContractSnapshot({ contractAddress: OTHER_ADDR });
+        await expect(resolveContractSnapshot({ contractAddress: CONTRACT_ADDR, snapshot: snap })).rejects.toThrow(/snapshot is for contract/);
+    });
+    it('lazy-refetches when snapshot is stale (pointer set, rental null)', async () => {
+        // First fetch: pointer set but rental fetch fails → snap.activeRental = null (stale)
+        vi.mocked(fetchConfig).mockResolvedValue({ data: makeConfig(), address: 'CFG' });
+        vi.mocked(fetchContract).mockResolvedValue({
+            data: makeContract({ activeRental: ACTIVE_ADDR }),
+            address: CONTRACT_ADDR,
+        });
+        vi.mocked(fetchRental).mockRejectedValueOnce(new Error('not found'));
+        const staleSnap = await getContractSnapshot({ contractAddress: CONTRACT_ADDR });
+        expect(staleSnap.activeRental).toBeNull();
+        // Refetch succeeds — rental now loads
+        vi.mocked(fetchRental).mockResolvedValueOnce({
+            data: makeRental(),
+            address: ACTIVE_ADDR,
+        });
+        const resolved = await resolveContractSnapshot({
+            contractAddress: CONTRACT_ADDR,
+            snapshot: staleSnap,
+        });
+        expect(resolved.activeRental).not.toBeNull();
+        // resolve called fetchContract once more for refetch
+        expect(fetchContract).toHaveBeenCalledTimes(2);
+    });
+    it('throws when still stale after lazy refetch', async () => {
+        vi.mocked(fetchConfig).mockResolvedValue({ data: makeConfig(), address: 'CFG' });
+        vi.mocked(fetchContract).mockResolvedValue({
+            data: makeContract({ activeRental: ACTIVE_ADDR }),
+            address: CONTRACT_ADDR,
+        });
+        vi.mocked(fetchRental).mockRejectedValue(new Error('not found'));
+        const staleSnap = await getContractSnapshot({ contractAddress: CONTRACT_ADDR });
+        await expect(resolveContractSnapshot({ contractAddress: CONTRACT_ADDR, snapshot: staleSnap })).rejects.toThrow(/could not be loaded after lazy refetch/);
+    });
+});
+//# sourceMappingURL=contractSnapshot.test.js.map