bridgetracker

type ActivityBridgeScanner = domain.ActivityBridgeScanner

type ActivityCache struct {
	// contains filtered or unexported fields
}

type ActivityClaimChecker = domain.ActivityClaimChecker

type ActivityEngine struct {
	// contains filtered or unexported fields
}

type ActivityEngineConfig struct {
	// PollInterval is the period between refresh rounds over the supervised addresses
	PollInterval time.Duration
	// MaxConcurrentRefreshes bounds how many addresses are refreshed at once in total — both
	// tick's regular sweep and the trigger fast-path share this same bound (see refreshOne) —
	// since each refresh is a full multi-network scan (see domain.ActivitySupervisedStore.
	// RefreshAddress), so, unlike the tracker's per-step resolutions, running every supervised
	// address at once could spawn far more outbound bridge-service/RPC calls than the configured
	// concurrency limits on the scanner side expect. A value <= 0 falls back to
	// DefaultActivityEngineMaxConcurrentRefreshes
	MaxConcurrentRefreshes int
	// IdleTimeout is how long an unaccessed address is kept supervised before being forgotten
	// (see domain.ActivitySupervisedStore.PruneIdle). A value <= 0 falls back to
	// DefaultActivityEngineIdleTimeout
	IdleTimeout time.Duration
	// RefreshTimeout bounds a single RefreshAddress call (see refreshOne), mirroring
	// EngineConfig.ResolveTimeout's reasoning for the tracker's own per-step resolutions: without
	// it, one hung network scan or RPC client can occupy a concurrency slot indefinitely, and —
	// because tick waits for every refresh it started before returning — wedge the whole loop
	// behind it (see tick's own doc). A value <= 0 falls back to
	// DefaultActivityEngineRefreshTimeout
	RefreshTimeout time.Duration
}

type ActivityEntry = domain.ActivityEntry

type ActivityQuerier = domain.ActivityQuerier

type ActivityRegistry = domain.ActivityRegistry

type ActivitySourceBridgeServiceConfig struct {
	// PageSize is the page size used while paging through a network's own
	// GET /bridge/v1/bridges scanning for a from_address (see fetchNewBridgesFrom). A value <= 0
	// falls back to DefaultActivitySourceBridgeServicePageSize.
	PageSize uint32 `mapstructure:"PageSize"`

	// Timeout bounds every individual HTTP call this source makes to a network's aggkit bridge
	// service (GetBridges, GetClaims, GetSyncStatus, GetL1InfoTreeIndex,
	// GetInjectedL1InfoLeaf — see bridgeservice/client.Client) — not the overall GET
	// /activity/from/{from_address} request itself, which can still issue several such calls per
	// bridge (see fetchNewBridgesFrom, ActivityCache.refresh). A value <= 0 falls back to
	// DefaultActivitySourceBridgeServiceTimeout.
	Timeout types.Duration `mapstructure:"Timeout"`

	// MaxConcurrentNetworkScans bounds how many networks sources.ActivitySource.BridgesFrom
	// scans at once — each one, in turn, queries this bridge-service source and the RPC
	// fallback (see ActivitySourceRPC) concurrently, so the actual number of in-flight calls is
	// up to twice this. Networks beyond the limit simply wait their turn instead of every
	// configured network being dialed at once, regardless of how many there are. A value <= 0
	// falls back to DefaultActivitySourceBridgeServiceMaxConcurrentNetworkScans.
	MaxConcurrentNetworkScans int `mapstructure:"MaxConcurrentNetworkScans"`
}

type ActivitySourceRPCConfig struct {
	// Enabled turns the RPC-based fallback on: GET /activity/from/{from_address} additionally
	// scans each network's own bridge contract directly via RPC over
	// [RangeFromBlock, RangeToBlock], in parallel with ActivitySourceBridgeService, merging in
	// whatever bridges that bridge service has not indexed yet. false keeps today's
	// bridge-service-only behavior.
	Enabled bool `mapstructure:"Enabled"`

	// RangeFromBlock is the lower bound of the RPC scan window, e.g. "LatestBlock/-90" (last 90
	// blocks) or "FinalizedBlock". A value <= 0/empty falls back to
	// DefaultActivitySourceRPCRangeFromBlock. Ignored when Enabled is false.
	RangeFromBlock aggkittypes.BlockNumberFinality `jsonschema:"enum=LatestBlock,enum=SafeBlock,enum=FinalizedBlock,enum=PendingBlock" mapstructure:"RangeFromBlock"` //nolint:lll

	// RangeToBlock is the upper bound of the RPC scan window, typically "LatestBlock". Ignored
	// when Enabled is false.
	RangeToBlock aggkittypes.BlockNumberFinality `jsonschema:"enum=LatestBlock,enum=SafeBlock,enum=FinalizedBlock,enum=PendingBlock" mapstructure:"RangeToBlock"` //nolint:lll
}

type ActivitySupervisedStore = domain.ActivitySupervisedStore

type ActivityTriggerable = domain.ActivityTriggerable

type BridgeAddressResolver = domain.BridgeAddressResolver

type BridgeEventSource = domain.BridgeEventSource

type BridgeInfo = domain.BridgeInfo

type BridgeStepPath = domain.BridgeStepPath

type BridgeTracker struct {
	// contains filtered or unexported fields
}

type CertificateSource interface {
	// CertificateFor returns the certificate that includes the bridge, or nil if the bridge
	// is not part of any certificate yet
	CertificateFor(ctx context.Context, bridge *BridgeInfo) (*types.CertificateInclusionData, error)
}

type ClaimChecker interface {
	// IsClaimed reports whether bridge has already been claimed on its destination network
	IsClaimed(ctx context.Context, bridge *BridgeInfo) (bool, error)
}

type ClaimSource interface {
	// ClaimFor returns the claim transaction of the bridge on the destination network, or
	// nil if the destination network's bridge service has not indexed it yet
	ClaimFor(ctx context.Context, bridge *BridgeInfo) (*types.ClaimResult, error)
}

type Config struct {
	// RetentionPeriod is how long a terminal bridge (Finished, or failed to ever resolve)
	// stays queryable before the tracker forgets it. Clients polling or subscribed observe
	// the terminal TrackingStatus during this window; once forgotten, a new request for the
	// same tx re-registers it and tracking restarts from scratch — the retry path for a tx
	// the tracker gave up on
	RetentionPeriod types.Duration `mapstructure:"RetentionPeriod"`

	// IdleTimeout is how long a bridge — terminal or still active — stays in the registry once
	// nobody has read it (no Get/GetAndAwait) and it has no active WebSocket subscriber. Unlike
	// RetentionPeriod, this applies regardless of TrackingStatus: a bridge that never resolves
	// and that nobody is polling or subscribed to would otherwise stay supervised (and in
	// memory) forever. A value <= 0 falls back to DefaultIdleTimeout
	IdleTimeout types.Duration `mapstructure:"IdleTimeout"`

	// RegisterResolveTimeout is how long the GetTxStatus endpoint waits, the first time a tx is
	// registered, for the tracking engine's immediate resolution attempt (triggered right away
	// instead of on the next poll tick, see Registry.GetAndAwait) to produce an update before
	// answering. A value <= 0 disables the wait: the first response is always the bare
	// Registered snapshot, exactly as before this field existed. Looking up an already-registered
	// tx never waits, regardless of this setting.
	RegisterResolveTimeout types.Duration `mapstructure:"RegisterResolveTimeout"`

	// L1BlockFinality is the finality level a bridge's creating tx receipt must reach on L1
	// (network 0) before the tracker accepts it (see sources.BridgeEventSource): accepting
	// a receipt from a block that later gets reorged out would otherwise leave the tracker
	// permanently following an orphaned deposit count/block, since a resolved bridge is never
	// re-checked (see TrackingBridgeTx.IsDone)
	L1BlockFinality aggkittypes.BlockNumberFinality `` //nolint:lll
	/* 132-byte string literal not displayed */

	// L2BlockFinality is the finality level a bridge's creating tx receipt must reach on any
	// L2 (non-zero network) before the tracker accepts it; see L1BlockFinality for the reasoning
	L2BlockFinality aggkittypes.BlockNumberFinality `` //nolint:lll
	/* 132-byte string literal not displayed */

	// BridgeAddrs is the static networkID -> canonical bridge contract address override used
	// to reject a BridgeEvent log emitted by a contract other than the origin network's real
	// bridge (see sources.BridgeEventSource). A network absent from this map (the default,
	// empty map) falls back to resolving its canonical bridge address through the bridge
	// service finder — there is no permissive fallback that matches logs on the event
	// signature alone.
	BridgeAddrs map[uint32]common.Address `mapstructure:"BridgeAddrs"`

	// L1GlobalExitRootAddress is the L1 GlobalExitRoot contract address (see sources.GERSource)
	L1GlobalExitRootAddress common.Address `mapstructure:"L1GlobalExitRootAddress"`

	// L2GlobalExitRootAddress is the static networkID -> GlobalExitRootManagerL2 contract address
	// map used as a fallback when a destination network's bridge-service instance does not
	// report the L2 block a covering GER was actually injected at (see sources.GERSource,
	// WaitingGERInjection's InjectedGERResult.L2InjectedGER): for a network present here, the
	// tracker scans that network's own L2 for the UpdateHashChainValue event instead of leaving
	// L2InjectedGER absent. A network absent from this map (the default, empty map) never gets
	// this fallback attempted — no different from before it existed
	L2GlobalExitRootAddress map[uint32]common.Address `mapstructure:"L2GlobalExitRootAddress"`

	// L2InjectionLookbackBlocks bounds how many blocks the L2GlobalExitRootAddress fallback (see
	// sources.GERSource.findL2InjectionBlockBackwards) scans backwards from the destination
	// network's head before giving up, instead of continuing all the way back to genesis: on a
	// network whose fallback never finds the event (e.g. a wrong L2GlobalExitRootAddress entry,
	// or a GER injected before the contract even existed there), an unbounded scan would walk the
	// entire chain history in bridgeservicefinder.DefaultBlockChunkSize-sized eth_getLogs calls
	// every time. A value <= 0 falls back to DefaultL2InjectionLookbackBlocks.
	L2InjectionLookbackBlocks uint64 `mapstructure:"L2InjectionLookbackBlocks"`

	// MaxTrackedBridges bounds how many distinct bridges the registry (see Registry) accepts at
	// once; a request that would exceed it fails instead of registering the bridge — reaching
	// the cap never evicts an existing entry to make room. On the default in-memory adapter,
	// RetentionPeriod and IdleTimeout are what keep the registry under it during normal
	// operation; the SQLite-backed adapter (see DBPath) does not evict anything yet, so once
	// reached there the cap is effectively permanent until the process restarts. A value <= 0
	// falls back to DefaultMaxTrackedBridges. Only meaningful to the binary wiring Registry
	// from it — ignored when Registry is set to a custom implementation.
	MaxTrackedBridges int `mapstructure:"MaxTrackedBridges"`

	// MaxConcurrentResolutions bounds how many active bridges the engine's poll tick resolves at
	// once (see EngineConfig.MaxConcurrentResolutions) — independent of MaxTrackedBridges, which
	// bounds the registry's size, not how much of it is in flight during a single tick. A value
	// <= 0 falls back to DefaultMaxConcurrentResolutions.
	MaxConcurrentResolutions int `mapstructure:"MaxConcurrentResolutions"`

	// DBPath is the SQLite file the supervised-bridges registry persists to (see
	// bridgetracker/db.NewSQLiteRegistry). Empty (the default) keeps the in-memory adapter
	// (NewMemoryRegistry): state does not survive a restart, exactly as before this field
	// existed. Setting it makes the binary construct a SQLite-backed registry instead, so
	// already-resolved bridges don't need re-resolving — and every bridge-service/agglayer call
	// behind that — after a restart. Only meaningful to the binary wiring Registry from it;
	// ignored once Registry is set.
	DBPath string `mapstructure:"DBPath"`

	// AgglayerClient configures the client used to query the agglayer for a bridge's covering
	// certificate and that certificate's current status (see sources.CertificateSource)
	AgglayerClient agglayer.ClientConfig `mapstructure:"AgglayerClient"`

	Logger aggkitcommon.Logger `mapstructure:"-"`

	// ConfigSHA1 is the sha1sum (hex) of the configuration the binary was started with,
	// exposed by the health endpoint to check that all instances behind a proxy run the
	// same configuration
	ConfigSHA1 string `mapstructure:"-"`

	// Registry is the supervised-bridges subsystem to use. Leave nil to get the in-memory
	// adapter (single instance); inject a shared-store implementation so several tracker
	// instances behind a proxy answer for any registered tx
	Registry SupervisedRegistry `mapstructure:"-"`

	// CORS mirrors the proxy's REST.CORS: it governs which origins may open a WebSocket
	// connection to this tracker's endpoints (see aggkitcommon.CORSConfig.OriginAllowed for
	// why WebSocket needs its own check instead of reusing the REST CORS headers). Wired
	// programmatically from REST.CORS by the binary, not read directly from [Tracker].
	CORS aggkitcommon.CORSConfig `mapstructure:"-"`

	// ActivityScanner and ActivityClaims wire the optional GET /activity/from/{from_address}
	// endpoint (see ActivityCache): ActivityScanner scans every configured bridge service for
	// bridges sent by an address, ActivityClaims resolves each one's claim state. Both are
	// wired programmatically by the binary (see sources.ActivitySource, which implements
	// both); leaving either nil leaves the endpoint unregistered entirely.
	ActivityScanner ActivityBridgeScanner `mapstructure:"-"`
	ActivityClaims  ActivityClaimChecker  `mapstructure:"-"`

	// Activity, when set, is used as the activity endpoint's ActivityRegistry as-is instead of
	// building an in-memory ActivityCache from ActivityScanner/ActivityClaims — the same
	// override pattern as Registry, so a caller can plug in a persisted implementation (see
	// bridgetracker/db.NewSQLiteActivityStore, which itself still needs ActivityScanner/
	// ActivityClaims — it takes them directly as constructor arguments, not through this
	// Config). ActivityScanner/ActivityClaims/ActivityIdleTimeout are ignored once this is set.
	Activity ActivityRegistry `mapstructure:"-"`

	// ActivityIdleTimeout is how long a from_address stays supervised (see ActivityCache,
	// ActivityEngine.PruneIdle) with no GET /activity/from/{from_address} call for it, before
	// being forgotten entirely (bridges, claim state, everything cached for it). Same semantics
	// as IdleTimeout, a separate knob because it governs a different cache. A value <= 0 falls
	// back to DefaultIdleTimeout.
	ActivityIdleTimeout types.Duration `mapstructure:"ActivityIdleTimeout"`

	// ActivityPollInterval is the period between the activity engine's background refresh
	// rounds over every supervised from_address (see ActivityEngine, ActivityEngineConfig.
	// PollInterval). A value <= 0 falls back to DefaultActivityPollInterval.
	ActivityPollInterval types.Duration `mapstructure:"ActivityPollInterval"`

	// MetricsSampleInterval is how often the Prometheus gauges (cache size, alive trackers/
	// activities) are refreshed (see BridgeTracker.StartMetricsSampler). Only used when the
	// proxy's [Prometheus] section is enabled. A value <= 0 falls back to
	// DefaultMetricsSampleInterval.
	MetricsSampleInterval types.Duration `mapstructure:"MetricsSampleInterval"`

	// ActivityRegisterResolveTimeout is how long the activity endpoint waits, the first time a
	// from_address is registered, for the activity engine's immediate refresh attempt
	// (triggered right away instead of on the next poll tick, see ActivitySupervisedStore.
	// RegisterAndAwait) to complete before answering. A value <= 0 disables the wait: the first
	// response is always whatever is cached so far (possibly empty). Looking up an
	// already-registered address never waits, regardless of this setting.
	ActivityRegisterResolveTimeout types.Duration `mapstructure:"ActivityRegisterResolveTimeout"`

	// ActivityMaxConcurrentRefreshes bounds how many supervised addresses the activity engine's
	// poll tick refreshes at once (see ActivityEngineConfig.MaxConcurrentRefreshes). A value
	// <= 0 falls back to DefaultActivityMaxConcurrentRefreshes.
	ActivityMaxConcurrentRefreshes int `mapstructure:"ActivityMaxConcurrentRefreshes"`

	// BridgeAddressResolver wires the optional GET /bridge-address[/{network_id}] endpoint: it
	// resolves the bridge contract address for one network, or every network it currently
	// knows about. Wired programmatically by the binary (bridgeservicefinder.Finder satisfies
	// this port directly); leaving it nil leaves the endpoint unregistered entirely.
	BridgeAddressResolver BridgeAddressResolver `mapstructure:"-"`

	// ActivitySourceBridgeService configures the bridge-service-backed ActivityBridgeScanner —
	// the existing GET /bridge/v1/bridges-based source behind GET /activity/from/{from_address}
	// (see sources.ActivitySource.BridgesFrom's REST path).
	ActivitySourceBridgeService ActivitySourceBridgeServiceConfig `mapstructure:"ActivitySourceBridgeService"`

	// ActivitySourceRPC configures the RPC-based fallback ActivityBridgeScanner (see
	// sources.activityRPCScanner, agglayer/aggkit#1837): a safety net that scans each network's
	// own bridge contract directly via RPC, in parallel with ActivitySourceBridgeService, for
	// bridges that service has not indexed yet. It never calls debug_traceTransaction, so it
	// works against any standard JSON-RPC endpoint (the debug namespace is not required); the
	// trade-off is that an Asset bridge routed through an intermediate contract (not sent
	// directly to the bridge contract) is not resolved by this fallback and is silently skipped —
	// it still shows up once ActivitySourceBridgeService's own indexer (which does trace) catches
	// up with it.
	ActivitySourceRPC ActivitySourceRPCConfig `mapstructure:"ActivitySourceRPC"`

	// PendingNetworksLister exposes the bridge service finder's not-yet-activated networks on the
	// health endpoint. Wired programmatically by the binary; nil is valid (the field is omitted)
	PendingNetworksLister api.PendingNetworksLister `mapstructure:"-"`
}

type Engine struct {
	// contains filtered or unexported fields
}

type EngineConfig struct {
	// PollInterval is the period between resolution rounds over the supervised list
	PollInterval time.Duration
	// ResolveTimeout bounds the source calls of a single bridge resolution
	ResolveTimeout time.Duration
	// UnresolvedTimeout is how long a supervised tx is given, since first seen unresolved, to
	// have FindBridge succeed before it is marked terminally failed (TrackingStatus becomes
	// Error, with an exhausted ErrorStep explaining why)
	UnresolvedTimeout time.Duration
	// RetentionPeriod is how long a terminal bridge stays queryable before being forgotten
	// (see DefaultEngineRetentionPeriod)
	RetentionPeriod time.Duration
	// IdleTimeout is how long an unaccessed, unsubscribed bridge — terminal or still active —
	// is kept before being forgotten (see DefaultEngineIdleTimeout)
	IdleTimeout time.Duration
	// MaxConcurrentResolutions bounds how many active bridges tick resolves at once: the
	// supervised list can hold as many entries as Config.MaxTrackedBridges allows (registration
	// is externally driven), so resolving it with one goroutine per entry and no cap could spawn
	// as many outbound source calls at once, exhausting memory/sockets/RPC capacity well before
	// that many bridges are ever actually active. A value <= 0 falls back to
	// DefaultEngineMaxConcurrentResolutions
	MaxConcurrentResolutions int
}

type EngineSources struct {
	Bridges                BridgeEventSource
	Certificates           CertificateSource
	GERs                   GERSource
	WaitingGERUpdateSource domain.WaitingGERUpdateSource
	LERs                   LERSource
	ClaimChecker           ClaimChecker
	Claims                 ClaimSource
	Settlement             SettlementSource
	// SettlementHistory backs WaitL1SettledGERResolver's exact-settlement search (see issue
	// #1817): in practice the same concrete instance as Certificates, which also implements
	// domain.SettlementHistorySource
	SettlementHistory domain.SettlementHistorySource
}

type GERSource interface {
	// OriginGER returns the GER update on the origin network that covers the bridge, or nil
	// if the bridge is not covered by any GER update yet. Only queried for L1-originated
	// bridges
	OriginGER(ctx context.Context, bridge *BridgeInfo) (*types.GERData, error)

	// InjectedGER returns the GER injected on the destination network that covers the
	// bridge, or nil if no covering GER has been injected yet. Only meaningful when the
	// destination is an L2 (injection does not apply to Mainnet)
	InjectedGER(ctx context.Context, bridge *BridgeInfo) (*types.GERData, error)

	// L1InfoTreeIndexForGER resolves the L1 info tree leaf index ger (produced by the bridge's
	// certificate settlement, see types.L1SettledGERResult) landed at, or nil if the L1 info
	// tree has not caught up with it yet. Only queried by StepWaitL1SettledGER, and only when
	// the settlement tx did not emit UpdateL1InfoTreeV2 (which already carries the index)
	L1InfoTreeIndexForGER(ctx context.Context, bridge *BridgeInfo, ger common.Hash) (*uint32, error)

	// InjectedGERAtIndex returns the GER injected at leafIndex on the bridge's destination
	// network, or nil if it has not been injected yet. Only queried for L2-originated bridges
	// arriving at an L2, right after StepWaitL1SettledGER
	InjectedGERAtIndex(ctx context.Context, bridge *BridgeInfo, leafIndex uint32) (*types.GERData, error)

	// L1InfoTreeIndexForBridge returns the L1 info tree leaf index covering bridge's origin
	// deposit — GET /bridge/v1/l1-info-tree-index, queried against the bridge-service instance
	// that will build the claim proof for it: the origin network's own instance, or, when the
	// origin is mainnet (which has no bridge-service deployment of its own), the destination's
	// — or nil if that instance's own L1 info tree sync has not caught up to this deposit yet.
	// Only queried by StepWaitingL1InfoLeafAvailable
	L1InfoTreeIndexForBridge(ctx context.Context, bridge *BridgeInfo) (*uint32, error)
}

type LERSource interface {
	// OriginLER returns the LER update on the origin L2 network that covers the bridge, or
	// nil if the bridge is not covered yet
	OriginLER(ctx context.Context, bridge *BridgeInfo) (*types.LERUpdateResult, error)
}

type SettlementSource interface {
	// SettlementGERUpdate returns the evidence read off settlementTxHash's L1 receipt once it
	// reaches the configured L1 finality, or nil if it is not there yet
	SettlementGERUpdate(
		ctx context.Context, bridge *BridgeInfo, settlementTxHash common.Hash,
	) (*types.L1SettledGERResult, error)
}

type StatusNotifier = domain.StatusNotifier

type SupervisedRegistry = domain.SupervisedRegistry

type SupervisedStore = domain.SupervisedStore

type TrackingID = domain.TrackingID