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.

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.