MyTonWallet Giveaways

Техническое задание на разработку системы раздач криптовалюты в MyTonWallet.

Описание задачи

Необходимо разработать систему для организации и проведения раздач (giveaways) криптовалюты (TON и jettons) пользователям кошелька MyTonWallet.

Авторизованные (с помощью secret-токена) партнёры смогут создавать раздачи, пополнять их баланс и приглашать других пользователей принять в них участие с помощью публикации ссылки вида https://my.tt/g/{GIVEAWAY_ID}.

Ссылка открывает MyTonWallet (через механизм universal link) и запускает процесс авторизации участника в раздаче. После прохождения авторизации участник может получить вознаграждение.

Существует два типа раздач:

• мгновенные (instant) — участники получают вознаграждения сразу после перехода по ссылке,
• розыгрыши (lottery) — раздача имеет срок действия и количество победителей, которые в момент окончания срока раздачи выбираются случайным образом среди всех участников.

Раздачи могут опционально содержать задание. В этом случае для выплаты необходимо подтверждение выполнения задания через обратный вызов от стороннего сервиса.

Проект включает в себя разработку трёх компонентов:

• серверное приложение для управления раздачами,
• dapp для авторизации участников в раздачах,
• (опционально) Telegram-бот для упрощения управления раздачами.

Компоненты системы

1. Основное серверное приложение

Описание

Основное приложение должно работать на сервере, взаимодействовать с базой данных для хранения информации о раздачах и участниках, а также управлять TON-кошельком для проверки пополнения баланса раздачи создателем и выплат участникам.

Технологии

Node.js, TypeScript, Sequelize, Postgres.

Ключевые функции

• Cоздание раздачи. POST-запрос с данными раздачи.

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;
}

• Мониторинг пополнений. Каждые 5 секунд необходимо проверять входящие транзакции на специальный кошелёк MAIN_ADDRESS и обновлять статус раздачи после пополнения баланса.
• GET-запрос для получения статуса и других данных раздачи.

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

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

• Авторизация пользователей. Проверяет captcha, подпись публичным ключом, и создаёт запись в таблице participants со значением 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';
}

• Обратные вызовы для заданий. POST-запрос для приема подтверждения выполнения задания от стороннего сервиса. Обновляет Participant.status = 'awaitingPayment'.

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

• Выплаты победителям. Каждые 5 секунд необходимо проверять участников со статусом Participant.status = 'awaitingPayment', производить выплаты на их адреса и обновлять Participant.status = 'paid'. Для подписи транзакций используется env-переменная MAIN_ADDRESS_MNEMONICS.
• Завершение розыгрышей. Каждые 5 секунд необходимо определять завершённые розыгрыши, случайным образом определять победителей и обновлять Participant.status = 'awaitingPayment' | 'lost'.

2. Checkin dapp

Описание

Приложение для регистрации участников в раздаче, использующее captcha и подпись с помощью TON Connect with proof для авторизации.

Технологии

JavaScript, HTML, CSS.

Функции

• Авторизация участников. Принимает единственный query-параметр ?giveawayId=.... Использует captcha и TON Connect для верификации и регистрации участников. См. https://checkin.mytonwallet.org для примера.
• Отображение статуса участия. Информирует пользователя о статусе его участия и выводит информацию о раздаче.
• Управление заданиями. Если раздача связана с выполнением задания, отображает статус задания и предоставляет ссылку для его выполнения.

Режим разработки

• Ссылки вида https://my.tt/g/{GIVEAWAY_ID} пока не поддерживаются в MyTonWallet. Для отладки вашего Checkin-приложения вы можете вручную открывать его, вводя адрес https://{YOUR_DAPP_URL}/?giveawayId={GIVEAWAY_ID} через встроенный браузер в разделе Обзор (Explore).

3. Telegram-бот (опционально)

Описание

Бот для Telegram, предоставляющий более удобный интерфейс к серверному приложению для управления раздачами.

Технологии

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

Функции

• Создание раздачи. Позволяет создателю раздачи задать её параметры через диалоговое взаимодействие. В конце присылает сообщение с информацией о раздаче и кнопкой (giveawayLink) для участия в раздаче (такое сообщение, например, удобно переслать в публичный канал). Дополнительно присылает ton://-ссылку для пополнения баланса раздачи и taskToken для обратного вызова после выполнения задания.
• Проверка статуса. Позволяет узнать статусы ранее созданных раздач по их ID через диалоговое взаимодействие.