From b2f61a85e7953370d319fc2dfd6368d8ea326c96 Mon Sep 17 00:00:00 2001
From: N-010 <chelsig96@gmail.com>
Date: Mon, 17 Nov 2025 19:58:19 +0300
Subject: [PATCH 01/10] Create 2025-11-04-QThirtyFour.md

---
 .../feature/2025-11-04-QThirtyFour.md         | 147 ++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 SmartContracts/feature/2025-11-04-QThirtyFour.md

diff --git a/SmartContracts/feature/2025-11-04-QThirtyFour.md b/SmartContracts/feature/2025-11-04-QThirtyFour.md
new file mode 100644
index 0000000..2ccbed4
--- /dev/null
+++ b/SmartContracts/feature/2025-11-04-QThirtyFour.md
@@ -0,0 +1,147 @@
+# Proposal: “4-of-30” Lottery — Final Specification with Adaptive Fast-Recovery
+
+## 1. Purpose and Scope
+
+This document defines the business, economic, and operational parameters of the on-chain lottery “4-of-30.” It establishes:
+
+* Prize structure and minimum payouts;
+* Revenue allocation and reserve policy;
+* An adaptive Fast-Recovery (FR) regime that accelerates jackpot rebuild to a configurable target (“Target Carry”) at high ticket volumes;
+* Shareholder remuneration from the Distribution component;
+* Machine-readable configuration for implementation in the smart contract (SC).
+
+---
+
+## 2. Product Overview
+
+**Game format.** A player selects 4 unique numbers from 30.
+**Prize tiers.** k=2, k=3, k=4 (jackpot).
+**Jackpot.** The jackpot (carry) is a separate, accumulating balance. Upon a k=4 win, the winner receives **100% of the current jackpot**. Jackpot replenishment is automatic per Sections 5–7.
+
+---
+
+## 3. Revenue Allocation (per round)
+
+Let ticket price be (P). Let (N) denote tickets sold in the round, and (R = N \cdot P).
+
+* **Winners (k=2/k=3)**: 68% of (R)
+* **Distribution (partners/shareholders)**: 20% of (R) —**shareholder income of the RL smart contract**
+* **Dev**: 10% of (R)
+* **Burn**: 2% of (R)
+
+The jackpot (k=4) is **not** funded from the 68% winners pool; it grows via FR redirects and overflow as defined below.
+
+> Note: During FR, a **temporary** fraction of Distribution may be redirected to the jackpot (per “Financial Mechanics During FR”); once FR is OFF, Distribution returns to the **full 20% of (R)** for RL shareholders.
+
+---
+
+## 4. Minimum Payout Floors
+
+* **k=2 floor:** ≥ 0.5 × (P) per winner.
+* **k=3 floor:** ≥ 5 × (P) per winner.
+  If a tier pool is insufficient, top-ups may be sourced from **Reserve.General**, subject to safety limits: ≤ 10% of total reserve per round; ≤ 25 × (P) per winner; soft floor of reserve equivalent to 20 × (P).
+
+---
+
+## 5. Reserves and Overflow
+
+* **Overflow.** Any unawarded amount within k=2/k=3 after payouts is overflow. Overflow is split between **Reserve** and **Jackpot (carry)** with mode-dependent coefficients (baseline vs FR).
+* **Reserve buckets.**
+
+  * **Reserve.General:** used to meet payout floors;
+  * **Reserve.JackpotRebuild:** used to reseed jackpot after k=4 wins up to the configured target (subject to availability).
+* **Safety limits.** As defined in Section 4.
+
+---
+
+## 6. Target Carry and Jackpot Reseed
+
+* **Target Carry** is configurable (e.g., 0.5B, 1B, 2B qu).
+* After a k=4 payout, the SC may reseed the jackpot from **Reserve.JackpotRebuild** up to Target Carry (or available balance if lower). The remainder is rebuilt through FR and overflow per Sections 7–8.
+
+---
+
+## 7. Adaptive Fast-Recovery (FR)
+
+**Objective.** When ticket volume is high, FR temporarily accelerates jackpot growth so that the jackpot is expected to reach Target Carry **not later** than the next average k=4 occurrence.
+
+**Adaptive trigger.** Each round, the SC evaluates:
+
+1. the remaining gap to Target Carry;
+2. the expected growth rate of the jackpot under FR;
+3. the expected number of rounds before the next average k=4 (as a function of (N)).
+
+**Activation rule.** If, at current (N), the expected FR-driven growth over the expected time to next k=4 is sufficient to close the gap, **FR=ON**.
+Additionally, within a **post-k4 window** (default 50 rounds), FR may activate under looser conditions to support early rebuild.
+
+**Deactivation rule (hysteresis).** If the jackpot is at or above Target Carry for **3 consecutive rounds**, **FR=OFF**.
+
+---
+
+## 8. Financial Mechanics During FR
+
+While FR=ON, a small, **equal** temporary redirect from Dev and Distribution augments the jackpot, complemented by a minor temporary contribution from k=3 and an overflow bias to carry. Players face no additional fees.
+
+**8.1 Equal redirects (Dev/Distribution).**
+
+* **Dev redirect:** `dev_redirect_pp = 1.0% of R` → jackpot (carry).
+* **Distribution redirect:** `dist_redirect_pp = 1.0% of R` → jackpot (carry).
+* **High-load supplement (optional):** If (N \geq 1000), add `dev_redirect_extra_pp = 0.35% of R` and `dist_redirect_extra_pp = 0.35% of R` (total +0.7% of R into carry).
+
+**8.2 Temporary k=3 contribution (recovery-rake).**
+
+* `winners_rake_of_winners_total_fr = 5%` of the 68% winners block is redirected to carry **from k=3 only**.
+* The remaining winners block (`win_eff`) is split with a slight tilt toward k=2 for stability during FR: **k=3 = 35% of `win_eff`**, **k=2 = 65% of `win_eff`**. Floors remain intact.
+
+**8.3 Overflow bias under FR.**
+
+* `alpha_when_active = 0.05`, i.e., **95% of tier overflow → carry**, **5% → reserve**.
+
+**8.4 Post-FR reversion.**
+
+* When FR turns OFF, Dev and Distribution return to 10%/20% of (R) (no redirect), winners split reverts to baseline, and overflow split reverts to baseline policy.
+
+---
+
+## 9. Shareholder Remuneration (Distribution)
+
+* **Source.** The Distribution block (20% of (R)).
+* **FR effect.** During FR, the `dist_redirect_pp [ + dist_redirect_extra_pp ]` portion is temporarily routed to carry; once FR is OFF, Distribution returns to the full 20% of (R).
+
+---
+
+## 10. Parameters (Defaults and Governance Ranges)
+
+* **Target Carry:** 1,000,000,000 qu (governable).
+* **post_k4_window_rounds:** 50 (range: 20–80).
+* **hysteresis_rounds_at_or_above_target:** 3 (range: 2–5).
+* **dev_redirect_pp:** 0.01 (range: 0.005–0.02).
+* **dist_redirect_pp:** 0.01 (range: 0.005–0.02).
+* **high_load_redirect_extra (N≥1000):** dev=0.0035, dist=0.0035 (each; range: 0.0025–0.005).
+* **winners_rake_of_winners_total_fr:** 0.05 (range: 0.03–0.08).
+* **tiers_pool_shares_fr (of `win_eff`):** k3=0.35, k2=0.65 (sum=1.0).
+* **alpha_when_active:** 0.05 (range: 0.03–0.20).
+* **Reserve safety limits:** per Sections 4–5.
+
+---
+
+## 11. Operational Order of Settlement (Per Round, High Level)
+
+1. Compute baseline blocks: **Dev 10%**, **Distribution 20%**, **Burn 2%**, **Winners 68%**.
+2. If **FR=ON**:
+
+   * Redirect `dev_redirect_pp * R [ + dev_redirect_extra_pp * R ]` to carry (reducing Dev by the same amount);
+   * Redirect `dist_redirect_pp * R [ + dist_redirect_extra_pp * R ]` to carry (reducing Distribution by the same amount);
+   * From Winners, redirect `winners_rake_of_winners_total_fr` (5% of 68% (R)) to carry from k=3;
+   * Split `win_eff` as `{k3:35%, k2:65%}`; apply floors;
+   * Split overflow with `alpha_when_active=0.05` (95% → carry, 5% → reserve).
+3. If **k=4** occurs: pay **100% of carry** to winner(s); then optionally reseed from **Reserve.JackpotRebuild** up to Target Carry (subject to availability).
+4. If **FR OFF**: apply baseline tier shares and baseline overflow split.
+
+---
+
+## 15. Summary
+
+This specification delivers a transparent “4-of-30” lottery with strict 100% jackpot payout and a principled, adaptive FR mechanism. FR leverages temporary, equal redirects from Dev and Distribution, a modest k=3 contribution, and an FR-biased overflow to restore the jackpot to Target Carry at scale, while preserving player fairness, shareholder remuneration, and operational discipline.
+
+**Distribution (20% of (R)) constitutes RL smart-contract shareholder income**; during FR, a small portion is temporarily redirected to the jackpot and then fully restored to shareholders once FR is OFF.

