Tournament Builder
Tournament Builder Integration Workflow#
This guide outlines the step-by-step process for integrating with the Tournament Builder developed for Forge Digital Ventures. For technical details of the architecture, see the Overview document.
This workflow assumes you have already set up your development environment and have the necessary credentials to access the Anvil API.
1. Tournament Creation#
Prepare Tournament Configuration
- Define bracket size, entry fees, and payout structure
- Identify administrator address
- Gather UTXOs for transaction fees
Create Tournament Transaction
- Call the
/tournamentsendpoint with configuration - Receive transaction hex in response
- Call the
Sign and Submit Transaction
- Sign the transaction with appropriate keys
- Submit the signed transaction (see Transaction Overview for details)
When successful, the tournament is created and an NFT is minted to represent it on-chain. The tournament is now ready to accept registrations.
// 1. Configure tournament parameters
const tournamentConfig = {
name: "Tournament Name",
adminAddress: "addr1...",
bracketSize: 16,
entryFee: "10000000", // 10 ADA in lovelace
payoutStructure: ["7000000", "2000000", "1000000"],
utxos: ["1234...#0", "5678...#1"]
};
// 2. Create tournament transaction
const response = await fetch("/tournaments", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(tournamentConfig)
});
const { transaction } = await response.json();
// 3. Sign and submit transaction
// See Transaction Overview documentation for details: ../guides/transaction/README.md
const signedTx = await signTransaction(transaction);
const submitResponse = await fetch("/tournaments/submit-tx", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ transaction: signedTx })
});
const { txHash } = await submitResponse.json();
console.log("Tournament created with transaction:", txHash);2. Registration Management#
The Tournament Builder uses a two-phase registration process:
- Participants self-register (creating registration UTXOs)
- Tournament administrator collects these registrations and officially adds participants
Phase 1: Participants Register#
Participant Initiates Registration
- Call
POST /tournaments/{id}/registerwith participant address - Include UTXOs covering entry fee
- Submit resulting transaction
- This creates a registration UTXO at the registration script address
- Call
Verification
- Query
GET /tournaments/{id}/registrationsto confirm registration - Validate status and fee payment
- Participants must monitor their registration status
- Query
Optional: Registration Cancellation
- If needed, participants can cancel their registration before being added to the tournament
- Call [POST /tournaments/{id}/unregister`](./registration.md#cancel-registration)
- The registration UTXO with the full entry fee amount is returned to the participant
- This provides a complete refund mechanism for participants who change their mind
Phase 2: Tournament Administrator Adds Participants#
Collect Registration Outputs
- Tournament administrator gathers valid registration output references
- Uses
GET /tournaments/{id}/registrationsto find valid registrations
Add Participants to Tournament
- Administrator calls
POST /tournaments/{id}/participantswith registration list - Only the tournament admin can perform this action
- Administrator signs and submits transaction
- This transaction consumes the registration UTXOs and updates the tournament datum
- Participants are now officially part of the tournament
- Administrator calls
Phase 3: Tournament Settlement#
Finalize Participant List
- Administrator reviews and confirms all participants
Conduct Tournament
- Actual competition happens off-chain
- Results are determined through competition
Submit Results
- Tournament administrator submits final standings using the
PATCH /tournaments/{id}/settleendpoint - Smart contract distributes rewards according to payout structure defined at tournament creation
- Each prize recipient receives their prize as a transaction output with the tournament ID as datum
- For details on prize distribution and fees, see the Fee Structure document
- Tournament administrator submits final standings using the