Tycoon on Stellar

What We Are Building

Tycoon is a Monopoly-style board game where players buy, sell, and trade properties, collect rent, build monopolies, and compete for on-chain prizes. Gameplay runs in real time through a web app; stakes, registration, payouts, and rewards are enforced by Soroban smart contracts on Stellar.

Core product surfaces

Surface	Description
Play vs Humans (PvP)	Create or join a room with a short game code. Optional USDC entry stake. Last player standing wins the pot.
Play vs AI	Solo player vs AI opponents. Wallet registration required; no stake.
Agent vs Agent	Up to 8 autonomous agents per match. Backend advances turns; agents resolve via callback URL or hosted logic.
Arena & Tournaments	Bracket-style competitions with entry fees held in escrow and prizes distributed on-chain.
Shop & Perks	In-game collectibles and vouchers redeemable for the TYC reward token or usable as perks (Jail Free, Instant Cash, Lucky 7, etc.).

On-chain vs off-chain split

On-chain (Soroban)	Off-chain (backend + DB)
Player registration & usernames	Board state, dice rolls, property ownership during play
Game create / join / leave (pending)	Turn order, Chance/Community Chest cards, trades
USDC stakes & prize payouts	Chat, matchmaking, AI/agent orchestration
TYC vouchers & collectibles (NFT-like)	Leaderboards, notifications, tournament brackets
Tournament escrow (fees + prize pool)	Anti-cheat, turn validation, `set_turn_count` for perk eligibility
House fee (5%) & rank-based payout math	Socket/WebSocket live updates to clients

This hybrid model keeps Stellar transactions cheap and fast while preserving trustless money flows.

Why Stellar

Low fees & fast finality — ideal for join/leave, stake, and payout flows.
Native USDC — Circle-issued USDC on Stellar is a first-class asset for entry stakes and prizes.
Soroban — Rust/WASM smart contracts with a mature SDK and test harness.
Wallet ecosystem — Freighter, Albedo, xBull, and WalletConnect-compatible flows via @stellar/stellar-sdk.
Global reach — Stellar’s payment rails align with mobile-first and remittance-friendly UX.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Next.js Frontend                            │
│  Board UI · Waiting room · Wallet connect · Tx signing          │
│  @stellar/stellar-sdk · Freighter / Albedo / WC                 │
└───────────────────────────┬─────────────────────────────────────┘
                            │ REST + WebSocket
┌───────────────────────────▼─────────────────────────────────────┐
│                     Node.js Backend                             │
│  Game engine · Agents · Tournaments · Shop webhooks             │
│  Soroban RPC client · Game controller keypair                   │
└───────────────────────────┬─────────────────────────────────────┘
                            │ Soroban invoke / submit
┌───────────────────────────▼─────────────────────────────────────┐
│                   Stellar / Soroban                             │
│  Tycoon Game · Reward System · Tournament Escrow · TYC Token    │
└─────────────────────────────────────────────────────────────────┘

Soroban contracts (Rust)

Contract	Responsibility
`tycoon_game`	`register_player`, `create_game`, `join_game`, `leave_pending_game`, `exit_game`, `remove_player` (backend-only), `set_turn_count`, views (`get_game`, `get_user`, `get_game_by_code`)
`tycoon_rewards`	Mint/redeem TYC vouchers, mint/buy/burn collectibles, shop stock, pause/unpause
`tycoon_tournament_escrow`	`create_tournament`, `register`, `fund_prize_pool`, `lock`, `finalize`, `cancel`
`tycoon_token`	TYC issuance (SEP-41-style token interface on Soroban)
`tycoon_lib`	Shared types: `GameStatus`, `GameType`, payout tiers, validation helpers

Payout rules (staked games):

House: 5% of pot when the winner exits.
Distributable (95%): Rank 1 → 50%, Rank 2 → 30%, Rank 3 → 20%.
Top 3: USDC + TYC voucher + random collectible (rank 1 gets higher strength).
Rank 4+: Consolation TYC voucher only.
min_turns_for_perks: Backend calls set_turn_count once a player crosses the threshold; voluntary exit uses stored count.

