feat: implement bet slip summary, oracle circuit breaker, and dispute UI

.env.example

@@ -1,6 +1,14 @@
 # Backend
 PORT=4000
 DATABASE_URL=postgresql://user:password@localhost:5432/stella_polymarket
+# Redis — used for rate limiting and market query caching.
+# Use REDIS_URL for a full connection string (takes precedence over individual vars).
+# Example: redis://user:password@host:6379
+REDIS_URL=redis://localhost:6379
+# Or use individual vars (used when REDIS_URL is not set):
+# REDIS_HOST=localhost
+# REDIS_PORT=6379
+# REDIS_PASSWORD=
 
 # Stellar
 STELLAR_NETWORK=testnet
@@ -9,5 +17,45 @@ CONTRACT_ID=your_contract_id_here
 
 # Oracle
 API_URL=http://localhost:4000
-SPORTS_API_KEY=your_key_here
+SPORTS_API_KEY=your_api_football_key_here
 FINANCIAL_API_KEY=your_key_here
+SPORTS_API_URL=https://v3.football.api-sports.io
+# CoinMarketCap API key — required for the 5th price feed in the multi-source aggregator.
+# Get a free key at https://coinmarketcap.com/api/
+# NEVER commit this value. Add to your secrets manager / CI env.
+CMC_API_KEY=your_coinmarketcap_api_key_here
+
+# CoinGecko API key — optional but recommended to avoid free-tier rate limits (10-30 req/min).
+# Get a free Demo key at https://www.coingecko.com/en/api
+# NEVER commit this value. Add to your secrets manager / CI env.
+COINGECKO_API_KEY=your_coingecko_api_key_here
+
+# Sports Oracle — Stellar on-chain resolution
+# ORACLE_SECRET_KEY must NEVER be committed. Add to your secrets manager / CI env.
+ORACLE_SECRET_KEY=your_stellar_oracle_secret_key_here
+POLL_INTERVAL_MS=60000
+
+# Firebase (Frontend)
+NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
+NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
+NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
+NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
+NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
+NEXT_PUBLIC_FIREBASE_APP_ID=your_firebase_app_id
+
+# Firebase App Check
+# reCAPTCHA Enterprise site key (from Google Cloud Console → reCAPTCHA Enterprise)
+# Required in production. Leave empty to disable App Check (not recommended).
+NEXT_PUBLIC_RECAPTCHA_ENTERPRISE_KEY=your_recaptcha_enterprise_site_key
+
+# App Check debug token for local development ONLY.
+# Generate one via: Firebase Console → App Check → Apps → your app → "..." → Manage debug tokens
+# NEVER commit a real debug token. Add this file to .gitignore.
+# Only active when NODE_ENV !== 'production'.
+NEXT_PUBLIC_APPCHECK_DEBUG_TOKEN=your_debug_token_here
+
+# Firebase Admin (Backend)
+# Path to a service account JSON with "Firebase App Check Admin" role.
+# In Cloud Run / Cloud Functions leave blank – ADC is used automatically.
+GOOGLE_APPLICATION_CREDENTIALS=./service-account.json
+FIREBASE_PROJECT_ID=your_project_id

.eslintrc.js

@@ -46,6 +46,11 @@ module.exports = {
         "@typescript-eslint/no-explicit-any": "off",
       },
     },
+    {
+      // Jest globals for test files
+      files: ["**/*.test.js", "**/*.test.ts", "**/*.test.tsx", "**/*.spec.js"],
+      env: { jest: true },
+    },
   ],
   ignorePatterns: ["node_modules/", ".next/", "dist/", "target/"],
 };

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,26 +1,62 @@
-## Summary
-Brief description of what this PR does.
+# Automated Market Settlement Logic (#11)
 
-## Related Issue
-Closes #(issue number)
+## Description
 
-## Type of Change
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Refactor
-- [ ] Documentation update
-- [ ] Other (describe):
+Implements the automated market settlement logic that processes an Oracle's "Result" and calculates winning shares with precise fixed-point arithmetic.
 
