@crewhaus/tool-defi 0.7.0

package/dist/lib/quotes.js

@@ -0,0 +1,370 @@
+/**
+ * Offchain prices from two unauthenticated public providers, with the
+ * provenance that makes a number checkable.
+ *
+ * Two origins, both constants, neither of which takes a credential:
+ *
+ *   - **Frankfurter** republishes the ECB's daily euro reference rates. One
+ *     fixing per TARGET business day at about 16:00 CET — so a weekend, a
+ *     Christmas Day, or "today before the fixing" all resolve BACK to an
+ *     earlier date, and the response says which. That returned date is the
+ *     `asOf`, and it is the whole reason a reconciliation run reproduces.
+ *   - **Coinbase's** `/v2/prices/{pair}/spot`, for crypto and for fiat pairs
+ *     the ECB does not publish.
+ *
+ * **Coinbase's spot response carries no timestamp.** Not a stale one, none at
+ * all: `{ "data": { "base", "currency", "amount" } }` is the whole document.
+ * The survey sketch that proposed this tool assumed every provider had a
+ * timestamp field to stamp `asOf` from; this one does not, and the honest
+ * answer is `asOf: null` with `asOfSource: "none"` rather than the time the
+ * response arrived. Stamping arrival time would make every reading look fresh
+ * by construction, which is the exact failure the sketch was trying to avoid.
+ *
+ * It also means **a historical crypto quote is refused here**, rather than
+ * served from a spot endpoint that echoes no date: a price that cannot be
+ * distinguished from today's must not be labelled as last Tuesday's. The
+ * refusal names the alternatives — a Chainlink round read at a pinned block,
+ * or pricing the asset in a fiat pair the ECB does publish.
+ *
+ * Every price carries where it came from and how it was derived: a direct
+ * quote, an inversion of the pair the provider actually publishes, or a cross
+ * through an intermediate asset — and a cross names the intermediate and
+ * carries both legs' provenance with it.
+ */
+import { KNOWN_CURRENCIES } from "@crewhaus/tool-math";
+import { divide, fixedFromJson, fromInteger, isPositive, multiply, toDecimalString, } from "./decimal";
+import { DefiError, getJson } from "./rpc";
+/** The two origins this package reads prices from. There is no third, and no override. */
+export const PROVIDER_ORIGINS = Object.freeze({
+    frankfurter: "https://api.frankfurter.app",
+    coinbase: "https://api.coinbase.com",
+});
+export const PROVIDER_NAMES = Object.freeze([
+    "frankfurter",
+    "coinbase",
+]);
+const ALLOWED_ORIGINS = new Set(Object.values(PROVIDER_ORIGINS));
+/** An asset symbol, as a provider spells it. Deliberately narrow: it goes into a path. */
+const SYMBOL = /^[A-Za-z0-9]{2,12}$/;
+/** ISO 8601 calendar date, which is the only `at` either provider understands. */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Inversion and cross division are carried to this many places.
+ *
+ * 1/3 has no exact decimal expansion, so an inverted quote is rounded exactly
+ * once, here, with the mode named in the result. Eighteen places is more than
+ * any provider publishes and matches the widest token decimalisation, so the
+ * rounding is below the noise of the input rather than above it.
+ */
+export const INVERSION_SCALE = 18;
+export function normalizeSymbol(raw, what) {
+    const text = raw.trim().toUpperCase();
+    if (!SYMBOL.test(text)) {
+        throw new DefiError(`${what}: "${raw}" is not an asset symbol (2 to 12 letters or digits)`);
+    }
+    return text;
+}
+function normalizeAt(raw) {
+    if (raw === undefined)
+        return undefined;
+    const text = raw.trim();
+    if (!ISO_DATE.test(text)) {
+        throw new DefiError(`at: "${raw}" is not an ISO calendar date (YYYY-MM-DD) — these providers publish by date, not by instant`);
+    }
+    return text;
+}
+/**
+ * Whether a code is a currency this monorepo knows.
+ *
+ * The table is `@crewhaus/tool-math`'s, through its public surface, rather than
+ * a second ISO 4217 list in this package that would drift from it.
+ */
+export function isFiat(code) {
+    return KNOWN_CURRENCIES.includes(code);
+}
+/** Which providers to try, and in what order, for a pair nobody named providers for. */
+export function defaultProviders(base, quote) {
+    // The ECB fixing is the reference rate a finance team reconciles against, so
+    // it goes first when it can answer at all; it publishes fiat only.
+    return isFiat(base) && isFiat(quote) ? ["frankfurter", "coinbase"] : ["coinbase"];
+}
+function assertKnownOrigin(url) {
+    if (!ALLOWED_ORIGINS.has(url.origin)) {
+        throw new DefiError(`refusing to dial "${url.origin}" — this package reads prices from ${[...ALLOWED_ORIGINS].join(" and ")} only`);
+    }
+}
+const FRANKFURTER_CONVENTION = "ECB daily euro reference rate, fixed at about 16:00 CET on a TARGET business day; a request for a non-business day resolves back to the previous fixing and the date field says which one";
+const COINBASE_CONVENTION = "Coinbase's current spot price for the pair; the endpoint publishes no timestamp, so this price has no asOf of its own";
+/** Ask Frankfurter for `base -> quote`, directly. It has no inverse problem: from/to are parameters. */
+async function frankfurterLeg(base, quote, at, options) {
+    if (!isFiat(base) || !isFiat(quote)) {
+        return {
+            ok: false,
+            reason: `frankfurter publishes ECB reference rates for currencies; ${isFiat(base) ? quote : base} is not one`,
+        };
+    }
+    if (base === quote) {
+        return { ok: false, reason: "a pair of one currency with itself is not a quote" };
+    }
+    const url = new URL(`${at ?? "latest"}?from=${base}&to=${quote}`, `${PROVIDER_ORIGINS.frankfurter}/`);
+    assertKnownOrigin(url);
+    const outcome = await getJson(url.toString(), options);
+    if (!outcome.ok)
+        return { ok: false, reason: `frankfurter: ${outcome.message}` };
+    const body = outcome.value;
+    if (typeof body !== "object" || body === null) {
+        return { ok: false, reason: "frankfurter answered something other than an object" };
+    }
+    const rates = body.rates;
+    if (typeof rates !== "object" || rates === null) {
+        return { ok: false, reason: "frankfurter's answer carried no rates object" };
+    }
+    const raw = rates[quote];
+    if (raw === undefined) {
+        return { ok: false, reason: `frankfurter does not publish a rate for ${base}/${quote}` };
+    }
+    const date = typeof body.date === "string" ? body.date : null;
+    if (date === null) {
+        // Without the fixing date there is no provenance, and an ECB rate without
+        // its date is exactly the number a reconciliation cannot reproduce.
+        return {
+            ok: false,
+            reason: "frankfurter's answer carried no date, so the fixing it used is unknown",
+        };
+    }
+    let price;
+    let literal;
+    try {
+        const parsed = fixedFromJson(raw, `the ${base}/${quote} rate`);
+        price = parsed.value;
+        literal = parsed.kind;
+    }
+    catch (err) {
+        return { ok: false, reason: `frankfurter: ${err.message}` };
+    }
+    if (!isPositive(price)) {
+        return {
+            ok: false,
+            reason: `frankfurter answered ${toDecimalString(price)} for ${base}/${quote}`,
+        };
+    }
+    return {
+        ok: true,
+        value: price,
+        leg: {
+            source: "frankfurter",
+            endpoint: PROVIDER_ORIGINS.frankfurter,
+            pair: `${base}/${quote}`,
+            derivation: "direct",
+            price: toDecimalString(price),
+            asOf: date,
+            asOfSource: "frankfurter.date",
+            convention: FRANKFURTER_CONVENTION,
+            literal,
+            requestedAt: at ?? null,
+        },
+    };
+}
+/** Ask Coinbase for a spot price, trying the inverse pair when the direct one is not published. */
+async function coinbaseLeg(base, quote, at, options) {
+    if (at !== undefined) {
+        return {
+            ok: false,
+            reason: "coinbase's spot endpoint publishes no date and echoes none back, so a historical answer from it cannot be told apart from today's — read a Chainlink round at a pinned block with OraclePriceRead, or quote the asset against a currency the ECB publishes",
+        };
+    }
+    if (base === quote) {
+        return { ok: false, reason: "a pair of one asset with itself is not a quote" };
+    }
+    const direct = await coinbaseSpot(base, quote, options);
+    if (direct.ok) {
+        return {
+            ok: true,
+            value: direct.price,
+            leg: {
+                source: "coinbase",
+                endpoint: PROVIDER_ORIGINS.coinbase,
+                pair: `${base}-${quote}`,
+                derivation: "direct",
+                price: toDecimalString(direct.price),
+                asOf: null,
+                asOfSource: "none",
+                convention: COINBASE_CONVENTION,
+                literal: direct.literal,
+                requestedAt: null,
+            },
+        };
+    }
+    const inverse = await coinbaseSpot(quote, base, options);
+    if (!inverse.ok) {
+        return {
+            ok: false,
+            reason: `coinbase publishes neither ${base}-${quote} (${direct.reason}) nor its inverse`,
+        };
+    }
+    if (!isPositive(inverse.price)) {
+        return {
+            ok: false,
+            reason: `coinbase answered ${toDecimalString(inverse.price)} for ${quote}-${base}`,
+        };
+    }
+    const inverted = divide(fromInteger(1n), inverse.price, INVERSION_SCALE, "halfEven");
+    return {
+        ok: true,
+        value: inverted,
+        leg: {
+            source: "coinbase",
+            endpoint: PROVIDER_ORIGINS.coinbase,
+            pair: `${quote}-${base}`,
+            derivation: "inverted",
+            price: toDecimalString(inverted),
+            asOf: null,
+            asOfSource: "none",
+            convention: `${COINBASE_CONVENTION}; this figure is 1 divided by the published ${quote}-${base} price of ${toDecimalString(inverse.price)}, rounded half-even to ${INVERSION_SCALE} places`,
+            literal: inverse.literal,
+            requestedAt: null,
+        },
+    };
+}
+async function coinbaseSpot(base, quote, options) {
+    const url = new URL(`/v2/prices/${base}-${quote}/spot`, PROVIDER_ORIGINS.coinbase);
+    assertKnownOrigin(url);
+    const outcome = await getJson(url.toString(), options);
+    if (!outcome.ok)
+        return { ok: false, reason: outcome.message };
+    const body = outcome.value;
+    const data = body?.data;
+    if (typeof data !== "object" || data === null) {
+        return { ok: false, reason: "coinbase's answer carried no data object" };
+    }
+    if (typeof data.currency === "string" && data.currency.toUpperCase() !== quote) {
+        // A quote currency that is not the one asked for is a wrong answer, not a
+        // near miss: the number would be right for some other pair.
+        return {
+            ok: false,
+            reason: `coinbase answered in ${data.currency} for a ${base}-${quote} request`,
+        };
+    }
+    try {
+        const parsed = fixedFromJson(data.amount, `the ${base}-${quote} spot price`);
+        if (!isPositive(parsed.value)) {
+            return {
+                ok: false,
+                reason: `coinbase answered ${toDecimalString(parsed.value)} for ${base}-${quote}`,
+            };
+        }
+        return { ok: true, price: parsed.value, literal: parsed.kind };
+    }
+    catch (err) {
+        return { ok: false, reason: err.message };
+    }
+}
+async function tryProviders(providers, base, quote, at, options, attempts) {
+    for (const provider of providers) {
+        const outcome = provider === "frankfurter"
+            ? await frankfurterLeg(base, quote, at, options)
+            : await coinbaseLeg(base, quote, at, options);
+        if (outcome.ok)
+            return outcome;
+        attempts.push(`${provider} could not quote ${base}/${quote}: ${outcome.reason}`);
+    }
+    return { ok: false, reason: attempts.join("; ") };
+}
+/** The intermediates a cross tries when the caller names none. */
+export const DEFAULT_CROSS_VIA = Object.freeze(["USD", "EUR"]);
+/**
+ * Price one asset in another, direct if a provider publishes it, inverted if
+ * one publishes the other direction, crossed through an intermediate if
+ * neither — and say which of the three happened, every time.
+ */
+export async function quotePrice(request, options = {}) {
+    const base = normalizeSymbol(request.base, "base");
+    const quote = normalizeSymbol(request.quote, "quote");
+    const at = normalizeAt(request.at);
+    if (base === quote) {
+        throw new DefiError(`base and quote are both "${base}" — a pair of an asset with itself has no price`);
+    }
+    const providers = request.providers ?? defaultProviders(base, quote);
+    if (providers.length === 0)
+        throw new DefiError("providers was empty, so there is nothing to ask");
+    const attempts = [];
+    const direct = await tryProviders(providers, base, quote, at, options, attempts);
+    if (direct.ok) {
+        return {
+            value: direct.value,
+            quote: {
+                base,
+                quote,
+                price: toDecimalString(direct.value),
+                derivation: direct.leg.derivation,
+                via: null,
+                legs: [direct.leg],
+                asOf: direct.leg.asOf,
+                notes: direct.leg.asOf === null ? [untimestampedNote(direct.leg.source)] : [],
+            },
+        };
+    }
+    if (request.allowCross === false) {
+        throw new DefiError(`no configured provider publishes ${base}/${quote} and crossing was not allowed: ${attempts.join("; ")}`);
+    }
+    const candidates = request.via === undefined ? DEFAULT_CROSS_VIA : [normalizeSymbol(request.via, "via")];
+    for (const raw of candidates) {
+        const via = normalizeSymbol(raw, "via");
+        if (via === base || via === quote)
+            continue;
+        // An explicit provider order applies to the LEGS too. A caller who named
+        // one provider did not ask for a price composed out of a different one.
+        const firstProviders = request.providers ?? defaultProviders(base, via);
+        const secondProviders = request.providers ?? defaultProviders(via, quote);
+        const first = await tryProviders(firstProviders, base, via, at, options, attempts);
+        if (!first.ok)
+            continue;
+        const second = await tryProviders(secondProviders, via, quote, at, options, attempts);
+        if (!second.ok)
+            continue;
+        // Exact: the legs' scales add, and nothing is rounded until a caller asks
+        // for a number of places.
+        const value = multiply(first.value, second.value);
+        const legs = [first.leg, second.leg];
+        const asOf = compositeAsOf(legs);
+        const notes = [
+            `crossed through ${via}: ${base}/${via} from ${first.leg.source}, ${via}/${quote} from ${second.leg.source}`,
+        ];
+        if (asOf === null)
+            notes.push(compositeUntimestampedNote(legs));
+        else if (legs.some((leg) => leg.asOf !== asOf)) {
+            notes.push(`the legs carry different dates (${legs.map((l) => l.asOf ?? "none").join(", ")}); the older one is reported`);
+        }
+        return {
+            value,
+            quote: {
+                base,
+                quote,
+                price: toDecimalString(value),
+                derivation: "cross",
+                via,
+                legs,
+                asOf,
+                notes,
+            },
+        };
+    }
+    throw new DefiError(`could not price ${base}/${quote} directly or through ${candidates.join(" or ")}: ${attempts.join("; ")}`);
+}
+function untimestampedNote(source) {
+    return `${source} publishes no timestamp with this price, so asOf is null rather than the time the response arrived`;
+}
+function compositeUntimestampedNote(legs) {
+    const without = legs.filter((leg) => leg.asOf === null).map((leg) => leg.source);
+    return `no asOf: ${[...new Set(without)].join(" and ")} publishes none, and a composite price is only as dated as its least dated leg`;
+}
+function compositeAsOf(legs) {
+    let oldest = null;
+    for (const leg of legs) {
+        if (leg.asOf === null)
+            return null;
+        if (oldest === null || leg.asOf < oldest)
+            oldest = leg.asOf;
+    }
+    return oldest;
+}

