EPIC: Event-based decryption triggers

[ylembachar]

This issue consolidates the specification and implementation tasks for event-based decryption triggers in Shutter. See internal discussion for design rationale and background.

Specification

EventTriggerDefinition (ETD)

• Contract address + event signature (topic0)
• 0–3 indexed argument matches (topic1–3)
• 0–n conditions for non-indexed arguments
• Encoded format for keypers, with planned human-readable JSON schema (ABI-based)

Condition Matching

• Comparisons on number arguments (lt, gt, eq)
• Equality checks on bytes32 and complex byte types

TTL (Time-to-Live)

• Each ETD has an expiry block to avoid indefinite keyper load
• Initial version: fixed lifetime (e.g. ~1 week)
• Long term: paid extensions to extend TTL
• ETDs re-checked each block until TTL expires or decryption succeeds

Tasks

• [x] Implement keyper logic
• [x] Implement contract logic
• [x] Integration tests (end-to-end with keypers + contracts)
• [x] Update Shutter API docs (WIP)
• [ ] Update specs
• [ ] Announce / after rolling-shutter release
• [ ] Deployment to internal keypers (via shutter-deployment to both Chiado and Mainnet)
• [ ] Update Shutter API to include ETDs with only an allowed list of contracts at first and the possibility to add contracts
• [ ] Define and add metrics
• [ ] Demo
• [ ] Launch
• [ ] Add pricing to add custom contracts (timing TBD)

Additional info:

• Handle safe vs. eager evaluation (HEAD vs. confirmed blocks) - low priority
• Handle incomplete threshold cases - handled via republishing of key shares until key generated

[ylembachar]

Internal design notes on the integration with the Shutter API / to be included in the docs pre-announcement:

• Register the event filter directly
• Not necessary to whitelist contracts / allow registering any filter (with any contract as part of definition) via the API and measure performance.
• Add TTL per event (needs to be filtered by the API not to exceed a month)
• JS library to get user event input and transform it to an event definition (can be used by users independently or via the API)
• Could have a front to verify the validity of the event or via API endpoint (both could also include ABI)

From dev perspective: Option A:

• define event filter via the JS library / front-end
• register identity with the event filter definition

Option B:

• define event filter part of the register identity endpoint
• register identity

Other endpoints (see other shutter api endpoints):

• get encryption data
• get decryption key
• decrypt commitment
• get event filter by identity (to be added)

Demo ideas:

• What's inside the cube
• Number guessing
• Reveal to subscribers
• Payment-gated unlock

[ylembachar]

@konradkonrad added some updates to the README regarding the future Shutter API endpoint that will allow registering identities for event filters: https://github.com/shutter-network/shutter-api?tab=readme-ov-file#1b-register-an-identity-with-event-based-decryption-triggers-wip