Consolidate configs, fix URL handling, improve docs and developer tooling

CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to Numbers Network
+
+Thank you for your interest in contributing to Numbers Network!
+
+## Getting Started
+
+### Prerequisites
+
+- [avalanchego](https://github.com/ava-labs/avalanchego/releases) — see `versions.env` for the supported version
+- [subnet-evm](https://github.com/ava-labs/subnet-evm/releases) — see `versions.env` for the supported version
+- Python 3.8+ with `pip` (for RPC tests)
+- `jq` (for JSON formatting)
+- `nginx` (for RPC provider setup)
+
+### Setup
+
+1. Clone the repository:
+
+    ```sh
+    git clone https://github.com/numbersprotocol/numbers-network.git
+    cd numbers-network
+    ```
+
+2. Install Python dependencies:
+
+    ```sh
+    pip install -r requirements.txt
+    ```
+
+3. Source version variables when running update scripts:
+
+    ```sh
+    source versions.env
+    ```
+
+## Repository Structure
+
+```
+numbers-network/
+├── api/                # AvalancheGo API helper scripts
+│   └── env.sh          # Set URL for local node (default: 127.0.0.1:9650)
+├── avalanchego/
+│   └── configs/        # Chain and upgrade configuration files
+├── chains/             # Validator update scripts and genesis files
+│   ├── mainnet/        # Mainnet genesis
+│   └── testnet/        # Testnet genesis files (canonical location)
+├── rpc/                # RPC test scripts and Nginx configs
+│   ├── mainnet/        # Mainnet Nginx config
+│   └── testnet/        # Testnet Nginx config
+├── subnet-cli/         # subnet-cli helper scripts
+├── versions.env        # Canonical avalanchego and subnet-evm versions
+└── requirements.txt    # Python dependencies
+```
+
+## API Scripts
+
+The `api/` directory contains helper scripts for interacting with a local AvalancheGo node.
+
+- All scripts source `api/env.sh` which sets `URL="127.0.0.1:9650"` by default.
+- To target a different node, set the `URL` environment variable before running a script:
+
+    ```sh
+    URL="https://api.avax.network" ./api/platform.getCurrentValidators.sh <subnet-id>
+    ```
+
+## Running Tests
+
+```sh
+python3 rpc/rpc_test.py
+python3 rpc/websocket_test.py
+```
+
+## Making Changes
+
+1. Create a feature branch from `main`.
+2. Make your changes, following the style of existing files.
+3. For JSON files, normalize formatting with `jq .`:
+
+    ```sh
+    jq . file.json > /tmp/normalized.json && mv /tmp/normalized.json file.json
+    ```
+
+4. Update `versions.env` if software versions change.
+5. Open a pull request with a clear description of the change.
+
+## Code Style
+
+- Shell scripts: use `#!/bin/bash` shebang; source `env.sh` for the node URL.
+- JSON: 2-space indentation (normalized by `jq`).
+- Python: follow PEP 8.

Makefile

@@ -0,0 +1,24 @@
+.PHONY: help setup test test-rpc test-ws fmt check-versions
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+setup: ## Install Python dependencies
+	pip install -r requirements.txt
+
+test: test-rpc ## Run all tests
+
+test-rpc: ## Test mainnet and testnet RPC connectivity
+	python3 rpc/rpc_test.py
+
+test-ws: ## Test mainnet and testnet WebSocket connectivity
+	python3 rpc/websocket_test.py
+
+fmt: ## Normalize JSON formatting in avalanchego config files
+	@find avalanchego/configs -name "*.json" | while read f; do \
+		jq . "$$f" > /tmp/normalized.json && mv /tmp/normalized.json "$$f"; \
+		echo "Formatted: $$f"; \
+	done
+
+check-versions: ## Show configured software versions
+	@. ./versions.env && echo "avalanchego: v$$AVALANCHEGO_VERSION" && echo "subnet-evm:  v$$SUBNET_EVM_VERSION"

README.md

@@ -34,7 +34,7 @@ Numbers Network is dedicated to preserving digital media provenance and related
 - [Self-Hosted Faucet](#self-hosted-faucet)
 - [Wrapped NUM](#wrapped-num)
 - [Bridge](#bridge)
-- [Archieve Node](#archieve-node)
+- [Archive Node](#archive-node)
 
 ## Mainnet: Jade (玉)
 
@@ -286,7 +286,7 @@ waiting for validator 8CGJYaRLChC79CCRnvd7sh5eB9E9L9dVF to start validating GBEw
 
 Launch validator. When running `avalanchego`, add
 
-* `-—http-host=0.0.0.0`: Make MetaMask can access the RPC URL
+* `--http-host=0.0.0.0`: Make MetaMask can access the RPC URL
 * `--http-allowed-hosts="*"`: Allow traffic from the RPC node (since v1.10.3)
 
 ```sh
@@ -342,8 +342,6 @@ Before validation staking expires, any wallet can not stake to a validator again
 
 Validator version distributions: [mainnet](https://explorer-xp.avax.network/validators), [testnet](https://explorer-xp.avax-test.network/validators)
 
-[Renew Numbers Validators](https://app.asana.com/0/1202305127727547/1202919355642524/f) (internal task)
-
 ## Import Existing L1 in Avalanche CLI
 
 ```sh
@@ -863,7 +861,7 @@ To bridge native NUM to ERC20/BEP20 NUM, you can use [XY Finance](https://app.xy
 
 To know more about NUM token, you can visit the [NUM token website](https://num.numbersprotocol.io/).
 
-# Archieve Node
+# Archive Node
 
 Archive Node provides full history of the blockchain and does not need to be a validator.
 
@@ -919,10 +917,10 @@ Make a Full Node instance to be an Archive Node instance:
     #!/bin/sh
 
     # Subnet IDs
-    SUBNET_MAINNET="81vK49Udih5qmEzU7opx3Zg9AnB33F2oqUTQKuaoWgCvFUWQe"
+    SUBNET_TESTNET="81vK49Udih5qmEzU7opx3Zg9AnB33F2oqUTQKuaoWgCvFUWQe"
 
     ./avalanchego \
-        --track-subnets=${SUBNET_MAINNET} \
+        --track-subnets=${SUBNET_TESTNET} \
         --http-host=0.0.0.0 \
         --public-ip=<node-public-ip> \
         --http-allowed-hosts="*"

api/health.health.sh

@@ -1,7 +1,9 @@
 #!/bin/bash
 
+source env.sh
+
 curl -X POST --data '{
     "jsonrpc":"2.0",
-        "id"     :1,
-	    "method" :"health.health"
-    }' -H 'content-type:application/json;' 127.0.0.1:9650/ext/health
+    "id"     :1,
+    "method" :"health.health"
+}' -H 'content-type:application/json;' ${URL}/ext/health

api/info.getNodeID.sh

@@ -5,7 +5,7 @@
 # Expected Output
 # {"jsonrpc":"2.0","result":{"nodeID":"NodeID-JRhJd4Qn4WTjP28RUFDQa2NC59deo7tT6"},"id":1}
 
-URL="127.0.0.1:9650"
+source env.sh
 
 curl -X POST --data '{
     "jsonrpc":"2.0",

api/info.isBootstrapped.sh

@@ -3,14 +3,15 @@
 # Note: The bootstrapping process takes approximately 50–100 hours and requires 100 GB of space.
 # https://chainstack.com/avalanche-subnet-tutorial-series-running-a-local-avalanche-node-on-fuji-testnet/
 
-URL="127.0.0.1:9650"
+source env.sh
+
 CHAIN_ID="$1"
 
-curl -X POST --data "{ 
-    \"jsonrpc\": \"2.0\", 
-    \"method\": \"info.isBootstrapped\", 
-    \"params\":{ 
-        \"chain\":\"${CHAIN_ID}\" 
-    }, 
-    \"id\": 1 
-}" -H 'content-type:application/json;' ${URL}/ext/info 
+curl -X POST --data "{
+    \"jsonrpc\": \"2.0\",
+    \"method\": \"info.isBootstrapped\",
+    \"params\":{
+        \"chain\":\"${CHAIN_ID}\"
+    },
+    \"id\": 1
+}" -H 'content-type:application/json;' ${URL}/ext/info

api/metrics.sh

@@ -1,3 +1,5 @@
 #!/bin/bash
 
-curl -X POST 127.0.0.1:9650/ext/metrics
+source env.sh
+
+curl -X POST ${URL}/ext/metrics

api/platform.getBlockchainStatus.sh

@@ -7,7 +7,8 @@
 #   "vmID": "kmYb53NrmqcW7gfV2FGHBHWXNA6YhhWf7R7LoQeGj9mdDYuaT"
 # }
 
-URL="127.0.0.1:9650"
+source env.sh
+
 BLOCKCHAIN_ID="$1"
 
 curl -X POST --data "{
@@ -17,4 +18,4 @@ curl -X POST --data "{
         \"blockchainID\":\"${BLOCKCHAIN_ID}\"
     },
     \"id\": 1
-}" -H 'content-type:application/json;' ${URL}/ext/P
+}" -H 'content-type:application/json;' ${URL}/ext/bc/P

