safehands-pharos 1.5.0 → 2.8.0

package/dist/lib/price/priceResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priceResolver.d.ts","sourceRoot":"","sources":["../../../src/lib/price/priceResolver.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,aAAa,EAEb,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAQjD,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAqDD,qBAAa,aAAa;IAKtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IALtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmD;gBAGzD,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,aAAa,CAAC,CAAC,EAChE,GAAG,GAAE,MAAM,MAAiB;IAG/C,UAAU,IAAI,IAAI;IAIZ,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAwC/F;;;OAGG;IACH,OAAO,CAAC,cAAc;YAwBR,SAAS;IAiGvB,OAAO,CAAC,OAAO;CAYhB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,eAExB,CAAC;AAEH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAExG"}

package/dist/lib/price/priceResolver.js

@@ -0,0 +1,246 @@
+// ─── PriceResolver ─────────────────────────────────────────────────────
+// Canonical USD price resolution: live oracle reads + validation + bounded
+// per-feed cache + structured error classification. Never fabricates prices;
+// never assumes stablecoins equal exactly 1 USD.
+//
+// Cache semantics:
+// - Fresh serve: entry younger than the TTL AND the oracle timestamp still
+//   within heartbeat → sourceStatus "ok", confidence "high".
+// - Degraded serve (RPC failed transiently): allowed ONLY after a previous
+//   successful oracle read, cache age <= 5 minutes, AND the oracle timestamp
+//   still within heartbeat → sourceStatus "rpc_degraded_cache",
+//   confidence "degraded". feedStale is never set just because a value came
+//   from cache — it means heartbeat violation only.
+// - Otherwise: structured PRICE_SOURCE_* failure with no price.
+// ────────────────────────────────────────────────────────────────────────
+import { formatUnits, BaseError, HttpRequestError, RpcRequestError, TimeoutError } from "viem";
+import { getActiveNetwork } from "../networks.js";
+import { CHAIN_ID } from "../constants.js";
+import { resolveFeedSymbol, pricedSymbolsForActiveNetwork } from "./feedRegistry.js";
+import { ChainlinkPushProvider } from "./chainlinkPushProvider.js";
+export const PRICE_CACHE_TTL_MS = 45_000; // fresh-serve window (mandated 30–60s)
+export const DEGRADED_CACHE_MAX_AGE_MS = 300_000; // hard bound for rpc_degraded_cache serves
+const MAX_FUTURE_SKEW_SECONDS = 300;
+function classifyPriceSourceError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const lower = message.toLowerCase();
+    // viem readContract failures arrive as ContractFunctionExecutionError wrapping
+    // the transport error; walk the chain, but also match the top-level message —
+    // the fallback transport can rewrap and viem embeds status text in `details`.
+    const walked = err instanceof BaseError
+        ? err.walk((e) => e instanceof HttpRequestError || e instanceof RpcRequestError || e instanceof TimeoutError)
+        : undefined;
+    const httpStatus = walked instanceof HttpRequestError ? walked.status : undefined;
+    const rpcCode = walked instanceof RpcRequestError ? walked.code : undefined;
+    const rateLimited = httpStatus === 429 ||
+        rpcCode === -32005 || // JSON-RPC "limit exceeded" (EIP-1474)
+        rpcCode === -32016 || // provider-specific throttle code
+        /\b429\b/.test(lower) ||
+        lower.includes("rate limit") ||
+        lower.includes("rate-limit") ||
+        lower.includes("too many requests") ||
+        lower.includes("compute unit") ||
+        lower.includes("cu limit") ||
+        lower.includes("capacity exceeded") ||
+        lower.includes("request limit") ||
+        lower.includes("quota");
+    if (rateLimited) {
+        return { code: "PRICE_SOURCE_RATE_LIMITED", retryable: true, message };
+    }
+    if (lower.includes("supra_provider_not_implemented")) {
+        return { code: "PRICE_SOURCE_UNAVAILABLE", retryable: false, message };
+    }
+    // Zero-data/revert at the feed address means a wrong or absent contract —
+    // a configuration problem, not a transient outage.
+    if (lower.includes("returned no data") || lower.includes("zero data") || lower.includes("reverted")) {
+        return { code: "PRICE_SOURCE_INVALID", retryable: false, message };
+    }
+    // Timeouts, aborts, network failures, 5xx → transient unavailability.
+    return { code: "PRICE_SOURCE_UNAVAILABLE", retryable: true, message };
+}
+export class PriceResolver {
+    providers;
+    now;
+    cache = new Map();
+    inflight = new Map();
+    constructor(providers, now = Date.now) {
+        this.providers = providers;
+        this.now = now;
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    async resolvePriceUsd(symbol, opts) {
+        const lookup = resolveFeedSymbol(symbol);
+        if (!lookup) {
+            const network = getActiveNetwork().name;
+            const configured = pricedSymbolsForActiveNetwork();
+            return {
+                ok: false,
+                error: {
+                    code: "PRICE_FEED_NOT_CONFIGURED",
+                    message: `${symbol} has no price feed configured for ${network} (${CHAIN_ID}). Configured symbols: ${configured.length > 0 ? configured.join(", ") : "none"}. No fallback price was fabricated.`,
+                    retryable: false,
+                    provider: "none",
+                },
+            };
+        }
+        const key = `${getActiveNetwork().name}:${lookup.feed.pair}`;
+        const ttlMs = opts?.cacheTtlMs ?? PRICE_CACHE_TTL_MS;
+        const fresh = this.serveFromCache(key, lookup, ttlMs, "ok");
+        if (fresh)
+            return { ok: true, resolution: fresh };
+        const inflight = this.inflight.get(key);
+        if (inflight) {
+            const shared = await inflight;
+            if (shared.ok) {
+                return { ok: true, resolution: { ...shared.resolution, token: lookup.requested } };
+            }
+            return shared;
+        }
+        const pending = this.fetchLive(key, lookup, opts).finally(() => {
+            this.inflight.delete(key);
+        });
+        this.inflight.set(key, pending);
+        return pending;
+    }
+    /**
+     * Serve a cached resolution if it is within maxAgeMs AND the original oracle
+     * timestamp is still within the feed heartbeat. Returns null otherwise.
+     */
+    serveFromCache(key, lookup, maxAgeMs, mode) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        const nowMs = this.now();
+        const cacheAgeMs = nowMs - entry.fetchedAtMs;
+        if (cacheAgeMs < 0 || cacheAgeMs > maxAgeMs)
+            return null;
+        const feedAgeSeconds = Math.max(0, Math.floor(nowMs / 1000) - entry.resolution.updatedAtUnix);
+        if (feedAgeSeconds > lookup.feed.heartbeatSeconds)
+            return null;
+        return {
+            ...entry.resolution,
+            token: lookup.requested,
+            cached: true,
+            cacheAgeSeconds: Math.floor(cacheAgeMs / 1000),
+            feedAgeSeconds,
+            sourceStatus: mode,
+            confidence: mode === "ok" ? "high" : "degraded",
+        };
+    }
+    async fetchLive(key, lookup, opts) {
+        const feed = lookup.feed;
+        const provider = this.providers[feed.provider];
+        if (!provider) {
+            return {
+                ok: false,
+                error: {
+                    code: "PRICE_SOURCE_UNAVAILABLE",
+                    message: `No ${feed.provider} provider is registered for ${feed.pair}.`,
+                    retryable: false,
+                    provider: feed.provider,
+                    pair: feed.pair,
+                },
+            };
+        }
+        try {
+            const quote = await provider.fetchQuote(feed);
+            const nowSec = Math.floor(this.now() / 1000);
+            if (quote.answer <= 0n) {
+                return this.invalid(feed, `latestAnswer ${quote.answer} is not a positive value`);
+            }
+            if (!Number.isFinite(quote.updatedAtUnix) ||
+                quote.updatedAtUnix <= 0 ||
+                quote.updatedAtUnix > nowSec + MAX_FUTURE_SKEW_SECONDS) {
+                return this.invalid(feed, `latestTimestamp ${quote.updatedAtUnix} is zero or implausible`);
+            }
+            const feedAgeSeconds = Math.max(0, nowSec - quote.updatedAtUnix);
+            if (feedAgeSeconds > feed.heartbeatSeconds) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "PRICE_SOURCE_STALE",
+                        message: `${feed.pair} feed is stale: feed age ${feedAgeSeconds}s exceeds heartbeat ${feed.heartbeatSeconds}s (feed ${feed.feedAddress}).`,
+                        retryable: true,
+                        provider: feed.provider,
+                        pair: feed.pair,
+                    },
+                };
+            }
+            const priceUsd = formatUnits(quote.answer, feed.decimals);
+            const priceUsdNumber = Number(priceUsd);
+            if (!Number.isFinite(priceUsdNumber) || priceUsdNumber <= 0) {
+                return this.invalid(feed, `latestAnswer did not decode to a finite positive price (${priceUsd})`);
+            }
+            const resolution = {
+                token: lookup.requested,
+                canonicalSymbol: lookup.canonical,
+                pair: feed.pair,
+                priceUsd,
+                priceUsdNumber,
+                provider: feed.provider,
+                source: provider.label,
+                sourceStatus: "ok",
+                confidence: "high",
+                timestamp: new Date(quote.updatedAtUnix * 1000).toISOString(),
+                updatedAtUnix: quote.updatedAtUnix,
+                feedAgeSeconds,
+                feedStale: false,
+                cached: false,
+                cacheAgeSeconds: null,
+                feedAddress: feed.feedAddress,
+                heartbeatSeconds: feed.heartbeatSeconds,
+                network: getActiveNetwork().name,
+                chainId: CHAIN_ID,
+            };
+            this.cache.set(key, { resolution, fetchedAtMs: this.now() });
+            return { ok: true, resolution };
+        }
+        catch (err) {
+            const classified = classifyPriceSourceError(err);
+            if (classified.retryable && opts?.allowDegradedCache !== false) {
+                const degraded = this.serveFromCache(key, lookup, DEGRADED_CACHE_MAX_AGE_MS, "rpc_degraded_cache");
+                if (degraded)
+                    return { ok: true, resolution: degraded };
+            }
+            return {
+                ok: false,
+                error: {
+                    code: classified.code,
+                    message: classified.message,
+                    retryable: classified.retryable,
+                    provider: feed.provider,
+                    pair: feed.pair,
+                },
+            };
+        }
+    }
+    invalid(feed, detail) {
+        return {
+            ok: false,
+            error: {
+                code: "PRICE_SOURCE_INVALID",
+                message: `${feed.pair} feed returned invalid data: ${detail} (feed ${feed.feedAddress}).`,
+                retryable: false,
+                provider: feed.provider,
+                pair: feed.pair,
+            },
+        };
+    }
+}
+/**
+ * Process-wide singleton wired to the live publicClient. Only implemented
+ * providers are registered — the Supra pull provider is a stub
+ * (src/lib/price/supraProvider.ts) and is deliberately NOT registered; a feed
+ * configured for "supra-pull" fails closed with a structured
+ * PRICE_SOURCE_UNAVAILABLE ("no provider registered") instead of advertising an
+ * unimplemented source.
+ */
+export const priceResolver = new PriceResolver({
+    "chainlink-push": new ChainlinkPushProvider(),
+});
+export function resolvePriceUsd(symbol, opts) {
+    return priceResolver.resolvePriceUsd(symbol, opts);
+}
+//# sourceMappingURL=priceResolver.js.map

