network

type ArchiveScope struct {
	// Kind is one of: "all" (full archive from genesis), "before" (prune
	// before a specific block), "distance" (keep last N blocks of history).
	Kind string
	// Block is set when Kind == "before".
	Block uint64
	// Distance is set when Kind == "distance".
	Distance uint64
	// Label is a human-readable description for logs/picker confirmation.
	Label string
	// Since is the canonical human token for the scope (a hardfork name
	// like "cancun", a duration like "365d", a raw block number, or
	// "genesis"). Written back to values.yaml so `network list|status` can
	// show what the user chose rather than only the resolved block.
	Since string
}

type ChainEntry struct {
	Name    string `json:"name"`
	Chain   string `json:"chain"`
	ChainID int    `json:"chainId"`
	RPC     []any  `json:"rpc"` // mix of strings and objects
}

type ChainListFetcher func() ([]byte, error)

type ConsensusStatus struct {
	Reachable    bool    `json:"reachable"`
	Error        string  `json:"error,omitempty"`
	Version      string  `json:"version,omitempty"`
	HeadSlot     uint64  `json:"head_slot"`
	SyncDistance uint64  `json:"sync_distance"`
	IsSyncing    bool    `json:"is_syncing"`
	IsOptimistic bool    `json:"is_optimistic"`
	ELOffline    bool    `json:"el_offline"`
	Peers        *uint64 `json:"peers,omitempty"`
	// SyncState is Lighthouse's own sync state (/lighthouse/syncing):
	// SyncingFinalized, SyncingHead, BackFillSyncing, SyncTransition,
	// Synced or Stalled. Empty for other clients.
	SyncState         string `json:"sync_state,omitempty"`
	SyncTargetSlot    uint64 `json:"sync_target_slot,omitempty"`
	BackfillCompleted uint64 `json:"backfill_completed,omitempty"`
	BackfillRemaining uint64 `json:"backfill_remaining,omitempty"`
	// Stages is the human view of the sync (finalized → head → backfill).
	Stages []SyncStage `json:"stages,omitempty"`
}

type Deployment struct {
	Type            string `json:"type"`
	ID              string `json:"id"`
	Namespace       string `json:"namespace"`
	Network         string `json:"network,omitempty"`
	ExecutionClient string `json:"execution_client,omitempty"`
	ConsensusClient string `json:"consensus_client,omitempty"`
	Mode            string `json:"mode,omitempty"`
	// ArchiveScope is the human-readable mode + history scope, e.g. "full",
	// "archive", "archive since cancun (block 19,426,587)" or
	// "archive, last 365d" (ethereum only; see FormatArchiveScope).
	ArchiveScope string `json:"archive_scope,omitempty"`
	// Raw pruning scope from values.yaml (ethereum only).
	PruneKind     string `json:"prune_kind,omitempty"`
	PruneBlock    uint64 `json:"prune_block,omitempty"`
	PruneDistance uint64 `json:"prune_distance,omitempty"`
	Since         string `json:"since,omitempty"`
	// Stopped is set by `obol network stop`: workloads scaled to 0, data
	// kept, not registered with eRPC (values.yaml `stopped: true`).
	Stopped bool `json:"stopped,omitempty"`
	// Error is set when values.yaml could not be read; the deployment
	// directory still exists, so it is listed rather than hidden.
	Error string `json:"error,omitempty"`
}

type ERPCAttempt struct {
	Upstream string `json:"upstream"`
	Phase    string `json:"phase,omitempty"`
	Result   string `json:"result,omitempty"`
	Won      bool   `json:"won,omitempty"`
}

type ERPCChain struct {
	Network   string         `json:"network"`
	ChainID   int            `json:"chain_id"`
	Upstreams []ERPCUpstream `json:"upstreams"`
	// Serving is the upstream that answered one eth_blockNumber sent
	// through eRPC ("" when not probed or nobody answered).
	Serving    string        `json:"serving,omitempty"`
	FromCache  bool          `json:"from_cache,omitempty"`
	Attempts   []ERPCAttempt `json:"attempts,omitempty"`
	ProbeError string        `json:"probe_error,omitempty"`
}

type ERPCChainCount struct {
	ChainID   int    `json:"chain_id"`
	Name      string `json:"name"`
	Upstreams int    `json:"upstreams"`
}

type ERPCOverlay struct {
	Version int `yaml:"version"`

	// Networks are merged into projects[0].networks by chainId (preferred)
	// or alias. Matching entries are replaced; others are appended.
	Networks []map[string]any `yaml:"networks,omitempty"`

	// Upstreams are merged into projects[0].upstreams by id. Matching
	// entries are replaced; others are appended (after existing).
	Upstreams []map[string]any `yaml:"upstreams,omitempty"`

	// RateLimiters budgets are merged by id; other top-level keys are
	// shallow-replaced (see mergeRateLimiters).
	RateLimiters map[string]any `yaml:"rateLimiters,omitempty"`

	// CachePoliciesAdd are appended to database.evmJsonRpcCache.policies
	// when no existing policy has the same network+method+finality triple.
	CachePoliciesAdd []map[string]any `yaml:"cachePoliciesAdd,omitempty"`
}

