driver

type ActionType int

type AuditTransactionStore interface {
	// Close closes the database
	Close() error

	// NewTransactionStoreTransaction opens an atomic database transaction. It must be committed or discarded.
	NewTransactionStoreTransaction() (TransactionStoreTransaction, error)

	// SetStatus sets the status of a TokenRequest
	// (and with that, the associated Movement and Transaction)
	SetStatus(ctx context.Context, txID string, status TxStatus, message string) error

	// GetStatus returns the status of a given transaction.
	// It returns an error if the transaction is not found
	GetStatus(ctx context.Context, txID string) (TxStatus, string, error)

	// QueryTransactions returns a list of transactions that match the passed params
	QueryTransactions(ctx context.Context, params QueryTransactionsParams, pagination driver.Pagination) (*driver.PageIterator[*TransactionRecord], error)

	// QueryMovements returns a list of movement records
	QueryMovements(ctx context.Context, params QueryMovementsParams) ([]*MovementRecord, error)

	// QueryTokenRequests returns an iterator over the token requests matching the passed params
	QueryTokenRequests(ctx context.Context, params QueryTokenRequestsParams) (TokenRequestIterator, error)

	// GetTokenRequest returns the token request bound to the passed transaction id, if available.
	// It returns nil without error if the key is not found.
	GetTokenRequest(ctx context.Context, txID string) ([]byte, error)

	// GetTokenRequests returns the token requests bound to the given tx ids
	// in a single query. Missing tx ids are absent from the returned map.
	// Empty input returns an empty map without touching the database.
	GetTokenRequests(ctx context.Context, txIDs []string) (map[string][]byte, error)

	// AcquireRecoveryLeadership tries to acquire the PostgreSQL advisory lock backing the sweeper leader election.
	// If acquired is false, leadership was not obtained and the returned lease must be nil.
	AcquireRecoveryLeadership(ctx context.Context, lockID int64) (RecoveryLeadership, bool, error)

	// ClaimPendingTransactions atomically claims a batch of Pending transactions for recovery processing.
	// Transactions whose recovery lease expired are eligible again.
	// Returns the minimal projection (TxID + StoredAt) needed by the recovery loop;
	// callers do not need the full TransactionRecord.
	ClaimPendingTransactions(ctx context.Context, params RecoveryClaimParams) ([]*RecoveryClaim, error)

	// ReleaseRecoveryClaim clears the recovery claim metadata for the given transaction if owned by owner.
	// The message parameter is stored for audit/debugging purposes.
	ReleaseRecoveryClaim(ctx context.Context, txID string, owner string, message string) error

	// PrefixedTableName returns the formatted table name for the given logical table name,
	// following the persistence naming rules of this store.
	PrefixedTableName(name string) string
}

type CertificationStore interface {
	// ExistsCertification returns true if a certification for the passed token exists,
	// false otherwise
	ExistsCertification(ctx context.Context, id *token.ID) bool

	// StoreCertifications stores the passed certifications
	StoreCertifications(ctx context.Context, certifications map[*token.ID][]byte) error

	// GetCertifications returns the certifications of the passed tokens.
	// For each token, the callback function is invoked.
	// If a token doesn't have a certification, the function returns an error
	GetCertifications(ctx context.Context, ids []*token.ID) ([][]byte, error)
	// Close closes the databases
	Close() error
}

type CleanupLeadership interface {
	// Close releases the leadership and any associated resources
	Close() error
}

type ColumnKey = driver2.ColumnKey

type Config = driver.Config

type ConfigProvider interface {
	UnmarshalKey(key string, rawVal any) error
	GetString(key string) string
	GetBool(key string) bool
	IsSet(key string) bool
	TranslatePath(path string) string
}

type DeletedToken struct {
	// TxID is the ID of the transaction that created the token
	TxID string
	// Index is the index in the transaction
	Index uint64
	// OwnerIdentity is the serialized owner identity used to derive SKIs for key deletion
	OwnerIdentity []byte
	// OwnerType is the type of the owner identity (e.g., "idemix", "x509")
	OwnerType string
	// DeletedAt is when the token was marked as deleted
	DeletedAt time.Time
}

