mithril

type Aggregator struct {
	// contains filtered or unexported fields
}

type AggregatorConfig struct {
	// Network is the Cardano network name written into certificates; only
	// snapshots of this network are certified.
	Network string
	// Epoch is the epoch signers register for. The genesis certificate is
	// issued at Epoch-1, so Epoch must be at least 1.
	Epoch uint64
	// Parameters are the STM protocol parameters for the signer set.
	Parameters ProtocolParameters
	// GenesisSigningKey signs the genesis certificate that roots the chain.
	GenesisSigningKey ed25519.PrivateKey
	// Store holds the snapshots to certify and receives the certificates.
	Store ArtifactStore
	// OperatorToken authorizes signer registration and registration closure.
	// Use at least 32 unpredictable bytes and transport it over TLS.
	OperatorToken string
}

type ArtifactStore interface {
	// Put writes the object at key, replacing any existing object. A
	// reader of key sees either the previous or the complete new object.
	Put(ctx context.Context, key string, r io.Reader) error
	// Open returns a seekable reader over the object at key, or an error
	// wrapping ErrArtifactNotFound.
	Open(ctx context.Context, key string) (io.ReadSeekCloser, error)
	// Subdirs returns the sorted names of the immediate directory-like
	// children of prefix ("" for the store root).
	Subdirs(ctx context.Context, prefix string) ([]string, error)
	// DeletePrefix removes the object whose key is prefix and every object
	// under prefix + "/". Removing nothing is not an error.
	DeletePrefix(ctx context.Context, prefix string) error
}

type BatchApplier interface {
	// Tip returns the point of the last applied block, or the zero point for
	// an empty ledger.
	Tip() ocommon.Point
	// ApplyTrustedBatch applies blocks, which extend expected, as one batch,
	// and returns the new tip. When the tip is no longer expected it applies
	// nothing and returns an error satisfying errors.Is(err, ErrStaleBatch).
	ApplyTrustedBatch(
		ctx context.Context,
		expected ocommon.Point,
		blocks []ledger.Block,
	) (ocommon.Point, error)
}

type Beacon struct {
	Epoch               uint64 `json:"epoch"`
	ImmutableFileNumber uint64 `json:"immutable_file_number"`
}

