Добавить promo-регистрацию и оффлайн генератор промокодов

shine-solana/shine/doc/programs/shine_users.md

@@ -19,8 +19,10 @@
 - создание `user_pda` по логину;
 - обновление `user_pda` без смены логина и root key;
 - хранение economy-конфига регистрации;
+- хранение PDA продавцов promo-логинов;
 - взимание комиссии за регистрацию и увеличение лимита;
 - проверку Ed25519-подписей `root_key` и `blockchain_public_key`;
+- проверку promo-подписей продавца для обхода premium/trademark login guard;
 - проверку связности новой версии записи с предыдущей через `prev_record_hash`.
 
 Программа не отвечает за:
@@ -91,7 +93,22 @@ system-переводом. Если бы создание шло строго ч
 Проверки повторной инициализации (`owner == System Program` и пустые данные) остаются и
 не зависят от баланса аккаунта.
 
-### 3.4. Строгий список аккаунтов (нет «лишних» аккаунтов)
+### 3.4. PDA продавца promo-логинов
+
+PDA продавца строится так:
+
+- seed prefix: `promo_seller=`
+- второй seed: логин продавца в нижнем регистре
+
+Формула:
+
+```text
+promo_seller_pda = PDA(["promo_seller=", lower(seller_login)], shine_users_program_id)
+```
+
+В программе может существовать сколько угодно таких PDA, по одному на каждого продавца.
+
+### 3.5. Строгий список аккаунтов (нет «лишних» аккаунтов)
 
 Все инструкции `shine_users` читают строго фиксированный набор аккаунтов и после этого
 явно требуют, чтобы в переданном списке больше ничего не было
@@ -130,17 +147,35 @@ system-переводом. Если бы создание шло строго ч
 
 Этот документ описывает именно логику программы, а не байтовую структуру блока.
 
+### 4.3. `promo_seller_pda`
+
+PDA продавца красивых логинов хранит:
+
+- `version: u8`
+- `remaining_sales: u64`
+- `min_login_length: u8`
+- `signer_pubkey: [u8; 32]`
+
+Смысл:
+
+- `remaining_sales` — сколько ещё красивых логинов продавец может выдать;
+- `min_login_length` — минимальная длина логина, которую продавец имеет право раздавать;
+- `signer_pubkey` — публичный Ed25519-ключ, которым off-chain подписываются promo-коды.
+
 ## 5. Константы и базовые правила
 
 Базовые значения из текущей логики:
 
 - seed `user_pda`: `user_login=`
 - seed economy config: `shine_users_economy_config`
+- seed promo seller PDA: `promo_seller=`
 - стартовый размер `user_pda`: `768` байт
+- размер `promo_seller_pda`: `64` байта
 - `LIMIT_STEP = 10_000`
 - `START_REGISTRATION_FEE_LAMPORTS = 10_000_000`
 - `START_LAMPORTS_PER_LIMIT_STEP = 100_000`
 - `START_BONUS_LIMIT = 100_000`
+- префикс promo-сообщения: `shine_promo_v1:`
 
 Правила:
 
@@ -230,6 +265,35 @@ On-chain инвариант только один:
 
 Если `shine_login_guard` вернул что-то иное или return_data некорректны, это ошибка.
 
+### 7.3. Promo-обход login guard
+
+При создании пользователя допускается опциональный `promo_code`.
+
+Формат строки:
+
+```text
+1<seller_login>-<signature_base58>
+```
+
+Где:
+
+- первый символ `1` — версия формата promo-кода;
+- `seller_login` — логин продавца, по которому ищется `promo_seller_pda`;
+- `signature_base58` — Ed25519-подпись по сообщению:
+
+```text
+shine_promo_v1:<login_из_запроса_create_user_pda>
+```
+
+Если promo-код валиден, то:
+
+- premium/trademark-проверка через `shine_login_guard` не выполняется;
+- базовая синтаксическая проверка логина всё равно остаётся обязательной;
+- `remaining_sales` уменьшается на `1`;
+- длина логина должна быть не меньше `min_login_length`.
+
+Если promo-код не передан, обычная CPI-проверка через `shine_login_guard` обязательна.
+
 ## 8. Инструкция `init_users_economy_config`
 
 ### Назначение