package/dist/lib/rpc.d.ts

@@ -0,0 +1,171 @@
+import { CrewhausError } from "@crewhaus/errors";
+/** A refusal this package chose: a missing endpoint, a bad shape, a write attempt. */
+export declare class DefiError extends CrewhausError {
+    readonly name = "DefiError";
+    constructor(message: string);
+}
+/** A pinned oracle feed, so a caller can name "eth-usd" instead of an address. */
+export type FeedPin = {
+    readonly chainId: string;
+    readonly kind: "chainlink" | "pyth";
+    readonly address: string;
+    /** Pyth's per-feed id. Required for a Pyth pin, meaningless for Chainlink. */
+    readonly priceId?: string;
+    /**
+     * The feed's published heartbeat, in seconds. Optional because a heartbeat
+     * is a property of the feed's deployment and is not readable from the
+     * aggregator — a tool that guessed one would be inventing the threshold it
+     * then judges against.
+     */
+    readonly heartbeatSeconds?: number;
+};
+export type DefiConfig = {
+    /** chain id -> JSON-RPC endpoint. */
+    readonly endpoints: ReadonlyMap<string, string>;
+    /** chain id -> Multicall3 deployment, when it is not at the canonical address. */
+    readonly multicall: ReadonlyMap<string, string>;
+    /** feed name -> pin. */
+    readonly feeds: ReadonlyMap<string, FeedPin>;
+};
+export type DefiConfigInput = {
+    readonly rpc?: Record<string, string>;
+    readonly multicall3?: Record<string, string>;
+    readonly feeds?: Record<string, Record<string, unknown>>;
+};
+export declare function buildDefiConfig(input: DefiConfigInput): DefiConfig;
+/** Replace the process-global config. Generated daemons call this at boot. */
+export declare function registerDefiConfig(input: DefiConfigInput): void;
+export declare function getDefiConfig(): DefiConfig;
+/**
+ * The config ONE call runs under: the serving candidate's `tool_config.defi`
+ * block when it declares one, else the boot registration. A non-object
+ * override is ignored rather than merged — an endpoint table only ever comes
+ * from a spec block or from boot.
+ */
+export declare function resolveDefiConfig(override: unknown): DefiConfig;
+/** Test-only — back to an empty, fail-closed table. */
+export declare function _resetDefiConfig(): void;
+/**
+ * The only form an endpoint takes in a message or a result: scheme, host and
+ * port, never the path.
+ *
+ * Provider RPC URLs carry the API key in the PATH — `/v2/<key>` at one vendor,
+ * `/<key>` at another. Printing the endpoint in a refusal, a provenance field
+ * or a caveat would put that key in a model's context and then in a transcript.
+ */
+export declare function endpointLabel(raw: string): string;
+/**
+ * Take the endpoint back out of a message this package did not write.
+ *
+ * Every failure here is assembled from `endpointLabel` — and then has somebody
+ * else's string concatenated onto it: the dialler's error, the node's own
+ * JSON-RPC message, an HTTP status line. Those are the one place the key can
+ * still get out, because a fetch implementation that reports "unable to
+ * connect to <url>" is quoting a URL whose PATH is the credential. One
+ * borrowed string undoes the labelling everywhere else, and it lands in a
+ * model's context and from there in a transcript.
+ *
+ * The path and the query are redacted as well as the whole URL, so a message
+ * that quotes only the tail is covered too.
+ */
+export declare function withoutEndpoint(message: string, endpoint: string): string;
+export declare function requireEndpoint(config: DefiConfig, chainId: string): string;
+export type DefiFetch = (req: Request) => Promise<Response>;
+/**
+ * Test-only injection point, the convention every networked package here
+ * follows. `undefined` restores the real dialler; a suite that sets it must
+ * restore it, or the next file in the same bun process inherits the stub.
+ */
+export declare function _setFetch(fn: DefiFetch | undefined): void;
+/** Epoch SECONDS, to match every onchain timestamp this package compares against. */
+export type Clock = () => number;
+/**
+ * Test-only clock. An oracle's age is the difference between two instants, and
+ * a test that took the second one from the wall clock would be asserting how
+ * fast the runner is. Every age in this package comes from here.
+ */
+export declare function _setClock(fn: Clock | undefined): void;
+export declare function nowSeconds(): number;
+export declare const DEFAULT_TIMEOUT_MS = 20000;
+export declare const MAX_TIMEOUT_MS = 120000;
+/** 16 MB. An `eth_getLogs` answer is not read here; an `eth_call` result is small. */
+export declare const MAX_RESPONSE_BYTES: number;
+/**
+ * The JSON-RPC methods this package may issue, narrower than the runtime's
+ * read-only set because this package reads state and prices and nothing else.
+ */
+export declare const DEFI_RPC_METHODS: ReadonlySet<string>;
+export type TransportFailure = {
+    readonly kind: "transport" | "status" | "rateLimited" | "malformed" | "rpcError" | "refused";
+    readonly message: string;
+    readonly status?: number;
+    /** The JSON-RPC error code, when the node answered with one. */
+    readonly code?: number;
+};
+export type RpcOutcome<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | ({
+    readonly ok: false;
+} & TransportFailure);
+export type RpcOptions = {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    /** Only for the refusal message when a method is off the allow-list. */
+    readonly chainId?: string;
+};
+/**
+ * Issue one JSON-RPC call.
+ *
+ * Failures are RETURNED rather than thrown, because the caller with the most
+ * at stake — `PortfolioValuation`, reading fifty assets — wants the asset that
+ * failed named in its unpriced bucket rather than losing the other forty-nine.
+ * A method outside the allow-list is the exception: that is a defect in this
+ * package and it throws.
+ */
+export declare function rpcCall<T = unknown>(endpoint: string, method: string, params: ReadonlyArray<unknown>, options?: RpcOptions): Promise<RpcOutcome<T>>;
+/**
+ * GET a JSON document, through the same seam and the same cap.
+ *
+ * The URL is never a caller's: `./quotes` builds it from one of two origin
+ * constants and re-checks the origin before dialling. Redirects are NOT
+ * followed — a price provider that 302s somewhere else is not a price
+ * provider, and following it is how an answer arrives from a host nobody
+ * configured.
+ */
+export declare function getJson(url: string, options?: RpcOptions & {
+    readonly accept?: string;
+}): Promise<RpcOutcome<unknown>>;
+/** `eth_call` at a named block, returning the raw 0x hex. */
+export declare function ethCall(endpoint: string, to: string, data: string, blockTag: string, options?: RpcOptions): Promise<RpcOutcome<string>>;
+/** The native-coin balance of an address, in wei, at a named block. */
+export declare function ethGetBalance(endpoint: string, address: string, blockTag: string, options?: RpcOptions): Promise<RpcOutcome<bigint>>;
+/** The head block number. */
+export declare function ethBlockNumber(endpoint: string, options?: RpcOptions): Promise<RpcOutcome<bigint>>;
+/**
+ * Turn a block number into the tag every read in one answer shares.
+ *
+ * A valuation assembled from reads at different heights is a number that never
+ * existed: balances from one block, a price from the next. Every tool here
+ * resolves ONE tag up front and passes it down.
+ */
+export declare function blockTagOf(blockNumber: bigint | undefined): string;
+export type Deadline = {
+    readonly signal: AbortSignal;
+    cancel(): void;
+};
+/**
+ * A deadline that also honours the runtime's own cancellation. Every call
+ * opens one and cancels it in a `finally` — a timer left running holds the
+ * process open past the answer.
+ */
+export declare function startDeadline(ms: number, outer?: AbortSignal): Deadline;
+/**
+ * Run `work` over `items` with at most `limit` in flight, preserving input
+ * order in the result. Order is preserved because the output is a TABLE, and a
+ * row order that depends on which read answered first is a diff that changes
+ * between two identical runs.
+ */
+export declare function mapPool<T, R>(items: readonly T[], limit: number, work: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/** Compact JSON — every byte returned is a byte in somebody's context window. */
+export declare const json: (value: unknown) => string;