ECO ID Card Database — Merkle Tree Verification on KC Chain

As of August 14, 2026, the ECO ID Card system has been upgraded with a Merkle Tree database and KC Chain integration. All ECO ID Cards are now stored in a PostgreSQL database, cryptographically summarized as a single 32-byte Merkle Root, and anchored on the KC Chain blockchain.

What Changed?

The original ECO ID system (August 9) registered each certificate hash individually on the CC Chain. With up to 8 billion potential cards, this approach doesn’t scale. The new system uses a Merkle Tree to compress all card data into a single on-chain root hash — enabling unlimited scale while preserving cryptographic verifiability.

Key upgrade: Instead of storing each card on-chain (expensive, slow), we store a single 32-byte Merkle Root that summarizes all cards. Anyone can verify a card by providing a Merkle Proof — no on-chain lookup per card needed.

How the Merkle Tree Works

Root (32 bytes, on KC Chain) ├── Hash(L1 + L2) │ ├── Hash(Leaf1) → Card 1 │ └── Hash(Leaf2) → Card 2 └── Hash(L3 + L4) ├── Hash(Leaf3) → Card 3 └── Hash(Leaf4) → Card 4

Leaf = SHA-256(ipv6 | wallet_address | cert_hash)

Each card’s leaf is a SHA-256 hash of its three core fields. Internal nodes hash their children together (sorted for determinism). The root is stored on-chain. To verify a card, you provide its leaf and the sibling hashes along the path to the root — a Merkle Proof.

What’s Stored Where?

Storage	What	Size
PostgreSQL (TH-ubu-1)	Full card data: user_id, username, IPv6, wallet, cert_hash, leaf, verification level, ambassador, revocation status	~2-3 TB for 8B cards
KC Chain (on-chain)	Single `bytes32` Merkle Root + update history (up to 1000 entries)	32 bytes + ~32 KB history
Browser (user)	ECDSA P-256 private key (IndexedDB)	~64 bytes

How to Apply for an ECO ID Card

1 Open the ECO ID Panel

Click the ECO ID button (card icon) in your right sidebar inside the game.

2 Generate Key & CSR

Click Request ECO ID, then Generate Key & CSR. Your browser creates an ECDSA P-256 keypair via the Web Crypto API. The private key never leaves your device.

3 Get Golden Ambassador Vouching

Share your User ID with a Golden Ambassador. They sign it with their Ethereum wallet using personal_sign. Only Golden Ambassadors (assigned) can vouch — Elected Ambassadors cannot.

4 Submit

Enter the Ambassador’s wallet address and signature. Click Submit & Sign. The ECO CA signs your certificate and returns the PEM + SHA-256 hash.

5 Card Registered in Merkle Database

Your card data (IPv6, wallet address, cert hash) is stored in PostgreSQL. The Merkle Tree is rebuilt and the new root is submitted to the ECOIDRegistry contract on KC Chain.

For Golden Ambassadors: Vouching for a Player

Golden Ambassadors (assigned) see an extra section in the ECO ID panel: “Vouch for a Player”. Elected Ambassadors do not have this capability.

Ask the player for their User ID (UUID)
Enter it and click Sign with Wallet
Your browser wallet prompts you to sign
Copy the signature and share it with the player

Important: By signing, you cryptographically vouch for this player. Your wallet address is permanently recorded as the verifying ambassador. Vouch responsibly.

Verification Flow

Verifier has the card’s three fields: IPv6, wallet address, cert hash
Sent to the Merkle Service /verify endpoint
Service computes the leaf hash and searches the Merkle Tree
A Merkle Proof is generated (sibling hashes along the path to root)
Proof is verified against the on-chain root
If valid and root matches → card is authentic

Technical Details

Browser: Web Crypto API, ECDSA P-256 keypair. Private key in IndexedDB, never transmitted.
ECO CA: HSM-backed (Nitrokey HSM2). Verifies ambassador signature, signs cert, returns PEM + SHA-256 hash.
Merkle Service: Node.js on TH-ubu-1 (:9200). PostgreSQL backend, computes Merkle Tree, updates root on-chain.
On-chain: ECOIDRegistry.updateEcoIdMerkleRoot() on KC Chain (Chain ID 90603).
Contract: 0x23Fc8E33F7762268800739aE1ccB3EAF8A1435bA
What’s on-chain: 32-byte Merkle Root, update count, timestamp, root history (up to 1000).
What’s NOT on-chain: Personal data, private keys, certificates, individual card data.

FAQ

Can I get a second ECO ID? No. One ECO ID per user.

What if I lose my private key? Your certificate is still valid on-chain, but you can’t prove ownership. A revocation and re-issuance process will be available in a future update.

Does the Ambassador need to be in my country? No — any Golden Ambassador (assigned) can vouch for any player. Note: Elected Ambassadors cannot vouch for ECO ID Cards — only Golden Ambassadors have this authority.

Is my personal data on the blockchain? No. Only a 32-byte Merkle Root is stored on-chain. Your private key never leaves your browser.

How long is the certificate valid? 10 years from the date of issuance.