Skip to content

🧩 HyperToken

About HyperToken

HyperToken is a distributed game engine where all game state is a Conflict-free Replicated Data Type (CRDT).

That architectural choice supports serverless multiplayer, replayable state, and forkable worlds in a single codebase. The repository ships three playable examples. Two are familiar card games: Blackjack and Cuttle; and the third is a new game called Watershed.

Core model

An Engine coordinates actions against one Chronicle. The Chronicle wraps one Automerge document; Token, Stack, Space, Source, agents, and game-specific state are views or values held in that document. Callers mutate state through the asynchronous engine.dispatch() path rather than writing to the document directly.

flowchart LR
  App[Game or client] --> Dispatch[engine.dispatch]
  Dispatch --> Registry[TypeScript ActionRegistry]
  Registry --> Chronicle[Chronicle / Automerge document]
  Chronicle --> Events[state:changed / state:updated]
  Chronicle <--> Sync[ConsensusCore]
  Sync <--> Network[WebSocket or WebRTC transport]

State and data flow

Local application code dispatches a typed action. A registry handler performs the Automerge transaction, the Chronicle emits a state change, and observers render the new state. ConsensusCore exchanges Automerge sync messages with connected peers; peers merge document changes rather than replaying network commands.

Why a CRDT?

Automerge supplies causality-aware merging for concurrent replicas and allows a peer to make changes while disconnected. A relay can forward messages without becoming the authoritative owner of game state. This removes some coordination work, but it does not decide whether a move is legal or whether a participant is trustworthy.

Quick Start

Install dependencies, build the TypeScript distribution, and run one of the examples:

git clone https://git.carpocratian.org/sibyl/hypertoken.git
cd hypertoken
npm install
npm run build
npm run blackjack

See the Quick Start for Cuttle, Watershed, the relay, Docker, and documentation commands.

Current examples

Example Command Current role
Blackjack npm run blackjack Engine-backed card game with betting and agents.
Cuttle npm run cuttle Two-player card combat example with its own game rules and optional CRDT/network layers.
Watershed npm run watershed:web Browser territory game and CRDT synchronization showcase.

Implementation status

The active runtime is TypeScript with Automerge. All actions use the TypeScript ActionRegistry and Chronicle path; there is no separate HyperToken WASM backend. Browser builds use esbuild and an Automerge package entry point that inlines Automerge's WASM implementation into the bundle.

Persistence is exposed through storage adapters, including memory, filesystem, and IndexedDB implementations. Networking includes peer synchronization, a relay, WebSocket transport, and an optional WebRTC-capable hybrid manager.

Limitations and caveats

  • CRDT convergence means replicas can reach the same state; it does not mean the state is legal, fair, or resistant to cheating. Rules, policies, and deployment trust remain application concerns.
  • Seeded shuffles help reproduce a controlled sequence, but IDs, timestamps, agent decisions, initial state, action ordering, and network timing can still affect replay.
  • engine.compact() discards pre-epoch CRDT history. It rejects while networking or sync is attached, and all peers must coordinate the same compaction boundary.
  • Generic network encryption is not wired into the peer paths. The relay is unauthenticated by design; room authentication and stronger trust models are separate server capabilities.
  • Cuttle's encrypted-hand mode is an honest-dealer demonstration, not an adversarially fair shuffle protocol.

Documentation map

  • Concepts explains the state model and the main domain primitives.
  • Architecture maps source folders and runtime boundaries.
  • Quick Start lists supported setup and run commands.
  • Earlier long-form guides remain in the repository as historical references; this site supersedes them for current documentation navigation.

Next steps

Start with the CRDT state model, then read Engine and Chronicle. For a browser path, follow Browser Runtime and run Watershed.