Neo Namespace - Chains

CAIP-2

For context, see the CAIP-2 specification.

Introduction

Every Neo N3 node is configured with an unsigned 32-bit Network Magic value. The neo CAIP-2 profile identifies a blockchain by encoding that value as a canonical unsigned decimal string.

Specification

Semantics

A Neo chain ID consists of the literal namespace neo, a colon, and a reference containing the blockchain’s Network Magic. Two blockchains configured with the same Network Magic have the same CAIP-2 chain ID by definition.

Syntax

chain_id:  "neo:" + reference
namespace: neo
reference: 0 | [1-9][0-9]{0,9}

The reference must match the following regular expression:

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

The parsed value must additionally be in the unsigned 32-bit integer range 0 through 4294967295, inclusive. The regular expression alone is not sufficient to enforce the upper bound.

The reference uses ASCII decimal digits without a sign, base prefix, separators, surrounding whitespace, or leading zeroes. The single value zero is encoded as 0. It is a valid reference and has no special meaning.

Resolution Mechanics

To resolve the chain ID reported by a Neo N3 JSON-RPC endpoint, call the getversion method:

{
  "jsonrpc": "2.0",
  "method": "getversion",
  "params": [],
  "id": 1
}

The response contains the Network Magic in result.protocol.network. The following is an abbreviated response from a MainNet node:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocol": {
      "network": 860833102
    }
  }
}

Validate the returned value as a uint32, serialize it in canonical unsigned decimal form, and prefix it with neo:. The example response therefore resolves to neo:860833102.

Rationale

Network Magic is the native network discriminator in Neo N3 protocol settings and is exposed directly by the standard JSON-RPC interface. Using it requires no additional registry or transformation and works for both public and independently operated Neo N3 networks.

Decimal encoding matches the JSON-RPC representation and avoids multiple textual forms for the same value, such as hexadecimal, signed, or zero-padded representations. The neo namespace identifier and decimal Network Magic reference were supported by the Neo community in the namespace discussion.

Well-Known Networks

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

The Neo N3 values are defined by the official MainNet configuration and TestNet configuration. The NeoFS values are defined by the NeoGo network magic constants.

Private Networks and Collisions

Network Magic is selected by the operator of a private Neo N3 network and is not allocated by a global registry. If two distinct blockchains use the same Network Magic, this profile cannot distinguish them and their CAIP-2 chain IDs collide.

Operators that require a distinguishable private-network identifier must keep their Network Magic stable, avoid the well-known values above, and coordinate with every other network in the interoperability domain. Selecting a random uint32 value and checking known deployments reduces the risk of accidental collision but does not guarantee global uniqueness.

Development tools can reuse conventional values across isolated deployments. For example, NeoGo defines 56753 as a default private-network magic; such a default must not be treated as identifying one globally unique blockchain.

Backwards Compatibility

There was no previously registered CAIP-2 profile for Neo N3. This profile does not change Neo’s native Network Magic values.

Test Cases

Valid identifiers

Invalid identifiers

Security Considerations

Resolving a chain ID through getversion only establishes what the queried endpoint reports. It does not authenticate that endpoint or make an operator-selected Network Magic globally unique. Applications that rely on a trusted chain identity should use authenticated endpoints or corroborate the result with trusted chain metadata.

References

• CAIP-2 - Blockchain ID specification
• Neo ProtocolSettings - Reference implementation and uint32 Network Magic type
• getversion - JSON-RPC method exposing result.protocol.network
• MainNet configuration - Official Neo N3 MainNet Network Magic
• TestNet configuration - Official Neo N3 TestNet T5 Network Magic
• NeoGo network magic constants - NeoFS and development-network values
• Namespace discussion - Neo community review of this profile

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Erik Zhang, "namespaces/neo-caip2: Neo Namespace - Chains [DRAFT]," Chain Agnostic Namespaces, neo-caip2, July 2026 / . [Online serial]. Available: https://github.com/ChainAgnostic/namespaces/neo-caip2.md