From f22899a3218376d2791607d5f277c27285f5abd5 Mon Sep 17 00:00:00 2001
From: N-010 <chelsig96@gmail.com>
Date: Tue, 25 Nov 2025 14:51:22 +0300
Subject: [PATCH 02/10] Create 2025-11-04-QThirtyFour.md

---
 SmartContracts/2025-11-04-QThirtyFour.md | 147 +++++++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 SmartContracts/2025-11-04-QThirtyFour.md

diff --git a/SmartContracts/2025-11-04-QThirtyFour.md b/SmartContracts/2025-11-04-QThirtyFour.md
new file mode 100644
index 0000000..2ccbed4
--- /dev/null
+++ b/SmartContracts/2025-11-04-QThirtyFour.md
@@ -0,0 +1,147 @@
+# Proposal: “4-of-30” Lottery — Final Specification with Adaptive Fast-Recovery
+
+## 1. Purpose and Scope
+
+This document defines the business, economic, and operational parameters of the on-chain lottery “4-of-30.” It establishes:
+
+* Prize structure and minimum payouts;
+* Revenue allocation and reserve policy;
+* An adaptive Fast-Recovery (FR) regime that accelerates jackpot rebuild to a configurable target (“Target Carry”) at high ticket volumes;
+* Shareholder remuneration from the Distribution component;
+* Machine-readable configuration for implementation in the smart contract (SC).
+
+---
+
+## 2. Product Overview
+
+**Game format.** A player selects 4 unique numbers from 30.
+**Prize tiers.** k=2, k=3, k=4 (jackpot).
+**Jackpot.** The jackpot (carry) is a separate, accumulating balance. Upon a k=4 win, the winner receives **100% of the current jackpot**. Jackpot replenishment is automatic per Sections 5–7.
+
+---
+
+## 3. Revenue Allocation (per round)
+
+Let ticket price be (P). Let (N) denote tickets sold in the round, and (R = N \cdot P).
+
+* **Winners (k=2/k=3)**: 68% of (R)
+* **Distribution (partners/shareholders)**: 20% of (R) —**shareholder income of the RL smart contract**
+* **Dev**: 10% of (R)
+* **Burn**: 2% of (R)
+
+The jackpot (k=4) is **not** funded from the 68% winners pool; it grows via FR redirects and overflow as defined below.
+
+> Note: During FR, a **temporary** fraction of Distribution may be redirected to the jackpot (per “Financial Mechanics During FR”); once FR is OFF, Distribution returns to the **full 20% of (R)** for RL shareholders.
+
+---
+
+## 4. Minimum Payout Floors
+
+* **k=2 floor:** ≥ 0.5 × (P) per winner.
+* **k=3 floor:** ≥ 5 × (P) per winner.
+  If a tier pool is insufficient, top-ups may be sourced from **Reserve.General**, subject to safety limits: ≤ 10% of total reserve per round; ≤ 25 × (P) per winner; soft floor of reserve equivalent to 20 × (P).
+
+---
+
+## 5. Reserves and Overflow
+
+* **Overflow.** Any unawarded amount within k=2/k=3 after payouts is overflow. Overflow is split between **Reserve** and **Jackpot (carry)** with mode-dependent coefficients (baseline vs FR).
+* **Reserve buckets.**
+
+  * **Reserve.General:** used to meet payout floors;
+  * **Reserve.JackpotRebuild:** used to reseed jackpot after k=4 wins up to the configured target (subject to availability).
+* **Safety limits.** As defined in Section 4.
+
+---
+
+## 6. Target Carry and Jackpot Reseed
+
+* **Target Carry** is configurable (e.g., 0.5B, 1B, 2B qu).
+* After a k=4 payout, the SC may reseed the jackpot from **Reserve.JackpotRebuild** up to Target Carry (or available balance if lower). The remainder is rebuilt through FR and overflow per Sections 7–8.
+
+---
+
+## 7. Adaptive Fast-Recovery (FR)
+
+**Objective.** When ticket volume is high, FR temporarily accelerates jackpot growth so that the jackpot is expected to reach Target Carry **not later** than the next average k=4 occurrence.
+
+**Adaptive trigger.** Each round, the SC evaluates:
+
+1. the remaining gap to Target Carry;
+2. the expected growth rate of the jackpot under FR;
+3. the expected number of rounds before the next average k=4 (as a function of (N)).
+
+**Activation rule.** If, at current (N), the expected FR-driven growth over the expected time to next k=4 is sufficient to close the gap, **FR=ON**.
+Additionally, within a **post-k4 window** (default 50 rounds), FR may activate under looser conditions to support early rebuild.
+
+**Deactivation rule (hysteresis).** If the jackpot is at or above Target Carry for **3 consecutive rounds**, **FR=OFF**.
+
+---
+
+## 8. Financial Mechanics During FR
+
+While FR=ON, a small, **equal** temporary redirect from Dev and Distribution augments the jackpot, complemented by a minor temporary contribution from k=3 and an overflow bias to carry. Players face no additional fees.
+
+**8.1 Equal redirects (Dev/Distribution).**
+
+* **Dev redirect:** `dev_redirect_pp = 1.0% of R` → jackpot (carry).
+* **Distribution redirect:** `dist_redirect_pp = 1.0% of R` → jackpot (carry).
+* **High-load supplement (optional):** If (N \geq 1000), add `dev_redirect_extra_pp = 0.35% of R` and `dist_redirect_extra_pp = 0.35% of R` (total +0.7% of R into carry).
+
+**8.2 Temporary k=3 contribution (recovery-rake).**
+
+* `winners_rake_of_winners_total_fr = 5%` of the 68% winners block is redirected to carry **from k=3 only**.
+* The remaining winners block (`win_eff`) is split with a slight tilt toward k=2 for stability during FR: **k=3 = 35% of `win_eff`**, **k=2 = 65% of `win_eff`**. Floors remain intact.
+
+**8.3 Overflow bias under FR.**
+
+* `alpha_when_active = 0.05`, i.e., **95% of tier overflow → carry**, **5% → reserve**.
+
+**8.4 Post-FR reversion.**
+
+* When FR turns OFF, Dev and Distribution return to 10%/20% of (R) (no redirect), winners split reverts to baseline, and overflow split reverts to baseline policy.
+
+---
+
+## 9. Shareholder Remuneration (Distribution)
+
+* **Source.** The Distribution block (20% of (R)).
+* **FR effect.** During FR, the `dist_redirect_pp [ + dist_redirect_extra_pp ]` portion is temporarily routed to carry; once FR is OFF, Distribution returns to the full 20% of (R).
+
+---
+
+## 10. Parameters (Defaults and Governance Ranges)
+
+* **Target Carry:** 1,000,000,000 qu (governable).
+* **post_k4_window_rounds:** 50 (range: 20–80).
+* **hysteresis_rounds_at_or_above_target:** 3 (range: 2–5).
+* **dev_redirect_pp:** 0.01 (range: 0.005–0.02).
+* **dist_redirect_pp:** 0.01 (range: 0.005–0.02).
+* **high_load_redirect_extra (N≥1000):** dev=0.0035, dist=0.0035 (each; range: 0.0025–0.005).
+* **winners_rake_of_winners_total_fr:** 0.05 (range: 0.03–0.08).
+* **tiers_pool_shares_fr (of `win_eff`):** k3=0.35, k2=0.65 (sum=1.0).
+* **alpha_when_active:** 0.05 (range: 0.03–0.20).
+* **Reserve safety limits:** per Sections 4–5.
+
+---
+
+## 11. Operational Order of Settlement (Per Round, High Level)
+
+1. Compute baseline blocks: **Dev 10%**, **Distribution 20%**, **Burn 2%**, **Winners 68%**.
+2. If **FR=ON**:
+
+   * Redirect `dev_redirect_pp * R [ + dev_redirect_extra_pp * R ]` to carry (reducing Dev by the same amount);
+   * Redirect `dist_redirect_pp * R [ + dist_redirect_extra_pp * R ]` to carry (reducing Distribution by the same amount);
+   * From Winners, redirect `winners_rake_of_winners_total_fr` (5% of 68% (R)) to carry from k=3;
+   * Split `win_eff` as `{k3:35%, k2:65%}`; apply floors;
+   * Split overflow with `alpha_when_active=0.05` (95% → carry, 5% → reserve).
+3. If **k=4** occurs: pay **100% of carry** to winner(s); then optionally reseed from **Reserve.JackpotRebuild** up to Target Carry (subject to availability).
+4. If **FR OFF**: apply baseline tier shares and baseline overflow split.
+
+---
+
+## 15. Summary
+
+This specification delivers a transparent “4-of-30” lottery with strict 100% jackpot payout and a principled, adaptive FR mechanism. FR leverages temporary, equal redirects from Dev and Distribution, a modest k=3 contribution, and an FR-biased overflow to restore the jackpot to Target Carry at scale, while preserving player fairness, shareholder remuneration, and operational discipline.
+
+**Distribution (20% of (R)) constitutes RL smart-contract shareholder income**; during FR, a small portion is temporarily redirected to the jackpot and then fully restored to shareholders once FR is OFF.

