SHiNE-server/SHiNE-promo-solana-devnet/README.md

SHiNE-promo-solana-devnet

Временное промо-приложение для тестеров Web3-социальной сети SHiNE / «Сияние» в Solana Devnet.

Основной сценарий:

• приложение SHiNE открывает страницу вида /?wallet=SOLANA_PUBLIC_KEY;
• пользователь вводит имя и промокод;
• backend проверяет промокод и отправляет реальную devnet-транзакцию на 0.1 SOL;
• использованный промокод фиксируется в файле и больше не может быть применён.

Стек

• Java 21
• Spring Boot
• Gradle
• Thymeleaf + HTML/CSS/JS (server-side UI)

Локальный запуск

1. Скопируйте пример настроек:

cp config/application.example.properties src/main/resources/application.properties

2. Положите реальный keypair-файл Solana CLI формата в:

config/devnet-wallet.json

3. Запустите:

./gradlew bootRun

Приложение будет доступно на http://localhost:8021.

Как указать порт

По умолчанию используется:

server.port=8021

Изменить можно:

• в src/main/resources/application.properties;
• или через параметр запуска:

./gradlew bootRun --args='--server.port=8090'

Настройка Solana RPC Devnet

Параметр:

solana.rpc.url=https://api.devnet.solana.com

Для другого RPC достаточно заменить URL в properties.

Настройка devnet keypair

• Файл должен быть в формате Solana keypair JSON: массив из 64 чисел (0..255).
• Пример лежит в config/devnet-wallet.example.json.
• Рабочий файл: config/devnet-wallet.json.

Важно: настоящий keypair нельзя коммитить в GitHub.
Он добавлен в .gitignore.

Где лежат промокоды

Файл:

data/promo-codes.txt

Где лежит файл использованных промокодов

Файл:

data/promo-used.txt

Формат promo-codes.txt

• одна строка = один промокод;
• пустые строки игнорируются;
• строки с # игнорируются как комментарии;
• промокод должен соответствовать regex: [a-z0-9]{8}.

Формат promo-used.txt

Каждая запись в формате:

promoCode | wallet | name | yyyy.MM.dd HH:mm | signature

Пример:

aidar2km | 8xF...abc | Иван Петров | 2026.04.27 18:45 | 5xTxSignature...

Пример URL

http://localhost:8021/?wallet=8zYQ...DevnetAddress

Пример API-запроса

curl -X POST http://localhost:8021/api/promo/top-up \
  -H "Content-Type: application/json" \
  -d '{
    "wallet":"SOLANA_PUBLIC_KEY",
    "name":"Иван Петров",
    "promoCode":"aidar2km"
  }'

Проверка транзакции в Solana Explorer Devnet

Explorer URL формируется по шаблону:

https://explorer.solana.com/tx/{signature}?cluster=devnet

Сборка jar через Gradle

./gradlew clean build

JAR:

build/libs/SHiNE-promo-solana-devnet.jar

Запуск jar

java -jar build/libs/SHiNE-promo-solana-devnet.jar

Health endpoint

GET /health

Ответ:

{
  "status": "ok",
  "app": "SHiNE-promo-solana-devnet"
}

Логи

• логируется старт приложения;
• логируются успешные пополнения;
• логируются ошибки транзакций;
• приватный ключ не логируется.

Gradle-задачи для серверного деплоя

В build.gradle добавлены задачи:

• buildServerBundle — готовит bundle в build/server-bundle;
• deployToServer — копирует JAR и application.properties на сервер и перезапускает systemd-сервис.

Запуск:

./gradlew deployToServer

Переопределение хоста/пути:

./gradlew deployToServer \
  -PdeployHost=user@10.147.20.7 \
  -PdeployPath=/home/user/docker/SHiNE-promo-solana-devnet \
  -PdeployService=SHiNE-promo-solana-devnet