iOS App

Overview

The LightChallenge iOS app is a full-featured SwiftUI fitness challenge client targeting iOS 17+. Users can discover challenges, join with an on-chain stake, have proof submitted automatically during the proof window, and claim rewards — all from their iPhone.

Key capabilities:

• Fitness challenges — full mobile participation: join, auto-proof (Apple Health / Strava / Fitbit / Garmin), claim rewards.
• Gaming challenges — discovery and browsing only. Gaming cards display a “Desktop Only” badge; tapping opens a desktop-handoff modal.
• 4-tab layout — Explore, Challenges, Achievements, Profile.
• Wallet integration — Reown (WalletConnect v2) for on-chain transactions.
• HealthKit — reads 7 fitness metrics for the exact challenge period and submits them as evidence.
• OAuth account linking — Strava, Fitbit, and Garmin via ASWebAuthenticationSession.
• Deep links — challenge invites and OAuth callbacks.
• Notifications — APNS push registration with server-synced notification feed.
• Offline support — file-based JSON cache for challenge data.

Architecture

Source Tree

Sources/
├── LightChallengeApp.swift                 # @main entry point, deep link routing, service init
├── Info.plist                              # App transport, HealthKit usage descriptions
├── LightChallengeApp.entitlements          # HealthKit, app groups
│
├── Models/
│   ├── Challenge.swift                     # ChallengeCategory, ChallengeMeta, MyChallenge
│   ├── Contracts.swift                     # LightChain config, contract addresses, ABI constants
│   ├── Models.swift                        # HealthKit data models (DailySteps, DailyDistance, etc.), ServerConfig
│   └── Templates.swift                     # Fitness challenge templates (steps, running, cycling, etc.)
│
├── Services/
│   ├── ABIEncoder.swift                    # Minimal Solidity ABI encoder for contract calls
│   ├── APIClient.swift                     # Network layer — challenge list, meta, activity, evidence
│   ├── AppState.swift                      # Persisted prefs (UserDefaults), navigation state, deep link target
│   ├── AutoProofService.swift              # Automatic proof collection + submission during proof window
│   ├── AvatarService.swift                 # Avatar local cache + server sync
│   ├── CacheService.swift                  # File-based JSON cache for offline challenge data
│   ├── ContractService.swift               # Typed contract interactions (create, join, claim, finalize)
│   ├── HealthKitService.swift              # HealthKit authorization, data collection, evidence submission
│   ├── NotificationService.swift           # APNS registration, notification feed management
│   ├── OAuthService.swift                  # Strava/Fitbit/Garmin OAuth linking via ASWebAuthenticationSession
│   └── WalletManager.swift                 # Reown AppKit wallet connection (WalletConnect v2)
│
├── Theme/
│   └── DesignTokens.swift                  # LC design system: colors, spacing, typography, adaptive surfaces
│
└── Views/
    ├── MainTabView.swift                   # Root TabView — Explore | Challenges | Achievements | Profile
    ├── ContentView.swift                   # Legacy root (pre-tab migration)
    │
    ├── Onboarding/
    │   ├── OnboardingView.swift            # First-run onboarding flow
    │   └── SplashPortal.swift              # Animated splash screen
    │
    ├── Explore/
    │   ├── ExploreView.swift               # Challenge discovery — sectioned: Featured, Fitness, Trending, Gaming
    │   └── ChallengeRow.swift              # Individual challenge card in explore lists
    │
    ├── Challenges/
    │   └── ChallengesView.swift            # "My Challenges" — joined/created challenges
    │
    ├── Detail/
    │   ├── ChallengeDetailView.swift       # Full challenge detail with lifecycle-aware CTAs
    │   ├── FitnessProofView.swift          # Fitness proof submission UI
    │   ├── GamingHandoffView.swift         # Desktop-only modal for gaming challenges
    │   └── VictoryCelebrationView.swift    # Animated celebration on challenge pass
    │
    ├── Achievements/
    │   ├── AchievementsView.swift          # Trophy/badge collection
    │   ├── AchievementShareCard.swift      # Shareable achievement card
    │   └── ChallengeShareCard.swift        # Shareable challenge completion card
    │
    ├── Activity/
    │   └── MyActivityView.swift            # Activity feed / history
    │
    ├── Claims/
    │   └── ClaimsView.swift                # Claim reward interface (winner/loser/refund)
    │
    ├── Create/
    │   └── CreateChallengeView.swift        # On-chain challenge creation (fitness templates)
    │
    ├── Leaderboard/
    │   └── LeaderboardView.swift           # Per-challenge leaderboard
    │
    ├── Library/
    │   └── ProofSelectionView.swift        # Proof method picker (Apple Health, Strava, manual)
    │
    ├── Notifications/
    │   └── NotificationsView.swift         # Notification center
    │
    ├── Profile/
    │   └── ProfileView.swift               # User profile, linked accounts, settings entry
    │
    ├── Settings/
    │   ├── SettingsView.swift              # App settings (server URL, lookback, preferences)
    │   ├── AvatarView.swift                # Avatar display component
    │   └── AvatarPickerView.swift          # Avatar selection / upload
    │
    └── Wallet/
        └── WalletSheet.swift               # Wallet connection sheet (Reown AppKit)

