Move Code Review

Finding Registry

Each check has a unique ID, a fixed severity, and a category. This registry is the authoritative reference. When reporting findings, always use the exact ID and its pre-assigned severity — do not override.

SEC — Security

DES — Design & Architecture

PAT — Capability & Version Patterns

TST — Testing & Validation

QA — Code Quality & Maintainability

CFG — Configuration & Constants

Source data: The finding registry above is distilled from 40+ production Move contract reviews. For the raw frequency analysis and full issue taxonomy, see references/past_reviews.md.

Analysis Workflow

Scoped reviews: When the user requests a focused review (specific module, specific function, or specific check categories like "access control and arithmetic safety"), run only the relevant phases and report only findings whose IDs match the requested categories. For example, if the user asks for SEC-AC and SEC-AR checks, report only SEC-AC-* and SEC-AR-* findings — do not include PAT-, DES-, TST-, QA-, or CFG-* findings even if you notice them. If you discover a noteworthy issue outside the requested scope during analysis, mention it briefly in the "Reviewed and Cleared" section as an adjacent observation, not as a formal finding. Always run Phase 1 Discovery to establish context, then jump to the relevant phase(s).

Clean packages: If the full scan produces zero findings, skip the Findings Table and Detailed Findings sections. Report a "Clean" risk rating and focus on the Strengths section. A clean report is a valid and valuable outcome.

Phase 1: Discovery

