Harden canonical network config surface

Author: sls_0x

.env.example

@@ -0,0 +1,10 @@
+# Canonical Dark Null root defaults
+DARK_NULL_NETWORK=devnet
+DARK_NULL_RPC_URL=https://api.devnet.solana.com
+DARK_NULL_WALLET_PATH=~/.config/solana/id.json
+
+# Optional proving overrides
+DARK_NULL_SNARKJS=snarkjs
+DARK_NULL_ZKEY_PATH=circuits/null_proof_final.zkey
+DARK_NULL_WASM_PATH=circuits/null_proof_js/null_proof.wasm
+DARK_NULL_VK_PATH=circuits/vk.json

.gitignore

@@ -45,6 +45,7 @@ vkey*.json
 .env
 .env.*
 *.env
+!.env.example
 deployer_wallet.json
 main_wallet.json
 relayer.json

MANIFEST.json

@@ -29,8 +29,13 @@
     },
     {
       "path": "Cargo.toml",
-      "sha256": "52c55cd3dbbae0bb9e199f382112e41c1b817998af1e286691a8ec115ab2234b",
-      "size": 858
+      "sha256": "692106d80328cc9c5835f7b7e4d3e26bc73f6f8bfbc4af65b6281899079f119c",
+      "size": 1069
+    },
+    {
+      "path": "NETWORKS.json",
+      "sha256": "22828856a7d97f054ac0e2833a138400edeae1d7d84daa777eff69b320efd9e0",
+      "size": 631
     },
     {
       "path": "src/lib.rs",

NETWORKS.json

@@ -0,0 +1,22 @@
+{
+  "canonicalProgramId": "2stas3cZYnBiWpndcTXQDGLXwfQ7kjEYYrW52DsUAcxF",
+  "defaultNetwork": "devnet",
+  "supportedNetworks": {
+    "devnet": {
+      "label": "Canonical devnet",
+      "cluster": "devnet",
+      "anchorCluster": "devnet",
+      "rpcUrl": "https://api.devnet.solana.com",
+      "wsUrl": "wss://api.devnet.solana.com/",
+      "manifestKey": "canonicalDevnet"
+    },
+    "localnet": {
+      "label": "Canonical localnet",
+      "cluster": "localnet",
+      "anchorCluster": "localnet",
+      "rpcUrl": "http://127.0.0.1:8899",
+      "wsUrl": "ws://127.0.0.1:8900",
+      "manifestKey": "canonicalDevnet"
+    }
+  }
+}

README.md

@@ -12,6 +12,7 @@ This repo now has one canonical public root:
 
 - one program ID: `2stas3cZYnBiWpndcTXQDGLXwfQ7kjEYYrW52DsUAcxF`
 - one root manifest: [`MANIFEST.json`](./MANIFEST.json)
+- one network map: [`NETWORKS.json`](./NETWORKS.json)
 - one root IDL: [`idl/paradox.json`](./idl/paradox.json)
 - one root circuit bundle: [`circuits/null_proof.circom`](./circuits/null_proof.circom), [`circuits/null_proof_final.zkey`](./circuits/null_proof_final.zkey), [`circuits/null_proof_js/null_proof.wasm`](./circuits/null_proof_js/null_proof.wasm), [`circuits/vk.json`](./circuits/vk.json)
 - one root verifier path: [`src/lib.rs`](./src/lib.rs) + [`src/verifying_key.rs`](./src/verifying_key.rs)
@@ -34,6 +35,21 @@ If you want the extended validation path:
 FULL_VALIDATION=1 sh scripts/bootstrap.sh
 ```
 
+## Canonical Network Selection
+
+```bash
+npm run config:devnet
+npm run config:localnet
+```
+
+For machine-readable output:
+
+```bash
+npm run config:json:devnet
+```
+
+Canonical defaults also live in [`.env.example`](./.env.example).
+
 ## npm SDK
 
 ```bash
@@ -51,6 +67,7 @@ npm install @dark-null/protocol @coral-xyz/anchor @solana/web3.js
 | Area | Root path |
 |---|---|
 | Program binding | [`MANIFEST.json`](./MANIFEST.json), [`Anchor.toml`](./Anchor.toml), [`src/lib.rs`](./src/lib.rs) |
+| Network config | [`NETWORKS.json`](./NETWORKS.json), [`.env.example`](./.env.example), [`scripts/network-config.mjs`](./scripts/network-config.mjs) |
 | Verifier | [`src/verifying_key.rs`](./src/verifying_key.rs), [`circuits/vk.json`](./circuits/vk.json) |
 | Circuit artifacts | [`circuits/null_proof.circom`](./circuits/null_proof.circom), [`circuits/null_proof_final.zkey`](./circuits/null_proof_final.zkey), [`circuits/null_proof_js/null_proof.wasm`](./circuits/null_proof_js/null_proof.wasm) |
 | Public IDL | [`idl/paradox.json`](./idl/paradox.json) |
@@ -71,6 +88,7 @@ npm install @dark-null/protocol @coral-xyz/anchor @solana/web3.js
 - a real Groth16 verifier path is published in the root
 - the root circuit, zkey, wasm, and vk are internally consistent
 - the root proof flow is reproducible locally with `npm test`
+- the root devnet/localnet selection now resolves through one published config surface
 - the repo has a canonical public devnet path instead of a placeholder root plus side branch
 
 ## What This Repo Does Not Prove
@@ -83,10 +101,11 @@ npm install @dark-null/protocol @coral-xyz/anchor @solana/web3.js
 ## Verification Flow
 
 1. Run `sh scripts/bootstrap.sh`.
-2. Read [`MANIFEST.json`](./MANIFEST.json) and [`docs/PROGRAM_IDS.md`](./docs/PROGRAM_IDS.md).
-3. Run `npm test`.
-4. Run `cargo test --offline`.
-5. If Python client dependencies are installed, run `npm run test:python:unit`.
+2. Run `npm run config:devnet` or `npm run config:localnet`.
+3. Read [`MANIFEST.json`](./MANIFEST.json), [`NETWORKS.json`](./NETWORKS.json), and [`docs/PROGRAM_IDS.md`](./docs/PROGRAM_IDS.md).
+4. Run `npm test`.
+5. Run `cargo test --offline`.
+6. If Python client dependencies are installed, run `npm run test:python:unit`.
 
 ## For Integrators and Agent Builders
 

client/README.md

@@ -14,6 +14,7 @@ This directory now carries a **canonical root helper client**, not a toy-root tr
 ## What `dark_client.py` Matches
 
 - program ID `2stas3cZYnBiWpndcTXQDGLXwfQ7kjEYYrW52DsUAcxF`
+- canonical network config from [`../NETWORKS.json`](../NETWORKS.json)
 - canonical root circuit artifacts under [`../circuits`](../circuits)
 - canonical root IDL semantics from [`../idl/paradox.json`](../idl/paradox.json)
 

client/dark_client.py

@@ -11,11 +11,14 @@
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
 CIRCUITS_DIR = REPO_ROOT / "circuits"
+NETWORKS_PATH = REPO_ROOT / "NETWORKS.json"
 DEFAULT_ZKEY_PATH = CIRCUITS_DIR / "null_proof_final.zkey"
 DEFAULT_WASM_PATH = CIRCUITS_DIR / "null_proof_js" / "null_proof.wasm"
 DEFAULT_VK_PATH = CIRCUITS_DIR / "vk.json"
+NETWORKS = json.loads(NETWORKS_PATH.read_text(encoding="utf8"))
+SUPPORTED_NETWORKS = NETWORKS["supportedNetworks"]
 
-PROGRAM_ID = Pubkey.from_string("2stas3cZYnBiWpndcTXQDGLXwfQ7kjEYYrW52DsUAcxF")
+PROGRAM_ID = Pubkey.from_string(NETWORKS["canonicalProgramId"])
 TOKEN_PROGRAM_ID = Pubkey.from_string("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")
 SYSTEM_PROGRAM_ID = Pubkey.from_string("11111111111111111111111111111111")
 VAULT_SEED = b"merkle_vault"
@@ -47,14 +50,43 @@ def coerce_bytes32(value) -> bytes:
     return raw
 
 
+def list_supported_networks():
+    return list(SUPPORTED_NETWORKS.keys())
+
+
+def resolve_network_config(network=None, rpc_url=None, wallet_path=None):
+    selected_network = network or os.environ.get("DARK_NULL_NETWORK") or NETWORKS["defaultNetwork"]
+    definition = SUPPORTED_NETWORKS.get(selected_network)
+    if definition is None:
+        known_networks = ", ".join(list_supported_networks())
+        raise ValueError(f"Unknown network: {selected_network}. Expected one of {known_networks}")
+
+    return {
+        "network": selected_network,
+        "label": definition["label"],
+        "cluster": definition["cluster"],
+        "anchor_cluster": definition["anchorCluster"],
+        "rpc_url": rpc_url or os.environ.get("DARK_NULL_RPC_URL") or definition["rpcUrl"],
+        "ws_url": definition.get("wsUrl"),
+        "wallet_path": wallet_path or os.environ.get("DARK_NULL_WALLET_PATH"),
+        "program_id": NETWORKS["canonicalProgramId"],
+        "manifest_key": definition["manifestKey"],
+    }
+
+
 class DarkClient:
-    def __init__(self, snarkjs_path=None, zkey_path=None, wasm_path=None, vk_path=None):
+    def __init__(self, snarkjs_path=None, zkey_path=None, wasm_path=None, vk_path=None, network=None, rpc_url=None, wallet_path=None):
+        self.network_config = resolve_network_config(network=network, rpc_url=rpc_url, wallet_path=wallet_path)
+        self.program_id = Pubkey.from_string(self.network_config["program_id"])
+        self.rpc_url = self.network_config["rpc_url"]
+        self.wallet_path = self.network_config["wallet_path"]
         self.snarkjs_path = snarkjs_path or os.environ.get("DARK_NULL_SNARKJS")
         self.zkey_path = Path(zkey_path) if zkey_path else Path(os.environ.get("DARK_NULL_ZKEY_PATH", DEFAULT_ZKEY_PATH))
         self.wasm_path = Path(wasm_path) if wasm_path else Path(os.environ.get("DARK_NULL_WASM_PATH", DEFAULT_WASM_PATH))
         self.vk_path = Path(vk_path) if vk_path else Path(os.environ.get("DARK_NULL_VK_PATH", DEFAULT_VK_PATH))
 
-    def derive_vault_pda(self, program_id=PROGRAM_ID):
+    def derive_vault_pda(self, program_id=None):
+        program_id = program_id or self.program_id
         return Pubkey.find_program_address([VAULT_SEED], program_id)[0]
 
     def build_proof_inputs(self, amount, blinding, nullifier_secret, root, path_elements, path_indices):
@@ -137,7 +169,8 @@ def verify_proof_locally(self, proof, public_signals):
             )
             return True
 