type Driver interface {
	NewTokenLock(driver.PersistenceName, ...string) (TokenLockStore, error)

	NewWallet(driver.PersistenceName, ...string) (WalletStore, error)

	NewIdentity(driver.PersistenceName, ...string) (IdentityStore, error)

	NewToken(driver.PersistenceName, ...string) (TokenStore, error)

	NewAuditTransaction(driver.PersistenceName, ...string) (AuditTransactionStore, error)

	NewOwnerTransaction(driver.PersistenceName, ...string) (TokenTransactionStore, error)

	NewEndorser(driver.PersistenceName, ...string) (EndorserStore, error)

	NewKeyStore(name driver.PersistenceName, params ...string) (KeyStore, error)
}

type EndorserStore interface {
	// Close closes the database
	Close() error

	// NewEndorserStoreTransaction opens an atomic database transaction. It must be committed or discarded.
	NewEndorserStoreTransaction() (EndorserStoreTransaction, error)

	// QueryValidations returns a list of validation records
	QueryValidations(ctx context.Context, params QueryValidationRecordsParams) (ValidationRecordsIterator, error)

	// GetStatus returns the status of a given transaction from the validation records.
	// It returns an error if the transaction is not found
	GetStatus(ctx context.Context, txID string) (TxStatus, string, error)
}

type EndorserStoreTransaction interface {
	Transaction

	// AddValidationRecord adds a new validation record for the given params.
	// The token request is stored directly in the validation table.
	AddValidationRecord(ctx context.Context, txID string, tokenRequest []byte, meta map[string][]byte, ppHash driver.PPHash) error

	// SetStatus sets the status of a validation record
	SetStatus(ctx context.Context, txID string, status TxStatus, message string) error
}

type IdentityConfiguration = driver.IdentityConfiguration

type IdentityStore = idriver.IdentityStoreService

type KeyStore = idriver.Keystore

type MovementDirection int

type MovementRecord struct {
	// TxID is the transaction ID
	TxID string
	// EnrollmentID is the enrollment ID of the account that is receiving or sending
	EnrollmentID string
	// TokenType is the type of token
	TokenType token2.Type
	// Amount is positive if tokens are received. Negative otherwise
	Amount *big.Int
	// Timestamp is the time the transaction was submitted to the db
	Timestamp time.Time
	// Status is the status of the transaction
	Status TxStatus
}

type NamedDriver = driver2.NamedDriver[Driver]

type Operation = driver2.Operation

type QueryMovementsParams struct {
	// EnrollmentIDs is the enrollment IDs of the accounts to query
	EnrollmentIDs []string
	// TokenTypes is the token types to query
	TokenTypes []token2.Type
	// TxStatuses is the statuses of the transactions to query
	TxStatuses []TxStatus
	// SearchDirection is the direction of the search
	SearchDirection SearchDirection
	// MovementDirection is the direction of the movement
	MovementDirection MovementDirection
	// NumRecords is the number of records to return
	// If 0, all records are returned
	NumRecords int
}

type QueryTokenDetailsParams struct {
	// WalletID is the optional identifier of the wallet owning the token.
	// When WalletIDs is non-empty this field is ignored.
	WalletID string
	// WalletIDs is an optional list of wallet identifiers. When set, tokens
	// owned by any of the listed wallets match (single SQL query with IN).
	// Takes precedence over WalletID; leave empty for the single-wallet path.
	WalletIDs []string
	// OwnerType is the type of owner, for instance 'idemix' or 'htlc'
	OwnerType string
	// TokenType (optional) is the type of token
	TokenType token.Type
	// IDs is an optional list of specific token ids to return
	IDs []*token.ID
	// TransactionIDs selects tokens that are the output of the provided transaction ids.
	TransactionIDs []string
	// IncludeDeleted determines whether to include spent tokens. It defaults to false.
	IncludeDeleted bool
	// Spendable determines whether to include only spendable/non-spendable or any tokens. It defaults to nil (any tokens)
	Spendable SpendableFilter
	// LedgerTokenFormats selects tokens whose output on the ledger has a format in the list
	LedgerTokenFormats []token.Format
}

type QueryTokenRequestsParams struct {
	// Statuses is the list of transaction status to accept
	// If empty, any status is accepted
	Statuses []TxStatus
}

