ZClassic23

One self-contained ~15 MB pure-C23 binary: a full ZClassic node (Equihash
200,9 proof-of-work, Sapling shielded transactions), an embedded Tor onion
service, a block explorer, a shielded wallet, and a built-in MCP server that
lets an AI agent operate the node through ~100 typed tools.

One binary, one onion, one stack.

Status — active stabilization

ZClassic23 is a work in progress and is not production-ready. The node
is in active stabilization: live sync currently holds at tip without
finalizing forward, and the v1 acceptance criteria in
docs/MVP.md are not yet met. Do not rely on this build as a
mainnet node until they are.

What is this?

A complete rewrite of zclassicd in pure C23. Every node is simultaneously:

• A full ZClassic node — syncs headers, validates blocks (Equihash PoW,
  ECDSA scripts, Sprout/Sapling zk-SNARK proofs), relays transactions, and
  serves peers on the ZClassic P2P network (port 8033). Historical chain
  validation matches legacy zclassicd; an ongoing consensus-parity audit
  tracks the forward edge.
• A fast-sync server — FlyClient MMB proofs plus SHA3-committed UTXO
  snapshots let a fresh node reach an operational tip in about a minute,
  with optional background re-validation of every historical proof and
  signature.
• A Tor hidden service — Tor is compiled into the binary. With -tor,
  the node creates a .onion address and serves the explorer and REST API
  over Tor circuits via in-process calls (no SOCKS, no exposed ports).
• A block explorer — charts, HODL-wave analysis, ZSLP token scanner,
  and a JSON REST API at /explorer and /api.
• A shielded wallet — transparent + Sapling shielded addresses, served
  over RPC and MCP.
• An MCP server — Claude (or any MCP client) operates the node as a
  first-class operator. See Claude integration.

Also on board, in varying states of completeness (labels match the
internal docs — scaffolding is scaffolding):

• ZNAM — on-chain name registry (OP_RETURN, multi-coin resolution,
  text records). Working.
• ZMSG — messaging: on-chain via the Sapling encrypted memo field
  (shielded); off-chain P2P messages are currently plaintext on the
  wire (transport encryption not yet implemented).
• ZCL Market — file-marketplace scaffolding: offer gossip and
  proof-of-possession challenges exist; file transfer and payment
  settlement are not yet implemented.
• ZSWP atomic swaps — HTLC contract scaffolding for BTC/LTC/DOGE:
  initiation and participation with redeem-script generation; redemption,
  refund, and settlement are not yet wired to broadcast.
• P2P games — latency ping + TicTacToe over a binary wire protocol,
  as an extensible framework.

Quick start

Prerequisites

• gcc 14+ (or a clang with working -std=c23 support) and GNU make.
• Vendored static libraries under vendor/lib/ (LevelDB, SQLite, libevent,
  OpenSSL, zlib, Tor). Only libsecp256k1.a is tracked in-tree today; the
  remaining archives must currently be built locally and dropped into
  vendor/lib/. Packaging them for fresh clones is a known gap — expect
  friction building outside the maintainer's environment for now.

Build and test

git clone https://github.com/ZclassiC23/zclassic.git
cd zclassic
make zclassic23     # main binary at build/bin/zclassic23
make test           # 860+ test cases across 333 test files
make lint           # defensive-coding gates (see docs/DEFENSIVE_CODING.md)

Other targets: make zcl-rpc (CLI RPC client), make zcl-nodectl (node
lifecycle tool), make deploy (install the systemd user service),
make ci (lint + full suite, what CI runs).

Run

build/bin/zclassic23                              # start node
build/bin/zclassic23 -tor                         # with .onion hidden service
build/bin/zclassic23 -cold-import=~/.zclassic     # bootstrap from legacy zclassicd data
build/bin/zclassic23 -addnode=74.50.74.102        # connect to a seed node

Data directory: ~/.zclassic-c23/ (override with -datadir=DIR). Default
ports: P2P 8033, RPC 18232.

Claude integration (MCP)

The differentiator: zclassic23 ships a built-in
Model Context Protocol server, so Claude
Code can query and operate the node directly through typed tools — no curl,
no log spelunking.

claude mcp add zcl23 -- build/bin/zclassic23 -mcp

Restart Claude Code and the tools appear automatically. The daily drivers:

Wallet, mining, ZNAM, ZMSG, swaps, metrics, and admin operations are typed
tools too — see the MCP section of CLAUDE.md for the full
reference.

Architecture

The canonical architecture document is
docs/FRAMEWORK.md — the Prime Directive, the Ten
Laws of Beauty, and the eight code shapes that every source file under
app/ must live in (lint-enforced). Current subsystem and boot topology
diagrams are in
docs/ARCHITECTURE_DIAGRAMS.md; the
rationale for the personal-sovereignty-stack pivot is in
docs/adr/0001-personal-sovereignty-stack.md.

The short version: an event log is the source of truth, state is rebuilt
through pure projections, and chain progress is a stage cursor on disk —
so silent halts are unreachable by construction.

zclassic23 binary (~15 MB, statically linked)
├── Full node         P2P 8033, RPC 18232, Equihash 200,9, Sapling
├── Tor (embedded)    .onion hosting via dynhost (in-process, no SOCKS)
├── MVC framework     Models (SQLite), Controllers (C23), Views (HTML/JSON)
├── Block explorer    /explorer routes + /api REST endpoints
├── Fast sync         FlyClient + SHA3 UTXO snapshot transfer
├── Wallet            transparent + Sapling shielded
└── MCP server        ~100 typed tools on stdio (-mcp)

Repository layout

Engineering posture

• Defensive coding is mandatory —
  docs/DEFENSIVE_CODING.md is enforced by make lint:
  every write goes through the ActiveRecord lifecycle, every error return
  logs context, every allocation is checked, every long-running loop is
  registered with a supervisor liveness tree.
• Tests — 860+ test cases across 333 test files (make test), run as
  ~380 parallel suites in CI. Bugs become 64-bit seeds in a deterministic
  simulator (docs/CHAOS_HARNESS.md).
• CI — .github/workflows/ci.yml gates
  every push on make ci (lint → bench regression → tests → hermetic MVP
  gates) plus real-process MVP proxies and a cross-runner byte-for-byte
  reproducible-build check.
• Reproducible builds — byte-identical, with optional GPG signing
  (tools/release.sh).

Boot-ordering invariants are documented in
docs/BOOT_INVARIANTS.md; historical performance numbers
live in docs/BENCHMARKS_LOG.md (treat them as
measurements from a healthy sync, not current guarantees).

Security

A third-party security audit was received and triaged in June 2026; the
point-by-point response — what was fixed, what was refuted, and why — is
in
docs/work/security-audit-response-2026-06-09.md.
Known soft spots are stated plainly there and in the status notice above
(e.g. off-chain ZMSG is plaintext on the wire).

To report a vulnerability, please open a GitHub security advisory or
contact the maintainer privately rather than filing a public issue — see
.github/SECURITY.md.

Operating the node

# One-time host setup (port capabilities, user-service linger)
sudo deploy/setup.sh

# Build, install, and watch the systemd user service
make zclassic23 && make deploy
systemctl --user status zclassic23
tail -f ~/.zclassic-c23/node.log

Operator-specific flags (-externalip and a seeded -addnode list) live
in ~/.config/zclassic23/env, not in the tracked systemd unit. Copy
deploy/zclassic23.env.example there and edit; a fresh install without
the env file starts cleanly against DNS seeds.

Useful RPC calls via build/bin/zcl-rpc: getblockchaininfo,
getpeerinfo, syncstate, healthcheck, eventlog 100,
z_gettotalbalance. The REST API mirrors the explorer: GET /api/blocks,
/api/block/:id, /api/tx/:txid, /api/address/:addr, /api/stats,
/api/hodl, /api/health.

Handy environment variables: ZCL_RPCPORT (RPC port for zcl-rpc /
zclassic-cli, default 18232) and ZCL_DATADIR (where zcl-rpc finds
the .cookie file, default ~/.zclassic-c23). Other ZCL_* knobs exist
for niche tuning; see the source.

Seeds: 74.50.74.102, 205.209.104.118, 140.174.189.3 ·
DNS: dnsseed.zclnet.net, dnsseed.zslp.org, mainnet.zclassic.org

Documentation

• CLAUDE.md — MCP tool reference, architecture overview, build/test/deploy
• docs/FRAMEWORK.md — canonical architecture
• docs/ARCHITECTURE_DIAGRAMS.md — boot, services, P2P, wallet diagrams
• docs/MVP.md — v1 acceptance criteria and honest readiness score
• docs/SYNC.md — sync methods, verification layers, self-healing
• docs/RUNBOOK.md — symptom-driven troubleshooting
• docs/DEFENSIVE_CODING.md — mandatory coding standards (lint-enforced)
• .github/CONTRIBUTING.md — build prerequisites, test workflow, contribution contract
• .github/SECURITY.md — supported status and vulnerability reporting
• docs/spec/power-node-contract.md — power-node contract surface

License

Copyright 2026 Rhett Creighton

Licensed under the Apache License, Version 2.0 — see LICENSE
for the full text. Upstream copyright notices from inherited code
(Bitcoin Core, Zcash, zclassicd) and vendored dependencies (Tor, SQLite,
secp256k1, LevelDB, dcrdex) are preserved in NOTICE.
Architectural concept attributions (Erigon, mcp-language-server, etc.)
are tracked in docs/ATTRIBUTIONS.md.