Engineering Documentation & Algorithmic Methodology

How WalletGenome Computes On-Chain Intelligence

A clear breakdown of the core algorithms, data pipelines, and security checks powering WalletGenome's on-chain analysis.

The scanner currently examines observable public activity on four supported EVM networks: Ethereum, Base, Arbitrum, and Optimism. Provider gaps remain explicitly partial or unavailable in the report.

Open Live Scanner Read practical guides

Focused guides: EVM Wallet AnalyticsCrypto Wallet Risk CheckerToken Approval CheckerSybil Wallet AnalysisMulti-Chain Wallet Forensics

Filter documentation topics

11 documentation topics

TABLE OF CONTENTSMulti-Chain Pipeline & Rate-Resilient Data Gateway11 TOPICS

SECTION 01 · DATA PIPELINE

Multi-Chain Pipeline & Rate-Resilient Data Gateway

We use a dual-gateway system and caching to reduce the impact of provider rate limits and improve retrieval resilience.

DUAL-GATEWAY FAILOVER WORKFLOW

Client Request (Single or Cluster Batch) │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Priority 1: Open Blockscout REST APIs (No API Key) │ │ eth.blockscout.com / base.blockscout.com │ │ arbitrum.blockscout.com / optimism.blockscout │ └──────────────────────────────┬──────────────────────────────┘ │ (If failed or rate-limited) ▼ ┌─────────────────────────────────────────────────────────────┐ │ Priority 2: Etherscan V2 Multi-Chain Gateway │ │ api.etherscan.io/v2/api?chainid=... │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Parallel Enrichment Pipeline: │ │ • Daily Price + Explicit Spot-Estimate Provenance │ │ • Recognized Contract Labels + Price Provenance │ │ • Web3.bio Identity Graph Resolution (Async non-blocking) │ └─────────────────────────────────────────────────────────────┘

Concurrency

Fresh scans deduplicate assets before requesting current DefiLlama quotes. They do not request historical price ranges. Provider failures remain explicit partial or unavailable results.

Contract & price controls

Known contract labels and token-asset allowlists limit attribution and pricing inputs. Fresh scans use current market quotes, including for stablecoins; missing quotes remain unpriced. Saved snapshots retain their original price provenance.

SECTION 02 · NORMALIZATION & GAS

Calldata Decoding & Transaction Categorization Engine

Transactions are decoded and categorized into distinct semantic types using their method signatures and contract registries.

Category	Method IDs / Heuristic Signatures	Classification Rules
approval	`0x095ea7b3`, `approve()`	ERC-20 token allowance approvals to DEXs, bridges, or custom spenders.
bridge	`0xd2ce7d65`, `0xe9e05c42`, `0x0f5287e0`	Cross-chain bridging via Arbitrum Gateway, Optimism Portal, Across, Stargate, or Polygon.
swap	`exactInput`, `multicall`, `execute`	DEX trading across Uniswap, Sushiswap, Curve, Balancer, or 1inch routers.
lending	`supply`, `borrow`, `repay`	Money market operations on Aave, Compound, MakerDAO, or Morpho.
staking	`stake`, `unstake`, `delegate`	Liquid staking / delegation across Lido, Rocket Pool, or native validators.
nft	`mint`, `safeTransferFrom`	ERC-721 / ERC-1155 minting and marketplace trading on OpenSea, Blur, etc.
transfer	`input === '0x'`	Pure native ETH / BNB value transfer between EOA accounts.

GAS & LIFETIME FEE VALUATION FORMULA

Gas Cost (ETH) = (gasUsed × gasPrice) / 10^18

Gas Cost (USD estimate) = Gas Cost (Native) × Current Price

Fresh scans use recent current quotes for USD estimates. A gas fee paid years ago is shown at today’s native-token price, not its value when paid. If no reliable current quote is available, its USD estimate remains unavailable.

SECTION 03 · BEHAVIORAL FORENSICS

6-Dimension Behavioral Fingerprinting & Persona Modeling

Wallets are analyzed across 6 behavioral dimensions, each scored from 0 to 100.

1. DeFi Diversity0–100 PTS

Measures breadth of smart contracts and distinct protocols used.

2. Activity Intensity0–100 PTS

Evaluates transaction execution frequency.

3. Capital Efficiency0–100 PTS

Ratio of transferred economic value to gas fees consumed.

4. Risk Appetite0–100 PTS

Measures tolerance for unverified contracts and failed transactions.

5. Maturity0–100 PTS

Longevity from first transaction combined with active consistency.

6. Network Breadth0–100 PTS

Diversity of peers across native transactions and token transfers.

AUTOMATED PERSONA CLASSIFICATION DECISION TREE

