Files
SHiNE-server/shine-solana/shine/doc/programs/shine_users.md
T

18 KiB
Raw Blame History

Программа shine_users

Актуальный пользовательский формат — user_pda 1.2. Полный бинарный формат: doc/formats/shine-user-pda-format-v.1.2.md. Legacy 1.0 считается тестовым и не мигрируется.

Что хранит программа

  • root_key — cold recovery authority;
  • client_key;
  • append-only список blockchain fork keys с временем создания и оплаченной квотой;
  • один optional server address;
  • ноль или один access server;
  • record_number, prev_record_hash и переносимую Ed25519-подпись состояния.

Пользовательские SHiNE-блоки/Arweave этим патчем не меняются.

Инструкции

1 init_users_economy_config

Без изменений.

2 update_users_economy_config

Меняется только право доступа: текущая upgrade authority из ProgramData данного shine_users, а не статическая DAO-константа. Accounts: signer writable? (signer), users_economy_config_pda writable, program read-only executable, programdata read-only. init (opcode 1) остаётся доступным любому подписанту один раз.

3 create_user_pda — новая V2-инструкция

Важно для развёртывания: этот патч изменяет экономику create_user_pda, но не wire-формат и не список account metas. Обновление on-chain программы shine_users должно предшествовать выкладке UI с новой формулой. Старый контракт списывает депозит PDA поверх цены namespace, новый — внутри неё. Ни тестирование, ни публикация программы в сеть не входят в подготовку патча.

tag:u8 = 3
login:string_u8                 // исходный регистр localpart, lowercase namespace, <= 30 байт
root_key:[32]
created_at_ms:u64 LE           // новая Solana дата в пределах +-5 мин
additional_limit:u64 LE        // кратно LIMIT_STEP
client_key:[32]
blockchain_key:[32]
address_count:u8              // 0 или 1
[address]                    // type:u8, version:u8, address:string_u8
access_server_count:u8        // 0 или 1
[access_server:string_u8]
record_signature:[64]         // подпись текущего blockchain-key, сохраняется в PDA
registrar_signature_present:u8 // 0 для type 1, 1 для type 2
[registrar_signature:[64]]     // только type 2, внутренняя подпись сертификата

Accounts в неизменном порядке:

  1. payer — signer, writable;
  2. user_pda — writable (SHA-256 нормализованного полного логина);
  3. system_program — read-only;
  4. shine_payments inflow vault — writable;
  5. sysvar::instructions — read-only;
  6. users_economy_config_pda — read-only;
  7. namespace_pda — read-only, owner shine_users.

Проверки: namespace реально существует в программе, localPart >= min_localpart_len, общая длина <= 30, localpart допускает ASCII [A-Za-z0-9_]+, namespace остаётся ASCII lowercase [a-z0-9_]+, PDA соответствует SHA256("user_login="+ASCII-lowercase(fullLogin)), схема v1.2, root и blockchain Ed25519 proof-of-possession. Цена создания PDA для подписанта (без комиссии самой сети) = namespace.registration_fee + additional_limit/LIMIT_STEP * economy.lamports_per_limit_step. На создание PDA направляется top_up = max(0, Rent::minimum_balance(USER_PDA_SPACE) - user_pda.lamports()), сумма namespace.registration_fee - top_up переводится в существующий shine_payments vault. Оплата дополнительного лимита направляется в тот же vault полностью. Схема учитывает заранее пополненный system-owned адрес PDA: подписант платит ровно цену namespace за регистрацию вне зависимости от ранее зачисленных lamports; их наличие уменьшает top-up и увеличивает остаток, направляемый в vault. Если namespace.registration_fee < Rent::minimum_balance(USER_PDA_SPACE), транзакция отклоняется независимо от заранее внесённых lamports ошибкой RegistrationFeeBelowRent (код 45). Сетевая комиссия Solana оплачивается подписантом сверх цены namespace; её определяет сеть, она не переводится в vault. Цену можно изменить только отдельной инструкцией 8 update_namespace_price по подписи текущей upgrade authority. Код валюты проверяется: пока разрешён лишь 1=SOL; пересчёт в USD/USDT не реализован. На create сохраняется существующая схема starter quota из economy-PDA: при переходе free→paid внешняя БД обязана учесть уже использованный бонус и не выдать его снова.

Ed25519 инструкции перед opcode 3 (строго непосредственно):

  • Тип 1: [root_verify(unsigned_hash), blockchain_verify(unsigned_hash), create_user]; смещения -2, -1.
  • Тип 2: [registrar_verify(inner_message), root_verify(unsigned_hash), blockchain_verify(unsigned_hash), create_user]; смещения -3, -2, -1.

