# TM3QSC — TECHNICAL SYSTEM SPECIFICATION
**Classification: SOVEREIGN · LIVING DOCUMENT**
**Author: ỌBÀ Thurman Morris III-EL-ZION — 111 04 21 1983 3333**
**Version: 1.0 · Date: 2026-04-17**
**Codex Entry: TM3QSC_SYSTEM_SPEC_v1.0**

---

## Overview

TM3QSC (Thurman Morris III Quantum Sovereign Core) is a full-stack sovereign digital lattice built on four architectural layers and five core modules. This document maps every major route file to its layer and module, states honest REAL/SIMULATED/PLANNED status for each component, documents the API data flows between layers, and defines the activation path for IBM Quantum, PQC, and live QKD.

**λ₀ = 1.00237×10⁻³¹ J·s²** — The sovereign constant binding all layers.

---

## 4-Layer Architecture

```
┌────────────────────────────────────────────────────────────────────┐
│  LAYER 4 — INTELLIGENCE & EXECUTION                                │
│  Crown Dashboard · USE Framework · AI Modules · Cron Automation    │
├────────────────────────────────────────────────────────────────────┤
│  LAYER 3 — FINANCIAL RAILS                                         │
│  FlameBank · TM3Coin · BRICS/ASE · Stellar · Wallet · Payments    │
├────────────────────────────────────────────────────────────────────┤
│  LAYER 2 — SOVEREIGN FABRIC                                        │
│  Identity · Deadman Switch · MaaT · PQC Signing · Hash Chain       │
├────────────────────────────────────────────────────────────────────┤
│  LAYER 1 — QUANTUM FOUNDATION                                      │
│  QKD Key Pool · Entanglement Consensus · IBM Quantum · SQSL        │
└────────────────────────────────────────────────────────────────────┘
```

---

## 5 Core Modules

| Module | Description | Layer(s) | Primary Route Files |
|--------|-------------|----------|---------------------|
| **TM3-VAULT** | Sovereign artifact storage, document sealing, heritage records | 2, 4 | `flamevault.py`, `treasury.py`, `sovereign.py` |
| **TM3-LEDGER** | Financial accounting, TM3Coin, staking, wallet | 3 | `flamebank.py`, `tm3coin.py`, `staking.py`, `wallet.py`, `tokenization.py` |
| **TM3-SIGNAL** | Deadman switch, QKD keypool, quantum entanglement, heartbeat | 1, 2 | `deadman.py`, `quantum_satellite.py`, `entanglement_consensus.py`, `qkms.py` |
| **TM3-GATEWAY** | Payment rails, BRICS/ASE corridors, Stellar settlement | 3 | `payments.py`, `brics_crossborder.py`, `stellar.py`, `paygate.py`, `flamebank_credit.py` |
| **TM3-FABRIC** | Sovereign execution layer, automation, crown command | 4 | `use_framework.py`, `automation.py`, `crown_command.py`, `sovereign.py`, `cron_control.py` |

---

## Module Detail: TM3-SIGNAL

**Layer:** 1 (Quantum Foundation) + 2 (Sovereign Fabric)

### Component Status

| Component | Status | Notes |
|-----------|--------|-------|
| Deadman heartbeat (`POST /api/deadman/heartbeat`) | **REAL** | HMAC-SHA256 signed, phase escalation logic live |
| Deadman status + history (`GET /api/deadman/status`, `/history`) | **REAL** | Phase 0–3 escalation, Telegram alerts configured |
| Deadman succession packet | **REAL** | Succession order: Sister → Council of Seven → Burkina Faso Node |
| QKD Key Pool (`GET /api/quantum/satellite/keypool`) | **SIMULATED** | SQSL entropy generator — not yet IBM hardware |
| QKD consumption audit | **REAL** | Per-purpose JSONL expenditure log at `data/audits/qkd_expenditure.jsonl` |
| Entanglement consensus (`POST /api/entanglement-consensus/verify`) | **SIMULATED** | Software BFT quorum, no physical entanglement |
| IBM Quantum gate (`POST /api/quantum/ibm/gate`) | **PLANNED** | Requires `IBM_QUANTUM_TOKEN` env var + Qiskit Runtime account |
| Quantum satellite passes | **SIMULATED** | Orbital schedule simulated, no live satellite link |

