Soroban Contract Upgrade Safety Analyzer — Storage Layout and Interface Diffing Before Upgrade (starforge upgrade analyze)

[Nanle-code]

Problem Statement

starforge upgrade currently verifies that the deployed WASM hash matches the intended new bytecode (see closed issue #11), which protects against deploying the wrong bytes but says nothing about whether the new contract is actually safe to upgrade to. Soroban contract upgrades can silently break production state if a storage key changes type, a persistent storage entry is dropped, or a public function's signature changes in a way existing callers don't expect. There is currently no tooling in StarForge to catch this before an upgrade is executed on mainnet.

Proposed Solution

Add starforge upgrade analyze --current <old.wasm> --candidate <new.wasm>, which statically compares two compiled Soroban contracts and produces a structured upgrade-safety report:

• Interface diff: extract the contract's exported function spec (name, argument types, return type) from each WASM's embedded contract metadata (the same metadata already used by starforge contract generate-bindings) and diff them, flagging removed functions, changed argument/return types, and changed function names as breaking changes; added functions and unchanged signatures are reported as non-breaking.
• Storage key diff: statically analyze both WASM binaries' storage access patterns (instance/persistent/temporary key literals and their associated value types, to the extent recoverable from the compiled contract's metadata) and flag storage keys that are removed, or whose associated type appears to change — since a type change on an existing persistent key is a common source of upgrade corruption.
• Risk classification: each finding is tagged breaking, warning, or info, and the command exits non-zero if any breaking finding is present (suitable for CI gating an upgrade PR).
• Report output: human-readable table by default, --format json for CI, and --output <file> to save a permanent record of the analysis alongside the upgrade for audit purposes.

Technical Scope

• New src/utils/upgrade_analyzer.rs: WASM metadata extraction (reusing the existing contract-spec parsing used by bindings.rs/contract inspect), interface diff engine, best-effort storage key/type extraction, and risk classification rules.
• Extend src/commands/upgrade.rs with the analyze subcommand.
• Because full storage-type recovery from compiled WASM without source is inherently best-effort, the report must clearly distinguish "confirmed from contract metadata" findings from "heuristic, verify manually" findings rather than presenting both with equal confidence.
• Tests using paired fixture contracts (built two ways from the existing templates: an additive-only change, and a deliberately breaking change to a function signature and a storage key) verifying the analyzer correctly classifies each.

Acceptance Criteria

• Running analyze on two builds of the same template with only an added function reports zero breaking findings.
• Running analyze on two builds where a public function's argument type changed reports it as breaking, naming the specific function.
• --format json output validates against a documented JSON schema for downstream CI consumption.
• Exit code is non-zero exactly when a breaking finding is present.
• Documentation includes a recommended CI snippet gating merges to an upgrade PR on starforge upgrade analyze.

Estimated Scope

Approximately 700 lines of new Rust across the analyzer, CLI wiring, fixtures, and tests.

[neromtoobad]

Hi, I'd like to work on this issue. I shipped OrbitChain's timelock + multi-sig upgrade governance (PR #203) and its storage-layout discipline — append-only DataKey/contracterror enums with reserved discriminants precisely so upgrades never break encodings — so upgrade-safety analysis is the exact problem space I've been working in. I can deliver in 12 hrs. Looking forward to contributing.

[dragoncode-01]

Hi @Nanle-code,

I'd like to work on this issue.

I have experience building Rust-based blockchain tooling, working with the Stellar/Soroban ecosystem, and performing smart contract security audits. I've built developer tooling around smart contracts, analyzed compiled artifacts, and worked with Rust codebases where correctness and maintainability are essential. This upgrade safety analyzer is a valuable addition to StarForge because it extends verification beyond bytecode integrity to compatibility and upgrade risk analysis.

My implementation plan is to:

• Build an upgrade analysis module that extracts and compares contract metadata from both WASM artifacts.
• Reuse the existing contract specification parsing where possible to implement interface diffing for exported functions, identifying breaking versus non-breaking API changes.
• Implement best-effort storage key and storage type analysis, clearly distinguishing metadata-confirmed findings from heuristic observations.
• Design a structured risk classification system (breaking, warning, and info) with appropriate CLI exit codes for CI integration.
• Add support for human-readable output, JSON output with a documented schema, and file export.
• Integrate the analyzer into the existing starforge upgrade command.
• Write comprehensive tests using fixture contracts covering additive upgrades, interface-breaking changes, and storage layout changes.
• Update the documentation with usage examples and a CI workflow demonstrating how to gate upgrade PRs using the analyzer.

I enjoy building tooling that improves developer confidence and security, and I'll focus on making the analyzer accurate, well-tested, and easy to extend while clearly communicating the confidence level of each finding.

I'd be happy to contribute this feature.

[grantfox-oss]

🦊 GrantFox — @dragoncode-01 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #60)
2. Your PR will be reviewed by the StarsForges maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@dragoncode-01's PR #61 was approved and merged by @Nanle-code.

🏆 @dragoncode-01: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (592 total points). Track your full progress on GrantFox.

👏 Great work, @dragoncode-01! Keep contributing to StarsForges.