metadata

type BulkLoadOptimizer interface {
	SetBulkLoadPragmas() error
	RestoreNormalPragmas() error
}

type MetadataStore interface {

	// Close closes the metadata store and releases all resources.
	Close() error

	// GetCommitTimestamp retrieves the last commit timestamp from the database.
	GetCommitTimestamp() (int64, error)

	// SetCommitTimestamp sets the last commit timestamp in the database.
	// Parameter order is (timestamp, txn) to match other store methods where
	// the transaction is the final parameter.
	SetCommitTimestamp(int64, types.Txn) error

	// GetNodeSettings returns the persisted immutable node settings, or
	// nil if the database has never been initialised.
	GetNodeSettings() (*types.NodeSettings, error)

	// SetNodeSettings persists the immutable node settings via an
	// idempotent insert that succeeds on repeated calls. If the row
	// already exists, implementations must not overwrite immutable
	// fields and should only populate network fields when they are
	// currently unset so callers like checkNodeSettings can perform
	// a one-time network backfill.
	SetNodeSettings(*types.NodeSettings) error

	// Transaction creates a new metadata transaction on the write
	// connection pool. Use ReadTransaction for read-only access to
	// avoid contending with writers.
	Transaction() types.Txn

	// ReadTransaction creates a read-only metadata transaction using
	// the read connection pool (when available). This avoids blocking
	// on the write connection, which is critical for operations like
	// FindIntersect that must complete within protocol timeouts.
	ReadTransaction() types.Txn

	// AddUtxos adds one or more unspent transaction outputs to the database.
	AddUtxos(
		[]models.UtxoSlot,
		types.Txn,
	) error

	// ImportUtxos inserts UTxOs in bulk, ignoring duplicates.
	ImportUtxos([]models.Utxo, types.Txn) error

	// ImportAccount upserts an account (insert or update delegation
	// fields on conflict).
	ImportAccount(*models.Account, types.Txn) error

	// ImportPool upserts a pool and creates a registration record.
	ImportPool(
		*models.Pool,
		*models.PoolRegistration,
		types.Txn,
	) error

	// ImportDrep upserts a DRep and creates a registration record.
	ImportDrep(
		*models.Drep,
		*models.RegistrationDrep,
		types.Txn,
	) error

	// CreateDrep inserts a Drep row directly. Used by callers (e.g.
	// fixture seeding from outside the plugin packages) that already
	// have a fully-populated model and want a single-row insert without
	// the registration-record side effects of ImportDrep.
	CreateDrep(types.Txn, *models.Drep) error

	// CreateAccount inserts an Account row directly. See CreateDrep
	// for the rationale; this is the simple-insert sibling of
	// ImportAccount.
	CreateAccount(types.Txn, *models.Account) error

	// CreateUtxo inserts a Utxo row directly. The normal block-
	// application path uses AddUtxos with UtxoSlot inputs; this is
	// the simple-insert variant for callers that already have a
	// populated model.
	CreateUtxo(types.Txn, *models.Utxo) error

	// GetImportCheckpoint retrieves the checkpoint for a given
	// import key (e.g., "{digest}:{slot}"). Returns nil if no
	// checkpoint exists.
	GetImportCheckpoint(
		importKey string,
		txn types.Txn,
	) (*models.ImportCheckpoint, error)

	// SetImportCheckpoint creates or updates a checkpoint for
	// the given import key with the completed phase.
	SetImportCheckpoint(
		checkpoint *models.ImportCheckpoint,
		txn types.Txn,
	) error

	// GetPoolRegistrations retrieves all registration certificates for a pool.
	GetPoolRegistrations(
		lcommon.PoolKeyHash,
		types.Txn,
	) ([]lcommon.PoolRegistrationCertificate, error)

	// GetPool retrieves a pool by its key hash, optionally including inactive pools.
	GetPool(
		lcommon.PoolKeyHash,
		bool,
		types.Txn,
	) (*models.Pool, error)

	// GetPools retrieves pools by key hash in batch.
	GetPools(
		[]lcommon.PoolKeyHash,
		types.Txn,
	) ([]models.Pool, error)

	// GetPoolByVrfKeyHash retrieves an active pool by its VRF key hash.
	// Returns nil if no active pool uses this VRF key.
	GetPoolByVrfKeyHash(
		[]byte,
		types.Txn,
	) (*models.Pool, error)

	// GetActivePoolRelays retrieves all relays from currently active pools.
	// This is used for ledger peer discovery.
	GetActivePoolRelays(types.Txn) ([]models.PoolRegistrationRelay, error)

	// GetActivePoolKeyHashes retrieves the key hashes of all currently active pools.
	// A pool is active if it has a registration and either no retirement or
	// the retirement epoch is in the future.
	GetActivePoolKeyHashes(types.Txn) ([][]byte, error)

	// GetActivePoolKeyHashesAtSlot retrieves the key hashes of pools that were
	// active at the given slot. A pool was active at a slot if:
	// 1. It had a registration with added_slot <= slot
	// 2. Either:
	//    a. No retirement with added_slot <= slot, OR
	//    b. The most recent retirement was for an epoch that hadn't started yet, OR
	//    c. A registration occurred AFTER the most recent retirement (re-registration
	//       cancels a pending retirement)
	//
	// When determining order of events in the same slot, block_index (transaction
	// index within block) and cert_index (certificate index within transaction)
	// are used as tie-breakers since cert_index resets per transaction. The full
	// ordering is: added_slot DESC, block_index DESC, cert_index DESC.
	// This handles cases where registration and retirement occur in different
	// transactions within the same block.
	//
	// This is used for stake snapshot calculations at historical points.
	//
	// Returns types.ErrNoEpochData (wrapped) if epoch data has not been synced
	// for the requested slot. Callers should use errors.Is() to check.
	GetActivePoolKeyHashesAtSlot(uint64, types.Txn) ([][]byte, error)

	// GetStakeByPool returns the total delegated stake and delegator count for a pool.
	// This aggregates all accounts delegated to the pool and sums their UTxO values.
	GetStakeByPool(
		[]byte,
		types.Txn,
	) (uint64, uint64, error) // (totalStake, delegatorCount, error)

	// GetStakeByPools returns delegated stake for multiple pools in a single query.
	// Returns maps of pool key hash -> total stake and pool key hash -> delegator count.
	GetStakeByPools(
		[][]byte,
		types.Txn,
	) (map[string]uint64, map[string]uint64, error)

	// GetStakeRegistrations retrieves all stake registration certificates for an account.
	GetStakeRegistrations(
		[]byte,
		types.Txn,
	) ([]lcommon.StakeRegistrationCertificate, error)

	// GetTip retrieves the current chain tip.
	GetTip(types.Txn) (ochainsync.Tip, error)

	// GetAccount retrieves an account by stake key, optionally including inactive accounts.
	GetAccount(
		[]byte,
		bool,
		types.Txn,
	) (*models.Account, error)

	// GetAccounts retrieves multiple accounts by stake key in a single query,
	// optionally including inactive accounts. The returned map is keyed by
	// string(StakingKey); stake keys with no matching row are omitted. An
	// empty input returns an empty (non-nil) map and no error.
	GetAccounts(
		[][]byte,
		bool,
		types.Txn,
	) (map[string]*models.Account, error)

	// AddAccountReward credits a reward account by stake credential.
	AddAccountReward(
		[]byte,
		uint64,
		uint64,
		types.Txn,
	) error

	// DeleteAccountRewardsAfterSlot reverts reward credits recorded after
	// the given slot and deletes their journal entries.
	DeleteAccountRewardsAfterSlot(uint64, types.Txn) error

	// GetBlockNonce retrieves a block nonce for a given point.
	GetBlockNonce(
		ocommon.Point,
		types.Txn,
	) ([]byte, error)

	// GetBlockNoncesInSlotRange retrieves all block nonces in [startSlot, endSlot).
	GetBlockNoncesInSlotRange(
		startSlot uint64,
		endSlot uint64,
		txn types.Txn,
	) ([]models.BlockNonce, error)

	// GetLastBlockNonceInRange retrieves the block nonce with the highest slot
	// in [startSlot, endSlot). Returns nil nonce and no error if none found.
	GetLastBlockNonceInRange(
		startSlot uint64,
		endSlot uint64,
		txn types.Txn,
	) ([]byte, error)

	// GetDatum retrieves a datum by its hash, returning nil if not found.
	GetDatum(
		lcommon.Blake2b256,
		types.Txn,
	) (*models.Datum, error)

	// GetDrep retrieves a DRep by its credential, optionally including inactive DReps.
	GetDrep(
		[]byte,
		bool,
		types.Txn,
	) (*models.Drep, error)

	// GetActiveDreps retrieves all active DReps.
	GetActiveDreps(types.Txn) ([]*models.Drep, error)

	// GetPParams retrieves the latest protocol-parameters row at
	// epoch <= the supplied epoch whose stored era_id matches the
	// supplied era. The era filter is required: at era boundaries the
	// rollover path writes both an old-era row (post-pparams-update)
	// and a new-era row (transitionToEra) at the same epoch, and an
	// unfiltered query collapses them to whichever was inserted last
	// — which is the new-era shape. Callers commit to a specific
	// era's struct decoder, so the row's era_id must match the chosen
	// decoder for the CBOR to decode.
	GetPParams(
		uint64,
		uint,
		types.Txn,
	) ([]models.PParams, error)

	// GetPParamUpdates retrieves protocol parameter updates for a given epoch.
	GetPParamUpdates(
		uint64,
		types.Txn,
	) ([]models.PParamUpdate, error)

	// GetUtxo retrieves an unspent transaction output by transaction ID and index.
	GetUtxo(
		[]byte,
		uint32,
		types.Txn,
	) (*models.Utxo, error)

	// GetUtxoIncludingSpent retrieves a transaction output by
	// transaction ID and index, including spent outputs.
	GetUtxoIncludingSpent(
		[]byte,
		uint32,
		types.Txn,
	) (*models.Utxo, error)

	// GetTransactionByHash retrieves a transaction by its hash.
	GetTransactionByHash(
		[]byte,
		types.Txn,
	) (*models.Transaction, error)

	// GetTransactionSlotByHash returns the slot of the block that
	// contains the given tx hash. The bool result is false when no
	// such transaction is recorded. Lighter than GetTransactionByHash
	// because it skips loading inputs/outputs/witnesses.
	GetTransactionSlotByHash(
		[]byte,
		types.Txn,
	) (uint64, bool, error)

	// GetTransactionIDByHash returns the primary-key ID of the
	// transaction with the given hash. The bool result is false when
	// no such transaction is recorded. Used by UTxO recovery paths
	// that need to populate the producer transaction FK on rows they
	// re-import without paying the cost of loading every association.
	GetTransactionIDByHash(
		[]byte,
		types.Txn,
	) (uint, bool, error)

	// GetTransactionsByHashes retrieves transactions by their hashes.
	GetTransactionsByHashes(
		[][]byte,
		types.Txn,
	) ([]models.Transaction, error)

	// GetTransactionsByBlockHash retrieves all transactions
	// for a given block hash, ordered by block_index.
	GetTransactionsByBlockHash(
		[]byte,
		types.Txn,
	) ([]models.Transaction, error)

	// GetTransactionsByAddress retrieves transactions involving
	// the provided payment/staking key pair with pagination and ordering.
	GetTransactionsByAddress(
		[]byte,
		[]byte,
		int,
		int,
		string,
		types.Txn,
	) ([]models.Transaction, error)

	// CountTransactionsByAddress returns the total number of
	// transactions involving the provided payment/staking
	// key pair.
	CountTransactionsByAddress(
		[]byte,
		[]byte,
		types.Txn,
	) (int, error)

	// GetAddressesByStakingKey retrieves distinct address mappings for a staking key.
	GetAddressesByStakingKey(
		[]byte,
		int,
		int,
		types.Txn,
	) ([]models.AddressTransaction, error)

	// GetTransactionsByMetadataLabel retrieves transactions that include
	// metadata for the given label.
	GetTransactionsByMetadataLabel(
		uint64,
		int,
		int,
		bool,
		types.Txn,
	) ([]models.Transaction, error)

	// CountTransactionsByMetadataLabel returns the total number of
	// transactions that include metadata for the given label.
	CountTransactionsByMetadataLabel(
		uint64,
		types.Txn,
	) (int, error)

	// GetAssetByPolicyAndName returns a live asset row for the provided
	// policy ID and asset name. Implementations return an empty model and
	// no error when the asset is not found.
	GetAssetByPolicyAndName(
		lcommon.Blake2b224,
		[]byte,
		types.Txn,
	) (models.Asset, error)

	// GetAssetQuantityByPolicyAndName returns the sum of live quantities for
	// the provided policy ID and asset name across all matching UTxOs.
	GetAssetQuantityByPolicyAndName(
		lcommon.Blake2b224,
		[]byte,
		types.Txn,
	) (uint64, error)

	// GetScript retrieves a script by its hash.
	GetScript(
		lcommon.ScriptHash,
		types.Txn,
	) (*models.Script, error)

	// SetBlockNonce stores a block nonce for a given block hash and slot.
	SetBlockNonce(
		[]byte,
		uint64,
		[]byte,
		bool,
		types.Txn,
	) error

	// SetDatum stores a datum with its hash and slot.
	SetDatum(
		lcommon.Blake2b256,
		[]byte,
		uint64,
		types.Txn,
	) error

	// SetEpoch sets epoch information.
	SetEpoch(
		uint64,
		uint64,
		[]byte,
		[]byte,
		[]byte,
		[]byte,
		uint,
		uint,
		uint,
		types.Txn,
	) error

	// SetPParams stores protocol parameters.
	SetPParams(
		[]byte,
		uint64,
		uint64,
		uint,
		types.Txn,
	) error

	// SetPParamUpdate stores a protocol parameter update.
	SetPParamUpdate(
		[]byte,
		[]byte,
		uint64,
		uint64,
		types.Txn,
	) error

	// SetTip sets the current chain tip.
	SetTip(
		ochainsync.Tip,
		types.Txn,
	) error

	// SetTransaction stores a transaction with its metadata.
	SetTransaction(
		lcommon.Transaction,
		ocommon.Point,
		uint32,
		map[int]uint64,
		types.Txn,
	) error

	// SetGapBlockTransaction stores a transaction record and its
	// produced outputs without looking up or consuming input UTxOs.
	// This is used for mithril gap blocks where the snapshot's UTxO
	// set already reflects the correct spent/unspent state.
	SetGapBlockTransaction(
		lcommon.Transaction,
		ocommon.Point,
		uint32,
		types.Txn,
	) error

	// SetGenesisTransaction stores a genesis transaction record.
	// Genesis transactions have no inputs, witnesses, or fees - just outputs.
	SetGenesisTransaction(
		hash []byte,
		blockHash []byte,
		outputs []models.Utxo,
		txn types.Txn,
	) error

	// SetGenesisStaking stores genesis pool registrations and stake
	// delegations from the shelley-genesis.json staking section.
	// pools maps pool key hash (hex) to its registration certificate.
	// stakeDelegations maps staking credential hash (hex) to pool key hash (hex).
	SetGenesisStaking(
		pools map[string]lcommon.PoolRegistrationCertificate,
		stakeDelegations map[string]string,
		blockHash []byte,
		txn types.Txn,
	) error

	// DeleteBlockNoncesBeforeSlot removes block nonces older than the given slot.
	DeleteBlockNoncesBeforeSlot(uint64, types.Txn) error

	// DeleteBlockNoncesBeforeSlotWithoutCheckpoints removes block nonces older than the given slot,
	// excluding checkpoint nonces.
	DeleteBlockNoncesBeforeSlotWithoutCheckpoints(
		uint64,
		types.Txn,
	) error

	// DeleteBlockNoncesAfterPoint removes block nonces after a rollback
	// point and competing nonces at the same slot.
	DeleteBlockNoncesAfterPoint(ocommon.Point, types.Txn) error

	// DeleteUtxo removes a single unspent transaction output.
	DeleteUtxo(models.UtxoId, types.Txn) error

	// DeleteUtxos removes multiple unspent transaction outputs.
	DeleteUtxos([]models.UtxoId, types.Txn) error

	// DeleteUtxosAfterSlot removes all UTxOs created after the given slot.
	DeleteUtxosAfterSlot(uint64, types.Txn) error

	// GetEpochsByEra retrieves all epochs for a given era.
	GetEpochsByEra(uint, types.Txn) ([]models.Epoch, error)

	// GetEpoch retrieves a single epoch by its ID.
	// Returns nil if the epoch is not found.
	GetEpoch(uint64, types.Txn) (*models.Epoch, error)

	// GetEpochs retrieves all epochs.
	GetEpochs(types.Txn) ([]models.Epoch, error)

	// GetEpochBySlot retrieves the epoch containing the given slot.
	// Returns nil if no matching epoch exists.
	GetEpochBySlot(uint64, types.Txn) (*models.Epoch, error)

	// DeleteEpochsAfterSlot removes all epoch entries whose start slot
	// is after the given slot. Used during chain rollback to discard
	// epoch nonces that were computed from rolled-back blocks.
	DeleteEpochsAfterSlot(uint64, types.Txn) error

	// GetUtxosAddedAfterSlot retrieves all UTxOs added after the given slot.
	GetUtxosAddedAfterSlot(uint64, types.Txn) ([]models.Utxo, error)

	// GetLiveUtxosBySlot returns the references ({TxId, OutputIdx}) of all
	// live UTxOs (deleted_slot = 0) created at the given slot. Used by the
	// pruner to materialize block-referenced UTxO bytes before deleting the
	// source block.
	GetLiveUtxosBySlot(uint64, types.Txn) ([]models.UtxoId, error)

	// GetUtxosByAddress retrieves all UTxOs for a given address.
	GetUtxosByAddress(ledger.Address, types.Txn) ([]models.Utxo, error)

	// GetUtxosByAddressWithOrdering runs q against live UTxOs with ordering metadata.
	// See models.UtxoWithOrderingQuery. q must be non-nil.
	GetUtxosByAddressWithOrdering(
		*models.UtxoWithOrderingQuery,
		types.Txn,
	) ([]models.UtxoWithOrdering, error)

	// GetUtxosByAddressAtSlot retrieves all UTxOs for a given address at a specific slot.
	GetUtxosByAddressAtSlot(
		lcommon.Address,
		uint64,
		types.Txn,
	) ([]models.Utxo, error)

	// GetUtxosByAssets retrieves all UTxOs that contain the specified assets.
	// Pass nil for assetName to match all assets under the policy, or empty []byte{} to match assets with empty names.
	GetUtxosByAssets(
		policyId []byte,
		assetName []byte,
		txn types.Txn,
	) ([]models.Utxo, error)

	// GetUtxosDeletedBeforeSlot retrieves UTxOs deleted before the given slot, up to the specified limit.
	GetUtxosDeletedBeforeSlot(
		uint64,
		int,
		types.Txn,
	) ([]models.Utxo, error)

	// SetUtxoDeletedAtSlot marks a UTxO as deleted at the given slot
	// and records the hash of the transaction that consumed it.
	SetUtxoDeletedAtSlot(
		input ledger.TransactionInput,
		deletedAtSlot uint64,
		spenderHash []byte,
		txn types.Txn,
	) error

	// SetUtxosNotDeletedAfterSlot marks all UTxOs created after the given slot as not deleted.
	SetUtxosNotDeletedAfterSlot(uint64, types.Txn) error

	// IterateLiveUtxos invokes fn once for each live UTxO row
	// (DeletedSlot == 0) in unspecified order. fn receives a
	// pointer to a row that is reused between callbacks — copy
	// out anything you intend to retain. Returning a non-nil
	// error from fn aborts iteration and that error is propagated
	// up. The intended callers iterate, classify, and (optionally)
	// hand a list of UtxoKeys to MarkUtxosDeletedAtSlot;
	// implementations are free to page or stream the underlying
	// query as long as the callback contract is honored.
	IterateLiveUtxos(
		txn types.Txn,
		fn func(*models.Utxo) error,
	) error

	// MarkUtxosDeletedAtSlot marks every live UTxO row matching one
	// of refs as deleted at atSlot. Refs that don't match any live
	// row are silently ignored (the SQL filter is deleted_slot == 0,
	// so already-deleted rows don't get rewritten). Rollback
	// un-deletion is handled by SetUtxosNotDeletedAfterSlot.
	MarkUtxosDeletedAtSlot(
		txn types.Txn,
		refs []types.UtxoKey,
		atSlot uint64,
	) error

	// SavePoolStakeSnapshot saves a single pool stake snapshot.
	SavePoolStakeSnapshot(
		*models.PoolStakeSnapshot,
		types.Txn,
	) error

	// SavePoolStakeSnapshots saves multiple pool stake snapshots in batch.
	SavePoolStakeSnapshots(
		[]*models.PoolStakeSnapshot,
		types.Txn,
	) error

	// GetPoolStakeSnapshot retrieves a specific pool's stake snapshot for an epoch.
	GetPoolStakeSnapshot(
		uint64,
		string,
		[]byte,
		types.Txn,
	) (*models.PoolStakeSnapshot, error)

	// GetPoolStakeSnapshotsByEpoch retrieves all pool stake snapshots for an epoch.
	GetPoolStakeSnapshotsByEpoch(
		uint64,
		string,
		types.Txn,
	) ([]*models.PoolStakeSnapshot, error)

	// GetTotalActiveStake returns the sum of all pool stakes for an epoch.
	GetTotalActiveStake(
		uint64,
		string,
		types.Txn,
	) (uint64, error)

	// SaveEpochSummary saves an epoch summary.
	SaveEpochSummary(
		*models.EpochSummary,
		types.Txn,
	) error

	// GetEpochSummary retrieves the summary for a specific epoch.
	GetEpochSummary(
		uint64,
		types.Txn,
	) (*models.EpochSummary, error)

	// GetLatestEpochSummary retrieves the most recent epoch summary.
	GetLatestEpochSummary(types.Txn) (*models.EpochSummary, error)

	// DeletePoolStakeSnapshotsForEpoch deletes snapshots for a specific epoch and type.
	DeletePoolStakeSnapshotsForEpoch(
		uint64,
		string,
		types.Txn,
	) error

	// DeletePoolStakeSnapshotsAfterEpoch deletes all snapshots after a given epoch.
	DeletePoolStakeSnapshotsAfterEpoch(uint64, types.Txn) error

	// DeletePoolStakeSnapshotsBeforeEpoch deletes all snapshots before a given epoch.
	DeletePoolStakeSnapshotsBeforeEpoch(uint64, types.Txn) error

	// DeleteEpochSummariesAfterEpoch deletes all epoch summaries after a given epoch.
	DeleteEpochSummariesAfterEpoch(uint64, types.Txn) error

	// DeleteEpochSummariesBeforeEpoch deletes all epoch summaries before a given epoch.
	DeleteEpochSummariesBeforeEpoch(uint64, types.Txn) error

	// GetTransactionHashesAfterSlot returns transaction hashes for transactions added after the given slot.
	// This is used for blob cleanup during rollback/truncation.
	GetTransactionHashesAfterSlot(uint64, types.Txn) ([][]byte, error)

	// DeleteTransactionsAfterSlot removes transaction records added after the given slot.
	// Child records are automatically removed via CASCADE constraints.
	DeleteTransactionsAfterSlot(uint64, types.Txn) error

	// DeleteAddressTransactionsAfterSlot removes address-transaction mappings
	// for transactions added after the given slot.
	DeleteAddressTransactionsAfterSlot(uint64, types.Txn) error

	// DeleteTransactionMetadataLabelsAfterSlot removes transaction metadata
	// label index records added after the given slot.
	DeleteTransactionMetadataLabelsAfterSlot(uint64, types.Txn) error

	// GetGovernanceProposal retrieves a governance proposal by transaction hash and action index.
	GetGovernanceProposal(
		[]byte,
		uint32,
		types.Txn,
	) (*models.GovernanceProposal, error)

	// GetActiveGovernanceProposals retrieves all governance proposals that
	// are still in the active pool (not expired, not enacted, not marked
	// expired, not soft-deleted).
	GetActiveGovernanceProposals(
		uint64,
		types.Txn,
	) ([]*models.GovernanceProposal, error)

	// GetRatifiedGovernanceProposals returns proposals that have been
	// ratified but not yet enacted. Used at epoch start by enactment.
	GetRatifiedGovernanceProposals(
		types.Txn,
	) ([]*models.GovernanceProposal, error)

	// GetExpiringGovernanceProposals returns proposals whose
	// `expires_epoch` is strictly less than the given epoch and that
	// have not yet been enacted, expired, or soft-deleted. Used at
	// epoch boundaries to mark expired proposals and return deposits.
	GetExpiringGovernanceProposals(
		epoch uint64,
		txn types.Txn,
	) ([]*models.GovernanceProposal, error)

	// GetLastEnactedGovernanceProposal returns the most recently enacted
	// proposal whose action_type is in the given set, or nil if none
	// exist. Callers pass the set of action types that share a chain
	// root per CIP-1694 (e.g., NoConfidence + UpdateCommittee together).
	// Used to resolve governance action chain roots at ratification
	// time.
	GetLastEnactedGovernanceProposal(
		actionTypes []uint8,
		txn types.Txn,
	) (*models.GovernanceProposal, error)

	// SetGovernanceProposal creates or updates a governance proposal.
	SetGovernanceProposal(
		*models.GovernanceProposal,
		types.Txn,
	) error

	// GetGovernanceVotes retrieves all votes for a governance proposal.
	GetGovernanceVotes(
		uint,
		types.Txn,
	) ([]*models.GovernanceVote, error)

	// SetGovernanceVote records a vote on a governance proposal.
	SetGovernanceVote(
		*models.GovernanceVote,
		types.Txn,
	) error

	// GetCommitteeMember retrieves a committee member by cold key.
	GetCommitteeMember(
		[]byte,
		types.Txn,
	) (*models.AuthCommitteeHot, error)

	// GetActiveCommitteeMembers retrieves all active committee members.
	GetActiveCommitteeMembers(types.Txn) ([]*models.AuthCommitteeHot, error)

	// IsCommitteeMemberResigned checks if a committee member has resigned.
	IsCommitteeMemberResigned(
		[]byte,
		types.Txn,
	) (bool, error)

	// GetResignedCommitteeMembers returns the cold credentials whose
	// latest resignation is after their latest authorization.
	GetResignedCommitteeMembers(
		[][]byte,
		types.Txn,
	) (map[string]bool, error)

	// GetCommitteeActiveCount returns the number of active (non-resigned)
	// committee members.
	GetCommitteeActiveCount(types.Txn) (int, error)

	// SetCommitteeMembers upserts committee members imported from a
	// Mithril snapshot. On conflict (same cold_cred_hash), the
	// expires_epoch and added_slot are updated.
	SetCommitteeMembers(
		[]*models.CommitteeMember,
		types.Txn,
	) error

	// SetCommitteeQuorum stores the quorum threshold enacted with a
	// committee update.
	SetCommitteeQuorum(*types.Rat, uint64, types.Txn) error

	// ClearCommitteeQuorum records that the committee has no
	// enacted quorum as of the given slot. Used by NoConfidence
	// enactment so GetCommitteeQuorum falls back to Conway
	// genesis until a subsequent UpdateCommittee sets a new
	// quorum.
	ClearCommitteeQuorum(uint64, types.Txn) error

	// GetCommitteeQuorum retrieves the latest enacted committee quorum.
	// Returns (nil, nil) when no quorum has been enacted or when the
	// most recent record is a ClearCommitteeQuorum marker.
	GetCommitteeQuorum(types.Txn) (*types.Rat, error)

	// GetCommitteeMembers retrieves all active (non-deleted)
	// snapshot-imported committee members.
	GetCommitteeMembers(types.Txn) ([]*models.CommitteeMember, error)

	// GetCommitteeMembersIncludeDeleted retrieves every committee
	// member row, including rows whose deleted_slot is set. Used to
	// distinguish "committee never seated" from "committee voted out
	// via NoConfidence" — the latter leaves every row soft-deleted,
	// which GetCommitteeMembers would hide.
	GetCommitteeMembersIncludeDeleted(
		types.Txn,
	) ([]*models.CommitteeMember, error)

	// DeleteCommitteeMembersAfterSlot removes committee state added
	// after the given slot and clears deleted_slot for any members
	// soft-deleted after that slot. Used during chain rollbacks.
	DeleteCommitteeMembersAfterSlot(uint64, types.Txn) error

	// SoftDeleteCommitteeMembers marks the given cold credential hashes
	// as removed by setting deleted_slot. Used by governance enactment
	// to remove members (UpdateCommittee/NoConfidence action).
	SoftDeleteCommitteeMembers(
		coldCredHashes [][]byte,
		slot uint64,
		txn types.Txn,
	) error

	// SoftDeleteAllCommitteeMembers marks all active committee members as
	// removed. Used by governance enactment for NoConfidence actions.
	SoftDeleteAllCommitteeMembers(
		slot uint64,
		txn types.Txn,
	) error

	// InsertDrepIfAbsent inserts a minimal DRep row when no record
	// exists for the given credential. If a row already exists, it is
	// left untouched: added_slot, anchor_url, anchor_hash, and active
	// are never overwritten. Used on the vote-replay recovery path to
	// recreate rows lost during recovery/bootstrap without clobbering
	// real registration metadata.
	InsertDrepIfAbsent(
		cred []byte,
		slot uint64,
		url string,
		hash []byte,
		active bool,
		txn types.Txn,
	) error

	// GetDRepVotingPower calculates the voting power for a DRep by summing
	// the current stake of all delegated accounts, approximated from live
	// UTxO balance plus reward-account balance.
	GetDRepVotingPower(
		[]byte,
		types.Txn,
	) (uint64, error)

	// GetDRepVotingPowerBatch is the batch form of GetDRepVotingPower.
	// Returns a credential-to-power map; credentials with no delegated
	// stake are omitted. Used by governance tallying to avoid N+1
	// per-DRep lookups.
	GetDRepVotingPowerBatch(
		drepCredentials [][]byte,
		txn types.Txn,
	) (map[string]uint64, error)

	// GetDRepVotingPowerByType returns voting power grouped by DRep
	// delegation type. This is used for predefined DRep options such
	// as AlwaysAbstain and AlwaysNoConfidence, which do not have a
	// credential hash.
	GetDRepVotingPowerByType(
		drepTypes []uint64,
		txn types.Txn,
	) (map[uint64]uint64, error)

	// UpdateDRepActivity updates the DRep's last activity epoch and
	// recalculates the expiry epoch.
	UpdateDRepActivity(
		[]byte,
		uint64,
		uint64,
		types.Txn,
	) error

	// GetExpiredDReps retrieves all active DReps whose expiry epoch is at
	// or before the given epoch.
	GetExpiredDReps(
		uint64,
		types.Txn,
	) ([]*models.Drep, error)

	// GetConstitution retrieves the current constitution.
	GetConstitution(types.Txn) (*models.Constitution, error)

	// SetConstitution sets the constitution.
	SetConstitution(
		*models.Constitution,
		types.Txn,
	) error

	// DeleteConstitutionsAfterSlot removes constitutions added after the given slot
	// and clears deleted_slot for any that were soft-deleted after that slot.
	// This is used during chain rollbacks.
	DeleteConstitutionsAfterSlot(uint64, types.Txn) error

	// SetNetworkState stores the treasury and reserves balances.
	SetNetworkState(
		treasury, reserves uint64,
		slot uint64,
		txn types.Txn,
	) error

	// GetNetworkState retrieves the most recent network state.
	GetNetworkState(types.Txn) (*models.NetworkState, error)

	// DeleteNetworkStateAfterSlot removes network state records
	// added after the given slot. This is used during chain
	// rollbacks.
	DeleteNetworkStateAfterSlot(uint64, types.Txn) error

	// DeleteGovernanceProposalsAfterSlot removes proposals added after the given slot
	// and clears deleted_slot for any that were soft-deleted after that slot.
	DeleteGovernanceProposalsAfterSlot(uint64, types.Txn) error

	// DeleteGovernanceVotesAfterSlot removes votes added after the given slot
	// and clears deleted_slot for any that were soft-deleted after that slot.
	DeleteGovernanceVotesAfterSlot(uint64, types.Txn) error

	// DeleteCertificatesAfterSlot removes all certificate records added after
	// the given slot. This is used during chain rollbacks to undo certificate
	// state changes.
	DeleteCertificatesAfterSlot(uint64, types.Txn) error

	// RestoreAccountStateAtSlot reverts account delegation state to the given
	// slot. For accounts modified after the slot, this restores their Pool and
	// Drep delegations to the state they had at the given slot, or deletes
	// them if they were registered after that slot.
	RestoreAccountStateAtSlot(uint64, types.Txn) error

	// RestorePoolStateAtSlot reverts pool state to the given slot. Pools
	// registered only after the slot are deleted; remaining pools have their
	// denormalized fields restored from the most recent registration at or
	// before the slot.
	RestorePoolStateAtSlot(uint64, types.Txn) error

	// RestoreDrepStateAtSlot reverts DRep state to the given slot. DReps
	// registered only after the slot are deleted; remaining DReps have their
	// anchor and active status restored.
	RestoreDrepStateAtSlot(uint64, types.Txn) error

	// ClearDanglingDRepDelegations implements the cardano-ledger Conway
	// HARDFORK STS rule for protocol major version 10 (Plomin, mainnet
	// January 2025, Cardano/Conway/Rules/HardFork.hs updateDRepDelegations).
	// For each account with a credential-backed DRep delegation
	// (DrepType 0 or 1), if the target DRep credential is not currently
	// registered as an active DRep, clear the delegation. Pseudo-DRep
	// delegations (AlwaysAbstain, AlwaysNoConfidence) are preserved.
	// Updates Account.AddedSlot to atSlot on every row it modifies so the
	// rewritten row is excluded from a subsequent rollback restore
	// targeting any slot before atSlot (the restore filters on
	// `added_slot <= targetSlot` and falls back to prior certificate
	// history). Returns the number of accounts updated.
	ClearDanglingDRepDelegations(atSlot uint64, txn types.Txn) (int, error)

	// DeletePParamsAfterSlot removes protocol parameter records added after
	// the given slot.
	DeletePParamsAfterSlot(uint64, types.Txn) error

	// DeletePParamUpdatesAfterSlot removes protocol parameter update records
	// added after the given slot.
	DeletePParamUpdatesAfterSlot(uint64, types.Txn) error

	// GetSyncState retrieves a sync state value by key.
	// Returns empty string if the key does not exist.
	GetSyncState(string, types.Txn) (string, error)

	// SetSyncState stores or updates a sync state value.
	SetSyncState(string, string, types.Txn) error

	// DeleteSyncState removes a sync state key.
	DeleteSyncState(string, types.Txn) error

	// ClearSyncState removes all sync state entries.
	ClearSyncState(types.Txn) error

	// GetBackfillCheckpoint retrieves a backfill checkpoint by phase.
	// Returns nil (not error) if no checkpoint exists for the phase.
	GetBackfillCheckpoint(
		phase string,
		txn types.Txn,
	) (*models.BackfillCheckpoint, error)

	// SetBackfillCheckpoint creates or updates a backfill checkpoint,
	// upserting on the Phase column.
	SetBackfillCheckpoint(
		checkpoint *models.BackfillCheckpoint,
		txn types.Txn,
	) error

	// DiskSize returns the on-disk size of the metadata store in bytes.
	// Returns 0 for remote databases where local size is not meaningful.
	DiskSize() (int64, error)
}