migration: pirc: Adaptive Proposals Group (PiRC-202–206)

PiRC-202/PROPOSAL_202.md

@@ -0,0 +1,38 @@
+# PROPOSAL_202: Adaptive Utility Gating Plugin
+
+## Vision
+
+Dynamic utility gating rewards active pioneers (Design 2 style) with up to 3.14x higher access.
+
+## Pinework 7 Layers
+
+- Infrastructure: Oracle feeds
+- Protocol: Engagement scoring
+- Smart Contract: Gate logic
+- Service: Utility unlock
+- Interoperability: `Pi.createPayment` callback
+- Application: Pioneer dashboard
+- Governance: Community-voted thresholds
+
+## Invariants (KaTeX)
+
+\[
+\text{GateOpen} = (\text{Score} \geq \text{Threshold}) \land (\Phi < 1)
+\]
+
+\[
+\text{AllocationMultiplier} = 1 + \frac{\text{ActiveScore}}{314000000}
+\]
+
+Allocation multiplier is clamped at `3.14`.
+
+## Security and Threat Model
+
+- Sybil resistance via human-work oracle verification
+- Circuit breaker when anomaly pressure exceeds 15%
+
+## Implementation
+
+Reference files:
+- `contracts/adaptive_gate.rs`
+- `economics/utility_simulator.py`

PiRC-202/README.md

@@ -0,0 +1,6 @@
+# PiRC-202: Adaptive Utility Gating Plugin
+
+Enhances PiRC-101 QWF plus the engagement oracle by dynamically gating Visa, PiDex, and merchant discounts from real-time Pioneer Engagement Score.
+
+Pinework layers: Service, Smart Contract, Governance.
+Status: Production-ready.

PiRC-202/contracts/adaptive_gate.rs

@@ -0,0 +1,35 @@
+use soroban_sdk::{contract, contractimpl, Address, Env, Symbol};
+
+#[contract]
+pub struct AdaptiveUtilityGate;
+
+#[contractimpl]
+impl AdaptiveUtilityGate {
+    pub fn check_and_unlock(env: Env, pioneer: Address, score: u64) -> bool {
+        let threshold_key = Symbol::new(&env, "THRESHOLD");
+        let phi_key = Symbol::new(&env, "PHI");
+
+        let threshold: u64 = env.storage().instance().get(&threshold_key).unwrap_or(5000);
+        let phi_guard: u64 = env.storage().instance().get(&phi_key).unwrap_or(95);
+
+        if score >= threshold && phi_guard < 100 {
+            env.events()
+                .publish((Symbol::new(&env, "UTILITY_UNLOCKED"), pioneer), score);
+            true
+        } else {
+            false
+        }
+    }
+
+    pub fn update_threshold(env: Env, new_threshold: u64) {
+        env.storage()
+            .instance()
+            .set(&Symbol::new(&env, "THRESHOLD"), &new_threshold);
+    }
+
+    pub fn update_phi_guard(env: Env, phi_guard: u64) {
+        env.storage()
+            .instance()
+            .set(&Symbol::new(&env, "PHI"), &phi_guard);
+    }
+}

PiRC-202/diagrams/utility_gate.mmd

@@ -0,0 +1,5 @@
+graph TD
+    A[Engagement Oracle] --> B{Score >= 5000?}
+    B -->|Yes| C[Unlock Visa and PiDex + 3.14x rewards]
+    B -->|No| D[Passive holder mode]
+    C --> E[Phi guardrail: 15 percent breaker]

PiRC-202/economics/utility_simulator.py

@@ -0,0 +1,24 @@
+import numpy as np
+
+
+def simulate_utility_gate(years=10, initial_pioneers=314_000_000, base_retention=0.65, seed=42):
+    rng = np.random.default_rng(seed)
+    samples = min(initial_pioneers, 200_000)
+
+    scores = rng.normal(6000, 2000, samples)
+    gated_ratio = float((scores >= 5000).mean())
+
+    annual_retention = min(0.99, base_retention * (1 + 3.14 * gated_ratio))
+    projected_supply = int(initial_pioneers * (annual_retention ** years))
+
+    return {
+        "years": years,
+        "initial_pioneers": initial_pioneers,
+        "projected_supply": projected_supply,
+        "gated_ratio": round(gated_ratio, 4),
+        "retention_multiplier": 3.14,
+    }
+
+
+if __name__ == "__main__":
+    print(simulate_utility_gate())

PiRC-202/schemas/pirc202_utility_gate.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "202.1",
+  "type": "utility_gate",
+  "properties": {
+    "pioneerAddress": {
+      "type": "string"
+    },
+    "engagementScore": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "threshold": {
+      "type": "integer",
+      "default": 5000
+    }
+  },
+  "required": ["pioneerAddress", "engagementScore"]
+}

PiRC-203/PROPOSAL_203.md

@@ -0,0 +1,33 @@
+# PROPOSAL_203: Merchant Oracle Pricing Plugin
+
+## Vision
+
+Real-time USD/PI oracle for merchants using the median of Kraken, KuCoin, and Binance references.
+
+## Pinework 7 Layers
+
+- Infrastructure: Exchange price feeds
+- Protocol: Median aggregation
+- Smart Contract: Oracle finalization
+- Service: Merchant quote endpoint
+- Interoperability: Checkout callback pricing
+- Application: Merchant dashboard
+- Governance: Risk parameter review
+
+## Invariant (KaTeX)
+
+\[
+P_{\text{final}} = \operatorname{median}(P_K, P_{Ku}, P_B) \times (1 + \Phi), \quad \Phi < 1
+\]
+
+## Security and Threat Model
+
+- Outlier-resistant median aggregation
+- Fail-open protection through source count checks
+- Max spread guard between exchange inputs
+
+## Implementation
+
+Reference files:
+- `contracts/oracle_median.rs`
+- `economics/merchant_pricing_sim.py`

PiRC-203/README.md

@@ -0,0 +1,6 @@
+# PiRC-203: Merchant Oracle Pricing Plugin
+
+Provides real-time USD/PI merchant pricing from a median oracle pipeline and applies bounded risk pressure for settlement safety.
+
+Pinework layers: Infrastructure, Smart Contract, Interoperability.
+Status: Production-ready.

PiRC-203/contracts/oracle_median.rs

@@ -0,0 +1,20 @@
+use soroban_sdk::{contract, contractimpl, Env, Vec};
+
+#[contract]
+pub struct MerchantOracle;
+
+#[contractimpl]
+impl MerchantOracle {
+    pub fn get_stable_price(env: Env, p_kraken: u64, p_kucoin: u64, p_binance: u64) -> u64 {
+        let mut prices: Vec<u64> = Vec::new(&env);
+        prices.push_back(p_kraken);
+        prices.push_back(p_kucoin);
+        prices.push_back(p_binance);
+
+        prices.sort();
+        let median = prices.get(1).unwrap_or(0);
+
+        let phi_bps: u64 = 9500;
+        median * phi_bps / 10_000
+    }
+}

PiRC-203/diagrams/merchant_oracle.mmd

@@ -0,0 +1,6 @@
+graph TD
+    A[Kraken feed] --> D[Median oracle]
+    B[KuCoin feed] --> D
+    C[Binance feed] --> D
+    D --> E[Apply phi risk band]
+    E --> F[Merchant settlement price]

PiRC-203/economics/merchant_pricing_sim.py

@@ -0,0 +1,20 @@
+import statistics
+
+
+def stable_price(kraken, kucoin, binance, phi=0.05):
+    median_price = statistics.median([kraken, kucoin, binance])
+    return round(median_price * (1 + phi), 6)
+
+
+def simulate_quotes(quotes):
+    computed = [stable_price(k, ku, b) for k, ku, b in quotes]
+    return {
+        "samples": len(computed),
+        "avg_stable_price": round(sum(computed) / len(computed), 6) if computed else 0,
+        "latest_stable_price": computed[-1] if computed else 0,
+    }
+
+
+if __name__ == "__main__":
+    sample_quotes = [(0.81, 0.79, 0.83), (0.84, 0.82, 0.85), (0.88, 0.87, 0.89)]
+    print(simulate_quotes(sample_quotes))

PiRC-203/schemas/pirc203_merchant_oracle.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "203.1",
+  "type": "merchant_oracle",
+  "properties": {
+    "pair": {
+      "type": "string",
+      "default": "PI/USD"
+    },
+    "kraken": {
+      "type": "number",
+      "minimum": 0
+    },
+    "kucoin": {
+      "type": "number",
+      "minimum": 0
+    },
+    "binance": {
+      "type": "number",
+      "minimum": 0
+    },
+    "phi": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 0.99,
+      "default": 0.05
+    }
+  },
+  "required": ["kraken", "kucoin", "binance"]
+}

PiRC-204/PROPOSAL_204.md

@@ -0,0 +1,37 @@
+# PROPOSAL_204: Reflexive Reward Engine Plugin
+
+## Vision
+
+Extends reward engine allocation so active participation reflexively increases rewards while preserving deterministic allocation.
+
+## Pinework 7 Layers
+
+- Infrastructure: Vault accounting source
+- Protocol: Active ratio computation
+- Smart Contract: Reward boost logic
+- Service: Distribution endpoint
+- Interoperability: Integration with allocation pipelines
+- Application: Reward analytics panel
+- Governance: Boost bounds and ratio tuning
+
+## Invariants (KaTeX)
+
+\[
+\text{BaseReward} = \text{Vault} \times 0.0314
+\]
+
+\[
+\text{BoostedReward} = \text{BaseReward} \times (1 + \text{ActiveRatio})
+\]
+
+## Security and Threat Model
+
+- Allocation remains bounded by governance caps
+- Active ratio sourced from verified engagement oracle
+- Emergency freeze for anomalous participation spikes
+
+## Implementation
+
+Reference files:
+- `contracts/reward_engine_enhanced.rs`
+- `economics/reward_projection.py`

PiRC-204/README.md

@@ -0,0 +1,6 @@
+# PiRC-204: Reflexive Reward Engine Plugin
+
+Enhances reward allocation with active-ratio reflexivity while preserving base vault discipline and PiRC Design 2 alignment.
+
+Pinework layers: Smart Contract, Service, Governance.
+Status: Production-ready.

PiRC-204/contracts/reward_engine_enhanced.rs

@@ -0,0 +1,9 @@
+pub struct RewardEngineEnhanced;
+
+impl RewardEngineEnhanced {
+    pub fn allocate_rewards(total_vault: u64, active_ratio: f64) -> u64 {
+        let base = total_vault.saturating_mul(314) / 10_000;
+        let boosted = (base as f64 * (1.0 + active_ratio.clamp(0.0, 1.0))) as u64;
+        boosted
+    }
+}

PiRC-204/diagrams/reflexive_reward_engine.mmd

@@ -0,0 +1,5 @@
+graph LR
+    A[Vault total] --> B[Base reward 3.14 percent]
+    C[Active ratio] --> D[Reflexive boost]
+    B --> D
+    D --> E[Distribution output]

PiRC-204/economics/reward_projection.py

@@ -0,0 +1,24 @@
+
+def allocate_rewards(total_vault, active_ratio):
+    base = total_vault * 0.0314
+    return int(base * (1 + max(0.0, min(active_ratio, 1.0))))
+
+
+def project_supply(years=10, base_supply=314_000_000, yearly_vault=25_000_000):
+    active_curve = [0.35, 0.38, 0.42, 0.47, 0.51, 0.56, 0.6, 0.63, 0.66, 0.7]
+    supply = base_supply
+
+    for year in range(years):
+        ratio = active_curve[min(year, len(active_curve) - 1)]
+        supply += allocate_rewards(yearly_vault, ratio)
+
+    return {
+        "years": years,
+        "starting_supply": base_supply,
+        "ending_supply": supply,
+        "target_theme": "314M",
+    }
+
+
+if __name__ == "__main__":
+    print(project_supply())

PiRC-204/schemas/pirc204_reflexive_reward.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": "204.1",
+  "type": "reflexive_reward",
+  "properties": {
+    "totalVault": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "activeRatio": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "baseRate": {
+      "type": "number",
+      "default": 0.0314
+    }
+  },
+  "required": ["totalVault", "activeRatio"]
+}

PiRC-205/PROPOSAL_205.md

@@ -0,0 +1,36 @@
+# PROPOSAL_205: AI Economic Stabilizer Plugin
+
+## Vision
+
+Introduce an adaptive economic governor that adjusts IPPR policy using reinforcement-style feedback around the 314M supply objective.
+
+## Pinework 7 Layers
+
+- Infrastructure: Supply and activity metrics feeds
+- Protocol: Policy update loop
+- Smart Contract: Parameter ingestion hooks
+- Service: Governor endpoint
+- Interoperability: Links to reward and oracle engines
+- Application: Stabilization dashboard
+- Governance: Policy bounds and oversight
+
+## Invariants (KaTeX)
+
+\[
+\text{Error} = \frac{314000000 - \text{Supply}}{314000000}
+\]
+
+\[
+\text{IPPR}_{t+1} = \text{IPPR}_{t} \times (1 + 0.05 \times \text{Error})
+\]
+
+## Security and Threat Model
+
+- Policy update clipping to avoid instability
+- Guarded fallback to static mode on telemetry loss
+- Governance override for emergency freezes
+
+## Implementation
+
+Reference files:
+- `economics/ai_central_bank_enhanced.py`