Всем проверкам нужны именно требуемые pubkey, message, а blockchain также сопоставляется с record_signature. Проверка сертификата использует registrar_pubkey из указанного namespace-PDA, а не ключ клиента. Порядок байтов inner message см. docs/Протоколы/SHINE_FREE_REGISTRATION_CERTIFICATE_V1.md. Solana подтверждает право создать PDA, но не утверждает успешную публикацию сертификата в Arweave.

Upgrade free→paid — тот же opcode 3 на том же полном логине и публичных ключах. Старые приватные ключи клиента не раскрываются; сохранение исходных публикаций обеспечивают синхронизатор/сервер (не Solana). Дата создания on-chain PDA может быть новой. Повторное создание PDA отвергается.

4 update_user_pda

Работает только с PDA 1.2. Для нового login@namespace ищет SHA-256 PDA; для существующего старого логина без @ сохраняет прежнюю схему [b"user_login=", lowercase_login], чтобы не блокировать прежние аккаунты. Оплата дополнительных лимитов и авторизация обновлений не меняются.

tag:u8 = 4
login:string_u8
new_root_key:[32]
updated_at_ms:u64
additional_limit:u64
new_client_key:[32]
auth_mode:u8                  // 0 blockchain, 1 root
new_blockchain_present:u8
[new_blockchain_key:[32]]
address_count:u8              // 0 или 1
[address]
access_server_count:u8        // 0 или 1
[access_server]
record_signature:[64]

Программа сама вычисляет record_number=old+1 и prev_record_hash. updated_at_ms должен быть в пределах ±5 минут от Solana Clock.

Перед update идут две Ed25519 instructions по hash нового unsigned state:

  1. старый authority разрешает переход;
  2. authority нового состояния подписывает запись; эта подпись сохраняется в PDA.

Blockchain-mode:

  • используется для всех обычных update;
  • старый authority = последний blockchain key;
  • signature[64] нового состояния = активный blockchain key либо новый blockchain key, если добавляется fork;
  • root/client менять нельзя;
  • новый fork — только после 72 часов от времени активного fork.

Root-mode:

  • допустим только для recovery/полной ротации ключей;
  • старый authority = текущий root;
  • полная ротация одной транзакцией меняет root_key, client_key и добавляет новый blockchain fork;
  • transition-подпись делает старый root, а signature[64] нового состояния делает новый blockchain key;
  • recovery fork может обходить 72-часовой cooldown;
  • смена root без одновременной смены client key и добавления нового blockchain fork отклоняется.

Обе Ed25519-подписи проверяются по одному и тому же hash нового unsigned PDA state, поэтому новые root/client/blockchain public keys входят в подписываемое состояние.

5 — зарезервированная старая promo instruction

В V2 диспетчер не исполняет opcode 5. Новая регистрация не обращается в shine_login_guard, не использует promo seller и premium классы. Исторические standalone программы не удалялись.

6 close_legacy_pda

Временная cleanup-инструкция для тестовых PDA 1.0.

tag:u8 = 6
login:string_u8

Accounts:

  1. caller signer + writable;
  2. legacy user PDA writable.

Программа проверяет PDA seed/owner и format=1.0, переводит все lamports PDA вызывающему и обнуляет account data. PDA 1.2 этой инструкцией закрыть нельзя.

7 create_namespace

tag:u8=7
namespace_type:u8          // 1 paid-direct / 2 free-cert
min_localpart_len:u8
namespace:string_u8
registration_fee:u64 LE
[if type=2: registrar_pubkey:[32]; server_login:string_u8]

Accounts: payer signer writable, namespace_pda writable, system_program read-only, economy_pda read-only, shine_users program executable read-only, shine_users ProgramData read-only; только type=2 — registered_access_server_user_pda (read-only) настоящего зарегистрированного сервера с ServerProfile.

Проверки: точный PDA по 32-байтному SHA-256 seed namespace=NAME, owner, пустой system PDA, на создание пишется версия 1.1 с currency_code=1, длина имени, тип, поля регистратора; economy валиден и read-only; ProgramData строго относится к этому исполняемому program ID и upgrade_authority=Some(signer). У immutable программы создание запрещено; цену можно обновлять только opcode 8, удалить/переименовать namespace нельзя. Отдельная документация: doc/formats/shine-namespace-pda-format-v1.md.

BlockchainRegistry 1.2

fork_count:u16
forks[]:
    blockchain_key:[32]
    created_at_ms:u64
    paid_limit_bytes:u32

