Skip to content

Implement get decryption key for event based triggers #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
konradkonrad merged 10 commits into from
Jan 21, 2026
Merged

Implement get decryption key for event based triggers #87

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
875824c
Implement /get_event_decryption_key
konradkonrad Jan 20, 2026
a6da64f
Generate swagger docs
konradkonrad Jan 20, 2026
33f4edc
Add event trigger to /decrypt_commitment
konradkonrad Jan 20, 2026
5ca214a
Update swagger docs
konradkonrad Jan 20, 2026
a0637c7
Fix name mismatch in docstring
konradkonrad Jan 20, 2026
636b0f5
Add new endpoint to rate limiter
konradkonrad Jan 20, 2026
9d2da5c
Add 'get_event_decryption_key' to README
konradkonrad Jan 20, 2026
7a2cc49
Fix swagger docstring
konradkonrad Jan 20, 2026
914f2a7
Introduce optional 'eon' argument for
konradkonrad Jan 20, 2026
e1533d2
Compile swagger docs
konradkonrad Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ For unauthorized access, the API on Gnosis Mainnet is rate limited with these li
- `/get_event_trigger_expiration_block` 20 requests per 24 hours
- `/get_data_for_encryption` 10 requests per 24 hours
- `/get_decryption_key` 20 requests per 24 hours
- `/get_event_decryption_key` 20 requests per 24 hours
- `/decrypt_commitment` 10 requests per 24 hours

We recommend using Chiado for development, because there are no rate limits in place.
Expand All @@ -92,6 +93,7 @@ Authorized requests have these limits:
- `/get_event_trigger_expiration_block` 2000 requests per 24 hours
- `/get_data_for_encryption` 1000 requests per 24 hours
- `/get_decryption_key` 2000 requests per 24 hours
- `/get_event_decryption_key` 2000 requests per 24 hours
- `/decrypt_commitment` 1000 requests per 24 hours

Authorization is done by using an `Authorization: Bearer $API_KEY` header, when calling the API.
Expand Down Expand Up @@ -367,7 +369,7 @@ console.log("Encrypted Commitment:", encryptedCommitment);

#### 3.A Retrieve the Decryption Key

After the decryption trigger conditions are met (i.e., the specified timestamp has passed), retrieve the decryption key using the `/get_decryption_key` endpoint.
After the decryption trigger conditions are met (i.e., the specified timestamp has passed), retrieve the decryption key using the `/get_decryption_key` endpoint, or for event based decryption triggers the `get_event_decryption_key` endpoint.

Refer to the Swagger documentation for detailed usage.

Expand Down
15 changes: 15 additions & 0 deletions docker-compose.rate_limit.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,13 @@ services:
caddy.rate_limit_0.zone_6.match.path: "*/get_event_trigger_expiration_block*"
caddy.rate_limit_0.zone_6.match.method: GET

caddy.rate_limit_0.zone_7: get_event_decryption_key__unauthorized
caddy.rate_limit_0.zone_7.key: "{remote_host}"
caddy.rate_limit_0.zone_7.events: 20
caddy.rate_limit_0.zone_7.window: 1d
caddy.rate_limit_0.zone_7.match.path: "*/get_event_decryption_key*"
caddy.rate_limit_0.zone_7.match.method: GET

# Rate limits with api key
caddy.rate_limit_1: "@withApiKey"
caddy.rate_limit_1.log_key: " "
Expand Down Expand Up @@ -148,6 +155,14 @@ services:
caddy.rate_limit_1.zone_6.match.path: "*/get_event_trigger_expiration_block*"
caddy.rate_limit_1.zone_6.match.method: GET

caddy.rate_limit_1.zone_7: get_event_decryption_key__authorized
caddy.rate_limit_1.zone_7.key: "{header.Authorization}"
caddy.rate_limit_1.zone_7.events: 2000
caddy.rate_limit_1.zone_7.window: 1d
caddy.rate_limit_1.zone_7.match.path: "*/get_event_decryption_key*"
caddy.rate_limit_1.zone_7.match.method: GET


