Origin-based endpoints: configure just https://api.provable.com

Users now pass the bare API origin; the SDK detects the hosted Provable API by
host (api.provable.com) and derives every service path itself — reads at /v2,
delegated proving at /prove, hosted scanner at /scanner, JWT auth at /jwts —
all per-network. Any OTHER host (devnode, local, custom node) is treated as a
literal read base (no /v2) with NO hosted prover/scanner wired up, so nothing
breaks and there's no footgun. A legacy ".../v2" value is still accepted
(detected as Provable and rebuilt identically) — fully backward compatible.

- _client_common: DEFAULT_HOST -> bare origin; add PROVABLE_API_HOSTS +
  is_provable_host().
- network_client / async: _resolve_urls() maps host -> (read_host, origin,
  prover_default, scanner_default); prover/scanner default only on the hosted
  API, else None. Expose origin/prover_uri/scanner_uri. submit_proving_request
  returns a clear error when no prover is configured off the hosted API.
- facade: HTTPProvider url is now the origin; scanner_base() returns None off
  the hosted API and the facade raises an actionable error rather than pointing
  at a bogus /scanner.
- Roundtrip live test: filter scan on min_microcredits (avoid spending a
  zero-balance record -> invalid SNARK inputs) and shrink the mint to 10_000.
- e2e endpoint defaults -> bare origin. Devnode untouched (non-Provable ->
  literal base). Live DPS + RSS tests pass on testnet + mainnet.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: iamalwaysuncomfortable

sdk/python/aleo/_client_common.py

@@ -35,8 +35,20 @@ def __init__(self, message: str, status: int | None = None) -> None:
 
 
 FIVE_MINUTES_MS: int = 5 * 60 * 1000
-DEFAULT_HOST: str = "https://api.provable.com/v2"
+DEFAULT_HOST: str = "https://api.provable.com"
 DEFAULT_NETWORK: str = "mainnet"
+
+# The hosted Provable API splits its services across path prefixes off a single
+# origin (reads at /v2, delegated proving at /prove, hosted scanner at /scanner,
+# JWT auth at /jwts). We detect it by host so that EVERY other endpoint (devnode,
+# local, or any custom node) is treated as a literal read base — no /v2 magic,
+# and no prover/scanner wired up (those services only exist on the hosted API).
+PROVABLE_API_HOSTS: frozenset[str] = frozenset({"api.provable.com"})
+
+
+def is_provable_host(url: str) -> bool:
+    """True if *url* points at the hosted Provable API (api.provable.com)."""
+    return (urlparse(url).hostname or "").lower() in PROVABLE_API_HOSTS
 SDK_HEADERS: set[str] = {"x-aleo-sdk-version", "x-aleo-environment", "x-aleo-method"}
 
 

sdk/python/aleo/async_network_client.py

@@ -23,6 +23,7 @@
     DEFAULT_NETWORK,
     AleoNetworkError,
     AleoProvingError,
+    is_provable_host,
     jwt_expired,
     jwt_origin,
     make_default_headers,
@@ -83,19 +84,26 @@ def __init__(
                 "Install with: pip install aleo[async]"
             ) from None
 
-        self._base_url: str = host
         self._network: str = network
-        self._host: str = f"{host}/{network}"
+        # See AleoNetworkClient._resolve_urls: hosted Provable API → /v2 reads +
+        # /prove + /scanner off the origin; any other host → literal read base
+        # with no hosted prover/scanner.
+        read_host, origin, prover_default, scanner_default = self._resolve_urls(host)
+        self._origin: str = origin
+        self._base_url: str = origin  # compat alias (now the origin)
+        self._host: str = read_host
         self._has_custom_transport: bool = transport is not None
         self._transport: Any = transport
         self._account: Any = None
         self._verbose_errors: bool = True
         self.api_key: str | None = api_key
         self.consumer_id: str | None = consumer_id
         self.jwt_data: dict[str, Any] | None = jwt_data
-        self._prover_uri: str | None = f"{prover_uri}/{network}" if prover_uri else None
+        self._prover_uri: str | None = (
+            f"{prover_uri}/{network}" if prover_uri else prover_default
+        )
         self._record_scanner_uri: str | None = (
-            f"{record_scanner_uri}/{network}" if record_scanner_uri else None
+            f"{record_scanner_uri}/{network}" if record_scanner_uri else scanner_default
         )
 
         if self._has_custom_transport:
