# vz-kore-adapter

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.