type ERPCOverlayStatus struct {
	Path           string
	Present        bool
	Version        int
	NetworkCount   int
	UpstreamCount  int
	BudgetCount    int
	CachePolicyAdd int
	NetworkKeys    []string
	UpstreamIDs    []string
	ContentHash    string

	// ClusterSync is a best-effort comparison of ContentHash against the
	// live ConfigMap's erpcOverlayAnnotKey annotation:
	// "in-sync" | "drifted" | "not-applied" | "" (cluster unreachable/unknown).
	ClusterSync string
}

type ERPCPod struct {
	Name     string `json:"name"`
	Phase    string `json:"phase"`
	Ready    bool   `json:"ready"`
	Restarts int    `json:"restarts"`
	Reason   string `json:"reason,omitempty"`
}

type ERPCStatus struct {
	Endpoint  string           `json:"endpoint"`
	Health    string           `json:"health"`
	Pods      []ERPCPod        `json:"pods"`
	Upstreams []ERPCChainCount `json:"upstreams"`
	Chains    []ERPCChain      `json:"chains"`
	Error     string           `json:"error,omitempty"`
}

type ERPCUpstream struct {
	ID string `json:"id"`
	// Local marks an upstream that is a local node deployment
	// (local-<type>-<id>); Deployment is its "<type>/<id>".
	Local      bool   `json:"local"`
	Deployment string `json:"deployment,omitempty"`
}

type ExecutionStatus struct {
	Reachable     bool    `json:"reachable"`
	Error         string  `json:"error,omitempty"`
	ClientVersion string  `json:"client_version,omitempty"`
	Syncing       bool    `json:"syncing"`
	HeadBlock     uint64  `json:"head_block"`
	CurrentBlock  uint64  `json:"current_block,omitempty"`
	HighestBlock  uint64  `json:"highest_block,omitempty"`
	Peers         *uint64 `json:"peers,omitempty"`
	// Stages is reth's staged-sync pipeline from eth_syncing, in pipeline
	// order, annotated with done/current/pending against the sync target.
	Stages []SyncStage `json:"stages,omitempty"`
}

type Hardfork struct {
	// Name is the canonical EL fork name used by --since=<name>.
	Name string
	// DisplayName is shown in the interactive picker.
	DisplayName string
	// Block is the first execution block at or after the fork activation.
	Block uint64
	// Date is the activation date, used only for picker labels.
	Date string
	// ApproxArchiveSizeTB is a rough estimate of mainnet archive disk usage
	// when pruning state history before this block (reth). Used in picker
	// labels so users have a realistic expectation. Values rounded.
	ApproxArchiveSizeTB float64
}

type NodeERPC struct {
	// Upstream is the eRPC upstream id the node registers as.
	Upstream string `json:"upstream"`
	// Registered is whether the live eRPC config lists that upstream.
	Registered bool `json:"registered"`
	// Serving is the upstream that answered a probe request for the node's
	// chain through eRPC (empty when not probed).
	Serving string `json:"serving,omitempty"`
}

type NodeProber struct {
	// Forward opens a tunnel to namespace/service:port and returns its base
	// URL and a closer.
	Forward func(ctx context.Context, namespace, service string, port int) (string, func(), error)
	// Pods lists the pods in a namespace.
	Pods func(ctx context.Context, namespace string) ([]PodStatus, error)
	// ERPCConfig returns the parsed live eRPC config (erpc-config ConfigMap).
	ERPCConfig func(ctx context.Context) (map[string]any, error)
	// DiskUsage sums the bytes under dir (partial when it could not read
	// everything in time). Nil disables the Data line.
	DiskUsage func(ctx context.Context, dir string) (bytes uint64, partial bool, err error)
	// FreeBytes reports free space on the filesystem holding path.
	FreeBytes func(path string) (uint64, error)
	// DataDir is the host directory holding PVC data (<ns>/<pvc>).
	DataDir string
	// HTTP is used for every API call; its Timeout bounds each request.
	HTTP *http.Client
	// Now is the clock for "last 3m ago" (defaults to time.Now).
	Now func() time.Time
	// contains filtered or unexported fields
}

type NodeStatus struct {
	Deployment

	Pods      []PodStatus      `json:"pods"`
	PodsError string           `json:"pods_error,omitempty"`
	Problems  []PodProblem     `json:"problems"`
	Execution *ExecutionStatus `json:"execution,omitempty"`
	Consensus *ConsensusStatus `json:"consensus,omitempty"`
	Storage   *StorageStatus   `json:"storage,omitempty"`
	ERPC      *NodeERPC        `json:"erpc,omitempty"`
	// GrafanaURL is the node's dashboard on the local Grafana route.
	GrafanaURL string  `json:"grafana_url,omitempty"`
	Verdict    Verdict `json:"verdict"`
}

