30 include game use case documentation

README.md

@@ -22,7 +22,7 @@ This repository will contain a reference implementation of a Substrate partnerch
 
 In the [docs](./docs/) folder you can find important information such as the [contribution guidelines](./docs/CONTRIBUTING.md) and the procedure for [releases](./docs/release_procedure.md). You can also find a document briefly explaining the [project structure](./docs/project_structure.md).
 
-Here you can also find the [dev activity logs](./docs/dev_logs/). The [initial_customizations](./docs/dev_logs/initial_customizations.md) document thoroughly explains the project and each step taken to modify the original template. It includes installation and running instructions, explanations on every component and a detailed walk through on each modification to the original node template. The [partner_chain_integration](./docs/dev_logs/partner_chain_integration.md) document explains the modifications made to include the partner-chain features, modifications on the partner-chain features themselves, and a step-by-step guide on how to use the commands to set up the governance UTxOs on the Cardano side, using a local development testnet. 
+Here you can also find the [dev activity logs](./docs/dev_logs/). The [initial_customizations](./docs/dev_logs/initial_customizations.md) document thoroughly explains the project and each step taken to modify the original template. It includes installation and running instructions, explanations on every component and a detailed walk through on each modification to the original node template. The [partner_chain_integration](./docs/dev_logs/partner_chain_integration.md) document explains the modifications made to include the partner-chain features, modifications on the partner-chain features themselves, and a step-by-step guide on how to use the commands to set up the governance UTxOs on the Cardano side, using a local development testnet. The [use_case_implementation](./docs/dev_logs/use_case_implementation.md) document explains the modifications made to the node to add the use case specific features.
 
 ## Getting Started
 
@@ -60,7 +60,13 @@ With this command you can start a local development chain that will use predefin
 
 ### Interacting with the node
 
-You can follow the instructions at [wallet](/wallet/README.md) to interact with the node using the Griffin wallet.
+You can follow the instructions at [wallet](/wallet/README.md) to interact with the node using the Griffin wallet. Starting from `v0.0.4` the wallet is integrated into the node commands. This means you can use it directly with the node's executable:
+
+```sh
+./target/release/griffin-partner-chains-node wallet <wallet-subcommands>
+```
+
+> Note: this command only supports the wallet's subcommands. This means options like `--purge-db` are NOT supported. You can manually clean the wallet's database with `rm -r ~/.local/share/griffin-wallet/`. If you have the `griffin-wallet` executable, you can use options and commands like normal.
 
 ### Build and run with docker
 
@@ -92,7 +98,8 @@ Make sure that the endpoint you are connecting to matches the node's being run i
 ## Use-case: Asteria game
 
 As the result of the discovery process, after surveying many developers, it was decided that the use case for the partnerchain reference implementation would be a game. We chose the game Asteria which consists of ships moving across a board to find the Asteria prize and collect a portion of it.
-In this repository we include the [on-chain code](./game/onchain/), which comes with a [design document](./game/onchain/docs/design/design.md) that thoroughly explains the transactions involved in the game. In the game [src](./game/src/) you can find the implementation of the commands necessary to play the game and [detailed instructions](./game/README.md) on how to run them.
+
+In this repository we include the [on-chain code](./game/onchain/), which comes with a [design document](./game/onchain/docs/design/design.md) that thoroughly explains the transactions involved in the game. In the game [src](./game/src/) you can find the implementation of the commands necessary to play the game and a [README](./game/README.md) that goes over the app design, in the context of the game's integration into the node, and [instructions](./game/README.md#game-usage) on how to run the commands.
 
 ## Setting up a Partner Chain
 

game/README.md

@@ -1,9 +1,61 @@
 # Game: Asteria
 
-As part of the discovery process, it was decided that the use case for the partnerchain reference implementation would be a game. We decided on implementing Asteria which is a simple game about that showcases the capabilities of the eUTxO model.
-The game consists of ships moving across a two-dimension grid to find the Asteria, which holds a prize pool that the players can redeem a portion of. In the grid there are also pellets that hold fuel for the ships to collect. The operations of the game are: create a ship, move a ship, gather fuel and mine asteria. 
+As part of the discovery process, it was decided that the use case for the partnerchain reference implementation would be a game. We decided on implementing Asteria which is a simple game about that showcases the capabilities of the eUTxO model. The game is simple: each player has its own ship that they can move according to a maximum speed to reach Asteria and claim a reward. 
 
