fix(config): enforce chain.joinbase.ai as public registry default

Codify Compose install templates and docs so public registry/weights stay on
https://chain.joinbase.ai, keep validator --master-url operator-explicit (no
hard-coded public IP defaults), and guard the contract with unit assertions.

Author: echobt

deploy/compose/config/master.compose.yaml

@@ -20,6 +20,7 @@ network:
       stake: 1000.0
 
 master:
+  # Public chain/registry control plane for the shipping public network.
   registry_url: https://chain.joinbase.ai
   proxy_host: 0.0.0.0
   proxy_port: 8081
@@ -32,6 +33,7 @@ master:
   orchestration_interval_seconds: 30
 
 validator:
+  # Public network default; do not substitute ad-hoc public IP hosts here.
   registry_url: https://chain.joinbase.ai
   registry_retry_seconds: 15
   weights_url: null

deploy/compose/install-master.sh

@@ -185,6 +185,7 @@ network:
       stake: 1000.0
 
 master:
+  # Public chain/registry control plane (not an operator master IP inventory).
   registry_url: https://chain.joinbase.ai
   proxy_host: 0.0.0.0
   proxy_port: 8081
@@ -198,6 +199,7 @@ master:
   orchestration_interval_seconds: 30
 
 validator:
+  # Public network registry/weights default; Validators attach via --master-url.
   registry_url: https://chain.joinbase.ai
   registry_retry_seconds: 15
   weights_url: null

deploy/compose/install-validator.sh

@@ -114,6 +114,9 @@ if [[ -z "${MASTER_URL}" ]]; then
 fi
 
 # Reject empty or clearly invalid master URLs early (VAL-SDK-086).
+# master_url is the operator's master coordination root (their running master
+# API). It is never defaulted to a public IP inventory. Public chain/registry
+# docs and Settings defaults remain https://chain.joinbase.ai.
 case "${MASTER_URL}" in
   http://*|https://*) ;;
   *)

docs/compose.md

@@ -59,6 +59,19 @@ Every deployable first-party reference is immutable: `repository@sha256:<64 hex>
 
 Base and Prism do **not** launch evaluator containers. Prism runs in `PRISM_COMBINED_MODE=true` and verifies/ingests external results. External long-lived TEE runtimes are never lifecycle-managed by this Compose project.
 
+## Public chain and master URL
+
+- Public chain/registry control-plane URL: `https://chain.joinbase.ai`
+  (master `registry_url` and validator `registry_url` / default weights resolution
+  for the public network).
+- Validator coordination uses an **explicit** operator master URL
+  (`install-validator.sh --master-url` / `validator.agent.master_url`). That is
+  the operator's running master API (often loopback in disposable setups), not a
+  hardcoded public IP host inventory.
+- Docker Compose installers must not invent alternate public master IP defaults.
+  Historical Swarm advertise addresses under `deploy/swarm/` are unsupported for
+  greenfield Compose installs.
+
 ## Validator project
 
 Entrypoint: `deploy/compose/docker-compose.validator.yml`

docs/operations/validator.md

@@ -77,14 +77,25 @@ On the Compose path the process is packaged as the `validator` service from
 
 ```yaml
 validator:
+  # Public network defaults (Settings / examples); resolved_weights_url falls
+  # back to registry_url when weights_url is null.
+  registry_url: https://chain.joinbase.ai
+  weights_url: null
   agent:
-    master_url: https://chain.joinbase.ai
+    # Operator master coordination root (install-validator --master-url).
+    # This is *not* the public chain URL. Examples for a local master:
+    master_url: http://127.0.0.1:3180
     capabilities: ["cpu"]
     version: "0.1.0"
     heartbeat_interval_seconds: 60
     poll_interval_seconds: 5.0
 ```
 
+Public registry and published weights documentation uses
+`https://chain.joinbase.ai` (for example `GET /v1/weights/latest` there).
+`install-validator.sh --master-url` must point at the operator master API that
+owns assignments; it never invents a hardcoded public IP as the master default.
+
 There is no master LLM gateway route and no per-assignment `BASE_LLM_GATEWAY_URL`
 / `BASE_GATEWAY_TOKEN` contract in the shipping target path.
 

docs/validator/README.md

@@ -15,6 +15,12 @@ The default public weights endpoint is:
 https://chain.joinbase.ai/v1/weights/latest
 ```
 
+Settings defaults for `registry_url` / resolved weights on the public network also
+use `https://chain.joinbase.ai`. Installer `--master-url` is the **operator master
+coordination root** (required, never invented as a hard-coded public IP). Local
+examples often use `http://127.0.0.1:3180`; public operators point both registry
+and master at the public control plane when that is the live master.
+
 ## Compute Requirements
 
 | Validator profile | Compute |

tests/unit/test_config_template_security.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import re
 import stat
 import subprocess
 from pathlib import Path
