scanner

type BalanceQueryFunc func(address string) (confirmed, unconfirmed, total string, err error)

type Base struct {
	Mu                sync.RWMutex
	ScanTargetFunc    BlockScanTargetFunc
	TokenMetadataFunc TokenMetadataFunc

	PeriodOfTask time.Duration
	// contains filtered or unexported fields
}

type BlockScanTargetFunc func(target types.ScanTargetParam) types.ScanTargetResult

type BlockScanner interface {
	SetBlockScanTargetFunc(scanTargetFunc BlockScanTargetFunc) error

	SetTokenMetadataFunc(tokenMetadataFunc TokenMetadataFunc) error

	// 运行控制：启动/停止内部扫描任务。
	Run() error
	Pause() error

	// ScanBlockWithResult 按高度扫描区块并返回摘要结果，供外部系统推进游标与重试。
	// 约定：error 用于表达“无法完成该高度扫描”（如 RPC 失败/块不存在等）；result.Success 表达业务语义上的成功与否。
	ScanBlockWithResult(height uint64) (*types.BlockScanResult, error)
	// ScanBlockOnce 指定高度扫描一次（用于补扫/漏扫修复），不进入持续循环、不维护外部游标。
	ScanBlockOnce(height uint64) (*types.BlockScanResult, error)

	// ResetScanHeight 将“持续扫块循环”的起始高度重置到指定值（用于后台指令修正游标/回滚重扫）。
	// 约定：该方法只影响正在运行的 RunScanLoop（若实现方支持），不应引起进程重启。
	ResetScanHeight(height uint64) error

	GetCurrentBlockHeader() (*types.BlockHeader, error)
	GetGlobalMaxBlockHeight() uint64
	ExtractTransactionAndReceiptData(txid string, scanTargetFunc BlockScanTargetFunc) ([]*types.ExtractDataItem, []*types.ContractReceiptItem, error)

	// GetBalanceByAddress 查询指定地址的余额。
	GetBalanceByAddress(address ...string) ([]*types.Balance, error)

	// VerifyTransactionByTxID 入账前按 txid 二次复核链上结果并返回可入账结果集。
	// 约定：error 用于表达“RPC/系统错误导致无法完成复核”；业务层面的不通过以 result.Verified=false + Reason 表达。
	VerifyTransactionByTxID(txid string, scanTargetFunc BlockScanTargetFunc, minConfirmations uint64) (*types.TxVerifyResult, error)

	// VerifyTransactionMatch 入账前对链上结果集做二次复核，并与外部期望对象 expected 严格比对。
	// 约定：error 表达系统/RPC 异常；业务不通过以 result.Verified=false + Reason/Mismatches 表达。
	VerifyTransactionMatch(txid string, expected *types.TxVerifyExpected, scanTargetFunc BlockScanTargetFunc, minConfirmations uint64) (*types.TxVerifyMatchResult, error)

	// RunScanLoop 按高度持续扫描区块：
	// - 从 params.StartHeight+1 开始，串行向上扫描；
	// - 直接扫描至 latest（链上最新高度），不再减去 Confirmations；
	// - Confirmations 仅用于计算 BlockHeader.Confirmations 字段供业务层参考；
	// - 每个高度只扫描一次，不会重复扫描，节省资源；
	// - 每扫完一个高度调用 params.HandleBlock（若非空）将 ScanBlockWithResult 的结果同步回调给外部系统；
	// - 每轮结束后 sleep Interval 再次循环。
	// 该方法只负责生产候选结果，入账/确认/重试策略由外部系统基于回调结果与 Verify 接口自行决定。
	RunScanLoop(params ScanLoopParams) error

	// ScanBlockPrioritize 插队扫描指定高度列表。
	// 说明：
	// - 将插队高度加入优先队列，RunScanLoop 会在主线扫描间隙优先处理这些高度；
	// - 插队高度的扫描结果复用 RunScanLoop 的 handleBlock（如果 RunScanLoop 未运行则无回调）；
	// - 插队扫描不影响 RunScanLoop 的主线 cursor 推进逻辑；
	// - 插队高度按升序处理，且去重；
	// - 严格要求所有传入的高度都满足 confirmations 要求（height <= latest - confirmations），否则直接返回错误；
	// - 调用方可根据错误信息调整高度后重试。
	ScanBlockPrioritize(heights []uint64) error
}

type ScanLoopParams struct {
	StartHeight   uint64                           // 起始扫描高度，从 StartHeight+1 开始扫描
	Confirmations uint64                           // 确认数，仅用于计算 BlockHeader.Confirmations 供业务层参考
	Interval      time.Duration                    // 每轮扫描后的休眠间隔
	HandleBlock   func(res *types.BlockScanResult) // 每扫完一个高度的回调函数（可为 nil）
}

type TokenMetadataFunc func(symbol, contractAddr string) *types.SmartContract