Tokens on Stellar

Asset	Role
USDC	Entry stakes, tournament fees, shop purchases, prize pools
TYC	Rewards, shop, vouchers, daily bonuses

USDC uses the canonical Stellar USDC issuer (testnet/mainnet config per environment). TYC is deployed as a Soroban token contract controlled by the reward system and game contracts.

Backend game controller

A dedicated Stellar keypair (server-side only) is authorized on-chain to:

remove_player_from_game(game_id, player, turn_count) — vote-out / stall removal
set_turn_count(game_id, player, count) — perk eligibility
Tournament lock / finalize / cancel

All controller transactions are serialized in a single queue to avoid sequence-number collisions under load.

Frontend Plan

Stack

Next.js (App Router) + TypeScript + Tailwind CSS
@stellar/stellar-sdk — build, sign, and submit transactions
@stellar/freighter-api (and optional Albedo) — wallet connection
Soroban contract bindings — generated from contract spec JSON (soroban contract bindings typescript)

User flows

Connect wallet → derive Stellar public key (G-address).
Register → sign register_player(username); receive welcome TYC voucher.
Create game → set players (2–8), stake, public/private + code → on-chain create + backend room.
Join game → enter code → approve USDC (if staked) → join_game.
Play → roll, buy, rent, trade, develop via backend; UI updates over WebSocket.
Win / exit → exit_game on-chain; USDC + rewards land in wallet.

Mobile

A lightweight Minipay-style shell can target Stellar-compatible in-app wallets using the same SDK and deep-link signing patterns.

Backend Plan

Stack

Node.js + Express REST API
PostgreSQL — games, players, trades, tournaments, users
Soroban RPC — soroban-rpc on testnet/mainnet
stellar-sdk Server — horizon optional for payment history; primary path is Soroban simulation + submission

New chain module: `stellarContract.js`

Central service for all Soroban invokes from the API:

Env variable	Purpose
`STELLAR_NETWORK`	`testnet` \| `mainnet`
`STELLAR_SOROBAN_RPC_URL`	Soroban RPC endpoint
`TYCOON_STELLAR_GAME_CONTRACT_ID`	Deployed `tycoon_game` contract ID (C-address)
`TYCOON_STELLAR_REWARDS_CONTRACT_ID`	Reward system contract ID
`TYCOON_STELLAR_TOURNAMENT_ESCROW_ID`	Tournament escrow contract ID
`TYCOON_STELLAR_TYC_TOKEN_ID`	TYC token contract ID
`STELLAR_USDC_ASSET_CODE` / `STELLAR_USDC_ISSUER`	USDC trustline params for client hints
`BACKEND_GAME_CONTROLLER_STELLAR_SECRET`	Controller keypair (never commit)

API & real-time

REST endpoints unchanged at the HTTP layer (/api/games, /api/trades, /api/tournaments, …) with chain: "STELLAR" on records.
WebSocket channels for board updates, chat, and waiting-room presence.
Agent runner polls or subscribes to active Stellar-chain agent games when ENABLE_AGENT_GAME_RUNNER=true.

Implementation Phases

Phase 1 — Foundation (weeks 1–2)

Scaffold Soroban workspace (cargo install soroban-cli)
Implement tycoon_lib types and payout math in Rust unit tests
Deploy tycoon_token + tycoon_game to Stellar testnet
CLI scripts: register, create game, join, exit (happy path)
Backend: stellarContract.js with simulated + submitted invokes

Phase 2 — Stakes & Rewards (weeks 3–4)

USDC deposit/withdraw in game contract (SEP-41 token transfers)
tycoon_rewards: vouchers, collectibles, shop buy_collectible
Backend: set_turn_count, remove_player_from_game
Frontend: Freighter connect, register, create/join staked game

Phase 3 — Full Gameplay (weeks 5–6)

Wire board UI to Stellar wallet hooks and Soroban contract bindings
Waiting room, property actions, trades (off-chain + socket)
Victory flow + on-chain prize claim
Play vs AI registration gate

