@temporalabs/treasury 0.1.0

package/dist/position.d.ts

@@ -0,0 +1,142 @@
+import { type Address } from "viem";
+import { type VaultEntry } from "./registry-schema.js";
+import type { ReadClient } from "./client.js";
+/** The value `entryBasisUsdc` / `accruedYieldUsdc` carry when the event scan failed outright: not a number. */
+export declare const UNKNOWN_AFTER_SCAN_FAILURE = "unknown \u2014 event scan failed; see scan.note";
+/**
+ * What `entryBasisUsdc` / `accruedYieldUsdc` carry when the scan read events but did NOT cover this
+ * position's history: shares in − shares out does not reconcile to the balance, so the deposits that
+ * produced these shares are outside the window. Reporting the partial sums there renders a position
+ * whose deposit was missed as 100% yield (measured in review: 10.011996 USDC of
+ * "accrued yield" on a 10 USDC position). A bound nobody can see the bounds of is not a number.
+ */
+export declare const UNKNOWN_INCOMPLETE_SCAN = "unknown \u2014 the scan did not cover this position's history; see scan.note";
+export interface Position {
+    vault: string;
+    principal: Address;
+    /** Shares held, exact, in share units — pass this string back to earn_prepare_withdraw({ all }) unchanged. */
+    sharesExact: string;
+    shares: string;
+    /** What the shares redeem for now (convertToAssets). 🔴 This is what the position is WORTH, not what
+     * can be taken out — see `exit`. */
+    usdcValue: string;
+    /**
+     * What a withdrawal would actually pay RIGHT NOW, measured by simulating it rather than by reading
+     * the vault's own view. `maxWithdraw()` answers what a holder is ENTITLED to, not what the vault can
+     * pay: measured on a live Fusion vault at block 51327076, it reported the full 14.999970
+     * USDC position while 1.498874 already reverted — the exit was capped at the vault's 1.498873 USDC
+     * idle balance, to the unit.
+     */
+    exit: {
+        /** The largest amount this simulation found payable now, or `"unknown"` when neither attempt resolved. */
+        exitableNow: string;
+        /** What that number is: the whole position, the vault's liquid balance, or neither. */
+        measuredAs: "full position" | "vault's liquid balance" | "nothing to withdraw" | "refused, size unknown" | "not measured";
+        /** The vault's own balance of the asset — what it can pay without unwinding, on a chassis that pays from it. */
+        instantLiquidity: string;
+        /** `maxWithdraw()`, reported because callers see it elsewhere — never as the verdict. */
+        maxWithdrawSays: string;
+        note: string;
+    };
+    /** Σ deposited − Σ withdrawn for this owner, from the vault's Deposit/Withdraw events over the scanned window — or `UNKNOWN_AFTER_SCAN_FAILURE` when no events could be read at all. */
+    entryBasisUsdc: string;
+    /** usdcValue − entryBasis. Negative means withdrawals exceeded deposits inside the window, or the window missed deposits — or `UNKNOWN_AFTER_SCAN_FAILURE`. */
+    accruedYieldUsdc: string;
+    sharePriceInAssets: string;
+    /**
+     * `source` names which RPC served the event scan, never its URL: `"logs rpc"` (the configured one)
+     * or `"fallback"` (the endpoint `TREASURY_LOGS_FALLBACK` names, Base's public one by default, used
+     * when the configured one could not cover the range). 🔴 `complete` is only a RECONCILIATION and is
+     * vacuously true for an empty window — `wholeHistory` is the coverage claim, and the note is written
+     * from it.
+     */
+    scan: {
+        fromBlock: string;
+        toBlock: string;
+        deposits: number;
+        withdrawals: number;
+        /**
+         * The Deposit transactions this scan actually saw, oldest first — `txHash` is what an explorer
+         * link needs. Derived from the logs the scan already fetched to compute `entryBasisUsdc`; no
+         * extra request is made for them. Bounded by `MAX_SCAN_TXS`: when `deposits` exceeds the array's
+         * length, the list is the most recent that many and the COUNT is the total.
+         * 🔴 These are the events inside the SCANNED WINDOW. They are the whole history only when
+         * `wholeHistory` is true — the same caveat that makes `entryBasisUsdc` unknown otherwise.
+         */
+        depositTxs: ScanTx[];
+        /** The Withdraw transactions this scan saw, on the same terms as `depositTxs`. */
+        withdrawTxs: ScanTx[];
+        complete: boolean;
+        capped: boolean;
+        providerWindow?: string;
+        source: "logs rpc" | "fallback";
+        /** `fromBlock` is at or before the vault's deployment block AND the scan reconciles: only then is this the WHOLE history. */
+        wholeHistory: boolean;
+        note: string;
+    };
+    measuredAtBlock: number;
+}
+export interface PositionArgs {
+    vault: VaultEntry;
+    principal: Address;
+    client: ReadClient;
+    /**
+     * How far back to try to scan for events. Default: from the vault's `deployedAtBlock` (the whole
+     * history), or 2,000,000 blocks (~46 days on Base at 2s) for a row that does not record it. The
+     * EFFECTIVE window is bounded by `maxLogRequests × the provider's per-request cap`: 100 × 10 = 1,000
+     * blocks on Alchemy's free tier, 100 × 2,000 = 200,000 (~4.6 days) on Base's public RPC. A vault
+     * older than that needs a provider with a wide eth_getLogs range for a complete history.
+     * The result's `scan` block says what was actually covered; `complete` is the reconciliation test.
+     */
+    lookbackBlocks?: bigint;
+    /**
+     * Cap on eth_getLogs requests per scan. RPC providers cap the block range per request (measured:
+     * Alchemy free tier 10 blocks, Base public RPC 2,000), so a long lookback is walked in chunks and
+     * may not reach `lookbackBlocks` — the result says how far it got. Default 100 (per event).
+     */
+    maxLogRequests?: number;
+    /**
+     * A second read client for the event scan, used only when `client` cannot cover the range: its
+     * eth_getLogs error is one no window can be sized from (measured 2026-09-14: publicnode refuses any
+     * range older than ~2,000 blocks with "Archive requests require a personal token"), or its window
+     * would need more than `maxLogRequests` requests (Alchemy free tier: 10 blocks). The server passes
+     * Base's public endpoint, whose 2,000-block window serves history. Omitted ⇒ no fallback.
+     */
+    fallbackClient?: ReadClient;
+    /**
+     * Wall-clock budget for the event walk, milliseconds (default 30,000). A provider-sized walk over a
+     * long range is unbounded in time — measured at 40 s on the public endpoint, longer under 429s — and
+     * a tool that never returns is worse than one that returns a bounded answer. On expiry the walk stops
+     * where it is and the result is `capped`, with the budget named in the note.
+     */
+    budgetMs?: number;
+    /** Wall-clock budget for the two exit simulations, milliseconds (default 12,000). Separate from the scan's. */
+    exitBudgetMs?: number;
+    /** Clock, for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Parses the provider's stated maximum range out of its error, e.g. "limited to a 2,000 range" /
+ * "up to a 10 block range". `undefined` means the failure is NOT a window refusal — a caller must
+ * rethrow rather than narrow, or a dead provider and an empty result become the same answer.
+ * Exported for `tests/access.ts`, which walks a different contract's logs and needs the same
+ * distinction; NOT re-exported from index.ts.
+ */
+export declare function rangeLimitFromError(e: unknown): bigint | undefined;
+/** One Deposit or Withdraw, as an operator needs it to reach a block explorer. */
+export interface ScanTx {
+    /** `null` only for a log the provider returned without one — never for a log from a mined range. */
+    txHash: `0x${string}` | null;
+    blockNumber: string | null;
+    /** The event's `assets`, formatted in the vault's asset units, e.g. `"10 USDC"`. */
+    amountUsdc: string;
+}
+/**
+ * How many transactions each of `scan.depositTxs` / `scan.withdrawTxs` carries at most. The COUNTS
+ * (`scan.deposits` / `scan.withdrawals`) stay the totals, so a truncated list is always detectable
+ * by comparing the two. A cap exists because this list is the only part of the response that grows
+ * with an account's history: an allocator depositing hourly reaches four figures in a year, and a
+ * tool response that large is a different failure from the one this field was added to fix.
+ */
+export declare const MAX_SCAN_TXS = 100;
+export declare function getPosition(args: PositionArgs): Promise<Position>;

package/dist/position.js

@@ -0,0 +1,354 @@
+import { BaseError, ContractFunctionRevertedError, ExecutionRevertedError, parseAbiItem } from "viem";
+import { erc4626Abi } from "./abi/erc4626.js";
+import { describeError } from "./redact.js";
+import { formatAmount } from "./units.js";
+/** ERC-4626's own events — the only durable record of what an account put in and took out. */
+const depositEvent = parseAbiItem("event Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares)");
+const withdrawEvent = parseAbiItem("event Withdraw(address indexed sender, address indexed receiver, address indexed owner, uint256 assets, uint256 shares)");
+/** The value `entryBasisUsdc` / `accruedYieldUsdc` carry when the event scan failed outright: not a number. */
+export const UNKNOWN_AFTER_SCAN_FAILURE = "unknown — event scan failed; see scan.note";
+/**
+ * What `entryBasisUsdc` / `accruedYieldUsdc` carry when the scan read events but did NOT cover this
+ * position's history: shares in − shares out does not reconcile to the balance, so the deposits that
+ * produced these shares are outside the window. Reporting the partial sums there renders a position
+ * whose deposit was missed as 100% yield (measured in review: 10.011996 USDC of
+ * "accrued yield" on a 10 USDC position). A bound nobody can see the bounds of is not a number.
+ */
+export const UNKNOWN_INCOMPLETE_SCAN = "unknown — the scan did not cover this position's history; see scan.note";
+/**
+ * Parses the provider's stated maximum range out of its error, e.g. "limited to a 2,000 range" /
+ * "up to a 10 block range". `undefined` means the failure is NOT a window refusal — a caller must
+ * rethrow rather than narrow, or a dead provider and an empty result become the same answer.
+ * Exported for `tests/access.ts`, which walks a different contract's logs and needs the same
+ * distinction; NOT re-exported from index.ts.
+ */
+export function rangeLimitFromError(e) {
+    const m = String(e).replace(/,/g, "").match(/(?:limited to a|up to a)\s+(\d+)\s*(?:block)?\s*range/i);
+    return m ? BigInt(m[1]) : undefined;
+}
+async function scanLogs(client, address, event, owner, from, to, maxRequests, refuseIfCapped, deadline, now) {
+    const argsFilter = { owner };
+    try {
+        const logs = await client.getLogs({ address, event, args: argsFilter, fromBlock: from, toBlock: to });
+        return { logs, coveredFrom: from, requests: 1, capped: false };
+    }
+    catch (e) {
+        const window = rangeLimitFromError(e);
+        if (!window)
+            throw e;
+        // Decide BEFORE walking whether the walk can finish. A walk that would stop short spends
+        // `maxRequests` calls to produce a bound; when a fallback exists, hand it the range instead.
+        const needed = (to - from + window) / window;
+        if (refuseIfCapped && needed > BigInt(maxRequests))
+            throw new WindowTooNarrow(window, needed);
+        // Walk backwards from `to` in provider-sized windows until the lookback is covered or the cap is hit.
+        const out = [];
+        let hi = to;
+        let requests = 0;
+        while (hi >= from && requests < maxRequests && now() < deadline) {
+            const lo = hi - window + 1n > from ? hi - window + 1n : from;
+            const chunk = await client.getLogs({ address, event, args: argsFilter, fromBlock: lo, toBlock: hi });
+            out.push(...chunk);
+            requests += 1;
+            hi = lo - 1n;
+        }
+        return { logs: out, coveredFrom: hi + 1n, requests, capped: hi >= from, window };
+    }
+}
+/** The provider's window would need more requests than allowed to cover the range. */
+class WindowTooNarrow extends Error {
+    window;
+    needed;
+    constructor(window, needed) {
+        super(`the provider's ${window}-block eth_getLogs window needs ${needed} requests for this range`);
+        this.window = window;
+        this.needed = needed;
+    }
+}
+/**
+ * How many transactions each of `scan.depositTxs` / `scan.withdrawTxs` carries at most. The COUNTS
+ * (`scan.deposits` / `scan.withdrawals`) stay the totals, so a truncated list is always detectable
+ * by comparing the two. A cap exists because this list is the only part of the response that grows
+ * with an account's history: an allocator depositing hourly reaches four figures in a year, and a
+ * tool response that large is a different failure from the one this field was added to fix.
+ */
+export const MAX_SCAN_TXS = 100;
+/**
+ * 🔴 SORT, DO NOT TRUST THE ORDER THE WALK PRODUCED — it is path-dependent. The single-request path
+ * returns the provider's own ascending order, while the chunked fallback walks BACKWARDS from
+ * `toBlock` and pushes each chunk, so its array is descending by chunk and ascending inside one.
+ * Both paths feed this function, and the sums above are order-independent so nothing else in this
+ * file ever noticed. A list of transactions handed to a human is the first consumer that does.
+ */
+function txsOf(logs, decimals, symbol) {
+    const key = (l) => [l.blockNumber ?? -1n, l.logIndex ?? -1];
+    const sorted = [...logs].sort((a, b) => {
+        const [ab, ai] = key(a);
+        const [bb, bi] = key(b);
+        return ab === bb ? ai - bi : ab < bb ? -1 : 1;
+    });
+    return sorted.slice(-MAX_SCAN_TXS).map((l) => ({
+        txHash: l.transactionHash,
+        blockNumber: l.blockNumber === null ? null : l.blockNumber.toString(),
+        amountUsdc: `${formatAmount(l.args.assets ?? 0n, decimals)} ${symbol}`,
+    }));
+}
+/**
+ * Did the CHAIN refuse this, or did the RPC fail to ask it? Every failure used to read as "cannot pay",
+ * so one HTTP 502 on the first simulation reported a fully-exitable position as unexitable AND blamed
+ * the vault for it (measured through a proxy that failed exactly one call: one attempt made, the vault
+ * never asked, `exitableNow: "unknown"`, note "the refusal is the vault's").
+ * viem's own error chain separates them: a real revert carries a ContractFunctionRevertedError or an
+ * ExecutionRevertedError; a transport failure does not.
+ */
+function isRevert(e) {
+    return e instanceof BaseError && e.walk((x) => x instanceof ContractFunctionRevertedError || x instanceof ExecutionRevertedError) !== null;
+}
+/**
+ * At most two simulated withdrawals — the whole position, then the vault's own liquid balance — and the
+ * answer is whichever the chain accepts. Simulation rather than arithmetic because the ceiling is
+ * chassis-specific: a Fusion vault with no instant-withdrawal fuses pays only from its own balance,
+ * while a Morpho V2 vault holds almost none and still pays, out of the markets beneath it. Reading
+ * either `maxWithdraw()` or the liquid balance alone gets one of those two wrong.
+ *
+ * Nothing here is reported as the vault's answer unless the vault answered.
+ */
+async function measureExit(a) {
+    const { vault, principal, client, shares, value } = a;
+    const fmt = (x) => `${formatAmount(x, vault.asset.decimals)} ${vault.asset.symbol}`;
+    // An empty account needs no reads at all — `earn_balance` is the most-called tool.
+    if (shares === 0n) {
+        return { exitableNow: fmt(0n), measuredAs: "nothing to withdraw", instantLiquidity: "not read", maxWithdrawSays: "not read", note: "the account holds no shares." };
+    }
+    const read = async (fn) => {
+        try {
+            return { value: await fn(), failed: undefined };
+        }
+        catch (e) {
+            return { failed: isRevert(e) ? "revert" : "rpc" };
+        }
+    };
+    const [liquidRead, maxRead] = await Promise.all([
+        read(() => client.readContract({ address: vault.asset.address, abi: erc4626Abi, functionName: "balanceOf", args: [vault.address] })),
+        read(() => client.readContract({ address: vault.address, abi: erc4626Abi, functionName: "maxWithdraw", args: [principal] })),
+    ]);
+    const liquid = liquidRead.value;
+    const liquidText = liquid === undefined ? (liquidRead.failed === "revert" ? "reverted" : "unavailable — the RPC call failed") : fmt(liquid);
+    const maxText = maxRead.value === undefined ? (maxRead.failed === "revert" ? "reverted" : "unavailable — the RPC call failed") : fmt(maxRead.value);
+    // Only worth saying when the vault actually answered with a number bigger than what can be paid.
+    const advisory = maxRead.value !== undefined && maxRead.value > 0n ? ` maxWithdraw() says ${maxText}; that is an entitlement, not an amount the vault can pay.` : "";
+    // Shares worth nothing at this share price: a known zero, not a refusal.
+    if (value === 0n) {
+        return {
+            exitableNow: fmt(0n),
+            measuredAs: "nothing to withdraw",
+            instantLiquidity: liquidText,
+            maxWithdrawSays: maxText,
+            note: `the account holds ${formatAmount(shares, vault.shareDecimals)} ${vault.symbol}, which converts to nothing at this share price. No withdrawal was simulated.`,
+        };
+    }
+    const attempt = async (assets) => {
+        if (assets === 0n)
+            return "refused";
+        if (a.now() >= a.deadline)
+            return "unresolved";
+        try {
+            await client.simulateContract({ address: vault.address, abi: erc4626Abi, functionName: "withdraw", args: [assets, principal, principal], account: principal });
+            return "paid";
+        }
+        catch (e) {
+            return isRevert(e) ? "refused" : "unresolved";
+        }
+    };
+    const unresolved = (what) => ({
+        exitableNow: "unknown",
+        measuredAs: "not measured",
+        instantLiquidity: liquidText,
+        maxWithdrawSays: maxText,
+        note: `${what} — this is a failure to ASK the vault, not an answer from it: no conclusion should be drawn about what can be withdrawn.${advisory}`,
+    });
+    const full = await attempt(value);
+    if (full === "paid") {
+        return { exitableNow: fmt(value), measuredAs: "full position", instantLiquidity: liquidText, maxWithdrawSays: maxText, note: `a withdrawal of the whole position simulates OK at this block.${advisory}` };
+    }
+    if (full === "unresolved")
+        return unresolved("the simulation of a full-position withdrawal did not complete");
+    // The vault refused the full amount. Probe the liquid bound whenever there is one — including when it
+    // is at or above the position, where the refusal has some other cause and the probe is still the
+    // cheapest thing that can tell us so.
+    if (liquid === undefined)
+        return unresolved("the vault refused a full-position withdrawal and the vault's liquid balance could not be read");
+    // When `liquid >= value` the bound IS the position, so this re-asks the same question. Keep it
+    // anyway: the two calls are separate requests against "latest", so a second can genuinely
+    // succeed where the first reverted — a cooldown clearing, a rate limiter resetting, a new block. What
+    // must NOT happen is describing it as something it was not: the note says what was
+    // asked, and a success is believed whatever bound produced it.
+    const boundedByLiquid = liquid < value;
+    const askedFor = boundedByLiquid ? liquid : value;
+    const bounded = await attempt(askedFor);
+    if (bounded === "paid" && boundedByLiquid) {
+        return {
+            exitableNow: fmt(liquid),
+            measuredAs: "vault's liquid balance",
+            instantLiquidity: liquidText,
+            maxWithdrawSays: maxText,
+            note: `the whole position does NOT come out at this block: this chassis pays withdrawals from the vault's own balance, and the rest is deployed. ${fmt(liquid)} of ${fmt(value)} is payable now; the remainder needs the fund to unwind first.${advisory}`,
+        };
+    }
+    // 🔴 A success is a success whatever bound produced it. The old gate reused the ATTEMPT condition as
+    // the TRUST condition, so a second probe that paid was silently discarded and the result then claimed
+    // both were refused — false, and reproduced live (liquid 5, value 1, first revert, second paid,
+    // reported as "refused, size unknown").
+    if (bounded === "paid") {
+        return { exitableNow: fmt(value), measuredAs: "full position", instantLiquidity: liquidText, maxWithdrawSays: maxText, note: `a withdrawal of the whole position simulates OK at this block — the first attempt was refused and an identical retry succeeded, which two separate calls against the chain's latest state can legitimately do.${advisory}` };
+    }
+    if (bounded === "unresolved")
+        return unresolved("the vault refused a full-position withdrawal and the second simulation did not complete");
+    return {
+        exitableNow: "unknown",
+        measuredAs: "refused, size unknown",
+        instantLiquidity: liquidText,
+        maxWithdrawSays: maxText,
+        // Say what was ASKED. When the liquid balance is at or above the position, the second attempt was
+        // the same amount as the first, and describing it as "bounded by the liquid balance" names a
+        // withdrawal nobody simulated.
+        note: `the vault REFUSED ${boundedByLiquid ? `a full-position withdrawal and one bounded by its liquid balance (${liquidText})` : `a full-position withdrawal, twice — its liquid balance (${liquidText}) is at or above the position, so there was no smaller bound to try`} at this block. Both refusals came from the vault, so this is its answer — but it is not a shortfall this client could size.${advisory}`,
+    };
+}
+export async function getPosition(args) {
+    const { vault, principal, client } = args;
+    const lookback = args.lookbackBlocks ?? 2000000n;
+    const oneShare = 10n ** BigInt(vault.shareDecimals);
+    const [block, shares, oneShareInAssets] = await Promise.all([
+        client.getBlockNumber(),
+        client.readContract({ address: vault.address, abi: erc4626Abi, functionName: "balanceOf", args: [principal] }),
+        client.readContract({ address: vault.address, abi: erc4626Abi, functionName: "convertToAssets", args: [oneShare] }),
+    ]);
+    const value = shares === 0n
+        ? 0n
+        : await client.readContract({ address: vault.address, abi: erc4626Abi, functionName: "convertToAssets", args: [shares] });
+    const now = args.now ?? Date.now;
+    // 🔴 The exit's clock, and the scan's, must not overlap. An earlier revision gave the exit its own 12 s but left
+    // the scan's deadline computed HERE, before the exit ran — so the exit still spent the scan's wall
+    // clock and the comment claiming otherwise was false (four zero-config runs: exit "not measured" and the
+    // scan cut short at 42,000 of 108,533 blocks, four for four). The scan's deadline is taken AFTER the
+    // exit returns, below.
+    const exitDeadline = now() + (args.exitBudgetMs ?? 12_000);
+    const exit = await measureExit({ vault, principal, client, shares, value, deadline: exitDeadline, now });
+    const deadline = now() + (args.budgetMs ?? 30_000);
+    // The scan starts at the vault's deployment block when the registry records it: a position has no
+    // history before its vault existed, so that range is the whole history. An explicit lookback still
+    // narrows it (never widens it past deployment).
+    const deployed = vault.deployedAtBlock === undefined ? undefined : BigInt(vault.deployedAtBlock);
+    const byLookback = block > lookback ? block - lookback : 0n;
+    const wanted = deployed === undefined ? byLookback : args.lookbackBlocks === undefined ? deployed : byLookback > deployed ? byLookback : deployed;
+    const maxReq = args.maxLogRequests ?? 100;
+    const fallback = args.fallbackClient;
+    // One scan = deposits then withdrawals, SEQUENTIALLY: two concurrent walks double the request rate
+    // against a provider that is already the thing rate-limiting us.
+    const scanBoth = async (c, refuseIfCapped) => {
+        const d = await scanLogs(c, vault.address, depositEvent, principal, wanted, block, maxReq, refuseIfCapped, deadline, now);
+        const w = await scanLogs(c, vault.address, withdrawEvent, principal, wanted, block, maxReq, refuseIfCapped, deadline, now);
+        return [d, w];
+    };
+    // Primary first. It hands over to the fallback on exactly two conditions, both decided by the
+    // provider's own answer: an eth_getLogs error no window can be sized from, or a window too narrow to
+    // finish inside `maxReq`. Anything else a primary returns is its answer.
+    // A provider whose eth_getLogs error wording matches neither phrasing `rangeLimitFromError` knows
+    // makes scanLogs re-throw. That must degrade the way a capped scan does — an empty, incomplete
+    // window with the reason in the note — not fail the whole position read.
+    let scanFailure;
+    let source = "logs rpc";
+    let handover;
+    const empty = { logs: [], coveredFrom: block, capped: true, window: undefined };
+    let result;
+    try {
+        result = await scanBoth(client, fallback !== undefined);
+    }
+    catch (primaryError) {
+        if (!fallback) {
+            scanFailure = describeError(primaryError);
+            result = [empty, empty];
+        }
+        else {
+            handover = primaryError instanceof WindowTooNarrow ? primaryError.message : `eth_getLogs failed: ${describeError(primaryError, 120)}`;
+            try {
+                result = await scanBoth(fallback, false);
+                // 🔴 Set ONLY once the fallback has RESOLVED. Setting it at handover made a both-failed scan
+                // report a source for data nothing served.
+                source = "fallback";
+            }
+            catch (fallbackError) {
+                scanFailure = `logs rpc: ${handover}; fallback: ${describeError(fallbackError)}`;
+                result = [empty, empty];
+            }
+        }
+    }
+    const [d, w] = result;
+    const deps = d.logs;
+    const wds = w.logs;
+    const fromBlock = d.coveredFrom > w.coveredFrom ? d.coveredFrom : w.coveredFrom;
+    const capped = d.capped || w.capped;
+    const timedOut = capped && now() >= deadline;
+    const providerWindow = d.window ?? w.window;
+    const depositedAssets = deps.reduce((n, l) => n + (l.args.assets ?? 0n), 0n);
+    const withdrawnAssets = wds.reduce((n, l) => n + (l.args.assets ?? 0n), 0n);
+    const depositedShares = deps.reduce((n, l) => n + (l.args.shares ?? 0n), 0n);
+    const withdrawnShares = wds.reduce((n, l) => n + (l.args.shares ?? 0n), 0n);
+    const basis = depositedAssets - withdrawnAssets;
+    // Completeness check the numbers themselves can make: if the shares in the window do not account
+    // for the shares held, the window missed history (or shares were transferred in/out).
+    const complete = depositedShares - withdrawnShares === shares;
+    // 🔴 `complete` alone is a RECONCILIATION, and it is vacuously true for an empty window on an
+    // account with no shares — or, with a short lookback, for a window that saw neither the deposits nor
+    // the withdrawals that cancel out. Whole history is a claim about COVERAGE: the scan reached the
+    // block the vault was deployed at, nothing was cut short, and the shares reconcile.
+    const wholeHistory = deployed !== undefined && fromBlock <= deployed && !capped && complete;
+    // 🔴 A LIFETIME FIGURE IS REPORTED ONLY WHEN THE SCAN COVERED THE LIFETIME. Basis and yield
+    // are sums over the account's whole history; a window that reconciles is not evidence it saw that
+    // history. Measured: a live wallet at lookback 83,000 reported the
+    // right basis ONLY because that window happened to catch all thirteen events — which the client
+    // cannot know. Every earlier formulation was a special case of this one: `!complete` (an exited
+    // account whose window saw the withdrawal but not the deposit printed a NEGATIVE basis),
+    // and the empty-window clause (an account that deposited and exited before the window printed a
+    // confident "0 USDC"). `!wholeHistory` subsumes both, including the honest zero.
+    const basisUnknown = !wholeHistory;
+    const fmtA = (x) => `${formatAmount(x, vault.asset.decimals)} ${vault.asset.symbol}`;
+    return {
+        vault: vault.symbol,
+        principal,
+        sharesExact: formatAmount(shares, vault.shareDecimals),
+        shares: `${formatAmount(shares, vault.shareDecimals)} ${vault.symbol}`,
+        usdcValue: fmtA(value),
+        exit,
+        // On a scan failure NOTHING was read, so basis and yield are unknown — never 0 and value−0, which
+        // would report the whole position as yield while the note says "unknown".
+        entryBasisUsdc: scanFailure ? UNKNOWN_AFTER_SCAN_FAILURE : basisUnknown ? UNKNOWN_INCOMPLETE_SCAN : fmtA(basis),
+        accruedYieldUsdc: scanFailure ? UNKNOWN_AFTER_SCAN_FAILURE : basisUnknown ? UNKNOWN_INCOMPLETE_SCAN : fmtA(value - basis),
+        sharePriceInAssets: `${formatAmount(oneShareInAssets, vault.asset.decimals)} ${vault.asset.symbol} per share`,
+        scan: {
+            fromBlock: fromBlock.toString(),
+            toBlock: block.toString(),
+            deposits: deps.length,
+            withdrawals: wds.length,
+            depositTxs: txsOf(deps, vault.asset.decimals, vault.asset.symbol),
+            withdrawTxs: txsOf(wds, vault.asset.decimals, vault.asset.symbol),
+            complete,
+            capped,
+            ...(providerWindow !== undefined ? { providerWindow: providerWindow.toString() } : {}),
+            source,
+            wholeHistory,
+            note: (handover && !scanFailure ? `the configured logs RPC could not cover this range (${handover}), so the fallback endpoint (TREASURY_LOGS_FALLBACK, Base's public endpoint by default) served the scan. ` : "") + (scanFailure
+                ? `event scan FAILED (${scanFailure}): the provider's eth_getLogs error was not one this client can size a window from, so no history was read — basis and yield are unknown, not zero. Set TREASURY_LOGS_RPC_BASE to a provider with a known window (Alchemy, Base public), or use the agent's own deposit receipts.`
+                : wholeHistory
+                    ? "the scan covered every block from the vault's deployment, and shares in − shares out reconciles to the balance: the basis covers this position's whole history"
+                    : capped
+                        ? `the scan was CUT SHORT — ${block - fromBlock + 1n} of the ${block - (deployed ?? 0n) + 1n} blocks since deployment, at the provider's ${providerWindow ?? "?"}-block eth_getLogs window and ${timedOut ? `a ${Math.round((args.budgetMs ?? 30_000) / 1000)}s time budget` : `${maxReq} requests`}; covering the rest needs about ${providerWindow ? (block - (deployed ?? 0n) + providerWindow) / providerWindow : BigInt(maxReq)} requests per event. ${complete ? "Shares in − shares out happens to reconcile over that window, which an empty window does vacuously — it is NOT evidence the history was covered." : "Basis and yield are unknown, not bounds."} Set TREASURY_LOGS_RPC_BASE to a provider with a wide eth_getLogs range${timedOut ? "" : ", raise max_log_requests"}, or use the agent's own deposit receipts.`
+                        : complete
+                            ? `shares in − shares out reconciles over the ${block - fromBlock + 1n} blocks scanned, but the scan started at block ${fromBlock}${deployed === undefined ? " and the registry does not record when this vault was deployed" : `, after the vault's deployment block ${deployed}`} — deposits and withdrawals before it cancel out unseen, so this is a WINDOW, NOT the whole history. Omit lookback_blocks to scan from deployment.`
+                            : "shares in − shares out ≠ balance: history predates the window or shares moved by transfer — basis and yield are unknown, not totals"),
+        },
+        measuredAtBlock: Number(block),
+    };
+}
+//# sourceMappingURL=position.js.map

package/dist/position.js.map

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

package/dist/preflight.d.ts

@@ -0,0 +1,62 @@
+import { type Address, type Hex } from "viem";
+import { type VaultEntry } from "./registry-schema.js";
+import type { ReadClient } from "./client.js";
+export type PreflightStatus = 
+/** Simulated deposit succeeds as-is: access open, allowance already sufficient. */
+"OPEN_READY"
+/** Simulated deposit reached the token pull and failed on allowance: access is OPEN; an approve is needed first. */
+ | "NEEDS_APPROVAL"
+/** Access-managed revert: the vault restricts `deposit` to a role the depositor lacks. */
+ | "WHITELIST_GATED"
+/** A definite revert this client cannot name. Candidates are listed; nothing is diagnosed. */
+ | "REVERTED_OTHER"
+/** The client refused before touching the chain (chassis, or registry/chain mismatch). */
+ | "REFUSED_BY_CLIENT"
+/** Transport failure. Not a verdict about the vault — an absence of evidence. */
+ | "UNRESOLVED";
+export interface RevertObservation {
+    selector?: Hex;
+    reason?: string;
+    raw?: Hex;
+}
+/**
+ * Names a cause only where the instrument discriminated; otherwise lists candidates.
+ * A revert is an answer. A transport error is not, and must never land here.
+ */
+export declare function classifyRevert(obs: RevertObservation): {
+    status: PreflightStatus;
+    note: string;
+};
+/** Pulls the revert payload out of viem's error chain. Returns undefined for anything that is not a definite revert. */
+export declare function extractRevert(err: unknown): RevertObservation | undefined;
+export interface PreflightResult {
+    vault: string;
+    depositor: Address;
+    status: PreflightStatus;
+    canDeposit: boolean;
+    /** Observations, in the order they were taken. Each is a sentence a human can act on. */
+    findings: string[];
+    balances?: {
+        asset: string;
+        shares: string;
+        allowance: string;
+    };
+    quotes?: {
+        sharePriceInAssets: string;
+        totalAssets: string;
+        previewShares?: string;
+    };
+    advisory?: {
+        maxDepositRaw: string;
+        note: string;
+    };
+    measuredAtBlock?: number;
+}
+export interface PreflightArgs {
+    vault: VaultEntry;
+    depositor: Address;
+    /** Optional. If omitted, one whole unit of the asset is simulated. */
+    assetsHuman?: string;
+    client: ReadClient;
+}
+export declare function preflightDeposit(args: PreflightArgs): Promise<PreflightResult>;