safehands-pharos 1.5.0 → 2.6.0

package/dist/lib/analysis/contractIntel.js

@@ -0,0 +1,320 @@
+// ─── Contract Intelligence Analyzer (read-only, decode-only) ───────────
+// Recognizes well-known canonical contracts by address and reports on-chain
+// code presence via read-only eth_getCode. It does NOT verify source code, does
+// NOT call explorer verification APIs, and does NOT confirm a contract is
+// deployed/verified on the active Pharos network. Recognition is by canonical
+// address only.
+//
+// Recognition is PER-NETWORK. Pacific Mainnet uses the Pharos-official canonical
+// addresses recorded from the Phase 5A Pharos docs audit — Pharos deploys
+// Safe/SafeL2/MultiSend at Pharos-specific addresses and ships CreateX, so the
+// standard-Ethereum Safe addresses are NOT used as Pharos defaults. Deterministic
+// CREATE2 contracts (Permit2/Multicall3/EntryPoint) share one address across EVM
+// chains and are recognized on every network.
+// ────────────────────────────────────────────────────────────────────────
+import { getAddress, isAddress } from "viem";
+import { getActiveNetwork } from "../networks.js";
+import { ATLANTIC_CANONICAL_CONTRACTS, PACIFIC_CANONICAL_CONTRACTS } from "../constants.js";
+import { makeResult } from "./types.js";
+/**
+ * Per-network recognition scope is derived from the canonical infrastructure
+ * lists in constants.ts (which in turn derive from the canonical ecosystem
+ * registry). This keeps the read-API analyzer and the policy engine's
+ * isCanonicalInfrastructure() recognizing the SAME set per network — the same
+ * address can no longer be "canonical" to one layer and "unknown" to another.
+ */
+function networksFor(lowercaseAddress) {
+    const networks = [];
+    if (PACIFIC_CANONICAL_CONTRACTS.includes(lowercaseAddress))
+        networks.push("pacific-mainnet");
+    if (ATLANTIC_CANONICAL_CONTRACTS.includes(lowercaseAddress))
+        networks.push("atlantic-testnet");
+    return networks;
+}
+/**
+ * Known canonical addresses. Recognition is by canonical address only —
+ * deployment/verification on the active network is NOT asserted. Addresses are
+ * lowercase keys. Pharos-specific Safe/SafeL2/MultiSend + CreateX are taken from
+ * the official Pharos canonical-contracts page (Phase 5A audit); per-network
+ * scope comes from networksFor(). DODO/DEX testnet infrastructure from the
+ * Atlantic allowlist is intentionally NOT given canonical metadata here — those
+ * addresses are governed by the DODO-specific allowlists and swap policy.
+ */
+const CANONICAL_CONTRACT_METADATA = {
+    // ── Deterministic CREATE2 deployments (same address on every EVM chain) ──
+    "0x000000000022d473030f116ddee9f6b43ac78ba3": {
+        label: "Uniswap Permit2",
+        standard: "Permit2",
+        category: "approval-router",
+        deterministic: true,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "Permit2 manages ERC-20 allowances and can later authorize transfers via signatures; an approval to Permit2 delegates allowance management to it.",
+        recommendedSafeHandsBehavior: "Recognize as canonical, but do NOT treat as automatically safe: unlimited approvals still REQUIRE_CONFIRMATION (deep Permit2 decode is experimental).",
+    },
+    "0xca11bde05977b3631167028862be2a173976ca11": {
+        label: "Multicall3",
+        standard: "MultiCall3",
+        category: "batching",
+        deterministic: true,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "Aggregates multiple calls into one; the batch's inner calls determine the real risk.",
+        recommendedSafeHandsBehavior: "Recognize as canonical batching contract; inspect the inner calls, not just the entrypoint.",
+    },
+    "0x5ff137d4b0fdcd49dca30c7cf57e578a026d2789": {
+        label: "ERC-4337 EntryPoint v0.6",
+        standard: "ERC4337EntryPoint",
+        category: "account-abstraction",
+        deterministic: true,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "ERC-4337 account-abstraction entrypoint; executes bundled UserOperations.",
+        recommendedSafeHandsBehavior: "Recognize as canonical; UserOperation contents are not decoded; treat the action as REQUIRE_CONFIRMATION.",
+    },
+    "0x0000000071727de22e5e9d8baf0edac6f37da032": {
+        label: "ERC-4337 EntryPoint v0.7",
+        standard: "ERC4337EntryPoint",
+        category: "account-abstraction",
+        deterministic: true,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "ERC-4337 account-abstraction entrypoint; executes bundled UserOperations.",
+        recommendedSafeHandsBehavior: "Recognize as canonical; UserOperation contents are not decoded; treat the action as REQUIRE_CONFIRMATION.",
+    },
+    // ── Pharos Pacific Mainnet official addresses (canonical-contracts page) ──
+    // Pharos deploys Safe v1.3.0 at Pharos-specific addresses (NOT the standard
+    // Ethereum Safe addresses), so those are used here for Pacific Mainnet.
+    "0x69f4d1788e39c87893c980c06edf4b7f686e2938": {
+        label: "Pharos Safe Singleton (GnosisSafe v1.3.0)",
+        standard: "Safe",
+        category: "smart-account",
+        deterministic: false,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "Safe smart-account singleton; transactions execute via the Safe's owners/threshold.",
+        recommendedSafeHandsBehavior: "Recognize as the canonical Safe singleton on Pacific Mainnet; Safe execTransaction / MultiSend batch contents are decoded separately (experimental).",
+        note: "Pharos-specific deployment address (differs from the standard-Ethereum Safe 1.3.0 address).",
+    },
+    "0xfb1bffc9d739b8d520daf37df666da4c687191ea": {
+        label: "Pharos SafeL2 Singleton (GnosisSafeL2 v1.3.0)",
+        standard: "SafeL2",
+        category: "smart-account",
+        deterministic: false,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "SafeL2 smart-account singleton (emits L2 events); transactions execute via the Safe's owners/threshold.",
+        recommendedSafeHandsBehavior: "Recognize as the canonical SafeL2 singleton on Pacific Mainnet; Safe execTransaction / MultiSend batch contents are decoded separately (experimental).",
+        note: "Pharos-specific deployment address (differs from the standard-Ethereum SafeL2 1.3.0 address).",
+    },
+    "0x998739bfdaadde7c933b942a68053933098f9eda": {
+        label: "Pharos Safe MultiSend (v1.3.0)",
+        standard: "MultiSend",
+        category: "batching",
+        deterministic: false,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "Batches multiple calls within a Safe transaction; the inner calls determine the real risk.",
+        recommendedSafeHandsBehavior: "Recognize as the canonical MultiSend on Pacific Mainnet; decode the batch's inner calls before trusting it (experimental).",
+        note: "Pharos-specific deployment address (differs from the standard-Ethereum MultiSend 1.3.0 address).",
+    },
+    "0xba5ed099633d3b313e4d5f7bdc1305d3c28ba5ed": {
+        label: "CreateX Factory",
+        standard: "CreateX",
+        category: "deployer",
+        deterministic: false,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "Deterministic contract-deployment factory (CREATE2/CREATE3); can deploy arbitrary contracts.",
+        recommendedSafeHandsBehavior: "Recognize as the canonical CreateX deployer on Pacific Mainnet; deployment payloads are not decoded; treat the action as REQUIRE_CONFIRMATION.",
+        note: "Listed for Pacific Mainnet in the Pharos canonical-contracts page; Atlantic deployment not asserted.",
+    },
+    "0x13b0d85ccb8bf860b6b79af3029fca081ae9bef2": {
+        label: "Create2Deployer",
+        standard: "Create2Deployer",
+        category: "deployer",
+        deterministic: true,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "CREATE2 contract-deployment factory; can deploy arbitrary contracts at deterministic addresses.",
+        recommendedSafeHandsBehavior: "Recognize as canonical deployer infrastructure; deployment payloads are not decoded; treat the action as REQUIRE_CONFIRMATION.",
+    },
+    "0x4e59b44847b379578588920ca78fbf26c0b4956c": {
+        label: "Foundry Deterministic Deployment Proxy",
+        standard: "DeterministicDeploymentProxy",
+        category: "deployer",
+        deterministic: true,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "Deterministic deployment proxy used by Foundry tooling; can deploy arbitrary contracts.",
+        recommendedSafeHandsBehavior: "Recognize as canonical deployer infrastructure; deployment payloads are not decoded; treat the action as REQUIRE_CONFIRMATION.",
+    },
+    "0x914d7fec6aac8cd542e72bca78b30650d45643d7": {
+        label: "Safe Singleton Factory",
+        standard: "SafeSingletonFactory",
+        category: "deployer",
+        deterministic: true,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "Deterministic factory used to deploy Safe singletons; can deploy arbitrary contracts.",
+        recommendedSafeHandsBehavior: "Recognize as canonical deployer infrastructure; deployment payloads are not decoded; treat the action as REQUIRE_CONFIRMATION.",
+    },
+    "0xa1dabef33b3b82c7814b6d82a79e50f4ac44102b": {
+        label: "Safe MultiSendCallOnly (v1.3.0)",
+        standard: "MultiSendCallOnly",
+        category: "batching",
+        deterministic: true,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "Batches multiple CALLs within a Safe transaction (no delegatecall); the inner calls determine the real risk.",
+        recommendedSafeHandsBehavior: "Recognize as canonical batching contract; decode the batch's inner calls before trusting it (experimental).",
+    },
+    "0xefc2c1444ebcc4db75e7613d20c6a62ff67a167c": {
+        label: "ERC-4337 SenderCreator v0.7",
+        standard: "ERC4337SenderCreator",
+        category: "account-abstraction",
+        deterministic: true,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "ERC-4337 helper that deploys smart accounts on first UserOperation.",
+        recommendedSafeHandsBehavior: "Recognize as canonical account-abstraction infrastructure; account initcode is not decoded; treat the action as REQUIRE_CONFIRMATION.",
+    },
+    "0x7fc98430eaedbb6070b35b39d798725049088348": {
+        label: "ERC-4337 SenderCreator v0.6",
+        standard: "ERC4337SenderCreator",
+        category: "account-abstraction",
+        deterministic: true,
+        source: "official_docs",
+        status: "implemented",
+        riskRelevance: "ERC-4337 helper that deploys smart accounts on first UserOperation.",
+        recommendedSafeHandsBehavior: "Recognize as canonical account-abstraction infrastructure; account initcode is not decoded; treat the action as REQUIRE_CONFIRMATION.",
+    },
+};
+export const CANONICAL_CONTRACTS = Object.fromEntries(Object.entries(CANONICAL_CONTRACT_METADATA).map(([address, entry]) => [
+    address,
+    { ...entry, networks: networksFor(address) },
+]));
+/**
+ * Raw, network-agnostic lookup by address (returns the entry if the address is a
+ * known canonical contract on ANY network). Kept for back-compat with spender /
+ * allowance recognition. Use {@link canonicalContractEvidence} for per-network
+ * recognition.
+ */
+export function lookupCanonical(address) {
+    if (!isAddress(address))
+        return undefined;
+    return CANONICAL_CONTRACTS[address.toLowerCase()];
+}
+/**
+ * Per-network canonical recognition evidence. Returns evidence ONLY when the
+ * address is a known canonical contract recognized on `network`. A known address
+ * that is not recognized on this network (e.g. a Pacific-only Safe address while
+ * the active network is Atlantic) returns `null` — fail-safe under-recognition,
+ * never a false positive. Recognition is metadata, not a safety guarantee.
+ */
+export function canonicalContractEvidence(address, network = getActiveNetwork()) {
+    const entry = lookupCanonical(address);
+    if (!entry || !entry.networks.includes(network.name))
+        return null;
+    return {
+        name: entry.label,
+        category: entry.category,
+        standard: entry.standard,
+        network: network.name,
+        chainId: network.chainId,
+        address: getAddress(address),
+        deterministic: entry.deterministic,
+        source: entry.source,
+        status: entry.status,
+        riskRelevance: entry.riskRelevance,
+        recommendedSafeHandsBehavior: entry.recommendedSafeHandsBehavior,
+    };
+}
+export async function analyzeContract(address, access) {
+    const reasons = [];
+    const warnings = [];
+    const network = getActiveNetwork();
+    if (!isAddress(address)) {
+        return makeResult({
+            analyzer: "contract_intel",
+            decision: "BLOCK",
+            internalDecision: "BLOCK",
+            riskLevel: "CRITICAL",
+            reasons: ["Not a valid EVM address."],
+            warnings: [],
+            analyzerStatus: "ok",
+            details: { address: null, recognized: false, label: null, standard: null, recognitionSource: "none", sourceVerified: false, canonicalContractEvidence: null, network: network.name, chainId: network.chainId, codePresent: "unknown", isContract: "unknown" },
+        });
+    }
+    const checksum = getAddress(address);
+    const knownEntry = lookupCanonical(address);
+    const evidence = canonicalContractEvidence(checksum, network);
+    const recognizedOnNetwork = evidence !== null;
+    let codePresent = "unknown";
+    if (access?.getCode) {
+        try {
+            const code = await access.getCode(checksum);
+            codePresent = !(code === undefined || code === null || code === "0x" || code === "");
+        }
+        catch {
+            codePresent = "unknown";
+        }
+    }
+    const isContract = codePresent;
+    let internalDecision;
+    let riskLevel;
+    if (recognizedOnNetwork && evidence) {
+        reasons.push(`Address matches the canonical ${evidence.name} address on ${network.label} (recognized by address; deployment/verification on the active network is NOT confirmed).`);
+        if (codePresent === false)
+            warnings.push("No code found at this canonical address on the active network; it may not be deployed here.");
+        internalDecision = "ALLOW";
+        riskLevel = "LOW";
+    }
+    else if (knownEntry) {
+        // Known canonical address, but not recognized on the ACTIVE network — do not auto-allow.
+        reasons.push(`Address matches the canonical ${knownEntry.label} address, but that contract is not recognized on ${network.label}; treat as an unknown contract and confirm.`);
+        if (knownEntry.note)
+            warnings.push(knownEntry.note);
+        internalDecision = "REQUIRE_CONFIRMATION";
+        riskLevel = "MEDIUM";
+    }
+    else if (codePresent === true) {
+        reasons.push(`Contract at ${checksum} is not a recognized canonical contract; unknown contract requires confirmation.`);
+        internalDecision = "REQUIRE_CONFIRMATION";
+        riskLevel = "MEDIUM";
+    }
+    else if (codePresent === false) {
+        reasons.push(`No code at ${checksum} (EOA), not a contract.`);
+        internalDecision = "ALLOW";
+        riskLevel = "LOW";
+    }
+    else {
+        reasons.push(`Code presence for ${checksum} not verified (no read-only client); treat unknown contracts with confirmation.`);
+        warnings.push("Provide a read-only RPC client to confirm code presence.");
+        internalDecision = "REQUIRE_CONFIRMATION";
+        riskLevel = "UNKNOWN";
+    }
+    return makeResult({
+        analyzer: "contract_intel",
+        decision: internalDecision,
+        internalDecision,
+        riskLevel,
+        reasons,
+        warnings,
+        analyzerStatus: codePresent === "unknown" ? "partial" : "ok",
+        details: {
+            address: checksum,
+            recognized: recognizedOnNetwork,
+            label: evidence?.name ?? knownEntry?.label ?? null,
+            standard: evidence?.standard ?? knownEntry?.standard ?? null,
+            recognitionSource: recognizedOnNetwork ? "canonical-address" : "none",
+            sourceVerified: false,
+            canonicalContractEvidence: evidence,
+            network: network.name,
+            chainId: network.chainId,
+            codePresent,
+            isContract,
+        },
+    });
+}
+//# sourceMappingURL=contractIntel.js.map