type BootstrapConfig struct {
	// Network is the Cardano network name (e.g., "mainnet",
	// "preprod", "preview").
	Network string
	// Backend selects the Mithril artifact backend. BackendV2 restores
	// per-immutable archives verified against the certified merkle
	// root and is the only backend; empty selects it.
	Backend string
	// AggregatorURL overrides the default aggregator URL for the
	// network. If empty, the default URL for the network is used.
	AggregatorURL string
	// AllowInsecureHTTP permits AggregatorURL and snapshot artifact locations
	// to use plain HTTP or resolve to local/private addresses. Defaults to
	// false; this is an explicit escape hatch for local development and tests
	// and should not be set in production.
	AllowInsecureHTTP bool
	// DownloadDir is the directory where the snapshot archive will
	// be downloaded. If empty, a temporary directory is created.
	DownloadDir string
	// CleanupAfterLoad controls whether temporary files are removed
	// after loading completes.
	CleanupAfterLoad bool
	// VerifyCertificateChain enables STM certificate verification against the
	// aggregator. When true, GenesisVerificationKey is required and the
	// bootstrap process verifies the chain back to that pinned genesis key.
	VerifyCertificateChain bool
	// GenesisVerificationKey is the pinned Mithril trust anchor used by STM
	// certificate verification. It is loaded from Cardano network config and
	// validated for parseability before any aggregator request.
	GenesisVerificationKey string
	// AncillaryVerificationKey is the Mithril ancillary verification key loaded
	// from Cardano network config. It is validated for parseability now and
	// will be used when ancillary artifacts are verified cryptographically.
	AncillaryVerificationKey string
	// Logger is used for structured logging.
	Logger *slog.Logger
	// OnProgress is called during download with progress updates.
	OnProgress ProgressFunc
	// DownloadIdleTimeout is the maximum time to wait for download
	// response headers or body bytes before retrying. Zero uses the
	// downloader default; negative disables idle detection.
	DownloadIdleTimeout time.Duration
	// DownloadMaxIdleRetries is the number of consecutive idle retries
	// allowed without additional bytes. Zero uses the downloader default.
	DownloadMaxIdleRetries int
	// DownloadMaxBytes bounds each compressed object, including resumed
	// bytes. Zero uses DefaultMaxDownloadBytes. It is not a cumulative
	// budget across archives, mirrors, or retries.
	DownloadMaxBytes int64
	// DownloadMaxTransientRetries is the maximum number of retry attempts
	// for transient network errors (TLS handshake failures, connection
	// resets, HTTP 429, HTTP 5xx) per download. Zero uses the downloader
	// default. Negative disables transient retries.
	DownloadMaxTransientRetries int

	// CertificateCache, when set, lets certificate verification stop at
	// certificates an earlier verification in this process accepted, and
	// skip the walk for a leaf it already accepted. Nil walks every chain to
	// genesis.
	CertificateCache *CertificateCache
	// OnArtifactSelected, when set, is invoked once this run's aggregator
	// artifact has been resolved, identity-checked and (when enabled)
	// certificate-verified, and before anything is downloaded. A non-nil
	// return aborts the bootstrap.
	//
	// It runs before the first download rather than after the bootstrap so the
	// caller can record the artifact identity durably while the run still owns
	// nothing: an interruption at any later point then has an artifact to
	// resume against, including the artifact-keyed download cache.
	OnArtifactSelected func(SelectedArtifact) error
	// PinnedDigest, when set, selects that exact artifact from the aggregator
	// instead of the latest one: it is resolved as a Cardano database
	// artifact hash. A resumed
	// Mithril sync sets it from the artifact pin the interrupted run recorded,
	// so the resume imports the artifact its partial database rows and phase
	// checkpoints belong to. Empty selects the latest artifact, the normal
	// first-run behaviour.
	PinnedDigest string
	// StartImmutable is the lowest immutable file number to download and
	// extract. Files below it are assumed already present (a Mithril v2
	// catch-up sets this to the immutable-import marker so it only fetches the
	// archives missing from the existing blob store). Zero downloads the full
	// 0..N range, the normal bootstrap behaviour.
	StartImmutable uint64
	// OnChunkContiguous, when set, enables download<->processing
	// pipelining: chunks are fetched in parallel (out of order) by the
	// shared chunk feed, and this callback is invoked from the feed's
	// in-order consumer for each immutable file number in strict
	// contiguous order as soon as that prefix is fully downloaded. The order
	// runs from StartImmutable upwards, not from zero — a catch-up leaves
	// everything below the marker to the blob store this run is adding to, so
	// those archives are neither downloaded nor extracted here and the files
	// need not exist. It lets the caller copy blocks into the blob store while
	// later chunks are still downloading. When nil, downloads run to
	// completion before any processing (legacy behaviour).
	// The callback runs on a single consumer goroutine and serializes
	// processing, so it needs no internal locking.
	OnChunkContiguous func(chunk ContiguousChunk) error
	// Metrics, when not nil, records the chunk downloads of this bootstrap
	// and of any chunk feed or stream catch-up configured with it.
	Metrics *PipelineMetrics
	// contains filtered or unexported fields
}