package/dist/lib/price/priceResolver.js.map

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

package/dist/lib/price/supraProvider.d.ts

@@ -0,0 +1,9 @@
+import type { PriceFeedConfig, PriceProvider, ProviderQuote } from "./types.js";
+export declare const SUPRA_DORA_STORAGE_ADDRESS: "0x58e158c74DF7Ad6396C0dcbadc4878faC9e93d57";
+export declare const SUPRA_DORA_PULL_ADDRESS: "0x16f70cAD28dd621b0072B5A8a8c392970E87C3dD";
+export declare class SupraPullProvider implements PriceProvider {
+    readonly kind: "supra-pull";
+    readonly label = "Supra DORA pull oracle on Pharos (not yet enabled)";
+    fetchQuote(_feed: PriceFeedConfig): Promise<ProviderQuote>;
+}
+//# sourceMappingURL=supraProvider.d.ts.map

package/dist/lib/price/supraProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supraProvider.d.ts","sourceRoot":"","sources":["../../../src/lib/price/supraProvider.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhF,eAAO,MAAM,0BAA0B,EAAG,4CAAqD,CAAC;AAChG,eAAO,MAAM,uBAAuB,EAAG,4CAAqD,CAAC;AAE7F,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IACtC,QAAQ,CAAC,KAAK,wDAAwD;IAEhE,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;CAKjE"}

