🔮 TimeLock Predictions

Decentralized prediction markets with immutable time-locked commitments on Stellar Soroban

---

🚀 Live Deployment

🌐 Frontend: https://arpit-jindal-01.github.io/TimeLock-Predictions/

Contract ID: CC2OBONLPDUPDMWJ34E77F2YKECLCWC5XS26EZG2KVV5OAS3LW4ZP2MD

View on Stellar Expert: Contract Explorer

---

🎯 What is TimeLock Predictions?

TimeLock Predictions is a blockchain-based prediction market where users stake tokens on future outcomes, but with a unique twist: answers are permanently locked in time capsules until the resolution date.

Unlike traditional prediction markets where users can change their minds, TimeLock creates immutable commitments. Users can't chicken out, can't change positions, and can't manipulate outcomes.

---

✨ Key Features

🔗 Smart Contract

• ✅ Immutable Commitments - Once staked, answers are locked on-chain forever
• ✅ Time-Locked - Enforced by Stellar smart contracts
• ✅ Proportional Payouts - Stake more, win more
• ✅ Anti-Spam - Creation fee + initial stake requirement
• ✅ Transparent Revenue - 5% platform fee, 70% creation fee to treasury
• ✅ Fully Tested - 10/10 comprehensive unit tests passing

🎨 Animated Frontend

• ✅ Rising Logo - Smooth animated entrance
• ✅ Floating Particles - Continuous background animation
• ✅ Dual Wallet Connection - Freighter + Manual public key
• ✅ Live XLM Balance - Real-time from Stellar network
• ✅ Instant Deductions - Visual balance updates (150 XLM per prediction)
• ✅ Analytics Dashboard - 4 Chart.js visualizations
• ✅ User Profile - History, stats, achievements
• ✅ Mobile Optimized - Responsive design for all devices
• ✅ Notification System - Browser + in-app notifications
• ✅ Social Sharing - Twitter, Telegram, WhatsApp

---

🔧 Tech Stack

Component	Technology
Blockchain	Stellar Soroban (Testnet)
Smart Contract	Rust
Frontend	HTML5, CSS3, JavaScript
Wallet	Freighter API
SDK	Stellar SDK v11.3.0
Charts	Chart.js v4.4.0
CLI Tool	Stellar CLI v23.1.4
Token	XLM (Stellar Lumens)
Network	Testnet
RPC URL	https://soroban-testnet.stellar.org
Horizon URL	https://horizon-testnet.stellar.org
Deployment	GitHub Pages

---

📦 Smart Contract Functions

Core Functions:

// Initialize contract
initialize(admin: Address)

// Create new prediction
create_prediction(
    creator: Address,
    question: String,
    unlock_time: u64,
    initial_choice: bool,
    token: Address
) -> u64

// Stake on prediction
stake(
    prediction_id: u64,
    user: Address,
    choice: bool,
    amount: i128,
    token: Address
)

// Resolve prediction (admin only)
resolve(
    admin: Address,
    prediction_id: u64,
    winner_choice: bool
)

// Claim winnings
claim(
    prediction_id: u64,
    user: Address,
    token: Address
) -> i128

Query Functions:

get_prediction(prediction_id: u64) -> Prediction
get_stake(prediction_id: u64, user: Address) -> Option<Stake>
get_prediction_count() -> u64
get_treasury() -> i128

Admin Functions:

withdraw_treasury(admin: Address, amount: i128, token: Address)

---

🚀 How It Works

1. Create Prediction

User → Pays 50 XLM creation fee + 100 XLM initial stake
     → Chooses YES or NO
     → Sets unlock time (must be 1+ hour in future)
     → Question stored on-chain

2. Others Stake

Users → Choose YES or NO
      → Lock minimum 100 XLM
      → Can't change answer once locked
      → Tokens go into prize pool

3. Time Lock

⏳ Prediction sealed until unlock time
❌ Cannot withdraw
❌ Cannot change answer
❌ Cannot resolve early

4. Resolution

After unlock time → Admin picks winner (YES/NO)
                 → Smart contract calculates payouts
                 → 5% platform fee deducted
                 → 95% distributed to winners proportionally

5. Claim Winnings

Winners → Call claim() function
       → Receive proportional share
       → Formula: (your_stake / winning_pool) × prize_pool

---

💰 Economics

Creation Fee: 50 XLM

• 70% (35 XLM) → Platform treasury
• 30% (15 XLM) → Burned (deflationary)

Platform Fee: 5% of prize pool

• Deducted on resolution
• Goes to platform treasury
• Industry standard rate

Minimum Stake: 100 XLM

• Prevents spam staking
• Ensures meaningful participation
• Required for prediction creators

---

� Frontend Quick Start

1. Access Live Site

Visit: https://arpit-jindal-01.github.io/TimeLock-Predictions/

2. Connect Wallet

Option A: Freighter Wallet (Recommended)

1. Install Freighter extension
2. Create/import wallet
3. Switch to Stellar Testnet
4. Click "Connect Freighter Wallet"
5. Approve connection

Option B: Manual Public Key

1. Click "Enter Public Key" button
2. Paste your Stellar public key (G...)
3. Click "Connect"
4. Sign transactions with Freighter

3. Get Test XLM

curl "https://friendbot.stellar.org?addr=YOUR_PUBLIC_KEY"

4. Create Your First Prediction