From c26b089d5326fb6632d4e8bd38dd4043f0ffd486 Mon Sep 17 00:00:00 2001
From: N-010 <chelsig96@gmail.com>
Date: Tue, 25 Nov 2025 14:51:40 +0300
Subject: [PATCH 03/10] Delete SmartContracts/feature directory

---
 .../feature/2025-11-04-QThirtyFour.md         | 147 ------------------
 1 file changed, 147 deletions(-)
 delete mode 100644 SmartContracts/feature/2025-11-04-QThirtyFour.md

diff --git a/SmartContracts/feature/2025-11-04-QThirtyFour.md b/SmartContracts/feature/2025-11-04-QThirtyFour.md
deleted file mode 100644
index 2ccbed4..0000000
--- a/SmartContracts/feature/2025-11-04-QThirtyFour.md
+++ /dev/null
@@ -1,147 +0,0 @@
-# Proposal: “4-of-30” Lottery — Final Specification with Adaptive Fast-Recovery
-
-## 1. Purpose and Scope
-
-This document defines the business, economic, and operational parameters of the on-chain lottery “4-of-30.” It establishes:
-
-* Prize structure and minimum payouts;
-* Revenue allocation and reserve policy;
-* An adaptive Fast-Recovery (FR) regime that accelerates jackpot rebuild to a configurable target (“Target Carry”) at high ticket volumes;
-* Shareholder remuneration from the Distribution component;
-* Machine-readable configuration for implementation in the smart contract (SC).
-
----
-
-## 2. Product Overview
-
-**Game format.** A player selects 4 unique numbers from 30.
-**Prize tiers.** k=2, k=3, k=4 (jackpot).
-**Jackpot.** The jackpot (carry) is a separate, accumulating balance. Upon a k=4 win, the winner receives **100% of the current jackpot**. Jackpot replenishment is automatic per Sections 5–7.
-
----
-
-## 3. Revenue Allocation (per round)
-
-Let ticket price be (P). Let (N) denote tickets sold in the round, and (R = N \cdot P).
-
-* **Winners (k=2/k=3)**: 68% of (R)
-* **Distribution (partners/shareholders)**: 20% of (R) —**shareholder income of the RL smart contract**
-* **Dev**: 10% of (R)
-* **Burn**: 2% of (R)
-
-The jackpot (k=4) is **not** funded from the 68% winners pool; it grows via FR redirects and overflow as defined below.
-
-> Note: During FR, a **temporary** fraction of Distribution may be redirected to the jackpot (per “Financial Mechanics During FR”); once FR is OFF, Distribution returns to the **full 20% of (R)** for RL shareholders.
-
----
-
-## 4. Minimum Payout Floors
-
-* **k=2 floor:** ≥ 0.5 × (P) per winner.
-* **k=3 floor:** ≥ 5 × (P) per winner.
-  If a tier pool is insufficient, top-ups may be sourced from **Reserve.General**, subject to safety limits: ≤ 10% of total reserve per round; ≤ 25 × (P) per winner; soft floor of reserve equivalent to 20 × (P).
-
----
-
-## 5. Reserves and Overflow
-
-* **Overflow.** Any unawarded amount within k=2/k=3 after payouts is overflow. Overflow is split between **Reserve** and **Jackpot (carry)** with mode-dependent coefficients (baseline vs FR).
-* **Reserve buckets.**
-
-  * **Reserve.General:** used to meet payout floors;
-  * **Reserve.JackpotRebuild:** used to reseed jackpot after k=4 wins up to the configured target (subject to availability).
-* **Safety limits.** As defined in Section 4.
-
----
-
-## 6. Target Carry and Jackpot Reseed
-
-* **Target Carry** is configurable (e.g., 0.5B, 1B, 2B qu).
-* After a k=4 payout, the SC may reseed the jackpot from **Reserve.JackpotRebuild** up to Target Carry (or available balance if lower). The remainder is rebuilt through FR and overflow per Sections 7–8.
-
----
-
-## 7. Adaptive Fast-Recovery (FR)
-
-**Objective.** When ticket volume is high, FR temporarily accelerates jackpot growth so that the jackpot is expected to reach Target Carry **not later** than the next average k=4 occurrence.
-
-**Adaptive trigger.** Each round, the SC evaluates:
-
-1. the remaining gap to Target Carry;
-2. the expected growth rate of the jackpot under FR;
-3. the expected number of rounds before the next average k=4 (as a function of (N)).
-
-**Activation rule.** If, at current (N), the expected FR-driven growth over the expected time to next k=4 is sufficient to close the gap, **FR=ON**.
-Additionally, within a **post-k4 window** (default 50 rounds), FR may activate under looser conditions to support early rebuild.
-
-**Deactivation rule (hysteresis).** If the jackpot is at or above Target Carry for **3 consecutive rounds**, **FR=OFF**.
-
----
-
-## 8. Financial Mechanics During FR
-
-While FR=ON, a small, **equal** temporary redirect from Dev and Distribution augments the jackpot, complemented by a minor temporary contribution from k=3 and an overflow bias to carry. Players face no additional fees.
-
-**8.1 Equal redirects (Dev/Distribution).**
-
-* **Dev redirect:** `dev_redirect_pp = 1.0% of R` → jackpot (carry).
-* **Distribution redirect:** `dist_redirect_pp = 1.0% of R` → jackpot (carry).
-* **High-load supplement (optional):** If (N \geq 1000), add `dev_redirect_extra_pp = 0.35% of R` and `dist_redirect_extra_pp = 0.35% of R` (total +0.7% of R into carry).
-
-**8.2 Temporary k=3 contribution (recovery-rake).**
-
-* `winners_rake_of_winners_total_fr = 5%` of the 68% winners block is redirected to carry **from k=3 only**.
-* The remaining winners block (`win_eff`) is split with a slight tilt toward k=2 for stability during FR: **k=3 = 35% of `win_eff`**, **k=2 = 65% of `win_eff`**. Floors remain intact.
-
-**8.3 Overflow bias under FR.**
-
-* `alpha_when_active = 0.05`, i.e., **95% of tier overflow → carry**, **5% → reserve**.
-
-**8.4 Post-FR reversion.**
-
-* When FR turns OFF, Dev and Distribution return to 10%/20% of (R) (no redirect), winners split reverts to baseline, and overflow split reverts to baseline policy.
-
----
-
-## 9. Shareholder Remuneration (Distribution)
-
-* **Source.** The Distribution block (20% of (R)).
-* **FR effect.** During FR, the `dist_redirect_pp [ + dist_redirect_extra_pp ]` portion is temporarily routed to carry; once FR is OFF, Distribution returns to the full 20% of (R).
-
----
-
-## 10. Parameters (Defaults and Governance Ranges)
-
-* **Target Carry:** 1,000,000,000 qu (governable).
-* **post_k4_window_rounds:** 50 (range: 20–80).
-* **hysteresis_rounds_at_or_above_target:** 3 (range: 2–5).
-* **dev_redirect_pp:** 0.01 (range: 0.005–0.02).
-* **dist_redirect_pp:** 0.01 (range: 0.005–0.02).
-* **high_load_redirect_extra (N≥1000):** dev=0.0035, dist=0.0035 (each; range: 0.0025–0.005).
-* **winners_rake_of_winners_total_fr:** 0.05 (range: 0.03–0.08).
-* **tiers_pool_shares_fr (of `win_eff`):** k3=0.35, k2=0.65 (sum=1.0).
-* **alpha_when_active:** 0.05 (range: 0.03–0.20).
-* **Reserve safety limits:** per Sections 4–5.
-
----
-
-## 11. Operational Order of Settlement (Per Round, High Level)
-
-1. Compute baseline blocks: **Dev 10%**, **Distribution 20%**, **Burn 2%**, **Winners 68%**.
-2. If **FR=ON**:
-
-   * Redirect `dev_redirect_pp * R [ + dev_redirect_extra_pp * R ]` to carry (reducing Dev by the same amount);
-   * Redirect `dist_redirect_pp * R [ + dist_redirect_extra_pp * R ]` to carry (reducing Distribution by the same amount);
-   * From Winners, redirect `winners_rake_of_winners_total_fr` (5% of 68% (R)) to carry from k=3;
-   * Split `win_eff` as `{k3:35%, k2:65%}`; apply floors;
-   * Split overflow with `alpha_when_active=0.05` (95% → carry, 5% → reserve).
-3. If **k=4** occurs: pay **100% of carry** to winner(s); then optionally reseed from **Reserve.JackpotRebuild** up to Target Carry (subject to availability).
-4. If **FR OFF**: apply baseline tier shares and baseline overflow split.
-
----
-
-## 15. Summary
-
-This specification delivers a transparent “4-of-30” lottery with strict 100% jackpot payout and a principled, adaptive FR mechanism. FR leverages temporary, equal redirects from Dev and Distribution, a modest k=3 contribution, and an FR-biased overflow to restore the jackpot to Target Carry at scale, while preserving player fairness, shareholder remuneration, and operational discipline.
-
-**Distribution (20% of (R)) constitutes RL smart-contract shareholder income**; during FR, a small portion is temporarily redirected to the jackpot and then fully restored to shareholders once FR is OFF.

