Tap Battle - Mobile-First Competitive Tapping Game

Transitional example: This example uses an older Cougr pattern and is preserved for compatibility reference. For the current recommended approach, see snake.

A competitive tapping game implemented as a Soroban smart contract using cougr-core's ECS framework with passkey authentication (secp256r1/WebAuthn) on the Stellar blockchain.

feat/session-manager-fresh

Related example: For the minimal session-only flow without passkeys or game mechanics, see session_arena.

🔐 Why Passkeys?

Why Passkeys?

Traditional blockchain games require seed phrases and per-transaction wallet prompts. Tap Battle eliminates both:

Passkeys use the secp256r1 curve (the same as WebAuthn/FIDO2), enabling biometric authentication natively on mobile devices without any crypto knowledge.

Mobile-First Authentication Flow

┌─────────────────────────────────────────────────────────┐
│ 1. REGISTRATION                                         │
│    Player registers passkey (secp256r1 public key)       │
│    → Secp256r1Storage persists the key on-chain          │
│    → No seed phrases, no mnemonics                       │
├─────────────────────────────────────────────────────────┤
│ 2. AUTHENTICATION + SESSION                              │
│    Player authenticates via passkey (Face ID / Touch ID)  │
│    → verify_secp256r1() validates the signature           │
│    → SessionManager::approve creates a gameplay session   │
│    → Session scoped to: tap, use_power_up                 │
├─────────────────────────────────────────────────────────┤
│ 3. GAMEPLAY (gasless via session key)                     │
│    Rapid tapping → tap(session_key) increments counter    │
│    Combos: consecutive taps within time window = multi    │
│    Power-ups: spend combo charges for burst effects       │
│    Round ends after N ledger sequences                    │
├─────────────────────────────────────────────────────────┤
│ 4. RENEWAL / FALLBACK                                     │
│    session_status → UI prompts when needs_renewal         │
│    renew_session → owner re-approves to extend play       │
│    fallback_tap → direct owner auth when session expires  │
├─────────────────────────────────────────────────────────┤
│ 5. RESULT                                                │
│    Compare scores → winner determined                    │
│    Stats recorded on-chain in PlayerProfile               │
└─────────────────────────────────────────────────────────┘

Cougr-Core Integration

This example showcases two key cougr-core features:

Passkey Authentication (secp256r1_auth)

#![allow(unused)]
fn main() {
use cougr_core::auth::{Secp256r1Key, Secp256r1Storage, verify_secp256r1};

// Register: store public key on-chain
Secp256r1Storage::store(&env, &player, &key);

// Authenticate: verify biometric signature
verify_secp256r1(&env, &pubkey, &message, &signature)?;
}

SessionManager Lifecycle

#![allow(unused)]
fn main() {
use cougr_core::accounts::SessionBuilder;
use cougr_core::session::SessionManager;

// 1. Approve once (after passkey auth)
let scope = SessionBuilder::new(&env)
    .allow_action(symbol_short!("tap"))
    .allow_action(symbol_short!("use_power"))
    .max_operations(500)
    .expires_in(duration)  // seconds from ledger timestamp
    .build_scope();
SessionManager::approve(&env, &player, scope)?;

// 2. Play many times without wallet prompts
SessionManager::execute_action(&env, &player, &session, action, intent_expires)?;

// 3. Poll health for renewal UI
let status = SessionManager::status(&env, &player, &key_id)?;

// 4. Renew before expiry (owner must require_auth)
SessionManager::renew(&env, &owner, &key_id, new_expires_at)?;

// 5. Fallback when session is stale
SessionManager::fallback_execute(&env, &session_intent, &direct_intent)?;
}

Sessions are managed by cougr_core::session::SessionManager - the same pattern as session_arena.

Duration semantics: Session expires_in / expires_at use ledger timestamps (seconds), not ledger sequence numbers. Round duration (start_round) still uses ledger sequences for combo timing.

ECS Components

Session state lives in SessionManager / SessionStorage - not as a custom ECS component.

Contract API

Authentication

Session Management

Gameplay

Power-Up Types

Game Mechanics

Combo System

Taps within 5 ledger sequences of each other maintain a combo streak:

Game Constants

️ Quick Start

Prerequisites

Build

# Standard Rust build
cargo build

# Build WASM for Soroban deployment
stellar contract build

Test

cargo test

Test Results: 17 tests passing ✅

Project Structure

examples/tap_battle/
├── Cargo.toml          # Dependencies: cougr-core 1.1.0 + soroban-sdk
├── README.md           # This documentation
└── src/
    ├── lib.rs          # Contract entry points
    ├── types.rs        # ECS Components (PasskeyIdentity, TapCounter, etc.)
    ├── auth.rs         # AuthSystem + SessionSystem (secp256r1 + SessionBuilder)
    ├── game.rs         # TapSystem, ComboSystem, PowerUpSystem, RoundSystem
    └── test.rs         # Unit tests (17 tests)

License

MIT OR Apache-2.0