api/platform.getBlockchains.sh

@@ -7,4 +7,4 @@ curl -X POST --data '{
     "id" :1,
     "method" :"platform.getBlockchains",
     "params" :{}
-}' -H 'content-type:application/json;' ${URL}/ext/P
+}' -H 'content-type:application/json;' ${URL}/ext/bc/P

api/platform.getCurrentValidators.sh

@@ -3,7 +3,8 @@
 # Note: The bootstrapping process takes approximately 50–100 hours and requires 100 GB of space.
 # https://chainstack.com/avalanche-subnet-tutorial-series-running-a-local-avalanche-node-on-fuji-testnet/
 
-URL="127.0.0.1:9650"
+source env.sh
+
 SUBNET_ID="$1"
 curl -X POST --data "{
     \"jsonrpc\": \"2.0\",

api/platform.getPendingValidators.sh

@@ -3,13 +3,13 @@
 # Note: The bootstrapping process takes approximately 50–100 hours and requires 100 GB of space.
 # https://chainstack.com/avalanche-subnet-tutorial-series-running-a-local-avalanche-node-on-fuji-testnet/
 
-URL="127.0.0.1:9650"
+source env.sh
 
 echo "URL: ${URL}"
 
 curl -X POST --data '{
     "jsonrpc": "2.0",
