Compliance Architecture

1. Architecture Overview

Every transaction in the JIL Sovereign settlement pipeline passes through the compliance layer before finalization. The compliance architecture is composed of four tightly integrated services that collectively enforce KYC verification, AML screening, sanctions checks, anti-dump rules, and jurisdiction-specific policy across all 20 mainnet validator zones.

The system follows a fail-closed design - if any compliance service is unavailable or returns an indeterminate result, transactions queue in Kafka rather than bypassing compliance. No transaction can reach settlement finalization without an explicit compliance approval.

Transaction Flow

The compliance pipeline processes every transaction through three stages:

Stage 1 - Transaction Submission

Stage 2 - Compliance Evaluation

Stage 3 - Decision and Settlement

Only transactions with a final APPROVED decision proceed to settlement finalization. Transactions marked BLOCKED are rejected with a compliance reason code. Transactions flagged for REVIEW are held in a pending queue until a compliance officer resolves them manually.

2. Service Map

The compliance layer consists of four microservices, each with a distinct responsibility within the pipeline. All services communicate over Kafka for asynchronous event processing and expose HTTP endpoints for synchronous lookups.

Service Responsibilities

compliance-api (Port 8100)

The core decision engine. It receives compliance check requests from the settlement pipeline, aggregates risk signals from analytics-integrations and bid-service, applies zone-specific policy rules, evaluates ATCE constraints, and produces a final APPROVED, BLOCKED, or REVIEW decision. All decisions are persisted to PostgreSQL and emitted to Kafka for downstream consumers.

compliance-checker (Port 8055)

A dedicated Kafka consumer that sits in the settlement pipeline. It consumes raw settlement intents from the jil.settlements topic, forwards them to compliance-api for evaluation, and produces compliance results to jil.compliance.results. This service acts as the bridge between the high-throughput settlement consumer and the compliance decision engine.

analytics-integrations (Port 8770)

Aggregates blockchain analytics from three external providers - Chainalysis KYT, TRM Labs, and Elliptic. It normalizes risk scores from each provider into a composite weighted score, caches results to reduce API costs, and provides graceful degradation when a provider is unavailable. The composite score feeds directly into compliance-api risk assessment.

bid-service (Port 8750)

Handles beneficiary identity verification - confirming that the receiving party of a transaction is a known, verified entity. It performs phone, email, address, person, and company identity checks and provides a trust score that factors into the overall compliance decision. BID verification is required for institutional transactions above configurable thresholds.

3. External Provider Integration

The analytics-integrations service aggregates blockchain risk intelligence from three industry-leading providers to deliver a composite risk assessment that is more reliable than any single-vendor score.

Provider Weighting

Composite Scoring

Each provider returns a normalized risk score between 0 (no risk) and 100 (maximum risk). The composite score is calculated as a weighted average:

// Composite risk score calculation
compositeScore = (chainalysis.score * 0.40)
               + (trmLabs.score * 0.35)
               + (elliptic.score * 0.25)

Graceful Degradation

If one provider is unavailable, the remaining providers auto-reweight proportionally to maintain full coverage:

• Chainalysis down: TRM Labs reweights to 58.3%, Elliptic to 41.7%
• TRM Labs down: Chainalysis reweights to 61.5%, Elliptic to 38.5%
• Elliptic down: Chainalysis reweights to 53.3%, TRM Labs to 46.7%
• Two providers down: Single remaining provider supplies 100% of score with elevated caution flag
• All three down: Fail-closed - compliance-api falls back to internal screening only (sanctions lists, velocity checks)

Caching Strategy

All provider responses are cached in Redis with a 5-minute TTL. This reduces external API costs, lowers response latency for repeated address lookups, and provides a buffer during brief provider outages. Cache keys are scoped by provider, address, and chain ID.

Provider Data Flow

4. Zone Policy Engine

JIL Sovereign operates across 13 compliance zones, each mapping to a mainnet validator jurisdiction. The zone policy engine within compliance-api applies jurisdiction-specific rules, risk thresholds, and reporting requirements on top of the base compliance checks.

Zone Configuration

Configurable Zone Parameters

Each zone has the following configurable parameters that compliance operators can adjust without code changes:

• Risk score thresholds: Review threshold (flag for manual review) and block threshold (automatic rejection). Expressed as composite risk scores from 0 to 100.
• Allowed asset lists: Whitelist of token contract addresses and native assets permitted in the zone. Transactions involving unlisted assets are blocked.
• Velocity limits: Per-hour transaction count limits and per-hour volume limits (denominated in USD equivalent). Exceeding velocity limits triggers automatic review.
• Reporting requirements: Jurisdiction-specific thresholds for Currency Transaction Reports (CTR), Suspicious Activity Reports (SAR), and travel rule data sharing.

5. ATCE - Anti-Token Concentration Exploitation

ATCE is a patented compliance mechanism designed to prevent post-vesting dump attacks that could crash the JIL token price. It enforces graduated sell limits on addresses that receive tokens through vesting unlocks, ensuring that large token holders cannot liquidate their entire position in a single burst.

Mechanism

When a vesting unlock occurs, ATCE activates a 30-day enforcement window for the receiving address. During this window, the address is limited to selling no more than 10% of their unlocked balance per calendar day. This prevents coordinated sell pressure while still allowing holders to realize value at a measured pace.

Vesting Tiers

Each tier triggers its own independent 30-day enforcement window. If Tier 1 and Tier 2 unlock on the same day, both enforcement windows run in parallel and daily limits are calculated independently for each tier's unlocked amount.

