services

type AccountService interface {
	// RegisterAccount registers an externally created Stellar account to be sponsored, and tracked by ingestion
	RegisterAccount(ctx context.Context, address string) error
	// DeregisterAccount deregisters a Stellar account, no longer sponsoring its transactions, nor tracking it on ingestion
	DeregisterAccount(ctx context.Context, address string) error
}

type BackfillBatch struct {
	StartLedger uint32
	EndLedger   uint32
}

type BackfillMode int

type BackfillResult struct {
	Batch        BackfillBatch
	LedgersCount int
	Duration     time.Duration
	Error        error
	BatchChanges *BatchChanges // Only populated for catchup mode
}

type BatchChanges struct {
	TrustlineChangesByKey     map[indexer.TrustlineChangeKey]types.TrustlineChange
	ContractChanges           []types.ContractChange
	AccountChangesByAccountID map[string]types.AccountChange
	SACBalanceChangesByKey    map[indexer.SACBalanceChangeKey]types.SACBalanceChange
	UniqueTrustlineAssets     map[uuid.UUID]data.TrustlineAsset
	UniqueContractTokensByID  map[string]types.ContractType
	SACContractsByID          map[string]*data.Contract // SAC contract metadata extracted from instance entries
}

type ChannelAccSigner func(ctx context.Context, tx *txnbuild.Transaction) (*txnbuild.Transaction, error)

type ChannelAccountService interface {
	EnsureChannelAccounts(ctx context.Context, number int64) error
}

type ChannelAccountServiceOptions struct {
	DB                                 db.ConnectionPool
	RPCService                         RPCService
	BaseFee                            int64
	DistributionAccountSignatureClient signing.SignatureClient
	ChannelAccountSignatureClient      signing.SignatureClient
	ChannelAccountStore                store.ChannelAccountStore
	PrivateKeyEncrypter                signingutils.PrivateKeyEncrypter
	EncryptionPassphrase               string
}

type ContractMetadata struct {
	ContractID string
	Name       string
	Symbol     string
	Decimals   uint32
}

type ContractMetadataService interface {
	// FetchSep41Metadata fetches metadata for SEP-41 contracts via RPC without storing.
	// Returns []*data.Contract with ID field pre-computed via DeterministicContractID.
	FetchSep41Metadata(ctx context.Context, contractIDs []string) ([]*data.Contract, error)
	// FetchSACMetadata fetches metadata for SAC contracts by calling name() via RPC.
	// SAC name() returns "code:issuer" format (or "native" for XLM).
	// Returns []*data.Contract with Code, Issuer, Name, Symbol, and Decimals=7.
	FetchSACMetadata(ctx context.Context, contractIDs []string) ([]*data.Contract, error)
	// FetchSingleField fetches a single contract method (name, symbol, decimals, balance, etc...) via RPC simulation.
	// The args parameter allows passing arguments to the contract function (e.g., address for balance(id) function).
	FetchSingleField(ctx context.Context, contractAddress, functionName string, args ...xdr.ScVal) (xdr.ScVal, error)
}

type ContractMetadataServiceMock struct {
	mock.Mock
}

type ContractValidator interface {
	ValidateFromContractCode(_ context.Context, _ []byte) (types.ContractType, error)
	Close(_ context.Context) error
}

type FeeBumpService interface {
	WrapTransaction(ctx context.Context, tx *txnbuild.Transaction) (string, string, error)
	GetMaximumBaseFee() int64
}

type FeeBumpServiceOptions struct {
	DistributionAccountSignatureClient signing.SignatureClient
	BaseFee                            int64
	Models                             *data.Models
}

type GetLedgersResponse protocol.GetLedgersResponse

type HistoryArchiveMock struct {
	mock.Mock
}

type IngestService interface {
	Run(ctx context.Context, startLedger uint32, endLedger uint32) error
	// PersistLedgerData persists processed ledger data to the database in a single atomic transaction.
	// This is the shared core used by both live ingestion and loadtest.
	// Returns the number of transactions and operations persisted.
	PersistLedgerData(ctx context.Context, ledgerSeq uint32, buffer *indexer.IndexerBuffer, cursorName string) (int, int, error)
}

type IngestServiceConfig struct {
	// === Core ===
	IngestionMode  string
	Models         *data.Models
	AppTracker     apptracker.AppTracker
	MetricsService metrics.MetricsService

	// === Stellar Network ===
	Network           string
	NetworkPassphrase string
	Archive           historyarchive.ArchiveInterface
	RPCService        RPCService

	// === Ledger Backend ===
	LedgerBackend        ledgerbackend.LedgerBackend
	LedgerBackendFactory LedgerBackendFactory

	// === Cursors ===
	LatestLedgerCursorName string
	OldestLedgerCursorName string

	// === Live Mode Dependencies ===
	ChannelAccountStore     store.ChannelAccountStore
	TokenIngestionService   TokenIngestionService
	ContractMetadataService ContractMetadataService

	// === Processing Options ===
	GetLedgersLimit            int
	SkipTxMeta                 bool
	SkipTxEnvelope             bool
	EnableParticipantFiltering bool

	// === Backfill Tuning ===
	BackfillWorkers           int
	BackfillBatchSize         int
	BackfillDBInsertBatchSize int
	CatchupThreshold          int
}

