From 2ee4fea84eb95c00c4941b28a0a4647adcb75516 Mon Sep 17 00:00:00 2001
From: JA <j@vectorzulu.com>
Date: Sat, 4 Jul 2026 02:10:41 +0000
Subject: [PATCH] Add README.md

---
 README.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 89 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6239e43..15ee914 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,91 @@
 # vz-kore-adapter
 
-Vector Zulu KoreID translation layer — converts Ethereum events to KoreID format and posts back to KoreChain
\ No newline at end of file
+Vector Zulu KoreID Translation Layer
+
+Converts Ethereum events (Mint, Burn, Transfer on SV tokens) into KoreID-formatted payloads and posts them back to KoreChain via KoreOracle API.
+
+## Architecture
+
+```
+Ethereum mainnet
+    ↓ (Transfer/Mint/Burn events)
+eth_listener.py
+    ↓ (KoreID payload)
+Redis queue (korechain:outbound_queue)
+    ↓
+korechain_poster.py
+    ↓ (mTLS + JWT)
+KoreOracle API → KoreChain
+```
+
+## Services
+
+| Service | Port | Purpose |
+|---|---|---|
+| vz-eth-listener | — | Watches SV token events on Ethereum |
+| vz-korechain-poster | — | Posts KoreID payloads to KoreChain |
+| vz-adapter-api | 8766 | Status, monitoring, manual injection |
+
+## KoreID Format
+
+```
+<S1>/<S2>-<S3>-<S4>-<S5>-<S6>
+
+S1 (8)  = DDMMYY + CT (ID type)
+S2 (8)  = PT (parent type) + T (parent treasury) + PNNNNN (parent network)
+S3 (4)  = CCC (currency) + CK (checksum)
+S4 (4)  = First 4 hex of current network
+S5 (4)  = Last 4 hex of current network
+S6 (12) = PPPP (parent seq) + T (treasury) + CCCC (current seq) + RRR (nonce)
+```
+
+## ⚠️ TODO — Awaiting Bryan's spec
+
+The lookup tables in `koreid.py` and `init.sql` use placeholder codes.
+Once Bryan provides the full KoreID spec with:
+- `kore_id_type` codes
+- `kore_treasury` codes  
+- `kore_network` codes
+- `kore_network_current` codes
+- `kore_currency` codes
+
+Update the `DICT` constants in `koreid.py` and the seed data in `init.sql`.
+
+Also awaiting:
+- KoreOracle API endpoint for external event posting (`/api/external/event` is a placeholder)
+- KoreID format for the `linked_koreid` field (to link VZ events to originating KoreNet transactions)
+
+## Deployment
+
+Runs on Charlie (63.245.138.38) alongside `charlie-vault-cache`.
+Shares the same Redis and Postgres instances.
+
+```bash
+cd ~/vz-kore-adapter
+docker compose up -d
+```
+
+## API Endpoints
+
+```
+GET  /health              — service status, queue depth
+GET  /queue               — current queue contents
+GET  /events              — recent posted events
+GET  /dead-letter         — failed events
+POST /dead-letter/retry   — requeue failed events
+POST /generate            — generate a test KoreID
+POST /inject              — manually inject an event
+```
+
+## Traceability
+
+Every KoreID payload preserves:
+- `koreid` — the KoreID display number
+- `guid` — UUIDv4 for internal tracking
+- `proof.hash` — Ethereum TX hash
+- `proof.block_number` — block number for verification
+- `proof.chain_reference` — KoreID back-reference
+- `source.tx_hash` — original Ethereum transaction
+
+Per Bryan's spec: Vector Zulu never strips identity, never generates fake IDs,
+never bypasses KoreOracle, never rewrites chain history.