type QueryTransactionsParams struct {
	// IDs is the list of transaction ids. If nil or empty, all transactions are returned
	IDs []string
	// ExcludeToSelf can be used to filter out 'change' transactions where the sender and
	// recipient have the same enrollment id.
	ExcludeToSelf bool
	// SenderWallet is the wallet of the sender
	// If empty, any sender is accepted
	// If the sender does not match but the recipient matches, the transaction is returned
	SenderWallet string
	// RecipientWallet is the wallet of the recipient
	// If empty, any recipient is accepted
	// If the recipient does not match but the sender matches, the transaction is returned
	RecipientWallet string
	// From is the start time of the query
	// If nil, the query starts from the first transaction
	From *time.Time
	// To is the end time of the query
	// If nil, the query ends at the last transaction
	To *time.Time
	// ActionTypes is the list of action types to accept
	// If empty, any action type is accepted
	ActionTypes []ActionType
	// Statuses is the list of transaction status to accept
	// If empty, any status is accepted
	Statuses []TxStatus
	// TokenTypes is the list of token types to accept
	// If empty, any token type is accepted
	TokenTypes []token2.Type
	// SearchDirection is the direction of the search.
	// Default (zero value) is FromLast (descending by stored_at).
	SearchDirection SearchDirection
}

type QueryValidationRecordsParams struct {
	// From is the start time of the query
	// If nil, the query starts from the first transaction
	From *time.Time
	// To is the end time of the query
	// If nil, the query ends at the last transaction
	To *time.Time
	// Statuses is the list of transaction status to accept
	// If empty, any status is accepted
	Statuses []TxStatus
	// Filter defines a custom filter function.
	// If specified, this filter will be applied.
	// the filter returns true if the record must be selected, false otherwise.
	Filter func(record *ValidationRecord) bool
}

type RecoveryClaim struct {
	// TxID is the transaction ID claimed for recovery.
	TxID string
	// StoredAt is the storage timestamp of the underlying row (UTC), used
	// by the recovery loop to compute row age for grace-period decisions.
	StoredAt time.Time
}

type RecoveryClaimParams struct {
	OlderThan     time.Time
	LeaseDuration time.Duration
	Limit         int
	Owner         string
}

type RecoveryLeadership interface {
	Close() error
}

type SearchDirection int

type SpendableFilter int

type TokenDetails struct {
	// TxID is the ID of the transaction that created the token
	TxID string
	// Index is the index in the transaction
	Index uint64
	// OwnerIdentity is the serialization of the owner identity
	OwnerIdentity []byte
	// OwnerType is the deserialized type inside OwnerRaw
	OwnerType string
	// OwnerEnrollment is the enrollment id of the owner
	OwnerEnrollment string
	// Type is the type of token
	Type string
	// Amount is the Quantity converted to decimal as a big integer to support arbitrary precision
	Amount *big.Int
	// IsSpent is true if the token has been spent
	IsSpent bool
	// SpentBy is the transactionID that spent this token, if available
	SpentBy string
	// StoredAt is the moment the token was stored by this wallet
	StoredAt time.Time
}

type TokenLockStore interface {
	common.DBObject
	// Lock locks a specific token for the consumer TX
	Lock(ctx context.Context, tokenID *token.ID, consumerTxID transaction.ID) error
	// UnlockByTxID unlocks all tokens locked by the consumer TX
	UnlockByTxID(ctx context.Context, consumerTxID transaction.ID) error
	// Cleanup removes the locks such that either:
	// 1. The transaction that locked that token is valid or invalid;
	// 2. The lock is too old.
	Cleanup(ctx context.Context, leaseExpiry time.Duration) error
	// Close closes the database
	Close() error
}

type TokenNotifier interface {
	// Subscribe registers a callback function to be called when a token record is inserted, updated or deleted.
	Subscribe(callback func(Operation, TokenRecordReference)) error
	// UnsubscribeAll unregisters all callbacks.
	UnsubscribeAll() error
}

type TokenNotifierDriver interface {
	// Open opens a token database with its listeners
	Open(cp ConfigProvider, tmsID token2.TMSID) (TokenNotifier, error)
}

