MyTonWallet Giveaways [En]

Technical Specifications for Developing a Cryptocurrency Giveaway System in MyTonWallet

Task Description

Develop a system for organizing and conducting cryptocurrency giveaways (TON and jettons) for MyTonWallet users.

Authorized partners (using a secret token) will have the capability to create giveaways, replenish their balances, and invite other users to participate by sharing a deeplink formatted as https://my.tt/g/{GIVEAWAY_ID}.

The link will open MyTonWallet via a universal link mechanism and start the participant's authorization process. Upon successful authorization, the participant can claim their reward.

There are two types of giveaways:

• instant – participants receive rewards immediately upon following the link,
• lottery – the giveaway has a set duration and a predetermined number of winners, who are randomly selected from all participants at the end of the giveaway period.

Giveaways may optionally include a task. In such cases, issuing payment requires confirmation of task completion via a callback from an external service.

The project includes the development of three components:

• server application for managing giveaways,
• dapp for authorizing participants in giveaways,
• (optional) Telegram bot to simplify giveaway management.

System Components

1. Main Server Application

Description

The main application should operate on a server, interact with a database to store information about the giveaways and participants, and manage the TON wallet to check the balance replenishment by the creator and make payments to participants.

Tech stack

Node.js, TypeScript, Sequelize, Postgres.

Functionality

• Creating a giveaway. POST request with giveaway data.

POST /giveaways { giveaway: NewGiveaway; secret: %SECRET% }
  => 200 SuccessResponse | 400 ErrorResponse

type NewGiveaway = {
  type: 'instant' | 'lottery';
  endsAt?: Date; // Required for 'lottery'
  tokenAddress?: string; // Leave blank for Toncoin
  amount: number; // For each receiver
  receiverCount: number;
  taskUrl?: string;
}

type SuccessResponse = {
  giveawayLink: string; // Ex.: https://my.tt/g/{GIVEAWAY_ID}
  topUpLink: string; // Ex.: ton://transfer/{MAIN_ADDRESS}?token={TOKEN_ADDRESS}&amount={amount * participantCount}&comment={GIVEAWAY_ID}
  taskToken?: string;
}

type ErrorResponse = {
  error: string;
}

• Monitoring replenishments. Every 5 seconds, it is necessary to check incoming transactions to the special wallet MAIN_ADDRESS and update the status of the giveaway after the balance is replenished.
• GET request to retrieve the status and other data of the giveaway.

GET /giveaways/{GIVEAWAY_ID}
  => 200 Giveaway | 404 ErrorResponse

type Giveaway = NewGiveaway & {
  status: 'pending' | 'active' | 'finished';
  participantCount: number;
}

• User authorization. Checks the captcha, verifies the signature with a public key, and creates an entry in the participants table with the value Participant.status = 'awaitingTask' | 'awaitingPayment'.

POST /giveaways/{GIVEAWAY_ID}/checkin {
  captchaToken: string;
  receiverAddress: string;
  publicKey: string;
  signedProof: string;
} 
  => 200 { ok: true, giveaway: Giveaway } | 400 ErrorResponse

model Participant {
  giveawayId: string;
  receiverAddress: string;
  status: 'awaitingTask' | 'awaitingPayment' | 'paid' | 'lost';
}

• Callback for tasks. POST request to receive confirmation of task completion from an external service. Updates Participant.status = 'awaitingPayment'.

POST /giveaways/{GIVEAWAY_ID}/complete-task {
  taskToken: string;
  receiverAddress: string;
} 
  => 200 { ok: true } | 400 ErrorResponse

• Payouts to winners. Every 5 seconds, it is necessary to check participants with the status Participant.status = 'awaitingPayment', make payments to their addresses, and update Participant.status = 'paid'. The MAIN_ADDRESS_MNEMONICS environment variable is used for signing transactions.
• Ending lotteries. Every 5 seconds, it is necessary to identify completed lotteries, randomly determine the winners, and update Participant.status = 'awaitingPayment' | 'lost'.

2. Checkin dapp

Description

An application for registering participants in giveaways, using captcha and signature through TON Connect with proof for authorization.

Technologies

JavaScript, HTML, CSS.

Functions

• Participant Authorization. Accepts a single query parameter ?giveawayId=.... Uses captcha and TON Connect for verification and registration of participants. See https://checkin.mytonwallet.org for a reference.
• Displaying Participation Status. Informs the user about their participation status and displays information about the giveaway.
• Task Management. If the giveaway involves completing a task, displays the task status and provides a link to complete it.

Debugging

• Deeplinks like https://my.tt/g/{GIVEAWAY_ID} are not yet supported in MyTonWallet. For debugging your dapp, you can manually open it by entering the address https://{YOUR_DAPP_URL}/?giveawayId={GIVEAWAY_ID} through the built-in browser in the Explore section.

3. Telegram Bot (optional)

Description

A Telegram bot that provides a more convenient interface to the server application for managing giveaways.

Technologies

Node.js, TypeScript, Telegraf.js/grammY.

Functions

• Creating Giveaways. Allows the giveaway creator to set its parameters through a dialog interaction. At the end, sends a message with information about the giveaway and a button (giveawayLink) to participate in the giveaway (such a message can then be easily forwarded to a public channel). Additionally sends a ton:// link for replenishing the giveaway balance and a taskToken for a callback after completing a task.
• Status Check. Allows checking the statuses of previously created giveaways by their ID through dialog interaction.