-        "method": "platform.getPendingValidators",
-	    "params": {},
-	        "id": 1
-	}' -H 'content-type:application/json;' ${URL}/ext/bc/P
+    "method": "platform.getPendingValidators",
+    "params": {},
+    "id": 1
+}' -H 'content-type:application/json;' ${URL}/ext/bc/P

api/platform.getSubnets.sh

@@ -3,13 +3,13 @@
 # Note: The bootstrapping process takes approximately 50–100 hours and requires 100 GB of space.
 # https://chainstack.com/avalanche-subnet-tutorial-series-running-a-local-avalanche-node-on-fuji-testnet/
 
-URL="127.0.0.1:9650"
+source env.sh
 
 echo "URL: ${URL}"
 
 curl -X POST --data '{
     "jsonrpc": "2.0",
-        "method": "platform.getSubnets",
-	    "params": {},
-	        "id": 1
-	}' -H 'content-type:application/json;' ${URL}/ext/bc/P
+    "method": "platform.getSubnets",
+    "params": {},
+    "id": 1
+}' -H 'content-type:application/json;' ${URL}/ext/bc/P

api/platform.getValidatorsAt.sh

@@ -1,13 +1,15 @@
 #!/bin/bash
 
+source env.sh
+
 SUBNET_ID="$1"
 
 curl -X POST --data "{
     \"jsonrpc\": \"2.0\",
     \"method\": \"platform.getValidatorsAt\",
     \"params\": {
         \"height\":1,
