price/pkg/source/source.go

// Copyright (c) 2025 Lux Partners Limited
// SPDX-License-Identifier: MIT

// Package source defines the price-feed provider interface used by the
// pricing oracle. Each Source fetches USD-denominated quotes for a set of
// token IDs from one upstream exchange or aggregator.
package source

import (
	"context"
	"time"
)

// Quote is a single observation produced by a Source.
//
// PriceUSD is the spot/last price denominated in USD. SourceName matches the
// owning Source's Name() so observations remain attributable when stored.
// Fields that the upstream does not expose are zero-valued.
type Quote struct {
	ID         string    `json:"id"`
	Symbol     string    `json:"symbol,omitempty"`
	PriceUSD   float64   `json:"price_usd"`
	Change24h  float64   `json:"change_24h,omitempty"`
	Volume24h  float64   `json:"volume_24h,omitempty"`
	MarketCap  float64   `json:"market_cap,omitempty"`
	UpdatedAt  time.Time `json:"updated_at"`
	SourceName string    `json:"source_name"`
}

// Source is the interface every price provider must implement.
//
// Implementations MUST be safe for concurrent use. Fetch should respect the
// caller's context deadline and never block longer than the upstream's
// reasonable response window — a single slow source must not stall the
// fetcher loop.
type Source interface {
	// Name returns the canonical lower-case identifier (e.g. "coingecko",
	// "coinbase", "kraken"). It is used as a foreign key on observation
	// rows and for default-weight lookups.
	Name() string

	// Enabled reports whether the source is configured to run. Disabled
	// sources are skipped by the fetcher loop without producing an error.
	Enabled() bool

	// Fetch returns one Quote per requested token ID that the source could
	// resolve. Tokens the source does not know about are silently dropped
	// from the result — they are not an error.
	Fetch(ctx context.Context, ids []string) (map[string]Quote, error)
}