[LAUNCHING 7/21 WILL BE POSTING THE GITHUB REPO]
# KaleidoCoin (KALI) — One File. One Chain. No Compromises.
**Ticker:** KALI ; **Network:** Scopenet ; **Algorithm:** Kaleidoscope (CPU-mineable, ASIC-resistant) ; **Block Time:** 600 seconds ; **Consensus:** Proof-of-Work ; **Language:** Rust
---
## TL;DR
KaleidoCoin is a complete proof-of-work Layer 1 blockchain — the node, the miner, the wallet, the peer-to-peer network, the RPC server, and a built-in web explorer — implemented entirely in **a single Rust source file**. You can read the whole chain, top to bottom, in an evening. You can compile it in under a minute. You can run a node, mine a block, and send a transaction, all from one binary, with zero external services required.
It started as a personal challenge. It's turning into a real coin. Here's everything about it.
---
## Table of Contents
1. [The Origin Story](#1-the-origin-story)
2. [Why a Single File? The Philosophy](#2-why-a-single-file-the-philosophy)
3. [Quick Facts & Specifications](#3-quick-facts--specifications)
4. [The Technology, Explained in Full](#4-the-technology-explained-in-full)
5. [Getting Started — Step by Step](#5-getting-started--step-by-step)
6. [Every Command, Explained](#6-every-command-explained)
7. [The Built-In Block Explorer](#7-the-built-in-block-explorer)
8. [Cross-Platform: Linux and Windows](#8-cross-platform-linux-and-windows)
9. [The wKALI Bridge](#9-the-wkali-bridge)
10. [The Floppy Disk Edition](#10-the-floppy-disk-edition)
11. [Roadmap](#11-roadmap)
12. [Join In](#12-join-in)
13. [Disclaimer](#13-disclaimer)
---
## 1. The Origin Story
Every project has an origin, and this one's is a little unusual.
It started as a dare to myself: **could a complete, functioning proof-of-work blockchain — node, miner, wallet, peer-to-peer networking, RPC, and a web-based block explorer — be written in a single source file, with no sprawling multi-crate workspace, no microservices, no twelve-repo architecture?**
Most blockchain codebases you'll find are split across dozens of crates or packages — a consensus module here, a networking module there, a separate wallet library, a separate RPC crate, all wired together through layers of abstraction. There's nothing wrong with that approach, and plenty of excellent projects are built that way. But I wanted to see if the opposite extreme was possible: one file, doing everything, that anyone could open in a text editor and read from the first line to the last.
It turns out the answer is yes. KaleidoCoin's entire core — the blockchain data structures, the Blake3-based proof-of-work engine, the DAG generation, the peer gossip protocol, the JSON-RPC server, the Ed25519 wallet system, and a full HTML/JS block explorer served straight out of the binary — lives in one `main.rs` file. No hidden dependencies on a dozen internal crates. No "you have to understand five other files before this one makes sense." Just one file, top to bottom.
And somewhere in the middle of writing it, a second idea took hold: **if the whole thing really fits in one file, how small could that file actually be?** The answer turned out to be delightfully small — small enough that the complete source code for this entire blockchain fits on a single 1.44MB floppy disk, using less than 8% of the available space. More on that in Section 10, because I think it's one of the more fun facts about this project.
KaleidoCoin is the result of that challenge, cleaned up, hardened, documented, and turned into something you can actually run, mine, and use today.
## 2. Why a Single File? The Philosophy
There's a real, practical philosophy behind the single-file design, beyond just being a neat trick:
- **Radical auditability.** You don't need to trace imports across a dozen files to understand what the code does when it validates a block, or how a wallet's private key is derived and encrypted. It's all right there, in order, in one place. Anyone with a Rust textbook and a free afternoon can read the entire chain's logic.
- **Zero-friction builds.** There's no complex workspace to configure. You copy one file, write one small `Cargo.toml` with pinned dependency versions, and run `cargo build --release`. That's the whole build process.
- **One binary does everything.** The same compiled executable is your node, your miner, your wallet, and (if you want) all three running together in one process. No juggling separate installs for separate roles.
- **Respect for the reader's time.** A lot of blockchain projects ask you to trust that the code does what the whitepaper says. With KaleidoCoin, verifying that claim is a much smaller ask — the whole implementation is sitting in front of you.
None of this is about cutting corners. It's about proving that a real, working, proof-of-work chain doesn't have to be an intimidating wall of interconnected repositories to be legitimate. Sometimes the simplest possible shape for a thing is also the most honest one.
## 3. Quick Facts & Specifications
| Property | Value |
|---|---|
| Coin name | KaleidoCoin |
| Ticker | KALI |
| Network name | `scopenet` |
| Consensus | Proof-of-Work |
| Hashing algorithm | Blake3, combined with a 2GB generated DAG (similar in spirit to Ethash) |
| CPU/GPU/ASIC | CPU-mineable by design; the DAG construction is intended to resist ASIC specialization |
| Block time target | 600 seconds |
| Difficulty adjustment | Automatic, retargeted daily (every 1,440 blocks), so block times stay close to target as network hashrate changes |
| Starting block reward | 250.00 KALI |
| Halving interval | Every 55,355 blocks |
| Internal precision | Integer "centikali" (2 decimal places) throughout — no floating-point rounding anywhere near your balance |
| Fork choice | Heaviest cumulative proof-of-work chain, not simply the tallest — a chain that represents more real computational work wins |
| Finality safeguard | Blocks more than 1,000 deep are treated as final and can't be reorganized away |
| Networking | Peer-to-peer gossip over TCP, with automatic peer discovery and chain sync |
| Wallet cryptography | Ed25519 keypairs, private keys encrypted at rest with a password you choose |
| Interfaces | Command-line node/miner/wallet, JSON-RPC, and a built-in web-based block explorer |
| Platforms | Linux and Windows |
| Implementation language | Rust |
| Lines of code | The entire chain — node, miner, wallet, P2P, RPC, and explorer — in one source file |
## 4. The Technology, Explained in Full
This section is for anyone who wants to understand exactly what's happening under the hood, not just the marketing bullet points.
### 4.1 Proof-of-Work: Blake3 + a Generated DAG
KaleidoCoin's mining algorithm combines the Blake3 hash function with a large, deterministically-generated DAG (Directed Acyclic Graph) — a big block of pseudorandom data, regenerated by every full node from the chain's parameters. This design draws inspiration from memory-hard mining algorithms like Ethash: by making the mining process depend on reading from a large dataset rather than pure raw compute, it becomes much harder to build cheap, specialized ASIC hardware that massively outperforms an ordinary computer. In practice, that means **anyone with a regular CPU can mine KaleidoCoin competitively** — no warehouse of specialized rigs required to participate meaningfully.
Every block's proof-of-work hash is cryptographically bound to that block's exact position in the chain — its height, its parent block, its difficulty, and the address of the miner who found it — in addition to the transactions it contains. That means a solved block is only ever valid for the exact position it was mined at; it can't be reused or repositioned anywhere else in the chain's history.
### 4.2 Fair, Predictable Emission
The starting block reward is **250.00 KALI**, halving every 55,355 blocks — a schedule similar in concept to Bitcoin's, tuned for this chain's own emission curve. Every reward figure, every balance, every fee is tracked internally as an integer number of "centikali" (hundredths of a coin), so there's never any floating-point rounding drift anywhere near your money. What the wallet shows you is exactly what the ledger holds.
### 4.3 Difficulty That Actually Adapts
Every 1,440 blocks, the network automatically retargets its mining difficulty based on how quickly the previous window of blocks was actually found. If miners join and blocks start coming in faster than the 60-second target, difficulty rises to compensate. If hashrate drops off, difficulty eases back down. The goal is a network that stays healthy and predictable regardless of how mining participation changes over time.
### 4.4 Heaviest-Chain Consensus
Rather than simply trusting whichever chain is tallest, KaleidoCoin nodes track the **cumulative proof-of-work** behind every chain they see — literally, the sum of the computational effort behind every block back to genesis — and always follow whichever chain represents the most real work, not merely the most blocks. This is a more robust security model than a naive "longest chain wins" rule, because it means length alone is never enough to hijack consensus; a competing chain has to out-work the real one, not just out-count it.
On top of that, once a block is 1,000 blocks deep in the chain, it's treated as permanently final — the network will never reorganize history that far back, giving recipients of a payment real confidence once a transaction has enough confirmations behind it.
### 4.5 A Network That Knows Its Own Chain
Every message passed between peers on the network carries a small fingerprint derived from the network's name and genesis block. Peers that don't share that exact fingerprint — because they're running an incompatible fork, a test network, or something else entirely — are simply never listened to. It's a small detail, but it means the peer-to-peer layer only ever engages with genuinely compatible nodes.
### 4.6 The Wallet
Wallets use **Ed25519** — the same modern elliptic-curve signature scheme trusted across much of the cryptocurrency and secure-messaging world for its speed and strong security guarantees. Private keys never touch disk unencrypted: they're encrypted with a password you choose the moment a wallet is created, and decrypted only in memory, only when you unlock it to sign something. Addresses are derived deterministically from your public key, so anyone can verify an address really corresponds to a given key without any central registry.
### 4.7 Peer-to-Peer Networking
Nodes discover each other and gossip blocks and transactions over a lightweight TCP-based protocol. New nodes joining the network sync up with peers automatically, catching up to the current chain tip without any manual intervention. You can point a node at a specific bootstrap peer with a simple flag, or let it discover the wider network on its own.
### 4.8 The Explorer, Built In
Every full node ships with its own web-based block explorer — no separate indexing service, no third-party explorer to trust. Point a browser at your node's explorer port and you can browse recent blocks, look up a specific block by hash, and see live network stats, straight from the same binary that's running your node.
## 5. Getting Started — Step by Step
This is the part that matters most: how do you actually go from "I downloaded this" to "I'm mining my own coin and holding it in my own wallet"? Here's the exact order of operations.
**⚠️ Important: create your wallet *before* you start mining.** The miner needs a KALI address to pay your block rewards to — you can't point it at a wallet that doesn't exist yet. So the very first thing you should do, before anything else, is open the wallet and create an address. Once you have that address, you hand it to the miner as its payout destination and you're off.
Here's the full sequence:
### Step 1 — Build it
```bash
# Linux
cargo build --release
# binary is now at target/release/kaleidocoin
# Windows
cargo build --release
# binary is now at target\release\kaleidocoin.exe
```
### Step 2 — Create your wallet first
```bash
./kaleidocoin wallet
```
This drops you into an interactive menu. Choose **1. Create New Wallet**, set a password (write it down somewhere safe — it encrypts your private key, and there's no "forgot password" button on a blockchain), and the wallet will print your brand-new KALI address, something like:
```
KALI-35a1e0d40795cbc81f10ba8f61405a7bfcc2bed4
```
**That address is what you'll use in every step from here on.** Keep the wallet menu open (option 4 lists all your wallets any time you need a reminder), or just make a note of the address.
### Step 3 — Start a node
In a separate terminal:
```bash
./kaleidocoin node
```
This starts your peer-to-peer node, its RPC server (which the miner and wallet talk to), and the built-in explorer. You'll see a clean, streaming log of network activity — new peers connecting, blocks arriving, everything happening in real time.
### Step 4 — Start mining, using the address from Step 2
```bash
./kaleidocoin miner KALI-35a1e0d40795cbc81f10ba8f61405a7bfcc2bed4
```
That's it. The miner connects to your node's RPC, pulls the current mining work, and starts hashing on every CPU thread available. Every block it finds and successfully submits pays its reward straight to the address you created in Step 2. You'll see a live speed report every few seconds, and a bright, unmissable log line the moment you actually find a block.
### Step 5 — Check your balance
Back in the wallet menu (or via a fresh `./kaleidocoin wallet`), choose **2. Check Balance**, enter your address, and watch your mined KALI show up as blocks confirm.
### The shortcut: run everything at once
If you just want to try the whole experience on one machine without juggling three terminals, there's a shortcut — but it still needs a wallet address, so create one first with Step 2, then:
```bash
./kaleidocoin all KALI-35a1e0d40795cbc81f10ba8f61405a7bfcc2bed4
```
This runs the node, the miner, and the interactive wallet together in a single process — perfect for a first test drive.
## 6. Every Command, Explained
| Command | What it does |
|---|---|
| `kaleidocoin node` | Runs the peer-to-peer node, RPC server, and web explorer. Doesn't mine on its own. |
| `kaleidocoin wallet` | Opens the interactive wallet menu — create/import/export wallets, check balances, send KALI, view transaction history. **Run this first.** |
| `kaleidocoin miner <your-address>` | Starts mining, paying rewards to `<your-address>`. Needs a node already running to talk to. |
| `kaleidocoin all <your-address>` | Runs the node, the miner, and the wallet together — the easiest way to try everything at once. |
| `kaleidocoin wallet-send <from> <to> <amount> <fee> <password>` | Sends KALI from the command line, without the interactive menu — handy for scripts. |
| `kaleidocoin wallet-sign-message <address> <password> <message>` | Signs an arbitrary message with a wallet's key, proving you own that address without ever revealing the private key. Used, among other things, for linking an address to the bridge (see Section 9). |
Useful flags, addable to most commands:
| Flag | What it does |
|---|---|
| `--port <number>` | Sets the P2P port (RPC and explorer ports are derived automatically from it). |
| `--rpc-port <number>` | Points the miner/wallet at a specific node's RPC port — use this if your node isn't on the default port, or is on another machine. |
| `--peer <ip:port>` | Adds a specific peer to connect to on startup — repeatable for multiple peers. |
| `--light` | Skips local DAG generation for a much faster startup — great for quickly poking around the network or the explorer without committing to full mining setup. |
## 7. The Built-In Block Explorer
Every node quietly runs its own web explorer alongside everything else — just open a browser to your node's explorer address (printed when the node starts) and you can:
- See the current chain height, difficulty, and mempool size at a glance.
- Browse the most recent blocks.
- Look up any block by its hash and see every transaction inside it.
No separate indexer, no third-party site holding your data, no trust required beyond your own node.
## 8. Cross-Platform: Linux and Windows
KaleidoCoin builds and runs natively on both Linux and Windows — the same single source file, the same commands, the same experience either way. Whether you're standing up a node on a home Linux box, a cloud VPS, or just trying it out on your Windows desktop with `cargo build`, the path is the same: build once, then `node`, `wallet`, `miner`, or `all`, exactly as described above.
## 9. The wKALI Bridge
Alongside the core chain, there's a companion project in the works: **wKALI**, a wrapped, ERC-20 representation of KaleidoCoin for EVM-compatible chains, with a full bridge stack — a smart contract, a relayer service, and a web portal for linking your KALI address to an EVM wallet.
**A quick, honest note on timing:** the bridge is a separate, additional piece of infrastructure on top of the core chain, and it's still being polished. Depending on how that work wraps up, KaleidoCoin's initial launch may go out **with just the core chain** — the node, miner, wallet, and explorer described above, which are ready to go — while the bridge follows shortly after in a repository update once it's fully ready. Either way, the core chain you can build and mine today is the real thing, right now, with or without the bridge attached to it yet. Watch the repository for the bridge components landing.
## 10. The Floppy Disk Edition
Here's a fact I genuinely love about this project: the **entire source code** for KaleidoCoin — the blockchain, the miner, the wallet, the networking layer, the RPC server, and the built-in web explorer, all of it — comes in at under 110KB as plain text.
A standard 3.5" floppy disk holds 1.44MB.
That means the complete, functioning source code for this entire cryptocurrency uses **less than 8% of a floppy disk's capacity**, with well over 90% of the disk still empty. This was genuinely part of the original design constraint that kicked the whole project off: if a blockchain can really live in one file, how small can that file be, and could you, in principle, hand someone the entire codebase for a working coin on a piece of 1980s storage media?
The answer is yes — and if there's enough interest from the community, I'd love to actually do a limited real-world floppy disk release: physical, mailable disks containing the complete source, as a fun nod to the constraint that shaped this project from day one. If that's something people want, let me know in the thread below.
## 11. Roadmap
- ✅ Core chain: node, miner, wallet, P2P networking, RPC, and block explorer — complete and ready to run today.
- ✅ Cross-platform builds for Linux and Windows.
- 🔜 wKALI bridge to EVM chains — contract, relayer, and web portal (see Section 9) — landing via a repository update as soon as it's fully ready.
- 🔜 Community feedback shaping what comes next — this thread is where that conversation starts.
- 💾 The Floppy Disk Edition, if enough people want it (Section 10).
## 12. Join In
This is a one-person passion project that grew from "can I fit a whole blockchain in one file" into something real enough to actually run and mine. If any part of that — the single-file philosophy, the CPU-friendly mining, the fair emission schedule, or just the floppy disk trivia — sounds like your kind of project, grab the source, build it, create a wallet, and start mining. Questions, feedback, and "I got this running on my machine" reports are all welcome right here in this thread.
## 13. Disclaimer
KaleidoCoin is an independent, experimental software project. As with any cryptocurrency, participate with funds and time you're comfortable dedicating to an early-stage project, do your own research, and never share your wallet password or private key with anyone. Nothing in this post is financial advice.
