migration: docs: Architecture Diagrams

diagrams/economic-loop.md

@@ -0,0 +1,11 @@
+Pioneer Mining
+      ↓
+Liquidity Weight Engine
+      ↓
+Economic Activity
+      ↓
+Fee Pool
+      ↓
+Reward Vault
+      ↓
+Liquidity Incentives

diagrams/pirc-economic-loop.md

@@ -0,0 +1,45 @@
+# PiRC Economic Coordination Loop
+
+                 ┌────────────────────┐
+                 │    Pioneer Mining   │
+                 │  (User Participation)│
+                 └─────────┬──────────┘
+                           │
+                           ▼
+                 ┌────────────────────┐
+                 │  Reward Allocation  │
+                 │   Reward Engine     │
+                 └─────────┬──────────┘
+                           │
+                           ▼
+                 ┌────────────────────┐
+                 │  Liquidity Supply   │
+                 │ Liquidity Controller│
+                 └─────────┬──────────┘
+                           │
+                           ▼
+                 ┌────────────────────┐
+                 │   DEX Transactions  │
+                 │    DEX Executor     │
+                 └─────────┬──────────┘
+                           │
+                           ▼
+                 ┌────────────────────┐
+                 │    Fee Generation   │
+                 │     Treasury        │
+                 └─────────┬──────────┘
+                           │
+                           ▼
+                 ┌────────────────────┐
+                 │  Governance Layer   │
+                 │ Parameter Updates   │
+                 └─────────┬──────────┘
+                           │
+                           ▼
+                 ┌────────────────────┐
+                 │ Ecosystem Expansion │
+                 │  Apps + Utilities   │
+                 └─────────┬──────────┘
+                           │
+                           ▼
+                     (Feedback Loop)

docs/ECONOMIC_PARITY.md

@@ -0,0 +1,15 @@
+# Economic Parity & Anti-Discrimination Framework
+
+## 1. The Capacity Model (Not Dual Price)
+PIRC-101 does not set two prices for the same good. It sets a single USD price.
+- **Speculative Capital:** Pays the USD price via external market liquidation.
+- **Productive Capital (Mined Pi):** Utilizes "Reserved Minting Capacity" earned through the Proof-of-Work (PoW) history.
+
+## 2. Dynamic Multiplier Smoothing (DMS)
+To prevent the "Absurd Calculation" (10M:1 ratio), the QWF is subjected to a **Liquidity Density Filter**:
+$$QWF_{effective} = QWF_{max} \cdot \left( \frac{L_{internal}}{L_{external}} \right)$$
+This ensures that if external liquidity increases, the internal multiplier "cools down" to maintain economic parity.
+
+## 3. Decentralized Provenance (Zero-Knowledge)
+To address "Centralized Control," the Snapshot registry is replaced by a **ZKP (Zero-Knowledge Proof)** circuit. Users prove their "Mined" status without a central registry, ensuring privacy and censorship resistance.
+

docs/MERCHANT_INTEGRATION.md

@@ -0,0 +1,22 @@
+# Merchant Integration Guide: PiRC-101 Protocol
+
+This guide provides the technical specifications for merchants to integrate the **$2,248,000 USD** internal purchasing power standard into their POS (Point of Sale) systems.
+
+## 1. Valuation Mechanism
+Merchants list products in **USD**. The PiRC-101 Justice Engine provides a real-time bridge where:
+`1 Mined Pi = [Market Price] * 10,000,000 USD`
+
+## 2. API Implementation
+Use the `JusticeEngineOracle` to fetch the current internal purchasing power.
+- **Input:** 1 Pi
+- **Output:** Current $REF$ (Sovereign USD-equivalent Credit)
+
+## 3. Transaction Example
+- **Item Price:** $2,248.00 USD
+- **Pioneer Pays:** 0.001 Mined Pi
+- **Merchant Receives:** 2,248 $REF$ units (Fully backed by Pi collateral in the Core Vault).
+
+## 4. Merchant Benefits
+- **Zero Volatility:** Protection against external market crashes.
+- **Instant Settlement:** No waiting for external exchange liquidations.
+

docs/PI-STANDARD-101.md

@@ -0,0 +1,17 @@
+# PI-STANDARD-101: Sovereign Monetary Standard (USD-Equivalent)
+
+## 1. Internal Purchasing Power Definition
+The protocol defines the **Internal Purchasing Power ($V_{int}$)** as the dollar-equivalent value of 1 Mined Pi within the sovereign ecosystem.
+
+## 2. Real-Time Valuation Logic
+The "Justice Engine" uses a **Direct Oracle Feed** from global exchanges to calculate the instantaneous purchasing power:
+
+$$V_{int} (USD) = P_{live} \times QWF$$
+
+- **P_live:** Real-time market price (e.g., $0.2248).
+- **QWF:** Sovereign Expansion Multiplier ($10,000,000$).
+- **Final Result:** **$2,248,000 USD** of internal purchasing power per 1 Mined Pi.
+
+## 3. Why USD?
+By anchoring internal credit to the USD equivalent, we provide a familiar benchmark for Pioneers, Merchants, and Institutions, ensuring the "Justice Engine" remains the gold standard for blockchain stability.
+

