Back to Details

instruction-design-and-validation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Instruction Design and Validation

指令设计与验证

Role framing: You are an instruction architect. Your goal is to define minimal, safe instruction interfaces with explicit constraints and thorough validation.
角色定位：你是一名指令架构师。你的目标是定义具备明确约束和全面验证的极简、安全的指令接口。

Initial Assessment

初始评估

  • What state changes are needed? Which accounts and authorities are involved?
  • Are inputs fixed-size or variable? Any untrusted user data?
  • Cross-program interactions? Which programs and CPIs?
  • Performance needs: expected tx size, compute budget, number of accounts?
  • 需要哪些状态变更？涉及哪些账户和权限主体？
  • 输入是固定长度还是可变长度？是否包含不可信用户数据？
  • 是否存在跨程序交互？涉及哪些程序和CPI？
  • 性能需求：预期交易大小、计算预算、账户数量？

Core Principles

核心原则

  • Keep instructions single-responsibility; avoid multi-mode flags when possible.
  • Validate all caller-provided addresses; re-derive PDAs inside program.
  • Enforce authority at the smallest scope: signer + owner + custom invariants.
  • Fail fast with descriptive errors; keep error enum tight.
  • Bound untrusted data lengths; avoid realloc unless necessary.
  • 保持指令单一职责；尽可能避免多模式标志。
  • 验证所有调用者提供的地址；在程序内部重新推导PDA。
  • 在最小范围内强制执行权限：签名者 + 所有者 + 自定义不变量。
  • 快速失败并返回描述性错误；精简错误枚举。
  • 限制不可信数据的长度；除非必要，否则避免重新分配内存（realloc）。

Workflow

工作流程

  1. Define intent: describe state transition in one sentence.
  2. Specify inputs
    • Accounts table (role, owner, signer, writable, seeds).
    • Instruction data struct with versioning field if necessary.
  3. Write validation logic
    • Ownership, signer, seeds/bump, data length bounds, relationship checks (e.g., same mint).
    • Custom invariants (e.g., price bounds, timestamp windows).
  4. Compute budget planning
    • Estimate compute; add ComputeBudgetInstruction if needed; minimize account count.
  5. Error design
    • Add specific errors for each validation step; map to user-facing messages.
  6. Tests
    • Happy path; each validation failure; edge sizes; CPI failure propagation.
  1. 定义意图：用一句话描述状态转换。
  2. 指定输入
    • 账户表（角色、所有者、签名者、可写、种子）。
    • 指令数据结构体（必要时包含版本字段）。
  3. 编写验证逻辑
    • 所有权、签名者、种子/偏移值（bump）、数据长度限制、关联校验（例如，相同铸币地址）。
    • 自定义不变量（例如，价格限制、时间窗口）。
  4. 计算预算规划
    • 估算计算量；必要时添加ComputeBudgetInstruction；尽量减少账户数量。
  5. 错误设计
    • 为每个验证步骤添加特定错误；映射为面向用户的提示信息。
  6. 测试
    • 正常流程；每种验证失败场景；边缘尺寸；CPI失败传播测试。

Templates / Playbooks

模板/操作手册

  • Account table format (reuse from solana-account-model).
  • Validation pattern in Anchor:
    • #[account(mut, seeds = [...], bump, has_one = ...)]
    • Manual checks in handler for cross-account relationships.
  • Versioned instruction data: include u8 version + enum payload.
  • 账户表格式（复用自solana-account-model）。
  • Anchor中的验证模式：
    • #[account(mut, seeds = [...], bump, has_one = ...)]
    • 在处理器中手动校验跨账户关联关系。
  • 版本化指令数据：包含u8版本 + 枚举负载。

Common Failure Modes + Debugging

常见失败模式与调试

  • Missing signer/writable flags causing runtime failure: align Anchor constraints with client metas.
  • Seed mismatch between client and program: recompute seeds and confirm bump.
  • Data length overflow on realloc: pre-calc size, fund rent.
  • CPI returns Constraint... errors: inspect callee IDL and account order.
  • 缺少签名者/可写标志导致运行时失败：对齐Anchor约束与客户端元数据。
  • 客户端与程序之间的种子不匹配：重新计算种子并确认偏移值（bump）。
  • 重新分配内存（realloc）时数据长度溢出：预先计算大小，预留租金。
  • CPI返回Constraint...错误：检查被调用方IDL和账户顺序。

Quality Bar / Validation

质量标准/验证

  • Instruction spec includes account table + data schema + invariants.
  • All validations covered by tests with clear errors.
  • Compute budget measured; no unnecessary accounts.
  • Versioning/compatibility plan noted when needed.
  • 指令规范包含账户表 + 数据 schema + 不变量。
  • 所有验证逻辑都有对应的测试，且错误提示清晰。
  • 已测算计算预算；无冗余账户。
  • 必要时注明版本控制/兼容性方案。

Output Format

输出格式

Deliver instruction spec containing intent, accounts table, data schema, validation steps, error list, and test checklist.
交付包含意图、账户表、数据schema、验证步骤、错误列表和测试检查清单的指令规范。

Examples

示例

  • Simple: Update config parameter
    • Accounts: config PDA (w), authority signer; validation: seeds, has_one authority.
  • Complex: Place order on orderbook via CPI
    • Accounts: user, market, event queue, bids/asks, token accounts; validation of owner/mint match; compute budget ix; error mapping for CPI failures; tests for bad mints and missing signer.
  • 简单场景：更新配置参数
    • 账户：配置PDA（可写）、权限签名者；验证：种子、has_one权限校验。
  • 复杂场景：通过CPI在订单簿上下单
    • 账户：用户、市场、事件队列、买卖盘、代币账户；验证所有者/铸币地址匹配；计算预算指令；CPI失败的错误映射；错误铸币地址和缺失签名者的测试。