Welcome to Cougr

Cougr is an on-chain game engine built for the Stellar network and Soroban smart contracts. It provides a full Entity-Component-System (ECS) runtime alongside account abstraction and zero-knowledge primitives in a single crate.

This documentation site is generated automatically from the salazarsebas/Cougr repository.

Start

Welcome to the Start section. If you're new to Cougr, this is the right place to begin.

• Getting Started - install the toolchain and run your first test in under two minutes.
• Build Your First Game - a step-by-step walkthrough from an empty directory to a deployed game on Stellar Testnet.

Getting Started

This page is synced from the main Cougr repository. To edit it, open a PR against salazarsebas/Cougr.

Prerequisites

Before you can build a Cougr game, you need the following tools installed:

Clone and run the starter example

git clone https://github.com/salazarsebas/Cougr
cd Cougr/examples/spawn_and_move
cargo test

All tests should pass within two minutes on a machine that has Rust installed.

Next step

Once the tests pass, head over to Build Your First Game for the full sequential tutorial.

Build Your First Game

Welcome to Cougr! This tutorial will take you from an empty directory to a fully tested, testnet-deployed game.

This guide is designed for developers who already know Rust but have no prior experience with Cougr, Soroban, or Stellar. By the end, you'll understand how Cougr's Entity-Component-System (ECS) architecture translates into safe, efficient smart contracts.

We are going to build a simple 2D grid game where a player can spawn into the world and walk in four directions.

1. Project Setup

Since we're building a smart contract, we start with a standard Rust library rather than a binary.

cargo new --lib my_first_game
cd my_first_game

Add cougr-core and the soroban-sdk to your Cargo.toml. We enable the testutils feature to get access to Cougr's built-in testing harness later.

[package]
name = "my_first_game"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
soroban-sdk = "25.3.2"
cougr-core = "1.1.0" # or the latest version from crates.io

[features]
testutils = ["soroban-sdk/testutils", "cougr-core/testutils"]

2. The Mental Model: ECS on Soroban

If you've used an ECS in a game engine like Bevy or Unity, you already know the basics: Entities are just IDs, Components hold data, and Systems run logic.

However, building for a blockchain introduces new constraints you must consider:

[!WARNING] Soroban-Specific Constraints

1. Storage is not a normal database: You cannot freely iterate over millions of rows. State must be loaded into memory, modified, and saved back efficiently.
2. Execution costs money: Every instruction, memory allocation, and storage write costs "gas". Infinite loops or massive arrays will cause your transaction to exceed resource limits and fail.
3. Instance Storage vs Persistent Storage: Cougr uses Soroban's "Instance Storage" by default for your hot-loop game state. This means all active gameplay components are loaded in a single read, making operations extremely cheap and fast, but it requires you to be mindful of total state size.

Cougr abstracts the heavy lifting of storage management, but you still need to write code with these constraints in mind.

3. Defining Components

Let's open src/lib.rs. First, we clear out the default code and define our game's data.

We need two components: a Position to track where the player is, and Moves to track how many steps they have left.

#![no_std]

use cougr_core::game::SorobanGame;
use cougr_core::{impl_component, impl_component_observed, impl_soroban_game};
use soroban_sdk::{contract, contractimpl, contracttype, Env};

// `Position` emits an indexed event on every change (so a UI can watch it)
#[contracttype]
#[derive(Clone, Debug, PartialEq)]
pub struct Position {
    pub x: i32,
    pub y: i32,
}
impl_component_observed!(Position, "position", Table, { x: i32, y: i32 });

// `Moves` is kept private; it doesn't need to emit an event on every step
#[contracttype]
#[derive(Clone, Debug, PartialEq)]
pub struct Moves {
    pub remaining: u32,
}
impl_component!(Moves, "moves", Table, { remaining: u32 });

Notice the two different macros:

• impl_component_observed! tells Cougr to emit a Soroban event every time this component is modified. This is crucial for off-chain clients (like your web frontend) to track movement in real-time without polling the blockchain.
• impl_component! is for standard data that doesn't need to be broadcasted to indexers, saving you gas on event emissions.

4. Writing the Game Contract (Systems)

Next, we define our contract. In Cougr, the contract acts as the outer shell that loads the ECS world, runs your system logic (the functions), and saves the world back.

Add this to the bottom of src/lib.rs:

#[contract]
#[derive(Clone)]
pub struct MyFirstGame;

// This macro wires up the `load_world` and `save_world` boilerplate.
impl_soroban_game!(MyFirstGame, "world");

#[contractimpl]
impl MyFirstGame {
    
    /// Spawns a new player entity into the world.
    pub fn spawn(env: Env) -> u32 {
        // 1. Load the ECS world from Soroban storage
        let mut world = MyFirstGame::load_world(&env);

        // 2. Spawn an entity and attach our components
        let entity = world.spawn_entity();
        world.set_typed_observed(&env, entity, &Position { x: 0, y: 0 });
        world.set_typed(&env, entity, &Moves { remaining: 10 });

        // 3. Save the ECS world back to Soroban storage
        MyFirstGame::save_world(&env, &world);
        
        entity
    }

    /// Moves a player entity in a given direction (0=North, 1=East, 2=South, 3=West).
    pub fn move_entity(env: Env, entity_id: u32, direction: u32) {
        let mut world = MyFirstGame::load_world(&env);

        let mut pos = world.get_typed::<Position>(&env, entity_id).unwrap();
        let mut moves = world.get_typed::<Moves>(&env, entity_id).unwrap();

        if moves.remaining == 0 {
            panic!("no moves left");
        }

        match direction {
            0 => pos.y += 1, // North
            1 => pos.x += 1, // East
            2 => pos.y -= 1, // South
            3 => pos.x -= 1, // West
            _ => panic!("invalid direction"),
        }
        
        moves.remaining -= 1;

        // Apply changes
        world.set_typed_observed(&env, entity_id, &pos);
        world.set_typed(&env, entity_id, &moves);

        MyFirstGame::save_world(&env, &world);
    }
    
    /// Query a player's current position.
    pub fn get_position(env: Env, entity_id: u32) -> Option<Position> {
        let world = MyFirstGame::load_world(&env);
        world.get_typed::<Position>(&env, entity_id)
    }
}

This pattern - Load World -> Query/Modify -> Save World - is the backbone of every Cougr contract entry point.

5. Local Testing

Testing smart contracts on an actual network is slow. Cougr provides a powerful local GameHarness to run tests instantly in memory.

Create a new file src/test.rs and add it to your module tree by adding #[cfg(test)] mod test; to the very bottom of src/lib.rs.

In src/test.rs:

#![cfg(test)]

use super::*;
use cougr_core::test::{GameHarness, Scenario};
use soroban_sdk::Env;

#[test]
fn test_spawn_and_move() {
    let env = Env::default();
    
    // Register our contract using Cougr's test harness
    let harness = GameHarness::new(env, MyFirstGame);

    // The macro generated a "MyFirstGameClient" for us automatically
    let client = MyFirstGameClient::new(harness.env(), harness.contract_id());
    
    // 1. Spawn the entity
    let entity_id = client.spawn();
    
    let pos = client.get_position(&entity_id).unwrap();
    assert_eq!(pos.x, 0);
    assert_eq!(pos.y, 0);

    // 2. Use Cougr's Scenario builder to simulate turns/moves
    Scenario::new("move north")
        .turns(1)
        .run(&harness, |_player, _turn, h| {
            let c = MyFirstGameClient::new(h.env(), h.contract_id());
            
            // Move North (direction = 0)
            c.move_entity(&entity_id, &0);
            
            let pos = c.get_position(&entity_id).unwrap();
            assert_eq!(pos.x, 0);
            assert_eq!(pos.y, 1);
        });
}

Run your tests to verify your game works locally:

cargo test

If it passes, you are ready to deploy!

6. Deploying to Testnet

To deploy, we need to compile our game to a WebAssembly (WASM) binary and use the Stellar CLI.

[!TIP] If you haven't installed the Stellar CLI yet, check out the Stellar Quickstart.

1. Build the WASM file:

cargo build --target wasm32-unknown-unknown --release

Your compiled game is now located at target/wasm32-unknown-unknown/release/my_first_game.wasm.

2. Configure your testnet identity:

stellar keys generate alice --network testnet

3. Deploy the contract:

stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/my_first_game.wasm \
  --source alice \
  --network testnet

If successful, the CLI will return a C... contract address. Congratulations! Your game is live on the Stellar Testnet.

7. Next Steps

You've built and deployed a basic ECS contract. However, real games require more advanced mechanics like access control, hidden information (Fog of War), or multi-contract plugin architectures.

• Learn the architecture: Read Cougr Patterns to understand how to structure larger, production-ready games.
• Get inspired: Browse the Showcase (like murdoku or battleship) in the examples/ directory to see full-stack implementations.

Learn

The Learn section takes you from a working first game to understanding the design decisions that make Cougr work the way it does.

Architecture

High-level overview of how Cougr is organized. For usage, see README.md.

Layers

┌──────────────────────────────────────────────────────────────┐
│           game::SorobanGame  (contract integration)          │  Contract layer
├──────────────────────────────────────────────────────────────┤
│               app::GameApp                                   │  Default runtime surface
├───────────┬───────────────┬──────────────────────────────────┤
│  ECS      │  Accounts     │  Standards      │  ZK Proofs     │
├───────────┴───────────────┴─────────────────┴────────────────┤
│  soroban-sdk 25.1.0  (no_std, WASM)                          │
└──────────────────────────────────────────────────────────────┘

game::SorobanGame (src/game.rs) bridges the ECS and Soroban contract models. The SorobanGame trait provides load_world and save_world as default methods, eliminating repetitive storage-key boilerplate from contract entrypoints. Wire up once with impl_soroban_game!(MyContract, "key").

The companion helpers SimpleWorld::load_from_instance and save_to_instance are the underlying primitives when you want finer control.

GameApp (src/plugin/mod.rs) is the default onboarding layer for complex games. It owns a SimpleWorld, the scheduler, plugin registration, and runtime resources in one place.

ECS

Two storage backends, same ComponentTrait interface:

Both support typed access (get_typed<T>, set_typed<T>) and raw access (get_component, add_component).

Supporting systems:

• Query cache (src/query/) - version-tagged, invalidates on world mutation
• Hooks (src/hooks.rs) - callbacks on component add/remove
• Observers (src/observers.rs) - event-driven reactions
• Commands (src/commands.rs) - deferred mutations during system execution
• Scheduler (src/scheduler/) - stage-based, dependency-aware system ordering
• Change tracker (src/change_tracker.rs) - per-component dirty flags
• Plugins (src/plugin/) - modular game logic bundles
• Incremental storage (src/incremental/) - only persist dirty entities

Component definition

Three macros cover every component case:

impl_rich_component! requires #[contracttype] on the struct. The XDR serialisation is handled entirely by the Soroban SDK - no manual serialize/deserialize implementation is needed.

Rich components are stored in Soroban instance storage (not the ECS Map) but share the same entity ID space.

ZK Proofs (src/zk/)

All ZK operations use Stellar Protocol 25 (X-Ray) host functions - the heavy crypto runs on the host, not in WASM.

• Groth16 (groth16.rs) - proof verification via BN254 pairing
• BLS12-381 (bls12_381.rs) - G1 add/mul/MSM, pairing checks
• Poseidon2 (crypto.rs) - ZK-friendly hashing, behind hazmat-crypto feature
• Merkle trees (merkle/) - SHA256 and Poseidon variants, sparse trees, on-chain proofs
• Pedersen (commitment.rs) - commitment scheme for hidden state
• Game circuits (circuits.rs, traits.rs) - GameCircuit trait + pre-built circuits (Movement, Combat, Inventory, TurnSequence) + CustomCircuitBuilder
• ECS integration (components.rs, systems.rs) - CommitReveal, HiddenState, ProofSubmission components with verification systems

Accounts (src/accounts/)

Account abstraction layer with pluggable implementations:

CougrAccount (trait)
├── ClassicAccount - standard Stellar keypair
└── ContractAccount - smart contract wallet
     ├── SessionStorage - persistent session keys
     ├── RecoveryStorage - guardian-based recovery
     ├── DeviceStorage - multi-device key management
     └── Secp256r1Storage - WebAuthn/Passkey keys

Key traits: CougrAccount, SessionKeyProvider, RecoveryProvider, MultiDeviceProvider.

SessionBuilder provides a fluent API for constructing scoped session keys. authorize_with_fallback handles graceful degradation from session keys to direct authorization. See ADR 0005.

Standards (src/standards/)

Reusable contract standards for integrations that need explicit operational controls:

• Ownable and Ownable2Step for owner-managed authority
• AccessControl for role-based authorization with delegated admins
• Pausable for emergency stops
• ExecutionGuard for serialized critical sections
• RecoveryGuard for blocking sensitive paths during recovery windows
• BatchExecutor for bounded multi-operation flows
• DelayedExecutionPolicy for time-delayed operation queues

Each standard instance is keyed by a caller-supplied Symbol, which keeps storage deterministic and avoids collisions when a contract composes multiple modules.

Competitive Layers (workspace subcrates)

Three layers ship inside the single cougr-core crate. Implementation lives in src/{circuits,session,test}/; internal/cougr-core-* workspace members use stubs for isolated cargo check -p runs.

Circuit builders: hidden_cards, fog_of_war, fair_dice, sealed_bid → GameCircuitSpec. Examples: hidden_hand, fog_explorer, dice_duel, blind_auction. See ADR 0006.

The test sandbox uses no_std + alloc with Soroban testutils - not std. Enable with cougr-core feature testutils. Modules: GameHarness, Scenario, WorldFixture, ReplayLog, SnapshotAssert. See ADR 0004 and ADR 0007.

Feature Flags

Build

Release builds are configured with LTO, opt-level = "z", and overflow-checks = true to keep artifacts optimized for constrained execution environments.

Primary target: wasm32v1-none.

Cougr Patterns

Purpose

This document captures the recommended architectural patterns for new Soroban game contracts built on Cougr.

The goal is to standardize how teams structure worlds, systems, stages, and storage choices instead of relying on ad-hoc example interpretation.

Find a pattern by problem

Start here if you know what you're trying to build but not which Cougr module answers it. Each row links to the module-level doc for full detail, and to a concrete, current example that demonstrates it.

Everything below this point is the module-level architectural guidance the table above links into - organized by Cougr's internal structure rather than by problem, for readers who already know which area they're working in.

Default Entry Point

Use GameApp as the default runtime entrypoint.

Recommended shape:

1. build the app
2. register plugins and startup systems
3. register tick systems into explicit stages, preferably with named_system(...) / named_context_system(...)
4. run one schedule tick per contract invocation that advances gameplay

This keeps the "contract entrypoint" thin and the gameplay loop explicit.

Stage Layout

Cougr's recommended schedule is:

• Startup: one-time entity/resource setup
• PreUpdate: input decoding, action validation, turn preparation
• Update: core gameplay state transitions
• PostUpdate: scoring, derived-state maintenance, indexing side effects
• Cleanup: despawns, expiry handling, transient marker removal

Do not use cross-stage before / after dependencies. Stage order is already the primary contract between phases.

System Design

Prefer small systems with one responsibility:

• validation systems should reject or mark invalid intent
• update systems should apply game-state transitions
• cleanup systems should remove expired markers or entities

Use context-aware systems when you need deferred structural changes:

• queue spawns during iteration
• queue despawns after collision passes
• queue marker additions that should apply after the current scan

Use plain world/env systems when the system only needs direct mutation and no command buffering.

Query Guidance

Prefer SimpleQueryBuilder for gameplay queries that need:

• multiple required components
• negative filters
• sparse-component inclusion
• "any-of" matching

Guidelines:

• default to table-only queries for tight loops
• opt into sparse inclusion only when marker/tag data must participate
• choose required components carefully so the scheduler can use the narrowest candidate set

Hidden Information Guidance

For hidden-state or commit-reveal contracts:

• keep the contract entrypoints thin and verification-oriented
• use privacy::stable Merkle and commit-reveal primitives instead of example-local crypto formats
• treat proof verification as a boundary concern, not as something every gameplay system needs to understand
• keep public derived state separate from private commitments and Merkle roots

battleship is the canonical reference for this pattern.

Storage Guidance

Use table storage for:

• frequently scanned gameplay state
• canonical state that participates in core loops
• components used by Update systems on most ticks

Use sparse storage for:

• infrequent markers
• administrative tags
• components mostly accessed by targeted lookups instead of broad scans

If a component becomes part of the hot loop, move it to table storage instead of compensating with more complex query logic.

Recommended Separation

Keep modules separated by concern:

• ECS/gameplay core
• account/auth flows
• privacy/ZK
• standards/operational controls

Do not let auth or ZK concerns leak into every system by default. Compose them at the boundaries where they are needed.

When Not To Use ECS

Do not force ECS into contracts that are:

• tiny and single-entity
• mostly configuration/state-machine driven
• dominated by one-off administrative flows

If the problem is closer to a fixed state machine than a world simulation, a direct contract model may be simpler and cheaper.

On-Chain / Off-Chain Boundary Guide

⏳ This page is being written.

Named as the second-highest-priority missing document in docs/strategy/08-ux-strategy.md and docs/strategy/12-documentation-architecture.md.

Tracked in: salazarsebas/Cougr issues

What this guide will cover

Developers coming from traditional game development or web backends often hit the same wall: what logic actually needs to be on-chain, and what doesn't? Getting this wrong is expensive - literally, in gas fees.

This guide will answer:

• Which game state must live in Soroban contract storage vs. what can stay off-chain
• How Cougr's observed components (impl_component_observed!) bridge the gap with real-time events
• Patterns for off-chain movement with on-chain settlement
• Resource cost intuition: what makes a transaction cheap vs. expensive

Check back soon - or watch the repository to be notified when this page goes live.

Smart Contract Patterns

⏳ This page is being written.

Will consolidate Soroban-specific patterns from PATTERNS.md and STANDARDS_LAYER.md into one place, distinguishing "Cougr patterns" from "general Soroban patterns."

Tracked in: salazarsebas/Cougr issues

What this guide will cover

• Access control with AccessControl and Ownable
• Emergency stop patterns with Pausable
• Time-delayed operations with DelayedExecutionPolicy
• Batch operations with BatchExecutor
• How these standards compose with the ECS world

Check back soon - or watch the repository.

Testing Guide

⏳ This page is being written.

GameHarness, Scenario, and SnapshotAssert exist in the codebase and are used across thousands of lines of tests, but have no standalone guide yet. Named explicitly in docs/strategy/08-ux-strategy.md Stage 5.

Tracked in: salazarsebas/Cougr issues

What this guide will cover

• Setting up GameHarness for unit tests
• Writing Scenario-based integration tests
• Using SnapshotAssert to lock in expected world state
• How the Soroban test sandbox works (and how it differs from running cargo test for a normal library)
• Estimating resource costs before you deploy

Check back soon - or watch the repository.

Deployment Guide

⏳ This page is being written.

The README has dev commands, but there's no standalone guide walking through production deployment to Stellar Testnet and Mainnet.

Tracked in: salazarsebas/Cougr issues

What this guide will cover

• Configuring the Stellar CLI for Testnet and Mainnet
• Building a release .wasm binary with the correct flags (LTO, opt-level = "z")
• Deploying with stellar contract deploy
• Understanding what a deployment costs (resource fees)
• Upgrading a contract after deploy

Check back soon - or watch the repository.

Reference

The Reference section contains low-level documentation for Cougr's modules, the API surface, and architectural decision records.

Cougr ECS Core

Purpose

This document defines the defended conceptual model for Cougr's ECS runtime.

It is the answer to "what are the actual core primitives?" and "which path is the one new users should learn first?"

Core Model

The stable conceptual model is:

• Entity: an opaque runtime identity
• Component: typed or raw data attached to entities
• Query: a declarative selection over entities by component presence
• System: logic that reads or mutates the world
• CommandQueue: deferred structural mutations
• GameApp: app-level orchestration over world + scheduler + plugins
• RuntimeWorld / RuntimeWorldMut: the shared backend contract for Soroban-first worlds

