SOL&Sandals — Technical Whitepaper

A verifiable, sink-driven token economy for on-chain gladiator combat on Solana.

Version 1.0 — July 2026 Author: Lisman Razvan (SECFORIT SRL)

Abstract

SOL&Sandals is a turn-based gladiator combat game deployed on the Solana blockchain. It combines a deterministic, seedable client-side combat engine with three Anchor programs that govern asset ownership, a capped token economy, trustless PvP wagering, and an escrowed NFT marketplace. The GOLD token — the game’s sole unit of account — follows a 50-million-unit hard cap with halving-style emission eras, a suite of deflationary sinks (arena entry fees, exponential forge upgrades, cosmetic renames, and marketplace fees split 50/50 between burn and treasury), and staking-based reward bonuses gated by lockup periods and elite-tier appearance bonds. Every economic constant is implemented identically in Rust (on-chain) and TypeScript (client-side), covered by unit tests on both sides. This document describes the full technical architecture, the token economy design from first principles, the combat engine mathematics, and the trust model under which the system operates.

1. Introduction

1.1 Problem Statement

Blockchain games face a structural economic problem: every in-game action that creates tokens is a faucet, and without proportional sinks, supply grows monotonically. A token with unbounded supply and zero marginal demand converges to zero value. Most web3 games address this with deferred promises (future land sales, governance tokens, staking emissions that print more tokens). SOL&Sandals inverts the model: the sinks are not future work — they are the core loop. Every time a player fights above tier 0, forges gear, renames their gladiator, or trades on the marketplace, a measurable fraction of GOLD is permanently destroyed or locked.

1.2 Design Philosophy

• Combat is client-side, settlement is on-chain. The fight itself costs no gas and runs in milliseconds. Only economically meaningful events — rewards, wagers, trades, forge upgrades — touch the chain.
• The economy must be verifiable. Every constant is public, every emission is capped, every burn is counted. GameConfig exposes total_minted, total_burned, and total_staked on-chain so anyone can audit the real float.
• No pre-mine, no team allocation. 100% of supply is emitted through gameplay. The treasury accumulates from fees, not from a founders’ mint.
• The engine must be replayable. Combat uses a deterministic mulberry32 PRNG seeded per fight. The same seed + action sequence produces the same outcome, which is the prerequisite for on-chain fight verification in production.

1.3 Technology Stack

2. System Architecture

The system is divided into four layers:

┌──────────────────────────────────────────────────────┐
│                  React UI (Vite)                      │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────┐ │
│  │ Game Engine  │  │ Wallet Layer │  │ State/Store │ │
│  │ (pure TS)   │  │ (adapters)   │  │ (local)     │ │
│  └──────┬──────┘  └──────┬───────┘  └─────────────┘ │
└─────────┼────────────────┼───────────────────────────┘
          │                │
          ▼                ▼
┌──────────────────────────────────────────────────────┐
│              Solana Devnet                            │
│  ┌────────────┐ ┌───────────┐ ┌───────────────────┐  │
│  │ arena-core │ │arena-wager│ │   marketplace     │  │
│  │ GOLD mint  │ │ PvP escrow│ │ NFT escrow (GOLD) │  │
│  │ profiles   │ │ settle    │ │ list/buy/cancel   │  │
│  │ forge/rename│ │ timeout   │ │ 5% fee burn/treas│  │
│  │ staking    │ │           │ │                   │  │
│  └────────────┘ └───────────┘ └───────────────────┘  │
│  ┌────────────────────────────────────────────────┐  │
│  │        Metaplex Token Metadata (NFTs)           │  │
│  └────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘

2.1 Program Addresses

2.2 Program Design

The three programs are loosely coupled — they share no direct CPI calls. They interact only through the shared GOLD SPL token. This means each program can be upgraded, redeployed, or replaced independently without breaking the others, as long as the GOLD mint and treasury account addresses remain stable.

3. The Combat Engine

3.1 Overview

The combat engine is 100% pure TypeScript with zero dependencies. It runs client-side in milliseconds, is fully deterministic (seeded PRNG), and is covered by 34 unit tests. The engine lives in app/src/game/ across seven modules: combat.ts, ai.ts, items.ts, progression.ts, rng.ts, types.ts, opponents.ts, and fight.ts.

