sovereignty-game 2.3.4

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

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

Sit down with 2-4 friends, roll a die, move around a board, and try to end up with more coins or more goodwill than anyone else. Make promises out loud — keep them and people trust you, break them and they don't. No prior games like this needed. No screens at the table.

Play tonight

Print the whole print-and-play package — board, player mats, quick reference, Market Board, and three decks of cards on 13 sheets of US Letter paper. Find a die and some coins. Sit down with two or three friends. You're playing in twenty minutes.

If you want individual sheets:

• Board — the 16-space Campfire loop, one page.
• Player mat — coins, reputation, upgrades, promises. One per player.
• Quick reference — board spaces, turn order, promise rules.
• Event cards — 28 cards, four pages, cut along the lines.
• Deal cards — 12 cards, two pages.
• Voucher cards — 10 IOUs between players, two pages.
• Market Board — Market Day / Town Hall, one page.
• Treaty quick reference — Tier 3 only.

The PDFs are vector with embedded fonts — they print clean on any home printer. Setup walkthrough lives at Print & Play.

Want a console to keep score?

Optional. The game runs fine on paper. But if someone has a laptop handy, sov tracks coins, rep, promises, and produces a tamper-proof receipt at the end:

pip install sovereignty-game
sov play campfire_v1

sov play campfire_v1 is the no-config quickstart — one human plus a default opponent. For multi-player at the table, use sov new -p Alice -p Bob -p Carol. For a guided 60-second walkthrough, use sov tutorial.

No Python? The npx path downloads a prebuilt binary:

npx @mcptoolshop/sovereignty tutorial

Or run it in Docker, with your saves kept in a named volume:

docker run --rm -it -v sov-data:/data ghcr.io/mcp-tool-shop-org/sovereignty tutorial

A real session

Once you and 2-3 friends are at the table, the console runs the round and you do the talking. A real session looks like this:

# Start a game with three players
sov new -p Alice -p Bob -p Carol

# Each player takes a turn — roll, land, resolve
sov turn

# Check where everyone stands
sov status

# When everyone has gone, close the round
sov end-round

sov status shows a Rich-formatted table with player coins, rep, upgrades, position, and goal. For a quick one-line glance between turns:

sov status --brief

R3 |  Alice: 7c 4r 0u | >Bob: 4c 3r 0u |  Carol: 6c 5r 0u

(Nc Nr Nu = coins / rep / upgrades; > marks the active player.)

Repeat for 15 rounds. sov game-end prints the final scores.

• Multiple saved games (v2.1+): sov games lists saves; sov resume <game-id> switches between them.
• Batched anchoring (v2.1+): sov anchor at game-end flushes pending rounds into a small constant of XRPL AccountSet transactions (≤8 memos each; a typical 16-round Campfire game → 2 txs) — not a single transaction / single chain pointer. Use sov anchor --checkpoint for mid-game flush.
• Network selection (v2.1+): sov anchor --network testnet|mainnet|devnet (or SOV_XRPL_NETWORK env var; default testnet).
• Daemon mode (v2.1+, optional): sov daemon start runs a localhost HTTP/JSON server for desktop integration and background chain polling. See Daemon mode below.
• Audit Viewer desktop app (v2.1+, optional): npm --prefix app run tauri dev. See Desktop app below.

Want a guided in-app walkthrough first? Run sov tutorial. Want a deeper rules tour? See Start here or the full handbook.

The inline sov turn example above shows what a round looks like in the console; for the v2.1 desktop visualization, see Desktop app below.

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

sov play campfire_v1                 # no-config quickstart (v2.1+) — alias for sov new
sov new --recipe cozy -p ...         # curated vibe (cozy/spicy/market/promise)
sov new --tier treaty-table -p ...   # pick a tier
sov new --code "SOV|..." -p ...      # play from a share code
sov games                            # list saved games (multi-save, v2.1+)
sov games --json                     # machine-readable saves list (v2.1+)
sov resume <game-id>                 # switch to a saved game (v2.1+)
sov tutorial                         # learn in 60 seconds
sov turn                             # roll, land, resolve
sov undo                             # last-turn only (cleared by end-round)
sov status                           # show current game state
sov board                            # show the board layout
sov recap                            # what happened this round
sov promise make "I'll help Bob"     # say it out loud
sov promise keep "I'll help Bob"     # kept it: +1 Rep
sov promise break "text"             # broke it: -2 Rep
sov apologize Bob                    # once per game, pay 1 coin, +1 Rep
sov offer "2 coins for 1 wood" --to Bob  # make a trade offer
sov treaty make "pact" --with Bob --stake "2 coins"  # binding treaty
sov treaty list                      # show your treaties
sov market                           # show market prices + supply
sov market buy food                  # buy a resource (Town Hall+)
sov market sell wood                 # sell a resource (Town Hall+)
sov vote mvp Alice                   # table votes: mvp/chaos/promise
sov toast Alice                      # +1 Rep, once per player per game
sov end-round                        # generate round proof
sov game-end                         # final scores + Story Points
sov anchor                           # batch pending rounds to XRPL (v2.1+)
sov anchor --checkpoint              # mid-game flush (v2.1+)
sov anchor --network mainnet         # network selection (v2.1+)
sov verify <proof.json> --tx <txid>  # confirm a proof is anchored on chain
sov daemon start [--readonly]        # localhost HTTP/JSON daemon (v2.1+)
sov daemon status                    # running | stale | none
sov daemon stop                      # SIGTERM + cleanup
sov postcard                         # shareable summary
sov season-postcard                  # season standings / printable recap
sov feedback                         # issue-ready play report
sov scenario list                    # browse scenario packs
sov scenario code cozy-night -s 42   # generate a share code
sov scenario lint                    # validate scenario files
sov doctor                           # pre-flight check before play night
sov self-check                       # diagnose your environment
sov support-bundle                   # diagnostic zip for bug reports