package/dist/lib/price/supraProvider.js

@@ -0,0 +1,17 @@
+// ─── Supra DORA Provider (placeholder) ─────────────────────────────────
+// Supra DORA Pull Oracle is deployed on Pharos, but exact feed IDs / pull
+// payload schema / timestamp semantics are not yet confirmed, so this provider
+// is intentionally a stub. The PriceResolver treats it as an unavailable
+// source; no price is ever fabricated.
+// ────────────────────────────────────────────────────────────────────────
+// Pacific Mainnet deployment (recorded for future Phase 2 wiring).
+export const SUPRA_DORA_STORAGE_ADDRESS = "0x58e158c74DF7Ad6396C0dcbadc4878faC9e93d57";
+export const SUPRA_DORA_PULL_ADDRESS = "0x16f70cAD28dd621b0072B5A8a8c392970E87C3dD";
+export class SupraPullProvider {
+    kind = "supra-pull";
+    label = "Supra DORA pull oracle on Pharos (not yet enabled)";
+    async fetchQuote(_feed) {
+        throw new Error("SUPRA_PROVIDER_NOT_IMPLEMENTED: Supra DORA pull provider is a stub until feed IDs and payload schema are confirmed.");
+    }
+}
+//# sourceMappingURL=supraProvider.js.map

