Feat/examples sandbox tests

.github/workflows/circuit_examples.yml

@@ -46,14 +46,25 @@ jobs:
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32v1-none
 
       - name: Cache dependencies
         uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: examples/${{ matrix.example }}
 
       - name: Test ${{ matrix.example }}
         working-directory: examples/${{ matrix.example }}
         run: cargo test
 
+      - name: Install Stellar CLI
+        uses: stellar/stellar-cli@v25.1.0
+
+      - name: Stellar contract build
+        working-directory: examples/${{ matrix.example }}
+        run: stellar contract build
+
   circuits-lib:
     name: Circuits Module
     runs-on: ubuntu-latest

.github/workflows/session_arena.yml

@@ -0,0 +1,28 @@
+name: Session Arena Example CI
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'examples/session_arena/**'
+      - '!examples/session_arena/**/*.md'
+      - '.github/workflows/example_reusable.yml'
+      - '.github/workflows/session_arena.yml'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'examples/session_arena/**'
+      - '!examples/session_arena/**/*.md'
+      - '.github/workflows/example_reusable.yml'
+      - '.github/workflows/session_arena.yml'
+
+concurrency:
+  group: session-arena-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    uses: ./.github/workflows/example_reusable.yml
+    with:
+      job_name: Session Arena Example CI
+      working_directory: examples/session_arena

.github/workflows/spawn_and_move.yml

@@ -0,0 +1,28 @@
+name: Spawn And Move Example CI
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'examples/spawn_and_move/**'
+      - '!examples/spawn_and_move/**/*.md'
+      - '.github/workflows/example_reusable.yml'
+      - '.github/workflows/spawn_and_move.yml'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'examples/spawn_and_move/**'
+      - '!examples/spawn_and_move/**/*.md'
+      - '.github/workflows/example_reusable.yml'
+      - '.github/workflows/spawn_and_move.yml'
+
+concurrency:
+  group: spawn-and-move-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    uses: ./.github/workflows/example_reusable.yml
+    with:
+      job_name: Spawn And Move Example CI
+      working_directory: examples/spawn_and_move

examples/README.md

@@ -83,11 +83,17 @@ them as the default onboarding path.
 
 The maintained reference architectures for Cougr should be read in this order:
 
-- `spawn_and_move`: **start here** — canonical onboarding example showing the full modern Cougr pattern
-- `tic_tac_toe`: turn-based game with rich components (`impl_rich_component!`) for `Address` and `Vec` fields
+- `spawn_and_move`: **start here** — canonical onboarding example showing the full modern Cougr pattern (`SorobanGame`, `impl_component_observed!`, typed ECS)
+- `tic_tac_toe`: turn-based game showing rich components (`impl_rich_component!`, `impl_soroban_game!`) for `Address` and `Vec` fields
+- `session_arena`: session lifecycle, authorization scopes, and fallback direct-auth flows (`SessionManager`)
 - `snake`: canonical arcade loop and `GameApp` tick model
 - `battleship`: canonical hidden-information / commit-reveal flow using `privacy::stable` Merkle primitives
 - `guild_arena`: canonical account recovery and multi-device authorization flow
+- **ZK Circuit Reference Examples**:
+  - `hidden_hand`: private card deals via `circuits::hidden_cards`
+  - `fog_explorer`: private line-of-sight map verification via `circuits::fog_of_war`
+  - `dice_duel`: verifiable on-chain dice rolling via `circuits::fair_dice`
+  - `blind_auction`: sealed-bid auction reveals via `circuits::sealed_bid`
 
 ## Conventions
 

examples/ai_dungeon_master_arena/.gitignore

@@ -0,0 +1,17 @@
+# Build artifacts
+target/
+*.wasm
+
+# Soroban
+.soroban/
+test_snapshots/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

examples/angry_birds/.gitignore

@@ -0,0 +1,17 @@
+# Build artifacts
+target/
+*.wasm
+
+# Soroban
+.soroban/
+test_snapshots/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

examples/angry_birds/Cargo.toml

@@ -3,7 +3,7 @@ name = "angry_birds"
 version = "0.1.0"
 edition = "2021"
 publish = false
-description = "Angry Birds turn-based physics puzzle using Cougr-Core ECS framework on Stellar Soroban"
+description = "Angry Birds turn-based physics puzzle using Cougr-Core ECS on Stellar Soroban"
 license = "MIT OR Apache-2.0"
 
 [lib]

examples/angry_birds/README.md

@@ -146,7 +146,7 @@ stellar network testnet
 stellar contract deploy \
   --wasm target/wasm32v1-none/release/angry_birds.wasm \
   --source <your-account> \
-  --network testnet
+  --network <NETWORK>
 
 # Note the contract ID for subsequent interactions
 ```
@@ -158,7 +158,7 @@ stellar contract deploy \
 stellar contract invoke \
   --id <contract-id> \
   --source <player-account> \
-  --network testnet \
+  --network <NETWORK> \
   -- init_level \
   --player <player-address> \
   --level_id 1
@@ -167,7 +167,7 @@ stellar contract invoke \
 stellar contract invoke \
   --id <contract-id> \
   --source <player-account> \
-  --network testnet \
+  --network <NETWORK> \
   -- shoot \
   --player <player-address> \
   --angle 45000 \
@@ -177,7 +177,7 @@ stellar contract invoke \
 stellar contract invoke \
   --id <contract-id> \
   --source <any-account> \
-  --network testnet \
+  --network <NETWORK> \
   -- get_state
 ```
 

