Wallet Intelligence Engine
Developer Specification

Overview

Purpose

The Wallet Intelligence Engine (WIE) is a pre-settlement fraud signal architecture that evaluates counterparty wallets before a transaction settles. It produces a deterministic YES / NO / REVIEW verdict by analyzing 42 discrete signals across 6 risk categories. The engine operates in the critical path between intent submission and settlement finality, with a target latency of under 200ms for the p50 case.

WIE is not a post-hoc analytics tool. It is a real-time gate. Every transaction processed by the JIL settlement layer passes through WIE before funds move. The verdict is cryptographically signed and recorded on-chain as an immutable attestation.

Design Principles

• Pre-settlement, not post-settlement. Fraud detection happens before funds leave the sender's custody, not after.
• Deterministic scoring. Given the same inputs, WIE always produces the same verdict. No probabilistic black boxes.
• Fail-closed. If any signal source is unavailable, the engine defaults to REVIEW, never YES.
• Auditable. Every verdict includes the full signal breakdown, weights applied, and data sources consulted. The complete decision trail is stored for regulatory review.
• Chain-agnostic. Signal collection adapts to 11 supported chains without changing the scoring model.
• Latency-bounded. Hard timeout at 2 seconds. If scoring cannot complete, the verdict is REVIEW with a timeout flag.

Verdict Definitions

Architecture

High-Level Component Diagram

Technology Stack

Signal Categories

WIE evaluates 42 discrete signals organized into 6 categories. Each signal produces a normalized score between 0.0 (no risk) and 1.0 (maximum risk). Signals within a category are averaged, then categories are combined using the weighted formula defined in the Scoring Engine section.

Evaluates the age, origin, and initial funding pattern of the counterparty wallet. New wallets funded from mixing services or freshly created before a high-value transaction are significantly riskier than established wallets with organic history.

Measures the degree to which a wallet has interacted with known-bad addresses, sanctioned entities, or flagged clusters. This category includes hard-block signals that override the composite score and force an immediate NO verdict.

Detects abnormal transaction patterns that deviate from the wallet's historical baseline. Sudden spikes in volume, frequency, or counterparty diversity are strong indicators of compromised credentials or money laundering layering.

Evaluates the wallet's DeFi positions to assess financial stability and sophistication. Unlike the other categories, DeFi signals primarily act as trust reducers - they decrease the composite risk score when healthy positions are detected. A wallet with diversified, well-managed DeFi positions is empirically less likely to be a fraud vehicle.

Identifies assets or value that the wallet may be attempting to conceal through obfuscation techniques, cross-chain hiding, or non-standard token mechanics. Hidden assets often indicate layering or integration phases of money laundering.

Evaluates wallet activity against jurisdiction-specific regulatory requirements. These signals check for compliance with financial regulations across the jurisdictions where JIL operates. Non-compliance with local regulations increases risk independent of other fraud signals.

Data Sources

On-Chain Data Sources

Off-Chain Data Sources

Caching Strategy

Signal data is cached in Redis with tiered TTLs based on data volatility. Stale cache entries are served with a stale: true flag while fresh data is fetched asynchronously.

Scoring Engine

Category Weights

Each category produces a normalized score between 0.0 and 1.0 (average of its constituent signals). The composite score is the weighted sum of all category scores.

Verdict Thresholds

Trust Reduction Cap

The DeFi Position Trust Scoring category (Category 4) can reduce the composite risk score by up to 40% of its weighted contribution. This cap exists because DeFi positions can be manufactured - a bad actor could deposit into Aave, provide Uniswap liquidity, and vote in a DAO governance proposal purely to lower their WIE score. The cap ensures that manufactured trust signals cannot override genuine risk signals from the other 5 categories.

Pseudocode for the cap:

defi_raw = average(DFT_001, DFT_002, ..., DFT_006)
defi_capped = max(defi_raw, -0.40)  # cannot reduce more than 40%
composite = (CPC_weight * CPC_score)
           + (VEL_weight * VEL_score)
           + (WAG_weight * WAG_score)
           + (HAS_weight * HAS_score)
           + (REG_weight * REG_score)
           + (DFT_weight * defi_capped)

Verdict Pipeline

End-to-End Flow (10 Steps)

Short-Circuit Rules

The pipeline supports early termination in the following cases:

• Hard-block hit (step 3): Immediate NO. Full signal collection still runs asynchronously for audit purposes but does not block the verdict.
• Cache hit (step 2): Return cached verdict if under 5 minutes old and no new OFAC/sanctions updates since cache time.
• Timeout (step 4): If more than 3 collectors timeout, the verdict defaults to REVIEW with reason: "insufficient_data".
• Composite score exceeds 0.90 after 3 categories: If the weighted partial score from the first 3 categories already exceeds 0.90, short-circuit to NO (remaining categories cannot reduce below 0.75).

