cmd/abigen/v2: add package-level errors (#34076)

# 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:

```go
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:

```go
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

accounts/abi/abigen/source2.go.tpl

@@ -183,8 +183,11 @@ var (
 		// Solidity: {{.Original.String}}
 		func ({{ decapitalise $contract.Type}} *{{$contract.Type}}) Unpack{{.Normalized.Name}}Event(log *types.Log) (*{{$contract.Type}}{{.Normalized.Name}}, error) {
 			event := "{{.Original.Name}}"
-			if len(log.Topics) == 0 || log.Topics[0] != {{ decapitalise $contract.Type}}.abi.Events[event].ID {
-				return nil, errors.New("event signature mismatch")
+			if len(log.Topics) == 0 {
+				return nil, bind.ErrNoEventSignature
+			}
+			if log.Topics[0] != {{ decapitalise $contract.Type}}.abi.Events[event].ID {
+				return nil, bind.ErrEventSignatureMismatch
 			}
 			out := new({{$contract.Type}}{{.Normalized.Name}})
 			if len(log.Data) > 0 {

accounts/abi/abigen/testdata/v2/crowdsale.go.txt

@@ -360,8 +360,11 @@ func (CrowdsaleFundTransfer) ContractEventName() string {
 // Solidity: event FundTransfer(address backer, uint256 amount, bool isContribution)
 func (crowdsale *Crowdsale) UnpackFundTransferEvent(log *types.Log) (*CrowdsaleFundTransfer, error) {
 	event := "FundTransfer"
-	if len(log.Topics) == 0 || log.Topics[0] != crowdsale.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != crowdsale.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(CrowdsaleFundTransfer)
 	if len(log.Data) > 0 {

accounts/abi/abigen/testdata/v2/dao.go.txt

@@ -606,8 +606,11 @@ func (DAOChangeOfRules) ContractEventName() string {
 // Solidity: event ChangeOfRules(uint256 minimumQuorum, uint256 debatingPeriodInMinutes, int256 majorityMargin)
 func (dAO *DAO) UnpackChangeOfRulesEvent(log *types.Log) (*DAOChangeOfRules, error) {
 	event := "ChangeOfRules"
-	if len(log.Topics) == 0 || log.Topics[0] != dAO.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != dAO.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(DAOChangeOfRules)
 	if len(log.Data) > 0 {
@@ -648,8 +651,11 @@ func (DAOMembershipChanged) ContractEventName() string {
 // Solidity: event MembershipChanged(address member, bool isMember)
 func (dAO *DAO) UnpackMembershipChangedEvent(log *types.Log) (*DAOMembershipChanged, error) {
 	event := "MembershipChanged"
-	if len(log.Topics) == 0 || log.Topics[0] != dAO.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != dAO.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(DAOMembershipChanged)
 	if len(log.Data) > 0 {
@@ -692,8 +698,11 @@ func (DAOProposalAdded) ContractEventName() string {
 // Solidity: event ProposalAdded(uint256 proposalID, address recipient, uint256 amount, string description)
 func (dAO *DAO) UnpackProposalAddedEvent(log *types.Log) (*DAOProposalAdded, error) {
 	event := "ProposalAdded"
-	if len(log.Topics) == 0 || log.Topics[0] != dAO.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != dAO.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(DAOProposalAdded)
 	if len(log.Data) > 0 {
@@ -736,8 +745,11 @@ func (DAOProposalTallied) ContractEventName() string {
 // Solidity: event ProposalTallied(uint256 proposalID, int256 result, uint256 quorum, bool active)
 func (dAO *DAO) UnpackProposalTalliedEvent(log *types.Log) (*DAOProposalTallied, error) {
 	event := "ProposalTallied"
-	if len(log.Topics) == 0 || log.Topics[0] != dAO.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != dAO.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(DAOProposalTallied)
 	if len(log.Data) > 0 {
@@ -780,8 +792,11 @@ func (DAOVoted) ContractEventName() string {
 // Solidity: event Voted(uint256 proposalID, bool position, address voter, string justification)
 func (dAO *DAO) UnpackVotedEvent(log *types.Log) (*DAOVoted, error) {
 	event := "Voted"
-	if len(log.Topics) == 0 || log.Topics[0] != dAO.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != dAO.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(DAOVoted)
 	if len(log.Data) > 0 {

accounts/abi/abigen/testdata/v2/eventchecker.go.txt

@@ -72,8 +72,11 @@ func (EventCheckerDynamic) ContractEventName() string {
 // Solidity: event dynamic(string indexed idxStr, bytes indexed idxDat, string str, bytes dat)
 func (eventChecker *EventChecker) UnpackDynamicEvent(log *types.Log) (*EventCheckerDynamic, error) {
 	event := "dynamic"
-	if len(log.Topics) == 0 || log.Topics[0] != eventChecker.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != eventChecker.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(EventCheckerDynamic)
 	if len(log.Data) > 0 {
@@ -112,8 +115,11 @@ func (EventCheckerEmpty) ContractEventName() string {
 // Solidity: event empty()
 func (eventChecker *EventChecker) UnpackEmptyEvent(log *types.Log) (*EventCheckerEmpty, error) {
 	event := "empty"
-	if len(log.Topics) == 0 || log.Topics[0] != eventChecker.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != eventChecker.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(EventCheckerEmpty)
 	if len(log.Data) > 0 {
@@ -154,8 +160,11 @@ func (EventCheckerIndexed) ContractEventName() string {
 // Solidity: event indexed(address indexed addr, int256 indexed num)
 func (eventChecker *EventChecker) UnpackIndexedEvent(log *types.Log) (*EventCheckerIndexed, error) {
 	event := "indexed"
-	if len(log.Topics) == 0 || log.Topics[0] != eventChecker.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != eventChecker.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(EventCheckerIndexed)
 	if len(log.Data) > 0 {
@@ -196,8 +205,11 @@ func (EventCheckerMixed) ContractEventName() string {
 // Solidity: event mixed(address indexed addr, int256 num)
 func (eventChecker *EventChecker) UnpackMixedEvent(log *types.Log) (*EventCheckerMixed, error) {
 	event := "mixed"
-	if len(log.Topics) == 0 || log.Topics[0] != eventChecker.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != eventChecker.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(EventCheckerMixed)
 	if len(log.Data) > 0 {
@@ -238,8 +250,11 @@ func (EventCheckerUnnamed) ContractEventName() string {
 // Solidity: event unnamed(uint256 indexed arg0, uint256 indexed arg1)
 func (eventChecker *EventChecker) UnpackUnnamedEvent(log *types.Log) (*EventCheckerUnnamed, error) {
 	event := "unnamed"
-	if len(log.Topics) == 0 || log.Topics[0] != eventChecker.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != eventChecker.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(EventCheckerUnnamed)
 	if len(log.Data) > 0 {

accounts/abi/abigen/testdata/v2/nameconflict.go.txt

@@ -134,8 +134,11 @@ func (NameConflictLog) ContractEventName() string {
 // Solidity: event log(int256 msg, int256 _msg)
 func (nameConflict *NameConflict) UnpackLogEvent(log *types.Log) (*NameConflictLog, error) {
 	event := "log"
-	if len(log.Topics) == 0 || log.Topics[0] != nameConflict.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != nameConflict.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(NameConflictLog)
 	if len(log.Data) > 0 {

accounts/abi/abigen/testdata/v2/numericmethodname.go.txt

@@ -136,8 +136,11 @@ func (NumericMethodNameE1TestEvent) ContractEventName() string {
 // Solidity: event _1TestEvent(address _param)
 func (numericMethodName *NumericMethodName) UnpackE1TestEventEvent(log *types.Log) (*NumericMethodNameE1TestEvent, error) {
 	event := "_1TestEvent"
-	if len(log.Topics) == 0 || log.Topics[0] != numericMethodName.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != numericMethodName.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(NumericMethodNameE1TestEvent)
 	if len(log.Data) > 0 {

accounts/abi/abigen/testdata/v2/overload.go.txt

@@ -114,8 +114,11 @@ func (OverloadBar) ContractEventName() string {
 // Solidity: event bar(uint256 i)
 func (overload *Overload) UnpackBarEvent(log *types.Log) (*OverloadBar, error) {
 	event := "bar"
-	if len(log.Topics) == 0 || log.Topics[0] != overload.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != overload.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(OverloadBar)
 	if len(log.Data) > 0 {
@@ -156,8 +159,11 @@ func (OverloadBar0) ContractEventName() string {
 // Solidity: event bar(uint256 i, uint256 j)
 func (overload *Overload) UnpackBar0Event(log *types.Log) (*OverloadBar0, error) {
 	event := "bar0"
-	if len(log.Topics) == 0 || log.Topics[0] != overload.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != overload.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(OverloadBar0)
 	if len(log.Data) > 0 {

accounts/abi/abigen/testdata/v2/token.go.txt

@@ -386,8 +386,11 @@ func (TokenTransfer) ContractEventName() string {
 // Solidity: event Transfer(address indexed from, address indexed to, uint256 value)
 func (token *Token) UnpackTransferEvent(log *types.Log) (*TokenTransfer, error) {
 	event := "Transfer"
-	if len(log.Topics) == 0 || log.Topics[0] != token.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != token.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(TokenTransfer)
 	if len(log.Data) > 0 {

accounts/abi/abigen/testdata/v2/tuple.go.txt

@@ -193,8 +193,11 @@ func (TupleTupleEvent) ContractEventName() string {
 // Solidity: event TupleEvent((uint256,uint256[],(uint256,uint256)[]) a, (uint256,uint256)[2][] b, (uint256,uint256)[][2] c, (uint256,uint256[],(uint256,uint256)[])[] d, uint256[] e)
 func (tuple *Tuple) UnpackTupleEventEvent(log *types.Log) (*TupleTupleEvent, error) {
 	event := "TupleEvent"
-	if len(log.Topics) == 0 || log.Topics[0] != tuple.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != tuple.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(TupleTupleEvent)
 	if len(log.Data) > 0 {
@@ -234,8 +237,11 @@ func (TupleTupleEvent2) ContractEventName() string {
 // Solidity: event TupleEvent2((uint8,uint8)[] arg0)
 func (tuple *Tuple) UnpackTupleEvent2Event(log *types.Log) (*TupleTupleEvent2, error) {
 	event := "TupleEvent2"
-	if len(log.Topics) == 0 || log.Topics[0] != tuple.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != tuple.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(TupleTupleEvent2)
 	if len(log.Data) > 0 {

accounts/abi/bind/v2/base.go

@@ -35,8 +35,8 @@ import (
 const basefeeWiggleMultiplier = 2
 
 var (
-	errNoEventSignature       = errors.New("no event signature")
-	errEventSignatureMismatch = errors.New("event signature mismatch")
+	ErrNoEventSignature       = errors.New("no event signature")
+	ErrEventSignatureMismatch = errors.New("event signature mismatch")
 )
 
 // SignerFn is a signer function callback when a contract requires a method to
@@ -536,10 +536,10 @@ func (c *BoundContract) WatchLogs(opts *WatchOpts, name string, query ...[]any)
 func (c *BoundContract) UnpackLog(out any, event string, log types.Log) error {
 	// Anonymous events are not supported.
 	if len(log.Topics) == 0 {
-		return errNoEventSignature
+		return ErrNoEventSignature
 	}
 	if log.Topics[0] != c.abi.Events[event].ID {
-		return errEventSignatureMismatch
+		return ErrEventSignatureMismatch
 	}
 	if len(log.Data) > 0 {
 		if err := c.abi.UnpackIntoInterface(out, event, log.Data); err != nil {
@@ -559,10 +559,10 @@ func (c *BoundContract) UnpackLog(out any, event string, log types.Log) error {
 func (c *BoundContract) UnpackLogIntoMap(out map[string]any, event string, log types.Log) error {
 	// Anonymous events are not supported.
 	if len(log.Topics) == 0 {
-		return errNoEventSignature
+		return ErrNoEventSignature
 	}
 	if log.Topics[0] != c.abi.Events[event].ID {
-		return errEventSignatureMismatch
+		return ErrEventSignatureMismatch
 	}
 	if len(log.Data) > 0 {
 		if err := c.abi.UnpackIntoMap(out, event, log.Data); err != nil {

accounts/abi/bind/v2/internal/contracts/db/bindings.go

@@ -276,8 +276,11 @@ func (DBInsert) ContractEventName() string {
 // Solidity: event Insert(uint256 key, uint256 value, uint256 length)
 func (dB *DB) UnpackInsertEvent(log *types.Log) (*DBInsert, error) {
 	event := "Insert"
-	if len(log.Topics) == 0 || log.Topics[0] != dB.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != dB.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(DBInsert)
 	if len(log.Data) > 0 {
@@ -318,8 +321,11 @@ func (DBKeyedInsert) ContractEventName() string {
 // Solidity: event KeyedInsert(uint256 indexed key, uint256 value)
 func (dB *DB) UnpackKeyedInsertEvent(log *types.Log) (*DBKeyedInsert, error) {
 	event := "KeyedInsert"
-	if len(log.Topics) == 0 || log.Topics[0] != dB.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != dB.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(DBKeyedInsert)
 	if len(log.Data) > 0 {

accounts/abi/bind/v2/internal/contracts/events/bindings.go

@@ -115,8 +115,11 @@ func (CBasic1) ContractEventName() string {
 // Solidity: event basic1(uint256 indexed id, uint256 data)
 func (c *C) UnpackBasic1Event(log *types.Log) (*CBasic1, error) {
 	event := "basic1"
-	if len(log.Topics) == 0 || log.Topics[0] != c.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != c.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(CBasic1)
 	if len(log.Data) > 0 {
@@ -157,8 +160,11 @@ func (CBasic2) ContractEventName() string {
 // Solidity: event basic2(bool indexed flag, uint256 data)
 func (c *C) UnpackBasic2Event(log *types.Log) (*CBasic2, error) {
 	event := "basic2"
-	if len(log.Topics) == 0 || log.Topics[0] != c.abi.Events[event].ID {
-		return nil, errors.New("event signature mismatch")
+	if len(log.Topics) == 0 {
+		return nil, bind.ErrNoEventSignature
+	}
+	if log.Topics[0] != c.abi.Events[event].ID {
+		return nil, bind.ErrEventSignatureMismatch
 	}
 	out := new(CBasic2)
 	if len(log.Data) > 0 {

accounts/abi/bind/v2/lib_test.go

@@ -379,16 +379,16 @@ func TestEventUnpackEmptyTopics(t *testing.T) {
 		if err == nil {
 			t.Fatal("expected error when unpacking event with empty topics, got nil")
 		}
-		if err.Error() != "event signature mismatch" {
-			t.Fatalf("expected 'event signature mismatch' error, got: %v", err)
+		if err != bind.ErrNoEventSignature {
+			t.Fatalf("expected 'no event signature' error, got: %v", err)
 		}
 
 		_, err = c.UnpackBasic2Event(log)
 		if err == nil {
 			t.Fatal("expected error when unpacking event with empty topics, got nil")
 		}
-		if err.Error() != "event signature mismatch" {
-			t.Fatalf("expected 'event signature mismatch' error, got: %v", err)
+		if err != bind.ErrNoEventSignature {
+			t.Fatalf("expected 'no event signature' error, got: %v", err)
 		}
 	}
 }