cmd/abigen: (v2) added a package-level error for event signature mismatch

[rglKali]

Summary

Replaces the inline errors.New("event signature mismatch") in generated UnpackXxxEvent methods with per-event package-level sentinel errors (e.g. ErrTransferSignatureMismatch, ErrApprovalSignatureMismatch), allowing callers to reliably distinguish a topic mismatch from a genuine decoding failure via errors.Is.

Each event gets its own sentinel, generated via the abigen template:

var ErrTransferSignatureMismatch = errors.New("event signature mismatch")

This scoping is intentional — it allows callers to be precise about which event was mismatched, which is useful when routing logs across multiple unpackers.

Motivation

Previously, all errors returned from UnpackXxxEvent were indistinguishable without string matching. This is especially problematic when processing logs sourced from eth_getBlockReceipts, where a caller receives the full set of logs for a block across all contracts and event types. In that context, a signature mismatch is expected and should be skipped, while any other error (malformed data, topic parsing failure) indicates something is genuinely wrong and should halt execution:

for _, log := range blockLogs {
    event, err := contract.UnpackTransferEvent(log)
    if errors.Is(err, gen.ErrTransferSignatureMismatch) {
        continue // not our event, expected
    }
    if err != nil {
        return fmt.Errorf("unexpected decode failure: %w", err) // alert
    }
    // process event
}

Changes:

• abigen template: generates a ErrXxxSignatureMismatch sentinel per event and returns it on topic mismatch instead of an inline error
• Existing generated bindings & testdata: regenerated to reflect the update

Implements #34075

[jwasinger]

Makes sense to me. I'll tag this so we can discuss it as a team.

[lightclient]

Generally makes sense. One question is if this error should be defined in the abigen package or like you have here where it is generated for each file. I don't have a great intuition which is more correct to be honest.

[MariusVanDerWijden]

LGTM