DeFi Power User: UniqueContracts > 50 OR DeFi Diversity > 60. Multi-year on-chain presence with broad multi-protocol routing.

Active Trader: SwapCount > 40% of Txs AND Activity > 50. High-frequency DEX rotation.

NFT Collector: NFTCount > 30% of Txs. Heavy minting, marketplace trading, and collection transfers.

Bridge Heavy: BridgeCount > 20% of Txs. High cross-chain asset mobility across L1s/L2s.

Airdrop Farmer: Activity > 40 AND UniqueContracts < 10 AND Maturity < 12 mo. Scripted repetitive interactions.

Passive Whale / Cautious Holder: Activity < 20 AND Maturity > 50. Long-term capital storage.

SECTION 04 · SECURITY & AUDITING

Composite Security Risk Engine (Score 0–100 & Grades A–F)

The risk engine produces a 0–100 heuristic score, mapping observed configured factors to grades A, B, C, D, or F. It is a screening signal, not proof that a wallet is safe or compromised.

Risk Factor	Max Weight	Calculation Formula	Severity
1. High-Risk Unlimited Approvals	40 pts	min(40, HighRiskApprovals × 15)	Critical
1b. Known-Contract Unlimited Approvals	20 pts	min(20, UnlimitedCount × 3) if no high-risk approvals and UnlimitedCount > 3	Warning
2. Failed Transaction Ratio	25 pts	min(25, round(FailedRatio × 120)) if FailedRatio > 5%	Warning
3. Stale Approvals (>6 Months)	15 pts	min(15, StaleCount × 3) if StaleCount > 2	Warning
4. Unidentified Contract Ratio	10 pts	min(10, round(UnknownRatio × 20)) if UnknownRatio > 30% and UnknownCount > 5	Info

GRADE A

Score 0–15

GRADE B

Score 16–30

GRADE C

Score 31–50

GRADE D

Score 51–70

GRADE F

Score 71–100

SECTION 05 · SYBIL & BLACKLIST DEFENSE

Sybil Radar & Local MEDIA-style Behavioral Heuristic

Sybil defense checks configured list snapshots and computes a local MEDIA-style behavioral heuristic to surface patterns sometimes associated with scripted activity. This behavioral risk score is not a live Trusta score. A positive non-behavioral blacklist match overrides the overall clean/organic headline; the behavioral score remains a separate secondary heuristic.

1. LayerZero Sybil Database~800K+ ADDR · illustrative

Published community reports and algorithmic script-execution signals.

2. Hop Protocol Sybil DefenseGRAPH DEFENSE

Graph analysis flagging co-funded multi-sig parent roots.

3. Umbra Privacy Mixer ClustersSTEALTH POOLS

Identified stealth address routing clusters.

4. US Treasury OFAC SDNSANCTIONED

Specially Designated Nationals registry.

LOCAL MEDIA-STYLE HEURISTIC FORMULATION

MEDIA Composite Score = (0.25 × M) + (0.25 × E) + (0.20 × D) + (0.15 × I) + (0.15 × A)

Behavioral Sybil Risk = 100 - MEDIA-style Composite Score

M (Monetary): 25% weight. Volume tiers ($100 to $50k+) + gas burned bonus.

E (Engagement): 25% weight. Active months + bot burstiness penalty (>90% txs in <48h).

D (Diversity): 20% weight. Unique smart contract depth + multi-category breadth.

I (Identity): 15% weight. Multi-chain footprint (1 to 4 supported chains) + counterparty diversity.

A (Age): 15% weight. Lifespan maturity from genesis block (30d to 365d+).

SECTION 06 · TOKEN ALLOWANCES

ERC-20 Approval & Capital at Risk Exposure Engine

WalletGenome estimates approval exposure from the latest observed non-revoked approval states reconstructed from returned ERC-20 approval transactions, reconstructed token balances, and current token prices. This is not a live allowance query: a later on-chain change may not appear in returned history. It does not treat an unknown balance or price as zero exposure.

CALLDATA PARSING & BALANCE RECONSTRUCTION SPEC

1. Calldata Spender Extraction:
Byte slice input[34:74] = 20-byte spender contract address.
Byte slice input[74:138] = 32-byte uint256 allowance amount.

2. Allowance Classification:
• Unlimited: If amount starts with ffff... or equals $2^256-1$.
• Revoked: If amount equals 0x0.
• Custom: Specific finite integer allowance.

3. Net Holdings Reconstruction & Dollar Risk:

Reconstructed Token Balance = max(0, Σ(Inbound Transfers) - Σ(Outbound Transfers))

Exposed Units = min(Reconstructed Balance, Finite Allowance); unlimited approvals use the reconstructed balance.