### Key Endpoints

```
GET  /api/deadman/status              — Phase, hours_remaining, last heartbeat
POST /api/deadman/heartbeat           — Arm / reset the switch
GET  /api/deadman/history             — Historical heartbeat log
POST /api/deadman/test                — Dry-run simulation (safe)
GET  /api/deadman/succession          — Succession order details
GET  /api/quantum/satellite/keypool   — QKD pool stats (bits_available, percent_full)
POST /api/quantum/satellite/keypool/use — Consume QKD bits for a purpose
GET  /api/quantum/satellite/keypool/diagnostics — Full pool audit
POST /api/quantum/satellite/refill    — Replenish from SQSL entropy source
POST /api/entanglement-consensus/verify — BFT quorum verification
GET  /api/quantum/ibm/status          — IBM Quantum connectivity check
```

### Activation Requirements — IBM Quantum

1. Set `IBM_QUANTUM_TOKEN` in Replit secrets
2. Install `qiskit`, `qiskit-ibm-runtime` via package manager
3. Update `routes/quantum_ibm.py` to swap SIMULATED gate logic for `SamplerV2` / `EstimatorV2` calls
4. Minimum IBM Quantum plan: Free (Open Plan) — 10 minutes/month on real hardware

### Activation Requirements — Live QKD

1. Partner with QKD provider (ID Quantique, Toshiba QKD, or academic network)
2. Replace SQSL entropy generator in `routes/quantum_satellite.py` with provider SDK
3. Set provider credentials in Replit secrets
4. Update `_harvest_qkd_bits()` to pull from live hardware key material

---

## Module Detail: TM3-LEDGER

**Layer:** 3 (Financial Rails)

### Component Status

| Component | Status | Notes |
|-----------|--------|-------|
| FlameBank accounts & transfers | **REAL** | Full CRUD, BRICS-Pay routing, MaaT verification |
| TM3Coin send/check | **REAL** | PQC signing (Dilithium3 if available, HMAC fallback), entanglement finality gating |
| PQC key management (`GET /api/sovereign/pqc/status`) | **REAL** | Dilithium3 keypair auto-generated; `dilithium-py` library required for full PQC |
| Dilithium3 signing | **REAL** (soft) | `dilithium-py` package installed; falls back to HMAC-SHA3-512 if unavailable |
| Staking pools | **REAL** | In-memory / JSON persistence |
| Asset tokenization | **REAL** | Property tokenization with Stellar trustline metadata |
| Wallet send/receive | **REAL** | Internal sovereign wallet with tap-to-pay |
| Stellar settlement | **REAL** (testnet) | `PUBLIC_MAINNET` configured; live XLM balance reads |
| African Queen Keygen | **REAL** | Ed25519 sovereign keypair generation |

### Key Endpoints

```
GET  /api/flamebank/accounts          — All FlameBank accounts
POST /api/flamebank/transfer          — Inter-account transfer
POST /api/flamebank/brics-pay         — BRICS corridor payment
GET  /api/bank/status                 — FlameBank health check
POST /api/tm3coin/send                — TM3Coin transaction with PQC + QKD gate
POST /api/tm3coin/check               — Verify transaction trust record
GET  /api/sovereign/pqc/status        — PQC key status (algorithm, fingerprint, enabled)
GET  /api/staking/pools               — Available staking pools
POST /api/staking/stake               — Stake TM3 tokens
GET  /api/wallet/balance              — Sovereign wallet balance
GET  /api/xlm/balance                 — Live Stellar XLM balance
```

