MicroRival

A Telegram-native P2P prediction dueling protocol built on Somnia Shannon Testnet and powered by DreamDEX Event Contracts.

MicroRival lets users challenge each other 1v1 on binary price predictions (UP or DOWN) directly through Telegram. The smart contract holds stakes in escrow and settles automatically against DreamDEX market outcomes on-chain.

---

How It Works

1. Create a Duel: A user initiates a challenge via /duelo <amount> <up|down>. The bot selects an active DreamDEX binary market, registers the match on-chain, and locks the creator's stake (in native STT or ERC-20 tokens like USDso).
2. Accept Challenge: Another user clicks "Aceptar Desafío" in Telegram. This locks an equal stake and takes the opposite prediction.
3. Automated Settlement: A background worker monitors DreamDEX markets on Somnia. Once the target market resolves (isResolved() == true), the worker executes resolveMatch on-chain.
4. Payout: The winner receives the entire pool minus a 3% protocol fee. If a market is canceled/voided on DreamDEX, both players get a 100% refund with zero fees.

---

Architecture & Tech Stack

Telegram (grammY)  <--->  Node.js Backend (TypeScript + Viem)  <--->  SQLite (Prisma ORM)
                                   |
                                   v
             Somnia Shannon Testnet (Chain ID: 50312)
            ------------------------------------------
             • MicroRival.sol (Escrow & Settlement)
             • DreamDEX IBinaryMarket (On-chain Oracle & Outcomes)
             • @somnia-chain/markets-sdk (Market Discovery)

• Smart Contracts: Solidity ^0.8.24, self-contained with built-in reentrancy protection and fee-on-transfer token safety.
• On-Chain Oracle: Direct reads from DreamDEX IBinaryMarket (isResolved(), isVoided(), payoutNumerators()).
• SDK: @somnia-chain/markets-sdk for market fetching.
• Bot Framework: grammY with interactive inline keyboards.
• Web3 Client: Viem with typed ABI definitions.
• Database: SQLite managed via Prisma.

---

Smart Contract Details (MicroRival.sol)

• Contract File: src/contracts/MicroRival.sol
• Interfaces: src/contracts/IEventsContracts.sol
• Supported Tokens: Native STT (address(0)) and standard ERC-20 tokens (e.g., USDso).
• Fee Structure:
  • Resolution Fee: 3.0% (300 BPS)
  • Cancel Fee: 0.5% (50 BPS, applies only if canceled before acceptance)

Key Functions

• createMatch(bytes32 matchId, address marketAddress, address token, uint256 amount, uint8 prediction)
• acceptMatch(bytes32 matchId)
• cancelMatch(bytes32 matchId)
• resolveMatch(bytes32 matchId)
• withdrawFees(address token) (Owner only)

---

Telegram Bot Commands

Command	Description
/start	Registers user and shows welcome instructions
/wallet <0x...>	Links a Somnia testnet public wallet to your Telegram profile
/markets	Lists active DreamDEX prediction markets on Somnia
/profile	Shows your linked wallet, active challenges, and win stats
/duel <amount> <up|down>	Creates a new 1v1 challenge (e.g., /duel 0.05 up)

---

Local Setup

1. Prerequisites

• Node.js v20+
• npm or pnpm

2. Clone and Install

git clone <repo-url>
cd microrival
npm install

3. Environment Variables

Create or update your .env file:

BOT_TOKEN=your_telegram_bot_token
RPC_URL=https://somnia.publicnode.com/
PRIVATE_KEY=your_operator_private_key
CONTRACT_ADDRESS=0x_deployed_microrival_address
DATABASE_URL="file:./dev.db"

4. Database Setup

Push the schema to your local SQLite database:

npx prisma db push

5. Deploy Contract (Remix IDE)

1. Open Remix IDE.
2. Load src/contracts/MicroRival.sol and src/contracts/IEventsContracts.sol.
3. Select compiler 0.8.24 and deploy to Somnia Shannon Testnet (Chain ID: 50312).
4. Copy the deployed address into CONTRACT_ADDRESS in .env.

6. Start the Application

npx tsx src/index.ts

---

Somnia Shannon Testnet Info

• Network Name: Somnia Shannon Testnet
• Chain ID: 50312
• Currency Symbol: STT
• RPC URL: https://somnia.publicnode.com/ or https://dream-rpc.somnia.network
• Explorer: https://shannon-explorer.somnia.network

---

License

MIT