Overview

Overview of the Tournament Builder system for Forge Digital Ventures

The Tournament Builder is a premium feature developed for Forge Digital Ventures. If you would like to enable this functionality with your Anvil API access, please contact the Anvil support team.

Overview

The Tournament Builder is a Cardano-based solution for running transparent, on-chain tournaments. It supports customizable brackets, entry fees, and payout structures, with tournament records stored as verifiable NFTs. On-chain actions like registration and prize distribution are automated by smart contracts, while gameplay and rules remain flexible and off-chain—managed by organizers. This ensures both transparency and ease of integration.

For a better understanding of the Anvil API transaction flow, please refer to the Transaction Overview documentation. In particular, you need to have an understanding of the transaction submission process. Every transaction generated by the tournament builder must be signed and submitted through the Anvil API.

Smart Contract & API Architecture

Key Concepts:

1. Simple, Consistent API Endpoints

   • All tournament actions—creating tournaments, registering participants, adding players, and submitting transactions—are exposed as clear, RESTful API endpoints.

   • Endpoints are designed for ease of use:

     Tournament Management

     • POST /tournaments — Create a new tournament

     • GET /tournaments — List all tournaments

     • GET /tournaments/{id} — Get tournament info

     • POST /tournaments/{id}/participants — Add participants to a tournament

     • PATCH /tournaments/{id}/settle — Settle tournament and distribute prizes

     Registration Management

     • POST /tournaments/{id}/register — Register as a participant

     • GET /tournaments/{id}/registrations — List all registrations for a tournament

     • POST /tournaments/{id}/unregister — Cancel a registration

     Transaction Submission

     • POST /tournaments/submit-tx — Submit signed transactions for all tournament operations

2. Dual Validator (Plutus Script) Architecture

   • Tournament Validator:

     • Handles tournament creation, participant management, and payout logic.

     • Mints a unique NFT (CIP-25) for each tournament, which acts as its on-chain identity.

   • Registration Validator:

     • Manages individual registrations, ensuring only valid participants are added.

3. NFT-Based Tournament Representation

   • Each tournament is a unique NFT, minted at creation.

   • Tournament configuration and state are stored in the datum of the NFT’s UTXO.

   • NFTs use the CIP-25 metadata standard for broad wallet and ecosystem compatibility.

4. EUTXO Transaction Model

   • All actions are UTXO-based: tournament and registration records are UTXOs managed by validators.

   • Transactions are deterministic and can be validated off-chain before submission, reducing surprises and increasing reliability.

5. Transparent Fee Management

   • Entry fees, protocol fees, and per-participant fees are all handled on-chain by the smart contract.

   • Refunds and payouts are enforced by validator logic, ensuring fairness.

Why This Approach?

• Simplicity: The API hides blockchain complexity. Developers interact with intuitive endpoints and clear request/response formats.

• Security & Transparency: All critical actions are enforced by on-chain logic and are fully auditable.

• Flexibility: Organizers retain control over tournament rules and flow, while the contract guarantees fair registration and prize handling.

Documentation Resources

Before diving into the API, we recommend reviewing the integration flow and fee structure documentation to understand the complete tournament process.

Core Documentation

Integration FlowFee Structure

API Reference

TournamentRegistration