Phase 4 — Arena & Agents (weeks 7–8)

tycoon_tournament_escrow deploy + bracket finalize
Agent registry (on-chain agent metadata + callback URL)
Agent vs Agent runner on Stellar chain tag
Leaderboard & public profiles

Phase 5 — Mainnet & Hardening (weeks 9–10)

External audit or structured internal review
Mainnet deploy, multisig admin, contract upgrade policy (if using admin pattern)
Monitoring: failed invokes, sequence gaps, escrow balance alerts
Documentation, env templates, runbooks

Development Setup

Prerequisites

# Rust + Soroban
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install soroban-cli --locked

# Node.js >= 18
node -v

# Stellar testnet account with XLM for fees (Friendbot on testnet)

Contract repo layout (new)

stellar/
├── contracts/
│   ├── tycoon_game/
│   ├── tycoon_rewards/
│   ├── tycoon_tournament_escrow/
│   ├── tycoon_token/
│   └── tycoon_lib/
├── scripts/
│   ├── deploy_testnet.sh
│   └── invoke_register.sh
└── README.md

Build & test contracts

cd stellar
soroban contract build
cargo test
soroban contract deploy \
  --wasm target/wasm32v1-none/release/tycoon_game.wasm \
  --source-account DEPLOYER_SECRET \
  --network testnet

Generate TypeScript bindings

soroban contract bindings typescript \
  --contract-id <C...> \
  --network testnet \
  --output-dir ../frontend/lib/stellar/bindings

Run app locally

# Backend
cd backend && cp .env.example .env   # add STELLAR_* vars
npm install && npm run dev

# Frontend
cd frontend && cp .env.example .env.local
npm install && npm run dev

Security & Operations

Secrets: Controller secret key and deployer keys live only in server env / CI secrets — never in the repo.
Trustlines: Clients must trust USDC issuer and TYC token before receiving payouts.
Simulation first: Every invoke is simulated via Soroban RPC before submission; surface revert reasons to the UI.
Admin keys: Use multisig or separate cold admin for set_backend_controller, pause, and emergency withdraw.
Rate limits: API throttling on create/join to prevent spam rooms.

Success Criteria

Milestone	Done when
MVP	Two wallets register, join a staked game on testnet, play to completion, winner receives USDC on-chain
Rewards	Top-3 exit receives voucher + collectible; shop purchase works with TYC or USDC
Tournament	4+ players pay entry fee; escrow finalizes prizes to declared winners
Agents	Agent vs Agent match runs end-to-end without a browser client
Mainnet	Public launch with monitored contracts and documented addresses

Contract Addresses (fill after deploy)

Contract	Testnet ID	Mainnet ID
Tycoon Game	`C...`	`C...`
Reward System	`C...`	`C...`
Tournament Escrow	`C...`	`C...`
TYC Token	`C...`	`C...`

Resources

Soroban documentation
Stellar developers
SEP-41: Soroban Token Interface
Freighter wallet
Stellar Laboratory — build and inspect transactions

License

Same as the parent Tycoon repository.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Tycoon on Stellar

What We Are Building

Core product surfaces

On-chain vs off-chain split

Why Stellar

Architecture

Soroban contracts (Rust)

Tokens on Stellar

Backend game controller

Frontend Plan

Stack

User flows

Mobile

Backend Plan

Stack

New chain module: stellarContract.js

API & real-time

Implementation Phases

Phase 1 — Foundation (weeks 1–2)

Phase 2 — Stakes & Rewards (weeks 3–4)

Phase 3 — Full Gameplay (weeks 5–6)

Phase 4 — Arena & Agents (weeks 7–8)

Phase 5 — Mainnet & Hardening (weeks 9–10)

Development Setup

Prerequisites

Contract repo layout (new)

Build & test contracts

Generate TypeScript bindings

Run app locally

Security & Operations

Success Criteria

Contract Addresses (fill after deploy)

Resources

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

New chain module: `stellarContract.js`

Packages