Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Amend suggestion #1

Open
wants to merge 2 commits into
base: DOCS-RR
Choose a base branch
from
Open

Amend suggestion #1

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dcbb620
amend suggestion for document
devan-ko Apr 16, 2024
83aa0db
add some explain for to achieve tranparency
devan-ko Apr 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 40 additions & 37 deletions docs/content/guides/developer/app-examples/reviews-rating.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@
title: Reviews Rating
---

The following documentation goes through an example implementation of a review rating platform for the food service industry on Sui.
Unlike traditional review rating platforms, that often do not disclose the algorithm used to rate reviews, the on-chain platform uses an algorithm that is published on-chain for everyone to see and verify.
The following documentation goes through an example implementation of a review rating platform for the services wanted to built more transparent post-service review dapp top on the Sui protocol.
This example shows to possbility unlike traditional review rating platforms which is not disclose the algorithm used to rate reviews, the on-chain platform uses an algorithm that is published on-chain for everyone to see and verify.
Furthermore, all submitted reviews are scored and ordered on-chain which is feasible due to the low gas cost of computation on Sui.

## Personas

There are four actors in the typical workflow of the reviews rating example.
There are four actors in the typical workflow of the reviews rating example.

```mermaid
sequenceDiagram
Expand Down Expand Up @@ -42,13 +42,14 @@ The incentive mechanism for moderators is not implemented for this guide, but se

## How reviews are rated

The reviews are rated (scored) on-chain using following criteria
The reviews are rated (scored) on-chain using following criteria in this app like below;

- Intrinsic score (IS)
- Length of content
- Length of review content
- Extrinsic score (ES)
- Number of votes received
- Number of votes a review received
- Verification multiplier (VM)
- Reviews with PoE get a multiplier to improve rating
- Reviews with PoE (Proof of Experience) socre get a multiplier to improve rating

```
Total Score = (IS + ES) * VM
Expand Down Expand Up @@ -115,8 +116,35 @@ struct Service has key, store {
```

#### Reward distribution
The same amount is rewarded to top reviewers, and the reward is distributed to 10 participants at most.
The pool of `SUI` tokens that will be distributed to reviewers is stored in `reward_pool` field, and the amount of `SUI` tokens that will be awarded to each participant is configured in `reward` field.
The same amount is rewarded to top reviewers, and the reward is distributed to Top 10 reviews at most.
`SUI` tokens acted as reward that will be distributed to reviewers is stored in `reward_pool` field, and the amount of `SUI` tokens that will be awarded to each participant is configured in `reward` field.

### review.move

`Review` struct defines on review.move.

In addition to the content of a review, all the elements that are required to compute total score are stored in a `Review` object.

And `Review` is a [shared object](../../../concepts/object-ownership/shared.mdx), so anyone can cast a vote on a review and update its `total_score` field.
After `total_score` is updated, the [`update_top_reviews`](#casting-votes) function can be called to update the `top_reviews` field of the `Service` object.

```move
struct Review has key, store {
id: UID,
owner: address,
service_id: ID,
content: String,
// intrinsic score
len: u64,
// extrinsic score
votes: u64,
time_issued: u64,
// proof of experience
has_poe: bool,
total_score: u64,
overall_rate: u8,
}
```

#### Storage for reviews
Since anyone can submit a review for a service, a `Service` should be defined as a shared object.
Expand All @@ -134,6 +162,9 @@ The elements of `top_reviews` are sorted by the `total_score` of the reviews, wi
the `ID` of the reviews (whose content and vote count can be looked up from the `reviews`).

#### Casting votes

Through the casting vote processes like below, we could watch how reviews will be rated on chain.

```move
public fun upvote(service: &mut Service, review_id: ID) {
let review = object_table::borrow_mut(&mut service.reviews, review_id);
Expand Down Expand Up @@ -205,34 +236,6 @@ struct Moderator has key {
This example follows a [capabilities pattern](../../../concepts/sui-move-concepts/patterns/capabilities.mdx) to manage authorizations.
For example, `SERVICE OWNERS` are given `AdminCap` and `MODERATORS` are given `Moderator` such that only they are allowed to perform privileged operations.


### review.move

This module defines the `Review` struct.

```move
struct Review has key, store {
id: UID,
owner: address,
service_id: ID,
content: String,
// intrinsic score
len: u64,
// extrinsic score
votes: u64,
time_issued: u64,
// proof of experience
has_poe: bool,
total_score: u64,
overall_rate: u8,
}
```

In addition to the content of a review, all the elements that are required to compute total score are stored in a `Review` object.

A `Review` is a [shared object](../../../concepts/object-ownership/shared.mdx), so anyone can cast a vote on a review and update its `total_score` field.
After `total_score` is updated, the [`update_top_reviews`](#casting-votes) function can be called to update the `top_reviews` field of the `Service` object.

## Deployment

Navigate to the [setup folder](https://github.com/MystenLabs/reviews-ratings-poc/tree/main/setup) of the repository and execute the `publish.sh` script. Refer to the [README instructions](https://github.com/MystenLabs/reviews-ratings-poc/blob/main/README.md) for deploying the smart contracts.
Expand Down
Loading