Event based triggers #627

jannikluhn · 2025-08-19T21:20:50Z

This PR implements event based triggers. It is based on the work done in #613. It is mostly complete, but still a draft because

it depends on ShutterTriggerRegistryContract in the contracts repository to be finalized, merged and added as a dependency to go.mod (currently, go.mod references this early version in the event-trigger-registry branch)
it contains the docker setup from Shutter API Keyper basic test setup #604 (squashed into commit 3c04cdb) to help with testing which should be removed before merging

For reviewing I suggest largely ignoring the commit history (the commits should be squashed before merging). The core logic is implemented in eventtrigger.go. multieventsyncer.go contains a generalized event syncing interface that is implemented once for trigger registration events and once for the actual trigger events. Everything is tied together in newblock.go.

- Implement generic MultiEventSyncer - Implement TriggerRegisteredEvent syncing and trigger syncing with MultiEventSyncer - Filter triggers based on TTL and log matching - Remove previous TriggerRegisteredEvent syncer (which replaced IdentityRegisteredEvent syncer)

Previous commits temporarily changed it to sync EventTriggerRegisteredEvents. This restores it to the original state.

This splits the triggering up into trigger generation and sending.

Instead, we use just the hash directly. This simplifies the code and means no information is lost during marshalling (even before, we only marshalled the hash).

It used to be [][]byte (which just got concatenated during unmarshaling), now it's just []byte. Presumably, the original idea was to have blocks of 32 bytes to make it easier for the EVM to handle, but ABI encoding already takes care of this for us.

The code did not match the comment and umarshaling logic.

