docs: add mining guide, video script, and P2P protocol docs (#1917)

Author: RematNOC

docs/MASTERING_THE_MINER.md

@@ -0,0 +1,50 @@
+# ⛏️ Mastering the RustChain Miner: Hardware Fingerprints & Dual-Mining v2.0
+
+RustChain isn't just another Proof-of-Work (PoW) coin. It uses **RIP-PoA (Hardware Fingerprint Attestation + Serial Binding)** to ensure that one CPU equals one vote, preventing large-scale farm domination.
+
+This guide covers how to set up and optimize the **Linux Ryzen Miner (v2.0)** for maximum efficiency.
+
+---
+
+## 🏗️ 1. The Core Architecture
+The miner is built on Python 3 but interacts directly with the Linux kernel via `/sys/class/dmi/` to bind your mining identity to your hardware serial number.
+
+### Hardware Binding
+The miner attempts to fetch your serial from:
+1. `/sys/class/dmi/id/product_serial`
+2. `/sys/class/dmi/id/board_serial`
+3. Fallback: `/etc/machine-id` (First 16 characters)
+
+**Tip:** If you are running in a VM, the serial might return `None`. For maximum yield, run on **Bare Metal** to pass the RIP-PoA attestation.
+
+---
+
+## 🛡️ 2. RIP-PoA Fingerprint Checks
+To mine on the mainnet, your machine must pass **6 hardware fingerprint checks**. These include:
+- **DMI Table Validation:** Ensures the BIOS info matches the CPU architecture.
+- **Cache Latency Check:** Detects virtualization or "noisy neighbor" environments.
+- **Instruction Set Verifier:** Confirms the presence of required AVX/AES-NI extensions.
+
+If these checks fail, your attestation will be invalid, and your blocks will be rejected by the node.
+
+---
+
+## ⚡ 3. Dual-Mining with Warthog (Sidecar)
+The v2.0 miner includes the **WarthogSidecar**. This allows you to mine RustChain (CPU) and Warthog (GPU/CPU) simultaneously without context-switching overhead.
+
+### Configuration
+Pass these flags to the `LocalMiner` class or your CLI wrapper:
+- `wart_address`: Your Warthog wallet address.
+- `wart_pool`: The stratum URL for your preferred Warthog pool.
+- `bzminer_path`: Path to your BZminer binary.
+
+---
+
+## 🚀 4. Optimization Tips
+- **Python Warnings:** The miner ignores `Unverified HTTPS` warnings for self-signed node certificates. This is normal but ensure your `NODE_URL` is set to `https://rustchain.org`.
+- **Entropy Management:** The miner tracks `last_entropy` to ensure your PoW isn't being "pre-calculated" on a different machine.
+- **Log Leveling:** Use `color_logs.py` (if available) to visually distinguish between `[FINGERPRINT]` passes and `[PoW]` shares.
+
+---
+
+*Written by RematNOC - Contributing to the RustChain Ecosystem.*

docs/MINER_VIDEO_SCRIPT.md

@@ -0,0 +1,25 @@
+# 🎥 RUSTCHAIN MINER EXPLAINER: 60-Second Script
+
+**Objective:** Explain RIP-PoA and set-up in under a minute for the content bounty.
+
+---
+
+## [0:00-0:10] Intro
+**Visual:** High-tech "RustChain" logo with an animated CPU icon.
+**Audio:** "RustChain is redefining decentralized mining. Forget massive server farms—RustChain uses RIP-PoA to give every CPU one vote."
+
+## [0:10-0:25] The Tech (RIP-PoA)
+**Visual:** Diagram showing a CPU serial number being "locked" to a block.
+**Audio:** "Our miner binds your identity directly to your hardware serial number. By verifying your DMI table and cache latency, we ensure one person equals one vote."
+
+## [0:25-0:40] Dual-Mining
+**Visual:** Split screen: RustChain (CPU) and Warthog (GPU).
+**Audio:** "Maximize your hardware. The v2.0 miner includes the Warthog Sidecar, allowing you to dual-mine RustChain and Warthog simultaneously with zero performance loss."
+
+## [0:40-0:55] Set-up
+**Visual:** Terminal showing: `python3 rustchain_linux_miner.py --wallet [address]`
+**Audio:** "Setup is instant on Linux and Mac. Just point it to your wallet, pass the six fingerprint checks, and start securing the network today."
+
+## [0:55-1:00] Outro
+**Visual:** "rustchain.org" URL and social links.
+**Audio:** "RustChain. The hardware-bound future of mining. Join the Flamekeepers at rustchain.org."

docs/NODE_P2P_PROTOCOL.md

@@ -0,0 +1,37 @@
+# 🌐 Understanding the RustChain Node: P2P Gossip & Block Production
+
+The RustChain node is the heart of the network. It manages the ledger, validates miner attestations, and syncs blocks via a custom **P2P Gossip Protocol**.
+
+---
+
+## 🤝 1. The P2P Handshake
+When a node starts, it connects to seed nodes and performs a handshake.
+- **Identity:** Every node has a unique `node_id`.
+- **Version Check:** Nodes will only peer with others running compatible protocol versions (current: v2.x).
+- **Gossip Mechanism:** When a new block is produced, it is "gossiped" to all connected peers, who then validate and relay it to their own neighbors.
+
+---
+
+## 🧱 2. Block Production & Validation
+Unlike standard PoW where any hash wins, RustChain requires:
+1. **Valid PoW Hash:** Meeting the current network difficulty.
+2. **Valid Hardware Attestation:** The block must include the miner's hardware serial and fingerprint data.
+3. **Serial Binding Check:** The node verifies that this serial hasn't already submitted a block in the current 600-second window.
+
+---
+
+## 🔄 3. State Migration & ROM Clustering
+RustChain uses a unique **ROM Clustering** server for identity management.
+- **Migration:** When the protocol upgrades (e.g., from v1 to v2), the `rustchain_migration.py` script handles the state transition of wallets and hardware bindings.
+- **Fingerprint DB:** A central (or clustered) database stores historical fingerprint data to prevent "fingerprint spoofing" across the network.
+
+---
+
+## 🛡️ 4. Transaction Handling
+The `rustchain_tx_handler.py` manages the mempool.
+- **Validation:** Transactions are checked for double-spending and signature validity before being added to the next block candidate.
+- **Round Robin:** In some versions (RIP-200), a Round Robin 1CPU1Vote mechanism is used to further decentralize the block production among active miners.
+
+---
+
+*Written by RematNOC - Building a decentralized future with RustChain.*