type BootstrapResult struct {
	// Snapshot is the snapshot that was downloaded and extracted.
	Snapshot *SnapshotListItem
	// ImmutableDir is the path to the extracted ImmutableDB
	// directory. It is the name the directory was vetted under; use
	// ImmutableRoot to read it.
	ImmutableDir string
	// ImmutableRoot is an open handle on ImmutableDir, held from the moment
	// the directory was vetted until Cleanup closes it.
	//
	// The load path opens the ImmutableDB through this handle rather than
	// through ImmutableDir. The directory sits in a download area, so between
	// vetting it and reading it a concurrent writer could put a different tree
	// at that name; resolving the name at load time would then read the
	// replacement, with the vetting having been about something else. The
	// handle refers to the directory that was vetted, and keeps referring to it
	// however the name is repointed.
	//
	// The bootstrap always sets it. A result without it did not come from a
	// vetted lookup, and loading refuses rather than falling back to the
	// pathname — a silent fallback would reinstate exactly the open this
	// replaces.
	ImmutableRoot *os.Root
	// ImmutableDigests is the certified SHA-256 of every file in ImmutableDir,
	// keyed by the name beneath it ("00000.chunk"). Set by the v2 backend,
	// which downloads each immutable trio against a digest list covered by the
	// certificate's merkle root.
	//
	// It is carried beside ImmutableRoot because the two answer different
	// questions and both have to be answered. The handle says the load reads
	// the directory that was vetted. It says nothing about the files in it: a
	// writer who shares the download directory can rename a file of their own
	// over a verified one without ever leaving the directory the handle refers
	// to. The digests are what let the load refuse those bytes, checked from
	// the descriptor the read goes through rather than from a name reopened
	// after the check.
	ImmutableDigests map[string]string
	// ExtractDir is the root directory where the archive was
	// extracted. Contains db/immutable/, db/ledger/, etc.
	ExtractDir string
	// AncillaryDir is the root directory where the ancillary
	// archive was extracted. Contains ledger/<slot>/{meta,state,
	// tables/tvar}. Set on every successful bootstrap.
	AncillaryDir string
	// AncillaryRoot is an open handle on AncillaryDir, on the same terms as
	// ImmutableRoot: the ledger-state import discovers and reads through it, so
	// the tree the signed manifest was checked against is the tree that gets
	// loaded. Set on every successful bootstrap.
	AncillaryRoot *os.Root
	// AncillaryVerified reports that the ancillary tree's contents were checked
	// against the signed ancillary manifest (a verified v2 bootstrap).
	//
	// The ledger-state import accepts a verified tree's state even when it is
	// newer than the certified tip, and refuses a verified tree that yields no
	// state at all.
	AncillaryVerified bool
	// CertificateVerified reports that the bootstrap was asked to verify the
	// certificate chain, so a missing ancillary tree is a verification failure
	// rather than an unverified run that simply produced none.
	CertificateVerified bool
	// AncillaryDigests is the signed ancillary manifest's digest map: every
	// file the ancillary key vouched for, keyed by its slash-separated path
	// under AncillaryDir. Set only when AncillaryVerified is true.
	//
	// The manifest check hashes each file and closes it; the import opens the
	// state and table it selects afterwards. Between those two the tree is the
	// same tree, but a file in it need not be the same file — so the map
	// travels with the handle and the selected files are checked again from
	// the descriptors the import reads through, before anything is parsed.
	AncillaryDigests map[string]string
	// ExtractRoot is an open handle on ExtractDir.
	//
	// ExtractDir is derived inside the download directory like everything else
	// here, so it is held through a handle rather than resolved by name.
	ExtractRoot *os.Root
	// AncillaryArchivePath is the path to the downloaded ancillary
	// archive file. Empty if no ancillary data was downloaded.
	AncillaryArchivePath string

	// TempDir is the auto-created temporary directory that holds
	// all downloaded and extracted files. Set only when
	// BootstrapConfig.DownloadDir was empty. Cleanup() removes it
	// after removing its children.
	TempDir string
	// TempRoot is the retained handle for TempDir. It is set only when TempDir
	// is set and lets Cleanup remove that exact temporary tree.
	TempRoot *os.Root
	// contains filtered or unexported fields
}

type CardanoDatabaseAncillary struct {
	SizeUncompressed int64                     `json:"size_uncompressed"`
	Locations        []CardanoDatabaseLocation `json:"locations"`
}

type CardanoDatabaseDigestEntry struct {
	ImmutableFileName string `json:"immutable_file_name"`
	Digest            string `json:"digest"`
}

type CardanoDatabaseDigests struct {
	SizeUncompressed int64                     `json:"size_uncompressed"`
	Locations        []CardanoDatabaseLocation `json:"locations"`
}

type CardanoDatabaseImmutables struct {
	AverageSizeUncompressed int64                     `json:"average_size_uncompressed"`
	Locations               []CardanoDatabaseLocation `json:"locations"`
}

type CardanoDatabaseLocation struct {
	Type                 string
	URI                  string
	URITemplate          string
	CompressionAlgorithm string
}

type CardanoDatabaseSnapshot struct {
	Hash                    string                    `json:"hash"`
	MerkleRoot              string                    `json:"merkle_root"`
	Network                 string                    `json:"network"`
	Beacon                  Beacon                    `json:"beacon"`
	CertificateHash         string                    `json:"certificate_hash"`
	TotalDbSizeUncompressed int64                     `json:"total_db_size_uncompressed"`
	Digests                 CardanoDatabaseDigests    `json:"digests"`
	Immutables              CardanoDatabaseImmutables `json:"immutables"`
	Ancillary               CardanoDatabaseAncillary  `json:"ancillary"`
	CardanoNodeVersion      string                    `json:"cardano_node_version"`
	CreatedAt               string                    `json:"created_at"`
}

