Skip to content

Add ICON namespace (icon) with CAIP-2 profile #208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
okwme wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add ICON namespace (icon) with CAIP-2 profile #208

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 85 additions & 0 deletions icon/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
namespace-identifier: icon
title: ICON
author: ["Billy Rennekamp (@okwme)"]
discussions-to: https://github.com/0xcounting/FAR/issues/1
status: Draft
type: Informational
created: 2026-09-14
---

# Namespace for ICON blockchains

ICON is a layer-1 blockchain with a delegated proof-of-contribution consensus, in which token holders delegate stake to elected Public Representatives who produce blocks.
Smart contracts on ICON are called SCOREs (Smart Contract on Reliable Environment) and are written in Python or Java rather than compiled to an EVM.
The `icon` namespace covers networks that run the ICON node software and expose its ICON JSON-RPC v3 interface.
Individual networks in the namespace are identified by their network ID, or NID, as specified in the [ICON CAIP-2 profile][].

## Address prefixes

ICON uses two address prefixes, and which one an address carries tells you what kind of account it is before you query anything.
An `hx` address is an externally owned account: a wallet controlled by a key.
A `cx` address is a contract account: a deployed SCORE.
In both cases the prefix is followed by exactly 40 lowercase hexadecimal characters encoding 20 bytes, so a full address is 42 characters.

This is more informative than it looks.
On an EVM chain the same 20-byte address space holds both wallets and contracts, and telling them apart requires a `getCode` call.
On ICON the distinction is carried in the identifier itself, which means an indexer, a wallet, or a CAIP-10 implementation can classify an account with a two-character string comparison.
The governance SCORE at `cx0000000000000000000000000000000000000000` is the conventional example of a contract address.

A later CAIP-10 profile for this namespace will need to preserve both prefixes, because `hx…` and `cx…` with the same 40 hex characters are two different accounts, not two spellings of one.

## ICON 2.0 and BTP

ICON migrated from its original loopchain node software to a new implementation, goloop, in the ICON 2.0 upgrade.
That migration replaced the node software, the consensus engine, and the virtual machine layer, but it did not renumber the networks.
MainNet's NID is `0x1` today, confirmed against two live MainNet endpoints, and the ICON documentation records no renumbering across the ICON 2.0 transition.
Anyone citing a NID for ICON should nonetheless resolve it from a node rather than from an ICON 1.0-era document, because the test networks were replaced during and after that transition.

ICON's cross-chain work, the Blockchain Transmission Protocol, introduced a second identifier format that an implementer will encounter: the BTP Network Address.
It is written `<nid>.<network system>`, so ICON MainNet is `0x1.icon`, and a full BTP address is `btp://0x1.icon/hx…`.
The NID inside a BTP Network Address is the same NID this namespace uses as its CAIP-2 reference, which makes BTP addresses a useful independent corroboration of a NID value.
BTP Network Addresses are not themselves CAIP-2 chain IDs and should not be used as references.

## Rationale

`icon` is the ecosystem's own name, is four characters long, and is all lowercase, so it satisfies the CAIP-2 namespace production `[-a-z0-9]{3,8}` without modification.
The provisional name needed no change: CASA names a namespace after an ecosystem, and ICON is the ecosystem.

NID is the right reference because it is the value the protocol itself uses to bind a signed transaction to a network.
Every ICON transaction carries a `nid` field, and a transaction signed with the wrong `nid` is rejected, so NID is already load-bearing for replay protection rather than being a label bolted on for tooling.

This namespace was drafted by the maintainers of FAR, an open cross-reference between CAIP-19, CoinGecko and ISO 24165 identifiers, which needs a CAIP-2 for this chain in order to name the assets that exist on it.
The authors do not represent the ICON ecosystem.
It is offered as a starting point for the ICON community to correct, adopt or replace, and the authors would rather it carry a maintainer's name than theirs.

## Governance

Technical standards for ICON are proposed as ICON Improvement Proposals in the [IIPs repository][], following a process modelled on Ethereum's EIPs.
ICON also has on-chain governance: ICX holders delegate stake to Public Representatives, who vote on Network Proposals that can change network parameters, revise the revision number that gates protocol behaviour, and approve or block SCORE deployments.
The [Network Proposals documentation][] describes the proposal types and the voting mechanics.
An implementer should note that ICON's protocol behaviour is versioned on chain by a revision number changed through this process, so behaviour can change without a node release.

## References

- [ICON documentation][] - Concepts, node operation, and client APIs
- [ICON networks][] - The published NID values for MainNet and the test networks
- [ICON JSON-RPC v3][] - The client API, including `icx_getNetworkInfo`
- [ICON accounts][] - The `hx` and `cx` address formats
- [BTP address][] - The BTP Network Address format and its relation to NID
- [IIPs repository][] - ICON Improvement Proposals
- [Network Proposals documentation][] - On-chain governance process
- [ICON CAIP-2 profile][] - The chain ID specification in this namespace