-	\"subnetID\": \"${SUBNET_ID}\"
+        \"subnetID\": \"${SUBNET_ID}\"
     },
     \"id\": 1
-}" -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
+}" -H 'content-type:application/json;' ${URL}/ext/bc/P

api/platform.validatedBy.sh

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+source env.sh
+
 BLOCKCHAIN_ID="$1"
 
 curl -X POST --data "{
@@ -9,4 +11,4 @@ curl -X POST --data "{
         \"blockchainID\": \"${BLOCKCHAIN_ID}\"
     },
     \"id\": 1
-}" -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
+}" -H 'content-type:application/json;' ${URL}/ext/bc/P

api/platform.validates.sh

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+source env.sh
+
 SUBNET_ID="$1"
 
 curl -X POST --data "{
@@ -9,5 +11,4 @@ curl -X POST --data "{
         \"subnetID\":\"${SUBNET_ID}\"
     },
     \"id\": 1
-}" -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
-
+}" -H 'content-type:application/json;' ${URL}/ext/bc/P

avalanchego/configs/README.md

@@ -8,12 +8,14 @@ Reference configuration files for Numbers Network nodes running on Avalanche inf
 configs/chains/
 ├── C/                          # Avalanche C-Chain configuration
 │   └── config.json            # Pruning enabled for storage optimization
-├── 2oo5UvYgFQikM7KBsMXFQE3RQv3xAFFc8JY2GEBNBF1tp4JaeZ/  # Numbers Testnet
+├── 2oo5UvYgFQikM7KBsMXFQE3RQv3xAFFc8JY2GEBNBF1tp4JaeZ/  # Numbers Testnet (Snow)
 │   ├── config.json            # Archive node configuration
-│   └── config-validator.json  # Validator node configuration
-└── 2PDRxzc6jMbZSTLb3sufkVszgQc2jtDnYZGtDTAAfom1CTwPsE/  # Numbers Mainnet
+│   ├── config-validator.json  # Validator node configuration
+│   └── upgrade.json           # Network upgrade schedule
+└── 2PDRxzc6jMbZSTLb3sufkVszgQc2jtDnYZGtDTAAfom1CTwPsE/  # Numbers Mainnet (Jade)
     ├── config.json            # Archive node configuration
-    └── config-validator.json  # Validator node configuration
+    ├── config-validator.json  # Validator node configuration
+    └── upgrade.json           # Network upgrade schedule
 ```
 
 ## Configuration Overview
@@ -36,6 +38,17 @@ The C-Chain configuration enables pruning to optimize storage usage:
 - Maintains recent state for validation
 - Reduced disk space requirements
 
+## Network Upgrades (`upgrade.json`)
+
+Unix timestamps used in `upgrade.json` files, with their human-readable equivalents:
+
+| Chain   | Timestamp  | Human-Readable (UTC)      | Description                              |
+|---------|------------|---------------------------|------------------------------------------|
+| Testnet | 1762510500 | 2025-11-07 10:15:00 UTC   | Granite network upgrade override         |
+| Testnet | 1767786600 | 2026-01-07 11:50:00 UTC   | Enable ContractDeployerAllowList precompile |
+| Testnet | 1767787800 | 2026-01-07 12:10:00 UTC   | Disable ContractDeployerAllowList precompile |
+| Mainnet | 1767789000 | 2026-01-07 12:30:00 UTC   | Disable ContractDeployerAllowList precompile |
+
 ## Usage
 
 Copy the appropriate configuration files to your AvalancheGo installation:

avalanchego/configs/chains/2PDRxzc6jMbZSTLb3sufkVszgQc2jtDnYZGtDTAAfom1CTwPsE/config-validator.json

@@ -1,5 +1,5 @@
 {
-    "feeRecipient": "0xe49a1220eE09Fbf0D25CA9e3BB8D5fD356Fc67FF",
-    "pruning-enabled": true,
-    "allow-missing-tries": true
+  "feeRecipient": "0xe49a1220eE09Fbf0D25CA9e3BB8D5fD356Fc67FF",
+  "pruning-enabled": true,
+  "allow-missing-tries": true
 }