type CardanoDatabaseSnapshotListItem struct {
	Hash                    string `json:"hash"`
	MerkleRoot              string `json:"merkle_root"`
	Beacon                  Beacon `json:"beacon"`
	CertificateHash         string `json:"certificate_hash"`
	TotalDbSizeUncompressed int64  `json:"total_db_size_uncompressed"`
	CardanoNodeVersion      string `json:"cardano_node_version"`
	CreatedAt               string `json:"created_at"`
}

type CardanoStakeDistribution struct {
	Hash            string                          `json:"hash"`
	CertificateHash string                          `json:"certificate_hash"`
	Epoch           uint64                          `json:"epoch"`
	Pools           []CardanoStakeDistributionParty `json:"pools"`
}

type CardanoStakeDistributionListItem struct {
	Hash                 string   `json:"hash"`
	CertificateHash      string   `json:"certificate_hash"`
	CreatedAt            string   `json:"created_at"`
	Locations            []string `json:"locations"`
	CompressionAlgorithm string   `json:"compression_algorithm"`
	Epoch                uint64   `json:"epoch"`
}

type CardanoStakeDistributionParty struct {
	PoolID string `json:"pool_id"`
	Stake  uint64 `json:"stake"`
}

type CardanoTransactionsBeacon struct {
	Epoch       uint64 `json:"epoch"`
	BlockNumber uint64 `json:"block_number"`
}

type Certificate struct {
	Hash                     string              `json:"hash"`
	PreviousHash             string              `json:"previous_hash"`
	Epoch                    uint64              `json:"epoch"`
	SignedEntityType         SignedEntityType    `json:"signed_entity_type"`
	Metadata                 CertificateMetadata `json:"metadata"`
	ProtocolMessage          ProtocolMessage     `json:"protocol_message"`
	SignedMessage            string              `json:"signed_message"`
	AggregateVerificationKey string              `json:"aggregate_verification_key"`
	MultiSignature           string              `json:"multi_signature"`
	GenesisSignature         string              `json:"genesis_signature"`
}

type CertificateCache struct {
	// contains filtered or unexported fields
}

type CertificateChainVerificationResult struct {
	Certificates       []*Certificate
	LeafCertificate    *Certificate
	GenesisCertificate *Certificate
	SignedEntityKind   string
}

type CertificateMetadata struct {
	Network     string                   `json:"network"`
	Version     string                   `json:"version"`
	Parameters  ProtocolParameters       `json:"parameters"`
	InitiatedAt string                   `json:"initiated_at"`
	SealedAt    string                   `json:"sealed_at"`
	Signers     []StakeDistributionParty `json:"signers"`
}

type CertifiedTarget struct {
	// Immutable is the highest certified immutable file number.
	Immutable uint64
	// Tip is the last block of that file. The certificate does not carry it,
	// so it is zero from LatestCertifiedTarget and, on a feed, is filled in
	// once Next has returned the last chunk (and stays zero if that file
	// holds no blocks).
	Tip ocommon.Point
}

type ChunkFeed struct {
	// contains filtered or unexported fields
}

type ChunkFeedConfig struct {
	// Bootstrap carries the network, aggregator, trust keys, download limits
	// and DownloadDir. VerifyCertificateChain and AncillaryVerificationKey
	// are ignored: a feed always verifies the certificate chain and never
	// reads the ancillary archive. An empty DownloadDir makes the feed create
	// and remove its own temporary directory.
	Bootstrap BootstrapConfig
	// StartImmutable is the lowest immutable file number to deliver. A value
	// above the certified target yields an empty feed.
	StartImmutable uint64
	// WindowChunks bounds how many chunk trios may exist on disk at once.
	// Zero or negative means unbounded. Trios wait in the window undecoded:
	// a chunk is decoded only when Next returns it, so decoded blocks in
	// memory are bounded by what the consumer holds, not by the window.
	WindowChunks int
	// Workers is the number of concurrent downloads. Zero or negative selects
	// the bootstrap default. It is capped at WindowChunks when that is set,
	// since a worker beyond the window could never start.
	Workers int
	// RawBlocks delivers each chunk's blocks as read from the verified trio,
	// in VerifiedChunk.Raw, instead of decoding them into VerifiedChunk.Blocks.
	RawBlocks bool
	// contains filtered or unexported fields
}

