AIQnetLab
diff --git a/‎development/qnet-contracts/examples/README.md‎
Lines changed: 67 additions & 0 deletions b/‎development/qnet-contracts/examples/README.md‎
Lines changed: 67 additions & 0 deletions
diff --git a/‎development/qnet-contracts/examples/node_stake_registry.rs‎
Lines changed: 216 additions & 0 deletions b/‎development/qnet-contracts/examples/node_stake_registry.rs‎
Lines changed: 216 additions & 0 deletions
@@ -0,0 +1,67 @@
+# QNet Native Smart Contract Examples
+
+Examples of contracts targeting QNet's Post-Quantum EVM (PQ-EVM).
+All signing uses **CRYSTALS-Dilithium3** (ML-DSA-65, NIST FIPS 204 Level 3) — the same algorithm
+used by QNet's core consensus layer (`quantum_crypto.rs`).
+Encryption uses **CRYSTALS-Kyber1024** (NIST FIPS 203).
+
+---
+
+## Contracts
+
+| File | Description |
+|------|-------------|
+| `qnet_token.rs` | QEP-20 fungible token — QNet equivalent of ERC-20 |
+| `pq_multisig.rs` | 2-of-N PQ multi-sig wallet using Dilithium3 signatures (ML-DSA-65) |
+| `qnc_yield_pool.rs` | **User/wallet-facing** QNC yield pool — purely financial, no node logic. Any wallet user stakes QNC and earns proportional yield (`reward = pool × stake / total_staked`). Deployer funds the reward pool; QNet block production is unaffected. |
+
+---
+
+## Compiling & Deploying
+
+> Requires the `qnet-node` binary built in release mode.
+
+```bash
+# 1. Build the node binary (run from repo root)
+cargo build --release --bin qnet-node
+
+# 2. Deploy a contract via the RPC endpoint
+curl -X POST http://localhost:9876/api/v1/contract/deploy \
+  -H "Content-Type: application/json" \
+  -d '{
+    "from": "YOUR_WALLET_ADDRESS",
+    "bytecode": "0x6000F3",
+    "gas_limit": 1000000,
+    "value": 0,
+    "pq_signature": "BASE64_DILITHIUM_SIG"
+  }'
+
+# 3. Call a deployed contract
+curl -X POST http://localhost:9876/api/v1/contract/call \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "CONTRACT_ADDRESS",
+    "data": "0x00000001...",
+    "gas_limit": 100000
+  }'
+```
+
+---
+
+## Writing Your Own Contract
+
+QNet contracts are currently written as Rust modules that produce bytecode
+via the `PQEvmInterpreter`. A high-level source language (`qnet-sol`) is on
+the roadmap. For now, use the helper functions in `qnet_token.rs` as a template.
+
+Key differences from Ethereum Solidity:
+
+| Feature | Ethereum | QNet |
+|---------|----------|------|
+| Signature scheme | ECDSA (secp256k1) | Dilithium3 / ML-DSA-65 (NIST FIPS 204 L3) |
+| Hash function | Keccak-256 | Keccak-256 + SHA3-256 |
+| Encryption | none native | Kyber1024 via PQ_ENCRYPT opcode |
+| Block time | ~12 s | ~1 s (microblock) |
+| Finality | ~2 min (32 conf.) | MacroBlock (~90 s) |
+| Custom opcodes | — | `0xE0` MICROBLOCK_COMMIT, `0xE1` MICROBLOCK_VERIFY |
+| PQ opcodes | — | `0xF0` PQ_SIGN, `0xF1` PQ_VERIFY, `0xF2` PQ_ENCRYPT |
@@ -0,0 +1,216 @@
+/// QNet Node Stake Registry Contract
+///
+/// On-chain registry for Super/Light node registrations and QNC stake management.
+/// Replaces the off-chain Python `node_activation_qnc.py` with a fully on-chain
+/// PQ-EVM contract that enforces staking rules deterministically.
+///
+/// # Responsibilities
+///
+/// - Accept QNC stake deposits from node operators
+/// - Record node type (Light=1, Super=2), region, and Dilithium5 public key
+/// - Gate participation: nodes below `MIN_STAKE` are excluded from emission
+/// - Allow unstake after a cooldown period
+/// - Emit events for the explorer/indexer
+///
+/// # Storage layout
+///
+/// | Slot              | Content                                         |
+/// |-------------------|-------------------------------------------------|
+/// | 0x00              | admin address (lower 8 bytes)                   |
+/// | 0x01              | total_staked (u64 QNC, 9-decimal fixed-point)   |
+/// | 0x10_0000 + addr  | NodeRecord { node_type, stake, registered_at }  |
+/// | 0x20_0000 + addr  | dilithium5 pk offset in PQ key store            |
+
+use crate::{Address, ExecutionContext, StateChange, Log};
+use pqcrypto_mldsa::mldsa87 as dilithium5;
+use pqcrypto_traits::sign::PublicKey;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Minimum stake for a Light node: 100 QNC (9 decimals)
+pub const MIN_STAKE_LIGHT: u64 = 100 * 1_000_000_000;
+
+/// Minimum stake for a Super node: 1000 QNC
+pub const MIN_STAKE_SUPER: u64 = 1_000 * 1_000_000_000;
+
+/// Unstake cooldown: 14 days in seconds
+pub const UNSTAKE_COOLDOWN_SECS: u64 = 14 * 24 * 3600;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Data types
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum NodeType {
+    Light = 1,
+    Super = 2,
+}
+
+impl TryFrom<u64> for NodeType {
+    type Error = &'static str;
+    fn try_from(v: u64) -> Result<Self, Self::Error> {
+        match v {
+            1 => Ok(NodeType::Light),
+            2 => Ok(NodeType::Super),
+            _ => Err("Invalid node type (must be 1=Light or 2=Super)"),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct NodeRecord {
+    pub node_type: NodeType,
+    pub stake: u64,
+    pub registered_at: u64,       // block timestamp
+    pub unstake_requested_at: u64, // 0 if not requested
+    pub pq_pubkey: Vec<u8>,        // Dilithium5 serialised public key
+    pub region: u8,                // 0-based region index
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Contract implementation (runs in PQ-EVM interpreter context)
+// ─────────────────────────────────────────────────────────────────────────────
+
+pub struct NodeStakeRegistry {
+    pub admin: Address,
+    pub nodes: std::collections::HashMap<Address, NodeRecord>,
+    pub total_staked: u64,
+}
+
+impl NodeStakeRegistry {
+    pub fn new(admin: Address) -> Self {
+        Self { admin, nodes: Default::default(), total_staked: 0 }
+    }
+
+    /// Register a new node with stake.
+    ///
+    /// `pq_pubkey_bytes` must be a valid Dilithium5 serialised public key.
+    pub fn register(
+        &mut self,
+        caller: Address,
+        node_type: NodeType,
+        region: u8,
+        pq_pubkey_bytes: Vec<u8>,
+        stake_amount: u64,
+        timestamp: u64,
+    ) -> Result<Vec<Log>, String> {
+        if self.nodes.contains_key(&caller) {
+            return Err("Node already registered".to_string());
+        }
+
+        let min_stake = match node_type {
+            NodeType::Light => MIN_STAKE_LIGHT,
+            NodeType::Super => MIN_STAKE_SUPER,
+        };
+        if stake_amount < min_stake {
+            return Err(format!(
+                "Insufficient stake: required={} provided={}",
+                min_stake, stake_amount
+            ));
+        }
+
+        // Validate PQ public key
+        dilithium5::PublicKey::from_bytes(&pq_pubkey_bytes)
+            .map_err(|_| "Invalid Dilithium5 public key".to_string())?;
+
+        self.total_staked = self.total_staked.saturating_add(stake_amount);
+        self.nodes.insert(caller, NodeRecord {
+            node_type: node_type.clone(),
+            stake: stake_amount,
+            registered_at: timestamp,
+            unstake_requested_at: 0,
+            pq_pubkey: pq_pubkey_bytes,
+            region,
+        });
+
+        let mut topic = [0u8; 32];
+        topic[31] = node_type as u8;
+        Ok(vec![Log {
+            address: caller,
+            topics: vec![topic],
+            data: format!("NodeRegistered:stake={}", stake_amount).into_bytes(),
+        }])
+    }
+
+    /// Initiate unstake cooldown.
+    pub fn request_unstake(
+        &mut self,
+        caller: Address,
+        timestamp: u64,
+    ) -> Result<(), String> {
+        let rec = self.nodes.get_mut(&caller).ok_or("Node not registered")?;
+        if rec.unstake_requested_at > 0 {
+            return Err("Unstake already requested".to_string());
+        }
+        rec.unstake_requested_at = timestamp;
+        Ok(())
+    }
+
+    /// Finalise unstake after cooldown. Returns stake amount to return to caller.
+    pub fn finalize_unstake(
+        &mut self,
+        caller: Address,
+        timestamp: u64,
+    ) -> Result<u64, String> {
+        let rec = self.nodes.get(&caller).ok_or("Node not registered")?;
+        if rec.unstake_requested_at == 0 {
+            return Err("Unstake not requested".to_string());
+        }
+        if timestamp < rec.unstake_requested_at + UNSTAKE_COOLDOWN_SECS {
+            let remaining = (rec.unstake_requested_at + UNSTAKE_COOLDOWN_SECS) - timestamp;
+            return Err(format!("Cooldown not expired: {}s remaining", remaining));
+        }
+        let stake = rec.stake;
+        self.total_staked = self.total_staked.saturating_sub(stake);
+        self.nodes.remove(&caller);
+        Ok(stake)
+    }
+
+    /// Returns nodes eligible for emission in the current epoch.
+    /// Eligibility: registered, stake >= minimum, no pending unstake.
+    pub fn eligible_nodes(&self) -> Vec<(&Address, &NodeRecord)> {
+        self.nodes.iter().filter(|(_, r)| {
+            r.unstake_requested_at == 0 && r.stake >= match r.node_type {
+                NodeType::Light => MIN_STAKE_LIGHT,
+                NodeType::Super => MIN_STAKE_SUPER,
+            }
+        }).collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_register_and_unstake() {
+        let admin: Address = [0x01; 20];
+        let node: Address  = [0x02; 20];
+        let mut registry = NodeStakeRegistry::new(admin);
+
+        let (pk, _sk) = dilithium5::keypair();
+        let pk_bytes = pk.as_bytes().to_vec();
+
+        let logs = registry.register(
+            node,
+            NodeType::Super,
+            0,
+            pk_bytes,
+            MIN_STAKE_SUPER,
+            1_000_000,
+        ).expect("registration failed");
+        assert_eq!(logs.len(), 1);
+        assert_eq!(registry.eligible_nodes().len(), 1);
+
+        // Request unstake then attempt to finalise too early
+        registry.request_unstake(node, 1_000_000).unwrap();
+        assert!(registry.finalize_unstake(node, 1_000_001).is_err());
+
+        // Finalise after cooldown
+        let amount = registry.finalize_unstake(node, 1_000_000 + UNSTAKE_COOLDOWN_SECS + 1).unwrap();
+        assert_eq!(amount, MIN_STAKE_SUPER);
+        assert!(registry.nodes.is_empty());
+    }
+}