Add endpoints for event based decryption triggers #79

konradkonrad · 2025-12-19T10:58:02Z

This implements API endpoints for event based decryption triggers.
WIP/TODO:

check TODO comments
codepath for RegisterEventIdentity is untested so far
consistency in json parameter naming: camel vs snake case
Add new endpoints (/compile_event_trigger_definition, /register_event_trigger) to rate limiting

Fixes #74

See also https://github.com/shutter-network/shutter-api?tab=readme-ov-file#1b-register-an-identity-with-event-based-decryption-triggers-wip

Note: it changed from 'use 3rd party tooling' but does not mention, that the provided compiler implementation is opinionated, and 3rd party tooling could provide more flexible event triggers. Namely triggers that allow for some parameters to be omitted, e.g. topic0

… get_data_for_encryption endpoint

…tity

ylembachar · 2026-01-08T11:51:56Z

internal/service/crypto.go

 ) *CryptoService {
 	return &CryptoService{
-		CryptoUsecase: usecase.NewCryptoUsecase(db, contract.ShutterRegistryContract, contract.KeyperSetManagerContract, contract.KeyBroadcastContract, ethClient, config),
+		CryptoUsecase: usecase.NewCryptoUsecase(db, contract.ShutterRegistryContract, contract.ShutterEventRegistryContract, contract.KeyperSetManagerContract, contract.KeyBroadcastContract, ethClient, config),


I understand the API can still be deployed even if the event registry contract isn’t deployed; event endpoints will just fail at runtime with a 500 error. Nice‑to‑have: add a feature flag to enable/disable event triggers while still serving endpoints. If the contract isn’t deployed, return a 503 Service Unavailable error. Not required for the upcoming deployment.

ylembachar · 2026-01-08T13:20:53Z

internal/service/crypto.go

+//		@Description	Retrieves all the necessary data required by clients for encrypting any message. Supports both time-based and event-based identity computation. If triggerDefinition is provided, the identity will be computed for event-based triggers. Otherwise, it uses time-based identity computation.
+//		@Tags			Crypto
+//		@Produce		json
+//		@Param			address			query		string									true	"Ethereum address associated with the identity. If you are registering the identity yourself, pass the address of the account making the registration. If you want the API to register the identity on gnosis mainnet, pass the address: 0x228DefCF37Da29475F0EE2B9E4dfAeDc3b0746bc. For chiado pass the address: 0xb9C303443c9af84777e60D5C987AbF0c43844918"


We should clarify here that users are not able to register event-based identities by themselves, and should always use the API address. Please find below a suggested update:

Ethereum address associated with the identity.

Time‑based: use the address that will register the identity (your account if self‑registering, or the API signer address below if you are using the API register endpoint).

Event‑based (triggerDefinition provided): users cannot self‑register because the registry is owner‑only, please use the API signer address below.

Gnosis Mainnet API address: 0x228DefCF37Da29475F0EE2B9E4dfAeDc3b0746bc

Chiado API address: 0xb9C303443c9af84777e60D5C987AbF0c43844918

ylembachar · 2026-01-08T13:45:21Z

internal/usecase/crypto.go


 	identity := common.ComputeIdentity(identityPrefix[:], newSigner.From)

+	// TODO: check for already registered identities also against event based triggers!


We should implement this cross-check in both time-based and event-based identity registrations to avoid identity collisions where a timestamp trigger could release an event-based identity and vice-versa.

This might not be needed if we compute the identities following my comment on identity calculation.

ylembachar · 2026-01-08T14:08:34Z

common/utils.go

 	return crypto.Keccak256(imageBytes)
 }

+func ComputeEventIdentity(prefix []byte, sender common.Address, triggerDefinition []byte) []byte {


The event identity calculation is inconsistent with the calculation in rolling shutter: https://github.com/shutter-network/rolling-shutter/blob/main/rolling-shutter/keyperimpl/shutterservice/eventtriggerregisteredprocessor.go#L123C6-L123C33

To make event triggers safe long‑term, we could:

Align identity derivation across repos (update rolling‑shutter to match API), and additionally add a domain separator, and enforce uniqueness on‑chain (requires a contract update). Suggested formula: eventIdentity = keccak(prefix + sender + 0x01 + triggerDefinition) (time‑based stays keccak(prefix + sender)). This ensures time-based and event-based identities don't collide if the trigger definition is empty.

Reject empty/0x triggerDefinition for event registrations.

Add a mapping in ShutterEventTriggerRegistry to revert on duplicate identity. This prevents event‑event duplicates without relying on API/DB race checks. We currently update on conflict: https://github.com/shutter-network/rolling-shutter/blob/main/rolling-shutter/keyperimpl/shutterservice/database/sql/queries/shutterservice.sql#L31

As discussed: the 0x01 infix is not necessary; an empty triggerDefinition is useless and ignored by the API, therefore the collision case can not happen in the current framework. If - at some later point - the registry contract was opened to the public, then keypers should check for empty trigger definitions and discard such registrations, or the registration contract could disallow empty values (for a little bit higher gas cost).

ylembachar · 2026-01-08T15:23:53Z

internal/usecase/crypto.go


-	identity := common.ComputeIdentity(identityPrefix[:], ethCommon.HexToAddress(address))
+	var identity []byte
+	if len(triggerDefinitionHex) > 0 {


We should check for 0x here and treat it as an invalid trigger definition

ylembachar · 2026-01-08T15:28:23Z

.env.example

-METRICS_PORT=4000
+METRICS_PORT=4000
+SHUTTER_EVENT_REGISTRY_CONTRACT_ADDRESS=
+WHITELISTED_TRIGGER_CONTRACT_ADDRESSES=


Maybe add a comment here on how to add addresses to this string, that they need to be comma-separated

As discussed: Whitelisting only certain contracts for event based decryption triggers does not help with reducing or limiting load on keypers. Instead, if there is need for it, we would need to limit the total number of active event based triggers.
Therefore I removed the whitelist feature.

ylembachar · 2026-01-12T09:29:10Z

internal/service/crypto.go

+//					- "name": <matching argument name from signature>
+//					- "op": <one of: lt, lte, eq, gte, gt>
+//					- "number": <integer argument for numeric comparison>
+//					- "bytes": <hex encoded byte argument for non numeric matches with 'op==eq'>


It would be helpful to add a short note to clarify how different params should be passed: indexed params (topics) are eq‑only. For indexed static types (address, uint256, bytes32), pass the hex representation. For indexed dynamic types (string, bytes, arrays), pass keccak256(value) as hex. For non‑indexed uint256, use number with lt/lte/eq/gte/gt. For other non‑indexed types, use bytes with op=eq hex‑encoded value.

ylembachar · 2026-01-12T09:32:45Z

internal/usecase/eventtrigger.go

+		return shs.UintGt
+	case "gte":
+		return shs.UintGte
+	default:


Unknown ops should return an explicit error here

ylembachar · 2026-01-12T09:52:58Z

internal/usecase/eventtrigger.go

+					}
+					lp.ValuePredicate.Op = shs.BytesEq
+					lp.ValuePredicate.ByteArgs = [][]byte{Align(val)}
+					length = uint64(len([]byte(arg.Bytes)) / 32)


len([]byte(arg.Bytes)) is the length of the hex string, not the decoded bytes, and would cause offset miscalculation later on.

:o good catch! thanks!

jannikluhn · 2026-01-12T23:39:42Z

internal/data/sql/schemas/event_registrations.sql

+    identity_prefix bytea NOT NULL,
+    sender text NOT NULL,
+    event_trigger_definition bytea NOT NULL,
+    expiration_block_number bigint,


is there a reason why this is not NOT NULL? The contract seems to always set it.

jannikluhn · 2026-01-12T23:42:17Z

docs/swagger.yaml

+        name: identityPrefix
+        required: true
+        type: string
+      - description: 'Ethereum address associated with the identity. For gnosis mainnet,


Not clear what this address is supposed to be, the registry contract?

I'm also not particular happy with this interface. The address is supposed to reflect the internal signer of the API used (e.g. gnosis main API or chiado API). Imo we should hide this complexity from the user.

We should either

derive the address parameter automatically/internally OR

use the computed identity as parameter

I went with deriving from the configured signing key and removed the address parameter from the endpoint.

jannikluhn · 2026-01-12T23:49:18Z

internal/usecase/eventtrigger.go

+type EventArgument struct {
+	Name     string `json:"name" example:"amount"`
+	Operator string `json:"op" example:"gte"`
+	Number   int    `json:"number" example:"25433"`


I think this should be a *big.Int (and probably encoded as a decimal string), not an int because of potential overflows

Whitelisting only certain contracts for event based decryption triggers does not help with reducing or limiting load on keypers. Instead, if there is need for it, we would need to limit the total number of active event based triggers.

The parameter is not necessary for event based identities, because it can be derived from signing key.

The specialized func was used in only one place and could produce semantically incorrect results. I inlined the switch statement and added an explicit error case on default.

konradkonrad added 13 commits December 12, 2025 14:07

Add happy path ETD compilation

ad7a49f

Add input validation for common errors

6ac3192

Add tests for CompileEventTriggerDefinition

ba5a085

Fix alignment/padding

2446e56

Add topic0

e025a81

Add commandline ETD compiler

49b2141

Fix json example

8d68e75

Stricter validation of values

b7da27e

Fix correct naming for event signature

9cff7ac

Move usecase out of service

1521a5a

WIP: Add event registry endpoint

403e549

Usage instructions in executable source

b6526c9

Add some todo's for collision checks and whitelist

0ee0c3b

konradkonrad assigned konradkonrad and blockchainluffy and unassigned konradkonrad Dec 19, 2025

konradkonrad and others added 8 commits December 19, 2025 13:34

Add ttl parameter to README

56b93ef

Add spec link to README

a6ebda6

Use valid data for triggerDefinition example

ebd9e11

More consistent parameter naming

d57cfdf

feat: register_event_identity endpoint and add swagger docs

3fc7621

feat: ttl getter endpoint, already registered identity checks, update…

8b76656

… get_data_for_encryption endpoint

feat: add rate limiting and update checks for already registered iden…

069f89f

…tity

blockchainluffy marked this pull request as ready for review December 29, 2025 11:15

ylembachar reviewed Jan 8, 2026

View reviewed changes

ylembachar reviewed Jan 12, 2026

View reviewed changes

jannikluhn reviewed Jan 12, 2026

View reviewed changes

konradkonrad added 2 commits January 13, 2026 17:51

Fix unit test

616f1f4

Add whitelist comment for env example

7325d87

konradkonrad added 4 commits January 13, 2026 18:20

Remove whitelist feature

2c4ea20

Whitelisting only certain contracts for event based decryption triggers does not help with reducing or limiting load on keypers. Instead, if there is need for it, we would need to limit the total number of active event based triggers.

Remove address from GetEventTriggerExpirationBlock

7dcf929

The parameter is not necessary for event based identities, because it can be derived from signing key.

Fix incorrect length calcuation

5edda9e

Remove overly generous opFromString

b3b026a

The specialized func was used in only one place and could produce semantically incorrect results. I inlined the switch statement and added an explicit error case on default.


		identity := common.ComputeIdentity(identityPrefix[:], newSigner.From)

		// TODO: check for already registered identities also against event based triggers!

Add endpoints for event based decryption triggers #79

Are you sure you want to change the base?

Add endpoints for event based decryption triggers #79

Uh oh!

Conversation

konradkonrad commented Dec 19, 2025 • edited by blockchainluffy Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

konradkonrad Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ylembachar Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

konradkonrad commented Dec 19, 2025 •

edited by blockchainluffy

Loading

konradkonrad Jan 13, 2026 •

edited

Loading

ylembachar Jan 8, 2026 •

edited

Loading