package/dist/lib/price/supraProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supraProvider.js","sourceRoot":"","sources":["../../../src/lib/price/supraProvider.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,0EAA0E;AAC1E,+EAA+E;AAC/E,yEAAyE;AACzE,uCAAuC;AACvC,2EAA2E;AAI3E,mEAAmE;AACnE,MAAM,CAAC,MAAM,0BAA0B,GAAG,4CAAqD,CAAC;AAChG,MAAM,CAAC,MAAM,uBAAuB,GAAG,4CAAqD,CAAC;AAE7F,MAAM,OAAO,iBAAiB;IACnB,IAAI,GAAG,YAAqB,CAAC;IAC7B,KAAK,GAAG,oDAAoD,CAAC;IAEtE,KAAK,CAAC,UAAU,CAAC,KAAsB;QACrC,MAAM,IAAI,KAAK,CACb,qHAAqH,CACtH,CAAC;IACJ,CAAC;CACF"}

package/dist/lib/price/types.d.ts

@@ -0,0 +1,67 @@
+import type { Abi } from "viem";
+export type PriceFeedProviderKind = "chainlink-push" | "supra-pull";
+export type PriceErrorCode = "PRICE_SOURCE_UNAVAILABLE" | "PRICE_SOURCE_STALE" | "PRICE_SOURCE_INVALID" | "PRICE_SOURCE_RATE_LIMITED" | "PRICE_FEED_NOT_CONFIGURED";
+export interface PriceFeedConfig {
+    pair: string;
+    base: string;
+    quote: "USD";
+    feedAddress: `0x${string}`;
+    decimals: number;
+    heartbeatSeconds: number;
+    provider: PriceFeedProviderKind;
+    docsSource: string;
+}
+export interface ProviderQuote {
+    answer: bigint;
+    updatedAtUnix: number;
+}
+/** Minimal read surface so providers are testable without the global viem client. */
+export interface ContractReader {
+    readContract(args: {
+        address: `0x${string}`;
+        abi: Abi;
+        functionName: string;
+    }): Promise<unknown>;
+}
+export interface PriceProvider {
+    readonly kind: PriceFeedProviderKind;
+    readonly label: string;
+    /** Fetch one raw quote for one feed. May throw raw errors; the resolver classifies them. */
+    fetchQuote(feed: PriceFeedConfig): Promise<ProviderQuote>;
+}
+export interface PriceResolution {
+    token: string;
+    canonicalSymbol: string;
+    pair: string;
+    priceUsd: string;
+    priceUsdNumber: number;
+    provider: PriceFeedProviderKind;
+    source: string;
+    sourceStatus: "ok" | "rpc_degraded_cache";
+    confidence: "high" | "degraded";
+    timestamp: string;
+    updatedAtUnix: number;
+    feedAgeSeconds: number;
+    feedStale: boolean;
+    cached: boolean;
+    cacheAgeSeconds: number | null;
+    feedAddress: `0x${string}`;
+    heartbeatSeconds: number;
+    network: string;
+    chainId: number;
+}
+export interface PriceResolverFailure {
+    code: PriceErrorCode;
+    message: string;
+    retryable: boolean;
+    provider: PriceFeedProviderKind | "none";
+    pair?: string;
+}
+export type PriceResolverResult = {
+    ok: true;
+    resolution: PriceResolution;
+} | {
+    ok: false;
+    error: PriceResolverFailure;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/price/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/price/types.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAEhC,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,YAAY,CAAC;AAEpE,MAAM,MAAM,cAAc,GACtB,0BAA0B,GAC1B,oBAAoB,GACpB,sBAAsB,GACtB,2BAA2B,GAC3B,2BAA2B,CAAC;AAEhC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,IAAI,EAAE;QACjB,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;QACvB,GAAG,EAAE,GAAG,CAAC;QACT,YAAY,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,UAAU,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IAGf,YAAY,EAAE,IAAI,GAAG,oBAAoB,CAAC;IAC1C,UAAU,EAAE,MAAM,GAAG,UAAU,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IAIvB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAAC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,eAAe,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,oBAAoB,CAAA;CAAE,CAAC"}

package/dist/lib/price/types.js

@@ -0,0 +1,7 @@
+// ─── Price Oracle Types ────────────────────────────────────────────────
+// Contracts for the provider-based PriceResolver. Price oracle/valuation is
+// separate from swap routing (DODO/FaroSwap stays route/execution-quote only).
+// No I/O in this module.
+// ────────────────────────────────────────────────────────────────────────
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/price/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/price/types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,+EAA+E;AAC/E,yBAAyB;AACzB,2EAA2E"}

package/dist/lib/productionGuards.d.ts

@@ -0,0 +1,16 @@
+export interface PostureIssue {
+    level: "warn" | "fatal";
+    code: string;
+    message: string;
+}
+/**
+ * Evaluate the production posture. Pure (reads env only, no side effects) so it is
+ * unit-testable. Returns [] outside production. The caller logs/throws.
+ */
+export declare function evaluateProductionPosture(env?: NodeJS.ProcessEnv): PostureIssue[];
+/**
+ * Apply the posture at server startup: log every issue, then throw if any are fatal.
+ * Warnings never block boot; fatals refuse to start (fail-fast).
+ */
+export declare function assertProductionPosture(): void;
+//# sourceMappingURL=productionGuards.d.ts.map

package/dist/lib/productionGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"productionGuards.d.ts","sourceRoot":"","sources":["../../src/lib/productionGuards.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,EAAE,CA4E9F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAY9C"}

package/dist/lib/productionGuards.js

@@ -0,0 +1,93 @@
+// ─── Production posture guards ─────────────────────────────────────────────
+// Lightweight startup checks that fail-fast (fatal) or warn on unsafe public-
+// hosting configuration. Active only when NODE_ENV=production, evaluated once at
+// server boot. These NEVER remove capability — they protect the Mainnet Production
+// Profile's zero-custody posture and durable state. Every check has an explicit
+// override so intentional self-hosted setups are never blocked silently.
+// ───────────────────────────────────────────────────────────────────────────
+import { safeHandsStateDir } from "./persistentJsonStore.js";
+/**
+ * Evaluate the production posture. Pure (reads env only, no side effects) so it is
+ * unit-testable. Returns [] outside production. The caller logs/throws.
+ */
+export function evaluateProductionPosture(env = process.env) {
+    const issues = [];
+    if (env.NODE_ENV !== "production")
+        return issues;
+    // 1) FATAL — custody landmine: managed execution enabled on a public host.
+    const managed = env.WALLET_MODE === "managed-mainnet";
+    const writeOn = env.WRITE_TOOLS_ENABLED === "true";
+    const allowManagedPublic = env.SAFEHANDS_ALLOW_MANAGED_ON_PUBLIC === "true";
+    if (managed && writeOn && !allowManagedPublic) {
+        issues.push({
+            level: "fatal",
+            code: "MANAGED_EXECUTION_ON_PUBLIC",
+            message: "Refusing to start: WALLET_MODE=managed-mainnet + WRITE_TOOLS_ENABLED=true in production puts a signing key on the host (custody). The public zero-custody profile requires WALLET_MODE=none + WRITE_TOOLS_ENABLED=false. For an intentional self-hosted single-tenant deployment, set SAFEHANDS_ALLOW_MANAGED_ON_PUBLIC=true.",
+        });
+    }
+    // 1b) FATAL — custody landmine: local x402 facilitator key in production.
+    // The standalone x402 server (`npm run start:x402`) signs settlements with
+    // X402_FACILITATOR_PRIVATE_KEY — a hot key on the host. The zero-custody
+    // production path is the Guardian API `/paid/*` gate with an EXTERNAL
+    // facilitator (X402_PAY_TO + X402_FACILITATOR_URL) and no local key.
+    const localFacilitatorKey = Boolean(env.X402_FACILITATOR_PRIVATE_KEY);
+    const allowLocalFacilitator = env.SAFEHANDS_ALLOW_LOCAL_FACILITATOR === "true";
+    if (localFacilitatorKey && !allowLocalFacilitator) {
+        issues.push({
+            level: "fatal",
+            code: "LOCAL_FACILITATOR_KEY_IN_PRODUCTION",
+            message: "Refusing to start: X402_FACILITATOR_PRIVATE_KEY is set in production: the local x402 facilitator signs settlements with a hot key on the host (custody). The zero-custody profile serves paid endpoints through the Guardian API /paid/* gate with an external facilitator (X402_PAY_TO + X402_FACILITATOR_URL) and no local key. For an intentional dev/self-hosted single-tenant deployment, set SAFEHANDS_ALLOW_LOCAL_FACILITATOR=true.",
+        });
+    }
+    // 2) WARN — ephemeral state dir → durability loss on restart.
+    const stateDirSet = Boolean(env.SAFEHANDS_STATE_DIR || env.STATE_DIR);
+    const dir = env.SAFEHANDS_STATE_DIR || env.STATE_DIR || safeHandsStateDir();
+    const looksEphemeral = !stateDirSet || dir === ".safehands" || dir === "." || dir.startsWith("./") || dir.startsWith(".safehands");
+    if (looksEphemeral) {
+        issues.push({
+            level: "warn",
+            code: "EPHEMERAL_STATE_DIR",
+            message: `SAFEHANDS_STATE_DIR resolves to "${dir}"; on an ephemeral host (e.g. Railway without a Volume) prepared transactions, the attestation queue, and the audit trail are LOST on restart. Mount a persistent Volume and set SAFEHANDS_STATE_DIR to its path (e.g. /data).`,
+        });
+    }
+    // 3) WARN — x402 enabled + replay required but Upstash Redis not configured.
+    // x402 counts as configured for EITHER profile: the zero-custody API gate
+    // (X402_FACILITATOR_URL) or the standalone local facilitator (private key).
+    const x402Configured = Boolean(env.X402_PAY_TO && (env.X402_FACILITATOR_URL || env.X402_FACILITATOR_PRIVATE_KEY));
+    const replayRequired = env.SAFEHANDS_X402_REPLAY_REDIS_REQUIRED === "true";
+    const upstash = Boolean((env.UPSTASH_REDIS_REST_URL || env.SAFEHANDS_REDIS_REST_URL) &&
+        (env.UPSTASH_REDIS_REST_TOKEN || env.SAFEHANDS_REDIS_REST_TOKEN));
+    if (x402Configured && replayRequired && !upstash) {
+        issues.push({
+            level: "warn",
+            code: "X402_REPLAY_REDIS_MISSING",
+            message: "x402 is configured and SAFEHANDS_X402_REPLAY_REDIS_REQUIRED=true, but Upstash Redis env (UPSTASH_REDIS_REST_URL/TOKEN) is missing. x402 replay protection will fail closed at runtime. Provision Upstash Redis or unset SAFEHANDS_X402_REPLAY_REDIS_REQUIRED.",
+        });
+    }
+    // 4) WARN — CORS wildcard in production (advisory; fine for the public read tier).
+    const cors = env.SAFEHANDS_CORS_ORIGIN || env.CORS_ORIGIN || env.SAFEHANDS_ALLOWED_ORIGINS;
+    if (!cors || cors === "*") {
+        issues.push({
+            level: "warn",
+            code: "CORS_WILDCARD",
+            message: "CORS is wildcard (*) in production. Acceptable for the public read tier, but tighten CORS_ORIGIN / SAFEHANDS_CORS_ORIGIN for guarded/paid surfaces.",
+        });
+    }
+    return issues;
+}
+/**
+ * Apply the posture at server startup: log every issue, then throw if any are fatal.
+ * Warnings never block boot; fatals refuse to start (fail-fast).
+ */
+export function assertProductionPosture() {
+    const issues = evaluateProductionPosture();
+    for (const i of issues) {
+        const tag = i.level === "fatal" ? "❌ FATAL" : "⚠️  WARNING";
+        console.error(`${tag} [SafeHands posture · ${i.code}] ${i.message}`);
+    }
+    const fatal = issues.filter((i) => i.level === "fatal");
+    if (fatal.length > 0) {
+        throw new Error(`SafeHands refused to start: ${fatal.length} fatal production-posture issue(s); see logs above. This protects the zero-custody Mainnet Production Profile.`);
+    }
+}
+//# sourceMappingURL=productionGuards.js.map

package/dist/lib/productionGuards.js.map

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

package/dist/lib/recipientSafety.d.ts

@@ -0,0 +1,5 @@
+/** Parse the operator-supplied denylist from env (comma-separated). Empty by default. */
+export declare function recipientDenylist(): Set<string>;
+/** True when the address is a valid EVM address present on the operator denylist. */
+export declare function isDenylistedRecipient(address?: string | null): boolean;
+//# sourceMappingURL=recipientSafety.d.ts.map

package/dist/lib/recipientSafety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipientSafety.d.ts","sourceRoot":"","sources":["../../src/lib/recipientSafety.ts"],"names":[],"mappings":"AAeA,yFAAyF;AACzF,wBAAgB,iBAAiB,IAAI,GAAG,CAAC,MAAM,CAAC,CAQ/C;AAED,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGtE"}

package/dist/lib/recipientSafety.js

@@ -0,0 +1,28 @@
+// ─── Recipient safety — operator-configurable denylist ─────────────────────
+// A sync, keyless, honest guard for the RECIPIENT of a value transfer/approval.
+// The denylist is entirely operator-supplied via env (empty by default) — SafeHands
+// ships NO fabricated scam list, so there is never false "scam protection" confidence.
+// Operators point it at their own known-bad set (drainers, scam addresses, mistyped
+// treasury addresses to hard-block, etc.).
+//
+// NOTE (honest scope): deeper recipient intelligence — address-poisoning detection
+// and first-time-recipient warnings — requires the sender's transfer history, which
+// is too RPC-heavy for the hot path without the Goldsky indexer. That is deferred to
+// the indexer-backed path rather than added as a laggy hot-path scan.
+// ───────────────────────────────────────────────────────────────────────────
+import { isAddress } from "viem";
+/** Parse the operator-supplied denylist from env (comma-separated). Empty by default. */
+export function recipientDenylist() {
+    const raw = process.env.SAFEHANDS_RECIPIENT_DENYLIST || "";
+    return new Set(raw
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => isAddress(s)));
+}
+/** True when the address is a valid EVM address present on the operator denylist. */
+export function isDenylistedRecipient(address) {
+    if (!address || !isAddress(address))
+        return false;
+    return recipientDenylist().has(address.toLowerCase());
+}
+//# sourceMappingURL=recipientSafety.js.map

