# Connector adapters

> What a Connector adapter must provide, and how support for a new source network is proposed, reviewed, and certified.

Source: https://docs.iceroot.com/projects/connector-adapters/

The IceRoot Connector and its adapters are not released yet. This page describes the planned design and the proposal path in the [draft protocol](https://docs.iceroot.com/core/protocol-design/index.md). Interfaces, repository names, and file formats may change.

The IceRoot Connector is the framework through which IceRoot integrates external chains. Each source network is supported through its own adapter: code that reads that network’s ledger and produces the inputs of a migration list in one canonical form. At mainnet launch, one source network is certified: Ethereum (ERC-20 tokens).

This guide explains what an adapter must provide and how anyone can propose support for another network.

## Who decides what

IceRoot provides tools and verifies; projects decide. An adapter makes a network’s ledger readable. It does not choose which assets migrate, which block a snapshot uses, or which holders are legitimate. Those choices belong to the project that declares them, and a certification means only that a list was reproduced from its declared inputs.

## One implementation for validators and projects

The same adapter code runs in two places:

- **Each validator’s Connector,** which rebuilds a published list from the source chain and signs a migration attestation when the result matches.
- **The planned [Snapshot Builder](https://docs.iceroot.com/projects/snapshot-builder/index.md),** which projects and communities use to prepare lists.

Because both run the same deterministic code, a list that a project builds can be rebuilt byte for byte by every certifying validator. A list that cannot be reproduced from its declared inputs is not certified.

The Connector runs outside the node. Block validity never consults a source chain, so an adapter cannot halt or fork IceRoot. A validator whose adapter or source data is wrong does not attest, and a list without 36 attestations waits while blocks continue. Every credit stays under the asset’s lifetime cap.

Every validator runs the same adapter, so an adapter bug affects all certifiers alike. An error such as a holder counted twice is usually credited before anyone can cancel it. The lifetime cap, the public list file, the quorum’s cancel before a list’s first credit, and the migration watcher bound that risk; a mistake found after crediting is corrected with existing units and a public post-mortem.

## What an adapter must provide

### Identity

- **Network identifier.** A canonical, byte-exact identifier for the source network, for example derived from its chain ID and genesis block hash. The validator quorum registers each source network once, and its registration records the network’s class: post-quantum only if both the holders’ ownership signatures and the chain’s finality are post-quantum, classical otherwise. A classical network also gets a cut-off, an IceRoot height and matching source block fixed at registration, which the quorum can only ever move earlier afterwards; see [Migrations and continuity](https://docs.iceroot.com/network/migrations/index.md#source-network-class-and-cut-off).
- **Asset reference.** A canonical reference for each source asset, such as an ERC-20 contract address in one fixed encoding. The external AssetID is a domain-tagged hash of the source network and the source asset, so the same source asset always maps to one AssetID, and two unrelated assets with the same ticker never share one.
- **One source asset per IceRoot asset.** Several source assets are never merged into one IceRoot asset.
- **Decimals.** The source asset’s decimals as the source chain records them. A token with more than 18 decimals is not registered.

### Finality

- **A source finality rule.** The rule states when a source block or event counts as final and may be attested. Nothing is attested before it is met.
- **Burn events need firm finality.** Burn-event routes are allowed only for networks with deterministic or checkpoint finality, such as Ethereum’s finalized checkpoints. Networks without firm finality, such as Bitcoin-like chains, migrate by snapshot only.

### Deterministic holder reconstruction

For a snapshot, the adapter reconstructs every holding at one source block. Two honest runs, against any two honest nodes of the source network, must produce the same bytes.

| Rule                                 | What it requires                                                                                                |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Integer base units                   | Every amount is an integer in the source asset’s base units, never a floating-point value                       |
| Canonical addresses                  | Each address has exactly one accepted encoding                                                                  |
| Canonical ordering and serialization | The same holdings always produce the same bytes, in the same order                                              |
| Exact source block                   | The list names its source block by height and block hash                                                        |
| Source-chain data only               | Data comes from the source network’s own nodes at the named block, not from a central API, indexer, or explorer |
| Reconciliation                       | The reconstructed holdings reconcile against the source asset’s supply at that block                            |

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

### Typed lines and holding classes

- **Typed source keys.** Every line carries a typed source key. The line format does not assume that the source chain uses accounts, so networks with other ledger models can be supported.
- **Contract and escrow holdings.** The adapter tells key-held holdings apart from contract and escrow holdings, such as bridge escrows, liquidity pools, and burn addresses, using only source-chain data, so that every certifier classifies them the same way. Contract and escrow holdings are excluded and recorded as unissued, unless their controller binds them through a documented public process before the list is certified.
- **Custodial lines.** A custodian, such as an exchange’s omnibus wallet, receives one aggregate line labeled “custodial”. Custodial lines are the only aggregate lines.
- **Policies.** A policy-adjusted list applies items from a small fixed menu: a declared recovery point, excluded addresses, and the treatment of escrow and contract holdings. The policy is a versioned file whose hash is committed in the certified list.

### Burn events

- **Events in a block range.** The adapter extracts the burns of the source asset in a range of source blocks. Each burn names its IceRoot account in the same source transaction that destroys the tokens.
- **Contiguous ranges.** Each new list starts right after the last source block already credited, so no event can be credited twice.
- **Stable event references.** Every migration has a MigrationID, a fixed-width, domain-tagged identifier derived from source data only. The adapter supplies the canonical source-event data it is derived from.
- **Malformed accounts.** A burn that names a malformed IceRoot account is recorded as rejected and remedied on the source chain.

### Ownership proofs

For a snapshot, a holder binds an IceRoot account off-chain, typically by signing with the source-chain key; late binding uses the same kind of proof. The adapter verifies these signatures with the source network’s own cryptography and address rules. The Connector is where such classical signatures are checked; they never authenticate anything in IceRoot consensus. For a classical source network, no snapshot list is certified after the network’s cut-off, whatever its snapshot block, and no late binding is accepted after it. 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.

### Operation

- **Source access.** Each validator reaches the network through its own node or a provider that it declares publicly. The adapter documents what it needs, for example historical state at a past block.
- **Test vectors.** A proposal includes fixtures from real source blocks with the expected list bytes and list hash, so that anyone can check that independent runs agree.

## Propose a new source network

A new source network takes these steps. Each network adds work for every validator, which must reach the network itself, and adds a source whose data validators must read correctly, so a proposal should name the assets and projects that need it.

1. **Open a proposal.** Describe the network, its finality, its signature schemes and address formats, its ledger model, the assets that need it, and how validators can reach it. Proposals are planned to be filed publicly on GitHub, in the `iceroot-network` organization, once the Connector repository is published.
2. **Build the adapter.** Implement the adapter against the Connector’s interface, with its test vectors.
3. **Public review.** The adapter is reviewed in public for determinism and for correct use of the source network’s cryptography before a Connector release includes it. Whether adapters also receive an independent security review is not yet decided.
4. **Public testnet.** Validators run the adapter on the public testnet, where lists are built and reproduced before any mainnet use.
5. **Validator access.** Each validator prepares its own access to the network and declares it. The limit of 17 validators per provider is a declared policy, shown on the explorer, not a consensus rule.
6. **Registration.** At least 36 of the 53 validators register the source network, recording its class and, if classical, its cut-off. Only then is it a certified source network. Each validator decides for itself whether to run the adapter and attest.
7. **Asset registration.** Each asset is then registered once with `ASSET_REGISTER_EXT`, certified by the same quorum, which fixes its identity, decimals, mode, trust label, source finality rule, and lifetime cap.

A merged adapter makes a network readable; only registration by the validator quorum makes it a certified source. If support for a network ends later, only new lists stop. Units already credited stay, and a node that resyncs from genesis never needs the source network.

When a network is certified, projects follow the [migration guide](https://docs.iceroot.com/projects/migration/index.md). The [Snapshot Builder](https://docs.iceroot.com/projects/snapshot-builder/index.md#source-networks) lists candidate adapters.

[Snapshot Builder →](https://docs.iceroot.com/projects/snapshot-builder/index.md) · [Migration guide →](https://docs.iceroot.com/projects/migration/index.md)