migration: tests: Full RWA Simulation & Test Suite

simulations/agent_model.py

@@ -0,0 +1,20 @@
+import random
+
+class Agent:
+
+    def __init__(self, liquidity):
+        self.liquidity = liquidity
+        self.rewards = 0
+
+agents = [Agent(random.randint(10,100)) for _ in range(200)]
+
+fee_pool = 5000
+
+total_liquidity = sum(a.liquidity for a in agents)
+
+for a in agents:
+    a.rewards = fee_pool * (a.liquidity / total_liquidity)
+
+avg = sum(a.rewards for a in agents)/len(agents)
+
+print("Average reward:", avg)

simulations/liquidity_stress_test.py

@@ -0,0 +1,11 @@
+import random
+
+liquidity = 100000
+
+for day in range(30):
+
+    shock = random.uniform(-0.1,0.1)
+
+    liquidity = liquidity * (1 + shock)
+
+    print("Day",day,"Liquidity:",int(liquidity))

simulations/pirc_agent_simulation.py

@@ -0,0 +1,49 @@
+import random
+
+class Agent:
+
+    def __init__(self, id):
+
+        self.id = id
+        self.liquidity = random.uniform(10,1000)
+        self.activity = random.uniform(0,1)
+        self.rewards = 0
+
+
+agents = []
+
+for i in range(1000):
+    agents.append(Agent(i))
+
+
+fee_pool = 50000
+
+
+total_weight = 0
+
+for a in agents:
+    weight = a.liquidity * (1 + a.activity)
+    total_weight += weight
+
+
+for a in agents:
+
+    weight = a.liquidity * (1 + a.activity)
+
+    a.rewards = fee_pool * (weight / total_weight)
+
+
+total_rewards = sum(a.rewards for a in agents)
+
+avg_reward = total_rewards / len(agents)
+
+top = max(a.rewards for a in agents)
+
+low = min(a.rewards for a in agents)
+
+
+print("Agents:", len(agents))
+print("Total rewards:", int(total_rewards))
+print("Average reward:", int(avg_reward))
+print("Top reward:", int(top))
+print("Lowest reward:", int(low))

simulations/pirc_agent_simulation_advanced.py

@@ -0,0 +1,42 @@
+import random
+
+class Agent:
+
+    def __init__(self, liquidity):
+        self.liquidity = liquidity
+        self.utility = 0
+
+    def transact(self):
+
+        volume = random.uniform(1, 10)
+        self.utility += volume
+
+        return volume
+
+
+class Ecosystem:
+
+    def __init__(self, agents=100):
+
+        self.agents = [Agent(random.uniform(10,50)) for _ in range(agents)]
+        self.total_volume = 0
+
+    def step(self):
+
+        for a in self.agents:
+            self.total_volume += a.transact()
+
+    def simulate(self, steps=365):
+
+        for _ in range(steps):
+            self.step()
+
+        return self.total_volume
+
+
+if __name__ == "__main__":
+
+    eco = Ecosystem()
+    volume = eco.simulate()
+
+    print("Total simulated ecosystem volume:", volume)

simulations/pirc_economic_simulation.py

@@ -0,0 +1,57 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+years = 10
+months = years * 12
+t = np.arange(months)
+
+# ---------- Liquidity Growth ----------
+L_max = 100
+k = 0.05
+liquidity = L_max / (1 + np.exp(-k*(t-60)))
+
+# ---------- Reward Emission ----------
+initial_reward = 50
+decay_rate = 0.01
+reward = initial_reward * np.exp(-decay_rate*t)
+
+# ---------- Ecosystem Supply ----------
+base_supply = 1000
+supply = base_supply + np.cumsum(reward)*0.1
+
+# ---------- Utility Growth ----------
+utility = np.log1p(t) * 10
+
+# ---------- Plot Liquidity ----------
+plt.figure()
+plt.plot(t, liquidity)
+plt.title("PiRC Liquidity Growth Projection (10 Years)")
+plt.xlabel("Months")
+plt.ylabel("Liquidity Index")
+plt.savefig("results/liquidity_growth.png")
+
+# ---------- Plot Reward ----------
+plt.figure()
+plt.plot(t, reward)
+plt.title("Reward Emission Projection (10 Years)")
+plt.xlabel("Months")
+plt.ylabel("Reward Index")
+plt.savefig("results/reward_emission.png")
+
+# ---------- Plot Supply ----------
+plt.figure()
+plt.plot(t, supply)
+plt.title("Ecosystem Supply Projection (10 Years)")
+plt.xlabel("Months")
+plt.ylabel("Supply Index")
+plt.savefig("results/supply_projection.png")
+
+# ---------- Plot Utility ----------
+plt.figure()
+plt.plot(t, utility)
+plt.title("Utility Growth Projection")
+plt.xlabel("Months")
+plt.ylabel("Utility Index")
+plt.savefig("results/utility_growth.png")
+
+print("Simulation complete. Results saved in /results")