package/dist/lib/recipientSafety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipientSafety.js","sourceRoot":"","sources":["../../src/lib/recipientSafety.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,oFAAoF;AACpF,uFAAuF;AACvF,oFAAoF;AACpF,2CAA2C;AAC3C,EAAE;AACF,mFAAmF;AACnF,oFAAoF;AACpF,qFAAqF;AACrF,sEAAsE;AACtE,8EAA8E;AAE9E,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEjC,yFAAyF;AACzF,MAAM,UAAU,iBAAiB;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,EAAE,CAAC;IAC3D,OAAO,IAAI,GAAG,CACZ,GAAG;SACA,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAC/B,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,OAAO,iBAAiB,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AACxD,CAAC"}

package/dist/lib/riskEngine.d.ts

@@ -10,10 +10,29 @@ export type RiskRecommendation = "proceed" | "caution" | "block";
 export interface RiskAssessment {
     riskScore: number;
     riskLevel: RiskLevel;
+    /**
+     * ADVISORY only — never gates execution. The actionPolicyEngine is the sole
+     * ALLOW/BLOCK decider on write paths (docs/DECISION_CONTRACT.md); this field
+     * exists for reports and the on-chain assessment record.
+     */
     recommendation: RiskRecommendation;
     breakdown: RiskBreakdown;
     reasons: string[];
     suggestion: string;
+    /**
+     * True when a CRITICAL risk signal could not be evaluated (route/liquidity or
+     * balance fetch failed). Callers must fail-closed on this — never silently
+     * proceed on degraded data. Market-condition gaps are non-critical and do
+     * NOT set this.
+     */
+    degraded: boolean;
+    degradedReasons: string[];
+    /**
+     * Structural (not transient): the swap liquidity provider is not configured/
+     * verified for the active chain (SWAP_LIQUIDITY_NOT_CONFIGURED). Liquidity and
+     * slippage dimensions were scored fail-closed without live route data.
+     */
+    swapProviderNotConfigured?: boolean;
 }
 export interface RiskInput {
     action: "swap" | "transfer";

package/dist/lib/riskEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"riskEngine.d.ts","sourceRoot":"","sources":["../../src/lib/riskEngine.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAC/D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,EAAE,kBAAkB,CAAC;IACnC,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AA+QD,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAoD1E"}
+{"version":3,"file":"riskEngine.d.ts","sourceRoot":"","sources":["../../src/lib/riskEngine.ts"],"names":[],"mappings":"AAoCA,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAC/D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB;;;;OAIG;IACH,cAAc,EAAE,kBAAkB,CAAC;IACnC,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAwTD,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAuF1E"}