fix(price): make legacy bitcoin_price_api_url optional + unify live Yadio URL

Human-review follow-ups on Phase 1 (spec §10.1 backward compatibility):

- types.rs: add #[serde(default)] to bitcoin_price_api_url so a settings.toml
  that has migrated to a [price] block may omit the deprecated key instead of
  failing deserialization and aborting startup (arkanoider, codaMW). Field
  stays — util.rs and install_price_manager() still read it until Phase 4/5.
- settings.tpl.toml: document the key's full lifecycle (now optional, still
  read by the live /convert path until Phase 4, removed in Phase 5).
- util.rs: route the live /convert + /currencies path through a yadio_base_url()
  helper that prefers [price.providers.yadio].url when a [price] block is
  present, falling back to the legacy key. Stops the live and cached paths
  silently hitting different Yadio bases when only the new key is customised.
- config.rs / manager.rs: point the three [price] validation errors at
  docs/PRICE_PROVIDERS.md §7 and make the unimplemented-provider message
  actionable.
- tests: prove a [mostro] block without bitcoin_price_api_url deserializes to
  the default URL, and that legacy synthesis is identical whether the key is
  present-at-default or omitted.

Does not touch price/aggregate.rs, price/store.rs, or the scheduler tick
(§5.4 extension-contract invariant holds).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: grunch

settings.tpl.toml

@@ -56,8 +56,15 @@ pow = 0
 publish_mostro_info_interval = 300
 # Bitcoin price API base URL.
 # DEPRECATED: prefer `[price.providers.yadio].url` in the new multi-source
-# `[price]` block below. Still honoured for backward compatibility when
-# `[price]` is absent (see docs/PRICE_PROVIDERS.md §10.1).
+# `[price]` block below (see docs/PRICE_PROVIDERS.md §10.1). Lifecycle:
+#  (a) Now OPTIONAL — once you configure a `[price]` block you may delete this
+#      key. When it is absent AND `[price]` is also absent, the default
+#      "https://api.yadio.io" is used for the legacy single-source synthesis.
+#  (b) Still read by the live market-quote path (/convert) until Phase 4. To
+#      avoid the live and cached paths hitting different Yadio URLs, the live
+#      path prefers `[price.providers.yadio].url` when a `[price]` block is
+#      present and only falls back to this key otherwise.
+#  (c) Fully removed in Phase 5.
 bitcoin_price_api_url = "https://api.yadio.io"
 # Fiat currencies accepted for orders - leave empty [] to accept all fiat currencies
 fiat_currencies_accepted = ['USD', 'EUR', 'ARS', 'CUP']

src/config/mod.rs

@@ -233,4 +233,72 @@ mod tests {
         );
         assert_eq!(mostro_settings.mostro.max_orders_per_response, 10);
     }
+
+    // Same as MOSTRO_SETTINGS but with `bitcoin_price_api_url` omitted — the
+    // shape an operator who has migrated to a `[price]` block and deleted the
+    // deprecated key would have (spec §10.1).
+    const MOSTRO_SETTINGS_NO_PRICE_URL: &str = r#"[mostro]
+                                            fee = 0
+                                            max_routing_fee = 0.002
+                                            max_order_amount = 1000000
+                                            min_payment_amount = 100
+                                            expiration_hours = 24
+                                            max_expiration_days = 15
+                                            expiration_seconds = 900
+                                            user_rates_sent_interval_seconds = 3600
+                                            publish_relays_interval = 60
+                                            pow = 0
+                                            publish_mostro_info_interval = 300
+                                            fiat_currencies_accepted = ['USD', 'EUR', 'ARS', 'CUP']
+                                            max_orders_per_response = 10
+                                            dev_fee_percentage = 0.30"#;
+
+    #[test]
+    fn test_mostro_settings_without_bitcoin_price_api_url_defaults() {
+        // A settings.toml that omits the deprecated key must still
+        // deserialize (it is `#[serde(default)]`), falling back to the same
+        // URL the `Default` impl uses.
+        let parsed: StubSettingsMostro =
+            toml::from_str(MOSTRO_SETTINGS_NO_PRICE_URL).expect("must deserialize without the key");
+        assert_eq!(
+            parsed.mostro.bitcoin_price_api_url, "https://api.yadio.io",
+            "omitted legacy key must fall back to the default URL"
+        );
+    }
+
+    #[test]
+    fn test_legacy_synthesis_same_whether_key_present_or_defaulted() {
+        // Legacy synthesis (`[price]` absent) must produce the same
+        // single-yadio config whether the deprecated key was present at its
+        // default value or omitted entirely (spec §10.1 byte-for-byte
+        // compatibility).
+        let omitted: StubSettingsMostro =
+            toml::from_str(MOSTRO_SETTINGS_NO_PRICE_URL).expect("deserialize (omitted)");
+        let present: StubSettingsMostro =
+            toml::from_str(MOSTRO_SETTINGS).expect("deserialize (present)");
+
+        let synth = |m: &MostroSettings| {
+            crate::price::synthesise_legacy_price_settings(
+                &m.bitcoin_price_api_url,
+                m.exchange_rates_update_interval_seconds,
+                m.publish_exchange_rates_to_nostr,
+            )
+        };
+        let from_omitted = synth(&omitted.mostro);
+        let from_present = synth(&present.mostro);
+
+        // Exactly one provider (yadio) in both, with the default URL.
+        for cfg in [&from_omitted, &from_present] {
+            assert_eq!(cfg.providers.len(), 1);
+            let yadio = cfg.providers.get("yadio").expect("yadio provider present");
+            assert!(yadio.enabled);
+            assert_eq!(yadio.url, "https://api.yadio.io");
+        }
+        // And the synthesised cadence / publish flag match across the two.
+        assert_eq!(
+            from_omitted.update_interval_seconds,
+            from_present.update_interval_seconds
+        );
+        assert_eq!(from_omitted.publish_to_nostr, from_present.publish_to_nostr);
+    }
 }

