From 0f180ed03e69be405b13bc4219fa042a90de4a7c Mon Sep 17 00:00:00 2001 From: N-010 Date: Thu, 25 Dec 2025 22:32:42 +0300 Subject: [PATCH 1/6] Create 2025-12-25-QDuel.md --- SmartContracts/feature/2025-12-25-QDuel.md | 60 ++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 SmartContracts/feature/2025-12-25-QDuel.md diff --git a/SmartContracts/feature/2025-12-25-QDuel.md b/SmartContracts/feature/2025-12-25-QDuel.md new file mode 100644 index 0000000..41b6ca1 --- /dev/null +++ b/SmartContracts/feature/2025-12-25-QDuel.md @@ -0,0 +1,60 @@ +QDuel Contract Proposal + +# Proposal + +## Available Options + +Option 0: No, do not upgrade the contract. + +Option 1: Yes, approve the upgrade to enable multi-asset functionality. + +## Overview +QDuel is a simple duel game contract where two players stake equal amounts, +and the winner receives the pooled amount minus configured fees. The contract +creates and manages duel rooms, handles winner selection, and distributes fees +to the team address, burn, and Random Lottery shareholders. + +## Motivation and Goals +- Provide a lightweight, on-chain duel mechanic with minimal state. +- Ensure fair settlement with deterministic winner selection. +- Refund funds if a duel does not resolve in time. +- Allow the team to tune fees and room TTL without redeploying. + +## Contract Summary +The contract maintains up to 512 active rooms. A room stores: +roomId, player1, optional allowedPlayer, amount, and creation timestamp. +Players interact through CreateRoom and ConnectToRoom. If a room expires before +it is joined, funds are returned to player1. All rooms are cleared at epoch end. + +## Current Fee Settings (from QDuel.h defaults) +- devFeePercent = 0.15% +- burnFeePercent = 0.30% +- shareholdersFeePercent = 0.25% +- total = 0.70% + +Shareholders fee is distributed to holders of the Random Lottery asset +(asset name RL). Distribution is proportional to shares owned at payout time. +Any remainder from integer division is burned. + +## Winner Selection +Winner is derived from the previous spectrum digest mixed with both player IDs +and the current tick, hashed via K12. The least significant bit selects either +the min or max player ID. This is deterministic and verifiable on-chain. + +## Example Duel Settlement +- Room amount: 100,000 QU from player1 and 100,000 QU from player2. +- Total pot: 200,000 QU. +- Fees at default settings: + - devFee: 200,000 * 0.15% = 300 QU + - burnFee: 200,000 * 0.30% = 600 QU + - shareholdersFee: 200,000 * 0.25% = 500 QU +- Winner payout: 200,000 - (300 + 600 + 500) = 198,600 QU. +- Shareholders fee is split across RL holders; any remainder is burned. + +## Lifecycle Management +- END_TICK (every 10 ticks): refund expired rooms based on TTL hours. +- END_EPOCH: refund all open rooms and reset storage. + +# Technical implementation + +https://github.com/qubic/core/pull/705 From 3ad3c8612a43113f01994330412ce7be43d7a902 Mon Sep 17 00:00:00 2001 From: N-010 Date: Thu, 25 Dec 2025 23:43:21 +0300 Subject: [PATCH 2/6] Update 2025-12-25-QDuel.md update Shareholders precents --- SmartContracts/feature/2025-12-25-QDuel.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/SmartContracts/feature/2025-12-25-QDuel.md b/SmartContracts/feature/2025-12-25-QDuel.md index 41b6ca1..216dd14 100644 --- a/SmartContracts/feature/2025-12-25-QDuel.md +++ b/SmartContracts/feature/2025-12-25-QDuel.md @@ -29,8 +29,8 @@ it is joined, funds are returned to player1. All rooms are cleared at epoch end. ## Current Fee Settings (from QDuel.h defaults) - devFeePercent = 0.15% - burnFeePercent = 0.30% -- shareholdersFeePercent = 0.25% -- total = 0.70% +- shareholdersFeePercent = 0.55% +- total = 1% Shareholders fee is distributed to holders of the Random Lottery asset (asset name RL). Distribution is proportional to shares owned at payout time. @@ -47,8 +47,8 @@ the min or max player ID. This is deterministic and verifiable on-chain. - Fees at default settings: - devFee: 200,000 * 0.15% = 300 QU - burnFee: 200,000 * 0.30% = 600 QU - - shareholdersFee: 200,000 * 0.25% = 500 QU -- Winner payout: 200,000 - (300 + 600 + 500) = 198,600 QU. + - shareholdersFee: 200,000 * 0.55% = 1,100 QU +- Winner payout: 200,000 - (300 + 600 + 1,100) = 198,000 QU. - Shareholders fee is split across RL holders; any remainder is burned. ## Lifecycle Management From 5b1c7d76852f5800cd47f45699e4c13f34817113 Mon Sep 17 00:00:00 2001 From: N-010 Date: Thu, 25 Dec 2025 23:44:20 +0300 Subject: [PATCH 3/6] Create 2025-12-25-QDuel.md --- SmartContracts/2025-12-25-QDuel.md | 60 ++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 SmartContracts/2025-12-25-QDuel.md diff --git a/SmartContracts/2025-12-25-QDuel.md b/SmartContracts/2025-12-25-QDuel.md new file mode 100644 index 0000000..3f3d173 --- /dev/null +++ b/SmartContracts/2025-12-25-QDuel.md @@ -0,0 +1,60 @@ +# QDuel Contract Proposal + +# Proposal + +## Available Options + +Option 0: No, do not upgrade the contract. + +Option 1: Yes, approve the upgrade to enable multi-asset functionality. + +## Overview +QDuel is a simple duel game contract where two players stake equal amounts, +and the winner receives the pooled amount minus configured fees. The contract +creates and manages duel rooms, handles winner selection, and distributes fees +to the team address, burn, and Random Lottery shareholders. + +## Motivation and Goals +- Provide a lightweight, on-chain duel mechanic with minimal state. +- Ensure fair settlement with deterministic winner selection. +- Refund funds if a duel does not resolve in time. +- Allow the team to tune fees and room TTL without redeploying. + +## Contract Summary +The contract maintains up to 512 active rooms. A room stores: +roomId, player1, optional allowedPlayer, amount, and creation timestamp. +Players interact through CreateRoom and ConnectToRoom. If a room expires before +it is joined, funds are returned to player1. All rooms are cleared at epoch end. + +## Current Fee Settings (from QDuel.h defaults) +- devFeePercent = 0.15% +- burnFeePercent = 0.30% +- shareholdersFeePercent = 0.55% +- total = 1% + +Shareholders fee is distributed to holders of the Random Lottery asset +(asset name RL). Distribution is proportional to shares owned at payout time. +Any remainder from integer division is burned. + +## Winner Selection +Winner is derived from the previous spectrum digest mixed with both player IDs +and the current tick, hashed via K12. The least significant bit selects either +the min or max player ID. This is deterministic and verifiable on-chain. + +## Example Duel Settlement +- Room amount: 100,000 QU from player1 and 100,000 QU from player2. +- Total pot: 200,000 QU. +- Fees at default settings: + - devFee: 200,000 * 0.15% = 300 QU + - burnFee: 200,000 * 0.30% = 600 QU + - shareholdersFee: 200,000 * 0.55% = 1,100 QU +- Winner payout: 200,000 - (300 + 600 + 1,100) = 198,000 QU. +- Shareholders fee is split across RL holders; any remainder is burned. + +## Lifecycle Management +- END_TICK (every 10 ticks): refund expired rooms based on TTL hours. +- END_EPOCH: refund all open rooms and reset storage. + +# Technical implementation + +https://github.com/qubic/core/pull/705 From bebd6b6a5f3d23da936707e9deb541c54a9f3cfa Mon Sep 17 00:00:00 2001 From: N-010 Date: Thu, 25 Dec 2025 23:45:35 +0300 Subject: [PATCH 4/6] Delete SmartContracts/feature/2025-12-25-QDuel.md --- SmartContracts/feature/2025-12-25-QDuel.md | 60 ---------------------- 1 file changed, 60 deletions(-) delete mode 100644 SmartContracts/feature/2025-12-25-QDuel.md diff --git a/SmartContracts/feature/2025-12-25-QDuel.md b/SmartContracts/feature/2025-12-25-QDuel.md deleted file mode 100644 index 216dd14..0000000 --- a/SmartContracts/feature/2025-12-25-QDuel.md +++ /dev/null @@ -1,60 +0,0 @@ -QDuel Contract Proposal - -# Proposal - -## Available Options - -Option 0: No, do not upgrade the contract. - -Option 1: Yes, approve the upgrade to enable multi-asset functionality. - -## Overview -QDuel is a simple duel game contract where two players stake equal amounts, -and the winner receives the pooled amount minus configured fees. The contract -creates and manages duel rooms, handles winner selection, and distributes fees -to the team address, burn, and Random Lottery shareholders. - -## Motivation and Goals -- Provide a lightweight, on-chain duel mechanic with minimal state. -- Ensure fair settlement with deterministic winner selection. -- Refund funds if a duel does not resolve in time. -- Allow the team to tune fees and room TTL without redeploying. - -## Contract Summary -The contract maintains up to 512 active rooms. A room stores: -roomId, player1, optional allowedPlayer, amount, and creation timestamp. -Players interact through CreateRoom and ConnectToRoom. If a room expires before -it is joined, funds are returned to player1. All rooms are cleared at epoch end. - -## Current Fee Settings (from QDuel.h defaults) -- devFeePercent = 0.15% -- burnFeePercent = 0.30% -- shareholdersFeePercent = 0.55% -- total = 1% - -Shareholders fee is distributed to holders of the Random Lottery asset -(asset name RL). Distribution is proportional to shares owned at payout time. -Any remainder from integer division is burned. - -## Winner Selection -Winner is derived from the previous spectrum digest mixed with both player IDs -and the current tick, hashed via K12. The least significant bit selects either -the min or max player ID. This is deterministic and verifiable on-chain. - -## Example Duel Settlement -- Room amount: 100,000 QU from player1 and 100,000 QU from player2. -- Total pot: 200,000 QU. -- Fees at default settings: - - devFee: 200,000 * 0.15% = 300 QU - - burnFee: 200,000 * 0.30% = 600 QU - - shareholdersFee: 200,000 * 0.55% = 1,100 QU -- Winner payout: 200,000 - (300 + 600 + 1,100) = 198,000 QU. -- Shareholders fee is split across RL holders; any remainder is burned. - -## Lifecycle Management -- END_TICK (every 10 ticks): refund expired rooms based on TTL hours. -- END_EPOCH: refund all open rooms and reset storage. - -# Technical implementation - -https://github.com/qubic/core/pull/705 From 1b6662f0c81d35a88aea6dbad80db00ab3933175 Mon Sep 17 00:00:00 2001 From: N-010 Date: Sat, 3 Jan 2026 19:27:10 +0300 Subject: [PATCH 5/6] Enhance QDuel contract proposal with detailed mechanics Expanded the QDuel contract proposal with detailed mechanics, fee structures, and lifecycle management. Added sections on room creation, winner selection, and auto-requeue functionalities. --- SmartContracts/2025-12-25-QDuel.md | 129 +++++++++++++++++++---------- 1 file changed, 86 insertions(+), 43 deletions(-) diff --git a/SmartContracts/2025-12-25-QDuel.md b/SmartContracts/2025-12-25-QDuel.md index 3f3d173..cf00e10 100644 --- a/SmartContracts/2025-12-25-QDuel.md +++ b/SmartContracts/2025-12-25-QDuel.md @@ -1,60 +1,103 @@ # QDuel Contract Proposal -# Proposal +## Overview -## Available Options +QDuel is a duel contract with reusable player balances. A room owner posts a +stake, another player matches it, and the winner receives the pooled amount +minus fees. Owners can keep a deposit on the contract to auto-open a new room +after each duel or timeout. -Option 0: No, do not upgrade the contract. +## Motivation and Goals +- Keep duels lightweight with bounded storage. +- Provide deterministic, verifiable winner selection. +- Allow optional rematching with configurable stake growth. +- Refund or recycle funds when rooms expire. +- Let the team adjust fees and TTL without redeploying. -Option 1: Yes, approve the upgrade to enable multi-asset functionality. +## Contract Summary +The contract maintains up to 512 active rooms. Each room stores: +roomId, owner, allowedPlayer (optional), amount, closeTimer, and lastUpdate. +A separate users map tracks the room owner profile: +roomId, depositedAmount, locked, stake, raiseStep, and maxStake. -## Overview -QDuel is a simple duel game contract where two players stake equal amounts, -and the winner receives the pooled amount minus configured fees. The contract -creates and manages duel rooms, handles winner selection, and distributes fees -to the team address, burn, and Random Lottery shareholders. +## Key Parameters and Defaults +- minimumDuelAmount = 10,000 QU +- ttlHours = 3 +- fee scale = 1000 (1.00% = 10 bps) +- devFeePercentBps = 15 (0.15%) +- burnFeePercentBps = 30 (0.30%) +- shareholdersFeePercentBps = 55 (0.55%) +- asset for shareholders distribution: Random Lottery (RL, assetName 19538) +- tick maintenance period: every 100 ticks -## Motivation and Goals -- Provide a lightweight, on-chain duel mechanic with minimal state. -- Ensure fair settlement with deterministic winner selection. -- Refund funds if a duel does not resolve in time. -- Allow the team to tune fees and room TTL without redeploying. +## Room Creation +CreateRoom(owner, allowedPlayer, stake, raiseStep, maxStake): +- invocationReward must be >= minimumDuelAmount and >= stake. +- stake is locked in the room; any extra sent becomes depositedAmount. +- each owner can have only one active room. +- roomId is derived from tick and invocator data; collisions are retried. -## Contract Summary -The contract maintains up to 512 active rooms. A room stores: -roomId, player1, optional allowedPlayer, amount, and creation timestamp. -Players interact through CreateRoom and ConnectToRoom. If a room expires before -it is joined, funds are returned to player1. All rooms are cleared at epoch end. - -## Current Fee Settings (from QDuel.h defaults) -- devFeePercent = 0.15% -- burnFeePercent = 0.30% -- shareholdersFeePercent = 0.55% -- total = 1% - -Shareholders fee is distributed to holders of the Random Lottery asset -(asset name RL). Distribution is proportional to shares owned at payout time. -Any remainder from integer division is burned. - -## Winner Selection -Winner is derived from the previous spectrum digest mixed with both player IDs -and the current tick, hashed via K12. The least significant bit selects either -the min or max player ID. This is deterministic and verifiable on-chain. - -## Example Duel Settlement +## Room Join and Settlement +ConnectToRoom(roomId): +- joining player must send at least room.amount; excess is refunded. +- winner = K12(prevSpectrumDigest XOR player ids XOR tick), LSB picks min/max id. +- if winner derivation fails, both stakes are refunded and the room is closed. +- otherwise, the pooled amount is split into: + - devFee -> teamAddress + - burnFee -> burned + - shareholdersFee -> RL holders (remainder burned) + - winner -> winner payout + +## Fees and Shareholders Distribution + +Fee percentages are set in basis points over the scale 1000. The shareholder +portion is rounded down to a value that can be evenly distributed per share. +Distribution uses dividendPerShare = shareholdersFee / NUMBER_OF_COMPUTORS. +Each RL holder receives shares * dividendPerShare, and any remainder is burned. + +## Example Duel Settlement (default fees) - Room amount: 100,000 QU from player1 and 100,000 QU from player2. - Total pot: 200,000 QU. -- Fees at default settings: +- Fees: - devFee: 200,000 * 0.15% = 300 QU - burnFee: 200,000 * 0.30% = 600 QU - - shareholdersFee: 200,000 * 0.55% = 1,100 QU + - shareholdersFee: 200,000 * 0.55% = 1,100 QU (rounded down if needed) - Winner payout: 200,000 - (300 + 600 + 1,100) = 198,000 QU. -- Shareholders fee is split across RL holders; any remainder is burned. + +## Auto-Requeue and Deposits +Room owners can keep a deposit on the contract: +- Deposit adds to depositedAmount. +- Withdraw removes free depositedAmount (not locked stakes). +- After a duel, only depositedAmount is considered for auto-requeue. +- After a timeout, depositedAmount + locked stake are considered. + +## Next stake is computed as: +- If raiseStep > 1, nextStake = stake * raiseStep. +- nextStake is capped by maxStake if provided. +- If nextStake < minimumDuelAmount, funds are returned and the user profile + is removed. +- If room creation fails, all available funds are returned and the user profile + is removed. ## Lifecycle Management -- END_TICK (every 10 ticks): refund expired rooms based on TTL hours. -- END_EPOCH: refund all open rooms and reset storage. +- BEGIN_EPOCH locks the contract until the default RL init time is reached. +- END_TICK runs every 100 ticks to decrement room timers and finalize expired + rooms. +- Room timers use lastUpdate to avoid large gaps across epochs. + +## Admin Controls +- SetPercentFees: teamAddress only; total fee must be < 100%. +- SetTTLHours: teamAddress only; ttlHours must be > 0. +- GetPercentFees, GetTTLHours, GetRooms, GetUserProfile are public queries. -# Technical implementation +## Limitations and Risks +- Deterministic randomness can be influenced by entities affecting the previous + spectrum digest; the digest is external to this contract. +- Only room owners are tracked; joiners have no stored profile. +- Auto-requeue depends on available deposits and minimumDuelAmount. +- Fee misconfiguration can shrink winner payouts. -https://github.com/qubic/core/pull/705 +## Conclusion +QDuel provides a compact duel system with adjustable fees, configurable room +TTL, and optional auto-requeue mechanics based on owner deposits. The design +keeps state bounded while supporting repeat play without redeploys. From a97fb09c929000ae8e24f9e5b7f083624cdacfc2 Mon Sep 17 00:00:00 2001 From: N-010 Date: Sat, 3 Jan 2026 19:29:59 +0300 Subject: [PATCH 6/6] Add options and code reference to QDuel documentation Added available options section and code reference. --- SmartContracts/2025-12-25-QDuel.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/SmartContracts/2025-12-25-QDuel.md b/SmartContracts/2025-12-25-QDuel.md index cf00e10..08619ef 100644 --- a/SmartContracts/2025-12-25-QDuel.md +++ b/SmartContracts/2025-12-25-QDuel.md @@ -101,3 +101,11 @@ Room owners can keep a deposit on the contract: QDuel provides a compact duel system with adjustable fees, configurable room TTL, and optional auto-requeue mechanics based on owner deposits. The design keeps state bounded while supporting repeat play without redeploys. + +# Available Options +> Option 0: no, dont allow + +> Option 1: yes, allow + +# Code +[PR](https://github.com/qubic/core/pull/705)