protocol

type Endpoint interface {
	// Addr is used to uniquely identify an endpoint.
	// Defining this as an interface allows Shannon to
	// define its own service endpoint address scheme.
	// See the comment on EndpointAddr type for more details.
	Addr() EndpointAddr

	// PublicURL is the publically exposed/accessible URL to which relay requests can be sent.
	PublicURL() string

	// WebsocketURL is the URL of the endpoint for websocket RPC type requests.
	// Returns an error if the endpoint does not support websocket RPC type requests.
	WebsocketURL() (string, error)
}

type EndpointAddr string

type EndpointAddrList []EndpointAddr

type EndpointArchival struct {
	// IsArchival indicates if the endpoint supports archival requests
	IsArchival bool `json:"is_archival"`

	// ExpiresAt indicates when the archival status needs re-validation
	ExpiresAt string `json:"expires_at,omitempty"`
}

type EndpointDetails struct {
	// Address is the unique identifier for this endpoint (supplier-url format)
	Address string `json:"address"`

	// SupplierAddress is the on-chain address of the supplier
	SupplierAddress string `json:"supplier_address"`

	// URL is the public URL of the endpoint
	URL string `json:"url"`

	// IsFallback indicates whether this is a fallback (non-protocol) endpoint
	IsFallback bool `json:"is_fallback"`

	// Reputation contains the endpoint's reputation metrics
	Reputation *EndpointReputation `json:"reputation,omitempty"`

	// Archival contains archival capability information (EVM services only)
	Archival *EndpointArchival `json:"archival,omitempty"`

	// RPCTypes lists the supported RPC types for this endpoint
	RPCTypes []string `json:"rpc_types,omitempty"`

	// Tier indicates the current reputation tier (1=highest, 2=medium, 3=lowest)
	Tier int `json:"tier,omitempty"`

	// InCooldown indicates if the endpoint is currently in cooldown
	InCooldown bool `json:"in_cooldown,omitempty"`

	// CooldownRemaining is the remaining cooldown time if in cooldown
	CooldownRemaining string `json:"cooldown_remaining,omitempty"`
}

type EndpointLatency struct {
	// AvgLatencyMs is the average response latency in milliseconds
	AvgLatencyMs float64 `json:"avg_latency_ms"`

	// MinLatencyMs is the minimum observed latency in milliseconds
	MinLatencyMs float64 `json:"min_latency_ms"`

	// MaxLatencyMs is the maximum observed latency in milliseconds
	MaxLatencyMs float64 `json:"max_latency_ms"`

	// LastLatencyMs is the most recent latency sample in milliseconds
	LastLatencyMs float64 `json:"last_latency_ms"`

	// SampleCount is the number of latency samples collected
	SampleCount int64 `json:"sample_count"`
}

type EndpointReputation struct {
	// Score is the current reputation score (0-100)
	Score float64 `json:"score"`

	// SuccessCount is the total number of successful requests
	SuccessCount int64 `json:"success_count"`

	// ErrorCount is the total number of failed requests
	ErrorCount int64 `json:"error_count"`

	// LastUpdated is when the score was last modified
	LastUpdated string `json:"last_updated,omitempty"`

	// Latency contains latency metrics for the endpoint
	Latency *EndpointLatency `json:"latency,omitempty"`

	// CriticalStrikes is the current strike count
	CriticalStrikes int `json:"critical_strikes,omitempty"`
}

type EndpointSelector interface {
	Select(EndpointAddrList) (EndpointAddr, error)
	SelectMultiple(EndpointAddrList, uint) (EndpointAddrList, error)
	// SelectMultipleWithArchival selects multiple endpoints with optional archival filtering.
	// When requiresArchival is true, only endpoints that have passed archival capability checks
	// are considered. When false, all valid endpoints are considered (same as SelectMultiple).
	// This enables archival requests to be routed only to archival-capable endpoints.
	SelectMultipleWithArchival(EndpointAddrList, uint, bool) (EndpointAddrList, error)
}

type GatewayMode string

type Payload struct {
	Data    string
	Method  string
	Path    string
	Headers map[string]string
	// RPCType indicates the type of RPC protocol for routing to appropriate backend ports:
	// - RPCType_REST: Cosmos SDK REST API (typically port 1317)
	// - RPCType_COMET_BFT: CometBFT RPC (typically port 26657)
	// - RPCType_JSON_RPC: EVM JSON-RPC (typically port 8545)
	RPCType sharedtypes.RPCType

	// OriginalRPCType preserves the RPC type detected from the request before any
	// fallback was applied. When COMET_BFT falls back to JSON_RPC for routing
	// (because no suppliers stake comet_bft endpoints), this field retains
	// COMET_BFT so downstream analysis (e.g., heuristic error detection) can
	// make protocol-aware decisions.
	// Zero value (UNKNOWN_RPC) means no fallback occurred — use RPCType directly.
	OriginalRPCType sharedtypes.RPCType

	// JSONRPCMethod is the JSON-RPC method name (e.g., "eth_blockNumber", "eth_getLogs").
	// Set at QoS request parsing time. Used by the heuristic analyzer for method-aware
	// response validation (e.g., "result":[] is valid for eth_getLogs but not eth_blockNumber).
	// Empty for non-JSON-RPC requests (REST, WebSocket).
	JSONRPCMethod string
}

type RelayMetadata struct {
	// AppAddress is the application address used to sign/authorize the relay.
	AppAddress string
	// SupplierAddress is the supplier/operator address of the endpoint that served the relay.
	SupplierAddress string
	// SessionID is the session identifier from which the supplier was selected.
	SessionID string
}

type Response struct {
	// Bytes is the response to a relay received from an endpoint.
	// An endpoint is the backend server servicing an onchain service.
	// This can be the serialized response to any type of RPC (gRPC, HTTP, etc.)
	Bytes []byte
	// HTTPStatusCode is the HTTP status returned by an endpoint in response to a relay request.
	HTTPStatusCode int

	// EndpointAddr is the address of the endpoint which returned the response.
	EndpointAddr

	// Metadata contains relay-specific information for debugging/transparency.
	// Used to populate response headers like X-Supplier-Address, X-App-Address, X-Session-ID.
	Metadata RelayMetadata

	// RequestID is the JSON-RPC request ID that this response corresponds to.
	// Used for batch request processing to ensure error responses have the correct ID.
	// For non-JSON-RPC requests or when ID extraction fails, this may be empty.
	RequestID string
}

type ServiceID string