Skip to content

feat(migrate): implement storage layout introspection and hazard analysis helpers - #1040

Merged
Nanle-code merged 1 commit into
Nanle-code:masterfrom
ibrahimmujidah1-stack:feat/803-storage-layout-introspection-helpers
Sep 25, 2026
Merged

Nanle-code merged 1 commit into
Nanle-code:masterfrom
ibrahimmujidah1-stack:feat/803-storage-layout-introspection-helpers

Conversation

@ibrahimmujidah1-stack

Copy link
Copy Markdown

Summary

Implements automated storage layout introspection and migration hazard analysis for Soroban contracts:

  • Introspection Engine (\src/utils/storage_layout.rs): Parses Rust contract definitions and specs to extract storage keys, storage tiers (\Instance, \Persistent, \Temporary), value types, and \DataKey\ enum variants with discriminants.
  • Hazard Detection: Automatically detects breaking changes between contract versions (removed keys, type mutations, storage tier shifts, discriminant renumbering, and uninitialized keys).
  • Automated Rule Generation: Generates starter migration rules files ready for dry-run testing.
  • CLI Subcommands (\src/commands/migrate.rs):
    • \starforge migrate introspect \ (with --json\ output)
    • \starforge migrate hazards --old --new \ (with --json\ and --output-rules )
  • Unit Tests: Full test coverage of layout extraction, breaking hazard detection, and safe layout verification.
  • Documentation (\docs/STORAGE_LAYOUT_MIGRATIONS.md): Guide on introspecting layouts, resolving migration hazards, and running state migrations safely.

Closes #803

@drips-wave

drips-wave Bot commented Sep 25, 2026

Copy link
Copy Markdown

@ibrahimmujidah1-stack Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

…ysis helpers

- Implement StorageLayoutIntrospector in src/utils/storage_layout.rs to extract storage keys, tiers, and DataKey enums
- Implement hazard detection (removed keys, type mutations, storage tier shifts, discriminant collisions, uninitialized keys)
- Implement automated starter migration rules generation
- Add 'starforge migrate introspect' and 'starforge migrate hazards' CLI subcommands in src/commands/migrate.rs
- Add unit tests for layout extraction, hazard detection, and safe migrations
- Document usage and migration workflows in docs/STORAGE_LAYOUT_MIGRATIONS.md

Closes Nanle-code#803
@ibrahimmujidah1-stack
ibrahimmujidah1-stack force-pushed the feat/803-storage-layout-introspection-helpers branch from e185670 to 9096f75 Compare September 25, 2026 08:29
@Nanle-code
Nanle-code merged commit c1f00a8 into Nanle-code:master Sep 25, 2026
17 of 44 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Advancement] Implement storage layout introspection helpers for migrations

2 participants