For Soroban gameplay contracts, the recommended path is:

• app
• SimpleWorld
• SimpleQuery
• SimpleScheduler
• GameApp

ArchetypeWorld is the alternate backend for heavier query workloads.

The shared stable overlap between those backends lives in:

• ecs::RuntimeWorld
• ecs::RuntimeWorldMut

Backend Roles

SimpleWorld

Use when:

• entity counts are modest
• table-backed scans dominate
• operational simplicity matters more than archetype migration costs

Cost profile:

• cheap add/remove/update
• indexed table and all-storage component lookups
• predictable query path for common gameplay loops

ArchetypeWorld

Use when:

• multi-component queries dominate
• entity composition is relatively stable
• migration cost is acceptable in exchange for tighter query scopes

Cost profile:

• more expensive structural changes
• more selective scans for multi-component queries

Learnability Rule

A new user should be able to learn the main Cougr runtime from:

1. README.md
2. GameApp
3. SimpleWorld
4. SimpleQueryBuilder
5. one or two canonical examples

If a concept requires diving outside the Soroban-first runtime path to understand basic gameplay flow, that is a product bug.

Account Kernel

Purpose

The goal is to make authorization explicit, modular, and replay-safe while keeping the accounts namespace outside Cougr's frozen 1.0 stable contract.

Core Model

The account subsystem is now organized around:

• AccountKernel
  • the orchestrator that runs signer verification, policy checks, and replay protection
• signer interfaces
  • AccountSigner
  • base implementations: direct owner auth, session auth, secp256r1 passkey auth
• policy interfaces
  • generic Policy<C>
  • base implementations for intent expiry, session enforcement, active device checks, and guardian checks
• signed intent schema
  • SignedIntent, SignerRef, IntentProof
• structured auth results
  • AuthResult, AuthMethod

Signed Intent Schema

SignedIntent binds:

• target account
• signer reference
• action payload
• nonce
• expiry
• deterministic action_hash
• proof material

The deterministic hash is derived from:

• nonce
• expiry
• signer identity fields
• action system name
• action bytes

Replay Protection

Cougr uses two replay domains:

• per-account nonce tracking for direct owner auth and passkey auth
• per-session nonce tracking for session intents

The replay implementation lives in:

• src/accounts/replay.rs
• src/accounts/storage.rs

Session Model

Session state now includes:

• unique key_id
• scoped allowed actions
• operation budget
• expiration timestamp
• next_nonce

Session enforcement requires all of:

• session exists
• action is in scope
• session is not expired
• operation budget remains
• intent nonce matches next_nonce

On success the session consumes one operation and advances next_nonce.

Signers

Current base signer implementations:

• direct owner signer
  • uses require_auth
• session signer
  • explicit non-fallback session path evaluated by the kernel
• secp256r1 passkey signer
  • verifies signatures against registered passkeys

Policies

The policy layer is intentionally reusable across account features.

Current base policies:

• IntentExpiryPolicy
• SessionPolicy
• ActiveDevicePolicy
• GuardianPolicy

This is how device and recovery support now live under the same policy model instead of ad hoc checks.

Auth Results

AuthResult returns structured information instead of only Result<(), AccountError>.

Current fields:

• method used
• nonce consumed
• session key id, when applicable
• remaining operations, when applicable

Integration Note

The account kernel is now consumed through the curated accounts / auth surface directly.

The previous GameWorld wrapper was removed so 1.0.0 does not freeze an extra orchestration layer. Authorization should be composed explicitly at the application layer around GameApp, SimpleWorld, and the account primitives.

Standards Layer

Purpose

The standards layer introduces reusable, storage-aware contract primitives in the style of OpenZeppelin building blocks, but shaped for Cougr's Soroban-oriented single-crate model.

These modules are meant to be composed into application contracts and account flows without depending on any example project.

Included Standards

Ownable

• single-owner access primitive
• explicit initialization
• direct transfer and renounce flows
• typed ownership transition events

Ownable2Step

• staged ownership handoff
• pending-owner tracking in storage
• explicit acceptance requirement before ownership changes
• cancellation support for abandoned handoffs

AccessControl

• role-based authorization keyed by Symbol
• per-role admin delegation
• explicit grant, revoke, and renounce semantics
• default admin role for bootstrapping new modules

Pausable

• storage-backed emergency stop flag
• explicit paused and unpaused transitions
• guard methods for mutating entrypoints

ExecutionGuard

• storage-backed execution lock
• suited for reentrancy-like protection and mutation serialization
• can be used as explicit enter/exit calls or as a scoped closure wrapper

RecoveryGuard

• blocks sensitive flows while a recovery window is active
• generic enough to compose with account recovery or application-defined incident response

BatchExecutor

• reusable batch length validation
• single-path execution semantics for collections of operations
• explicit empty and oversize rejection

DelayedExecutionPolicy

• storage-backed delayed operation queue
• deterministic operation IDs
• readiness and expiry checks
• cancellation and execution events

Storage and Namespacing

Each standards module is instantiated with a Symbol identifier.

That identifier becomes part of the storage key, which allows a single contract to host multiple independent instances of the same standard without collisions.

Authorization Model

These modules do not assume hidden caller semantics.

Where authorization matters:

• Ownable and Ownable2Step require an explicit caller address
• AccessControl checks the caller against the relevant admin role
• Pausable, RecoveryGuard, and similar state machines leave the surrounding authorization decision to the integrating contract

This is intentional. Cougr keeps authorization visible at the integration boundary instead of burying it in generic helpers.

Error Semantics

The standards layer uses StandardsError for consistent negative-path behavior across integrations.

Important failure modes include:

• unauthorized caller
• duplicate initialization
• missing or mismatched pending owner
• duplicate role grant or missing role during revoke
• paused versus not-paused guard failures
• execution lock contention
• recovery-active guard failure
• empty or oversized batches
• delayed operation not ready, expired, already executed, or missing

Maturity

Status: Stable

The standards layer is part of Cougr's frozen 1.0 stable contract. Integrators should still supply their own caller-auth composition where required, but the module interfaces and documented failure semantics are now part of the defended public surface.

Cougr Privacy Model

Purpose

This document defines Cougr's privacy and proof-verification contract after the 1.0 release gate.

Its job is to separate the stable privacy subset from experimental proof systems so that the repository can make a smaller, stronger claim about what is safe to depend on in the stable contract.

Stable Privacy Surface

The stable privacy subset in Cougr is:

• commitments
• commit-reveal flows
• hidden-state encoding interfaces
• Merkle inclusion verification
• sparse Merkle utilities
• privacy interfaces:
  • CommitmentScheme
  • MerkleProofVerifier
  • HiddenStateCodec
  • ProofVerifier as an interface contract only

These are exposed through:

• cougr_core::privacy::stable
• cougr_core::zk::stable as the compatibility alias

Experimental Privacy Surface

The following remain Experimental:

• Groth16 proof verification flows
• proof-submission execution helpers
• prebuilt verification circuits
• fog-of-war Merkle exploration orchestration
• multiplayer ZK state-channel transition contracts
• recursive proof-composition descriptors
• advanced hidden-state automation
• hazmat Poseidon-based privacy helpers
• broader confidential-state abstractions

These are exposed through:

• cougr_core::privacy::experimental
• cougr_core::zk::experimental as the compatibility alias

Compatibility note:

Experimental modules may still be re-exported from cougr_core::zk for transition convenience, but they are not part of Cougr's stable privacy promise. New application code should prefer cougr_core::privacy::experimental so the product-level intent is obvious at the import site.

1.0 Privacy Freeze

The frozen 1.0 privacy contract is exactly:

• commitments
• commit-reveal flows
• hidden-state codec interfaces
• Merkle inclusion verification
• sparse Merkle utilities
• the interface contracts re-exported from cougr_core::privacy::stable

The following are explicitly excluded from the 1.0 stable privacy contract:

• zk::experimental
• proof-submission orchestration that depends on experimental verification
• Groth16 verifier implementations
• prebuilt advanced circuit helpers
• state-channel, recursive, and fog-of-war orchestration helpers

Privacy Maturity Table

Proof Verification Contract

Cougr's experimental Groth16 verifier makes these explicit guarantees:

• verification keys must satisfy vk.ic.len() == public_inputs.len() + 1
• malformed verification-key shape returns ZKError::InvalidVerificationKey
• malformed pairing inputs return ZKError::InvalidInput
• a well-formed but invalid proof returns Ok(false) only when the pairing check fails

Cougr does not currently claim stronger guarantees for Groth16 around:

• subgroup validation beyond Soroban host-type decoding
• normalization guarantees beyond fixed-width typed wrappers
• broader proof-system maturity for production confidentiality claims

That is why the implementation remains Experimental even though the verifier interface is explicit.

Merkle Verification Contract

Cougr's stable Merkle verification guarantees:

• malformed proofs with siblings.len() != depth return ZKError::InvalidProofLength
• well-formed but non-matching proofs return Ok(false)
• sparse Merkle utilities produce the same on-chain proof representation used by the stable SHA256 verifier

Hidden-State Encoding Contract

Stable hidden-state codecs must:

• define an exact byte-level representation
• reject malformed encoded state with ZKError::InvalidInput
• avoid silent truncation or padding

The built-in Bytes32HiddenStateCodec satisfies this by requiring an exact 32-byte payload in both directions.

Relationship to Public Surface

This model works with:

• docs/MATURITY_MODEL.md
• docs/API_CONTRACT.md
• docs/PUBLIC_GAPS.md
• docs/THREAT_MODEL.md

Any future claim that advanced proof verification is Stable should add stronger input-validation guarantees, clearer host-assumption boundaries, and tighter negative-path coverage than exists today.

Cougr Feature Flags

Purpose

This document groups Cougr feature flags by maturity and intended usage.

Current Flags

Policy

• feature flags do not automatically promote a surface into the stable contract
• test-only or support-only flags remain outside compatibility guarantees
• new security-sensitive flags should default to Beta or Experimental until their contracts are written down

Relationship To Public Surface

The maturity of the feature flag should be interpreted together with:

• MATURITY_MODEL.md
• API_CONTRACT.md
• COMPATIBILITY_PROMISES.md

In the product-level facade:

• auth mirrors the Beta accounts surface
• privacy::stable and privacy::experimental mirror the split inside zk
• ops mirrors the stable standards surface

Cougr Performance Guide

Purpose

This document explains the current performance model for Cougr's Soroban-first ECS path.

It is not a promise of fixed gas costs. It is a guide to the data structures and tradeoffs that determine query and scheduling behavior.

The practical question it should answer is:

• which backend should I use
• where should a component live
• what kinds of mutations are cheap versus expensive

SimpleWorld Query Model

SimpleWorld now maintains direct component indexes:

• table_index for table-backed components
• all_index for table + sparse lookups

That changes the expected behavior of the common query paths:

• get_table_entities_with_component() uses the direct table index
• get_all_entities_with_component() uses the all-storage index
• SimpleQuery selects the narrowest available required component index before filtering

This is the default performance story for gameplay loops.

Use SimpleWorld by default when:

• your hot loop is dominated by one- or two-component scans
• you mutate entity composition often
• you rely on table vs sparse placement to control scan scope

Use ArchetypeWorld when:

• your hot loop is dominated by repeated multi-component queries
• entity compositions are relatively stable after setup
• you are willing to pay more for add/remove migrations to get tighter query scopes

Storage Tradeoffs

Table storage:

• optimized for repeated scans
• should back components that appear in hot gameplay loops

Sparse storage:

• better for infrequent markers or tags
• excluded from table-only scans by default

If a sparse component starts showing up in tick-critical queries, it is usually a signal that the component belongs in table storage.

Prescriptive rule:

• if you scan it every tick, it probably belongs in table storage
• if you mostly address it directly or use it as a sparse marker, keep it sparse

Scheduler Tradeoffs

SimpleScheduler now validates stage-local dependencies before execution.

Costs introduced by the stronger model:

• dependency validation during run planning
• topological ordering within each stage

Benefits:

• explicit execution order
• early detection of invalid schedules
• safer composition as system counts grow

This is a good trade in Soroban-oriented contracts because schedule size is typically small relative to the cost of incorrect execution order.

Benchmark Focus Areas

Benchmarks should answer these practical questions:

• how many entities can the indexed query path scan efficiently
• when does ArchetypeWorld outperform SimpleWorld
• what is the cost of adding/removing indexed components
• what is the cost of stage validation and deferred command application

The current benchmark suite in benches/ecs_bench.rs covers these paths directly.

It now includes:

• entity spawn cost
• component insert / lookup cost
• indexed query vs sparse-inclusive query cost
• cache warm-read vs invalidated-read behavior
• scheduler validation + execution cost
• SimpleWorld vs ArchetypeWorld multi-component query comparison
• SimpleWorld vs ArchetypeWorld structural mutation comparison

Reading The Current Benchmarks

Interpret the benchmark output in this order:

1. Query Paths If plain indexed queries and cached queries are already cheap enough, stay on SimpleWorld.
2. Backend Query Comparison If ArchetypeWorld is materially better on your real multi-component query shape, it may be worth adopting.
3. Backend Structural Mutation Comparison If archetype migration is significantly more expensive for your workload, do not switch just because query numbers look better in isolation.
4. Query Cache Invalidation If your world mutates every tick, cache benefits may collapse; optimize data shape first.

Decision Heuristics

Choose SimpleWorld when:

• gameplay writes are frequent
• entity compositions change often
• table/sparse separation gives you enough control
• your queries are broad but predictable

Choose ArchetypeWorld when:

• the same multi-component query runs constantly
• compositions are mostly fixed after startup
• entity migration cost is amortized over many reads

Keep GameApp, SimpleWorld, and SimpleQuery as the default performance story for new Soroban gameplay code.

Interpretation Rules

Use benchmark output to compare patterns, not to claim universal throughput numbers.

For real contracts, evaluate:

• data shape
• component cardinality
• table vs sparse placement
• how often the world mutates between repeated queries

Performance guidance should always be tied back to those conditions.

If benchmark results and your data shape disagree, trust the data shape first.

Related

This guide answers where a component should live once you have decided it belongs on-chain. For the prior decision, whether a piece of state or logic justifies being on-chain in the first place, see ONCHAIN_OFFCHAIN_BOUNDARY.md.

Cougr Public API Contract

Purpose

This document defines how Cougr presents its public Rust API for 1.0.

It answers four practical questions:

• which entrypoints are central to the product
• which surfaces are usable but still evolving
• which modules should not be interpreted as production commitments
• which compatibility shims or testing helpers are intentionally outside the long-term contract

API Positioning

Cougr exposes a broad crate surface, but only a scoped subset is part of the defended 1.0 contract.

The current product story is:

• cougr-core is primarily an ECS framework for Soroban-compatible applications
• app is the default gameplay runtime surface for new projects
• auth, privacy, and ops are the clearest product-level domain namespaces
• accounts remain Beta, while privacy is split between a stable primitive subset and experimental proof systems
• ECS onboarding/runtime surfaces and standards are part of the 1.0 stable contract
• helper APIs that exist only for compatibility or transition should remain clearly demoted

Recommended Public Contract

This file now serves as the explicit 1.0 stable API list for cougr-core.

Core entrypoints

These are the frozen entrypoints for the 1.0 stable contract:

• SimpleWorld
• ArchetypeWorld
• ecs::{RuntimeWorld, RuntimeWorldMut, WorldBackend}
• typed and raw component operations
• command queues
• scheduling primitives
• events, hooks, and observers
• incremental persistence utilities

Concrete frozen root-level contract:

• SimpleWorld
• ArchetypeWorld
• CommandQueue
• Component, ComponentTrait, ComponentStorage, ComponentId
• SimpleQuery, SimpleQueryBuilder
• RuntimeWorld, RuntimeWorldMut, WorldBackend
• Resource
• runtime::ChangeTracker, runtime::TrackedWorld
• Plugin, PluginGroup, GameApp
• ScheduleStage, SystemConfig, SimpleScheduler, SystemGroup
• prelude
• runtime
• app
• ops as the clearest Stable standards namespace
• standards as a Stable namespace
• privacy::stable as the clearest stable privacy namespace
• zk::stable as the stable privacy namespace
• auth as the clearest Beta account namespace
• accounts as a Beta namespace
• privacy::experimental as an explicitly non-contract namespace
• zk::experimental as an explicitly non-contract namespace

Supported but evolving surfaces

These surfaces are useful and implemented, but should continue to be presented as Beta:

• accounts
• higher-level query helpers
• higher-level scheduler helpers
• proof-submission helpers in zk

Stable privacy subset

These privacy surfaces are intentionally narrower and can be presented as Stable:

• commitments
• commit-reveal
• hidden-state codec interfaces
• Merkle inclusion and sparse Merkle utilities
• zk::stable

Non-contract surfaces

These surfaces are public today, but they must not be interpreted as stable commitments:

• testing-only helpers
• advanced proof-verification APIs whose assumptions are still being hardened
• zk::experimental
• compatibility shims retained for transition
• internals-heavy modules whose invariants are not yet documented as stable guarantees

Top-Level Surface in src/lib.rs

Public modules

Current top-level modules:

• app
• auth
• accounts
• archetype_world
• commands
• component
• debug behind feature flag
• error
• event
• ops
• privacy
• plugin
• query
• resource
• scheduler
• simple_world
• zk

Internal implementation modules such as hidden scheduler helpers, storage internals, and entity internals are no longer part of the intended default public surface. They may still exist in the repository, but the root crate is not meant to advertise them as onboarding entrypoints. Advanced runtime support such as hooks, observers, change tracking, and incremental storage is exposed through curated re-exports and runtime instead of direct top-level module entrypoints.

Public re-exports

Current top-level re-exports emphasize:

• worlds: SimpleWorld, ArchetypeWorld
• backend contracts: RuntimeWorld, RuntimeWorldMut, WorldBackend
• ECS data: Component, ComponentId, ComponentStorage, ComponentTrait, Position, Resource
• orchestration: CommandQueue, GameApp, schedulers
• queries: SimpleQuery, SimpleQueryBuilder
• domain access through explicit namespaces: auth, privacy, ops, accounts, zk::stable, zk::experimental

Public top-level helper functions

There are no root-level placeholder helper functions in the supported contract.

The sanctioned onboarding path is the curated root surface itself:

• app
• auth
• privacy
• ops
• SimpleWorld
• ArchetypeWorld
• CommandQueue
• GameApp
• app::{named_system, named_context_system} and add_systems

Compatibility Exceptions

Public API Risks

The main public API risks before this cleanup were:

• the crate exports more surface area than it can reasonably defend as stable
• some internals-heavy modules are public before their long-term contract is clearly documented
• some privacy and verification surfaces are easy to overread as production guarantees
• accounts and privacy modules still include beta-grade behavior that is intentionally documented outside the stable story

Freeze Direction

The 1.0 freeze is intentionally narrower than the full public module graph:

• app is the clearest default runtime namespace for new gameplay code
• auth is the clearest Beta auth namespace for application code
• privacy is the clearest domain namespace for privacy adoption, with stability determined by submodule
• ops is the clearest stable namespace for operational standards in application code
• root re-exports and prelude are the default onboarding path
• runtime is the supported namespace for advanced ECS integrations that are not part of the smallest onboarding contract
• query and archetype_world retain their cache/state helpers outside the smallest root onboarding surface
• standards is a supported stable namespace
• accounts remains a public Beta namespace
• zk::stable is the only privacy namespace treated as Stable
• zk::experimental remains public for explicit opt-in use, but outside compatibility guarantees

Cougr Compatibility Promises

Purpose

This document defines the compatibility story Cougr is prepared to defend at 1.0.

It turns the maturity model into explicit expectations for adopters, contributors, and maintainers.

1.0 Baseline

Cougr 1.0.0 freezes a scoped stable surface inside a broader public crate.

That means:

• compatibility promises are scoped by maturity, not by visibility alone
• stable, beta, and experimental namespaces can coexist in the same crate
• the stable guarantee is the documented contract, not every public symbol

Stable Surfaces

The following surfaces are treated as Cougr's strongest 1.0 compatibility commitments:

• root ECS onboarding and runtime entrypoints documented in API_CONTRACT.md
• prelude
• runtime
• ops
• standards
• privacy::stable
• zk::stable
• the contracts documented in PRIVACY_MODEL.md for commit-reveal, hidden-state codecs, and Merkle verification

For these surfaces, maintainers should preserve:

• type and function intent unless there is a documented breaking reason
• documented failure behavior
• documented malformed-input behavior where applicable
• byte-level or proof-shape contracts already written in the privacy model

Beta Surfaces

The following surfaces are supported but intentionally not frozen:

• higher-level ECS helpers outside the frozen root/runtime contract
• auth
• accounts
• proof-submission orchestration that depends on experimental verification flows

For Beta surfaces, maintainers commit to:

• keep the product direction coherent
• document meaningful semantic changes
• avoid gratuitous churn
• preserve the curated onboarding path where practical

For Beta surfaces, maintainers do not yet promise:

• SemVer-stable signatures
• unchanged storage layouts for every helper
• unchanged auth or orchestration semantics across all releases

Experimental Surfaces

The following surfaces are explicitly outside compatibility guarantees:

• privacy::experimental
• zk::experimental
• hazmat cryptographic helpers
• advanced proof-verification helpers and descriptors
• any public support surface documented as test-only or transition-only

These may:

• change shape
• move namespace
• be removed
• gain stronger validation that changes edge-case behavior

Non-Contract Support Surfaces

Support-only surfaces such as MockAccount are not part of the default product contract.

They exist for tests and explicit utility consumers, not as long-term framework guarantees.

Change Management Rules

When changing a Stable or Beta public surface, update at minimum:

• MATURITY_MODEL.md if the classification changes
• API_CONTRACT.md if the recommended contract changes
• PUBLIC_GAPS.md if a known gap is closed or newly introduced
• THREAT_MODEL.md if trust assumptions or security posture change

1.0 Freeze Decisions

The 1.0 release gate decisions are:

• ECS onboarding and runtime surfaces are in the stable contract
• ops is the stable domain alias for standards
• standards is in the stable contract
• auth is a Beta domain alias and is not part of the stable guarantee
• accounts remains Beta and is not part of the stable guarantee
• privacy::stable maps to the frozen privacy contract
• zk::stable is the frozen privacy contract
• privacy::experimental remains outside compatibility guarantees
• zk::experimental remains outside compatibility guarantees

Migration Guide

Purpose

This guide explains how to move existing Cougr integrations toward the curated 1.0 product surface.

It is not a promise that every older pattern disappears immediately. It is the recommended direction for users who want to converge on the defended path.

Core Direction

Prefer these namespaces in new or updated code:

• app for gameplay runtime
• auth for account and session flows
• privacy::stable for stable privacy primitives
• ops for operational standards

Runtime Migration

From direct world/scheduler wiring

If you currently do something like:

let mut world = SimpleWorld::new(&env);
let mut scheduler = SimpleScheduler::new();

prefer:

let mut app = cougr_core::app::GameApp::new(&env);

and register systems through GameApp.

When multiple systems belong to the same phase, prefer the declarative path:

use cougr_core::app::{named_context_system, named_system, GameApp, ScheduleStage};

let mut app = GameApp::new(&env);
app.add_systems((
    named_system("spawn", |world, env| {
        let entity = world.spawn_entity();
        world.set_typed(env, entity, &Position::new(0, 0));
    })
    .in_stage(ScheduleStage::Startup),
    named_context_system("cleanup_tags", |context| {
        let entities = context
            .world()
            .get_entities_with_component(&symbol_short!("expired"), context.env());
        for i in 0..entities.len() {
            let entity = entities.get(i).unwrap();
            context
                .commands()
                .remove_component(entity, symbol_short!("expired"));
        }
    })
    .in_stage(ScheduleStage::Cleanup),
));

Why:

• clearer lifecycle
• explicit stages
• one onboarding surface instead of several loose primitives
• a single system registration model for plain and context-aware systems

From the removed pre-1.0 ECS model

If you were previously on the removed pre-1.0 World / System path, port directly to GameApp, SimpleWorld, and SimpleQuery.

Query Migration

If you still do ad-hoc scans or manual component filtering, prefer:

• SimpleQueryBuilder
• SimpleQueryState
• SimpleQueryCache

Both SimpleQueryBuilder and ArchetypeQueryBuilder now support:

• with_components(...)
• without_components(...)
• with_any_components(...)

If you need backend-agnostic gameplay helpers across Soroban-first worlds, prefer:

• RuntimeWorld
• RuntimeWorldMut

These are the shared contracts between SimpleWorld and ArchetypeWorld.

Domain Migration

Accounts

If you currently import from accounts directly in application code:

use cougr_core::accounts::SessionBuilder;

prefer:

use cougr_core::auth::SessionBuilder;

The semantics are the same today. The change is about product clarity.

Privacy

If you rely on stable privacy primitives, prefer:

use cougr_core::privacy::stable::...

instead of:

use cougr_core::zk::stable::...

If you rely on advanced proof tooling, prefer:

use cougr_core::privacy::experimental::...

and treat it as an explicit opt-in to non-frozen APIs.

Standards

If you currently import standards directly:

use cougr_core::standards::Pausable;

prefer:

use cougr_core::ops::Pausable;

Again, this is a namespace migration for clarity, not a semantic rewrite.

Example-Level Migration

Use these examples as references:

• snake for app::GameApp and stage-based gameplay loops
• battleship for privacy::stable and hidden-information patterns
• guild_arena for account/session/recovery patterns

What Does Not Need Immediate Migration

You do not need to rewrite everything at once if:

• the contract still needs a focused port from the removed pre-1.0 runtime path
• you are preserving an older example or integration
• your current code already sits behind a stable local abstraction

The main goal is to stop growing new code on top of older default imports.

Migration Checklist

• move runtime entrypoints to app where practical
• move account imports to auth
• move stable privacy imports to privacy::stable
• move standards imports to ops
• update local docs/examples to use the curated namespaces

CLI Reference

⏳ This page does not exist yet because the cougr-cli crate does not exist yet.

Per docs/strategy/12-documentation-architecture.md: "CLI reference - Does not exist because the CLI does not exist yet; ships alongside it."

When the CLI ships, this page will document all cougr new, cougr add, and cougr check subcommands.

Tracked in: salazarsebas/Cougr issues

Client SDK Reference

⏳ This page does not exist yet because the TypeScript client SDK does not exist yet.

Per docs/strategy/12-documentation-architecture.md: "Client SDK reference - Ships alongside the SDK described in 06-product-strategy.md."

When the SDK ships, this page will document the TypeScript API for connecting a frontend to a Cougr game contract, including wallet integration and session key management.

Tracked in: salazarsebas/Cougr issues

Architecture Decision Records

Architecture Decision Records (ADRs) document significant technical decisions made in Cougr's design. They are kept in the main salazarsebas/Cougr repository under docs/adr/ and synced here automatically.

Each ADR follows the format: context → decision → consequences.

ADR 0001: Curated Public Surface

Status

Accepted

Context

Cougr exposes a broad API. Without curation, adopters can easily mistake public visibility for stable-contract inclusion.

Decision

Cougr keeps a curated onboarding path at the crate root and explicitly separates:

• root-level ECS onboarding re-exports
• standards as a Stable namespace
• zk::stable as the stable privacy namespace
• accounts as a Beta namespace
• zk::experimental as the explicit non-contract privacy namespace

Consequences

• docs can name the golden path without pretending the whole crate is frozen
• advanced but useful namespaces remain available
• public visibility alone is no longer the compatibility signal

ADR 0002: Keep Accounts Out Of The Stable 1.0 Contract

Status

Accepted

Context

The account kernel, typed intents, replay domains, passkey support, and session enforcement are implemented. However, account abstraction remains a security-sensitive area with meaningful design-space risk.

Decision

Cougr will keep accounts as a Beta namespace at 1.0 even though the kernel exists and is tested.

Consequences

• the repo can truthfully document real implementation value
• maintainers keep room to tighten signer, policy, and integration contracts
• adopters are warned not to treat the current account API as SemVer-frozen

ADR 0003: Stable Privacy Subset With Experimental Verification

Status

Accepted

Context

Cougr contains both defensible privacy primitives and faster-moving proof-verification helpers. Treating them as one maturity tier would overclaim guarantees.

Decision

Cougr formally splits privacy into:

• zk::stable for commitments, commit-reveal, hidden-state codecs, and Merkle verification
• zk::experimental for advanced proof verification, circuits, channels, recursive layouts, and hazmat helpers

Consequences

• privacy claims can stay narrow and defendable
• advanced ZK work can continue without blocking the stable subset
• compatibility promises can be scoped precisely by namespace

ADR 0004: Sandbox Design

Status

Accepted

Context

We need a secure testing and simulation environment for contracts to allow developers to validate logic (like ECS events and ZK proofs) locally without full node deployments. The sandbox should emulate the target environment accurately.

Decision

We introduce a test sandbox utilizing no_std and alloc alongside the Soroban testutils feature. This sandbox provides core modules for testing games (such as GameHarness, Scenario, WorldFixture, ReplayLog, and SnapshotAssert).

Consequences

• Developers can write fast local tests with a familiar testing API.
• We must maintain parity between sandbox behavior and on-chain execution.
• Relies on the testutils feature flag being managed correctly in the crate.

ADR 0004: Include Standards In The Stable 1.0 Contract

Status

Accepted

Context

The standards layer is documented, integration-tested, and intentionally designed as a reusable framework surface rather than example glue.

Decision

Cougr includes standards in the stable 1.0 contract.

Consequences

• integrators can treat standards as part of the defended public framework surface
• future changes to these modules now carry stable-contract weight
• authorization composition remains explicit at the integration boundary rather than hidden inside the primitives

ADR 0005: Session UX

Status

Accepted

Context

Repeatedly signing transactions degrades the user experience for on-chain games, especially those requiring frequent interactions (like real-time or turn-based strategy). Players expect a seamless experience akin to Web2 gaming without constantly engaging with a wallet prompt.

Decision

We introduce session keys with a fluent SessionBuilder API to authorize specific game actions over a time-bound window without requiring repeated user prompts. authorize_with_fallback will be used for graceful degradation, allowing operations to fall back to direct authorization when a session is expired or unavailable.

Consequences

• Massively improved gameplay experience for end users.
• Integration becomes slightly more complex to handle session lifecycles.
• Wallets and client integrations must support and manage session key delegation.

ADR 0006: Game Circuit Suite (cougr_core::circuits)

Status

Accepted

Context

Game developers need fog-of-war, hidden cards, fair dice, and sealed-bid mechanics without authoring Circom circuits and wiring Groth16 verification by hand. Cougr already exposes low-level verifiers under zk::experimental, but the onboarding path requires weeks of ZK specialization.

Decision

1. Ship four pre-built circuit builders under cougr_core::circuits (always available, Experimental maturity):

   Builder	Public inputs
   hidden_cards(deck_size, hand_size)	deck_root, hand_commitment, player_id, deck_size, hand_size
   fog_of_war(w, h, radius)	map_root, prior/next explored roots, origin, tile, radius
   fair_dice(sides, seed_commitment)	seed_commitment, roll_result, sides, nonce
   sealed_bid(max_bid)	auction_id, bid_commitment, revealed_bid, max_bid

2. Each builder returns GameCircuitSpec with a frozen PublicInputLayout, placeholder VK (correct IC length), and typed verify methods that delegate to zk::experimental::verify_groth16. Production deploys replace the VK via with_verification_key.

3. fog_of_war reuses FogOfWarCircuit in zk::advanced - no duplicate verification logic.

4. Circom scaffolds and off-chain scripts live in internal/cougr-core-circuits/ (publish = false). Rust implementation lives in src/circuits/.

5. Canonical examples demonstrate each builder:

   • examples/hidden_hand/
   • examples/fog_explorer/
   • examples/dice_duel/
   • examples/blind_auction/

Consequences

