Implement Stacks Blockchain Listener

[CyrusVorwald]

The Listener function monitors the Stacks blockchain for relevant events and passes them to the relay system for processing. It should handle both catching up with historical blocks and subscribing to new blocks.

type StacksListener interface {
	// Listener is the main function that starts listening for events on the Stacks blockchain
	Listener(ctx context.Context, lastSavedHeight uint64, blockInfoChan chan<- *types.BlockInfo) error

	// StartFromHeight determines the appropriate starting height for the listener
	StartFromHeight(ctx context.Context, lastSavedHeight uint64) (uint64, error)

	// ProcessPastBlocks handles the processing of historical blocks
	ProcessPastBlocks(ctx context.Context, startHeight uint64, blockInfoChan chan<- *types.BlockInfo) error

	// SubscribeToNewBlocks sets up a subscription for new incoming blocks
	SubscribeToNewBlocks(ctx context.Context, blockInfoChan chan<- *types.BlockInfo) error

	// GetBlockInfo retrieves information about a specific block, including relevant events
	GetBlockInfo(ctx context.Context, height uint64) (*types.BlockInfo, error)

	// ParseStacksEvent converts a Stacks-specific event into a relay system message
	ParseStacksEvent(event StacksEvent) (*StacksMessage, error)

	// QueryLatestHeight retrieves the latest block height from the Stacks blockchain
	QueryLatestHeight(ctx context.Context) (uint64, error)

	// GetFinalityBlock returns the number of blocks required for finality on the Stacks blockchain
	GetFinalityBlock(ctx context.Context) uint64

	// HandleError processes errors and implements reconnection logic
	HandleError(ctx context.Context, err error) error

	// GetPerformanceMetrics returns performance-related metrics for the listener
	GetPerformanceMetrics(ctx context.Context) (PerformanceMetrics, error)
}

// StacksBlockHeader represents the header of a Stacks block
type StacksBlock struct {
	Height     uint64     `json:"height"`
	Hash       string     `json:"block_hash"`
	Timestamp  int64      `json:"timestamp"`
	TxCount    int        `json:"tx_count"`
	Events     []StacksEvent `json:"events"`
}

// StacksEvent represents an event emitted during a Stacks transaction
type StacksEvent struct {
	TxID       string          `json:"tx_id"`
	EventIndex int             `json:"event_index"`
	EventType  string          `json:"event_type"`
	Contract   string          `json:"contract_identifier"`
	Topic      string          `json:"topic"`
	Data       json.RawMessage `json:"data"`
}

// StacksMessage represents a parsed message from a Stacks event
type StacksMessage struct {
	Src           string   `json:"src"`
	Dst           string   `json:"dst"`
	Sn            *big.Int `json:"sn"`
	MessageHeight uint64   `json:"message_height"`
	Data          []byte   `json:"data"`
	EventType     string   `json:"event_type"`
}

// PerformanceMetrics represents performance-related metrics for the Stacks listener
type PerformanceMetrics struct {
	ProcessedBlocks uint64
	ProcessedEvents uint64
	AverageBlockProcessingTime time.Duration
}

Acceptance criteria

• Listener successfully processes historical blocks from the determined start height
• Listener receives and processes new blocks in real-time
• Events are correctly parsed and converted to relay system messages
• Proper error handling and reconnection logic is implemented
• Logging provides clear information about processed blocks and detected events
• Unit tests cover all methods with >80% code coverage
• Integration tests confirm functionality against Stacks testnet