-    def build_initialize_instruction(self, user, vault=None, program_id=PROGRAM_ID):
+    def build_initialize_instruction(self, user, vault=None, program_id=None):
+        program_id = program_id or self.program_id
         vault = vault or self.derive_vault_pda(program_id)
         return Instruction(
             program_id,
@@ -149,7 +182,8 @@ def build_initialize_instruction(self, user, vault=None, program_id=PROGRAM_ID):
             ],
         )
 
-    def build_update_root_instruction(self, signer, new_root, vault=None, program_id=PROGRAM_ID):
+    def build_update_root_instruction(self, signer, new_root, vault=None, program_id=None):
+        program_id = program_id or self.program_id
         vault = vault or self.derive_vault_pda(program_id)
         data = bytearray(anchor_discriminator("update_root"))
         data.extend(coerce_bytes32(new_root))
@@ -173,8 +207,9 @@ def build_deposit_wsol_and_whisper_instruction(
         ephemeral_pubkey,
         view_tag,
         vault=None,
-        program_id=PROGRAM_ID,
+        program_id=None,
     ):
+        program_id = program_id or self.program_id
         vault = vault or self.derive_vault_pda(program_id)
         data = bytearray(anchor_discriminator("deposit_wsol_and_whisper"))
         data.extend(int(amount).to_bytes(8, "little"))