3.2 The Six Attributes

3.3 The Five Actions

Players choose one action per turn. The AI opponent chooses simultaneously via its personality-driven weight system.

Attack

The core action. Hit probability is a ratio contest:

hitChance = (atk×2 + agi) × moraleMult(A) / [(atk×2 + agi) × moraleMult(A) + (def×0.5 + agi×1.5) × moraleMult(D)]

• Morale multiplier: 1.0 at ≥50 morale, dropping linearly to 0.6 at 0 morale.
• On hit: damage = weapon_roll(min, max) + strength × 0.8 × moraleMult. Reduced by defense × 0.6 × moraleMult. If blocking, further reduced to 35%.
• Crit rate: 5% + agility%. Crit multiplier: 1.75×.
• A miss boosts the defender’s morale by 3 (emboldened).
• A hit erodes the defender’s morale by 4 (or 8 on crit).

Block

Brace until next turn. Damages taken are reduced to 35%. Restores 5 morale. The block stance lapses automatically when the blocker’s next turn begins. The AI notices blocking and shifts toward taunts and casts (which partially or fully ignore armor).

Cast

Spend 3 focus (built at +1/turn, capped at 3) to hurl an arcane bolt. Ignores armor entirely — defense does not reduce cast damage. Blocking still helps (damage reduced to 60% instead of 35%). Damage formula: roll(4,8) + charisma × 1.2. Erodes 6 morale. Casting without enough focus causes a fizzle: the caster loses 5 morale from the crowd’s jeers.

Taunt

The signature mechanic. A charisma contest:

power = charisma(A) × 2 + roll(0,10)
resist = charisma(D) + roll(0,10)

• If power ≤ resist: backfire. The defender gains 6 morale, the attacker loses 4.
• If power > resist: defender loses min(30, 8 + (power - resist) × 0.8) morale. Attacker gains 4.
• At 0 morale, the defender must pass a 35% flee check on every subsequent taunt. Fleeing is an instant loss, regardless of HP.
• Each fighter has a repertoire of taunt lines; one is selected at random per taunt attempt.

Rest

Recover roll(6,10) + vitality/4 HP and 10 morale. However, the resting fighter is exposed: incoming damage until their next turn is increased (the block multiplier of 0.35 does not apply, and the rest action does not set blocking = true — the fighter takes full damage).

3.4 Morale System

Morale ranges from 0 to 100 and is the combat differentiator. Below 50 (the “shaken” threshold), attack and defense are penalized by a linear multiplier from 1.0 down to 0.6 at 0 morale. At 0 morale, a fighter may flee (35% per taunt received). Morale is damaged by being hit, being taunted, and fizzling a cast. It is restored by blocking, resting, dodging an attack, and successfully taunting. This creates a second dimension of combat: you can win by depleting HP, or by breaking your opponent’s nerve.

3.5 AI Personalities

Five personality archetypes govern opponent decision-making via weighted random action selection:

These weights are dynamically modified by the fight state: - Low HP (<35%) doubles block weight and adds +3 to rest (except berserkers, who never rest). - Enemy morale ≤25: +4 to taunt weight (smell blood). - Enemy blocking: attack weight halved, +2 to taunt (chip morale instead of swinging into a shield). - Enemy HP <20%: +6 to attack, rest weight set to 0.1 (finish them). - Cast weight drops to 0.1 when focus < 3 (can’t cast yet).

3.6 Deterministic RNG

Combat uses the mulberry32 algorithm, a fast 32-bit PRNG:

a = a + 0x6D2B79F5
t = imul(a ^ (a >>> 15), 1 | a)
t = t + imul(t ^ (t >>> 7), 61 | t)
return ((t ^ (t >>> 14)) >>> 0) / 4294967296

Every fight is seeded. Given the same seed and action sequence, the fight replays identically. This is the foundation for on-chain fight verification: the seed can be committed before the fight, and the action sequence submitted afterward for a verifier contract to replay and confirm the outcome. Chance values are clamped to [0.02, 0.95] so nothing is probabilistically certain.

3.7 The Opponent Ladder

Ten opponents, tier 0 through 9, each with unique stats, equipment, personality, taunt lines, and flavor text:

4. The GOLD Token Economy

