VitoCoin — Complete Technical Disclosure

1.1 Frontend

• Language: Vanilla HTML/CSS/JavaScript (ES2020+, no transpiler)
• Entry point: /home/user/app/app.html — served directly by Vercel as a static file
• State management: Module-level JS variables + localStorage for session persistence (wallets, active address, cached balance)
• Routing: history.pushState — path-based page switching, no SPA framework
• Rendering: DOM manipulation via innerHTML and getElementById — no virtual DOM
• Real-time: EventSource (SSE) connected to /api/node/events; fallback polling every 30 s
• Auth: Supabase JS SDK (@supabase/supabase-js) via CDN script tag
• PWA: /manifest.json + /sw.js service worker, offline page, install banner

1.2 Backend / Node Server

• Language: Python 3.10+
• API server: api.py — ThreadingHTTPServer, one thread per request
• P2P network: network.py — asyncio event loop + raw TCP sockets, port 6334
• Miner: miner.py — Python threading.Thread per CPU core, SHA-256d in Python hashlib
• Blockchain core: blockchain.py, block.py, transaction.py, script.py, utxo.py
• Storage: store.py — SQLite via Python sqlite3
• Deployment: systemd service (vitocoin.service, Restart=always), one service per VPS

1.3 Blockchain

• Type: Custom clean-room implementation — not a fork of Bitcoin Core, Litecoin, or any existing chain
• Architecture: UTXO (Unspent Transaction Output) — identical model to Bitcoin
• Consensus: SHA-256d Proof-of-Work, heaviest cumulative chain work rule
• Smart contracts: None — basic P2PKH (Pay-to-Public-Key-Hash) scripts only
• Core logic files: blockchain.py (chain), block.py (structure + PoW), transaction.py (UTXO logic), utxo.py (UTXO set), network.py (P2P), miner.py (mining), api.py (REST + SSE)

1.4 Vercel Proxy Layer

• Platform: Vercel (static + serverless proxy)
• Project: vito-coin-v2
• Frontend: Static files served from /home/user/app/ (GitHub repo root)
• Proxy routes: /api/node/* → Node1 (195.114.193.73:6333), /api/node2/* → Node2 (213.139.77.18:6333), /api/node3/* → Node3 (84.201.20.90:6333)

1.5 Folder Structure (important files)

/home/user/app/                  ← Vercel deploy root
  app.html                       ← Entire frontend (~3,100 lines, vanilla JS)
  whitepaper.html                ← Investor whitepaper
  api-docs.html                  ← Interactive API documentation
  tech-disclosure.html           ← This document
  manifest.json                  ← PWA manifest
  sw.js                          ← Service worker (caching + offline)
  vercel.json                    ← Routing rules + proxy config
  features-p1.js / features-p2.js ← Lazy-loaded feature modules (charts, etc.)

/opt/vitocoin/vitocoin/          ← On each VPS node
  main.py                        ← Entry point (CLI args, service init)
  blockchain.py                  ← Chain state, tip tracking, block acceptance
  block.py                       ← Block structure, header serialisation, PoW validation
  transaction.py                 ← TX parsing, validation, coinbase check
  utxo.py                        ← UTXO set management, balance queries
  network.py                     ← P2P TCP, peer handshake, sync protocol
  miner.py                       ← CPU mining threads, nonce iteration
  api.py                         ← HTTP REST API + SSE /events endpoint
  store.py                       ← SQLite persistence layer
  script.py                      ← P2PKH script execution
  wallet.py                      ← Key derivation (BIP-44), address encoding

/opt/vitocoin/vitocoin/chaindata/
  chainstore.db                  ← SQLite database (blocks, UTXOs, metadata)

2.1 Block Creation

Blocks are created by the miner process on each node. When the miner finds a valid nonce, it assembles the block from the candidate template and calls chain.accept_block(block). The process:

1. Collect pending transactions from the mempool (currently always empty → coinbase only)
2. Build a coinbase transaction paying 50 VITO to the configured wallet address
3. Compute Merkle root of all transaction TXIDs (single-element tree = coinbase TXID)
4. Assemble 80-byte block header: version ∥ prev_hash ∥ merkle_root ∥ timestamp ∥ bits ∥ nonce
5. Iterate nonce 0–4,294,967,295 until SHA256d(header) < target
6. On valid nonce: persist block to SQLite, update UTXO set, relay to all peers via P2P

2.2 Mining Algorithm — SHA-256d

Identical to Bitcoin's Proof-of-Work algorithm:

block_hash = SHA256( SHA256( version[4] ∥ prev_hash[32] ∥ merkle_root[32]
                            ∥ timestamp[4] ∥ bits[4] ∥ nonce[4] ) )

# All fields little-endian (Bitcoin byte order)
# valid when:  int.from_bytes(block_hash, 'big') < target
  

2.3 Target Derivation from bits

The compact bits field encodes the target in Bitcoin's standard format:

bits      = 0x1d00ffff  (genesis difficulty, also current difficulty)
exponent  = (bits >> 24) & 0xFF  =  0x1d = 29
mantissa  = bits & 0x00FFFFFF    =  0x00ffff

target    = mantissa × 2^(8 × (exponent − 3))
          = 0x00ffff × 2^(8 × 26)
          = 0x00000000ffff0000000000000000000000000000000000000000000000000000

# In decimal:
target    = 26959535291011309493156476344723991336010898738574164086137773096960
  

2.4 Difficulty Formula

Difficulty retargets every 2,016 blocks (~2 weeks at 10-min target). No retarget has occurred yet (chain is at height 10):

expected_time = 600 × 2016         = 1,209,600 seconds
actual_time   = block[2016].ts − block[0].ts

# Anti-manipulation clamp:
actual_time   = max(expected_time / 4, min(actual_time, expected_time × 4))

new_target    = old_target × (actual_time / expected_time)
new_target    = min(new_target, genesis_target)   # floor — difficulty never drops below 1.0

current_difficulty = genesis_target / current_target
  

Current: difficulty = 1.0, bits = 0x1d00ffff (genesis minimum — no retarget yet)

2.5 Validation Logic Location

All validation happens in blockchain.py → accept_block() and block.py → validate():

• block.validate_pow() — SHA256d(header) < target from bits
• block.validate_merkle() — recompute Merkle root, compare to header field
• blockchain.py — height continuity, coinbase reward check, UTXO input validation
• utxo.py — every non-coinbase input must reference an existing unspent output
• script.py — input script must satisfy output script (P2PKH signature check)

2.6 Sample Block JSON — Block #10 (most recent)

{
  "hash": "00000000e060cafcd66eb2a4425a5e52a1490fbf6eec4af8ebf1fd94a77528de",
  "height": 10,
  "header": {
    "version": 2,
    "prev_hash": "000000003c218be4e1c22268a5ef00ecc468d56313126ba94240c795c4bd62cb",
    "merkle_root": "0f30bb164cbfc0db676d47cef352992ab543e8c349fd00fa1d566d7c1e121e9e",
    "timestamp": 1775706303,
    "bits": 486604799,
    "bits_hex": "1d00ffff",
    "nonce": 3242755474,
    "difficulty": 1.0
  },
  "tx_count": 1,
  "size": 177,
  "work": "4295032833",
  "transactions": [
    {
      "txid": "0f30bb164cbfc0db676d47cef352992ab543e8c349fd00fa1d566d7c1e121e9e",
      "version": 2,
      "locktime": 0,
      "is_coinbase": true,
      "inputs": [
        {"prev_txid": "0000000000000000000000000000000000000000000000000000000000000000",
         "prev_index": 4294967295}
      ],
      "outputs": [
        {"value": 5000000000, "value_vito": 50.0,
         "script_pubkey": "76a914e75a382381dfe9049ce8bce1f5842058d096f03388ac"}
      ],
      "size": 97
    }
  ]
}

2.7 PoW Verification — 3 Consecutive Blocks

Verification method: Python hashlib.sha256(hashlib.sha256(header_bytes).digest()).digest() with header fields serialised as little-endian uint32 (Bitcoin byte order). All three blocks independently confirmed valid.

3.1 Node Inventory (live at time of report)

3.2 Node Sync Protocol

Sync follows Bitcoin's headers-first protocol over TCP (port 6334), with JSON-encoded messages instead of Bitcoin's binary wire format:

1. Connection: TCP connect to peer IP:6334. Magic bytes: 0x56 0x49 0x54 0x4F ("VITO") prefix each message frame.
2. Handshake: version message (includes node height, user-agent, timestamp) → peer replies with version + verack → sender replies verack
3. Sync: If peer reports higher height in version message, send getheaders (with current tip hash) → peer replies with up to 2,000 block headers → sender validates each header's PoW → sends getdata for each missing block → peer sends full blocks
4. Accept: Each received block passes full validation in accept_block(). On success: persisted, UTXO set updated, relayed to other peers.
5. Transaction relay: inv message announces TX hash → peer sends getdata if unseen → TX sent → validated and added to mempool
6. Periodic resync: Every 10 seconds the node requests headers from all peers reporting a higher height (fallback for missed events)

3.3 Conflict Resolution (Fork Handling)

Fork resolution uses Bitcoin's canonical heaviest cumulative chain work rule, not longest chain:

canonical_chain = chain with max( sum(difficulty) for all blocks from genesis )

• If a peer presents a chain with higher cumulative work: switch to that chain (reorganise)
• Reorganisation: walk back to common ancestor, undo UTXOs for orphaned blocks, apply UTXOs for new chain blocks
• Orphaned transactions re-enter the mempool
• Currently no reorg has occurred (single-chain history, all nodes mining to same canonical chain)

3.4 Peer Discovery

• Hardcoded seeds: Each node has the other two nodes' IPs hardcoded in network.py → SEED_NODES
• Address exchange: getaddr / addr messages — nodes share up to 1,000 known peer addresses
• Reconnect: Outbound reconnect with exponential backoff on disconnect

4.1 Where Hashing Happens

4.2 Mining Architecture

• Thread model: Each node spawns N independent Python threads (Node 1: 8, Nodes 2 & 3: 4)
• Nonce space partitioning: Each thread works a different starting nonce offset to avoid duplicate work
• Timestamp updates: Template refreshed every ~30 seconds and on each new block from network
• Candidate block: Pre-built header template refreshed on each accept_block() call; each thread hashes the template with varying nonce
• Extra nonce: Field present but currently extra_nonce=0 — not incremented (nonce space of 4.3 billion is sufficient at current low difficulty)
• Block relay on find: Immediately calls accept_block() then broadcasts to all connected peers via P2P
• Wallet: All three nodes mine to Sovereign Founder Wallet — re-keyed Apr 12 2026 (see §3b transparency report) (admin wallet)

4.3 Live Hashrate at Time of Report

At current difficulty (1.0) and combined hashrate (~900 KH/s), the expected time per block is:

expected_hashes_per_block = 2^32 / 1.0 ≈ 4,294,967,296
time_per_block ≈ 4,294,967,296 / 902,000 ≈ 4,762 seconds (~79 minutes)

# Note: blocks 0–10 were mined at difficulty 1.0
# Target block time is 600 seconds (10 minutes)
# Current hashrate is insufficient to hit 10-min targets — addressed in Known Limitations
  

4.4 Shares / Pool

No pool protocol exists. Each node is a solo miner. When any node finds a block, it broadcasts to peers who verify and add to their chain. There is no share accounting, no pool fee, no vardiff.

5.1 Protocol

• Transport: HTTP/1.1 chunked transfer encoding, persistent keep-alive
• Direction: Server → client only (one-way push)
• Reconnect: Browser/client auto-reconnects on disconnect via EventSource API; frontend adds exponential backoff (2s → 4s → 8s → max 30s)

5.2 SSE Endpoint

# Direct node access:
http://195.114.193.73:6333/events
http://213.139.77.18:6333/events
http://84.201.20.90:6333/events

# Via Vercel proxy (HTTPS, production):
https://vitocoin.com/api/node/events

# Terminal test:
curl -N https://vitocoin.com/api/node/events
  

5.3 Event Types

5.4 Live Event Payload (captured from production)

event: block
data: {"height":10,"best_hash":"00000000e060cafcd66eb2a4425a5e52a1490fbf6eec4af8ebf1fd94a77528de",
       "difficulty":1.0,"peers":4,"mempool":0,"supply_vito":550.0,"block_reward":50.0,
       "next_halving":209990,"miner":{"mining":true,"hashrate":"184.81 KH/s",
       "hashrate_hps":184814.72,"blocks_found":0},"ts":1775728380}

event: ping
data: {"height":10,"best_hash":"00000000e060cafcd66eb2a4425a5e52a1490fbf6eec4af8ebf1fd94a77528de",
       "difficulty":1.0,"peers":4,"mempool":0,"supply_vito":550.0,"block_reward":50.0,
       "next_halving":209990,"miner":{"mining":true,"hashrate":"186.29 KH/s",
       "hashrate_hps":186293.33,"blocks_found":0},"ts":1775728381}
  

5.5 Frontend Integration

// app.html — SSE engine
const es = new EventSource('https://vitocoin.com/api/node/events');
es.addEventListener('block', (e) => {
  const d = JSON.parse(e.data);
  if (d.height > _sseLastHeight) {
    _sseLastHeight = d.height;
    refreshBalances();                        // re-query /balance/:addr
    loadOverviewTxs();                        // reload transaction history
    addNotification('success', `Block #${d.height} mined`);
  }
  // Update status bar: height, peers, difficulty, hashrate
});
es.onerror = () => {
  es.close();
  _sseRetryDelay = Math.min(_sseRetryDelay * 2, 30000);
  setTimeout(_connectSSE, _sseRetryDelay);
};
  

6.1 Blockchain Database

Schema: a single key-value table with binary keys and values:

CREATE TABLE kv (
    key   BLOB PRIMARY KEY,
    value BLOB
);
  

Data is stored via key prefix convention:

6.2 What is Stored

• Blocks: Full block objects (header + all transactions) stored in B: and b: namespaces
• Transactions: Indexed by TXID in T: for fast lookup by explorer
• UTXOs (balances): Every unspent output is in u:. Balance = sum of value fields for UTXOs with script matching address. No separate balance table.
• Address index: x: maps each address to its UTXO references (built on-the-fly as blocks accepted)
• Metadata: m:tip_hash, m:height, m:chain_work — loaded at startup to restore chain state

6.3 Auth Database (separate)

Stores only user authentication data and wallet metadata — NOT blockchain data:

6.4 Blockchain ↔ Database Sync

There is no sync to maintain. They are two independent systems:

• Blockchain balances are always queried live from /balance/:address which reads the UTXO set directly
• Supabase only stores which address belongs to which user — never cached balances
• There is no risk of stale balance data; every balance shown in the UI is a real-time query to the node

7.1 Auth Provider

• Method: Email + password
• Token type: JWT (RS256 signed by Supabase)
• Session storage: localStorage — Supabase SDK persists the access token and refresh token automatically
• Session refresh: Supabase SDK auto-refreshes JWT before expiry in background
• Anon key: Public key used in frontend for read-only Supabase table access — not a secret

7.2 Session Handling Flow

// 1. App opens
init() {
  loadWallets();         // Read wallets from localStorage (instant, no network)
  showPage('home');      // Render UI immediately from cached state

  // 2. Auth check runs IN BACKGROUND after UI is visible
  checkAuth() {
    const session = await supabase.auth.getSession(); // reads localStorage JWT
    if (!session) { showLoginModal(); return false; }
    // Validate JWT against Supabase (single HTTP call, ~200ms)
    // On success: fetch user's wallet addresses from 'wallets' table
    // Cache wallet data in localStorage
    return true;
  }

  // 3. SSE starts after auth resolves
  _connectSSE();
}
  

7.3 Why "Loading…" Appeared (historical)

Previously, the init function called checkAuth() before showPage(). The 200–400ms JWT validation round-trip caused the UI to show "Loading…" until auth resolved. This was fixed: the UI now renders from localStorage cache immediately, and auth runs in the background with a 4-second timeout fallback. The "Loading…" state no longer blocks interaction.

7.4 Auth Does NOT Affect Blockchain

Auth is purely a frontend gate for the web app. The node APIs (/api/node/*) have no authentication — they are fully public. Any blockchain data (blocks, transactions, balances) can be queried without a user account.

8.1 Model: UTXO (Unspent Transaction Output)

• Every transaction consumes one or more UTXOs (inputs) and creates one or more new UTXOs (outputs)
• Balance of an address = sum of all unspent outputs locked to that address's public key hash
• Change outputs: if input value exceeds payment amount, sender creates a change output back to themselves
• Currently only coinbase transactions exist on-chain (mining rewards). No user-to-user transfers have been executed yet.

8.2 Double-Spend Prevention

Two layers of protection:

1. Mempool check: When a new transaction arrives at a node, all input UTXOs are checked against (a) the confirmed UTXO set and (b) the mempool. A UTXO already spent in any mempool transaction is rejected ("double spend detected").
2. Block validation check: When a block is proposed, accept_block() re-validates every input UTXO against the current confirmed UTXO set. Any input referencing an already-spent output causes the entire block to be rejected.

The canonical UTXO set (stored in u: keys) is the authoritative source. An output is spent when it is consumed by a confirmed transaction in a confirmed block — not when it enters the mempool.

8.3 Confirmation Tracking

confirmations = chain.height - tx_block_height + 1

# Example: TX in block #10, current chain height = 10
confirmations = 10 - 10 + 1 = 1

# A TX in block #8:
confirmations = 10 - 8 + 1 = 3
  

• Coinbase maturity: Coinbase outputs (mining rewards) require 100 confirmations before they can be spent. This is hardcoded: COINBASE_MATURITY = 100. At current height 10, no coinbase output is yet mature.
• Standard confirmation recommendation: 6 confirmations for user transactions (same as Bitcoin)
• The explorer shows confirmations for each transaction in the block detail view

8.4 Transaction Broadcast

# POST /tx/send
{"raw_tx": "<hex-encoded signed transaction>"}

# Response (accepted):
{"txid": "abc123...", "status": "accepted"}

# Response (rejected):
{"error": "double spend detected", "code": 400}
  

On acceptance, the node adds the TX to its mempool and relays to all peers via P2P inv/getdata exchange.

8.5 Script System

Only P2PKH (Pay-to-Public-Key-Hash) scripts are implemented:

# Output (locking) script:
OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
# Hex: 76a914 <20-byte-hash> 88ac

# Input (unlocking) script:
<signature> <pubKey>
  

Script execution is in script.py. No SegWit, no Taproot, no multisig, no P2SH in the current version.

8.6 USDT Buy/Cash-Out (Web App Feature)

Base URL: https://vitocoin.com/api/node/ (Vercel proxy → Node 1). All return JSON. All GET endpoints are public — no authentication required.

Additional node aliases: /api/node2/ → Node 2 (213.139.77.18), /api/node3/ → Node 3 (84.201.20.90). All nodes expose the same endpoint set.

10.1 Synchronisation Issues

10.2 Performance Issues

10.3 Simulated / Non-Production Components

10.4 Security Posture