docs/PiRC-207_CEX_Liquidity_Entry.md

@@ -0,0 +1,9 @@
+# PiRC-207: CEX Liquidity Entry Rules
+
+- Hold exactly 1 PI in the system
+- Lock into 10,000,000 CEX Liquidity Pool
+- Minimum participation: 1000 CEX
+- π (blue) represents liquidity accumulation × 31,847
+- All calculations and governance votes are transparent on Vanguard Bridge
+
+Approved for immediate integration.

docs/PiRC101_Whitepaper.md

@@ -0,0 +1,48 @@
+# PiRC-101: Sovereign Monetary Standard Specification
+
+## 1. Executive Summary
+This document provides the formal normative specification for **PiRC-101**, a decentralized monetary standard engineered for the Pi Network GCV (Global Consensus Value) merchant ecosystem. It introduces a reflexive, collateral-backed stable credit system ($REF$) to isolate internal productive commerce from external market volatility.
+
+## 2. Introduction: The Walled Garden Architecture
+PiRC-101 creates a productive "Walled Garden." It solves the DeFi Triffin Dilemma by safely backing internal sovereign credits ($REF$) with a 10M:1 expansion on locked external Pi ($P_e$).
+
+## 3. Normative Specification: The State Machine
+This section defines the formal state of the standard at any given Epoch $n$.
+
+### 3.1. Primary State Vector (${\Omega}_n$)
+$${\Omega}_n = \{R_n, S_n, L_n, \Psi_n\}$$
+Where:
+* $R_n$: Total Reserves (Locked Pi).
+* $S_n$: Total Supply (Minted REF).
+* $L_n$: External USD Liquidity Depth (Placeholder Oracle Input).
+* ${\Psi}_n$: Provenance Invariant (Hybrid Decay Model tracking Mined vs External Status).
+
+### 3.2. Deterministic State Transition Function ($f$)
+$${\Omega}_{n+1} = f({\Omega}_n, A_n)$$
+Where $A_n$ is the vector of user actions (Mint, Exit) in Epoch $n$. All state transitions are strictly governed by the algorithmic Justice Engine.
+
+## 4. The Justice Engine: Reflexive Liquidity Guardrail (${\Phi}$)
+The Core Vault Layer includes a non-linear, quadratic circuit breaker (${\Phi}$). It forces internal solvency by crushing incoming expansion when the external exit queue is crowded.
+
+$${\Phi} = calculatePhi(L_n, S_n / QWF)$$
+
+Production deployment requires hardening inputs via a **Decentralized Oracle Aggregation Mechanism (DOAM)**.
+
+## 5. Architectural Modularity and Governance Roadmap
+This standard embraces modular engineering for failsafe operations.
+
+### 5.1. Layer 1: Core Vault Invariants
+Defined in `/contracts/PiRC101Vault.sol` (EVM Reference). strictly enforces the State Transition Function.
+
+### 5.2. Layer 2: Dynamic WCF Weighting Engine
+treating weighting as a reflexive system that adapts to liquidity and behavioral signals, ingesting log(TVL) and Economic Velocity (Track C).
+
+### 5.3. Layer 3: Anti-Manipulation Layer (Track B)
+Specifies Proof-of-Utility (PoU) requirements, Reputation Scores (KYC), and Cluster Detection to prevent Wash-Trading before reward distribution.
+
+## 6. Implementation Roadmap
+Detailed Mainnet Enclosed to Open Mainnet rollout phases.
+
+## 7. Conclusion
+PiRC-101 achieves robust, engineering-validated convergence toward stability, even under extreme human panic.
+

docs/QUICKSTART_FOR_PI_CORE_TEAM.md

@@ -0,0 +1,8 @@
+# Quickstart Guide for Pi Core Team
+
+Welcome. To integrate **PiRC-101** into the Pi Network Mainnet transition within 14 days, follow these steps:
+
+1. **Automation**: Navigate to the "Actions" tab in this repo and run `One-Click Testnet Deployment`.
+2. **Verification**: Check `results/` for the latest Economic Solvency Report generated by `treasury_ai.py`.
+3. **Smart Contracts**: The core logic resides in `contracts/`. No modifications needed.
+4. **Parity**: The $2.248M USD anchor is enforced by the Justice Engine in `contracts/reward_engine.rs`.

docs/REFLEXIVE_PARITY.md