Key Services

Challenge Lifecycle (iOS)

The app guides users through the full challenge lifecycle with context-aware UI:

1. Join Window

The Explore tab shows fitness challenges in sectioned layout (Featured, Fitness, Trending, Gaming). Each fitness challenge card displays a “Join” CTA. Tapping opens ChallengeDetailView, where the user stakes LCAI tokens via ContractService.joinChallengeNative().

Gaming challenges appear with a “Desktop Only” badge. Tapping opens GamingHandoffView with instructions to complete the challenge on the web app.

2. Challenge Period (Active Progress Sync)

After joining, the detail view shows “Challenge In Progress” with a countdown timer to the end date. The user completes the fitness activity (steps, running, cycling, etc.) during this period. The Challenges tab (ChallengesView) lists all joined/created challenges with live status.

Apple Health progress is pushed automatically every ~15 minutes while the app is open. AutoProofService.syncActiveProgress() collects HealthKit data from the challenge start to the current time and uploads it to /api/aivm/intake. This keeps the progress ring on the challenge detail view up to date without waiting for the proof window.

Server-side providers (Strava, Fitbit, OpenDota, Riot, FACEIT) are synced by the backend progressSyncWorker every 15 minutes — the iOS app does not need to take any action for these.

3. Proof Window

Once the challenge period ends (endTs < now < proofDeadlineTs), AutoProofService triggers automatically:

4. Verdict and Claim

After evidence submission, the detail view shows phase-aware status:

On pass, a “Claim Reward” button appears, which calls ContractService to execute the on-chain claim. A VictoryCelebrationView animation plays on successful claims.

When a challenge fails, the detail view displays up to 3 verdict reasons from the evaluator (e.g. “Did not meet step threshold”, “Insufficient activity days”) so users understand why.

Auto-Proof System

AutoProofService is a @MainActor singleton that manages both active-period progress sync and proof window auto-submission.

ProofStatus Enum

The service tracks per-challenge status via @Published var status: [String: ProofStatus]:

Two Modes of Operation

1. Active-Period Progress Sync (during challenge: startTs <= now < endTs)

• syncActiveProgress() pushes Apple Health data every ~15 minutes per challenge
• syncActiveChallenges() batch-syncs all joined active challenges on app launch / foreground
• Collects HealthKit data from challenge start to NOW (partial period)
• Uploads to /api/aivm/intake — server upserts evidence for the (challenge, subject, apple) triple
• Throttled to once per 15 minutes per challenge to avoid excessive uploads
• Non-critical: failures silently fall back to waitingForWindow

2. Proof Window Auto-Submission (after challenge ends: endTs <= now < proofDeadlineTs)

• triggerAutoProof() is called when the user views a challenge in the proof window
• checkPendingChallenges() batch-checks all joined challenges on app launch / foreground
• Only triggers for fitness challenges (or unknown category). Gaming challenges are skipped.
• Skips challenges that already have evidence or a verdict.
• Allows retry from error or waitingForWindow states.

Submission Flow

triggerAutoProof(challengeId, challenge, appState, healthService)
  │
  ├─ isInActivePeriod? (startTs <= now < endTs)
  │   └─ Yes → syncActiveProgress() → push HealthKit data (start → now)
  │
  ├─ isInProofWindow? (endTs <= now < proofDeadlineTs)
  │   └─ No → status = .waitingForWindow
  │
  └─ Yes → autoSubmit()
       │
       ├─ Strategy 1: tryServerAutoProof()
       │   POST /api/challenge/{id}/auto-proof { subject: wallet }
       │   └─ "collected" or "already-submitted" → status = .submitted ✓
       │
       ├─ Strategy 2: submitViaAppleHealth()
       │   HealthKit collectEvidence(from: startDate, to: endDate)
       │   POST /api/aivm/intake (multipart/form-data)
       │   └─ ok=true → status = .submitted ✓
       │
       └─ Strategy 3: Request HealthKit auth → retry Strategy 2
            └─ No platform → status = .error("Connect a fitness platform")

HealthKit Integration

Supported Metrics

Wearable Integration via HealthKit

Many fitness wearables sync their data to Apple Health automatically via their companion iOS app:

Once HealthKit sync is enabled, the data flows automatically:

Wearable → Companion App → Apple Health → AutoProofService → LightChallenge Server

No manual export needed. The app shows an onboarding tip on the challenge detail view reminding users to enable HealthKit sync in their wearable’s companion app.

Access Model

• Read-only — no write permissions are requested.
• No clinical data — only fitness quantity types.
• Daily aggregates only — no raw samples, timestamps, or source device identifiers leave the device.

Date-Range Collection

HealthKitService provides two collection modes:

1. Challenge-period collection (primary): collectEvidence(from: challengeStart, to: challengeEnd) — collects data for exactly the challenge duration.
2. Lookback collection (legacy fallback): collectEvidence(days: 90) — used only when challenge dates are unavailable.

