v0.2.11-pre.002-fix.001

crates/ksp-offchain-transport-lib/src/market_price_provider.rs

@@ -0,0 +1,408 @@
+// file: crates/ksp-offchain-transport-lib/src/market_price_provider.rs
+// version: 2
+
+/// Maximum UTF-8 byte length of one provider display name.
+pub const PRICE_PROVIDER_DISPLAY_NAME_MAX_BYTES: usize = 96;
+/// Maximum byte length of one opaque provider identifier.
+pub const PRICE_PROVIDER_ID_MAX_BYTES: usize = 64;
+
+/// Only price pair exposed by the `0.2.11` V1 public contract.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PricePair {
+    /// Native SOL quoted directly in US dollars according to one provider's documented semantics.
+    SolUsd,
+}
+
+impl PricePair {
+    /// Returns the stable human-readable pair code.
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        return match self {
+            Self::SolUsd => "SOL/USD",
+        };
+    }
+}
+
+/// Price semantics retained so normalized observations do not imply cross-provider equivalence.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PriceSemantics {
+    /// Aggregated market price produced by a multi-market data provider.
+    AggregatedMarket,
+    /// USD price associated with one explicitly configured DEX pair.
+    DexPairUsd,
+    /// Last-trade price reported by one centralized exchange market.
+    ExchangeLastTrade,
+    /// Heuristic USD price derived from Solana swap/liquidity activity.
+    SolanaHeuristic,
+    /// Direct Solana-oriented spot price supplied by an on-chain market data provider.
+    SolanaSpot,
+}
+
+/// Generic authentication capability exposed by one configured provider.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PriceProviderAuthMode {
+    /// No credential is required for the configured access mode.
+    None,
+    /// Provider accepts an API key but also supports an unauthenticated mode selected by configuration.
+    OptionalApiKey,
+    /// An API key is required for the configured access mode.
+    RequiredApiKey,
+}
+
+/// Scope to which a provider documents a request limit.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PriceProviderRateLimitScope {
+    /// Limit is associated with the configured account or API key.
+    Account,
+    /// Limit is associated with the source IP address.
+    Ip,
+    /// Limit is associated with an organization or project wider than one key.
+    Organization,
+    /// Provider documentation does not expose a stronger stable scope.
+    Unspecified,
+}
+
+/// Shape of one generic provider request-limit capability.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PriceProviderRateLimitKind {
+    /// Dynamic or server-driven limit that cannot be represented as one safe fixed local cadence.
+    Dynamic,
+    /// Locally enforceable fixed request budget over a documented window.
+    Fixed,
+}
+
+/// Generic provider request-limit capability with validated fixed-limit values.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Serialize)]
+pub struct PriceProviderRateLimit {
+    burst: std::option::Option<u32>,
+    kind: crate::PriceProviderRateLimitKind,
+    requests: std::option::Option<u32>,
+    scope: crate::PriceProviderRateLimitScope,
+    window_seconds: std::option::Option<u32>,
+}
+
+impl PriceProviderRateLimit {
+    /// Creates a validated fixed request limit.
+    pub fn fixed(requests: u32, window_seconds: u32, burst: std::option::Option<u32>, scope: crate::PriceProviderRateLimitScope) -> ksp_core_lib::Result<Self> {
+        if requests == 0 || window_seconds == 0 || burst == std::option::Option::Some(0) {
+            return std::result::Result::Err(provider_descriptor_error());
+        }
+        return std::result::Result::Ok(Self {
+            burst,
+            kind: crate::PriceProviderRateLimitKind::Fixed,
+            requests: std::option::Option::Some(requests),
+            scope,
+            window_seconds: std::option::Option::Some(window_seconds),
+        });
+    }
+
+    /// Creates a dynamic/server-driven request-limit descriptor.
+    #[must_use]
+    pub const fn dynamic(scope: crate::PriceProviderRateLimitScope) -> Self {
+        return Self {
+            burst: std::option::Option::None,
+            kind: crate::PriceProviderRateLimitKind::Dynamic,
+            requests: std::option::Option::None,
+            scope,
+            window_seconds: std::option::Option::None,
+        };
+    }
+
+    /// Returns optional documented burst capacity.
+    #[must_use]
+    pub const fn burst(&self) -> std::option::Option<u32> {
+        return self.burst;
+    }
+
+    /// Returns whether the limit is fixed or dynamic/server-driven.
+    #[must_use]
+    pub const fn kind(&self) -> crate::PriceProviderRateLimitKind {
+        return self.kind;
+    }
+
+    /// Returns the request budget for a fixed limit, or `None` for a dynamic limit.
+    #[must_use]
+    pub const fn requests(&self) -> std::option::Option<u32> {
+        return self.requests;
+    }
+
+    /// Returns the documented limit scope.
+    #[must_use]
+    pub const fn scope(&self) -> crate::PriceProviderRateLimitScope {
+        return self.scope;
+    }
+
+    /// Returns the fixed window duration in seconds, or `None` for a dynamic limit.
+    #[must_use]
+    pub const fn window_seconds(&self) -> std::option::Option<u32> {
+        return self.window_seconds;
+    }
+}
+
+/// Period used by one documented long-term provider quota.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PriceProviderQuotaPeriod {
+    /// Quota resets on a provider-defined daily period.
+    Day,
+    /// Quota resets on a provider-defined monthly period.
+    Month,
+}
+
+/// Unit used by one documented long-term provider quota.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PriceProviderQuotaUnit {
+    /// Provider-specific credits, not assumed to equal HTTP requests.
+    Credits,
+    /// HTTP/API requests.
+    Requests,
+}
+
+/// Long-term provider quota descriptor exposed as non-authoritative capability metadata.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Serialize)]
+pub struct PriceProviderLongTermQuota {
+    amount: u64,
+    period: crate::PriceProviderQuotaPeriod,
+    unit: crate::PriceProviderQuotaUnit,
+}
+
+impl PriceProviderLongTermQuota {
+    /// Creates a non-zero documented quota descriptor.
+    pub fn new(amount: u64, period: crate::PriceProviderQuotaPeriod, unit: crate::PriceProviderQuotaUnit) -> ksp_core_lib::Result<Self> {
+        if amount == 0 {
+            return std::result::Result::Err(provider_descriptor_error());
+        }
+        return std::result::Result::Ok(Self { amount, period, unit });
+    }
+
+    /// Returns the documented amount without treating it as a local remaining counter.
+    #[must_use]
+    pub const fn amount(&self) -> u64 {
+        return self.amount;
+    }
+
+    /// Returns the provider-defined quota period.
+    #[must_use]
+    pub const fn period(&self) -> crate::PriceProviderQuotaPeriod {
+        return self.period;
+    }
+
+    /// Returns the documented quota unit.
+    #[must_use]
+    pub const fn unit(&self) -> crate::PriceProviderQuotaUnit {
+        return self.unit;
+    }
+}
+
+/// Opaque validated provider identifier owned by Off-chain Transport.
+#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd, serde::Deserialize, serde::Serialize)]
+#[serde(try_from = "std::string::String", into = "std::string::String")]
+pub struct PriceProviderId(std::string::String);
+
+impl PriceProviderId {
+    /// Creates one bounded stable provider identifier.
+    pub fn new(value: impl std::convert::Into<std::string::String>) -> ksp_core_lib::Result<Self> {
+        ksp_logging_lib::trace!(target: crate::TRACING_TARGET, "validating market-price provider identifier");
+        let value = value.into();
+        if !valid_provider_id(value.as_str()) {
+            ksp_logging_lib::warn!(target: crate::TRACING_TARGET, field = "provider_id", "rejected invalid market-price provider identifier");
+            return std::result::Result::Err(ksp_core_lib::Error::new(
+                crate::ERROR_CODE_PROVIDER_ID_INVALID,
+                "invalid off-chain market-price provider identifier",
+            ));
+        }
+        return std::result::Result::Ok(Self(value));
+    }
+
+    /// Returns the opaque identifier as a stable string.
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        return self.0.as_str();
+    }
+}
+
+impl std::fmt::Display for PriceProviderId {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter.write_str(self.0.as_str());
+    }
+}
+
+impl std::convert::TryFrom<std::string::String> for PriceProviderId {
+    type Error = ksp_core_lib::Error;
+
+    fn try_from(value: std::string::String) -> std::result::Result<Self, Self::Error> {
+        return crate::PriceProviderId::new(value);
+    }
+}
+
+impl std::convert::From<PriceProviderId> for std::string::String {
+    fn from(value: PriceProviderId) -> Self {
+        return value.0;
+    }
+}
+
+/// Provider capability and presentation descriptor consumed by provider-agnostic callers.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize)]
+pub struct PriceProviderDescriptor {
+    auth_mode: crate::PriceProviderAuthMode,
+    display_name: std::string::String,
+    id: crate::PriceProviderId,
+    long_term_quota: std::option::Option<crate::PriceProviderLongTermQuota>,
+    rate_limit: crate::PriceProviderRateLimit,
+    semantics: crate::PriceSemantics,
+    supports_sol_usd: bool,
+}
+
+impl PriceProviderDescriptor {
+    /// Creates a validated provider-neutral descriptor.
+    pub fn new(
+        id: crate::PriceProviderId,
+        display_name: impl std::convert::Into<std::string::String>,
+        semantics: crate::PriceSemantics,
+        auth_mode: crate::PriceProviderAuthMode,
+        rate_limit: crate::PriceProviderRateLimit,
+        long_term_quota: std::option::Option<crate::PriceProviderLongTermQuota>,
+        supports_sol_usd: bool,
+    ) -> ksp_core_lib::Result<Self> {
+        ksp_logging_lib::trace!(target: crate::TRACING_TARGET, "validating market-price provider descriptor");
+        let display_name = display_name.into();
+        if !valid_display_name(display_name.as_str()) {
+            ksp_logging_lib::warn!(target: crate::TRACING_TARGET, field = "display_name", "rejected invalid market-price provider descriptor");
+            return std::result::Result::Err(provider_descriptor_error());
+        }
+        return std::result::Result::Ok(Self { auth_mode, display_name, id, long_term_quota, rate_limit, semantics, supports_sol_usd });
+    }
+
+    /// Returns the configured authentication capability.
+    #[must_use]
+    pub const fn auth_mode(&self) -> crate::PriceProviderAuthMode {
+        return self.auth_mode;
+    }
+
+    /// Returns the safe display name.
+    #[must_use]
+    pub fn display_name(&self) -> &str {
+        return self.display_name.as_str();
+    }
+
+    /// Returns the opaque provider identifier.
+    #[must_use]
+    pub const fn id(&self) -> &crate::PriceProviderId {
+        return &self.id;
+    }
+
+    /// Returns optional long-term quota metadata without exposing a local remaining counter.
+    #[must_use]
+    pub const fn long_term_quota(&self) -> std::option::Option<crate::PriceProviderLongTermQuota> {
+        return self.long_term_quota;
+    }
+
+    /// Returns the configured request-limit capability.
+    #[must_use]
+    pub const fn rate_limit(&self) -> crate::PriceProviderRateLimit {
+        return self.rate_limit;
+    }
+
+    /// Returns the documented price semantics.
+    #[must_use]
+    pub const fn semantics(&self) -> crate::PriceSemantics {
+        return self.semantics;
+    }
+
+    /// Reports whether this descriptor can serve the V1 SOL/USD pair.
+    #[must_use]
+    pub const fn supports_sol_usd(&self) -> bool {
+        return self.supports_sol_usd;
+    }
+}
+
+/// Generic runtime availability state exposed without provider-specific error parsing.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(tag = "state", rename_all = "snake_case")]
+pub enum PriceProviderAvailability {
+    /// Required authentication material is unavailable or rejected.
+    AuthenticationUnavailable,
+    /// Provider is locally cooling down until the supplied timestamp.
+    CoolingDown {
+        /// Earliest known wall-clock timestamp at which a new attempt may be admitted.
+        retry_at: crate::PriceTimestamp,
+    },
+    /// Provider is disabled by runtime configuration.
+    Disabled,
+    /// Runtime settings do not satisfy the provider adapter contract.
+    Misconfigured,
+    /// Provider-reported quota prevents current use.
+    QuotaUnavailable,
+    /// Provider is eligible for a new request.
+    Ready,
+    /// Transport/provider failure is transient; retry time is present only when actually known.
+    TemporarilyUnavailable {
+        /// Optional next retry timestamp derived from safe runtime/provider information.
+        retry_at: std::option::Option<crate::PriceTimestamp>,
+    },
+}
+
+/// Current provider-neutral runtime state projection.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize)]
+pub struct PriceProviderState {
+    availability: crate::PriceProviderAvailability,
+    provider_id: crate::PriceProviderId,
+}
+
+impl PriceProviderState {
+    /// Creates one generic state projection for a configured provider.
+    #[must_use]
+    pub fn new(provider_id: crate::PriceProviderId, availability: crate::PriceProviderAvailability) -> Self {
+        return Self { availability, provider_id };
+    }
+
+    /// Returns the generic availability classification.
+    #[must_use]
+    pub const fn availability(&self) -> crate::PriceProviderAvailability {
+        return self.availability;
+    }
+
+    /// Returns the opaque provider identifier.
+    #[must_use]
+    pub const fn provider_id(&self) -> &crate::PriceProviderId {
+        return &self.provider_id;
+    }
+}
+
+fn provider_descriptor_error() -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_PROVIDER_DESCRIPTOR_INVALID, "invalid off-chain market-price provider descriptor");
+}
+
+fn valid_display_name(value: &str) -> bool {
+    if value.is_empty() || value.len() > crate::PRICE_PROVIDER_DISPLAY_NAME_MAX_BYTES || value.trim() != value {
+        return false;
+    }
+    for character in value.chars() {
+        if character.is_control() {
+            return false;
+        }
+    }
+    return true;
+}
+
+fn valid_provider_id(value: &str) -> bool {
+    if value.is_empty() || value.len() > crate::PRICE_PROVIDER_ID_MAX_BYTES {
+        return false;
+    }
+    for byte in value.bytes() {
+        if !(byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-' || byte == b'_') {
+            return false;
+        }
+    }
+    return true;
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/market_price_provider.rs"]
+mod tests;