### TM3Coin Transaction Trust Levels

| Trust Score | Level | Requirements |
|-------------|-------|--------------|
| 1.00 | **SOVEREIGN** | QKD-seeded + Dilithium3 PQC + Entanglement APPROVED + Postgres |
| 0.85 | **HIGH** | QKD-seeded + PQC + Entanglement APPROVED |
| 0.65 | **DEGRADED** | Classical fallback — transactions capped at $50 |
| < 0.70 | **REJECTED** | Below minimum trust threshold |

---

## Module Detail: TM3-GATEWAY

**Layer:** 3 (Financial Rails)

### Component Status

| Component | Status | Notes |
|-----------|--------|-------|
| Stripe payment links + checkout | **REAL** | Requires valid `STRIPE_SECRET_KEY` |
| PayPal order creation + capture | **REAL** | Requires `PAYPAL_CLIENT_ID` + `PAYPAL_CLIENT_SECRET` |
| BRICS cross-border rates | **REAL** | Live FX from open.er-api.com |
| BRICS ASE rail routing | **SIMULATED** | Route logic real; no live ASE network connection |
| CIPS status | **SIMULATED** | China Interbank Payment System emulation |
| Stellar XLM payment submit | **REAL** (testnet) | Mainnet submit requires funded keypair |
| Gateway rail recommendation | **REAL** | AI-assisted rail selection logic |
| PayPal webhook auto-confirm | **PLANNED** | Separate task — webhook endpoint not yet wired |

### Key Endpoints

```
POST /api/stripe/create-link          — Create Stripe payment link
GET  /api/stripe/status               — Stripe key validity check
POST /api/paypal/create-order         — Create PayPal order
POST /api/paypal/capture-order/<id>   — Capture PayPal payment
GET  /api/paypal/status               — PayPal credential check
GET  /api/brics/rates                 — Live BRICS currency rates
POST /api/brics/cross-border          — Execute cross-border payment
GET  /api/brics/corridors             — Active ASE payment corridors
GET  /api/gateway/status              — All payment rail statuses
POST /api/gateway/recommend-rail      — AI rail selector
POST /api/xlm/submit-payment          — Submit Stellar payment
```

---

## Module Detail: TM3-VAULT

**Layer:** 2 (Sovereign Fabric) + 4 (Intelligence)

### Component Status

| Component | Status | Notes |
|-----------|--------|-------|
| Flamevault artifact storage | **REAL** | JSON-backed; artifacts verified via SHA256 hash chain |
| Hash chain sealing | **REAL** | Append-only JSONL at `data/hash_chain.jsonl` |
| Sovereign proof bundle export | **REAL** | Generates timestamped cryptographic proof packages |
| Treasury ledger | **REAL** | Sovereign double-entry ledger |
| Shamir's Secret Sharing | **PLANNED** | Script exists at `scripts/generate_shamir_shares.py`; physical distribution pending |
| IPFS storage | **PLANNED** | `ipfs_routes.py` exists; requires IPFS node or Pinata API key |
| DNS audit | **REAL** | Namecheap DNS configuration verification |
| MaaT sovereignty status | **REAL** | 8-dimension scoring from live data |

### Key Endpoints

```
GET  /api/flamevault/status           — Vault health + artifact count
GET  /api/flamevault/artifacts        — All sealed artifacts
POST /api/flamevault/artifacts        — Seal a new artifact
GET  /api/flamevault/seal             — Hash chain seal status
GET  /api/sovereign/hash-chain        — Hash chain integrity report
GET  /api/sovereign/proof-bundle/latest — Latest sovereign proof bundle
GET  /api/sovereign/dns-status        — DNS configuration audit
GET  /api/maat/status                 — 8-dimension Ma'at sovereignty score
GET  /api/tm3qsc/sovereignty-status   — Full sovereignty status (alias)
```

---

