home / skills / multiversx / mx-ai-skills / diff_review

diff_review skill

safe

This skill helps you analyze diffs between versions of smart contracts, emphasizing upgradeability, regression testing, and data flow integrity.

npx playbooks add skill multiversx/mx-ai-skills --skill diff_review

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.1 KB

---
name: diff_review
description: Reviewing changes between versions of SCs (Upgradeability checks).
---

# Differential Review

This skill helps you analyze the difference between two versions of a codebase, focusing on security implications of changes.

## 1. Upgradeability Checks (MultiversX)
When reviewing a diff between `v1` and `v2` of a Smart Contract:
- **Storage Layout**:
    - *Critical*: Did the order of fields in a `struct` stored in a `VecMapper` or `SingleValueMapper` change?
    - *Result*: Usage of existing data will interpret bytes incorrectly (Memory Corruption).
    - *Fix*: Append new fields to the end of structs, never reorder.
- **Initialization**:
    - *Critical*: Does `v2` introduce new Storage Mappers?
    - *Check*: Are they initialized in `#[upgrade]`? (Remember `#[init]` is NOT called on upgrade).

## 2. Regression Testing
- **New Features**: Do they break old invariants?
- **Deleted Code**: Was a check removed? Why?

## 3. Workflow
1.  **Generate Diff**: `git diff v1..v2`.
2.  **Filter Noise**: Ignore formatting/style changes.
3.  **Trace Data**: Follow the flow of changed data structures.

Overview

This skill analyzes differences between two codebase versions with a focus on smart contract upgradeability and security impacts. It highlights storage layout changes, initialization gaps, and regression risks so maintainers can spot breaking upgrades quickly. The guidance is practical and oriented to actionable checks and fixes.

How this skill works

The skill inspects diffs to identify changes to storage structs, mappers, and initialization logic. It flags reordered or newly added fields in persisted structs, missing upgrade-time initialization for new storage mappers, and deletions that remove important checks. It also helps filter noise and trace data flows to assess behavioral regressions.

When to use it

Before deploying an upgraded smart contract version to production
When reviewing pull requests that modify persistent storage or initialization code
After adding or removing features that touch on invariants or access control
During release checklists that require upgrade safety validation

Best practices

Never reorder fields in structs that are serialized or stored; append new fields at the end
When adding storage mappers, add explicit initialization in the upgrade handler (#[upgrade]) since #[init] won’t run on upgrades
Run targeted regression tests for invariants and access control after any change
Filter out formatting and unrelated noise in diffs to focus security review on logic and storage
Trace the data flow of modified structures to ensure new code interprets existing bytes correctly

Example use cases

Compare v1 and v2 of a MultiversX smart contract to detect struct field reordering and missing upgrade init
Review a pull request that adds a new storage mapper to ensure it’s initialized during upgrade
Audit deletions that removed validation checks to understand potential invariant breaks
Create a release checklist that runs diff checks, focused regression tests, and manual storage-layout verification

FAQ

What exactly breaks if struct field order changes?

Reordering fields causes existing stored bytes to map to the wrong fields, creating memory corruption and incorrect state interpretation.

How do I ensure new storage mappers are safe on upgrade?

Add explicit initialization in the upgrade handler (#[upgrade]) and include regression tests that exercise the new mappers against existing state.