event_handlers

func (*EventHandlerService) HandleEscrowDepositChallenged ¶

func (s *EventHandlerService) HandleEscrowDepositChallenged(ctx context.Context, tx core.ChannelHubEventHandlerStore, event *core.EscrowDepositChallengedEvent) error

HandleEscrowDepositChallenged processes the EscrowDepositChallenged event emitted when an escrow deposit is challenged on-chain. It marks the channel as Challenged and sets the expiration time. Resolution policy depends on whether the node holds a newer fully-signed state for this channel:

• If a newer signed FINALIZE_ESCROW_DEPOSIT exists, finalize the escrow on the non-home chain.
• Otherwise the user is withholding finalize: defend the node allocation on the home chain by scheduling challengeChannel(...) with the INITIATE_ESCROW_DEPOSIT state. Without this, the user can let the non-home challenge expire, recover escrow-chain funds, and still threaten the home-chain finalize path against the node's locked allocation.

func (*EventHandlerService) HandleEscrowDepositFinalized ¶

func (s *EventHandlerService) HandleEscrowDepositFinalized(ctx context.Context, tx core.ChannelHubEventHandlerStore, event *core.EscrowDepositFinalizedEvent) error

HandleEscrowDepositFinalized processes the EscrowDepositFinalized event emitted when an escrow deposit is successfully finalized on-chain. It updates the channel status to Closed and sets the final state version, completing the deposit lifecycle.

func (*EventHandlerService) HandleEscrowDepositInitiated ¶

func (s *EventHandlerService) HandleEscrowDepositInitiated(ctx context.Context, tx core.ChannelHubEventHandlerStore, event *core.EscrowDepositInitiatedEvent) error

HandleEscrowDepositInitiated processes the EscrowDepositInitiated event emitted when an escrow deposit operation begins on-chain. It updates the escrow channel status to Open, sets the state version, and schedules a checkpoint to finalize the deposit if a matching state exists in the database.

func (*EventHandlerService) HandleEscrowDepositsPurged ¶

func (s *EventHandlerService) HandleEscrowDepositsPurged(ctx context.Context, tx core.ChannelHubEventHandlerStore, event *core.EscrowDepositsPurgedEvent) error

HandleEscrowDepositsPurged processes the EscrowDepositsPurged event emitted when expired escrow deposits are finalized by the on-chain purge queue without a signed FINALIZE_ESCROW_DEPOSIT state. It marks each corresponding escrow channel as Closed, preserving its existing StateVersion.

TODO: consider scoping the DB transaction per channel update instead of wrapping the whole batch, so a single failure does not roll back already-processed channels in the same purge event.

func (*EventHandlerService) HandleEscrowWithdrawalChallenged ¶

func (s *EventHandlerService) HandleEscrowWithdrawalChallenged(ctx context.Context, tx core.ChannelHubEventHandlerStore, event *core.EscrowWithdrawalChallengedEvent) error

HandleEscrowWithdrawalChallenged processes the EscrowWithdrawalChallenged event emitted when an escrow withdrawal is challenged on-chain. It marks the channel as Challenged, sets the expiration time, and schedules a checkpoint for escrow withdrawal with the latest signed state to resolve the challenge.

func (*EventHandlerService) HandleEscrowWithdrawalFinalized ¶

func (s *EventHandlerService) HandleEscrowWithdrawalFinalized(ctx context.Context, tx core.ChannelHubEventHandlerStore, event *core.EscrowWithdrawalFinalizedEvent) error

HandleEscrowWithdrawalFinalized processes the EscrowWithdrawalFinalized event emitted when an escrow withdrawal is successfully finalized on-chain. It updates the channel status to Closed and sets the final state version, completing the withdrawal lifecycle.

func (*EventHandlerService) HandleEscrowWithdrawalInitiated ¶

func (s *EventHandlerService) HandleEscrowWithdrawalInitiated(ctx context.Context, tx core.ChannelHubEventHandlerStore, event *core.EscrowWithdrawalInitiatedEvent) error

HandleEscrowWithdrawalInitiated processes the EscrowWithdrawalInitiated event emitted when an escrow withdrawal operation begins on-chain. It updates the escrow channel status to Open and sets the state version to reflect the initiated withdrawal.

func (*EventHandlerService) HandleHomeChannelChallenged ¶

func (s *EventHandlerService) HandleHomeChannelChallenged(ctx context.Context, tx core.ChannelHubEventHandlerStore, hub core.ReadOnlyChannelHub, event *core.HomeChannelChallengedEvent) error

HandleHomeChannelChallenged processes the HomeChannelChallenged event emitted when a potentially stale state is submitted on-chain. It marks the channel as Challenged and persists the challenge expiry so subsequent state-submission paths (CheckActiveChannel, RefreshUserEnforcedBalance) stop treating the channel as open. Automatic challenge response is intentionally disabled: the latest signed state may carry an intent (e.g. CLOSE, escrow initiate/finalize, migration) that cannot be resolved via ScheduleCheckpoint, and silently queueing an impossible transaction risks letting the challenge expire on a stale state. A warning is emitted so operators submit the appropriate on-chain action manually before expiry.

func (*EventHandlerService) HandleHomeChannelCheckpointed ¶

func (s *EventHandlerService) HandleHomeChannelCheckpointed(ctx context.Context, tx core.ChannelHubEventHandlerStore, hub core.ReadOnlyChannelHub, event *core.HomeChannelCheckpointedEvent) error

HandleHomeChannelCheckpointed processes the HomeChannelCheckpointed event emitted when a channel state is successfully checkpointed on-chain. It updates the channel's state version and clears the Challenged status if present, returning the channel to Open — unless the local DB already holds a co-signed Finalize for this channel, in which case the post-Finalize Closing marker is restored instead. Without that restore, a Closing → Challenged → Open sequence driven by on-chain events would erase the fact that the node has already signed a finalized state, and CheckActiveChannel would let the user submit further transitions past the finalized state.

func (*EventHandlerService) HandleHomeChannelClosed ¶

func (s *EventHandlerService) HandleHomeChannelClosed(ctx context.Context, tx core.ChannelHubEventHandlerStore, hub core.ReadOnlyChannelHub, event *core.HomeChannelClosedEvent) error

HandleHomeChannelClosed processes the HomeChannelClosed event emitted when a home channel is finalized and closed on-chain. It updates the channel status to Closed and sets the final state version. Once closed, no further state updates are possible for this channel.

Additionally, when the channel was locally Challenged at the time of close, the handler issues a ChallengeRescue state crediting the user the net receiver-minus-sender balance accrued strictly above the closure version. The rescue runs unconditionally on the Challenged → Closed transition: both path-1 (timeout on a stale candidate) and path-2 (cooperative close on a signed Finalize) routes pass through this branch, and the constructor + prev source pick the correct placement for the rescue row.

MF3-I01 recovery anchor. This handler is the single recovery point for the wedge state described in audit finding MF3-I01: a receiver credit issued during the challenge window inherits HomeChannelID from currentState via NextState(), so the user's latest stored state can transiently point at a channel that closes via path-1 before the next receiver-credit issuance reads currentState again. The listener ordering & idempotency invariant (pkg/blockchain/evm/listener.go, see processEvents doc) guarantees HandleHomeChannelChallenged has already run for any path-1 close, so wasChallenged is true here and the rescue advances the user past the closed channel. Subsequent receiver-credit issuance reads the rescue row as currentState and no longer carries the closed channel reference, so request_creation can reopen on the same (wallet, asset) through the normal flow.

func (*EventHandlerService) HandleHomeChannelCreated ¶

func (s *EventHandlerService) HandleHomeChannelCreated(ctx context.Context, tx core.ChannelHubEventHandlerStore, event *core.HomeChannelCreatedEvent) error

HandleHomeChannelCreated processes the HomeChannelCreated event emitted when a home channel is successfully created on-chain. It updates the channel status to Open and sets the state version. The channel must exist in the database with type ChannelTypeHome, otherwise a warning is logged. A legitimate Created event is observed exactly once per channel, when the local row is still in the ChannelStatusVoid state seeded by CreateChannel. If the channel has already advanced past Void, this handler is being re-fired (indexer replay, chain reorg, block reprocessing) and any mutation here would regress the post-Open lifecycle — most importantly resetting a Closing channel back to Open and erasing the Finalize marker that gates CheckActiveChannel.

func (*EventHandlerService) HandleHomeChannelMigrated ¶

func (s *EventHandlerService) HandleHomeChannelMigrated(ctx context.Context, tx core.ChannelHubEventHandlerStore, event *core.HomeChannelMigratedEvent) error

HandleHomeChannelMigrated processes the HomeChannelMigrated event emitted when a home channel is migrated to a new version or blockchain. This is currently not implemented and logs a warning. TODO: Implement HomeChannelMigrated handler logic

func (*EventHandlerService) HandleNodeBalanceUpdated ¶

func (s *EventHandlerService) HandleNodeBalanceUpdated(ctx context.Context, tx core.ChannelHubEventHandlerStore, event *core.NodeBalanceUpdatedEvent) error

HandleNodeBalanceUpdated processes the NodeBalanceUpdated event emitted when the node's on-chain liquidity changes. It records the new node liquidity for the (blockchain, asset) pair via SetNodeBalance; this is observability data only and does not affect user staking state.

func (*MockStore) GetChannelByID ¶

func (m *MockStore) GetChannelByID(channelID string) (*core.Channel, error)

GetChannelByID mocks retrieving a channel by its ID

func (*MockStore) GetLastStateByChannelID ¶

func (m *MockStore) GetLastStateByChannelID(channelID string, signed bool) (*core.State, error)

GetLastStateByChannelID mocks retrieving the last state for a channel

func (*MockStore) GetLastUserState ¶

func (m *MockStore) GetLastUserState(wallet, asset string, signed bool) (*core.State, error)

GetLastUserState mocks retrieving the most recent state for a user's asset across all channels and detached chain entries.

func (*MockStore) GetStateByChannelIDAndVersion ¶

func (m *MockStore) GetStateByChannelIDAndVersion(channelID string, version uint64) (*core.State, error)

GetStateByChannelIDAndVersion mocks retrieving a specific state version for a channel

func (*MockStore) HasSignedFinalize ¶

func (m *MockStore) HasSignedFinalize(channelID string) (bool, error)

HasSignedFinalize mocks the existence check for a node-signed Finalize state on the given home channel.

func (*MockStore) LockUserState ¶

func (m *MockStore) LockUserState(wallet, asset string) (decimal.Decimal, error)

LockUserState mocks acquiring SELECT ... FOR UPDATE on a user's balance row.

func (*MockStore) LockUserStateForHomeChannel ¶ added in v1.4.0

func (m *MockStore) LockUserStateForHomeChannel(channelID string) (*core.Channel, error)

LockUserStateForHomeChannel mocks locking the balance row of the channel owner and returning the channel read under that lock.

func (*MockStore) RecordTransaction ¶

func (m *MockStore) RecordTransaction(tx core.Transaction, applicationID string) error

RecordTransaction mocks recording a transaction row.

func (*MockStore) RefreshUserEnforcedBalance ¶

func (m *MockStore) RefreshUserEnforcedBalance(wallet, asset string) error

RefreshUserEnforcedBalance mocks recomputing the locked balance from DB

func (*MockStore) ScheduleChallenge ¶

func (m *MockStore) ScheduleChallenge(stateID string, chainID uint64) error

ScheduleChallenge mocks scheduling a challenge operation

func (*MockStore) ScheduleCheckpoint ¶

func (m *MockStore) ScheduleCheckpoint(stateID string, chainID uint64) error

ScheduleCheckpoint mocks scheduling a checkpoint operation

func (*MockStore) ScheduleFinalizeEscrowDeposit ¶

func (m *MockStore) ScheduleFinalizeEscrowDeposit(stateID string, chainID uint64) error

ScheduleFinalizeEscrowDeposit mocks scheduling an escrow deposit checkpoint

func (*MockStore) ScheduleFinalizeEscrowWithdrawal ¶

func (m *MockStore) ScheduleFinalizeEscrowWithdrawal(stateID string, chainID uint64) error

ScheduleFinalizeEscrowWithdrawal mocks scheduling an escrow withdrawal checkpoint

func (*MockStore) ScheduleInitiateEscrowDeposit ¶

func (m *MockStore) ScheduleInitiateEscrowDeposit(stateID string, chainID uint64) error

ScheduleInitiateEscrowDeposit mocks scheduling an escrow deposit checkpoint

func (*MockStore) SetNodeBalance ¶

func (m *MockStore) SetNodeBalance(blockchainID uint64, asset string, value decimal.Decimal) error

SetNodeBalance mocks upserting the on-chain liquidity

func (*MockStore) StoreUserState ¶

func (m *MockStore) StoreUserState(state core.State, applicationID string) error

StoreUserState mocks persisting a user state row.

func (*MockStore) SumNetTransitionAmountAfterVersion ¶

func (m *MockStore) SumNetTransitionAmountAfterVersion(channelID string, minVersion uint64) (decimal.Decimal, error)

SumNetTransitionAmountAfterVersion mocks the net-change query used to compute challenge-rescue amounts on a closed channel.

func (*MockStore) UpdateChannel ¶

func (m *MockStore) UpdateChannel(channel core.Channel) error

UpdateChannel mocks updating a channel in the database

func (*MockStore) UpdateStateSigsIfMissing ¶

func (m *MockStore) UpdateStateSigsIfMissing(channelID string, version uint64, userSig, nodeSig string) error

UpdateStateSigsIfMissing mocks backfilling missing user and/or node signatures for a stored state.