Whitepaper
Source: IceRoot whitepaper, revision f3f09e7, 26 September 2026.
Draft, not final. This is a working draft of the IceRoot whitepaper. It will change before publication, and values marked [TBD] are not yet fixed.
Abstract
Section titled “Abstract”IceRoot is a Layer 1 blockchain network that keeps an exact, long-lived record of who owns which digital asset. Its native token is ROOT, and its node software, Heartwood Core, is written in Rust.
Every signature the protocol verifies, from block 1, is ML-DSA-65 (FIPS 204): account transactions, blocks, validator online attestations, migration attestations and the identity of every peer. Peer connections use TLS 1.3 with a hybrid X25519 and ML-KEM-768 key exchange. No classical signature authenticates anything in consensus.
Consensus is QDPoS, a post-quantum delegated proof of stake. ROOT holders elect 53 validators, which produce blocks in 8-second slots. Finality follows a Lisk-BFT rule whose votes travel in block headers: a block with 36 of 53 implied precommits is final and is never reverted. A block is final at least 71 blocks after it is produced; with all validators online and no missed slots, it is typically final within about 71 to 108 blocks, about 10.8 minutes on average.
Every token, ROOT included, is a standardized ledger object identified by its AssetID, and IceRoot runs no smart contracts. Each node checks supply conservation for every asset after every block. Native assets are created through Seedbed with a fixed supply: the whole supply is created once, and no operation creates further units. External assets migrate in through public lists that at least 36 of the 53 validators rebuild and sign, under a lifetime cap per asset, and assets can leave for allowed destination chains. Two assets change hands in one all-or-nothing swap operation, hash time-locked transfers support swaps with other chains, and order books and matching run off-chain. Time-locked transfers carry vesting and the public release of reserves: each entry is claimable for its recipient only after its unlock time, and no one can revoke it.
Rules change only through public releases with named activation heights; there is no on-chain governance. This paper describes the network as it runs on mainnet and states each trust assumption with its bound.
Introduction
Section titled “Introduction”IceRoot is a blockchain network that keeps an exact, long-lived record of who owns which digital asset. It secures that record from its first block with post-quantum signatures and deterministic finality.
This paper describes the IceRoot Network as it runs on mainnet. It is written for engineers who build on the network, for exchanges and custodians who hold assets on it, and for the operators who run its validators. Every figure in it is a protocol value, a constant of a published standard, a value derived directly from these, or a result of analysing the protocol rules, which the text labels as such. None is a measurement. Numbers in square brackets, such as [1], refer to the list in Acknowledgements and references.
Why IceRoot exists
Section titled “Why IceRoot exists”Most public blockchains authenticate every transaction with elliptic-curve signatures such as ECDSA, Schnorr or EdDSA. Their security rests on the hardness of the elliptic-curve discrete logarithm problem. Shor’s algorithm [18] solves that problem efficiently on a sufficiently large quantum computer, and such a computer can derive a private key from its public key.
On a blockchain, public keys are not secret. A verifier needs the public key to check a signature, so any account that has signed a transaction has published its key, and the chain keeps it permanently. Once a large enough quantum computer exists, whoever operates it can sign as the holder of any exposed account, and the chain cannot tell that forgery from a genuine signature.
The arrival date of such a computer is unknown. The cost of preparing for it is known. Moving a chain to post-quantum signatures takes new transaction and block formats, a coordinated protocol upgrade, much larger keys and signatures, and every holder moving funds to a new key. It needs an active development team, an active validator set and active holders at the same time.
Chains are also retired or replaced. Their assets still have holders, and those holders need a ledger that keeps recording their ownership.
What IceRoot is for
Section titled “What IceRoot is for”IceRoot is a network on which projects and holders keep digital assets under post-quantum keys, whether an asset was created on IceRoot or migrated in from another chain. “Post-quantum” has a narrow, checkable meaning here: every signature the protocol verifies, from block 1, is ML-DSA-65, the module-lattice signature standard of FIPS 204 [1]. No classical signature authenticates anything in consensus, so an asset held on IceRoot is controlled by post-quantum keys from the moment it arrives.
Assets reach IceRoot in two ways:
- Native assets. A project creates its asset on IceRoot through Seedbed, IceRoot’s native asset creation and distribution platform.
- External assets. A project or community migrates an existing asset in from another chain, for example because that chain is being retired or replaced.
While hosted on IceRoot, every asset stays transferable. An asset can also leave for a supported destination chain, including a project’s own chain, through a recorded exit. Migration routes differ in what they rely on, and each carries an explicit trust label (see Migration).
Diagram source
flowchart LR
SRC["Source chain<br/>(retired, replaced or live)"] -->|"certified migration in"| IR["IceRoot Network<br/>(assets stay transferable)"]
SB["Seedbed<br/>(native asset creation)"] --> IR
IR -->|"recorded exit"| DST["Destination chain,<br/>including a project's own chain"]IceRoot hosts tokens as native ledger assets and runs no smart contracts, by design. There is no virtual machine and no user-deployed executable code. Assets are standardized ledger objects, not programs.
The engineering philosophy is “Boring by design. Safe by design.” The node’s job fits in one line: “Agree on who owns what, and never get it wrong.” Design principles explains how these two lines shape the protocol.
Four properties
Section titled “Four properties”Post-quantum from genesis. Account transactions, blocks, online attestations, migration attestations and the identity of every node on the peer-to-peer network use ML-DSA-65. See Post-quantum cryptography.
Deterministic finality. Blocks become final under a Byzantine fault tolerant rule whose votes travel inside the block headers, and a finalized block is never reverted. See Consensus.
Native assets. Every token, ROOT included, is a ledger object identified by its AssetID and moved by one fixed set of standardized operations. The same set creates each native asset with its whole, fixed supply, swaps two assets in one all-or-nothing transaction, locks units for swaps with other chains and holds vesting tranches in time-locked entries that no one can revoke. Consensus keeps supply counters for every asset, and every node checks them after every block. See Accounts, transactions and native assets.
Migration in and out. A migration is a public list of who owned what on the source chain and which IceRoot account receives it. At least 36 of the 53 validators check and sign the list before it is credited, under a lifetime cap per asset, so no single key can ever create migrated units. See Migration.
Complete from height 1
Section titled “Complete from height 1”The multi-asset account model, finality, Seedbed asset creation, atomic swaps, hash time-locked transfers, time-locked transfers for vesting, and migration in and out are all active from mainnet height 1. A new node can validate the whole chain from genesis under the same rules as every other node.
Mainnet starts with 53 independent validators: every genesis seat is held by an independent operator, selected by the IceRoot team from the operators of the public testnet.
IceRoot at a glance
Section titled “IceRoot at a glance”| Item | Value |
|---|---|
| Network | IceRoot Network |
| Native token | ROOT, 18 decimals |
| Genesis supply | 100,000,000 ROOT |
| Node software | Heartwood Core, written in Rust; binary heartwood |
| Consensus | QDPoS, post-quantum delegated proof of stake, with header-carried BFT finality |
| Validator seats | 53 |
| Slot (block interval) | 8 s |
| Round | 53 slots, 424 s |
| Finality threshold | 36 of 53 validators |
| Time to finality | At least 71 blocks (568 s); with all validators online and no missed slots, typically about 71 to 108 blocks (about 568 to 864 s) |
| Block reward | 1.8 to 2.2 ROOT by seated rank, mean 2.0 ROOT |
| Signature scheme | ML-DSA-65 (FIPS 204), for every signature in consensus |
| Address | 32-byte hash of the public key, written in Bech32m with the prefix ice (ice1...) |
| Smart contracts | None; assets are ledger objects |
| Asset supply | Fixed at creation; no operation creates further units |
| Trading | Native atomic swap of two assets, all or nothing, and hash time-locked transfers; order books and matching off-chain |
| Vesting | Non-revocable time-locked transfers, one entry per tranche, claimable for the recipient after each unlock time; also used to release reserves |
| Explorer | scan.iceroot.com |
| Documentation | docs.iceroot.com |
Timing figures are derived from the protocol rules or from analysis of them; none is a measurement of the running network. The derivations are in Consensus and Economics.
Names and places
Section titled “Names and places”- IceRoot is the project and brand. The IceRoot Network is the blockchain, called “the network” in this paper.
- ROOT is the network’s native token. It pays every transaction fee, carries the vote weight in validator elections and is the currency of validator rewards.
- Heartwood Core (“Heartwood”) is the node software, written in Rust. Its binary is
heartwood. - QDPoS is IceRoot’s consensus: post-quantum delegated proof of stake.
- Seedbed is the native asset creation and distribution platform. Its interface runs outside consensus.
- The IceRoot Connector (“Connector”) is the external-chain integration framework. It runs outside the node.
The website is iceroot.com, which also serves the verified-asset list and the destination registry over HTTPS. The explorer is scan.iceroot.com. The documentation, including the public onboarding guide for exchanges and custodians, is at docs.iceroot.com. Heartwood Core releases are published on GitHub under the organization iceroot-network. The legal entity behind IceRoot is Mono Labs R&D LLC.
Nothing in this paper promises an exchange listing, liquidity or a price for ROOT or any other asset.
How this paper is organized
Section titled “How this paper is organized”- Design principles states the rules behind the rules, and the reason for each.
- Network architecture describes Heartwood’s processes, key handling, peer-to-peer transport, storage and networks.
- Consensus covers validator election, the slot schedule, finality, fork choice, faults and penalties.
- Post-quantum cryptography covers the signature scheme, signing domains, hashing, addresses and keys.
- Accounts, transactions and native assets covers the account model, the operation set, account names, fees, limits, the asset model, atomic swaps, hash time-locked transfers and time-locked transfers.
- Economics covers ROOT’s supply, block rewards, donations and the fee split.
- Governance and protocol upgrades covers releases, activation heights and the rollback policy.
- Migration covers moving assets in from other chains and out to destination chains.
- Integrations covers the node API, the indexer, SDKs, the wallets, the explorer, validator reward sharing and exchange integration.
- Security model and assurance collects every trust assumption, its bound, and the assurance work behind the release.
- Conclusion summarizes the design and its stated limits.
- Acknowledgements and references lists the standards and papers the text relies on.
Design principles
Section titled “Design principles”IceRoot’s rules follow from one aim: to keep an ownership record exact over the long term, with no more consensus code, audit scope or attack surface than that job requires.
Each principle below is stated once, with its reason and a pointer to the section that describes the mechanism. The table at the end summarizes them.
Boring by design, safe by design
Section titled “Boring by design, safe by design”IceRoot optimizes for correctness, modularity, lean code and long-term asset continuity, not for novelty. Every rule is weighed by what it adds in consensus complexity, audit scope and attack surface, and where a rule adds any of these, the cost is stated rather than hidden.
In practice, “boring” means standard, well-studied parts. Signatures use ML-DSA-65 from FIPS 204. Peer connections use TLS 1.3 with a hybrid key exchange that combines X25519 and ML-KEM-768. Finality follows a published BFT protocol with a published safety analysis. Where IceRoot adapts a published design, it says how (see Consensus).
Consensus records ownership
Section titled “Consensus records ownership”The node’s one-line job, quoted in the Introduction, sets the scope of consensus: it records ownership and the few facts needed to protect it, and nothing else.
The following run outside consensus:
- the Seedbed interface;
- the explorer and the indexer;
- the market-data service;
- wallet interfaces;
- rich metadata hosting, social links, analytics and charts;
- exchange tooling;
- order books, trade matching and trading interfaces;
- the IceRoot Connector (consensus verifies only the attestations it signs);
- the measurement and display of validators’ reward sharing, the payout tool and the launchpad distribution kit;
- marketing and project discovery.
Each of these can change, fail or be replaced without changing a rule that every node enforces. An explorer outage or a wrong price cannot halt the chain, fork it or change a balance.
Trading follows the same line. Consensus settles a trade between two accounts with one atomic swap operation, all or nothing, and supports swaps with other chains through hash time-locked transfers. It keeps no order book and runs no automated market maker; matching happens off-chain, where anyone may build it. See Accounts, transactions and native assets.
Assets are ledger objects, not programs
Section titled “Assets are ledger objects, not programs”Assets are created and moved by one fixed set of standardized operations, with no virtual machine and no user-deployed code (see Introduction). An asset’s identity is its AssetID, never its ticker or name.
No operation lets an issuer freeze, seize, tax or redirect holders’ balances, or create further units of an asset: every native asset’s supply is created once, when the asset is created. The authorities an asset carries, for its metadata and for its migration routes, can never debit, move or freeze any holder’s units or change provenance. The asset lifecycle never freezes transfers, and any asset can be received by any address. A power over balances, or a power to mint, would be a key whose loss or compromise reaches every holder of an asset.
The reason for a fixed operation set is auditability. Because asset behaviour is fixed by the protocol, it is reviewed once, for all assets, and no deployed program joins the audit scope of every holder’s assets. A holder, a wallet or an exchange learns everything an asset can do by reading its ledger record, not its code. See Accounts, transactions and native assets.
Prices stay outside consensus
Section titled “Prices stay outside consensus”Market pricing never enters consensus, and asset creators cannot set their own market price. A price in a validity rule would make an outside feed part of consensus. See Economics.
Bounded data
Section titled “Bounded data”The memo is the only free-form data field in a transaction. It holds at most 255 bytes, is paid for by size, is never executable, and never carries migration provenance. Every other field has a typed schema; the other text fields, an account’s name and an asset’s name, symbol and metadata URI, have fixed length limits and character or format rules. The provenance of migrated assets is typed protocol data that every node can check (see Migration). Consensus never interprets the memo’s content: conventions built on it, such as exchange deposit tags and validators’ identity declarations, are read only by services outside consensus (see Integrations). Bounded, byte-priced fields keep the cost of every byte on chain explicit, and typed fields give no field a second, hidden meaning.
Post-quantum only, with explicit schemes
Section titled “Post-quantum only, with explicit schemes”Every signature carries a signature-scheme identifier and length-prefixed witness bytes, so the authentication scheme is an explicit, versioned field and not an assumption built into the format. ML-DSA-65 is the only scheme the protocol accepts. Classical signatures never authenticate anything in consensus: a classical fallback would be the weakest path into every account and every block. See Post-quantum cryptography.
Trust is stated, never blurred
Section titled “Trust is stated, never blurred”Different migration methods rest on different trust assumptions, and IceRoot never merges them into one claim. Every registered migrated asset and route carries an explicit trust label. Community or manual bridges are always distinguished from native, verified routes. No migration method is described as post-quantum as a class: an asset’s history before it arrived on IceRoot is only as strong as its source chain and the route that carried it.
Every trust assumption of the network, with its bound, is listed in one place, in Security model and assurance.
Determinism and full replay
Section titled “Determinism and full replay”Every node must reach the same result from the same bytes, whenever it processes them. IceRoot builds this in at four levels:
- Rules. Mainnet starts with every rule active from height 1. Once a rule activates, its code stays in every subsequent release, so any node can validate the chain from genesis.
- Activation. Block and transaction validity never changes without a named activation height. See Governance and protocol upgrades.
- Inputs. Validity depends only on the block’s bytes and IceRoot’s own state. No node calls another chain or a price source to decide whether a block is valid.
- Encoding. Decoding is strict and canonical, integers are encoded little-endian, and every hash that consensus computes is SHA-256 with a domain tag for its kind, except the hash lock of a hash time-locked transfer, which is untagged so that it matches the other chain of a swap. See Post-quantum cryptography.
Invariants enforced at run time
Section titled “Invariants enforced at run time”After every block, each node checks supply conservation for every asset and stops on a violation. Each block header also commits to the block’s economic results, and a node that computes a different value rejects the block at once. An accounting error therefore stops visibly at the first block where it appears, instead of spreading. See Accounts, transactions and native assets, and Economics.
No discretionary power over the ledger
Section titled “No discretionary power over the ledger”No party can change the ledger outside its rules:
- There is no on-chain governance and there are no rule-change votes. A vote on rules would let vote weight rewrite the rules of ownership. Validator voting elects seats; it does not change rules.
- Genesis allocations are plain accounts. Vesting exists only as a time-locked transfer that a sender makes: each entry is claimable by its recipient only after its unlock time, and no one, the sender included, can revoke it. Because no entry can be revoked, no party keeps a power over units it has sent. A hash time-locked transfer serves a single exchange between two parties and ends in a claim or a refund.
- Finalized history is never rolled back, and theft or a bad trade is never a reason for a rollback. A rollback would make finality conditional, and finality is what exchanges and destination chains rely on.
Rule changes reach the network only as published releases with activation heights. See Governance and protocol upgrades.
Separation of duties
Section titled “Separation of duties”Network-facing work and key-holding work run in separate processes, and the relay, which talks to the network, never reads a validator’s keys. A validator uses four different keys: one for its funds, one for signing blocks and online attestations, one for its network identity and one for signing migration attestations. A compromise of one process or one key is bounded to that key’s role. See Network architecture and Post-quantum cryptography.
Summary
Section titled “Summary”| Principle | How IceRoot applies it | Section |
|---|---|---|
| Boring by design, safe by design | Standard, studied parts; the cost of every rule stated | This section |
| Consensus records ownership | Explorer, indexer, market-data service, wallets, metadata hosting, order books and matching, and the IceRoot Connector run outside consensus; trades settle by atomic swap | Network architecture, Integrations |
| Assets are ledger objects | No virtual machine; one fixed operation set; fixed supply, with no minting; authorities never debit or move holders’ units or change provenance | Accounts, transactions and native assets |
| Prices outside consensus | Market data comes from a separate service; creators cannot set prices | Economics, Integrations |
| Bounded data | Memo of at most 255 bytes, paid by size, never executable, never provenance | Accounts, transactions and native assets |
| Post-quantum only | Scheme identifier on every signature; ML-DSA-65 only | Post-quantum cryptography |
| Trust stated | Trust label on every migrated asset and route; bridges distinguished from verified routes | Migration, Security model and assurance |
| Determinism and full replay | Every rule from height 1; activation heights; no other chain or price source in validity; canonical encoding | Governance and protocol upgrades |
| Run-time invariants | Supply check after every block; economic results committed in the header | Accounts, transactions and native assets, Economics |
| No discretionary power | No on-chain governance; vesting entries cannot be revoked; no rollback of finalized history | Governance and protocol upgrades |
| Separation of duties | Separate processes; four validator keys | Network architecture, Post-quantum cryptography |
Network architecture
Section titled “Network architecture”Heartwood Core runs each duty of an IceRoot node in its own operating-system process, keeps validator keys out of every network-facing process, and connects nodes to each other only over TLS 1.3 authenticated with post-quantum keys.
Heartwood Core
Section titled “Heartwood Core”Heartwood Core (“Heartwood”) is IceRoot’s node software, written in Rust. It is a Cargo workspace of separate crates. The cryptographic primitives sit in their own crate, so the code that signs and verifies can be reviewed on its own.
By default, Heartwood never runs as one monolithic daemon. A single binary, heartwood, runs each role as its own operating-system process:
heartwood <role> <command>
roles: relay | forger | indexercommands: run | start | stop | restart | status | logA validator operator therefore runs, for example, heartwood relay start and heartwood forger start as two processes with separate duties. A combined mode that runs relay and forger in one process exists for testing. No default configuration or command selects it, because it would place a validator key inside the process that faces the network.
Processes and keys
Section titled “Processes and keys”| Process | Key it holds | Listens for | Does |
|---|---|---|---|
| relay | node key | peers (TLS 1.3, wss://) and node API clients | Validates and relays blocks and transactions, keeps the transaction pool, serves the node API |
| forger | consensus key | nothing: no public listener and no API; its only persistent state besides its key is its signing record | Produces and signs its validator’s block in its slot; signs online attestations |
| indexer | none | history search and event stream clients | Serves history search and the live event stream; measures validators’ reward sharing |
| IceRoot Connector (outside Heartwood) | migration attestation key | described in Integrations | Rebuilds migration lists from its own source-chain node or declared provider and signs its validator’s attestations |
A validator’s fourth key, the account key that holds its funds, is on no server. The roles of the four keys are defined in Post-quantum cryptography.
Diagram source
flowchart LR
subgraph OP["One validator operator"]
F["forger<br/>(consensus key)"] -->|"internal routes,<br/>allow-listed"| R["relay<br/>(node key)"]
R -->|"chain data"| I["indexer"]
C["IceRoot Connector<br/>(attestation key)"] --- SN["source-chain node<br/>or declared provider"]
end
R <-->|"TLS 1.3, wss://"| P["peer relays"]
CL["wallets, exchanges,<br/>explorers"] -->|"node API"| R
CL -->|"history search,<br/>event stream"| IThe relay is the node’s contact with the network. It connects to peers, validates and relays blocks and transactions, keeps the transaction pool and serves the node API: state, single objects, block contents, fees, configuration and transaction broadcast (see Integrations). It also passes the forger’s blocks to the network.
The relay never reads a validator’s keys. When it needs its validator’s online attestation, it asks the forger to sign it.
Forger
Section titled “Forger”The forger holds the validator’s consensus key. It produces and signs the validator’s block in the validator’s slot, and it signs online attestations when its relay asks. It is a thin client: it opens no public listener and serves no API, and apart from its key file its only persistent state is the signing record described below.
The forger talks to its relay over a small set of internal routes on the relay’s P2P listener:
- current round;
- slot number;
- network state;
- unconfirmed transactions;
- post block;
- sync;
- a restricted event route.
The relay admits these routes only for addresses on its remoteAccess allow-list. An empty allow-list admits nobody, and the node logs a warning. A forger may run on a different host from its relay. The relay then obtains the forger’s online attestations over an authenticated link: [TBD: forger-relay link authentication].
Indexer
Section titled “Indexer”The indexer is a separate process, heartwood indexer. It serves history search and a read-only live event stream, and it measures validators’ reward sharing; the relay and the forger take no part in that measurement (see Integrations). Keeping history search out of the relay keeps expensive queries away from the process that validates blocks.
Keys and the signing record
Section titled “Keys and the signing record”A Heartwood process refuses to start if any key file it loads is readable by group or others.
For each key, the forger keeps a persisted signing record: the last height, slot and block hash it signed. It writes the record and flushes it to disk (fsync) before a block leaves the forger. It never signs a different block for a slot it has already signed; a retry re-sends the identical signed bytes. The record also holds the height that the forger must place in the maxHeightPreviouslyForged field of its next block header (see Consensus).
On every start, the forger first syncs to the tip. It then takes as its previous forged height the higher of two values: the height in its signing record, and the height of its own latest block on chain. If the local record is missing, or older than the chain, the forger refuses to forge until the operator confirms with a command. A forger that had lost track of its own blocks could otherwise sign a header that contradicts one it signed before, which the network treats as evidence of misbehaviour.
The operator rule follows from the same reasoning: never run one key on two forgers.
Operator diagnostics
Section titled “Operator diagnostics”No Heartwood process loads or calls a language model or any other machine-learning model, and nothing such a model produces influences validity, forging or peer handling. A separate diagnostic tool, the doctor, runs deterministic checks of a node’s configuration and state. It exports a report with keys, secrets and IP addresses removed, and it offers a read-only Model Context Protocol interface that the operator’s own client starts over SSH: the interface can run the checks and read the report, redacted log summaries and the documentation of each check, and it has no network listener, no tool that writes or runs commands and no access to keys. Any model behind that client runs wherever the client runs, never on the validator host.
Peer-to-peer transport
Section titled “Peer-to-peer transport”Nodes exchange messages with WebSocket framing [8] over TLS 1.3 [5], so every connection is wss://.
| Property | Value |
|---|---|
| Protocol | TLS 1.3 only |
| Key exchange | Hybrid X25519 with ML-KEM-768 only |
| Peer authentication | ML-DSA-65 node key, presented during connection setup; transcript signed with it |
| Node identity | Hash of the node key; no certificate authority |
| Validator check | A validator’s presented node key must equal its registered node key |
| Maximum message size | [TBD: block, transaction and message size limits] |
| Incoming connections | Rate-limited |
During connection setup, each node presents its ML-DSA-65 node key and signs the connection transcript with it. The transcript is unique to the connection, so the signature cannot be replayed into another connection. There is no certificate authority: a node’s identity is the hash of its node key. For a validator, the key must match the node key registered for it on chain, so a relay cannot impersonate a validator’s node without that validator’s node key.
The hybrid key exchange [7] derives each session key from both X25519 [6] and ML-KEM-768 [2]. The session stays confidential as long as either of the two holds, which protects recorded traffic against an adversary who can break X25519. Nodes offer and accept only this key exchange, only ML-DSA-65 signatures and only TLS 1.3. There is nothing weaker to fall back to.
Each handshake costs the accepting node one ML-DSA-65 signature, and each side sends at least 1,952 bytes of public key and 3,309 bytes of signature. Incoming connections are rate-limited for this reason.
Network defence
Section titled “Network defence”Missed slots carry no penalty and finality tolerates 17 validators offline, so flooding validators threatens liveness, not safety. Every node knows each round’s forging order when the round starts, so the next forgers are the likely targets. Heartwood limits that exposure with fixed rules and simple scoring:
- Sentry relays. A validator can keep the relay that presents its registered node key private, behind public sentry relays that carry no validator identity, and its forger can connect to two or three relays with failover. Sentries are optional; the validator hardening guide at
docs.iceroot.comsets them up step by step. - Peer scoring. A peer’s misbehaviour accumulates in a score, and the peer is banned when the score crosses a limit.
- Eclipse resistance. A node keeps diverse outbound peers, across subnets and providers, and caps inbound connections per subnet.
- Public APIs apart. Public API endpoints run on separate API nodes behind caching and rate limits, never on a validator’s relay.
Version handshake
Section titled “Version handshake”When two nodes connect, each announces its protocolVersion and the next scheduled activation, as a height and a version. Two peers are compatible when their protocol versions at the common tip are equal.
A node that sees peers announce an activation it does not know logs a warning for its operator. It never halts and never forges because of what peers claim; an announcement is a hint, not an instruction. Separately, a minimum software version, p2p.minimumVersions, keeps known-bad software off the network. It rises at each activation height, as described in Governance and protocol upgrades.
Online attestations and the forging gate
Section titled “Online attestations and the forging gate”Each validator’s forger signs an “I am online” status message, the online attestation, whenever its relay asks. It signs with the consensus key, under a domain tag reserved for this message, and the message carries the node’s software version. The relay presents these attestations to its peers.
The forging gate uses these attestations. A forger produces a block only when its relay sees at least 27 of the 53 active validators online through their attestations, and a second local check, the relay’s quorum check on its peers, also passes: [TBD: forging quorum check rule].
The forging gate is a local liveness safeguard, not a consensus rule. A block’s validity never depends on it. It stops a forger that is cut off from most of the network from producing blocks the rest of the network would discard. It is separate from the finality threshold of 36 of 53 described in Consensus.
Each node keeps the last software version it has seen for each validator in a local table that survives restarts. That table is not part of consensus and never enters consensus hashing. The software versions in the attestations also feed the readiness count shown before an activation height (see Governance and protocol upgrades).
Transaction pool admission
Section titled “Transaction pool admission”A vote enters a node’s transaction pool only if every validator it names is attested online, and a resignation revoke only if the validator revoking its resignation is attested online. Otherwise the pool refuses the transaction with the error ERR_OFFLINE.
Storage and retention
Section titled “Storage and retention”Every node keeps every block, every header and every transaction. There is no pruning. The node database is SQLite.
Because every node keeps the full chain, any node can validate it from genesis, serve history and help new nodes sync. Each Heartwood release also carries a checkpoint of the chain for nodes that join the network: [TBD: release checkpoint contents and how a joining node uses it]. A joining node can still validate the whole chain from genesis. The checkpoint that a recovery release publishes is a separate record (see Consensus).
Networks
Section titled “Networks”| Network | Purpose | Parameter values | Genesis |
|---|---|---|---|
| Mainnet | Real economic value | Compiled into the release binary | One genesis; every activated rule stays for replay; [TBD: mainnet genesis date, chain id and genesis hash] |
| Public testnet | Validator onboarding; testing with mainnet values | The same values as mainnet, compiled into the release binary | May start over from a new genesis |
The public testnet runs with the same parameter values as mainnet, and mainnet mirrors it with real economic value. Validators onboard on the public testnet. For both networks the parameter files are compiled into the release binary, and a node refuses to start if a copy in its configuration directory differs (see Governance and protocol upgrades).
Every signature commits to its network’s chain id and genesis hash, so a transaction signed for one network is invalid on any other network (see Post-quantum cryptography).
Consensus
Section titled “Consensus”IceRoot reaches agreement with QDPoS, a post-quantum delegated proof of stake: ROOT holders elect 53 validators, the validators produce blocks in turn in 8-second slots, and a Byzantine fault tolerant rule carried inside the block headers makes blocks final, after which they are never reverted.
Consensus has two layers. Block production follows a fixed schedule and never waits for finality. Finality follows production: every node computes it from the headers of blocks already produced, with no messages beyond the blocks and 8 bytes per header.
Parameters
Section titled “Parameters”| Parameter | Value |
|---|---|
| Active validator seats | 53 |
| Slot (block interval) | 8 s |
| Round | 53 slots, 424 s (about 7 minutes) |
| Election check | Every 24 rounds, 10,176 s (about 2.8 hours) |
| Seats changed per set change | At most 1 |
| Validators named in a vote | At most 53; at least 20 in a vote that names validators |
| Share of a vote for one validator | At most 500 basis points (5 %) of the voter’s weight |
| Vote weight of an account holding more than 5 % of ROOT’s supply | Zero, judged at each round’s snapshot |
| Finality threshold | 36 of 53 |
| Implied-vote window | [TBD: implied-vote window] |
| Finality fields per header | 2 unsigned 32-bit integers, 8 bytes |
| Time to finality | At least 71 blocks (568 s), by the rules |
| Typical time to finality, from analysis of random forging orders (all validators online, no missed slots) | About 71 to 108 blocks (568 to 864 s); about 10.8 minutes on average |
| Safety bound | At most 18 Byzantine validators; 16 next to a set change |
| Liveness bound | Up to 17 crashed validators |
| Stall alert | 4 rounds without new finality (1,696 s, about 28 minutes) |
| User-transaction pause | 24 rounds without new finality (about 2.8 hours) |
| Forging gate (local safeguard) | 27 of 53 validators seen online |
| Validator registration surcharge | 250 ROOT |
| Reward-sharing declaration surcharge | 25 ROOT |
| Jail length | [TBD: jail length in set changes] |
| Withheld-reward period | [TBD: number of rounds] |
Timings in this section are derived from the rules, or from analysis of the rules with random forging orders, under the stated conditions; none is a measurement. The slot length and the number of seats cannot change after height 1 (see Governance and protocol upgrades).
Validators and voting
Section titled “Validators and voting”The 53 seats go to the registered validators with the most vote weight, through the set changes described below.
Any account can vote, except a validator account (see below). A vote names at most 53 validators, the number of seats. A vote that names validators splits the account’s weight among them in integer basis points that sum to 10,000, with at most 500 basis points, 5 % of the account’s weight, for any one validator, so such a vote names at least 20 validators. An empty vote withdraws the account’s current vote. A vote’s entries are sorted in bytewise order, and its contents are at most 1,280 bytes. A vote identical to the account’s current vote is rejected, and so is an empty vote from an account that votes for no one. Because the 5 % limit applies to each account’s own weight, splitting ROOT across several accounts never lets a holder give one validator more than 5 % of its vote weight, so support for each validator has to be broad. Wallets can fill a vote automatically, with diversity across operators and hosting providers as the default (see Integrations).
Vote weight is the voter’s liquid ROOT balance. Voting locks or bonds nothing, only ROOT carries vote weight, and every change to a voter’s ROOT balance changes its vote weight. ROOT held in a hash time-locked transfer or a time-locked entry is outside every balance and carries no vote weight. Validators are ranked by vote weight in a snapshot taken at the start of each round.
At that snapshot, an account whose liquid ROOT balance exceeds 5 % of ROOT’s supply carries no vote weight for the round. The threshold, in base units, is computed once per round, in unsigned 128-bit integer arithmetic, from S, ROOT’s supply in the consensus supply counters at the snapshot (issued minus burned, with units held in hash time-locked transfers and time-locked entries still counted):
The account’s vote stays recorded and counts again from the first snapshot at which its balance no longer exceeds the threshold. The rule keeps a single large account, such as a custodial or team wallet, from electing validators with its whole balance. A holder can still split ROOT across accounts to stay below the threshold; such splitting is deliberate and visible on chain.
A validator joins with a validator registration, which pays a 250 ROOT surcharge on top of the size-based fee (see Accounts, transactions and native assets) and records the validator’s name and its consensus, node and migration attestation keys, each key with a proof of possession (see Post-quantum cryptography). The name follows the rules for every name on IceRoot, and an account that already holds a name registers under it; the name of an account that is or ever was a validator never moves to another account (see Accounts, transactions and native assets). A validator can resign temporarily or permanently. A temporary resignation can be revoked; a permanent one cannot. A resignation that would leave fewer than 53 validators that have not resigned is refused. A validator declares what it shares with its voters in a SHARE_DECLARE transaction, which pays a 25 ROOT surcharge; consensus stores the terms and pays nothing (see Integrations).
The account that registers a validator, its validator account, cannot cast or change a vote, and its balance carries no vote weight, so the block rewards credited to it never add to its own rank. A registration is refused while the account has an active vote. An account that resigns permanently becomes an ordinary account and may vote again; a temporary resignation keeps the restriction. A validator can still send ROOT to another account and vote from there, so the rule ends automatic compounding rather than every self-vote: such a self-vote is deliberate and visible, because the explorer and wallets show the share of each validator’s vote weight that comes from addresses funded directly by its validator account (see Integrations).
Slots, rounds and forging order
Section titled “Slots, rounds and forging order”Slots last 8 s and a round is 53 slots. Each seated validator owns exactly one slot per round, so a round lasts 424 s. Rounds are defined by slots, not by block counts: the first block whose slot lies past the end of a round opens the next round, even when slots in the previous round stayed empty.
The forging order of each round is a fresh permutation of the 53 seated validators, drawn by an unbiased shuffle that every node computes identically. Each validator is equally likely to hold any position in the round. Every node therefore knows which validator owns each slot, and a block is valid only if that validator signed it.
A missed slot stays empty; no other validator fills it. Misses are recorded in the node database, as events and as a 30-day productivity figure per validator. They carry no penalty and never trigger a rollback. Separately, a forger produces a block only when it sees at least 27 of the 53 validators online, a local safeguard rather than a consensus rule (see Network architecture).
Rewards and set changes
Section titled “Rewards and set changes”Block rewards follow seated rank. Each round, the 53 seated validators are ranked by vote weight among themselves, and each rank maps to a reward tier (amounts in Economics). Every validator that forges therefore has a tier, including one that has fallen out of the top 53 but keeps its seat until the set change that removes it. A validator without a seat earns no block reward.
The election result is checked every 24 rounds. If the top 53 by vote weight equals the seated set, nothing happens. Otherwise at most one seat changes, and further differences wait for the next check. The change takes effect at the first round start after the block that carries the election result is final under the old set. The old set therefore finalizes its own replacement, and each finality-gated change moves at most one seat, which keeps m at 1 in the safety bound below.
Replacing 19 seats, one more than the safety bound tolerates, needs at least 19 checks, 18 intervals apart: at least 18 × 10,176 s = 183,168 s, about 50.9 hours. Jailed validators leave through the same path, so two jailed validators leave at least 10,176 s (about 2.8 hours) apart.
Finality: votes carried by headers
Section titled “Finality: votes carried by headers”IceRoot’s finality rule is Lisk-BFT, specified in LIP-0014 [14] and analysed by Hackfeld [15], adapted to 53 slot-based seats, a threshold of 36, one-seat finality-gated set changes and ML-DSA-65 header signatures. Every block header carries two numbers, both covered by the forging validator’s signature:
| Field | Meaning |
|---|---|
maxHeightPreviouslyForged | Height of the previous block this validator forged |
maxHeightPrevoted | Height of the highest block with at least 36 implied prevotes |
Each field is an unsigned 32-bit integer. Every node recomputes maxHeightPrevoted, and a block that carries a different value is invalid. A maxHeightPreviouslyForged that contradicts a block the validator signed earlier is evidence of misbehaviour (see Evidence and penalties). Forging a block is also voting:
- Implied prevote. A block at height h forged by validator V counts as a prevote by V for every block from the height after V’s previous block up to h.
- Implied precommit. The same block counts as a precommit by V for every earlier block that already has at least 36 implied prevotes.
- Window. Implied votes reach back a bounded number of heights: [TBD: implied-vote window].
- Finality. A block with at least 36 implied precommits is final, and so is every block before it. The finalized height is the height of the highest final block.
Votes are counted against the validator set recorded for each height, so every node derives the same finalized height from the same chain. The consensus key signs blocks and online attestations only; there are no separate finality votes.
Finality: threshold and timing
Section titled “Finality: threshold and timing”The threshold follows the LIP-0014 formula for 53 seats:
A block B cannot become final sooner than 71 blocks after it. B carries its own forger’s prevote; 35 blocks from other validators bring its prevotes to 36; then 36 blocks from distinct validators bring its precommits to 36.
The bound of 71 blocks follows from the rules. How much longer finality takes depends on the forging order. Analysis of the rules with random forging orders, with all validators online and no missed slots, gives about 71 to 108 blocks: about 568 to 864 s (9.5 to 14.4 minutes), about 10.8 minutes on average, a lag of about 1.3 to 2.0 rounds. With 17 of 53 validators offline, the highest lag in the same analysis is 2.96 rounds. These figures describe typical orders, not an upper bound: an unfavourable forging order that the rules allow can take longer.
Diagram source
flowchart LR
A["Block B at height h<br/>1 implied prevote"] --> B["35 blocks by other validators<br/>B has 36 implied prevotes"]
B --> C["36 blocks by distinct validators<br/>B has 36 implied precommits"]
C --> D["B and its ancestors are final<br/>earliest at h + 71"]Safety, liveness and set changes
Section titled “Safety, liveness and set changes”Safety. With a stable validator set, two conflicting blocks cannot both be finalized while at most 18 of the 53 validators are Byzantine. Two sets of 36 validators drawn from 53 share at least 2 × 36 − 53 = 19 members, so finalizing two conflicting blocks requires at least 19 validators to sign contradicting headers, and those headers identify every one of them.
Set changes. When the set changes between two finalized blocks, the margin shrinks by two validators per changed seat (Hackfeld [15], Theorem 4.4(b)). With m seats changed, safety needs at least 35 + 2m honest validators:
Finality-gated, one-seat changes keep m at 1 or less, so the bound next to a set change is 16 Byzantine validators. An independent review of this rule is described in Security model and assurance.
Liveness. Finality is proven to progress with up to 17 crashed validators. It is not proven to progress against coordinated forking by Byzantine validators: a Byzantine minority that builds competing branches on purpose can delay finality. With 18 or more seats offline, fewer than 36 validators can vote and no block becomes final; blocks are still produced as long as a forger’s relay sees at least 27 validators online.
Fork choice and proofs of finality
Section titled “Fork choice and proofs of finality”Between competing chains a node prefers the larger maxHeightPrevoted, then the greater height, then the block received in its own slot. It never moves below its local finalized height. A finalized block is never reverted, and a peer serving a chain that conflicts with finality is disconnected.
A proof that a block is final is the chain of signed headers from that block to the block that finalizes it: at least 71 headers, and with all validators online and no missed slots typically 71 to 108 headers, about 250 to 380 KB; missed slots lengthen it. A verifier checks each header’s ML-DSA-65 signature against the validator set for its height and recomputes the implied votes. Each set change is carried in a block that the old set finalizes, so a verifier that knows one validator set can follow each subsequent change from the chain; a recovery record is the exception, and its hash is published with its release (see Recovery from a permanent loss of seats). The exact data a verifier reads to track the set is [TBD: validator-set data for finality proofs]. Destination chains use this proof to accept exits from IceRoot (see Migration).
When finality stalls
Section titled “When finality stalls”A stall appears as a growing gap between the tip and the finalized height. Two levels respond:
| Rounds without new finality | Response |
|---|---|
| 4 (1,696 s, about 28 minutes) | Nodes raise an alert, the API reports “stalled” and wallets can warn. Production and transactions continue. |
| 24 (10,176 s, about 2.8 hours) | A consensus rule lets blocks carry only evidence and validator system messages ([TBD: list of validator system messages]) and the claims and refunds of hash time-locked transfers, and no other user transactions. |
Both levels lift automatically when finality resumes. No stall, however long, lowers the threshold of 36; a recovery release replaces the validator set, not the threshold. The 4-round alert lies above the typical lag and above the highest lag found in the analysis with 17 validators offline, 2.96 rounds.
Evidence and penalties
Section titled “Evidence and penalties”Honest validators never sign contradicting headers; each forger keeps a persisted signing record that prevents it (see Network architecture). Two different headers signed by the same validator are first ordered, as LIP-0014 [14] specifies, by maxHeightPreviouslyForged, then by maxHeightPrevoted, then by height. They contradict each other when:
- both carry the same
maxHeightPrevotedand the second header’s height is not greater than the first header’s height, which covers double forging; - the second header’s
maxHeightPreviouslyForgedlies below the first header’s height, so their implied votes overlap; - the second header carries a lower
maxHeightPrevotedthan the first.
A contradicting header pair is the only evidence of consensus misbehaviour: one typed evidence object with exactly one byte encoding, holding the two headers and their two ML-DSA-65 signatures (2 × 3,309 bytes). Anyone can include evidence in a block. Every node verifies it against the recorded validator sets and applies the penalty automatically, and the first evidence against each key is kept forever. Once a node knows that a producer signed two blocks for one slot, it never picks either block as the chain tip.
A validator with valid evidence against it is jailed: it is removed at the next set change and cannot be elected for [TBD: jail length in set changes]. Its block rewards are withheld, that is burned, for [TBD: number of rounds]. Nothing is slashed: there is no self-bond, voters’ funds are never touched, and missed blocks carry no penalty. False migration attestations carry the same penalties; how such an attestation is proven is [TBD: evidence format and procedure for false migration attestations] (see Migration).
Recovery from a permanent loss of seats
Section titled “Recovery from a permanent loss of seats”If 18 or more seats are permanently lost, no block can become final. Finality is then restored only by a coordinated public release from the release authority (see Governance and protocol upgrades). The release installs a recovery record at a fixed round named in the release: a new validator set with a fresh set identifier, anchored at or above the finalized height so that no finalized block is reverted, with the old set sealed. The record’s hash is published as a weak-subjectivity checkpoint for new nodes. There is no automatic on-chain forced change of the validator set.
Genesis validator set
Section titled “Genesis validator set”All 53 seats at genesis are held by independent operators, selected by the IceRoot team from the operators of the public testnet; each applicant confirms the published validator independence statement during selection. The genesis block registers the 53 validators and carries no votes: no genesis account votes, so every genesis validator starts with zero vote weight, and like every validator account, a genesis validator’s account cannot vote. From the first election check on, a registered validator with more vote weight than a seated one can take its seat, one seat per check (see Rewards and set changes).
Seat concentration is reported publicly on the explorer, outside consensus. Validators declare their operator, hosting provider and country, and the explorer shows seats and vote weight per declared operator and per hosting provider, with an alert when one operator or hosting provider reaches 6 seats and again at 18 seats (see Integrations).
Post-quantum cryptography
Section titled “Post-quantum cryptography”Every signature the IceRoot Network verifies, from block 1, is an ML-DSA-65 signature as standardized in FIPS 204 [1], and no classical signature scheme authenticates anything in consensus.
One signature scheme
Section titled “One signature scheme”ML-DSA-65 signs:
- account transactions, including second-key, multisig and key-rotation signatures, the swap offers that makers sign off-chain and the name-transfer authorizations that holders sign off-chain;
- blocks and validators’ online attestations;
- migration attestations;
- the P2P identity of every node.
ML-DSA-65 is the FIPS 204 parameter set at NIST security category 3. No classical signature is accepted anywhere in consensus. Every signature carries a signature-scheme identifier and length-prefixed signature bytes, so the scheme is an explicit, versioned field of each format rather than an assumption built into it. ML-DSA-65 is the only scheme the protocol accepts.
Why ML-DSA-65
Section titled “Why ML-DSA-65”- Standardized. FIPS 204 is a final NIST standard.
- No known practical attack. No practical attack on ML-DSA-65 at its claimed security level is publicly known as of [TBD: publication month and year].
- Recommended. The UK NCSC recommends ML-DSA-65 as providing appropriate levels of security and efficiency for most use cases [20].
- Recoverable. FIPS 204 key generation is a deterministic function of a 32-byte seed, so a recovery phrase restores the same key in every conforming implementation.
- Deterministic to verify. Verification uses only integer arithmetic and hash functions, so conforming verifiers reach the same result on every input, as consensus requires. The verification path was externally audited during the public testnet, before launch (see Security model and assurance).
The cost is size. Keys and signatures are large, and ML-DSA signatures cannot be aggregated. IceRoot’s formats account for both: public keys travel only when needed, and finality counts votes implied by block headers instead of collecting signatures (see Consensus).
| Item | Size |
|---|---|
| ML-DSA-65 public key | 1,952 bytes |
| ML-DSA-65 signature | 3,309 bytes |
| Signatures on a transaction with a second key | 2 × 3,309 = 6,618 bytes |
| Signatures on a 3-of-5 multisig transaction | 3 × 3,309 = 9,927 bytes |
| Block signature | 3,309 bytes |
| Address (before encoding) | 32 bytes |
Signatures, ids and witnesses
Section titled “Signatures, ids and witnesses”Transactions and blocks carry their signatures in a witness: the signature-scheme identifier followed by length-prefixed signatures. A transaction id is a domain-tagged SHA-256 hash of the unsigned bytes, so it does not depend on the signatures. A transaction’s id is therefore fixed before anyone signs, and no change to the witness can change it. Blocks commit to transaction ids and to signatures through two separate roots (see Accounts, transactions and native assets).
Signing domains
Section titled “Signing domains”Every signed message has the same shape:
The tag names the purpose, such as a transaction, a block or an online attestation, from one registry of domain tags. The chain id and the genesis hash bind the signature to the IceRoot Network. H is SHA-256 [3]. This paper uses H with that meaning throughout and writes every domain tag explicitly as part of the hashed input, as the AssetID formulas do. A signature made for one purpose is therefore not valid for another, and a signature made for IceRoot is not valid on another chain. Off-chain messages that a wallet signs use their own tags, so they cannot be presented as transactions.
All signatures on one transaction (the account key, the second key, multisig keys) sign this same message, in any order, and no signature covers another. Several parties can sign in parallel and offline; the transaction is complete when the required signatures are attached.
Diagram source
flowchart LR
U["Unsigned transaction bytes"] --> H["H = SHA-256"]
H --> M["m = tag ‖ chain_id ‖ genesis_hash ‖ H"]
M --> S["Each required key signs m with ML-DSA-65<br/>account key, second key, multisig keys"]
S --> W["Witness: scheme identifier and<br/>length-prefixed signatures"]Hashing and encoding
Section titled “Hashing and encoding”Every structure writes integers little-endian and hashes with SHA-256 [3]. Each kind of hash (transaction ids, Merkle trees, digests, AssetIDs, migration identifiers) carries its own short domain tag from the same registry, so hashes computed for different purposes are domain-separated. The hash lock of a hash time-locked transfer is the exception: consensus checks it as the plain SHA-256 hash of a 32-byte secret, with no domain tag, so that the same lock works on the other chain of a swap (see Accounts, transactions and native assets). The content hash of an asset’s metadata document is also a plain SHA-256 hash; wallets compute it over the file, and consensus only stores it. ML-DSA-65 uses its internal SHA-3 family functions [4], as FIPS 204 specifies. Against a quantum computer, Grover’s algorithm [19] reduces a preimage search on SHA-256 to about 128-bit security.
Addresses
Section titled “Addresses”An address is a 32-byte hash of a public key, written in Bech32m [9] with a readable IceRoot prefix: ice on mainnet and tice on the public testnet, so addresses read ice1... and tice1... and an address for one network is not mistaken for the other. A mainnet address is about 62 characters of lowercase letters and digits. The 6-character Bech32m checksum detects every error that touches up to 4 characters and can point to where the error is. A 32-byte hash gives about 128-bit security against a large quantum computer.
A transaction names its sender by address, not by public key. The 1,952-byte public key travels only in the account’s first transaction and in a key rotation, which carries the new key; nodes keep the account’s current key in state. Carrying the key in every transaction would add about 58 % to a one-recipient transfer.
Key generation and recovery
Section titled “Key generation and recovery”Wallets generate 24-word BIP39 recovery phrases [10] and accept 18-, 21- and 24-word phrases on import; keys use hardened derivation only [11]. The ML-DSA-65 key comes from a SLIP-0010-style derivation [12] of the phrase’s seed. Phrases shorter than 18 words are refused: 18 words carry 192 bits of entropy, the seed strength FIPS 204 requires for ML-DSA-65, and 24 words carry 256 bits.
IceRoot’s wallets have their own recovery phrase and never share a process or a key store with another chain’s wallet.
There is no recovery key. A phrase restores the keys derived from it, and an account whose key and phrase are both lost cannot be recovered. A key that may be exposed is replaced with a key rotation while its holder still controls it.
Key rotation, second keys and multisig
Section titled “Key rotation, second keys and multisig”- Key rotation.
KEY_ROTATEis signed by the account’s current key and carries a proof of possession by the new key. The address stays the same. The same operation rotates the account’s second key. - Second key. An account may register a permanent second key. From then on every transaction from the account needs both signatures. The second key can be rotated. It suits holdings, or a validator’s account, that should not be spendable with one key alone.
- Multisig.
MULTISIG_REGISTERconverts an existing account into an M-of-N multisig account, which keeps its address; no address is ever derived from several parties’ keys. It supports at least 3-of-5, and the maximum number of keys is [TBD: multisig key cap].
Validator keys
Section titled “Validator keys”A validator holds four separate ML-DSA-65 keys, each registered with a proof of possession:
| Key | Held in | Signs |
|---|---|---|
| Account key | The operator’s wallet, never on a server | The validator’s transactions; it may register a second key |
| Consensus key | The forger | Blocks and online attestations; never transactions |
| Node key | The relay | The P2P connection transcript; its hash is the node’s identity |
| Migration attestation key | The IceRoot Connector process | Migration attestations |
Every node has a node key; a validator’s must match the node key it registered. Keeping the keys apart means a host holds only the key its role needs (see Security model and assurance).
Transport security
Section titled “Transport security”P2P connections accept only TLS 1.3, only the hybrid key exchange X25519 with ML-KEM-768 and only ML-DSA-65 node authentication. The transport, and why the hybrid exchange protects recorded traffic, is described in Network architecture.
Where classical cryptography remains
Section titled “Where classical cryptography remains”Classical signatures appear only outside consensus: inside IceRoot Connectors, which check source chains’ own signatures during migration (see Migration), and in the launchpad distribution kit, which checks the other-chain wallet signatures that bind buyers to their IceRoot addresses (see Integrations). They never authenticate anything in consensus, and a migration attestation signed with a classical scheme is invalid.
Accounts, transactions and native assets
Section titled “Accounts, transactions and native assets”IceRoot records ownership as balances of standardized assets held in accounts, and it changes those balances only through a fixed set of signed operations that treat every asset, ROOT included, in the same way.
Accounts
Section titled “Accounts”An account is identified by its address (see Post-quantum cryptography). It holds one balance per AssetID and one sequential nonce that is shared across all assets. Each transaction carries the sender’s next nonce, so a signed transaction applies at most once, and the transactions of one account apply in order. An account comes into existence with its first credit.
Every amount is an unsigned 128-bit integer counted in base units: on the wire, in state, in the node database and in the API. The API writes amounts as decimal strings of base units. For an asset with d decimals, one base unit is 10^-d of a whole unit. A 128-bit amount holds up to about 3.4 × 10^38 base units, which is about 3.4 × 10^20 ROOT.
ROOT has 18 decimals, so its base unit is 10^-18 ROOT. ROOT has a reserved AssetID, and an API request that names no assetId refers to ROOT.
Transactions
Section titled “Transactions”A transaction contains:
- the sender’s address and nonce;
- the fee, always in ROOT;
- an optional memo;
- the fields of exactly one operation, where every value operation names its AssetID (the field
asset_idin the encoding,assetIdin the API), and an atomic swap names two; - the sender’s public key, in the account’s first transaction only; a
KEY_ROTATEcarries the new key once, and no other transaction carries a key; - the witness: a signature-scheme identifier and length-prefixed signatures.
The transaction id is a domain-tagged SHA-256 hash of the unsigned bytes, so adding or replacing signatures never changes it (see Post-quantum cryptography). Decoding is strict: input that is not in its single canonical encoding is rejected, not normalized.
Operations
Section titled “Operations”The operation set is fixed. Each transaction performs one of the following operations.
| Operation | What it does |
|---|---|
| Transfer | Moves one asset from the sender to 1 to 256 recipients, with one memo |
BURN | Destroys an amount of one of the sender’s own assets |
| Vote | Splits the sender’s ROOT vote weight across 20 to 53 validators, at most 5 % to each, or withdraws the sender’s vote; a validator account cannot vote (see Consensus) |
| Validator registration | Registers a validator with its name (see Names) and its consensus, node and migration attestation keys, each key with proof of possession; pays a 250 ROOT surcharge; refused while the sender has an active vote |
| Validator resignation, and its revoke | Resigns a validator, temporarily or permanently, or revokes a temporary resignation |
SHARE_DECLARE | Records a validator’s reward-sharing terms: its share in basis points, a payout interval of one day or seven days, and its payout address; sent from the validator account; pays a 25 ROOT surcharge; moves no funds (see Integrations) |
NAME_REGISTER | Gives the sending account its one name; pays a 125 ROOT surcharge |
NAME_CLAIM | Moves a name to a fresh account, which submits the holder’s signed authorization as its first transaction; pays a 125 ROOT surcharge |
| Second-key registration | Adds a permanent second key that must co-sign every subsequent transaction |
KEY_ROTATE | Replaces the account key or the second key; the current key signs, the new key proves possession, and the address stays the same |
MULTISIG_REGISTER | Converts an existing account into an M-of-N multisig account |
ASSET_CREATE | Creates a native asset and credits its whole supply, fixed at creation, to the creator |
ASSET_METADATA_UPDATE | Replaces an asset’s metadata URI and content hash together |
| Authority propose, accept, cancel | Moves the asset authority or the migration authority to a new holder |
| Authority renounce | Gives up one of those authorities permanently |
| Atomic swap | Exchanges two assets between a maker, who signed an offer, and a taker, who submits it and pays the fee; all or nothing, with no partial fills |
| Lock, claim, refund | A hash time-locked transfer: locks units for a recipient under a hash lock and an expiry height; anyone claims for the recipient with the secret until the expiry height is final, or the sender refunds after that |
| Time-locked transfer, claim | Places units of one asset in one or more non-revocable entries, one per tranche, each claimable by its recipient only after its unlock time; the recipient claims |
| Migration operations | Register source networks and external assets (ASSET_REGISTER_EXT); commit, cancel and credit migration lists (MANIFEST_COMMIT, MIGRATE_IN); bind unbound holdings late and cancel a binding; set out-destinations and lifecycle flags; exit through MIGRATE_OUT (see Migration) |
An operation written in code font above carries that exact type name in the encoding and in the API. The type names of the other operations are [TBD: type names of the transfer, vote, validator, second-key, authority, swap, hash time-locked and time-locked operations].
Besides transactions, blocks carry evidence of validator misbehaviour and validator system messages (see Consensus).
Transfers
Section titled “Transfers”A transfer names one AssetID for the whole transaction and pays 1 to 256 recipients. The same operation serves one recipient or many; there are no mixed-asset multipayments. Any asset can be sent to any address. Wallets and exchanges decide which assets they display or credit (see Integrations).
The memo is the only free-form data field in a transaction. Account names and an asset’s name, symbol and metadata URI are text as well, but follow the fixed rules given under Names and Asset record below. The memo holds at most 255 bytes of UTF-8 text [13], and non-canonical UTF-8 is rejected. The memo is signed and is part of the transaction id. A transaction has one memo, with no per-recipient tags.
The memo is never executable. It is never the location of migration provenance, which is typed protocol data (see Migration). Memo bytes count toward the transaction’s size and pay the size-based fee like every other byte.
An account can hold one name, and validators and other accounts share one namespace. A name is 1 to 20 lowercase letters from a to z, with no digits, capitals or symbols, so no digit can stand in for a look-alike letter. Consensus refuses:
- a name that contains
icerootorheartwood, except the IceRoot team’s own names registered in the genesis block; - a name on a short fixed list of reserved names, such as
admin,supportandofficial; - a name that contains a word from the banned-words list, which is part of the published protocol specification and changes only through a release with an activation height; names registered before a change stay valid.
NAME_REGISTER gives the sending account its name, for a 125 ROOT surcharge. A validator registration records a name under the same rules, and an account that already holds a name registers as a validator under it. A name has no renewal and no expiry, and it stays with its account, with one exception. The holder can sign an authorization off-chain, like a swap offer: it names the recipient and an expiry height and is bound to the holder’s current nonce. The recipient submits it with NAME_CLAIM, which must be the recipient’s first transaction and pays a 125 ROOT surcharge. The recipient is therefore a fresh account, one that has never sent a transaction: the new holder announces its ownership itself, and a name never moves onto an account that already has a history. The claim advances the holder’s nonce, and any transaction by the holder cancels an open authorization. After a transfer the old account has no name and may register a new one. The name of an account that is or ever was a registered validator never moves. Sales and any market for names stay outside consensus.
Each name’s record holds its registration height, its transfer count and the height of its last claim, and the node API returns them. A name is a label, not proof of identity: wallets and the explorer always show the address next to it, together with the name’s age and how often and when it last changed hands (see Integrations).
Every transaction pays its fee in ROOT, whatever asset it moves. A holder with no ROOT cannot move assets until they obtain some. Issuers may include a small amount of ROOT in their distributions so that recipients can pay fees; this is practice, not a protocol rule. A migration never includes ROOT (see Migration).
The minimum fee depends on the size of the transaction and on its operation:
Here size is the size of the transaction in bytes, and size/2 is rounded up when size is odd. addonBytes[type] is a per-operation surcharge expressed in bytes, and minFee is the base rate in base units of ROOT. A surcharge of S base units is set as addonBytes[type] = S / minFee; for example, the 250 ROOT validator registration surcharge is 250 × 10^18 base units divided by minFee.
| Fee parameter | Value |
|---|---|
minFee, and the fee of a one-recipient ROOT transfer | [TBD: minFee and the fee of a one-recipient ROOT transfer] |
| Validator registration surcharge | 250 ROOT |
Reward-sharing declaration surcharge (SHARE_DECLARE) | 25 ROOT, on every declaration |
Name registration and name claim surcharges (NAME_REGISTER, NAME_CLAIM) | 125 ROOT each |
| Asset and migration surcharges | [TBD: asset and migration surcharge values] |
| Swap, hash time-locked and time-locked operations | [TBD: fees of the atomic swap, the lock, claim and refund operations, and the time-locked transfer and its claim] |
| Burning ROOT | Zero fee; minimum amount 0.02 ROOT |
| Burning any other asset | Ordinary size-based fee in ROOT; no minimum amount |
Every fee, surcharges included, is divided the same way: 90 % is burned and the rest goes to the forging validator (see Economics).
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Recipients per transfer | 1 to 256 |
| Memo | At most 255 bytes |
| Vote contents | At most 1,280 bytes |
| Transactions per block | [TBD: maximum transactions per block] |
| Block payload, transaction size and P2P message size | [TBD: block, transaction and message size limits] |
Blocks
Section titled “Blocks”A block header carries:
- the payload root, a Merkle root over the signature-free ids of the block’s transactions;
- the witness root, a separate root over their signatures;
- the economic-results hash, 32 bytes (see Economics);
- the two finality fields,
maxHeightPreviouslyForgedandmaxHeightPrevoted(see Consensus); - the forging validator’s ML-DSA-65 signature, made with its consensus key.
Separating the payload root from the witness root fixes each transaction’s id by its content, while the block still commits to every signature. The header carries no total amount; the API computes totals from the block’s transactions (see Integrations).
Asset identity
Section titled “Asset identity”An asset’s identity is its AssetID, a 32-byte value. Names and tickers are metadata and need not be unique. An AssetID is never derived from a ticker or a name.
A native asset’s AssetID is computed from the transaction that creates it:
Here the tag is the domain tag for native AssetIDs, chain binds the id to the IceRoot Network (its chain identifier and genesis hash), and the creator nonce is the nonce of the ASSET_CREATE transaction. Every node derives the same AssetID, with no randomness and no registry. Because an account’s nonce never repeats, no two creations produce the same id. External assets use a different derivation with its own domain tag (see Migration).
Asset record
Section titled “Asset record”The only descriptive fields that consensus stores for an asset are these:
| Field | Rule | Can change |
|---|---|---|
| Name | 1 to 32 bytes of text without control characters | Never |
| Symbol | 1 to 12 characters from A to Z and 0 to 9 | Never |
| Decimals | 0 to 18, set at creation | Never |
| Metadata URI | At most 256 bytes, beginning with https:// or ipfs:// | Only together with the content hash, by the asset authority |
| Content hash | 32 bytes: the SHA-256 hash of the hosted metadata document | Only together with the URI |
The symbol alphabet excludes look-alike letters from other alphabets. The website, description, logo and contact details live in the hosted metadata document, which the URI locates and the content hash commits to. The asset record also keeps the asset’s authorities, its two lifecycle flags and its supply counters, described below. There is no rename operation.
Consensus neither reserves nor deduplicates symbols. The symbol “ROOT” is reserved off-chain, and verification labels come from lists maintained outside consensus (see Integrations).
Supply and distribution
Section titled “Supply and distribution”Every native asset has a fixed supply. ASSET_CREATE credits the whole supply to the creator’s account, and no operation creates further units of any asset: there is no minting, no cap to raise and no key that could dilute holders. ROOT’s issuance follows the block reward rules (see Economics), and the units of a migrated asset arrive only through certified migration under its lifetime cap (see Migration).
A project that needs more units after creation creates a new asset, or keeps a reserve out of the whole supply at creation and releases it publicly, for example on a schedule of time-locked transfers (see Time-locked transfers below). The creator distributes the supply with ordinary transfers of 1 to 256 recipients each. Wallets and the explorer show every native asset as fixed supply.
Authorities
Section titled “Authorities”Each asset has two roles:
- the asset authority replaces the metadata URI and content hash;
- the migration authority controls the asset’s migration routes and lifecycle flags, and can be required to co-sign the asset’s inbound migration lists (see Migration).
The creator chooses the holder of each role: a single-key account or a native multisig account. An M-of-N account with M = 1 covers “any of several addresses”. Both roles default to the creator, and one account may hold both. Neither role can debit, move or freeze any holder’s units, create units or change provenance.
A role moves in two steps. The current holder proposes a new holder, and the proposed account accepts. Until acceptance, the current holder can cancel the proposal. Either role can be renounced, and a renounce is permanent. Renouncing the asset authority freezes the metadata URI and content hash. Renouncing the migration authority freezes the asset’s migration routes and lifecycle flags.
Lifecycle
Section titled “Lifecycle”Consensus keeps two lifecycle flags per asset: whether new inbound migration lists are accepted, and whether migrate-out is open. The migration authority changes them explicitly, under guards; for example, migrate-out opens only for an asset that has an allowed out-destination. The explorer also shows descriptive lifecycle labels, which it derives from counters and records; they are documented at docs.iceroot.com. They are labels, not consensus state. No lifecycle flag or label freezes transfers.
Supply counters and the invariant
Section titled “Supply counters and the invariant”For every asset, consensus keeps five counters: issued, migrated_in, burned, migrated_out and hosted, the units of the asset currently held on IceRoot. ROOT keeps three more, for block rewards, burned fees and donations (see Economics). For ROOT, issued covers the genesis issuance and the block rewards, and burned covers burned fees, BURN operations and the withheld rewards of jailed validators; donation payouts direct part of a block reward to the donation recipients and change neither counter. For a native asset, issued is the whole supply that ASSET_CREATE created and never changes afterwards; a burn adds to burned. After every block, each node checks, for every asset X:
The second sum covers the units held in open hash time-locked transfers and in time-locked entries not yet claimed, both described below. A node that finds a violation stops instead of continuing from a state the rules do not allow. Burned units and migrated-out units are always counted separately, so the record shows whether units were destroyed on IceRoot or left for another chain.
Burning is a protocol operation, not a transfer to a burn address. Any holder can permanently destroy their own units of any asset with BURN(asset, amount). Burned units count as burned, never as migrated out.
Atomic swaps
Section titled “Atomic swaps”An atomic swap exchanges two assets between two accounts in one transaction, all or nothing. The maker signs an offer off-chain with ML-DSA-65, under the offer’s own signing domain (see Post-quantum cryptography), with every signature its account requires. The offer names the maker’s address, the asset and amount the maker gives, the asset and amount the maker wants, an expiry height, and the maker’s nonce at the time of signing.
The taker submits the offer inside a transaction of its own. Consensus accepts the swap only if:
- the maker’s signatures on the offer and the taker’s signatures on the transaction are valid;
- the maker’s nonce still equals the nonce in the offer;
- the block is below the offer’s expiry height;
- the maker holds the amount it gives, and the taker holds the amount the maker wants.
It then moves both amounts in the same transaction, or nothing at all. An offer is filled whole or not at all; it cannot be filled in part. The swap advances the maker’s nonce as well as the taker’s, so an executed offer can never be replayed. Because an offer is bound to the maker’s nonce, any other transaction by the maker also cancels every open offer the maker has signed. The chain keeps no offers and no order book. The taker, who submits the swap, pays its fee in ROOT.
Order books, matching and trading interfaces are off-chain services that anyone may build on this operation (see Integrations). Consensus runs no order book, no automated market maker and no liquidity pool.
Hash time-locked transfers
Section titled “Hash time-locked transfers”IceRoot implements the hashed time-locked contract (HTLC) pattern [21] as three fixed operations for any asset, with no script:
- Lock. The sender names the asset, the amount, the recipient, a hash lock and an expiry height. The hash lock is the SHA-256 hash of a 32-byte secret, with no domain tag, so the same lock can be used on the other chain of a swap. The amount leaves the sender’s balance and is held in the lock. Consensus rejects a lock whose expiry height lies less than 900 blocks (about 2 hours) above the height of its block.
- Claim. Until the expiry height is final, anyone may claim by revealing a 32-byte secret whose SHA-256 hash equals the hash lock. The amount is always credited to the recipient named in the lock, and whoever submits the claim pays its fee.
- Refund. Once the expiry height is final, only the sender can refund, and the amount returns to the sender. From then on no claim is valid.
Consensus checks the secret’s length and hash, the signer of each operation and the lock’s expiry height against the finalized height, and lets each lock end exactly once, by a claim or by a refund. Every operation is an ordinary transaction signed with ML-DSA-65, and the hash lock is SHA-256, so no step on IceRoot relies on classical cryptography. A claim pays its fee in ROOT like every transaction. Because anyone may submit it, a recipient without ROOT can have the other party, or any service, submit the claim; the units still go only to the recipient.
A claim counts once its block is final, and a final claim is never reverted. The minimum lock duration of 900 blocks spans several finality periods, so a recipient has time to claim and to see the claim become final before the lock expires; wallets choose longer locks for swaps with other chains. Because expiry is judged against finality, a finality stall never shortens the claim window, and claims and refunds stay admissible while user transactions are paused (see Consensus). A claim in a block that is reverted can be submitted again, since the secret is already public. The API exposes the secret that a claim reveals, so the other party of a cross-chain swap can use it on the other chain (see Integrations).
A lock moves units that already exist on IceRoot. No lock, claim or refund creates or destroys units or changes a supply counter, and none creates units of an external asset or counts as a migration credit: an external asset’s units reach IceRoot only through certified migration (see Migration). Consensus cannot see the other chain of a swap, so the ordering of the two locks’ expiry times is enforced by the wallets and the documentation, not by consensus (see Integrations).
Time-locked transfers
Section titled “Time-locked transfers”A time-locked transfer places units of one asset in one or more entries, each claimable by its recipient only after its own unlock time. A vesting schedule is one such transaction, with one entry per tranche, and an issuer that kept a reserve at creation releases it on a public schedule the same way. Any sender can make one, for any asset, ROOT included, and its entries are held like the locks of hash time-locked transfers, with no script.
- Unlock times. An unlock time is a slot time: the slot number × 8 s, counted from genesis. A slot’s time does not depend on how many blocks were produced, so each tranche unlocks on its calendar date whatever slots are missed.
- Claims. Nothing unlocks automatically. After an entry’s unlock time, anyone may submit its claim with a transaction. The units are always credited to the entry’s recipient, and the submitter pays the fee in ROOT.
- No revocation. No one can revoke an entry, the sender included.
Locked units sit in escrow, not in any balance: they carry no vote weight (see Consensus), and the supply check counts them together with the units of open hash time-locked transfers. An entry moves units that already exist on IceRoot, so creating or claiming one changes no supply counter. Every operation is an ordinary transaction signed with ML-DSA-65. Each entry pays a surcharge and must hold a minimum amount, which keeps entries from being used for spam: [TBD: time-locked entry surcharge, minimum amount and maximum entries per transaction].
Seedbed
Section titled “Seedbed”Seedbed is IceRoot’s native asset creation and distribution platform. Its interface runs outside consensus. On chain, a Seedbed asset uses the same operations as every native asset: ASSET_CREATE, metadata updates, authority operations, ordinary transfers and time-locked transfers. A Seedbed asset can leave for a project’s own chain through MIGRATE_OUT, to a destination on its allow-list (see Migration).
Diagram source
flowchart LR
A["ASSET_CREATE: whole fixed supply to the creator"] --> B["Distribution by transfers of 1 to 256 recipients,<br/>and by time-locked transfers for vesting and reserves"]
B --> C["Holders transfer, swap and burn"]
A --> D["Asset authority: ASSET_METADATA_UPDATE"]
D --> E["Authority propose and accept, or renounce"]
C --> F["MIGRATE_OUT to an allowed destination (see Migration)"]Economics
Section titled “Economics”ROOT’s supply starts at 100,000,000 ROOT and changes only through fixed protocol rules: block rewards set by validator rank add to it, except the rewards withheld from jailed validators, which are burned and so never add to it; the fee burn and holders’ own burns remove from it.
ROOT is the native token of the IceRoot Network, with 18 decimals, so one base unit is 10^-18 ROOT. ROOT pays every transaction fee, including the surcharges on validator registrations, reward-sharing declarations, name registrations and claims, asset and migration operations and the fees of atomic swaps, hash time-locked transfers and time-locked transfers, whatever asset they move. It is the only asset that carries vote weight (see Consensus), and validator rewards are paid in it. ROOT’s supply grows only through the block rewards described below; no operation creates units of ROOT or of any other asset (see Accounts, transactions and native assets).
Genesis supply and allocation
Section titled “Genesis supply and allocation”The genesis block issues 100,000,000 ROOT, which is 10^26 base units. The supply is created by an explicit issuance record with an issuance counter; no account ever holds a negative balance, including at genesis.
The genesis supply goes to plain key-held accounts, including a team wallet:
[TBD: genesis allocation table, recipients and amounts]
The donation recipients and the validators receive a genesis allocation only if that table lists them, and an allocation to a validator account carries no vote weight. The team wallet is a 2-of-3 native multisig account: any two of its three keys must sign. The team’s wallets are labelled by name on the explorer. The genesis block registers the 53 genesis validators with no votes: no genesis account votes, so every genesis validator starts with zero vote weight (see Consensus).
Genesis allocations are plain accounts with no lock. Any sender can place units of any asset, ROOT included, in non-revocable time-locked entries, one per tranche, which the recipient claims after each unlock time (see Accounts, transactions and native assets).
Block rewards
Section titled “Block rewards”Each produced block pays a newly issued reward to the validator that forged it. The amount depends on the validator’s seated rank among the 53 seated validators, from the rank snapshot taken at the start of the round (see Consensus). The forging validator’s relay computes the reward, and every node validates it.
| Seated rank | ROOT per block | Base units per block | Each donation share (5 %) | To the forging validator |
|---|---|---|---|---|
| 1 to 10 | 1.8 | 1,800,000,000,000,000,000 | 0.09 ROOT | 1.62 ROOT |
| 11 to 21 | 1.9 | 1,900,000,000,000,000,000 | 0.095 ROOT | 1.71 ROOT |
| 22 to 32 | 2.0 | 2,000,000,000,000,000,000 | 0.10 ROOT | 1.80 ROOT |
| 33 to 43 | 2.1 | 2,100,000,000,000,000,000 | 0.105 ROOT | 1.89 ROOT |
| 44 to 53 | 2.2 | 2,200,000,000,000,000,000 | 0.11 ROOT | 1.98 ROOT |
Lower-ranked validators earn slightly more per block. The tiers hold 10 + 11 + 11 + 11 + 10 = 53 seats, so a full 53-slot round pays 106 ROOT and the mean reward is exactly 2.0 ROOT per block:
A missed slot produces no block and therefore no reward, and a validator outside the 53 seats earns no block reward.
Emission
Section titled “Emission”The reward table is flat: it pays the same amount per rank every year, and it changes only through a protocol upgrade with an activation height (see Governance and protocol upgrades). No step-downs are scheduled, no decay formula runs and no maximum supply is coded.
At full production, when every 8-second slot produces a block, the network produces 10,800 blocks and issues 21,600 ROOT a day. Over 365 days that is 3,942,000 blocks and 7,884,000 ROOT. Missed slots only lower these figures.
Inflation
Section titled “Inflation”Gross issuance is constant at full production, while supply grows. The gross inflation rate in year n is therefore:
| Year | Supply at the start of the year (ROOT) | Gross issuance (ROOT) | Gross rate |
|---|---|---|---|
| 1 | 100,000,000 | 7,884,000 | 7.88 % |
| 2 | 107,884,000 | 7,884,000 | 7.31 % |
| 3 | 115,768,000 | 7,884,000 | 6.81 % |
| 4 | 123,652,000 | 7,884,000 | 6.38 % |
| 5 | 131,536,000 | 7,884,000 | 5.99 % |
| 10 | 170,956,000 | 7,884,000 | 4.61 % |
After 10 years the supply is about 178.84 million ROOT. Gross issuance stays below 8 % of supply in every year, and the rate falls every year. These figures follow from the rules at full production with the reward table unchanged. They count issuance before any burn; missed slots lower issuance, and burns lower supply.
Rewards per seat
Section titled “Rewards per seat”At full production each seat forges 3,942,000 / 53 ≈ 74,377 blocks a year. Before donations, that is about 133,879 ROOT a year at 1.8 ROOT per block and about 163,630 ROOT at 2.2 ROOT per block. After the two 5 % donation shares, it is about 120,491 and 147,267 ROOT. Fee income comes in addition. These are properties of the rules, not measured earnings. Consensus pays each reward to the forging validator; what a validator shares with its voters is declared on chain and measured outside consensus (see Integrations).
Donations
Section titled “Donations”Each block reward, never the fees, pays 5 % (500 basis points) to each of two donation recipient accounts. Each share is rounded down to a whole base unit, and the remainder of the reward goes to the forging validator. Because 5 % of every tier is an exact number of base units (0.09 to 0.11 ROOT), the rounding removes nothing.
At full production the two recipients together receive about 788,400 ROOT a year, 394,200 ROOT each. This amount is part of the 7,884,000 ROOT of annual issuance, not an addition to it.
The recipients are native multisig accounts held by the IceRoot team from genesis:
- recipients: the Development fund and the Ecosystem fund, at [TBD: addresses of the two donation recipients];
- key setup: 2-of-3 for each account, so any two of its three keys must sign.
The IceRoot team decides spending off-chain and makes no commitment to publish spending reports. The addresses are labelled publicly on the explorer, and every payment from them is visible on chain. The recipients may vote like any ordinary account, and each donation credit updates their vote weight.
Every node validates the donation list when it starts: each address must be valid, each share must be an integer number of basis points, the shares must total at most 10,000, and null or non-numeric values are refused. A change to the list replaces the whole list and takes effect only through a protocol upgrade at an activation height.
The fee formula is described in Accounts, transactions and native assets. Atomic swaps, hash time-locked transfers and time-locked transfers pay under the same formula: [TBD: fees of the atomic swap, the lock, claim and refund operations, and the time-locked transfer and its claim]. For each transaction, whatever its operation and including any surcharge, such as the 250 ROOT of a validator registration, the 125 ROOT of a name registration or claim, or the 25 ROOT of a reward-sharing declaration, every node computes the burned part of the fee:
The forging validator receives the remainder, about 10 % of the fee. Fees are never subject to donations. The burned amount is derived by every node from the fee; it is not a signed field. The basis-points parameter is validated when a node starts.
Burned ROOT
Section titled “Burned ROOT”Burned ROOT comes from three sources:
- the fee burn, 90 % of every transaction fee, surcharges included;
BURNoperations, in which holders destroy their own ROOT (see Accounts, transactions and native assets);- the withheld rewards of jailed validators (see Consensus).
The first two reduce the existing supply. A withheld reward is burned instead of being paid, so it never adds to supply.
Next to the counters every asset keeps, ROOT’s supply counters record block rewards, burned fees and donations, and the per-block supply check covers ROOT like every other asset (see Accounts, transactions and native assets).
Economic commitment in the block header
Section titled “Economic commitment in the block header”Each block header carries one 32-byte hash over the block’s burned-fee total, each donation payout (address and amount) and the forging validator’s payout. Every node recomputes this hash from the block, and a node that computes a different value rejects the block at once. A wrong reward, a wrong donation or a wrong burn therefore makes the block invalid.
Diagram source
flowchart LR
R["Block reward: 1.8 to 2.2 ROOT by seated rank"] --> D1["5 % to the Development fund"]
R --> D2["5 % to the Ecosystem fund"]
R --> V["Remainder to the forging validator"]
F["Transaction fees in the block,<br/>surcharges included"] --> B["90 % burned"]
F --> V
D1 --> H["Economic-results hash in the block header"]
D2 --> H
V --> H
B --> HROOT and migrated assets
Section titled “ROOT and migrated assets”Migrations deliver the migrated asset only, never ROOT. Holders of migrated assets obtain ROOT themselves to pay fees (see Migration).
Prices
Section titled “Prices”Market prices never enter consensus. Asset creators cannot set their own market price, and a failure of the market-data service that wallets and the explorer use never affects consensus (see Integrations).
Governance and protocol upgrades
Section titled “Governance and protocol upgrades”IceRoot’s rules change only through public software releases, and every change to what makes a block or transaction valid activates at a named block height; no rule is voted on chain.
Who decides what
Section titled “Who decides what”Holders and validators govern who operates the network, not what its rules are:
- Holders elect validators. Every account except a validator account can vote, with its ROOT balance as its vote weight and at most 5 % of it for any one validator; an account holding more than 5 % of ROOT’s supply carries no vote weight. Votes decide which validators hold the 53 seats (see Consensus).
- Validators run Heartwood Core, install releases and forge blocks under the rules those releases activate.
- No rule change is voted on chain. There are no transaction types that propose or vote on rules. Validator voting elects seats; it does not change rules.
Three public texts, published on iceroot.com and in the public documentation, state how the parties closest to the network use their influence over elections: a team voting policy says which team wallets vote and how; an exchange voting commitment, part of the onboarding guide for exchanges, in which an exchange commits not to vote with its customers’ ROOT and names any validator it runs; and a validator independence statement is confirmed by every applicant for a genesis seat. None of them is a consensus rule.
The IceRoot team is the only release authority. A release is code published on GitHub, and validators are instructed formally, through the project’s announcement channel, the announcements channel of the IceRoot Discord ([TBD: Discord URL]), to install it. X, the status page on docs.iceroot.com, the IceRoot blog on iceroot.com and the IceRoot Telegram channel mirror each announcement. The same authority issues the recovery release that restores finality after a permanent loss of 18 or more seats (see Consensus).
Release integrity
Section titled “Release integrity”No release is signed with a key. Releases are protected by these measures instead:
- maintainers use hardware security keys or authenticator apps on GitHub and on the announcement channel;
- release tags are protected, so only administrators can create them;
- changes to the main branch are reviewed before they are merged;
- the release notes on GitHub list the SHA-256 checksum of every download, the announcement repeats the checksums, and operators compare the two before installing;
- the release notes name every activation height the release contains;
- builds are reproducible: anyone who builds from the release tag gets a byte-identical binary, so an operator can check a published binary against the public source.
The model has two limits, stated plainly. Operators cannot check a release against a signing key, and the measures do not protect against a compromise of GitHub and the announcement channel at the same time. The consolidated trust assumptions are listed in Security model and assurance.
Milestones
Section titled “Milestones”Consensus parameters and rule activations live in milestone files, keyed by activation height. For the public testnet and mainnet, the milestone files are compiled into the release binary. If the node’s configuration directory also holds them, they must be byte-identical to the compiled files; otherwise the node refuses to start and names the file.
A strict schema applies. The node refuses to start if a milestone file contains:
- an unknown key at any level;
- a null value;
- two entries at the same height;
- a first entry at a height other than 1;
- a version floor that would refuse the node’s own version.
The block time (8 s) and the number of active validators (53) cannot change after height 1. Configuration values such as the fee-burn basis points, the donation list and the minimum amount of a ROOT burn are validated when the node starts. An invalid value stops the node at start-up instead of affecting the chain.
Fingerprints of applied entries
Section titled “Fingerprints of applied entries”The node records a digest of every milestone entry it has applied, and recomputes the digests at every start. If an applied consensus entry has changed or disappeared, or a new entry sits at or below the current tip, the node refuses to start. It reports the height to roll its local database back to, or to resync from. A release therefore cannot silently rewrite a rule that has already applied.
Only consensus-scoped keys are fingerprinted. The network-scoped keys p2p.minimumVersions and protocolVersion only decide which peers a node talks to. The version floor can therefore be raised in place, in an entry that has already applied, to cut off a vulnerable software version quickly.
Activation heights
Section titled “Activation heights”Every change to block or transaction validity names an activation height, and every activation height falls on a round start. Validity never changes because a node was upgraded; it changes at the named height. As a result:
- every node switches to the new rule at the same block;
- nodes that have not upgraded stop at that height and catch up after upgrading;
- a node syncing from genesis knows from which block each rule applies.
A round lasts 424 s, so aligning a height to a round start moves an activation by less than one round, about 7 minutes.
A patch that changes no rule needs no height: for example an API fix, a speed-up, a crash fix, or a change of forger or pool policy. Operators install such a patch when convenient.
When an upgrade changes the shape of the ledger state, the activating milestone names a one-shot deterministic migration. It runs exactly once, in the activation block, inside the same state transaction as that block. Reverting the block restores the prior state exactly, and the old shape disappears at one known height.
Lead time
Section titled “Lead time”The lead time between a release and its activation height is set per change; there is no fixed minimum. An urgent critical change can be due in about one day, which is about 10,800 blocks at full production. A scheduled upgrade can give one or two months.
| Change | Activation height | Lead time | What nodes do |
|---|---|---|---|
| Patch that changes no rule | None | None; operators install when convenient | Upgraded and non-upgraded nodes accept the same blocks |
| Change to block or transaction validity | Required, on a round start | Set per change, from about one day | All nodes switch at the same block; nodes that have not upgraded stop, then catch up after upgrading |
| Change to the shape of the ledger state | Required, on a round start | Set per change | A one-shot deterministic migration runs once in the activation block |
| Version floor raise | At every activation height; raised in place to cut off a vulnerable version | Set per change | Peers below the floor are refused |
| Recovery release after a permanent loss of 18 or more seats | A fixed round named in the release | Set per case | Nodes install a recovery record with a new validator set (see Consensus) |
Readiness
Section titled “Readiness”The relay’s status command, heartwood relay status, and the node API show how many active validators run a version that satisfies a new release. The count comes from the software version each validator signs into its online attestations (see Network architecture). Each validator’s own software reports that version, so the count is an operational signal, not proof.
The release process requires a readiness target before the activation height: [TBD: readiness target before activation]. If the target is missed, a corrected release with a higher activation height ships before the original height is reached. Nothing in consensus reads the readiness signal, and there is no on-chain signalling.
Diagram source
sequenceDiagram
participant T as IceRoot team
participant G as GitHub
participant A as Announcement channel
participant O as Validators and operators
T->>G: Release tag, notes with SHA-256 checksums and activation height
T->>A: Announcement repeating the checksums
O->>G: Download the binary or build it from the tag
O->>O: Compare both checksums, then install
O-->>T: Readiness count from signed online attestations
alt Readiness target met before the height
O->>O: New rule applies from the round-start height
else Target missed
T->>G: Corrected release with a higher activation height
endVersion floor
Section titled “Version floor”Every activation raises the version floor, p2p.minimumVersions, at its own height. From that height, nodes running older software are refused as peers, so they are cut off visibly rather than forking silently. Each node also announces the next scheduled activation in its peer handshake (see Network architecture).
Emergencies
Section titled “Emergencies”An emergency is handled in two parts. Immediate relief comes from forger and pool policy: validators stop including transactions that exploit the fault at once, which needs no activation height because it changes no rule. The rule fix then activates at its own height, as close as the case requires. A vulnerable software version can also be cut off by raising the version floor in place. If 18 or more seats are permanently lost, finality is restored only by a recovery release (see Consensus).
Chain splits and rollbacks
Section titled “Chain splits and rollbacks”IceRoot’s written policy for a chain split is that the finalized chain always wins and is never reverted; among branches above the finalized height, the canonical chain is the one that follows the latest official release.
Finalized history is never rolled back. Theft or a bad trade is never a reason for a rollback. A recovery release also anchors its new validator set at or above the finalized height, so it reverts no finalized block (see Consensus).
Full replay
Section titled “Full replay”Once a rule activates on mainnet, its code path and its milestone entry stay in every subsequent release. Superseded code paths are never selected for new heights, but they remain for history, so a new node can validate the whole chain from genesis.
What an upgrade can change
Section titled “What an upgrade can change”The reward table and the donation list change only through milestones with activation heights (see Economics); the block time and the number of active validators never change (see Milestones above). Every other consensus change follows the same path: a published release, a named activation height on a round start, and a raised version floor at that height.
Migration
Section titled “Migration”IceRoot moves an asset from another chain onto its ledger, and from its ledger to a destination chain, through one certified mechanism in which no single key can create migrated units and every limit on issuance is a consensus rule.
Overview
Section titled “Overview”A migration is a public list, the manifest, of who owned what on the source chain and which IceRoot account receives each holding. At least 36 of the 53 validators rebuild and sign the list independently. Its lines are then credited in order, under a lifetime cap that is fixed for each asset at registration and enforced by consensus.
Migration methods differ in what a holder must trust, and IceRoot states the difference rather than blurring it (see Design principles). Every registered asset and route carries a trust label, recorded at registration. Community or manual bridges are always presented separately from native, verified routes. A source holding is established from the source chain’s own data and signatures, which the IceRoot Connector checks with that chain’s cryptography, outside consensus; post-quantum protection applies from the moment the asset is credited on IceRoot.
Diagram source
sequenceDiagram
participant S as Source chain
participant L as Published list file
participant V as Validators, each with its own Connector and source-chain access
participant N as IceRoot Network
participant A as Any submitter
L->>V: The list is published as a file first
S->>V: Each validator reads the source chain independently
V->>V: Rebuild the list and check it against the file
V->>N: MANIFEST_COMMIT with fingerprint and totals, certified by at least 36 of 53
Note over N: The quorum may cancel the list only before its first credit
A->>N: MIGRATE_IN in order, at most 256 lines per chunk
N->>N: Check the lifetime cap and declared totals, then creditRegistering a source network and an asset
Section titled “Registering a source network and an asset”Each source network is registered once, by the validator quorum. Each external asset is registered once with ASSET_REGISTER_EXT, certified by the same quorum. Registration fixes the following for the life of the asset.
| Fixed at registration | Rule |
|---|---|
| Identity | External AssetID derived from the source network and the source asset, never from a ticker or name |
| Decimals | At most 18; a source token with more than 18 decimals is not registered |
| Mode | Snapshot or burn events, never changed |
| Trust label | One of [TBD: trust label names] |
| Source finality rule | When a source event counts as final and may be attested |
| Lifetime cap | The most base units migration can ever credit to the asset |
H is SHA-256 (see Post-quantum cryptography), and tag_ext is the domain tag reserved for external AssetIDs. The same source asset therefore maps to one AssetID across every list, and two unrelated source assets with the same ticker never share one.
Two modes, one mechanism
Section titled “Two modes, one mechanism”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 destroyed by holders 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, and checked by every certifier’s Connector | 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, including chains without firm finality, such as Bitcoin-like chains | Only registered source networks with deterministic or checkpoint finality, such as Ethereum’s finalized checkpoints |
The source networks supported on mainnet are listed in Parameters and operating cost. A snapshot of a chain that is still live is labelled a distribution, not a succession. Fee-on-transfer and rebasing tokens migrate only by snapshot, because for them the amount received can differ from the amount sent, while a snapshot reads real balances.
Certification
Section titled “Certification”In this paper, a migration attestation is one validator’s signature on a list, and a certification is the set of at least 36 such attestations that consensus accepts.
The list is published as a file before anything goes on chain. Each certifying validator rebuilds it with its own IceRoot Connector and its own access to the source chain (see Parameters and operating cost), and signs it with its migration attestation key, an ML-DSA-65 key separate from its consensus key (see Post-quantum cryptography). Nothing is attested before the source finality rule is met.
Only the list’s fingerprint and declared totals go on chain, with MANIFEST_COMMIT. A dedicated verifier accepts the certification only with valid ML-DSA-65 signatures from at least 36 of the 53 validators active at that height. Those signatures alone occupy 36 × 3,309 = 119,124 bytes, so certifications have a size limit of their own (see Parameters and operating cost).
Migration validity is a pure function of the transaction bytes and IceRoot state. No node calls another chain to validate a block, source-chain signatures are checked only by Connectors, and a classical signature is never a valid attestation.
Crediting: push, not claims
Section titled “Crediting: push, not claims”Once a list is certified, anyone (the issuer, a validator or any other party) submits its lines with MIGRATE_IN, in order, in chunks of at most 256 lines. A list is creditable immediately after certification, with no waiting period, and the credited totals must equal the declared totals exactly. The maximum number of lines per list is given in Parameters and operating cost.
Each line’s IceRoot account is fixed before certification, so a submitter cannot redirect anything. Holders make no claim and need no ROOT to receive. A migration delivers only the migrated asset, so moving it afterwards takes ROOT for fees like any other transaction (see Economics).
The validator quorum can cancel a list only before its first credit. This is also how a flawed snapshot is replaced.
Each source event credits at most once
Section titled “Each source event credits at most once”Each asset keeps a cursor: the last source block already credited. Every new event list must start right after the cursor, so no event at or below it can be credited again, including a re-encoded copy of an old event. Every migration has a MigrationID: a fixed-width, domain-tagged identifier derived from source data only.
Ledger state answers “can this still be issued?”. The node’s index, rebuilt by replaying the chain, answers “was it issued, to whom, and how much?”.
Errors are handled once
Section titled “Errors are handled once”Because nothing is attested before source finality, there is nothing to retry inside consensus: a retry is a resubmission, and a duplicate is rejected. After a list’s first credit, a mistake is corrected off-chain with units that already exist and a public post-mortem, and the wrong provenance stays in history. A source event that names a malformed IceRoot account is recorded as rejected and remedied on the source chain. There is no pending state, no correction record and no optimistic issuance.
Holdings that name no account
Section titled “Holdings that name no account”Nothing is ever swept to an authority, a treasury or other holders. Certified lines stay submittable indefinitely. A holder who named no account stays unissued, and the explorer shows such holdings as the unissued remainder of the migration.
Late binding lets certifiers bind a separate list of unbound holdings until a deadline that consensus enforces. It applies only to key-held holdings. Each binding carries its line and a proof signed with the holding’s own source-chain key, checked by Connectors. The total still unbound is declared and shown, and each binding waits out a delay during which it can be cancelled. The deadline falls below the cut-off height after which source-chain key proofs are no longer trusted.
Custodial and contract holdings
Section titled “Custodial and contract holdings”A custodian, such as an exchange’s omnibus wallet, receives one aggregate line labelled “custodial”, credited to its IceRoot account. It redistributes to its customers with ordinary transfers, and no customer data goes on chain. Custodial lines are the only aggregate lines; every other line carries a typed source key, and the line format does not assume that the source chain uses accounts.
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. Late binding does not apply to them.
Limits on issuance
Section titled “Limits on issuance”Every migrated asset has a mandatory lifetime cap, fixed at registration. Consensus rejects any credit above it, so even a party holding every validator key cannot create more than the cap. The damage model that follows is set out in Security model and assurance. No operation other than the crediting of a certified list creates units of a migrated asset (see Accounts, transactions and native assets).
An issuer can also require its asset’s migration authority (see Accounts, transactions and native assets) to co-sign each list. The issuer can then veto a list for its own asset but can never create units. If that authority’s key is lost or the role is renounced, inbound migration of the asset stops permanently.
Who may do what
Section titled “Who may do what”| Actor | Can | Cannot |
|---|---|---|
| Validator quorum (36 of 53) | Register source networks and assets; commit lists; cancel a list before its first credit; bind unbound key-held holdings until the deadline | Create units outside a certified list; exceed the cap; edit provenance |
| Migration authority | Set the out-destination allow-list; open or close acceptance of new inbound lists and migrate-out (the lifecycle flags); co-sign lists if the issuer opted in | Create units; touch balances or provenance; stop or delay the crediting of a list that is already certified |
| Anyone | Submit certified lines in order | Redirect a line |
No one can change who certified a committed list, bind an IceRoot account to a holding after certification except by late binding, or edit provenance.
Provenance
Section titled “Provenance”Migration provenance is typed protocol data with its own schema; the memo never carries it. Once final, the source network, source event, ownership reference, amount, MigrationID, manifest and historical destination of every credit are immutable history.
Leaving IceRoot
Section titled “Leaving IceRoot”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. An exit is possible only while the asset’s migrate-out flag is open, and only to a destination on the asset’s allow-list; the migration authority controls both. There is no refund, so an exit can never create units. A Seedbed asset moves to its project’s own chain the same way.
A compatible destination verifies IceRoot finality from signed block headers (see Consensus), 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.
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, without a signing key; users can change the feed URL or add others.
Custody gateways and returns
Section titled “Custody gateways and returns”A custody gateway is an ordinary IceRoot account, preferably a native multisig account. It is listed in the destination registry and shown on scan.iceroot.com and in the wallets with the label “custodial gateway” and its operator’s name, with its current holdings visible. A user sends units to it with a memo naming their address on the other chain, and the operator issues the same amount there; returns come back from the gateway’s account. The units never leave IceRoot’s supply, so a return keeps 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 external asset with its own AssetID and lifetime cap. It never credits the original AssetID, and any link between the two is kept off-chain.
Swaps with other chains
Section titled “Swaps with other chains”Hash time-locked transfers (see Accounts, transactions and native assets) complement migration and never replace it. With a counterparty on another chain, a holder can obtain ROOT for fees: the counterparty locks ROOT for the holder and, since anyone may submit a claim, can submit the claim too, and while a migrated asset’s source chain is live, a holder can exchange IceRoot units for units on that chain without a custodian. Such a swap moves no supply between chains: the IceRoot units change hands on IceRoot, and the counterparty’s units change hands on its own chain. A hash time-locked transfer never creates units of a migrated asset and never adds to its migrated_in counter. An external asset’s units reach IceRoot only through a certified list under its lifetime cap, and leave IceRoot’s supply only through MIGRATE_OUT or a burn.
Display and privacy
Section titled “Display and privacy”The link from a source address to an IceRoot account is public and permanent. The explorer shows it on the migration record and the asset page, with lookup by source reference or MigrationID, and an account page shows “received N via migration M” as a link. The explorer does no clustering, applies no entity labels, precomputes no holder paths and carries a “public and permanent” notice. Suppression for a legal request affects only the explorer’s display, never chain data. Consensus has no privacy modes; wallets warn users and use a fresh account for each migration.
Monitoring and penalties
Section titled “Monitoring and penalties”The migration watcher is an open-source tool that anyone, including validators, projects and exchanges, can run. It re-checks every credited line against the source chain and raises an alarm on a mismatch; the explorer shows its status. It runs outside consensus.
A false migration attestation carries the consensus penalties of jailing and withheld rewards (see Consensus). How such an attestation is proven is [TBD: evidence format and procedure for false migration attestations].
Parameters and operating cost
Section titled “Parameters and operating cost”Every validator runs an IceRoot Connector, on a machine or service separate from its relay and forger, and reaches each supported source network through its own node or through a reputable provider that it declares publicly. No provider serves more than 17 validators, so no single provider can ever account for the 36 attestations a certification needs. That limit is a declared policy, shown on the explorer and applied during onboarding, not a consensus rule: block validity never consults a source chain. A validator whose node or provider is wrong or offline does not attest; with fewer than 36 attestations a list waits while blocks continue, units already credited stay, and a node that resyncs from genesis never needs the source chain. The Connector as a component is described in Integrations.
| Parameter | Value |
|---|---|
| Supported source networks | Ethereum (ERC-20 tokens) |
| Certification quorum | 36 of the 53 active validators |
| Attestation signature | ML-DSA-65, 3,309 bytes; 119,124 bytes for 36 |
| Certification size limit | [TBD: certification size limit] |
Lines per MIGRATE_IN chunk | At most 256 |
| Lines per list | [TBD: entry maximum per list] |
| Earliest first credit | Immediately after certification |
| Late-binding deadline | [TBD: late-binding deadline] |
| Delay per late binding | [TBD: per-binding delay] |
| Cut-off for source-chain key proofs | [TBD: source-key cut-off height rule] |
Integrations
Section titled “Integrations”IceRoot exposes its ledger through a small set of interfaces that share one vocabulary and one rule for when value counts: a transaction counts once its block is final.
Interfaces
Section titled “Interfaces”| Surface | Served by | Purpose |
|---|---|---|
| Node REST API | Relay | State, single objects, block contents, fees, configuration and transaction broadcast |
| History search and live event stream | Indexer | Search across history; Server-Sent Events |
| Mesh gateway | Gateway next to the indexer | Mesh Data API; Construction API submit, hash and parse only |
| SDKs | One Rust core; TypeScript through WebAssembly; a Go binding | Encoding, signing domains and ML-DSA-65 signing |
| IceRoot wallets (desktop, mobile and browser) | The user’s device | Holding, sending, inspecting and burning assets; sending to names; voting, with automatic filling; hash time-locked swap flows; claiming time-locked entries |
Explorer, scan.iceroot.com | IceRoot | Public view of blocks, accounts, assets, migrations and validators, including validator concentration |
Documentation, docs.iceroot.com | IceRoot | Documentation, including the exchange and custodian onboarding guide, the validator hardening guide, the connector-adapter guide for proposing a new source network and the custody-gateway guide |
| Verified-asset list and destination registry | Feeds on iceroot.com, bundled in releases | Verified badges; compatible exit destinations and custody gateways |
| IceRoot Connector | Each validator, outside the node | Reads source chains and signs migration attestations |
| Launchpad distribution kit | Open-source tools, outside the node | Distributes an asset from an allocation list in multi-recipient transfers with a public proof of distribution; sets up vesting as time-locked transfers; lets a buyer name its IceRoot address by signing with its Ethereum or Solana wallet |
| Market-data service | A separate read-only service | Prices for display |
Node API
Section titled “Node API”The relay serves a REST API with a {meta, data} envelope, stable paths and a common query grammar. It covers ledger state, single objects, block contents, fees, configuration and transaction broadcast.
One vocabulary applies everywhere. Paths, fields, event names, transaction type names, command-line output and configuration files and keys, such as validators.json and activeValidators, say “validator”, “voter” and “memo”. The API uses no other terms for these concepts.
Amounts are unsigned 128-bit integers, written as decimal strings of base units. Balances can be filtered by asset, and a request without an assetId refers to ROOT. The asset endpoint, /assets/{id}, returns an asset’s on-chain fields, supply counters and authorities. Block totals are computed per asset from the block’s transactions. For every claimed hash time-locked transfer, the API returns the secret that the claim revealed. For every validator, the API returns its current reward-sharing terms and the height of their last change. The API resolves a name to its account and returns the name’s registration height, transfer count and last claim height.
“Received” has one meaning. recipientId and every “received” view mean exactly “this transaction credits this address”, following a published table per transaction type (transfer items, asset creation, both sides of an atomic swap, claims and refunds, inbound migrations and the others). Block rewards and donations are block-level credits, visible through block and validator routes.
Finality in the API
Section titled “Finality in the API”Every block and transaction carries finalized, and /node/status reports finalizedHeight. Every block and transaction view also carries a progress count, where h is the height of the block and h_tip the height of the chain tip:
Confirmations measure progress; finalized: true is the signal to act on. How long finality takes is set out in Consensus. Wallets and the explorer show “final” or “not final yet (about N minutes)”. After 4 rounds without a newly finalized block, the API reports “stalled” (see Consensus).
History and live events
Section titled “History and live events”The heartwood indexer process serves history search and one read-only Server-Sent Events stream [17]. The stream carries events when a block is applied or reverted, when a transaction is applied or reverted, and when a block is finalized. An event is sent only after its data is saved. The relay offers polling only.
Only a block that is not final can be reverted. An integrator that acts on block-finalized events, or on finalized: true, never has to undo a credit.
Mesh gateway
Section titled “Mesh gateway”For exchanges and custodians, a gateway next to the indexer serves the Mesh (formerly Rosetta) Data API [16] and the Construction API endpoints /construction/submit, /construction/hash and /construction/parse. The other Construction endpoints are not served. The gateway reports the latest final block as the network tip, so every block a Mesh client reads is final.
The API data model follows Mesh operations per currency, with the AssetID as the currency’s identity. Custodians build and sign transactions with the IceRoot SDKs, not through the gateway, and submit them through /construction/submit. Everything a signer depends on (the nonce, the fee, whether the account’s public key is already on chain, and the format version) comes from the node online and is never inferred offline.
One Rust core implements the encodings, the signing domains and ML-DSA-65 signing. Rust software uses it natively. JavaScript and TypeScript use it through WebAssembly with a thin TypeScript wrapper. A Go binding calls the same Rust core. Every supported language therefore runs one implementation of encoding and signing, and a rule cannot drift between languages.
Test vectors are published, so developers can build SDKs in other languages and check them against the same results.
IceRoot wallets
Section titled “IceRoot wallets”IceRoot provides three wallets of its own: a desktop wallet, a mobile wallet and a self-custody browser wallet. Each has its own recovery phrase and never shares a process or a key store with another chain’s wallet. Each signs with ML-DSA-65 and follow the signing domains and key derivation described in Post-quantum cryptography.
- Desktop wallet. A native application with local profiles. Each profile keeps its own wallets, contacts, network, currency and privacy preferences, separate from every other profile. It supports watch-only addresses and transfers to one or many recipients through a details, review and result sequence. Its stored application data never contains a recovery phrase or a private key.
- Mobile wallet. An application for Android and iOS for balances, assets, transfers and validator voting, with a guided review step before each signature. Its keys are generated and kept on the device.
- Browser wallet. Keys are generated and transactions are signed inside the browser. Nothing leaves the device except the signed transactions the user chooses to broadcast. It injects no provider into web pages.
Their asset view keeps what the ledger says apart from what an issuer says. Ledger facts (balance, AssetID, name, symbol, decimals, origin, supply counters, authorities, lifecycle and migration status) come from the node API. Every native asset is shown as fixed supply. Issuer claims (logo, website, description) are fetched from the metadata URI, shown only if the document’s hash matches the on-chain content hash, and labelled as provided by the issuer. The full view sits behind a “show more” or “asset details” button.
Any address can receive any asset, so the wallets filter. Assets the user has not added or recognized sit in a collapsed “unknown assets” list with a warning. A “hide unknown assets” switch hides them, and a burn option destroys them for the ordinary ROOT fee.
The wallets can send to a name. A name is a label, not proof of identity, so the wallets always show the address next to a name, together with its age and how often and when it last changed hands, show verified labels from the label list, warn before sending to a name that carries no verified label, and flag names that look like verified ones. They keep the address with each saved name and warn when a name’s address has changed since it was last used. A display blocklist hides offensive names, and a report button flags abuse.
A vote that names validators names at least 20 of them (see Consensus), so the wallets can fill a vote automatically in one of four modes:
- Diverse, the default, spreads the vote across validators with different declared operators and hosting providers, among those with a healthy sharing score and uptime;
- Best sharing picks the highest sharing scores, capped per operator;
- Random picks uniformly among eligible validators;
- Manual leaves every choice to the user.
Eligibility uses the indexer’s sharing scores, self-funded vote shares and productivity figures (see Reward sharing). Randomness and diversity keep any default list from deciding the election.
Explorer
Section titled “Explorer”scan.iceroot.com is the public explorer. It is a web interface backed by its own API service, and every view is built from one consistent snapshot of the ledger. When that service is unavailable, the explorer reports the error and offers a retry; it never shows substitute data. Balances are shown as exact integers of base units, formatted with the asset’s decimals. Beyond blocks, transactions, accounts, assets and validators, with search and filters, it shows:
- verification badges from the verified-asset list;
- names with the address always next to them, each name’s history, age and transfers, verified labels from the label list and flags on look-alike names; a display blocklist hides offensive names, and a report button flags abuse;
- the labelled donation addresses, and the team’s wallets labelled by name;
- custody gateways with their current holdings;
- migration records with the “public and permanent” notice, and each migration’s unissued remainder (see Migration);
- the status of the migration watcher;
- each validator’s declared identity, its operator, hosting provider and country, which the validator states in a standard memo that the indexer reads;
- a concentration dashboard with seats and vote weight per declared operator and per hosting provider, and an alert when one operator or hosting provider reaches 6 seats and again at 18 seats;
- each validator’s declared source-chain access, its own node or a named provider, with the number of validators per provider and a flag on any provider that serves more than 17 (see Migration);
- each validator’s reward-sharing terms and score, and the share of its vote weight that comes from addresses funded directly by its validator account (see Reward sharing).
Reward sharing
Section titled “Reward sharing”Consensus pays the forging validator its block reward, after donations, and its part of the fees (see Economics). What a validator shares with its voters is declared on chain and measured outside consensus, and nothing enforces it: a validator can stop paying, but it cannot hide that it has stopped.
- Declaration. A validator declares its terms with
SHARE_DECLARE, a transaction from its validator account with three fields: its share in basis points (0 to 10,000), a payout interval of one day or seven days, and its payout address. Every declaration, the first included, pays a 25 ROOT surcharge. Consensus checks only that the sender is a registered validator and that the fields are well formed, then stores the latest terms and the height of the change in the validator’s record; it moves no funds and pays nobody. Every node’s API returns the current terms. The indexer applies a change 24 hours after its block, or at the start of the next interval if that comes after those 24 hours. - Measurement. For each interval, the indexer multiplies the validator’s forger payouts after donations, taken from the economic results of its blocks, by the declared share; the result is the pool. Each voter’s expected share is the pool times that voter’s time-weighted share of the validator’s vote weight over the interval. Each voter’s credit is what it received from the declared payout address within [TBD: payout grace window], capped at its expected share. Payments to accounts that do not vote for the validator count for nothing, and no payment can make up for another voter’s shortfall, so paying accounts that the validator itself controls never offsets what its other voters are owed.
- Display. The explorer and wallets show each validator’s score and each voter’s owed-versus-received line, flag missed payouts, and show the share of each validator’s vote weight that comes from addresses funded directly by its validator account (see Consensus).
- Payouts. An open-source payout tool computes each voter’s exact share and pays in transfers of up to 256 recipients.
The computation is open source and deterministic, so anyone can reproduce every score from the chain.
Verified-asset lists
Section titled “Verified-asset lists”A ticker proves nothing: only the AssetID identifies an asset, and consensus has no rule about look-alike symbols. The IceRoot team publishes a curated list of AssetIDs it has checked, and wallets and the explorer show a verified badge for them. Anyone may publish a competing list, and users can add it.
The list ships inside wallet releases and explorer deployments and is updated from iceroot.com over HTTPS, without a signing key. Users can change the feed URL or add others. The destination registry for exits is distributed the same way (see Migration).
Exchanges and custodians
Section titled “Exchanges and custodians”docs.iceroot.com carries one public onboarding guide for every exchange and custodian. It covers node setup, deposit tags, crediting on finality and the SDKs. Arrangements with exchanges and custodians are made in writing.
Diagram source
flowchart LR
C[Customer wallet] -->|transfer with deposit tag in the memo| R[Relay node API]
R --> X[Indexer]
X -->|SSE events| E[Exchange backend]
R -->|polling| E
E -->|AssetID on allow-list and finalized is true| B[Credit the customer]
E -->|withdrawal built and signed with an SDK| RDeposits follow one of two patterns:
- Tagged deposits (recommended). One deposit address, with a per-customer tag in the memo. Nothing needs sweeping.
- Address pool. Per-customer addresses drawn from a pool generated offline. Keys use hardened-only derivation, so a server cannot derive new deposit addresses from public data alone.
A transaction has one memo and no per-recipient tags. Tagged withdrawals therefore go out one transaction each, while untagged recipients can be batched in one transfer of up to 256 recipients.
Any asset can be sent to any address, so an exchange credits only AssetIDs on its own allow-list. Transfer, metadata and API semantics are identical for every AssetID.
Trading and swaps
Section titled “Trading and swaps”Off-chain trading services, such as decentralized exchanges, can build on the atomic swap: they collect makers’ signed offers, match them and hand them to takers, all off-chain, and consensus settles each trade in one all-or-nothing transaction (see Accounts, transactions and native assets). An offer lapses when its maker’s nonce changes, so a service drops a maker’s open offers once that maker sends any transaction.
For swaps with other chains, the IceRoot wallets and the documentation at docs.iceroot.com enforce the ordering of lock times that consensus cannot see. The first lock, made by the party that chose the secret, must expire after the second, with enough margin for the other party to read the revealed secret on one chain and to have its own claim final on the other. Wallets treat a claim as complete only once its block is final.
IceRoot Connector
Section titled “IceRoot Connector”The IceRoot Connector is the framework through which IceRoot integrates external chains. It runs outside the node, on a machine or service separate from the validator’s relay and forger. Each validator runs its own Connector and reaches each supported source network (listed in Migration) through its own node or a reputable provider that it declares publicly. Each source network is supported through its own Connector adapter; the connector-adapter guide at docs.iceroot.com describes how to propose one.
The Connector reads the source chain, rebuilds migration lists, checks source-chain key proofs and holds the validator’s migration attestation key, an ML-DSA-65 key. It verifies the classical signatures of source chains, and the launchpad distribution kit, which shares its key-proof code, verifies those of buyers’ wallets on other chains. These are the only places where classical signatures are checked, and no classical signature authenticates anything in consensus. A compromised Connector cannot create units: every credit needs a certification by at least 36 of the 53 validators and stays under the asset’s lifetime cap (see Migration).
Market data
Section titled “Market data”Prices shown in wallets and on the explorer come from a separate, read-only market-data service outside consensus, so its failure leaves consensus unaffected (see Economics).
Network separation
Section titled “Network separation”Each signature’s signing domain binds it to the IceRoot Network and to one purpose, so a signature made for IceRoot cannot be replayed on another chain (see Post-quantum cryptography).
Security model and assurance
Section titled “Security model and assurance”IceRoot’s security rests on a short list of stated assumptions, and for each one the protocol defines what happens when it fails and which rule or practice limits the damage. The mechanisms are described in their own sections; this section collects the assumptions, their bounds and the assurance work behind the release.
Trust assumptions
Section titled “Trust assumptions”| Assumption | If it fails | Bound or mitigation |
|---|---|---|
| At most 18 of the 53 validators are Byzantine (16 next to a set change) | Two conflicting blocks could both be finalized | Conflicting finalization needs at least 19 Byzantine validators, or 17 next to a set change; on a stable set the 19 sign contradicting headers, which is provable from the headers; jailing and withheld rewards |
| At most 17 of the 53 validators are offline | No block becomes final; blocks are still produced while at least 27 validators are online | Alert after 4 rounds; user transactions pause after 24 rounds; a recovery release if 18 or more seats are permanently lost |
| Byzantine validators do not coordinate forking | Finality can be delayed | Stall policy; finality progress is proven only against crashed validators |
| Validators are run by independent operators | One operator or hosting provider holding many seats could approach the safety or liveness bound on its own | Declared operator, hosting provider and country; the explorer’s concentration dashboard, with alerts at 6 and 18 seats; the validator independence statement; each vote gives one validator at most 5 %, and an account holding more than 5 % of ROOT’s supply carries no vote weight; declarations are self-reported |
| Fewer than 36 of the 53 migration attestation keys are compromised or dishonest | Units of a migrated asset could be credited without a real source event | The lifetime cap bounds each asset; issuer veto where chosen; public list file; cancel before the first credit; migration watcher |
| A validator’s source-chain node or provider reports the source chain correctly | That validator could attest to a wrong list, or to none | Block validity never consults a source chain; a certification needs 36 attestations, and no provider serves more than 17 validators, a declared policy shown on the explorer; a validator with wrong or missing source data does not attest, so a list waits while blocks continue |
| Certification software is correct | An error, such as a holder counted twice, is usually credited before anyone can cancel it | Lifetime cap; migration watcher; off-chain correction with existing units and a public post-mortem |
| A custody gateway operator is honest | The operator could lose or steal the units it holds | Labelled as custodial; holdings visible; no path to create units |
| A maker shares a signed swap offer only on terms it accepts | Anyone who holds the offer can execute it on its signed terms until it lapses | Bound to the maker’s nonce, so it executes at most once and cannot be replayed; any transaction by the maker cancels it; it expires at its expiry height; its signing domain makes it valid for nothing else and on no other chain |
| The other chain of a hash time-locked swap is secure | The units on that chain can be lost or stolen | IceRoot’s side uses only ML-DSA-65 signatures and a SHA-256 hash lock and is unaffected; the other side is only as secure as its own chain and cryptography |
| Both parties complete a hash time-locked swap | One party holds a free option: it can let the swap lapse, for example after a price move, while the other party’s units stay locked until expiry | The refund returns locked units after expiry; the lock duration bounds how long they are held |
| A claim made before expiry stays in the chain | A reverted claim would let the sender refund units the recipient had claimed | A claim counts once its block is final, and a final block is never reverted; the minimum lock duration of 900 blocks spans several finality periods; wallets enforce the cross-chain lock-time ordering; expiry is judged against finality, so a finality stall never closes a claim window early, and claims and refunds stay admissible while user transactions are paused |
| The release authority publishes correct releases | Changed rules, or a wrong recovery record, reach operators who install them | Public code; reproducible builds; activation heights named in release notes; each operator decides whether to install |
| GitHub and the announcement channel are not compromised together | Changed rules could reach operators who upgrade | Checksums in two places; protected release tags; hardened maintainer accounts; reproducible builds |
The list feed on iceroot.com is not compromised | A fake verified badge or destination-registry entry is shown until noticed | Lists bundled in releases; users can change or add feeds; wallets show AssetIDs |
| A destination chain honours IceRoot exits | Units destroyed by MIGRATE_OUT are never credited there | Allow-list set by the asset’s migration authority; destination standard; no refund, stated plainly |
| Metadata hosting is available | Issuer claims (logo, website, description) are unavailable | The content hash makes the document tamper-evident; on-chain fields never depend on hosting |
| The market-data service is correct | Wrong or missing prices in wallets | Prices are outside consensus |
| A name belongs to the account a user expects | A user could vote for, or send assets to, an impersonator, or a new holder after a name has moved | Names of 1 to 20 lowercase letters only; names containing iceroot or heartwood, reserved names and banned words refused by consensus; a name moves only to a fresh account, and a validator’s name never moves; the address always shown next to a name, with its age and transfers; verified labels, look-alike flags, a warning before sending to an unverified name and a warning when a saved name’s address has changed |
| A validator pays what it declares | Its voters receive less than the declared share, or nothing | Not enforced; measured and displayed: the terms are recorded on chain by SHARE_DECLARE and returned by every node’s API, the explorer and wallets show each validator’s score and each voter’s owed-versus-received line, and anyone can reproduce the computation (see Integrations) |
Six limits follow from this table and are stated plainly:
- The lifetime cap is the only bound on a compromised migration quorum. There is no rate limit and no delay, so such a quorum can credit up to an asset’s full cap in one block.
- Finality is proven to keep progressing with up to 17 crashed validators, not against coordinated forking by Byzantine validators.
- Releases carry no cryptographic signature (see Governance and protocol upgrades).
- The link between a source address and an IceRoot account created by a migration is public and permanent.
- Custody gateways are trusted operators.
- A hash time-locked swap is only as secure as the other chain, and it gives one party a free option.
Faults tolerated
Section titled “Faults tolerated”The safety and liveness bounds, the stall policy, and evidence and penalties are defined in Consensus. In summary: missed slots are recorded but never penalized; finality keeps progressing with up to 17 validators offline; with 18 or more offline, blocks are still produced while a forger’s relay sees at least 27 validators online, but no block becomes final until enough validators return or a recovery release installs a new set. Equivocation is punished by jailing and withheld rewards; nothing is slashed and voters’ funds are never touched.
Against network faults, the transport accepts only TLS 1.3, only the hybrid X25519 with ML-KEM-768 key exchange and only ML-DSA-65 node authentication (see Network architecture). The negotiated key-exchange group is re-checked after every handshake, and a classical-only peer is refused. Against flooding, validators can place their relay behind sentry relays, peers are scored, outbound peers are diversified and public APIs run apart from validators’ relays (see Network architecture). A synced node never reverts a finalized block and disconnects a peer that serves a chain conflicting with finality, so no peer set can rewrite that node’s finalized history.
Each key has one job, and its compromise is bounded by that job. Where each key is held is set out in Post-quantum cryptography.
| Key | If compromised |
|---|---|
| Account key | That account’s funds; with a second key or a multisig account, one stolen key cannot spend |
| Consensus key | Conflicting blocks can be signed; they are provable and punished by jailing and withheld rewards |
| Node key | That relay can be impersonated on the P2P network |
| Migration attestation key | One of the 36 attestations a certification needs |
| Asset authority | Metadata URI and hash can be replaced; never balances or provenance |
| Migration authority | Exit destinations and lifecycle flags can be changed, and lists vetoed where the issuer opted in; never balances or provenance, and no units can be created |
Heartwood keeps keys away from network-facing code: the relay never reads a validator’s keys, key files readable by group or others stop a process at start, the forger channel admits only allow-listed addresses, and the combined relay-and-forger mode is never the default. Accidental equivocation is prevented by the forger’s persisted signing record and its restart rule, and a node never selects either of two blocks signed by one producer for one slot as its tip (see Network architecture and Consensus).
Checks the node runs on itself
Section titled “Checks the node runs on itself”Every node checks supply conservation for every asset after every block and stops on a violation, and it rejects a block whose economic-results hash differs from its own computation (see Accounts, transactions and native assets, and Economics). Decoding is strict and canonical. Configuration values are validated at start, milestone files must pass a strict schema, and a node refuses to start if an applied consensus entry has changed. Validity changes only at named activation heights on round starts, each activation raises the minimum peer version, and every node can replay the chain from genesis (see Governance and protocol upgrades).
Incident handling
Section titled “Incident handling”Each incident response is defined where its mechanism lives. Public disclosure of an incident is decided case by case. An exploit through transactions that the rules accept is stopped at once by forger and pool policy and fixed by a rule change at an activation height; a vulnerable node version is cut off by raising the version floor in place (see Governance and protocol upgrades). A finality stall triggers the alert and the user-transaction pause, and a permanent loss of seats is resolved by a recovery release (see Consensus). A faulty migration list is cancelled before its first credit, or corrected afterwards with existing units and a public post-mortem (see Migration). In every case, finalized history is never rolled back.
How the implementation was checked
Section titled “How the implementation was checked”Before launch:
- During the public testnet, the ML-DSA-65 verifier path and the finality core were externally audited: [TBD: auditor names, scopes and report links].
- During the public testnet, an independent reviewer of BFT protocols checked the finality-gated set change and the application of Theorem 4.4(b) of the Lisk-BFT analysis [15] (see Consensus): [TBD: BFT reviewer name, scope and report link].
- The public testnet, which uses the same parameter values as mainnet, ran with finality enforced for at least 8 weeks before mainnet, and migration in and out, atomic swaps, hash time-locked transfers and time-locked transfers ran on it before mainnet.
- Builds are reproducible: anyone who builds a release tag gets a byte-identical binary. SDK test vectors are published.
An adversarial test campaign covered:
| Area | Scenarios |
|---|---|
| Transactions and load | Every transaction type; spam and floods; invalid-signature floods; oversize and malformed witnesses; key rotation under load; second-key and multisig paths |
| Malicious validators | Double forging; wrong reward claims; bad timestamps; a validator running a modified binary |
| Malformed data | Malformed blocks, transactions and P2P frames |
| Network | Many fake peers; eclipse attempts; several malicious relays run by one party; attacks from outside on the forger and the relay; floods aimed at the next forgers of a round, with and without sentry relays |
| Operator faults | Clock skew on one node; a full disk; a corrupted database file |
| Upgrades | Milestone and configuration changes; a rehearsed switch of transaction format; old-version transactions at and after an activation height |
| Swaps and time locks | Replayed and cancelled swap offers; claims and refunds around the expiry height; claim races near finality; claims of time-locked entries around their unlock times and attempts to revoke them; a check that no step on IceRoot relies on classical cryptography |
Public accountability
Section titled “Public accountability”Anyone can check the network’s concentration and conduct. Validators declare their operator, hosting provider and country, and the explorer reports seats and vote weight per declared operator and per hosting provider, with an alert when one reaches 6 seats and again at 18 seats. It also shows each validator’s reward-sharing terms and score and its declared source-chain access, labels the donation addresses and the team’s wallets by name, and shows the migration watcher’s status. A team voting policy, an exchange voting commitment and a validator independence statement are published on iceroot.com and in the public documentation (see Governance and protocol upgrades). Migration list files are public, and the node API exposes every asset’s supply counters.
What users must protect
Section titled “What users must protect”- Holders protect the recovery phrase. It controls every asset of every account derived from it. There is no recovery key, and a theft is never reversed by a rollback. A second key or a multisig account means one stolen key cannot spend. Holders identify assets by AssetID or verified badge, never by ticker, check the address shown next to a name before sending to it, keep some ROOT for fees, and check the destination account before an exit, because
MIGRATE_OUThas no refund. They sign a swap offer only on terms they accept, since anyone who holds it can execute it until it lapses, and in a swap with another chain they follow the wallet’s lock-time ordering. A custody gateway holds what it receives, so using one means trusting its operator. A fresh account for each migration limits what the public migration link reveals. - Validators keep the account key off every server and run each consensus key on exactly one forger; one key on two forgers can sign two blocks for one slot, which is evidence of misbehaviour. Key files are never readable by group or others. Before installing a release, operators compare the checksum in the release notes with the one in the announcement, or rebuild from the tag.
- Issuers protect the asset and migration authority keys, preferably as multisig accounts. Renouncing a role is permanent, and where the issuer opted into the veto, losing the migration authority key stops inbound migration of the asset permanently. A time-locked transfer is permanent too: no one, the sender included, can revoke an entry, so issuers check the recipient and every unlock time before signing one.
- Exchanges and custodians credit only on
finalized: true, credit only AssetIDs on their own allow-list, generate any address pool offline and sign with the published SDKs (see Integrations).
Conclusion
Section titled “Conclusion”IceRoot is built around one job: agree on who owns what, and never get it wrong. Each part of the protocol described in this paper serves that job, and each leaves out what the job does not need.
Ownership is authenticated with ML-DSA-65 from block 1, with no classical fallback anywhere in consensus. Blocks are produced by 53 elected validators in 8-second slots and become final under a header-carried BFT rule, so a finalized block is never reverted and exchanges and destination chains have one signal to act on. Assets are standardized ledger objects rather than programs: their behaviour is fixed by the protocol, their authorities can never debit or move holders’ units or change provenance, and every node checks every asset’s supply after every block. Every native asset’s supply is fixed when the asset is created, two assets change hands in one all-or-nothing swap, hash time-locked transfers support swaps with other chains, and time-locked transfers carry vesting schedules that no one can revoke, while order books and matching stay off-chain.
Migration applies the same discipline to assets that arrive from other chains. A public list, rebuilt and signed by at least 36 of the 53 validators, fixes each recipient before anything is credited, and a lifetime cap set at registration bounds what migration can ever create for an asset. An exit destroys units on IceRoot and leaves a typed record that a destination checks against IceRoot’s finality.
The paper also states the limits of the design. Safety holds while at most 18 validators are Byzantine, and 16 next to a set change. Finality progress is proven for crashed validators, not against coordinated forking. The lifetime cap is the only bound on a compromised migration quorum. Releases carry no cryptographic signature, and custody gateways are trusted operators. A hash time-locked swap is only as secure as the other chain, and it gives one party a free option. Security model and assurance lists each of these with its mitigation.
Rules change only through public releases with named activation heights, and every activated rule stays in every subsequent release, so any node can validate the chain from genesis. The result is a ledger whose behaviour an engineer, an exchange or a validator can predict from its published rules.
Boring by design. Safe by design.
Acknowledgements and references
Section titled “Acknowledgements and references”Acknowledgements
Section titled “Acknowledgements”IceRoot’s protocol design inherits from ARK Core and Solar Core. Heartwood Core is a new implementation in Rust. ROOT is a new token with no link to any earlier token.
References
Section titled “References”- NIST, FIPS 204, “Module-Lattice-Based Digital Signature Standard” (ML-DSA), August 2024. https://doi.org/10.6028/NIST.FIPS.204
- NIST, FIPS 203, “Module-Lattice-Based Key-Encapsulation Mechanism Standard” (ML-KEM), August 2024. https://doi.org/10.6028/NIST.FIPS.203
- NIST, FIPS 180-4, “Secure Hash Standard (SHS)” (SHA-256), August 2015. https://doi.org/10.6028/NIST.FIPS.180-4
- NIST, FIPS 202, “SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions”, August 2015. https://doi.org/10.6028/NIST.FIPS.202
- IETF, RFC 8446, “The Transport Layer Security (TLS) Protocol Version 1.3”, August 2018. https://www.rfc-editor.org/rfc/rfc8446
- IETF, RFC 7748, “Elliptic Curves for Security” (X25519), January 2016. https://www.rfc-editor.org/rfc/rfc7748
- IETF, RFC 10024, “Post-Quantum Traditional (PQ/T) Hybrid Key Agreement Mechanisms for TLS 1.3” (X25519MLKEM768), August 2026. https://www.rfc-editor.org/rfc/rfc10024
- IETF, RFC 6455, “The WebSocket Protocol”, December 2011. https://www.rfc-editor.org/rfc/rfc6455
- BIP 350, “Bech32m format for v1+ witness addresses”. https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki
- BIP 39, “Mnemonic code for generating deterministic keys”. https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki
- BIP 32, “Hierarchical Deterministic Wallets”. https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
- SatoshiLabs, SLIP-0010, “Universal private key derivation from master private key”. https://github.com/satoshilabs/slips/blob/master/slip-0010.md
- IETF, RFC 3629, “UTF-8, a transformation format of ISO 10646”, November 2003. https://www.rfc-editor.org/rfc/rfc3629
- Lisk Improvement Proposals, LIP-0014, “Introduce BFT consensus protocol”, 2019 (status: Replaced by LIP-0058; IceRoot follows LIP-0014 as adapted in Consensus). https://github.com/LiskArchive/lips/blob/main/proposals/lip-0014.md
- J. Hackfeld, “A Lightweight BFT Consensus Protocol for Blockchains”, arXiv:1903.11434, 2019. https://arxiv.org/abs/1903.11434
- Mesh (formerly Rosetta) API specification. https://github.com/coinbase/mesh-specifications
- WHATWG, HTML Living Standard, “Server-sent events”. https://html.spec.whatwg.org/multipage/server-sent-events.html
- P. W. Shor, “Polynomial-Time Algorithms for Prime Factorization and Discrete Logarithms on a Quantum Computer”, SIAM Journal on Computing 26(5), 1997. https://arxiv.org/abs/quant-ph/9508027
- L. K. Grover, “A fast quantum mechanical algorithm for database search”, Proceedings of the 28th Annual ACM Symposium on Theory of Computing, 1996. https://arxiv.org/abs/quant-ph/9605043
- UK National Cyber Security Centre, “Next steps in preparing for post-quantum cryptography”, August 2024, updated April 2026. https://www.ncsc.gov.uk/paper/next-steps-in-preparing-for-post-quantum-cryptography
- BIP 199, “Hashed Time-Locked Contract transactions”. https://github.com/bitcoin/bips/blob/master/bip-0199.mediawiki
Legal notice
Section titled “Legal notice”This document describes the protocol of the IceRoot Network and the Heartwood Core software that implements it. It is published for technical information only.
It is not an offer or solicitation to buy or sell securities, tokens or any other asset, and it is not investment, financial, legal or tax advice. It makes no promise of an exchange listing, liquidity or a price for ROOT or any other asset.
The legal entity behind IceRoot is Mono Labs R&D LLC.