Files
SHiNE-server/docs/Solana/SHINE_USER_PDA_V13_ROOT_LIMITS.md
T

4.5 KiB

SHiNE User PDA 1.3 — Root-signature, system limits, economy v2

Canonical binary record

  • Outer record layout and fork size remain unchanged from PDA 1.2; paid_limit_bytes remains u32 (4 bytes) in every fork.
  • The new format_minor = 3. On create every fork limit is 0. No additional_limit instruction argument or paid top-up.
  • 0 means unlimited total blockchain bytes, positive N means maximum N bytes. This does not remove per-block/request limits.
  • Canonical signing preimage = exact serialized unsigned PDA bytes, omitting only four quota bytes in each fork. Keep original physical record_len and variable-block payload_len fields unchanged in the canonical preimage; changing length values would change hashes.
  • SHA256(canonical signing bytes) is verified by an Ed25519 instruction from the Root Key. The 64-byte signature stored in PDA is Root Key's signature. The contract verifies signatures; it never signs for the user.
  • Normal update: one root Ed25519 instruction. Full key rotation: old root Ed25519 followed by new root Ed25519; stored signature is from new root. New root/client/blockchain keys must be rotated together. Blockchain Key remains for signing user-blockchain content, not User PDA.
  • Changes to on-chain limits are not implemented in this patch. Future privileged instruction must mutate ONLY the 4 bytes and have explicit authorization/audit. It must not permit untrusted PDA input to override the limit.
  • Every new fork starts with paid_limit_bytes = 0 (unlimited), regardless of the previous fork's limit. Historical forks retain their own values. The existing fork cooldown is retained for ordinary forks.
  • prev_record_hash for a predecessor v1.2 is SHA256(physical v1.2 unsigned bytes). For v1.3 it is SHA256(canonical unsigned bytes without limit bytes). The first signed update migrates v1.2 -> 1.3 at the same PDA address.
  • Old v1.2 accounts remain readable and usable for Stars support operations. Their record signatures follow the old v1.2 rule until the first root-authorized migration to 1.3.

Economy PDA v2

The on-chain state contains only version=2:u8 and update_fee_lamports:u64 (9 useful bytes; old allocated space may remain padded). No registration fee or quota price in this PDA. Registration fee lives in the namespace PDA. User PDA update fee comes from this economy PDA.

For existing v1 economy PDA, the program temporarily reads the legacy state and uses the previous fixed update fee 20,000 lamports; submit the authorized IX_UPDATE_USERS_ECONOMY_CONFIG with only 8-byte LE update_fee_lamports to migrate the existing economy PDA to v2. Its PDA address does not change.

Wire changes

  • IX_CREATE_USER_PDA(3): removed additional_limit:u64 after created_at_ms.
  • IX_UPDATE_USER_PDA(4): removed additional_limit:u64 after updated_at_ms; retained auth_mode:u8 with only 1 (root) supported. The normal update requires the old root; rotation requires both old/new root signatures.
  • IX_UPDATE_USERS_ECONOMY_CONFIG(2): now only update_fee_lamports:u64; same authority and account list as v1.

Server

  • Keep size_limit=0 in runtime blockchain_state_store as unlimited, and size_limit>0 as the active block-size total quota.
  • Both the optimistic handler check and the atomic SQL file-size update must treat zero as unlimited.
  • Synchronize limits for all historical forks from solana_user_pda_current into existing runtime blockchain states without resetting tips, size, or key material; use current fork value when accepting a block. If a valid free user has no Solana PDA yet, default to 0.
  • Limit mutation is not yet exposed; future change will require sync by slot/signature even without a changed record_number.

Deployment order

  1. Deploy server and client handling v1.2 + 1.3, economy v2 and zero-unlimited semantics together.
  2. Upgrade Solana shine_users program with the existing Program ID using authorized upgrade procedures; do not rotate seeds or PDA addresses.
  3. Migrate economy PDA v1 -> v2 through the authorized update instruction (default 20,000 lamports or chosen value).
  4. Create a new v1.3 account and verify stored root signature, first zero quota, added blocks >100 KB, Stars support, old v1.2 read, first v1.2 -> v1.3 root migration.
  5. Test full root/client/blockchain rotation requiring signatures from both roots, old fork read, and paid namespace creation.

Deployment and live signed chain transactions have not been performed by this source patch.