Make v1 migration idempotent (#2965)

* Make migrations idempotent

* Update CHANGELOG

Author: citizen-stig

CHANGELOG.md

@@ -87,6 +87,7 @@ Temporary section for maintaining breaking changes from individual PRs, which wi
   Receipt `effectiveGasPrice` and projected `gasUsed` are now unconditionally derived from the actual metered fee. 
   Forks that had set this to a non-zero future activation height must migrate; the new behavior is mandatory.
 - #2934 **Breaking Change**: Removes the `CHANGE_GAS_LIMIT_AFTER_HEIGHT` gas-limit fork. The `INITIAL_GAS_LIMIT` and `UPDATED_GAS_LIMIT` constants are replaced by a single `BLOCK_GAS_LIMIT` constant (test override env var `SOV_TEST_CONST_OVERRIDE_INITIAL_GAS_LIMIT` → `SOV_TEST_CONST_OVERRIDE_BLOCK_GAS_LIMIT`). Removes the `sequencer.height_for_gas_limit_computation` rate-limiter config field and the `ChainStateCapability::block_gas_limit` / `ChainState::block_gas_limit{,_at}` methods (use `<S as GasSpec>::block_gas_limit()` instead). The block gas limit is now constant for all heights; the per-block sequencer safeguards (preferred-sequencer pre-exec escrow, zero-bond preferred-sequencer penalization, and the slot-gas-limit pre-check) remain unconditionally enabled.
+- #2965 sov-migrations: the v1 (state_version 0->1) migration is now idempotent. Re-running it against an already-migrated DB (state_version >= 1) logs a message and exits Ok instead of erroring, so a restarted rollup that re-invokes the migration binary no longer fails.
 
 # 2026-04-01
 - #2670 **Breaking change** Remove `InnerVm` and `OuterVm` generic type parameters from `StateTransitionFunction` trait and all downstream types.

crates/utils/sov-migrations/src/v1.rs

@@ -182,6 +182,39 @@ where
     let pre_state_root = storage
         .get_root_hash(head_slot_number)
         .context("failed to read pre-migration state root")?;
+
+    // Idempotency guard: if the migration has already been applied (state_version is at or
+    // beyond the target), do nothing and exit successfully. This makes the migration safe to
+    // re-run, e.g. when a node restarts and re-invokes the migration binary.
+    let from_state_version = {
+        let value = state_version_value(chain_state);
+        match storage.get_accessory_unbound(value.slot_key(), Some(head_slot_number)) {
+            Some(slot_value) => value.decode_unwrap(&slot_value),
+            // Absent ⇒ version 0, mirroring `ChainState::state_version`'s `unwrap_or(0)`.
+            None => 0,
+        }
+    };
+    if from_state_version >= TARGET_STATE_VERSION {
+        eprintln!(
+            "v1 migration already applied: on-disk state_version is {from_state_version} \
+             (target {TARGET_STATE_VERSION}); nothing to do"
+        );
+        return Ok(crate::MigrationOutcome {
+            dry_run: options.dry_run,
+            db_path: db_path.display().to_string(),
+            pre_state_root: pre_state_root.to_string(),
+            post_state_root: pre_state_root.to_string(),
+            head_rollup_slot: head_slot_number.get(),
+            migration: MigrationReport {
+                from_state_version,
+                to_state_version: from_state_version,
+                accounts: sov_accounts::migrations::MigrationReport {
+                    entries_migrated: 0,
+                },
+            },
+        });
+    }
+
     let migration_data = collect(accounts, chain_state, &storage)?;
 
     let mut checkpoint = {

examples/demo-rollup/tests/migrations/mod.rs

@@ -39,6 +39,91 @@ struct KernelRoundtrip {
 
 #[tokio::test(flavor = "multi_thread")]
 async fn v1_migration_rewrites_live_demo_state() -> anyhow::Result<()> {
+    let (builder, storage_config, credential_id, account_address) =
+        build_and_force_v0_demo_state().await?;
+
+    let report = run_v1_migration(storage_config.clone())?;
+
+    assert!(!report.dry_run);
+    assert!(report.head_rollup_slot > 0);
+    assert_ne!(report.pre_state_root, report.post_state_root);
+    assert_eq!(
+        report.migration.from_state_version,
+        sov_migrations::v1::SOURCE_STATE_VERSION
+    );
+    assert_eq!(
+        report.migration.to_state_version,
+        sov_migrations::v1::TARGET_STATE_VERSION
+    );
+    assert_eq!(report.migration.accounts.entries_migrated, 1);
+
+    assert_migrated_state(storage_config, credential_id, account_address)?;
+
+    let restarted_rollup = builder.start().await?;
+    restarted_rollup.wait_for_node_synced().await?;
+    restarted_rollup.shutdown().await?;
+
+    Ok(())
+}
+
+/// Re-running the migration against an already-migrated database must be a graceful no-op: it
+/// exits `Ok` without changing state, so a restarted node that re-invokes the migration binary
+/// does not fail.
+#[tokio::test(flavor = "multi_thread")]
+async fn v1_migration_is_idempotent() -> anyhow::Result<()> {
+    let (_builder, storage_config, credential_id, account_address) =
+        build_and_force_v0_demo_state().await?;
+
+    // First run actually applies the migration, establishing the already-migrated precondition.
+    let first = run_v1_migration(storage_config.clone())?;
+    assert_eq!(
+        first.migration.accounts.entries_migrated, 1,
+        "first run should migrate the seeded legacy account"
+    );
+    assert_ne!(
+        first.pre_state_root, first.post_state_root,
+        "first run should change the state root"
+    );
+
+    // Second run sees state_version already at the target and must do nothing.
+    let second = run_v1_migration(storage_config.clone())?;
+    assert_eq!(
+        second.migration.from_state_version,
+        sov_migrations::v1::TARGET_STATE_VERSION,
+        "second run should observe the already-migrated state version"
+    );
+    assert_eq!(
+        second.migration.to_state_version,
+        sov_migrations::v1::TARGET_STATE_VERSION,
+        "second run should leave the state version at the target"
+    );
+    assert_eq!(
+        second.migration.accounts.entries_migrated, 0,
+        "second run must not migrate any accounts"
+    );
+    assert_eq!(
+        second.pre_state_root, second.post_state_root,
+        "second run must not change the state root"
+    );
+    assert_eq!(
+        second.pre_state_root, first.post_state_root,
+        "state must be unchanged between the first and second runs"
+    );
+
+    assert_migrated_state(storage_config, credential_id, account_address)?;
+
+    Ok(())
+}
+
+/// Builds a live demo rollup, advances it past genesis with one transfer, shuts it down, and
+/// rewrites its head into a state-version-0 database carrying a legacy account entry. Returns the
+/// shutdown builder (for an optional restart), the storage config, and the seeded account ids.
+async fn build_and_force_v0_demo_state() -> anyhow::Result<(
+    RollupBuilder<Rollup>,
+    RollupDbConfig,
+    CredentialId,
+    <DemoRollupSpec as Spec>::Address,
+)> {
     let credential_id = credential_id(0x11);
     let account_address = account_address(0x22);
 
@@ -74,37 +159,23 @@ async fn v1_migration_rewrites_live_demo_state() -> anyhow::Result<()> {
 
     prepare_v0_state_with_legacy_account(storage_config.clone(), credential_id, account_address)?;
 
+    Ok((builder, storage_config, credential_id, account_address))
+}
+
+/// Runs the v1 migration against `storage_config` with a fresh runtime, returning the outcome.
+fn run_v1_migration(
+    storage_config: RollupDbConfig,
+) -> anyhow::Result<sov_migrations::MigrationOutcome<sov_migrations::v1::MigrationReport>> {
     let mut runtime = DemoRuntime::<DemoRollupSpec>::default();
     let runtime_inner = &mut *runtime;
-    let report = sov_migrations::v1::run_with_options::<DemoRollupSpec, Hasher>(
+    sov_migrations::v1::run_with_options::<DemoRollupSpec, Hasher>(
         sov_migrations::MigrationOptions {
-            storage: storage_config.clone(),
+            storage: storage_config,
             dry_run: false,
         },
         &mut runtime_inner.accounts,
         &mut runtime_inner.chain_state,
-    )?;
-
-    assert!(!report.dry_run);
-    assert!(report.head_rollup_slot > 0);
-    assert_ne!(report.pre_state_root, report.post_state_root);
-    assert_eq!(
-        report.migration.from_state_version,
-        sov_migrations::v1::SOURCE_STATE_VERSION
-    );
-    assert_eq!(
-        report.migration.to_state_version,
-        sov_migrations::v1::TARGET_STATE_VERSION
-    );
-    assert_eq!(report.migration.accounts.entries_migrated, 1);
-
-    assert_migrated_state(storage_config, credential_id, account_address)?;
-
-    let restarted_rollup = builder.start().await?;
-    restarted_rollup.wait_for_node_synced().await?;
-    restarted_rollup.shutdown().await?;
-
-    Ok(())
+    )
 }
 
 fn prepare_v0_state_with_legacy_account(