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

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

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.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add endpoints for event based decryption triggers #79

Add endpoints for event based decryption triggers #79

Uh oh!

konradkonrad commented Dec 19, 2025 •

edited by blockchainluffy

Loading

Uh oh!

ylembachar Jan 8, 2026

Uh oh!

ylembachar Jan 8, 2026

Uh oh!

ylembachar Jan 8, 2026

Uh oh!

ylembachar Jan 8, 2026

Uh oh!

ylembachar Jan 8, 2026

Uh oh!

ylembachar Jan 8, 2026

Uh oh!

ylembachar Jan 8, 2026 •

edited

Loading

Uh oh!

ylembachar Jan 12, 2026

Uh oh!

ylembachar Jan 12, 2026

Uh oh!

ylembachar Jan 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

konradkonrad commented Dec 19, 2025 •

edited by blockchainluffy

Loading

ylembachar Jan 8, 2026 •

edited

Loading