From de8c4a75ebfda927e338a5bc728fc89041619142 Mon Sep 17 00:00:00 2001
From: N-010 <chelsig96@gmail.com>
Date: Fri, 12 Dec 2025 18:35:47 +0300
Subject: [PATCH 04/10] Update 2025-11-04-QThirtyFour.md

---
 SmartContracts/2025-11-04-QThirtyFour.md | 662 ++++++++++++++++++++---
 1 file changed, 580 insertions(+), 82 deletions(-)

diff --git a/SmartContracts/2025-11-04-QThirtyFour.md b/SmartContracts/2025-11-04-QThirtyFour.md
index 2ccbed4..fb94e69 100644
--- a/SmartContracts/2025-11-04-QThirtyFour.md
+++ b/SmartContracts/2025-11-04-QThirtyFour.md
@@ -1,147 +1,645 @@
-# Proposal: “4-of-30” Lottery — Final Specification with Adaptive Fast-Recovery
+# QThirtyFour (QTF) Technical Specification
 
-## 1. Purpose and Scope
+## Contract Overview
 
-This document defines the business, economic, and operational parameters of the on-chain lottery “4-of-30.” It establishes:
+**Contract Name:** QThirtyFour (QTF)
+**Type:** Lottery smart contract
+**Platform:** Qubic blockchain
+**Version:** 1.0
+**Status:** Development/Testing
 