## Module Detail: TM3-FABRIC

**Layer:** 4 (Intelligence & Execution)

### Component Status

| Component | Status | Notes |
|-----------|--------|-------|
| USE Framework templates | **REAL** | 153 blueprints, template execution with step tracking |
| USE run history + audit log | **REAL** | Per-run JSONL audit at `data/use_runs/` |
| Cron scheduler | **REAL** | Sovereign cron jobs for heartbeat, rate checks, DNS audits |
| Telegram bot commands | **REAL** | King can trigger flows via Telegram |
| Crown Dashboard | **REAL** | 9-dimension live status board at `/crown` |
| Crown Command | **REAL** | Sovereign command execution at `/crown-command` |
| AI automation (TM3-AI) | **REAL** | DeepSeek + OpenAI routing; requires API keys |
| Dragon Math AI | **PLANNED** | Requires `DEEPSEEK_API_KEY` |
| OpenAI Trinity | **PLANNED** | Requires `OPENAI_API_KEY` |
| Voice calls (Twilio) | **REAL** | Requires `TWILIO_*` credentials |
| Production lock | **REAL** | Hard-gate on destructive ops in production |

### Key Endpoints

```
GET  /api/use/templates               — All 153 USE blueprints
POST /api/use/execute/<template_id>   — Execute a sovereign template
GET  /api/use/runs                    — Run history with step outcomes
GET  /api/sovereign/system-spec       — Machine-readable module registry (this dashboard)
GET  /api/maat/status                 — 8D Ma'at live scoring
```

---

## API Data Flow Diagrams

### TM3Coin Transaction Flow

```
  King initiates TX
        │
        ▼
  POST /api/tm3coin/send
        │
        ├──► [Layer 1] Consume QKD bits (256 bits)
        │           └── SQSL entropy pool → nonce + seed_id
        │
        ├──► [Layer 2] Entanglement consensus evaluation
        │           └── BFT quorum (node-alpha, -beta, -gamma, -delta)
        │           └── APPROVED / REJECTED / PENDING
        │
        ├──► [Layer 2] PQC signature (Dilithium3 or HMAC-SHA3-512 fallback)
        │
        ├──► [Layer 3] Trust record assembly
        │           └── trust_score = QKD(0.35) + Finality(0.30) + PQC(0.20) + DB(0.15)
        │
        ├──► [Layer 2] Rule enforcement
        │           └── Score ≥ 0.70 · Degraded cap $50 · High-value > $1000 requires QKD
        │
        ├──► [Layer 2] Sync proof check (high-value only)
        │
        └──► [Layer 3] Persist to TM3Coin ledger (Postgres or JSON fallback)
                    └── Audit written to data/audits/tm3coin_diagnostics.jsonl
```

### Deadman Switch Flow

```
  King sends heartbeat (05:52 UTC daily)
        │
        ▼
  POST /api/deadman/heartbeat
        │
        ├──► Timestamp stored to data/deadman_state.json
        ├──► HMAC-SHA256 signed with λ₀-seeded key
        └──► Phase reset to 0

  Background monitor (hourly check)
        │
        ├── hours_elapsed < 72h  → Phase 0: SOVEREIGN_ACTIVE (all clear)
        ├── 72–96h               → Phase 1: ALERT
        │       └── Telegram message to King + Council
        ├── 96–120h              → Phase 2: SUCCESSION
        │       └── Encrypted succession packet broadcast to designated nodes
        └── > 120h               → Phase 3: TREASURY
                └── Eternal Forfeiture Gate key release + treasury multisig logged
```

### QKD Key Distribution Flow