src/config/types.rs

@@ -340,7 +340,15 @@ pub struct MostroSettings {
     pub pow: u8,
     /// Publish mostro info interval
     pub publish_mostro_info_interval: u32,
-    /// Bitcoin price API base URL
+    /// Bitcoin price API base URL.
+    ///
+    /// DEPRECATED (spec §10.1): superseded by `[price.providers.yadio].url`.
+    /// `#[serde(default)]` so a `settings.toml` that has migrated to a
+    /// `[price]` block may omit this key entirely without failing
+    /// deserialization. Still read by the live `/convert` path
+    /// (`src/util.rs`) and by `install_price_manager()` legacy synthesis when
+    /// `[price]` is absent, so the field itself stays until Phase 4/5.
+    #[serde(default = "default_bitcoin_price_api_url")]
     pub bitcoin_price_api_url: String,
     /// Fiat currencies accepted for orders (empty list accepts all)
     pub fiat_currencies_accepted: Vec<String>,
@@ -365,6 +373,12 @@ pub struct MostroSettings {
     pub exchange_rates_update_interval_seconds: u64,
 }
 
+fn default_bitcoin_price_api_url() -> String {
+    // Matches the `Default` impl below so an omitted legacy key and an
+    // explicit one behave identically for legacy synthesis (spec §10.1).
+    "https://api.yadio.io".to_string()
+}
+
 fn default_publish_exchange_rates() -> bool {
     true // Enable by default for censorship resistance
 }

src/price/config.rs

@@ -74,12 +74,14 @@ impl ProviderConfig {
     pub fn validate(&self, id: &str) -> Result<(), String> {
         if self.only.is_some() && self.except.is_some() {
             return Err(format!(
-                "price provider '{id}': `only` and `except` are mutually exclusive"
+                "price provider '{id}': `only` and `except` are mutually exclusive \
+                 (see docs/PRICE_PROVIDERS.md §7)"
             ));
         }
         if self.enabled && self.url.trim().is_empty() {
             return Err(format!(
-                "price provider '{id}': enabled provider must have a non-empty `url`"
+                "price provider '{id}': enabled provider must have a non-empty `url` \
+                 (see docs/PRICE_PROVIDERS.md §7)"
             ));
         }
         Ok(())

src/price/manager.rs

@@ -453,7 +453,9 @@ fn build_provider(id: ProviderId, cfg: &ProviderConfig) -> Result<Box<dyn PriceP
         | ProviderId::CurrencyApi
         | ProviderId::Blockchain
         | ProviderId::ElToque => Err(format!(
-            "price: provider `{id}` is configured but not yet implemented in this release"
+            "price: provider `{id}` is configured (enabled) but not yet implemented in \
+             this release — disable it or remove it from `[price.providers]` \
+             (see docs/PRICE_PROVIDERS.md §7)"
         )),
     }
 }

src/util.rs

@@ -36,13 +36,37 @@ const MAX_RETRY: u16 = 4;
 // Redefined for convenience
 type OrderKind = mostro_core::order::Kind;
 
+/// Resolve the Yadio base URL for the live market-quote path (`/convert`,
+/// `/currencies`).
+///
+/// Phase 1 transition (spec §10.1): the cached aggregate path reads
+/// `[price.providers.yadio].url`, but this live path historically read the
+/// legacy `[mostro].bitcoin_price_api_url`. If an operator customises only
+/// the new key, the two paths would silently hit different Yadio bases.
+/// Prefer the configured Yadio provider URL when a `[price]` block is present
+/// (falling back to the legacy key otherwise). Phase 4 removes this live HTTP
+/// path entirely, at which point the legacy key only feeds legacy synthesis.
+fn yadio_base_url() -> String {
+    if let Some(price) = Settings::get_price() {
+        if let Some(yadio) = price
+            .providers
+            .get(&crate::price::ProviderId::Yadio.to_string())
+        {
+            let url = yadio.url.trim();
+            if !url.is_empty() {
+                return url.to_string();
+            }
+        }
+    }
+    Settings::get_mostro().bitcoin_price_api_url.clone()
+}
+
 pub async fn retries_yadio_request(
     req_string: &str,
     fiat_code: &str,
 ) -> Result<(Option<reqwest::Response>, bool), MostroError> {
     // Get Fiat list and check if currency exchange is available
-    let mostro_settings = Settings::get_mostro();
-    let api_req_string = format!("{}/currencies", mostro_settings.bitcoin_price_api_url);
+    let api_req_string = format!("{}/currencies", yadio_base_url());
     let fiat_list_check = HTTP_CLIENT
         .get(api_req_string)
         .send()
@@ -78,10 +102,11 @@ pub async fn get_market_quote(
     premium: i64,
 ) -> Result<i64, MostroError> {
     // Add here check for market price
-    let mostro_settings = Settings::get_mostro();
     let req_string = format!(
         "{}/convert/{}/{}/BTC",
-        mostro_settings.bitcoin_price_api_url, fiat_amount, fiat_code
+        yadio_base_url(),
+        fiat_amount,
+        fiat_code
     );
     info!("Requesting API price: {}", req_string);