Terms to consider. We recommend reading the Master Scroll (opens in a new tab) which outlines the theory behind the game.
Eternum is in active development and is evolving every month. This information could be outdated.
- A player with a wallet
- An admin who controls the Arbiter.
- The admin may be an L2 DAO to administer governance decisions voted through on L2, where voting will be cheap.
- Governance might enable a new module to have write-access to and important game variable. For example, to change the location that a player is currently in. All other modules that read and use location would be affected by this.
- Contract that can update/add module mappings in ModuleController
- The game 'swichboard' that connects all modules.
- Is the reference point for all modules. Modules call this contract as the source of truth for the address of other modules.
- The controller stores where modules can be found, and which modules have write access to other modules.
Modules (open ended set)
- Game mechanics (where a player would interact to play).
- Storage modules (game variables).
- L1 connectors (for integrating L1 state/ownership to L2)
- Other arbitrary contracts
How does the game work?
From a technical POV the game has two central contracts. The
Arbiter.cairo. All the games logic is split into Modules whose addresses are stored within the
ModuleController.cairo acts like a "switchboard" for the game. All modules route via it as it controls what modules can write. It is the long lived contract that should not have to be upgradable.
- Contract addresses
- Permissions of each contract
The Arbiter contract owns the
ModuleController.cairo contract. Only the owner of the
Arbiter.cairo can adjust the game state. In production the
Arbiter.cairo will be owned by a Multisig, or itself might be a multisig.
The game revolves around a Module Controller, this acts like a switchboard for the modules to route through. It controls what modules can write to what other module.
You will notice all contracts follow the proxy pattern. We believe in immutability when you do not have ownership governance, however games require constant upgrades, hence why we use the proxy pattern. Currently the owner of the contracts is the deployer, however this will be change to the Arbiter once in production. For fast iteration we have purposely left it as is.
Module structure (Core, Library, Interface, Constants)
All modules follow the same pattern. Once a module is complete it can be added to the
This contains the actual deployable contract. This contract contains imports from the modules Library, Interface and Constants files. It is best practice to develop this part of the module last. All logic should be ommited from this contract where possible and be contained within the
library.cairo file. Depoloying and testing contracts even in tests takes time, so by offloading all the logic into the libraries we can greatly accelerate development.
Libraries are composed of small composable stateless functions. They are the core of the module and contain all the logic necessary.
Interface file contains the necessary public endpoints to allow the contract to be called by another contract.
consts that belong to the module go in this file. Any generalised
structs live in
Get started by copying the module template folder and renaming.