examples/arkanoid/.gitignore

@@ -0,0 +1,17 @@
+# Build artifacts
+target/
+*.wasm
+
+# Soroban
+.soroban/
+test_snapshots/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

examples/arkanoid/README.md

@@ -113,10 +113,10 @@ Get test XLM from Friendbot:
 
 ```bash
 # Generate a new keypair
-stellar keys generate alice --network testnet
+stellar keys generate alice --network <NETWORK>
 
 # Fund the account
-stellar keys fund alice --network testnet
+stellar keys fund alice --network <NETWORK>
 ```
 
 Or use the web faucet: https://faucet-stellar.acachete.xyz
@@ -131,10 +131,10 @@ stellar contract build
 stellar contract deploy \
   --wasm target/wasm32v1-none/release/arkanoid.wasm \
   --source alice \
-  --network testnet
+  --network <NETWORK>
 ```
 
-Save the contract ID returned (e.g., `CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX`).
+Save the contract ID returned (e.g., `<CONTRACT_ID>XXX`).
 
 ### 3. Invoke Contract Functions
 
@@ -144,7 +144,7 @@ Save the contract ID returned (e.g., `CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source alice \
-  --network testnet \
+  --network <NETWORK> \
   -- init_game
 ```
 
@@ -170,14 +170,14 @@ stellar contract invoke \
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source alice \
-  --network testnet \
+  --network <NETWORK> \
   -- move_paddle --direction 1
 
 # Move left (direction = -1)
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source alice \
-  --network testnet \
+  --network <NETWORK> \
   -- move_paddle --direction -1
 ```
 
@@ -187,7 +187,7 @@ stellar contract invoke \
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source alice \
-  --network testnet \
+  --network <NETWORK> \
   -- update_tick
 ```
 
@@ -203,7 +203,7 @@ This advances the game by one frame:
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source alice \
-  --network testnet \
+  --network <NETWORK> \
   -- get_game_state
 ```
 
@@ -213,7 +213,7 @@ stellar contract invoke \
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source alice \
-  --network testnet \
+  --network <NETWORK> \
   -- check_game_over
 ```
 

examples/asteroids/.gitignore

@@ -5,4 +5,6 @@ target
 .soroban
 .stellar
 
-/test_snapshots/
+/test_snapshots/
+target/
+*.wasm

examples/asteroids/Cargo.toml

@@ -1,4 +1,5 @@
 [package]
+description = "Arcade asteroid shooter with entity movement and collision systems"
 name = "asteroids"
 version = "0.0.0"
 edition = "2021"

examples/asteroids/README.md

@@ -94,13 +94,13 @@ stellar network add testnet \
   --rpc-url https://soroban-testnet.stellar.org \
   --network-passphrase "Test SDF Network ; September 2015"
 
-stellar keys generate testnet --network testnet
-stellar keys fund testnet --network testnet
+stellar keys generate testnet --network <NETWORK>
+stellar keys fund testnet --network <NETWORK>
 
 stellar contract deploy \
   --wasm target/wasm32v1-none/release/asteroids.wasm \
   --source testnet \
-  --network testnet
+  --network <NETWORK>
 ```
 
 Invoke contract methods:
@@ -110,45 +110,45 @@ Invoke contract methods:
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source testnet \
-  --network testnet \
+  --network <NETWORK> \
   -- \
   init_game
 
 # Control ship
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source testnet \
-  --network testnet \
+  --network <NETWORK> \
   -- \
   rotate_ship --delta_steps 1
 
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source testnet \
-  --network testnet \
+  --network <NETWORK> \
   -- \
   thrust_ship
 
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source testnet \
-  --network testnet \
+  --network <NETWORK> \
   -- \
   shoot
 
 # Update game state
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source testnet \
-  --network testnet \
+  --network <NETWORK> \
   -- \
   update_tick
 
 # Query state
 stellar contract invoke \
   --id <CONTRACT_ID> \
   --source testnet \
-  --network testnet \
+  --network <NETWORK> \
   -- \
   get_game_state
 ```

examples/battleship/.gitignore

@@ -1,6 +1,5 @@
 # Rust
 target/
-Cargo.lock
 **/*.rs.bk
 *.pdb
 

examples/battleship/Cargo.toml

@@ -11,10 +11,11 @@ crate-type = ["cdylib", "rlib"]
 
 [dependencies]
 soroban-sdk = "25.1.0"
-cougr-core = "1.0.0"
+cougr-core = "1.1.0"
 
 [dev-dependencies]
 soroban-sdk = { version = "25.1.0", features = ["testutils"] }
+cougr-core = { version = "1.1.0", features = ["testutils"] }
 
 [profile.release]
 opt-level = "z"