safehands-pharos 1.5.0 → 2.8.0

package/dist/lib/pharos/ecosystemEvidence.js

@@ -0,0 +1,133 @@
+// ─── Pharos Ecosystem Evidence Classifier (read-only, evidence-only) ───
+// Labels a target/intent with an ecosystem category and an HONEST status, from:
+// known official addresses (e.g. Chainlink cache), recognized canonical contracts
+// (Safe, Phase 5B), and provider/category hints. The evidence EXPLAINS risk and may
+// only ESCALATE a decision (cross-chain/WASM → REQUIRE_CONFIRMATION); it can NEVER
+// relax policy or make a risky action safe. Pure: no RPC, no keys, no external APIs.
+// ───────────────────────────────────────────────────────────────────────
+import { getActiveNetwork, getNetworkByChainId, isNetworkName } from "../networks.js";
+import { ECOSYSTEM_PROVIDERS, ecosystemForCanonical, lookupEcosystemByAddress, lookupEcosystemByName, } from "./ecosystem.js";
+/** Per-category decision impact. Only cross-chain + WASM-interop escalate. */
+const CATEGORY_IMPACT = {
+    oracle: "none",
+    cross_chain: "REQUIRE_CONFIRMATION",
+    indexing: "none",
+    wallet_infrastructure: "none",
+    custody_infrastructure: "none",
+    evm_wasm_interop: "REQUIRE_CONFIRMATION",
+    payment: "none",
+    rpc_provider: "none",
+    security: "none",
+    identity: "none",
+    unknown: "none",
+};
+/** Generic descriptions for category-only / unknown classifications. */
+const CATEGORY_META = {
+    oracle: { riskRelevance: "Oracle/price dependency.", safehandsBehavior: "Evidence only; SafeHands has no direct oracle analyzer." },
+    cross_chain: { riskRelevance: "Cross-chain / bridge-like: relayer/finality risk.", safehandsBehavior: "Bridge-like intent → REQUIRE_CONFIRMATION unless trusted. No cross-chain API is called." },
+    indexing: { riskRelevance: "Indexing/data source.", safehandsBehavior: "Optional read-only data source only; not an execution path." },
+    wallet_infrastructure: { riskRelevance: "Smart-account / wallet infrastructure.", safehandsBehavior: "Awareness only; SafeHands holds no keys and never custodies." },
+    custody_infrastructure: { riskRelevance: "External custody/key management.", safehandsBehavior: "Awareness only; SafeHands holds no keys." },
+    evm_wasm_interop: { riskRelevance: "EVM↔WASM interop can bypass EVM-only assumptions.", safehandsBehavior: "Experimental; WASM-interop intent → REQUIRE_CONFIRMATION. No WASM analyzer." },
+    payment: { riskRelevance: "Payment intent (x402).", safehandsBehavior: "Route to the x402 preflight analyzer. mainnet-only; never signs/settles." },
+    rpc_provider: { riskRelevance: "RPC provider/infrastructure.", safehandsBehavior: "Read-only RPC only; secrets redacted." },
+    security: { riskRelevance: "External security/compliance/audit intel.", safehandsBehavior: "Awareness only; SafeHands does not call it and its own verdicts remain the source of truth. An audit/screening is evidence, never a guarantee." },
+    identity: { riskRelevance: "Name service / identity / NFT: names can be spoofed; name ≠ address trust.", safehandsBehavior: "Awareness only; SafeHands never resolves or trusts names as identity; address verification is still required." },
+    unknown: { riskRelevance: "No ecosystem category recognized.", safehandsBehavior: "No ecosystem awareness applies; base analyzers/policy still govern the decision." },
+};
+function isEcosystemCategory(v) {
+    return Object.prototype.hasOwnProperty.call(CATEGORY_IMPACT, v);
+}
+function evidenceFromEntry(entry, ctx) {
+    return {
+        category: entry.category,
+        providerName: entry.name,
+        status: entry.status,
+        confidence: ctx.confidence,
+        source: entry.source,
+        officialDocsUrl: entry.officialDocsUrl ?? null,
+        riskRelevance: entry.riskRelevance,
+        safehandsBehavior: entry.safehandsBehavior,
+        recommendedDecisionImpact: CATEGORY_IMPACT[entry.category],
+        network: ctx.network ?? null,
+        chainId: ctx.chainId ?? null,
+        address: ctx.address ?? null,
+    };
+}
+function evidenceFromCategory(category, source, address) {
+    const meta = CATEGORY_META[category];
+    return {
+        category,
+        providerName: null,
+        status: category === "unknown" ? "not_implemented" : "to_verify",
+        confidence: "low",
+        source,
+        officialDocsUrl: null,
+        riskRelevance: meta.riskRelevance,
+        safehandsBehavior: meta.safehandsBehavior,
+        recommendedDecisionImpact: CATEGORY_IMPACT[category],
+        network: null,
+        chainId: null,
+        address,
+    };
+}
+/**
+ * Classify an ecosystem target. Priority: known official address → recognized
+ * canonical Safe → provider-name hint → category hint → unknown.
+ */
+export function classifyEcosystem(input) {
+    const network = input.network ?? getActiveNetwork();
+    const address = input.address?.trim() || null;
+    // 1) Known official ecosystem address (e.g. Chainlink price-feed cache).
+    if (address) {
+        const byAddr = lookupEcosystemByAddress(address);
+        if (byAddr) {
+            return evidenceFromEntry(byAddr.entry, { confidence: "high", network: byAddr.network, chainId: byAddr.chainId, address });
+        }
+        // 2) Recognized canonical contract that maps to an ecosystem (Safe → wallet infra).
+        const canonicalEco = ecosystemForCanonical(address, network);
+        if (canonicalEco) {
+            return evidenceFromEntry(canonicalEco, { confidence: "high", network: network.name, chainId: network.chainId, address });
+        }
+    }
+    // 3) Provider name/alias hint.
+    if (input.provider) {
+        const byName = lookupEcosystemByName(input.provider);
+        if (byName)
+            return evidenceFromEntry(byName, { confidence: "medium", address });
+    }
+    // 4) Direct category hint.
+    if (input.category) {
+        const c = input.category.trim().toLowerCase();
+        if (isEcosystemCategory(c) && c !== "unknown")
+            return evidenceFromCategory(c, "to_verify", address);
+    }
+    // 5) Nothing recognized.
+    return evidenceFromCategory("unknown", "to_verify", address);
+}
+/** Classify ecosystem evidence for a request (address/target + optional hints). */
+export function ecosystemEvidenceForRequest(req) {
+    const network = req.network && isNetworkName(req.network)
+        ? getNetworkByChainId(req.network === "pacific-mainnet" ? 1672 : 688689) ?? getActiveNetwork()
+        : getActiveNetwork();
+    return classifyEcosystem({
+        address: req.address ?? req.to ?? req.token,
+        provider: req.provider,
+        category: req.ecosystemCategory,
+        network,
+    });
+}
+const SEVERITY = { BLOCK: 3, REQUIRE_CONFIRMATION: 2, PREPARE_ONLY: 1, ALLOW: 0 };
+/**
+ * Apply ecosystem evidence to a decision — ESCALATE-ONLY. Returns the more severe
+ * of the current decision and the evidence's recommended impact; it NEVER downgrades
+ * (a BLOCK stays BLOCK; an unlimited-approval BLOCK is never relaxed).
+ */
+export function applyEcosystemEscalation(decision, evidence) {
+    if (evidence.recommendedDecisionImpact !== "REQUIRE_CONFIRMATION")
+        return decision;
+    return SEVERITY[decision] >= SEVERITY.REQUIRE_CONFIRMATION ? decision : "REQUIRE_CONFIRMATION";
+}
+/** Re-export the registry for callers that want the full provider list. */
+export { ECOSYSTEM_PROVIDERS };
+//# sourceMappingURL=ecosystemEvidence.js.map

