DYSNOMIA (V1) — The Token Base Class¶
One-line pitch: DYSNOMIA is the shared base every other token in the ecosystem inherits from. Plumbing — you don't call it directly. It's what makes H2O, VITUS, LAU, CHO, and every other game token behave the same way.
What this is¶
DYSNOMIA is an ERC-20 base contract with three Dysnomia-specific additions:
- Built-in exchange (Purchase/Redeem) — any DYSNOMIA-based token can be swapped for another, with rates managed by ZHOU. No external DEX needed.
- MaxSupply determined by VMREQ — each token has a randomized cap, so supply curves vary.
- MultiOwnable — multiple owners can co-manage a token, supporting the system's delegation patterns.
It's the abstract parent class for everything. You'll almost never encounter DYSNOMIA directly, but you'll see inherits DYSNOMIA everywhere in the technical docs.
If you've played a web3 game before¶
- Closest analogy: OpenZeppelin's ERC20 contract — the mother-of-all-tokens base you inherit from.
- Or: a protocol-wide base like Compound's CToken — every token gets the same helpers.
- Or: a framework class every game token extends.
| Dysnomia term | What it maps to |
|---|---|
| DYSNOMIA | Shared ERC-20 base class |
| Purchase(token, amount) | Built-in swap — trade this token for another |
| Redeem(token, amount) | The inverse |
| GetMarketRate | Read the current conversion rate |
| maxSupply | Random cap set at deployment via VMREQ |
| Xiao | The math library the token uses |
| MotzkinPrime | Large prime used in the cryptographic math (953467954114363) |
What you actually do with it¶
- Use Purchase/Redeem via concrete tokens that inherit DYSNOMIA — LAU.Purchase, a QING's Purchase, etc.
- Don't construct a bare DYSNOMIA — always use a concrete subclass.
Rewards / costs¶
- Cost: Purchase / Redeem may have fee mechanics set by the inheriting token.
- Reward: none direct — DYSNOMIA itself just provides the machinery.
Requirements & gating¶
- You interact with it only through concrete tokens.
Where it connects¶
Inherited by every token in the ecosystem — LAU, CHO, H2O, VITUS, QING, WORLD, WAR, and all the plumbing contracts (YI, ZHENG, ZHOU, YAU, YANG, SIU).
Quick FAQ¶
Q: Why not just use standard ERC-20? A: The in-protocol exchange (Purchase/Redeem) and the randomized maxSupply are core game mechanics, not bolt-ons. Baking them into the base means every token gets them for free.
Q: What's the MotzkinPrime?
A: A large prime used in the cryptographic math (specifically in Fa/SHA reactions). Its value is 953467954114363. Appears everywhere modular arithmetic happens.
Q: V1 vs V2 — which should I use? A: V1 is the older version used by core/plumbing contracts. V2 is used by the domain (gameplay) contracts. Identical behavior for you as a player.
Want the Solidity? The contract reference lives at
technical/docs/core/01_DYSNOMIA.md.