mithril

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: BackendV1
	// downloads the legacy full-database tarball, BackendV2 restores
	// per-immutable archives verified against the certified merkle
	// root. Empty selects BackendV2.
	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 instead of HTTPS. 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
	// 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

	// 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: the v2 backend resolves it as a Cardano
	// database artifact hash and the v1 backend as a snapshot digest. 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) but this
	// callback is invoked 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
	// 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.
	//
	// Both bootstrap paths set 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; nil for v1, which certifies one archive
	// rather than the files inside it and so has nothing to re-check against.
	//
	// 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}. Empty if no ancillary data was downloaded.
	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. Nil when no ancillary data was obtained.
	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 will not look past a verified tree that yields no
	// state. Falling through would move the import from a tree covered by a
	// signature to one that is not, and an attacker who can empty the first can
	// then choose the second. Where nothing was verified there is no such
	// downgrade, and the fallback stays available — v1 keeps its ledger state
	// in the main archive, so looking there is how that layout works at all.
	AncillaryVerified 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.
	//
	// The ledger-state import falls back to the main extraction directory when
	// the ancillary archive carried no ledger state (v1 snapshots keep it in
	// db/ledger). ExtractDir is derived inside the download directory like
	// everything else here, so that fallback reads through a handle too rather
	// than resolving a name nothing vetted.
	ExtractRoot *os.Root
	// AncillaryArchivePath is the path to the downloaded ancillary
	// archive file. Empty if no ancillary data was downloaded.
	AncillaryArchivePath string
	// ArchivePath is the path to the downloaded archive file.
	ArchivePath 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
}

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 CertificateChainVerificationResult struct {
	Certificates       []*Certificate
	LeafCertificate    *Certificate
	GenesisCertificate *Certificate
	SignedEntityKind   string
	SnapshotDigest     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 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 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
	// 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. When nil, a per-call client
	// with keep-alives disabled is used (single-archive downloads).
	HTTPClient *http.Client
	// AllowInsecureHTTP permits URL to use plain HTTP instead of HTTPS.
	// By default, Validate rejects a non-HTTPS URL; 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
}

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 NetworkConfig struct {
	AggregatorURL               string
	GenesisVerificationKeyURL   string
	AncillaryVerificationKeyURL string
}

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 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 SnapshotListItem struct {
	SnapshotBase
}

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

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

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.json path (else "<network>/config.json")
	Backend                string                     // Mithril artifact backend; same semantics as BootstrapConfig.Backend (empty selects v2)
	AggregatorURL          string                     // optional; defaults per-network
	AllowInsecureHTTP      bool                       // permit plain-HTTP aggregator/artifact URLs; local dev/test only
	DownloadDir            string                     // optional; defaults to <DataDir>/.mithril-cache
	DownloadIdleTimeout    string                     // optional; passed to BootstrapConfig
	DownloadMaxIdleRetries int                        // must be >= 0
	VerifyCertChain        bool
	CleanupAfterLoad       bool
	StoragePlugins         StoragePlugins
	RunMode                string
	BackfillBatchSize      int
	DatabaseWorkers        int
	Logger                 *slog.Logger     // optional; defaults to slog.Default()
	OnProgress             SyncProgressFunc // optional
}

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