feat: nv28 base migration

[LesnyRumcajs]

Summary of changes

Changes introduced in this pull request:

• added base migration for nv28

Reference issue to close (if applicable)

Closes

Other information and links

Change checklist

• I have performed a self-review of my own code,
• I have made corresponding changes to the documentation. All new code adheres to the team's documentation standards,
• I have added tests that prove my fix is effective or that my feature works (if possible),
• I have made sure the CHANGELOG is up-to-date. All user-facing changes should be reflected in this document.

Outside contributions

• I have read and agree to the CONTRIBUTING document.
• I have read and agree to the AI Policy document. I understand that failure to comply with the guidelines will lead to rejection of the pull request.

Summary by CodeRabbit

• Chores
  • Added infrastructure and migration logic for the NV28 network upgrade. This prepares the system for handling state transitions but is not yet active.

[coderabbitai]

Walkthrough

This PR introduces a new NV28 state migration module that registers migrators for built-in actors and performs state tree migration. It adds module declarations, a migration orchestration function, and system state definitions to support the NV28 network upgrade.

Changes

Cohort / File(s)	Summary
State Migration Module Setup src/state_migration/mod.rs, src/state_migration/nv28/mod.rs	Declares new nv28 module and establishes migration entry point via public re-export of run_migration. Wires up system state definitions for v17 and v18, and registers system/verifier implementations.
Migration Implementation src/state_migration/nv28/migration.rs	Implements add_nv28_migrations method to register per-actor migrators and run_migration function that orchestrates the full NV28 migration by loading the new manifest, initializing a state migrator with verification, applying migrations to the state tree, and returning the new state root CID.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant run_migration
    participant ChainConfig
    participant Blockstore as Blockstore
    participant StateMigration
    participant StateTree
    
    Client->>run_migration: run_migration(chain_config, blockstore, state, epoch)
    run_migration->>ChainConfig: Lookup manifest CID from height_infos
    run_migration->>Blockstore: Validate manifest exists
    run_migration->>Blockstore: Load BuiltinActorManifest
    run_migration->>StateMigration: Create with Verifier (Arc)
    run_migration->>StateMigration: add_nv28_migrations(store, state, new_manifest)
    StateMigration->>Blockstore: Load current StateTree from root CID
    StateMigration->>Blockstore: Load system actor manifest
    StateMigration->>StateMigration: Register per-actor migrators
    run_migration->>Blockstore: Load input StateTree
    run_migration->>StateMigration: migrate_state_tree (V5, epoch)
    StateMigration->>StateTree: Apply registered migrators
    run_migration->>Client: Return new state root CID

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: nv27 skeleton & base migration #6023: Introduces the analogous NV27 state migration module with the same pattern of implementing add_nv27_migrations and run_migration for the preceding network upgrade.

Suggested reviewers

• akaladarshi
• hanabi1224
• sudo-shashank

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly summarizes the main change: adding base migration logic for the NV28 upgrade across three new files with appropriate API exports.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch nv28-base-migration

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch nv28-base-migration

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/state_migration/mod.rs`:
- Line 31: The new nv28 module was added but not wired into get_migrations, so
run_state_migrations never reaches the NV28 migration; update the get_migrations
function to include the nv28 migration in the appropriate network branches (the
same branches that should execute NV28) by adding the nv28 migration entry
alongside the existing migrations so that Height::Xxx is returned/executed for
those networks; ensure you reference the nv28 module and include it in each
network match arm in get_migrations where NV28 should run.

In `@src/state_migration/nv28/migration.rs`:
- Around line 31-42: The code calls several fallible functions without
contextual error messages; wrap each call with anyhow context so failures
identify the step: add .context("creating StateTree from root") to
StateTree::new_from_root(store.clone(), state), .context("getting system actor
from state tree") to state_tree.get_required_actor(&Address::SYSTEM_ACTOR),
.context("loading old SystemState from store") to
store.get_cbor_required::<SystemStateOld>(&system_actor.state),
.context("loading current builtin manifest") to
BuiltinActorManifest::load_v1_actor_list(store, &current_manifest_data), and add
context when retrieving new_manifest.get(name) and when calling
self.add_migrator(code, nil_migrator(new_code)); apply the same pattern for the
similar fallible calls around lines 79-85 so any error clearly states which
migration step failed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: a831001e-2566-4ddb-8dbf-3cac1f59b58b

📥 Commits

Reviewing files that changed from the base of the PR and between 101befd and 07e06cf.

📒 Files selected for processing (3)

• src/state_migration/mod.rs
• src/state_migration/nv28/migration.rs
• src/state_migration/nv28/mod.rs

[codecov]

Codecov Report

❌ Patch coverage is 0% with 45 lines in your changes missing coverage. Please review.
✅ Project coverage is 63.84%. Comparing base (101befd) to head (07e06cf).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/state_migration/nv28/migration.rs	0.00%	45 Missing ⚠️

Additional details and impacted files

Files with missing lines	Coverage Δ
src/state_migration/mod.rs	80.00% <ø> (ø)
src/state_migration/nv28/migration.rs	0.00% <0.00%> (ø)

... and 4 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 101befd...07e06cf. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.