package/dist/lib/analysis/contractIntel.js.map

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

package/dist/lib/analysis/evm.d.ts

@@ -0,0 +1,42 @@
+import { type CanonicalContractEvidence } from "./contractIntel.js";
+import { type AnalyzerResult, type ReadOnlyChainAccess } from "./types.js";
+export type EvmTargetType = "EOA" | "contract" | "unknown";
+export type EvmCallClass = "native_transfer" | "contract_call" | "calldata_to_eoa" | "empty" | "invalid";
+export interface EvmCallInput {
+    to?: string;
+    /** Calldata, e.g. 0x095ea7b3... */
+    data?: string;
+    /** Value as a decimal or hex string (wei). */
+    value?: string;
+    chainId?: number;
+}
+export interface EvmAnalysisDetails {
+    to: string | null;
+    toValid: boolean;
+    hasCalldata: boolean;
+    selector: string | null;
+    valueProvided: boolean;
+    valueIsPositive: boolean;
+    isNativeValueTransfer: boolean;
+    targetType: EvmTargetType;
+    callClass: EvmCallClass;
+    chainId: number | null;
+    /** Per-network canonical recognition of `to` (null when not a known canonical). */
+    canonicalContractEvidence: CanonicalContractEvidence | null;
+}
+/** Classify a target address as EOA / contract / unknown using read-only eth_getCode. */
+export declare function classifyTarget(address: string, access?: ReadOnlyChainAccess): Promise<EvmTargetType>;
+export declare function analyzeEvmCall(input: EvmCallInput, access?: ReadOnlyChainAccess): Promise<AnalyzerResult<EvmAnalysisDetails>>;
+export interface EvmTxReceiptDetails {
+    txHash: string;
+    status: "success" | "reverted" | "unknown";
+    blockNumber: string | null;
+    gasUsed: string | null;
+}
+/**
+ * Optional existing-transaction analysis via read-only eth_getTransactionReceipt.
+ * Returns analyzerStatus "unavailable" when no read-only client is supplied
+ * (keeps offline use safe). Never sends a transaction.
+ */
+export declare function analyzeTxHash(txHash: string, access?: ReadOnlyChainAccess): Promise<AnalyzerResult<EvmTxReceiptDetails>>;
+//# sourceMappingURL=evm.d.ts.map

