Tournament Builder

Tournament Registration Management#

Creating Registration Records#

Endpoint: POST /tournaments/{tournamentId}/register

Allows participants to register for a specific tournament. This only creates a registration record and does not yet add the participant to the tournament.

Request Parameters:

• utxos (string[], min 1): Array of UTXO strings to use for the transaction
• registererAddress (string): Address of the registering participant, used for prize payouts
• changeAddress (string, optional): Address to receive change UTXOs (defaults to registererAddress)
• tournamentId (string): Tournament identifier
• contractVersion (string, optional): Contract version for custom deployments
• contractTitle (string, optional): Contract title for custom deployments

Response:

• complete: Hex-encoded transaction for signing

Technical Notes:

• Creates an output at the parameterized registration script address
• The output must contain the required entry fee
• The registration datum stores the participant's address
• This address will be used for prize payouts.
• After registration, participants must wait for tournament admin to add them

Example (Node.js with fetch):

async function createRegistration(tournamentId) {
  const apiUrl = `https://preprod.api.ada-anvil.app/v2/services/tournaments/${tournamentId}/register`;
  
  const requestData = {
    utxos: ["8282...", "8282...", "8282..."], // UTXOs must contain enough funds to cover the entry fee
    registererAddress: "addr_test1...", // Tournament participant address
    changeAddress: "addr_test1...", // Optional, defaults to registererAddress
    tournamentId: tournamentId,
  };
  
  const response = await fetch(apiUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestData),
  });
  
  const data = await response.json();
  console.log('Registration transaction:', data.complete);
  
  // The returned transaction must be signed and submitted (see Transaction Overview: ../guides/transaction/README.md)
  return data.complete;
}

Cancelling a Registration#

Endpoint: POST /tournaments/{tournamentId}/unregister

Allows participants to cancel their registration and recover their entry fee.

Request Parameters:

• utxos (string[], min 1): Array of UTXO strings to use for the transaction
• registererAddress (string): Address of the registered participant
• changeAddress (string, optional): Address to receive change UTXOs (defaults to registererAddress)
• tournamentId (string): Tournament identifier
• outputRef (string): Reference to the registration UTXO in format txHash#index
• contractTitle (string, optional): Contract title for custom deployments
• contractVersion (string, optional): Contract version for custom deployments

Response:

• complete: Hex-encoded transaction for signing

Technical Notes:

• Only the original registrant can cancel their registration
• The "Cancel" redeemer is used to validate the transaction
• The registration UTXO (including the entry fee) is returned to the participant
• This provides a full refund of the entry fee to the canceling participant
• Cancellation is only possible before the administrator has added the participant to the tournament

Example (Node.js with fetch):

async function cancelRegistration(tournamentId, outputRef) {
  const apiUrl = `https://preprod.api.ada-anvil.app/v2/services/tournaments/${tournamentId}/unregister`;
  
  const requestData = {
    registererAddress: "addr_test1...",
    tournamentId: tournamentId,
    outputRef: outputRef,
    changeAddress: "addr_test1...", // Optional, defaults to registererAddress
    utxos: ["8282...", "8282...", "8282..."]
  };
  
  const response = await fetch(apiUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestData),
  });
  
  const data = await response.json();
  console.log('Cancellation transaction:', data.complete);
  
  // The returned transaction must be signed and submitted (see Transaction Overview: ../guides/transaction/README.md)
  return data.complete;
}

Retrieving Registrations#

Endpoint: GET /tournaments/{tournamentId}/registrations

Retrieves a list of all registrations for a specific tournament.

Request Parameters:

• tournamentId (string): Tournament identifier
• valid (boolean, optional): Filter to only valid or invalid registrations
• limit (number, optional): Max number of results to return (1-100, default: 100)
• page (number, optional): Page number for pagination
• cursor (number, optional): Alias for page, enables TRPC infinite queries
• contractTitle (string, optional): Contract title for custom deployments
• contractVersion (string, optional): Contract version for custom deployments

Response:

• entryFeeLovelace (string): The required entry fee amount in lovelace
• results: Array of registration objects, each containing:
  • address (string): Registrant address
  • outputRef (string): Registration UTXO reference
  • valid (boolean): Whether the registration has sufficient funds
  • paidFeesLovelace (string): Amount of fees paid in lovelace

Technical Notes:

• Results can be filtered by validity (sufficient funds)
• Results are paginated with a default limit of 100 registrations
• Output refs uniquely identify each registration UTXO on the blockchain

Example (Node.js with fetch):

async function getRegistrations(tournamentId, validOnly = true) {
  const apiUrl = `https://preprod.api.ada-anvil.app/v2/services/tournaments/${tournamentId}/registrations?valid=${validOnly}&limit=50`;
  
  const response = await fetch(apiUrl, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    }
  });
  
  const data = await response.json();
  console.log(`Required entry fee: ${data.entryFeeLovelace} lovelace`);
  console.log(`Found ${data.results.length} registrations`);
  
  return data;
}

Technical Notes:

• Returns both valid and invalid registrations (can be filtered with the valid parameter)
• Invalid registrations may not have paid the correct entry fee

Example (Node.js with fetch):

async function getRegistrations(tournamentId, validOnly = false) {
  const apiUrl = `https://preprod.api.ada-anvil.app/v2/services/tournaments/${tournamentId}/registrations${validOnly ? '?valid=true' : ''}`;
  
  const response = await fetch(apiUrl, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    },
  });
  
  const data = await response.json();
  console.log('Required entry fee (lovelace):', data.entryFeeLovelace);
  console.log('Registrations:', data.results);
  
  return data;
}