⏳ Chronos: Immutable Cryptographic Ledger

Chronos is a high-performance, cryptographically secure logging and audit system. It ingests raw logs at high velocity, secures them using a mathematically verifiable Merkle Chain architecture, and stores them in a highly optimized PostgreSQL vault.

Built for cybersecurity applications, forensic auditing, and tamper-proof compliance, Chronos ensures that once a log is recorded, it can never be silently altered, deleted, or reordered.

🚀 Architecture Overview

Chronos separates I/O-bound networking from CPU-bound cryptography using a multi-process architecture to achieve massive vertical scaling:

1. Ingestion (Vector & FastAPI): Logs are routed via vector and ingested in micro-batches by an asynchronous FastAPI server.
2. Decoupling (PyNNG IPC): The network payload is handed off to the cryptographic engine via a Zero-MQ style Inter-Process Communication (IPC) pipe, preventing network backpressure.
3. Cryptographic Engine (Core Worker):
   • Computes individual $O(1)$ Leaf Hashes for every log utilizing C-optimized blake3 / sha256.
   • Constructs an $O(\log N)$ Merkle Tree with native padding for variable block sizes.
   • Chains the Merkle Roots chronologically to guarantee global state immutability.
4. Vault Writer (DB IPC Server): Receives the cryptographically secured batches and utilizes PostgreSQL's COPY FROM STDIN protocol for hyper-efficient, sub-millisecond ACID-compliant disk writes.

✨ Key Features & Optimizations

• True Merkle Chain: Combines the batch-parallelization of a Merkle Tree with the temporal security of a Linked List.
• Multi-Process Architecture: Isolates network I/O, cryptography, and database writes into separate Python processes to maximize CPU utilization on multi-core systems.
• "Batching the Batcher": Implements a two-tier micro-batching system—first in the core worker, then again in the DB server—to drastically reduce kernel context switches (syscalls) and transaction overhead.
• UNLOGGED Tables: The logs table is configured as UNLOGGED in PostgreSQL, skipping the Write-Ahead Log (WAL) to nearly double write throughput. Integrity is guaranteed by the logged batches table.
• Tamper Evident: If a single byte in a historical log is modified, the leaf hash fails, the Merkle root breaks, and the chronological chain is severed.
• Blazing Fast: Fully asynchronous API coupled with byte-native Python operations to minimize memory allocation and garbage collection overhead.

🛠️ Prerequisites

• Python 3.13+
• Docker & Docker Compose
• uv (Python package installer)

📦 Installation & Setup

1. Clone the repository

git clone https://github.com/Nova-Stark/Chronos.git
cd Chronos

2. Install dependencies

# This syncs the virtual environment with the versions in uv.lock
uv sync

3. Configure the Environment Create a .env file in the root directory and set a secret key.

# Generate a secure key (e.g., using openssl rand -hex 32)
CHRONOS_HMAC_KEY=your_secure_32_byte_hex_string_here

4. Launch the System with Docker This single command builds the images and starts the entire Chronos stack (Vector, Postgres, and the Chronos Engine).

docker-compose up --build -d

The API is now available at http://localhost:5000.

📡 API Ingestion Format

Chronos accepts batched JSON payloads via POST /ingest.

[
  {
    "timestamp": "2026-03-17T08:04:53.131Z",
    "message": "User admin logged in from 192.168.1.50"
  },
  {
    "timestamp": "2026-03-17T08:04:54.222Z",
    "message": "Failed SSH attempt for user root"
  }
]

Documentation

• Docs

🔮 Future Roadmap (v2.0)

Chronos is actively evolving to support enterprise-grade horizontal and vertical scaling:

⚡ uvloop for FastAPI (Network Optimization)

• What it is: A drop-in replacement for Python's default asyncio event loop, written in Cython and built on top of libuv.
• The Impact: Doubles or triples FastAPI's ability to handle concurrent network connections from Vector without changing any core logic.

🧠 POSIX Shared Memory (IPC Elimination)

• What it is: Transitioning from NNG IPC pipes to Python's multiprocessing.shared_memory module.
• The Impact: The API writes raw log bytes directly into a shared block of RAM. The Hashing Worker reads from that exact same physical memory address—zero serialization, zero network syscalls, infinite throughput.

🦀 C/Rust Shared Library Core (Compute Optimization)

• What it is: Rewriting the _build_merkle_root and leaf-hashing loop in pure C or Rust (using PyO3), compiled as a .so (Linux) or .dll (Windows).
• The Impact: Bypasses the Python Interpreter for the heavy lifting. The system hands the C-library a pointer to the shared memory block and receives the calculated Merkle root in microseconds.

⛓️ External Blockchain Anchoring (Absolute Immutability)

• What it is: A scheduled process that takes the highest current_chain_hash every 24 hours and writes it to a public blockchain (like Ethereum or Polygon) as a smart contract transaction.
• The Impact: Provides cryptographic proof of the system's integrity permanently etched into a decentralized ledger, protecting against even full database deletions.