Custody gateways

This guide follows the draft protocol, which describes the intended mainnet. The format of the destination registry, which lists gateways, is not yet fixed; check listings and interfaces against an actual release before relying on them.

A custody gateway lets holders use an IceRoot asset on another chain through an operator that holds the IceRoot units. It needs no change to consensus and no migration: a gateway is an ordinary IceRoot account whose operator issues a matching amount on the other chain. Users trust the operator.

How a gateway works

1. Deposit. A holder sends units to the gateway’s IceRoot account with an ordinary transfer, and names their address on the other chain in the memo.
2. Issue. Once the transfer is final, the operator issues the same amount on the other chain.
3. Return. To come back, the holder follows the operator’s return procedure on the other chain, and the operator sends the units from the gateway’s IceRoot account to the holder’s IceRoot account.

What follows from this design:

• The units never leave IceRoot’s supply. They sit in the gateway’s account and are counted as held on IceRoot, not as migrated out.
• There is no path to create units. A return is an ordinary transfer from the gateway’s account, so it can never exceed what the gateway holds.
• Holdings are visible. The explorer shows each listed gateway with its current holdings, and anyone can compare them with the amount the operator has issued on the other chain.
• The operator is trusted. The operator could lose or steal the units it holds, or fail to issue or redeem. Consensus does not know that an account is a gateway, and an operator’s commitments are not consensus rules.

Because a deposit is an ordinary transfer, a gateway needs no entry on an asset’s allow-list of exit destinations and no open migrate-out flag. No lifecycle flag or label freezes transfers to or from it.

Returns and AssetIDs

Route back to IceRoot	AssetID on IceRoot	What bounds it
Through the gateway	The original AssetID, because the units never left	What the gateway holds
Any other route, such as migrating the other-chain copy in	A new external AssetID, with its own lifetime cap	That asset’s own lifetime cap

A copy that returns from another chain by any route other than the gateway registers as a new external asset. It never credits the original AssetID, the two assets are never merged, and any link between them is kept off-chain. The project announces on its own channels which AssetID is its canonical asset.

A gateway also differs from an exit. MIGRATE_OUT destroys units on IceRoot, counts them as migrated out, and has no refund; a compatible destination verifies IceRoot finality itself. A gateway destroys nothing, and holders rely on its operator instead.

Labels

A gateway is listed in the destination registry, an off-chain document that wallet releases bundle and that wallets update from iceroot.com over HTTPS, without a signing key. Users can change the feed URL or add others.

On scan.iceroot.com and in the IceRoot wallets, a listed gateway’s account carries the label “custodial gateway” with its operator’s name, and its current holdings are shown.

• A label names the operator. It tells users who holds the units. It is not a consensus fact, and it does not guarantee the operator’s conduct or solvency.
• An unlisted account has no gateway label. Sending units to an account that claims to be a gateway but is not listed is an ordinary transfer to that account.
• “Custodial” is a different label. In a migration list, “custodial” marks the aggregate line credited to a custodian, such as an exchange’s omnibus wallet. It is unrelated to gateway listings.

What an operator publishes

The registry’s listing format is not yet fixed. A gateway operator is expected to publish, on its own channels and for its listing:

• Identity. The operator’s name, as the label shows it, and contacts for support and for security reports.
• The gateway account. Its IceRoot address and its key setup. A native multisig account is recommended, for example 2-of-3 or 3-of-5.
• Assets. Each supported asset by AssetID, never by ticker alone, with the matching representation on the other chain: the network, the token contract or identifier, and how decimals map.
• The deposit memo. Exactly how a memo names the other-chain address. A memo holds at most 255 bytes, and a transaction has one memo, so each deposit names one destination.
• Crediting rules. When the operator issues, for example only after the IceRoot transfer is final, and how many confirmations or which finality it waits for on the other chain before a return.
• The return procedure. How a holder redeems on the other chain, which IceRoot account returns come from, and how the holder names the receiving IceRoot account.
• Terms. Fees, minimum and maximum amounts, expected processing times, and what happens to deposits that do not follow the memo format.
• Supply on the other chain. Where anyone can read the amount issued there, to compare it with the gateway’s holdings on IceRoot.
• Wind-down. How holders redeem if the operator stops operating the gateway.

Operate a gateway

• Use a multisig account. Hold the gateway’s units in a native multisig account, so one stolen key cannot move them.
• Credit on finality. Issue on the other chain only once the deposit’s transaction shows finalized: true. Confirmations count progress; they do not replace finality.
• Allow-list by AssetID. Any asset can be sent to any address, so unexpected assets will arrive. Handle only the AssetIDs you list, and state what happens to others.
• Keep holdings in the listed account. Holdings are visible only while they stay in the account the registry lists. Moving them elsewhere makes the public view misleading.
• Sign with the published SDKs. Build and sign transactions with the IceRoot SDKs, reading the nonce, fee, and public-key state from a node before signing. See Exchanges and custodians for the integration surfaces.

For holders

• Check the label and the address. Confirm the “custodial gateway” label and the operator’s name, and compare the address with the operator’s own announcement.
• Copy the memo exactly. A transfer is final once its block is final, and finalized history is never rolled back. A deposit with a wrong memo can only be fixed by the operator.
• Know what is public. The memo is public and permanent, so the link between your IceRoot account and your address on the other chain is public too.
• Know whom you trust. A gateway holds what it receives. Using one means trusting its operator.

Exchanges and custodians → · Migration guide →