package/dist/lib/analysis/evm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm.d.ts","sourceRoot":"","sources":["../../../src/lib/analysis/evm.ts"],"names":[],"mappings":"AAMA,OAAO,EAA6B,KAAK,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,EAAc,KAAK,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEvF,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3D,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,eAAe,GACf,iBAAiB,GACjB,OAAO,GACP,SAAS,CAAC;AAEd,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,UAAU,EAAE,aAAa,CAAC;IAC1B,SAAS,EAAE,YAAY,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mFAAmF;IACnF,yBAAyB,EAAE,yBAAyB,GAAG,IAAI,CAAC;CAC7D;AAyBD,yFAAyF;AACzF,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CASxB;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,YAAY,EACnB,MAAM,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC,CA2F7C;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAC3C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC,CA6C9C"}

package/dist/lib/analysis/evm.js

@@ -0,0 +1,185 @@
+// ─── EVM Call Analyzer (read-only) ─────────────────────────────────────
+// Analyzes `to + calldata + value` (and, optionally, an existing tx hash) using
+// only read-only JSON-RPC. Never executes, never sends a transaction.
+// ────────────────────────────────────────────────────────────────────────
+import { isAddress } from "viem";
+import { canonicalContractEvidence } from "./contractIntel.js";
+import { makeResult } from "./types.js";
+function valueInfo(value) {
+    if (value === undefined || value === null || String(value).trim() === "") {
+        return { provided: false, positive: false };
+    }
+    const s = String(value).trim();
+    try {
+        return { provided: true, positive: BigInt(s) > 0n };
+    }
+    catch {
+        const n = Number(s);
+        return { provided: true, positive: Number.isFinite(n) && n > 0 };
+    }
+}
+function hasCalldata(data) {
+    return typeof data === "string" && data !== "0x" && data.replace(/^0x/, "").length > 0;
+}
+function selectorOf(data) {
+    if (!data)
+        return null;
+    const hex = data.startsWith("0x") ? data : `0x${data}`;
+    return hex.length >= 10 ? hex.slice(0, 10).toLowerCase() : null;
+}
+/** Classify a target address as EOA / contract / unknown using read-only eth_getCode. */
+export async function classifyTarget(address, access) {
+    if (!isAddress(address) || !access?.getCode)
+        return "unknown";
+    try {
+        const code = await access.getCode(address);
+        if (code === undefined || code === null || code === "0x" || code === "")
+            return "EOA";
+        return "contract";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export async function analyzeEvmCall(input, access) {
+    const reasons = [];
+    const warnings = [];
+    const to = input.to ?? null;
+    const toValid = to === null ? true : isAddress(to);
+    const calldata = hasCalldata(input.data);
+    const selector = calldata ? selectorOf(input.data) : null;
+    const { provided: valueProvided, positive: valueIsPositive } = valueInfo(input.value);
+    const isNativeValueTransfer = valueIsPositive && !calldata;
+    const toCanonical = to && toValid ? canonicalContractEvidence(to) : null;
+    const targetType = to && toValid ? await classifyTarget(to, access) : "unknown";
+    let callClass;
+    let internalDecision;
+    let riskLevel;
+    if (to !== null && !toValid) {
+        callClass = "invalid";
+        internalDecision = "BLOCK";
+        riskLevel = "CRITICAL";
+        reasons.push(`Target address is not a valid EVM address (${to}).`);
+    }
+    else if (!calldata && !valueIsPositive) {
+        callClass = "empty";
+        internalDecision = "REQUIRE_CONFIRMATION";
+        riskLevel = "MEDIUM";
+        reasons.push("No calldata and no value: empty / no-op transaction.");
+    }
+    else if (isNativeValueTransfer) {
+        callClass = "native_transfer";
+        if (targetType === "contract") {
+            internalDecision = "REQUIRE_CONFIRMATION";
+            riskLevel = "MEDIUM";
+            reasons.push("Native value sent to a contract with no calldata; may trigger a fallback/receive function.");
+        }
+        else if (targetType === "EOA") {
+            internalDecision = "ALLOW";
+            riskLevel = "LOW";
+            reasons.push("Plain native value transfer to an EOA.");
+        }
+        else {
+            // targetType === "unknown": recipient code could NOT be verified (RPC down /
+            // no read-only client). Fail-closed — a security layer must not ALLOW when it
+            // cannot rule out a hostile contract recipient. Ask for confirmation instead.
+            internalDecision = "REQUIRE_CONFIRMATION";
+            riskLevel = "MEDIUM";
+            reasons.push("Native value transfer with unverifiable recipient code; confirm the recipient before sending.");
+            warnings.push("Recipient code could not be verified (no read-only client).");
+        }
+    }
+    else if (calldata) {
+        if (targetType === "EOA") {
+            callClass = "calldata_to_eoa";
+            internalDecision = "REQUIRE_CONFIRMATION";
+            riskLevel = "MEDIUM";
+            warnings.push("Calldata sent to an address with no code (EOA); the call will not execute contract logic.");
+        }
+        else {
+            callClass = "contract_call";
+            internalDecision = "REQUIRE_CONFIRMATION";
+            riskLevel = "MEDIUM";
+            reasons.push(targetType === "contract"
+                ? `Contract call to ${to} (selector ${selector ?? "n/a"}); unknown contract call requires confirmation.`
+                : `Contract call (selector ${selector ?? "n/a"}); target code not verified; requires confirmation.`);
+            if (targetType === "unknown")
+                warnings.push("Target code could not be verified (no read-only client).");
+        }
+    }
+    else {
+        callClass = "empty";
+        internalDecision = "REQUIRE_CONFIRMATION";
+        riskLevel = "MEDIUM";
+    }
+    return makeResult({
+        analyzer: "evm",
+        decision: internalDecision === "BLOCK" ? "BLOCK" : internalDecision === "ALLOW" ? "ALLOW" : "REQUIRE_CONFIRMATION",
+        internalDecision,
+        riskLevel,
+        reasons,
+        warnings,
+        analyzerStatus: targetType === "unknown" && (calldata || isNativeValueTransfer) ? "partial" : "ok",
+        details: {
+            to,
+            toValid,
+            hasCalldata: calldata,
+            selector,
+            valueProvided,
+            valueIsPositive,
+            isNativeValueTransfer,
+            targetType,
+            callClass,
+            chainId: input.chainId ?? null,
+            canonicalContractEvidence: toCanonical,
+        },
+    });
+}
+/**
+ * Optional existing-transaction analysis via read-only eth_getTransactionReceipt.
+ * Returns analyzerStatus "unavailable" when no read-only client is supplied
+ * (keeps offline use safe). Never sends a transaction.
+ */
+export async function analyzeTxHash(txHash, access) {
+    const base = (status, details, reasons, warnings = []) => makeResult({
+        analyzer: "evm_tx",
+        decision: "REQUIRE_CONFIRMATION",
+        internalDecision: "REQUIRE_CONFIRMATION",
+        riskLevel: "UNKNOWN",
+        reasons,
+        warnings,
+        analyzerStatus: status,
+        details,
+    });
+    if (!/^0x[0-9a-fA-F]{64}$/.test(txHash)) {
+        return makeResult({
+            analyzer: "evm_tx",
+            decision: "BLOCK",
+            internalDecision: "BLOCK",
+            riskLevel: "CRITICAL",
+            reasons: ["Invalid transaction hash."],
+            warnings: [],
+            analyzerStatus: "ok",
+            details: { txHash, status: "unknown", blockNumber: null, gasUsed: null },
+        });
+    }
+    if (!access?.getTransactionReceipt) {
+        return base("unavailable", { txHash, status: "unknown", blockNumber: null, gasUsed: null }, ["Receipt analysis requires a read-only RPC client."]);
+    }
+    try {
+        const r = (await access.getTransactionReceipt(txHash));
+        if (!r)
+            return base("unavailable", { txHash, status: "unknown", blockNumber: null, gasUsed: null }, ["Transaction not found or not yet mined."]);
+        const status = r.status === "success" ? "success" : r.status === "reverted" ? "reverted" : "unknown";
+        return base("ok", {
+            txHash,
+            status,
+            blockNumber: r.blockNumber !== undefined ? r.blockNumber.toString() : null,
+            gasUsed: r.gasUsed !== undefined ? r.gasUsed.toString() : null,
+        }, [status === "reverted" ? "Transaction reverted on-chain." : "Transaction receipt retrieved."]);
+    }
+    catch {
+        return base("unavailable", { txHash, status: "unknown", blockNumber: null, gasUsed: null }, ["Could not read transaction receipt."]);
+    }
+}
+//# sourceMappingURL=evm.js.map

package/dist/lib/analysis/evm.js.map

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

package/dist/lib/analysis/gas.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_GAS_BUFFER_PCT = 20;
+/** Apply a buffer percentage to a raw gas estimate (integer math). */
+export declare function recommendGasWithBuffer(estimate: bigint, bufferPct?: number): bigint;
+//# sourceMappingURL=gas.d.ts.map

package/dist/lib/analysis/gas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas.d.ts","sourceRoot":"","sources":["../../../src/lib/analysis/gas.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,sEAAsE;AACtE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAA+B,GAAG,MAAM,CAG3G"}

package/dist/lib/analysis/gas.js

@@ -0,0 +1,13 @@
+// ─── Gas buffering helpers (read-only) ─────────────────────────────────
+// Shared gas-limit buffering used by the estimate_gas / simulate_transaction
+// tools and RPC evidence. Never submits a transaction.
+// (A full `analyzeGas` analyzer lived here until 2026-07: zero call sites, no
+// surface, no tests — removed per the dead-code policy; see git history.)
+// ────────────────────────────────────────────────────────────────────────
+export const DEFAULT_GAS_BUFFER_PCT = 20;
+/** Apply a buffer percentage to a raw gas estimate (integer math). */
+export function recommendGasWithBuffer(estimate, bufferPct = DEFAULT_GAS_BUFFER_PCT) {
+    const pct = BigInt(Math.max(0, Math.trunc(bufferPct)));
+    return estimate + (estimate * pct) / 100n;
+}
+//# sourceMappingURL=gas.js.map

package/dist/lib/analysis/gas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas.js","sourceRoot":"","sources":["../../../src/lib/analysis/gas.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6EAA6E;AAC7E,uDAAuD;AACvD,8EAA8E;AAC9E,0EAA0E;AAC1E,2EAA2E;AAE3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC,sEAAsE;AACtE,MAAM,UAAU,sBAAsB,CAAC,QAAgB,EAAE,YAAoB,sBAAsB;IACjG,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACvD,OAAO,QAAQ,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC;AAC5C,CAAC"}

package/dist/lib/analysis/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./types.js";
+export * from "./evm.js";
+export * from "./token.js";
+export * from "./pharosTokens.js";
+export * from "./gas.js";
+export * from "./contractIntel.js";
+export * from "./approval.js";
+export * from "./calldata.js";
+export * from "./safeTx.js";
+export * from "./x402.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/analysis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/analysis/index.ts"],"names":[],"mappings":"AAMA,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}

package/dist/lib/analysis/index.js

@@ -0,0 +1,16 @@
+// ─── SafeHands Read-Only Analyzers ─────────────────────────────────────
+// Shared, read-only analysis used by MCP tools (and, later, API/Web/SDK/CLI).
+// Every analyzer is read-only and returns the public four-value SafeHands
+// decision plus internal detail for explanation. No analyzer signs or writes.
+// ────────────────────────────────────────────────────────────────────────
+export * from "./types.js";
+export * from "./evm.js";
+export * from "./token.js";
+export * from "./pharosTokens.js";
+export * from "./gas.js";
+export * from "./contractIntel.js";
+export * from "./approval.js";
+export * from "./calldata.js";
+export * from "./safeTx.js";
+export * from "./x402.js";
+//# sourceMappingURL=index.js.map