@@ -310,6 +374,7 @@ On-chain инвариант только один:
 - sysvar `instructions`
 - `users_economy_config_pda`
 - `shine_login_guard_program`
+- опционально: `promo_seller_pda`, если регистрация идёт по promo-коду
 
 ### Входные данные
 
@@ -320,6 +385,7 @@ On-chain инвариант только один:
 - `additional_limit`
 - mutable fields записи
 - `root` signature по unsigned части
+- опционально `promo_code`
 
 ### Бинарный ABI
 
@@ -332,20 +398,27 @@ On-chain инвариант только один:
 - additional_limit: u64 LE
 - fields: UserMutableFieldsV1
 - root_signature: [u8; 64]
+- optional trailing promo_code: string_u8
 ```
 
 ### Обязательные проверки
 
 1. Логин валиден по синтаксису.
-2. Логин разрешён `shine_login_guard`.
-3. `additional_limit % LIMIT_STEP == 0`.
-4. inflow vault совпадает с PDA программы `shine_payments`.
-5. `user_pda` вычислена правильно и ещё не существует.
-6. Поля блокчейна валидны.
-7. Поля server/session/trusted валидны по формату.
-8. `last_block_signature` соответствует `LastBlockState`.
-9. `root signature` соответствует unsigned части записи.
-10. Размер сериализованной записи не превышает допустимый стартовый размер PDA или иные ограничения реализации.
+2. Если promo-код не передан, логин разрешён `shine_login_guard`.
+3. Если promo-код передан, он должен:
+   - иметь формат `1<seller_login>-<signature_base58>`;
+   - ссылаться на существующий `promo_seller_pda`;
+   - проходить Ed25519-проверку через `signer_pubkey` продавца;
+   - иметь `remaining_sales > 0`;
+   - удовлетворять правилу `login.len() >= min_login_length`.
+4. `additional_limit % LIMIT_STEP == 0`.
+5. inflow vault совпадает с PDA программы `shine_payments`.
+6. `user_pda` вычислена правильно и ещё не существует.
+7. Поля блокчейна валидны.
+8. Поля server/session/trusted валидны по формату.
+9. `last_block_signature` соответствует `LastBlockState`.
+10. `root signature` соответствует unsigned части записи.
+11. Размер сериализованной записи не превышает допустимый стартовый размер PDA или иные ограничения реализации.
 
 ### Экономика
 
@@ -375,9 +448,52 @@ limit_fee(additional_limit) = (additional_limit / LIMIT_STEP) * lamports_per_lim
 
 - создаётся PDA;
 - в неё записывается полная запись `user_pda`;
+- если используется promo-код, в `promo_seller_pda` уменьшается `remaining_sales`;
 - средства переводятся в inflow vault `shine_payments`.
 
-## 11. Инструкция `update_user_pda`
+## 11. Инструкция `upsert_promo_seller`
+
+### Назначение
+
+Создать нового продавца promo-логинов или полностью перезаписать настройки уже существующего продавца.
+
+### Авторизация
+
+Только `DAO_AUTHORITY`.
+
+### Аккаунты
+
+- signer
+- `promo_seller_pda`
+- system program
+
+### Входные данные
+
+- `seller_login`
+- `remaining_sales`
+- `min_login_length`
+- `signer_pubkey`
+
+### Бинарный ABI
+
+```text
+- tag: u8 = 5
+- seller_login: string_u8
+- remaining_sales: u64 LE
+- min_login_length: u8
+- signer_pubkey: [u8; 32]
+```
+
+### Правила
+
+- signer должен совпадать с `DAO_AUTHORITY`;
+- `seller_login` проходит ту же базовую проверку логина;
+- `min_login_length` лежит в диапазоне `1..20`;
+- адрес PDA обязан совпадать с `promo_seller=` + `lower(seller_login)`;
+- если PDA ещё нет, она создаётся;
+- если PDA уже есть, её состояние полностью перезаписывается.
+
+## 12. Инструкция `update_user_pda`
 
 ### Назначение
 
@@ -445,9 +561,9 @@ topup_fee = limit_fee(additional_limit)
 - root_signature: [u8; 64]
 ```
 