type Client struct {
	// contains filtered or unexported fields
}

type ClientOption func(*Client)

type ContiguousChunk struct {
	// Dir is the directory the chunks are extracted into. It is the name the
	// directory was vetted under, for messages; read through Root.
	Dir string
	// Root is the open handle extraction writes through. Read through it
	// rather than through Dir: the name can be repointed while the download
	// runs and the handle cannot.
	Root *os.Root
	// Digests is the certified SHA-256 of every file the download covers,
	// keyed by the name beneath Dir. The handle settles which directory is
	// read and these settle which bytes, which is the half a handle cannot
	// carry — see BootstrapResult.ImmutableDigests.
	Digests map[string]string
	// Start is the lowest immutable file number this run covers, from
	// BootstrapConfig.StartImmutable. Anything below it was left to the blob
	// store the run is adding to and is not in Dir.
	Start uint64
	// Num is the highest immutable file number whose trio is complete. Every
	// number in [Start, Num] has been downloaded, verified and extracted;
	// below Start, nothing has, which is why the range is given rather than
	// implied. Chunks are addressed by number — a number is not a position in
	// Dir's listing unless Start is zero.
	Num uint64
}

type CreateSnapshotConfig struct {
	// Network is the Cardano network name recorded in the artifact.
	Network string
	// DBDir is a cardano-node style database directory holding a sealed
	// immutable/ directory and the ledger/ snapshots taken at its tip.
	DBDir string
	// AncillarySigningKey signs the ancillary manifest. Clients verify it
	// with the matching ancillary verification key.
	AncillarySigningKey ed25519.PrivateKey
	// CardanoNodeVersion is recorded verbatim in the artifact.
	CardanoNodeVersion string
	// CreatedAt is recorded in the artifact metadata; the zero value means
	// now. The archives are a function of DBDir and AncillarySigningKey.
	CreatedAt time.Time
	// Store receives the produced objects.
	Store ArtifactStore
	// Logger receives progress; nil discards it.
	Logger *slog.Logger
}

type DecisionInput struct {
	// LocalImmutable is the immutable file holding the local ledger tip.
	LocalImmutable uint64
	// Target is the aggregator's certified target. Only Target.Immutable is
	// read: LatestCertifiedTarget leaves Tip zero.
	Target CertifiedTarget
	// OuroborosBPS is the blocks per second Ouroboros applied over the last
	// check interval. Zero means unknown.
	OuroborosBPS float64
	// MithrilBPS is the blocks per second the last Mithril catch-up applied.
	// Zero means unknown.
	MithrilBPS float64
	// MinGapChunks is the smallest certified gap, in immutable files, worth
	// a catch-up. Zero is treated as one: any gap at all.
	MinGapChunks uint64
}

type DigestMismatchError struct {
	// FileName is the immutable file the digest list names ("05471.chunk").
	FileName string
	// Expected is the certified digest; Observed is what the bytes hashed to.
	Expected string
	Observed string
}

type DownloadConfig struct {
	// URL is the download URL for the snapshot archive.
	URL string
	// DestDir is the directory where the archive will be saved.
	DestDir string
	// Filename is the name of the downloaded file. If empty, a
	// default name is generated from the snapshot digest.
	Filename string
	// ExpectedSize is the expected file size in bytes. When > 0,
	// the downloaded file size is verified after download. A
	// mismatch returns an error.
	ExpectedSize int64
	// MaxBytes bounds the complete downloaded file, including resumed bytes,
	// even when ExpectedSize or Content-Length is absent. Zero selects
	// DefaultMaxDownloadBytes; negative values are invalid. This is a
	// per-object bound, not an aggregate bootstrap or transfer-byte budget.
	MaxBytes int64
	// Logger is used for logging download progress.
	Logger *slog.Logger
	// OnProgress is called periodically with download progress.
	OnProgress ProgressFunc
	// IdleTimeout is the maximum time to wait for response headers
	// or body bytes before retrying. If zero, a conservative default
	// is used. If negative, idle detection is disabled.
	IdleTimeout time.Duration
	// MaxIdleRetries is the number of consecutive retry attempts
	// after idle timeouts that make no additional download progress.
	// If zero, a conservative default is used.
	MaxIdleRetries int
	// MaxTransientRetries is the maximum number of retry attempts for
	// transient network errors (TLS handshake failures, connection
	// resets, unexpected EOF, HTTP 429, HTTP 5xx). If zero, a
	// conservative default is used. If negative, transient retries
	// are disabled.
	MaxTransientRetries int

	// HTTPClient, when non-nil, is reused for the download instead of
	// constructing a fresh client per call. Callers that fetch many
	// files (the v2 immutable pool) pass one shared keep-alive client so
	// connections are pooled across files. Unless AllowInsecureHTTP is set,
	// custom transports are cloned and restricted before use. When nil, a
	// per-call client with keep-alives disabled is used.
	HTTPClient *http.Client
	// AllowInsecureHTTP permits URL to use plain HTTP or resolve to a
	// local/private address. By default, Validate rejects either; this is an
	// explicit escape hatch for local development and tests (e.g. against an
	// httptest server) and should not be set in production.
	AllowInsecureHTTP bool
	// contains filtered or unexported fields
}

