Skip to content

sgns::evmwatcher::BridgeCatchupWatcher

Polling watcher that scans bridge chains for historical burn events and forwards them to the node for parsing + minting. More...

#include <bridge_catchup_watcher.hpp>

Inherits from sgns::watcher::MessagingWatcher

Public Classes

Name
struct Config
Configuration for the catch-up scan watcher.

Public Types

Name
enum class uint8_t BurnOutcome { Processed, InFlight, Retry}
Outcome of presenting one discovered burn to the node.
using std::function< std::vector< ChainContractPair >()> ChainsProvider
Callback that returns the current set of chains to scan.
using std::function< std::optional< std::string >(const std::string &chain_id_str)> RpcUrlResolver
Callback that resolves a chain-id string to an RPC URL.
using std::function< BurnOutcome(const std::vector< eth::abi::AbiValue > &decoded_values, const std::string &tx_hash_hex, const std::string &chain_id_str)> BurnProcessor
Callback invoked for each discovered burn event.

Public Functions

Name
BridgeCatchupWatcher(const Config & config, MessageCallback message_callback, ChainsProvider chains_provider, RpcUrlResolver rpc_resolver, BurnProcessor burn_processor)
Constructs a BridgeCatchupWatcher.
virtual void startWatching() override
virtual void stopWatching() override
uint64_t GetLastProcessedBlock(uint64_t chain_id) const
Returns the last processed block for a specific chain.

Protected Functions

Name
virtual void watch() override

Additional inherited members

Public Types inherited from sgns::watcher::MessagingWatcher

Name
using std::function< void(const std::string &)> MessageCallback

Public Functions inherited from sgns::watcher::MessagingWatcher

Name
virtual ~MessagingWatcher() =default
bool isRunning() const
void addWatcher(const std::shared_ptr< MessagingWatcher > & newWatcher)
void startAll()
void stopAll()

Protected Functions inherited from sgns::watcher::MessagingWatcher

Name
MessagingWatcher(MessageCallback callback)

Protected Attributes inherited from sgns::watcher::MessagingWatcher

Name
MessageCallback messageCallback
std::atomic_bool running
std::mutex running_mutex
boost::thread watcherThread

Detailed Description

class sgns::evmwatcher::BridgeCatchupWatcher;

Polling watcher that scans bridge chains for historical burn events and forwards them to the node for parsing + minting.

Owns its own boost::thread (via MessagingWatcher). The watch() loop polls eth_getLogs at a configurable interval, tracks the last processed block per chain, and forwards discovered logs through a typed BurnProcessor callback. The callback implementation (provided by GeniusNode) handles ABI parsing and minting — the watcher itself only decodes the raw log.

Public Types Documentation

enum BurnOutcome

Enumerator Value Description
Processed Mint is durably confirmed; the cursor may advance past this burn.
InFlight A mint is reserved and awaiting consensus; hold the cursor, do not resubmit.
Retry No confirmed mint and none in flight; hold the cursor and re-present next poll.

Outcome of presenting one discovered burn to the node.

A plain bool cannot express this: submitting a mint is not the same as the mint being confirmed, and conflating the two let a rejected mint fall behind the block cursor and be lost forever (the burn is then never re-presented, so the tokens burned on the source chain are never minted here).

using ChainsProvider

using sgns::evmwatcher::BridgeCatchupWatcher::ChainsProvider =  std::function<std::vector<ChainContractPair>()>;

Callback that returns the current set of chains to scan.

using RpcUrlResolver

using sgns::evmwatcher::BridgeCatchupWatcher::RpcUrlResolver =  std::function<std::optional<std::string>( const std::string &chain_id_str )>;

Callback that resolves a chain-id string to an RPC URL.

using BurnProcessor

using sgns::evmwatcher::BridgeCatchupWatcher::BurnProcessor =  std::function<BurnOutcome( const std::vector<eth::abi::AbiValue> &decoded_values, const std::string &tx_hash_hex, const std::string &chain_id_str )>;

Callback invoked for each discovered burn event.

Parameters:

  • decoded_values ABI-decoded log parameters.
  • tx_hash_hex Source-chain transaction hash (hex, no 0x).
  • chain_id_str Source chain ID as a decimal string.

Return: Confirmation state of this burn's mint.

The watcher has already decoded the raw log into ABI values. The callback implementation (in GeniusNode) is responsible for:

  1. Calling BridgeRelayer::ParseBurnEventValues(values) to extract amount / token_id / destination
  2. Checking UTXO state (consumed / reserved)
  3. Calling MintTokens()

Only BurnOutcome::Processed lets the per-chain cursor move past this burn's block.

Public Functions Documentation

function BridgeCatchupWatcher

BridgeCatchupWatcher(
    const Config & config,
    MessageCallback message_callback,
    ChainsProvider chains_provider,
    RpcUrlResolver rpc_resolver,
    BurnProcessor burn_processor
)

Constructs a BridgeCatchupWatcher.

Parameters:

  • config Polling and start-block configuration.
  • message_callback Callback for raw messages (MessagingWatcher base).
  • chains_provider Returns the current chain list to scan.
  • rpc_resolver Resolves a chain-id string to an RPC URL.
  • burn_processor Called for each discovered burn log.

function startWatching

virtual void startWatching() override

Reimplements: sgns::watcher::MessagingWatcher::startWatching

function stopWatching

virtual void stopWatching() override

Reimplements: sgns::watcher::MessagingWatcher::stopWatching

function GetLastProcessedBlock

uint64_t GetLastProcessedBlock(
    uint64_t chain_id
) const

Returns the last processed block for a specific chain.

Parameters:

  • chain_id Numeric chain identifier.

Return: Last processed block number, or 0 if never scanned.

Protected Functions Documentation

function watch

virtual void watch() override

Reimplements: sgns::watcher::MessagingWatcher::watch

Updated on 2026-09-15 at 17:28:59 +0000