1. Locate the Move project

   • Find Move.toml in current directory or user-specified path
   • Glob for all .move files under sources/
   • Identify test modules (*_tests.move or #[test_only] modules)

2. Build a structural map

   • List all modules and their public/public(package)/entry/private functions
   • Identify all struct definitions, especially those with key/store abilities (objects and capabilities)
   • Map shared objects (created via share_object) vs owned objects
   • Identify all transfer::transfer and transfer::public_transfer call sites
   • Count lines per module

3. Identify critical zones

   • Functions that handle Coin, Balance, or custom token types
   • Functions gated (or not) by capability parameters
   • All arithmetic operations: division, type casts, multiplication chains
   • All loops and their termination conditions

Phase 2: Security Scan (SEC checks)

Run all SEC checks from the Finding Registry:

Access Control (SEC-AC-1, SEC-AC-2, SEC-AC-3):

• For each public and entry function, determine if it modifies shared state or creates/destroys objects
• If it does, verify it requires a capability parameter (&AdminCap, &OperatorCap, etc.) or uses the witness pattern
• Check if any authorization helper functions return bool — these MUST be wrapped in assert!() at the call site, not left unchecked
• Special attention to mint, create, burn, update, set_*, remove_* function names

Arithmetic Safety (SEC-AR-1, SEC-AR-2, SEC-AR-3):

• Find all / division operators and div function calls. For each, trace the denominator back to verify a non-zero assertion exists before the division
• Find all as type casts between integer types. For narrowing casts (u128→u64, u64→u32, u64→u8), verify an upper-bound check exists
• Find multi-step calculations where intermediate results are stored. Check for premature flooring. Recommend mul_div patterns for precision

Logic Errors (SEC-LG-1, SEC-LG-2):

• For security-gating logic (if/else branches that allow/deny), verify the condition matches the intent described by the function name and doc comment
• For set_* and update_* functions, verify the field being modified matches the function name

Phase 3: Design & Architecture Scan (DES checks)

Object Model (DES-OM-1, DES-OM-2, DES-OM-3):

• Find all VecMap and VecSet usages. If the collection is populated by user actions (not bounded by the developer), flag as S2
• Find all shared objects. For each, count how many functions take &mut access. If the ratio of &mut to & exceeds 2:1 in non-admin functions, flag contention risk
• Check for multiple Publisher object creations. Recommend shared Registry pattern if found

Data Structures (DES-DS-1, DES-DS-2, DES-DS-3):

• Find struct fields typed as address — if the field name contains id, object, nft, or references an on-chain entity, flag as should-be-ID
• Find numeric constants or field values used in if comparisons for state branching. If a number represents a logical state, recommend Option or enum pattern
• Check for LinkedTable usage — if the table is not iterated or if order doesn't matter, simpler alternatives exist

Function Design (DES-FN-1, DES-FN-2, DES-FN-3):

• Find functions that call transfer::transfer or transfer::public_transfer on objects they create or receive. If the function could instead return the object, flag it
• Find functions that accept vector<T> and loop over it to perform repeated single operations. Consider if this is a batch function that PTB loops would replace
• Find single-line wrapper functions that delegate entirely to another function. If the wrapper adds no logic, authorization, or type transformation, flag it

Blind Transfers (DES-BT-1):

• Find all transfer::transfer calls where the recipient is an object ID (not a user address). Verify a corresponding receive function exists in the codebase
• For derived objects, verify the contract checks existence before transferring to them

Phase 4: Pattern Scan (PAT checks)

Capability Patterns (PAT-CP-1, PAT-CP-2):

• Find structs used for authorization that don't have key ability (Solidity-style role mappings in tables instead of owned capability objects)
• Find public(package) functions. For each, check if any external module in the package calls it. If only the declaring module calls it, it should be private

Version Management (PAT-VM-1, PAT-VM-2):

• Check for a VERSION constant in the package. If the package appears to be designed for upgradeability (has admin functions, uses dynamic fields for extensibility), flag missing version tracking
• Check for version-check assertions in state-modifying functions
• Flag migrate or migration functions in packages with no evidence of a prior version

Phase 5: Testing Scan (TST checks)

Coverage (TST-CV-1, TST-CV-2):

• Cross-reference functions identified as security-critical in Phase 2 against test modules. If a security-critical function has no test calling it, flag S2
• Check if test modules contain any #[test, expected_failure] tests. If zero exist, flag missing unhappy-path coverage

Validation (TST-VL-1, TST-VL-2, TST-VL-3):

• For functions that access vectors/VecMaps by index, check if tests exercise the empty-collection case
• For all loops found in Phase 1, check if tests exercise the termination boundary
• For time-based logic, check if tests cover zero-duration, epoch-boundary, and overflow scenarios

Phase 6: Quality & Config Scan (QA, CFG checks)

Unused Code (QA-UC-1):

• Build a call graph from all public and entry functions. Find public(package), private, and #[test_only] functions that are never called from any reachable path. Distinguish:
  • Dead code (no callers at all) → recommend removal
  • Test-only reachable code → verify #[test_only] annotation is present
  • Possibly-incomplete feature → flag for clarification

Module Organization (QA-MO-1, QA-MO-2, QA-MO-3):

• Count lines per module (excluding blank lines and comments). Flag >500
• Check if related constants/types are co-located with the logic that uses them
• Check for logic that requires reading 3+ modules to understand a single operation

Naming & Documentation (QA-NM-1, QA-NM-2, QA-NM-3, QA-DC-1, QA-DC-2):

• Scan for generic names in function parameters and local variables
• Check time-related field names for unit suffixes
• Check for struct names that shadow Sui framework types (e.g., custom CoinMetadata<T>, TreasuryCap, Publisher)
• Count public functions without /// doc comments
• Grep for TODO, FIXME, HACK, XXX in non-test files

Configuration (CFG-HC-1, CFG-HC-2, CFG-MN-1, CFG-MD-1):

• Find @0x... address literals outside of init and #[test] functions
• Find numeric literals in logic (not in constant definitions) that appear to represent limits or thresholds
• Check for freeze_object calls on metadata objects — verify all fields are set beforehand

Reporting Format

Present findings using this exact structure. The structure is designed for both human readability and automated metrics extraction.

Header

## Move Code Security & Architecture Review

**Package**: [package name from Move.toml]
**Modules reviewed**: [count] ([list of module names])
**Date**: [current date]
**Reviewer**: Claude Code (move-code-review skill)

Findings Table

### Findings Summary

| # | ID | Severity | Weight | Category | File | One-line Summary |
|---|-----|----------|--------|----------|------|-----------------|
| 1 | SEC-AC-1 | S1 | 10 | Access Control | sources/admin.move:45 | Unprotected public mint function |
| 2 | SEC-AR-1 | S1 | 10 | Arithmetic | sources/pool.move:112 | Division by zero in fee calculation |
| ... | ... | ... | ... | ... | ... | ... |

Detailed Findings

For each finding, use this exact template:

---

### [#N] [ID]: [One-line Summary]

**Severity**: [S1 Critical | S2 High | S3 Medium | S4 Low] (Weight: [N])
**Category**: [Full category name]
**File**: `[path]:[line]`

**Issue**: [Precise description of what is wrong]

**Impact**: [What could go wrong if this is not fixed — concrete scenario]

**Current code**:
```move
// The problematic code snippet

Recommended fix:

// The corrected code snippet or pattern to follow

Rationale: [Why this fix is appropriate — reference to Move patterns if relevant]

### Score Summary

```markdown
### Risk Score

| Severity | Count | Weight Each | Subtotal |
|----------|-------|-------------|----------|
| S1 Critical | N | 10 | N×10 |
| S2 High | N | 7 | N×7 |
| S3 Medium | N | 4 | N×4 |
| S4 Low | N | 2 | N×2 |
| **Total** | **N** | | **X** |

**Risk Rating**: [Critical / High / Moderate / Low / Clean]
- Critical: Any S1 finding, OR Total ≥ 40
- High: Any S2 finding (no S1), OR Total ≥ 20
- Moderate: Total ≥ 8 (no S1, no S2)
- Low: Total > 0 (S3/S4 only)
- Clean: Total = 0

Positive Findings

### Strengths
- [What is done well — be specific]

Next Steps

### Recommended Next Steps
1. Fix all S1 Critical findings before any deployment
2. Address S2 High findings before mainnet deployment
3. Review S3 Medium findings for design improvements
4. Consider S4 Low findings for long-term code health
5. Run `/move-code-quality` for syntax and idiom compliance

Guidelines

1. Use exact Finding IDs — Always reference the registry ID (e.g., SEC-AC-1). Never invent new IDs. If a finding does not match any registered check, report it under the closest matching ID with a note.
2. Never override severity — The severity is pre-assigned in the registry. Report exactly as defined. If you believe a specific instance is less severe in context, note it in the Rationale but keep the assigned severity.
3. Be specific — Always include file paths and line numbers. Never give generic advice without pointing to the exact code.
4. Show concrete fixes — Every finding must include a "Recommended fix" code snippet or clear pattern description.
5. Explain impact — Describe what could go wrong in a concrete scenario, not abstract risk.
6. Do not duplicate move-code-quality — Do not flag: module label syntax, import style, method syntax vs function syntax, macro usage (do!, fold!, etc.), struct naming conventions (Cap suffix, event tense), getter naming, test attribute merging, or test naming conventions. Those belong to /move-code-quality.
7. Acknowledge strengths — Always include at least one positive finding. Good security patterns, clean architecture, and thorough testing deserve recognition.
8. Multi-package awareness — When analyzing a workspace with multiple packages, check public(package) callers across all packages before flagging PAT-CP-2.
9. Context over rules — If a VecMap is provably bounded (e.g., enum-like set of 5 values), do not flag DES-OM-1. Use judgment on context, but document your reasoning.
10. Order findings by severity — List S1 findings first, then S2, S3, S4. Within the same severity, order alphabetically by category ID.
11. Suppress false positives — If you inspect a potential finding and determine it's a false positive (e.g., a denominator provably non-zero due to an earlier guard, or a VecMap bounded by design), do not include it in the Findings Table. If the suppressed finding is S1 or S2, briefly note it in a "Reviewed and cleared" section after Strengths so the reader knows it was considered.

Interactive Follow-up

After presenting the review:

• Offer to fix Critical and High findings automatically
• Provide deeper explanations for any specific finding
• Discuss architectural alternatives for Design findings
• Help write tests for identified TST gaps

Example Interactions

User: "Review this Move package for security issues" You: [Run the full analysis workflow, produce the complete report with findings table, detailed findings, and risk score]

User: "Check the access control in my staking module" You: [Run Phase 1 discovery + Phase 2 SEC-AC checks only on the specified module, produce a focused report]

User: "Is this function safe?" You: [Run SEC checks on the specific function, check its callers and callees, produce a scoped report]

User: "What's the risk score for this package?" You: [Run full scan, produce the Findings Summary table and Risk Score section — skip detailed findings unless asked]