Skip to content

Commit

Permalink
docs: scavenge tuto improve language and apply styles (ignite#2134)
Browse files Browse the repository at this point in the history 
* improve language and apply styles

* edits and style

* Update docs/guide/scavenge/02-game.md

Co-authored-by: Sonia Singla <soniasingla.1812@gmail.com>

Co-authored-by: Sonia Singla <soniasingla.1812@gmail.com>
  • Loading branch information
@barriebyron @soniasingla
barriebyron and soniasingla authored Mar 7, 2022
1 parent f76f9f0 commit 3f4eccf
Show file tree
Hide file tree
Showing 9 changed files with 353 additions and 104 deletions.
24 changes: 15 additions & 9 deletions docs/guide/scavenge/02-game.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,34 @@
order: 2
---

# The Scavenger Hunt Game
# Scavenger hunt game

The application you are building today can be used in many different ways but I'll be talking about building the app as a **scavenger hunt** game. Scavenger hunts are all about someone setting up tasks or questions that challenge a participant to find solutions that come with some sort of a prize. The basic mechanics of the game are as follows:
This tutorial focuses on building the app as a **scavenger hunt** game. Scavenger hunts are all about someone setting up tasks or questions that challenge a participant to find solutions that come with a prize. The basic mechanics of the game are as follows:

* Anyone can post a question with an encrypted answer.
* This question comes paired with a bounty of coins.
* Anyone can post an answer to this question. If the answer is correct, that person receives the bounty of coins.

Something to note here is that when dealing with a public network with latency, it is possible that something like a [man-in-the-middle attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) could take place. Instead of pretending to be one of the parties, an attacker would take the sensitive information from one party and use it for their own benefit. This scenario is actually called [Front Running](https://en.wikipedia.org/wiki/Front_running) and happens as follows:
## Safe interactions

On a public network with latency, it is possible that something like a [man-in-the-middle attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) could take place. Instead of pretending to be one of the parties, an attacker takes the sensitive information from one party and uses it for their own benefit. This scenario is called [Front Running](https://en.wikipedia.org/wiki/Front_running) and happens as follows:

1. You post the answer to some question with a bounty attached to it.
2. Someone else sees you posting the answer and posts it themselves right before you.
3. Since they posted the answer first, they receive the reward instead of you.

To prevent Front-Running, you will implement a **commit-reveal** scheme. A commit-reveal scheme converts a single exploitable interaction and turns it into two safe interactions.
### Prevent front running

To prevent front running, implement a commit-reveal scheme that converts a single exploitable interaction into two safe interactions.

The first interaction is the commit where you "commit" to posting an answer in a follow-up interaction. This commit consists of a cryptographic hash of your name combined with the answer that you think is correct. The app saves that value as a claim that you know the answer, but hasn't yet confirmed whether the answer is correct.

**The first interaction is the commit**. This is where you "commit" to posting an answer in a follow-up interaction. This commit consists of a cryptographic hash of your name combined with the answer that you think is correct. The app saves that value which is a claim that you know the answer but that it hasn't been confirmed whether the answer is correct.
The second interaction is the reveal where you post the answer in plain text along with your name. The application takes your answer and your name and cryptographically hashes them. If the result matches what you previously submitted during the commit stage, that is the proof that it is in fact you who knows the answer and not someone who is just front-running you.

**The next interaction is the reveal**. This is where you post the answer in plaintext along with your name. The application will take your answer and your name and cryptographically hash them. If the result matches what you previously submitted during the commit stage, then it will be proof that it is in fact you who knows the answer, and not someone who is just front-running you.
### Security

A system like this could be used in tandem with any kind of gaming platform in a **trustless** way. Imagine you were playing "The Legend of Zelda" and the game was compiled with all the answers to different scavenger hunts already included. When you beat a level the game could reveal the secret answer. Then either explicitly or behind the scenes, this answer could be combined with your name, hashed, submitted and subsequently revealed. Your name would be rewarded and you would have more points in the game.
A system like this commit-reveal scheme could be used in tandem with any kind of gaming platform in a **trustless** way. Imagine playing "The Legend of Zelda" and the game was compiled with all the answers to different scavenger hunts already included. When you obtain a certain level the game could reveal the secret answer. Then explicitly or behind the scenes, this answer could be combined with your name, hashed, submitted, and subsequently revealed. Your name could be rewarded so that you gain more points in the game.

Another way of achieving this level of security would be to have an Access Control List where there was an admin account that the video game company controlled. This admin account could confirm that you beat the level and then give you points. The problem with this is that it creates a ***single point of failure*** and a single target for trying to attack the system. If there is one key that rules the castle then the whole system is broken if that key is compromised. It also creates a problem with coordination if that Admin account has to be online all the time in order for players to get their points. If you use a commit reveal system then you have a more trustless architecture where you don't need permission to play. This design decision has benefits and drawbacks, but paired with a careful implementation it can allow your game to scale without a single bottle neck or point of failure.
Another way of achieving this level of security is with access-control list (ACL) managed by an admin account under control of the gaming company. This admin account could confirm that you beat the level and then give you points. The problem with this ACL approach is a ***single point of failure*** and a single target for trying to attack the system. If there is one key that rules the castle then the whole system is broken if that key is compromised. ACL security also creates a problem with coordination if that admin account is required to be online in order for players to get their points. With a commit-reveal system you have a more trustless architecture where permission is not required to play. The commit-reveal design decision has benefits and drawbacks, but when paired with a careful implementation your game can scale without a single bottleneck or point of failure.

Now that you know what you are building you can get started.
Now that you know what you are building, you can get started building your game.
27 changes: 21 additions & 6 deletions docs/guide/scavenge/03-scaffolding.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
order: 3
---

# Scaffolding
# Scaffold the scavenge chain

Scaffold a new Cosmos SDK blockchain using the `starport scaffold chain` command.

Expand All @@ -12,22 +12,37 @@ By default a chain is scaffolded with a new empty Cosmos SDK module. Use the `--
starport scaffold chain github.com/cosmonaut/scavenge --no-module
```

This command created a new directory `scavenge` with a brand new Cosmos SDK blockchain. This blockchain doesn't have any application-specific logic yet, but it imports standard Cosmos SDK modules, such as `auth`, `bank`, `mint` and others.
This command creates a new `scavenge` directory with a brand new Cosmos SDK blockchain. This blockchain doesn't have any application-specific logic yet, but it imports standard Cosmos SDK modules, such as `auth`, `bank`, `mint`, and others.

Change the current directory to `scavenge`:

```bash
cd scavenge
```

Inside the project directory you can execute other Starport commands to start a blockchain node, scaffold modules, messages, types, generate code, and much more.
Inside the project directory, you execute other Starport commands to start a blockchain node, scaffold modules, messages, types, generate code, and much more.

In a Cosmos SDK blockchain, application-specific logic is implemented in separate modules. Using modules keeps code easy to understand and reuse.
In a Cosmos SDK blockchain, implement application-specific logic in separate modules. Using modules keeps code easy to understand and reuse.

Scaffold a new module called `scavenge`. Based on our design the `scavenge` module will be sending tokens between participants. Sending tokens is implemented in the standard `bank` module. Specify `bank` as a dependency using the optional `--dep` flag.
## Scaffold the scavenge module

Scaffold a new module called `scavenge`. Based on the game design, the `scavenge` module sends tokens between participants.

- Implement sending tokens in the standard `bank` module.
- Use the optional `--dep` flag to specify the `bank` module.

```bash
starport scaffold module scavenge --dep bank
```

A module has been created in the `x/scavenge` directory and imported into the blockchain in `app/app.go`.
This command creates the `x/scavenge` directory and imports the scavenge module into the blockchain in the `app/app.go` directory.

## Save changes

Before you go to the next step, you can store your project in a git commit:

```bash
git add .
git commit -m "scaffold scavenge chain and module"
```

150 changes: 123 additions & 27 deletions docs/guide/scavenge/04-messages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,65 +4,161 @@ order: 4

# Messages

Messages are a great place to start when building a module because they define the actions that your application can make. Think of all the scenarios where a user would be able to update the state of the application in any way. These should be boiled down into basic interactions, similar to **CRUD** (Create, Read, Update, Delete).
Messages are a great place to start when building a module because messages define your application actions. Think of all the scenarios where a user would be able to update the state of the application in any way. These scenarios are the basic interactions, similar to CRUD (create, read, update, and delete) operations. Messages are objects whose end-goal is to trigger state-transitions.

The Scavenge module will have 3 messages:
For the scavenger hunt game, the scavenge module requires 3 messages:

* Submit scavenge
* Commit solution
* Reveal solution

## Submit Scavenge Message
## Submit scavenge message

Submit scavenge message should contain all the necessary information when creating a scavenge:
The submit scavenge message must contain all the information that is required to create a scavenge:

* Description - what is the question to be solved or description of the challenge.
* Description - the question to be solved or description of the challenge.
* Solution hash - the scrambled solution.
* Reward - this is the bounty that is awarded to whoever submits the answer first.
* Reward - the bounty that is awarded to whoever submits the answer first.

Use the `starport scaffold message` command to scaffold a new Cosmos SDK message for your module. The command accepts message name as the first argument and a list of fields. By default, a message is scaffolded in a module with a name that matches the name of the project, in our case `scavenge` (this behaviour can be overwritten by using a flag).
Use the `starport scaffold message` command to scaffold a new Cosmos SDK message for your module. The command accepts the message name as the first argument and a list of fields. By default, a message is scaffolded in a module with a name that matches the name of the project, in our case `scavenge`. You can use a flag to overwrite this default naming behavior.

```bash
starport scaffold message submit-scavenge solutionHash description reward
```

The command has created and modified several files.
The command creates and modifies several files:

* `proto/scavenge/tx.proto`: `MsgSubmitScavenge` and `MsgSubmitScavengeResponse` proto messages are added and a `SubmitScavenge` RPC is registered in the `Msg` service.
* `x/scavenge/types/message_submit_scavenge.go`: methods are defined to satisfy `Msg` interface.
* `x/scavenge/handler.go`: `MsgSubmitScavenge` message is registered in the module message handler.
* `x/scavenge/keeper/msg_server_submit_scavenge.go`: `SubmitScavenge` keeper method is defined
* `x/scavenge/client/cli/tx_submit_scavenge.go`: CLI command added to brodcast a transaction with a message.
* `x/scavenge/client/cli/tx.go`: CLI command is registered.
* `x/scavenge/types/codec.go`: codecs are registered.
```bash
modify app/app.go
create proto/scavenge/genesis.proto
create proto/scavenge/params.proto
create proto/scavenge/query.proto
create proto/scavenge/tx.proto
create testutil/keeper/scavenge.go
create x/scavenge/client/cli/query.go
create x/scavenge/client/cli/query_params.go
create x/scavenge/client/cli/tx.go
create x/scavenge/genesis.go
create x/scavenge/genesis_test.go
create x/scavenge/handler.go
create x/scavenge/keeper/grpc_query.go
create x/scavenge/keeper/grpc_query_params.go
create x/scavenge/keeper/grpc_query_params_test.go
create x/scavenge/keeper/keeper.go
create x/scavenge/keeper/msg_server.go
create x/scavenge/keeper/msg_server_test.go
create x/scavenge/keeper/params.go
create x/scavenge/keeper/params_test.go
create x/scavenge/module.go
create x/scavenge/module_simulation.go
create x/scavenge/simulation/simap.go
create x/scavenge/types/codec.go
create x/scavenge/types/errors.go
create x/scavenge/types/expected_keepers.go
create x/scavenge/types/genesis.go
create x/scavenge/types/genesis_test.go
create x/scavenge/types/keys.go
create x/scavenge/types/params.go
create x/scavenge/types/types.go

🎉 Module created scavenge.
```

In `x/scavenge/types/message_submit_scavenge.go` you can notice that the message follows the `sdk.Msg` interface. The message `struct` contains all the necessary information when creating a new scavenge: `Description`, `SolutionHash`, `Reward`, and `Creator` (which was added automatically).
The `scaffold message` command does all of these code updates for you:

The `Msg` interface requires some other methods be set, like validating the content of the `struct`, and confirming the msg was signed and submitted by the Creator.
* `proto/scavenge/tx.proto`

Now that one can submit a scavenge the only other essential action is to be able to solve it. This should be broken into two separate actions as described before: `MsgCommitSolution` and `MsgRevealSolution`.
* Adds `MsgSubmitScavenge` and `MsgSubmitScavengeResponse` proto messages
* Registers a `SubmitScavenge` RPC in the `Msg` service

## Commit Solution Message
* `x/scavenge/types/message_submit_scavenge.go`

Commit solution message needs to contain the following fields:
* Defines methods to satisfy `Msg` interface

* Solution hash - the scrambled solution.
* Solution scavenger hash - this is the hash of the combination of the solution and the person who solved it.
* `x/scavenge/handler.go`

* Registers the `MsgSubmitScavenge` message in the module message handler

* `x/scavenge/keeper/msg_server_submit_scavenge.go`

* Defines the `SubmitScavenge` keeper method

* `x/scavenge/client/cli/tx_submit_scavenge.go`

* Adds CLI command to broadcast a transaction with a message

* `x/scavenge/client/cli/tx.go`

* Registers the CLI command

* `x/scavenge/types/codec.go`

* Registers the codecs

In `x/scavenge/types/message_submit_scavenge.go`, you can notice that the message follows the `sdk.Msg` interface. The message `struct` automatically contains the information required to create a new scavenge:

```go
func NewMsgSubmitScavenge(creator string, solutionHash string, description string, reward string) *MsgSubmitScavenge {
return &MsgSubmitScavenge{
Creator: creator,
SolutionHash: solutionHash,
Description: description,
Reward: reward,
}
```
The `Msg` interface requires some other methods be set, like validating the content of the `struct` and confirming the message was signed and submitted by the creator.
Now that a user can submit a scavenge, the only other essential action is to be able to solve the scavenge. As described earlier to prevent front running, use two separate actions, `MsgCommitSolution` and `MsgRevealSolution`.
## Commit solution message
The commit solution message requires the following fields:
* Solution hash - the scrambled solution
* Solution scavenger hash - the hash of the combination of the solution and the person who solved it
```bash
starport scaffold message commit-solution solutionHash solutionScavengerHash
```
As you're using the same `starport scaffold message` command the set of modified and created files are the same.
Because you're using the same `starport scaffold message` command, the set of modified and created files is the same:
```bash
modify proto/scavenge/tx.proto
modify x/scavenge/client/cli/tx.go
create x/scavenge/client/cli/tx_commit_solution.go
modify x/scavenge/handler.go
create x/scavenge/keeper/msg_server_commit_solution.go
modify x/scavenge/module_simulation.go
create x/scavenge/simulation/commit_solution.go
modify x/scavenge/types/codec.go
create x/scavenge/types/message_commit_solution.go
create x/scavenge/types/message_commit_solution_test.go

🎉 Created a message `commit-solution`.
```
## Reveal Solution Message
## Reveal solution message
Reveal solution message needs only one field:
The reveal solution message requires only one field:
* Solution - this is the plain text version of the solution.
* Solution - the plain text version of the solution
```bash
starport scaffold message reveal-solution solution
```
Information about the scavenger (creator of the message is automatically included) and solution hash can be deterministically derived from the solution string.
Again, because you're using the same `starport scaffold message` command, the set of modified and created files is the same for the `reveal-solution` message.
Information about the scavenger (the creator of the message is automatically included) and the solution hash can be deterministically derived from the solution string.
## Save changes
Now is a good time to store your project in a git commit:
```bash
git add .
git commit -m "add scavenge messages"
```
Loading

0 comments on commit 3f4eccf

Please sign in to comment.