-The game is implemented through commands that build the transactions for each operation. A more in depth explanation of the game can be found in the [design document](./onchain/docs/design/design.md).
+In this document we’ll go over the [mechanics of the game](#brief-introduction-to-game-mechanics), to better understand the requirements, then we’ll lay out the [design decisions and technical aspects](#technical-details) of the implementation, and finally, we'll detail the [usage of the game](#game-usage) via node commands.
+
+## Brief introduction to game mechanics
+
+The game happens within a 2D grid through which `ships` can travel by moving a certain `distance` that does not surpass the `maximum speed`. The `Asteria` is at the center of the grid, at the `(0,0) coordinates`. Dispersed through the grid at fixed coordinates are `pellets`, which are freely available sources of fuel that ships can consume when they are sitting on those same coordinates.
+The distance between the Asteria and the ships, or the ship’s before and after moving, is measured using [Manhattan distance](https://en.wikipedia.org/wiki/Taxicab_geometry).
+
+The game is ruled over by on chain validators that are parameterised. Because of this, we can have various games with different settings. The most relevant parameters for our case are the following:
+
+- `Min_asteria_distance`: minimum distance between the Asteria and a new ship on its creation.
+- `Max_ship_fuel`: maximum amount of fuel that a ship can have.
+- `Max_asteria_mining`: maximum percentage of the reward pool that a single ship can withdraw upon arriving at Asteria
+- `Max_speed`: maximum distance a ship can travel in a certain time.
+- `Fuel_per_step`: how much fuel is consumed when moving the ship 1 step.
+
+And we have the following configuration:
+
+- `Min_asteria_distance`: 10
+- `Max_ship_fuel`: 30
+- `Max_asteria_mining`: 50
+- `Max_speed`: 1 step per 30 seconds.
+- `Fuel_per_step`: 1 fuel per step.
+
+### Game Operations
+
+Let’s see the details of the operations that our node supports and their constraints:
+- *Create ship*: Places a new ship on the map, according to the coordinates provided by the user. This initial placement needs to abide by the previously mentioned `min_asteria_distance`. 
+- *Move ship*: Moves a ship to the coordinates provided by the user if:
+the movement complies with the max_speed, and
+the ship has enough fuel to travel
+- *Gather fuel*: Collects fuel from a pellet if the ship’s coordinates overlap the pellet’s.
+- *Mine Asteria*: Collects a portion of the reward if the ship’s coordinates overlap Asteria’s and the portion to be redeemed satisfies `max_asteria_mining`.
+
+There are more operations that we don’t support, and there are other validations done upon these operations we mentioned, but for the sake of simplicity we don’t go over every single one of the validations. For a more thorough explanation, you can check [Asteria’s official repository](https://github.com/txpipe/asteria).
+
+## Technical details
+
+Asteria is implemented utilizing the capabilities of the eUTxO model. It relies on three validators to check every operation of the game.  It uses redeemers to specify game operations, and uses datums to keep the game’s state. We won’t discuss the overall design of the application in the eUTxO model as there is already a [design document](./design/design.md) that excellently describes it. From now on we’ll describe the technical aspects of implementing the game in our Substrate node.
+
+### Offchain implementation
+As the first step, we decided on an offchain transaction building approach. This is the functionality that allows us to interact with the chain, and it is similar to that of regular offchains we see on Cardano. This allowed us to integrate the game easily into the node with minimal modifications to the node itself.
+The complexity arises as the system does not have a lot of usual features like a balancer, e.g., every output has to be constructed individually taking the coin expenses in consideration. Fortunately, there are no fees so that reduces the calculations to perform. 
+
+### Node integration
+
+The key step is to integrate the game into the node via the definition of a command line interface that allows the users to play the game and the modification of the genesis of the chain.
+
+#### Genesis
+
+An important decision made was to assume a fixed instance of the validators. This allows us to initialize the chain with the game board in the genesis. In the file that holds the initial UTxO set of the chain, we included the UTxOs for the Asteria and some pellets. This means that as soon as the chain starts, the user can enter the game by creating their ship.
+
+#### Node commands
+
+The main purpose of these functions is to simplify the usage for the user, as they could interact with the game using the `tx-builder` as well. The game commands are innate to the node, as we want the game to be the main functionality of the chain.
 
 ## Game usage