System Architecture
Scanner Page 2
Home Page
Scanner Page
Guardian Page

BitShield

Bitcoin's First Quantum Vulnerability Scanner & Policy-Enforced Wallet Guardian

SCAN. PROTECT. MIGRATE. Built at the MIT Bitcoin Expo 2026 Hackathon (April 10–12) — Team ACE

Inspiration

On March 31, 2026, Google's Quantum AI team published a whitepaper that changed the threat timeline for Bitcoin. Their research demonstrated that a quantum computer with fewer than 500,000 physical qubits — a 20x reduction from prior estimates — can derive a Bitcoin private key from its public key in approximately 9 minutes.

That arithmetic is terrifying: Bitcoin's average block confirmation time is 10 minutes. A quantum attacker intercepting a live transaction in the mempool has a ~41% probability of cracking the key before the transaction confirms.

The exposure already exists on-chain today:

6.9 million BTC (~\$690 billion) sit in addresses where public keys are already exposed
1.7 million BTC remain in early P2PK addresses where the public key is permanently visible (including Satoshi's coins)
Every previously-spent P2PKH and P2WPKH address has its public key revealed in the scriptSig or witness data

Despite this being the most urgent security challenge in Bitcoin's 17-year history, no tool exists that scans a Bitcoin wallet, classifies each address by quantum vulnerability, and guides the holder through migration.

Three days before this hackathon, Nunchuk released their Agent Skills framework (April 8, 2026) — the first bounded-authority model for AI agents managing Bitcoin wallets. No product had been built on it yet.

We saw the intersection: quantum threat detection + bounded-authority wallet management + on-chain accountability. We built BitShield in 48 hours.

What it does

BitShield is a unified security dashboard with three layers:

1. Quantum Vulnerability Scanner

The core feature. BitShield scans every address in a Bitcoin wallet using bitcoinjs-lib for script-type classification and mempool.space for real-time UTXO and spent-address detection, then assigns each address a quantum risk level:

Risk Level	Address Type	Why It's Vulnerable
CRITICAL	P2PK (Pay-to-Public-Key)	Public key stored directly in the locking script. Permanently exposed. Includes Satoshi-era coins.
HIGH	Spent P2PKH / P2WPKH / P2TR	Public key revealed when a previous transaction was broadcast. Key is now permanently on-chain.
MEDIUM	Unspent P2PKH / P2WPKH	Hash-protected at rest, but the key will be exposed the moment a spend is initiated — creating a 9-minute attack window.
LOW	Fresh unspent addresses	Currently hash-protected with no on-chain key exposure. Safest existing format.

The scanner auto-detects spent status from the blockchain — users don't need to know their address types. They paste an address (or scan their entire wallet) and get a clear risk assessment with specific migration instructions.

A 9-minute countdown timer visualizes the attack window in real time, and when it completes, displays a full breach report with affected BTC statistics and BIP-360 migration guidance.

An interactive 3D visualizer built with Three.js shows Bitcoin's quantum vulnerability layers — the secp256k1 core, concentric rings for each address type (P2TR safe → P2WPKH high risk → P2PK critical), and animated Shor's algorithm attack nodes with electric arcs. Click any element for detailed risk information.

2. Policy-Enforced Group Wallet (Nunchuk Bounded Authority)

BitShield implements Nunchuk's multisignature group wallet model with three keys:

User key — the human holder retains ultimate signing authority
Agent key — the AI guardian can sign transactions within policy bounds
Policy co-signer — Nunchuk's server enforces spending limits, approval workflows, and transaction thresholds

Key properties:

Spending limits: The agent can execute transactions up to a configurable daily threshold (e.g., 5000 sats/day). Anything above requires human co-signing.
Quantum-aware execution: Before signing any outbound transaction, BitShield checks the destination address against the quantum scanner. If the destination has an exposed public key, the user is warned.
Separation of custody: Depositing funds does not grant the agent permission to spend them.

This is Bitcoin-native multisig, not a custodial wrapper. The policy enforcement happens at the signing layer using standard Bitcoin scripts.

3. On-Chain Audit Trail (Cogcoin OP_RETURN Anchoring)

Every guardian action — policy changes, transaction approvals, quantum scan results, spending limit modifications — is anchored to Bitcoin's blockchain via Cogcoin's OP_RETURN mechanism.

This creates an immutable, timestamped, publicly verifiable record of every decision the system made. It is not database logging. It is proof-of-work-secured accountability: the audit trail inherits Bitcoin's thermodynamic security guarantees, meaning it cannot be altered, backdated, or deleted by any party.

4. Natural Language Interface (Claude AI)

The dashboard provides a chat interface where users issue wallet commands in plain English. Claude Sonnet 4 parses natural language into structured Bitcoin operations:

You say	What happens
"What's my balance?"	Fetches real balance from Nunchuk wallet and displays inline
"Scan my wallet for quantum risk"	Runs batch scan on all wallet addresses
"Send 5000 sats to tb1q..."	Policy check → quantum scan destination → multisig execution
"Set daily limit to 10000 sats"	Updates Nunchuk platform key spending policy
"How does quantum computing threaten Bitcoin?"	Educational explanation of ECDLP and Shor's algorithm

The language model is the UX, not the product. The intelligence lives in the Bitcoin layer: the policy engine, the quantum scanner, the multisig signing logic, and the on-chain anchoring.

5. Lightning Payments (Alby NWC)

For small, policy-compliant payments, BitShield integrates Alby's Nostr Wallet Connect (NWC) to handle Lightning Network micropayments without touching the on-chain multisig flow.

How we built it

Runtime: Bun 1.3.8 — TypeScript runtime and package manager

Backend: Hono 4 + Bun HTTP server (port 3001)

Claude Sonnet 4 (@anthropic-ai/sdk) for natural language intent parsing
Nunchuk CLI (real nunchuk binary) for 2-of-3 multisig wallet operations
bitcoinjs-lib v7 for Bitcoin address type detection and script classification
mempool.space API for UTXO lookups and spent-address auto-detection
Alby NWC (@getalby/sdk v7) for Lightning payments
Cogcoin CLI for OP_RETURN on-chain event anchoring
Nostr relay broadcasting for decentralized event propagation
Nunchuk webhook receiver for real-time transaction events
Security middleware: rate limiting (60 req/min), security headers, Zod input validation

Frontend: Next.js 16 + React 19 + Turbopack (port 3000)

TanStack Query v5 for server state management
Zustand v5 for client state
Tailwind CSS v4 + shadcn/ui for the dark-theme UI
Three.js + React Three Fiber + Drei + Postprocessing for the 3D quantum visualizer
Motion 12 (AnimateUI) for animations
xior for HTTP client with structured error handling
WebSocket for real-time dashboard updates

Bitcoin:

Bitcoin Core full node (via Cogcoin managed bitcoind)
mempool.space Signet API for blockchain data
Cogcoin indexer for OP_RETURN data
Blockstream Electrum server for Nunchuk backend

Infrastructure:

Vercel (frontend deployment)
Railway (backend deployment)
Docker Compose for self-hosting
Fly.io + Render deployment configs

Challenges we ran into

Cogcoin descriptor import bug: During wallet setup, the Cogcoin CLI's repair command failed with "Cannot import descriptor without private keys to a wallet with private keys enabled." We traced this to three bugs in @cogcoin/client where getdescriptorinfo RPC strips private keys from the descriptor, corrupts the saved wallet state, and stores mismatched checksums. We patched all three issues in the compiled library and reported them to the Cogcoin team.

Nunchuk CLI integration: The Nunchuk CLI documentation describes a REST API, but the actual nunchuk binary uses a subcommand structure (nunchuk wallet get, nunchuk tx create). We reverse-engineered the entire CLI from --help output and rewrote the service layer to match the real binary. The default Electrum server was also down — we switched to Blockstream's testnet server.

Claude JSON parsing: Claude occasionally wraps JSON responses in markdown code fences despite explicit instructions not to. We hardened the parser to strip code fences and strengthened the system prompt.

macOS file descriptor limits: The managed bitcoind process requires 160+ file descriptors, but macOS defaults to a soft limit of 256. Combined with other open files, bitcoind would fail silently with "Not enough file descriptors available. -1 available." We added ulimit -n 10240 to the startup process.

Accomplishments that we're proud of

First product built on Nunchuk Agent Skills — released 3 days before the hackathon, implemented in 48 hours
Real blockchain data throughout — every scan hits mempool.space, every wallet operation goes through the real Nunchuk CLI, every audit event touches a real Cogcoin node
Found and fixed 3 bugs in @cogcoin/client — contributed back to the ecosystem
16-point security audit — input validation, rate limiting, security headers, error sanitization across all endpoints
Interactive 3D quantum visualizer — Three.js scene with bloom post-processing, particle rings, electric arcs, and click-to-inspect panels
Zero mock data in production — the guardian chat fetches real balances, the scanner queries real blockchain state, the Cogcoin identity is a real Bitcoin address

What we learned

Bitcoin's quantum vulnerability is not theoretical — the math is concrete and the timeline is accelerating
Bounded authority (not full autonomy) is the right model for AI agents managing financial assets
On-chain accountability via OP_RETURN is a powerful pattern for any automated Bitcoin application
The Nunchuk CLI's multisig model elegantly separates custody from spending authority
Building on sponsor technology released days before a hackathon requires significant reverse-engineering

What's next for BitShield

Fund the Cogcoin wallet to register a domain and activate full on-chain anchoring
BIP-360 (P2QRH) migration assistant — generate post-quantum addresses when the proposal is adopted
Mainnet deployment with real wallet scanning at scale
Institutional dashboard — batch-scan thousands of addresses for quantum migration prioritization
Hardware signer integration — connect Coldcard/Ledger as the user key in the Nunchuk multisig
Open-source the quantum scanner as a standalone library for other Bitcoin wallets to integrate