Kala: The Immutability of Time

WIP - This project is under active development. APIs and architecture may change.

Version: v0.0.3 Author: Hrishi

Disclaimer

All claims, content, designs, algorithms, estimates, roadmaps, specifications, and performance measurements described in this project are provided with the author's best effort. You are encouraged to validate their accuracy and truthfulness independently. Nothing in this project constitutes a solicitation for investment.

Overview

Kala is a high-performance, VDF-based blockchain architecture designed for trustless, verifiable timestamping and consensus. By leveraging sequential modular squaring in class groups and integrating RSW timelock puzzles for MEV mitigation, Kala constructs an eternal, fork-free timeline of fixed "ticks," enabling:

Unforgeable, fine-grained timestamping at the iteration level
Leader-based, fork-free consensus at the tick level
MEV-resistant transaction ordering via timelock encryption
Graceful degradation under partial consensus failures

For full technical details, see the project whitepaper.

Architecture

Kala implements a novel VDF-based consensus mechanism with the following key components:

Core Components

Eternal VDF: Continuous verifiable delay function creating an unstoppable timeline
Tick-Based Consensus: Fixed epochs of 65,536 iterations (~497ms) for deterministic processing
RSW Timelock Puzzles: MEV-resistant transaction ordering through temporal encryption
GPU Acceleration: CUDA-powered parallel timelock decryption
Modular Architecture: Cleanly separated crates for consensus, state, transactions, and RPC

The Four-Phase Tick Protocol

Collection Phase (0 to k/3): Timestamp encrypted transactions as they arrive
Ordering Phase (at k/3): Commit to canonical transaction ordering
Validation Phase (k/3 to 2k/3): Validate and apply decrypted transactions
Decryption Phase (2k/3 to k): Decrypt timelock puzzles in parallel

Quick Start Options

Docker (Recommended)

git clone https://github.com/enigmarikki/kala.git
cd kala
docker compose up --build

That's it! The Docker setup handles all dependencies automatically.

Native Build Prerequisites

If you prefer to build natively, you'll need:

Docker and Docker Compose (for the easy path)
Rust toolchain (stable + nightly)
System dependencies (see below)

Install Rust

curl https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env
rustup component add rustfmt-preview

System Dependencies (Native Build Only)

Note: Skip this section if using Docker - all dependencies are included in the container.

Required Build Tools & Libraries

For native builds, you'll need the following system dependencies:

Core Build Tools

GCC/G++ - GNU Compiler Collection
Clang/LLVM - Required for bindgen and some Rust crates
CMake - Cross-platform build system
pkg-config - Helper tool for compiling applications

Required Libraries

libgmp-dev - GNU Multiple Precision Arithmetic Library
libclang-dev - Clang development libraries (for bindgen)
m4 - Macro processor (required for GMP builds)
autoconf/automake/libtool - GNU build system tools

CUDA Support (if using GPU features)

CUDA Toolkit - NVIDIA CUDA development tools
cudart - CUDA runtime library

Additional Dependencies

FlatBuffers (flatc) - Efficient serialization library

Installation

Ubuntu/Debian

sudo apt-get update && sudo apt-get install -y \
    build-essential \
    gcc \
    g++ \
    libgmp-dev \
    cmake \
    git \
    pkg-config \
    libclang-dev \
    clang \
    llvm-dev \
    m4 \
    autoconf \
    automake \
    libtool \
    flatbuffers

macOS

# Install Xcode Command Line Tools
xcode-select --install

# Using Homebrew
brew install gmp cmake pkg-config llvm flatbuffers m4 autoconf automake libtool

Arch Linux

sudo pacman -S base-devel gcc gmp cmake pkgconf clang llvm flatbuffers m4 autoconf automake libtool

Getting Started

Clone the Repository

git clone https://github.com/enigmarikki/kala.git
cd kala

Option 1: Docker (Recommended) 🐳

The easiest way to run Kala is using Docker, which handles all system dependencies and build configuration automatically.

Prerequisites

Docker and Docker Compose
NVIDIA Docker runtime (optional, for GPU acceleration)

Quick Start with Docker

# Build and start the Kala node (includes all dependencies)
docker compose up --build

# Or run in detached mode
docker compose up --build -d

This will:

Build a complete Kala development environment with all native dependencies
Compile the native VDF libraries (C++) and timelock puzzles (CUDA)
Build all Rust crates with optimizations
Start the devnode with persistent data storage
Expose the RPC API on http://localhost:8545

Docker Configuration

The Docker setup includes:

Multi-stage build for optimized production images
CUDA support for GPU-accelerated timelock solving
Persistent data mounted to ./kala_dev_db
Configuration volume for easy customization

Docker Commands

# View logs
docker compose logs -f

# Stop the node
docker compose down

# Rebuild after code changes
docker compose up --build

# Execute commands in running container
docker compose exec kala devnode --help

Option 2: Native Build

For development or custom configurations, you can build Kala natively.

Building

# Build all crates in debug mode
cargo build

# Build in release mode
cargo build --release

Running the Dev Node

The devnode binary in the kala-core crate spins up a local node with persistent state and RPC endpoint.

# Initialize or reuse the database at ./kala_db and expose RPC on port 8545
cargo run -p kala-core --bin devnode -- --db-path ./kala_db --rpc-port 8545

# For faster development (1-second ticks instead of ~500ms)
cargo run -p kala-core --bin devnode -- --fast --db-path ./kala_dev_db

API Access

The RPC endpoint will be available at:

http://127.0.0.1:8545

Example API call:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"kala_chainInfo","id":1}' \
  http://127.0.0.1:8545

