database

type Database interface {
	// BeginDatabaseTransaction will start a database transaction, then you can perform CRUD on it, finally can do commit or rollback on purpose
	BeginDatabaseTransaction(ctx context.Context) (DbTransaction, error)

	// CommitTransaction performs committing the db transaction into store
	CommitTransaction(ptx DbTransaction) error

	// RollbackTransaction performs rolling back changes made by the db transaction
	RollbackTransaction(ptx DbTransaction) error

	// Close closes the underlying database connection
	Close()

	// PreparePartitionedTablesForChainId create partitioned tables for the corresponding chain-id.
	PreparePartitionedTablesForChainId(chainId string) error

	// PreparePartitionedTablesForEpochAndChainId create partitioned tables for the corresponding epoch UTC and chain-id.
	PreparePartitionedTablesForEpochAndChainId(epochUtcSeconds int64, chainId string) error

	// InsertOrUpdateRecordChainInfo inserts a new chain info record into the database.
	// If the chain info already exists, it will be updated.
	InsertOrUpdateRecordChainInfo(chainInfo dbtypes.RecordChainInfo) (insertedOrUpdated bool, err error)

	// UpdateBeJsonRpcUrlsIfExists updates the be_json_rpc_urls field of the chain info record with the given chain ID.
	// If the chain info does not exist, nothing will be updated.
	UpdateBeJsonRpcUrlsIfExists(chainId string, urls []string) (updated bool, err error)

	// GetBech32Config returns the bech32 config of the chain info record with the given chain ID.
	GetBech32Config(chainId string) (bech32Cfg dbtypes.Bech32PrefixOfChainInfo, err error)

	// IsChainPostponed returns true if the chain is postponed. If the chain is not exists, it returns false.
	IsChainPostponed(chainId string) (postponed bool, err error)

	// GetLatestIndexedBlock returns the latest indexed block height of the chain info record with the given chain ID.
	GetLatestIndexedBlock(chainId string) (height int64, postponed bool, err error)

	// SetLatestIndexedBlock updates the latest indexed block height of the chain info record with the given chain ID.
	SetLatestIndexedBlock(chainId string, height int64) error

	// InsertOrUpdateFailedBlocks inserts a batch of failed block records into the database.
	// If the record is already present, the logic fields will be updated.
	InsertOrUpdateFailedBlocks(chainId string, blocksHeight []int64, optionalReason error) error

	// GetOneFailedBlock returns the height of a failed block record of the chain with the given chain ID.
	GetOneFailedBlock(chainId string) (height int64, err error)

	// GetFailedBlocksInRange returns the heights of failed block records in the given range, inclusive.
	GetFailedBlocksInRange(chainId string, from, to int64) (blocksHeight []int64, err error)

	// RemoveFailedBlockRecord removes a failed block record from the database.
	// Typically, this is used when the failed block is successfully processed.
	RemoveFailedBlockRecord(chainId string, height int64) error
}

type DbTransaction interface {
	// CommitTransaction commits the current transaction instance, returns error if any problem happened using commit progress
	CommitTransaction() error
	// RollbackTransaction rollbacks the current transaction instance, returns error if any problem happened using rollback progress
	RollbackTransaction() error

	// SetLatestIndexedBlock updates the latest indexed block height of the chain info record with the given chain ID.
	SetLatestIndexedBlock(chainId string, height int64) error

	// InsertOrUpdateRecordsAccount inserts or updates the given accounts into the database.
	// If the account is exists, it will update the account's balance on erc20 and nft contracts,
	// the list of contracts address will be appended to the existing list distinctly.
	InsertOrUpdateRecordsAccount(accounts dbtypes.RecordsAccount) error

	// InsertRecordTransactionsIfNotExists inserts the given transactions into the database.
	// If the transaction is exists, it will do nothing.
	InsertRecordTransactionsIfNotExists(txs dbtypes.RecordsTransaction) error

	// InsertRecordsRecentAccountTransactionIfNotExists inserts the given recent account transactions into the database.
	// If the transaction is exists, it will do nothing.
	InsertRecordsRecentAccountTransactionIfNotExists(txs dbtypes.RecordsRecentAccountTransaction) error

	// InsertRecordsRefAccountToRecentTxIfNotExists inserts the given references of account to recent transaction into the database.
	// If the reference is exists, it will do nothing.
	// The record connects the recent account transaction with the account that has the transaction.
	InsertRecordsRefAccountToRecentTxIfNotExists(refs dbtypes.RecordsRefAccountToRecentTx) error

	// CleanupZeroRefCountRecentAccountTransaction call procedures to clean-up `recent_account_transaction` records
	// which have zero referent (`ref_account_to_recent_tx`).
	CleanupZeroRefCountRecentAccountTransaction() error

	// RemoveFailedBlockRecord removes a failed block record from the database.
	// Typically, this is used when the failed block is successfully processed.
	RemoveFailedBlockRecord(chainId string, height int64) error
}