All 7 metrics are fetched concurrently via async let.

Submission Format

Evidence is submitted as multipart/form-data to POST /api/aivm/intake with:

• challengeId — the challenge identifier
• subject — the user’s wallet address
• modelHash — the AIVM model hash for the challenge type
• json — JSON payload containing daily aggregate arrays

Wallet Integration

Reown AppKit (WalletConnect v2)

WalletManager wraps the Reown AppKit SDK for wallet pairing and transaction signing:

• Project ID: Shared with the webapp (LightChain.walletConnectProjectId)
• Chain: LightChain Testnet v2 (chain ID 8200, RPC https://rpc.testnet.lightchain.ai)
• Native WebSocket: Uses URLSessionWebSocketTask directly (no Starscream dependency)
• Deep link handling: Processes wc: protocol links for wallet pairing callbacks

On-Chain Operations

ContractService + ABIEncoder handle all on-chain interactions:

Transaction Construction (Custom Chain Compatibility)

WalletManager.sendTransaction() bypasses the Reown SDK’s W3MJSONRPC.eth_sendTransaction helper and constructs raw WalletConnect Request objects directly. This is required because:

1. Array-wrapped params — MetaMask expects eth_sendTransaction params as [{txObj}] (JSON-RPC spec), but the SDK sends them as a flat dictionary.
2. Explicit gasPrice — LightChain (chain ID 8200) uses legacy gas pricing (no EIP-1559). Without an explicit gasPrice, MetaMask fails with “Cannot convert undefined value to object”.
3. Gas estimation — Each transaction includes an eth_estimateGas RPC call with a 20% buffer, plus an eth_gasPrice RPC call for the current gas price.

API Authentication (Mobile)

Mobile clients authenticate API writes using tx-receipt verification as a fallback when EIP-191 signature auth is not available (WalletConnect doesn’t support personal_sign after a transaction without a second wallet interaction).

The server verifies the on-chain transaction receipt:

1. Fetches the receipt from LightChain RPC
2. Confirms status == 0x1 (success)
3. Verifies from matches the claimed wallet address
4. Optionally verifies to matches the ChallengePay contract

This applies to POST /api/challenges (metadata save after creation) and POST /api/challenge/{id}/participant (join recording).

Contract Addresses (Testnet)

Platform Rules

When a user taps a gaming challenge card, ExploreView presents GamingHandoffView — a modal explaining that gaming challenges require a desktop browser and providing a link to the web app.

Deep Links

The app registers the lightchallengeapp:// URL scheme and handles two link patterns:

Challenge Invite

lightchallengeapp://challenge/{id}?subject={wallet}&token={token}&expires={expiry}

On receipt, AppState.handleDeepLink() sets deepLinkChallengeId, and the app navigates to the challenge detail view. The token and expiry are passed to HealthKitService for authenticated evidence submission.

OAuth Callback

lightchallengeapp://auth/callback?provider={strava|fitbit}&status=ok

Returned after completing an OAuth flow in ASWebAuthenticationSession. OAuthService processes the callback and refreshes linked account status.

Universal Links

The app also supports universal links:

https://uat.lightchallenge.app/challenge/{id}?subject={wallet}

Setup and Build

Requirements

• Xcode 15.0 or later
• iOS 17.0+ deployment target
• Swift 5.9
• Physical iPhone — HealthKit is not available in the iOS Simulator
• Apple Developer account — free tier works for personal testing

Project Generation

The project uses XcodeGen with project.yml:

cd mobile/ios/LightChallengeApp
xcodegen generate

This regenerates LightChallengeApp.xcodeproj from the declarative spec. Key settings from project.yml:

• Bundle ID: io.lightchallenge.app
• Marketing version: 1.2.0
• Dependencies: ReownAppKit (from reown-swift package)
• Entitlements: HealthKit access, app groups (group.io.lightchallenge.app)

Server URL Configuration

Edit Sources/Models/Models.swift and set the appropriate base URL in ServerConfig:

The server URL can also be changed at runtime in Settings within the app.

Signing

1. Open LightChallengeApp.xcodeproj in Xcode
2. Select the project in the navigator
3. Go to Signing & Capabilities
4. Select your development team (automatic signing is preconfigured)
5. Xcode manages provisioning profiles automatically

Build

From the command line:

xcodebuild \
  -project mobile/ios/LightChallengeApp/LightChallengeApp.xcodeproj \
  -scheme LightChallengeApp \
  -destination 'generic/platform=iOS' \
  build

Or in Xcode: select your iPhone as the target device and press Cmd+R.

Design System

The app uses a centralized design token system defined in Theme/DesignTokens.swift (the LC enum):

• Primary accent: Deep electric blue (#2563EB)
• Semantic colors: success (green), danger (red), warning (yellow), info (blue)
• Adaptive surfaces: LC.pageBg(_:), LC.cardBg(_:), etc. respond to light/dark ColorScheme
• Dark mode: Slate-based palette (0F172A page, 1E293B cards) — follows system appearance

Troubleshooting