SHiNE-server/Dev_Docs/Solana_Architecture/details/shine_payments.md

shine_payments

Кратко

shine_payments — третья программа Solana-модуля SHiNE. Она отвечает за vault входящих средств, DAO-казну, покупку тикетов, менеджерские лимиты, очереди выплат и пошаговое исполнение выплат.

Папка программы: shine-solana/shine/programs/shine_payments/.

Текущие функции

1. init

   • Создает основные PDA: config_pda, coef_limit_pda, queues_pda, inflow_vault_pda.
   • Записывает dao_wallet и стартовые параметры выплат.

2. update_coef_limit

   • Обновляет коэффициент выплаты, лимит очереди и награду вызвавшему step_payout.
   • Требует подпись DAO-кошелька из ConfigState.

3. grant_manager_limits

   • DAO выдает менеджеру лимиты на создание тикетов в очередях Q1/Q2.
   • Создает или обновляет manager_allowance_pda.

4. buy_ticket

   • Покупка тикета с суммой в lamports, пересчетом через Pyth SOL/USD.

5. buy_ticket_usd

   • Покупка тикета от USD-центов с защитой по максимальному платежу в lamports.

6. buy_ticket_sol

   • Покупка тикета в lamports с проверкой минимального ожидаемого USD-эквивалента.

7. manager_add_ticket

   • Менеджер создает тикет за счет выданного ему DAO-лимита.

8. step_payout

   • Любой подписант может вызвать шаг выплат.
   • Программа выплачивает следующий тикет, DAO-часть и награду вызывающему.

9. change_ticket_recipient

   • Текущий получатель тикета может поменять адрес получателя, если тикет еще не следующий на выплату.

Аргументы инструкций

init аргументов не принимает.

update_coef_limit:

• coef_ppm: u64
• limit_usd_cents: u64
• call_reward_lamports: u64

grant_manager_limits:

• manager_wallet: Pubkey
• add_q1_usd_cents: u64
• add_q2_usd_cents: u64

buy_ticket:

• amount_lamports: u64
• recipient_wallet: Pubkey

buy_ticket_usd:

• amount_usd_cents: u64
• max_pay_lamports: u64
• recipient_wallet: Pubkey

buy_ticket_sol:

• amount_lamports: u64
• min_expected_usd_cents: u64
• recipient_wallet: Pubkey

manager_add_ticket:

• queue_id: u8 — только 1 или 2
• recipient_wallet: Pubkey
• payout_usd_cents: u64

change_ticket_recipient:

• new_recipient_wallet: Pubkey

Главные PDA

1. config_pda

   • Seed: shine_payments_config.
   • Хранит dao_wallet и inflow_vault.
   • Размер PDA: 8 + 160 байт.

2. coef_limit_pda

   • Seed: shine_payments_coef_limit.
   • Хранит коэффициент выплат, лимит и награду step_payout.
   • Размер PDA: 8 + 96 байт.

3. queues_pda

   • Seed: shine_payments_queues.
   • Хранит агрегаты очередей Q1/Q2.
   • Размер PDA: 8 + 192 байт.

4. inflow_vault_pda

   • Seed: shine_payments_inflow_vault.
   • Принимает деньги от shine_users.
   • Из него выполняются выплаты тикетам, DAO и вызывающему step_payout.
   • Размер PDA: 8 + 32 байт.

5. ticket_pda

   • Seed зависит от очереди и индекса тикета.
   • Отдельная PDA-запись на каждый тикет.
   • Q1 seed: shine_payments_q1_ticket + ticket_index.
   • Q2 seed: shine_payments_q2_ticket + ticket_index.
   • Размер PDA: 8 + 160 байт.

6. manager_allowance_pda

   • Seed: shine_p_manager_allow + адрес менеджера.
   • Хранит доступный лимит менеджера по Q1/Q2.
   • Размер PDA: 8 + 128 байт.

Текущие параметры

Параметры initial config из programs/shine_payments/src/settings.rs:

Поле	Значение	Смысл
START_COEF_PPM	5_000_000	коэффициент 5.0x в ppm-масштабе
START_LIMIT_USD_CENTS	1_000_000	стартовый лимит Q1: 10_000 USD
START_CALL_REWARD_LAMPORTS	8_000_000	награда вызвавшему step_payout, 0.008 SOL
MAX_CALL_REWARD_LAMPORTS	10_000_000	максимум награды, 0.01 SOL
ORACLE_MAX_AGE_SECS	120	максимальный возраст цены Pyth

Для расчетов используется Pyth SOL/USD:

• feed id: 0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d
• price update account: 7UVimffxr9ow1uXYxsr4LHAcV58mLzhmwaeKvJ1pjLiE

Деньги

Входы:

• из shine_users в inflow_vault_pda при регистрации и увеличении лимита;
• от покупателя тикета сразу в dao_wallet при buy_ticket*.

Выходы:

• из inflow_vault_pda получателю тикета;
• из inflow_vault_pda в dao_wallet;
• из inflow_vault_pda вызвавшему step_payout;
• если очереди пустые, весь доступный остаток inflow_vault_pda переводится в DAO.

Очереди и выплаты

Выплаты идут строго пошагово:

• если есть невыплаченные Q1-тикеты, step_payout берет следующий Q1;
• если Q1 пустая, берется следующий Q2;
• для Q1 DAO-часть равна сумме тикета в USD;
• для Q2 DAO-часть равна двойной сумме тикета в USD;
• перед выплатой суммы пересчитываются из USD-центов в lamports по Pyth SOL/USD;
• если в inflow_vault_pda не хватает средств на тикет, DAO-часть и награду вызвавшему, шаг отклоняется.

change_ticket_recipient запрещает менять получателя у тикета, который является следующим на выплату.

Ключи и управление

На старте удобно считать, что у программы есть отдельный управляющий ключ key_3.

Целевая модель:

• update_coef_limit вызывает DAO;
• grant_manager_limits вызывает DAO;
• upgrade-authority программы после проверки передается DAO;
• step_payout остается открытым для любого подписанта, чтобы выплаты не зависели от одного оператора.