type KMSImportService interface {
	ImportDistributionAccountKey(ctx context.Context, distributionAccountSeed string) error
}

type LedgerBackendFactory func(ctx context.Context) (ledgerbackend.LedgerBackend, error)

type LedgerBackendMock struct {
	mock.Mock
}

type RPCService interface {
	GetTransaction(transactionHash string) (entities.RPCGetTransactionResult, error)
	GetTransactions(startLedger int64, startCursor string, limit int) (entities.RPCGetTransactionsResult, error)
	SendTransaction(transactionXDR string) (entities.RPCSendTransactionResult, error)
	GetHealth() (entities.RPCGetHealthResult, error)
	GetLedgers(startLedger uint32, limit uint32) (GetLedgersResponse, error)
	GetLedgerEntries(keys []string) (entities.RPCGetLedgerEntriesResult, error)
	GetAccountLedgerSequence(address string) (int64, error)
	GetHeartbeatChannel() chan entities.RPCGetHealthResult
	// TrackRPCServiceHealth continuously monitors the health of the RPC service and updates metrics.
	// It runs health checks at regular intervals and can be triggered on-demand via immediateHealthCheckTrigger.
	//
	// The immediateHealthCheckTrigger channel allows external components to request an immediate health check,
	// which is particularly useful when the ingestor needs to catch up with the RPC service.
	//
	// Returns an error if the context is cancelled. The caller is responsible for handling shutdown signals.
	TrackRPCServiceHealth(ctx context.Context, immediateHealthCheckTrigger <-chan any) error
	SimulateTransaction(transactionXDR string, resourceConfig entities.RPCResourceConfig) (entities.RPCSimulateTransactionResult, error)
	NetworkPassphrase() string
}

type RPCServiceMock struct {
	mock.Mock
}

type TokenIngestionService interface {
	// PopulateAccountTokens performs initial PostgreSQL cache population from Stellar
	// history archive for a specific checkpoint. It extracts all trustlines and contract
	// tokens from checkpoint ledger entries and stores them in PostgreSQL.
	// The checkpointLedger parameter specifies which checkpoint to use for population.
	// The initializeCursors callback is invoked within the same DB transaction as
	// the metadata storage to ensure atomic initialization.
	PopulateAccountTokens(ctx context.Context, checkpointLedger uint32, initializeCursors func(pgx.Tx) error) error

	// ProcessTokenChanges applies trustline, contract, and SAC balance changes to PostgreSQL.
	// This is called by the indexer for each ledger's state changes during live ingestion.
	//
	// Storage semantics differ between token types:
	// - Trustlines: Can be added or removed. When all trustlines for an account are removed,
	//   the account's entry is deleted from PostgreSQL.
	// - Contracts: Only SEP-41 contracts are tracked (contracts accumulate). Unknown contracts
	//   are skipped. Contract balance entries persist in the ledger even when balance is zero,
	//   so we track all contracts an account has ever held a balance in.
	// - SAC Balances: For contract addresses (C...) only. Stores absolute balance values with
	//   authorized and clawback flags. G-addresses use trustlines for SAC balances.
	//
	// Both trustline and contract IDs are computed using deterministic hash functions (DeterministicAssetID, DeterministicContractID).
	ProcessTokenChanges(ctx context.Context, dbTx pgx.Tx, trustlineChangesByTrustlineKey map[indexer.TrustlineChangeKey]types.TrustlineChange, contractChanges []types.ContractChange, accountChangesByAccountID map[string]types.AccountChange, sacBalanceChangesByKey map[indexer.SACBalanceChangeKey]types.SACBalanceChange) error
}

type TokenIngestionServiceMock struct {
	mock.Mock
}

type TransactionService interface {
	NetworkPassphrase() string
	BuildAndSignTransactionWithChannelAccount(ctx context.Context, transaction *txnbuild.GenericTransaction, simulationResult *entities.RPCSimulateTransactionResult) (*txnbuild.Transaction, error)
}

type TransactionServiceOptions struct {
	DB                                 db.ConnectionPool
	DistributionAccountSignatureClient signing.SignatureClient
	ChannelAccountSignatureClient      signing.SignatureClient
	ChannelAccountStore                store.ChannelAccountStore
	RPCService                         RPCService
	BaseFee                            int64
}