-## 12. Ed25519-проверки и порядок инструкций
+## 13. Ed25519-проверки и порядок инструкций
 
-В транзакции должны стоять две встроенные Ed25519-инструкции прямо перед вызовом `shine_users`:
+В обычной транзакции `create/update` должны стоять две встроенные Ed25519-инструкции прямо перед вызовом `shine_users`:
 
 1. подпись `root_key` по unsigned записи;
 2. подпись `blockchain_public_key` по `LastBlockState`.
@@ -459,7 +575,19 @@ topup_fee = limit_fee(additional_limit)
 
 Это правило порядка является частью контракта между off-chain клиентом и программой.
 
-## 13. LastBlockState
+Если `create_user_pda` вызывается с promo-кодом, то перед ними добавляется ещё одна Ed25519-инструкция:
+
+1. подпись продавца promo-логина по строке `shine_promo_v1:<login>`;
+2. подпись `root_key` по unsigned записи;
+3. подпись `blockchain_public_key` по `LastBlockState`.
+
+Тогда программа читает:
+
+- `-3` — promo-подпись;
+- `-2` — `root_key`;
+- `-1` — `blockchain_public_key`.
+
+## 14. LastBlockState
 
 Сообщение для подписи `blockchain_public_key`:
 
@@ -479,7 +607,7 @@ message_hash = SHA-256(LastBlockState bytes)
 signature = Ed25519(blockchain_private_key, message_hash)
 ```
 
-## 14. Валидируемые mutable-поля записи
+## 15. Валидируемые mutable-поля записи
 
 Программа допускает обновление:
 
@@ -507,7 +635,7 @@ signature = Ed25519(blockchain_private_key, message_hash)
 - `blockchain_public_key`
 - `blockchain_type`
 
-## 15. Правила серверных и сессионных полей
+## 16. Правила серверных и сессионных полей
 
 ### UserMutableFieldsV1
 
@@ -567,7 +695,7 @@ signature = Ed25519(blockchain_private_key, message_hash)
 - `sessions_mode = 1`
 - `sessions = []`
 
-## 16. Realloc поведения PDA
+## 17. Realloc поведения PDA
 
 Запись может расти. Если новая сериализованная запись длиннее текущего размера PDA:
 
@@ -575,7 +703,7 @@ signature = Ed25519(blockchain_private_key, message_hash)
 - нельзя делать чрезмерный рост одним шагом выше внутреннего лимита реализации;
 - перед realloc нужно обеспечить rent для нового размера.
 
-## 17. Ошибки и классы отказа
+## 18. Ошибки и классы отказа
 
 Программа должна различать как минимум такие классы ошибок:
 
@@ -592,9 +720,14 @@ signature = Ed25519(blockchain_private_key, message_hash)
 - попытка уменьшить лимит/used_bytes/block number;
 - overflow;
 - неверный inflow vault;
-- неверный DAO authority для economy config.
+- неверный DAO authority для economy config и promo seller update;
+- неверный promo-код;
+- несуществующий или повреждённый `promo_seller_pda`;
+- исчерпанная promo-квота;
+- promo-подпись не совпадает;
+- логин короче `min_login_length`.
 
-## 18. Что должно сохраниться при переписи без Anchor
+## 19. Что должно сохраниться при переписи без Anchor
 
 В текущей чисто-rust реализации уже сохранены:
 
@@ -604,6 +737,7 @@ signature = Ed25519(blockchain_private_key, message_hash)
 - тот же порядок Ed25519-инструкций;
 - те же immutable/mutable правила;
 - ту же валидацию логина и CPI в `shine_login_guard`;
+- ту же promo-механику с PDA продавцов и подписью `shine_promo_v1:<login>`;
 - ту же зависимость от inflow vault программы `shine_payments`.
 
 Сознательно не сохранялись: