Visual Chain

Interactive Bitcoin Fork, Reorg & Chain Creator for Regtest and Signet

Visual Chain is an open-source, interactive web tool that lets Bitcoin developers visually create, simulate, and observe blockchain forks and chain reorganizations (reorgs) in real time on Regtest and Signet networks.

While tools like fork.observer offer passive observation of forks, Visual Chain is the first truly interactive creator: mine blocks on any tip, build competing chains, trigger reorgs with one click — and watch the node's chain switch live in a beautiful directed graph.

Perfect for testing wallet reorg handling, Lightning force-close behavior during reorgs, consensus edge cases, and educational demos.

https://github.com/yourusername/visual-chain

✨ Features

• Real-time interactive DAG/tree visualization of all chain tips & forks
• Color-coded chain status: Active (green), Valid-Fork (orange), Stale (gray), Invalid (red)
• One-click "Mine here" on any block tip (Regtest: instant blocks)
• Create Fork tool: automatically mine a competing chain of chosen depth
• Live reorg detection with smooth animation & highlight
• Block details sidebar (height, hash, timestamp, prevhash, status)
• Zoom, pan, search, collapsible branches
• Connect to local Regtest and/or Signet nodes
• Planned: multi-node view, ZMQ live updates, scenario export

Why This Project?

Bitcoin reorgs (even 1–5 blocks) can break wallet confirmations, Lightning channels, and indexers — yet testing them remains manual and CLI-only.

Visual Chain turns this into an intuitive playground:

• Regtest → fast deterministic testing
• Signet → realistic PoW + occasional natural reorgs

Great for Lightning devs, wallet teams, educators, and anyone wanting to deeply understand Bitcoin consensus.

Tech Stack

Layer	Technology	Purpose
Frontend	Next.js + TypeScript + Tailwind	Modern, fast dev & build
Graph Visualization	Cytoscape.js + dagre layout	Hierarchical DAG/tree rendering
Backend	Node.js + Express + TypeScript	RPC proxy & tree computation
Bitcoin RPC	bitcoin-core (npm)	Clean interface to Bitcoin Core
Real-time	Socket.io (WebSocket)	Live graph updates

Quick Start

Prerequisites

• Bitcoin Core ≥ v27 (v28+ recommended)
• Node.js ≥ 20
• 8 GB RAM recommended (for multiple nodes)

1. Setup Bitcoin Nodes

Create two directories:

mkdir -p ~/.bitcoin/regtest ~/.bitcoin/signet

regtest/bitcoin.conf (example):

regtest=1
server=1
rpcuser=visualchain
rpcpassword=supersecret123
rpcallowip=127.0.0.1
rpcbind=127.0.0.1
zmqpubhashblock=tcp://127.0.0.1:28332   # optional but recommended

signet/bitcoin.conf — similar but with signet=1 and appropriate port/rpc settings.

Start nodes:

bitcoind -conf=~/.bitcoin/regtest/bitcoin.conf -daemon
bitcoind -conf=~/.bitcoin/signet/bitcoin.conf -daemon

Mine genesis blocks on Regtest:

bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)

2. Clone & Install Visual Chain

git clone https://github.com/yourusername/visual-chain.git
cd visual-chain
npm install

3. Configure .env

Copy .env.example to .env and fill in your RPC credentials:

# Regtest
VITE_REGTEST_RPC_HOST=127.0.0.1
VITE_REGTEST_RPC_PORT=18443
VITE_REGTEST_RPC_USER=visualchain
VITE_REGTEST_RPC_PASS=supersecret123

# Signet (optional)
VITE_SIGNET_RPC_HOST=127.0.0.1
VITE_SIGNET_RPC_PORT=38332
VITE_SIGNET_RPC_USER=...
VITE_SIGNET_RPC_PASS=...

4. Run

Development mode:

npm run dev

Open http://localhost:5173

Build & serve production:

npm run build
npm run preview

Screenshots

(Add your own screenshots here later)

Full chain tree with active path highlighted

Mine competing chain on stale tip → trigger reorg

Live reorg detection & flip

Architecture (High-Level)

Browser (React + Cytoscape.js)
   ↕ WebSocket / HTTP polling
Node.js/Express Backend
   ↕ JSON-RPC
Bitcoin Core (Regtest/Signet)
   ↕ (optional) ZMQ block notifications

Backend periodically calls getchaintips + getblockheader → builds directed graph → sends JSON to frontend.

Development Roadmap

• MVP: Regtest support + basic mining/fork creation
• Reorg animation & detection polish
• Signet integration (mining trigger)
• ZMQ real-time instead of polling
• Multi-node comparison view
• Scenario save/load (JSON export)

Contributing

Contributions welcome! Especially:

• Better Signet mining UX
• Performance improvements for deep chains
• UI/UX enhancements
• Tests (vitest/jest)

1. Fork & branch (git checkout -b feature/amazing-feature)
2. Commit (git commit -m 'Add amazing feature')
3. Push & open PR

Please open an issue first for major changes.

License

MIT © Muhammad

Inspired by the Bitcoin project-ideas list and tools like fork.observer.

Built as a portfolio project to demonstrate deep Bitcoin consensus understanding + modern full-stack development.