@hexora/address-guard 1.0.0

package/dist/checkAddress.d.ts

@@ -0,0 +1,3 @@
+import type { CheckAddressParams, CheckResult } from "./types.js";
+export declare function checkAddress(params: CheckAddressParams): Promise<CheckResult>;
+//# sourceMappingURL=checkAddress.d.ts.map

package/dist/checkAddress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkAddress.d.ts","sourceRoot":"","sources":["../src/checkAddress.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAOlE,wBAAsB,YAAY,CAChC,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,WAAW,CAAC,CAkGtB"}

package/dist/checkAddress.js

@@ -0,0 +1,79 @@
+import { detectProvider, validateAddress, findMostSimilar, DefaultHistoryProvider, txCache, } from "@hexora/core";
+import { analyzeInputAddress, analyzeUserHistory } from "./detector.js";
+import { buildResult, buildErrorResult } from "./scorer.js";
+const DEFAULT_HISTORY_LIMIT = 20;
+const DEFAULT_SIMILARITY_THRESHOLD = 85;
+export async function checkAddress(params) {
+    const { userAddress, inputAddress, provider, historyProvider, historyLimit = DEFAULT_HISTORY_LIMIT, similarityThreshold = DEFAULT_SIMILARITY_THRESHOLD, dustThreshold, apiKeys = {}, } = params;
+    // Step 1: detect provider, resolve chain
+    let chain;
+    try {
+        chain = await detectProvider(provider).chainId();
+    }
+    catch (err) {
+        const e = err;
+        return buildErrorResult(e.hexoraCode ?? "unknown", e.message ?? "Failed to detect provider");
+    }
+    // Step 2: validate addresses
+    if (!validateAddress(userAddress, chain))
+        return buildErrorResult("invalid_address", `userAddress "${userAddress}" is not valid for chain "${chain}"`, chain);
+    if (!validateAddress(inputAddress, chain))
+        return buildErrorResult("invalid_address", `inputAddress "${inputAddress}" is not valid for chain "${chain}"`, chain);
+    // Step 3: fetch history (in-memory cache, 5 min TTL)
+    const fetcher = historyProvider ?? new DefaultHistoryProvider(apiKeys);
+    let userHistory = [];
+    let inputAddrHistory = [];
+    try {
+        const cached = txCache.get(userAddress, chain);
+        const [userTxs, inputTxs] = await Promise.all([
+            cached
+                ? Promise.resolve(cached)
+                : fetcher.getTransactions(userAddress, chain, Math.min(historyLimit, 50)),
+            fetcher.getTransactions(inputAddress, chain, 50),
+        ]);
+        if (!cached)
+            txCache.set(userAddress, chain, userTxs);
+        userHistory = userTxs;
+        inputAddrHistory = inputTxs;
+    }
+    catch {
+        /* continue with empty history */
+    }
+    // Step 4: similarity check
+    const known = extractKnownAddresses(userHistory, userAddress);
+    const match = findMostSimilar(inputAddress, known, similarityThreshold);
+    // Step 5: analyze user history for injected poison
+    const histAnalysis = analyzeUserHistory(inputAddress, userHistory, userAddress);
+    // Step 6: analyze input address on-chain behavior
+    const inputAnalysis = analyzeInputAddress(inputAddress, inputAddrHistory, dustThreshold);
+    // Step 7: combine signals
+    return buildResult({
+        chain,
+        userAddress,
+        inputAddress,
+        historyScanned: userHistory.length,
+        similarityScore: match?.similarityScore ?? 0,
+        matchedAddress: match?.address ?? null,
+        zeroValueFound: histAnalysis.zeroValueFound,
+        batchPoisonFound: histAnalysis.batchPoisonFound,
+        dustFound: histAnalysis.dustFound,
+        transferFromFound: histAnalysis.transferFromFound,
+        inputAddrDetection: {
+            detected: inputAnalysis.detected,
+            reason: inputAnalysis.reason,
+            confidence: inputAnalysis.confidence,
+        },
+    });
+}
+function extractKnownAddresses(history, userAddress) {
+    const lower = userAddress.toLowerCase();
+    const seen = new Set();
+    for (const tx of history) {
+        if (tx.from === lower && tx.to)
+            seen.add(tx.to);
+        if (tx.to === lower && tx.from && !tx.isZeroValue)
+            seen.add(tx.from);
+    }
+    return Array.from(seen);
+}
+//# sourceMappingURL=checkAddress.js.map

package/dist/checkAddress.js.map

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

package/dist/detector.d.ts

@@ -0,0 +1,17 @@
+import type { NormalizedTransaction, ScamReason } from "@hexora/core";
+export declare const DEFAULT_DUST_THRESHOLD = 10000000000000n;
+export interface DetectionResult {
+    detected: boolean;
+    reason: ScamReason | null;
+    confidence: number;
+    evidence: string[];
+}
+export declare function analyzeInputAddress(inputAddress: string, inputAddrHistory: NormalizedTransaction[], dustThreshold?: bigint): DetectionResult;
+export declare function analyzeUserHistory(inputAddress: string, userHistory: NormalizedTransaction[], userAddress: string): {
+    zeroValueFound: boolean;
+    batchPoisonFound: boolean;
+    dustFound: boolean;
+    transferFromFound: boolean;
+    evidence: string[];
+};
+//# sourceMappingURL=detector.d.ts.map

package/dist/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../src/detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAEtE,eAAO,MAAM,sBAAsB,kBAAsB,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,qBAAqB,EAAE,EACzC,aAAa,GAAE,MAA+B,GAC7C,eAAe,CA2DjB;AAED,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,qBAAqB,EAAE,EACpC,WAAW,EAAE,MAAM,GAClB;IACD,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAqCA"}

package/dist/detector.js

@@ -0,0 +1,78 @@
+export const DEFAULT_DUST_THRESHOLD = 10000000000000n; // 0.00001 ETH in wei
+export function analyzeInputAddress(inputAddress, inputAddrHistory, dustThreshold = DEFAULT_DUST_THRESHOLD) {
+    const evidence = [];
+    let maxConfidence = 0;
+    let reason = null;
+    const addr = inputAddress.toLowerCase();
+    const batchTxs = inputAddrHistory.filter((tx) => tx.isBatchPoison);
+    if (batchTxs.length > 0) {
+        evidence.push(`Address executed ${batchTxs.length} batch poisoning transaction(s) with zero-value token transfers`);
+        maxConfidence = Math.max(maxConfidence, 98);
+        reason = "batch_poisoning";
+    }
+    const zeroSent = inputAddrHistory.filter((tx) => tx.isZeroValue && tx.from === addr);
+    if (zeroSent.length >= 2) {
+        evidence.push(`Address sent ${zeroSent.length} zero-value token transfers`);
+        maxConfidence = Math.max(maxConfidence, 90);
+        if (!reason)
+            reason = "zero_value_transfer";
+    }
+    const dustSent = inputAddrHistory.filter((tx) => tx.from === addr &&
+        !tx.isZeroValue &&
+        tx.value > 0n &&
+        tx.value < dustThreshold);
+    const uniqueTargets = new Set(dustSent.map((tx) => tx.to)).size;
+    if (uniqueTargets >= 5) {
+        evidence.push(`Address sent dust to ${uniqueTargets} unique addresses`);
+        maxConfidence = Math.max(maxConfidence, 85);
+        if (!reason)
+            reason = "dust_attack";
+    }
+    if (inputAddrHistory.length > 0) {
+        const firstTx = Math.min(...inputAddrHistory.map((tx) => tx.timestamp));
+        const ageDays = (Date.now() / 1000 - firstTx) / 86400;
+        const onlyOut = inputAddrHistory.every((tx) => tx.from === addr || tx.isBatchPoison);
+        if (ageDays < 30 && onlyOut && inputAddrHistory.length >= 3) {
+            evidence.push(`Address is ${Math.round(ageDays)} days old with only outgoing activity`);
+            maxConfidence = Math.max(maxConfidence, 75);
+            if (!reason)
+                reason = "new_suspicious_address";
+        }
+    }
+    return {
+        detected: evidence.length > 0,
+        reason,
+        confidence: maxConfidence,
+        evidence,
+    };
+}
+export function analyzeUserHistory(inputAddress, userHistory, userAddress) {
+    const evidence = [];
+    const inputLower = inputAddress.toLowerCase();
+    const userLower = userAddress.toLowerCase();
+    const fromInput = userHistory.filter((tx) => tx.from === inputLower);
+    const zeroValueFound = fromInput.some((tx) => tx.isZeroValue);
+    const batchPoisonFound = fromInput.some((tx) => tx.isBatchPoison);
+    const dustFound = fromInput.some((tx) => !tx.isZeroValue && tx.value > 0n && tx.value < DEFAULT_DUST_THRESHOLD);
+    const transferFromFound = userHistory.some((tx) => tx.from === userLower &&
+        tx.to === inputLower &&
+        tx.isZeroValue &&
+        tx.contractAddress !== undefined &&
+        tx.contractAddress !== userLower);
+    if (zeroValueFound)
+        evidence.push(`Incoming zero-value transfer from ${inputAddress}`);
+    if (batchPoisonFound)
+        evidence.push(`Batch poisoning transaction from ${inputAddress}`);
+    if (dustFound)
+        evidence.push(`Dust transaction received from ${inputAddress}`);
+    if (transferFromFound)
+        evidence.push(`transferFrom spoofing detected involving ${inputAddress}`);
+    return {
+        zeroValueFound,
+        batchPoisonFound,
+        dustFound,
+        transferFromFound,
+        evidence,
+    };
+}
+//# sourceMappingURL=detector.js.map

package/dist/detector.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { checkAddress } from "./checkAddress.js";
+export { DEFAULT_DUST_THRESHOLD } from "./detector.js";
+export type { CheckAddressParams, CheckResult, CheckDetails } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAEvD,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { checkAddress } from "./checkAddress.js";
+export { DEFAULT_DUST_THRESHOLD } from "./detector.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC"}

package/dist/scorer.d.ts

@@ -0,0 +1,22 @@
+import type { ChainId, ScamReason } from "@hexora/core";
+import type { CheckResult } from "./types.js";
+export interface ScorerInput {
+    chain: ChainId;
+    userAddress: string;
+    inputAddress: string;
+    historyScanned: number;
+    similarityScore: number;
+    matchedAddress: string | null;
+    zeroValueFound: boolean;
+    batchPoisonFound: boolean;
+    dustFound: boolean;
+    transferFromFound: boolean;
+    inputAddrDetection: {
+        detected: boolean;
+        reason: ScamReason | null;
+        confidence: number;
+    };
+}
+export declare function buildResult(input: ScorerInput): CheckResult;
+export declare function buildErrorResult(code: string, message: string, chain?: ChainId): CheckResult;
+//# sourceMappingURL=scorer.d.ts.map

package/dist/scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.d.ts","sourceRoot":"","sources":["../src/scorer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAyB,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAC;AAE5D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,kBAAkB,EAAE;QAClB,QAAQ,EAAE,OAAO,CAAC;QAClB,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;QAC1B,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAoD3D;AAUD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,OAAoB,GAC1B,WAAW,CAmBb"}

package/dist/scorer.js

@@ -0,0 +1,79 @@
+export function buildResult(input) {
+    const signals = [];
+    if (input.batchPoisonFound)
+        signals.push({ reason: "batch_poisoning", weight: 100 });
+    if (input.transferFromFound)
+        signals.push({ reason: "transferfrom_spoofing", weight: 95 });
+    if (input.zeroValueFound)
+        signals.push({ reason: "zero_value_transfer", weight: 90 });
+    if (input.inputAddrDetection.detected &&
+        input.inputAddrDetection.reason !== null)
+        signals.push({
+            reason: input.inputAddrDetection.reason,
+            weight: input.inputAddrDetection.confidence,
+        });
+    if (input.similarityScore >= 85)
+        signals.push({
+            reason: "address_poisoning",
+            weight: input.similarityScore,
+        });
+    if (input.dustFound)
+        signals.push({ reason: "dust_attack", weight: 70 });
+    signals.sort((a, b) => b.weight - a.weight);
+    const top = signals[0];
+    const riskScore = top?.weight ?? 0;
+    const confidence = signals.length > 1
+        ? Math.min(100, riskScore + signals.length * 3)
+        : riskScore;
+    const details = {
+        chain: input.chain,
+        userAddress: input.userAddress,
+        inputAddress: input.inputAddress,
+        historyScanned: input.historyScanned,
+        poisonTxFound: input.batchPoisonFound || input.transferFromFound,
+        zeroValueFound: input.zeroValueFound,
+        dustFound: input.dustFound,
+    };
+    return {
+        scam: top !== undefined && riskScore >= 70,
+        reason: top?.reason ?? null,
+        riskLevel: toRiskLevel(riskScore, signals.length),
+        similarityScore: input.similarityScore,
+        confidence,
+        matchedAddress: input.matchedAddress,
+        details,
+        error: null,
+    };
+}
+function toRiskLevel(score, count) {
+    if (score === 0)
+        return "none";
+    if (score < 50)
+        return "low";
+    if (score < 70)
+        return "medium";
+    if (score >= 90 || (score >= 80 && count >= 2))
+        return "critical";
+    return "high";
+}
+export function buildErrorResult(code, message, chain = "ethereum") {
+    return {
+        scam: false,
+        reason: null,
+        riskLevel: "none",
+        similarityScore: 0,
+        confidence: 0,
+        matchedAddress: null,
+        details: {
+            chain,
+            userAddress: "",
+            inputAddress: "",
+            historyScanned: 0,
+            poisonTxFound: false,
+            zeroValueFound: false,
+            dustFound: false,
+        },
+        error: { code: code, message },
+    };
+}
+//# sourceMappingURL=scorer.js.map

package/dist/scorer.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+import type { ChainId, RiskLevel, ScamReason, CheckError, HistoryProvider, RawProvider } from "@hexora/core";
+export interface CheckAddressParams {
+    userAddress: string;
+    inputAddress: string;
+    provider: RawProvider;
+    historyProvider?: HistoryProvider;
+    historyLimit?: number;
+    similarityThreshold?: number;
+    dustThreshold?: bigint;
+    apiKeys?: {
+        etherscan?: string;
+        bscscan?: string;
+        polygonscan?: string;
+    };
+}
+export interface CheckDetails {
+    chain: ChainId;
+    userAddress: string;
+    inputAddress: string;
+    historyScanned: number;
+    poisonTxFound: boolean;
+    zeroValueFound: boolean;
+    dustFound: boolean;
+}
+export interface CheckResult {
+    scam: boolean;
+    reason: ScamReason | null;
+    riskLevel: RiskLevel;
+    similarityScore: number;
+    confidence: number;
+    matchedAddress: string | null;
+    details: CheckDetails;
+    error: CheckError | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,UAAU,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACZ,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,WAAW,CAAC;IACtB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CAC1B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@hexora/address-guard",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@hexora/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "vitest": "^1.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "dev": "tsc --watch"
+  }
+}