Deterministic wallet risk scoring: the CredScore methodology

CredScore is a deterministic scoring engine that produces a 0-100 risk score, a categorical tier (High / Medium / Low / Unclassified), a decision posture recommendation (Proceed / Review / Escalate / Block), a confidence value, an enumerated set of primary drivers with cited evidence, an enumerated set of offsetting factors, and a sensitivity analysis describing conditions that would flip the verdict — all as output of a single analysis event on a single wallet address.

The engine covers six chains at the time of writing: Ethereum mainnet, Base, Arbitrum, Optimism, Polygon, and Tron. Bitcoin support ships in a UTXO-model scoring pipeline currently under development.

This whitepaper documents the reasoning stack — inputs, transformations, weighting, offsetting, capping — that produces the verdict. It does not enumerate every driver in the corpus (see the driver reference at /methodology) or specify every threshold constant (those are engine-version-scoped and stamped on every verdict).

Every scoring system is a series of choices about what counts and what doesn’t. CredScore’s three central choices, ranked by their downstream impact on verdict shape:

1. Behavior over labels. CredScore evaluates on-chain activity patterns — the observed shape of transfers, counterparty diversity, timing signatures, entity role balance — as the primary risk signal. Attribution labels (this wallet is X exchange, this address is on Y sanctions list) are used as capping and context, not as the basis for the score itself. This differentiates CredScore from label-heavy risk products where an unlabeled wallet defaults to low risk.
2. Deterministic reproducibility. The engine is not machine-learned. Given the same input state and the same engine version, the output is identical. This makes verdicts auditable, reproducible in litigation, and free of the black-box explanation problem that undermines ML-based risk output in regulatory review.
3. Defensible artifacts, not just numbers. Every verdict emits a Defensible Verdict Report with the engine version and analysis timestamp baked into the header. Every driver is cited with the underlying evidence. Offsetting factors and sensitivity notes make the reasoning path transparent. This is the format compliance analysts hand to auditors and regulators as-is.

The engine executes a pipeline of stages against the wallet’s observed on-chain activity:

1. Ingestion. Transfer history is fetched from chain-specific providers (Alchemy for EVM chains, TronGrid for Tron). The engine caps ingestion at a configurable transaction budget to prevent unbounded compute on high-volume addresses.
2. Behavioral profiling. Ingested transfers are aggregated into a snapshot: transfer counts, counterparty counts, timing histograms, value distribution, wallet age, activity level, entity role breakdown (DEX, CEX, mixer, bridge, aggregator, protocol, sanctions).
3. Attribution enrichment. Known counterparties are matched against the CredScore attribution corpus and any live sanctions registry (OFAC SDN + regional sanctions). Enrichment adds entity roles and category flags to each counterparty.
4. Driver evaluation. Each named driver — high_activity_with_limited_history, dex_routed_pass_through_pattern, source_return_flow_detected, sanctions_exposure_pattern, etc. — evaluates its trigger condition against the snapshot. Triggered drivers produce cited evidence and an impact assessment.
5. Offsetting factor evaluation. The same snapshot is evaluated against a set of legitimacy-signal conditions — established_history, distributed_counterparties, recognizable_entity_context, high_confidence_label_coverage. Triggered offsetting factors soften driver weights.
6. Weighting and capping. Driver weights are aggregated. Sanctions exposure applies hard caps regardless of offsetting factors present. Insufficient behavioral signal produces an Unclassified verdict rather than a fabricated numeric score.
7. Sensitivity analysis. The engine emits notes on what conditions, if changed, would flip the verdict — the analytical equivalent of “show your work.”
8. Output validation. An output inspector runs consistency checks on the emitted verdict (drivers match evidence, score aligns with tier band, sanctions cap correctly applied). Corrections and failures are recorded to the analysis_validation_failures table for engine calibration.

CredScore emits a numeric score on a 0-100 scale where lower = higher risk. This convention is inherited from credit-scoring analog and is documented on every verdict artifact.

The engine emits three risk tiers plus an Unknown state, not five. The boundaries above (0-39 / 40-68 / 69-100) are the current calibration; parameter changes are tracked with engine version bumps and reflected on every verdict artifact.

The tier and decision posture are not mechanical translations of the score alone — they are influenced by specific rules that can override the numeric band. High_confidence_sanctions_attribution forces the High tier regardless of score. A wallet with fewer than five observable transfers returns Unknown regardless of any signal. A wallet with any direct sanctions interaction is capped at score 12 and forced to Escalate posture.

Confidence is a separate output that describes how well-founded the verdict is, independent of the verdict itself. It is expressed as a percentage 0-100 with three human-legible bands:

