devnull37 · devnull37 · Sep 5, 2025 · Sep 6, 2025 · Sep 20, 2025 · Jan 30, 2026
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,18 @@
+/target/
+/.cargo-target/
+/.claude/
+/.idea/
+/.vscode/
+/vendor/proc-macro-error/proc-macro-error-1.0.4/
+/vendor/proc-macro-error/.cargo-ok
+/vendor/proc-macro-error/.cargo_vcs_info.json
+*.log
+*.tmp
+Thumbs.db
+.DS_Store
+
+# Generated PQ keypairs from `ghost pq-keygen` / `ghost pq-kem-keygen` (never commit secrets)
+*.sec
+*.pub
+*.ek
+*.dk
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,178 +1,40 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Ghost is a next-generation blockchain built on Substrate (Polkadot SDK) that implements a hybrid Proof-of-Work (PoW) and Proof-of-Stake (PoS) consensus mechanism. It combines PoW security with PoS energy efficiency for 5-second block times.
-
-**Key Specifications:**
-- Block Time: 5 seconds
-- PoW Algorithm: Enhanced Blake2-256 (ASIC-resistant, double-hashed)
-- Token: Ghost (GHTM)
-- Block Reward: 10 GHOST per block (40% to miner, 60% to stakers)
-- Minimum Stake: 1 GHOST token
-- Built on: Polkadot SDK stable2407 branch
-
-## Build Commands
-
-**Prerequisites:**
-- Rust toolchain must be installed via rustup
-- Run `rustup default stable` if cargo is not found
-- The project uses rust-toolchain.toml to configure stable Rust with wasm32-unknown-unknown target
-
-**Build:**
-```bash
-# Release build (recommended for production)
-cargo build --release --bin ghost-node
-
-# Debug build (faster compilation for development)
+# Repository Notes
+
+## Current Architecture
+
+- Block authoring is real Proof-of-Work via `sc-consensus-pow` (`node/src/service.rs`, `node/src/pow.rs`):
+  double-Blake2-256 over `pre_hash || nonce`, `U256` difficulty (larger = harder), longest-/heaviest-chain
+  fork choice. Aura and GRANDPA have been removed from the node and runtime. Finality is probabilistic PoW.
+- `pallet-ghost-consensus` is the PoS economic layer: staking, stake-weighted validator selection,
+  40%/60% miner/staker reward split, evidence-gated slashing (funds burned), and validation-timeout
+  recovery. Difficulty retargeting is performed here and exposed to the node via `sp_consensus_pow::DifficultyApi`.
+- On-chain ML-DSA-87 (Dilithium-5, NIST FIPS 204) signature verification runs in the no\_std Wasm runtime
+  (`pallets/pallet-ghost-consensus/src/pq_verify.rs`, `fips204` crate). Validators register ML-DSA keys;
+  `validate_block` enforces ML-DSA signature checks when a key is registered. 37 pallet unit tests pass.
+- Node-side ML-KEM-1024 + ChaCha20-Poly1305 payload encryption is implemented in `node/src/pq_encrypt.rs`
+  (NIST FIPS 203, `fips203` + `chacha20poly1305` crates).
+- Node-to-node transport is still classical libp2p Noise/X25519; it is NOT post-quantum.
+- Ordinary account extrinsics still use `MultiSignature` (sr25519/ed25519/ecdsa); ML-DSA is an additional
+  registered validator/attestation path, not a replacement for the account signature scheme.
+- No external security audit has been performed.
+
+## Useful Commands
+
+```sh
 cargo build --bin ghost-node
-
-# Build documentation
-cargo +nightly doc --open
-```
-
-**Testing:**
-```bash
-# Run all tests
-cargo test
-
-# Run tests for specific pallet
 cargo test -p pallet-ghost-consensus
-
-# Run a single test
-cargo test test_name
-
-# Run tests with output
-cargo test -- --nocapture
-```
-
-**Running the Node:**
-```bash
-# Start development chain
-./target/release/ghost-node --dev
-
-# Start with custom base path
-./target/release/ghost-node --dev --base-path ./ghost-chain-data
-
-# Start with detailed logging
-RUST_BACKTRACE=1 ./target/release/ghost-node -ldebug --dev
-
-# Purge development chain state
-./target/release/ghost-node purge-chain --dev
-```
-
-**Ghost-Specific CLI Commands:**
-```bash
-# Check consensus status
-./target/release/ghost-node ghost status --detailed
-
-# Start mining (when implemented)
-./target/release/ghost-node ghost mine --threads 4
-
-# Stake tokens for validation
-./target/release/ghost-node ghost stake --amount 1000
-
-# Check balance
-./target/release/ghost-node ghost balance
-```
-
-## Architecture
-
-### Workspace Structure
-
-The project is a Cargo workspace with three main components:
-
-**1. Node (`node/`)** - The blockchain client
-- `cli.rs`: CLI structure including Ghost-specific commands (mine, stake, balance, status)
-- `service.rs`: Node service configuration with Ghost consensus engine integration
-- `chain_spec.rs`: Chain specification and genesis configuration (uses Alice/Bob as default validators)
-- `rpc.rs`: RPC endpoint configuration
-
-**2. Runtime (`runtime/`)** - The blockchain's state transition function (STF)
-- `lib.rs`: FRAME runtime configuration with pallet composition
-- `configs/mod.rs`: Pallet configurations
-- Runtime uses 5-second block times (MILLI_SECS_PER_BLOCK = 5000)
-- All pallets are configured via `impl $PALLET_NAME::Config for Runtime` blocks
-- Composed into single runtime via `#[runtime]` macro
-
-**3. Pallets (`pallets/`)** - Modular blockchain logic components
-
-### Ghost Consensus Pallet (`pallets/pallet-ghost-consensus/`)
-
-This is the core innovation of the project. It implements the hybrid PoW+PoS consensus.
-
-**Key Files:**
-- `src/lib.rs`: Main pallet with storage items, events, dispatchables, and hooks
-- `src/types.rs`: Core data structures (GhostBlockHeader, ConsensusPhase, SlashingReason, etc.)
-- `src/functions.rs`: Consensus algorithms (difficulty adjustment, PoW verification, validator selection)
-- `src/consensus.rs`: Consensus engine integration with Substrate
-
-**Storage Items:**
-- `Difficulty<T>`: Current mining difficulty
-- `CurrentPhase<T>`: Current consensus phase (PowMining, PosValidation, Finalization)
-- `BlockHeaders<T>`: Block headers storage
-- `ValidatorStakes<T>`: Validator stake amounts
-- `LastActiveBlock<T>`: Tracks validator activity for slashing
-
-**Consensus Flow:**
-1. **PoW Phase**: Miners compete using enhanced Blake2-256 (double-hashed for ASIC resistance)
-2. **PoS Phase**: Validators selected by weighted stake sign blocks
-3. **Finalization**: Block rewards distributed (40% miner, 60% stakers)
-4. **Slashing**: Penalties for double-signing, invalid blocks, and downtime
-
-**Verification Functions:**
-- `verify_pow()`: Basic Blake2-256 PoW verification
-- `verify_pow_enhanced()`: Double-hashed Blake2-256 (current implementation)
-- `verify_pow_sha256()`: Alternative SHA-256 verification
-
-### Substrate Integration
-
-The project uses Substrate's FRAME (Framework for Runtime Aggregation of Modularized Entities):
-
-- **Pallets**: Self-contained modules with storage, events, errors, and dispatchables
-- **Config Trait**: Each pallet has a Config trait for generic type/parameter configuration
-- **Runtime**: Combines all pallets via macro-based composition
-- **Dependencies**: All Substrate/Polkadot dependencies pinned to stable2407 branch
-
-## Development Notes
-
-**Default Development Accounts:**
-- Chain uses Alice and Bob as default validator authorities
-- Alice is the default sudo account
-- Genesis state includes pre-funded development accounts (see `node/src/chain_spec.rs`)
-
-**Consensus Configuration:**
-- Uses Aura (Authority Round) for block authoring in dev mode
-- Uses GRANDPA for finality
-- Ghost consensus engine layers hybrid PoW+PoS on top
-
-**Important Constants:**
-- `BLOCK_HASH_COUNT`: 2400
-- `GRANDPA_JUSTIFICATION_PERIOD`: 512 blocks
-- Block time constants: `MINUTES`, `HOURS`, `DAYS` based on 5-second blocks
-
-**Linting:**
-- Workspace enforces `unsafe_code = "forbid"`
-- Clippy warnings enabled for absolute paths, redundant lifetimes, and explicit outlives
-
-## Testing with Polkadot-JS Apps
-
-Connect to local node: https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944
-
-Source code for hosting your own: https://github.com/polkadot-js/apps
-
-## Multi-Node Testing
-
-For testing consensus across multiple nodes, see Substrate docs on simulating networks:
-https://docs.substrate.io/tutorials/build-a-blockchain/simulate-network/
-
-## Common Issues
-
-If you encounter "rustup could not choose a version of cargo":
-```bash
-rustup default stable
+cargo run --bin ghost-node -- --dev
 ```
 