-## Changes Made
-- 
-- 
+## Changes
+
+### New Files
+- [`contracts/prediction_market/src/settlement_math.rs`](contracts/prediction_market/src/settlement_math.rs) - Settlement math module with fixed-point arithmetic
+- [`docs/math_spec.md`](docs/math_spec.md) - Mathematical specification and payout formula documentation
+
+### Modified Files
+- [`contracts/prediction_market/src/lib.rs`](contracts/prediction_market/src/lib.rs) - Added `distribute_rewards()` and `get_settlement_info()` functions
+
+## Key Features
+
+### Fixed-Point Arithmetic
+- Uses 7 decimal places of precision (10^7) for calculations
+- No floating-point operations to avoid precision loss
+- All monetary values stored as integers
+
+### Payout Formula
+```
+payout_pool = floor(total_pool × 97 / 100)  // 3% platform fee
+individual_payout = floor(bet_amount × payout_pool / winning_stake)
+```
+
+### Dust Handling
+The implementation ensures 100% conservation by redistributing dust (remainder from integer division):
+1. Calculate ideal payouts using integer division
+2. Track dust: `dust = payout_pool - sum(payouts)`
+3. Redistribute dust in 1-unit increments to first N winners
+
+### Market State Transition
+- `resolve_market()` transitions market from Locked → Resolved
+- `distribute_rewards()` executes payout calculation and transfers
 
 ## Testing
-Describe how you tested your changes.
-
-## Checklist
-- [ ] My code follows the project's style guidelines
-- [ ] I have performed a self-review of my code
-- [ ] I have commented complex logic where necessary
-- [ ] I have updated documentation if needed
-- [ ] My changes don't introduce new warnings or errors
+
+**All 15 tests passing:**
+- `test_platform_fee` - 3% fee calculation
+- `test_payout_pool` - 97% payout pool calculation
+- `test_basic_payout` - Single and multiple bettor scenarios
+- `test_exact_division` - Cases with no dust
+- `test_dust_redistribution` - Dust handling verification
+- `test_zero_winning_stake` - Edge case handling
+- `test_large_amounts` - Real XLM amount simulation
+- `test_conservation_property` - All payouts sum to payout_pool
+
+## Documentation
+
+See [`docs/math_spec.md`](docs/math_spec.md) for:
+- Payout formula derivation
+- Dust handling algorithm explanation
+- Conservation property proof
+- Edge case handling
+- Security considerations
+
+## Related Issues
+
+Closes #11

.github/workflows/contract-attestation.yml