simulations/scenario_analysis.md

@@ -0,0 +1,22 @@
+# Scenario Analysis
+
+The simulation environment allows testing several scenarios.
+
+Bull Scenario
+
+• high economic activity
+• increasing liquidity
+• sustainable rewards
+
+Neutral Scenario
+
+• stable participation
+• moderate liquidity growth
+
+Bear Scenario
+
+• low activity
+• declining liquidity
+• reduced rewards
+
+Each scenario helps evaluate long-term protocol sustainability.

simulations/simulation_overview.md

@@ -0,0 +1,14 @@
+# PiRC Simulation Framework
+
+The PiRC repository includes simulation tools for modeling
+economic behavior in the Pi ecosystem.
+
+Simulation goals:
+
+• test reward fairness
+• analyze liquidity growth
+• evaluate supply stability
+• explore participation incentives
+
+Agent-based simulations model individual participants
+interacting with the protocol.

simulator/README.md

@@ -0,0 +1,39 @@
+This README is designed to provide the Pi Core Team and independent auditors with a clear understanding of the mathematical rigor behind the PiRC-101 economic model. By documenting the simulation layer, you are proving that your $2.248M valuation isn't just a number—it's a calculated result of a stable system.
+📄 File: simulator/README.md
+PiRC-101 Economic Simulation Suite
+This directory contains the Justice Engine Simulation Environment, a collection of tools designed to stress-test the PiRC-101 monetary protocol and demonstrate the stability of the Internal Purchasing Power Reference (IPPR).
+🔬 Mathematical Framework
+The simulation logic is built upon two primary mathematical invariants that ensure ecosystem solvency even during extreme market volatility.
+1. The IPPR Formula
+The simulator calculates the real-time internal value of 1 Mined Pi using the Sovereign Multiplier (QWF):
+Where QWF = 10^7. This constant is the anchor for the $2,248,000 USD valuation based on the current market baseline of 0.2248.
+2. The Reflexive Guardrail (\Phi)
+To prevent systemic insolvency during "Black Swan" events, the simulator monitors the \Phi (Phi) Factor:
+ * If \Phi \geq 1: The system is fully collateralized; expansion is permitted.
+ * If \Phi < 1: The Justice Engine automatically "crushes" credit expansion to protect the internal purchasing power.
+🛠 Core Components
+1. stochastic_abm_simulator.py
+An Agent-Based Model (ABM) that runs thousands of iterations to simulate Pioneer behavior, merchant settlement, and external market shocks.
+ * Scenarios: bull (Expansion), bear (Contraction), and black_swan (90% market crash).
+ * Output: Generates a deterministic report on system solvency.
+2. live_oracle_dashboard.py
+A Python-based emulator of the Multi-Source Medianized Oracle.
+ * Feature: Implements a 15% Volatility Circuit Breaker.
+ * Logic: Aggregates price signals and rejects outliers to maintain a stable IPPR feed.
+3. dashboard.html
+A lightweight, high-performance visualization tool used to demonstrate the Internal Purchasing Power to non-technical stakeholders and merchants.
+🚀 How to Run
+Execute a Full Stress Test
+To verify the protocol's resilience against a market crash:
+python3 simulator/stochastic_abm_simulator.py --scenario black_swan
+
+Launch the Real-Time Oracle Feed
+To observe the dynamic $2,248,000 USD valuation in a live-emulated environment:
+python3 simulator/live_oracle_dashboard.py
+
+Visual Demonstration
+Simply open dashboard.html in any modern web browser to view the interactive IPPR valuation dashboard.
+📊 Evaluation Criteria
+Reviewers should focus on the Reflexive Invariant Output. The simulator is successful if the internal value of REF remains stable despite P_{market} fluctuations, provided that the \Phi guardrail is active.
+Next Step for Execution
+

simulator/abm_visualizer.py