type PodProblem struct {
	Component string     `json:"component"`
	Pod       string     `json:"pod"`
	State     string     `json:"state"`
	Cause     string     `json:"cause,omitempty"`
	Restarts  int32      `json:"restarts,omitempty"`
	LastAt    *time.Time `json:"last_at,omitempty"`
	Message   string     `json:"message"`
	Hint      string     `json:"hint,omitempty"`
}

type PodStatus struct {
	Name      string `json:"name"`
	Component string `json:"component"`
	Phase     string `json:"phase"`
	Ready     bool   `json:"ready"`
	Restarts  int32  `json:"restarts"`
	// Reason is the current waiting/terminated reason (CrashLoopBackOff,
	// ContainerCreating, OOMKilled …).
	Reason string `json:"reason,omitempty"`
	// LastTermination is the most recent container exit (lastState), the
	// cause behind a CrashLoopBackOff.
	LastTermination *Termination `json:"last_termination,omitempty"`
	// Unschedulable is the scheduler's message while the pod can't be
	// placed (e.g. "0/1 nodes are available: 1 Insufficient memory.").
	Unschedulable string `json:"unschedulable,omitempty"`
	MemoryRequest string `json:"memory_request,omitempty"`
	MemoryLimit   string `json:"memory_limit,omitempty"`
}

type RPCEndpoint struct {
	URL      string `json:"url"`
	Tracking string `json:"tracking"` // "none", "limited", or "yes"
}

type RPCNetworkInfo struct {
	ChainID   int
	Alias     string
	Upstreams []RPCUpstreamInfo
}

type RPCUpstreamInfo struct {
	ID       string
	Endpoint string
	ChainID  int
}

type RateTracker struct {
	// Window is how far back samples count (default 10m).
	Window time.Duration
	// contains filtered or unexported fields
}

type RecordedChain struct {
	Name      string             `yaml:"name"`
	Chainlist *RecordedChainlist `yaml:"chainlist,omitempty"`
	Custom    *RecordedCustom    `yaml:"custom,omitempty"`
}

type RecordedChainlist struct {
	ReadOnly  bool          `yaml:"readOnly"`
	Endpoints []RPCEndpoint `yaml:"endpoints"`
}

type RecordedCustom struct {
	Endpoint string `yaml:"endpoint"`
	ReadOnly bool   `yaml:"readOnly"`
}

type RecordedRPCs struct {
	Version int                       `yaml:"version"`
	Chains  map[string]*RecordedChain `yaml:"chains"` // key: decimal chain ID
}

type StatusOptions struct {
	// NoProbe skips live API calls (node APIs and the eRPC serving probe);
	// pods and the eRPC config are still read.
	NoProbe bool
	// Installed is every installed deployment, used to link eRPC's local
	// upstreams to them. Defaults to the probed deployments.
	Installed []Deployment
}

type StatusReport struct {
	Time  time.Time    `json:"time"`
	ERPC  ERPCStatus   `json:"erpc"`
	Nodes []NodeStatus `json:"nodes"`
}

type StorageStatus struct {
	Path           string  `json:"path"`
	ExecutionBytes uint64  `json:"execution_bytes"`
	ConsensusBytes uint64  `json:"consensus_bytes"`
	FreeBytes      *uint64 `json:"free_bytes,omitempty"`
	// Partial means some of it couldn't be read (permissions) or summed in
	// time; the sizes are then lower bounds.
	Partial bool `json:"partial,omitempty"`
}

type SyncStage struct {
	Name string `json:"name"`
	// Block is the progress reached (a block, a slot, or for backfill the
	// number of slots filled), in Unit.
	Block  uint64 `json:"block"`
	Target uint64 `json:"target,omitempty"`
	State  string `json:"state"`
	Unit   string `json:"unit,omitempty"`
	// RatePerSec and ETASeconds are set by --watch once a few samples exist.
	RatePerSec *float64 `json:"rate_per_sec,omitempty"`
	ETASeconds *int64   `json:"eta_seconds,omitempty"`
}

type TemplateField struct {
	Name         string
	DefaultValue string
	FlagName     string   // CLI flag name derived from field name
	Description  string   // Human-readable description from @description
	EnumValues   []string // Valid enum values from @enum
	Required     bool     // Whether this field is required (no default value)
}

type Termination struct {
	Reason     string    `json:"reason,omitempty"`
	ExitCode   int32     `json:"exit_code"`
	FinishedAt time.Time `json:"finished_at,omitzero"`
}

type Verdict struct {
	State       string   `json:"state"`
	Summary     string   `json:"summary"`
	ProgressPct *float64 `json:"progress_pct,omitempty"`
	Warnings    []string `json:"warnings,omitempty"`
}