SHA256
147 lines
5.9 KiB
Markdown
147 lines
5.9 KiB
Markdown
# Программа `shine_login_guard`
|
|
|
|
Документ описывает целевое поведение программы классификации логинов SHiNE.
|
|
|
|
Задача программы:
|
|
|
|
- по логину определить класс регистрации;
|
|
- вернуть результат в `return_data`;
|
|
- не хранить PDA и не вести собственное состояние.
|
|
|
|
## 1. Назначение
|
|
|
|
`shine_login_guard` — маленькая служебная программа, которую вызывает `shine_users` через CPI до регистрации пользователя.
|
|
|
|
Она отвечает только на вопрос:
|
|
|
|
- можно ли зарегистрировать логин автоматически;
|
|
- является ли логин premium;
|
|
- является ли логин trademark/company.
|
|
|
|
## 2. Program ID
|
|
|
|
Текущий program id:
|
|
|
|
- `3xkopA7cXagxzMFrKdv3NCBfV6BKiRJCk69kr27M2sRo`
|
|
|
|
## 3. Состояние
|
|
|
|
У программы нет PDA-состояний и persistent storage.
|
|
|
|
Она опирается на статически сгенерированные словари, встроенные в бинарник на этапе сборки.
|
|
|
|
## 4. Внешние артефакты
|
|
|
|
Словари хранятся в:
|
|
|
|
- `src/dictionaries/premium/**/*.txt`
|
|
- `src/dictionaries/trademarks/**/*.txt`
|
|
|
|
На этапе build:
|
|
|
|
- все `.txt` файлы рекурсивно собираются;
|
|
- слова нормализуются;
|
|
- дубль-слова детектятся и логируются как warning;
|
|
- итоговые массивы слов вшиваются в generated Rust file.
|
|
|
|
## 5. Нормализация словаря
|
|
|
|
Слово словаря считается валидным, если:
|
|
|
|
- не пустое;
|
|
- длина не больше `20`;
|
|
- содержит только ASCII-буквы и цифры;
|
|
- после `trim()` и `lowercase()` остаётся валидным.
|
|
|
|
Символ `_` в словарных словах не допускается.
|
|
|
|
## 6. Единственная инструкция
|
|
|
|
Инструкция:
|
|
|
|
- `classify_login(login: String)`
|
|
|
|
Бинарный ABI инструкции:
|
|
|
|
```text
|
|
- tag: u8 = 1
|
|
- login_len: u32 LE
|
|
- login_bytes[login_len]: UTF-8
|
|
```
|
|
|
|
Аккаунты:
|
|
|
|
- аккаунты не требуются
|
|
|
|
Подпись транзакции для самой классификации не имеет бизнес-смысла. Если вызов идёт через CPI из `shine_users`, программа `shine_login_guard` не требует signer-аккаунтов вообще.
|
|
|
|
## 7. Выходные классы
|
|
|
|
Программа возвращает `u32` через `set_return_data`:
|
|
|
|
- `0` — `CLASS_FREE`
|
|
- `1` — `CLASS_PREMIUM`
|
|
- `2` — `CLASS_TRADEMARK`
|
|
|
|
## 8. Правила нормализации логина
|
|
|
|
Перед классификацией логин нормализуется:
|
|
|
|
- пустой логин запрещён;
|
|
- длина исходного логина не больше `20`;
|
|
- символ `_` удаляется;
|
|
- остальные символы обязаны быть ASCII alnum;
|
|
- буквы приводятся к нижнему регистру.
|
|
|
|
Если нормализация не удалась:
|
|
|
|
- логин считается `CLASS_PREMIUM`.
|
|
|
|
Это намеренно жёсткое поведение: сомнительный логин не должен автоматически попадать в free-класс.
|
|
|
|
## 9. Правила классификации
|
|
|
|
Алгоритм:
|
|
|
|
1. Нормализовать логин.
|
|
2. Попробовать разрезать его на `1..3` слов из словарей.
|
|
3. Если среди найденных частей есть trademark-слово, вернуть `CLASS_TRADEMARK`.
|
|
4. Если есть только premium-слова, вернуть `CLASS_PREMIUM`.
|
|
5. Если словарное совпадение не найдено и длина нормализованного логина `<= 7`, вернуть `CLASS_PREMIUM`.
|
|
6. Иначе вернуть `CLASS_FREE`.
|
|
|
|
## 10. Разбиение на слова
|
|
|
|
Максимум слов в логине:
|
|
|
|
- `3`
|
|
|
|
Алгоритм разбиения:
|
|
|
|
- DFS/backtracking по префиксам строки;
|
|
- на каждом шаге берётся префикс длиной `1..20`;
|
|
- если префикс найден в premium или trademark словаре, поиск продолжается на остатке строки;
|
|
- если найден хотя бы один путь с trademark-словом, итог = `CLASS_TRADEMARK`;
|
|
- если найден путь только с premium-словами, итог = `CLASS_PREMIUM`.
|
|
|
|
## 11. Инварианты
|
|
|
|
Должно быть сохранено при переписи:
|
|
|
|
- тот же способ нормализации логина;
|
|
- та же семантика классов `0/1/2`;
|
|
- тот же лимит `MAX_WORDS_PER_LOGIN = 3`;
|
|
- тот же fallback `len <= 7 => premium`, если словарь ничего не нашёл;
|
|
- тот же порядок приоритета `TRADEMARK > PREMIUM > FREE`.
|
|
|
|
## 12. Что не обязано сохраниться при переписи
|
|
|
|
Можно менять без изменения бизнес-логики:
|
|
|
|
- build pipeline словарей;
|
|
- структуру хранения слов внутри бинарника;
|
|
- способ поиска слов, если сохраняется тот же результат;
|
|
- техническую форму возврата, если внешний контракт для `shine_users` останется совместимым.
|
|
|
|
Но если меняется именно интерфейс `return_data` или классы, это уже требует обновления `shine_users` и документации.
|