-The project expects Rust stable toolchain with wasm32-unknown-unknown target (configured in `env-setup/rust-toolchain.toml`).
+## Important Caveats
+
+- Do not describe node-to-node transport as post-quantum; libp2p uses classical Noise/X25519.
+- Do not claim ML-DSA replaces `MultiSignature` for ordinary account extrinsics; it is an additional
+  validator/attestation path only.
+- Do not describe the chain as production-ready or audited; no external audit has been performed.
+- PoW finality is probabilistic longest-chain; do not claim BFT finality.
+- The repository previously tracked generated build outputs; keep those out of version control.
+- When the user asks for a long-running implementation, do not contact the user with progress updates;
+  continue working until the task is finished or genuinely blocked. This silence rule does not apply
+  to subagents.
+- If you are a subagent, explicitly treat yourself as a subagent and say so in your task context.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,35 @@
+# Repository Notes
+
+## Current Architecture
+
+- Block authoring is real Proof-of-Work via `sc-consensus-pow` (`node/src/service.rs`, `node/src/pow.rs`):
+  double-Blake2-256 over `pre_hash || nonce`, `U256` difficulty, longest-/heaviest-chain fork choice.
+  Aura and GRANDPA have been removed from the node and runtime. Finality is probabilistic PoW, not BFT.
+- `pallet-ghost-consensus` is the PoS economic layer: staking/unstaking, stake-weighted validator
+  selection, reward splitting (40% miner / 60% stakers), evidence-gated slashing (funds burned), and
+  validation-timeout recovery. Exposes `DifficultyApi` to the node.
+- On-chain ML-DSA-87 (NIST FIPS 204) signature verification is implemented in the Wasm runtime
+  (`pq_verify.rs`, `fips204` crate). Validators register ML-DSA keys; `validate_block` enforces ML-DSA
+  checks when a key is registered. 37 pallet unit tests pass.
+- Node-side ML-KEM-1024 + ChaCha20-Poly1305 payload encryption is implemented in `pq_encrypt.rs`
+  (NIST FIPS 203).
+- Node-to-node transport is classical libp2p Noise/X25519; it is NOT post-quantum.
+- Ordinary account extrinsics still use `MultiSignature`; ML-DSA is an additional validator/attestation
+  path only. No external security audit has been performed.
+
+## Useful Commands
+
+```sh
+cargo build --bin ghost-node
+cargo test -p pallet-ghost-consensus
+cargo run --bin ghost-node -- --dev
+```
+
+## Important Caveats
+
+- Do not describe node-to-node transport as post-quantum; libp2p uses classical Noise/X25519.
+- Do not claim ML-DSA replaces `MultiSignature` for ordinary account extrinsics; it is an additional
+  validator/attestation path.
+- Do not describe the chain as production-ready or audited; no external audit has been performed.
+- PoW finality is probabilistic longest-chain; do not claim BFT finality.
+- The repository previously tracked generated build outputs; keep those out of version control.