Integration Flow

Step-by-step guide for integrating with the Tournament Builder for Forge Digital Ventures

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

Step-by-Step Process

1. Prepare Tournament Configuration

   • Define bracket size, entry fees, and payout structure

   • Identify administrator address

   • Gather UTXOs for transaction fees

2. Create Tournament Transaction

   • Call the /tournaments endpoint with configuration

   • Receive transaction hex in response

3. 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.

Example API Flow

// 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:

1. Participants self-register (creating registration UTXOs)

2. Tournament administrator collects these registrations and officially adds participants

Phase 1: Participants Register

1. Participant Initiates Registration

   • Call POST /tournaments/{id}/register with participant address

   • Include UTXOs covering entry fee

   • Submit resulting transaction

   • This creates a registration UTXO at the registration script address

2. Verification

   • Query GET /tournaments/{id}/registrations to confirm registration

   • Validate status and fee payment

   • Participants must monitor their registration status

3. Optional: Registration Cancellation

   • If needed, participants can cancel their registration before being added to the tournament

   • Call POST /tournaments/{id}/unregister`

   • 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

1. Collect Registration Outputs

   • Tournament administrator gathers valid registration output references

   • Uses GET /tournaments/{id}/registrations to find valid registrations

2. Add Participants to Tournament

   • Administrator calls POST /tournaments/{id}/participants with 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

Phase 3: Tournament Settlement

1. Finalize Participant List

   • Administrator reviews and confirms all participants

2. Conduct Tournament

   • Actual competition happens off-chain

   • Results are determined through competition

3. Submit Results

   • Tournament administrator submits final standings using the PATCH /tournaments/{id}/settle endpoint

   • 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