package/dist/lib/pharos/ecosystemEvidence.js.map

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

package/dist/lib/pharos/rpc.d.ts

@@ -0,0 +1,44 @@
+import { type PharosNetwork } from "../networks.js";
+import { type RpcMethodClassification } from "./rpcMethods.js";
+/** Raw JSON-RPC transport: (method, params) → result. Must perform reads only. */
+export type RpcTransport = (method: string, params: unknown[]) => Promise<unknown>;
+export interface PharosReadOnlyRpcOptions {
+    network?: PharosNetwork;
+    /** Explicit RPC URL override; otherwise resolved from env (never exposed). */
+    url?: string;
+    /** Injectable transport (used by tests). Defaults to a fetch JSON-RPC POST. */
+    transport?: RpcTransport;
+}
+export interface RpcAdapterCapabilities {
+    configured: boolean;
+    ethGetProof: RpcMethodClassification;
+    ethGetAccount: RpcMethodClassification;
+    ethFeeHistory: RpcMethodClassification;
+}
+export declare class PharosReadOnlyRpc {
+    readonly network: PharosNetwork;
+    private readonly url;
+    private readonly injectedTransport;
+    constructor(opts?: PharosReadOnlyRpcOptions);
+    /** True when a transport or RPC URL is available (does not perform any I/O). */
+    isConfigured(): boolean;
+    /**
+     * Gate + execute a raw read-only JSON-RPC call. The matrix gate runs FIRST, so
+     * write/unsupported/unknown methods throw before any network I/O.
+     */
+    request<T = unknown>(method: string, params?: unknown[]): Promise<T>;
+    /**
+     * Best-effort experimental read: still gated (throws for blocked methods), but
+     * returns null instead of throwing when the transport is missing or fails.
+     */
+    tryRequest<T = unknown>(method: string, params?: unknown[]): Promise<T | null>;
+    /**
+     * Gate a method name, then run a (e.g. viem) read function. Lets existing typed
+     * reads keep their result parsing while still passing the whitelist chokepoint.
+     */
+    guarded<T>(method: string, fn: () => Promise<T>): Promise<T>;
+    /** Matrix-derived capability descriptor (deterministic; performs no I/O). */
+    capabilities(): RpcAdapterCapabilities;
+    private transport;
+}
+//# sourceMappingURL=rpc.d.ts.map

package/dist/lib/pharos/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../../../src/lib/pharos/rpc.ts"],"names":[],"mappings":"AASA,OAAO,EAAmC,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAErF,OAAO,EAAiD,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE9G,kFAAkF;AAClF,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEnF,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,uBAAuB,CAAC;IACrC,aAAa,EAAE,uBAAuB,CAAC;IACvC,aAAa,EAAE,uBAAuB,CAAC;CACxC;AAED,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2B;gBAEjD,IAAI,GAAE,wBAA6B;IAM/C,gFAAgF;IAChF,YAAY,IAAI,OAAO;IAIvB;;;OAGG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAK9E;;;OAGG;IACG,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAUxF;;;OAGG;IACG,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAKlE,6EAA6E;IAC7E,YAAY,IAAI,sBAAsB;IAStC,OAAO,CAAC,SAAS;CAsBlB"}

