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

	// 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

	// 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)

	// 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)

	// 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)

	// 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 protocol parameters for a given epoch.
	GetPParams(
		uint64,
		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)

	// 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)

	// GetAddressesByStakingKey retrieves distinct address mappings for a staking key.
	GetAddressesByStakingKey(
		[]byte,
		int,
		int,
		types.Txn,
	) ([]models.AddressTransaction, 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

	// 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)

	// 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)

	// GetUtxosByAddress retrieves all UTxOs for a given address.
	GetUtxosByAddress(ledger.Address, types.Txn) ([]models.Utxo, 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.
	SetUtxoDeletedAtSlot(
		ledger.TransactionInput,
		uint64,
		types.Txn,
	) error

	// SetUtxosNotDeletedAfterSlot marks all UTxOs created after the given slot as not deleted.
	SetUtxosNotDeletedAfterSlot(uint64, types.Txn) 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

	// 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 haven't expired.
	GetActiveGovernanceProposals(
		uint64,
		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)

	// 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

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

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

	// GetDRepVotingPower calculates the voting power for a DRep by summing
	// the stake of all accounts delegated to it. Uses the current live
	// UTxO set (deleted_slot = 0) for the calculation.
	GetDRepVotingPower(
		[]byte,
		types.Txn,
	) (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

	// 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
}