Skip to content

Dip 9001

dip: 9001 title: Government Administration Network Identifiers (GANI) author: Cosimo Constantinos cosimo@juro.net Digitalia editing author: Cosimo Constantinos cosimo@juro.net type: Standards Track category: Networking status: Draft created: 2026-04-16 Created for Digitalia: 2025-01-07 requires: 155

Abstract

This DIP introduces Government Administration Network Identifiers (GANI) — an alphanumeric networkId field for Digitalia genesis configurations that enables sovereign governments to operate dedicated private blockchain networks for public administration and government DApps. The identifier encodes the ISO 3166-1 alpha-2 country code combined with the ITU-T E.164 calling code (e.g. AF93 for Afghanistan). The numeric chainId required for DIP-155 transaction signing is derived deterministically from the alphanumeric networkId via base-36 encoding.

The Digitalia Mainnet (chainId: 1) is unaffected by this DIP.

Motivation

Existing Digitalia network identifiers are strictly numeric (positive integers) which are human-opaque and provide no intrinsic metadata about the operating jurisdiction. Government networks require:

  1. Human-readable identity — operators and auditors must be able to immediately identify which jurisdiction operates a given network without consulting an external registry.
  2. Globally unique identifiers — the identifier scheme must be collision-free across all 250+ jurisdictions covered by ISO 3166-1.
  3. DIP-155 compatibility — existing transaction signing and replay-protection mechanisms must continue to function without modification.
  4. Permissioned network semantics — government networks are private, permissioned chains and must be clearly distinguishable in genesis configuration from public networks.

Specification

1. The networkId Field

A new optional field networkId is added to the genesis configuration config block:

{
  "config": {
    "networkId": "AF93",
    ...
  }
}

The networkId value: - MUST be an uppercase alphanumeric string (characters A–Z, 0–9). - MUST follow the GANI encoding scheme: {ISO 3166-1 alpha-2}{ITU-T E.164 code} (see §3). - MUST NOT be "1" (reserved for Digitalia Mainnet, numeric only). - MAY be present alongside an explicit chainId. If both are present, chainId takes precedence for DIP-155 transaction signing. - When networkId is present and chainId is absent, the effective numeric chain ID is derived as defined in §2.

2. Numeric Chain ID Derivation

When a genesis configuration carries networkId but no explicit chainId, the numeric chain ID used for DIP-155 transaction signing MUST be computed as:

effectiveChainId = new BigInteger(networkId.toUpperCase(), 36)

This is the standard base-36 integer decoding of the alphanumeric string, treating A–Z as digits 10–35 and 0–9 as digits 0–9.

Examples:

networkId Country effectiveChainId (base-36 decode)
AF93 Afghanistan 486,327
DE49 Germany 519,765
US1 United States 1,116,001
CA1 Canada 435,601
GB44 United Kingdom 597,120
DA1 Atlantis, Dominion of 17,209
AB7840 Abkhazia 623,474,640

All derived chain IDs are distinct and do not conflict with any Digitalia public network chain ID (Mainnet=1, Testnet=11).

3. GANI Encoding Scheme

The alphanumeric networkId is composed as:

networkId = {ISO_ALPHA2}{ITU_CODE}

Where: - ISO_ALPHA2 is the ISO 3166-1 alpha-2 two-letter country code, uppercased. - ITU_CODE is the ITU-T E.164 international calling code (digits only, no leading +). - Territories without an ITU calling code use XX as the ITU_CODE suffix (e.g. AQXX for Antarctica, BVXX for Bouvet Island). - Partially-recognised territories and special jurisdictions (e.g. Abkhazia, North Cyprus, Atlantis Dominion) use their assigned alpha-2 code and calling code from the canonical government networks registry.

The authoritative registry is published at: config/src/main/resources/government-networks-registry.json

4. Genesis Configuration

A government network genesis file MUST include:

{
  "config": {
    "networkId": "<GANI_CODE>",
    "digitalia": {
      "networkType": "government",
      "accessPolicy": "permissioned"
    },
    ...standard fork block fields at 0...
  }
}

The reference genesis template is available at: config/src/main/resources/government-network-template.json

5. ChainIdDeserializer Behaviour

The ChainIdDeserializer (used when the chainId field in genesis JSON is a string) is extended to handle alphanumeric values:

  1. Try hex: attempt UInt256.fromHexString(value).
  2. Fallback to base-36: on parse failure, attempt new BigInteger(value.toUpperCase(), 36).
  3. Error: if both fail, throw IllegalArgumentException.

This allows operators to set "chainId": "AF93" directly in JSON as a convenience shorthand, producing the same numeric chain ID as the base-36 derivation.

6. getEffectiveChainId() API

The GenesisConfigOptions interface exposes a default method:

default Optional<BigInteger> getEffectiveChainId() {
    final Optional<BigInteger> explicit = getChainId();
    if (explicit.isPresent()) {
        return explicit;
    }
    return getNetworkId().map(id -> new BigInteger(id.toUpperCase(), 36));
}

All components requiring the numeric chain ID for DIP-155 signing SHOULD call getEffectiveChainId() rather than getChainId() directly when operating with government network genesis files.

Rationale

Why base-36?

Base-36 (digits 0–9, letters A–Z) is the natural encoding for uppercase alphanumeric strings and is natively supported by java.math.BigInteger. It produces deterministic, unique, and reproducible numeric values from the alphanumeric identifier without any additional lookup table. The resulting numeric values are large enough (typically 17,000 – 623,000,000 range for 3–6 character IDs) to avoid collision with all current and plausible future public Digitalia chain IDs.

Why not a separate lookup table?

A static lookup table would require consensus on the mapping and would be brittle to territory additions. The base-36 derivation is self-contained and computable by any node without external state.

Why is networkId separate from chainId?

DIP-155 specifies that CHAIN_ID is used in the transaction signing hash as a uint256 integer. Changing the type of chainId to a string would break all transaction signing and verification logic. Introducing a separate networkId field preserves full DIP-155 compatibility while adding human-readable identification at the configuration layer.

Backwards Compatibility

This DIP is fully backwards-compatible: - All existing numeric chainId values continue to function unchanged. - networkId is an optional field; genesis files without it are unaffected. - The ChainIdDeserializer change is backwards-compatible: valid hex/numeric strings continue to parse as before.

Security Considerations

  • Government network genesis files MUST use permissioned validator sets (Clique PoA or QBFT). Open validator access on a government network is prohibited.
  • The networkId field does not grant any special permissions or access controls on the Digitalia Mainnet. It is a configuration-layer identifier only.
  • Base-36 collision analysis: the shortest possible GANI codes are 3 characters (e.g. DA1 = 17,209). This is above all current Digitalia public network chain IDs and below uint256 overflow by many orders of magnitude.
  • Operators MUST verify their derived effectiveChainId does not collide with any registered network before deployment, using the canonical registry.

Copyright and related rights waived via Juro Restricted License v2.