The GOLD token (SPL, 0 decimals, mint authority held by the arena-core PDA) is the sole medium of exchange, unit of account, and store of value within SOL&Sandals. Its supply policy is designed to transition from inflationary bootstrapping to deflationary maturity.

4.1 Supply Policy

The cap is on cumulative minted (total_minted), not on circulating supply. Burns do not reopen emission room — once minted, that unit counts against the cap forever. This prevents the classic “burn and re-mint” dilution attack.

Emission is demand-driven, not clock-driven. The faster the game grows, the sooner rewards halve. Early players are compensated for bootstrapping the economy; late-era players rely on the sink/velocity economy rather than issuance.

4.2 Sinks

Every sink splits its payment by TREASURY_SHARE_BPS = 5000: 50% burned, 50% routed to the treasury PDA (burn takes the rounding remainder).

Entry Fee Schedule

Above tier 2, a loss is a net GOLD loss. This makes reckless farming of high tiers self-defeating.

Forge Cost Schedule

The full forge ladder costs 102,300 GOLD — approximately 170 days of capped daily income — and the total bonus it unlocks (+20%) generates far less GOLD over a player’s lifetime than the sink cost. Forge is a net-negative GOLD flow: it exists to give late-game players something to burn toward, not to print more tokens.

4.3 Staking and Bonds

Staking locks GOLD in a program vault, removing it from the circulating float. It serves two purposes:

1. Reward bonus: +1% fight gold per 50 GOLD staked, capped at +20% (1,000 GOLD staked).
2. Appearance bond: Required to enter elite arenas. Tier 6 requires 50 staked, tier 7 requires 100, tier 8 requires 150, tier 9 requires 200. Tiers 0–5 require no bond.

The combined forge + stake bonus is capped at +40%. Bonuses multiply the base reward after era scaling but before the daily cap. The daily cap is always enforced — bonuses increase how fast you reach the cap, not the cap itself.

Staked GOLD is subject to a minimum lock period (MIN_STAKE_LOCK_SLOTS = 300 on devnet, ~2 minutes; designed for days on mainnet). Each new stake refreshes the lock timer.

4.4 Treasury

The treasury PDA accumulates 50% of every sink payment. It is a program-owned token account with no direct withdrawal instruction in the current deployment — spend governance is deferred to Phase 3 (see §8). Planned uses: DEX liquidity seeding, tournament prize pools (recycled, not minted), buy-and-burn operations. The treasury also serves as an on-chain verifiable sink accumulator: anyone can read its balance and confirm the total GOLD drained from circulation.

4.5 Float Accounting

At any point, the effective circulating supply is:

float = total_minted - total_burned - treasury_balance - total_staked

All four values are readable from GameConfig and the treasury/stake vault token accounts. The economic claim is not that GOLD is scarce, but that its float is transparent and its supply-side drivers are fully constrained.

5. On-Chain Programs

5.1 arena-core

The central hub. Owns the GOLD mint authority (a PDA), manages gladiator identity, and records PvE fight results.

Accounts: - GameConfig — singleton PDA at ["config"]. Stores authority, gold_mint, aggregate counters. - GladiatorProfile — one PDA per NFT at ["gladiator", nft_mint]. Stores level, XP, W/L, rating, cooldown, gear tier, daily emission tracking. - StakeAccount — one PDA per owner at ["stake", owner]. Tracks staked amount and lock expiry.

Instructions: - initialize — creates GameConfig, GOLD mint (PDA authority), treasury, stake vault. One-time. - register_gladiator(name) — creates profile, mints era-scaled stipend. Requires holding the NFT. - record_fight(tier, won) — charges entry fee (burned + treasury), verifies cooldown, checks bond, awards XP/rating, mints GOLD (era-scaled, boosted by forge/stake, clamped by daily cap and supply cap). Emits FightRecorded event. - forge_upgrade — burns 100 × 2^tier GOLD, increments gear tier. Emits GoldSunk. - rename_gladiator(new_name) — burns 25 GOLD, updates name. Emits GoldSunk. - stake_gold(amount) — transfers GOLD to stake vault, records amount and lock. Emits GoldStaked. - unstake_gold(amount) — returns GOLD from vault after lock expires. Emits GoldUnstaked.

5.2 arena-wager

Trustless PvP betting. State machine: Open → Active → Settled/Canceled/Refunded.