type DownloadProgress struct {
	BytesDownloaded int64
	TotalBytes      int64
	Percent         float64
	BytesPerSecond  float64
	// Artifact identifies the artifact whose progress is being reported.
	// It is populated by the bootstrap orchestration layer so concurrent
	// downloads can be distinguished by callers consuming one callback.
	Artifact string
	// SnapshotHash identifies the Mithril snapshot or Cardano database
	// artifact that owns the download.
	SnapshotHash string
	// ArtifactsCompleted and ArtifactsTotal are populated for aggregate
	// progress, such as the v2 immutable archive worker pool.
	ArtifactsCompleted uint64
	ArtifactsTotal     uint64
}

type ExtractOption func(*extractConfig)

type ImmutableArchiveAttempt struct {
	// Source is the local cache label or the redacted location URI.
	Source string
	// Location is the 1-based index into the artifact's immutable location
	// list, or 0 for the local cache.
	Location int
	// Err is why the attempt was rejected.
	Err error
}

type ImmutableArchiveError struct {
	ArtifactHash        string
	Epoch               uint64
	ImmutableFileNumber uint64
	// Attempts is every source tried, in order, including the local cache
	// when a cached trio was present and rejected.
	Attempts []ImmutableArchiveAttempt
	// Locations is how many published locations the artifact carried.
	Locations int
}

type MithrilStakeDistribution struct {
	Hash            string                          `json:"hash"`
	CertificateHash string                          `json:"certificate_hash"`
	Epoch           uint64                          `json:"epoch"`
	Signers         []MithrilStakeDistributionParty `json:"signers"`
}

type MithrilStakeDistributionListItem struct {
	Hash                 string   `json:"hash"`
	CertificateHash      string   `json:"certificate_hash"`
	CreatedAt            string   `json:"created_at"`
	Locations            []string `json:"locations"`
	CompressionAlgorithm string   `json:"compression_algorithm"`
	Epoch                uint64   `json:"epoch"`
}

type MithrilStakeDistributionParty struct {
	PartyID         string `json:"party_id"`
	Stake           uint64 `json:"stake"`
	VerificationKey string `json:"verification_key"`
}

type Mode int

type NetworkConfig struct {
	AggregatorURL               string
	GenesisVerificationKeyURL   string
	AncillaryVerificationKeyURL string
}

type PipelineMetrics struct {
	// contains filtered or unexported fields
}

type ProgressFunc func(DownloadProgress)

type ProtocolMessage struct {
	MessageParts map[string]string `json:"message_parts"`
}

type ProtocolParameters struct {
	K    uint64  `json:"k"`
	M    uint64  `json:"m"`
	PhiF float64 `json:"phi_f"`
}

type ResolvedStakeDistribution struct {
	Kind                     string
	MithrilStakeDistribution *MithrilStakeDistribution
	CardanoStakeDistribution *CardanoStakeDistribution
}

type SelectedArtifact struct {
	Backend         string
	Network         string
	Digest          string
	Beacon          Beacon
	CertificateHash string
}

