The Matryx Bounty System¶
The Matryx Bounty system enables and incentivizes decentralized scientific collaboration in the form of tournaments and submissions, where all users participating in a tournament receive credit for their contributions, and the tournament bounty is rightfully distributed among the chosen winners.
Tournament and Round States¶
Each tournament in Matryx is subdivided into rounds, which are indexed incrementally. In each round, tournament participants make submissions to the tournament, and at the end of each round one or multiple submissions are selected by the tournament owner to be the winners of the round. The round winners then receive the allocated round reward.
A tournament can be in one of five possible states: NotYetOpen
, OnHold
, Open
, Closed
, or Abandoned
.
If a tournament is NotYetOpen
, then its first round has not started yet.
If it is OnHold
, that means that the tournament has already started but the next upcoming round has yet to begin.
Open
tournaments are the ones that are currently active: submissions are being made or reviewed.
Closed
tournaments are no longer active; the tournament owner has decided to end the tournament, and all of the tournament’s bounty has been distributed among the various rounds’ winners.
Lastly, a tournament becomes Abandoned
if a round ends without receiving any submissions, or if the tournament owner fails to select winners before the end of the round’s review period.
You can check the state of a tournament at any time by calling
tournament.getState()
A round can be in one of seven possible states: NotYetOpen
, Unfunded
, Open
, InReview
, HasWinners
, Closed
, or Abandoned
.
Rounds that have not started yet are NotYetOpen
.
A round is Unfunded
if it has already started but the tournament owner has not added any MTX to its bounty yet.
Open
rounds are currently active; you can enter the round and make new submissions.
If a round is InReview
, you can no longer make any more submissions (you’re going to have to wait until the next round!).
This is the time when the tournament owner reviews all the submissions made to the round and selects the winners.
A round is Closed
after the InReview
period ends.
Lastly, a round becomes Abandoned
if it reaches the end of its Open
state without receiving any submissions.
You can check the state of any round at any time by calling
tournament.getRoundState(roundIndex)
Entering and Exiting Tournaments¶
To enter a tournament that you’d like to participate in, you can make the following call:
tournament.enter()
Whenever you enter a tournament, you will have to pay the tournament entry fee designated by the tournament creator, so you will need to first approve at least that many MTX tokens. To check what a tournament’s entry fee is before entering, you can call
tournament.getDetails()
You can choose to exit an ongoing tournament at any time with the following call:
tournament.exit()
When you exit the tournament, the entry fee that you paid when you first entered will be returned to you automatically.
Note
If you later decide to enter the tournament again, you will have to pay the tournament entry fee again before making any submissions.
If a tournament you are currently participating in happens to become Abandoned
, you can collect your share of the remaining tournament bounty, as well as your original entry fee, with the following call:
tournament.withdrawFromAbandoned()
Making your first Submission¶
To create a submission, you must first enter the tournament that you want to participate in by calling
tournament.enter()
You can then create a submission in two ways: You can create a new commit and submit it to the tournament, or you can submit one of your previous commits.
To create a new commit, you first need to claim the commit hash:
commit.claimCommit(commitHash)
Then, you can create the commit and submit it to a tournament using the following function:
commit.createSubmission(tournament, content, parentHash, isFork, salt, commitContent, value)
Where tournament
is the address of the tournament, content
is the Submission content,
and parentHash
, isFork
, salt
, commitContent
, and value
are the data that corresponds to the commit you are creating.
Alternatively, if you want to submit a commit that already exists, you can simply call:
tournament.createSubmission(content, commitHash)
Where content
is the content of your submission and commitHash
is the hash of your commit.
Checking Commit Balances¶
If a commit receives some amount of MTX, the appropriate amount will be allocated to the commit on the Matryx platform. To check the current allocated balance of any commit, you can call
commit.getCommitBalance(commitHash)
Collecting your Reward¶
When a commit in your line of work receives a reward from winning a tournament, you can withdraw your share of the reward by calling:
commit.withdrawAvailableReward(commitHash)
To check the reward that any user is entitled to for any particular commit, you can call
commit.getAvailableRewardForUser(userAddress)
After you withdraw your reward, your available reward for that particular commit goes down to 0.
The share of the reward that is allocated to each commit owner in a commit chain is proportional to the total value of the commits that they created. Therefore, when a commit wins a tournament, everyone who contributed a piece of work used by the winning commit receives compensation for their contributions.
Creating your own Tournament¶
To create a tournament, you can call the createTournament
function on the platform as follows:
platform.createTournament(tournamentDetails, roundDetails)
Where tournamentDetails
and roundDetails
are:
struct TournamentDetails
{
string content;
uint256 bounty;
uint256 entryFee;
}
struct RoundDetails
{
uint256 start;
uint256 duration;
uint256 review;
uint256 bounty;
}
These structs contain information about the tournament that you are about to create and the first round that will kick off when the tournament begins.
You can add more funds to the tournament bounty at any point, but you cannot remove funds from it after you make the createTournament
call, so choose your initial bounty wisely!
Similarly, you cannot remove funds from the share of the tournament bounty you assign to the first round, and you won’t be able to edit the round details after the round has started.
Be sure to enter a reasonable amount of time (in seconds) for the round’s start
time and duration
, as well as its review
period.
You’ll need some time to look over the submissions and choose your round winners before the review period ends!
Note
The tournament and round bounty will be visible to any users looking to enter your tournament, as well as the tournament and round details.
Updating Tournament Details¶
To edit the data of your tournament, you can call the updateDetails
function as follows:
tournament.updateDetails(tournamentDetails)
Where tournamentDetails
is the same data struct used to create the tournament originally.
The bounty
field, however, will not change when you try to modify the tournament’s data.
Adding to a Tournament Bounty¶
Suppose you wanted to add MTX to a tournament’s bounty. You can call the addToBounty
function as follows:
tournament.addToBounty(amount)
This function transfers MTX to the specified tournament. To allocate these new funds to the current round, you can call the transferToRound
function:
tournament.transferToRound(amount)
The added MTX will now also be distributed to this round’s winners when it is time to reward their submissions.
Warning
Remember that you cannot remove funds from a tournament’s bounty after you’ve added them or remove funds from a round after it has already started.
Choosing Tournament Winners¶
To get all the submissions made to a round, you can call
tournament.getRoundInfo(roundIndex)
Round info contains all the hashes of all the submissions made to the round. To view the contents of each submission, you can call
platform.getSubmission(submissionHash)
To choose your round winners, you can call selectWinners
on the tournament as follows:
tournament.selectWinners(winnersData, roundDetails)
Where winnersData
is:
struct WinnersData
{
bytes32[] submissions;
uint256[] distribution;
uint256 action;
}
Here, action
represents an enumerated value from the following enum:
enum SelectWinnerAction { DoNothing, StartNextRound, CloseTournament }
and RoundDetails
are:
struct RoundDetails
{
uint256 start;
uint256 duration;
uint256 review;
uint256 bounty;
}
In winnersData
, you can specify which submissions get rewarded and how much MTX is assigned to each one.
The first parameter contains all the winning submissions’ hashes, and the second contains the reward each one will get, respectively, expressed as a percentage or a proportion of the total round bounty.
When selecting round winners, you have three options for how to proceed with the tournament:
you can choose to wait until the end of the review period for the next round to start, to start the next round immediately after selecting the winners, or to close the tournament.
The action you choose (0, 1 or 2, representing SelectWinnerAction.DoNothing
, SelectWinnerAction.StartNextRound
and SelectWinnerAction.CloseTournament
, respectively)
is passed as the third parameter of winnersData
and indicates how you would like to proceed.
If you choose to wait until the end of the review period (DoNothing
), the next round will automatically be created as an identical copy of the last round, and it will begin once the current review period ends.
If you choose to start the next round immediately when you select the winners (StartNextRound
), the next round will be initialized with the round data that you provide and will begin immediately.
If you choose to close the Tournament (CloseTournament
), the remaining bounty unallocated to any round will be allocated to the current round and used to award winnersData.submissions
,
and the Tournament will end.
Warning
Once you close the tournament, you can’t open it up again. Any remaining funds that might still be in the tournament’s balance will be evenly distributed among the last round’s winners when you decide to close the tournament.
Warning
If the round’s review period ends and you still have not chosen any winners, the tournament will be considered Abandoned, and any remaining funds in the tournament’s balance will be uniformly allocated to all of the round’s participants for them to withdraw.