Estimated Exposure (USD) = Exposed Units × Unit Price (USD)

Unknown balance or price = unavailable. A verified zero reconstructed balance is shown separately as zero balance.

SECTION 07 · CADENCE & STREAKS

24×7 Temporal Matrix & Continuous Streak Engine

Transaction times are mapped to a 24x7 matrix to identify bot patterns and timezone activity.

24×7 Heatmap Normalization

Intensity per cell (day, hour) is normalized against maximum hourly volume:
Intensity(d, h) = Count(d, h) / max(Count)

O(N) Daily Streak Algorithm

Calculates consecutive active transaction days by sorting calendar keys and measuring date deltas:
DeltaDays = (Time[i] - Time[i-1]) / 86400s

SECTION 08 · NETWORK TOPOLOGIES

Capital Flow Topology & Cluster Linkage Matrix

We visualize funds using Capital Flow Graphs for single addresses and Cluster Matrices for multiple wallets.

Cluster evidence rule

Direct links require a native, internal, or ERC-20 transfer whose source and target are both submitted wallets. Evidence is deduplicated by chain, transaction hash, direction, asset type, and asset identifier, then aggregated by source, target, and chain.

Every linkage retains unique evidence hashes, transaction count, direction, last date, and USD completeness. Shared counterparties are computed from the full evidence set; only rendering is truncated. These are observed direct-transfer and shared-counterparty signals, not proof of common control. The Arbitrum Foundation match is limited to published sample addresses and does not reproduce its full graph-based clustering model.

Graph Layout Mathematics:

1. Arkham 3-Column Topology:
• Column 1 (X=160): Inbound funding sources & CEX withdrawals.
• Column 2 (X=550): User core address.
• Column 3 (X=940): Destination DeFi protocols & recipient addresses.
• Line widths: Volume-weighted stroke W = min(8, 1.5 + log10(USD_Volume)).

2. Cluster Radial Orbital Layout:
• Orbital Radius: R = max(320, WalletCount × 24.5) px.
• Angle per wallet: theta = (2π × i / N) - π/2.
• Coordinates: X = Xc + R × cos(theta), Y = Yc + R × sin(theta).
• Shared Hubs placed at gravitational center with force links.

SECTION 09 · SOCIAL GRAPH

Decentralized Identity & Platform Priority Hierarchy

Available Web3 identities (like ENS and Farcaster) are resolved using Web3.bio, with the primary label selected by the configured platform priority order.

Platform	Priority Weight	Deep Link Resolution Format
ENS (.eth)	10 (Highest)	`https://app.ens.domains/{name}`
Farcaster (Warpcast)	9	`https://warpcast.com/{handle}`
Lens Protocol	8	`https://hey.xyz/u/{handle}`
BaseNames (.base.eth)	7	`https://base.org/names?query={name}`
Unstoppable Domains	6	`https://unstoppabledomains.com`

CANONICAL API CONTRACT

Reporting metric definitions

In plain language: flow fields describe value that entered or left, risk fields describe a heuristic rather than a loss probability, and approval exposure estimates value covered by the latest observed approvals rather than a live allowance. Missing history or price inputs stay partial or unavailable instead of being guessed.

These definitions are imported from the same contract used by API responses and dashboard labels. Use the stable field anchors in the table when linking to an exact definition; USD metrics are withheld when their required provider or price inputs are incomplete.