ATCE Decisions

• APPROVED - Sell amount is within the daily allowance for all active enforcement windows.
• BLOCKED - Sell amount exceeds the daily allowance and the entire transaction is rejected.
• PARTIAL - Sell amount exceeds the daily allowance, but a partial fill up to the remaining daily limit is offered to the seller.

Database Schema

ATCE state is tracked across three tables in PostgreSQL:

• atce_unlock_events - Records each vesting unlock: address, tier, amount, unlock timestamp, enforcement window end timestamp.
• atce_daily_sales - Tracks cumulative sell volume per address per day per enforcement window. Reset at midnight UTC.
• atce_decisions - Audit log of every ATCE evaluation: address, requested amount, allowed amount, decision, reasons.

Patent Coverage

6. Sanctions List Management

JIL Sovereign maintains a comprehensive sanctions screening capability that checks addresses and entities against multiple international sanctions lists at every compliance checkpoint.

Primary Sanctions Lists

• OFAC SDN (Specially Designated Nationals): U.S. Treasury list of sanctioned individuals, entities, and wallet addresses. Includes the OFAC crypto address list (e.g., Tornado Cash addresses).
• EU Consolidated Sanctions List: European Union consolidated list covering financial sanctions, travel bans, and arms embargoes. Updated by the European Commission.
• UN Security Council Sanctions: United Nations consolidated list of individuals and entities subject to Security Council sanctions measures.
• Internal Watchlist: JIL-maintained watchlist of addresses and entities flagged by the compliance team based on internal investigations, law enforcement requests, or suspicious activity patterns.

Screening Points

Sanctions screening occurs at three points in the transaction lifecycle:

1. Address registration: When a new wallet address is registered with the platform, it is screened against all active sanctions lists before the address is activated.
2. Transaction submission: Both sender and receiver addresses are screened at the time a transaction is submitted to the settlement pipeline.
3. Settlement finalization: A final sanctions check runs immediately before settlement finalization as a last-line defense against race conditions where a sanctions list may have been updated between submission and settlement.

Matching Configuration

• Exact match: Blockchain addresses are matched exactly (case-insensitive for hex addresses, case-sensitive for base58).
• Fuzzy match: Entity names are matched using configurable fuzzy matching with a default threshold of 85% similarity. This catches common evasion techniques such as transliteration, abbreviated names, and minor spelling variations.
• Partial match: When a fuzzy match score falls between 70% and 85%, the transaction is flagged for REVIEW rather than automatically blocked.

List Refresh Schedule

External sanctions lists are automatically refreshed on a daily schedule at 02:00 UTC. The refresh process downloads updated lists from official sources, computes a diff against the current list, and triggers re-screening of any active addresses that match newly added entries. The internal watchlist can be updated in real-time by authorized compliance operators.

7. Fail-Closed Design

The foundational principle of the JIL compliance architecture is that no transaction may bypass compliance checks under any circumstances. Every failure mode in the system defaults to holding the transaction rather than allowing it to proceed.

Failure Scenarios

Circuit Breaker Pattern

All external provider calls (Chainalysis, TRM Labs, Elliptic) are wrapped in a circuit breaker with the following configuration:

• Failure threshold: 5 consecutive failures opens the circuit
• Reset timeout: 30 seconds before attempting a probe request
• Half-open: Single probe request determines if circuit should close or remain open
• Timeout per call: 10 seconds maximum per provider API call

Health Check Cascade

The compliance-api health endpoint (/health) performs a cascading dependency check:

// Health check cascade order
1. PostgreSQL connection    // Primary data store
2. Redis connection         // Velocity cache + provider cache
3. analytics-integrations   // External provider aggregator
4. bid-service              // Beneficiary identity
5. Kafka producer           // Decision event publishing

If any dependency is unhealthy, the compliance-api reports itself as unhealthy, which causes the settlement consumer to stop pulling new transactions from Kafka until compliance capacity is restored.

8. Audit Trail

Every compliance decision is permanently recorded in an immutable audit trail. This trail serves dual purposes - internal operational visibility and regulatory reporting to supervisory authorities across all 13 jurisdictions.

Decision Record Schema

Each compliance decision is persisted to the compliance_decisions table in PostgreSQL:

Event Streaming

In addition to PostgreSQL persistence, every compliance decision is emitted to the jil.compliance.decisions Kafka topic. This enables real-time streaming to downstream consumers such as the ops-dashboard, SentinelAI fleet inspector, and external SIEM integrations.

Immutability Guarantee

• Compliance decision records are append-only. Once written, a decision is never updated or deleted.
• If a decision needs to be overridden (e.g., a compliance officer resolves a REVIEW as APPROVED), a new decision record is created with a reference to the original decision ID.
• Database-level protections prevent UPDATE and DELETE operations on the compliance_decisions table in production environments.

Retention and Reporting

• Retention period: 7 years (aligned with the strictest regulatory requirement across all 13 jurisdictions).
• Export format: Compliance records are exportable in ISO 20022 format for regulatory reporting to financial supervisors.
• On-chain anchoring: Daily Merkle root of all compliance decisions is anchored to the JIL L1 chain, providing a tamper-evident timestamp proof that the audit trail has not been altered after the fact.

9. Competitive Advantage

JIL Sovereign's compliance architecture provides capabilities that are not available from any single analytics vendor or standalone compliance platform. The combination of multi-provider aggregation, native settlement integration, and patented enforcement mechanisms creates a compliance moat that is difficult to replicate.