Qperp Sc Proposal

SmartContracts/2026-04-17-QPerp.md

@@ -0,0 +1,82 @@
+# Computor Proposal: Include PERP Contracts (PFEED + PERPS) in Qubic Mainnet
+
+## Proposal
+Allow the **Qubic Perpetual Futures (PERP) smart contracts** to be included in Qubic Core and deployed on mainnet.
+
+## Available Options
+- **Option 0:** No, don’t include
+- **Option 1:** Yes, include
+
+## Summary
+This proposal requests mainnet inclusion of two contracts:
+- **PFEED (PriceFeed)**: a simple on-chain price store for a small set of assets.
+- **PERPS (Perpetuals)**: a perpetual futures engine implementing leveraged long/short positions, margin accounting, and liquidation logic.
+
+These contracts are already present in this codebase:
+- PriceFeed contract: [PriceFeed.h](https://github.com/uzochukwuV/core/tree/feature-2025-12-05-Perpetuals/src/contracts/PriceFeed.h)
+- Perpetuals contract: [Perpetuals.h](https://github.com/uzochukwuV/core/tree/feature-2025-12-05-Perpetuals/src/contracts/Perpetuals.h)
+
+They are registered in core as:
+- Asset names + construction epoch placeholders: [contract_def.h](file:///workspace/src/contract_core/contract_def.h#L301-L330)
+- Contract registration wiring: [contract_def.h]((https://github.com/uzochukwuV/core/tree/feature-2025-12-05-Perpetuals/src/contract_core/contract_def.h#L424-L447)
+
+## Contracts Requested For Inclusion
+### 1) PriceFeed (PFEED)
+- **Contract index:** 20
+- **Asset name:** PFEED
+- **State type:** `PRICEFEED`
+- **Source:** [PriceFeed.h](https://github.com/uzochukwuV/core/tree/feature-2025-12-05-Perpetuals/src/contracts/PriceFeed.h)
+
+### 2) Perpetuals (PERPS)
+- **Contract index:** 21
+- **Asset name:** PERPS
+- **State type:** `PERPETUALS`
+- **Source:** [Perpetuals.h](https://github.com/uzochukwuV/core/tree/feature-2025-12-05-Perpetuals/src/contracts/Perpetuals.h)
+
+## Technical Overview (As Implemented)
+### PriceFeed (PFEED)
+Provides:
+- `getPrice(token_id)` (function): returns current price and update tick
+- `getAllPrices()` (function): returns all configured prices
+- `updatePrice(token_id, new_price)` (procedure): updates one token price
+
+### Perpetuals (PERPS)
+Implements:
+- Position lifecycle: open → close or liquidate
+- Open interest tracking per token and side
+- Fee accounting and protocol stats reporting
+
+Important note (scope of this proposal):
+- The current PERPS implementation sets a mock entry price rather than calling PFEED for pricing ([Perpetuals.h](https://github.com/uzochukwuV/core/tree/feature-2025-12-05-Perpetuals/src/contracts/Perpetuals.h#L457-L475)).
+
+## Security / Verification Notes
+Qubic smart contracts must comply with the restricted contract C++ rules and pass the Qubic contract verification tool before core inclusion.
+
+Before submitting this proposal on-chain, the linked core PR should demonstrate:
+- Successful build (0 errors, 0 warnings)
+- Passing contract verification checks
+- Passing automated tests
+
+## Testing
+Project documentation claims:
+- Test summary: [TESTING_SUMMARY.md](https://github.com/uzochukwuV/core/tree/feature-2025-12-05-Perpetuals/docs/TESTING_SUMMARY.md)
+- PriceFeed tests: [contract_pricefeed.cpp](https://github.com/uzochukwuV/core/tree/feature-2025-12-05-Perpetuals/test/contract_pricefeed.cpp)
+- Perpetuals tests: [contract_perpetuals.cpp](https://github.com/uzochukwuV/core/tree/feature-2025-12-05-Perpetuals/test/contract_perpetuals.cpp)
+
+## Governance Timeline (Recommended)
+Current network epoch can be checked via `https://rpc.qubic.org/v1/tick-info`.
+
+At the time this proposal draft was prepared, the live network epoch was **208**, therefore:
+- **Epoch X = 209**: Computor proposal + voting
+- **Epoch X+1 = 210**: IPO
+- **Epoch X+2 = 211**: Contract construction and go-live (first user interactions)
+
+If submission happens later, shift X/X+1/X+2 accordingly.
+
+## Required Links (To Fill Before Submission)
+- Qubic core PR (must be merged into `develop` before on-chain proposal): TBD
+- Proposal repo PR (this document merged into `qubic/proposals`): TBD
+
+## Call To Action
+Vote **Option 1 (YES)** to include the PERP smart contracts in mainnet Qubic Core.
+