• Developers integrate common game privacy patterns in hours, not weeks.
• Public-input layouts are versioned by CircuitId and must not change without a new ADR.
• On-chain builders ship an unbound VK; load test/production keys from internal/cougr-core-circuits (bun run pipeline → exported/*_vk.json).
• Circuits use Poseidon + game constraints (~325–13.6k R1CS); pot14 trusted setup.
• zk::stable remains unchanged; all new surface stays Experimental until external audit.

ADR 0007: Workspace Subcrates Compiled Into cougr-core

Status

Accepted

Context

Cougr is adding three competitive layers (ZK circuit builders, session UX, game testing sandbox). They need compile-time isolation without publishing separate crates.io packages, so download metrics stay unified under cougr-core.

Decision

1. Add a Cargo workspace with three internal members under internal/:

   • cougr-core-circuits
   • cougr-core-session
   • cougr-core-test

2. Each internal member sets publish = false.

3. Each layer's implementation lives in src/{circuits,session,test}/inner.rs. The public modules include! that file; internal workspace members point their [lib] path at the same inner.rs for isolated cargo check -p runs. This avoids:

   • circular dependencies (session needs auth from the same crate)
   • cargo publish failures on unpublished path deps
   • missing files in the published tarball

4. Public API:

   • cougr_core::circuits - always available
   • cougr_core::session - always available
   • cougr_core::test - testutils feature only

5. The test sandbox uses no_std + alloc, not std. It runs in Soroban testutils environments the same way contract tests do today.

Consequences

• One cargo add cougr-core for all capabilities
• Internal folders can still be checked with cargo check -p cougr-core-session
• cargo publish ships internal/** sources inside the cougr-core tarball
• Feature testutils keeps sandbox code out of contract WASM builds

ADR 0008: Include Standards In The Stable 1.0 Contract

Status

Accepted

Context

The standards layer is documented, integration-tested, and intentionally designed as a reusable framework surface rather than example glue.

Decision

Cougr includes standards in the stable 1.0 contract.

Consequences

• integrators can treat standards as part of the defended public framework surface
• future changes to these modules now carry stable-contract weight
• authorization composition remains explicit at the integration boundary rather than hidden inside the primitives

Showcase

The Showcase is a live directory of games and demos built with Cougr. It is generated automatically from the example catalog and each example's own README.md — no manual duplication.

Browsing the gallery

• Example Gallery — filter by category and maturity to find the right reference for your use case.
• Click any card to see the full detail page, pulled directly from that example's README.md.

How it works

The gallery is a static, build-time-generated set of pages — zero backend, zero database. The generator (cougr-site/generate-showcase.py) reads:

1. examples/catalog.toml — structured metadata (category, maturity, Cougr features, optional screenshot/testnet contract).
2. Each example's README.md — the description and full documentation.
3. packages/tokens/tokens.json — design tokens (colors, typography, spacing) consumed as CSS custom properties, so the showcase never visually diverges from the docs site.

To generate locally:

python3 cougr-site/generate-showcase.py
mdbook serve cougr-site

Preview images

Examples with a preview.svg in their directory display it in the gallery card and detail page. Examples without a preview image render cleanly without any broken image tags.

Submit your game

Once your example is cataloged in examples/catalog.toml and meets the quality standard, it will appear in the gallery automatically. A "Cougr Verified" badge can be earned by opening a PR — the catalog's verified field controls whether the badge renders.

account_kernel_counter

Canonical example proving that cougr add account-kernel produces a module that is usable in a real Soroban game, not just importable.

The game is a simple per-owner counter. Every increment must be authorized through the account_kernel module that was scaffolded by cougr add account-kernel.

How this project was generated

# 1. Scaffold the project from the session-auth template.
cougr new account_kernel_counter --template session-auth
cd account_kernel_counter

# 2. Drop in the account-kernel piece (writes src/account_kernel.rs
#    and adds `pub mod account_kernel;` to lib.rs).
cougr add account-kernel

# 3. Build and test.
cargo test
stellar contract build

src/account_kernel.rs has one change from the file written by step 2: the testutils::Address as _ import is gated with #[cfg(test)] instead of #[cfg(any(test, feature = "testutils"))]. The testutils feature is not declared by this crate, so the original attribute causes Clippy to emit an unexpected_cfgs error under -D warnings. Moving the import under #[cfg(test)] is the correct fix; everything else in the file is verbatim piece output.

Purpose and pattern

account_kernel_counter is the end-to-end proof that the account-kernel piece integrates cleanly into a real game contract. It strips away all game mechanics so you can focus on:

1. Register – owner calls register_session once to approve a scoped session key via account_kernel::build_scope and SessionStorage::store.
2. Authorize – each increment call delegates to account_kernel::authorize_action, which runs the full AccountKernel → SessionPolicy pipeline (expiry check, op-budget decrement, nonce advancement).
3. Reject – expired sessions, replayed nonces, and exhausted budgets all surface as panics from authorize_action, preventing the counter from advancing.

Authorization flow

register_session(owner, key_id, max_ops, expires_at)
  └─ account_kernel::build_scope()          ← unmodified piece
     └─ SessionBuilder → SessionScope
  └─ SessionStorage::store()

increment(owner, key_id, nonce, intent_expires_at)
  └─ account_kernel::authorize_action()     ← unmodified piece
     └─ AccountKernel::authorize_session()
        ├─ SessionPolicy: expiry check
        ├─ SessionPolicy: action-name allow-list
        ├─ SessionPolicy: nonce advancement
        └─ SessionPolicy: op-budget decrement
  └─ counter += 1  (only reached on Ok)

Public contract API

Cougr APIs used

• account_kernel::build_scope – piece helper that calls SessionBuilder
• account_kernel::counter_action – piece helper that constructs the tap GameAction
• account_kernel::authorize_action – piece helper that calls AccountKernel::authorize_session
• AccountKernel – separates signer verification, policy evaluation, and replay protection
• SessionStorage – load / store session keys on-chain
• SessionBuilder – declare allowed actions, max operations, and expiry

Test coverage

The piece's own unit tests (account_kernel::tests::*) also run as part of cargo test and cover build_scope, expiry, and nonce isolation at the function level.

Build and test

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
stellar contract build

When to use which example

License

MIT

AI Dungeon Master Arena Example

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

This example demonstrates a complex gameplay loop on Stellar/Soroban using:

1. x402-style Paid Actions: Premium encounters or rerolls purchased in-game via a request-driven model.
2. stellar-zk (via Cougr-Core): Proof-backed validation of sensitive encounter progression and reward eligibility.

Features

• Run Initialization: Start an entity-backed arena run for a player.
• Turn-based Combat: Attack or defend in procedural encounters.
• x402 Hooks: Premium rerolls or hints appearing at specific progression points.
• ZK Verification: Submit Groth16 proofs to validate off-chain state or hidden attributes on-chain.
• Reward System: Track and claim rewards earned from verified milestones.

Architecture

The example follows an ECS-like structure (Entity Component System):

• RunStateComponent: Core session data.
• EncounterComponent: Current enemy and challenge data.
• PremiumActionComponent: Tracks availability of x402-driven premium options.
• ProofStateComponent: Stores verification status for ZK-backed progression.
• RewardComponent: Management of in-game assets and rewards.

stellar-zk Integration

This contract uses cougr-core::zk which is built for high-performance on-chain verification compatible with stellar-zk generated circuits.

• The verify_run_proof function takes a Groth16Proof and public inputs.
• It validates the proof against a stored VerificationKey (which would correspond to the circuit built for your arena logic).
• Successful validation unlocks pending rewards and confirms floor progression.

x402 Flow

1. Player completes a floor.
2. At every 3rd floor, a PremiumActionComponent is attached to their run.
3. This signals an HTTP 402 Payment Required state to the frontend/off-chain DM.
4. Player pays the fee (XLM/tokens) to purchase the purchase_premium_action.
5. Contract verifies payment and grants a high-tier reward or easier encounter path.

Development

Prerequisites

• Soroban CLI
• Rust toolchain with wasm32-unknown-unknown target.

Build

cargo build --target wasm32-unknown-unknown --release

Test

cargo test

On-Chain Deployment

1. Deploy the contract: soroban contract deploy ...
2. Initialize VK: soroban contract invoke --id <ID> --fn set_vk --vk <VK_JSON>
3. Start run: soroban contract invoke --id <ID> --fn init_run --player <ADDR>

Acceptance Criteria

• Includes x402 representation in purchase_premium_action.
• Real stellar-zk verification path in verify_run_proof.
• Deterministic run loop and full test coverage.
• Soroban-compatible build (wasm32v1-none).

Angry Birds on Stellar Soroban

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

A turn-based physics puzzle implementation using the Cougr ECS framework on Stellar/Soroban. This contract demonstrates complex state transitions, entity relationships, and bounded on-chain computation suitable for blockchain gaming.

Game Design

Angry Birds is a physics-based puzzle game where players launch projectiles (birds) at structures to eliminate targets (pigs). This implementation focuses on turn-based gameplay with deterministic physics simulation.

Core Mechanics

• Turn-based shooting: Players submit angle and power parameters for each shot
• Deterministic physics: Fixed-point mathematics ensure reproducible results
• Material system: Different materials (wood, glass, stone) have varying damage resistance
• Bounded computation: Maximum 50 simulation steps per shot prevents gas limit issues
• Win/loss conditions: Win by destroying all targets, lose by running out of birds

ECS Architecture

This implementation showcases the Cougr-Core ECS framework with the following components and systems:

Components

Systems

1. ShotResolutionSystem - Resolves projectile trajectory using discrete steps (max 50 iterations)
2. DamageSystem - Applies damage based on material resistance (wood < glass < stone)
3. ScoreSystem - Calculates points from destroyed entities and remaining birds
4. WinConditionSystem - Checks if all pigs are eliminated (win) or no birds remain (loss)

Technical Constraints

Fixed-Point Mathematics

• All positions and velocities use fixed-point math scaled by 1000
• Eliminates floating-point inconsistencies across different environments
• Ensures deterministic behavior crucial for blockchain applications

Bounded Computation

• Maximum 50 simulation steps per shot
• Prevents unbounded loops and gas limit issues
• Grid-based collision detection for efficiency

Deterministic Behavior

• Same input (angle, power, bird_type) always produces the same output
• Critical for fair gameplay and blockchain verification

Contract API

init_level(env: Env, player: Address, level_id: u32) -> LevelState

Initializes a new game level with default configuration:

• 3 birds available
• Empty game field
• Score reset to 0
• Game status set to InProgress

shoot(env: Env, player: Address, angle: i32, power: i32) -> ShotOutcome

Executes a shot with specified parameters:

• angle: Launch angle in degrees (scaled by 1000)
• power: Launch power (scaled by 1000)
• Returns shot outcome (hit, miss, win, loss)
• Validates player authorization and game state

get_state(env: Env) -> LevelState

Returns current game state including:

• Level ID and status
• Current score and birds remaining
• Number of entities in the game

reset_level(env: Env, player: Address) -> LevelState

Resets the current level to initial state:

• Maintains same level ID and player
• Resets score, birds, and game status
• Clears all game entities

Building and Testing

Prerequisites

• Rust 1.88+ with wasm32 target
• Stellar CLI for contract deployment
• Git for cloning the repository

Setup

# Clone the Cougr repository
git clone https://github.com/salazarsebas/Cougr.git
cd Cougr/examples/angry_birds

# Install Rust targets
rustup target add wasm32v1-none

# Install Stellar CLI
brew install stellar-cli  # macOS
# or follow https://github.com/stellar/stellar-cli for other platforms

Build Commands

# Standard Rust build
cargo build

# Release build with optimizations
cargo build --release

# Stellar contract build (produces .wasm)
stellar contract build

# Format code
cargo fmt

# Lint code
cargo clippy --all-targets --all-features -- -D warnings

Testing

# Run all tests
cargo test

# Run specific test
cargo test test_level_initialization

# Run tests with output
cargo test -- --nocapture

Deployment

Testnet Deployment

# Set up testnet environment
stellar network testnet

# Deploy contract
stellar contract deploy \
  --wasm target/wasm32v1-none/release/angry_birds.wasm \
  --source <your-account> \
  --network <NETWORK>

# Note the contract ID for subsequent interactions

Contract Interaction

# Initialize a level
stellar contract invoke \
  --id <contract-id> \
  --source <player-account> \
  --network <NETWORK> \
  -- init_level \
  --player <player-address> \
  --level_id 1

# Take a shot (45 degrees, medium power)
stellar contract invoke \
  --id <contract-id> \
  --source <player-account> \
  --network <NETWORK> \
  -- shoot \
  --player <player-address> \
  --angle 45000 \
  --power 500000

# Get game state
stellar contract invoke \
  --id <contract-id> \
  --source <any-account> \
  --network <NETWORK> \
  -- get_state

Game Example

#![allow(unused)]
fn main() {
// Initialize game
let state = AngryBirdsContract::init_level(env, player, 1);
// state: LevelState { level_id: 1, status: InProgress, score: 0, birds_remaining: 3, ... }

// Take first shot
let outcome = AngryBirdsContract::shoot(env, player, 45000, 500000);
// outcome: ShotOutcome::Miss (no entities to hit yet)

// Check state after shot
let state = AngryBirdsContract::get_state(env);
// state: LevelState { ..., birds_remaining: 2, ... }
}

Design Tradeoffs

Fixed-Point vs Floating-Point

• Choice: Fixed-point mathematics scaled by 1000
• Rationale: Ensures deterministic behavior across different execution environments
• Tradeoff: Limited precision compared to floating-point, but sufficient for game physics

Bounded Simulation

• Choice: Maximum 50 simulation steps per shot
• Rationale: Prevents gas limit issues and ensures predictable execution cost
• Tradeoff: May limit complex trajectory calculations, but adequate for turn-based gameplay

Grid-Based Collisions

• Choice: Simple circular collision detection with fixed radius
• Rationale: Computationally efficient and easy to verify
• Tradeoff: Less precise than continuous collision detection, but sufficient for puzzle gameplay

Integration with Cougr Framework

This example demonstrates several key benefits of the Cougr ECS framework:

1. Component Modularity: Each game aspect (position, health, material) is a separate, reusable component
2. System Separation: Game logic is organized into discrete systems with clear responsibilities
3. Scalability: Adding new features (power-ups, different bird types) requires minimal code changes
4. Testability: Components and systems can be tested independently
5. Clarity: The ECS architecture makes game state and logic immediately understandable

Future Enhancements

Potential extensions that showcase Cougr's flexibility:

• Multiple bird types with unique behaviors
• Power-up system using additional components
• Level editor for creating custom scenarios
• Multiplayer support with turn management
• Leaderboard system for high scores
• Visual themes using component-based rendering

Contributing

When contributing to this example:

1. Follow the existing ECS patterns and component structure
2. Maintain deterministic behavior for all game logic
3. Add comprehensive tests for new features
4. Update documentation for API changes
5. Ensure all build commands pass without errors

License

This example is licensed under MIT OR Apache-2.0, consistent with the main Cougr project.

Arkanoid On-Chain Game

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

A practical example demonstrating how to use the cougr-core package to implement Arkanoid game logic on the Stellar blockchain via Soroban smart contracts.

Overview

This example showcases:

• ECS Architecture: Component-based design using Cougr-Core patterns
• On-Chain Game Logic: Complete Arkanoid implementation without graphical interface
• Soroban Integration: Smart contract deployment on Stellar blockchain
• Comprehensive Testing: Full test coverage of game mechanics

Game Components

Following the Cougr-Core ECS pattern:

• PaddleComponent: Horizontal paddle position
• BallComponent: Ball position and velocity
• BricksComponent: Grid of breakable bricks (10x5)
• ScoreComponent: Score, lives, and game state

Prerequisites

Required Tools

1. Rust (1.88.0 or later)

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

2. Cargo (comes with Rust)

3. Stellar CLI

   cargo install stellar-cli --locked
   

4. WASM Target

   rustup target add wasm32v1-none
   

Verify Installation

rustc --version
cargo --version
stellar --version

Setup

1. Clone Repository

git clone https://github.com/salazarsebas/Cougr.git
cd Cougr/examples/arkanoid

2. Install Dependencies

cargo update

Development

Build

# Standard build
cargo build

# Release build
cargo build --release

# WASM build
cargo build --target wasm32v1-none --release

# Stellar CLI build (recommended for deployment)
stellar contract build

Test

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_init_game

Lint

# Format code
cargo fmt

# Run clippy
cargo clippy --all-features -- -D warnings

Deployment

1. Setup Testnet Account

Get test XLM from Friendbot:

# Generate a new keypair
stellar keys generate alice --network <NETWORK>

# Fund the account
stellar keys fund alice --network <NETWORK>

Or use the web faucet: https://faucet-stellar.acachete.xyz

2. Deploy Contract

# Build the contract
stellar contract build

# Deploy to testnet
stellar contract deploy \
  --wasm target/wasm32v1-none/release/arkanoid.wasm \
  --source alice \
  --network <NETWORK>

Save the contract ID returned (e.g., <CONTRACT_ID>XXX).

3. Invoke Contract Functions

Initialize Game

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source alice \
  --network <NETWORK> \
  -- init_game

Expected Output:

{
  "paddle_x": 50,
  "ball_x": 50,
  "ball_y": 50,
  "ball_vx": 1,
  "ball_vy": -1,
  "score": 0,
  "lives": 3,
  "game_active": true,
  "bricks_remaining": 50
}

Move Paddle

# Move right (direction = 1)
stellar contract invoke \
  --id <CONTRACT_ID> \
  --source alice \
  --network <NETWORK> \
  -- move_paddle --direction 1

# Move left (direction = -1)
stellar contract invoke \
  --id <CONTRACT_ID> \
  --source alice \
  --network <NETWORK> \
  -- move_paddle --direction -1

Update Game Tick

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source alice \
  --network <NETWORK> \
  -- update_tick

This advances the game by one frame:

• Moves the ball
• Checks collisions (walls, paddle, bricks)
• Updates score and lives
• Checks win/loss conditions

Get Game State

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source alice \
  --network <NETWORK> \
  -- get_game_state

Check Game Over

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source alice \
  --network <NETWORK> \
  -- check_game_over

Returns true if game is over, false otherwise.

Game Flow

1. Initialize: Call init_game() to set up the game state
2. Play Loop:
   • Call move_paddle(direction) to control the paddle
   • Call update_tick() to advance the game
   • Call get_game_state() to check current state
3. Game Over: When lives reach 0 or all bricks are broken

Game Mechanics

Constants

• Field: 100x60 units
• Paddle: Width 15, Speed 3
• Ball: Speed 1
• Bricks: 10 columns × 5 rows (50 total)
• Lives: 3

Scoring

• Breaking a brick: +10 points
• Win condition: Break all bricks
• Loss condition: Lives reach 0

Collisions

• Top/Side Walls: Ball bounces
• Bottom Wall: Lose 1 life, ball resets
• Paddle: Ball bounces upward
• Bricks: Brick breaks, ball bounces, score increases

Troubleshooting

Rust Version Issues

rustup update stable
rustup default stable

Dependency Resolution Errors

cargo clean
cargo update
cargo build

WASM Build Failures

Ensure WASM targets are installed:

rustup target add wasm32v1-none

Stellar CLI Not Found

cargo install stellar-cli --locked --force

Network Errors

Use --simulate flag to test without deploying:

stellar contract invoke --id <CONTRACT_ID> --simulate -- init_game

Architecture

Cougr-Core Benefits

This example demonstrates how Cougr-Core simplifies on-chain game development:

1. Component Pattern: Modular game data (Paddle, Ball, Bricks, Score)
2. System Pattern: Organized logic (Physics, Collision, Scoring systems)
3. Scalability: Easy to add features (power-ups, multiple balls)
4. Clarity: Clear separation of data and operations
5. Reusability: Components can be used across different games

ECS Systems

• PhysicsSystem: Updates ball position based on velocity
• CollisionSystem: Handles wall, paddle, and brick collisions
• ScoringSystem: Manages score, lives, and win/loss conditions

Testing

The test suite covers:

• ✅ Game initialization
• ✅ Paddle movement (left, right, bounds)
• ✅ Ball physics
• ✅ Wall collisions (top, sides, bottom)
• ✅ Paddle collision
• ✅ Brick breaking
• ✅ Scoring
• ✅ Lives system
• ✅ Game over conditions
• ✅ Inactive game state

Run tests with:

cargo test

CI/CD

GitHub Actions workflow automatically:

• Checks code compilation
• Runs formatting checks
• Runs clippy lints
• Executes all tests
• Builds WASM contracts
• Builds with Stellar CLI

License

MIT OR Apache-2.0

Resources

• Soroban Documentation
• Stellar CLI Guide
• Cougr Repository
• Rust Book
• Cargo Documentation

Asteroids (Soroban ECS Example)

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

This example demonstrates a complete Asteroids game implementation using Cougr ECS patterns on Soroban.

ECS Architecture

This example showcases full Entity-Component-System design following Cougr-Core patterns:

Components

All game objects are represented as ECS components implementing ComponentTrait:

• ShipComponent - Player ship with position (x, y), velocity (vx, vy), and rotation angle
• AsteroidComponent - Asteroids with position, velocity, and size (splits on destruction)
• BulletComponent - Projectiles with position, velocity, and lifetime counter
• ScoreComponent - Game state tracking points and lives

Systems

Game logic is organized into discrete systems that operate on components:

• MovementSystem - Updates positions based on velocities with screen wrapping
• CollisionSystem - Detects bullet-asteroid and ship-asteroid collisions
• ShootingSystem - Spawns bullet entities from ship position and angle
• AsteroidSplitSystem - Splits large/medium asteroids into smaller ones on destruction

Why ECS?

Compared to vanilla Soroban structs, the ECS approach provides:

1. Modularity - Components are reusable across different game types
2. Clarity - Systems clearly separate concerns (movement, collision, scoring)
3. Extensibility - Adding features (power-ups, enemies) requires only new components/systems
4. Testability - Individual systems can be tested in isolation

See examples/pong/ and examples/arkanoid/ for similar ECS patterns.

Project Structure

.
├── src
│   ├── lib.rs      # ECS components, systems, and contract implementation
│   └── test.rs     # Component serialization and gameplay tests
├── Cargo.toml
└── README.md

Setup

1. Install Rust + Cargo:

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

2. Add the WASM target:

rustup update
rustup target add wasm32v1-none

3. Install the Stellar CLI:

cargo install stellar-cli --locked

Development

Build and test locally:

cd examples/asteroids
cargo fmt
cargo build
cargo test
cargo clippy

Build Soroban WASM:

stellar contract build

Deployment

Deploy to Testnet:

stellar network add testnet \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015"

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 <NETWORK>

Invoke contract methods:

# Initialize game
stellar contract invoke \
  --id <CONTRACT_ID> \
  --source testnet \
  --network <NETWORK> \
  -- \
  init_game

# Control ship
stellar contract invoke \
  --id <CONTRACT_ID> \
  --source testnet \
  --network <NETWORK> \
  -- \
  rotate_ship --delta_steps 1

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source testnet \
  --network <NETWORK> \
  -- \
  thrust_ship

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source testnet \
  --network <NETWORK> \
  -- \
  shoot

# Update game state
stellar contract invoke \
  --id <CONTRACT_ID> \
  --source testnet \
  --network <NETWORK> \
  -- \
  update_tick

# Query state
stellar contract invoke \
  --id <CONTRACT_ID> \
  --source testnet \
  --network <NETWORK> \
  -- \
  get_game_state

Tests

The test suite covers:

• Component serialization/deserialization
• Ship rotation and thrust mechanics
• Bullet spawning and lifetime cleanup
• Asteroid splitting on destruction
• Ship-asteroid collision and lives system
• Game over conditions (no lives or no asteroids)

Run tests:

cargo test

Expected output:

test result: ok. 11 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Game Mechanics

• Ship: Rotates in 8 directions, applies thrust in facing direction
• Bullets: Travel in straight lines, despawn after 50 ticks
• Asteroids:
  • Size 3 (large) splits into 2 size 2 asteroids
  • Size 2 (medium) splits into 2 size 1 asteroids
  • Size 1 (small) is destroyed completely
• Scoring: +10 points per asteroid hit
• Lives: Start with 3, lose 1 on ship-asteroid collision
• Win: Destroy all asteroids
• Lose: Lives reach 0

Verification (Feb 22, 2026)

All standard build commands pass:

cargo build    # ✓ No errors
cargo test     # ✓ 11 tests pass
cargo clippy   # ✓ No warnings

Battleship with Hidden Board

Hidden Information Canonical

privacycommit-revealgame-appecs

View source on GitHub →

A two-player Battleship game demonstrating hidden information using commit-reveal pattern and Merkle proofs on Stellar Soroban. Players commit their board layouts cryptographically, then prove hit/miss results without revealing unattacked positions.

This example is Cougr's canonical hidden-information reference. It intentionally leans on the stable privacy surface in cougr_core::privacy::stable instead of re-defining Merkle verification inside the example.

Status

Canonical - maintained reference implementation for commit-reveal + selective disclosure on Soroban. Uses cougr-core = "1.1.0", privacy::stable Merkle primitives, and impl_component! macros for standardized serialization.

The Hidden Information Problem

Traditional on-chain games face a challenge: all data is public. In Battleship, if boards are stored directly on-chain, opponents can see ship positions and cheat.

Solution: Commit-Reveal + Merkle Proofs

SETUP PHASE (hide boards)
├─ Player A: commitment = SHA256(board || salt)
├─ Player A: merkle_root = MerkleTree(board).root
├─ Submit (commitment, merkle_root) on-chain
└─ Player B: same process

ATTACK PHASE (selective reveal)
├─ Attacker: attack(x, y)
├─ Defender: reveal_cell(x, y, value, merkle_proof)
├─ Contract: verify proof against merkle_root
└─ Record hit/miss (other cells remain hidden)

END PHASE (anti-cheat)
├─ Winner declared when all ships sunk
└─ Full board can be verified against commitment

Key Properties:

• ✅ Hiding: Unattacked cells remain secret
• ✅ Binding: Can't change board after commitment
• ✅ Selective Reveal: Prove one cell without revealing others
• ✅ Verifiable: Merkle proofs ensure honesty

Game Flow

1. Setup Phase

#![allow(unused)]
fn main() {
new_game(player_a, player_b)
}

Each player computes off-chain:

#![allow(unused)]
fn main() {
// 1. Create 10x10 board (0=water, 1=ship)
let board = [0u32; 100];
board[0] = 1; // Ship at (0,0)

// 2. Compute commitment
let commitment = SHA256(board || salt);

// 3. Build Merkle tree
let merkle_root = MerkleTree::new(board).root();

// 4. Submit on-chain
commit_board(player, commitment, merkle_root)
}

2. Attack Phase

Alternating turns:

Attacker:

#![allow(unused)]
fn main() {
attack(attacker, x, y)
}

Defender:

#![allow(unused)]
fn main() {
// Off-chain: get Merkle proof for cell (x,y)
let proof = merkle_tree.get_proof(x, y);

// On-chain: reveal with proof
reveal_cell(defender, x, y, value, proof)
}

Contract verifies:

1. Proof is valid against stored merkle_root
2. Records hit (value=1) or miss (value=0)
3. Updates ship count
4. Switches turn

3. Win Condition

Game ends when one player's ships are all sunk (17 hits total: 5+4+3+3+2).

Contract API

Data Structures

Phase

#![allow(unused)]
fn main() {
enum Phase {
    Setup,    // Waiting for board commitments
    Attack,   // Game in progress
    Finished, // Winner declared
}
}

CellResult

#![allow(unused)]
fn main() {
enum CellResult {
    Unknown, // Not yet attacked
    Miss,    // Attacked, no ship
    Hit,     // Attacked, ship present
}
}

BoardCommitment

#![allow(unused)]
fn main() {
struct BoardCommitment {
    commitment: BytesN<32>,  // SHA256(board || salt)
    merkle_root: BytesN<32>, // Root of Merkle tree
}
}

Stable Merkle Verification

The contract uses Cougr's stable SHA256 Merkle proof contract:

#![allow(unused)]
fn main() {
use cougr_core::privacy::stable::{MerkleProofVerifier, Sha256MerkleProofVerifier};

let verifier = Sha256MerkleProofVerifier;
assert!(verifier.verify(&env, &proof, &merkle_root)?);
}

The leaf payload still binds index || value, but the inclusion proof format and verification rules come from Cougr's stable privacy API.

When to Use Commit-Reveal vs ZK Circuits

Use commit-reveal when you need to hide state but reveal it incrementally with verifiable proofs. Use ZK circuits when the game logic itself must remain private (e.g., proving a move is valid without revealing the move).

For a reference ZK implementation, see hidden_hand, which demonstrates circuit-based hidden card dealing with Groth16 proofs.

Storage Model

Committed State

Stored on-chain during setup:

• commitment_a/b - SHA256 hash of each player's board with random salt
• merkle_root_a/b - root of the Merkle tree built from cell hashes
• has_commitment_a/b - flags tracking which players have committed

Both commitments must be submitted before the game transitions to Phase::Attack.

Revealed State

Updated during the attack phase:

• attack_grid_a/b - maps cell indices to CellResult (hit/miss)
• ship_status - tracks remaining ship cells per player (starts at 17)
• turn_state - tracks current player, phase, and pending reveals

Proven State

The reveal_cell function verifies that disclosed cell values match the original commitment:

1. Constructs the expected leaf hash from (index, value) using the same SHA256 scheme as the commit phase
2. Validates the OnChainMerkleProof against the stored merkle_root using Sha256MerkleProofVerifier
3. Only if the proof verifies is the hit/miss recorded on-chain

Component Serialization

BoardCommitment uses the impl_component! macro for standardized serialization:

#![allow(unused)]
fn main() {
impl_component!(BoardCommitment, "board", Table, {
    commitment: bytes32,
    merkle_root: bytes32
});
}

This replaces manual byte-level serialization with a type-safe macro that handles big-endian encoding/decoding automatically.

Building & Testing

Prerequisites

• Rust 1.88.0+
• Stellar CLI 25.0.0+ (optional)

Build

cargo build
cargo build --release --target wasm32v1-none

Test

cargo test

Test Coverage (12 tests):

Recommended Testing Approach: For verification of complex setup commitment sequences and attack/reveal turn-based interactions, utilize GameHarness and Scenario (see sandbox_tests.rs). This ensures cryptographic commitments and Merkle proofs verify correctly across turns.

Test Coverage (10 tests):

• ✅ Game initialization
• ✅ Board commitment
• ✅ Attack and reveal (miss)
• ✅ Attack and reveal (hit)
• ✅ Invalid proof rejection
• ✅ Cannot attack same cell twice
• ✅ Turn enforcement
• ✅ Win condition
• ✅ Component trait serialization (via impl_component!)
• ✅ Turn switching
• ✅ Reveal without pending attack
• ✅ Attack before commit phase

Example Usage

Off-Chain (Player)

#![allow(unused)]
fn main() {
// Build Merkle tree from hashed cell payloads
let mut leaves = Vec::new();
for (idx, &value) in board.iter().enumerate() {
    let leaf = sha256(idx || value);
    leaves.push(leaf);
}
let tree = MerkleTree::from_leaves(&env, &leaves)?;
let root = tree.root();

// Get proof for specific cell
let proof = to_on_chain_proof(&tree.proof(x * 10 + y)?, &env);

// Submit on-chain
client.reveal_cell(&player, &x, &y, &value, &proof);
}

On-Chain (Contract)

#![allow(unused)]
fn main() {
let verifier = Sha256MerkleProofVerifier;
assert!(verifier.verify(&env, &proof, &stored_merkle_root)?);
}

Security Considerations

Secure

• Commitment binding: SHA256 prevents changing board
• Selective reveal: Merkle proofs reveal only attacked cells
• Proof verification: Invalid proofs rejected
• Turn enforcement: Players alternate attacks

️ Important

• Salt randomness: Use 32 cryptographically random bytes
• Merkle tree depth: 7 levels for 100 cells (padded to 128)
• Proof ordering: Siblings must be in correct order

Best Practices

#![allow(unused)]
fn main() {
// ✅ Good: Random salt
let salt = generate_random_bytes(32);

// ❌ Bad: Predictable salt
let salt = BytesN::from_array(&env, &[0u8; 32]);

// ✅ Good: Verify proof before revealing
if !verify_proof(root, index, value, proof) {
    panic!("Invalid proof");
}
}

ECS Architecture

Components

Systems

Why Merkle Proofs?

Merkle trees enable selective disclosure:

For a 10x10 board:

• Full reveal: 100 cells
• Merkle proof: ~7 hashes (log₂ 128)

Deployment

# Deploy to testnet
stellar keys generate battleship-deployer --network <NETWORK> --fund
stellar contract deploy \
  --wasm target/wasm32v1-none/release/battleship.wasm \
  --source battleship-deployer \
  --network <NETWORK>

Resources

• Cougr Repository
• Merkle Trees
• Commitment Schemes
• hidden_hand - ZK circuit example
• Soroban Documentation

License

MIT OR Apache-2.0

blind_auction

Canonical ZK circuit example demonstrating circuits::sealed_bid for sealed-bid reveals.

Purpose and pattern

This example demonstrates how to run a blind auction on-chain. Bidders commit their encrypted bids, and during the reveal phase, submit a ZK proof to verify their bid value matches the original commitment and is below the maximum allowed bid limits, without revealing bids early or leaking bid range details.

Public contract API

Architecture overview

                         ┌───────────────┐
                         │    Bidder     │
                         └──────┬────────┘
                                │ Submits Bid & ZK Proof
                     ┌──────────▼──────────┐
                     │    BlindAuction     │
                     │ (Soroban Contract)  │
                     └──────────┬──────────┘
                                │ Loads Spec
                     ┌──────────▼──────────┐
                     │ circuits::          │
                     │  sealed_bid         │
                     └─────────────────────┘

The bidder submits their bid value and proof that verifies their bid corresponds to the committed hash. The contract runs the sealed_bid verifier logic to register the bid.

Storage model

Auction configuration records and active bid listings are stored in Instance Storage on-chain.

Main gameplay flow

1. Setup: Call init_auction to setup maximum bid constraints and the auction ID.
2. Commit Phase: Bidders record hash commitments of their bids (handled off-chain or via standard storage).
3. Reveal Phase: Bidders call reveal_bid with their bids and ZK proofs to unlock and register their bid weights.

Cougr APIs used

• circuits::sealed_bid: Handles verify calculations for sealed on-chain bidding logic.
• zk::Groth16Proof: Contains the proof struct representation.

Recommended testing approach

Use GameHarness and standard test_fixtures to execute happy-path reveals and invalid proof rejection flows.

Build and test commands

cargo test
stellar contract build

Known limitations

• Simple single-item auction model.
• Winner computation logic is not included (focuses on verification of bid validity).

Bomberman On-Chain Game

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

This example demonstrates how to implement a Bomberman game as a smart contract on the Stellar blockchain using Soroban and cougr-core.

Overview

This contract implements a simplified version of the classic Bomberman game where players can:

• Initialize a game with a grid
• Spawn and move players around the grid
• Place bombs that have individually configurable blast power
• Trigger chain reactions - a bomb overlapped by an explosion detonates instantly in the same tick
• Pick up power-ups that improve stats (blast radius, bomb capacity, movement speed)
• Handle collisions and scoring
• Check for game-over conditions

Setup

Prerequisites

• Rust (latest stable version)
• Cargo
• Stellar CLI (install with cargo install --locked stellar-cli)

Installation

1. Install Rust from https://rustup.rs/
2. Install Stellar CLI:

   cargo install --locked stellar-cli
   

Building the Contract

# Build the Rust code
cargo build

# Build the WASM file
stellar contract build

Testing and Validation

# Formatting check
cargo fmt --check

# Lint check
cargo clippy --all-targets --all-features -- -D warnings

# Run unit tests
cargo test

# Build WASM (target wasm32v1-none)
stellar contract build

Game Logic

ECS Components

Power-ups

Three power-up types are supported and modelled as first-class ECS entities:

Power-ups are spawned at game start (deterministic grid positions) and when a bomb destroys a destructible block (~25% chance via (x+y)%4==0). Walking over a PowerUpComponent entity silently applies the buff and removes the entity from the world (PickupSystem).

Chain Reactions

The ChainReactionSystem runs inside update_tick:

1. Bombs whose timer hits 0 are placed in a detonation_queue.
2. Each bomb is detonated in order - explosions are spawned immediately.
3. After each detonation, every remaining live bomb is checked for overlap with a fresh explosion cell. A hit bomb is removed and pushed to the back of the queue, so it detonates in the same tick - forming a cascade.
4. The process repeats until the queue is empty.

Systems at a Glance

Contract Functions

• init_game(): Initializes the game state
• move_player(player_id, direction): Moves a player in the specified direction
• place_bomb(player_id): Places a bomb at the player's current position
• update_tick(): Advances timers, triggers explosions, handles collisions
• get_score(player_id): Returns the current score for a player
• check_game_over(): Checks if the game has ended

Integration with Cougr-Core

This example demonstrates how cougr-core simplifies on-chain game development by providing:

• Persistent storage management for game state
• Transaction validation
• Generic game logic utilities
• Efficient data structures for complex game states

Deployment

Prerequisites for Deployment

1. Test Account: Fund a test account using the Friendbot: https://faucet-stellar.acachete.xyz
2. Stellar CLI: Install with cargo install --locked stellar-cli
3. WASM Build: Ensure the contract builds successfully

To Testnet

1. Build the WASM file:

   stellar contract build
   

2. Deploy the contract:

   stellar contract deploy \
     --wasm target/wasm32v1-none/release/bomberman.wasm \
     --source <your-secret-key> \
     --network <NETWORK>
   

3. the contract ID for future invocations (e.g., <CONTRACT_ID>)

https://stellar.expert/explorer/testnet/account/GAQAXKUQYNBHZYZ2OYISPXDZDP2HV57534VMGARGGIICH2BGNKDTKXOX

Testing the Contract

Invoke functions to test gameplay:

# Initialize game
stellar contract invoke \
  --id <contract-id> \
  --source <your-secret-key> \
  --network <NETWORK> \
  -- \
  init_game

# Move player (directions: 0=up, 1=right, 2=down, 3=left)
stellar contract invoke \
  --id <contract-id> \
  --source <your-secret-key> \
  --network <NETWORK> \
  -- \
  move_player \
  --player_id 1 \
  --direction 1

# Place bomb
stellar contract invoke \
  --id <contract-id> \
  --source <your-secret-key> \
  --network <NETWORK> \
  -- \
  place_bomb \
  --player_id 1

# Update game tick (advances timers, processes explosions)
stellar contract invoke \
  --id <contract-id> \
  --source <your-secret-key> \
  --network <NETWORK> \
  -- \
  update_tick

# Get player score
stellar contract invoke \
  --id <contract-id> \
  --source <your-secret-key> \
  --network <NETWORK> \
  -- \
  get_score \
  --player_id 1

# Check game status
stellar contract invoke \
  --id <contract-id> \
  --source <your-secret-key> \
  --network <NETWORK> \
  -- \
  check_game_over

Example Game Sequence

1. Initialize: Call init_game to set up the world
2. Spawn Players: In a full implementation, add player spawning functions
3. Gameplay Loop:
   • Move players with move_player
   • Place bombs with place_bomb
   • Advance game state with update_tick
   • Check scores and game status periodically
4. Game Over: Monitor check_game_over for completion

Cost Monitoring

Monitor transaction costs during testing:

• Rent: Storage costs on Stellar ledger
• Fees: Network transaction fees
• CPU/RAM: Contract execution costs

Use --simulate flag to estimate costs before actual deployment:

stellar contract invoke --simulate [other flags]

Troubleshooting

Common Issues

1. Rust version conflicts: Update Rust with rustup update
2. Stellar CLI not found: Ensure it's in your PATH after installation
3. Compilation errors: Check that all dependencies are correctly specified in Cargo.toml

Debug Commands

# Verbose build
cargo build --verbose

# Check Stellar CLI version
stellar --version

# Simulate contract deployment
stellar contract deploy --wasm target/wasm32v1-none/release/bomberman.wasm --simulate

Architecture

The contract uses the cougr-core ECS (Entity–Component–System) pattern for all game state:

• Entities: Numeric IDs created by world.spawn_entity() / removed by world.despawn_entity()
• Components: Plain structs implementing ComponentTrait (typed serialize / deserialize)
• Systems: Free functions / inline blocks inside contract entry-points that compose over component queries

All state is persisted in a single SimpleWorld under DataKey::World. The separation of components and systems makes it straightforward to add new mechanics without touching unrelated code.

Checkers

Board Transitional

ecs

View source on GitHub →

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

A fully on-chain two-player Checkers game implemented as a Soroban smart contract.

Purpose and pattern

This example demonstrates a turn-based board game with non-trivial rule enforcement - diagonal grid movement, mandatory captures, multi-hop chain captures, king promotion, and win detection - implemented as plain Rust functions over #[contracttype] structs. It showcases the simplest possible Cougr-adjacent pattern: component-shaped data types with hand-written contract storage access, predating the ComponentTrait/GameApp conventions used by newer examples. It is a useful reference for understanding what a Soroban board-game contract looks like with no ECS framework involvement at all.

Public contract API

Error codes

Architecture overview

There is no GameApp tick loop. submit_move runs a fixed validation/update pipeline synchronously on each call:

submit_move
  └─ identify caller, check turn order, bounds, and dark-square rule
  └─ MoveValidationSystem  (systems.rs: legal_steps / legal_captures)
       → confirms the requested move is a legal step or capture for this piece
  └─ forced-capture check   (systems.rs: any_capture_available)
       → rejects a non-capture move if any capture exists for the player
  └─ apply move + remove captured piece
  └─ PromotionSystem        (systems.rs: maybe_promote)
       → crowns a man reaching the opponent's back rank
  └─ chain-capture detection (systems.rs: legal_captures on the landing square)
       → holds the turn and records the active square if another capture is available
  └─ EndConditionSystem     (systems.rs: check_winner)
       → declares a winner on piece-count exhaustion or no legal moves
  └─ TurnSystem
       → advances current_player, or holds it during a chain capture

components.rs holds the data shapes (BoardComponent, TurnComponent, GameStatusComponent, GameStatus, the public GameState/BoardState view types, the internal ChainCapture tracker, and the small SmallVec4 fixed-capacity collection). systems.rs holds the pure, storage-free game-logic functions (move/capture legality, promotion, win detection, board initialisation). lib.rs is the only module that touches env.storage(); it loads components, calls into systems.rs, and writes the results back.

Storage model

All state lives in persistent storage, under five top-level Symbol keys:

Persistent storage (rather than instance storage) is used because each key is read and rewritten independently inside submit_move - the board, turn, and status are not bundled into one aggregate struct in this example, so per-key persistent entries map directly onto that access pattern. The CHAIN key is removed as soon as a turn fully ends; its absence is what tells submit_move that no multi-hop sequence is active, so it doubles as both data and a lightweight state flag.

Main gameplay flow

1. Deployer calls init_game(player_one, player_two). The board is seeded with the standard 12-piece-per-side opening position; Player One moves first.
2. Player One calls submit_move with a (from_row, from_col) → (to_row, to_col) pair. The contract checks turn order, bounds, the dark-square rule, piece ownership, and move geometry (diagonal step or jump).
3. If any capture is available for the mover anywhere on the board, a non-capture move is rejected with MustCapture - captures are mandatory, not optional.
4. On a legal capture, the jumped piece is removed. If the landing square has a further capture available, the turn is held: the same player must continue jumping with the same piece (tracked via the CHAIN key) until no further capture exists.
5. A man reaching the opponent's back rank is promoted to a king immediately after the move that lands it there, before chain-capture continuation is checked.
6. After each move, EndConditionSystem checks whether either side has no pieces left or no legal move available; if so, STATUS flips to Finished with a recorded winner.
7. Players alternate submit_move calls until a winner is recorded; get_state, get_board, and get_current_player provide read-only views at any point.

Cougr APIs used

• cougr_core::component::ComponentTrait - gives each component (BoardComponent, TurnComponent, GameStatusComponent) a component_type() symbol and byte-level serialize/deserialize, chosen here because the game has a single fixed set of components per instance rather than a dynamic entity population that would benefit from SimpleWorld/SimpleQueryBuilder scanning.

Per the API usage guidance in EXAMPLE_STANDARD.md §8, GameApp/ScheduleStage, SimpleWorld, auth, and privacy APIs do not apply here: there is exactly one fixed-shape game state per contract instance, one synchronous validation pipeline per call, no session-key or multi-device flow, and no hidden information or proof submission. This example is kept as a transitional reference precisely because it predates Cougr's GameApp tick conventions - see snake for the current recommended approach.

Build and test commands

cargo test
stellar contract build

Known limitations

• Does not use GameApp, ScheduleStage, or SimpleWorld - game logic is invoked directly from contract entrypoints rather than through a tick-based scheduler, since a two-player, one-decision-per-call board game does not require staged scheduling or entity queries.
• No timeout/forfeit mechanism for an unresponsive player.
• No draw detection (e.g., repetition or no-progress rules); a game can only end by piece exhaustion or a player having no legal move.
• No spectator or replay API beyond the three read-only getters.

Verifiable Chess with ZK Move Validation

Transitional example: This example uses an older Cougr pattern and is preserved for compatibility reference. For the current recommended approach to ZK-backed game logic specifically, see hidden_hand, which uses cougr_core::circuits' pre-built circuit builders instead of constructing a CustomCircuit by hand.

A simplified chess implementation on Stellar Soroban that demonstrates zero-knowledge proof verification for move legality using the Cougr ZK framework. Move legality is checked off-chain by a circuit; the contract only verifies a compact Groth16 proof and applies the move.

Purpose and pattern

This example demonstrates how to keep move-validation logic entirely off-chain while still enforcing it trustlessly: instead of the contract checking piece-movement rules, path obstruction, and check/checkmate conditions on every move, the player generates a Groth16 proof off-chain that the move is legal given the current board state, and the contract verifies that proof in constant time. It showcases cougr_core::privacy::experimental's generic CustomCircuit builder for binding a proof's public inputs (state_hash, from, to) to a verification key, alongside the same ComponentTrait pattern used by the other ECS-lite examples for typed, byte-serializable game state.

Public contract API

Architecture overview

There is no GameApp tick loop. submit_move runs a fixed pipeline synchronously on each invocation:

submit_move
  └─ TurnSystem              → rejects calls from the wrong player or a finished game
  └─ ProofVerificationSystem → verifies the Groth16 proof against state_hash/from/to via CustomCircuit
  └─ BoardUpdateSystem       → applies the move to the piece map, recomputes state_hash
  └─ TurnSystem              → increments move_count, switches current player
  └─ EndGameSystem           → marks Checkmate if either king is no longer on the board

components.rs defines the data (Piece, BoardState, TurnState, ProofRecord, GameState, MoveResult) and the ComponentTrait implementations for BoardState and TurnState. systems.rs holds the pure, storage-free game logic (init_board, compute_state_hash, apply_move, check_endgame). zk.rs holds the proof-verification wrapper (build_move_circuit, decode_proof) built on cougr_core::privacy::experimental. lib.rs owns the single GameState aggregate, is the only module that touches contract storage, and wires the systems and the ZK verification step together inside submit_move.

Storage model

The entire game lives under one instance-storage key (GAME_KEY, symbol_short!("GAME")) as a single GameState struct bundling both player addresses, the board, turn state, and the last proof record. The verification key is stored separately under its own instance-storage key (VK_KEY, symbol_short!("VK")) so it can be rotated with set_vk independently of game state. Instance storage is used for both - not persistent or temporary - because there is exactly one game and one verification key per contract instance, with no per-entry TTL management needed.

Main gameplay flow

1. Deployer calls set_vk(vk) once to register the Groth16 verification key matching the off-chain move-validation circuit.
2. Deployer (or either player) calls new_game(white, black); the board is seeded with the standard opening position, White to move, and the initial state_hash is computed.
3. Off-chain, White picks a move (from, to), runs the move-validation circuit against the current state_hash, and produces a Groth16 proof that the move is legal.
4. White calls submit_move(white, from, to, proof). The contract checks turn order, verifies the proof via CustomCircuit, and on success applies the move, recomputes state_hash, records the proof, and switches the turn to Black.
5. Players alternate steps 3-4. If a king is ever captured, EndGameSystem sets the status to Checkmate; either player may also call resign at any time to end the game early.
6. Any caller reads get_board or get_state to render the current position or check status.

Cougr APIs used

• cougr_core::component::ComponentTrait - gives BoardState and TurnState a component_type() symbol and byte-level serialize/deserialize, chosen because chess has a single fixed-shape game state per contract instance rather than a dynamic entity population that would benefit from SimpleWorld/SimpleQueryBuilder scanning.
• cougr_core::privacy::experimental (CustomCircuit) - chosen specifically because this example demonstrates Groth16 proof submission: the contract never evaluates chess rules itself, it only binds a proof's public inputs (state_hash, from, to) to a verification key and checks the proof verifies. This is the canonical use case the privacy::experimental guidance in the Cougr API table calls out (Groth16 proof submission / pairing-based verification), as opposed to privacy::stable, which is for commit-reveal and Merkle-proof patterns this example does not use. Newer examples (hidden_hand, fog_explorer, dice_duel, blind_auction) use the higher-level cougr_core::circuits pre-built builders instead of hand-rolling a CustomCircuit; this example predates that module and is kept as a reference for the lower-level builder API.
• cougr_core::privacy::{Groth16Proof, VerificationKey} - the concrete proof and key types the CustomCircuit builder and verifier operate on; stored on-chain (VerificationKey) or passed per-call (Groth16Proof, decoded from the proof: Bytes argument) so the contract has everything it needs to verify a move without re-deriving any chess logic.

Build and test commands

cargo test
stellar contract build

Known limitations

• Proof decoding (zk::decode_proof) is not implemented - it intentionally panics, since wiring up a real off-chain Groth16 prover/serializer is out of scope for this example. Tests exercise the turn/resign/game-over paths that return before proof verification is reached.
• The move-validation circuit itself (piece movement rules, path obstruction, check/checkmate detection) lives off-chain and is not part of this repository; only the on-chain verification wrapper is shown.
• Checkmate detection is simplified to "a king is missing from the board" rather than full check/checkmate/stalemate rules. Castling, en passant, and pawn promotion are not modeled.
• Does not use GameApp, ScheduleStage, or SimpleWorld - submit_move runs its pipeline directly from the contract entrypoint since each call has exactly one decision point and does not need staged scheduling.

Connect Four

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

An on-chain Connect Four game built with the Cougr ECS framework on Stellar Soroban.

Purpose and pattern

This example demonstrates a turn-based, perfect-information board game driven by gravity-based piece placement: a move only specifies a column, and the contract resolves which row the piece lands in before checking for a win. It showcases Cougr's ComponentTrait pattern for typed, byte-serializable game state - components are plain Rust structs annotated with #[contracttype] that implement ComponentTrait directly, rather than being scanned through SimpleWorld/SimpleQueryBuilder. This is a lighter-weight integration suited to a single fixed-shape game state (one board, two players) with no dynamic entity population.

Public contract API

Architecture overview

There is no GameApp tick loop - drop_piece runs all systems synchronously in a fixed pipeline on each invocation:

drop_piece
  └─ validation_system     → rejects out-of-turn, out-of-bounds, full-column, or post-game moves
  └─ gravity_system        → finds the lowest empty row in the target column
  └─ execution_system      → places the piece and increments the move counter
  └─ win_detection_system  → scans the board for horizontal/vertical/diagonal 4-in-a-row
  └─ draw_system           → marks the game a draw if the board fills with no winner
  └─ turn_system           → advances to the other player if the game is still active

Each system is a pure function over components.rs types (BoardComponent, PlayerComponent, GameStateComponent, bundled into ECSWorldState); lib.rs owns that aggregate and is the only module that touches contract storage.

Storage model

The entire game lives under one instance-storage key (WORLD_KEY, symbol_short!("WORLD")) as a single ECSWorldState struct bundling the board, both player addresses, and the game-state component (turn, move count, status, last move). Instance storage is used - not persistent or temporary - because there is exactly one game per contract instance and the state must survive for the lifetime of that instance with no per-entry TTL management.

Main gameplay flow

1. Deployer calls init_game(player_one, player_two); the board is seeded empty, player_one to move, status in-progress.
2. player_one calls drop_piece(player, column). The contract checks turn order, column bounds, and that the column isn't full.
3. On a legal move: gravity_system finds the lowest empty row in that column, execution_system places the piece there and increments the move count, win_detection_system scans the whole board for a 4-in-a-row, and draw_system marks the game a draw if all 42 cells are filled with no winner.
4. If the game is still in progress, turn_system switches to the other player; the updated ECSWorldState is written back to instance storage.
5. Players alternate drop_piece calls until is_finished returns true. Either player reads get_winner to see who won (or None for a draw).
6. reset_game can be called at any point to start a fresh game with the same two players.

Cougr APIs used

• cougr_core::component::ComponentTrait - gives each component (BoardComponent, GameStateComponent) a component_type() symbol and explicit byte-level serialize/deserialize. This was chosen because the game has one fixed-shape ECSWorldState per contract instance (a single board, two fixed player slots, one game- state record) rather than a dynamic population of entities that would benefit from SimpleWorld/SimpleQueryBuilder scanning - per the guidance in EXAMPLE_STANDARD.md §8, SimpleWorld and SimpleQueryBuilder are for examples that store and query entities by component type, which doesn't apply here. PlayerComponent is also #[contracttype] but does not implement ComponentTrait, since it is embedded directly in ECSWorldState rather than serialized standalone.
• No GameApp, ScheduleStage, auth, privacy::stable/experimental, or ops standards are used - drop_piece has exactly one decision point per call, so there is no multi-stage tick to schedule, no hidden information to commit-reveal, and no pausability/ownership requirement for a two-player, always-on game.

Build and test commands

cargo test
stellar contract build

Known limitations

• Does not use GameApp, ScheduleStage, or SimpleWorld - game logic is invoked directly from contract entrypoints rather than through a tick-based scheduler, since a turn-based game with one decision point per call does not need staged scheduling.
• No timeout/forfeit mechanism for an unresponsive player.
• win_detection_system re-scans the entire board on every move rather than checking only the cell that was just placed; this is simple and correct but not the most efficient approach for a larger board.
• No spectator or replay API beyond the read-only getters.

Cross-Asset Racing League (Stellar + Soroban)

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

Cross-Asset Racing League is a multi-asset payment-driven racing game example for Soroban that combines:

• payment-gated boost mechanics enabled by cross-asset payment flows
• proof-backed race-state validation through stellar-zk
• league standings and progression tracking
• deterministic race result verification

This example is intentionally contract-only: no frontend, no real-time physics simulation, no multiplayer middleware.

Why This Is Stellar-Specific

This example demonstrates three Stellar-native patterns working together:

1. Soroban contract state for deterministic race progression and league management.
2. stellar-zk style Groth16 verification on-chain using Soroban BN254 pairing checks for anti-cheat and race integrity.
3. x402-style payment credits represented as settled payment units tied to multi-asset payment flows.

References:

• https://crates.io/crates/stellar-zk
• https://github.com/salazarsebas/stellar-zk
• https://developers.stellar.org/docs/build/apps/x402

Gameplay Flow

1. League Initialization

The owner initializes a racing league, establishing:

• Season ID and tracking metadata
• Initial contract state for race creation and standings

2. Race Creation

The owner creates a race instance with:

• Unique race ID
• Duration (in ledger blocks)
• Registration phase for player entry
• Support for up to 10 racers per race

3. Player Entry

Players join a race during the registration phase:

• Entrant cap enforced (max 10 racers)
• Vehicle state initialized for each player
• Replay protection via tracking entered players

4. Race Activation

Owner starts the race, transitioning it to the active phase:

• Entrants are locked in
• Payment-gated boosts can now be activated
• Race-state proofs can be submitted

5. Payment-Gated Boost Activation

Players consume pre-settled payment credits to activate boosts:

• Standard Boost (cost: 10 credits) → +10 speed
• Premium Boost (cost: 50 credits) → +30 speed
• Legendary Boost (cost: 200 credits) → +60 speed

Payment flow:

1. Off-chain settlement process (e.g., via x402 gateway) receives cross-asset payment
2. Owner calls credit_payment(player, amount, receipt_hash) with proof of settlement
3. Replay protection via receipt hash prevents double-crediting
4. Player activates boost, consuming credits in-contract

6. Proof-Backed Race Validation

Players submit Groth16 proofs to validate race integrity:

• Proof verifies correct race execution state
• Public inputs bound to race commitments
• Nullifier-based replay protection
• BN254 pairing checks ensure anti-cheat properties

7. Race Completion and Standings Update

Owner completes the race:

• Race transitions to completed phase
• Points awarded by position: 1st=10, 2nd=6, 3rd=3, rest=1
• League standings updated for each racer

Architecture

The example follows a modular architecture, separating data structures, ECS components, business systems, and contract entrypoints.

Module Layout

• lib.rs: Contract entrypoints and orchestration.
• types.rs: Shared domain models, enums, and storage keys.
• components.rs: Cougr ECS component definitions.
• systems.rs: Core gameplay transitions and logic.
• helpers.rs: Validation and verification utilities.

Components

Systems

• RaceSystem: Handles create_race, enter_race, start_race, complete_race, and submit_race_proof.
• PaymentSystem: Handles credit_payment logic.

stellar-zk Integration

Proof-Backed Race Integrity

This contract uses stellar-zk for a real validation path:

1. Race Commitment: Off-chain race state committed via Merkle root
2. Proof Generation: Player proves valid race state against commitment
3. On-Chain Verification: BN254 pairing checks verify the Groth16 proof
4. Nullifier Protection: Prevents replay attacks using commitment hashing

Proof Structure

#![allow(unused)]
fn main() {
pub struct ProofInput {
    pub proof: BytesN<256>,           // Groth16 proof (compressed)
    pub public_inputs: Bytes,          // Public inputs bound to race state
    pub commitment: BytesN<32>,        // Race state commitment root
    pub race_id: u32,                  // Associated race
    pub player_id: u32,                // Associated player
}
}

Verification Pattern

1. Extract public inputs from proof
2. Verify proof structure and length
3. Hash commitment for nullifier uniqueness
4. Check nullifier not previously used (replay protection)
5. Perform BN254 pairing checks (Groth16 verifier)
6. Mark nullifier as consumed

Contract API

Initialization

#![allow(unused)]
fn main() {
fn init_league(env: Env, owner: Address)
}

Initializes the racing league. Requires owner authorization.

Race Management

#![allow(unused)]
fn main() {
fn create_race(env: Env, owner: Address, duration: u32) -> u32
}

Creates a new race with specified duration. Returns race ID. Owner-only.

#![allow(unused)]
fn main() {
fn start_race(env: Env, owner: Address, race_id: u32)
}

Transitions race from registration to active phase. Owner-only.

#![allow(unused)]
fn main() {
fn complete_race(env: Env, owner: Address, race_id: u32)
}

Completes the race, updates standings, and awards points. Owner-only.

Player Actions

#![allow(unused)]
fn main() {
fn enter_race(env: Env, player: Address, race_id: u32)
}

Player enters a race during registration phase. Requires player authorization.

#![allow(unused)]
fn main() {
fn activate_boost(env: Env, player: Address, race_id: u32, boost_type: u32)
}

Player activates a boost by spending payment credits. Boost types: 1=Standard, 2=Premium, 3=Legendary.

Payment Integration

#![allow(unused)]
fn main() {
fn credit_payment(env: Env, owner: Address, player: Address, amount: u32, receipt_hash: BytesN<32>)
}

Owner credits player with payment settlement. Receipt hash prevents double-crediting. Owner-only.

#![allow(unused)]
fn main() {
fn get_player_credits(env: Env, player: Address) -> u32
}

Query player's available payment credits.

Proof Validation

#![allow(unused)]
fn main() {
fn submit_race_proof(env: Env, player: Address, proof: ProofInput) -> bool
}

Player submits proof for race-state validation. Returns true if proof is valid. Implements replay protection via nullifier.

Query Functions

#![allow(unused)]
fn main() {
fn get_game_state(env: Env) -> GameState
}

Returns current league state.

#![allow(unused)]
fn main() {
fn get_race(env: Env, race_id: u32) -> Race
}

Returns race details.

#![allow(unused)]
fn main() {
fn get_player_standing(env: Env, season_id: u32, player: Address) -> PlayerStanding
}

Returns player's season standings with points, completion count, and best finish.

Payment Model and Cross-Asset Integration

This example models payment as abstract credited-unit settlement:

Off-Chain Settlement (Illustrative)

1. Player initiates cross-asset trade (e.g., USDC → stablecoin or asset)
2. Payment gateway settles transaction
3. Settlement proof returned to owner with receipt hash

On-Chain Credit

Owner calls credit_payment(player, units, receipt_hash):

• Units represent settled payment value
• Receipt hash ensures idempotent settlement
• Credits are consumed by boost activation

Multi-Asset Representation

In production, payment units could represent:

• USDC stablecoins
• Native Stellar lumens (XLM)
• Custom issued assets
• Cross-chain bridged assets

The contract treats all as abstract credits, allowing flexible payment backends.

Testing

Run tests with:

cargo test

Test Coverage

• League initialization
• Race creation and player entry
• Boost activation with various types
• Payment credit system
• Proof validation and replay protection
• Race completion and standings
• Multiple races and cumulative standings
• Error conditions and edge cases

Building and Validation

Build the contract

cargo build --release

Format and lint

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings

Run tests

cargo test

Build to WASM

stellar contract build

Design Decisions

Why Abstract Payments?

The contract doesn't directly integrate with specific payment backends (Stripe, PayPal), but instead accepts settled credits. This allows flexibility:

• The same contract can work with different payment gateways
• Payment logic can be upgraded off-chain without contract changes
• Anti-censorship: payment flow doesn't depend on specific custodian

Why Proof-Based Anti-Cheat?

Groth16 proofs enable:

• Hidden tuning: Players prove valid race parameters without revealing them
• Deterministic fairness: Proof ties race outcome to cryptographic commitment
• Privacy: Only commitment revealed on-chain, detailed race state stays off-chain

Why Ledger-Based Timing?

Race duration uses ledger sequence numbers, not wall-clock time:

• Stellar ledgers close ~every 5 seconds (deterministic)
• No oracle dependency for timing
• Replay protection via sequence-based race ID

Files

• src/lib.rs: Main contract entrypoints and orchestration
• src/types.rs: Data structures, enums, and storage keys
• src/components.rs: ECS components
• src/systems.rs: Core game logic and transitions
• src/helpers.rs: Validation helpers
• src/test.rs: Unit tests
• README.md: Architectural overview and documentation
• Cargo.toml: SDK dependencies

Compatibility

• Soroban SDK: 25.1.0
• Edition: 2021
• Target: wasm32v1-none

License

MIT OR Apache-2.0

dice_duel

Canonical ZK circuit example demonstrating circuits::fair_dice for verifiable dice rolls.

Purpose and pattern

This example showcases a verifiable on-chain dice rolling game. Players generate random numbers off-chain and submit ZK proofs to prove that their roll result is deterministic, within bounds, and bound to the initial committed seed, preventing manipulation of on-chain randomness.

Public contract API

Architecture overview

                         ┌───────────────┐
                         │    Player     │
                         └──────┬────────┘
                                │ Rolls & Generates ZK Proof
                     ┌──────────▼──────────┐
                     │      DiceDuel       │
                     │ (Soroban Contract)  │
                     └──────────┬──────────┘
                                │ Loads Spec
                     ┌──────────▼──────────┐
                     │ circuits::          │
                     │  fair_dice          │
                     └─────────────────────┘

The player commits a random seed and runs a deterministic calculation. They submit a Groth16 proof showing the calculation output matches the result of their roll.

Storage model

Dice duel config and player roll history are stored in Instance Storage on-chain via Soroban instance key-value associations.

Main gameplay flow

1. Setup: Call init_duel to bind the dice properties and seed commitment.
2. Roll: Players roll dice off-chain and calculate proof.
3. Submit: Players call submit_roll to verify and record the roll on-chain.

Cougr APIs used

• circuits::fair_dice: Implements the dice roll verification boundary specifications.
• zk::Groth16Proof: Holds proof payload.

Recommended testing approach

Integrate GameHarness and Scenario runner combined with test_fixtures::pipeline_proof to simulate individual rolls and multi-player roll scenarios.

Build and test commands

cargo test
stellar contract build

Known limitations

• Simple single-roll mechanics.
• The seed is assumed to be cryptographically secure and generated off-chain.

Flappy Bird On-Chain Game

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

Purpose and pattern

This example demonstrates a side-scroller gravity loop on Soroban with Cougr ECS concepts. It remains transitional while the arcade examples converge on the canonical snake GameApp architecture.

Public contract API

Architecture overview

contract entrypoint
  ├─ reads game state from Soroban storage
  ├─ applies input or tick systems
  └─ writes updated state back to storage

Bird, pipe, position, velocity, and scoring markers are represented as ECS components in components.rs and updated by systems in systems.rs.

Storage model

Main gameplay flow

1. Call the initialization function to create the starting state.
2. Submit an input action such as movement, jump, flap, rotation, or shoot.
3. Call the tick/update function to run deterministic simulation logic.
4. Query public getters for score, position, active state, or terminal status.
5. Stop when the game-over/completed condition is reached, or reset/reinitialize where supported.

Cougr APIs used

• ComponentTrait and custom component modules document the ECS data boundary.
• SimpleWorld, SimpleQueryBuilder, GameApp, ScheduleStage, or SystemConfig are used where this transitional example has already adopted the maintained runtime shape.
• Auth, privacy, ZK, and standards APIs are intentionally not used; these arcade examples focus on deterministic game logic.

Build and test commands

cargo test
stellar contract build

Known limitations

The tests cover:

• Game initialization
• Bird flapping mechanics
• Gravity and physics
• Collision detection
• Score tracking
• Game over conditions

Deploying to Testnet

1. Create and Fund Account

Generate a new keypair:

stellar keys generate test-account --network <NETWORK>

Get the account address:

stellar keys address test-account

Fund the account using Friendbot:

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

2. Deploy Contract

stellar contract deploy \
  --wasm target/wasm32v1-none/release/flappy_bird.wasm \
  --source test-account \
  --network <NETWORK>

Save the returned CONTRACT_ID for later use.

3. Play the Game

Initialize Game

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source test-account \
  --network <NETWORK> \
  -- init_game

Make Bird Flap

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source test-account \
  --network <NETWORK> \
  -- flap

Advance Game Tick

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source test-account \
  --network <NETWORK> \
  -- update_tick

Check Score

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source test-account \
  --network <NETWORK> \
  -- get_score

Check Game Status

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source test-account \
  --network <NETWORK> \
  -- check_game_over

Get Bird Position

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source test-account \
  --network <NETWORK> \
  -- get_bird_pos

Game Mechanics

Constants

• GRAVITY: 2 pixels per tick
• FLAP_VELOCITY: -15 pixels per tick (upward)
• PIPE_SPEED: 3 pixels per tick (leftward)
• GROUND_Y: 400 pixels
• BIRD_SIZE: 20 pixels (hitbox radius)
• PIPE_GAP: 100 pixels

How to Play

1. Initialize a new game with init_game()
2. Make the bird flap with flap() to gain upward velocity
3. Advance the game with update_tick() - this applies:
   • Gravity to the bird
   • Movement to all entities
   • Collision detection
   • Score updates
4. Repeat steps 2-3 to keep the bird alive and score points
5. Game ends when bird hits ground, ceiling, or pipes

Scoring

• Score increases by 1 for each pipe successfully passed
• Bird must pass through the gap without touching the pipe

Code Examples

Creating a Custom Component

#![allow(unused)]
fn main() {
#[contracttype]
#[derive(Clone, Debug)]
pub struct BirdState {
    pub is_alive: bool,
}

impl ComponentTrait for BirdState {
    fn component_type() -> Symbol {
        symbol_short!("birdstate")
    }

    fn serialize(&self, env: &Env) -> Bytes {
        let mut bytes = Bytes::new(env);
        let value: u8 = if self.is_alive { 1 } else { 0 };
        bytes.append(&Bytes::from_array(env, &[value]));
        bytes
    }

    fn deserialize(env: &Env, data: &Bytes) -> Option<Self> {
        if data.len() != 1 {
            return None;
        }
        let is_alive = data.get(0).unwrap() != 0;
        Some(Self { is_alive })
    }
}
}

Implementing a Game System

#![allow(unused)]
fn main() {
pub fn apply_gravity(world: &mut World, env: &Env) {
    for entity in world.entities.iter_entities() {
        let entity_id = entity.id();
        if entity.has_component(&symbol_short!("birdstate")) {
            if let Some(vel_comp) = world.get_component(entity_id, &symbol_short!("velocity")) {
                if let Some(mut velocity) = Velocity::deserialize(env, vel_comp.data()) {
                    velocity.y += GRAVITY;
                    let new_vel_comp = Component::new(
                        symbol_short!("velocity"),
                        velocity.serialize(env)
                    );
                    world.storage.add_component(entity_id, new_vel_comp);
                }
            }
        }
    }
}
}

Troubleshooting

Common Issues

Issue: error: failed to compile

• Solution: Ensure you have the correct Rust version (1.88.0+) and wasm32 target installed
• Run: rustup update && rustup target add wasm32v1-none

Issue: stellar: command not found

• Solution: Install Stellar CLI following the official guide

Issue: Contract size too large

• Solution: Ensure you're using release mode and the optimizations in Cargo.toml:

  [profile.release]
  opt-level = "z"
  lto = true
  codegen-units = 1
  

Issue: Transaction fails with "budget exceeded"

• Solution: On-chain games are resource-intensive. Consider simplifying game logic or reducing the number of entities

Debugging Tips

1. Use cargo test to verify logic before deploying
2. Use --simulate flag to test transactions without broadcasting:

   stellar contract invoke --id <CONTRACT_ID> --simulate -- init_game
   

3. Check contract logs in Stellar Explorer
4. Use smaller test scenarios to isolate issues

Performance Considerations

On-Chain Constraints

• WASM Binary Size: Keep contract under 1MB (optimized binary should be ~200KB)
• Transaction Costs: Each transaction consumes fees - minimize storage operations
• Execution Budget: Soroban has CPU and memory limits - keep game ticks simple

Optimizations Used

1. Opt-level "z": Optimize for size in release builds
2. LTO: Link-time optimization reduces binary size
3. Minimal Storage: Only store essential game state
4. Efficient Queries: Cache entity lookups when possible

Next Steps

Extending the Game

1. Add Power-ups: Create new components for temporary abilities
2. Difficulty Scaling: Increase pipe speed over time
3. Multiplayer: Store multiple game states with player IDs
4. Leaderboard: Track high scores across players
5. Visual Output: Create a frontend that reads contract state and renders graphics

Learning More

• Cougr-Core Documentation
• Soroban Documentation
• ECS Pattern

License

This example is part of the Cougr project and follows the same license.

Contributing

• Transitional code may preserve older storage or scheduling patterns for compatibility reference.
• No authentication, matchmaking, real-time rendering, or production randomness is included.
• One contract instance generally represents one game or one keyed set of player games.
• For new work, prefer the canonical snake module split and GameApp tick wiring.

fog_explorer

Canonical ZK circuit example demonstrating circuits::fog_of_war for private exploration.

Purpose and pattern

This example showcases a verifiable "fog of war" map exploration. Players move around a private map commitment, proving that they only reveal cells within their current line-of-sight visibility radius, without publishing the full map layout or their exact positions on the public blockchain.

Public contract API

Architecture overview

                         ┌───────────────┐
                         │    Player     │
                         └──────┬────────┘
                                │ Moves & Generates ZK Proof
                     ┌──────────▼──────────┐
                     │     FogExplorer     │
                     │ (Soroban Contract)  │
                     └──────────┬──────────┘
                                │ Loads Spec
                     ┌──────────▼──────────┐
                     │ circuits::          │
                     │  fog_of_war         │
                     └─────────────────────┘

The player proves off-chain that the update from prior_explored_root to next_explored_root only uncovers the tile (tile_x, tile_y) within a visibility radius of their player coordinates. The contract verifies this transition against the map commitment.

Storage model

Player exploration commitments and map layouts are stored in Instance Storage on-chain. Using instance storage guarantees fast state reads and writes during hot loops.

Main gameplay flow

1. Map Config: Call init_map to configure map dimensions and visibility boundaries.
2. Registration: Explorer calls register_explorer to record their initial map state.
3. Exploration: Explorer calls explore with a Groth16 proof to update their visible tiles and progress.

Cougr APIs used

• circuits::fog_of_war: Configures and handles verification of private line-of-sight map calculations.
• zk::experimental::{FogOfWarSnapshot, FogOfWarTransition}: Input structs for ZK state transition logic.
• zk::Groth16Proof: Cryptographic proof data container.

Recommended testing approach

Use GameHarness and test_fixtures to mock ZK inputs and pipeline proof bytes. This allows testing successful proof verification paths without running full proving ceremonies in unit tests.

Build and test commands

cargo test
stellar contract build

Known limitations

• Grid coordinates are simplified.
• Map generation and parsing are managed off-chain.

Geometry Dash On-Chain Game

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

Purpose and pattern

This example demonstrates a rhythm-platformer fixed-tick runner on Soroban with Cougr ECS concepts. It remains transitional while the arcade examples converge on the canonical snake GameApp architecture.

Public contract API

Architecture overview

contract entrypoint
  ├─ reads game state from Soroban storage
  ├─ applies input or tick systems
  └─ writes updated state back to storage

Player physics, mode, obstacle, and status components live in components.rs; motion/collision behavior lives in systems.rs.

Storage model

Main gameplay flow

1. Call the initialization function to create the starting state.
2. Submit an input action such as movement, jump, flap, rotation, or shoot.
3. Call the tick/update function to run deterministic simulation logic.
4. Query public getters for score, position, active state, or terminal status.
5. Stop when the game-over/completed condition is reached, or reset/reinitialize where supported.

Cougr APIs used

• ComponentTrait and custom component modules document the ECS data boundary.
• SimpleWorld, SimpleQueryBuilder, GameApp, ScheduleStage, or SystemConfig are used where this transitional example has already adopted the maintained runtime shape.
• Auth, privacy, ZK, and standards APIs are intentionally not used; these arcade examples focus on deterministic game logic.

Build and test commands

cargo test
stellar contract build

Known limitations

• Transitional code may preserve older storage or scheduling patterns for compatibility reference.
• No authentication, matchmaking, real-time rendering, or production randomness is included.
• One contract instance generally represents one game or one keyed set of player games.
• For new work, prefer the canonical snake module split and GameApp tick wiring.

Guild Arena

PvP arena game on Soroban demonstrating guild-based social recovery and multi-device play using Cougr-Core.

Overview

On-chain gaming has a key risk: players losing access to accounts holding progress, items, and currency. Guild Arena solves this with two Cougr-Core account patterns:

1. Social Recovery - guild members act as guardians who can collectively restore account access after a timelock period
2. Multi-Device - players register multiple device keys (desktop, mobile) with per-device permission policies

How It Works

Account Setup

Player registers → sets 3 guild members as guardians (threshold 2-of-3)
                 → adds desktop key (Full permissions)
                 → adds mobile key (PlayOnly permissions)

Gameplay

Players queue for PvP matches. The challenger moves first, then the players alternate turns. Combat has three actions:

• Attack - standard damage
• Defend - reduced damage
• Special - high damage

After each match, the winner gains 32 rating points and the loser loses 32 points (without dropping below zero). Every 3 wins triggers a level-up with stat boosts.

Recovery Flow

Player loses key → Guardian 1 initiates recovery
                 → Guardian 2 approves (threshold met)
                 → 7-day timelock starts
                 → After timelock: finalize_recovery()
                 → New key active, old key revoked
                 → All stats, rating, history preserved

Contract API

Device Policies

Building

cargo build
cargo test
stellar contract build

Testing

cargo test

Tests cover:

• Player registration with guardians
• Multi-device management
• Device policy enforcement
• Full combat match resolution
• Rating updates after matches
• Out-of-turn actions, active-match protection, duplicate registration, and device ownership
• Complete recovery lifecycle (initiate → approve → timelock → finalize)
• Recovery with insufficient approvals (rejected)
• Game state preservation through recovery

Architecture

Uses Cougr-Core ECS patterns:

Components: Fighter, MatchRecord, GuildMembership, ArenaState

Systems: Matchmaking, Combat, Rating, Recovery, Device authorization

Storage: Soroban persistent storage keyed by player/device addresses. Recovery and device state managed through RecoverableAccount and DeviceManager from cougr-core.

Reference Role

This example is the canonical reference for Cougr's account-oriented flows:

• social recovery
• multi-device authorization
• gameplay permissions separated from full admin authority

Unlike the arcade examples, this one is intentionally more account-centric than GameApp-centric.

Prerequisites

• Rust 1.89+
• rustup target add wasm32v1-none
• Stellar CLI (optional, for deployment)

License

MIT OR Apache-2.0

️ Guild Treasury Wars - DAO-Governed Factions with stellar-zk Commitments

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

A guild-based strategy game implemented as a Soroban smart contract using cougr-core's ECS framework. Guilds manage shared treasuries, vote on strategic actions through DAO mechanics, and compete through hidden strategic commitments powered by stellar-zk.

Why stellar-zk?

In strategy games, revealing your plans to the enemy is a losing move. stellar-zk enables sealed war plans - players commit to strategies without revealing them, then prove their commitments on-chain when it's time to resolve battles.

Gameplay Flow

┌─────────────────────────────────────────────────────────┐
│ 1. GUILD CREATION                                        │
│    Admin creates a guild with INITIAL_TREASURY (1000)     │
│    → Members join the guild (up to 10)                    │
│    → cougr-core ECS World tracks entities                 │
├─────────────────────────────────────────────────────────┤
│ 2. GOVERNANCE (DAO-style proposals)                       │
│    Members submit proposals: Defend, Attack, Upgrade,     │
│    or Allocate resources from the shared treasury          │
│    → 51% vote threshold for approval/rejection             │
│    → Inspired by Stellar governance (governance.script3)   │
├─────────────────────────────────────────────────────────┤
│ 3. TREASURY EXECUTION                                     │
│    Approved proposals deduct treasury and apply effects:   │
│    → Defend (100): +10 defense strength                   │
│    → Attack (200): Launch campaign against enemy guild     │
│    → Upgrade (150): +10 attack strength                   │
│    → Allocate: Custom resource allocation                  │
├─────────────────────────────────────────────────────────┤
│ 4. SEALED WAR PLANS (stellar-zk commit-reveal)            │
│    Members commit: SHA256(action || target || amount ||    │
│    salt) → hash stored on-chain, strategy hidden           │
│    Reveal: provide preimage, contract verifies hash        │
│    → Nullifier consumed (anti-replay protection)           │
├─────────────────────────────────────────────────────────┤
│ 5. BATTLE RESOLUTION                                      │
│    Attack strength vs defense strength                     │
│    → Winner plunders defender's treasury                   │
│    → Game round incremented                                │
└─────────────────────────────────────────────────────────┘

stellar-zk Integration

This example uses stellar-zk for real hidden-strategy gameplay, not just narrative flavor. The integration follows stellar-zk's on-chain verification patterns:

Where stellar-zk Fits

Commitment Hash

commitment = SHA256(action_type ∥ target_guild_id ∥ resource_amount ∥ salt)

The salt (32-byte random value) ensures that identical strategies produce different hashes, preventing pattern analysis by opponents.

Nullifier Pattern

Each commitment hash acts as a nullifier (following stellar-zk's verifier contract design). Once revealed:

1. The commitment is marked as revealed = true
2. The hash is stored in DataKey::Nullifier(hash) → true
3. Any attempt to reuse the same commitment is rejected

References

• stellar-zk - ZK DevKit for Stellar/Soroban
• stellar-zk on crates.io - Crate reference
• Stellar Governance - DAO voting patterns inspiration

Cougr-Core Integration

ECS Components

ECS World

#![allow(unused)]
fn main() {
// cougr-core ECS entity management
let mut world = cougr_core::SimpleWorld::new(&env);
let _guild_entity = world.spawn_entity();
}

Contract API

Guild Management

Governance

Strategy (stellar-zk)

Queries

️ Quick Start

Prerequisites

Build

# Standard Rust build
cargo build

# Build WASM for Soroban deployment
stellar contract build

Test

cargo test

Validation

# Full validation suite
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
stellar contract build

Test Results: 14 tests passing ✅

Project Structure

examples/guild_treasury_wars/
├── Cargo.toml          # Dependencies: cougr-core + soroban-sdk
├── README.md           # This documentation
└── src/
    ├── lib.rs          # Contract entry points
    ├── types.rs        # ECS Components (Guild, Proposal, Strategy, etc.)
    ├── governance.rs   # ProposalSystem, VotingSystem, TreasuryExecutionSystem
    ├── strategy.rs     # StrategyProofSystem, ResolutionSystem (stellar-zk)
    └── test.rs         # Unit tests (14 tests)

License

MIT OR Apache-2.0

hidden_hand

Canonical ZK circuit example demonstrating circuits::hidden_cards for private card deals.

Purpose and pattern

This example demonstrates how to implement private card dealing (e.g., poker hand setups) on-chain. It uses ZK proofs to verify that a deck was shuffled and a hand of cards was dealt honestly, without revealing the cards to other players or the public on-chain ledger.

Public contract API

Architecture overview

                         ┌──────────────┐
                         │ Card Dealer  │
                         └──────┬───────┘
                                │ Generates ZK Proof
                     ┌──────────▼──────────┐
                     │     HiddenHand      │
                     │ (Soroban Contract)  │
                     └──────────┬──────────┘
                                │ Loads Spec
                     ┌──────────▼──────────┐
                     │ circuits::          │
                     │  hidden_cards       │
                     └─────────────────────┘

The dealer generates a Groth16 proof off-chain, verifying that the hand commitment was indeed created from a valid slice of the shuffled deck. The contract verifies the proof using the hidden_cards circuit spec.

Storage model

The TableConfig containing the card configuration is stored in Instance Storage. The ZK verification keys are built dynamically or stored securely within the contract instance.

Main gameplay flow

1. Setup: The contract calls init_table(deck_size, hand_size) to prepare the ZK circuit parameters.
2. Dealing: The dealer generates a hand commitment and a proof off-chain.
3. Verification: The contract calls verify_deal(player, deck_root, hand_commitment, proof) to validate that the deal is correct before proceeding with gameplay.

Cougr APIs used

• circuits::hidden_cards: Fetches the circuit layout, verification key, and verify wrapper for Groth16 hidden cards.
• zk::Groth16Proof: Data structure representing the cryptographic proof.

Recommended testing approach

Utilize GameHarness and test_fixtures to mock ZK inputs and pipeline proof bytes. This allows testing successful proof verification paths without running full proving ceremonies in unit tests.

Build and test commands

cargo test
stellar contract build

Known limitations

• Simple single-deck configuration.
• Proving is done entirely off-chain.

Memory Match

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

An on-chain Memory Match card game built with the Cougr ECS framework on Stellar Soroban.

Purpose and pattern

This example demonstrates a single-player, turn-based reveal-and-match game where pairs of cards are flipped and compared against each other rather than against fixed rules. It showcases Cougr's ComponentTrait pattern for typed, byte-serializable game state: cards, the board, and game progress are each modeled as a #[contracttype] struct with manual serialize/deserialize, rather than being scanned through SimpleWorld/SimpleQueryBuilder. This is a lighter-weight integration suited to a single fixed-shape game state (16 cards, one board, one player) with no dynamic entity population.

Public contract API

Architecture overview

There is no GameApp tick loop - reveal_card runs a fixed pipeline synchronously on each invocation:

reveal_card
  └─ ValidationSystem     → checks caller, game-over state, two-card limit, position bounds
  └─ RevealSystem          → flips the card to Revealed, increments the move counter
  └─ (when 2 cards are revealed)
       └─ PairResolutionSystem → compares values; marks Matched + checks for game-over,
                                  or hides both cards again on a mismatch

reset_game runs a separate ResetSystem that rehides every card and zeroes progress counters without regenerating the board layout. components.rs defines the data (CardComponent, BoardComponent, GameStateComponent, the ECSWorldState aggregate, and the public GameState/RevealInfo/RevealResult types); systems.rs holds the pure validation, reveal, resolution, reset, and projection functions; lib.rs owns the single ECSWorldState and is the only module that touches contract storage.

Storage model

The entire game lives under one instance-storage key (WORLD_KEY, symbol_short!("WORLD")) as a single ECSWorldState struct bundling all 16 card components, the board component, and the game-state component. Instance storage is used - not persistent or temporary - because there is exactly one game per contract instance and the state must survive for the lifetime of that instance with no per-entry TTL management.

Main gameplay flow

1. Deployer calls init_game(player); 16 cards are created with a deterministic layout (positions 0–7 and 8–15 hold matching values 0–7), all starting Hidden.
2. Player calls reveal_card(player, position) for a hidden card; it flips to Revealed and the move counter increments.
3. Once two cards are revealed, the contract compares their values:
   • Match: both cards become Matched, matched_pairs increments, and reveals are re-enabled. If all 8 pairs are now matched, the game is marked over.
   • No match: both cards flip back to Hidden and reveals are re-enabled.
4. Player repeats step 2–3 until matched_pairs reaches 8 and game_over is true.
5. Player (or anyone reading state) calls get_game_state at any point to read the board, or calls reset_game to rehide all cards and start over on the same layout.

Cougr APIs used

• cougr_core::component::ComponentTrait - gives each component (CardComponent, BoardComponent, GameStateComponent) a component_type() symbol and explicit byte-level serialize/deserialize. This is the only Cougr API the example uses: the game has one fixed-shape ECSWorldState per contract instance (16 cards, one board, one player) rather than a dynamic entity population, so SimpleWorld/SimpleQueryBuilder scanning would add overhead with no benefit. There is a single decision point per call (reveal or reset), so GameApp/ScheduleStage staged ticking is not needed either, and the game has no hidden information, multi-device auth, or proof-verification requirements that would call for auth, privacy::stable, privacy::experimental, or ops standards.

Build and test commands

cargo test
stellar contract build

Known limitations

• Does not use GameApp, ScheduleStage, or SimpleWorld - game logic is invoked directly from contract entrypoints rather than through a tick-based scheduler, since a single-player game with one decision point per call does not need staged scheduling.
• The card layout is fixed and deterministic (not shuffled), so the pairing is the same for every game; randomized layouts are out of scope for this example.
• reset_game reuses the same fixed layout rather than generating a new one.
• No timeout/forfeit mechanism, scoring across multiple games, or multiplayer support.

Minesweeper

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

An on-chain Minesweeper game built with the Cougr ECS framework on Stellar Soroban.

Purpose and pattern

This example demonstrates a single-player reveal-and-deduce puzzle over a fixed, deterministic mine layout - no player input or randomness influences where mines are placed, which keeps the board auditable and reproducible across deployments. It showcases Cougr's ComponentTrait pattern for typed, byte-serializable game state: the board, the (hidden) mine layout, and the game status are each their own component with manual serialize/deserialize, demonstrating explicit byte-layout control for a fixed-size 9×9 grid.

Public contract API

Architecture overview

There is no GameApp tick loop - reveal_cell runs all logic synchronously in a fixed pipeline on each invocation:

reveal_cell
  └─ status/bounds/already-revealed checks  → rejects finished games, out-of-bounds
     coordinates, and cells already revealed with the matching `message` symbol
  └─ mine check                              → if the cell holds a mine, marks the cell,
     sets status to Lost, and returns immediately
  └─ adjacency count + board update          → writes the computed adjacent-mine count
     into the board for a safe reveal
  └─ CompletionSystem                        → sets status to Won once every safe cell
     has been revealed

components.rs defines the data (BoardComponent, MineLayoutComponent, GameStateComponent, plus the ECSWorldState aggregate and the public API types); systems.rs holds the pure functions (place_mines_deterministic, completion_system); lib.rs owns the single ECSWorldState per contract instance and is the only module that touches contract storage.

Storage model

The entire game lives under one instance-storage key (WORLD_KEY, symbol_short!("WORLD")) as a single ECSWorldState struct bundling the board, the mine layout, and the game status. Instance storage is used - not persistent or temporary - because there is exactly one game per contract instance and the state must survive for the lifetime of that instance with no per-entry TTL management.

Main gameplay flow

1. Deployer (or any caller) calls init_game(). The board starts fully hidden and place_mines_deterministic seeds 10 mines at fixed coordinates across the 9×9 grid.
2. Player calls reveal_cell(row, col) for a hidden cell.
3. If the cell is a mine, the board marks it revealed-as-mine, status flips to Lost, and the call returns message = boom. No further reveals are accepted until reset_game.
4. If the cell is safe, the contract counts mines among its up-to-8 neighbors, writes that count into the board, and increments the revealed-cell counter.
5. After each safe reveal, CompletionSystem checks whether all 71 safe cells (81 total minus 10 mines) have been revealed; if so, status flips to Won.
6. Caller reads get_state, get_visible_cell, or is_finished to check progress or terminal state; reset_game starts over with the same deterministic layout.

Cougr APIs used

• cougr_core::component::ComponentTrait - gives each component (BoardComponent, MineLayoutComponent, GameStateComponent) a component_type() symbol and explicit byte serialize/deserialize, chosen because the game has one fixed-shape 81-cell grid rather than a dynamic entity population that would benefit from SimpleWorld/SimpleQueryBuilder scanning.
• No other cougr-core APIs are used. GameApp/ScheduleStage are unnecessary because reveal_cell has a single decision point per call with no multi-stage ordering; SimpleWorld/ SimpleQueryBuilder are unnecessary because the game has exactly three fixed components and never scans entities by type; auth, privacy::stable/experimental, and ops standards are unused because this example has no multi-party authorization, hidden-information disclosure, or pausability/ownership requirements - the entire board state is openly readable via get_board and get_visible_cell.

Build and test commands

cargo test
stellar contract build

Known limitations

• Does not use GameApp, ScheduleStage, or SimpleWorld - reveal logic is invoked directly from contract entrypoints since a single-player puzzle with one decision point per call has no need for staged scheduling.
• Mine placement is fixed and deterministic rather than randomized per game; this keeps the layout auditable but means every new game (or reset_game call) has mines in the same positions.
• No flagging system - the contract only supports revealing cells, not marking suspected mines.
• No multi-player or wagering support; any caller can call any entrypoint for the single shared game instance.

Murdoku

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

Murdoku is a murder mystery logic puzzle built with the Cougr ECS framework on Stellar Soroban. It demonstrates how to combine Entity Component System (ECS) game state, Pollar social logins, session key authorization, and zero-knowledge proof verification for privacy-preserving puzzle solving.

Purpose and Pattern

Murdoku is an on-chain logic puzzle that combines Sudoku-style Latin square constraints with murder mystery storytelling. Players place suspects (e.g., characters, weapons, rooms) on a grid while satisfying constraints provided by clues (e.g., "The suspect with the knife is not in the same row as the butler").

This example showcases the canonical reference architecture for a full-stack game within the Cougr ecosystem:

• Entity Component System (ECS): Separation of game state, input validation, puzzle constraint checks, and win conditions using the Cougr ECS engine.
• Social Authentication & Session Keys: Account abstraction utilizing Pollar for embedded wallet logins and scoped session key creation (SessionBuilder) to support non-intrusive gameplay transactions.
• ZK Privacy Layer: The solution is never stored in plaintext on-chain. Instead, puzzle creators submit a cryptographic commitment (Poseidon2 hash of the solution + salt) and a Groth16 verifier key. Players prove they know a valid solution by submitting a Groth16 zero-knowledge proof, without revealing the solution itself.

The contract supports two build modes controlled by the zk Cargo feature:

• Default (v1): Plaintext solution stored on-chain. Simpler but exposes the solution to on-chain observers.
• zk feature enabled: Solution commitment + Groth16 proof verification. The solution remains private; the contract only stores a hash and validates ZK proofs.

Architecture Overview

Murdoku follows a decoupled design where all gameplay rules and state changes are handled by the Soroban contract, while the user interface and wallet management are facilitated by a React web app.

Browser (Vite + React)
  └── Pollar (@pollar/react) - embedded wallet, social login
  └── contract.ts - Stellar SDK contract client
        │
        ▼
  Soroban Contract (examples/murdoku/src/)
  ├── lib.rs - entrypoints & GameApp wiring
  ├── components.rs - ECS components (Board, Suspect, GameState)
  ├── systems.rs - validation, move execution, and completion systems
  ├── types.rs - domain types (Clues, Suspects, GridConfiguration)
  └── auth.rs - session keys, CougrAccount wiring
        │
        ▼
  Stellar Testnet (Soroban RPC)

The React frontend embeds the Pollar SDK for OAuth/social logins. Pollar creates a temporary keypair representing a session key. The frontend uses the session key to sign game moves (e.g., place_suspect). The Soroban contract verifies that the session key is valid and authorized to act on behalf of the player using the authorize_with_fallback module.

Public Contract API

Below is the entrypoint surface defined in the #[contractimpl] block of the Murdoku smart contract. Some entrypoints are only available with the zk feature enabled.

Storage Model

Murdoku uses Soroban's state storage model (Instance, Persistent, and Temporary) to optimize gas costs and storage lifetimes.

| Storage Type | Data Kept | Lifetime | Rationale | |---|---|---|---|---| | Persistent | Registered Puzzle catalog (by ID), Creator profiles, Passkey credentials, Verifier keys (ZK), Solver state (ZK) | Indefinite | Puzzle templates and user credentials must persist forever across sessions and are read-heavy. | | Instance | Active Player Game session, ECS World state (SimpleWorld), Admin configs | Extended (Renewed on play) | The active board state must persist during active play but can be garbage-collected or archived if the player abandons the game. | | Temporary | Active Session Key tokens, cryptographic challenges | Short-term (Expires in blocks) | Session authorization keys only need to last for the duration of the play session and should expire automatically to free state space. |

In ZK mode, the following additional storage keys are used:

Main Gameplay Flow

Play Flow

1. Connect Wallet: The player logs into the frontend via Pollar using an email or social login. Pollar provisions a Stellar account and prepares a local session key.
2. Browse Catalog: The frontend calls list_puzzles to fetch and render the list of available murder mystery puzzles.
3. Open Puzzle: The player selects a puzzle. The frontend calls get_puzzle to retrieve the clues and grid dimensions, then calls start_game to initialize the ECS world state for this puzzle.
4. Place Suspects: The player drags and drops suspects (e.g., characters, weapons) onto grid cells. Each placement calls place_suspect. This transaction is signed by the local session key and bypasses manual wallet confirmations.
5. On-chain Validation: The contract executes the validation system:
   • Verifies the cell is editable.
   • Enforces Latin square constraints (no duplicate suspects in the same row or column).
   • Validates placement against the puzzle's clues.
6. Completion: If all cells are filled correctly, the contract marks the game status as solved. is_solved returns true, and the frontend displays a victory screen.

Create Flow

1. Connect Wallet: The creator authenticates on the creator portal via Pollar.
2. Configure Puzzle: The creator designs a puzzle:
   • Selects grid size (4x4 or 5x5).
   • Enters the full solution grid.
   • Defines the clues (e.g., cell constraints, adjacency rules).
3. Submit Puzzle (v1): The creator clicks "Publish", triggering a call to submit_puzzle with the plaintext solution.
4. Submit Puzzle (ZK): The creator generates a Poseidon2 commitment of the solution and a Groth16 verifier key, then calls submit_puzzle with the commitment and key instead of the plaintext.
5. Contract Validation:
   • v1 mode: The contract validates the Latin square constraints and clue consistency via ECS systems.
   • ZK mode: The contract validates puzzle structure (grid size, suspects, clue bounds) but cannot verify solution correctness - the ZK proof catches cheating at solve time.
6. Publishing: If checks pass, the contract assigns a puzzle ID, stores the puzzle in persistent storage, and activates it.

Cougr APIs Used

Murdoku is built on the core APIs of the Cougr framework.

Frontend Setup

1. Requirements

• Node.js v18 or later
• Stellar CLI installed and configured

2. Run Locally

Navigate to the frontend directory:

cd examples/murdoku/frontend

Copy the environment template:

cp .env.example .env

Open .env and set the variables:

• VITE_POLLAR_API_KEY: Obtain this from the Pollar Developer Console by registering an application.
• VITE_CONTRACT_ID: The deployed contract ID from your testnet deployment (see below).

Install dependencies and run the Vite development server:

npm install
npm run dev

The frontend will run locally on http://localhost:5173.

Contract Build and Test Commands

Execute the following commands from the examples/murdoku directory to format, lint, test, and build the contract.

cd examples/murdoku
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo test --features zk   # run ZK-specific tests
stellar contract build

To build with the ZK privacy layer enabled:

cargo build --features zk
cargo test --features zk

Deploying to Testnet

To deploy and test the contract manually on Stellar Testnet, use the following commands:

# 1. Generate an identity for deployment
stellar keys generate murdoku_deployer

# 2. Fund the identity using Friendbot
stellar keys fund murdoku_deployer --network <NETWORK>

# 3. Deploy the compiled WASM to Testnet
CONTRACT_ID=$(stellar contract deploy \
  --wasm target/wasm32v1-none/release/murdoku.wasm \
  --network <NETWORK> \
  --source murdoku_deployer)

# 4. Initialize the contract game registry
stellar contract invoke \
  --id $CONTRACT_ID \
  --network <NETWORK> \
  --source murdoku_deployer \
  -- init_game \
  --admin murdoku_deployer

# 5. Submit a minimal 4x4 placeholder puzzle to the catalog
# (Solution grid contains flat representation of a 4x4 Latin square)
stellar contract invoke \
  --id $CONTRACT_ID \
  --network <NETWORK> \
  --source murdoku_deployer \
  -- submit_puzzle \
  --creator murdoku_deployer \
  --size 4 \
  --solution '[1,2,3,4,2,3,4,1,3,4,1,2,4,1,2,3]' \
  --clues '[]'

ZK Privacy Layer

Circuit Statement

The Groth16 circuit proves the following statement without revealing the solution:

"I know a set of values cells such that: (1) cells is a valid Latin square of size N, (2) Poseidon2(cells || salt) == commitment, (3) each cell value is in range 1..=N."

Public Inputs Format

Player Solve Flow (ZK mode)

1. Browse Puzzles: Frontend calls list_puzzles and get_puzzle to fetch puzzle metadata (grid size, suspects, clues, solution commitment - not the plaintext solution).
2. Solve Off-Chain: The player solves the puzzle manually, arriving at a candidate grid arrangement.
3. Generate Proof: The frontend (or a backend prover service) generates a Groth16 proof that the player knows a valid arrangement consistent with the commitment.
4. Submit Proof: The player calls submit_proof(player, puzzle_id, proof, public_inputs). The contract verifies the Groth16 proof against the stored verifier key.
5. Mark Solved: On valid proof, the contract marks the puzzle as solved for that player and increments the solver count.

Key Files

Backward Compatibility

The v1 plaintext solution path is preserved behind the default (no zk feature) build. To switch between modes:

# v1 mode (default)
cargo build
cargo test

# ZK mode
cargo build --features zk
cargo test --features zk

Known Constraints

• Trusted Setup: Groth16 requires a trusted setup ceremony for each circuit. The development verifier keys used in this implementation are not production-safe. A proper multi-party ceremony must be completed before mainnet deployment. See the module-level docs in src/zk.rs for details.
• Client-Side Proof Generation: Generating Groth16 proofs in the browser requires a WASM-compiled prover. This is tracked as a separate enhancement and is not yet implemented in the frontend.
• Circuit Size: A 5×5 Murdoku circuit has 25 cells. Each cell requires range checks (1..=N) and Latin square row/column uniqueness constraints. The constraint count should be verified against Stellar's Groth16 verification limits before production use.

Known Limitations

• ZK trusted setup is development-only. The Groth16 verifier keys shipped here come from a development setup and are not production-safe. See Known Constraints above for the full ZK caveats (trusted setup, client-side proving, circuit size).
• Difficulty is unverified creator metadata. The contract validates Latin-square correctness on submission but does not independently grade or rank difficulty - the difficulty field is taken from the creator at face value.
• No ranked leaderboard or rewards. A per-puzzle solver count is tracked, but the example intentionally omits scoring, ranked leaderboards, and reward distribution to keep the reference focused on the ECS + auth + ZK pattern.
• Puzzle catalog grows without an on-chain cap. Submissions increment PUZZLE_COUNT without an upper bound. Reads are paginated via offset/limit, but production deployments expecting very large catalogs should add submission limits and indexed lookups.

Classification

Marked as Canonical. Murdoku is the reference full-stack example for Cougr, showcasing how to build games that combine ECS, session-key-based social logins (via Pollar), and multi-step transaction authorization. Use this as the template for production-grade full-stack game contracts.

Pac-Man On-Chain Game

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

A practical example demonstrating how to use the cougr-core package to implement on-chain game logic on the Stellar blockchain via Soroban.

Overview

This example implements a complete Pac-Man game as a Soroban smart contract. The focus is exclusively on the smart contract logic (without graphical interface), showcasing how cougr-core simplifies on-chain game development.

Features

• 10x10 maze with walls, pellets, and power pellets
• Pac-Man movement with direction control
• 4 ghosts with simplified AI (chase and frightened modes)
• Score tracking and lives system
• Win/lose conditions
• Complete test coverage

Architecture

The example follows a modular architecture, separating domain types, ECS components, game systems, and contract entrypoints.

Module Layout

• src/lib.rs: Main contract entrypoints and orchestration
• src/types.rs: Game enums, state structures, and storage keys
• src/components.rs: ECS-inspired data structures (Position, Ghost)
• src/maze.rs: Maze layout and generation logic
• src/systems.rs: Core game loop and logic
• src/test.rs: Comprehensive test suite
• README.md: This file
• Cargo.toml: Soroban SDK dependencies

┌─────────────────────────────────────────────────────────────┐
│                    Pac-Man Contract (lib.rs)                │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  GameState  │  │   Maze      │  │    Ghosts[4]        │  │
│  │  (types.rs) │  │  (maze.rs)  │  │  (components.rs)    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                    GameSystems (systems.rs)           │  │
│  │  - move_pacman                                        │  │
│  │  - move_ghosts                                        │  │
│  │  - check_collisions                                   │  │
│  └───────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                    Contract Functions                       │
│  ┌──────────────┐ ┌────────────────┐ ┌──────────────────┐  │
│  │  init_game   │ │change_direction│ │   update_tick    │  │
│  └──────────────┘ └────────────────┘ └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Maze Layout

The game uses a fixed 10x10 maze:

##########
#P......P#
#.##.##..#
#.#...#..#
#...#....#
#.#.#.##.#
#.#......#
#.##.###.#
#P......P#
##########

Legend:
  # = Wall
  . = Pellet (10 points)
  P = Power Pellet (50 points)

Prerequisites

Required Tools

1. Rust (1.88.0 or later)

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

2. Stellar CLI

   cargo install stellar-cli --locked
   stellar --version
   

3. WASM Target

   rustup target add wasm32v1-none
   

Verify Installation

rustc --version    # Should be 1.88.0 or later
cargo --version
stellar --version  # Should show Stellar CLI version

Setup

1. Clone the Repository

git clone https://github.com/salazarsebas/Cougr.git
cd Cougr/examples/pac_man

2. Update Dependencies

cargo update

3. Build the Contract

# Debug build
cargo build

# Release build (optimized for WASM)
cargo build --release

4. Build for Soroban

stellar contract build

This generates the WASM file at:

target/wasm32v1-none/release/pac_man.wasm

Testing

Run All Tests

cargo test

Run Tests with Output

cargo test -- --nocapture

Run Specific Test

cargo test test_init_game
cargo test test_pellet_collection
cargo test test_ghost_ai

Expected Output

running 25 tests
test test::test_init_game ... ok
test test::test_maze_layout ... ok
test test::test_ghosts_initialized ... ok
test test::test_change_direction_up ... ok
test test::test_change_direction_down ... ok
...
test result: ok. 25 passed; 0 failed; 0 ignored

Code Walkthrough

1. Contract Types

The game uses Soroban-compatible types with #[contracttype]:

#![allow(unused)]
fn main() {
#[contracttype]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u32)]
pub enum Direction {
    Up = 0,
    Down = 1,
    Left = 2,
    Right = 3,
}

#[contracttype]
#[derive(Clone, Debug)]
pub struct GameState {
    pub pacman_pos: Position,
    pub pacman_dir: Direction,
    pub ghosts: Vec<Ghost>,
    pub maze: Vec<CellType>,
    pub score: u32,
    pub lives: u32,
    pub game_over: bool,
    // ...
}
}

2. Storage Pattern

Game state is stored using Soroban's instance storage:

#![allow(unused)]
fn main() {
#[contracttype]
pub enum DataKey {
    GameState,
    Initialized,
}

// Writing state
env.storage().instance().set(&DataKey::GameState, &state);

// Reading state
let state: GameState = env.storage()
    .instance()
    .get(&DataKey::GameState)
    .expect("Game not initialized");
}

3. Cougr-Core Integration

The contract uses cougr-core for ECS patterns and event handling:

#![allow(unused)]
fn main() {
use cougr_core::component::{ComponentTrait, Position as CorePosition};
use cougr_core::event::{CollisionEvent, Event, EventTrait};
}

Position Component: Game positions integrate with cougr_core's Position:

#![allow(unused)]
fn main() {
impl Position {
    /// Convert to cougr_core Position for ECS integration
    pub fn to_core_position(&self) -> CorePosition {
        CorePosition::new(self.x, self.y)
    }
}
}

Collision Events: Ghost collisions use cougr_core's event system:

#![allow(unused)]
fn main() {
// Each ghost has an entity_id for collision tracking
pub struct Ghost {
    pub entity_id: u64,
    // ...
}

// Create collision events using cougr_core
let collision_event = CollisionEvent::new(
    PACMAN_ENTITY_ID,
    ghost.entity_id,
    symbol_short!("ghost"),
);
}

Query Functions: Get serialized component data:

#![allow(unused)]
fn main() {
// Get Pac-Man's position as serialized cougr_core component
pub fn get_serialized_pacman_position(env: Env) -> Bytes {
    let core_pos = state.pacman_pos.to_core_position();
    core_pos.serialize(&env) // Uses ComponentTrait
}
}