CIP 34: Network Registry

CIP-0034/README.md

@@ -0,0 +1,69 @@
+---
+CIP: 34
+Title: Chain ID Registry
+Authors: Sebastien Guillemot <seba@dcspark.io>
+Comments-URI: No comments
+Status: Draft
+Type: Informational
+Created: 2021-11-24
+License: CC-BY-4.0
+---
+
+## Abstract
+
+Currently Cardano has two easily-usable networks: "mainnet" and "testnet". However, in the future, we expect more networks to exist and so we need some way to refer to these networks to be able to write better multi-network applications and systems.
+
+## Terminology
+
+### Existing network IDs
+
+Cardano currently has three ways to refer to a network:
+- The "network ID" included in every address and also optionally present in the transaction body. This only stores 16 possibilities (4 bits)
+- The "network magic" used for Byron addresses and in the handshake with other nodes in the network layer. This is a random 32-bit number
+- The genesis block hash (a 28-byte number)
+
+## Motivation
+
+Blockchains can have multiple deployments of the same codebase. For example:
+
+1. Test networks where the base asset has no value (so devs can test at no cost)
+1. Test networks where the protocol is simplified for ease of testing (ex: Cardano but with a Proof of Authority consensus for stable block production in testing)
+1. Test networks for new features
+    1. Plutus Application Backend (PAB) testnet
+    2. Shelley incentivized testnet
+1. Forks that diverge in feature set (the many forks of Bitcoin and Ethereum)
+
+dApps may be deployed on specific testnets that match their criteria and wallets need to know about these networks to know how to behave.
+
+Additionally, having a standardized registry for networks allows easy integration into the broader crypto ecosystem via standards like [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md)
+
+## Specification
+
+We create a machine-readable registry of networks
+
+All entries in this registry should have the following entries:
+
+- User-friendly name
+- Network ID
+- Network magic
+- Genesis hash
+
+When representing these networks in a human-readable string, the following format shall be used:
+
+```
+cip34:NetworkId-NetworkMagic
+```
+
+# Rationale
+
+We pick this format for the following reason:
+- The network ID is too small to be used by itself. You can see from [chainlist](https://chainlist.org/) that 16 possibilities is too few
+- The genesis hash is too long and user-unfriendly to be used.
+
+# Reference implementation
+
+[CIP34-JS](https://www.npmjs.com/package/@dcspark/cip34-js)
+
+## Copyright
+
+This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode)

CIP-0034/registry.json

@@ -0,0 +1,14 @@
+{
+    "Mainnet": {
+        "Name": "Mainnet",
+        "NetworkId": 1,
+        "NetworkMagic": 764824073,
+        "GenesisHash": "5f20df933584822601f9e3f8c024eb5eb252fe8cefb24d1317dc3d432e940ebb"
+    },
+    "Testnet": {
+        "Name": "Testnet",
+        "NetworkId": 0,
+        "NetworkMagic": 1097911063,
+        "GenesisHash": "96fceff972c2c06bd3bb5243c39215333be6d56aaf4823073dca31afe5038471"
+    }
+}

CIP-0034/schema.json

@@ -0,0 +1,37 @@
+{
+  "definitions": {
+    "network": {
+      "$id": "#/definitions/network",
+      "type": "object",
+      "properties": {
+        "Name": {
+          "type": "string"
+        },
+        "NetworkId": {
+          "type": "integer",
+          "minimum": 0,
+          "exclusiveMaximum": 16
+        },
+        "NetworkMagic": {
+          "type": "integer",
+          "minimum": 0,
+          "exclusiveMaximum": 4294967295
+        },
+        "GenesisHash": {
+          "type": "string",
+          "pattern": "^[0-9a-fA-F]+$",
+          "minLength": 64,
+          "maxLength": 64
+        }
+      },
+      "required": [
+        "Name",
+        "NetworkId",
+        "NetworkMagic",
+        "GenesisHash"
+      ]
+     }
+  },
+  "type": "object",
+  "additionalProperties": { "$ref": "#/definitions/network" }
+}