type TokenRecord struct {
	// TxID is the ID of the transaction that created the token
	TxID string
	// Index is the index in the transaction
	Index uint64
	// IssuerRaw represents the serialization of the issuer identity
	// if this is an IssuedToken.
	IssuerRaw []byte
	// OwnerRaw is the serialization of the owner TypedIdentity
	OwnerRaw []byte
	// OwnerType is the deserialized type inside OwnerRaw
	OwnerType string
	// OwnerIdentity is the deserialized Identity inside OwnerRaw
	OwnerIdentity []byte
	// OwnerWalletID is the identifier of the wallet that owns this token, it might be empty
	OwnerWalletID string
	// Ledger is the raw token as stored on the ledger
	Ledger []byte
	// LedgerFormat is the type of the raw token as stored on the ledger
	LedgerFormat token.Format
	// LedgerMetadata is the metadata associated to the content of Ledger
	LedgerMetadata []byte
	// Quantity is the number of units of Type carried in the token.
	// It is encoded as a string containing a number in base 16. The string has prefix “0x”.
	Quantity string
	// Type is the type of token
	Type token.Type
	// Amount is the Quantity converted to decimal
	Amount uint64
	// Owner is used to mark the token as owned by this node
	Owner bool
	// Auditor is used to mark this token as audited by this node
	Auditor bool
	// Issuer issued to mark this token as issued by this node
	Issuer bool
}

type TokenRecordReference struct {
	// TxID is the unique identifier of the transaction that created the token.
	TxID string
	// Index is the index of the token in the transaction.
	Index uint64
}

type TokenRequestIterator = iterators.Iterator[*TokenRequestRecord]

type TokenRequestRecord struct {
	// TxID is the transaction ID
	TxID string
	// TokenRequest is the token request marshalled
	TokenRequest []byte
	// Status is the status of the transaction
	Status TxStatus
}