@@ -58,9 +59,17 @@ def test_registry_url_defaults_and_examples_use_chain_endpoint() -> None:
     validator_example = yaml.safe_load(
         (root / "config" / "validator.example.yaml").read_text(encoding="utf-8")
     )
+    master_compose = yaml.safe_load(
+        (root / "deploy" / "compose" / "config" / "master.compose.yaml").read_text(
+            encoding="utf-8"
+        )
+    )
 
     assert master_example["master"]["registry_url"] == expected
+    assert master_example["validator"]["registry_url"] == expected
     assert validator_example["validator"]["registry_url"] == expected
+    assert master_compose["master"]["registry_url"] == expected
+    assert master_compose["validator"]["registry_url"] == expected
     assert ValidatorSettings().weights_url is None
     assert ValidatorSettings().resolved_weights_url == expected
     assert (
@@ -79,19 +88,94 @@ def test_registry_url_defaults_and_examples_use_chain_endpoint() -> None:
     assert ValidatorSettings().weights_retries == 3
     assert ValidatorSettings().weights_freshness_seconds == 720
     assert validator_example["validator"]["weights_url"] is None
+    assert master_compose["validator"]["weights_url"] is None
     assert validator_example["validator"]["weights_interval_seconds"] == 360
     assert validator_example["validator"]["weights_timeout_seconds"] == 15.0
     assert validator_example["validator"]["weights_retries"] == 3
     assert validator_example["validator"]["weights_freshness_seconds"] == 720
 
 
+def test_compose_shipping_defaults_pin_public_chain_joinbase_url() -> None:
+    """Compose install/templates must keep public registry on chain.joinbase.ai.
+
+    Operator ``--master-url`` stays an explicit coordination root and must not be
+    invented as a hard-coded public IP default. Public registry/weights defaults
+    remain ``https://chain.joinbase.ai``.
+    """
+    root = Path(__file__).resolve().parents[2]
+    expected = "https://chain.joinbase.ai"
+    retired_public_hosts = (
+        "86.38.238.235",
+        "51.83.112.164",
+        "88.216.198.199",
+    )
+
+    install_master = (root / "deploy" / "compose" / "install-master.sh").read_text(
+        encoding="utf-8"
+    )
+    install_validator = (
+        root / "deploy" / "compose" / "install-validator.sh"
+    ).read_text(encoding="utf-8")
+    master_compose = (
+        root / "deploy" / "compose" / "config" / "master.compose.yaml"
+    ).read_text(encoding="utf-8")
+    master_example = (root / "config" / "master.example.yaml").read_text(
+        encoding="utf-8"
+    )
+    validator_example = (root / "config" / "validator.example.yaml").read_text(
+        encoding="utf-8"
+    )
+    validator_docs = (root / "docs" / "validator" / "README.md").read_text(
+        encoding="utf-8"
+    )
+    ops_validator_docs = (root / "docs" / "operations" / "validator.md").read_text(
+        encoding="utf-8"
+    )
+
+    for shipping in (
+        install_master,
+        master_compose,
+        master_example,
+        validator_example,
+    ):
+        assert f"registry_url: {expected}" in shipping
+        for host in retired_public_hosts:
+            assert host not in shipping
+
+    # Master install renders both master + validator registry defaults to public chain.
+    assert install_master.count(f"registry_url: {expected}") >= 2
+    assert "weights_url: null" in install_master
+
+    # Validator install requires an explicit operator master URL and never invents
+    # a hard-coded public IP master default. registry/weights may follow that
+    # operator root for a private master, but public docs keep the chain host.
+    assert "--master-url" in install_validator
+    assert "VALIDATOR_MASTER_URL" in install_validator
+    assert "validator install requires --master-url" in install_validator
+    for host in retired_public_hosts:
+        assert host not in install_validator
+    # No default IP master for empty --master-url.
+    assert (
+        re.search(r'MASTER_URL="\$\{VALIDATOR_MASTER_URL:-[^"]+\}"', install_validator)
+        is None
+    )
+
+    assert expected in validator_docs
+    assert f"{expected}/v1/weights/latest" in validator_docs
+    assert expected in ops_validator_docs
+    # master_url is the operator coordination root, not the public chain URL.
+    assert "master_url: https://chain.joinbase.ai" not in ops_validator_docs
+
+
 def test_registry_facing_defaults_docs_and_examples_do_not_use_rpc_endpoint() -> None:
     root = Path(__file__).resolve().parents[2]
     registry_facing_files = [
         root / "src" / "base" / "config" / "settings.py",
         root / "config" / "master.example.yaml",
         root / "config" / "validator.example.yaml",
         root / "docs" / "validator" / "README.md",
+        root / "deploy" / "compose" / "config" / "master.compose.yaml",
+        root / "deploy" / "compose" / "install-master.sh",
         root / "deploy" / "swarm" / "master.yaml",
     ]