# Snapshot Builder

> Planned tooling that turns a source chain's ledger into a migration list that validators can reproduce and certify.

Source: https://docs.iceroot.com/projects/snapshot-builder/

The Snapshot Builder does not exist yet. This page describes its planned design, and its commands and screens may change before release.

The Snapshot Builder is planned tooling for projects. It is designed to turn a source chain’s ledger into a canonical migration list that validators can reproduce and certify. It is planned to run outside consensus and changes no protocol rule.

## One implementation for projects and validators

The builder is planned to share its deterministic code with the IceRoot Connector that each validator runs. A project and every certifying validator then build the list with the same implementation, and a list that one of them builds can be rebuilt byte for byte by the others.

A command-line tool is planned underneath any web interface, so that a website never becomes the trusted source of a list: anyone could run the tool on the same inputs and get the same result.

## From source chain to certified list

1. **Source chain.** Read the asset’s ledger at an exact, finalized source block, or at a declared recovery point.
2. **Holder reconstruction.** Rebuild every holding deterministically.
3. **Reconciliation.** Check the reconstructed holdings against the source supply.
4. **Canonical migration list.** Produce the list in its one canonical form.
5. **Reproduction and certification.** Validators rebuild the list independently and certify it.

## Determinism rules

| Rule                                 | What it requires                                                                   |
| ------------------------------------ | ---------------------------------------------------------------------------------- |
| Integer base units                   | Amounts are integers in the source asset’s base units, never floating-point values |
| Canonical addresses                  | Each address has one accepted encoding                                             |
| Canonical ordering and serialization | The same holdings always produce the same bytes                                    |
| Exact source block                   | The list names its source block by height and block hash                           |
| Versioned policy                     | The policy is a versioned file with a hash                                         |
| Reproducible list hash               | The same inputs always produce the same list hash                                  |

Nothing in a list may depend on floating-point arithmetic, timestamps, locale settings, a central API, spreadsheet edits, or undocumented exclusions.

## Policies

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

The policy is explicit, versioned, and hashed, and its hash is committed in the certified list. What cannot be reproduced is not certified. See [Recover after an incident](https://docs.iceroot.com/projects/migration/index.md#recover-after-an-incident) for how recovery policies are used.

## Planned workflow

1. Select the source network, the asset, and a finalized block, or a declared recovery point.
2. Choose the policy.
3. Build the holder set.
4. Reconcile the result against the source supply.
5. Review the exceptions.
6. Generate the migration list.
7. Publish the list and its report.
8. Validators reproduce and certify the list.

An illustrative command, which may change before release:

```sh
iceroot-snapshot build --network ethereum --asset <asset> --block <height> --policy <policy>
```

## Migration report

The builder is planned to produce a report for every migration or recovery it prepares, stating:

- the source network, asset, block, and block hash, and the declared recovery point where there is one;
- the source supply, the included supply, and the holder count;
- the excluded and system addresses;
- the policy and its hash.

## Source networks

Adapters are planned as projects need them. Candidates include:

| Adapter    | Networks                                                                                                 |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| EVM        | Ethereum, BNB Smart Chain, Polygon, Base, Arbitrum, Optimism, and Avalanche C-Chain, through one adapter |
| Solana SPL | SPL tokens on Solana                                                                                     |
| Cosmos SDK | Chains built with the Cosmos SDK                                                                         |
| ARK        | The ARK network                                                                                          |

An adapter makes a network’s ledger readable. It does not make the network a certified source: the validator quorum must also register the network, and each certifying validator must run the adapter in its own Connector, with its own access to that network. At mainnet launch, Ethereum (ERC-20 tokens) is the supported source network for certified migration. It is registered as classical, so a snapshot of it must be taken at or before its cut-off block, and no snapshot list of it is certified after the cut-off, whatever its snapshot block. [Connector adapters](https://docs.iceroot.com/projects/connector-adapters/index.md) describes what an adapter must provide and how to propose a new network.

[Migration guide →](https://docs.iceroot.com/projects/migration/index.md) · [Connector adapters →](https://docs.iceroot.com/projects/connector-adapters/index.md)