[Feature Request] Git Diff-Style Package Upgrade History

[mshakeg]

Overview

I would like to propose adding a git diff-style package upgrade history feature to the Aptos Explorer. This would allow users to easily track and visualize changes between different versions of Move packages deployed on the blockchain, significantly improving transparency, security auditing, and developer experience.

Motivation

Currently, the Aptos Explorer only displays the latest version of verified package source code, with each module appearing as its own file. While this provides a snapshot of the current state, it lacks historical context about how packages have evolved over time.

As Aptos supports package upgrades, having a visual diff tool would:

1. Enhance transparency - Make code changes between versions visible and accessible to all stakeholders
2. Improve security - Help auditors and users identify potentially problematic changes
3. Aid debugging - Enable developers to track when and how code has evolved
4. Support governance - Provide context for voting on protocol changes
5. Expedite code reviews - Simplify review processes for upgraded packages

Proposed Solution

A comprehensive diff visualization system that:

1. Shows a timeline of all package upgrades
2. Provides git-style diffs between consecutive versions
3. Works for both verified source code and unverified bytecode (via decompilation)
4. Integrates with the existing explorer interface

Detailed Requirements

Core Functionality

• Version History Timeline: Display a chronological history of all package upgrades
• Module-Level Diffs: Show changes to individual modules within a package
• Diff Highlighting: Use color coding (additions in green, deletions in red) to highlight changes
• Decompiler Integration: Leverage the Revela decompiler by Verichains for unverified packages
• Metadata Display: Show upgrade timestamps, transaction hashes, and upgrade policies

User Interface

• Version Selector: Allow users to select which versions to compare
• Module Navigator: Tree view showing which modules changed between versions
• Diff View Modes: Support both side-by-side and inline diff viewing options
• Code Folding: Collapsible sections for unchanged code to focus on differences
• Visual Indicators: Clear labeling for verified source vs. decompiled code

Advanced Features (Future Phases)

• Function-Level Navigation: Jump directly to specific functions within diffs
• Semantic Change Detection: Highlight breaking vs. non-breaking changes
• Dependency Impact Analysis: Show how changes might affect dependent packages
• Annotation System: Allow developers to add notes explaining upgrade rationale

Requirements

• Package upgrade timeline view showing all versions
• Basic diff highlighting between consecutive versions
• Module-level change summaries with transaction metadata
• Integration with Revela for decompilation of unverified packages
• Upgrade policy compliance indicators
• Clear identification of newly added structs and functions

Technical Considerations

• Storage: Database extensions to track historical package versions
• Performance: On-demand diff generation to ensure responsiveness
• Decompiler API: Standardized connection to Revela for unverified packages
• Caching Strategy: Cache frequently viewed diffs and decompiled code

User Experience Examples

Example 1: Developer Debugging

A developer using a third-party package notices unexpected behavior after an upgrade. Using the diff view, they quickly identify that while the public function signatures remain unchanged (as required by the compatibility policy), the internal implementation logic of a critical function has been modified, changing its behavior in edge cases.

Example 2: Security Audit

An auditor reviews a protocol upgrade by examining the diff to verify new functionality added to the package. They can easily distinguish between existing code and newly added functions/structs, ensuring that compatibility requirements are maintained while also thoroughly reviewing the security implications of the new code paths.

Example 3: Community Governance

DAO members review a proposed upgrade before voting(or contributing signatures on a package owned by a multisig account), focusing specifically on changes to implementation logic and new functionality. The diff view clearly highlights that no existing structs were modified and public interfaces remain stable, while showing exactly how internal algorithms have been optimized or fixed. This will require UIs such as msafe to show this code diff and they could rely on an aptos maintained API to get this.

Example 4: Compatibility Verification

A developer preparing to build on top of a frequently updated package uses the diff history to validate the package maintainer's adherence to compatibility requirements over time, building confidence that future upgrades won't break their integrations.

Conclusion

A git diff-style package upgrade history would significantly enhance the utility of the Aptos Explorer, bringing much-needed transparency and context to on-chain code evolution. By integrating with tools like Revela, this feature could provide value even for unverified packages, making the Explorer a more comprehensive tool for developers, auditors, and users alike.