DD 69: Exchange Base URL Completion

23.70. DD 69: Exchange Base URL Completion#

Design status:

Accepted

Implementation status:

Implemented

DD shepherd:

TBD

Historical contributors:

Vlada Svirsh

First published:

2025-09-16

Last substantive change:

2025-11-22

Implementation evidence:

taler-typescript-core (2025-09-15; 2026-07-31)

Normative references:

wallet/wallet-core.md (exchange-base-URL completion operation)

Upstream follow-up:

Regenerate/fix wallet/wallet-core.md: its operation comment incorrectly describes coin refresh, and the generated request/result omit progressToken/suggestions that are present in the implementation. Do not treat the generated text as the authoritative completion algorithm until corrected.

23.70.1. Summary#

Define the request, which turns user-provided input (like exchange.example.com or just example.com) into a canonical, validated HTTPS exchange base URL. Validation requires that GET <base>/config returns a valid ExchangeVersionResponse object.

23.70.2. Motivation#

Users may provide incomplete or ambiguous input when configuring an exchange. For example, they may type just example.com instead of the full https://exchange.example.com/. The system must normalize, complete, and validate such inputs to ensure that only valid exchanges are accepted. This improves robustness and user experience while preventing misconfiguration.

23.70.3. Requirements#

  • Accepts a single string from the user (host or URL).

  • Supports inputs like exchange.example.com, example.com, or https://exchange.example.com/.

  • Always enforces HTTPS.

  • Base URL must end with a single / and omit ports.

  • Must validate by requesting GET <base>/config and checking for a valid ExchangeVersionResponse object.

  • Must support a local list of trusted exchanges for resolution of ambiguous inputs or typos (70% Levenshtein similarity).

23.70.4. Proposed Solution#

Process:

  1. Clean up locally

    • Trim spaces and lowercase scheme/host.

    • Default scheme to https:// if missing.

    • Reject non-HTTPS schemes.

    • Remove explicit port and strip query/fragment.

    • Ensure a trailing slash.

  2. Candidate base URLs

    • If input host starts with exchange., use directly.

    • If input is a bare domain, construct https://exchange.<domain>/ as a second candidate.

  3. Network check (keys)

    • For each candidate, perform GET <base>/config.

    • Follow HTTPS redirects within limits.

    • Accept if the final response is a valid ExchangeVersionResponse.

    • Otherwise, treat as protocol failure.

  4. List of trusted exchanges

    • Check the input against a local list of trusted exchanges.

    • Match by exact part match of hostname and fuzzy match (≥70% Levenshtein).

    • Return bad-exchange and, if trusted entries are found, return them in the suggestions array.

23.70.4.1. Outcome values#

  • ok — Keys validated; return canonical base.

  • bad-syntax — Input invalid (e.g., non-HTTPS scheme).

  • bad-network — Network failure (DNS/connect/TLS/timeout).

  • bad-exchange — Response received but not a valid exchange.

23.70.4.2. Canonicalization of output#

  • Always return in the form https://<lowercased-host>/.

  • No ports, queries, or fragments.

23.70.4.3. Examples#

  • exchange.example.com -> ok, returns https://exchange.example.com/.

  • example.com -> try https://example.com/config first. If not valid, then try https://exchange.example.com/config. If that works → ok, returns https://exchange.example.com/.

  • https://exchange.example.com/ with /config returning something other than a valid ExchangeVersionResponse object -> bad-exchange.

  • http://exchange.example.com -> bad-syntax (HTTPS required).

  • example.com where /config redirects to https://api.example.com/config and returns valid data -> ok, returns https://api.example.com/.

  • DNS failure -> bad-network.

23.70.5. Definition of Done#

  • [x] Request implemented and documented.

  • Unit tests cover: - valid inputs, - redirects, - trusted exchange fallback, - failure cases (syntax, network, protocol).

  • [x] Feature is enabled by default.

23.70.6. Alternatives#

23.70.7. Drawbacks#

  • Requires maintaining a local list of trusted exchanges and fuzzy matching.

  • Adds network overhead (GET /config probes).

  • Possible user confusion if multiple trusted exchanges are suggested as fuzzy matches.

23.70.8. Discussion / Q&A#

(To be filled in with results from discussions on mailing lists / personal communication.)