Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Events is a free-form service that allows you to create an event that can be made up of any number of contests or objectives that an individual or group of individuals can participate in. These contests can have a single winner or you can apply rankings based on the performance of the individuals in the contest. Individuals in a contest can be grouped to form teams. In this scenario, an entire team can be declared as the winner.
Entry to an event can require a payment via any SPL-token (USDC, $RAIN, ...), NFT, SFT, or Raindrops artifact(Item, Player). Upon entry to the event, participants can be granted an NFT to signify as their ticket. Holders of the event's entry NFT can then join contests, which may be free, require a specific type of entry NFT, and/or require an additional payment.
Each event can have an "unlimited" amount of prize pools that can be made up of SPL-tokens, NFTs, SFTs, and/or Raindrops artifacts. These prize pools can be distributed to the winners of contests and/or the winners of the entire event.
The entirety of the event is played out on-chain. When the event is declared finalized and all rewards have been distributed, the event data will remain as the permanent history of the outcomes during the event.
Given the highly free-form nature of the events service, we are first providing it's functionality via the opinionated Tournaments service. The Tournaments service is meant to define the typical structure of a competitive series of match based contests. We will be providing more opinionated event services over the coming months. Two other opinionated service examples are Campaigns, and Scavenger Hunts.
Tournaments users will interact with the Tournaments API via HTTP, this allows flexibility for a variety of user types with the service, we will proxy your requests to the blockchain for you after signing.
We support a typescript HTTP client which will always be compatible with our Tournaments API, we suggest starting here to try things out. The client is designed to be usable from web applications and scripting.
Tournaments is built on top of a generic Events Program, please refer to the Events Reference Errors & State Pages for detail. On those pages, a Tournament is an Event and a Match is a Contest.
An EntryFee can be optionally set at Tournament creation, requires all participants entering the tournament to pay a fee upon entrance. There can only be one tournament entry fee at this time
Multiple Matches can be created within a Tournament, each Match can have an unlimited number of participants, winners of matches accrue Points.
A Participant is an entity which has entered a Tournament and is eligible to play matches
Points are accrued by winners of Matches within a Tournament. These points are used to keep track of which participants are eligible to move onto the next Tournament Round. Throughout the Tournament it's possible to query the point totals of all participating. Tournament Authorities can use these point totals to determine distribution of Tournament Rewards. In addition, if it's determined that one or multiple participants have cheated, their points can be revoked.
Rewards are used to incentivize participants to enter into Tournaments. There can be unlimited number of rewards and the Tournament Authority has complete control over the distribution of these Rewards after the Tournament has been moved to the Ended State. Optionally, the Tournament Entry Fee tokens can be used as a Tournament Reward.
A Round is a grouping of matches within a Tournament, each Round has a unique Round Index. The first round in a Tournament has a Round Index of 0, this means that any participant is eligible to play in the first round of matches (provided they have entered the Tournament of course!).
The winners of each match within a Round are awarded 1 point, this corresponds to the Round Index. For example, the Second Round in this Tournament has a Round Index of 1, which means participants who have been awarded 1 Point from playing in the previous round are eligible for these new Matches.
The farther along a participant makes it within a Tournament, the more points they accrue and the Tournament Authority can query these point totals to make a decision on Reward distribution.
When a Tournament is created it's possible to add a Token Gate, a Token Gate requires that a prospective participant has a particular mint and amount of said mint in their wallet upon joining. One use case of this might be a whitelist token, only allowing participants with the token to be eligible to play in the tournament.
A Tournament is a series of Matches in which participants compete for escrowed Rewards, the Tournament results are recorded on chain and when complete, are immutable and forever public.
This first script highlights tournaments setup taken by the Tournament Authority, the Authority has full control over configuration, point and reward distribution.
With the Tournament configured, participants can now enter the tournament
Once all participants have entered, it's time to start the tournament. When the tournament moves into the started state, no more participants can join.
Now that the tournament has started, it's time to create a tournament round. A round is simply a collection of matches in which participants face off against each other.
After the round of matches have been created, it's time to select which participants face each other in each match, this is completely up to the Tournament Authority
~Matches are now played off chain~
Once the matches finish, it's time to tell Tournaments who won!
At this point, a full round of a tournament has been played out off-chain and the results have been written on-chain. Repeat this flow until a tournament winner has been determined. For each round, increment the roundIndex
by 1.
Lets say the final tournament standings have been determined, it's time to wrap this up!
A comprehensive list of endpoints exposed by our Tournaments API
Each Endpoint has a GET and a POST operation, the GET will generate a prepared transaction for the endpoint, complete with signatures from newly created accounts and our API signer. Next, this transaction must be signed by the caller and send back in a POST body. We will validate the transaction received via HTTP POST and forward this along to the Solana network.
Transfer tokens collected by a Tournaments Entry Fee to the Reward Escrow, this enables the Entry Fee to be redistributed to tournament participants. This endpoint is only callable by a Tournament Authority.
Transfer tokens from the Tournament Authority to the Reward Escrow. It's important to specify the Reward Amount with the correct decimal precision. This endpoint is only callable by a Tournament Authority.
Example: 1 $USDC would be a reward amount of "100000", USDC has 6 decimals of precision.
Revoke all tournament points gained by a detected cheater in a tournament. This endpoint is only callable by a Tournament Authority.
Create a new round of matches within a Tournament. For each new round, increment the Round Index by 1, the API uses the Participants per Round to determine the number of matches to create for a round. This endpoint is only callable by a Tournament Authority.
Create a new Tournament, the creator mints a Tournament Authority token granting them full control over Tournament operations.
Specify a Name and a Tournament Size, optionally specify an Entry Fee and/or a Token Gate. The Name cannot be longer than 100 characters. The Size sets a limit on number of participants who can join, but this limit does not need to be reached to start the Tournament.
An Entry Fee requires a Mint and an Amount which each participant must pay to enter into your Tournament.
A Token Gate requires a Mint and an Amount which each participant must have in their Wallet to be eligible to enter into your Tournament.
Distribute the tokens stored in a Tournament Reward Escrow to a Tournament Participant
Update the state of a Match to Ended. This endpoint is only callable by a Tournament Authority.
Before a winner of a match can be determined, the Match must be in the Ended State.
Update the state of the Tournament to Ended. This endpoint is only callable by a Tournament Authority.
When a Tournament is moved to Ended, no more Matches or Rounds can be created. Cheaters can still be detected and banned at this stage, this is where rewards would be distributed to eligible participants.
Enter a Tournament Participant into a Match. This endpoint is only callable by a Tournament Authority.
The Tournament Authority is in control of which participants enter which Matches so that the Tournament Authority can control bracketing and matchmaking semantics.
A participant uses this endpoint to enter into a tournament of their choice. If the tournament has an Entry Fee or Token Gate configured, the participant must pay or have in their wallet the necessary tokens.
Finalize the results of a Tournament, all rewards have be distributed, cheaters banned and the results of the Tournament become immutable. This endpoint is only callable by a Tournament Authority.
Retrieve Match Details in JSON format
Retrieve all Matches of a particular Round in a tournament. Use the Round Index to select a particular round. Flip the finalized Boolean if you would like to selectively retrieve Matches which are finalized or not.
Retrieve all participants for a particular Match.
Retrieve all participants who are eligible for a particular Round, regardless if they have entered a Match in that Round or not.
Retrieve current Tournament Standings sorted descending from most points awarded. For each Match win a participant is awarded 1 Tournament Point.
Retrieve Tournament Details in JSON format
Determine a Winner of an Ended Match and move the Match into the Finalized State. This endpoint is only callable by a Tournament Authority.
The Winner will receive 1 Point in their points token account. Tournaments uses the points to determine which participants are eligible to play in subsequent tournament rounds and for participants and managers to keep track of Tournament state.
Currently only 1 winner can be selected but we will make this endpoint more flexible to support multiple winners in the future.
Move a Match within a Tournament into the Started State, this signifies that the Match is beginning to be played out on chain, no other participants may enter this Match. This endpoint is only callable by a Tournament Authority.
Move a Tournament into the Started State, no more participants may enter the tournament and now it's possible to begin creating Tournament Rounds. This endpoint is only callable by a Tournament Authority.
Tournaments is an Events service for creating and managing tournament events. You can use an HTTP client to interact with our API. Soon after the initial release of the API you will also be able to use a Web UI to create and run a tournament.
Unlimited matches and participants per tournament
Rewards escrow (aka Prize pool)
Entry fees can be used for rewards
Unlimited number of rewards can be held
Customizable reward distribution
Optionally enforce token gating for tournament entry
Optionally require entry fees to join a tournament
Ban tournament cheaters or revoke any of their rewards for cheating in a match
Data availability, it's simple to query the existing state of the tournament without having to store anything client side
Accounts and Data Structures
Errors are returned in hexadecimal format from the Solana Blockchain, convert to decimal then reference this page to determine the error. If the decimal returned is not a 6XXX number, then the error is a built-in error from the Solana blockchain, reference here to troubleshoot: https://docs.rs/anchor-lang/latest/anchor_lang/error/enum.ErrorCode.html