RYO

Roll Your Own - A Dope Wars open universe project.

A modular game engine architecture for the StarkNet L2 roll-up, where computation is cheap and new game styles are being explored. Roll your own module and join the ecosystem.

What

A community-driven collection of contracts that allows sharing of game states between different game modules. Games all fit within the Dope Wars ecosystem, which is an open-ended project where anyone can add something for the community to enjoy.

Design a new game module that interests you. Call other modules and read their state to create composable game interactions. Create new artefacts that other future modules can use.

Games can pull inspiration from the DOPE ERC721 NFT on Mainnet, the item-equipped Hustler ERC1155 characters on Optimism, or other community ideas that are fun.

Some modules are outlines waiting to be explored and expanded. The first module is an implementation of the Drug Wars drug arbitrage game on TI-83-era calculators.

History:

• Background mechanism design notion here.
• Initial exploration / walkthrough viability testing blog here.
• Expansion for forward compatibility here.

From there the idea evolved to be a system where, just like the open-ended nature of the DOPE NFT, anyone can come and build what they like. To achieve that, the modules are able to read from each other by using a central coordinator contract. There is even the possibility to have contracts grant write access to each other, potentially though a governance process.

Join in

Everyone is welcome to join in:

• Learn about Cairo. A turing-complete language for programs that become proofs.
• Learn about StarkNet. An Ethereum L2 rollup with:
  • L1 for data availability
  • State transitions executed by validity proofs that the EVM checks.
• Work on anything to do with the game/ecosystem that fits your skills and interest.
• If you have an idea for a new module, first claim the next available number and start writing some ideas down in /module_notes. Then use the 00_TemplateModule.cairo file to start writing your module. Help is always available in the Dope Wars discord.

The modules here are by their nature experimental and assumed to be broken by default. The goal is to have fun exploring new ideas. As modules mature, they might be suitable to be slotted into the front end game, where players can use their characters. For example, a player might go to a payphone and partake in Module 01 to make a drug trade (single transaction), then go to a car park and start a fight using Module 08 (open channel with a single transaction).

Game modules can take any form, and if revenue is generated, there is a cultural norm to direct 5% to the DOPE DAO. If the community likes your idea, perhaps the DOPE DAO might vote to support you in your efforts!

System architecture

Modules can exist in isolation, or they can read or even write to other modules.

The game mechanics are separated from the game state variables. A controller system manages a mapping of modules to deployed addresses and a governance module may update the controller.

For example all these modules could read and write from the state modules and be connected-but-distinct game interactions:

• Try arbitrage drug markets 01 Dope Wars module. Manage inventory against risks and try to out-trade other players. Swap coke in one region and swoop in to collect cheap Krokodil after a regional drug bust.
• Try to become a regional Drug Lord by submitting an autobattler to the 05 Combat module. Hand crafted strategies submitted against the current drug Lord. Winner collects a cut from future regional trades.
• Try an L3 move-by-move 1v1 fight with another player in the 08 State channel module. Inventory from your work in the drug trades is placed as collateral for the channel. Off-chain messages signed by your key ensure that when submitted back to L2 the winnings are enforced. High-frequency moves allow for granular game play.
• Leave some graffiti on-chain, appraise and erase the tags of others with the Wall module (module 09).
• Generate a report card (module 11), attesting to the achievements of a player. Perhaps the report card can be structured to enable another module (or ecosystem) to ingest it.
• Explore or use a game-balancer, such as the one in module 11, giving equippable items a theme that is suited to specific domains.

Contract hierarchy

It is also worth pointing out that StarkNet has account abstraction (see background notes here). This means that transactions are actioned by sending a payload to a personal Account contract that holds your public key. The contract checks the payload and forwards it on to the destination.

• Player Account
  • A user who controls a Hustler (game character) in the system.
• Governance Account
  • 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.
• Arbiter (most power in the system).
  • Can update/add module mappings in ModuleController.
• ModuleController (mapping of deployments to module_ids).
  • 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/registry (for integrating L1 state/ownership to L2)
  • Other arbitrary contracts as they are added to the game system.

For more information see

• Modular system architecture.
• Descriptions of example modules in module notes.

Status

| Module | Description | Status | | --- | ----------- | - | | 01 DopeWars | Self-contained Drug Game with random hazards | Needs event/item effect paramater tweaks and improved call to user-registry | | 02 LocationOwned | Storage for module 01 dealer drug quantities | Functional. Can adjust initial values for different 'vibes'. | | 03 UseOwned | Storage for module 01 player drug quantities | Functional | | 04 UserRegistry | Stores cross-chain NFT ownership | Needs implementation of storage/input mechanism (E.g., storage proofs later if available) | | 05 Combat | King-of-the-hill fights from pre-planned moves | Needs design of combat data structure and calculations | | 06 DrugLord | Storage for module 05 winners | Functional | | 07 PseudoRandom | Source of pRandom numbers | Ready for low importance uses | | 08 StateChannel | 1v1 move-by-move off chain game | Needs design of data structure for messages | | 09 Wall | Store and vote on text 'graffiti' | Needs testing, could bve expanded. | | 10 ReportCard | Token that represents player performance | Idea only, no code. Likely suitable as ERC1155 | | 11 BellLabs | A three-axis scoring system for dope elements | Boiler-plate code and ideas only. Needs design/setting of values for each item on each axis | | Account | Identity/contract/wallet for each user | Regularly refresh from OpenZepellin's latest | | Arbiter | Can tell the module controller that one module has write access over another | Might be good to upgrade this to a governance contract to vote through write access changes | | ModuleController | Keeps module addresses so they can read or even write to each other | Functional. Can add new modules to initial module addresses set function |

Setup

Clone this repo and use our docker shell to interact with starknet:

git clone git@github.com:dopedao/RYO.git
cd RYO
bin/shell starknet --version

The CLI allows you to deploy to StarkNet and read/write to contracts already deployed. The CLI communicates with a server that StarkNet runs, which bundles the requests, executes the program (contracts are Cairo programs), creates and aggregates validity proofs, then posts them to the Goerli Ethereum testnet. Learn more in the Cairo language and StarkNet docs here, which also has instructions for manual installation if you are not using docker.

Development workflow

If you are using VSCode, we provide a development container with all required dependencies. When opening VS Code, it should ask you to re-open the project in a container, if it finds the .devcontainer folder. If not, you can open the Command Palette (cmd + shift + p), and run “Remote-Containers: Reopen in Container”.

Outline

Flow:

1. Compile the contract with the CLI
2. Test using pytest
3. Deploy with CLI
4. Interact using the CLI or the explorer

Compile

The compiler will check the integrity of the code locally. It will also produce an ABI, which is a mapping of the contract functions (used to interact with the contract).

Compile all contracts:

nile compile

Compile an individual contract:

nile compile contracts/01_DopeWars.cairo

Test

Run all github actions tests: bin/test

Run individual tests

bin/shell pytest -s testing/01_DopeWars_contract_test.py

Deploy

Start up a local StarkNet devnet with:

nile node

Then run the deployment of all the contracts. This uses nile and handles passing addresses between the modules to creat