type ServerConfig struct {
	// Store holds the produced artifacts.
	Store ArtifactStore
	// PublicBaseURL is the configured public HTTP(S) origin used in artifact
	// download locations. It is required for detail responses and must use
	// HTTPS except for loopback origins used by local deployments and tests.
	PublicBaseURL string
	// RedirectBaseURL, when set, answers artifact file requests with a
	// redirect to RedirectBaseURL + "/" + key instead of streaming the
	// object from Store. It is meant for remote stores whose objects are
	// publicly readable under that base URL.
	RedirectBaseURL string
	// Aggregator, when set, mounts its signer registration, signature and
	// stake distribution endpoints beside the artifact API.
	Aggregator *Aggregator
	// Logger receives request failures; nil discards them.
	Logger *slog.Logger
}

type SignedEntityType struct {
	// contains filtered or unexported fields
}

type SnapshotBase struct {
	Digest               string   `json:"digest"`
	Network              string   `json:"network"`
	Beacon               Beacon   `json:"beacon"`
	CertificateHash      string   `json:"certificate_hash"`
	Size                 int64    `json:"size"`
	AncillarySize        int64    `json:"ancillary_size"`
	CreatedAt            string   `json:"created_at"`
	Locations            []string `json:"locations"`
	AncillaryLocations   []string `json:"ancillary_locations"`
	CompressionAlgorithm string   `json:"compression_algorithm"`
	CardanoNodeVersion   string   `json:"cardano_node_version"`
}

type SnapshotConfig struct {
	// Feed carries the aggregator, trust keys and download limits. The
	// ancillary verification key is required. StartImmutable is ignored:
	// the restore derives the range from the ledger state. WindowChunks
	// bounds the probed files kept on disk for the load, and separately
	// each feed that loads the rest, so the trios on disk stay within it
	// except when the cutoff lies below the probe bound: the feed loading
	// the files below the probes then runs while the kept probes wait, for
	// a peak of twice WindowChunks. Zero keeps up to maxCutoffProbes probed
	// files.
	Feed ChunkFeedConfig
	// DB is the empty database to restore into, or the one holding the
	// restore to resume.
	DB *database.Database
	// StabilityWindow is the history-expiry retention, in slots: every block
	// at or above the ledger state's slot minus it is loaded.
	StabilityWindow uint64
	// CardanoNodeConfig supplies era epoch lengths to the ledger import.
	CardanoNodeConfig *cardano.CardanoNodeConfig
	// DataDir is the node's data directory. The restore downloads under it
	// when Feed.Bootstrap.DownloadDir is empty. One of the two is required.
	DataDir    string
	Logger     *slog.Logger
	OnProgress SyncProgressFunc
	// contains filtered or unexported fields
}

type SnapshotListItem struct {
	SnapshotBase
}

type SnapshotStartup int

type StakeDistributionParty struct {
	PartyID string `json:"party_id"`
	Stake   uint64 `json:"stake"`
}

type StoragePlugins struct {
	Blob     plugin.Selection
	Metadata plugin.Selection
}

type StreamConfig struct {
	// Feed configures each chunk feed the run opens. Its StartImmutable is
	// ignored: the run derives the start from the ledger tip. An empty
	// Bootstrap.DownloadDir selects a directory under DataDir. The download
	// directory must belong to this run alone: stale feed directories in it
	// are deleted before each feed opens.
	Feed ChunkFeedConfig
	// DataDir is the node's data directory. The run downloads under it when
	// Feed.Bootstrap.DownloadDir is empty, so a crash leaves nothing in the
	// OS temp directory that no later run would clean up. One of the two is
	// required.
	DataDir string
	// ChunkSlots is the number of slots each immutable file spans: the Byron
	// epoch length, 10*k from the Byron genesis, for every Cardano network.
	// It turns the ledger tip's slot into an estimate of the tip's file. Zero
	// means no estimate, and the file is found by bisection.
	ChunkSlots uint64
	// BatchChunks is the most immutable files whose last block one batch may
	// carry. Zero or negative means one.
	BatchChunks int
	// MaxBatchBlocks is the most blocks one ApplyTrustedBatch call carries;
	// a chunk with more is split across batches. Zero or negative means no
	// limit.
	MaxBatchBlocks int
	// DB holds the immutable-import marker the run resumes from and advances.
	DB *database.Database
	// Applier is the ledger the blocks are applied to. Its tip must be on the
	// certified chain.
	Applier BatchApplier
	Logger  *slog.Logger
	// Hold, when set, is called once, after the run has verified its
	// artifact and digest list and located the applier's tip, and before it
	// re-reads the tip to apply anything; the run calls the returned release
	// on every exit, after its no-progress watchdog has stopped, so a release
	// may take longer than NoProgressTimeout. Everything that asks the aggregator about the artifact
	// happens before it, so a slow or failing aggregator delays only the
	// unheld half. Nil holds nothing.
	Hold func() (release func())
	// NoProgressTimeout ends a run, with ErrStreamStalled, once it has held
	// for this long without committing a batch. Zero or negative selects
	// DefaultStreamNoProgressTimeout.
	NoProgressTimeout time.Duration
	// contains filtered or unexported fields
}

