sovereignty-game 1.4.1

A strategy game about governance, trust, and trade — offline tabletop + XRPL online verification.

日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

A board game about trust, trade, and keeping your word.

Play tonight

Print the cards, grab a die and some coins, sit down with 2-4 people. No screens required. Takes about 30 minutes.

Start here | Print & Play | Full rules | Play with strangers

Or use the console

pipx install sovereignty-game       # one-time install (or: uv tool install sovereignty-game)
sov tutorial                         # learn in 60 seconds
sov new -p Alice -p Bob -p Carol     # start a game

Full command reference

sov new --recipe cozy -p ...         # curated vibe (cozy/spicy/market/promise)
sov new --tier treaty-table -p ...   # pick a tier
sov turn                             # roll, land, resolve
sov promise make "I'll help Bob"     # say it out loud
sov treaty make "pact" --with Bob --stake "2 coins"  # stakes
sov scenario list                    # browse scenario packs
sov scenario code cozy-night -s 42   # generate a share code
sov scenario lint                    # validate scenario files
sov new --code "SOV|..." -p ...      # play from a share code
sov doctor                           # pre-flight check before play night
sov recap                            # what happened this round
sov game-end                         # final scores + Story Points
sov postcard                         # shareable summary
sov feedback                         # issue-ready play report
sov season-postcard                  # season standings across games

The console keeps score. You keep your word.

How it works

You start with 5 coins and 3 reputation. Roll a die, move around a 16-space board, and land on spaces that give you choices: trade, help someone, take a risk, or draw a card.

20 Event cards read like moments: "Has anyone seen a small leather pouch?" (Lost Wallet) or "Nobody saw... right?" (Found a Shortcut).

20 Deal cards force conversation: "Spot me 2 coins? I'll pay 3 back." or "I've got your back if you've got mine."

The Promise rule: Once per round, say "I promise..." out loud and commit to something. Keep it: +1 reputation. Break it: -2 reputation. The table decides.

The Apology: Once per game, if you broke a promise, publicly apologize. Pay 1 coin to who you wronged, regain +1 reputation.

Pick your goal (secret or public):

• Prosperity — reach 20 coins
• Beloved — reach 10 reputation
• Builder — complete 4 upgrades

After 15 rounds, highest combined score wins.

What is Diary Mode?

Every round, the console can produce a proof — a fingerprint of the game state. If anyone changes the score, the fingerprint won't match.

Optionally, that fingerprint can be posted to the XRPL Testnet — a public ledger. Think of it as writing the score on a wall that nobody can erase.

sov end-round                        # generate proof
sov wallet                           # create testnet wallet (free)
sov anchor                           # post hash to XRPL (optional)
sov verify proof.json --tx <txid>    # trust but verify

Only the host needs a wallet. Nobody else touches a screen. The game works perfectly without anchoring — it's just the diary that remembers.

Three tiers

Tier	Name	Status	What it adds
1	Campfire	Playable	Coins, reputation, promises, IOUs
2	Town Hall	Playable	Shared market, resource scarcity
3	Treaty Table	Playable	Treaties with stakes — promises with teeth

Core rules are stable through v1.x. See roadmap.

Scenario packs

Zero new rules. Just vibes. Each pack sets a tier, recipe, and mood.

Scenario	Tier	Best for
Cozy Night	Campfire / Market Day	First game, mixed groups
Market Panic	Town Hall	Economy drama
Promises Matter	Campfire	Trust and commitment
Treaty Night	Treaty Table	High-stakes agreements

sov scenario list to browse from the console.

Project structure

sovereignty/
  sov_engine/       # Pure game logic (models, rules, serialization, hashing)
  sov_transport/    # Ledger transport (offline + XRPL Testnet)
  sov_cli/          # Typer CLI (the "Round Console")
  tests/            # 143 tests
  docs/             # Rules, cards, print-and-play, play-with-strangers
  assets/print/     # Printable cards, player mat, quick reference

Development

git clone https://github.com/mcp-tool-shop-org/sovereignty.git
cd sovereignty
uv sync --dev
uv run pytest tests/ -v
uv run ruff check .

Design principle

"Teach through consequences, not terminology."

Players learn by doing: issuing IOUs, breaking promises, trading at shifting prices. The concepts map to Web3 primitives — wallets, tokens, trust lines — but players don't need to know that to have fun.

Contributing

The easiest way to contribute is to add a card. No engine knowledge needed — just a name, a description, and some flavor text.

Security

Wallet seeds, game state, and proof files — what to share and what not to. No telemetry, no analytics, no phone-home. The only optional network call is XRPL Testnet anchoring.

See SECURITY.md.

Threat Model

Threat	Mitigation
Seed leakage via proofs	Proofs contain hashes only, never seeds
Seed in git	.sov/ gitignored; sov wallet warns
Game state manipulation	Round proofs hash full state; sov verify detects tampering
XRPL anchor spoofing	Proof hash anchored on-chain; mismatch detection in verify
Player name privacy	Game state is local-only; proofs don't include names

License

MIT

---

Built by MCP Tool Shop