type TokenStore interface {
	CertificationStore
	// DeleteTokens marks the passsed tokens as deleted
	DeleteTokens(ctx context.Context, deletedBy string, toDelete ...*token.ID) error
	// IsMine return true if the passed token was stored before
	IsMine(ctx context.Context, txID string, index uint64) (bool, error)
	// UnspentTokensIterator returns an iterator over all owned tokens
	UnspentTokensIterator(ctx context.Context) (driver.UnspentTokensIterator, error)
	// UnspentLedgerTokensIteratorBy returns an iterator over all unspent ledger tokens
	UnspentLedgerTokensIteratorBy(ctx context.Context) (driver.LedgerTokensIterator, error)
	// UnspentTokensIteratorBy returns an iterator over all tokens owned by the passed wallet identifier and of a given type
	UnspentTokensIteratorBy(ctx context.Context, walletID string, tokenType token.Type) (driver.UnspentTokensIterator, error)
	// SpendableTokensIteratorBy returns an iterator over all tokens owned solely by the passed wallet identifier and of a given type
	SpendableTokensIteratorBy(ctx context.Context, walletID string, typ token.Type) (driver.SpendableTokensIterator, error)
	// UnsupportedTokensIteratorBy returns the minimum information for upgrade about the tokens that are not supported
	UnsupportedTokensIteratorBy(ctx context.Context, walletID string, tokenType token.Type) (driver.UnsupportedTokensIterator, error)
	// ListUnspentTokensBy returns the list of all tokens owned by the passed identifier of a given type
	ListUnspentTokensBy(ctx context.Context, walletID string, typ token.Type) (*token.UnspentTokens, error)
	// ListUnspentTokensByWallets returns unspent tokens owned by any of the
	// provided wallets, partitioned by wallet id. An optional token type
	// filter narrows the result set (empty type means any type).
	//
	// The returned map contains only wallet ids that had at least one
	// matching unspent token — callers should treat a missing key as "no
	// tokens" (same semantics as an empty *token.UnspentTokens). An empty
	// or nil walletIDs slice returns an empty map without touching the
	// database.
	//
	// This is a single-query alternative to calling ListUnspentTokensBy
	// per wallet in a loop: one SQL statement with an IN clause, then
	// partitioned on the read side.
	//
	// Scale note: the IN clause expands to two placeholders per wallet id
	// (one per wallet column). Postgres's default parameter limit (~65k)
	// leaves ample headroom; SQLite's default (999) caps the practical
	// batch size at a few hundred wallet ids. Callers expecting thousands
	// of ids should chunk on the caller side and merge the returned maps.
	//
	// Position in the ListUnspentTokens family:
	//
	//	UnspentTokensIterator(ctx)                       → iterator (all)
	//	UnspentTokensIteratorBy(ctx, walletID, typ)      → iterator (one wallet)
	//	ListUnspentTokens(ctx)                           → *UnspentTokens (all)
	//	ListUnspentTokensBy(ctx, walletID, typ)          → *UnspentTokens (one wallet)
	//	ListUnspentTokensByWallets(ctx, walletIDs, typ)  → map[walletID]*UnspentTokens (batch)
	ListUnspentTokensByWallets(ctx context.Context, walletIDs []string, typ token.Type) (map[string]*token.UnspentTokens, error)
	// ListUnspentTokens returns the list of all owned tokens
	ListUnspentTokens(ctx context.Context) (*token.UnspentTokens, error)
	// ListAuditTokens returns the audited tokens for the passed ids
	ListAuditTokens(ctx context.Context, ids ...*token.ID) ([]*token.Token, error)
	// ListHistoryIssuedTokens returns the list of all issued tokens
	ListHistoryIssuedTokens(ctx context.Context) (*token.IssuedTokens, error)
	// GetTokenOutputs returns the value of the tokens as they appear on the ledger for the passed ids.
	// For each token, the call-back function is invoked. The call-back function is invoked respecting the order of the passed ids.
	GetTokenOutputs(ctx context.Context, ids []*token.ID, callback driver.QueryCallbackFunc) error
	// GetTokenMetadata returns the metadata of the tokens for the passed ids.
	GetTokenMetadata(ctx context.Context, ids []*token.ID) ([][]byte, error)
	// GetTokenOutputsAndMeta retrieves both the token output, metadata, and type for the passed ids.
	GetTokenOutputsAndMeta(ctx context.Context, ids []*token.ID) ([][]byte, [][]byte, []token.Format, error)
	// GetTokens returns the owned tokens and their identifier keys for the passed ids.
	GetTokens(ctx context.Context, inputs ...*token.ID) ([]*token.Token, error)
	// WhoDeletedTokens for each id, the function return if it was deleted and by who as per the Delete function
	WhoDeletedTokens(ctx context.Context, inputs ...*token.ID) ([]string, []bool, error)
	// TransactionExists returns true if a token with that transaction id exists in the db
	TransactionExists(ctx context.Context, id string) (bool, error)
	// StorePublicParams stores the public parameters.
	// If they already exist, the function return with no error. No changes are applied.
	StorePublicParams(ctx context.Context, raw []byte) error
	// PublicParams returns the stored public parameters.
	// If not public parameters are available, it returns nil with no error
	PublicParams(ctx context.Context) ([]byte, error)
	// PublicParamsByHash returns the public parameters whose hash matches the passed one.
	// If not public parameters are available for that hash, it returns an error
	PublicParamsByHash(ctx context.Context, rawHash driver.PPHash) ([]byte, error)
	// NewTokenDBTransaction returns a new Transaction to commit atomically multiple operations
	NewTokenDBTransaction() (TokenStoreTransaction, error)
	// ContinueTokenDBTransaction returns a new TokenStoreTransaction building upon the passed transaction.
	ContinueTokenDBTransaction(tx Transaction) (TokenStoreTransaction, error)
	// QueryTokenDetails provides detailed information about tokens
	QueryTokenDetails(ctx context.Context, params QueryTokenDetailsParams) ([]TokenDetails, error)
	// Balance returns the sum of the amounts of the tokens with type and EID equal to those passed as arguments.
	// The result is returned as a *big.Int to support arbitrary precision and prevent overflow.
	Balance(ctx context.Context, ownerEID string, typ token.Type) (*big.Int, error)
	// SetSupportedTokenFormats sets the supported token formats
	SetSupportedTokenFormats(formats []token.Format) error
	// Notifier returns a TokenNotifier for this store to subscribe to token changes.
	Notifier() (TokenNotifier, error)
	// GetDeletedTokensPendingSKICleanup returns deleted tokens older than the specified duration that haven't had their SKI keys cleaned yet.
	// This is used by the keystore cleanup service to identify tokens whose cryptographic keys can be safely removed.
	// Only tokens without a record in the token_ski_cleanups table are returned.
	GetDeletedTokensPendingSKICleanup(ctx context.Context, olderThan time.Duration, limit int) ([]DeletedToken, error)
	// MarkTokenCleaned marks a token as having its cryptographic keys cleaned up.
	// This prevents the cleanup service from processing the same token multiple times.
	// The cleanedBy parameter identifies which instance performed the cleanup for audit purposes.
	MarkTokenCleaned(ctx context.Context, txID string, index uint64, cleanedBy string) error
	// AcquireCleanupLeadership attempts to acquire leadership for keystore cleanup operations.
	// Returns (leadership, true, nil) if leadership was acquired.
	// Returns (nil, false, nil) if leadership is held by another instance.
	// Returns (nil, false, error) if an error occurred.
	AcquireCleanupLeadership(ctx context.Context, lockID int64) (CleanupLeadership, bool, error)
}

