Betting - 0002

SRCS/SRC-0002.md

@@ -0,0 +1,131 @@
+# SRC-0002: On-Chain Betting Metaprotocol
+
+| **SRC** | 002 |
+| --- | --- |
+| **Title** | On-Chain Betting Metaprotocol |
+| **Authors** | Johnny <johnny@empyrealsdk.com> |
+| **Status** | Draft |
+| **Created** | 2024-11-04 |
+| **Updated** | 2024-11-04 |
+| **License** | CC0 |
+
+---
+
+## Abstract
+
+SRC-0002 defines a metaprotocol for on-chain binary betting between two or more parties using an intent-based design. It specifies how intents are used to create, accept, and finalize wagers. The protocol includes an escrow for secure funds handling, allows the wager creator to set odds, and integrates an oracle that can return outcomes for binary wagers with additional conditions for ties or incomplete outcomes (win/lose/tie/undecided). This framework focuses on intent structure, escrow management, and oracle interactions, ensuring flexibility across platforms.
+
+## Motivation
+
+This metaprotocol facilitates secure, transparent on-chain betting between parties by using an intent-based structure. Its flexibility accommodates various platforms and decentralized systems, enabling automated, trustless betting without predefined contracts. By allowing odds customization and diverse outcome resolution, it supports fair play and efficient fund management.
+
+## Specification
+
+### 1. Intent Overview
+
+The metaprotocol relies on three core intents to facilitate betting interactions:
+- **Create Wager Intent**: Defines the wager’s parameters, including stake, odds, expiration, and oracle details.
+- **Accept Wager Intent**: Enables other parties to accept the wager (fully or partially).
+- **Finalize Wager Intent**: Allows the oracle to resolve the wager outcome and distribute funds based on the outcome.
+
+Each intent is time-sensitive, with an expiration parameter to manage time-limited actions. All interactions are handled within an escrow system until the wager is finalized.
+
+### 2. Create Wager Intent (SRC-0002.1)
+
+**Parameters**:
+- `wagerAmount`: `uint256` - The amount of cryptocurrency staked by the creator.
+- `odds`: `float` - Odds set by the creator (e.g., 1.5:1) for the counterparty’s payout.
+- `token`: `tokenID` - An identifier for the token accepted for the wager.
+- `expiry`: `timestamp` - Expiration date/time for the wager.
+- `oracle`: `ID` - ID of the oracle responsible for verifying the outcome. This can also be omitted to use the default oracle.
+- `oracleArgs`: `list[string]` - Parameters for the oracle to use in evaluating the outcome, such as the desired source for evaluation.
+- `allowPartial`: `bool` - Allows partial acceptance by multiple parties if true.
+- `escrowToken` (optional): `address` - Token address for the asset to be escrowed. Defaults to a standard token if omitted.
+- `acceptanceToken` (optional): `address` - Token address for the asset accepted by the counterparty. Defaults to the same token as escrowToken if omitted.
+
+**Process**:
+- The creator initiates a CreateWager intent, signaling the creation of a wager with specified terms, including the odds. The creator’s address is inferred from the initiating transaction.
+- Funds equivalent to the wagerAmount are locked in escrow, securing the creator’s stake until the wager is resolved.
+
+**Example**:
+
+```json
+{
+    "type": "CreateWager",
+    "wagerAmount": 1000,
+    "odds": 0.95,
+    "expiry": "2025-01-01T00:00:00Z",
+    "oracle": "@simOracle",
+    "oracleArgs": ["Tampa Bay Buccaneers vs. Kansas City Chiefs (Chiefs -9)", "source: espn.com"],
+    "allowPartial": true,
+    "escrowToken": "ETH",
+    "acceptanceToken": "USDC"
+}
+```
+
+### 3. Accept Wager Intent (SRC-0002.2)
+
+**Parameters**:
+- `acceptanceAmount`: `uint256` - Amount staked by the accepting party, which will determine potential winnings based on the creator’s odds.
+- `expiry`: `timestamp` - Expiration date/time for the acceptance intent.
+
+**Process**:
+- An interested party initiates an AcceptWager intent to accept the wager fully or partially, staking `acceptanceAmount`.
+- The AcceptWager intent must be initiated before the expiration of the original CreateWager intent.
+- Funds from the accepting party are placed into escrow, ensuring they are secure until the wager is resolved.
+
+**Example**:
+
+```json
+{
+    "type": "AcceptWager",
+    "acceptanceAmount": 500,
+    "expiry": "2025-01-01T00:00:00Z"
+}
+```
+
+### 4. Finalize Wager Intent (SRC-0002.3)
+
+**Parameters**:
+- `oracleVerification`: `object` - Contains proof or data needed by the oracle to finalize the wager outcome.
+- `outcome`: `enum {win, lose, tie, undecided}` - The result of the wager as determined by the oracle.
+
+**Process**:
+- Upon meeting the wager’s outcome conditions, the oracle issues a FinalizeWager intent, confirming the result as win, lose, tie, or undecided.
+
+**Example**:
+
+```json
+{
+    "type": "FinalizeWager",
+    "oracleVerification": {
+        "oracle": "0xOracleAddress",
+        "proof": "oracleProofData"
+    },
+    "outcome": "win"
+}
+```
+
+### 5. Escrow Mechanics
+
+- **Escrow Setup**: Funds are placed in escrow upon the creation and acceptance of the wager, ensuring they are only accessible upon wager resolution.
+- **Partial Acceptance**: If multiple parties accept portions of the wager, each party’s funds are separately escrowed and tracked.
+- **Funds Release**: Funds are distributed based on the oracle’s outcome result.
+
+## Security and Edge Cases
+
+- **Intent Expiry**: Expired intents are invalid and automatically voided.
+- **Oracle Failure**: In case of oracle failure or undecided result, the protocol should allow fallback mechanisms.
+- **Partial Acceptances**: Multiple acceptances require separate escrow tracking and are handled individually.
+
+## Rationale
+
+SRC-0002 is designed for flexibility, using inferred addresses for simplicity and reducing redundancy. Custom odds and varied outcome results create a balanced, fair betting protocol.
+
+## Backwards Compatibility
+
+SRC-0002 is a standalone metaprotocol, designed to be compatible with various decentralized betting systems.
+
+## Implementation Considerations
+
+This metaprotocol can be implemented across multiple blockchain ecosystems and supports integration with decentralized oracles. Each intent should use a standard encoding format (e.g., JSON or ABI-encoded) to ensure cross-platform compatibility.