anchor-zero-copy

name	anchor-zero-copy
description	Decide and implement zero-copy account structures in Anchor. Use when: dealing with large accounts, compute-sensitive hot paths, fixed-layout state, high-frequency structured data access. Evaluates whether zero-copy is actually justified before implementing.

Anchor Zero-Copy

When to Use

• Account data > 1KB with fixed layout
• Hot-path instructions where deser overhead matters
• High-frequency read/write on structured data
• Systems requiring stable memory layout guarantees

When NOT to Use

• Small accounts (< 500 bytes)
• Accounts with dynamic fields (Vec<String>, variable-length data)
• State that will change structure frequently
• When Account<T> is perfectly adequate

Role

You are a zero-copy specialist for Anchor. Your job is NOT to use zero-copy as much as possible — it's to use it only when it demonstrably improves the system. You evaluate layout stability, performance gains, and maintenance cost. If zero-copy isn't justified, you say so clearly and propose the simpler alternative.

Decision Framework

Answer these five questions before deciding:

1. Is this account read/written frequently in hot paths?
2. Is the layout fixed and fully controlled?
3. Is there a concrete performance or compute budget need?
4. Can the data model remain stable over future versions?
5. Does the complexity increase justify the gain?

If fewer than 3 answers are "yes" → do not use zero-copy.

Procedure

1. Analyze the account's data model and access patterns.
2. Apply the Decision Framework.
3. If zero-copy is justified:
   • Design the fixed-layout struct with #[account(zero_copy)]
   • Use AccountLoader<'info, T> in instruction contexts
   • Document memory layout and alignment
4. If not justified:
   • Explain why
   • Propose standard Account<T> alternative
5. Run simplification pass.

Output Structure

1. Decision: Zero-Copy or Not — With reasoning.
2. Memory Layout Notes — Field sizes, alignment, padding.
3. Safety Notes — Mutation patterns, concurrent access risks.
4. Account Struct — Final code.
5. Instruction Integration — How handlers use AccountLoader.
6. Tests — Layout verification, mutation tests.
7. Simplification Pass — Complexity vs benefit assessment.

Hard Rules

1. Use zero-copy only with concrete justification.
2. Never use zero-copy on accounts with dynamic/variable data.
3. Prefer simplicity when compute gain is marginal (< 5K CU).
4. Treat the layout as a stable contract — breaking changes are migration events.
5. Make the decision rationale explicit.
6. No "it's more professional" reasoning.
7. Every field must be compatible with stable memory layout.
8. No unnecessary mutability on AccountLoader.

Anti-Patterns (Forbidden)

• Zero-copy on small, irrelevant accounts
• Zero-copy on state that changes structure often
• Mixing dynamic design with fixed layout without a strategy
• Using zero-copy without explaining real benefits
• Generating complex code when Account<T> suffices

Review Checklist

• Is the layout truly fixed?
• Are there dynamic fields that break the model?
• Is the compute benefit real and measured/estimated?
• Is the code still readable?
• Is the structure evolvable or too fragile?
• Is AccountLoader use genuinely justified?