Instructions: - create_match(match_id, stake) — challenger escrows stake into a match PDA vault. Any SPL mint accepted (client enforces GOLD). Match is Open. - join_match — opponent matches the stake. Match becomes Active. Clock restarts for timeout. - settle_cooperative(winner) — both players co-sign. Winner receives the pot (2× stake). Match is Settled. - settle_by_arbiter(winner) — the designated arbiter (a pubkey set at match creation, e.g., a game server key) signs. Fallback for when a loser refuses to co-sign. - cancel_match — creator reclaims stake from an Open match nobody joined. - timeout_refund — anyone can trigger a refund of both stakes after SETTLE_TIMEOUT_SLOTS (9000 slots, ~1h on devnet). Funds can never be permanently locked.

Security properties: - The vault authority is the match PDA — only the program can move escrowed funds. - Settle paths are gated by signature checks (cooperative: both players; arbiter: the designated key). - The timeout path is permissionless after the slot threshold: no signature is required from either player. This is the ultimate escape hatch.

5.3 marketplace

Escrowed NFT listings priced in GOLD. One listing per NFT mint.

Instructions: - init_market — one-time setup pinning the payment mint, treasury, and authority. - list_item(price) — seller escrows the NFT into a listing PDA vault. - buy_item — buyer pays the seller (price − fee), burns half the fee, routes half to treasury, receives the NFT. Listing and vault are closed; rent returns to the seller. Emits ItemSold. - cancel_listing — seller reclaims the NFT, closes the listing and vault.

Fee structure: 5% of sale price. Split 50/50 between burn and treasury (2.5% each). For a 100 GOLD sale: seller receives 95, 3 GOLD burned, 2 GOLD to treasury.

6. Frontend Architecture

6.1 Tech Stack

• React 18 with TypeScript
• Vite 5 for build and dev server
• @solana/wallet-adapter for Phantom/Solflare
• Metaplex UMI for NFT minting
• Pure CSS (no framework) — dark arena theme
• State persisted to localStorage (fully playable without a wallet)

6.2 Screens

6.3 SVG Gladiator Rendering

The gladiator is rendered as an inline SVG with customizable appearance (skin tone, hair style, hair color, warpaint) set at character creation. Equipment changes the rendered character: each item carries a hue value that tints the corresponding body part (weapon in hand, shield on arm, armor on torso, helmet on head, boots on feet). This creates visible progression — a fresh gladiator in a cloth tunic looks fundamentally different from a tier-10 champion in Dreadlord Cuirass wielding a Titan Cleaver.

7. Security and Trust Model

7.1 Current State (Devnet Demo)

record_fight is self-reported by the NFT holder’s wallet. The program trusts the caller’s won: bool and tier parameters. This is acceptable for a devnet demo where GOLD has no real-world value. The following mitigations bound the damage of forged wins:

7.2 Production Path

The combat engine is already deterministic and seedable. The production verification path is:

1. Commit-reveal: Before a fight, the player commits to a seed hash on-chain. After the fight, they submit the (seed, action_sequence). An on-chain verifier replays the engine, confirms the outcome, and only then mints rewards.

2. Signed oracle: A game server (the same key that serves as arbiter in PvP wagers) signs fight results. The program verifies the signature against a known oracle pubkey.

Both approaches are compatible with the current engine without modification. The daily cap, entry fees, and bonds remain valuable as defense-in-depth even with verified fights.

7.3 Known Limitations

• Wager accepts any SPL token as stake. The program does not hard-check that the mint is GOLD — the client enforces this. A malicious client could create a wager in a worthless token. Mitigation: the UI only allows GOLD wagering; the arbiter path could also dispute non-GOLD matches.
• One listing per NFT mint. To change the price, the seller must cancel and re-list. No update_price instruction exists.
• NFT metadata uses data: URIs. This avoids external storage dependencies for devnet but means metadata is not permanently stored. Production would use Arweave or IPFS (e.g., via Irys).
• Account migration. The GameConfig, GladiatorProfile, and Market accounts changed layout with the economy update. Existing devnet deployments need a fresh deploy or a migrate_* reallocation instruction (not implemented; documented in ECONOMY_DESIGN.md).

8. Economic Analysis

8.1 Why GOLD Can Hold Value

