# State migration in filecoin

State migration is a process in the filecoin network where the actor's StateTree contents are transformed from an older form to a newer form. There are possibly two situations where state migration is needed. First, is when the actor state change is required and second is when there's usually a breaking change between how the actors behaves and functions between network upgrades.

## Why network version 12 migration was required?
There's a good blog post on the official filecoin blog about why this upgrade is beneficial to the performance of the network:
https://filecoin.io/blog/posts/filecoin-network-v12/

# State migration in forest
Forest currently does not have state migration implemented. As a result a forest node will not be able to process the tipset at the network upgrade epoch, only the tipsets before and after that epoch.

At present, a manual intervention is required which requires importing a snapshot post the migration epoch and continue from there. It would be great if forest does this in code and so the PR.

## Relevant Issue/PR:

https://github.com/ChainSafe/forest/tree/creativcoder/state-migration [WIP]

#### Points on https://github.com/ChainSafe/forest/issues/1039

- Implement current state migration. Ideally aim to have a generic re-usable migration code, where we can just plug in the list of actors that need migration and their respective migration function.
- How to test the state migration code?
The idea is to get a snapshot where the nv12 upgrade happens. We run forest with the snapshot and expect the migrtion to trigger at the given epoch.
- Parallelize the root state migration.
- Measure and compare the time in state migration with lotus and forest.

## Pre-requisite terminologies

### Actor

An actor is an entity in the filecoin network; equivalent to a smart contract in Ethereum. Example of an actor include: miner actor, cron actor, init actor. Each of these actors will hold some state, for the lifecycle of their existence in the filecoin network. Any change to current state of the filecoin blockchain is triggered through an actor method invocation.

### The cron actor
The cron actor is a built-in singleton actor that sends messages to other registered actors at the end of each epoch to perform important book keeping operations.

### Actor state

Every actor will store some state that is changed over time due to messages/transactions sent across the network. The state tree is represented by a Hash Array Mapped Trie data structure in code. A HAMT<Cid, ActorState>. The actor state is represented by `ActorState` structure.

### What does `network ` mean in network version 12 upgrade?
TODO

### What does `actor` mean when we say actorsv5 upgrade?
It's mainly referring to the state of the actor.

## How does state migration happen?

State migration is done in the event when a hard fork happens (be it actor version updates or a network update) on the network. The high level idea is to iterate over the state of each actor at the given epoch and write as the new state along with any specific changes to the respective state (if any). This involves iterating over each of the hamt nodes which stores the state and write them to the db (rocksDB in forest's case).

An important thing to note about state migration is that, every network upgrade need not require a state migration. But every state migration
implies that there is a network upgrade/hard fork.

State migration happens at specific epochs: https://github.com/ChainSafe/forest/blob/ec2/state-migration-v3/vm/interpreter/src/vm.rs#L210 Usually these epochs are decided upon by the community and upon reaching consensus they are added in the implementation.

For network version 12 state migration, we need to define the epoch as `UPGRADE_ACTORS_V4_HEIGHT` in the forest and accordingly hook the top level root migration code to migrate_state function in vm.rs: https://github.com/ChainSafe/forest/blob/415a5649733c4956df20e55455cd022934bf779b/vm/interpreter/src/vm.rs#L175

## Implementation in forest [WIP]
We have a [state_migration](https://github.com/ChainSafe/forest/tree/59ed6d24f077ecda8922134f35ba6bdb48ef07d5/vm/state_migration) crate created within vm. For network v12, we need to migrate the actor states from v3 to v4. The [actor_interface](https://github.com/ChainSafe/forest/tree/creativcoder/state-migration/vm/actor_interface) crate is where we re-export the prior actor versions for backward compatibility.

### Job execution design

We use a thread pool for job execution. In addition to that there are channels that handle asynchronous processing of events sent to these threads. Because of how move semantics work we iterate over each actor state and queue messages in these channels.

### Blockers

BlockStore is not Sync + Send: State migration needs an immutable ref to Blockstore, but since the jobs are spawned on different threads, we cannot pass BlockStore as part of a migration job instance.

### Testing state migration

We test state migration with a snapshot which contains the 712320 epoch point. We run