type TokenStoreTransaction interface {
	// GetToken returns the owned tokens and their identifier keys for the passed ids.
	GetToken(ctx context.Context, tokenID token.ID, includeDeleted bool) (*token.Token, []string, error)
	// Delete marks the passed token as deleted by a given identifier (idempotent)
	Delete(ctx context.Context, tokenID token.ID, deletedBy string) error
	// StoreToken stores the passed token record in relation to the passed owner identifiers, if any
	StoreToken(ctx context.Context, tr TokenRecord, owners []string) error
	// SetSpendable updates the spendable flag of the passed token
	SetSpendable(ctx context.Context, tokenID token.ID, spendable bool) error
	// SetSpendableBySupportedTokenFormats sets the spendable flag to true for all the tokens having one of the passed token type.
	// The spendable flag is set to false for the other tokens
	SetSpendableBySupportedTokenFormats(ctx context.Context, formats []token.Format) error
	// Commit commits this transaction
	Commit() error
	// Rollback rollbacks this transaction
	Rollback() error
}

type TokenTransactionStore interface {
	TransactionStore
	TransactionEndorsementAckStore
}

type Transaction interface {
	Impl() TransactionImpl
	// Commit applies and persists any pending changes to the asset database.
	Commit() error
	// Rollback undoes all pending changes, restoring the asset database to its previous committed state.
	Rollback()
}

type TransactionEndorsementAckStore interface {
	// AddTransactionEndorsementAck records the signature of a given endorser for a given transaction
	AddTransactionEndorsementAck(ctx context.Context, txID string, endorser token.Identity, sigma []byte) error

	// GetTransactionEndorsementAcks returns the endorsement signatures for the given transaction id
	GetTransactionEndorsementAcks(ctx context.Context, txID string) (map[string][]byte, error)
}

type TransactionImpl = any

type TransactionIterator = iterators.Iterator[*TransactionRecord]

type TransactionNotifier interface {
	// Subscribe registers a callback function to be called when a transaction request status is updated.
	Subscribe(callback func(Operation, TransactionRecordReference)) error
	// UnsubscribeAll unregisters all callbacks.
	UnsubscribeAll() error
}

type TransactionRecord struct {
	// TxID is the transaction ID
	TxID string
	// ActionType is the type of action performed by this transaction record
	ActionType ActionType
	// SenderEID is the enrollment ID of the account that is sending tokens
	SenderEID string
	// RecipientEID is the enrollment ID of the account that is receiving tokens
	RecipientEID string
	// TokenType is the type of token
	TokenType token2.Type
	// Amount is positive if tokens are received. Negative otherwise
	Amount *big.Int
	// Timestamp is the time the transaction was submitted to the db
	Timestamp time.Time
	// RecoveryClaimedBy identifies the recovery worker/replica currently holding the lease for this transaction.
	RecoveryClaimedBy string
	// RecoveryClaimExpiresAt is the lease expiration for the current recovery claim, if any.
	RecoveryClaimExpiresAt *time.Time
	// Status is the status of the transaction
	Status TxStatus
	// ApplicationMetadata is the metadata sent by the application in the
	// transient field. It is not validated or recorded on the ledger.
	ApplicationMetadata map[string][]byte
	// PublicMetadata is the metadata that is stored on the ledger as part
	// of an Issuance or Transfer Action (for instance the HTLC hash).
	PublicMetadata map[string][]byte
}

type TransactionRecordReference struct {
	// TxID is the unique identifier of the transaction request.
	TxID string
}