@@ -112,6 +120,28 @@ def __init__(
         else:
             self._client = httpx.AsyncClient()
 
+    def _resolve_urls(
+        self, host: str
+    ) -> tuple[str, str, str | None, str | None]:
+        """Resolve ``(read_host, origin, prover_default, scanner_default)`` for *host*.
+
+        Hosted Provable API → reads under ``/v2`` with the delegated prover
+        (``/prove``) and hosted scanner (``/scanner``) off the same origin; any
+        other host → literal read base with no hosted prover/scanner. (``/jwts``
+        and ``/consumers`` always live at the bare origin — handled in
+        :meth:`_refresh_jwt`, not here.) Mirrors ``AleoNetworkClient._resolve_urls``.
+        """
+        origin = jwt_origin(host)
+        network = self._network
+        if is_provable_host(host):
+            return (
+                f"{origin}/v2/{network}",
+                origin,
+                f"{origin}/prove/{network}",
+                f"{origin}/scanner/{network}",
+            )
+        return (f"{host.rstrip('/')}/{network}", origin, None, None)
+
     # ── Network module selection ──────────────────────────────────────────
 
     def _net(self) -> Any:
@@ -135,8 +165,12 @@ def _net(self) -> Any:
     # ── Mutators ──────────────────────────────────────────────────────────
 
     def set_host(self, host: str) -> None:
-        self._base_url = host
-        self._host = f"{host}/{self._network}"
+        read_host, origin, prover_default, scanner_default = self._resolve_urls(host)
+        self._origin = origin
+        self._base_url = origin
+        self._host = read_host
+        self._prover_uri = prover_default
+        self._record_scanner_uri = scanner_default
 
     def set_prover_uri(self, prover_uri: str) -> None:
         self._prover_uri = f"{prover_uri}/{self._network}"
@@ -150,6 +184,21 @@ def set_account(self, account: Any) -> None:
     def get_account(self) -> Any:
         return self._account
 
+    @property
+    def origin(self) -> str:
+        """The API origin (``scheme://host``) all services derive from."""
+        return self._origin
+
+    @property
+    def prover_uri(self) -> str | None:
+        """DPS prover base (``{origin}/prove/{network}`` on the hosted API), or None."""
+        return self._prover_uri
+
+    @property
+    def scanner_uri(self) -> str | None:
+        """Hosted-scanner base (``{origin}/scanner/{network}`` on the hosted API), or None."""
+        return self._record_scanner_uri
+
     def set_header(self, name: str, value: str) -> None:
         self.headers[name] = value
 
@@ -221,8 +270,7 @@ async def _do() -> Any:
     # ── JWT refresh ───────────────────────────────────────────────────────
 
     async def _refresh_jwt(self, api_key: str, consumer_id: str) -> dict[str, Any]:
-        origin = jwt_origin(self._base_url)
-        url = f"{origin}/jwts/{consumer_id}"
+        url = f"{self._origin}/jwts/{consumer_id}"
         hdrs = {
             **self._request_headers("refreshJwt"),
             "X-Provable-API-Key": api_key,
@@ -480,15 +528,22 @@ async def submit_proving_request_safe(
         consumer_id: str | None = None,
         jwt_data: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        # DPS is a Provable service at the API origin under the ``/prove``
-        # prefix, per network (e.g. https://api.provable.com/prove/testnet),
-        # sibling to /scanner — not the read node's /v2/{network} base. Handshake
-        # hits {base}/pubkey and {base}/prove/authorization. Explicit override wins.
-        prover_uri = (
-            url
-            or self._prover_uri
-            or f"{jwt_origin(self._base_url)}/prove/{self._network}"
-        )
+        # Prover base: {origin}/prove/{network} on the hosted API (set at
+        # construction). Off the hosted API there is no prover unless configured.
+        prover_uri = url or self._prover_uri
+        if not prover_uri:
+            return {
+                "ok": False,
+                "status": None,
+                "error": {
+                    "message": (
+                        "No delegated prover configured for host "
+                        f"{self._origin!r}. Delegated proving is available on the "
+                        "Provable API (api.provable.com); for another endpoint pass "
+                        "HTTPProvider(prover_uri=...)."
+                    )
+                },
+            }
         # Build auth headers, optionally forcing a fresh JWT mint. The prover and
         # the hosted scanner share ONE consumer, and the auth server keeps a
         # single active JWT per consumer — so a scanner JWT mint invalidates the

sdk/python/aleo/facade/async_client.py

@@ -231,12 +231,21 @@ def _build_scanner(self) -> Any:
         from ..async_record_scanner import AsyncRecordScanner
         from .provider import scanner_base
 
+        provider = self._client.provider
+        base = scanner_base(provider)
+        if base is None:
+            raise RuntimeError(
+                "The hosted record scanner is only available on the Provable API "
+                f"(api.provable.com); this client points at {provider.url!r}. "
+                "Assign your own scanner (aleo.records.scanner = AsyncRecordScanner(...)) "
+                "or a custom aleo.record_provider to scan against this endpoint."
+            )
         return AsyncRecordScanner(
-            scanner_base(self._client.provider),
-            network=self._client.provider.network,
-            api_key=self._client.provider.api_key,
-            consumer_id=getattr(self._client.provider, "consumer_id", None),
-            transport=getattr(self._client.provider, "_transport", None),
+            base,
+            network=provider.network,
+            api_key=provider.api_key,
+            consumer_id=getattr(provider, "consumer_id", None),
+            transport=getattr(provider, "_transport", None),
         )
 
     @property

sdk/python/aleo/facade/provider.py

@@ -10,24 +10,29 @@
 from urllib.parse import urlparse
 
 from ..network_client import AleoNetworkClient
-from .._client_common import DEFAULT_HOST, DEFAULT_NETWORK
+from .._client_common import DEFAULT_HOST, DEFAULT_NETWORK, is_provable_host
 
 # AsyncAleoNetworkClient imported lazily to avoid pulling httpx at import time.
 
 _VALID_NETWORKS = frozenset({"mainnet", "testnet"})
 
 
-def scanner_base(provider: "HTTPProvider") -> str:
-    """Derive the hosted record-scanner base from a provider's URL.
+def scanner_base(provider: "HTTPProvider") -> str | None:
+    """Derive the hosted record-scanner base from a provider's URL, or ``None``.
 
-    The scanner is a Provable *service* at the API origin under the ``/scanner``
-    prefix (sibling to ``/prove`` and ``/jwts``), so — like the prover — it is
-    derived from the endpoint origin, NOT the read node's ``/v2/{network}`` base.
-    The :class:`~aleo.record_scanner.RecordScanner` appends ``/{network}``, so we
-    return ``{scheme}://{host}/scanner`` (no network suffix). Users only ever
-    configure the one endpoint URL; reads, proving, and scanning all derive from
-    its origin.
+    The hosted scanner is a Provable *service* at the API origin under the
+    ``/scanner`` prefix (sibling to ``/prove`` and ``/jwts``), derived from the
+    origin — NOT the read node's ``/v2/{network}`` base.  The
+    :class:`~aleo.record_scanner.RecordScanner` appends ``/{network}``, so we
+    return ``{scheme}://{host}/scanner`` (no network suffix).
+
+    Returns ``None`` off the hosted Provable API: the hosted scanner does not
+    exist on devnode / local / custom nodes, so there is nothing to point at.
+    Callers that need scanning against such an endpoint assign their own
+    :class:`~aleo.record_scanner.RecordScanner` or ``RecordProvider``.
     """
+    if not is_provable_host(provider.url):
+        return None
     parsed = urlparse(provider.url)
     return f"{parsed.scheme}://{parsed.netloc}/scanner"
 
@@ -38,7 +43,12 @@ class HTTPProvider:
     Parameters
     ----------
     url:
-        Versioned API root, e.g. ``"https://api.provable.com/v2"``.
+        API origin, e.g. ``"https://api.provable.com"`` (the default).  For the
+        hosted Provable API the SDK adds the service prefixes itself — reads at
+        ``/v2``, delegated proving at ``/prove``, hosted scanner at ``/scanner``,
+        JWT auth at ``/jwts`` — so you never spell them out.  Any other host
+        (devnode, a local or custom node) is used as a literal read base, with no
+        hosted prover/scanner wired up.  A legacy ``".../v2"`` value still works.
     network:
         Network name — ``"mainnet"`` (default) or ``"testnet"``.
     api_key:

sdk/python/aleo/facade/records.py

@@ -80,8 +80,16 @@ def _build_scanner(self) -> Any:
         from .provider import scanner_base
 
         provider = self._client._provider
+        base = scanner_base(provider)
+        if base is None:
+            raise RuntimeError(
+                "The hosted record scanner is only available on the Provable API "
+                f"(api.provable.com); this client points at {provider.url!r}. "
+                "Assign your own scanner (aleo.records.scanner = RecordScanner(...)) "
+                "or a custom aleo.record_provider to scan against this endpoint."
+            )
         return RecordScanner(
-            scanner_base(provider),
+            base,
             network=provider.network,
             api_key=provider.api_key,
             consumer_id=getattr(provider, "consumer_id", None),