7ac74f432b
- Institutional / JVMTM / reserve-provenance / GRU transport + standards JSON - Validation and verify scripts (Blockscout labels, x402, GRU preflight, P1 local path) - Wormhole wiring in AGENTS, MCP_SETUP, MASTER_INDEX, 04-configuration README - Meta docs, integration gaps, live verification log, architecture updates - CI validate-config workflow updates Operator/LAN items, submodule working trees, and public token-aggregation edge routes remain follow-up (see TODOS_CONSOLIDATED P1). Made-with: Cursor
703 lines
10 KiB
Markdown
703 lines
10 KiB
Markdown
# HYBX Jurisdictional Cheat Sheets — Technical Plan
|
|
|
|
## Purpose
|
|
|
|
Design a comprehensive **Jurisdictional Intelligence System (JIS)** that functions as the financial equivalent of a global intelligence reference, similar in concept to the CIA World Factbook but specialized for banking, payments, liquidity movement, settlement routing, and regulatory execution.
|
|
|
|
This system provides **deterministic jurisdiction knowledge** used by the Compliance & Routing Sidecar to ensure that every transaction is legally executable within applicable jurisdictions.
|
|
|
|
## Implementation tracking (2026-03-30)
|
|
|
|
Ship work is tracked as **P1-E02** in `docs/00-meta/TODOS_CONSOLIDATED.md` (with the compliance/routing sidecar plan). This document is **design/spec** only.
|
|
|
|
---
|
|
|
|
# Core Objective
|
|
|
|
Create a structured, versioned, queryable **Book of Jurisdictional Cheat Sheets** covering every jurisdiction where financial activity may occur.
|
|
|
|
Each jurisdiction profile must provide:
|
|
|
|
- Regulatory constraints
|
|
- Currency permissions
|
|
- Settlement rules
|
|
- Liquidity restrictions
|
|
- Licensing requirements
|
|
- Cross-border permissions
|
|
- Fee constraints
|
|
- Compliance requirements
|
|
|
|
This becomes the **ground truth registry** for jurisdictional logic.
|
|
|
|
---
|
|
|
|
# Core Concept
|
|
|
|
The Jurisdictional Cheat Sheets system acts as:
|
|
|
|
1. Jurisdiction Knowledge Base
|
|
2. Compliance Reference Library
|
|
3. Routing Constraint Source
|
|
4. FX Permission Authority
|
|
5. Settlement Legality Validator
|
|
6. Institutional Licensing Reference
|
|
|
|
---
|
|
|
|
# System Role in Overall Architecture
|
|
|
|
Primary Consumers:
|
|
|
|
- Compliance Sidecar
|
|
- Routing Engine
|
|
- Liquidity Engine
|
|
- Transaction Composer
|
|
- Risk Engine
|
|
|
|
Integration Flow:
|
|
|
|
Transaction Graph → Sidecar → Jurisdiction Lookup → Decision Output
|
|
|
|
## Mapping to `transaction-composer/`
|
|
|
|
`transaction-composer/` should be treated as the human-facing authoring client for jurisdiction-aware transaction design.
|
|
|
|
The practical flow is:
|
|
|
|
1. Composer generates the transaction graph.
|
|
2. Composer compiles the graph into a normalized transaction request.
|
|
3. Compliance & Routing Sidecar resolves the relevant jurisdictions.
|
|
4. Jurisdictional Cheat Sheets return:
|
|
- currency permissions
|
|
- cross-border restrictions
|
|
- licensing requirements
|
|
- settlement legality
|
|
- reporting thresholds
|
|
5. Sidecar returns the decision package back to the composer UI for operator review.
|
|
|
|
This means the cheat-sheet system is not a standalone reporting tool only. It is an online policy backend for the sidecar and a visible explanation source for the composer.
|
|
|
|
---
|
|
|
|
# System Architecture Overview
|
|
|
|
## Primary Subsystems
|
|
|
|
1. Jurisdiction Registry
|
|
2. Policy Knowledge Base
|
|
3. Currency Rules Engine
|
|
4. Licensing Database
|
|
5. Cross-Border Rule Engine
|
|
6. Reporting and Visualization Layer
|
|
|
|
---
|
|
|
|
# Jurisdiction Registry Design
|
|
|
|
## Purpose
|
|
|
|
Maintain canonical jurisdiction definitions.
|
|
|
|
Each jurisdiction receives a **Jurisdiction ID**.
|
|
|
|
---
|
|
|
|
## Core Fields
|
|
|
|
Each jurisdiction record includes:
|
|
|
|
Jurisdiction ID
|
|
Country Name
|
|
ISO Country Code
|
|
Region
|
|
Capital City
|
|
Primary Financial Regulator
|
|
Secondary Regulators
|
|
Legal System Type
|
|
Central Bank Name
|
|
Currency
|
|
Time Zones
|
|
Languages
|
|
Political Risk Tier
|
|
Financial Risk Tier
|
|
Sanctions Status
|
|
|
|
---
|
|
|
|
# Regulatory Metadata Layer
|
|
|
|
## Purpose
|
|
|
|
Capture jurisdiction-specific financial regulations.
|
|
|
|
---
|
|
|
|
## Regulatory Categories
|
|
|
|
### Banking Regulations
|
|
|
|
Fields:
|
|
|
|
Bank Licensing Requirements
|
|
Minimum Capital Requirements
|
|
Reserve Requirements
|
|
Reporting Requirements
|
|
Audit Requirements
|
|
|
|
---
|
|
|
|
### Payments Regulations
|
|
|
|
Fields:
|
|
|
|
Allowed Payment Types
|
|
Domestic Settlement Systems
|
|
Real-Time Gross Settlement Availability
|
|
Instant Payment Availability
|
|
Payment Network Participation
|
|
|
|
---
|
|
|
|
### FX Regulations
|
|
|
|
Fields:
|
|
|
|
FX Convertibility Status
|
|
Allowed Currency Pairs
|
|
Capital Controls
|
|
FX Approval Requirements
|
|
Maximum FX Limits
|
|
|
|
---
|
|
|
|
### Cross-Border Regulations
|
|
|
|
Fields:
|
|
|
|
Outbound Transfer Permissions
|
|
Inbound Transfer Permissions
|
|
Restricted Jurisdictions
|
|
Reporting Thresholds
|
|
Documentation Requirements
|
|
|
|
---
|
|
|
|
# Currency Rules Engine
|
|
|
|
## Purpose
|
|
|
|
Define currency behavior within jurisdiction.
|
|
|
|
---
|
|
|
|
## Currency Model
|
|
|
|
Currency Code
|
|
Convertibility Level
|
|
Settlement Type
|
|
Liquidity Availability
|
|
Central Bank Restrictions
|
|
Digital Currency Support
|
|
|
|
---
|
|
|
|
# Licensing Database Design
|
|
|
|
## Purpose
|
|
|
|
Track institutional permissions.
|
|
|
|
---
|
|
|
|
## License Types
|
|
|
|
Commercial Bank License
|
|
Remittance License
|
|
Money Services License
|
|
Broker License
|
|
Liquidity Provider License
|
|
|
|
---
|
|
|
|
## License Fields
|
|
|
|
License ID
|
|
License Type
|
|
Issuing Authority
|
|
Validity Period
|
|
Operational Scope
|
|
Restrictions
|
|
|
|
---
|
|
|
|
# Cross-Border Rule Engine
|
|
|
|
## Purpose
|
|
|
|
Define international transaction permissions.
|
|
|
|
---
|
|
|
|
## Rule Types
|
|
|
|
Country-to-Country Transfer Rules
|
|
Currency Export Rules
|
|
Sanctions Restrictions
|
|
Dual-Control Requirements
|
|
Capital Flow Restrictions
|
|
|
|
---
|
|
|
|
# Settlement Infrastructure Registry
|
|
|
|
## Purpose
|
|
|
|
Catalog financial settlement systems.
|
|
|
|
---
|
|
|
|
## Settlement System Fields
|
|
|
|
System Name
|
|
Settlement Type
|
|
Operating Hours
|
|
Supported Currencies
|
|
Settlement Finality Model
|
|
Participation Requirements
|
|
|
|
Examples:
|
|
|
|
RTGS
|
|
ACH
|
|
Instant Payment Systems
|
|
Cross-border Clearing Networks
|
|
|
|
---
|
|
|
|
# Liquidity Infrastructure Registry
|
|
|
|
## Purpose
|
|
|
|
Identify available liquidity channels.
|
|
|
|
---
|
|
|
|
## Liquidity Fields
|
|
|
|
Liquidity Providers
|
|
Supported Currency Pools
|
|
Liquidity Windows
|
|
Collateral Requirements
|
|
Liquidity Limits
|
|
|
|
---
|
|
|
|
# Fee Governance Model
|
|
|
|
## Purpose
|
|
|
|
Define jurisdictional fee constraints.
|
|
|
|
---
|
|
|
|
## Fee Fields
|
|
|
|
Maximum Allowed Fees
|
|
Regulated Fee Categories
|
|
Mandatory Fee Disclosures
|
|
Taxation Rules
|
|
Stamp Duty Rules
|
|
|
|
---
|
|
|
|
# Risk Intelligence Layer
|
|
|
|
## Purpose
|
|
|
|
Provide jurisdictional risk indicators.
|
|
|
|
---
|
|
|
|
## Risk Indicators
|
|
|
|
Political Stability Index
|
|
Regulatory Stability Index
|
|
Financial Crime Risk
|
|
AML Risk Tier
|
|
Sanctions Risk Tier
|
|
Currency Volatility Index
|
|
|
|
---
|
|
|
|
# Sanctions Intelligence Module
|
|
|
|
## Purpose
|
|
|
|
Track restricted jurisdictions.
|
|
|
|
---
|
|
|
|
## Sanctions Fields
|
|
|
|
Sanctioning Authority
|
|
Sanctions Type
|
|
Restricted Activities
|
|
Blocked Entities
|
|
Sector Restrictions
|
|
|
|
---
|
|
|
|
# Documentation Requirements Engine
|
|
|
|
## Purpose
|
|
|
|
Define required transaction documentation.
|
|
|
|
---
|
|
|
|
## Documentation Types
|
|
|
|
Customer Identification
|
|
Beneficiary Documentation
|
|
Source of Funds Declaration
|
|
Purpose of Payment
|
|
Regulatory Filings
|
|
|
|
---
|
|
|
|
# Data Model Design
|
|
|
|
## Core Structure
|
|
|
|
Each jurisdiction stored as structured object.
|
|
|
|
Example:
|
|
|
|
{
|
|
jurisdictionId,
|
|
regulator,
|
|
currencyRules,
|
|
fxRules,
|
|
settlementSystems,
|
|
licensingRules,
|
|
crossBorderRules,
|
|
riskProfile
|
|
}
|
|
|
|
---
|
|
|
|
# Versioning Architecture
|
|
|
|
Every jurisdiction profile is versioned.
|
|
|
|
Supports:
|
|
|
|
Historical snapshots
|
|
Policy rollback
|
|
Audit tracking
|
|
|
|
---
|
|
|
|
# Update Model
|
|
|
|
Updates triggered by:
|
|
|
|
Regulatory change
|
|
Policy update
|
|
Market changes
|
|
|
|
---
|
|
|
|
# Data Acquisition Model
|
|
|
|
Sources include:
|
|
|
|
Official regulatory publications
|
|
Central bank releases
|
|
Financial supervisory authorities
|
|
International financial organizations
|
|
Licensed legal intelligence providers
|
|
|
|
---
|
|
|
|
# Data Normalization Layer
|
|
|
|
Normalize all incoming jurisdiction data.
|
|
|
|
Ensure consistent schema alignment.
|
|
|
|
---
|
|
|
|
# Validation Model
|
|
|
|
Each jurisdiction profile must pass validation checks.
|
|
|
|
Checks include:
|
|
|
|
Field completeness
|
|
Logical consistency
|
|
Policy compatibility
|
|
|
|
---
|
|
|
|
# Query Interface Design
|
|
|
|
Provide high-speed lookup capability.
|
|
|
|
Example Queries:
|
|
|
|
Get FX permissions for USD → IDR
|
|
Check cross-border transfer legality
|
|
Retrieve settlement options
|
|
Fetch licensing requirements
|
|
|
|
---
|
|
|
|
# API Architecture
|
|
|
|
Primary Endpoint:
|
|
|
|
GET /jurisdiction/{id}
|
|
|
|
Returns full jurisdiction profile.
|
|
|
|
---
|
|
|
|
# Search Capability
|
|
|
|
Enable multi-dimensional search.
|
|
|
|
Search filters:
|
|
|
|
Country
|
|
Currency
|
|
Regulator
|
|
Risk Tier
|
|
Settlement Availability
|
|
|
|
---
|
|
|
|
# Integration with Sidecar
|
|
|
|
Sidecar queries jurisdiction data during validation.
|
|
|
|
Used for:
|
|
|
|
Routing validation
|
|
Compliance validation
|
|
Liquidity validation
|
|
|
|
---
|
|
|
|
# Caching Model
|
|
|
|
Frequently accessed jurisdictions cached.
|
|
|
|
Cache TTL configurable.
|
|
|
|
---
|
|
|
|
# Storage Architecture
|
|
|
|
Primary Storage:
|
|
|
|
PostgreSQL
|
|
|
|
Secondary Storage:
|
|
|
|
ElasticSearch (search index)
|
|
|
|
Optional:
|
|
|
|
Graph Database
|
|
|
|
---
|
|
|
|
# Visualization Interface
|
|
|
|
Provide UI dashboard.
|
|
|
|
Displays:
|
|
|
|
Jurisdiction Overview
|
|
Currency Rules
|
|
Risk Indicators
|
|
Settlement Systems
|
|
|
|
---
|
|
|
|
# Dashboard Components
|
|
|
|
Interactive maps
|
|
Jurisdiction comparison tables
|
|
Risk heat maps
|
|
Compliance summaries
|
|
|
|
---
|
|
|
|
# Policy Linking Model
|
|
|
|
Each jurisdiction links to policy references.
|
|
|
|
Policies stored separately.
|
|
|
|
Referenced dynamically.
|
|
|
|
---
|
|
|
|
# Multi-Jurisdiction Simulation Support
|
|
|
|
Support modeling of multi-country flows.
|
|
|
|
Example:
|
|
|
|
USD → Indonesia → Botswana → Malta
|
|
|
|
Simulate legal pathway.
|
|
|
|
---
|
|
|
|
# Localization Support
|
|
|
|
Support multilingual output.
|
|
|
|
Languages configurable.
|
|
|
|
---
|
|
|
|
# Audit Trail Model
|
|
|
|
All changes logged.
|
|
|
|
Includes:
|
|
|
|
User
|
|
Timestamp
|
|
Change Summary
|
|
Previous Version
|
|
|
|
---
|
|
|
|
# Security Architecture
|
|
|
|
Access Control:
|
|
|
|
Role-Based Access Control (RBAC)
|
|
|
|
Encryption:
|
|
|
|
Data-at-rest encryption
|
|
Data-in-transit encryption
|
|
|
|
---
|
|
|
|
# Observability Architecture
|
|
|
|
Track:
|
|
|
|
Lookup latency
|
|
Query frequency
|
|
Update frequency
|
|
|
|
---
|
|
|
|
# Performance Targets
|
|
|
|
Lookup latency target:
|
|
|
|
< 100 ms
|
|
|
|
Search latency target:
|
|
|
|
< 300 ms
|
|
|
|
---
|
|
|
|
# Horizontal Scaling Model
|
|
|
|
Scale by:
|
|
|
|
Jurisdiction clusters
|
|
|
|
Regions grouped geographically.
|
|
|
|
---
|
|
|
|
# Global Coverage Requirement
|
|
|
|
System must support:
|
|
|
|
All sovereign states
|
|
Dependent territories
|
|
Special financial jurisdictions
|
|
|
|
---
|
|
|
|
# Jurisdiction Classification Model
|
|
|
|
Classify jurisdictions into tiers.
|
|
|
|
Example:
|
|
|
|
Tier 1 — Major Financial Centers
|
|
Tier 2 — Regional Banking Hubs
|
|
Tier 3 — Restricted or Emerging Jurisdictions
|
|
|
|
---
|
|
|
|
# Deployment Model
|
|
|
|
Deploy as independent service.
|
|
|
|
Accessible via API.
|
|
|
|
---
|
|
|
|
# Backup Strategy
|
|
|
|
Nightly backups required.
|
|
|
|
Geo-redundant storage recommended.
|
|
|
|
---
|
|
|
|
# Minimum Viable Jurisdiction Dataset
|
|
|
|
Initial coverage:
|
|
|
|
Top 50 global financial jurisdictions.
|
|
|
|
Includes:
|
|
|
|
United States
|
|
Indonesia
|
|
Singapore
|
|
Switzerland
|
|
Malta
|
|
United Kingdom
|
|
European Union jurisdictions
|
|
|
|
---
|
|
|
|
# Production Expansion Plan
|
|
|
|
Phase 1:
|
|
|
|
Core jurisdictions.
|
|
|
|
Phase 2:
|
|
|
|
Full global coverage.
|
|
|
|
Phase 3:
|
|
|
|
Real-time regulatory updates.
|
|
|
|
---
|
|
|
|
# Final Outcome
|
|
|
|
When complete, the Jurisdictional Cheat Sheets system becomes:
|
|
|
|
A continuously updated, machine-readable global financial intelligence reference that enables compliant, optimized, jurisdiction-aware financial transaction execution.
|