@@ -203,8 +238,9 @@ def build_prepare_phantom_withdraw_instruction(
         amount,
         proof_bundle,
         vault=None,
-        program_id=PROGRAM_ID,
+        program_id=None,
     ):
+        program_id = program_id or self.program_id
         vault = vault or self.derive_vault_pda(program_id)
         proof_a = bytes(proof_bundle["proof_a"])
         proof_b = bytes(proof_bundle["proof_b"])
@@ -253,8 +289,9 @@ def build_burn_and_whisper_instruction(
         ephemeral_pubkey,
         view_tag,
         vault=None,
-        program_id=PROGRAM_ID,
+        program_id=None,
     ):
+        program_id = program_id or self.program_id
         vault = vault or self.derive_vault_pda(program_id)
         data = bytearray(anchor_discriminator("burn_and_whisper"))
         data.extend(int(amount).to_bytes(8, "little"))

client/test_dark_protocol.py

@@ -11,7 +11,10 @@
     DEFAULT_WASM_PATH,
     DEFAULT_ZKEY_PATH,
     DarkClient,
+    PROGRAM_ID,
     anchor_discriminator,
+    list_supported_networks,
+    resolve_network_config,
 )
 from nebula_core import NebulaCore
 
@@ -58,6 +61,16 @@ class TestDarkClient:
     def setup_method(self):
         self.client = DarkClient()
 
