harpy

Harpy is a from-scratch blockchain node — signed UTXO transactions, a mempool, difficulty retargeting, cumulative-work fork choice with reorgs, peer-to-peer block gossip, and a hash-anchoring/verification layer with SPV light-client proofs. It's an educational project (single operator, not mainnet-grade), but every layer is built and tested the way a real node would be: adversarial specs, a formally model-checked consensus core, and a chaos harness. Named after Harpocrates, the Greek god of silence.

What it is not: production financial infrastructure. No privacy, no external audit, no economic guarantees. Run it to understand how a chain works — see docs/THREAT_MODEL.md for the honest security posture.

---

Features

Transactions & cryptography

• 💸 UTXO model — signed inputs/outputs, coinbase with 100-block maturity, fees, double-spend prevention (STATE_MODEL.md)
• 🔑 Ed25519 signatures with a crypto-agile address format (versioned, algorithm-tagged, checksummed) so post-quantum schemes are additive, not breaking (POST_QUANTUM_MIGRATION.md)
• 🧾 Mempool with validation, fee ordering, and conflict rejection

Consensus

• ⛏️ Proof-of-work with configurable difficulty and time-based retargeting
• 🏋️ Cumulative-work fork choice — heaviest chain wins, not longest (SELFISH_MINING.md, CONFIRMATION_DEPTH.md)
• 🔁 Reorgs with per-block undo logs for exact UTXO rewind

Networking

• 🌐 P2P block gossip with an orphan pool and multi-node convergence (P2P.md)
• 🛡️ Network hardening — peer caps, misbehavior banning, eclipse-attack countermeasures (SYBIL_RESISTANCE.md, ROUTING_PARTITION.md)

Storage & integrity

• 💾 Atomic writes (temp-file + rename) behind a swappable storage backend
• 🔒 Checksum envelope — bit-rot / tamper detected on load, before validation (STORAGE_BACKENDS.md)

Verification layer

• ⚓ Merkle anchoring API + SDK — commit external record hashes on-chain, get inclusion proofs (AUDIT_LOG_ANCHORING.md)
• 🪶 SPV light clients — verify a genesis-and-tip-pinned header chain + Merkle path, no full node

Assurance

• ✅ TLA+ consensus spec, model-checked with TLC — the fork-choice safety property holds across the state space (spec/tla)
• 🌪️ Chaos harness — partition/heal, crash/restart, and Byzantine-block fault injection (spec/chaos_harness_spec.cr)
• 🔐 Opsec docs — node hardening, key rotation, threshold multisig design (NODE_HARDENING.md)

Quick start

Prerequisites: Crystal ≥ 1.12. On Windows: winget install CrystalLang.Crystal, enable Developer Mode (for shards symlinks), restart your terminal, or run .\scripts\setup.ps1.

shards install
crystal run src/harpy.cr          # starts an HTTP node on 127.0.0.1:3000

Then open http://127.0.0.1:3000/dashboard — a branded status page with live chain stats and one-click mining (shown in the GIF above).

Mine your first block and inspect the chain:

# generate a keypair for the coinbase payout, then:
curl -X POST http://127.0.0.1:3000/mine \
  -H "Content-Type: application/json" \
  -d '{"miner_pubkey":"<64-hex-ed25519-pubkey>"}'

curl http://127.0.0.1:3000/            # full chain
curl http://127.0.0.1:3000/validate    # {valid, height, work, tip}

New to it? Walk through docs/DEMO.md for a guided tour with real payloads.

HTTP API

🔑 = requires Authorization: Bearer <HARPY_API_KEY> (or X-API-Key) when HARPY_API_KEY is set. Write endpoints are rate-limited. See NODE_HARDENING.md.

Anchoring: hash-on-chain, data off-chain

Harpy's endgame is a verification layer: commit a record's hash on-chain and keep the data anywhere. A light client verifies it from the complete header chain between a caller-pinned genesis and independently obtained trusted tip/checkpoint, plus a Merkle proof — no full node required. Genesis pinning alone does not establish canonicality.

crystal run examples/audit_log_anchoring.cr   # anchors log lines, proves inclusion, → DEMO OK

client = Harpy::AnchorClient.new(trusted_genesis_hash, trusted_tip_hash, "http://127.0.0.1:3000")
client.submit(digest)     # queue a record hash  →  next POST /mine seals it into the block
client.verify(digest)     # verify proof against the independently pinned tip → true

Full walkthrough: docs/AUDIT_LOG_ANCHORING.md.

Configuration

All configuration is via environment variables.

An absent HARPY_API_KEY permits unauthenticated writes only for the default loopback development setup. An explicitly empty or whitespace-only value is a startup error; the Docker testnet always requires a non-empty key. | HARPY_ANCHOR_PEERS | Trusted peers for eclipse countermeasures | – |

Multi-node on one host:

HARPY_DATA_DIR=/tmp/a.json HARPY_HTTP_PORT=3000 HARPY_P2P_PORT=9333 crystal run src/harpy.cr
HARPY_DATA_DIR=/tmp/b.json HARPY_HTTP_PORT=3001 HARPY_P2P_PORT=9334 \
  HARPY_P2P_PEERS=127.0.0.1:9333 crystal run src/harpy.cr

CLI

Running with no arguments starts the node; subcommands operate on a chain file and exit non-zero on failure (CI-friendly):

crystal run src/harpy.cr -- verify-chain --path data/chain.json
crystal run src/harpy.cr -- export-chain --path data/chain.json --out backup.json
crystal run src/harpy.cr -- help

Architecture

flowchart LR
  W[Wallet / SDK] -->|POST /tx /mine /anchor| API[HTTP API]
  L[Light client] -->|GET /header /proof /anchor| API
  API --> MP[Mempool]
  MP --> MINER[Miner - PoW]
  ANCHOR[Anchor - Merkle roots] --> MINER
  MINER --> CHAIN[Chain - fork choice and reorg]
  CHAIN --> STATE[UTXO state and undo log]
  CHAIN --> STORE[(Storage - atomic and checksum)]
  CHAIN <-->|block gossip| P2P[P2P - orphan pool and peers]
  P2P <--> PEERS[Other nodes]

src/harpy.cr              # entry point → CLI dispatch / server
src/harpy/                # block, block_header, chain, state, utxo, mempool, miner,
                          # transaction, crypto, merkle, spv, anchor, difficulty, storage, server
src/harpy/storage/        # backend interface + atomic file backend
src/harpy/p2p/            # gossip, protocol, orphan pool, peer manager, eclipse, reputation
public/dashboard.html     # branded live status page (GET /dashboard)
public/design-system/     # full Harpy design system (tokens, fonts, icons, components)
spec/                     # unit + integration + chaos specs; spec/tla/ TLA+ model
examples/                 # runnable demos (audit-log anchoring)
docs/                     # design, security, and ops documentation

Documentation

Development

crystal spec            # run the test suite
crystal tool format     # format sources
shards build            # build the bin/harpy binary

Model-check the consensus spec (needs Java + TLC):

cd spec/tla
java -cp tla2tools.jar tlc2.TLC -nowarning -config HarpyConsensus.cfg HarpyConsensus.tla
# → Model checking completed. No error has been found.

Status

Harpy is feature-complete across its educational roadmap:

Explored but out of scope: embedded-KV storage backend, a smart-contract VM, cross-chain bridges — see the docs and roadmap issues.

License

MIT — see shard.yml. An educational project; use at your own risk.