type TransactionStore interface {
	// Close closes the databases
	Close() error

	// NewTransactionStoreTransaction opens an atomic database transaction. It must be committed or discarded.
	NewTransactionStoreTransaction() (TransactionStoreTransaction, error)

	// SetStatus sets the status of a TokenRequest
	// (and with that, the associated Movement and Transaction)
	SetStatus(ctx context.Context, txID string, status TxStatus, message string) error

	// GetStatus returns the status of a given transaction.
	// It returns an error if the transaction is not found
	GetStatus(ctx context.Context, txID string) (TxStatus, string, error)

	// QueryTransactions returns a list of transactions that match the given criteria
	QueryTransactions(ctx context.Context, params QueryTransactionsParams, pagination driver2.Pagination) (*driver2.PageIterator[*TransactionRecord], error)

	// QueryMovements returns a list of movement records
	QueryMovements(ctx context.Context, params QueryMovementsParams) ([]*MovementRecord, error)

	// QueryTokenRequests returns an iterator over the token requests matching the passed params
	QueryTokenRequests(ctx context.Context, params QueryTokenRequestsParams) (TokenRequestIterator, error)

	// GetTokenRequest returns the token request bound to the passed transaction id, if available.
	// It returns nil without error if the key is not found.
	GetTokenRequest(ctx context.Context, txID string) ([]byte, error)

	// GetTokenRequests returns the token requests bound to the given
	// transaction ids, in a single query. The returned map contains an
	// entry only for tx ids that were present in storage — callers should
	// treat a missing key identically to GetTokenRequest returning nil
	// (no error, no record). An empty or nil txIDs slice returns an empty
	// map without touching the database.
	GetTokenRequests(ctx context.Context, txIDs []string) (map[string][]byte, error)

	// AcquireRecoveryLeadership tries to acquire the PostgreSQL advisory lock backing the sweeper leader election.
	// If acquired is false, leadership was not obtained and the returned lease must be nil.
	AcquireRecoveryLeadership(ctx context.Context, lockID int64) (RecoveryLeadership, bool, error)

	// ClaimPendingTransactions atomically claims a batch of Pending transactions for recovery processing.
	// Transactions whose recovery lease expired are eligible again.
	// Returns the minimal projection (TxID + StoredAt) needed by the recovery loop;
	// callers do not need the full TransactionRecord.
	ClaimPendingTransactions(ctx context.Context, params RecoveryClaimParams) ([]*RecoveryClaim, error)

	// ReleaseRecoveryClaim clears the recovery claim metadata for the given transaction if owned by owner.
	// The message parameter is stored for audit/debugging purposes.
	ReleaseRecoveryClaim(ctx context.Context, txID string, owner string, message string) error

	// Notifier returns a TransactionNotifier for this store to subscribe to transaction status changes.
	Notifier() (TransactionNotifier, error)
}

type TransactionStoreTransaction interface {
	Transaction

	// AddTokenRequest binds the passed transaction id to the passed token request
	AddTokenRequest(ctx context.Context, txID string, tr []byte, applicationMetadata, publicMetadata map[string][]byte, ppHash driver.PPHash) error

	// AddMovement adds a movement record to the database transaction.
	// Each token transaction can be seen as a list of movements.
	// This operation _requires_ a TokenRequest with the same tx_id to exist
	AddMovement(ctx context.Context, records ...MovementRecord) error

	// AddTransaction adds a transaction record to the database transaction.
	// This operation _requires_ a TokenRequest with the same tx_id to exist
	AddTransaction(ctx context.Context, records ...TransactionRecord) error

	// SetStatus sets the status of a TokenRequest
	// (and with that, the associated Movement and Transaction)
	SetStatus(ctx context.Context, txID string, status driver.TxStatus, message string) error
}

type TxStatus = driver2.TxStatus

type ValidationRecord struct {
	// TxID is the transaction ID
	TxID string
	// TokenRequest is the token request marshalled
	TokenRequest []byte
	// Metadata is the metadata produced by the validator when evaluating the token request
	Metadata map[string][]byte
	// Timestamp is the time the transaction was submitted to the db
	Timestamp time.Time
}

type ValidationRecordsIterator = iterators.Iterator[*ValidationRecord]

type WalletID = idriver.WalletID

type WalletStore = idriver.WalletStoreService