[ICON documentation]: https://docs.icon.community/
[ICON networks]: https://docs.icon.community/develop-on-icon-chain/networks
[ICON JSON-RPC v3]: https://docs.icon.community/develop-on-icon-chain/client-apis/json-rpc-api
[ICON accounts]: https://docs.icon.community/develop-on-icon-chain/blockchain-components/accounts
[BTP address]: https://docs.icon.community/cross-chain-communication/blockchain-transmission-protocol-btp/btp-address
[IIPs repository]: https://github.com/icon-project/IIPs
[Network Proposals documentation]: https://docs.icon.community/operate-icon/governance/network-proposals
[ICON CAIP-2 profile]: ./caip2.md

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
204 changes: 204 additions & 0 deletions icon/caip2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
---
namespace-identifier: icon-caip2
title: ICON Namespace - Blockchain ID Specification
author: ["Billy Rennekamp (@okwme)"]
discussions-to: https://github.com/0xcounting/FAR/issues/1
status: Draft
type: Standard
created: 2026-09-14
requires: CAIP-2
---

# CAIP-2

*For context, see the [CAIP-2][] specification.*

## Introduction

Every ICON network has a network ID, universally abbreviated NID.
The NID is required in every transaction, and a transaction signed for one NID is rejected on a network with any other, so the NID is the value that binds a signed payload to a network.
The `icon` CAIP-2 profile identifies a network by encoding its NID as a canonical unsigned decimal string.

## Specification

### Semantics

An ICON chain ID consists of the literal namespace `icon`, a colon, and a reference holding the network's NID.
Two networks configured with the same NID have the same CAIP-2 chain ID by definition.

The ICON JSON-RPC renders the NID as a `0x`-prefixed hexadecimal string, because ICON's JSON-RPC v3 encodes every integer that way.
The NID is an integer value, not a string, and the hexadecimal form is a transport encoding rather than the identifier itself.
This profile therefore normalises it to decimal, which removes the case and zero-padding variation that a hexadecimal reference would allow.

### Syntax

```text
chain_id: "icon:" + reference
namespace: icon
reference: 0 | [1-9][0-9]{0,30}
```

The reference must match the following regular expression:

```regex
^(0|[1-9][0-9]{0,30})$
```

The reference is the canonical unsigned decimal encoding of the NID.
It uses ASCII decimal digits with no `0x` prefix, sign, digit separators, surrounding whitespace, or leading zeroes.

To derive the reference from a JSON-RPC response:

1. Read the `nid` field, for example `"0x1"`.
2. Strip the `0x` prefix and parse the remainder as a hexadecimal integer.
3. Serialise that integer as decimal with no leading zeroes.

ICON has not published an upper bound for NID values, so this profile imposes none beyond the 32-character limit CAIP-2 places on references.
Every NID in public use is far smaller than that limit.

### Resolution Mechanics

To resolve the chain ID reported by an ICON JSON-RPC endpoint, call `icx_getNetworkInfo`:

```json
{
"jsonrpc": "2.0",
"method": "icx_getNetworkInfo",
"params": {},
"id": 1
}
```

The following is a verbatim response from a MainNet node at `https://ctz.solidwallet.io/api/v3`, with the block height abbreviated:

```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"platform": "icon",
"nid": "0x1",
"channel": "icon_dex",
"earliest": "0x0",
"stepPrice": "0x2e90edd00"
}
}
```

Convert `result.nid` to canonical decimal and prefix it with `icon:`.
The example response therefore resolves to `icon:1`.

The `platform` field should be checked as well.
A node reporting a `platform` other than `icon` is running a different goloop-based network, and this namespace does not claim it.

## Rationale

NID is the only ICON value whose protocol purpose is to say which network a signed payload belongs to, so it is the natural CAIP-2 reference.
It requires no registry lookup, no hashing, and no truncation, and it is already the value every ICON SDK asks a developer to configure.

Decimal was chosen over ICON's native `0x`-prefixed hexadecimal because a hexadecimal reference would admit several spellings of the same network.
`0x1`, `0x01`, `0X1` and `0x001` all denote NID one, and a reference format that accepts more than one string for a network defeats the purpose of a chain ID.
Decimal has exactly one canonical form per value.
The cost is that `icon:1` does not visually match the `"0x1"` an implementer sees in a JSON-RPC response, which the derivation steps above are written to make explicit.
For the three networks in public use the digits happen to be identical either way, since `0x1`, `0x2` and `0x7` are `1`, `2` and `7`; the forms only diverge at NID ten and above.

The genesis block hash was considered and rejected.
ICON's block hashes are 32 bytes, so a hash reference would require the kind of documented truncation `bip122` and `hive` use, and it would discard the NID, which is the identifier ICON's own tooling, transactions and BTP addresses are built around.

## Well-Known Networks

