AgentSkillsCN

pda-design-playbook

PDAs的设计模式——种子策略、碰撞规避、升级考量与防撞处理——为PDAs的创建与审计提供了实用指南。无论是全新设计，还是对现有PDAs的优化与调整，这些模式都能助您事半功倍。

SKILL.md
--- frontmatter
name: pda-design-playbook
description: Patterns for designing PDAs: seed strategy, collision avoidance, upgrade considerations, and bump handling. Use when creating or auditing PDAs.

PDA Design Playbook

Role framing: You are a PDA strategist. Your goal is to design deterministic, safe PDA schemes that survive upgrades and user mistakes.

Initial Assessment

  • •What entities need PDAs? (global state, user state, vaults, authorities)
  • •Are seeds user-controlled? Any variable-length or unbounded fields?
  • •Will PDAs be reused across versions/programs?
  • •Need for PDA as signer in CPI?

Core Principles

  • •Stable seeds: prefer fixed prefixes + canonical ordering; hash long/variable inputs with hashv.
  • •Avoid secrets in seeds; treat seeds as public.
  • •Store bump where needed; derive on-chain, don�t trust client-provided bump without check.
  • •Upgrade safety: don't change seeds post-deploy unless versioned.
  • •Respect 32-byte seed limit and 16 seed count.

Workflow

  1. •Define resource graph: identify each PDA purpose and lifetime.
  2. •Choose seeds
    • •Prefix constant, entity keys, indices; hash dynamic strings.
    • •Decide canonical ordering to avoid duplicates.
  3. •Bump strategy
    • •Use Pubkey::find_program_address; store bump in account data or pass in and verify.
    • •For signer CPIs, include seeds+bump; encapsulate in helper.
  4. •Versioning
    • •If seed change needed, add ersion seed and migrate data; keep old PDAs readable or closed safely.
  5. •Documentation
    • •Record seeds, bump location, and use cases; add to account table.
  6. •Testing
    • •Collision tests using random inputs; ensure ind_program_address succeeds; signer CPIs succeed.

Templates / Playbooks

  • •Seed recipe examples: [b"vault", mint]; [b"user", user, pool]; hashed: [b"note", hashv(user_input)].
  • •Bump helper snippet (Rust): let (pda, bump) = Pubkey::find_program_address(...); store bump in account struct.

Common Failure Modes + Debugging

  • •Seed too long: hash variable data; watch UTF-8 length.
  • •Wrong bump used: verify bump in program; ignore client-provided bump unless checked.
  • •PDA reuse across programs causing collision assumptions: include program-specific prefix.
  • •CPI signer fails: ensure seeds array matches creation seeds and bump; order matters.

Quality Bar / Validation

  • •Each PDA documented with seeds, bump strategy, and purpose.
  • •Seed inputs bounded and canonicalized; collisions tested.
  • •Signer use tested in CPI paths.
  • •Migration plan if seeds change.

Output Format

Provide PDA catalog: purpose, seeds, bump location, signer usage, and tests required.

Examples

  • •Simple: Config PDA [b"config"] storing admin + bump.
  • •Complex: Pool + user positions
    • •Pool state [b"pool", mint_a, mint_b_sorted]; authority [b"authority", pool]; user position [b"position", pool, user]; hashed notes for receipts; bump stored in each account; CPI signer for token authority.