Merge branch 'main' into main

Author: sanaica

README.md

@@ -4,15 +4,15 @@
 <!-- Organization Logo -->
 <div align="center" style="display: flex; align-items: center; justify-content: center; gap: 16px;">
   <img alt="Stability Nexus" src="public/stability.svg" width="175">
-  <img src="public/todo-project-logo.svg" width="175" />
+  <img alt="MiniChain" src="public/minichain.svg" width="175" />
 </div>
 
 &nbsp;
 
 <!-- Organization Name -->
 <div align="center">
 
-[![Static Badge](https://img.shields.io/badge/Stability_Nexus-/TODO-228B22?style=for-the-badge&labelColor=FFC517)](https://TODO.stability.nexus/)
+[![Static Badge](https://img.shields.io/badge/Stability_Nexus-MiniChain-228B22?style=for-the-badge&labelColor=FFC517)](https://stability.nexus/)
 
 <!-- Correct deployed url to be added -->
 
@@ -32,9 +32,9 @@
 <a href="https://discord.gg/YzDKeEfWtS">
 <img src="https://img.shields.io/discord/995968619034984528?style=flat&logo=discord&logoColor=white&logoSize=auto&label=Discord&labelColor=5865F2&color=57F287" alt="Discord Badge"/></a>
 &nbsp;&nbsp;
-<!-- Medium -->
-<a href="https://news.stability.nexus/">
-  <img src="https://img.shields.io/badge/Medium-black?style=flat&logo=medium&logoColor=black&logoSize=auto&color=white" alt="Medium Badge"></a>
+<!-- Blogs -->
+<a href="https://viewpoints.stability.nexus/">
+  <img src="https://img.shields.io/badge/Stable_Viewpoints-Articles-2ea44f?style=flat&labelColor=facc15" alt="Stable Viewpoints"></a>
 &nbsp;&nbsp;
 <!-- LinkedIn -->
 <a href="https://linkedin.com/company/stability-nexus">
@@ -101,65 +101,12 @@ It is encouraged that you develop an initial prototype during the application ph
 * Read this book:  https://www.marabu.dev/blockchain-foundations.pdf 
 
 
----
-
-## Project Maturity
-
-TODO: In the checklist below, mark the items that have been completed and delete items that are not applicable to the current project:
-
-* [ ] The project has a logo.
-* [ ] The project has a favicon.
-* [ ] The protocol:
-   - [ ] has been described and formally specified in a paper.
-   - [ ] has had its main properties mathematically proven.
-   - [ ] has been formally verified.
-* [ ] The smart contracts:
-   - [ ] were thoroughly reviewed by at least two knights of The Stable Order.
-   - [ ] were deployed to:
-      - [ ] Ergo
-      - [ ] Cardano
-      - [ ] EVM Chains:
-        - [ ] Ethereum Classic
-        - [ ] Ethereum
-        - [ ] Polygon
-        - [ ] BSC
-        - [ ] Base
-* [ ] The mobile app:
-   - [ ] has an _About_ page containing the Stability Nexus's logo and pointing to the social media accounts of the Stability Nexus.
-   - [ ] is available for download as a release in this repo.
-   - [ ] is available in the relevant app stores.
-* [ ] The web frontend:
-   - [ ] has proper title and metadata.
-   - [ ] has proper open graph metadata, to ensure that it is shown well when shared in social media (Discord, Telegram, Twitter, LinkedIn).
-   - [ ] has a footer, containing the Stability Nexus's logo and pointing to the social media accounts of the Stability Nexus.
-   - [ ] is fully static and client-side.
-   - [ ] is deployed to Github Pages via a Github Workflow.
-   - [ ] is accessible through the https://TODO:PROJECT-NAME.stability.nexus domain.
-* [ ] the project is listed in [https://stability.nexus/protocols](https://stability.nexus/protocols).
-
 ---
 
 ## Tech Stack
 
 TODO:
 
-### Frontend
-
-TODO:
-
-- Next.js 14+ (React)
-- TypeScript
-- TailwindCSS
-- shadcn/ui
-
-### Blockchain
-
-TODO:
-
-- Wagmi
-- Solidity Smart Contracts
-- Ethers.js
-
 ---
 
 ## Getting Started
@@ -168,63 +115,15 @@ TODO:
 
 TODO
 
-- Node.js 18+
-- npm/yarn/pnpm
-- MetaMask or any other web3 wallet browser extension
-
 ### Installation
 
 TODO
 
-#### 1. Clone the Repository
-
-```bash
-git clone https://github.com/StabilityNexus/TODO.git
-cd TODO
-```
-
-#### 2. Install Dependencies
-
-Using your preferred package manager:
-
-```bash
-npm install
-# or
-yarn install
-# or
-pnpm install
-```
-
-#### 3. Run the Development Server
-
-Start the app locally:
-
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-```
-
-#### 4. Open your Browser
-
-Navigate to [http://localhost:3000](http://localhost:3000) to see the application.
-
 ---
 
 ## Contributing
 
-We welcome contributions of all kinds! To contribute:
-
-1. Fork the repository and create your feature branch (`git checkout -b feature/AmazingFeature`).
-2. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
-3. Run the development workflow commands to ensure code quality:
-   - `npm run format:write`
-   - `npm run lint:fix`
-   - `npm run typecheck`
-4. Push your branch (`git push origin feature/AmazingFeature`).
-5. Open a Pull Request for review.
+We welcome contributions of all kinds!
 
 If you encounter bugs, need help, or have feature requests:
 

genesis.json

@@ -0,0 +1,13 @@
+{
+  "chain_id": "minichain_testnet_1",
+  "timestamp": 1716880000000,
+  "difficulty": 4,
+  "alloc": {
+    "0000000000000000000000000000000000000001": {
+      "balance": 1000000000
+    },
+    "0000000000000000000000000000000000000002": {
+      "balance": 500000000
+    }
+  }
+}

main.py

@@ -19,7 +19,6 @@
 import argparse
 import asyncio
 import logging
-import os
 import re
 import sys
 
@@ -77,6 +76,8 @@ def mine_and_process_block(chain, mempool, miner_pk):
         logger.info("No mineable transactions in current queue window.")
         return None
 
+    temp_state.credit_mining_reward(miner_pk)
+
     block = Block(
         index=chain.last_block.index + 1,
         previous_hash=chain.last_block.hash,
@@ -89,7 +90,6 @@ def mine_and_process_block(chain, mempool, miner_pk):
     if chain.add_block(mined_block):
         logger.info("✅ Block #%d mined and added (%d txs)", mined_block.index, len(mineable_txs))
         mempool.remove_transactions(mineable_txs)
-        chain.state.credit_mining_reward(miner_pk)
         return mined_block
     else:
         logger.error("❌ Block rejected by chain")
@@ -148,10 +148,6 @@ async def handler(data):
             if chain.add_block(block):
                 logger.info("📥 Received Block #%d — added to chain", block.index)
 
-                # Apply mining reward for the remote miner (burn address as placeholder)
-                miner = payload.get("miner", BURN_ADDRESS)
-                chain.state.credit_mining_reward(miner)
-
                 # Drop only confirmed transactions so higher nonces can remain queued.
                 mempool.remove_transactions(block.transactions)
             else:
@@ -295,11 +291,12 @@ async def run_node(port: int, host: str, connect_to: str | None, fund: int, data
 
     # Load existing chain from disk, or start fresh
     chain = None
-    if datadir and os.path.exists(os.path.join(datadir, "data.json")):
+    if datadir:
         try:
-            from minichain.persistence import load
-            chain = load(datadir)
-            logger.info("Restored chain from '%s'", datadir)
+            from minichain.persistence import load, persistence_exists
+            if persistence_exists(datadir):
+                chain = load(datadir)
+                logger.info("Restored chain from '%s'", datadir)
         except FileNotFoundError as e:
             logger.warning("Could not load saved chain: %s — starting fresh", e)
         except ValueError as e:

minichain/block.py

@@ -59,6 +59,8 @@ def __init__(
         self.difficulty: Optional[int] = difficulty
         self.nonce: int = 0
         self.hash: Optional[str] = None
+        self.state_root: Optional[str] = state_root
+        self.miner: Optional[str] = miner
 
         # NEW: compute merkle root once
         self.merkle_root: Optional[str] = _calculate_merkle_root(self.transactions)
@@ -71,9 +73,11 @@ def to_header_dict(self):
             "index": self.index,
             "previous_hash": self.previous_hash,
             "merkle_root": self.merkle_root,
+            "state_root": self.state_root,
             "timestamp": self.timestamp,
             "difficulty": self.difficulty,
             "nonce": self.nonce,
+            "miner": self.miner,
         }
         # Include miner in header only when present (optional field)  <-- Reworded comment
         if self.miner is not None:

minichain/chain.py

@@ -3,6 +3,9 @@
 from .pow import calculate_hash
 import logging
 import threading
+import json
+import os
+import sys
 
 logger = logging.getLogger(__name__)
 
@@ -28,22 +31,61 @@ class Blockchain:
     Manages the blockchain, validates blocks, and commits state transitions.
     """
 
-    def __init__(self):
+    def __init__(self, genesis_path="genesis.json"):
         self.chain = []
         self.state = State()
         self._lock = threading.RLock()
-        self._create_genesis_block()
+        self._create_genesis_block(genesis_path)
 
-    def _create_genesis_block(self):
+    def _create_genesis_block(self, genesis_path):
         """
-        Creates the genesis block with a fixed hash.
+        Creates the genesis block and initializes state from config.
         """
+        config = {}
+        if os.path.exists(genesis_path):
+            try:
+                with open(genesis_path, "r") as f:
+                    config = json.load(f)
+            except Exception as e:
+                logger.error(f"Failed to load genesis config: {e}")
+                sys.exit(1)
+        else:
+            logger.error(f"Failed to load genesis config: file {genesis_path} does not exist.")
+            sys.exit(1)
+        
+        # Apply genesis allocations
+        alloc = config.get("alloc", {})
+        for address, data in alloc.items():
+            balance = data.get("balance", 0)
+            if not isinstance(balance, int) or balance < 0:
+                logger.error(f"Invalid genesis balance for {address}: {balance}. Must be a non-negative integer.")
+                sys.exit(1)
+            account = self.state.get_account(address)
+            account['balance'] = balance
+
+        timestamp = config.get("timestamp")
+        difficulty = config.get("difficulty")
+        
         genesis_block = Block(
             index=0,
             previous_hash="0",
-            transactions=[]
+            transactions=[],
+            timestamp=timestamp,
+            difficulty=difficulty,
+            state_root=self.state.state_root()
         )
-        genesis_block.hash = "0" * 64
+        
+        computed_hash = calculate_hash(genesis_block.to_header_dict())
+        config_hash = config.get("hash")
+        
+        if config_hash:
+            if config_hash != computed_hash:
+                logger.error(f"Genesis hash mismatch. Config hash: {config_hash}, Computed hash: {computed_hash}")
+                sys.exit(1)
+            genesis_block.hash = config_hash
+        else:
+            genesis_block.hash = computed_hash
+            
         self.chain.append(genesis_block)
 
     @property
@@ -78,6 +120,14 @@ def add_block(self, block):
                     logger.warning("Block %s rejected: Transaction failed validation", block.index)
                     return False
 
+            if block.miner:
+                temp_state.credit_mining_reward(block.miner)
+
+            # Verify state root
+            if block.state_root != temp_state.state_root():
+                logger.warning("Block %s rejected: Invalid state root. Expected %s, got %s", block.index, temp_state.state_root(), block.state_root)
+                return False
+
             # All transactions valid → commit state and append block
             self.state = temp_state
             self.chain.append(block)