{"id":26795087,"url":"https://github.com/shutter-network/shutter-api","last_synced_at":"2026-01-12T06:38:30.250Z","repository":{"id":265064047,"uuid":"893993694","full_name":"shutter-network/shutter-api","owner":"shutter-network","description":"An API that allows to use shutter by exposing relevant API endpoints.","archived":false,"fork":false,"pushed_at":"2025-03-24T21:07:25.000Z","size":375,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-24T22:22:00.004Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shutter-network.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-25T15:07:34.000Z","updated_at":"2025-03-21T16:29:41.000Z","dependencies_parsed_at":"2024-12-16T18:41:57.069Z","dependency_job_id":"dc884370-33bc-43af-bfe7-61cd4fe74a55","html_url":"https://github.com/shutter-network/shutter-api","commit_stats":null,"previous_names":["shutter-network/shutter-service-api","shutter-network/shutter-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shutter-network%2Fshutter-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shutter-network%2Fshutter-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shutter-network%2Fshutter-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shutter-network%2Fshutter-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shutter-network","download_url":"https://codeload.github.com/shutter-network/shutter-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246223267,"owners_count":20743158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-29T17:45:19.556Z","updated_at":"2026-01-12T06:38:30.244Z","avatar_url":"https://github.com/shutter-network.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shutter API Documentation for dApp Developers\n\n## Disclaimer\n\nThis software is in its early stages of development. Users are strongly advised to exercise caution and not entrust any assets or sensitive information of high value to this API until further maturity and decentralization are achieved.\n\nPlease note that all threshold cryptography systems and multi-party computation (MPC) frameworks inherently rely on a threshold trust assumption. While the Shutter API currently utilizes a decentralized set of keypers, the network is not fully decentralized at this time. We expect additional keypers to join and enhance the network's resilience shortly.\n\nThis project is released as open source and provided \"as is\" without any warranties, express or implied. The developers and contributors assume no liability for any issues, losses, or damages arising from the use or misuse of this API. Use at your own risk.\n\n---\n\n## Welcome to the **Shutter API** documentation!\n\nThis guide will help you integrate Shutter's Commit and Reveal Scheme into your decentralized application (dApp). The Shutter system provides a secure, decentralized, and tamper-proof commit-and-reveal workflow, ensuring integrity and confidentiality in your application.\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Prerequisites](#prerequisites)\n3. [Endpoints](#endpoints)\n   - [Register an Identity with a Decryption Trigger](#1-register-an-identity-with-a-decryption-trigger)\n   - [Retrieve the Encryption Data](#2-retrieve-the-encryption-data)\n   - [Retrieve the Decryption Key](#3-retrieve-the-decryption-key)\n   - [Decrypt Commitments](#4-decrypt-commitments)\n4. [Future features](#future-features)\n5. [FAQs](#faqs)\n6. [Swagger Documentation](#swagger-documentation)\n7. [Support](#support)\n\n---\n\n## Overview\n\nThe Shutter system leverages threshold encryption, distributed cryptographic operations, and a decentralized infrastructure to handle commitments securely. Core components include:\n\n- **Registry Contract**: An on-chain contract where clients register identities and specify time-based decryption triggers.\n- **Keypers**: A distributed set of nodes that monitor the registry contract, handle cryptographic operations such as distributed key generation, and release decryption keys securely.\n- **API**: An API that simplifies interaction with the Shutter system by exposing endpoints for encryption and decryption operations.\n\nThis documentation will guide you through:\n- Setting up identities and time-based decryption triggers.\n- Retrieving encryption data and decryption keys.\n- Decrypting encrypted commitments.\n\n---\n\n## Prerequisites\n\n- **API Access**:\n  At the moment, the access is free of charge, but rate limited for Gnosis Mainnet. You only need to query the API endpoints at the addresses below:\n  - **Chiado**: `https://shutter-api.chiado.staging.shutter.network/api/[ADD_ENDPOINT]`\n  - **Mainnet**: `https://shutter-api.shutter.network/api/[ADD_ENDPOINT]`\n\n- **Address of the Shutter Registry Contract**:\n  - **Chiado Address**: `0x2693a4Fb363AdD4356e6b80Ac5A27fF05FeA6D9F`\n  - **Gnosis Address**: `0x694e5de9345d39C148DA90e6939A3fd2142267D9`\n\n- **Address of the API**:\n  - **Chiado Address**: `0xb9C303443c9af84777e60D5C987AbF0c43844918`\n  - **Gnosis Address**: `0x228DefCF37Da29475F0EE2B9E4dfAeDc3b0746bc`\n\n### Rate limits / Authorization\n\nFor unauthorized access, the API on Gnosis Mainnet is rate limited with these limits per endpoint and remote ip:\n\n  - `/register_identity` 5 requests per 24 hours\n  - `/get_data_for_encryption` 10 requests per 24 hours\n  - `/get_decryption_key` 20 requests per 24 hours\n  - `/decrypt_commitment` 10 requests per 24 hours\n\nWe recommend using Chiado for development, because there are no rate limits in place.\n\nIf you need higher limits, contact [loring@brainbot.com](mailto:loring@brainbot.com) to request an API key.\n\nAuthorized requests have these limits:\n\n  - `/register_identity` 500 requests per 24 hours\n  - `/get_data_for_encryption` 1000 requests per 24 hours\n  - `/get_decryption_key` 2000 requests per 24 hours\n  - `/decrypt_commitment` 1000 requests per 24 hours\n\nAuthorization is done by using an `Authorization: Bearer $API_KEY` header, when calling the API.\n\nUse the `/check_authentication` endpoint, to test your API key.\n\n---\n\n## Endpoints\n\n### 1.A Register an Identity with Time-based Decryption Triggers\n\nTo begin using the Shutter system, register an identity and specify a time-based decryption trigger. This step links an identity to a decryption key and sets the release conditions for the key to a Unix timestamp.\n\nRefer to the `/register_identity` endpoint in the Swagger documentation for details on parameters and responses.\n\n\u003e **Note**: When registering identities through our API, the API account address is used to compute the identity that will be returned. If you want to use your own address, you need to submit the registration directly to the registry contract. The contract's definition can be found here:\n\u003e [ShutterRegistry.sol](https://github.com/shutter-network/contracts/blob/main/src/shutter-service/ShutterRegistry.sol#L1C1-L86C2).\n\n#### Example Request\n```bash\ncurl -X POST https://\u003cAPI_BASE_URL\u003e/register_identity \\\n-H \"Content-Type: application/json\" \\\n-d '{\n  \"decryptionTimestamp\": 1735044061,\n  \"identityPrefix\": \"0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0\"\n}'\n```\n\n#### Example Response\n```json\n{\n  \"eon\": 1,\n  \"eon_key\": \"0x57af5437a84ef50e5ed75772c18ae38b168bb07c50cadb65fc6136604e662255\",\n  \"identity\": \"0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75\",\n  \"identity_prefix\": \"0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0\",\n  \"tx_hash\": \"0x3026ad202ca611551377eef069fb6ed894eae65329ce73c56f300129694f12ba\"\n}\n```\n\n### 1.B Register an Identity with Event-based Decryption Triggers [WIP]\n\nAn alternative is the upcoming feature of \"event-based\" decryption triggers. This is very similar to the time-based release conditions discussed above. However here the decryption key is produced only when a specific EVM event has been observed by the keypers.\n\nThe trigger condition is specified by a `contract address` (mandatory), the event's `topic-0` (mandatory) and a number of additional topic- or data-matchers. Event data can be matched as `byte-equals` or numeric comparisons (`\u003c, \u003c=, ==, \u003e=, \u003e`) over an uint256-cast of the specified event data fields.\n\nRegistered event based decryption triggers are bound by a time-to-live (`ttl`). The decryption keys are only released once and only if\n\n- the release condition has not been met before (since registration)\n- the `ttl` timer has not run out, and\n- *all* conditions of the trigger definition were fulfilled.\n\n\n\u003e **Note**: When registering identities through our API, the API account address is used to compute the identity that will be returned. If you want to use your own address, you need to submit the registration directly to the registry contract. The contract's definition can be found here:\n\u003e [ShutterEventRegistry.sol](https://github.com/shutter-network/contracts/blob/main/src/shutter-service/ShutterEventTriggerRegistry.sol#L35-L40)\n\n#### Example Request\n```bash\ncurl -X POST https://\u003cAPI_BASE_URL\u003e/register_event_identity \\\n-H \"Content-Type: application/json\" \\\n-d '{\n  \"eventDefinition\": \"0x808ba62b3fb085eae2e58888828d5aa5d0d8d3cc44dcb1750e3664468a1288c38501d8d9e5d89930656b6ce9aa13b6a311031b89963b83d95588e26e5e8a9aeef2b9c1b07740d24bbd7aef9935fde194e05aff41fe6e3529de9a4b81779ddf4bed488b753efabe29aa7407bf131a7f744f2cf0429b0a200b1d369791fae3c740d62edd422b649a41660a6f0bd4310ecad617fb8ba626970934bd473c4dcc7784fac7ed66c4576590c76e70af4f3d99ea1361669349beb8cbb3346e9cc821435d\",\n  \"identityPrefix\": \"0x32fdbd2ca52e171f77db2757ff6200cd8446350f927a3ad46c0565483dd8b41c\"\n}'\n```\n\n\u003e **Note**: The encoding of `eventDefinition` is specified [elsewhere](FIXME link missing). It is a concatenation of contract address, topic0 and the rlp encoding of the other conditions. Event definitions should be constructed by using provided tooling (WIP).\n\n#### Example Response\n```json\n{\n  \"eon\": 1,\n  \"eon_key\": \"0x9348cbe5372c1b467bfe60d6c678bbe1aed74a90b93f857b2db1b6a5dac5cd95\",\n  \"identity\": \"0xdfb9b97b2ff057a1fdff173e10e974ffb16c28105f0524b33e8a6906c6c81dc0\",\n  \"identityPrefix\": \"0x32fdbd2ca52e171f77db2757ff6200cd8446350f927a3ad46c0565483dd8b41c\",\n  \"tx_hash\": \"0xf7cb7ef13edee67735bba17d5ff84546a1ac7547b3d2a9f1d15e4d1b2e9f303c\"\n}\n```\n\n### 2. Retrieve the Encryption Data\n\nTo encrypt commitments, obtain the encryption data associated with your identity. Use the `/get_data_for_encryption` endpoint to retrieve all necessary encryption data.\n\nRefer to the Swagger documentation for specifics on this endpoint.\n\n#### Example Request\n```bash\ncurl -X GET \"https://\u003cAPI_BASE_URL\u003e/get_data_for_encryption?address=0xb9C303443c9af84777e60D5C987AbF0c43844918\u0026identityPrefix=0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0\"\n```\n\n#### Example Response\n```json\n{\n\"eon\": 1,\n\"eon_key\": \"0x57af5437a84ef50e5ed75772c18ae38b168bb07c50cadb65fc6136604e662255\",\n\"identity\": \"0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75\",\n\"identity_prefix\": \"0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0\",\n\"epoch_id\": \"0x88f2495d1240f9c5523db589996a50a4984ee7a08a8a8f4b269e4345b383310abd2dc1cd9c9c2b8718ed3f486d5242f5\"\n}\n```\n\n#### Encrypting Commitments in Go\n\nThe following Go code demonstrates how to use the encryption data retrieved from the Shutter API to encrypt commitments:\n\n```go\n// NOTE: This example requires the \"github.com/shutter-network/shutter/shlib/shcrypto\" package.\n// Make sure to install it in your Go environment before running this code.\npackage main\n\nimport (\n  \"crypto/rand\"\n  \"encoding/hex\"\n  \"fmt\"\n  \"log\"\n  \"strings\"\n\n  \"github.com/shutter-network/shutter/shlib/shcrypto\"\n)\n\nfunc main() {\n  // Encryption data provided by the Shutter API\n  identityHex := \"0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75\"\n  eonPublicKeyHex := \"0x57af5437a84ef50e5ed75772c18ae38b168bb07c50cadb65fc6136604e662255\"\n  message := []byte(\"please hide this message\")\n\n  identityHex = strings.TrimPrefix(identityHex, \"0x\")\n  eonPublicKeyHex = strings.TrimPrefix(eonPublicKeyHex, \"0x\")\n\n  // Convert hex strings to bytes\n  identity, err := hex.DecodeString(identityHex)\n  if err != nil {\n    log.Fatalf(\"Failed to decode identity: %v\", err)\n  }\n\n  eonPublicKeyBytes, err := hex.DecodeString(eonPublicKeyHex)\n  if err != nil {\n    log.Fatalf(\"Failed to decode eon public key: %v\", err)\n  }\n\n  // Create EonPublicKey struct from bytes\n  eonPublicKey := \u0026shcrypto.EonPublicKey{}\n  if err := eonPublicKey.Unmarshal(eonPublicKeyBytes); err != nil {\n    log.Fatalf(\"Failed to unmarshal EonPublicKey: %v\", err)\n  }\n\n  // Compute the Epoch ID from the identity\n  epochID := shcrypto.ComputeEpochID(identity)\n\n  // Generate a random sigma\n  sigma, err := shcrypto.RandomSigma(rand.Reader)\n  if err != nil {\n    log.Fatalf(\"Failed to generate random sigma: %v\", err)\n  }\n\n  // Encrypt the message\n  encryptedCommitment := shcrypto.Encrypt(message, eonPublicKey, epochID, sigma)\n\n  // Marshal the encrypted commitment into bytes\n  encryptedCommitmentBytes := encryptedCommitment.Marshal()\n\n  // Convert to hex string\n  encryptedCommitmentHex := \"0x\" + hex.EncodeToString(encryptedCommitmentBytes)\n\n  // Print the encrypted commitment\n  fmt.Printf(\"Encrypted Commitment: %s\\n\", encryptedCommitmentHex)\n}\n```\n\n#### Encrypting Commitments in TypeScript\n\nYou can also use our [Shutter TypeScript SDK](https://github.com/shutter-network/shutter-sdk) to easily encrypt commitments:\n\n```ts\nimport { encryptData } from \"@shutter-network/shutter-sdk\";\nimport { stringToHex } from \"viem\";\n\n// Encryption data provided by the Shutter API\nconst eonKeyHex = \"0x57af5437a84ef50e5ed75772c18ae38b168bb07c50cadb65fc6136604e662255\";\nconst identityPreimageHex = \"0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75\";\nconst msgHex = stringToHex(\"please hide this message\")\n\n// some random sigma\nconst sigmaHex = \"0x312c10b186086d502ba683cffc2ae650d53b508904b3c430df8e7d5aa336c0f5\";\n\n// Encrypt the message\nconst encryptedCommitment = await encryptData(message, eonPublicKey, identityPreimageHex, sigma);\n// Print the encrypted commitment\nconsole.log(\"Encrypted Commitment:\", encryptedCommitment);\n```\n\n### 3. Retrieve the Decryption Key\n\nAfter the decryption trigger conditions are met (i.e., the specified timestamp has passed), retrieve the decryption key using the `/get_decryption_key` endpoint.\n\nRefer to the Swagger documentation for detailed usage.\n\n#### Example Request\n```bash\ncurl -X GET \"https://\u003cAPI_BASE_URL\u003e/get_decryption_key?identity=0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75\"\n```\n\n#### Example Response\n```json\n{\n  \"decryption_key\": \"0x99a805fc26812c13041126b25e91eccf3de464d1df7a95d1edca8831a9ec02dd\",\n  \"decryption_timestamp\": 1735044061,\n  \"identity\": \"0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75\"\n}\n```\n\n### 4. Decrypt Commitments\n\nOnce you have the decryption key, use it to decrypt commitments encrypted with the Shutter system. The `/decrypt_commitment` endpoint enables this process.\n\nRefer to the Swagger documentation for endpoint details.\n\n#### Example Request\n```bash\ncurl -X GET \"https://\u003cAPI_BASE_URL\u003e/decrypt_commitment?identity=0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75\u0026encryptedCommitment=0x03b5685a460a95ba628e04b24155d6722f7c4e376a1627f714a4ae9cecd2982e005eff12ac8150b8842c29f8d5eaf4d0da0b626f762b4826d779d8969b577acb28df96cab026aa57c00cd74b07ca51e8c0c1a59933e29a728311900ebfc26c6804260914c96cb10dbd6d2ed3f6cb77788a74b5aae5f4ce6f40be53310a0524d42d5a6f03b5c1517ec097553733e228276fcdfc4b569f7ef4311a461d68819d634c\"\n```\n\n#### Example Response\n```json\n{\n  \"decrypted_message\": \"0x706c6561736520686964652074686973206d657373616765\"\n}\n```\n\nThe decrypted message is returned in its hex format. To get the initial message, convert the decrypted message to string.\n\n\u003e **Note**: Replace `\u003cAPI_BASE_URL\u003e` in all example requests with the actual base URL for the API, found in the pre-requisite section, such as `https://shutter-api.shutter.network/api`.\n\n## Future Features\n\n- **Event-Based and Block-Based Triggers**\n  Future versions of the Shutter system will support event-based and block-based decryption triggers for enhanced functionality.\n\n- **Real-Time Notifications**\n  Planned updates include WebSocket-based notifications for real-time key releases, improving user experience and interactivity.\n\n## FAQs\n\n### What happens if a keyper experiences downtime?\nThe keyper set is designed to handle downtime gracefully. Any missed decryption key releases will be sent upon recovery.\n\n### How secure is the Shutter system?\nThe Shutter system uses threshold encryption and distributed cryptographic operations to ensure that no single entity can compromise the security of commitments.\n\n## Swagger Documentation\n\nFor detailed API specifications, including parameters, responses, and error codes, visit the Swagger Documentation:\n\n- [Chiado Swagger Documentation](https://shutter-api.chiado.staging.shutter.network/docs/index.html)\n- [Mainnet Swagger Documentation](https://shutter-api.shutter.network/docs/index.html)\n\n## Support\n\nFor additional support or inquiries:\n- Contact the Shutter development team.\n- Open an issue on our GitHub repository.\n\n---\n\nThank you for using Shutter! Together, we are building a more secure and decentralized future.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshutter-network%2Fshutter-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshutter-network%2Fshutter-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshutter-network%2Fshutter-api/lists"}