• ≥ 80%: High confidence. The engine had strong signal (adequate transfer count, good attribution coverage, unambiguous driver triggers) to produce this verdict. Treat as authoritative pending independent review.
• 55% – 80%: Moderate confidence. The verdict is directional but rests on partial signal. Common causes: thin attribution coverage, ambiguous behavioral patterns, or low-volume wallets. Treat as informative.
• < 55%: Low confidence. Signal is thin or contradictory. Use as a starting point for investigation, not as a decision input on its own. The Defensible Verdict Report’s sensitivity notes are the key artifact at this confidence band.

CredScore ingests OFAC SDN designations from public sources on a weekly schedule and evaluates every wallet against the current registry. Two exposure classes are recognized:

• Self-sanctioned. The wallet’s own address matches a sanctions registry entry. The engine hard-caps the score at 12 and forces the decision posture to Escalate. No offsetting factor or driver combination can override this cap.
• Counterparty-sanctioned. The wallet has transferred to or from a sanctioned address. Direct interactions force Escalate. Indirect exposure (interactions with a wallet that itself interacted with sanctions) caps the ceiling of the score.

Sanctions caps are audit-logged; the engine records which sanctions rule fired on any given verdict so that a downstream review can retrace the enforcement decision.

Alongside the verdict, CredScore computes a Behavioral Watermark — a compact 20-dimensional vector that captures the wallet’s operational shape independent of any risk label. The Watermark exists because a determined adversary can rotate addresses in seconds but cannot easily rotate the shape of how a wallet accumulates value, times its transfers, distributes across counterparties, or interacts with protocol categories. Two wallets with different addresses, different chains, and no overlapping attribution can still reveal themselves as the same operational actor when their fingerprints match under cosine distance.

The Watermark runs orthogonal to the scoring engine. It is not itself a risk score; it is a similarity primitive that lets an analyst answer a different question — “does this wallet operate like any wallet CredScore has seen before?” — without depending on labels the corpus may not yet have. Version tag: cs.watermark.v1.

7.1 Dimension design: pattern metrics only

The 20 dimensions are drawn exclusively from pattern metrics — normalized measurements of behavioral shape — never from outcome variables. Wallet score, tier, sanctions exposure count, and other engine-derived verdicts are deliberately excluded. If outcome variables were included, wallets that scored similarly would trivially match under any distance metric, making the Watermark circular. Pattern metrics capture the underlying operational shape that produced the score, which is the layer that survives address rotation.

The vector is materialized in a fixed canonical order:

• Structural / lifecycle (5): log-normalized wallet age, log-normalized transfer count, average transfers per day, log-normalized unique counterparty count, normalized recency (days since last activity).
• Distribution / concentration (3): counterparty concentration ratio, counterparty entropy, largest-single-inbound-source share.
• Directionality (3): inbound-share ratio, self-transfer ratio, zero-value transfer ratio.
• Timing patterns (2): rapid-inflow burstiness, rapid-outflow burstiness.
• Role mix (protocol category exposure) (7): mixer, bridge, exchange (CEX), DEX, aggregator, protocol, and attribution-coverage interaction ratios.

Every dimension is normalized to [0, 1] using either log-scale caps (for count metrics where the meaningful range spans orders of magnitude) or linear caps (for ratio metrics already bounded). Missing dimensions default to 0, and the fingerprint records a coverage value — the share of dimensions that had real underlying data — so downstream callers can weight low-coverage matches appropriately.

7.2 Similarity computation

Similarity between two fingerprints is cosine distance in the 20-dimensional space. Because every dimension is non-negative, cosine similarity is bounded in [0, 1] in practice, where 1.0 is an identical operational shape and 0.0 is fully orthogonal.

Alongside the aggregate similarity score, the engine emits per-dimension deltas — the absolute distance between two wallets on each of the 20 axes, sorted by divergence. This is the interpretability layer: an analyst reading a Watermark match can see exactly which operational axes the two wallets are most alike on (“identical rapid-inflow burstiness, near-identical counterparty entropy, matching mixer-exposure profile”) and where they diverge (“different wallet age, different aggregator mix”). This distinguishes the Watermark from a black-box embedding — every match comes with structured evidence, not a similarity number alone.

7.3 How the Watermark surfaces

Two surfaces expose the Watermark today:

• Per-wallet fingerprint page at /wallets/{address}/fingerprint. Renders the wallet’s 20-dimension vector as horizontal bars, then lists the top matches from CredScore’s shared-verdict corpus ranked by similarity, with per-dimension “most alike” and “diverges on” explanations for each match.
• Bearer-key API at GET /api/v1/watermark/match. Query parameters: target wallet address, result limit, minimum similarity threshold. Returns ranked matches with similarity scores, per-match fingerprint coverage, and known-entity attribution when available. Rate-limited to 30 requests per minute per key.

7.4 Value grows with corpus depth, not code

The Watermark primitive is deterministic and complete at v1 — the vector shape and similarity math are not the axis of improvement. Match quality is a function of corpus size. At small corpus depth, only near-identical wallets surface useful matches. At 5,000+ wallets in the corpus, cross-actor similarity patterns emerge — a fresh unlabeled wallet moving like known Lazarus laundering wallets from a prior incident can surface even before attribution catches up. At 50,000+ wallets, the primitive becomes a genuine forensic tool for identifying same-actor operations across chains and time.

CredScore runs an autonomous corpus-growth scanner that feeds the shared-verdict store on a bounded budget, populating the lookup table over time. Growth is deliberately capped by monthly compute-unit budget and per-day wallet caps so infrastructure cost stays predictable.

7.5 Limitations and honest boundaries

• Not a verdict. A Watermark match is a similarity signal, not a risk determination. A 90%+ match to a known laundering wallet is a review trigger, not proof of shared control. Analyst judgment remains load-bearing.
• Coverage-weighted. Matches on sparse fingerprints (low coverage on either side) propagate uncertainty. The API and per-wallet page surface coverage explicitly so this is not hidden.
• EVM + Tron only today. The pattern metrics are chain-agnostic in design but the current analyzer pipeline covers six chains: Ethereum, Tron, Base, Arbitrum, Optimism, and Polygon. Bitcoin and Solana coverage would extend the Watermark to those chains without changing the vector shape.
• Adversarial adaptation. A determined adversary aware of the specific dimensions could attempt to modulate their operational shape to defeat matching. This is meaningfully harder than rotating addresses (the shape is the aggregate of hundreds of decisions rather than a single input), but it is not impossible. Future Watermark versions will incorporate additional dimensions and possibly second-order features to raise the adaptation cost.

Every verdict emits a Defensible Verdict Report (DVR) — a print-ready single-page artifact that carries:

• The engine version and analysis timestamp in the header, so the verdict is a forensic snapshot rather than a live read.
• Every driver enumerated with its cited evidence and impact.
• Every offsetting factor enumerated as a peer section — not collapsed away.
• The sensitivity notes describing verdict-flipping conditions.
• Any sanctioned counterparty interactions with list source attribution.
• The analyst’s notes as a distinct section (autosaved per authenticated user).
• A footer disclaimer specifying that CredScore is decision support, not final determination.

The DVR is exportable to PDF via browser print and to Markdown via one-click copy. Both formats preserve the structure so downstream review — legal, regulatory, or internal — reads the same shape as the analyst screen.

Every risk system has scope limits. CredScore’s honestly disclosed limitations at the current engine version:

• Chain coverage. Six chains today; Bitcoin’s UTXO-model scoring is under development. Non-supported chain traffic is not analyzed.
• Cross-chain tracing. Multi-hop tracing is limited to sanctioned-counterparty edges within the engine’s stored data model. A future engine revision will store address-level counterparty edges on every analysis to enable full-graph tracing.
• Attribution corpus size. The current corpus is hand-verified and covers 75 entities across Ethereum and Tron as of 2026-07-05. A production-scale attribution pipeline (community submissions, partner data feeds, heuristic clustering) is on the Year-1 roadmap.
• Attribution latency. Newly-published sanctions designations may not appear in the CredScore corpus for up to seven days depending on registry sync schedule. Every verdict includes the engine version so downstream review can confirm whether the sanction was known at the analysis timestamp.

Appropriate uses. Analyst screening of on-chain counterparties; SAR narrative decision support; case-file evidence attachment; exchange-compliance transaction monitoring (via KYT rules); Chrome-extension surface for block explorer analyst workflows.

Inappropriate uses. Sole basis for account freezes, transaction blocks, or terminal customer actions without independent analyst review. CredScore is decision support, not final determination — the distinction is repeated on every verdict and every DVR footer.

Referenced artifacts:

• CredScore driver reference at credscore.us/methodology.
• Published case studies: credscore.us/case-studies — every case study references the underlying engine output on a real wallet.
• Live verdict corpus: credscore.us/wallets — every public verdict is inspectable in the same shape described here.
• Security posture: credscore.us/security and credscore.us/security/soc2.
• Expert-report template: credscore.us/legal/expert-report-template.