@@ -0,0 +1,188 @@
+name: Contract Source Attestation (SEP-0157)
+
+# Triggers on version tags only — e.g. v1.0.0-mvp, v1.2.3
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+# Required permissions for GitHub Attestations API
+permissions:
+  contents: read
+  id-token: write       # needed to mint the OIDC token for attestation signing
+  attestations: write   # needed to write the attestation to GitHub
+
+env:
+  RUST_VERSION: "1.79.0"
+  WASM_PATH: contracts/prediction_market/target/wasm32-unknown-unknown/release/prediction_market.wasm
+  OPTIMIZED_WASM_PATH: contracts/prediction_market/target/wasm32-unknown-unknown/release/prediction_market.optimized.wasm
+
+jobs:
+  # ── 1. Reproducible WASM build ────────────────────────────────────────────
+  build-wasm:
+    name: Reproducible WASM Build
+    runs-on: ubuntu-latest
+
+    outputs:
+      wasm-hash: ${{ steps.hash.outputs.wasm-hash }}
+      tag: ${{ steps.tag.outputs.tag }}
+
+    steps:
+      - name: Checkout repository (full history)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract tag name
+        id: tag
+        run: echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Setup Rust toolchain (pinned for reproducibility)
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: ${{ env.RUST_VERSION }}
+          target: wasm32-unknown-unknown
+          cache: true
+
+      - name: Cache Cargo dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: "contracts/prediction_market"
+
+      - name: Build WASM (release)
+        working-directory: ./contracts/prediction_market
+        run: |
+          echo "🔨 Building WASM for tag ${{ steps.tag.outputs.tag }}..."
+          # Set SOURCE_DATE_EPOCH for reproducible builds
+          export SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)
+          cargo build --target wasm32-unknown-unknown --release
+          echo "✅ WASM build complete"
+
+      - name: Install Soroban CLI (for optimization)
+        run: |
+          cargo install cargo-binstall --locked
+          cargo binstall soroban-cli --secure --locked -y
+
+      - name: Optimize WASM with soroban contract optimize
+        working-directory: ./contracts/prediction_market
+        run: |
+          soroban contract optimize \
+            --wasm ${{ env.WASM_PATH }} \
+            --wasm-out ${{ env.OPTIMIZED_WASM_PATH }}
+          echo "✅ WASM optimized"
+
+      - name: Compute WASM SHA-256 hash
+        id: hash
+        run: |
+          HASH=$(sha256sum ${{ env.OPTIMIZED_WASM_PATH }} | awk '{print $1}')
+          echo "wasm-hash=$HASH" >> $GITHUB_OUTPUT
+          echo "### 🔐 WASM SHA-256" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "\`$HASH\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Commit: \`${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "Tag: \`${{ steps.tag.outputs.tag }}\`" >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload WASM artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: prediction-market-wasm-${{ steps.tag.outputs.tag }}
+          path: |
+            ${{ env.WASM_PATH }}
+            ${{ env.OPTIMIZED_WASM_PATH }}
+          retention-days: 90
+
+  # ── 2. GitHub Attestation (SEP-0157) ──────────────────────────────────────
+  attest:
+    name: Generate GitHub Attestation
+    runs-on: ubuntu-latest
+    needs: build-wasm
+
+    steps:
+      - name: Download WASM artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: prediction-market-wasm-${{ needs.build-wasm.outputs.tag }}
+          path: ./wasm-output
+
+      - name: Generate GitHub build attestation
+        id: attest
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: ./wasm-output/prediction_market.optimized.wasm
+
+      - name: Log attestation details
+        run: |
+          echo "### ✅ GitHub Attestation Generated" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Field | Value |" >> $GITHUB_STEP_SUMMARY
+          echo "|-------|-------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Tag | \`${{ needs.build-wasm.outputs.tag }}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Commit SHA | \`${{ github.sha }}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| WASM SHA-256 | \`${{ needs.build-wasm.outputs.wasm-hash }}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Attestation URL | ${{ steps.attest.outputs.bundle-path }} |" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Verify at: https://github.com/Idrhas/Stellar-PolyMarket/attestations" >> $GITHUB_STEP_SUMMARY
+
+  # ── 3. Create GitHub Release with WASM + attestation bundle ──────────────
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [build-wasm, attest]
+
+    permissions:
+      contents: write
+      attestations: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download WASM artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: prediction-market-wasm-${{ needs.build-wasm.outputs.tag }}
+          path: ./wasm-output
+
+      - name: Create release with WASM binary
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.build-wasm.outputs.tag }}
+          name: "Prediction Market ${{ needs.build-wasm.outputs.tag }}"
+          body: |
+            ## Prediction Market Contract — ${{ needs.build-wasm.outputs.tag }}
+
+            ### 🔐 Source Attestation (SEP-0157)
+            This release includes a GitHub-signed build attestation linking the
+            compiled WASM binary to commit `${{ github.sha }}`.
+
+            **WASM SHA-256:**
+            ```
+            ${{ needs.build-wasm.outputs.wasm-hash }}
+            ```
+
+            ### Verify the attestation
+            ```bash
+            # 1. Install Soroban CLI
+            cargo install soroban-cli --locked
+
+            # 2. Download the WASM from this release
+            curl -L -o prediction_market.optimized.wasm \
+              https://github.com/Idrhas/Stellar-PolyMarket/releases/download/${{ needs.build-wasm.outputs.tag }}/prediction_market.optimized.wasm
+
+            # 3. Hash it locally and compare
+            sha256sum prediction_market.optimized.wasm
+
+            # 4. Verify via GitHub CLI
+            gh attestation verify prediction_market.optimized.wasm \
+              --repo Idrhas/Stellar-PolyMarket
+            ```
+
+            ### View attestation
+            https://github.com/Idrhas/Stellar-PolyMarket/attestations
+          files: |
+            ./wasm-output/prediction_market.wasm
+            ./wasm-output/prediction_market.optimized.wasm
+          draft: false
+          prerelease: ${{ contains(needs.build-wasm.outputs.tag, 'alpha') || contains(needs.build-wasm.outputs.tag, 'beta') || contains(needs.build-wasm.outputs.tag, 'rc') }}