API Specification

POST /v1/attest

Primary attestation endpoint. Evaluates a counterparty wallet and returns a signed verdict.

{
  "sender": "0x7Bcff27567cfE3e67020a0d771a445178756aBa2",
  "recipient": "0x9347efffa3e8985e0d35536b408cab48599971e8",
  "asset": "USDC",
  "amount": "250000.00",
  "chain": "ethereum",
  "intent_id": "int_a1b2c3d4e5f6",
  "metadata": {
    "source_app": "settlement-consumer",
    "urgency": "standard"
  }
}

{
  "verdict": "YES",
  "composite_score": 0.18,
  "attestation_id": "att_8f7e6d5c4b3a",
  "timestamp": "2026-04-12T14:30:22.441Z",
  "latency_ms": 142,
  "categories": {
    "wallet_age_genesis": { "score": 0.08, "weight": 0.15, "signals_evaluated": 6 },
    "counterparty_contamination": { "score": 0.02, "weight": 0.30, "signals_evaluated": 9 },
    "velocity_pattern": { "score": 0.12, "weight": 0.20, "signals_evaluated": 8 },
    "defi_trust": { "score": -0.22, "weight": 0.05, "signals_evaluated": 6 },
    "hidden_assets": { "score": 0.05, "weight": 0.15, "signals_evaluated": 7 },
    "regulatory_alignment": { "score": 0.10, "weight": 0.15, "signals_evaluated": 6 }
  },
  "hard_blocks": [],
  "cache_hit": false,
  "signature": "dilithium3_0xabc123...def789",
  "chain_recorded": true
}

GET /v1/wallet/{address}

Returns the most recent verdict and signal profile for a wallet address. Does not trigger a new evaluation.

{
  "address": "0x9347efffa3e8985e0d35536b408cab48599971e8",
  "last_verdict": "YES",
  "last_score": 0.18,
  "last_evaluated": "2026-04-12T14:30:22.441Z",
  "evaluation_count": 47,
  "signal_profile": {
    "wallet_age_days": 412,
    "total_transactions": 1893,
    "kyc_verified": true,
    "defi_protocols_used": 7,
    "hard_block_history": [],
    "jurisdiction": "US"
  }
}

POST /v1/sweep

Batch re-evaluation of all wallets with a previous REVIEW verdict. Typically run daily as a scheduled job. Returns a summary of verdict changes.

{
  "scope": "review_pending",
  "max_wallets": 1000,
  "priority": "high_value_first"
}

{
  "sweep_id": "swp_x9y8z7w6",
  "wallets_evaluated": 312,
  "verdict_changes": {
    "review_to_yes": 198,
    "review_to_no": 14,
    "review_unchanged": 100
  },
  "duration_ms": 48200,
  "next_sweep_recommended": "2026-04-13T04:00:00Z"
}

POST /v1/attest/batch

Evaluate multiple wallets in a single request. Maximum 100 wallets per batch. Returns individual verdicts for each wallet.

{
  "sender": "0x7Bcff27567cfE3e67020a0d771a445178756aBa2",
  "recipients": [
    { "address": "0xaaa...111", "asset": "USDC", "amount": "50000.00", "chain": "ethereum" },
    { "address": "0xbbb...222", "asset": "ETH", "amount": "25.5", "chain": "ethereum" },
    { "address": "0xccc...333", "asset": "SOL", "amount": "1000.0", "chain": "solana" }
  ],
  "intent_id": "int_batch_001"
}

{
  "batch_id": "bat_q1w2e3r4",
  "total": 3,
  "results": [
    { "address": "0xaaa...111", "verdict": "YES", "score": 0.12, "latency_ms": 134 },
    { "address": "0xbbb...222", "verdict": "REVIEW", "score": 0.52, "latency_ms": 189 },
    { "address": "0xccc...333", "verdict": "YES", "score": 0.08, "latency_ms": 156 }
  ],
  "total_latency_ms": 203
}

DeFi Position Enumeration

The DeFi Enumerator scans the counterparty wallet's positions across the following protocol categories. Position data is used exclusively by Category 4 (DeFi Position Trust Scoring) signals.

Supported Protocol Categories

Cross-Chain Coverage

WIE supports signal collection across 11 chains. Not all signal capabilities are available on every chain. The matrix below shows coverage by chain and capability.

Coverage Definitions:

• Full: Complete signal collection via native RPC and indexer APIs. All signals in the category can be evaluated.
• Partial: Limited signal collection. Some signals may return neutral scores due to missing data. Coverage percentage noted in signal metadata.
• N/A: Capability does not apply to this chain (e.g., DeFi positions on Bitcoin's base layer).

Legal and Regulatory

SAR Trigger Conditions

A Suspicious Activity Report (SAR) trigger event is generated automatically when any of the following conditions are met:

• Any hard-block signal fires (CPC-001, CPC-007 direct, CPC-008 direct, CPC-009)
• Composite score exceeds 0.85 (high-confidence NO verdict)
• Structuring pattern detected (VEL-005 score above 0.7) with aggregate value over $10,000 in 48 hours
• Three or more NO verdicts on the same wallet within 30 days
• Manual escalation from compliance review queue

SAR trigger events are published to the compliance.sar_triggers Kafka topic and stored in the audit log with a 7-year retention period.

Nacha Return Code Mapping

For ACH-adjacent transactions, WIE maps its verdicts to the appropriate Nacha return codes:

GENIUS Act Compliance

Signal REG-006 evaluates stablecoin transactions against the GENIUS Act (Guiding and Establishing National Innovation for U.S. Stablecoins) requirements:

• Issuer must maintain 1:1 reserve backing with qualifying assets
• Monthly attestation reports from a registered public accounting firm
• Issuer must be a US-chartered entity or licensed foreign issuer
• Redemption at par value within 1 business day

Non-compliant stablecoin issuers receive a REG-006 score of 0.45, which contributes to but does not alone trigger a NO verdict.

Audit Log Schema

CREATE TABLE wie_audit_log (
    id              BIGSERIAL PRIMARY KEY,
    attestation_id  VARCHAR(64) NOT NULL UNIQUE,
    intent_id       VARCHAR(64) NOT NULL,
    sender          VARCHAR(128) NOT NULL,
    recipient       VARCHAR(128) NOT NULL,
    asset           VARCHAR(32) NOT NULL,
    amount          NUMERIC(38,18) NOT NULL,
    chain           VARCHAR(32) NOT NULL,
    verdict         VARCHAR(8) NOT NULL CHECK (verdict IN ('YES','NO','REVIEW')),
    composite_score NUMERIC(6,4) NOT NULL,
    category_scores JSONB NOT NULL,
    signal_details  JSONB NOT NULL,
    hard_blocks     JSONB DEFAULT '[]',
    cache_hit       BOOLEAN DEFAULT FALSE,
    latency_ms      INTEGER NOT NULL,
    signature       TEXT NOT NULL,
    sar_triggered   BOOLEAN DEFAULT FALSE,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    archived_to_s3  BOOLEAN DEFAULT FALSE,
    s3_key          VARCHAR(256)
);

CREATE INDEX idx_wie_audit_recipient ON wie_audit_log (recipient);
CREATE INDEX idx_wie_audit_verdict ON wie_audit_log (verdict, created_at);
CREATE INDEX idx_wie_audit_sar ON wie_audit_log (sar_triggered) WHERE sar_triggered = TRUE;
CREATE INDEX idx_wie_audit_created ON wie_audit_log (created_at);

Performance

Latency Targets

Throughput Targets

Availability

Target availability: 99.99% uptime (52.6 minutes of downtime per year). Achieved through:

• Active-passive failover with less than 5 second switchover
• Redis Sentinel for cache high availability
• Kafka consumer group rebalancing for queue resilience
• PostgreSQL streaming replication for audit log durability
• Circuit breaker on all external API calls (Chainalysis, TRM) with fallback to cached scores

Security

Verdict Signing

Every verdict is cryptographically signed using CRYSTALS-Dilithium (NIST PQC Level 3) to ensure post-quantum tamper resistance. The signed payload includes the composite score, all category scores, the verdict, the timestamp, and the intent ID. Signatures are verified by the attestation service before on-chain recording.

Validator Quorum for High-Value Verdicts

Transactions exceeding $1,000,000 in value require multi-validator consensus on the WIE verdict:

• The originating node produces the primary verdict
• The verdict and signal snapshot are broadcast to the validator set
• A minimum of 3 additional validators must independently confirm the verdict within 10 seconds
• If quorum is not reached, the verdict defaults to REVIEW regardless of the composite score
• Quorum responses are recorded on-chain as co-attestations

Key Management

Testing

Test Coverage Requirements

False Positive Targets

Backtesting Requirements

Before any scoring weight change or new signal deployment, the following backtesting protocol must be completed:

1. Historical Replay: Run the updated scoring model against the last 90 days of verdict history (minimum 100,000 verdicts). Compare old vs. new verdict distribution.
2. Known-Bad Validation: Verify that all confirmed fraud cases in the validation set still produce NO verdicts. Zero regression tolerance on known-bad wallets.
3. False Positive Delta: Calculate the change in false positive rate per use case. No single use case may increase by more than 0.1 percentage points.
4. Sensitivity Analysis: Vary the changed weight by +/- 20% and verify verdict stability. Unstable weights (where small changes cause large verdict swings) require additional review.
5. Sign-Off: Backtesting results must be reviewed and approved by at least two engineers before deployment to production.