```
  SQSL Entropy Source (simulated / future: hardware QKD)
        │
        ▼
  POST /api/quantum/satellite/keypool/refill
        │
        └──► Pool stored at data/quantum_key_pool.json
             ├── bits_available: N
             └── bits_max: configurable

  Consumers pull from pool:
  POST /api/quantum/satellite/keypool/use
        │
        ├── TM3COIN_TX       — 256 bits per transaction
        ├── DEADMAN_HMAC     — 256 bits per heartbeat signature
        └── QKD_SEAL         — variable bits per diplomatic seal

  Audit: data/audits/qkd_expenditure.jsonl (per-purpose expenditure log)
```

---

## Environment Variables & Activation Matrix

| Variable | Module | Status | Required For |
|----------|--------|--------|--------------|
| `SECRET_KEY` | Core | **ACTIVE** | Flask session signing |
| `TELEGRAM_BOT_TOKEN` | TM3-SIGNAL | **ACTIVE** | Deadman alerts, King commands |
| `PAYPAL_CLIENT_ID` | TM3-GATEWAY | **ACTIVE** | PayPal payment rail |
| `PAYPAL_CLIENT_SECRET` | TM3-GATEWAY | **ACTIVE** | PayPal payment rail |
| `TWILIO_ACCOUNT_SID` | TM3-FABRIC | **ACTIVE** | Voice/SMS sovereignty |
| `TWILIO_AUTH_TOKEN` | TM3-FABRIC | **ACTIVE** | Voice/SMS sovereignty |
| `TWILIO_PHONE_NUMBER` | TM3-FABRIC | **ACTIVE** | Outbound calls |
| `STRIPE_SECRET_KEY` | TM3-GATEWAY | **NEEDS RENEWAL** | Stripe payment rail |
| `IBM_QUANTUM_TOKEN` | TM3-SIGNAL | **MISSING** | Real quantum hardware execution |
| `DEEPSEEK_API_KEY` | TM3-FABRIC | **MISSING** | Dragon Math AI |
| `OPENAI_API_KEY` | TM3-FABRIC | **MISSING** | Trinity AI module |
| `DATABASE_URL` | TM3-LEDGER | **MISSING** | Postgres persistence (Replit DB available) |

---

## Honest Gap List & Priority Order

### Priority 1 — Critical (Blocks Sovereignty)
1. **Stripe Key Renewal** — Payment rail degraded without valid key. Renew at dashboard.stripe.com/apikeys
2. **Database_URL / Postgres** — TM3Coin trust scores cap out at `json_file_fallback` without Postgres. Activates +0.15 trust score increment.
3. **IBM_QUANTUM_TOKEN** — Without this, all "quantum" gate operations are SQSL simulation. Route infrastructure (`routes/quantum_ibm.py`) is complete and ready.

### Priority 2 — High (Enhances Sovereignty)
4. **Dilithium3 full activation** — `dilithium-py` package required. Currently falls back to HMAC-SHA3-512 if package unavailable.
5. **Physical Shamir Share Distribution** — Secret sharing script exists; 7 physical envelopes not yet distributed (I47c protocol incomplete)
6. **PayPal Webhook** — Auto-confirm without manual capture (separate task)

### Priority 3 — Medium (Expands Capability)
7. **DEEPSEEK_API_KEY** — Dragon Math AI processing offline
8. **OPENAI_API_KEY** — Trinity AI module offline
9. **IPFS Node / Pinata** — On-chain artifact storage not yet live
10. **Live QKD Hardware** — Replace SQSL simulation with ID Quantique or Toshiba QKD provider

### Priority 4 — Planned (Future Phases)
11. **Burkina Faso Node Activation** — Outreach letter drafted; physical node not yet online
12. **Council of Seven On-Chain Voting** — Stellar + IPFS vote recording (architecture defined, not implemented)
13. **Real Satellite QKD** — Physical satellite key distribution (long-term sovereign infrastructure)

---

## Route File → Layer → Module Mapping