package/dist/lib/pharos/rpc.js

@@ -0,0 +1,90 @@
+// ─── Pharos Read-Only RPC Adapter (single whitelist chokepoint) ────────
+// A read-only JSON-RPC adapter that gates EVERY call through the method matrix
+// (rpcMethods.ts) BEFORE any network I/O. Write/signing/account/unknown methods
+// throw fail-closed and never reach the transport. There is no signer, wallet,
+// or key surface here — read-only by construction. The transport is injectable
+// (tests inject a spy); the default is a fetch-based JSON-RPC POST whose URL is
+// resolved from env only (premium/keyed URLs are never hardcoded or exposed).
+// ───────────────────────────────────────────────────────────────────────
+import { getActiveNetwork, resolveRpcUrl } from "../networks.js";
+import { fetchWithTimeoutAndRetry } from "../http.js";
+import { assertHostedReadOnlyMethod, classifyRpcMethod } from "./rpcMethods.js";
+export class PharosReadOnlyRpc {
+    network;
+    url;
+    injectedTransport;
+    constructor(opts = {}) {
+        this.network = opts.network ?? getActiveNetwork();
+        this.url = opts.url ?? resolveRpcUrl(this.network);
+        this.injectedTransport = opts.transport;
+    }
+    /** True when a transport or RPC URL is available (does not perform any I/O). */
+    isConfigured() {
+        return Boolean(this.injectedTransport) || Boolean(this.url);
+    }
+    /**
+     * Gate + execute a raw read-only JSON-RPC call. The matrix gate runs FIRST, so
+     * write/unsupported/unknown methods throw before any network I/O.
+     */
+    async request(method, params = []) {
+        assertHostedReadOnlyMethod(method);
+        return (await this.transport()(method, params));
+    }
+    /**
+     * Best-effort experimental read: still gated (throws for blocked methods), but
+     * returns null instead of throwing when the transport is missing or fails.
+     */
+    async tryRequest(method, params = []) {
+        assertHostedReadOnlyMethod(method);
+        if (!this.isConfigured())
+            return null;
+        try {
+            return (await this.transport()(method, params));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Gate a method name, then run a (e.g. viem) read function. Lets existing typed
+     * reads keep their result parsing while still passing the whitelist chokepoint.
+     */
+    async guarded(method, fn) {
+        assertHostedReadOnlyMethod(method);
+        return fn();
+    }
+    /** Matrix-derived capability descriptor (deterministic; performs no I/O). */
+    capabilities() {
+        return {
+            configured: this.isConfigured(),
+            ethGetProof: classifyRpcMethod("eth_getProof"),
+            ethGetAccount: classifyRpcMethod("eth_getAccount"),
+            ethFeeHistory: classifyRpcMethod("eth_feeHistory"),
+        };
+    }
+    transport() {
+        if (this.injectedTransport)
+            return this.injectedTransport;
+        const url = this.url;
+        if (!url) {
+            return async (method) => {
+                throw new Error(`No RPC URL configured for ${this.network.name} (offline read-only); cannot call ${method}.`);
+            };
+        }
+        return async (method, params) => {
+            const res = await fetchWithTimeoutAndRetry(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+                timeoutMs: 10_000,
+                retries: 1,
+                retryDelayMs: 250,
+            });
+            const json = (await res.json());
+            if (json.error)
+                throw new Error(`RPC error for ${method}: ${json.error.message ?? "unknown"}`);
+            return json.result;
+        };
+    }
+}
+//# sourceMappingURL=rpc.js.map

package/dist/lib/pharos/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../../src/lib/pharos/rpc.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,+EAA+E;AAC/E,gFAAgF;AAChF,8EAA8E;AAC9E,0EAA0E;AAE1E,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAsB,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,iBAAiB,EAAgC,MAAM,iBAAiB,CAAC;AAoB9G,MAAM,OAAO,iBAAiB;IACnB,OAAO,CAAgB;IACf,GAAG,CAAqB;IACxB,iBAAiB,CAA2B;IAE7D,YAAY,OAAiC,EAAE;QAC7C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,gBAAgB,EAAE,CAAC;QAClD,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,SAAS,CAAC;IAC1C,CAAC;IAED,gFAAgF;IAChF,YAAY;QACV,OAAO,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAc,MAAc,EAAE,SAAoB,EAAE;QAC/D,0BAA0B,CAAC,MAAM,CAAC,CAAC;QACnC,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,CAAC;IACvD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAc,MAAc,EAAE,SAAoB,EAAE;QAClE,0BAA0B,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE;YAAE,OAAO,IAAI,CAAC;QACtC,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAI,MAAc,EAAE,EAAoB;QACnD,0BAA0B,CAAC,MAAM,CAAC,CAAC;QACnC,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAED,6EAA6E;IAC7E,YAAY;QACV,OAAO;YACL,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE;YAC/B,WAAW,EAAE,iBAAiB,CAAC,cAAc,CAAC;YAC9C,aAAa,EAAE,iBAAiB,CAAC,gBAAgB,CAAC;YAClD,aAAa,EAAE,iBAAiB,CAAC,gBAAgB,CAAC;SACnD,CAAC;IACJ,CAAC;IAEO,SAAS;QACf,IAAI,IAAI,CAAC,iBAAiB;YAAE,OAAO,IAAI,CAAC,iBAAiB,CAAC;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACrB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,KAAK,EAAE,MAAM,EAAE,EAAE;gBACtB,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,CAAC,OAAO,CAAC,IAAI,qCAAqC,MAAM,GAAG,CAAC,CAAC;YAChH,CAAC,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YAC9B,MAAM,GAAG,GAAG,MAAM,wBAAwB,CAAC,GAAG,EAAE;gBAC9C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;gBAC/D,SAAS,EAAE,MAAM;gBACjB,OAAO,EAAE,CAAC;gBACV,YAAY,EAAE,GAAG;aAClB,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuD,CAAC;YACtF,IAAI,IAAI,CAAC,KAAK;gBAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC,CAAC;YAC/F,OAAO,IAAI,CAAC,MAAM,CAAC;QACrB,CAAC,CAAC;IACJ,CAAC;CACF"}

package/dist/lib/pharos/rpcEvidence.d.ts

@@ -0,0 +1,49 @@
+import { type NetworkName, type PharosNetwork, type RpcProviderName } from "../networks.js";
+import type { ReadOnlyChainAccess } from "../analysis/types.js";
+import { type RpcMethodMatrixSummary } from "./rpcMethods.js";
+export interface RpcProviderEvidence {
+    name: RpcProviderName;
+    configuredViaEnv: boolean;
+    usingPublicDefault: boolean;
+    /** Always true — the URL/API key is never included in evidence. */
+    secretsRedacted: true;
+}
+export interface RpcProofCapability {
+    method: "eth_getProof";
+    status: "experimental" | "implemented";
+    readOnly: true;
+    spvVerification: "not_implemented" | "implemented";
+}
+export interface RpcFeeCapability {
+    gasPrice: boolean;
+    maxPriorityFeePerGas: boolean;
+    feeHistory: boolean;
+    estimateGas: boolean;
+}
+export interface RpcEvidence {
+    readOnly: true;
+    executionAvailable: boolean;
+    network: NetworkName;
+    chainId: number;
+    provider: RpcProviderEvidence;
+    methods: RpcMethodMatrixSummary;
+    writeBlocked: string[];
+    capabilities: {
+        ethGetProof: RpcProofCapability;
+        feeData: RpcFeeCapability;
+    };
+    /** True when no live read-only access was supplied (capability-only evidence). */
+    fallbackUsed: boolean;
+}
+export declare function rpcEvidence(network?: PharosNetwork, access?: ReadOnlyChainAccess): RpcEvidence;
+export interface GasEvidence {
+    gasBufferPct: number;
+    feeDataAvailable: boolean;
+    feeHistoryAvailable: boolean;
+    priorityFeeAvailable: boolean;
+    estimateGasAvailable: boolean;
+    /** True when no live gas estimator was supplied (offline/capability-only). */
+    fallbackUsed: boolean;
+}
+export declare function gasEvidence(access?: ReadOnlyChainAccess): GasEvidence;
+//# sourceMappingURL=rpcEvidence.d.ts.map

package/dist/lib/pharos/rpcEvidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpcEvidence.d.ts","sourceRoot":"","sources":["../../../src/lib/pharos/rpcEvidence.ts"],"names":[],"mappings":"AAQA,OAAO,EAAwC,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGlI,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAmE,KAAK,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE/H,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mEAAmE;IACnE,eAAe,EAAE,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,cAAc,GAAG,aAAa,CAAC;IACvC,QAAQ,EAAE,IAAI,CAAC;IACf,eAAe,EAAE,iBAAiB,GAAG,aAAa,CAAC;CACpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,IAAI,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,sBAAsB,CAAC;IAChC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE;QACZ,WAAW,EAAE,kBAAkB,CAAC;QAChC,OAAO,EAAE,gBAAgB,CAAC;KAC3B,CAAC;IACF,kFAAkF;IAClF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,WAAW,CAAC,OAAO,GAAE,aAAkC,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,WAAW,CAuBlH;AAED,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,8EAA8E;IAC9E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,WAAW,CASrE"}

package/dist/lib/pharos/rpcEvidence.js

@@ -0,0 +1,46 @@
+// ─── Pharos Read-Only RPC Evidence (deterministic, secret-free) ────────
+// Builds read-only `rpcEvidence` / `gasEvidence` descriptors for API and Agent
+// responses. Everything here is derived from the method matrix + network/config
+// — it performs NO network I/O and is deterministic offline. It NEVER exposes an
+// RPC URL or API key (only the redacted provider name). Evidence is metadata: it
+// describes read-only capability and never relaxes a SafeHands decision.
+// ───────────────────────────────────────────────────────────────────────
+import { getActiveNetwork, resolveRpcProvider } from "../networks.js";
+import { isExecutionAvailable } from "../config.js";
+import { DEFAULT_GAS_BUFFER_PCT } from "../analysis/gas.js";
+import { isReadOnlyMethod, rpcMethodMatrixSummary, WRITE_BLOCKED_METHODS } from "./rpcMethods.js";
+export function rpcEvidence(network = getActiveNetwork(), access) {
+    const provider = resolveRpcProvider(network);
+    return {
+        readOnly: true,
+        executionAvailable: isExecutionAvailable(network),
+        network: network.name,
+        chainId: network.chainId,
+        provider: { ...provider, secretsRedacted: true },
+        methods: rpcMethodMatrixSummary(),
+        writeBlocked: WRITE_BLOCKED_METHODS,
+        capabilities: {
+            // Status matches rpcMethods.ts: the method is experimental (heavy, best-effort);
+            // SPV verification itself is implemented (spvVerifier.ts via get_spv_proof).
+            ethGetProof: { method: "eth_getProof", status: "experimental", readOnly: true, spvVerification: "implemented" },
+            feeData: {
+                gasPrice: isReadOnlyMethod("eth_gasPrice"),
+                maxPriorityFeePerGas: isReadOnlyMethod("eth_maxPriorityFeePerGas"),
+                feeHistory: isReadOnlyMethod("eth_feeHistory"),
+                estimateGas: isReadOnlyMethod("eth_estimateGas"),
+            },
+        },
+        fallbackUsed: !access,
+    };
+}
+export function gasEvidence(access) {
+    return {
+        gasBufferPct: DEFAULT_GAS_BUFFER_PCT,
+        feeDataAvailable: isReadOnlyMethod("eth_gasPrice"),
+        feeHistoryAvailable: isReadOnlyMethod("eth_feeHistory"),
+        priorityFeeAvailable: isReadOnlyMethod("eth_maxPriorityFeePerGas"),
+        estimateGasAvailable: isReadOnlyMethod("eth_estimateGas"),
+        fallbackUsed: !access?.estimateGas,
+    };
+}
+//# sourceMappingURL=rpcEvidence.js.map

package/dist/lib/pharos/rpcEvidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpcEvidence.js","sourceRoot":"","sources":["../../../src/lib/pharos/rpcEvidence.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,+EAA+E;AAC/E,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,yEAAyE;AACzE,0EAA0E;AAE1E,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAA8D,MAAM,gBAAgB,CAAC;AAClI,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,qBAAqB,EAA+B,MAAM,iBAAiB,CAAC;AAwC/H,MAAM,UAAU,WAAW,CAAC,UAAyB,gBAAgB,EAAE,EAAE,MAA4B;IACnG,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,kBAAkB,EAAE,oBAAoB,CAAC,OAAO,CAAC;QACjD,OAAO,EAAE,OAAO,CAAC,IAAI;QACrB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE;QAChD,OAAO,EAAE,sBAAsB,EAAE;QACjC,YAAY,EAAE,qBAAqB;QACnC,YAAY,EAAE;YACZ,iFAAiF;YACjF,6EAA6E;YAC7E,WAAW,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,EAAE,eAAe,EAAE,aAAa,EAAE;YAC/G,OAAO,EAAE;gBACP,QAAQ,EAAE,gBAAgB,CAAC,cAAc,CAAC;gBAC1C,oBAAoB,EAAE,gBAAgB,CAAC,0BAA0B,CAAC;gBAClE,UAAU,EAAE,gBAAgB,CAAC,gBAAgB,CAAC;gBAC9C,WAAW,EAAE,gBAAgB,CAAC,iBAAiB,CAAC;aACjD;SACF;QACD,YAAY,EAAE,CAAC,MAAM;KACtB,CAAC;AACJ,CAAC;AAYD,MAAM,UAAU,WAAW,CAAC,MAA4B;IACtD,OAAO;QACL,YAAY,EAAE,sBAAsB;QACpC,gBAAgB,EAAE,gBAAgB,CAAC,cAAc,CAAC;QAClD,mBAAmB,EAAE,gBAAgB,CAAC,gBAAgB,CAAC;QACvD,oBAAoB,EAAE,gBAAgB,CAAC,0BAA0B,CAAC;QAClE,oBAAoB,EAAE,gBAAgB,CAAC,iBAAiB,CAAC;QACzD,YAAY,EAAE,CAAC,MAAM,EAAE,WAAW;KACnC,CAAC;AACJ,CAAC"}

package/dist/lib/pharos/rpcMethods.d.ts

@@ -0,0 +1,46 @@
+export type RpcMethodClassification = "read_only" | "experimental_read_only" | "write_blocked" | "unsupported" | "to_verify";
+export type RpcMethodSafehandsStatus = "implemented" | "experimental" | "blocked" | "not_implemented" | "to_verify";
+export interface RpcMethodEntry {
+    method: string;
+    classification: RpcMethodClassification;
+    officialDocsUrl?: string;
+    safehandsStatus: RpcMethodSafehandsStatus;
+    riskRelevance: string;
+    hostedModeBehavior: string;
+}
+export declare const RPC_METHOD_MATRIX: Record<string, RpcMethodEntry>;
+/** Error thrown when a non-read-only (or unknown) method is requested in hosted mode. */
+export declare class RpcMethodBlockedError extends Error {
+    readonly method: string;
+    readonly classification: RpcMethodClassification;
+    constructor(method: string, classification: RpcMethodClassification);
+}
+/**
+ * Classify a method. Known methods use the matrix; unknown `wallet_*`/`personal_*`
+ * are treated as write_blocked, and any other unknown method as unsupported — both
+ * fail closed in {@link assertHostedReadOnlyMethod}.
+ */
+export declare function classifyRpcMethod(method: string): RpcMethodClassification;
+/** A method usable by read-only analyzers (read_only or experimental_read_only). */
+export declare function isReadOnlyMethod(method: string): boolean;
+export declare function isWriteBlockedMethod(method: string): boolean;
+/**
+ * Fail-closed gate for hosted/read-only mode. Returns for read_only and
+ * experimental_read_only methods; THROWS for write_blocked, unsupported,
+ * to_verify, and any unknown method. This must run BEFORE any network I/O.
+ */
+export declare function assertHostedReadOnlyMethod(method: string): void;
+export declare const READ_ONLY_METHODS: string[];
+export declare const EXPERIMENTAL_READ_ONLY_METHODS: string[];
+export declare const WRITE_BLOCKED_METHODS: string[];
+export declare const UNSUPPORTED_METHODS: string[];
+export interface RpcMethodMatrixSummary {
+    readOnly: number;
+    experimentalReadOnly: number;
+    writeBlocked: number;
+    unsupported: number;
+    toVerify: number;
+    total: number;
+}
+export declare function rpcMethodMatrixSummary(): RpcMethodMatrixSummary;
+//# sourceMappingURL=rpcMethods.d.ts.map

package/dist/lib/pharos/rpcMethods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpcMethods.d.ts","sourceRoot":"","sources":["../../../src/lib/pharos/rpcMethods.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,uBAAuB,GAC/B,WAAW,GACX,wBAAwB,GACxB,eAAe,GACf,aAAa,GACb,WAAW,CAAC;AAEhB,MAAM,MAAM,wBAAwB,GAChC,aAAa,GACb,cAAc,GACd,SAAS,GACT,iBAAiB,GACjB,WAAW,CAAC;AAEhB,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,uBAAuB,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,wBAAwB,CAAC;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAwHD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAE5D,CAAC;AAEF,yFAAyF;AACzF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,uBAAuB,CAAC;gBACrC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,uBAAuB;CAMpE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,uBAAuB,CAKzE;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAI/D;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAAiF,CAAC;AACxH,eAAO,MAAM,8BAA8B,EAAE,MAAM,EAA8F,CAAC;AAClJ,eAAO,MAAM,qBAAqB,EAAE,MAAM,EAAqF,CAAC;AAChI,eAAO,MAAM,mBAAmB,EAAE,MAAM,EAAmF,CAAC;AAE5H,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,sBAAsB,IAAI,sBAAsB,CAW/D"}

package/dist/lib/pharos/rpcMethods.js

@@ -0,0 +1,176 @@
+// ─── Pharos JSON-RPC Method Matrix (read-only enforcement) ─────────────
+// Single source of truth classifying every JSON-RPC method SafeHands may
+// encounter. Hosted/read-only mode allows ONLY read methods; write, signing,
+// and account methods are blocked fail-closed (unknown methods are blocked too).
+// Grounded in the official Pharos JSON-RPC docs
+// (docs.pharos.xyz/api-and-sdk/json-rpc-methods, verified 2026-06-27):
+//   • the ONLY documented write method is eth_sendRawTransaction
+//   • eth_getProof (EIP-1186) and eth_getAccount are officially supported reads
+//   • eth_accounts returns [] (the node manages no accounts); eth_sign is undocumented
+// Nothing in this module signs, sends, or mutates chain state.
+// ───────────────────────────────────────────────────────────────────────
+const JSON_RPC_DOCS = "https://docs.pharos.xyz/api-and-sdk/json-rpc-methods";
+const GETPROOF_DOCS = "https://docs.pharos.xyz/api-and-sdk/eth-getproof-storage-state-verification";
+const ALLOW_BEHAVIOR = "Allowed in hosted read-only mode.";
+const EXPERIMENTAL_BEHAVIOR = "Allowed as a read-only call, attempted with graceful fallback; deeper verification (e.g. SPV) is NOT implemented.";
+const BLOCK_BEHAVIOR = "BLOCKED in hosted read-only mode; never called.";
+const UNSUPPORTED_BEHAVIOR = "Unsupported on Pharos / never called automatically.";
+function readOnly(method, riskRelevance, officialDocsUrl = JSON_RPC_DOCS) {
+    return { method, classification: "read_only", officialDocsUrl, safehandsStatus: "implemented", riskRelevance, hostedModeBehavior: ALLOW_BEHAVIOR };
+}
+function experimental(method, riskRelevance, officialDocsUrl = JSON_RPC_DOCS) {
+    return { method, classification: "experimental_read_only", officialDocsUrl, safehandsStatus: "experimental", riskRelevance, hostedModeBehavior: EXPERIMENTAL_BEHAVIOR };
+}
+function writeBlocked(method, riskRelevance) {
+    return { method, classification: "write_blocked", officialDocsUrl: JSON_RPC_DOCS, safehandsStatus: "blocked", riskRelevance, hostedModeBehavior: BLOCK_BEHAVIOR };
+}
+function unsupported(method, riskRelevance) {
+    return { method, classification: "unsupported", safehandsStatus: "not_implemented", riskRelevance, hostedModeBehavior: UNSUPPORTED_BEHAVIOR };
+}
+const ENTRIES = [
+    // ── Read-only (officially supported) ──────────────────────────────────
+    readOnly("eth_chainId", "Confirms the active chain (Pacific Mainnet = 1672)."),
+    readOnly("eth_blockNumber", "Chain head; freshness of read evidence."),
+    readOnly("eth_gasPrice", "Legacy gas price for fee estimation."),
+    readOnly("eth_maxPriorityFeePerGas", "EIP-1559 priority fee for fee estimation."),
+    readOnly("eth_feeHistory", "Historical base/priority fees for fee estimation."),
+    readOnly("eth_call", "Simulated read-only call; never changes state."),
+    readOnly("eth_estimateGas", "Gas estimation; a failing estimate often signals a revert."),
+    readOnly("eth_getCode", "Distinguishes contracts from EOAs."),
+    readOnly("eth_getBalance", "Account balance for affordability checks."),
+    readOnly("eth_getStorageAt", "Raw contract storage read."),
+    readOnly("eth_getTransactionCount", "Account nonce."),
+    readOnly("eth_getTransactionByHash", "Transaction lookup by hash."),
+    readOnly("eth_getTransactionReceipt", "Receipt/status of a mined transaction."),
+    readOnly("eth_getBlockByHash", "Block lookup by hash."),
+    readOnly("eth_getBlockByNumber", "Block lookup by number."),
+    readOnly("eth_getBlockReceipts", "All transaction receipts in a block."),
+    readOnly("eth_getLogs", "Event logs (block range ≤100 when rate-limited)."),
+    readOnly("eth_getAccount", "Account details (balance/nonce); officially supported read."),
+    readOnly("eth_syncing", "Node sync status."),
+    readOnly("net_version", "Network id."),
+    readOnly("web3_clientVersion", "Client version string."),
+    // ── Experimental read-only (supported but heavy / not fully consumed) ──
+    experimental("eth_getProof", "EIP-1186 account/storage Merkle proof. SPV verification is implemented (src/lib/pharos/spvVerifier.ts, exposed via get_spv_proof) using Pharos' SHA-256 trie; the method itself remains experimental (heavy, best-effort).", GETPROOF_DOCS),
+    experimental("debug_traceTransaction", "Full execution trace; heavy/optional, best-effort only."),
+    experimental("trace_filter", "Filtered traces (block range ≤500); heavy/optional, best-effort only."),
+    // ── Write — BLOCKED in hosted read-only mode ──────────────────────────
+    writeBlocked("eth_sendRawTransaction", "Submits a signed transaction: the only documented state-changing method; NEVER used in hosted read-only mode."),
+    writeBlocked("eth_sendTransaction", "Node-signed send; blocked (the node manages no accounts and SafeHands never sends)."),
+    writeBlocked("eth_signTransaction", "Signs a transaction; blocked: SafeHands never signs."),
+    writeBlocked("eth_sign", "Signs arbitrary data; blocked (also undocumented on Pharos)."),
+    writeBlocked("personal_sign", "Wallet message signing; blocked: SafeHands holds no keys."),
+    writeBlocked("eth_signTypedData", "EIP-712 typed-data signing; blocked."),
+    writeBlocked("eth_signTypedData_v4", "EIP-712 typed-data signing; blocked."),
+    writeBlocked("personal_unlockAccount", "Unlocks a node-managed account; blocked."),
+    writeBlocked("personal_newAccount", "Account creation; blocked: SafeHands never creates/holds keys."),
+    writeBlocked("personal_importRawKey", "Private-key import; blocked: SafeHands never imports keys."),
+    writeBlocked("wallet_addEthereumChain", "Wallet management; blocked."),
+    writeBlocked("wallet_switchEthereumChain", "Wallet management; blocked."),
+    writeBlocked("wallet_watchAsset", "Wallet management; blocked."),
+    writeBlocked("wallet_requestPermissions", "Wallet management; blocked."),
+    // ── Unsupported on Pharos / never auto-called ─────────────────────────
+    unsupported("eth_accounts", "Returns [] on Pharos (node manages no accounts); never relied upon."),
+    unsupported("eth_coinbase", "Deprecated PoW-era method; not used."),
+    unsupported("eth_mining", "Deprecated PoW-era method; not used."),
+    unsupported("eth_hashrate", "Deprecated PoW-era method; not used."),
+    unsupported("eth_getUncleCountByBlockHash", "Uncles are a PoW concept; returns null."),
+    unsupported("eth_getUncleCountByBlockNumber", "Uncles are a PoW concept; returns null."),
+    unsupported("eth_getUncleByBlockHashAndIndex", "Uncles are a PoW concept; returns null."),
+    unsupported("eth_getUncleByBlockNumberAndIndex", "Uncles are a PoW concept; returns null."),
+    unsupported("eth_getCompilers", "Deprecated."),
+    unsupported("eth_pendingTransactions", "Returns empty array on Pharos."),
+    unsupported("eth_batchGetBlockByNumber", "Method not implemented on Pharos."),
+    unsupported("eth_batchGetTransactionByHash", "Method not implemented on Pharos."),
+    unsupported("eth_batchGetTransactionReceipt", "Method not implemented on Pharos."),
+    unsupported("eth_batchGetBlockReceipts", "Method not implemented on Pharos."),
+    // ── Newly Documented Read Methods (Pacific Mainnet) ───────────────────
+    readOnly("eth_createAccessList", "Creates an EIP-2930 access list for a transaction (under debugging)."),
+    readOnly("eth_getBlockTransactionCountByHash", "Returns the number of transactions in a block by block hash."),
+    readOnly("eth_getBlockTransactionCountByNumber", "Returns the number of transactions in a block by block number."),
+    readOnly("eth_getTransactionByBlockHashAndIndex", "Returns a transaction by block hash and index position."),
+    readOnly("eth_getTransactionByBlockNumberAndIndex", "Returns a transaction by block number and index position."),
+    readOnly("eth_subscribe", "Creates a subscription for real-time events (WebSocket only)."),
+    readOnly("eth_unsubscribe", "Cancels an existing subscription (WebSocket only)."),
+    readOnly("net_listening", "Returns whether the node is actively listening (not available on public RPC)."),
+    readOnly("net_peerCount", "Returns the number of connected peers (not available on public RPC)."),
+    readOnly("web3_sha3", "Returns the Keccak-256 hash of the given data (not available on public RPC)."),
+    readOnly("eth_getProposerByTxHash", "Returns the block proposer for a given transaction (Pharos Extension)."),
+    readOnly("eth_getProposersByBlockNumber", "Returns the list of proposers for a given block (Pharos Extension)."),
+    // ── Debug / Trace Methods ──────────────────────────────────────────────
+    experimental("debug_traceCall", "Executes a call and returns the execution trace without creating a transaction."),
+    experimental("debug_traceBlockByHash", "Returns traces for all transactions in a block by block hash."),
+    experimental("debug_traceBlockByNumber", "Returns traces for all transactions in a block by block number."),
+    experimental("debug_getRawBlock", "Returns the RLP-encoded block data."),
+    experimental("debug_getRawHeader", "Returns the RLP-encoded block header."),
+    experimental("debug_getRawReceipts", "Returns the raw receipts for a block."),
+    experimental("debug_getRawTransaction", "Returns the raw transaction data by hash."),
+    experimental("debug_protocolVersion", "Returns detailed protocol and version information."),
+    experimental("txpool_nonceFrom", "Returns the next nonce for an address from the transaction pool."),
+    experimental("debug_getValidatorInfo", "Returns validator information for the consensus layer (Pharos Extension)."),
+    experimental("debug_getBlockProof", "Returns the block proof data for BLS signature verification (Pharos Extension)."),
+    experimental("debug_getBlockReadStates", "Returns the read state set for a block (Pharos Extension)."),
+    experimental("debug_getBlockWriteStates", "Returns the write state set for a block (Pharos Extension)."),
+    experimental("debug_getBlockWriteSetKeys", "Returns the write set keys for a block (Pharos Extension)."),
+];
+export const RPC_METHOD_MATRIX = Object.fromEntries(ENTRIES.map((e) => [e.method, e]));
+/** Error thrown when a non-read-only (or unknown) method is requested in hosted mode. */
+export class RpcMethodBlockedError extends Error {
+    method;
+    classification;
+    constructor(method, classification) {
+        super(`RPC method "${method}" is blocked in hosted read-only mode (classification: ${classification}).`);
+        this.name = "RpcMethodBlockedError";
+        this.method = method;
+        this.classification = classification;
+    }
+}
+/**
+ * Classify a method. Known methods use the matrix; unknown `wallet_*`/`personal_*`
+ * are treated as write_blocked, and any other unknown method as unsupported — both
+ * fail closed in {@link assertHostedReadOnlyMethod}.
+ */
+export function classifyRpcMethod(method) {
+    const entry = RPC_METHOD_MATRIX[method];
+    if (entry)
+        return entry.classification;
+    if (method.startsWith("wallet_") || method.startsWith("personal_"))
+        return "write_blocked";
+    return "unsupported";
+}
+/** A method usable by read-only analyzers (read_only or experimental_read_only). */
+export function isReadOnlyMethod(method) {
+    const c = classifyRpcMethod(method);
+    return c === "read_only" || c === "experimental_read_only";
+}
+export function isWriteBlockedMethod(method) {
+    return classifyRpcMethod(method) === "write_blocked";
+}
+/**
+ * Fail-closed gate for hosted/read-only mode. Returns for read_only and
+ * experimental_read_only methods; THROWS for write_blocked, unsupported,
+ * to_verify, and any unknown method. This must run BEFORE any network I/O.
+ */
+export function assertHostedReadOnlyMethod(method) {
+    const c = classifyRpcMethod(method);
+    if (c === "read_only" || c === "experimental_read_only")
+        return;
+    throw new RpcMethodBlockedError(method, c);
+}
+export const READ_ONLY_METHODS = ENTRIES.filter((e) => e.classification === "read_only").map((e) => e.method);
+export const EXPERIMENTAL_READ_ONLY_METHODS = ENTRIES.filter((e) => e.classification === "experimental_read_only").map((e) => e.method);
+export const WRITE_BLOCKED_METHODS = ENTRIES.filter((e) => e.classification === "write_blocked").map((e) => e.method);
+export const UNSUPPORTED_METHODS = ENTRIES.filter((e) => e.classification === "unsupported").map((e) => e.method);
+export function rpcMethodMatrixSummary() {
+    const vals = Object.values(RPC_METHOD_MATRIX);
+    const count = (c) => vals.filter((e) => e.classification === c).length;
+    return {
+        readOnly: count("read_only"),
+        experimentalReadOnly: count("experimental_read_only"),
+        writeBlocked: count("write_blocked"),
+        unsupported: count("unsupported"),
+        toVerify: count("to_verify"),
+        total: vals.length,
+    };
+}
+//# sourceMappingURL=rpcMethods.js.map