# Migration from Substrate independent chain to a Parachain
The following is a guide for teams that want to transition from a live Substrate independent chain to a Parachain.

## Terminology
It is key to understand the terminology used in the following guide to perform the needed actions in the correct way.
- **Substrate Independent Node**. The Node that is currently being run by the project as a Substrate Independent Chain.
- **Substrate Independent Runtime**. The Runtime that is currently being run by the project as a Substrate Independent Chain.
- **Solo<>Para Node**. Substrate Node that has the ability to produce blocks with different consensus algorithms given a condition.
- **Seedling Node**. The Node that the parachain will initially have to author blocks before the transition but after becoming a parachain.
- **Seedling Runtime**. The runtime of the parachain that will be registered on the relay chain and will then be merged with the existing Substrate Independent Chain. [Seedling Runtime can be found here](https://github.com/paritytech/cumulus/tree/master/polkadot-parachains/seedling).

## Migration Process
The Migration Process will be leveraging the flexibility of a Substrate Node as well as the Relay Chain - Parachain architecture where the Relay Chain finalizes blocks of a Parachain through a specific Proof Of Validity (POV) that this provides.

To achieve this, teams will need to:
1. Transition their current Substrate Independent Nodes to a Solo<>Para Node.
2. Secure a Relay Chain slot with a Seedling Runtime.

### Solo<>Para Node
This node has the ability to run different consensus algorithm and switch when a given condition is met. For that reason, teams will need to upgrade to this particular, which will be triggered when the time comes to switch to a consensus algorithm suited for being a parachain.

**`TODO: ADD CODE FOR THE CONDITION`**

### Seedling Parachain
This very specific runtime will have the ability to perform two tasks. On the one hand, it will allow for teams to perform runtime upgrades, so that they will be able to match their current Substrate Independent Runtime. On the other hand, it holds the ability to return a specific header at a specific moment in time([#846](https://github.com/paritytech/cumulus/pull/846) added this functionality). Parachains get from the Relay Chain the header of their last block and use that as an input to produce a new block with a new header that is sent to the Relay Chain for Validation. This header will not be the result of common block production by a parachain, but rather the header from the last block of the Substrate Independent Chain at the moment of the transition.

**`TODO: ADD CODE FOR THE HEADER RETURN FUNCTION`**

| Node Transition | Runtime Transition |
| -------- | -------- |
| | |

> **The Migration Process requires the execution of both a Node Transtion as well as a Runtime Transition. Timing of these two will be of the esence.**

## Migration Steps
Execution of this migration needs to be well ordered. This guide assumes that a team has an existing Substrate Independent Chain running before doing this migration.
1. Transition from a Substrate Independent Chain Node to a Solo<>Para Node.
2. Register the Seedling Runtime on a parachain and secure a slot. This Seedling Runtime should have the keys from the Substrate Independent Chain that allows for the migration to take place. **Continue only if you win a slot on a Relay chain and the Seedling Parachain is successfully producing blocks.**
4. Execute the Runtime Upgrade on the Substrate Independent Chain Runtime to the Parachain Code. This will stop block production on the Substrate Independent Chain.
5. Pass the Header of the last block of the Substrate Independent Chain to the Seedling Parachain. [#825](https://github.com/paritytech/cumulus/pull/825) added the functionality on Cummulus to return a specific header.
6. Request the Relay Chain to upgrade the seedling parachain to the parachain code.
7. Once the Relay Chain accepts the upgrade, it will send a message to the parachain to update itself. [OnDataValidation](https://github.com/paritytech/cumulus/blob/6d25c29087add9c692b6a2b23217441344c3f5c1/pallets/parachain-system/src/lib.rs#L107) callback will run and will execute the upgrade of the parachain and the setting of the header as well.


### Order

The order in which each component is running is key.


The Seedling Node needs to be running and in sync with the relay chain before the Seedling Runtime starts being executed in the Seedling parachain. Only once that is done and producing blocks, the Solo Runtime can do the Runtime Upgrade to the Parachain Code allowing only then the Seedling Runtime to execute the Runtime upgrade.

On top of this, the Solo Runtime needs to be running before the Seedling Runtime is registered on a Relay Chain so that the keys can be passed to it. These keys will be the ones that will hold the permission to execute the migration. Finally, the Solo<>Para Node needs to be running as well before the Solo Runtime does the Runtime Upgrade to the parachain code.

> In between the Solo Chain runtime Upgrade execution and the Seedling Parachain runtime Upgrade execution, the project will have neither a working solochain nor a working parachain. These two upgrades should probably happen close together to have the least amount of service-downtime as possible.

## License
- Substrate Primitives (`sp-*`), Frame (`frame-*`) and the pallets (`pallets-*`), binaries (`/bin`) and all other utilities are licensed under [Apache 2.0](https://github.com/paritytech/substrate/blob/master/LICENSE-APACHE2).
- Substrate Client (`/client/*` / `sc-*`) is licensed under [GPL v3.0 with a classpath linking exception](https://github.com/paritytech/substrate/blob/master/LICENSE-GPL3).

The reason for the split-licensing is to ensure that for the vast majority of teams using Substrate to create feature-chains, then all changes can be made entirely in Apache2-licensed code, allowing teams full freedom over what and how they release and giving licensing clarity to commercial teams.

In the interests of the community, we require any deeper improvements made to Substrate's core logic (e.g. Substrate's internal consensus, crypto or database code) to be contributed back so everyone can benefit.