+    def test_network_config_matches_canonical_root(self):
+        devnet = resolve_network_config("devnet")
+        localnet = resolve_network_config("localnet")
+
+        assert list_supported_networks() == ["devnet", "localnet"]
+        assert devnet["program_id"] == str(PROGRAM_ID)
+        assert devnet["rpc_url"] == "https://api.devnet.solana.com"
+        assert localnet["rpc_url"] == "http://127.0.0.1:8899"
+        assert self.client.program_id == PROGRAM_ID
+
     def test_build_proof_inputs_requires_seven_level_path(self):
         inputs = self.client.build_proof_inputs(
             amount=1_000_000,

docs/getting-started.md

@@ -13,32 +13,50 @@ That installs npm dependencies and runs the public checks.
 ## 2. Read the Canonical Binding First
 
 - [`../MANIFEST.json`](../MANIFEST.json)
+- [`../NETWORKS.json`](../NETWORKS.json)
 - [`PROGRAM_IDS.md`](./PROGRAM_IDS.md)
 
-Those two files tell you which program ID and artifact set the root actually uses.
+Those three files tell you which program ID, network map, and artifact set the root actually uses.
 
-## 3. Review the Root Program
+## 3. Resolve the Canonical Network Config
+
+```bash
+npm run config:devnet
+```
+
+If you are working against a local validator instead:
+
+```bash
+npm run config:localnet
+```
+
+## 4. Review the Root Program
 
 - [`../Anchor.toml`](../Anchor.toml)
 - [`../Cargo.toml`](../Cargo.toml)
 - [`../src/lib.rs`](../src/lib.rs)
 - [`../src/verifying_key.rs`](../src/verifying_key.rs)
 
-## 4. Review the Root Circuit Artifacts
+## 5. Review the Root Circuit Artifacts
 
 - [`../circuits/null_proof.circom`](../circuits/null_proof.circom)
 - [`../circuits/null_proof_final.zkey`](../circuits/null_proof_final.zkey)
 - [`../circuits/null_proof_js/null_proof.wasm`](../circuits/null_proof_js/null_proof.wasm)
 - [`../circuits/vk.json`](../circuits/vk.json)
 
-## 5. Use the npm SDK
+## 6. Use the npm SDK
 
 ```bash
 npm install @dark-null/protocol @coral-xyz/anchor @solana/web3.js
 ```
 
 ```typescript
-import { createAnchorProgram, getInstructionDefinition, resolveProgramId } from "@dark-null/protocol";
+import {
+  createAnchorProgram,
+  getInstructionDefinition,
+  resolveNetworkConfig,
+  resolveProgramId,
+} from "@dark-null/protocol";
 
 const program = await createAnchorProgram({
   anchor,
@@ -48,9 +66,10 @@ const program = await createAnchorProgram({
 
 const withdraw = getInstructionDefinition("prepare_phantom_withdraw");
 const programId = resolveProgramId("canonicalDevnet");
+const network = resolveNetworkConfig("devnet");
 ```
 
-## 6. Or Use the Public IDL Directly
+## 7. Or Use the Public IDL Directly
 
 ```typescript
 import { AnchorProvider, Idl, Program } from "@coral-xyz/anchor";
@@ -66,15 +85,15 @@ const program = new Program(
 );
 ```
 
-## 7. Run the Canonical Checks
+## 8. Run the Canonical Checks
 
 ```bash
 npm test
 npm run test:python:unit
 cargo test --offline
 ```
 
-## 8. Keep the Boundary Straight
+## 9. Keep the Boundary Straight
 
 - the root repo now has a real Groth16 verifier path and a canonical circuit bundle
 - the repo still does **not** prove a completed audit or a mainnet release

historical/null-mint/MANIFEST.json

@@ -26,13 +26,13 @@
     },
     {
       "path": "programs/paradox/src/lib.rs",
-      "sha256": "555362463b40d827a5d4de89b9e9e334c695b8865e7c9dbd8d0dcd82509041fc",
-      "size": 11542
+      "sha256": "c2c0fed68e54be04565517f3fbabe195b3b7a20acd339ff434af34aa1c257659",
+      "size": 11485
     },
     {
       "path": "programs/paradox/Cargo.toml",
-      "sha256": "a96355eae0ea46f83fcdd91c8593c2768508794983a14b6d54eb61daab563a71",
-      "size": 811
+      "sha256": "dc3d6172b15d4545590e5838702573fbfdc845cbdff5a1024a7fbf768eae4b05",
+      "size": 1022
     },
     {
       "path": "idl/paradox.json",