The console keeps score. You keep your word.

Daemon mode (optional, v2.1+)

For desktop integration (Audit Viewer, Tauri shell) or background chain polling, run sovereignty as a localhost HTTP daemon:

pip install 'sovereignty-game[daemon]'
sov daemon start --readonly        # audit-only, no wallet seed
sov daemon start                   # full daemon with anchor endpoints (loads XRPL_SEED)
sov daemon status                  # running | stale | none
sov daemon stop

Daemon binds to 127.0.0.1 on a random port; connection details (port + bearer token) live in .sov/daemon.json. One daemon per project root. See docs/v2.1-daemon-ipc.md for the full IPC contract.

The [daemon] extra needs 2.3.2 or later. Wheels through 2.3.1 left the sov_daemon package out, so sov daemon start failed on a PyPI install.

Docker (optional, v2.3.2+)

The image at ghcr.io/mcp-tool-shop-org/sovereignty carries the sov CLI and the daemon, for linux/amd64 and linux/arm64. Everything the game remembers lives under /data/.sov: games, round proofs, anchors.json, the season record, the wallet seed, and the daemon handshake. Mount a volume on /data or the container forgets it all.

Run the daemon with the bundled compose.yaml:

docker compose up -d                  # readonly audit daemon on 127.0.0.1:47823
docker compose run --rm sov doctor    # any sov command, same saves
docker compose run --rm sov play campfire_v1
docker compose logs -f

The container defaults to a readonly daemon on testnet. The port is published to the host's loopback only (127.0.0.1:47823), and every request still needs the bearer token from .sov/daemon.json.

Attach the desktop app. Point SOV_DATA at the project folder the app opens. The daemon writes its handshake there, and the app dials 127.0.0.1:47823 with the token from it:

SOV_DATA=./ docker compose up -d

While the container owns the daemon, manage it with docker compose, not sov daemon start|stop|status on the host. The host CLI can't see a container's process, so it reports the handshake as stale, and sov daemon start would clear it.

Anchor from the container. Create a testnet wallet in the volume, then turn readonly off:

docker compose run --rm sov wallet
SOV_DAEMON_READONLY=0 docker compose up -d

To keep the seed out of the volume, supply it as a Docker secret instead. The commented secrets block in compose.yaml shows how.

Desktop app (optional, v2.1+)

The Audit Viewer is the v2.1 desktop app — a Tauri shell (Rust + webview) that runs the audit viewer and a read-only game view on top of the daemon.

Install (binaries)

v2.3.4 is the current release. GitHub Release v2.3.0 did not ship wheels or desktop assets, so do not pin pip install …==2.3.0.

• Python / daemon: pip install 'sovereignty-game[daemon]' (2.3.2 or later for the daemon).
• Desktop app: the latest GitHub Release when CI has attached platform files. If a platform job failed, run from source (below).

First-launch OS warning is expected when attested binaries do ship. Those builds carry SLSA build-provenance attestation only — not OS-level Apple Developer ID / Authenticode signing. macOS: control-click the .app → Open. Windows SmartScreen: More info → Run anyway.

Verify provenance

When a release actually attaches desktop artifacts, verify the file you downloaded:

gh attestation verify \
  --repo mcp-tool-shop-org/sovereignty \
  ./<downloaded-artifact>

A clean verification proves the binary was built from a specific commit, by the release workflow, in this repo. Different layer of trust than OS-level code signing — the binary still triggers the OS warning, but its supply-chain provenance is cryptographically pinned.

Run from source

If you'd rather build from source (or the binary won't run on your platform):

# 1. Install Python + daemon deps
pip install -e '.[xrpl,daemon]'

# 2. Install frontend + Rust deps (one-time)
cd app && npm install && cd ..
cargo build --manifest-path app/src-tauri/Cargo.toml

# 3. Start the dev shell (auto-starts the daemon in readonly mode)
npm --prefix app run tauri dev

The Tauri shell auto-starts a readonly daemon on launch and auto-stops it on exit. Externally-started daemons (sov daemon start) stay alive across shell restarts.

See docs/v2.1-tauri-shell.md for the full contract.

The Audit Viewer ships with three views:

• /audit — XRPL-anchored proof viewer. Collapsible per-game list, per-round anchor status, "Verify all rounds" runs local proof recompute + chain lookup in series. The auditor's view: confirm a game ran honestly without reading raw JSON.
• /game — passive real-time state display for the active game. Player resource cards, round timeline, last-20 SSE events log. Read-only; play in the CLI in another terminal.
• /settings — daemon config display + network switcher (testnet / mainnet / devnet) with mainnet-confirmation guardrail.

Full view spec at docs/v2.1-views.md.

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.

28 Event cards read like moments: "Has anyone seen a small leather pouch?" (Lost Wallet) or "Nobody saw... right?" (Found a Shortcut). Includes market-shift events for Town Hall games.

12 Deal cards + 10 Voucher cards force conversation: "Spot me 2 coins? I'll pay 3 back." or "I've got your back if you've got mine." Deals set goals with deadlines; Vouchers are IOUs you issue to other players.

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

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

Scenario packs

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

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")
  sov_daemon/       # Localhost HTTP/SSE daemon for the desktop app
  app/              # Tauri desktop app (Audit Viewer)
  docker/           # Container entrypoint + healthcheck
  site/             # Landing page + handbook
  tests/            # Engine, transport, daemon, and CLI tests
  docs/             # Rules, cards, print-and-play, play-with-strangers
  assets/print/     # Print pack — markdown sources, rendered PDFs, JSX render sources

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

License

MIT

Built by MCP Tool Shop