type StreamResult struct {
	// Tip is the applier's tip when the run ended.
	Tip ocommon.Point
	// Immutable is the highest immutable file whose blocks are all committed,
	// as recorded in the import marker. It is zero when no marker was written.
	Immutable uint64
	// Restarts counts replays after the applier's tip moved under a batch.
	Restarts int
}

type SyncConfig struct {
	Network                string                     // "mainnet" | "preprod" | "preview"
	DataDir                string                     // node database path
	StorageMode            string                     // "api" | "core"
	CardanoNodeConfig      *cardano.CardanoNodeConfig // genesis + Mithril verification keys; if nil, loaded from EmbeddedConfigFS for Network
	CardanoConfigPath      string                     // optional explicit config path (else the network's embedded config)
	Backend                string                     // Mithril artifact backend; same semantics as BootstrapConfig.Backend (empty selects v2)
	AggregatorURL          string                     // optional; defaults per-network
	AllowInsecureHTTP      bool                       // permit insecure/local destinations; local dev/test only
	DownloadDir            string                     // optional; defaults to <DataDir>/.mithril-cache
	DownloadIdleTimeout    string                     // optional; passed to BootstrapConfig
	DownloadMaxIdleRetries int                        // must be >= 0
	DownloadMaxBytes       int64                      // per compressed object; zero uses DefaultMaxDownloadBytes
	PinnedDigest           string                     // optional exact artifact identity for a fresh bootstrap (database hash)
	VerifyCertChain        bool
	CleanupAfterLoad       bool
	// RepairLegacyRewardState forces a same-chain Mithril reconciliation for
	// an existing database marked by the reward-pot migration. The node may
	// serve only after an artifact covers the local tip and the reconciliation
	// completes; a clean bootstrap is never selected for this path.
	RepairLegacyRewardState bool
	StoragePlugins          StoragePlugins
	RunMode                 string
	BackfillBatchSize       int
	DatabaseWorkers         int
	Tracing                 bool             // OpenTelemetry tracing enabled; forwarded to the metadata pool
	Logger                  *slog.Logger     // optional; defaults to slog.Default()
	OnProgress              SyncProgressFunc // optional
	Metrics                 *PipelineMetrics // optional; records the immutable chunk downloads
}

type SyncPhase string

type SyncProgress struct {
	Phase           SyncPhase
	Active          bool    // true while the phase is active (begin + every mid-phase tick); false only marks the phase end
	BytesDownloaded int64   // download phase
	TotalBytes      int64   // download phase
	BytesPerSecond  float64 // download/copy/backfill rate
	CurrentSlot     uint64
	TipSlot         uint64
	Percent         float64
	Count           int    // generic counter (gap blocks, blocks copied)
	Total           int    // Total complements Count for non-byte progress (e.g. ledger-import items).
	Description     string // free-form (era/stage label)
}

type SyncProgressFunc func(SyncProgress)

type SyncResult struct {
	Snapshot   *SnapshotListItem
	LedgerSlot uint64
}

type VerificationKey struct {
	Type        string
	Description string
	CborHex     string
	RawKeyBytes []byte
}

type VerificationMaterial struct {
	CertificateChain         *CertificateChainVerificationResult
	MithrilCertificate       *Certificate
	CardanoCertificate       *Certificate
	MithrilStakeDistribution *MithrilStakeDistribution
	CardanoStakeDistribution *CardanoStakeDistribution
}

type VerificationMode uint8

type VerifiedChunk struct {
	Num    uint64
	Blocks []ledger.Block
	// Raw holds the chunk's blocks undecoded, when the feed was configured
	// with RawBlocks; Blocks is then empty.
	Raw []immutable.Block
}