The economic claim is narrow and defensible: given organic demand for the game, GOLD can hold value, whereas an unbounded-faucet token provably cannot. The mechanisms:

1. Utility demand. GOLD is required for: arena entry above tier 0, forge upgrades, elite bonds, renames, marketplace purchases, and PvP stakes. A player who wants to progress must acquire GOLD — either by playing or by buying from other players.

2. Burn deflation. Every sink destroys ≥50% of what it collects. Once emission eras advance, net supply growth can turn negative while activity is high. Marketplace burn scales with trade volume, which grows with player count.

3. Lockup constrains float. Bonds + staking remove a structural fraction of supply. Progression forces lockup — to farm the best arenas, you must first lock GOLD.

4. Hard cap enables pricing. 50M lifetime units, verifiable on-chain. A market can price a capped asset; it cannot price an unbounded one.

5. Honest assumptions. This holds only if (a) the game retains players — token design cannot rescue a game nobody plays; (b) fight verification becomes trust-minimized; (c) real liquidity exists (Phase 3). The system is designed to be compatible with value accrual, not to guarantee it.

8.2 Emission Era Projection

At era 5 the cap is reached and all emission stops. Fights still grant XP and rating — GOLD emission simply ends. The economy thereafter runs entirely on velocity: existing GOLD circulates through wagers, marketplace trades, entry fees, and forge upgrades.

8.3 Sink/Faucet Balance (Era 0, per gladiator per day)

Maximum faucet: 600 GOLD/day (hard cap). Maximum sink (theoretical): 18 GOLD/fight × 5 fights/day (cooldown-bounded) = 90 GOLD/day in entry fees. Forge at tier 9→10: 51,200 GOLD (one-time, ~85 days of capped income). Net daily: At the cap, even a 100%-win-rate tier-9 farmer (implausible without verification) nets at most 600 − 90 = 510 GOLD/day — but the forge curve ahead of them will consume it all. A realistic mid-tier player (tier 5, mixed W/L) nets 50–150 GOLD/day after entry fees.

The sink/faucet balance is not perfectly symmetric at launch — that would make the game unplayable. It is designed so that early eras are net-inflationary (bootstrapping) and late eras are net-deflationary (maturity), with the crossover determined by actual player activity rather than a calendar date.

9. Roadmap

Phase 1 — Implemented (Current)

• Supply hard cap + halving emission eras
• Arena entry fees, forge sink, rename sink
• Staking: vault, lockup, bonds, reward bonus
• Treasury PDA (accumulating 50% of all sink flow)
• Marketplace with 5% fee (burn/treasury split)
• Mirrored client math in progression.ts
• 17 Anchor integration tests + 34 vitest unit tests + cargo unit tests

Phase 2 — Trust + More Sinks (Planned)

• Wager rake (e.g., 2% of pot, burn/treasury split)
• Healing/repair fees after PvP losses
• Respec costs for stat reallocation
• Seasonal cosmetics from the treasury
• Commit-reveal fight verification
• Per-wallet (not per-gladiator) daily emission caps

Phase 3 — Market Infrastructure (Planned)

• DEX pool seeded from treasury (GOLD/SOL)
• Treasury buy-and-burn keeper bot
• Staking yield paid from treasury inflow (never from new emission)
• Governance over economic constants
• Arweave/IPFS NFT metadata storage
• Mainnet deployment with verified trust model

10. Conclusion

SOL&Sandals is not a token with a game attached. It is a game whose economic design makes the token necessary, scarce, and auditable. The combat engine is fast, deterministic, and fully testable. The on-chain programs are minimal — three contracts, one token, no oracles, no dependencies between programs. The sinks are the core loop: every time a player fights, forges, renames, or trades, GOLD leaves circulation. The emission schedule is capped and decaying. The treasury exists but cannot print.

The system makes no promises about price. It makes a verifiable promise about supply. The rest depends on whether people want to fight in the arena.

Appendix A: Program Constants Reference

Appendix B: XP Curve

Level n requires 50 × n × (n−1) total XP: - Level 1: 0 XP - Level 2: 100 XP - Level 3: 300 XP - Level 5: 1,000 XP - Level 10: 4,500 XP - Level 20: 19,000 XP - Level 50: 122,500 XP (max level)

Repository: github.com/navzar97/gladiator-arena License: MIT