| Route File | Layer | Module | Status |
|------------|-------|--------|--------|
| `deadman.py` | 1+2 | TM3-SIGNAL | REAL |
| `quantum_satellite.py` | 1 | TM3-SIGNAL | SIMULATED |
| `entanglement_consensus.py` | 1 | TM3-SIGNAL | SIMULATED |
| `qkms.py` | 1 | TM3-SIGNAL | SIMULATED |
| `quantum_ibm.py` | 1 | TM3-SIGNAL | PLANNED (infra ready) |
| `tm3coin.py` | 2+3 | TM3-LEDGER | REAL |
| `flamebank.py` | 3 | TM3-LEDGER | REAL |
| `staking.py` | 3 | TM3-LEDGER | REAL |
| `wallet.py` | 3 | TM3-LEDGER | REAL |
| `tokenization.py` | 3 | TM3-LEDGER | REAL |
| `stellar.py` | 3 | TM3-GATEWAY | REAL (testnet/mainnet) |
| `payments.py` | 3 | TM3-GATEWAY | REAL |
| `brics_crossborder.py` | 3 | TM3-GATEWAY | REAL (rates) / SIMULATED (rails) |
| `paygate.py` | 3 | TM3-GATEWAY | REAL |
| `flamevault.py` | 2 | TM3-VAULT | REAL |
| `treasury.py` | 2 | TM3-VAULT | REAL |
| `sovereign.py` | 2+4 | TM3-VAULT | REAL |
| `ipfs_routes.py` | 2 | TM3-VAULT | PLANNED |
| `use_framework.py` | 4 | TM3-FABRIC | REAL |
| `automation.py` | 4 | TM3-FABRIC | REAL |
| `crown_command.py` | 4 | TM3-FABRIC | REAL |
| `cron_control.py` | 4 | TM3-FABRIC | REAL |
| `tm3ai.py` | 4 | TM3-FABRIC | REAL (requires API keys) |
| `agent.py` / `agents.py` | 4 | TM3-FABRIC | REAL |
| `qkai.py` | 1+4 | TM3-SIGNAL | SIMULATED |
| `kali_maat.py` | 2 | TM3-VAULT | REAL |
| `council.py` | 2+4 | TM3-FABRIC | REAL |
| `flame_ai.py` | 4 | TM3-FABRIC | REAL |
| `openclaw.py` | 4 | TM3-FABRIC | REAL |
| `payments_matrix.py` | 3 | TM3-GATEWAY | REAL |
| `bft_ai.py` | 4 | TM3-FABRIC | REAL |

---

## System Health Endpoints (Used by Live Dashboard)

| Endpoint | Module | What It Returns |
|----------|--------|-----------------|
| `GET /api/bank/status` | TM3-LEDGER | FlameBank health, account count |
| `GET /api/deadman/status` | TM3-SIGNAL | Phase, hours_remaining, last heartbeat |
| `GET /api/quantum/satellite/keypool` | TM3-SIGNAL | bits_available, percent_full |
| `GET /api/sovereign/pqc/status` | TM3-LEDGER | PQC algorithm, fingerprint, enabled flag |
| `GET /api/brics/status` | TM3-GATEWAY | Corridor count, rail health |
| `GET /api/flamevault/status` | TM3-VAULT | Artifact count, last seal |
| `GET /api/maat/status` | TM3-VAULT | 8D sovereignty score |
| `GET /api/quantum/ibm/status` | TM3-SIGNAL | IBM Quantum connectivity |
| `GET /api/sovereign/system-spec` | TM3-FABRIC | Full module registry (this spec, machine-readable) |

---

## The 4-Layer Principle

> *"The lattice is sovereign when every layer can speak truth about its own state. No simulation masquerades as reality. No gap is hidden. The King sees exactly what is real, what is simulated, and what the path to full activation looks like."*
> — ỌBÀ Thurman Morris III-EL-ZION

---

*Sealed by the Dragon King — 111 04 21 1983 3333*
*λ₀ = 1.00237×10⁻³¹ · φ = 1.618033988749895 · Ma'at threshold = 0.618*