Skip to content
Sovereignty

Getting Started

Sovereignty can be played as a physical board game (print the cards, grab a die and coins) or with the digital console that keeps score.

Install the console

Section titled “Install the console”

No Python required — downloads a prebuilt binary:

Terminal window
npx @mcptoolshop/sovereignty tutorial

Or install with Python:

Terminal window
pipx install sovereignty-game

Tutorial

Section titled “Tutorial”

Run the built-in tutorial to learn the basics:

Terminal window
sov tutorial

Start a game

Section titled “Start a game”

Create a new game with 2–4 players:

Terminal window
sov new -p Alice -p Bob -p Carol

Take turns:

Terminal window
sov turn

End a round and generate a proof:

Terminal window
sov end-round
Section titled “Print and play”

For the physical version, print the cards and reference sheets from assets/print/ (the PDFs in assets/print/pdf/). You need:

  • 28 Event cards
  • 12 Deal cards
  • 10 Voucher cards
  • Market Board (Market Day / Town Hall)
  • A six-sided die
  • Coins (real or tokens)

See How to Play and the full rules.

Multiple games at once (v2.1+)

Section titled “Multiple games at once (v2.1+)”

sov keeps every game you start under .sov/games/<game-id>/. Starting a new game no longer overwrites the old one.

Terminal window
sov games            # list all saved games (active marked with *)
sov resume s42       # switch the active game pointer to s42
sov games --json     # structured output for scripts

The active-game pointer at .sov/active-game tracks which game sov turn, sov status, etc. operate on. Existing v1.x layouts (.sov/game_state.json) auto-migrate transparently on first v2.1 invocation.

Daemon mode (v2.1+, optional)

Section titled “Daemon mode (v2.1+, optional)”

The daemon is an optional HTTP/JSON server that backs the desktop app and external audit tools. Install with the [daemon] extra:

Terminal window
pip install 'sovereignty-game[daemon]'   # 2.3.2+; earlier wheels lack sov_daemon


sov daemon start --readonly   # for the audit viewer
sov daemon status             # check pid/port/network/readonly
sov daemon stop               # clean shutdown

The daemon binds to 127.0.0.1:<random-port> with bearer-token auth. It serves audit reads + anchor writes (full mode); readonly mode is sufficient for the audit viewer alone.

Prefer a container? The same daemon ships as a Docker image with its state in a volume. See Docker.

Audit Viewer desktop app (v2.1+)

Section titled “Audit Viewer desktop app (v2.1+)”

The Audit Viewer visualizes XRPL-anchored proofs as collapsible per-game lists with per-round verify status. Three views ship:

  • /audit — XRPL-anchored proof viewer; “Verify all rounds” runs local proof recompute + chain lookup in series
  • /game — passive real-time state display for the active game
  • /settings — daemon config + network switcher (testnet / mainnet / devnet) with mainnet-confirmation guardrail

v2.3.6 is the current release. GitHub Release v2.3.0 did not publish wheels or desktop assets, so do not pin ==2.3.0.

Python/daemon: pip install 'sovereignty-game[daemon]'. Desktop: the latest GitHub Release when CI has attached files, otherwise npm --prefix app run tauri dev.

First-launch warning is expected

Section titled “First-launch warning is expected”

When attested binaries do ship, they carry build-provenance attestation only — not OS-level Apple Developer ID / Authenticode signing.

  • macOS: control-click the .app → Open → “Are you sure?” → Open
  • Windows: SmartScreen says “unrecognized publisher” → “More info” → “Run anyway”
  • Linux (.deb / AppImage): install or chmod +x the attached artifact, then launch

Verify supply-chain provenance

Section titled “Verify supply-chain provenance”

When a release actually attaches desktop artifacts, every artifact carries a SLSA build-provenance attestation:

Terminal window
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.

Network selection (v2.1+)

Section titled “Network selection (v2.1+)”

sov defaults to XRPL Testnet. Switch via flag or env:

Terminal window
sov anchor --network testnet     # default
sov anchor --network mainnet     # real XRP, real cost
sov anchor --network devnet      # short-lived test ledger


export SOV_XRPL_NETWORK=mainnet   # alternative: env var

Mainnet warning: anchoring on mainnet costs real XRP (~$0.0002/game). Mainnet has no faucet — set XRPL_SEED to a funded mainnet seed. The Audit Viewer’s network switcher shows a confirmation dialog before crossing the testnet→mainnet boundary.

Next steps

Section titled “Next steps”