The following table allows clients to label well-known networks without an RPC round trip.
It is informative; the resolution method above remains authoritative.

| Network | NID (as reported) | CAIP-2 chain ID |
| --- | --- | --- |
| ICON MainNet | `0x1` | `icon:1` |
| Lisbon test network | `0x2` | `icon:2` |
| Berlin test network | `0x7` | `icon:7` |

The MainNet value was read from two independent live endpoints, `https://ctz.solidwallet.io/api/v3` and `https://api.icon.community/api/v3`, which agreed.
The Lisbon and Berlin values are taken from the [ICON networks][] documentation; the published endpoints for both test networks did not resolve at the time of writing, so those two rows are documented but not independently confirmed by the authors.

Lisbon is the long-term-support test network and is the one to target for pre-production testing.
Berlin is the first-stage test network and is reset more aggressively.

## Private Networks and Collisions

NID is chosen by the operator of a network, not allocated by a global registry.
Local development networks conventionally run with a small NID, and every deployment started from the same local-network image shares whatever default that image ships with, so a low-valued reference may name many unrelated private chains and must not be treated as identifying one globally unique network.
If two distinct networks use the same NID, this profile cannot distinguish them and their CAIP-2 chain IDs collide.

Operators who need a distinguishable private network should pick a NID well away from the well-known values above and keep it stable.

## Backwards Compatibility

There was no previously registered CAIP-2 profile for ICON.
This profile does not change any native ICON identifier.

ICON migrated from its original loopchain node software to goloop in the ICON 2.0 upgrade.
MainNet's NID is `0x1` after that migration, as confirmed against live nodes, and the ICON documentation records no renumbering.
The test networks were replaced across and after the transition, however, so NIDs quoted for retired test networks such as Euljiro or Yeouido should not be assumed to be live.

## Test Cases

### Valid identifiers

| Identifier | Reason |
| --- | --- |
| `icon:1` | ICON MainNet |
| `icon:2` | Lisbon test network |
| `icon:7` | Berlin test network |
| `icon:0` | Valid zero reference |
| `icon:255` | Decimal form of a hypothetical NID `0xff` |

### Invalid identifiers

| Identifier | Reason |
| --- | --- |
| `icon:` | Empty reference |
| `icon:0x1` | Native hexadecimal transport form rather than canonical decimal |
| `icon:0X1` | Hexadecimal form with uppercase prefix |
| `icon:01` | Leading zero |
| `icon:00` | Non-canonical zero |
| `icon:-1` | Signed value |
| `icon:0xff` | Hexadecimal representation of 255 |
| `icon:1.icon` | BTP Network Address rather than a CAIP-2 reference |
| `icon:0x1.icon` | BTP Network Address, also containing an illegal `.` |
| `icon: 1` | Leading whitespace |
| `ICON:1` | Incorrect namespace casing |

## Additional Considerations

Some goloop-based deployments distinguish a chain's internal chain ID, CID, from its network ID, NID, and the two need not be equal.
This profile normatively uses the `nid` reported by `icx_getNetworkInfo`, because that is the value transactions are signed against.
The authors were unable to review the goloop reference implementation to describe the CID/NID relationship precisely, because the `icon-project/goloop` repository was not publicly reachable at the time of writing.
The ICON community should correct this section if the distinction matters for any network that expects to be named in this namespace.

A later CAIP-10 profile must preserve ICON's `hx` and `cx` address prefixes; see the [namespace README][].
A later CAIP-19 profile will need to cover the native coin ICX alongside ICON's IRC token standards, whose tokens are SCOREs identified by `cx` addresses.

## Security Considerations

Resolving a chain ID through `icx_getNetworkInfo` establishes only what the queried endpoint reports.
It does not authenticate the endpoint, and it does not make an operator-chosen NID globally unique.
Applications that depend on a trusted chain identity should use authenticated endpoints, or corroborate the reported NID against a known block hash on the network they expect.

## References

- [CAIP-2][] - Blockchain ID specification
- [ICON networks][] - Published NID values for MainNet, Lisbon and Berlin
- [ICON JSON-RPC v3][] - The client API, including `icx_getNetworkInfo` and the `0x`-prefixed integer encoding
- [ICON accounts][] - The `hx` and `cx` address formats referenced in the test cases
- [BTP address][] - BTP Network Addresses such as `btp://0x1.icon/hx…`, which embed the same NID
- [namespace README][] - ICON namespace overview, address prefixes, and the ICON 2.0 transition

[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2
[ICON networks]: https://docs.icon.community/develop-on-icon-chain/networks
[ICON JSON-RPC v3]: https://docs.icon.community/develop-on-icon-chain/client-apis/json-rpc-api
[ICON accounts]: https://docs.icon.community/develop-on-icon-chain/blockchain-components/accounts
[BTP address]: https://docs.icon.community/cross-chain-communication/blockchain-transmission-protocol-btp/btp-address
[namespace README]: ./README.md

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).