# Migration guide

> Move an asset onto IceRoot, retire a chain, leave a smart contract, recover after an incident, and move assets out again.

Source: https://docs.iceroot.com/projects/migration/

Migration moves an asset from another network onto IceRoot, and from IceRoot to a destination chain. It serves planned moves as well as retirements and recoveries: an asset can move from Chain A to IceRoot, or from Chain A to IceRoot and on to Chain B.

This guide follows the [draft protocol](https://docs.iceroot.com/core/protocol-design/index.md), which describes the intended mainnet. Values that the draft leaves open are marked as not yet fixed. [Migrations and continuity](https://docs.iceroot.com/network/migrations/index.md) summarizes the model.

## Choose your situation

| Situation                                               | Section                                                                                                                     |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Moving an existing asset to IceRoot                     | [Migrate an asset in](https://docs.iceroot.com/projects/migration/index.md#migrate-an-asset-in)                             |
| Retiring or consolidating your own chain                | [Planned chain retirement](https://docs.iceroot.com/projects/migration/index.md#planned-chain-retirement)                   |
| A chain that is winding down                            | [End-of-life chains](https://docs.iceroot.com/projects/migration/index.md#end-of-life-chains)                               |
| Replacing an ERC-20 or proxy token                      | [Leave a smart contract](https://docs.iceroot.com/projects/migration/index.md#leave-a-smart-contract)                       |
| Recovering holdings after an incident                   | [Recover after an incident](https://docs.iceroot.com/projects/migration/index.md#recover-after-an-incident)                 |
| Holding an asset on IceRoot while your chain is rebuilt | [A temporary home while rebuilding](https://docs.iceroot.com/projects/migration/index.md#a-temporary-home-while-rebuilding) |
| Moving an asset from IceRoot to another chain           | [Migrate out](https://docs.iceroot.com/projects/migration/index.md#migrate-out)                                             |

## Migrate an asset in

A migration is a public list of who owned what on the source chain and which IceRoot account receives each holding. At least 36 of the 53 validators each rebuild and sign the list before it is credited, under a lifetime cap that is fixed for the asset.

### Check the requirements

- **Source network.** At mainnet launch, Ethereum (ERC-20 tokens) is the supported source network. Each further network needs its own Connector adapter and registration by the validator quorum before its assets can migrate; see [Connector adapters](https://docs.iceroot.com/projects/connector-adapters/index.md).
- **Class and cut-off.** Registering a source network records its class: post-quantum only if both the holders’ ownership signatures and the chain’s finality are post-quantum, classical otherwise. Ethereum is classical (ECDSA ownership signatures, BLS finality signatures), so it also carries a cut-off: an IceRoot height and the matching source block, fixed by the validator quorum at registration and only ever moved earlier. After a classical source’s cut-off, consensus refuses new asset registrations from that network, event lists that reach past the cut-off block, any snapshot list, whatever its snapshot block, and any late binding. Lists certified before the cut-off stay creditable indefinitely, and an event list whose whole range lies at or before the cut-off block can still be certified after it. A post-quantum source network has no cut-off. See [Migrations and continuity](https://docs.iceroot.com/network/migrations/index.md#source-network-class-and-cut-off).
- **Decimals.** A source token with more than 18 decimals is not registered.
- **Identity.** A migrated asset’s AssetID is derived from its source network and its source asset, never from a ticker or name. The same source asset maps to one AssetID across every list.
- **Lifetime cap.** Registration fixes the most base units migration can ever credit to the asset, and consensus rejects any credit above it. For a live source whose supply can still grow, the cap has to leave room for that growth.
- **Trust label.** Registration records a trust label for the asset and its route. An asset’s history before it arrived keeps the strength of its source chain and of the route that carried it.

### Choose a mode

Each asset uses one mode, fixed at registration and never changed. Both modes produce the same kind of certified list and are credited the same way.

| Aspect                           | Snapshot                                                                      | Burn events                                                                                             |
| -------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| What a list records              | Every holder of the asset at one source block                                 | Tokens that holders destroy on the live source chain                                                    |
| How the IceRoot account is fixed | Bound off-chain by the holder, typically by signing with the source-chain key | Named in the same source transaction that destroys the tokens                                           |
| Lists                            | One list for the snapshot block                                               | One list per range of source blocks                                                                     |
| Source chains                    | Any registered source network                                                 | Registered networks with deterministic or checkpoint finality, such as Ethereum’s finalized checkpoints |

A snapshot of a chain that is still live is labeled a distribution, not a succession. Fee-on-transfer and rebasing tokens must migrate by snapshot, because for them the amount received can differ from the amount sent.

For a classical source network, an event list cannot reach past its cut-off block, and no snapshot list can be certified after its cut-off, whatever its snapshot block. A post-quantum source network has no such limit.

### Follow the steps

1. **Registration.** The validator quorum registers the source network once, and registers the asset once with `ASSET_REGISTER_EXT`. Registration fixes the identity, decimals, mode, trust label, source finality rule, and lifetime cap.
2. **Binding.** For a snapshot, each holder binds an IceRoot account off-chain before certification, typically by signing with the source-chain key. For burn events, the holder names the account in the burn transaction. Wallets use a fresh IceRoot account for each migration.
3. **Custodians.** A custodian, such as an exchange’s omnibus wallet, receives one aggregate line labeled “custodial” and redistributes to its customers with ordinary transfers. No customer data goes on chain.
4. **Contracts and escrows.** Contract and escrow holdings, such as bridge escrows, liquidity pools, and burn addresses, are excluded and recorded as unissued, unless their controller binds them through a documented public process before the list is certified.
5. **The list.** The list is published as a file before anything goes on chain. For a snapshot, the planned [Snapshot Builder](https://docs.iceroot.com/projects/snapshot-builder/index.md), which does not exist yet, is designed to build it reproducibly.
6. **Certification.** Each certifying validator rebuilds the list with its own IceRoot Connector and its own access to the source chain, and signs it with its migration attestation key. With at least 36 of 53 signatures, `MANIFEST_COMMIT` records the list’s fingerprint and declared totals. Nothing is attested before the source chain’s finality rule is met.
7. **Crediting.** Anyone submits the certified lines with `MIGRATE_IN`, in order, in chunks of at most 256 lines. A list is creditable as soon as it is certified, and the credited totals must equal the declared totals exactly.
8. **Announcement.** Announce the asset’s AssetID on your own channels. The open-source migration watcher, which anyone can run, re-checks credited lines against the source chain and raises an alarm on a mismatch.

An issuer can also require the asset’s migration authority to co-sign each list. The issuer can then veto a list but can never create units. If that authority’s key is lost or the role is renounced, inbound migration of the asset stops permanently.

### If something goes wrong

- **Before any line is credited,** the validator quorum can cancel the list. This is how a flawed snapshot is replaced.
- **After lines are credited,** a mistake is corrected off-chain with units that already exist and a public post-mortem. The wrong provenance stays in history. There is no pending state, no correction record, and no optimistic issuance.
- **Holders who named no account** stay unissued, and the explorer shows their holdings as the migration’s unissued remainder. Nothing is ever swept to an authority, a treasury, or other holders.
- **Late binding** lets certifiers bind unbound key-held holdings until a deadline that consensus enforces. Each binding carries a proof signed with the holding’s own source-chain key and waits out a delay during which it can be cancelled. The deadline and the delay are not yet fixed, except that for a classical source network the deadline must fall at or below the network’s cut-off, and no binding is accepted past it. Post-quantum sources have no network cut-off, but the late-binding deadline and delay still apply.

### What holders should know

- A holder needs no ROOT to receive migrated units. A migration never includes ROOT, and moving the asset afterwards takes ROOT for fees like any other transaction. A project can receive a [fee grant](https://docs.iceroot.com/network/root/index.md#fee-grants) that covers registration surcharges and small ROOT amounts for its migrated holders.
- The link between a source address and an IceRoot account is public and permanent.
- Wallets and the explorer show the source network’s class and, for a classical source, its cut-off.
- From the moment it is credited, the asset is controlled by post-quantum keys.

## Planned chain retirement

A project that no longer needs its own blockchain can retire it, or consolidate onto IceRoot, and keep its asset’s ownership record. This is a planned decision, not a failure.

1. **Check support early.** If your chain is not yet a supported source network, it needs a Connector adapter and registration by the validator quorum before its assets can migrate.
2. **Announce the snapshot block.** For a classical source network, it must fall at or before the network’s cut-off block, and no snapshot list is certified after the cut-off, so leave time for certification. Give holders time to bind their IceRoot accounts before certification.
3. **Coordinate holders that are not individuals.** Custodians receive aggregate lines. Contract and escrow holdings need their controller to bind them before certification, or they stay unissued.
4. **Keep your chain’s data readable.** Every certifying validator reads the source chain through its own node or a declared provider. Keep nodes and the data for the snapshot block available until the list is certified, and preferably until the late-binding deadline has passed.
5. **Retire the chain.** After the list is credited, the asset’s record continues on IceRoot. If your chain keeps running after the snapshot, the migration is labeled a distribution, not a succession.

## End-of-life chains

The lifetime of an asset does not have to equal the lifetime of the blockchain on which it was created. When a chain is losing its validators, developers, or infrastructure, a snapshot migration lets holders keep their ownership record on IceRoot.

- **Check support early.** A network other than Ethereum needs its own Connector adapter and registration by the validator quorum before its assets can migrate, so start that work while the chain still runs.
- **Start while the chain is readable.** Certification depends on validators reading the source chain themselves. A list that validators cannot reproduce is not certified.
- **A company is not required.** A project team or a community can prepare the list and announce the AssetID. Validators reproduce the list from the source chain’s own data in either case.
- **Unbound holdings stay recorded.** Holders who do not bind an account stay in the unissued remainder. Late binding covers key-held holdings until its deadline; for a classical source network, that deadline must fall at or below the network’s cut-off, after which no binding is accepted.

## Leave a smart contract

A project can replace an ERC-20 or proxy token with a standardized IceRoot asset to reduce its attack surface. This is a routine change, not an emergency measure. Ethereum is a supported source network at mainnet launch. It is registered as classical, so burns after its cut-off block are never credited, and a snapshot list must be certified before the cut-off.

- **Burn events** suit a contract that stays in use during the move. Holders destroy their tokens on Ethereum in a transaction that also names their IceRoot account, so the source side needs a way to do both in one transaction. Each range of source blocks becomes one list. The tokens are destroyed on Ethereum as they move to IceRoot.
- **A snapshot** records every holder at one block. Because the contract keeps running, the migration is labeled a distribution, and the tokens also remain on Ethereum.

On IceRoot, the asset has no contract code: no upgradeable proxy, no administrator functions, and no pause, blacklist, tax, or rebasing logic. Its behavior is the protocol’s fixed operation set. Units of a migrated asset arrive through certified lists under the lifetime cap, and no other operation creates them.

The source contract remains on Ethereum with whatever powers it has, and its history before the migration keeps the strength of Ethereum and of the route. Announce which AssetID is canonical, and say whether the source contract remains in use. Liquidity pools and bridge escrows are excluded unless their controllers bind them before certification, so coordinate with them early.

## Recover after an incident

When a network suffers an incident, its project can bring holdings onto IceRoot from a point the project declares, and later move them to a rebuilt chain.

### Who decides what

- The source project declares a recovery point and a recovery policy, and publishes both on its own channels.
- IceRoot does not decide whether a hack happened, which block or holders are legitimate, or which transactions are reversed.
- Validators reproduce the list from the declared recovery point and policy, and certify that it reproduces. Certification means reproduced, not endorsed.
- The result is balances derived from the declared recovery policy, credited through an IceRoot-certified migration list.
- The project announces which AssetID is its canonical asset. That responsibility is the project’s.

### Recovery policies

A recovery uses a small, fixed menu of deterministic, versioned policies:

- **Strict ledger reconstruction:** every holding as the source ledger records it at the declared block.
- **Policy-adjusted reconstruction:** the same reconstruction with items from the menu: a declared recovery point, excluded addresses, and the treatment of escrow and contract holdings.

The policy is explicit, versioned, and hashed, and the certified list includes the policy’s hash. What cannot be reproduced is not certified: manual edits, exclusions that the policy does not document, and items outside the menu cannot be certified.

### Steps

1. **Check support.** The source network must be supported, with its own Connector adapter and registration by the validator quorum.
2. **Declare.** Publish the declared recovery point, as a source block height and hash, and the policy file.
3. **Build.** Generate the list deterministically from the source chain at the declared point under the policy. The planned Snapshot Builder, which does not exist yet, is designed for this.
4. **Bind.** Holders bind their IceRoot accounts under the snapshot rules above.
5. **Reproduce and certify.** At least 36 of the 53 validators each rebuild the list from the declared inputs with their own Connector and source-chain access, and sign it.
6. **Credit.** Anyone submits the certified lines with `MIGRATE_IN`, under the asset’s lifetime cap.
7. **Publish the migration report.** It records the source network, asset, block and block hash, the declared recovery point, the source supply, included supply and holder count, the excluded and system addresses, and the policy with its hash.
8. **Move on when ready.** The asset can later move to a rebuilt chain through a recorded exit. See [A temporary home while rebuilding](https://docs.iceroot.com/projects/migration/index.md#a-temporary-home-while-rebuilding).

### Wording for announcements

These terms describe what IceRoot does in a recovery.

| Use                                                | Instead of                |
| -------------------------------------------------- | ------------------------- |
| Declared recovery point                            | Last legitimate block     |
| Balances derived from the declared recovery policy | Correct balances          |
| IceRoot-certified migration list                   | IceRoot-approved recovery |

This recovery path applies to incidents on other networks. IceRoot’s own finalized history is never rolled back, and theft or a bad trade is never a reason for a rollback.

## A temporary home while rebuilding

A project rebuilding its chain can hold its asset on IceRoot in the meantime: the asset moves from the original chain to IceRoot, and later on to the rebuilt chain.

1. **Arrive.** Bring the asset in by snapshot, following [Planned chain retirement](https://docs.iceroot.com/projects/migration/index.md#planned-chain-retirement) or [Recover after an incident](https://docs.iceroot.com/projects/migration/index.md#recover-after-an-incident).
2. **Hold.** On IceRoot, holders transfer, swap, and burn as with any asset.
3. **Prepare the rebuilt chain.** It must meet the destination rules under [Migrate out](https://docs.iceroot.com/projects/migration/index.md#migrate-out). Test the route on the public testnet.
4. **Leave.** The asset’s migration authority adds the rebuilt chain to the allow-list and opens migrate-out, the project announces the destination, and holders move with `MIGRATE_OUT`.

Holders who do not move keep transferable units on IceRoot. If the asset later comes back from the rebuilt chain by migration, it registers as a new asset with its own AssetID.

## Migrate out

An exit works the same way for a native asset and for a migrated one.

### Conditions

- The asset’s migrate-out flag is open.
- The destination is on the asset’s allow-list.
- The migration authority controls both. The flag cannot open until the asset has an allowed destination.

The explorer describes an asset whose exits are open with a descriptive label; see [Lifecycle labels](https://docs.iceroot.com/network/lifecycle/index.md). No flag or label freezes transfers.

### What an exit does

`MIGRATE_OUT` destroys the holder’s units and counts them as migrated out, never as burned. It writes a typed record naming the destination network, the destination account, and an out id. There is no refund, so an exit can never create units.

A compatible destination verifies IceRoot finality from signed block headers, records IceRoot’s out id, and rejects duplicates. IceRoot cannot compel a destination to act, so the care taken in choosing the destinations on an allow-list is what protects holders. Holders should check a destination against the project’s announcement before moving.

The destination registry is an off-chain document listing compatible destinations and custody gateways. Wallet releases bundle it, and wallets update it from `iceroot.com` over HTTPS; users can change the feed URL or add others. The registry also records each destination’s class, by the same test as for a source network, and, for a classical destination, its cut-off. Wallets and the explorer show these and warn before a migrate-out to a classical destination past its cut-off. Consensus does not refuse the exit; the choice, and its risk, stays with the holder.

### Custody gateways and returns

A custody gateway is an ordinary IceRoot account, labeled “custodial gateway” with its operator’s name, and its current holdings are visible. A user sends units to it with a memo naming an address on the other chain, and the operator issues the same amount there. Returns come back from the gateway’s account, so they keep the original AssetID and can never exceed what the gateway holds. Users trust the operator.

A copy of an IceRoot asset that comes back from another chain by any other route registers as a new asset, with its own AssetID and lifetime cap. It never credits the original AssetID, and any link between the two is kept off-chain.

The [custody-gateway guide](https://docs.iceroot.com/developers/custody-gateways/index.md) covers labels and what an operator publishes.

## What is not supported

- **Mergers and restructuring.** Combining several source assets into one IceRoot asset is not supported. Each IceRoot asset maps to one source asset.
- **Refunds of exits.** An exit is one step, and destroyed units are not returned.
- **Private migration links.** Consensus has no privacy modes, and the link between a source address and an IceRoot account stays public.

[Snapshot Builder →](https://docs.iceroot.com/projects/snapshot-builder/index.md) · [Migrations and continuity →](https://docs.iceroot.com/network/migrations/index.md)