18 KiB
Программа 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 в неизменном порядке:
payer— signer, writable;user_pda— writable (SHA-256 нормализованного полного логина);system_program— read-only;shine_paymentsinflow vault — writable;sysvar::instructions— read-only;users_economy_config_pda— read-only;namespace_pda— read-only, ownershine_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:
- старый authority разрешает переход;
- 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:
- caller signer + writable;
- 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; история тех переводов не импортируется.