Testing & Benchmarking

Using Docker

# Run tests in container
docker compose exec kala cargo test

# Run benchmarks (if available)
docker compose exec kala cargo bench

Native Testing

# Run the test suite
cargo test

# Run benchmarks (nightly required)
rustup install nightly
time cargo +nightly bench --features unstable

Monitoring & Observability

Real-time Monitoring

# Watch node logs in real-time
docker compose logs -f kala

# Monitor VDF progress and tick processing
curl -s http://localhost:8545 -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"kala_chainInfo","id":1}' | jq

Key Metrics to Monitor

Tick Progress: Current tick number and VDF iteration
Transaction Throughput: Transactions processed per tick
Timing Performance: Actual vs. expected tick duration (~497ms)
MEV Resistance: Transaction ordering consistency
GPU Utilization: Timelock decryption performance (if GPU enabled)

Health Checks

# Check if the node is responding
curl -f http://localhost:8545/health || echo "Node is down"

# Get recent tick information
curl -X POST http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"kala_getRecentTicks","params":5,"id":1}'

Development

Hot Reloading with Docker

For development with automatic rebuilding:

# Make code changes, then rebuild
docker compose up --build

# Or use development mode (if configured)
docker compose -f docker-compose.dev.yml up

Configuration

Environment variables for fine-tuning:

# In compose.yaml or your environment
RUST_LOG=debug              # Enable debug logging
KALA_FAST_MODE=true         # Use 1-second ticks for development
KALA_GPU_ENABLED=false      # Disable GPU acceleration
KALA_MAX_TXS_PER_TICK=100   # Limit transactions per tick

Client SDK Development

Coming soon! The client SDK will provide:

# Future client demo
cargo run --release --bin kala-client-demo -- --config client.toml

API Examples

# Submit a transaction (example format)
curl -X POST http://localhost:8545 -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "kala_submitTransaction", 
    "params": {
      "encrypted_tx": "0x1234567890abcdef..."
    },
    "id": 1
  }'

# Get account information
curl -X POST http://localhost:8545 -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "kala_getAccount",
    "params": {
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "id": 1
  }'

Performance & Troubleshooting

Expected Performance

Tick Duration: ~497ms (65,536 VDF iterations at 7.6μs each)
Transaction Throughput: Up to 10,000 transactions per tick
Finality: Single-tick finality (~500ms)
MEV Protection: Complete front-running prevention through timelock ordering

Troubleshooting Common Issues

Docker Build Fails

# Clean up and try again
docker compose down
docker system prune -f
docker compose up --build --no-cache

Node Performance Issues

# Check system resources
docker stats kala-node

# Enable debug logging
docker compose logs -f kala | grep -E "(WARN|ERROR)"

# Check VDF timing consistency
curl -s http://localhost:8545 -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"kala_chainInfo","id":1}' | jq '.result'

GPU Acceleration Not Working

# Verify NVIDIA Docker runtime
docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

# Check container GPU access
docker compose exec kala nvidia-smi

Database Issues

# Reset the database (WARNING: destroys all data)
docker compose down
sudo rm -rf ./kala_dev_db
docker compose up --build

Production Deployment

For production deployments, consider:

Resource Requirements: 8+ CPU cores, 16GB+ RAM, SSD storage
Network Configuration: Proper firewall rules for port 8545
GPU Optimization: NVIDIA RTX 4090 or better for optimal timelock decryption
Monitoring: Prometheus metrics integration (coming soon)
Backup Strategy: Regular database snapshots of ./kala_dev_db

Contributing

Kala is an open-source research project. Contributions are welcome!

Development Setup

Fork the repository
Install dev tools: make install-tools
Install git hooks: make install-hooks
Make your changes
Run checks: make pr
Submit a pull request

Development Commands

make build       # Build all crates
make test        # Run tests
make fmt         # Format code
make clippy      # Run lints
make lint        # Format + clippy
make pr          # Full PR checks (lint, test, deny)
make help        # Show all commands

Project Structure

kala/
├── crates/
│   ├── kala-common/      # Shared types and utilities
│   ├── kala-core/        # Node and consensus logic
│   ├── kala-rpc/         # JSON-RPC API
│   ├── kala-state/       # State management
│   ├── kala-tick/        # CVDF streamer (Pietrzak proofs)
│   ├── kala-timelocks/   # RSW timelock puzzles (CUDA)
│   └── kala-transaction/ # Transaction types
├── scripts/              # Development scripts
├── docs/                 # Whitepaper and documentation
└── Makefile              # Development workflow

Research Areas

We're actively researching:

Scalability: Optimizing VDF computation for higher throughput
Network Layer: P2P networking for multi-node deployments
Light Clients: Efficient verification without full VDF computation
Cross-chain Integration: Bridging with other blockchain networks

License

This project is licensed under the MIT License. See LICENSE for details.

Citation

If you use Kala in your research, please cite:

@misc{kala2025,
  title={Kala: The Immutability of Time - VDF-Based Consensus with MEV Resistance},
  author={Hrishi},
  year={2025},
  url={https://github.com/enigmarikki/kala}
}

"kālo'smi loka-kṣaya-kṛt pravṛddho" - I am Time, the destroyer of worlds

Name		Name	Last commit message	Last commit date
crates		crates
docs		docs
scripts		scripts
.dockerignore		.dockerignore
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
Readme.md		Readme.md
clippy.toml		clippy.toml
compose.yaml		compose.yaml
deny.toml		deny.toml
rustfmt.toml		rustfmt.toml

Latest commit

History

Folders and files

Repository files navigation