Последний fork активный. Старые записи неизменяемы.

Server/access limits в 1.2

Бинарный формат использует count/arrays для forward compatibility, но текущая программа намеренно ограничивает:

  • ServerProfileBlock: один адрес;
  • AccessServersBlock: 0 или 1 сервер доступа.

Позже лимиты можно увеличить без изменения структуры блоков.

Регистронезависимая идентичность (28.10.2026)

Локальная часть полного login@namespace допускает латинские буквы A–Z и a–z, цифры и _; namespace допускает только нижний ASCII-регистр. Выбранный при регистрации регистр логина неизменяем. Адрес user PDA вычисляется по SHA256(UTF8("user_login=" + ASCII-lowercase(fullLogin))) и bump для find_program_address. Сама запись PDA 1.2 содержит оригинальное написание login; подписи записи и регистраторского сертификата проверяются по исходному регистру без нормализации. Это изменение правила seed, не бинарного формата PDA.

8 update_namespace_price — настройка цены пространства имён

Формат: tag=8; namespace:string_u8; currency_code:u8; registration_fee:u64LE. Код 1 = SOL, код 2 зарезервирован для USDT и отвергается (UnsupportedNamespaceCurrency=46). Цена registration_fee в lamports включает rent user PDA, без комиссии транзакции.

Accounts: signer/current upgrade authority writable, namespace PDA writable, system program read-only, economy PDA read-only, shine_users executable read-only, ProgramData read-only. Проверяется реальная текущая upgrade authority, а не ключ по умолчанию. У старого namespace 1.0 цена обновляется с миграцией бинарной записи до v1.1 и возможной доплатой rent за 1 байт. Изменение полей registrar/server/type не допускается.

Синхронизатор получает новую цену по истории economy PDA с разбором opcode 8 и чтением обновлённого namespace PDA. Новые регистрации в обоих сценариях всегда проверяют стоимость по on-chain namespace непосредственно перед отправкой транзакции.

Поддержка и комиссия обновления

update_user_pda после успешной проверки и записи взимает фиксированные 20_000 lamports в существующий shine_payments_inflow_vault, дополнительно к оплате увеличения лимита и rent. Ошибка инструкции откатывает и запись, и перевод.

Stars v1 (Devnet, без истории legacy)

Все инструкции поддержки передают amount_lamports:u64 LE и amount_star_cents:u64 LE (1 ⭐ = 100 cents, минимум 10 cents = 0,10 ⭐). Курс Stars = 1 USDT; на входе SOL/USD и USDT/USD как readonly PriceUpdateV2 Pyth (после system_program). Программа проверяет owner Pyth Receiver, точный feed id, полную верификацию, возраст ≤ 3600 сек (1 час для Devnet), относительную погрешность цены ≤ 1% и совпадение стоимости в Stars с погрешностью ≤ 0,5%. Нарушение любого ограничения откатывает перевод.

Важно перед Mainnet: часовой лимит установлен только для нестабильного Devnet. Перед публикацией Stars в Mainnet нужно отдельно выбрать и задеплоить более строгий лимит свежести Pyth; значение 3600 нельзя переносить в Mainnet автоматически.

Инструкция 9 (support_user) сериализуется как: tag=9; sender_login:string_u8; recipient_login:string_u8; amount_lamports:u64LE; amount_star_cents:u64LE; target:u8; [channel_number:u64LE;channel_hash:bytes32]; [message_number:u64LE;message_hash:bytes32]. Счётчик support_sent увеличивается на полную сумму Stars; support_received получателя — на amount_star_cents - ceil(amount_star_cents/10). Фактические SOL распределяются 90/10 с округлением доли vault вверх до одного lamport. Получатель должен быть отдельным Paid PDA с актуальным ключом.

Инструкция 10 (support_dao): tag=10; sender_login:string_u8; amount_lamports:u64LE; amount_star_cents:u64LE. Все SOL идут в shine_payments_inflow_vault, счётчик dao_direct увеличивается на Stars. Оба вида донатов используют readonly economy PDA для индексации.

В конце каждой успешной инструкции выводится транзакционный лог SHINE_STARS_V1|USER|sender|recipient|lamports|star_cents|author_cents|dao_cents либо SHINE_STARS_V1|DAO|sender|-|lamports|star_cents|0|star_cents. Это доказательство успешной операции для индексатора вместе с meta.err=null. Stars не имеют токена/баланса: это только неизменяемые суммы поддержки.

В чистом тестовом запуске исторические счётчики lamports v1 принимаются за нуль и при следующем обновлении PDA заменяются форматом Stars v2; история тех переводов не импортируется.