Topics should not be specified (not even if they're empty) if they don't exist in the event signature, otherwise the filter doesn't match.

This aligns the config parameter with the contract name. This makes automatically setting the config value to the deployment address easier.

When looking for triggers in a certain block range, the trigger registration event does not have to be from this range. Rather, it may have been registered a long time prior to this, as long as it hasn't expired yet.

The event needs to have access to the trigger register event, otherwise it doesn't know the identity prefix etc.

Similar to how it is handled with time based triggers, trigger events are now marked as "decrypted" when a corresponding decryption key has been produced. To do that, we store the full identity in the database even though it could be derived from prefix and sender. In the middleware, we cannot distinguish between keys that have been generated due to a time based or an event based trigger, so we just look in both tables if we can find the corresponding identity.

This simplifies the data structures and avoids interfaces. It allows using RLP for encoding. The commit also adds proper validation of the data structures. The functionality is broadly equivalent.

In practice, the contract will probably apply reasonable bounds, but it doesn't hurt to check it here too.

Copilot

Pull Request Overview

This PR implements event-based triggers for the shutter service, enabling triggers to fire based on specific Ethereum events rather than just time-based triggers. The implementation includes event syncing infrastructure, trigger processing logic, and database schema updates to support event-based trigger registration and execution.

Key changes:

Added EventTriggerDefinition system for defining complex event-based triggers with predicates on log topics and data
Implemented MultiEventSyncer for synchronizing multiple types of blockchain events with reorg handling
Added database support for event trigger registration and fired trigger tracking

Reviewed Changes

Copilot reviewed 37 out of 38 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
eventtrigger.go	Core event trigger definition and validation logic with RLP encoding/decoding
multieventsyncer.go	Generic event synchronization framework with reorg detection and rollback capabilities
triggerprocessor.go	Processes trigger events to check if registered triggers should fire
eventtriggerregisteredprocessor.go	Handles EventTriggerRegistered events from the trigger registry contract
newblock.go	Integrates event-based triggers into the main block processing flow
database schema/queries	Database support for event trigger storage and tracking

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

rolling-shutter/keyperimpl/shutterservice/triggerprocessor.go

rolling-shutter/keyperimpl/shutterservice/newblock.go

Copilot · 2025-08-19T21:22:34Z

rolling-shutter/keyperimpl/shutterservice/newblock.go


-	return nil
+		select {
+		case kpr.decryptionTriggerChannel <- event:


The channel send operation could block if the channel is full, but there's no timeout or non-blocking alternative. Consider adding a timeout or making this non-blocking to prevent the goroutine from hanging.

Copilot · 2025-08-19T21:22:34Z

rolling-shutter/keyperimpl/shutterservice/multieventsyncer.go

+		}
+
+		err = s.setSyncStatus(ctx, tx, toBlock, []byte{})
+		if err != nil {


Setting block hash to empty bytes during rollback could cause issues. Consider setting it to the actual block hash at the rollback target block for consistency.

Suggested change

if err != nil {

// Fetch the block hash for the rollback target block

blockHeader, err := s.EthClient.BlockByNumber(ctx, big.NewInt(toBlock))

if err != nil {

return errors.Wrapf(err, "failed to fetch block header for block %d during rollback", toBlock)

}

blockHash := blockHeader.Hash().Bytes()

err = s.setSyncStatus(ctx, tx, toBlock, blockHash)

if err != nil {

blockchainluffy

looks good overall, just some small changes requested

rolling-shutter/keyperimpl/shutterservice/database/sql/queries/shutterservice.sql

rolling-shutter/keyperimpl/shutterservice/database/sql/schemas/shutterservice.sql

blockchainluffy · 2025-08-20T10:19:51Z

rolling-shutter/keyperimpl/shutterservice/eventtrigger.go

+type ValuePredicate struct {
+	Op       Op
+	IntArgs  []*big.Int
+	ByteArgs [][]byte


maybe something for next version or future improvements, we can just use BytesArgs for all data types, after encoding them.

rolling-shutter/keyperimpl/shutterservice/eventtrigger.go

blockchainluffy · 2025-08-21T12:07:16Z

rolling-shutter/keyperimpl/shutterservice/eventtrigger.go

+		FromBlock: nil,
+		ToBlock:   nil,
+		Addresses: []common.Address{d.Contract},
+		Topics:    topics,


will this work correctly, if there are multiple LogPredicates and one of which is topic and others are not? It could just fetch the topic then and not other events (non topic ones)?

I think it should work correctly. LogPredicates are supposed to be "anded" together, so we want to fetch events that fulfill all predicates. The filter will return all events that match all topic predicates. The Match afterwards (in newblock.go) will filter it down further using the remaining predicates.

what I meant to say is, if one of the LogPredicate is for a different event which contains topic and other LogPredicate is of different event which does not have topic specified, can it fetch the second event as well, which we will match afterwards?

rolling-shutter/keyperimpl/shutterservice/eventtrigger.go

blockchainluffy · 2025-08-21T12:39:07Z

rolling-shutter/keyperimpl/shutterservice/triggerprocessor.go

+			continue
+		}
+
+		filterQuery, err := trigger.ToFilterQuery()


one future improvement here could be combining these filter queries to do a single query to the rpc? wdyt?

Agree, but at this stage I think it would be premature optimization.

Depending on the contract design, identity prefix and sender might not be unique, but with the eon they should be.

konradkonrad · 2025-08-25T09:01:40Z

docker-test-setup-api/02-init-chain.sh

+
+    # share genesis
+    if [ $num -eq 0 ]; then
+        for destination in data/chain-seed/config/ data/chain-{1..2}-validator/config/; do


I know, this is a copy and past from elsewhere, but I think this could just be:

Suggested change

for destination in data/chain-seed/config/ data/chain-{1..2}-validator/config/; do

for destination in data/chain-seed/config/ data/chain-${num}-validator/config/; do

or it could be pulled out of the for num in {0..2}; do-loop and just be

for destination in data/chain-seed/config/ data/chain-{1..2}-validator/config/; do ${BB} cp -v data/chain-0-validator/config/genesis.json "${destination}" done

konradkonrad and others added 30 commits August 19, 2025 16:56

WIP

27ca74a

Experiment with more complex log data

8ff0e83

Add type definitions

75288a7

Initial test for TriggerDefinition

08da22b

Fixes for condensed encoding

d9cde75

Enhance complex type matching

c3698a5

Make spec human friendly

08dac78

Add initial registry contract

f42bd00

Start condensed encoding implementation [WIP]

4d7d27b

Updated condensed spec

3968454

First take of EventTriggerDefinition UnmarshalBytes

d701f2b

Debugging serdes

38922a4

Fixed UnmarshalBytes

1751a52

WIP use special event trigger contract

8ca9446

Add DB functions

28d7727

Remove unused py module

79a50f2

Implement syncing

ff92413

- Implement generic MultiEventSyncer - Implement TriggerRegisteredEvent syncing and trigger syncing with MultiEventSyncer - Filter triggers based on TTL and log matching - Remove previous TriggerRegisteredEvent syncer (which replaced IdentityRegisteredEvent syncer)

Restore RegistrySyncer

e57f4b1

Previous commits temporarily changed it to sync EventTriggerRegisteredEvents. This restores it to the original state.

Use MultiEventSyncer in keyper

93ae1d6

Refactor decryption triggering

e8a5b71

This splits the triggering up into trigger generation and sending.

Send decryption triggers for fired triggers

5205854

Squashed docker setup

3c04cdb

Fix test

5377b6f

Remove EventSignature type

7dbfee2

Instead, we use just the hash directly. This simplifies the code and means no information is lost during marshalling (even before, we only marshalled the hash).

Add event trigger marshalling tests

f3ab189

Simplify event trigger byte format

5a93ce0

It used to be [][]byte (which just got concatenated during unmarshaling), now it's just []byte. Presumably, the original idea was to have blocks of 32 bytes to make it easier for the EVM to handle, but ABI encoding already takes care of this for us.

Fix endianness of topic pattern

98c2aea

The code did not match the comment and umarshaling logic.

Validate address and signatures are read in full

683813d

Use event trigger registry from contract repo

e499a4c

Fix trigger definition marshalling

9dbdf10

jannikluhn added 16 commits August 19, 2025 16:58

Fix event trigger filter test

ea390ae

Use helper contract from contracts repo

9639457

Fix filter query generation

07b0eb5

Topics should not be specified (not even if they're empty) if they don't exist in the event signature, otherwise the filter doesn't match.

Rename config contract parameter

28c7417

This aligns the config parameter with the contract name. This makes automatically setting the config value to the deployment address easier.

Fix trigger event query

719be4a

When looking for triggers in a certain block range, the trigger registration event does not have to be from this range. Rather, it may have been registered a long time prior to this, as long as it hasn't expired yet.

Fix trigger processor event

e594171

The event needs to have access to the trigger register event, otherwise it doesn't know the identity prefix etc.

Improve event trigger data structures

2b616b8

This simplifies the data structures and avoids interfaces. It allows using RLP for encoding. The commit also adds proper validation of the data structures. The functionality is broadly equivalent.

Tidy go.mod

2c47b86

Improve logging

6ff7b49

Valiate TTL

e1a73c6

In practice, the contract will probably apply reasonable bounds, but it doesn't hurt to check it here too.

Only handle event based triggers if enabled

cf29631

Cleanup newblock

8141167

Fix linting errors

6c7ae0a

Fix tests

d81c17d

Handle context cancellations when sending triggers

38829b5

jannikluhn requested a review from Copilot August 19, 2025 21:21

Copilot AI reviewed Aug 19, 2025

View reviewed changes

jannikluhn added 2 commits August 19, 2025 23:28

Use identity from db instead of recomputing

d69ca8a

Fix fired trigger rollback

a7c41bc

jannikluhn force-pushed the event-based-triggers branch from 026b6a8 to a7c41bc Compare August 19, 2025 21:28

blockchainluffy reviewed Aug 21, 2025

View reviewed changes

jannikluhn added 4 commits August 21, 2025 23:08

Remove unused db query

b2e4d3c

Include eon in primary key

a15c58b

Depending on the contract design, identity prefix and sender might not be unique, but with the eon they should be.

Simplify IsTopic check

ac5c293

Return error instead of panicking in Match

6f53ac9

konradkonrad mentioned this pull request Aug 25, 2025

Event triggers #613

Closed

konradkonrad reviewed Aug 25, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Event based triggers #627

Event based triggers #627

jannikluhn commented Aug 19, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Aug 19, 2025

Uh oh!

Copilot AI Aug 19, 2025

Uh oh!

blockchainluffy left a comment

Uh oh!

Uh oh!

Uh oh!

blockchainluffy Aug 20, 2025

Uh oh!

Uh oh!

Uh oh!

blockchainluffy Aug 21, 2025

Uh oh!

jannikluhn Aug 21, 2025

Uh oh!

blockchainluffy Aug 22, 2025

Uh oh!

Uh oh!

Uh oh!

blockchainluffy Aug 21, 2025

Uh oh!

jannikluhn Aug 21, 2025

Uh oh!

konradkonrad Aug 25, 2025

Uh oh!

Uh oh!

-		if err != nil {
+		// Fetch the block hash for the rollback target block
+		blockHeader, err := s.EthClient.BlockByNumber(ctx, big.NewInt(toBlock))
+		if err != nil {
+			return errors.Wrapf(err, "failed to fetch block header for block %d during rollback", toBlock)
+		}
+		blockHash := blockHeader.Hash().Bytes()
+		err = s.setSyncStatus(ctx, tx, toBlock, blockHash)
+		if err != nil {

	for destination in data/chain-seed/config/ data/chain-{1..2}-validator/config/; do
	for destination in data/chain-seed/config/ data/chain-${num}-validator/config/; do

Event based triggers #627

Are you sure you want to change the base?

Event based triggers #627

Conversation

jannikluhn commented Aug 19, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

blockchainluffy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

blockchainluffy Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

blockchainluffy Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

jannikluhn Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

blockchainluffy Aug 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

blockchainluffy Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

jannikluhn Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

konradkonrad Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!