-* Prize structure and minimum payouts;
-* Revenue allocation and reserve policy;
-* An adaptive Fast-Recovery (FR) regime that accelerates jackpot rebuild to a configurable target (“Target Carry”) at high ticket volumes;
-* Shareholder remuneration from the Distribution component;
-* Machine-readable configuration for implementation in the smart contract (SC).
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Game Mechanics](#game-mechanics)
+3. [Revenue Distribution](#revenue-distribution)
+4. [Prize Pool Structure](#prize-pool-structure)
+5. [Fast-Recovery System](#fast-recovery-system)
+6. [Reserve Pool Integration](#reserve-pool-integration)
+7. [Settlement Process](#settlement-process)
+8. [Security Features](#security-features)
+9. [Configuration Parameters](#configuration-parameters)
 
 ---
 
-## 2. Product Overview
+## 1. Introduction
+
+QThirtyFour is a 4-of-30 lottery smart contract that operates on the Qubic blockchain. Players select 4 unique numbers from a range of 1-30, and prizes are awarded based on how many numbers match the randomly drawn winning numbers.
+
+### Key Features
 
-**Game format.** A player selects 4 unique numbers from 30.
-**Prize tiers.** k=2, k=3, k=4 (jackpot).
-**Jackpot.** The jackpot (carry) is a separate, accumulating balance. Upon a k=4 win, the winner receives **100% of the current jackpot**. Jackpot replenishment is automatic per Sections 5–7.
+- **Three prize tiers:** k=2, k=3, and k=4 (jackpot)
+- **Guaranteed minimum payouts** with reserve pool backing
+- **Adaptive Fast-Recovery (FR) system** for jackpot rebuilding
+- **Scheduled draws** with configurable draw days and times
+- **Transparent prize pool calculations** visible before draws
+- **Integration with QReservePool (QRP)** for financial stability
 
 ---
 
-## 3. Revenue Allocation (per round)
+## 2. Game Mechanics
+
+### Number Selection
+
+- Players choose **4 unique numbers** from the range **[1, 30]**
+- All numbers must be unique within a single ticket
+- Invalid selections are rejected with appropriate error codes
+
+### Ticket Purchase
 
-Let ticket price be (P). Let (N) denote tickets sold in the round, and (R = N \cdot P).
+1. Player invokes `BuyTicket` procedure with:
+   - Payment: Ticket price in QU (default: 1,000,000 QU)
+   - Selection: Array of 4 unique numbers [1-30]
 
-* **Winners (k=2/k=3)**: 68% of (R)
-* **Distribution (partners/shareholders)**: 20% of (R) —**shareholder income of the RL smart contract**
-* **Dev**: 10% of (R)
-* **Burn**: 2% of (R)
+2. Contract validates:
+   - Ticket price is correct (exact payment or overpayment with refund)
+   - Numbers are valid and unique
+   - Player limit not exceeded (max 1,024 players per round)
+   - Selling is currently active
 
-The jackpot (k=4) is **not** funded from the 68% winners pool; it grows via FR redirects and overflow as defined below.
+3. If valid: Ticket is registered, excess payment refunded
+4. If invalid: Full refund with error code
 
-> Note: During FR, a **temporary** fraction of Distribution may be redirected to the jackpot (per “Financial Mechanics During FR”); once FR is OFF, Distribution returns to the **full 20% of (R)** for RL shareholders.
+### Winning Criteria
+
+- **k=2 (Second Tier):** Match exactly 2 of 4 numbers
+- **k=3 (Third Tier):** Match exactly 3 of 4 numbers
+- **k=4 (Jackpot):** Match all 4 numbers
+
+### Draw Schedule
+
+- **Primary draw:** Every Wednesday at configured hour (default: 11:00 UTC)
+- **Additional draws:** Configurable via schedule bitmask (7 days of week)
+- **Draw frequency:** Throttled to once per day maximum
+- **Settlement:** Triggered automatically by BEGIN_TICK system procedure
 
 ---
 
-## 4. Minimum Payout Floors
+## 3. Revenue Distribution
+
+### Default Fee Structure (from RandomLottery contract)
+
+When tickets are sold, revenue is split according to fees:
 
-* **k=2 floor:** ≥ 0.5 × (P) per winner.
-* **k=3 floor:** ≥ 5 × (P) per winner.
-  If a tier pool is insufficient, top-ups may be sourced from **Reserve.General**, subject to safety limits: ≤ 10% of total reserve per round; ≤ 25 × (P) per winner; soft floor of reserve equivalent to 20 × (P).
+| Recipient | Percentage | Description |
+|-----------|------------|-------------|
+| Winners Block | 68% | Allocated to prize pools (k2, k3, jackpot) |
+| Distribution (Shareholders) | 20% | RL asset holders (computors) |
+| Development Team | 10% | Contract development and maintenance |
+| Burn | 2% | Deflationary mechanism |
+| **Total** | **100%** | |
+
+**Example:** 100 tickets × 1M QU = 100M QU revenue
+- Winners: 68M QU
+- Distribution: 20M QU
+- Dev: 10M QU
+- Burn: 2M QU
 
 ---
 
-## 5. Reserves and Overflow
+## 4. Prize Pool Structure
+
+### Baseline Mode (FR Inactive)
+
+When Fast-Recovery is **OFF**, the Winners Block (68% of revenue) is split:
+
+| Pool | Percentage of Winners Block | Example (68M QU) |
+|------|----------------------------|------------------|
+| k=3 Pool | 40% | 27.2M QU |
+| k=2 Pool | 28% | 19.04M QU |
+| Overflow | 32% | 21.76M QU |
+
+**Overflow Split (50/50):**
+- 50% → Reserve Pool (QRP)
+- 50% → Jackpot carry
+
+### Fast-Recovery Mode (FR Active)
+
+When FR is **ON**, additional mechanisms activate:
+
+#### 1. Winners Rake (5%)
+- **5% of Winners Block** redirected to jackpot
+- Example: 68M × 5% = 3.4M QU to jackpot
+- Remaining 95% split into k2/k3 pools
+
+#### 2. Base Redirects (Always Applied in FR)
+- **Dev redirect:** 1.00% of revenue → Jackpot
+- **Dist redirect:** 1.00% of revenue → Jackpot
+- Deducted from Dev and Distribution payouts
+
+#### 3. Extra Redirects (Deficit-Driven)
+Calculated dynamically based on:
+- **Deficit:** Δ = max(0, targetJackpot - currentJackpot)
+- **Expected rounds to k=4:** E_k4(N) = 1 / (1 - (1-p4)^N)
+  - p4 = 1/27,405 (combinatorial probability)
+  - N = number of tickets sold
+- **Horizon:** H = min(E_k4(N), 50 rounds)
+- **Needed gain:** g_need = max(0, Δ/H - baseGain)
+- **Extra percentage:** extra_pp = clamp(g_need / R, 0, 0.70%)
 
-* **Overflow.** Any unawarded amount within k=2/k=3 after payouts is overflow. Overflow is split between **Reserve** and **Jackpot (carry)** with mode-dependent coefficients (baseline vs FR).
-* **Reserve buckets.**
+Split equally between Dev and Dist (max 0.35% each).
 
-  * **Reserve.General:** used to meet payout floors;
-  * **Reserve.JackpotRebuild:** used to reseed jackpot after k=4 wins up to the configured target (subject to availability).
-* **Safety limits.** As defined in Section 4.
+#### 4. Overflow Bias (95/5)
+- **95% of overflow** → Jackpot
+- **5% of overflow** → Reserve Pool
+
+**FR Mode Winners Block Split:**
+
+| Component | Calculation |
+|-----------|-------------|
+| Winners Block | 68% of revenue |
+| Winners Rake (5%) | → Jackpot |
+| Effective Winners Block | 95% of original |
+| k=3 Pool | 40% of effective |
+| k=2 Pool | 28% of effective |
+| Overflow | 32% of effective |
 
 ---
 
-## 6. Target Carry and Jackpot Reseed
+## 5. Fast-Recovery System
+
+### Purpose
+
+Rebuild jackpot to target level after a k=4 win as quickly as possible while maintaining player value.
+
+### Activation Logic
+
+FR activates when **BOTH** conditions are true:
+1. **Jackpot < Target Jackpot**
+2. **Rounds since last k=4 < 50** (post-k4 window)
+
+### Deactivation Logic (Hysteresis)
+
+FR deactivates when:
+- **Jackpot ≥ Target Jackpot** for **3 consecutive rounds**
+
+This prevents rapid on/off toggling near the threshold.
+
+### FR Mechanisms Summary
 
-* **Target Carry** is configurable (e.g., 0.5B, 1B, 2B qu).
-* After a k=4 payout, the SC may reseed the jackpot from **Reserve.JackpotRebuild** up to Target Carry (or available balance if lower). The remainder is rebuilt through FR and overflow per Sections 7–8.
+| Mechanism | Rate | Destination |
+|-----------|------|-------------|
+| Winners Rake | 5% of Winners Block | Jackpot |
+| Base Dev Redirect | 1% of Revenue | Jackpot |
+| Base Dist Redirect | 1% of Revenue | Jackpot |
+| Extra Dev Redirect | 0-0.35% of Revenue | Jackpot |
+| Extra Dist Redirect | 0-0.35% of Revenue | Jackpot |
+| Overflow Bias | 95% of Overflow | Jackpot |
+
+### Post-K4 Reseed
+
+When jackpot is won (k=4):
+1. Jackpot paid out to winners (divided equally if multiple)
+2. Jackpot balance reset to 0
+3. **Reseed from QRP:** Up to min(QRP balance, targetJackpot)
+4. FR counters reset
+5. FR activates for next round
 
 ---
 
-## 7. Adaptive Fast-Recovery (FR)
+## 6. Reserve Pool Integration
+
+QThirtyFour integrates with **QReservePool (QRP)** contract for financial stability.
+
+### QRP Functions Used
+
+| Function | Purpose |
+|----------|---------|
+| `GetAvailableReserve` | Query total reserve available |
+| `GetReserve` | Request funds from reserve |
+
+### Reserve Usage Scenarios
+
+#### 1. Floor Guarantee Top-Up
+
+If prize pool insufficient to meet minimum floors:
+- **k=2 floor:** 0.5 × Ticket Price per winner
+- **k=3 floor:** 5 × Ticket Price per winner
+
+**Safety Limits:**
+- Maximum 10% of QRP balance per round
+- Soft floor: Keep ≥20 × P in QRP
+- Per-winner cap: 25 × P maximum
+
+#### 2. Jackpot Reseed (Post-K4)
 
-**Objective.** When ticket volume is high, FR temporarily accelerates jackpot growth so that the jackpot is expected to reach Target Carry **not later** than the next average k=4 occurrence.
+After k=4 win:
+- Request: min(QRP balance, targetJackpot)
+- No safety limits (jackpot critical)
 
-**Adaptive trigger.** Each round, the SC evaluates:
+#### 3. Overflow Deposit
 
-1. the remaining gap to Target Carry;
-2. the expected growth rate of the jackpot under FR;
-3. the expected number of rounds before the next average k=4 (as a function of (N)).
+Unawarded funds sent to QRP:
+- **Baseline mode:** 50% of overflow → QRP
+- **FR mode:** 5% of overflow → QRP
 
-**Activation rule.** If, at current (N), the expected FR-driven growth over the expected time to next k=4 is sufficient to close the gap, **FR=ON**.
-Additionally, within a **post-k4 window** (default 50 rounds), FR may activate under looser conditions to support early rebuild.
+---
 
-**Deactivation rule (hysteresis).** If the jackpot is at or above Target Carry for **3 consecutive rounds**, **FR=OFF**.
+## 7. Settlement Process
+
+### Trigger
+
+Settlement occurs automatically via `BEGIN_TICK` system procedure when:
+1. Current hour ≥ configured draw hour
+2. Scheduled day (Wednesday or schedule bit set)
+3. Different date from last draw
+
+### SettleEpoch Detailed Steps
+
+#### Phase 1: Validation
+1. Check if players > 0 (else return)
+2. Calculate revenue (ticketPrice × numberOfPlayers)
+3. Verify contract balance ≥ revenue (else refund all)
+
+#### Phase 2: Fee Calculation
+4. Query fees from RL contract
+5. Calculate base payouts:
+   - devPayout = revenue × 10%
+   - distPayout = revenue × 20%
+   - burnAmount = revenue × 2%
+
+#### Phase 3: Prize Pool Calculation
+6. Call `CalculatePrizePools`:
+   - Calculate winnersBlock (68% of revenue)
+   - Apply FR rake if active (5% to jackpot)
+   - Split into k2 (28%) and k3 (40%) pools
+   - Calculate overflow (32% remaining)
+
+#### Phase 4: FR Hysteresis & Activation
+7. Update hysteresis counter:
+   - If jackpot ≥ target: increment frRoundsAtOrAboveTarget
+   - Else: reset to 0
+8. Determine FR activation:
+   - Activate if: jackpot < target AND roundsSinceK4 < 50
+   - Deactivate if: frRoundsAtOrAboveTarget ≥ 3
+
+#### Phase 5: FR Redirects (if active)
+9. Calculate deficit: Δ = max(0, target - jackpot)
+10. Estimate base gain (1% Dev + 1% Dist + 5% rake + 95% overflow)
+11. Calculate extra redirect based on deficit/horizon
+12. Compute total redirects (base + extra)
+13. Deduct from Dev/Dist payouts (capped at available)
+
+#### Phase 6: Random Number Generation
+14. Generate 4 unique winning numbers [1-30] using K12 hash
+
+#### Phase 7: Winner Counting
+15. First pass through players:
+    - Count matches for each ticket (k=2, k=3, k=4)
+    - Cache results for second pass
+
+#### Phase 8: Tier Payouts
+16. Query QRP available reserve
+17. Process k=2 tier:
+    - Call `ProcessTierPayout` with floor 0.5×P
+    - Top-up from QRP if needed
+    - Calculate per-winner payout (capped at 25×P)
+    - Collect overflow
+18. Process k=3 tier:
+    - Call `ProcessTierPayout` with floor 5×P
+    - Top-up from QRP if needed
+    - Calculate per-winner payout (capped at 25×P)
+    - Collect overflow
+
+#### Phase 9: Winner Payments
+19. Second pass through players:
+    - Pay k=2 winners (if countK2 > 0)
+    - Pay k=3 winners (if countK3 > 0)
+    - Pay k=4 winners (jackpot / countK4)
+    - Record winners in lastWinnerData
+
+#### Phase 10: Jackpot Handling
+20. If k=4 won:
+    - Deplete jackpot to 0
+    - Reset FR counters
+    - Reseed from QRP (up to min(QRP, target))
+21. Else:
+    - Increment frRoundsSinceK4
+
+#### Phase 11: Overflow Distribution
+22. Split overflow:
+    - FR mode: 95% → jackpot, 5% → QRP
+    - Baseline: 50% → jackpot, 50% → QRP
+
+#### Phase 12: Jackpot Update
+23. Add to jackpot:
+    - Winners rake (if FR)
+    - Dev redirects (if FR)
+    - Dist redirects (if FR)
+    - Overflow carry portion
+
+#### Phase 13: External Transfers
+24. Transfer overflow reserve to QRP
+25. Transfer dev payout to teamAddress
+26. Distribute dist payout to RL shareholders:
+    - Iterate through RL asset holders
+    - Calculate per-share dividend
+    - Transfer to each holder
+    - Return remainder to RL contract
+27. Burn burnAmount
 
 ---
 
-## 8. Financial Mechanics During FR
+## 8. Security Features
+
+### Input Validation
+
+1. **Number validation:**
+   - Range check: 1 ≤ value ≤ 30
+   - Uniqueness check via HashSet
+   - ASSERT on array access to prevent overflow
 
-While FR=ON, a small, **equal** temporary redirect from Dev and Distribution augments the jackpot, complemented by a minor temporary contribution from k=3 and an overflow bias to carry. Players face no additional fees.
+2. **Payment validation:**
+   - Exact or higher payment accepted
+   - Excess refunded immediately
+   - Zero-payment rejected
 
-**8.1 Equal redirects (Dev/Distribution).**
+3. **Access control:**
+   - Owner-only procedures (SetPrice, SetSchedule, etc.)
+   - Non-owner invocations rejected with ACCESS_DENIED
 
-* **Dev redirect:** `dev_redirect_pp = 1.0% of R` → jackpot (carry).
-* **Distribution redirect:** `dist_redirect_pp = 1.0% of R` → jackpot (carry).
-* **High-load supplement (optional):** If (N \geq 1000), add `dev_redirect_extra_pp = 0.35% of R` and `dist_redirect_extra_pp = 0.35% of R` (total +0.7% of R into carry).
+### Economic Safety
 
-**8.2 Temporary k=3 contribution (recovery-rake).**
+1. **Balance verification:**
+   - Check contract balance ≥ revenue before settlement
+   - Refund all players if insufficient
 
-* `winners_rake_of_winners_total_fr = 5%` of the 68% winners block is redirected to carry **from k=3 only**.
-* The remaining winners block (`win_eff`) is split with a slight tilt toward k=2 for stability during FR: **k=3 = 35% of `win_eff`**, **k=2 = 65% of `win_eff`**. Floors remain intact.
+2. **Reserve limits:**
+   - Max 10% QRP per round for top-ups
+   - Soft floor: Keep ≥20×P in QRP
+   - Per-winner cap: 25×P maximum
 
-**8.3 Overflow bias under FR.**
+3. **Overflow protection:**
+   - Safe arithmetic: `sadd()`, `smul()`, `div()`
+   - No raw `+` or `*` in financial calculations
+   - Division by zero prevented
 
-* `alpha_when_active = 0.05`, i.e., **95% of tier overflow → carry**, **5% → reserve**.
+### State Integrity
 
-**8.4 Post-FR reversion.**
+1. **Ticket selling gates:**
+   - Disabled during settlement
+   - Disabled on Wednesdays (main draw day)
+   - Max 1,024 players enforced
 
-* When FR turns OFF, Dev and Distribution return to 10%/20% of (R) (no redirect), winners split reverts to baseline, and overflow split reverts to baseline policy.
+2. **Draw scheduling:**
+   - Date stamp prevents same-day re-draws
+   - Throttled to RL_TICK_UPDATE_PERIOD
+
+3. **FR counters:**
+   - Reset on jackpot win
+   - Hysteresis prevents rapid toggling
 
 ---
 
-## 9. Shareholder Remuneration (Distribution)
+## 9. Configuration Parameters
+
+### Core Game Parameters
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `QTF_MAX_NUMBER_OF_PLAYERS` | 1024 | Max tickets per round |
+| `QTF_RANDOM_VALUES_COUNT` | 4 | Numbers per ticket |
+| `QTF_MAX_RANDOM_VALUE` | 30 | Number range [1-30] |
+| `QTF_TICKET_PRICE` | 1,000,000 QU | Default ticket price |
+
+### Prize Pool Splits (Baseline)
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `QTF_BASE_K3_SHARE_BP` | 4000 | k=3 gets 40% of winners block |
+| `QTF_BASE_K2_SHARE_BP` | 2800 | k=2 gets 28% of winners block |
+| (Overflow) | 3200 | 32% remaining goes to overflow |
+
+### Fast-Recovery Parameters
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `QTF_FR_DEV_REDIRECT_BP` | 100 | 1.00% base dev redirect |
+| `QTF_FR_DIST_REDIRECT_BP` | 100 | 1.00% base dist redirect |
+| `QTF_FR_EXTRA_MAX_BP` | 70 | 0.70% max extra redirect total |
+| `QTF_FR_WINNERS_RAKE_BP` | 500 | 5% of winners block |
+| `QTF_FR_ALPHA_BP` | 500 | 5% overflow to reserve (95% to jackpot) |
+| `QTF_FR_POST_K4_WINDOW_ROUNDS` | 50 | Rounds after k=4 to keep FR eligible |
+| `QTF_FR_HYSTERESIS_ROUNDS` | 3 | Rounds at target before FR off |
+| `QTF_FR_GOAL_ROUNDS_CAP` | 50 | Max horizon for deficit calculation |
+| `QTF_P4_DENOMINATOR` | 27405 | Exact k=4 probability: 1/27405 |
+
+### Payout Floors and Caps
 
-* **Source.** The Distribution block (20% of (R)).
-* **FR effect.** During FR, the `dist_redirect_pp [ + dist_redirect_extra_pp ]` portion is temporarily routed to carry; once FR is OFF, Distribution returns to the full 20% of (R).
+| Constant | Value | Calculation | Example (P=1M) |
+|----------|-------|-------------|----------------|
+| `QTF_K2_FLOOR_MULT` | 1 | 1×P / 2 | 500k QU |
+| `QTF_K2_FLOOR_DIV` | 2 | | |
+| `QTF_K3_FLOOR_MULT` | 5 | 5×P | 5M QU |
+| `QTF_TOPUP_PER_WINNER_CAP_MULT` | 25 | 25×P | 25M QU |
+
+### Reserve Safety Limits
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `QTF_TOPUP_RESERVE_PCT_BP` | 1000 | Max 10% QRP per round |
+| `QTF_RESERVE_SOFT_FLOOR_MULT` | 20 | Keep ≥20×P in QRP |
+
+### Overflow Split (Baseline)
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `QTF_BASELINE_OVERFLOW_ALPHA_BP` | 5000 | 50% reserve, 50% jackpot |
+
+### Defaults
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `QTF_DEFAULT_TARGET_JACKPOT` | 1,000,000,000 QU | 1 billion QU |
+| `QTF_DEFAULT_SCHEDULE` | 0x08 | Wednesday only |
+| `QTF_DEFAULT_DRAW_HOUR` | 11 | 11:00 UTC |
+
+### Default Fees (Fallback)
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `QTF_DEFAULT_DEV_PERCENT` | 10 | 10% to dev |
+| `QTF_DEFAULT_DIST_PERCENT` | 20 | 20% to shareholders |
+| `QTF_DEFAULT_BURN_PERCENT` | 2 | 2% burned |
+| `QTF_DEFAULT_WINNERS_PERCENT` | 68 | 68% to winners |
 
 ---
 
-## 10. Parameters (Defaults and Governance Ranges)
+## Appendix A: Probability Calculations
+
+### K=4 Win Probability
+
+**Combinatorics:**
+- Total combinations: C(30,4) = 27,405
+- Winning combinations: C(4,4) × C(26,0) = 1
+- **Probability: p4 = 1 / 27,405 ≈ 0.00365%**
 
-* **Target Carry:** 1,000,000,000 qu (governable).
-* **post_k4_window_rounds:** 50 (range: 20–80).
-* **hysteresis_rounds_at_or_above_target:** 3 (range: 2–5).
-* **dev_redirect_pp:** 0.01 (range: 0.005–0.02).
-* **dist_redirect_pp:** 0.01 (range: 0.005–0.02).
-* **high_load_redirect_extra (N≥1000):** dev=0.0035, dist=0.0035 (each; range: 0.0025–0.005).
-* **winners_rake_of_winners_total_fr:** 0.05 (range: 0.03–0.08).
-* **tiers_pool_shares_fr (of `win_eff`):** k3=0.35, k2=0.65 (sum=1.0).
-* **alpha_when_active:** 0.05 (range: 0.03–0.20).
-* **Reserve safety limits:** per Sections 4–5.
+### Expected Rounds to K=4
+
+Given N tickets per round:
+
+**Formula:**
+```
+E_k4(N) = 1 / (1 - (1 - p4)^N)
+```
+
+**Examples:**
+| Tickets (N) | Approx E_k4 |
+|-------------|-------------|
+| 100 | ~274 rounds |
+| 500 | ~55 rounds |
+| 1000 | ~27 rounds |
+
+This drives the FR extra redirect calculation.
 
 ---
 
-## 11. Operational Order of Settlement (Per Round, High Level)
+## Appendix C: Example Scenarios
+
+### Scenario 1: Baseline Round (FR Off)
+
+**Setup:**
+- Tickets sold: 200
+- Ticket price: 1M QU
+- FR: Inactive
+- Jackpot: 1.5B QU (above target)
+
+**Revenue Distribution:**
+- Total: 200M QU
+- Dev: 20M (10%)
+- Dist: 40M (20%)
+- Burn: 4M (2%)
+- Winners: 136M (68%)
+
+**Prize Pools:**
+- k=3: 54.4M (40% of 136M)
+- k=2: 38.08M (28% of 136M)
+- Overflow: 43.52M (32% of 136M)
+
+**Overflow Split (50/50):**
+- To QRP: 21.76M
+- To Jackpot: 21.76M
+
+**Winners (example):**
+- k=2: 15 winners → 2.54M each (38.08M / 15)
+- k=3: 3 winners → 18.13M each (54.4M / 3)
+- k=4: 0 winners → Jackpot carries
 
-1. Compute baseline blocks: **Dev 10%**, **Distribution 20%**, **Burn 2%**, **Winners 68%**.
-2. If **FR=ON**:
+**Final State:**
+- Jackpot: 1.52176B (+21.76M)
+- QRP: +21.76M
+- Rounds since k4: +1
 
-   * Redirect `dev_redirect_pp * R [ + dev_redirect_extra_pp * R ]` to carry (reducing Dev by the same amount);
-   * Redirect `dist_redirect_pp * R [ + dist_redirect_extra_pp * R ]` to carry (reducing Distribution by the same amount);
-   * From Winners, redirect `winners_rake_of_winners_total_fr` (5% of 68% (R)) to carry from k=3;
-   * Split `win_eff` as `{k3:35%, k2:65%}`; apply floors;
-   * Split overflow with `alpha_when_active=0.05` (95% → carry, 5% → reserve).
-3. If **k=4** occurs: pay **100% of carry** to winner(s); then optionally reseed from **Reserve.JackpotRebuild** up to Target Carry (subject to availability).
-4. If **FR OFF**: apply baseline tier shares and baseline overflow split.
+---
+
+### Scenario 2: FR Active Round
+
+**Setup:**
+- Tickets sold: 500
+- Ticket price: 1M QU
+- FR: Active
+- Jackpot: 500M QU (below 1B target)
+- Deficit: 500M QU
+
+**Revenue Distribution:**
+- Total: 500M QU
+- Base Dev: 50M (10%)
+- Base Dist: 100M (20%)
+- Burn: 10M (2%)
+- Winners: 340M (68%)
+
+**Prize Pools (FR):**
+- Winners rake (5%): 17M → Jackpot
+- Effective winners: 323M
+- k=3: 129.2M (40% of 323M)
+- k=2: 90.44M (28% of 323M)
+- Overflow: 103.36M (32% of 323M)
+
+**FR Redirects:**
+- Base dev redirect (1%): 5M
+- Base dist redirect (1%): 5M
+- Extra redirect (calculated): ~2M total (1M dev, 1M dist)
+- Total redirects: 12M (5+5+1+1)
+
+**Adjusted Payouts:**
+- Dev: 50M - 6M = 44M
+- Dist: 100M - 6M = 94M
+
+**Overflow Split (95/5):**
+- To Jackpot: 98.19M (95% of 103.36M)
+- To QRP: 5.17M (5% of 103.36M)
+
+**Total to Jackpot:**
+- Winners rake: 17M
+- Redirects: 12M
+- Overflow: 98.19M
+- **Total: 127.19M**
+
+**Winners (example):**
+- k=2: 40 winners → 2.26M each (90.44M / 40)
+- k=3: 5 winners → 25M each (capped at 25M, was 25.84M)
+- k=4: 0 winners
+
+**Final State:**
+- Jackpot: 627.19M (+127.19M)
+- QRP: +5.17M
+- Rounds since k4: +1
+- FR stays active (still below target)
 
 ---
 
-## 15. Summary
+### Scenario 3: Jackpot Win
+
+**Setup:**
+- Tickets sold: 800
+- Ticket price: 1M QU
+- FR: Active
+- Jackpot: 1.2B QU
+
+**Revenue:**
+- Total: 800M QU
+
+**Winners:**
+- k=2: 50 winners
+- k=3: 8 winners
+- **k=4: 2 winners** ← Jackpot won!
 
-This specification delivers a transparent “4-of-30” lottery with strict 100% jackpot payout and a principled, adaptive FR mechanism. FR leverages temporary, equal redirects from Dev and Distribution, a modest k=3 contribution, and an FR-biased overflow to restore the jackpot to Target Carry at scale, while preserving player fairness, shareholder remuneration, and operational discipline.
+**Jackpot Payout:**
+- Per winner: 1.2B / 2 = 600M QU each
+- Total: 1.2B depleted
 
-**Distribution (20% of (R)) constitutes RL smart-contract shareholder income**; during FR, a small portion is temporarily redirected to the jackpot and then fully restored to shareholders once FR is OFF.
+**Post-Win:**
+1. Jackpot reset to 0
+2. FR counters reset
+3. Reseed from QRP:
+   - Request: min(QRP balance, 1B target)
+   - Assume QRP has 2B available
+   - **Receive: 1B QU**
+4. New jackpot: 1B QU
+5. FR activates (jackpot = target, but will deactivate after 3 rounds)
+
+---
+
+## Glossary
+
+| Term | Definition |
+|------|------------|
+| **Basis Points (BP)** | 1/100 of 1% (e.g., 500 BP = 5%) |
+| **Carry** | Jackpot pool that carries over between rounds |
+| **Computor** | Qubic network validator node |
+| **Deficit** | Gap between current and target jackpot (Δ) |
+| **Epoch** | Qubic time unit (7 days) |
+| **FR** | Fast-Recovery mode (jackpot rebuilding system) |
+| **Hysteresis** | Delay in state change to prevent rapid toggling |
+| **K12** | Kangaroo Twelve cryptographic hash function |
+| **k=2, k=3, k=4** | Prize tiers (2, 3, 4 matching numbers) |
+| **Overflow** | Unallocated/unawarded prize funds |
+| **QPI** | Qubic Programming Interface (contract API) |
+| **QRP** | QReservePool contract (reserve management) |
+| **QU** | Qubic Unit (base currency) |
+| **Rake** | Percentage taken from prize pool |
+| **RL** | RandomLottery contract (existing lottery) |
+| **Tick** | Qubic block (~1 second) |
+| **Winners Block** | Revenue portion allocated to prizes (68%) |
+
+---

From a7c3360bad3768c9fa968e8ac0f521805dd00e44 Mon Sep 17 00:00:00 2001
From: N-010 <chelsig96@gmail.com>
Date: Fri, 19 Dec 2025 16:35:16 +0300
Subject: [PATCH 05/10] Update 2025-11-04-QThirtyFour.md

---
 SmartContracts/2025-11-04-QThirtyFour.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/SmartContracts/2025-11-04-QThirtyFour.md b/SmartContracts/2025-11-04-QThirtyFour.md
index fb94e69..6942208 100644
--- a/SmartContracts/2025-11-04-QThirtyFour.md
+++ b/SmartContracts/2025-11-04-QThirtyFour.md
@@ -8,6 +8,11 @@
 **Version:** 1.0
 **Status:** Development/Testing
 
+## Available Options
+> Option 0: no, dont allow
+
+> Option 1: yes, allow
+
 ## Table of Contents
 
 1. [Introduction](#introduction)

From 585396bb0383222a6670d949de31ffe1c2372f41 Mon Sep 17 00:00:00 2001
From: N-010 <chelsig96@gmail.com>
Date: Fri, 19 Dec 2025 16:42:17 +0300
Subject: [PATCH 06/10] Update 2025-11-04-QThirtyFour.md

---
 SmartContracts/2025-11-04-QThirtyFour.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/SmartContracts/2025-11-04-QThirtyFour.md b/SmartContracts/2025-11-04-QThirtyFour.md
index 6942208..31322f5 100644
--- a/SmartContracts/2025-11-04-QThirtyFour.md
+++ b/SmartContracts/2025-11-04-QThirtyFour.md
@@ -15,8 +15,8 @@
 
 ## Table of Contents
 
-1. [Introduction](#introduction)
-2. [Game Mechanics](#game-mechanics)
+1. [Introduction](#1-introduction)
+2. [Game Mechanics](#2-game-mechanics)
 3. [Revenue Distribution](#revenue-distribution)
 4. [Prize Pool Structure](#prize-pool-structure)
 5. [Fast-Recovery System](#fast-recovery-system)
@@ -24,6 +24,7 @@
 7. [Settlement Process](#settlement-process)
 8. [Security Features](#security-features)
 9. [Configuration Parameters](#configuration-parameters)
+10. [Code](#9-code)
 
 ---
 
@@ -648,3 +649,8 @@ This drives the FR extra redirect calculation.
 | **Winners Block** | Revenue portion allocated to prizes (68%) |
 
 ---
+
+## [9. Code]
+[QThirtyFour](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QThirtyFour.h)
+[QReservePool](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QReservePool.h)
+---

From 9a2a04090d18ff43cebd5c8a0d43099ec72bea98 Mon Sep 17 00:00:00 2001
From: N-010 <chelsig96@gmail.com>
Date: Fri, 19 Dec 2025 16:43:58 +0300
Subject: [PATCH 07/10] Update 2025-11-04-QThirtyFour.md

---
 SmartContracts/2025-11-04-QThirtyFour.md | 28 +++++++++++++-----------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/SmartContracts/2025-11-04-QThirtyFour.md b/SmartContracts/2025-11-04-QThirtyFour.md
index 31322f5..6091bd1 100644
--- a/SmartContracts/2025-11-04-QThirtyFour.md
+++ b/SmartContracts/2025-11-04-QThirtyFour.md
@@ -17,14 +17,15 @@
 
 1. [Introduction](#1-introduction)
 2. [Game Mechanics](#2-game-mechanics)
-3. [Revenue Distribution](#revenue-distribution)
-4. [Prize Pool Structure](#prize-pool-structure)
-5. [Fast-Recovery System](#fast-recovery-system)
-6. [Reserve Pool Integration](#reserve-pool-integration)
-7. [Settlement Process](#settlement-process)
-8. [Security Features](#security-features)
-9. [Configuration Parameters](#configuration-parameters)
-10. [Code](#9-code)
+3. [Revenue Distribution](#3-revenue-distribution)
+4. [Prize Pool Structure](#4-prize-pool-structure)
+5. [Fast-Recovery System](#5-fast-recovery-system)
+6. [Reserve Pool Integration](#6-reserve-pool-integration)
+7. [Settlement Process](#7-settlement-process)
+8. [Security Features](#8-security-features)
+9. [Configuration Parameters](#9-configuration-parameters)
+10. [Code](#10-code)
+11. [Glossary](#glossary)
 
 ---
 
@@ -626,6 +627,12 @@ This drives the FR extra redirect calculation.
 
 ---
 
+## 10. Code
+[QThirtyFour](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QThirtyFour.h)
+[QReservePool](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QReservePool.h)
+
+---
+
 ## Glossary
 
 | Term | Definition |
@@ -649,8 +656,3 @@ This drives the FR extra redirect calculation.
 | **Winners Block** | Revenue portion allocated to prizes (68%) |
 
 ---
-
-## [9. Code]
-[QThirtyFour](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QThirtyFour.h)
-[QReservePool](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QReservePool.h)
----

From 76272a2f5aedc779f5ac440fd0c615b242b5a028 Mon Sep 17 00:00:00 2001
From: N-010 <chelsig96@gmail.com>
Date: Fri, 19 Dec 2025 16:44:28 +0300
Subject: [PATCH 08/10] Update 2025-11-04-QThirtyFour.md

---
 SmartContracts/2025-11-04-QThirtyFour.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/SmartContracts/2025-11-04-QThirtyFour.md b/SmartContracts/2025-11-04-QThirtyFour.md
index 6091bd1..b605b01 100644
--- a/SmartContracts/2025-11-04-QThirtyFour.md
+++ b/SmartContracts/2025-11-04-QThirtyFour.md
@@ -629,6 +629,7 @@ This drives the FR extra redirect calculation.
 
 ## 10. Code
 [QThirtyFour](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QThirtyFour.h)
+
 [QReservePool](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QReservePool.h)
 
 ---

From 7eb0aac27c261c311ae57c946f471b17e2edd6ad Mon Sep 17 00:00:00 2001
From: N-010 <chelsig96@gmail.com>
Date: Fri, 19 Dec 2025 17:48:21 +0300
Subject: [PATCH 09/10] Create 2025-11-04-QReservePool.md

---
 SmartContracts/2025-11-04-QReservePool.md | 118 ++++++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 SmartContracts/2025-11-04-QReservePool.md

diff --git a/SmartContracts/2025-11-04-QReservePool.md b/SmartContracts/2025-11-04-QReservePool.md
new file mode 100644
index 0000000..ff784a1
--- /dev/null
+++ b/SmartContracts/2025-11-04-QReservePool.md
@@ -0,0 +1,118 @@
+# QReservePool (QRP)
+
+## Available Options
+> Option 0: no, dont allow
+
+> Option 1: yes, allow
+
+## Table of Contents
+
+1. [Introduction](#1-introduction)
+2. [Goals and Non-Goals](#2-goals-and-non-goals)
+3. [Core Model](#3-core-model)
+4. [Interface Summary](#4-interface-summary)
+5. [Access Control](#5-access-control)
+6. [Integration: QThirtyFour (QTF)](#6-integration-qthirtyfour-qtf)
+7. [Future Integrations: RL-family Projects](#7-future-integrations-rl-family-projects)
+7. [Code](#8-code)
+
+---
+
+## 1. Introduction
+
+QReservePool (QRP) is a shared on-chain reserve vault implemented in `src/contracts/QReservePool.h`.
+Its purpose is to provide a simple, reusable backstop reserve that allowlisted smart contracts can draw from when their own per-epoch cashflow is insufficient to meet obligations.
+
+At the current stage, QRP is required by `src/contracts/QThirtyFour.h` (QTF) as a reserve source for payout floors and jackpot carry rebuild scenarios.
+In the future, other RandomLottery-style projects are expected to use this same pool instead of deploying separate reserve contracts.
+
+---
+
+## 2. Goals and Non-Goals
+
+### Goals
+
+- **Centralize reserve management** in a single contract.
+- **Restrict withdrawals** to allowlisted smart contracts only.
+- **Keep the surface minimal** and easy to audit.
+- **Enable reuse** by future RL-family contracts via allowlisting.
+
+### Non-Goals
+
+- Per-consumer accounting or “sub-balances” per project.
+- Rate limiting, per-epoch quotas, or per-winner limits.
+- Enforcement of any consumer economics/spec rules (those belong to consumer contracts).
+
+---
+
+## 3. Core Model
+
+### Reserve Definition
+
+QRP treats its available reserve as the net balance of its entity:
+
+- `availableReserve = incomingAmount - outgoingAmount` (clamped to >= 0)
+
+### Withdrawal Model
+
+- A consumer contract requests a withdrawal by calling `GetReserve`.
+- If the caller is allowlisted and enough reserve is available, QRP transfers the requested amount to the invocator.
+
+---
+
+## 4. Interface Summary
+
+| Method | Type | Purpose |
+|--------|------|---------|
+| `GetReserve` | Procedure | Withdraw reserve to an allowlisted contract (caller = invocator). |
+| `AddAvailableSC` | Procedure | Owner-only: add a contract index to the allowlist. |
+| `RemoveAvailableSC` | Procedure | Owner-only: remove a contract index from the allowlist. |
+| `GetAvailableReserve` | Function | Read available reserve (net balance). |
+| `GetAvailableSC` | Function | Read allowlisted smart contracts. |
+
+---
+
+## 5. Access Control
+
+### Allowlisted Withdrawals
+
+- `GetReserve` must be callable only by allowlisted contract IDs.
+- End users (wallets) cannot withdraw directly.
+
+### Owner Governance
+
+- The allowlist is maintained via owner-only procedures:
+  - `AddAvailableSC`
+  - `RemoveAvailableSC`
+
+---
+
+## 6. Integration: QThirtyFour (QTF)
+
+QRP is currently needed for QTF (`src/contracts/QThirtyFour.h`) to support:
+
+- **Payout floors backstop:** when epoch revenue is too low to meet minimum guaranteed payouts.
+- **Carry/jackpot rebuild support:** when QTF needs to reseed/rebuild carry after a k=4 jackpot win (subject to QTF’s own safety rules).
+
+QRP itself does not encode QTF-specific limits. QTF must enforce its own caps and policies before calling `GetReserve`.
+
+---
+
+## 7. Future Integrations: RL-family Projects
+
+The long-term intent is for multiple RL-derived contracts (RandomLottery-style) to share the same reserve pool:
+
+- New consumer onboarding should be done by adding the contract to QRP allowlist (by contract index).
+- Each consumer contract must implement its own safety caps, governance constraints, and usage policy.
+
+This approach avoids deploying (and auditing) a separate reserve contract for every RL-family project.
+
+---
+
+## 8. Code
+
+[QThirtyFour](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QThirtyFour.h)
+
+[QReservePool](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QReservePool.h)
+
+---

From 7db7a48b3ed8e802cb1e49805f303e072eb7ef76 Mon Sep 17 00:00:00 2001
From: N-010 <chelsig96@gmail.com>
Date: Fri, 19 Dec 2025 17:48:31 +0300
Subject: [PATCH 10/10] Update 2025-11-04-QThirtyFour.md

---
 SmartContracts/2025-11-04-QThirtyFour.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/SmartContracts/2025-11-04-QThirtyFour.md b/SmartContracts/2025-11-04-QThirtyFour.md
index b605b01..e70f229 100644
--- a/SmartContracts/2025-11-04-QThirtyFour.md
+++ b/SmartContracts/2025-11-04-QThirtyFour.md
@@ -1,4 +1,4 @@
-# QThirtyFour (QTF) Technical Specification
+# QThirtyFour (QTF)
 
 ## Contract Overview
 
@@ -628,6 +628,7 @@ This drives the FR extra redirect calculation.
 ---
 
 ## 10. Code
+
 [QThirtyFour](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QThirtyFour.h)
 
 [QReservePool](https://github.com/N-010/core/blob/feature/2025-11-04-QThirtyFour/src/contracts/QReservePool.h)