1. Check your XLM balance (top right)
2. Fill in prediction question
3. Set unlock date (future)
4. Choose your answer (Yes/No)
5. Click "Create Prediction"
6. Watch balance deduct 150 XLM instantly

5. Explore Features

• Analytics: View charts and statistics
• Profile: Check your prediction history
• Social: Share predictions on Twitter/Telegram
• Mobile: Works seamlessly on phones

---

�🏗️ Installation & Setup

Prerequisites:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Stellar CLI
cargo install --locked soroban-cli --features opt

# Verify installation
stellar --version

Build Contract:

cd contract
stellar contract build

Run Tests:

cargo test

---

📝 Deployment

1. Configure Identity

stellar keys generate admin --network testnet
stellar keys address admin

2. Fund Account (Friendbot)

curl "https://friendbot.stellar.org?addr=$(stellar keys address admin)"

3. Deploy Contract

stellar contract deploy \
  --wasm target/wasm32v1-none/release/timelock_predictions.wasm \
  --source admin \
  --network testnet

4. Initialize Contract

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source admin \
  --network testnet \
  -- initialize \
  --admin $(stellar keys address admin)

---

🧪 Testing

All Tests Passing ✅

running 10 tests
test test::test_initialize ... ok
test test::test_double_initialize - should panic ... ok
test test::test_create_prediction ... ok
test test::test_create_prediction_invalid_time - should panic ... ok
test test::test_create_prediction_short_question - should panic ... ok
test test::test_stake ... ok
test test::test_double_stake - should panic ... ok
test test::test_resolve_and_claim ... ok
test test::test_resolve_too_early - should panic ... ok
test test::test_claim_loser - should panic ... ok

test result: ok. 10 passed; 0 failed

Test Coverage:

• ✅ Contract initialization
• ✅ Prediction creation (valid & invalid)
• ✅ Staking mechanism
• ✅ Double-staking prevention
• ✅ Time lock enforcement
• ✅ Resolution logic
• ✅ Proportional payout calculation
• ✅ Winner/loser validation
• ✅ Edge cases & error handling

---

📊 Contract Constants

CREATION_FEE: 50 XLM (50_0000000 stroops)
MIN_STAKE: 100 XLM (100_0000000 stroops)
ONE_HOUR: 3600 seconds
PLATFORM_FEE: 5% of prize pool
TREASURY_SPLIT: 70% to treasury, 30% burned

---

🎮 Example Usage

Create Prediction:

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source creator \
  --network testnet \
  -- create_prediction \
  --creator $(stellar keys address creator) \
  --question "Will Bitcoin hit $100k by 2025?" \
  --unlock_time 1735689600 \
  --initial_choice true \
  --token <NATIVE_TOKEN_ADDRESS>

Stake on Prediction:

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source user \
  --network testnet \
  -- stake \
  --prediction_id 1 \
  --user $(stellar keys address user) \
  --choice false \
  --amount 2000000000 \
  --token <NATIVE_TOKEN_ADDRESS>

Resolve Prediction:

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source admin \
  --network testnet \
  -- resolve \
  --admin $(stellar keys address admin) \
  --prediction_id 1 \
  --winner_choice true

Claim Winnings:

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source winner \
  --network testnet \
  -- claim \
  --prediction_id 1 \
  --user $(stellar keys address winner) \
  --token <NATIVE_TOKEN_ADDRESS>

---

🔒 Security Features

• ✅ Authorization Checks - require_auth() on all user actions
• ✅ Admin Validation - Only admin can resolve predictions
• ✅ Time Lock Enforcement - Cannot resolve before unlock_time
• ✅ Double-Stake Prevention - One stake per user per prediction
• ✅ Input Validation - Question length, minimum stakes, time limits
• ✅ Overflow Protection - Safe integer math
• ✅ Reentrancy Safe - State updates before external calls

---

📈 Development Progress

Phase 1: Core Contract ✅ COMPLETE

• Smart contract with 10 functions
• Comprehensive test suite (10/10 passing)
• Deployed to testnet
• Zero warnings build

Phase 2: Frontend ✅ COMPLETE

• Animated UI with rising logo
• Freighter wallet integration
• Manual public key login
• Live XLM balance display
• Instant balance deductions
• Analytics dashboard
• User profile page
• Mobile optimization
• Notification system
• Social sharing
• GitHub Pages deployment

Phase 3: Future Enhancements

• Oracle integration (Chainlink) for automatic resolution
• Community voting for subjective questions
• Group predictions (friends compete)
• Reputation system
• NFT achievement badges
• Streak tracking (5-win, 10-win bonuses)
• Advanced leaderboard
• Mainnet deployment
• Custom domain

---

🐛 Known Limitations

• Manual Resolution: Currently requires admin to resolve predictions (oracle integration coming in Phase 2)
• Testnet Only: Not audited for mainnet deployment yet
• Single Token: Only supports native XLM token currently
• No Cancellation: Predictions cannot be cancelled once created (by design)

---

📄 License

MIT License - See LICENSE file for details

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure all tests pass
5. Submit a pull request

---

📞 Support

• Issues: GitHub Issues
• Stellar Discord: Stellar Developers
• Documentation: Stellar Docs

---

⚠️ Disclaimer

This is experimental software. Use at your own risk. Not audited for production use. Test thoroughly before deploying to mainnet.

---

🎉 Built With

• 💚 Stellar Soroban
• 🦀 Rust
• ⚡ Stellar CLI
• 🧪 Thoroughly Tested

---

Made with 🔥 for the Stellar ecosystem