caddy:
build:
context: .
Expand Down
93 changes: 80 additions & 13 deletions docs/docs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "Provides a way for clients to easily decrypt their encrypted message for which they have registered the identity for. Timestamp with which the identity was registered should have been passed for the message to be decrypted successfully.",
"description": "Provides a way for clients to easily decrypt their encrypted message for which they have registered the identity for. The trigger condition for the decryption key (timestamp or event) to be released must have been met for the message to be decrypted successfully.",
"produces": [
"application/json"
],
Expand All @@ -87,7 +87,7 @@ const docTemplate = `{
"parameters": [
{
"type": "string",
"description": "Identity used for registeration and encrypting the message.",
"description": "Identity used for registration and encrypting the message.",
"name": "identity",
"in": "query",
"required": true
Expand All @@ -98,6 +98,13 @@ const docTemplate = `{
"name": "encryptedCommitment",
"in": "query",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "Optional eon parameter for the identity.",
"name": "eon",
"in": "query"
}
],
"responses": {
Expand All @@ -106,7 +113,8 @@ const docTemplate = `{
"schema": {
"type": "array",
"items": {
"type": "integer"
"type": "integer",
"format": "int32"
}
}
},
Expand Down Expand Up @@ -149,7 +157,7 @@ const docTemplate = `{
"parameters": [
{
"type": "string",
"description": "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",
"description": "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",
"name": "address",
"in": "query",
"required": true
Expand Down Expand Up @@ -253,6 +261,71 @@ const docTemplate = `{
}
}
},
"/get_event_decryption_key": {
"get": {
"security": [
{
"BearerAuth": []
}
],
"description": "Retrieves a decryption key for a given registered event based identity once it was triggered. Decryption key is 0x padded, clients need to remove the prefix when decrypting on their end.",
"produces": [
"application/json"
],
"tags": [
"Crypto"
],
"summary": "Get decryption key.",
"parameters": [
{
"type": "string",
"description": "Identity associated with the decryption key.",
"name": "identity",
"in": "query",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "Optional eon parameter for the identity.",
"name": "eon",
"in": "query"
}
],
"responses": {
"200": {
"description": "Success.",
"schema": {
"$ref": "#/definitions/GetDecryptionKey"
}
},
"400": {
"description": "Invalid Get decryption key request.",
"schema": {
"$ref": "#/definitions/error.Http"
}
},
"404": {
"description": "Decryption key not found for the associated identity.",
"schema": {
"$ref": "#/definitions/error.Http"
}
},
"429": {
"description": "Too many requests. Rate limited.",
"schema": {
"$ref": "#/definitions/error.Http"
}
},
"500": {
"description": "Internal server error.",
"schema": {
"$ref": "#/definitions/error.Http"
}
}
}
}
},
"/get_event_trigger_expiration_block": {
"get": {
"security": [
Expand All @@ -271,6 +344,7 @@ const docTemplate = `{
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "Eon number associated with the event identity registration.",
"name": "eon",
"in": "query",
Expand All @@ -282,13 +356,6 @@ const docTemplate = `{
"name": "identityPrefix",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Ethereum address associated with the identity. For gnosis mainnet, pass the address: 0x228DefCF37Da29475F0EE2B9E4dfAeDc3b0746bc. For chiado pass the address: 0xb9C303443c9af84777e60D5C987AbF0c43844918",
"name": "address",
"in": "query",
"required": true
}
],
"responses": {
Expand Down Expand Up @@ -586,8 +653,8 @@ const docTemplate = `{
"example": "amount"
},
"number": {
"type": "integer",
"example": 25433
"type": "string",
"example": "25433"
},
"op": {
"type": "string",
Expand Down
86 changes: 80 additions & 6 deletions docs/swagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@
"BearerAuth": []
}
],
"description": "Provides a way for clients to easily decrypt their encrypted message for which they have registered the identity for. Timestamp with which the identity was registered should have been passed for the message to be decrypted successfully.",
"description": "Provides a way for clients to easily decrypt their encrypted message for which they have registered the identity for. The trigger condition for the decryption key (timestamp or event) to be released must have been met for the message to be decrypted successfully.",
"produces": [
"application/json"
],
Expand All @@ -78,7 +78,7 @@
"parameters": [
{
"type": "string",
"description": "Identity used for registeration and encrypting the message.",
"description": "Identity used for registration and encrypting the message.",
"name": "identity",
"in": "query",
"required": true
Expand All @@ -89,6 +89,13 @@
"name": "encryptedCommitment",
"in": "query",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "Optional eon parameter for the identity.",
"name": "eon",
"in": "query"
}
],
"responses": {
Expand All @@ -97,7 +104,8 @@
"schema": {
"type": "array",
"items": {
"type": "integer"
"type": "integer",
"format": "int32"
}
}
},
Expand Down Expand Up @@ -140,7 +148,7 @@
"parameters": [
{
"type": "string",
"description": "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",
"description": "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",
"name": "address",
"in": "query",
"required": true
Expand Down Expand Up @@ -244,6 +252,71 @@
}
}
},
"/get_event_decryption_key": {
"get": {
"security": [
{
"BearerAuth": []
}
],
"description": "Retrieves a decryption key for a given registered event based identity once it was triggered. Decryption key is 0x padded, clients need to remove the prefix when decrypting on their end.",
"produces": [
"application/json"
],
"tags": [
"Crypto"
],
"summary": "Get decryption key.",
"parameters": [
{
"type": "string",
"description": "Identity associated with the decryption key.",
"name": "identity",
"in": "query",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "Optional eon parameter for the identity.",
"name": "eon",
"in": "query"
}
],
"responses": {
"200": {
"description": "Success.",
"schema": {
"$ref": "#/definitions/GetDecryptionKey"
}
},
"400": {
"description": "Invalid Get decryption key request.",
"schema": {
"$ref": "#/definitions/error.Http"
}
},
"404": {
"description": "Decryption key not found for the associated identity.",
"schema": {
"$ref": "#/definitions/error.Http"
}
},
"429": {
"description": "Too many requests. Rate limited.",
"schema": {
"$ref": "#/definitions/error.Http"
}
},
"500": {
"description": "Internal server error.",
"schema": {
"$ref": "#/definitions/error.Http"
}
}
}
}
},
"/get_event_trigger_expiration_block": {
"get": {
"security": [
Expand All @@ -262,6 +335,7 @@
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "Eon number associated with the event identity registration.",
"name": "eon",
"in": "query",
Expand Down Expand Up @@ -570,8 +644,8 @@
"example": "amount"
},
"number": {
"type": "integer",
"example": 25433
"type": "string",
"example": "25433"
},
"op": {
"type": "string",
Expand Down
Loading