@@ -0,0 +1,22 @@
+PiRC-101: Reflexive Parity & Monetary Equilibrium Proofs
+1. Executive Summary
+This document formalizes the mathematical mechanisms that ensure the $REF (Reflexive Economic Fiat) maintains a stable 1 USD Purchasing Power Parity, neutralizing the risk of hyperinflation or "Feudal" economic extraction.
+2. The Parity Invariant
+To counter the critique of a "10,000,000:1 Absurdity," the protocol distinguishes between Market Price (P_{live}) and Systemic Capacity (C_{sys}). REF is not a speculative token; it is a Capacity Asset.
+The minting of REF is governed by the Minting Difficulty (D_m):
+ * Parity Goal: 1 \text{ REF} = 1 \text{ USD} of internal goods/services.
+ * Correction Mechanism: If S_{ref} exceeds the ecosystem's real-world absorption capacity, D_m increases algorithmically to stabilize the unit value.
+3. The \Phi (Phi) Stability Guardrail
+The "Justice Engine" prevents internal credit crashes by monitoring the Liquidity Density (L_{\rho}) of the ecosystem.
+ * Expansion Phase (\Phi \geq 1): The internal economy is growing; QWF is fully active.
+ * Contraction Phase (\Phi < 1): The protocol detects a "Liquidity Drain." It automatically collapses the QWF multiplier to protect the vault's solvency.
+4. Dynamic Multiplier Smoothing (DMS)
+To address the "Hereditary Privilege" concern, the QWF is no longer a static right but a Meritocratic Utility that decays based on inactivity or excessive velocity.
+The Effective Multiplier (QWF_{eff}) is calculated as:
+Where:
+ * \lambda: Systemic Decay Constant (Governance-tuned).
+ * t: Time elapsed since the last "Proof of Contribution" (Mining/Validator activity).
+5. Anti-Discrimination & Open Access
+While "Mined Pi" holders utilize their Reserved Capacity, external participants (Speculators) are converted into Liquidity Providers (LPs).
+ * External buyers pay the market premium to access the Zero-Volatility Garden.
+ * This creates a Positive-Sum Game: Speculators gain stability, while Pioneers gain a high-velocity trade environment.

docs/architecture.md

@@ -0,0 +1,37 @@
+PiRC Architecture
+
+1 Pioneer Supply Layer
+2 Liquidity Contribution Layer
+3 Transaction Activity Layer
+4 Fee Generation Layer
+5 Reward Distribution Engine
+System Architecture
+
+The ecosystem model is composed of three major layers.
+
+1. Network Layer
+
+Models user growth, adoption dynamics, and global participation.
+
+2. Utility Layer
+
+Represents application activity and service interactions:
+
+- App economy
+- Human work marketplaces
+- AI validation tasks
+
+3. Financial Layer
+
+Handles token flows:
+
+- Mining distribution
+- Staking and locking
+- Liquidity pools
+- Price equilibrium
+
+These layers interact to create an evolving digital economy.
+
+Users → Apps → Transactions
+Transactions → Liquidity → Price
+Price → Incentives → Network Growth

docs/dev-guide/integration.md

@@ -0,0 +1,25 @@
+# PiRC-101 Developer Integration Guide
+
+## Overview
+This guide provides the necessary guidelines for developers interacting with the **PiRC-101 Sovereign Vault Reference Model**.
+
+## ⚙️ Architectural Note: EVM Reference Model
+**Important:** Pi Network’s blockchain consensus does not natively execute Ethereum Virtual Machine (EVM) bytecode. The Solidity contract provided (`/contracts/PiRC101Vault.sol`) serves strictly as a **Turing-complete Economic Reference Model**.
+
+Deployment requires either:
+1.  **Porting to Soroban (Rust)** for native Stellar L1 deployment.
+2.  Execution on an **EVM-compatible Layer 2** sidechain anchored to Pi.
+
+## Contract Interface Guide (API Reference)
+API definitions for the Justice Engine flow.
+
+### `depositAndMint(uint256 _amount, uint8 _class)`
+Allows verified users (linked to established identity ERS-1/KYC hub) to lock external Pi and mint dynamic amounts of REF credits, subject to the Reflexive ${\Phi}$ Guardrail.
+
+### `conceptualizeWithdrawal(uint256 _refAmount, uint8 _class)`
+Burns internal REF credits and conceptually liquidates conceptual USD value from external reserves, subject to dynamic daily exit caps and unit consistent unit comparisons.
+
+## Oracle Integration Guidelines
+Production deployment requires integrating a reliable Decentralized Oracle Aggregation Mechanism to feed the $\Phi$ guardrail calculation:
+* **Pi Price Oracle:** Secure, manipulation-resistant USD value of Pi.
+* **Liquidity Depth Oracle:** Validating AMM TVL against clustering.

docs/economic_model.md

@@ -0,0 +1,22 @@
+Economic Model
+
+The economic model is based on the monetary identity:
+
+MV = PQ
+
+Where:
+
+M = circulating token supply
+V = velocity of money
+P = token price
+Q = transaction output
+
+Additional multipliers include:
+
+Network effect
+Utility demand
+Liquidity availability
+
+Price equilibrium is estimated as:
+
+price ≈ (demand / supply) × network_effect × liquidity_factor