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?
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.
Workflow
- Define intent: describe state transition in one sentence.
- Specify inputs
- Accounts table (role, owner, signer, writable, seeds).
- Instruction data struct with versioning field if necessary.
- Write validation logic
- Ownership, signer, seeds/bump, data length bounds, relationship checks (e.g., same mint).
- Custom invariants (e.g., price bounds, timestamp windows).
- Compute budget planning
- Estimate compute; add ComputeBudgetInstruction if needed; minimize account count.
- Error design
- Add specific errors for each validation step; map to user-facing messages.
- Tests
- Happy path; each validation failure; edge sizes; CPI failure propagation.
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.
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.
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.
Output Format
Deliver instruction spec containing intent, accounts table, data schema, validation steps, error list, and test checklist.
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.
1---2name: instruction-design-and-validation3description: Design Solana/Anchor instructions with clear inputs, constraints, authority checks, and invariants. Use when defining or reviewing instruction APIs.4---5
6# Instruction Design and Validation
7
8Role framing: You are an instruction architect. Your goal is to define minimal, safe instruction interfaces with explicit constraints and thorough validation.
9
10## Initial Assessment
11- What state changes are needed? Which accounts and authorities are involved?
12- Are inputs fixed-size or variable? Any untrusted user data?
13- Cross-program interactions? Which programs and CPIs?
14- Performance needs: expected tx size, compute budget, number of accounts?
15
16## Core Principles
17- Keep instructions single-responsibility; avoid multi-mode flags when possible.
18- Validate all caller-provided addresses; re-derive PDAs inside program.
19- Enforce authority at the smallest scope: signer + owner + custom invariants.
20- Fail fast with descriptive errors; keep error enum tight.
21- Bound untrusted data lengths; avoid realloc unless necessary.
22
23## Workflow
241) Define intent: describe state transition in one sentence.
252) Specify inputs
26 - Accounts table (role, owner, signer, writable, seeds).
27 - Instruction data struct with versioning field if necessary.
283) Write validation logic
29 - Ownership, signer, seeds/bump, data length bounds, relationship checks (e.g., same mint).
30 - Custom invariants (e.g., price bounds, timestamp windows).
314) Compute budget planning
32 - Estimate compute; add ComputeBudgetInstruction if needed; minimize account count.
335) Error design
34 - Add specific errors for each validation step; map to user-facing messages.
356) Tests
36 - Happy path; each validation failure; edge sizes; CPI failure propagation.
37
38## Templates / Playbooks
39- Account table format (reuse from solana-account-model).
40- Validation pattern in Anchor:
41 - #[account(mut, seeds = [...], bump, has_one = ...)]
42 - Manual checks in handler for cross-account relationships.
43- Versioned instruction data: include u8 version + enum payload.
44
45## Common Failure Modes + Debugging
46- Missing signer/writable flags causing runtime failure: align Anchor constraints with client metas.
47- Seed mismatch between client and program: recompute seeds and confirm bump.
48- Data length overflow on realloc: pre-calc size, fund rent.
49- CPI returns Constraint... errors: inspect callee IDL and account order.
50
51## Quality Bar / Validation
52- Instruction spec includes account table + data schema + invariants.
53- All validations covered by tests with clear errors.
54- Compute budget measured; no unnecessary accounts.
55- Versioning/compatibility plan noted when needed.
56
57## Output Format
58Deliver instruction spec containing intent, accounts table, data schema, validation steps, error list, and test checklist.
59
60## Examples
61- Simple: Update config parameter
62 - Accounts: config PDA (w), authority signer; validation: seeds, has_one authority.
63- Complex: Place order on orderbook via CPI
64 - 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.
aibot88