Field	Unit / window	Sources and rules	Completeness / pricing
`inflowUSD` Inflow	USD Full history returned by the selected explorers.	Successful native, internal, and ERC-20 transfers to the scanned wallet. Includes inbound transfer legs with a reliable current quote; excludes failed and unpriced legs. Sum across selected chains; each transfer leg is counted once.	Publishes a current-price subtotal when history is complete and at least one eligible leg is priced; missing quotes reduce coverage. Current market quotes, including stablecoins, for fresh scans. Unpriced legs are excluded and reported in capitalFlowCoverage.
`outflowUSD` Outflow	USD Full history returned by the selected explorers.	Successful native, internal, and ERC-20 transfers from the scanned wallet. Includes outbound transfer legs with a reliable current quote; excludes failed and unpriced legs. Sum across selected chains; each transfer leg is counted once.	Publishes a current-price subtotal when history is complete and at least one eligible leg is priced; missing quotes reduce coverage. Current market quotes, including stablecoins, for fresh scans. Unpriced legs are excluded and reported in capitalFlowCoverage.
`netFlowUSD` Net flow	USD Same window as inflowUSD and outflowUSD.	Canonical inflowUSD and outflowUSD fields. No additional records are introduced. inflowUSD minus outflowUSD.	Available when both current-price flow subtotals are available; inherits their partial coverage status. Combined provenance of the inflow and outflow inputs.
`grossVolumeUSD` Gross transfer volume	USD Same window as inflowUSD and outflowUSD.	Canonical inflowUSD and outflowUSD fields. Counts both directions; it is not net flow or portfolio value. inflowUSD plus outflowUSD.	Available when both current-price flow subtotals are available; inherits their partial coverage status. Combined provenance of the inflow and outflow inputs.
`protocolVolumeUSD` Protocol interaction volume	USD Full history returned by the selected explorers.	Priced transfer legs correlated to recognized protocol transactions and contracts. Excludes unpriced legs and ordinary counterparty transfers. Sum by protocol contract and chain, then across chains without removing chain provenance.	Unavailable unless transaction, transfer, and price inputs are complete. Current quotes for fresh scans; unavailable when required quotes are missing.
`approvalExposureUSD` Estimated approval exposure	USD Latest observed approval state in returned history.	Latest non-revoked observed ERC-20 approvals, reconstructed token balances, and current token prices. Includes priced positive balances for latest non-revoked observed approvals; revoked, zero-balance, and unpriced exposure are not converted to zero proof. Sum of per-approval estimated exposure across selected chains.	Unavailable when any latest non-revoked observed approval balance or required price is unknown. Current spot quote, stablecoin assumption, or unpriced when no current quote is available.
`riskScore` Worst-chain risk score	score_0_100 Full history returned by the selected explorers.	The documented approval, failure, stale-approval, and unknown-contract factors. Higher is riskier; this is a heuristic, not a loss probability. Maximum chain risk score across selected chains.	Unavailable when wallet history is incomplete. Not applicable.
`riskGrade` Worst-chain risk grade	grade Same window as riskScore.	Canonical riskScore. Grades A, B, C, D, and F map to documented score thresholds. Grade derived from the maximum chain risk score.	Unavailable when wallet history is incomplete. Not applicable.
`sybilProbability` Behavioral Sybil risk (heuristic)	risk_percent Full returned cross-chain behavior history.	Local MEDIA-style behavioral dimensions; blacklist matches are reported separately. A local behavioral heuristic, not a live Trusta score and not a blacklist verdict. Computed once from the combined selected-chain dataset.	Unavailable when wallet history or the behavioral report is incomplete. When current prices are incomplete, the monetary dimension is omitted and the remaining behavioral dimensions are reweighted.
`blacklistStatus` Blacklist status	status Latest blacklist snapshots checked for the scan.	Configured external and bundled blacklist datasets; excludes the Trusta behavioral heuristic. Flagged when any non-behavioral blacklist source positively matches. flagged overrides clear; unavailable when checks did not complete.	Unavailable when the Sybil/blacklist report is absent. Not applicable.
`activeDays` Active days	days Full transaction history returned by selected explorers.	Successful and failed normal transactions with valid timestamps. A UTC calendar date counts once even when activity occurs on multiple chains. Cardinality of the union of UTC activity dates.	Unavailable unless transaction history is complete. Not applicable.
`longestStreakDays` Longest activity streak	days Full transaction history returned by selected explorers.	The union of UTC activity dates across selected chains. Consecutive UTC calendar dates; same-day cross-chain activity counts once. Longest consecutive run in the sorted date union.	Unavailable unless transaction history is complete. Not applicable.
`totalUnlimitedApprovals` Unlimited approvals	count Latest observed approval state in returned history.	Decoded ERC-20 approval transactions. Counts unlimited approvals in the latest observed state; observed revoked states are excluded. Sum across selected chains.	Unavailable unless transaction history is complete. Not applicable.

SECTION 10 · TECHNICAL SPECIFICATIONS

Algorithmic Complexity & Cache Policy

Algorithmic complexity and cache policies. The cache-size and timing figures are illustrative, not reproducible benchmark results or production capacity guarantees.

Subsystem	Time Complexity	Space Complexity	Execution Layer	Cache Policy
Sybil Blacklist Check	O(1) lookup	O(M) in-memory set (~800K entries, illustrative)	Server Memory	24h Global TTL
Behavioral Fingerprint	O(N) transactions	O(U) unique contracts	Server / Client	Session / Per-Scan
Risk Scoring Engine	O(A + G + D) summary	O(F) factor list	Server / Client	Instant Compute
Cluster Linkage Graph	O(W × C) pair analysis	O(W + L) nodes & links	Server Route	Per-Batch Run
Daily Price OHLC Feed	O(1) cache read	O(K) token day pairs	Server Memory	Process Lifecycle
Web3.bio Identity Graph	O(1) async HTTP	O(P) profile records	Server Gateway	force-cache HTTP

LAUNCH FORENSICS SCANNER