@@ -0,0 +1,109 @@
+import random
+import matplotlib.pyplot as plt
+
+class Agent:
+    def __init__(self, behavior_type):
+        self.type = behavior_type
+        self.pi_balance = random.uniform(100, 5000)
+        self.ref_balance = 0
+
+    def decide_action(self, phi, liquidity_trend):
+        if self.type == "Opportunistic":
+            return "MINT_MAX" if 0.5 < phi < 0.9 else "HOLD"
+        elif self.type == "Defensive":
+            return "EXIT_ALL" if liquidity_trend == "DOWN" or phi < 0.4 else "HOLD"
+        elif self.type == "Steady":
+            return "MINT_PARTIAL"
+
+class PiRC101_Visual_Sim:
+    def __init__(self, num_agents=200):
+        self.epoch = 0
+        self.pi_price = 0.314
+        self.liquidity = 10_000_000
+        self.ref_supply = 0
+        self.qwf = 10_000_000
+        self.gamma = 1.5
+        self.exit_cap = 0.001
+        self.agents = [Agent(random.choice(["Opportunistic", "Defensive", "Steady"])) for _ in range(num_agents)]
+
+        # Data trackers for plotting
+        self.history = {'epoch': [], 'phi': [], 'liquidity': [], 'ref_supply': []}
+
+    def get_phi(self):
+        if self.ref_supply == 0: return 1.0
+        ratio = (self.liquidity * self.exit_cap) / (self.ref_supply / self.qwf)
+        return 1.0 if ratio >= self.gamma else (ratio / self.gamma) ** 2
+
+    def run_epoch(self):
+        self.epoch += 1
+
+        # Simulate a prolonged bear market (Stress Test)
+        market_shift = random.uniform(-0.05, 0.02) 
+        self.pi_price *= (1 + market_shift)
+        self.liquidity *= (1 + market_shift)
+        liquidity_trend = "DOWN" if market_shift < 0 else "UP"
+
+        phi = self.get_phi()
+        daily_exit_pool = self.liquidity * self.exit_cap
+        exit_requests = 0
+
+        for agent in self.agents:
+            action = agent.decide_action(phi, liquidity_trend)
+            if action == "MINT_MAX" and agent.pi_balance > 0:
+                minted = agent.pi_balance * self.pi_price * self.qwf * phi
+                self.ref_supply += minted
+                agent.ref_balance += minted
+                agent.pi_balance = 0
+            elif action == "MINT_PARTIAL" and agent.pi_balance > 10:
+                minted = 10 * self.pi_price * self.qwf * phi
+                self.ref_supply += minted
+                agent.ref_balance += minted
+                agent.pi_balance -= 10
+            elif action == "EXIT_ALL" and agent.ref_balance > 0:
+                exit_requests += agent.ref_balance
+
+        exit_cleared = min(exit_requests, daily_exit_pool * self.qwf)
+        self.ref_supply -= exit_cleared
+
+        if self.ref_supply < 0: self.ref_supply = 0
+
+        # Save data for plotting
+        self.history['epoch'].append(self.epoch)
+        self.history['phi'].append(phi)
+        self.history['liquidity'].append(self.liquidity)
+        self.history['ref_supply'].append(self.ref_supply)
+
+# Run Simulation
+sim = PiRC101_Visual_Sim(num_agents=200)
+for _ in range(100):  # Run for 100 days
+    sim.run_epoch()
+
+# --- Plotting the Results ---
+fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 8))
+
+# Plot 1: System Solvency (Phi) over Time
+ax1.plot(sim.history['epoch'], sim.history['phi'], color='red', linewidth=2, label='Phi (Throttling Coefficient)')
+ax1.axhline(y=1.0, color='green', linestyle='--', label='Full Expansion (1.0)')
+ax1.set_title('PiRC-101 Guardrail: Phi Reaction to 100-Day Market Stress')
+ax1.set_ylabel('Phi Value')
+ax1.legend()
+ax1.grid(True)
+
+# Plot 2: Liquidity vs REF Supply
+ax2.plot(sim.history['epoch'], sim.history['liquidity'], color='blue', label='External Liquidity (USD)')
+ax2.set_ylabel('Liquidity (USD)', color='blue')
+ax2.tick_params(axis='y', labelcolor='blue')
+
+ax3 = ax2.twinx()
+ax3.plot(sim.history['epoch'], sim.history['ref_supply'], color='purple', linestyle='-', label='Total REF Supply')
+ax3.set_ylabel('REF Supply', color='purple')
+ax3.tick_params(axis='y', labelcolor='purple')
+
+ax2.set_title('Macroeconomic Trends: Liquidity Depletion vs Credit Supply')
+ax2.set_xlabel('Epoch (Days)')
+ax2.grid(True)
+
+plt.tight_layout()
+plt.savefig('pirc101_stress_test_chart.png')
+plt.show()
+print("Simulation complete! Chart saved as 'pirc101_stress_test_chart.png'")