From 909ca3e89cb0ebc6f88b526645f625f35f13f552 Mon Sep 17 00:00:00 2001 From: "Smokyish@github.com" Date: Tue, 21 Oct 2025 15:31:40 +0300 Subject: [PATCH 1/2] Update event-based trigger related API entries --- docs/protocol/api/get_started.md | 61 ++---- docs/protocol/api/glossary.md | 2 +- docs/protocol/api/how_it_works.md | 29 +-- docs/protocol/api/index.md | 6 +- .../api/integrating_api_llm_friendly.md | 71 ++----- docs/protocol/api/use_cases.md | 174 +++--------------- 6 files changed, 64 insertions(+), 279 deletions(-) diff --git a/docs/protocol/api/get_started.md b/docs/protocol/api/get_started.md index 9bdb659..c960cb3 100644 --- a/docs/protocol/api/get_started.md +++ b/docs/protocol/api/get_started.md @@ -69,27 +69,18 @@ This request registers an identity and sets a future timestamp when the decrypti } ``` -#### **Option 2: Register an Identity with an Event Trigger (ETD)** +#### **Option 2: Register an Identity with an Event Trigger (WIP)** -Instead of a time trigger, you can register an **Event Trigger Definition (ETD)**. The identity will decrypt when Keypers observe a matching on-chain event from a specific contract. +Instead of using a time trigger, you can register an identity that decrypts when Keypers observe a corresponding on-chain event within a TTL window. Utilize the **`/register_event_identity`** endpoint with an encoded `eventDefinition`. -##### API Call: Register Identity with ETD +##### API Call: Register Event Identity ```bash -curl -X POST https://shutter-api.shutter.network/register_identity\ +curl -X POST https://shutter-api.shutter.network/register_event_identity\ -H "Content-Type: application/json"\ -d '{ - "trigger": { - "type": "event", - "etd": { - "contract": "0xA1b2c3D4e5F6a7B8c9D0E1f2A3b4C5d6E7f8A9B0", - "eventSignature": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", - "indexedTopics": [null, null, "0x000000000000000000000000feed0000000000000000000000000000cafe"], - "conditions": [{"arg":"value","op":"gte","value":"10000000"}], - "ttl": 86400 - } - }, - "identityPrefix": "0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0" + "eventDefinition": "0x808ba62b3fb085eae2e58888828d5aa5d0d8d3cc44dcb1750e3664468a1288c38501d8d9e5d89930656b6ce9aa13b6a311031b89963b83d95588e26e5e8a9aeef2b9c1b07740d24bbd7aef9935fde194e05aff41fe6e3529de9a4b81779ddf4bed488b753efabe29aa7407bf131a7f744f2cf0429b0a200b1d369791fae3c740d62edd422b649a41660a6f0bd4310ecad617fb8ba626970934bd473c4dcc7784fac7ed66c4576590c76e70af4f3d99ea1361669349beb8cbb3346e9cc821435d", + "identityPrefix": "0x32fdbd2ca52e171f77db2757ff6200cd8446350f927a3ad46c0565483dd8b41c" }' ``` @@ -97,20 +88,14 @@ curl -X POST https://shutter-api.shutter.network/register_identity\ ```json { - "eon": 2, - "eon_key": "0x9ab65437a84ef50e5ed75772c18ae38b168bb07c50cadb65fc6136604e6622aa", - "identity": "0x5f77b7e72f3d2c5b1a0f1c2a33b6f4a1b9d8c7e6f5a4b3c29181716151413121", - "tx_hash": "0x6d54be9940b784b10c9a0c95c6ed1d6df8a8c1d2a78b7d9a0c7e6f5d4c3b2a19" + "eon": 1, + "eon_key": "0x9348cbe5372c1b467bfe60d6c678bbe1aed74a90b93f857b2db1b6a5dac5cd95", + "identity": "0xdfb9b97b2ff057a1fdff173e10e974ffb16c28105f0524b33e8a6906c6c81dc0", + "identityPrefix": "0x32fdbd2ca52e171f77db2757ff6200cd8446350f927a3ad46c0565483dd8b41c", + "tx_hash": "0xf7cb7ef13edee67735bba17d5ff84546a1ac7547b3d2a9f1d15e4d1b2e9f303c" } ``` -:::note **Notes** - -- `eventSignature` is the Keccak-256 topic0 of the event. -- `indexedTopics` positions map to topic1 to topic3. Use `null` for wildcards. -- `conditions` apply to non-indexed arguments, for example numeric comparisons. -- `ttl` is the number of seconds to track the event after registration. -::: * * * * * ### 2\. **Encrypt and Submit the Commitment** @@ -163,29 +148,9 @@ const decryptedData = await decrypt(encryptedData, epochSecretKey); console.log("Decryption successful:", decryptedData); ``` -#### Alternative: **Decrypt After Event Trigger** - -For ETD identities, the key is released when a matching on-chain event is observed within the TTL window. - -##### Optionally check identity status - -```bash -curl -X GET "https://shutter-api.shutter.network/get_identity_status?identity=0x5f77b7e72f3d2c5b1a0f1c2a33b6f4a1b9d8c7e6f5a4b3c29181716151413121" -``` - -Example response: - -```json -{ "status": "satisfied", "triggerType": "event", "observedAt": 1735045061 } -``` - -##### Retrieve decryption key - -```bash -curl -X GET "https://shutter-api.shutter.network/get_decryption_key?identity=0x5f77b7e72f3d2c5b1a0f1c2a33b6f4a1b9d8c7e6f5a4b3c29181716151413121" -``` +#### Alternative: **Decrypt After Event Trigger (WIP)** -Use the same SDK `decrypt` call as above to reveal the plaintext. +For identities registered with **`/register_event_identity`**, the decryption key is released when a corresponding on-chain event is observed within the time-to-live (TTL) window. * * * * * diff --git a/docs/protocol/api/glossary.md b/docs/protocol/api/glossary.md index a3893fc..b971ab0 100644 --- a/docs/protocol/api/glossary.md +++ b/docs/protocol/api/glossary.md @@ -99,7 +99,7 @@ A hardware-based solution that provides a secure enclave for running private com #### **Event-Based Encryption Triggers** The Shutter API enables encryption to be **triggered by predefined events**, such as **when all players submit their moves in a game**, instead of relying solely on time-based triggers. This approach ensures that decryption occurs only when all specified conditions are met. -Decryption is **released when a specific on-chain event is observed** by the Keypers. These events are compared against a registered **Event Trigger Definition (ETD)**, which details the emitter contract, the event signature, and includes optional indexed topic filters as well as conditions for non-indexed arguments. This functionality is useful for various applications, such as payment-gated content, enhancing DAO transparency after a proposal is executed, settling auctions once they are closed, or revealing game rounds upon completion. +The decryption key is **released when the Keypers observe a specific on-chain event**. These events are compared against a registered **Event Trigger Definition (ETD)** outlining the emitter contract and the event signature. It may also include optional indexed topic filters and conditions for non-indexed arguments. Each ETD has a **time-to-live (TTL)** window. Keys are **released only** if the condition has not been met previously and all constraints are satisfied. --- diff --git a/docs/protocol/api/how_it_works.md b/docs/protocol/api/how_it_works.md index fe17674..ef3a22b 100644 --- a/docs/protocol/api/how_it_works.md +++ b/docs/protocol/api/how_it_works.md @@ -43,11 +43,10 @@ The Shutter protocol provides a robust and secure commit-and-reveal workflow by

- **Register Identity with Timestamp**: Allows clients to register identities and decryption triggers seamlessly. - - **Register Identity with Event Trigger (ETD)**: This feature enables clients to register identities that decrypt upon the observation of a specific on-chain event. + - **Register Event Identity (event-based trigger)**: Register identities that are decrypted upon observing a specific on-chain event by submitting an encoded `eventDefinition` via `/register_event_identity`. - **Retrieve Encryption Data**: Enables retrieval of encryption data for specific identities. - **Retrieve Decryption Keys**: Provides access to decryption keys once trigger conditions are met. - **Decrypt Commitments**: Facilitates direct decryption of commitments using stored decryption keys. - - **Get Identity Status**: Indicates if an identity is pending, satisfied, expired by TTL, or finalized.

@@ -115,7 +114,7 @@ Before using Shutter's encryption, a dApp must **register an identity and specif :::tip[How it works] 1. For time-based identities, the developer sends a request to the Shutter API to **register an identity with a decryption timestamp**. -2. For event-based identities, the developer sends a request to **register an identity with an Event Trigger Definition (ETD)**, which specifies which on-chain event will unlock decryption and how long it should be tracked. +2. For event-based identities, the developer sends a request to register an event identity via `/register_event_identity`, submitting an encoded `eventDefinition` that specifies the on-chain event to monitor and a TTL for tracking. 3. The API **submits this registration to the on-chain registry contract**. 4. The **Keypers monitor the registry** and initiate the **threshold key generation process**. 5. Once successful, the registry **stores the identity and its associated trigger**. @@ -132,31 +131,19 @@ The Shutter API can optionally **cover the gas fees** for this transaction. curl -X POST https://API_BASE_URL/register_identity \ -H "Content-Type: application/json" \ -d '{ - "trigger": { - "type": "time", - "decryptionTimestamp": 1735044061 - }, + "decryptionTimestamp": 1735044061, "identityPrefix": "0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0" }' ``` -> ##### Event-based (inline ETD) +> ##### Event-based (register event identity) ```bash -curl -X POST https://API_BASE_URL/register_identity \ --H "Content-Type: application/json" \ +curl -X POST https://API_BASE_URL/register_event_identity\ +-H "Content-Type: application/json"\ -d '{ - "trigger": { - "type": "event", - "etd": { - "contract": "0xA1b2c3D4e5F6a7B8c9D0E1f2A3b4C5d6E7f8A9B0", - "eventSignature": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", - "indexedTopics": [null, "0x000000000000000000000000feed0000000000000000000000000000cafe", null], - "conditions": [{"arg":"value","op":"gte","value":"10000000"}], - "ttl": 86400 - } - }, - "identityPrefix": "0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0" + "eventDefinition": "0x808ba62b3fb085eae2e58888828d5aa5d0d8d3cc44dcb1750e3664468a1288c38501d8d9e5d89930656b6ce9aa13b6a311031b89963b83d95588e26e5e8a9aeef2b9c1b07740d24bbd7aef9935fde194e05aff41fe6e3529de9a4b81779ddf4bed488b753efabe29aa7407bf131a7f744f2cf0429b0a200b1d369791fae3c740d62edd422b649a41660a6f0bd4310ecad617fb8ba626970934bd473c4dcc7784fac7ed66c4576590c76e70af4f3d99ea1361669349beb8cbb3346e9cc821435d", + "identityPrefix": "0x32fdbd2ca52e171f77db2757ff6200cd8446350f927a3ad46c0565483dd8b41c" }' ``` diff --git a/docs/protocol/api/index.md b/docs/protocol/api/index.md index 1b002b5..304dc95 100644 --- a/docs/protocol/api/index.md +++ b/docs/protocol/api/index.md @@ -23,7 +23,11 @@ The system operates using a commit-and-reveal process. In this process, a user e Developers can integrate Shutter API into various applications, such as decentralized finance platforms that want to protect traders from MEV attacks, DAOs looking to implement private and tamper-proof voting, and gaming applications that require secrecy in game mechanics. The API also enables new use cases, such as parimutuel betting, sealed RFPs for corporate procurement, and fair auction mechanisms that eliminate the Free Option Problem, ensuring that bids remain confidential until the deadline. -**The Shutter API also introduces event-based decryption triggers**, which allow encrypted data to be automatically revealed when specific on-chain conditions are met. This feature enables programmable, state-dependent privacy. For example, it can reveal a document after a payment is made, unlock a game secret when a milestone is reached, or release encrypted content when a contract emits a particular event. +**The Shutter API introduces event-based decryption triggers**, allowing encrypted data to be automatically revealed when specific on-chain conditions are met. This feature enables programmable, state-dependent privacy. For instance, it can reveal a document after a payment is made, unlock a game secret when a milestone is achieved, or release encrypted content when a contract emits a particular event. + +**Currently, event-based triggers can be accessed through a single API endpoint: `POST /register_event_identity`. This endpoint registers an identity linked to an encoded event definition (`eventDefinition`). Keys will be released only if the observed event matches the definition within its time-to-live (TTL) window and the condition has not been met before.** + +Please note that event-based triggers are still a work in progress; at this time, there are no separate endpoints for "register event trigger" or "get trigger status." Unlike solutions based on Trusted Execution Environments (TEEs), which introduce a single point of failure and rely on specialized hardware, Shutter API provides a fully decentralized approach that does not require trusting any central entity. It operates as a distributed threshold encryption network, where independent Keypers collaboratively generate and release encryption keys, making it a truly trust-minimized solution. diff --git a/docs/protocol/api/integrating_api_llm_friendly.md b/docs/protocol/api/integrating_api_llm_friendly.md index 1d7820d..e7fa05c 100644 --- a/docs/protocol/api/integrating_api_llm_friendly.md +++ b/docs/protocol/api/integrating_api_llm_friendly.md @@ -1,4 +1,3 @@ - --- title: Integrating Shutter API and SDK for dApp Development description: Integrating Shutter API and SDK for dApp Development @@ -123,33 +122,21 @@ Note: Replace `API_BASE_URL` with the appropriate API base URL (Chiado or Mainne ### Registering an Identity with an Event-Based Trigger (ETD) -To release decryption when a specific on-chain event occurs, use an **Event Trigger Definition**. In this definition, you specify the contract that emits the event, the event signature, and any optional indexed topic filters. You can also set conditions on non-indexed arguments if needed. Additionally, you will establish a Time-To-Live (TTL) to limit how long the Keypers will monitor the trigger. +To release decryption when a specific on-chain event occurs, use an **Event Trigger Definition**. For alignment with the current API, submit the encoded **`eventDefinition`** using **`/register_event_identity`** (WIP). The encoding is a concatenation of the contract address, topic0, and the RLP-encoded matchers (use provided tooling when available). You also supply an `identityPrefix`. ``` -Endpoint: /register_event_trigger +Endpoint: /register_event_identity Method: POST ``` #### Example Request ``` -curl -X POST https://`API_BASE_URL`/register_event_trigger\ +curl -X POST https://`API_BASE_URL`/register_event_identity\ -H "Content-Type: application/json"\ -d '{ - "identityPrefix": "0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0", - "etd": { - "contract": "0x1234567890abcdef1234567890abcdef12345678", - "eventSignature": "0x4bb278f3a1a2c3f4d5e6a7b8c9d0e1f2a3b4c5d6e7f8090a1b2c3d4e5f607182", - "indexedTopics": [ - "0x000000000000000000000000228DefCF37Da29475F0EE2B9E4dfAeDc3b0746bc", - null, - null - ], - "conditions": [ - {"argIndex": 2, "op": ">=", "value": "1000000000000000000"} - ], - "ttl": 86400 - } + "eventDefinition": "0x808ba62b3fb085eae2e58888828d5aa5d0d8d3cc44dcb1750e3664468a1288c38501d8d9e5d89930656b6ce9aa13b6a311031b89963b83d95588e26e5e8a9aeef2b9c1b07740d24bbd7aef9935fde194e05aff41fe6e3529de9a4b81779ddf4bed488b753efabe29aa7407bf131a7f744f2cf0429b0a200b1d369791fae3c740d62edd422b649a41660a6f0bd4310ecad617fb8ba626970934bd473c4dcc7784fac7ed66c4576590c76e70af4f3d99ea1361669349beb8cbb3346e9cc821435d", + "identityPrefix": "0x32fdbd2ca52e171f77db2757ff6200cd8446350f927a3ad46c0565483dd8b41c" }' ``` @@ -157,47 +144,15 @@ curl -X POST https://`API_BASE_URL`/register_event_trigger\ ``` { - "identity": "0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75", - "eon": 1, - "eon_key": "0x57af5437a84ef50e5ed75772c18ae38b168bb07c50cadb65fc6136604e662255", - - "epoch_id": "0x88f2495d1240f9c5523db589996a50a4984ee7a08a8a8f4b269e4345b383310a", - - "tx_hash": "0xabcdad202ca611551377eef069fb6ed894eae65329ce73c56f300129694f1abc" - -} -``` - -* * * * * - -### Checking Trigger Status - -Query the current status of a time-based or event-based identity. Useful for polling your UI. - -``` -Endpoint: /get_trigger_status -Method: GET -``` - -#### Example Request - -```bash -curl -X GET "https://`API_BASE_URL`/get_trigger_status?identity=0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75" -``` - -#### Example Response + "eon_key": "0x9348cbe5372c1b467bfe60d6c678bbe1aed74a90b93f857b2db1b6a5dac5cd95", -``` -{ - "identity": "0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75", + "identity": "0xdfb9b97b2ff057a1fdff173e10e974ffb16c28105f0524b33e8a6906c6c81dc0", - "type": "event", + "identityPrefix": "0x32fdbd2ca52e171f77db2757ff6200cd8446350f927a3ad46c0565483dd8b41c", - "status": "Satisfied", - - "observedAt": 1735045061 + "tx_hash": "0xf7cb7ef13edee67735bba17d5ff84546a1ac7547b3d2a9f1d15e4d1b2e9f303c" } ``` @@ -263,7 +218,6 @@ curl -X GET "https://`API_BASE_URL`/get_decryption_key?identity=0x8c232eae4f9 } ``` - * * * * * ### Decrypting Commitments @@ -301,7 +255,7 @@ The Shutter SDK is a TypeScript library that simplifies the encryption and decry To install the Shutter SDK in your project, run: -`npm install @shutter-network/shutter-sdk` +`npm install @shutter-network/shutter-sdk` * * * * * @@ -346,7 +300,7 @@ console.log("Decrypted Message:", decryptedData); ``` :::note [Note] -For event-based triggers, first poll or subscribe to trigger status, then request the decryption key and run the same decrypt flow. +For event-based triggers, wait until the event condition is met, then request the decryption key and execute the same decryption flow. ::: * * * * * @@ -370,7 +324,6 @@ import ( "strings" - "github.com/shutter-network/shutter/shlib/shcrypto" ) @@ -438,7 +391,7 @@ When building a new dApp with the Shutter API, follow these steps: Tip: If you want full control over your address, consider registering directly with the registry contract. - *Event-based option*: You can also register an identity with an ETD using **/register_event_trigger** so that decryption keys are released when a matching on-chain event is observed. + *Event-based option*: You can register an identity with an ETD using **/register_event_identity** by submitting the encoded `eventDefinition` along with your `identityPrefix`. 3. **Retrieve Encryption Data** diff --git a/docs/protocol/api/use_cases.md b/docs/protocol/api/use_cases.md index 4ed7bae..c66b153 100644 --- a/docs/protocol/api/use_cases.md +++ b/docs/protocol/api/use_cases.md @@ -316,8 +316,7 @@ Some governance processes should remain confidential until execution. With event

###### Register Event Trigger - - Define an ETD using the DAO contract address and event signature, with the option to filter by `proposalId`. - - Set the TTL to match the voting window. + - Define an ETD using the DAO contract address and event signature, with the option to filter by `proposalId` (**register via `/register_event_identity`**). ###### Commit - Encrypt the vote or supporting document and submit. @@ -420,8 +419,7 @@ In an auction contract that utilizes event-based triggers, it is the contract it

###### Register Event Trigger - - The ETD includes the auction contract address along with the `AuctionClosed` topic. - - Optional filters for `auctionId`. + - The ETD includes the auction contract address along with the `AuctionClosed` topic. Optional filters for `auctionId` (**register via `/register_event_identity`**). ###### Commit Bids - Participants encrypt their bids and submit them during the designated time window. @@ -437,10 +435,6 @@ In an auction contract that utilizes event-based triggers, it is the contract it - **Treasury sales** that include a verified closing. - **On-chain auctions in the style of Christie's** that prevent pre-reveal leaks. -Now as you can see from the page I just provided to you (and of course you should have already spotted this earlier when I was asking you to make your edits similar to the previous entries), all the old, time-based, entries have an "Example" section, but these are missing from the event-based entries that you came up with. - -Please now create two options for an example for the "Event-Triggered Auction Settlement Reveal" entry. Here is an example of how to do it from the older content, the example for the "Shielded Voting" entry. I expect the same format, length, details and style for all the examples that I'm asking you to provide to me. Please give your reply completely in rich text format only. - ##### Example

@@ -451,6 +445,16 @@ Please now create two options for an example for the "Event-Triggered Auction Se

+##### Example + +

+ ###### The Sealed Bids and the Clockwork Bell + Picture a hall where bidders place sealed notes into a locked chest beside the auction lot. A clockwork bell is wired to the auction contract itself; when the sale officially ends, the bell strikes. Until then, the chest is visible but impossible to open—no curator, no guard, no VIP can peek inside. + + On-chain, that bell strike is the AuctionClosed event. You register its observation as the trigger (via /register_event_identity), bidders commit encrypted offers during the window, and when the event fires, Keypers publish the decryption key. All notes are read at once, the highest valid offer wins, and there was never a chance for early leaks, last-second sniping, or backroom reveals. +

+ + ___ > ### Gaming @@ -506,7 +510,7 @@ This structure removes turn-based bias, prevents unfair move selection, and ensu - Ensures that combat actions remain hidden until all players have locked in their choices. - Prevents last-minute strategic counterpicking of moves. - **Hidden Role & Social Deduction Games (Mafia, Werewolf, Daoplomacy)** - - Keeps player roles and actions hidden until the correct moment. + - Keeps player roles and actions hidden until the reveal phase. - Prevents bias or leaks that could ruin the secrecy of the game. - **Tournaments & Competitive Matchmaking** - Ensures that players submit their game choices (e.g., characters, weapons, skills) without pre-revealing them. @@ -609,133 +613,6 @@ This method prevents pre-reveal move sniping, ensures unpredictable randomness,

-#### Parimutuel Betting -##### Fair & Manipulation-Resistant Wagering -Parimutuel betting is a popular system used in horse racing, sports betting, and prediction markets. In this system, all bets are combined into a pool, and the winnings are distributed based on the total amount wagered. Unlike fixed-odds betting, where payouts are predetermined, parimutuel odds fluctuate dynamically according to the bets placed. However, this system can be susceptible to strategic manipulation and insider exploitation. - -:::warning[Common problems in traditional parimutuel betting] -- **Late-Stage Betting Exploits** - - Players wait until the last moment to place bets, adjusting based on the current odds. -- **Odds Manipulation** - - Early bettors can strategically place large bets to shift the odds in their favor. -- **Insider Advantage** - - Market operators or validators may see bets before they are finalized, allowing them to adjust their positions accordingly. -::: - -:::tip[With Shutter API's encrypted parimutuel betting, bets remain completely hidden until the pool closes] -- No one can adjust their bets based on the current odds. -- Bets are only revealed after the betting window closes, ensuring fairness. -- The final odds reflect true market sentiment, free from last-minute manipulation. -::: - -Consider this system as if you are placing your bet in a sealed envelope—no one can see how much you've wagered until all envelopes are opened simultaneously, ensuring that no one can manipulate the odds before the final reveal. - -##### Transaction Flow Overview -Parimutuel betting with Shutter API's commit-reveal encryption ensures that wagers remain confidential until the betting period ends. - - -

- ###### Commitment Phase (Bet Placement) - - Players encrypt their bets before submitting them to the betting smart contract. - - The encrypted bet is stored on-chain but remains unreadable to all other players, validators, and the market operator. - ###### Waiting Period (Betting Pool Open) - - Players can see the total number of participants but not the individual bets. - - No one can adjust their wagers based on others' betting patterns. - ###### Reveal Phase (Pool Closure & Odds Calculation) - - When the betting window closes, the decryption key is released by Shutter's distributed Keyper network. - - All bets are revealed simultaneously, and final odds are calculated based on total wagers in the pool. - - The winnings are distributed fairly, based on the final odds. -

- - -This method prevents last-minute betting exploits, guarantees privacy, and ensures that no player can manipulate the market before the final odds are locked in. - -##### Real-World Applications of Parimutuel Betting -- **Horse Racing & Traditional Sports Betting** - - Ensures fair parimutuel odds without last-minute betting exploits. - - Prevents sportsbooks from adjusting odds based on insider knowledge. -- **Decentralized Prediction Markets** - - Keeps market participants' wagers hidden until the event concludes. - - Ensures manipulation-free forecasting in political and financial markets. -- **Crypto & NFT Betting Pools** - - Allows users to place bets on NFT rarities or token price movements without others seeing their predictions. - - Prevents whales from manipulating outcomes by front-loading bets. -- **On-Chain Fantasy Sports & eSports Betting** - - Guarantees that no one can adjust their fantasy league wagers based on early game results. - - Keeps betting odds stable until all positions are locked in. -- **Yield-Based Betting & DeFi Risk Pools** - - Used in DeFi insurance pools, where participants bet on protocol risks or security events. - - Ensures fair distribution of payouts based on final pool outcomes. - -##### Example - -

- ###### A Blindfolded Auction for Betting - Imagine a group of friends betting on a mystery box auction, where the final price is determined by the total amount wagered. If they could see each other's bids before submitting their own, they might: - - Adjust their bets to manipulate the final price. - - Wait until the last second to place their wager, ensuring they get the best possible deal. - - Use insider knowledge to game the system. - - Now, imagine instead: - - All bets are placed inside locked boxes and submitted without revealing the amounts. - - When the betting period ends, all boxes are opened at the same time, and the final price is determined fairly. - - No one knew what others were betting, so the final result was free from manipulation. - - This is exactly how Shutter API's Parimutuel Betting system works—bets remain hidden until the pool closes, ensuring fair odds and trust-minimized betting outcomes. -

- - -#### Randomness Generation -##### Threshold-Generated Randomness for Games and Protocols -Randomness plays a critical role in gaming, lotteries, NFT mints, and many on-chain applications where fairness and unpredictability are essential. However, generating reliable randomness on a public blockchain is notoriously difficult due to its transparent and deterministic nature. Traditional approaches, such as relying on block hashes or centralized oracles, introduce vulnerabilities and trust assumptions. - -Shutter API offers a unique solution: it provides access to random values generated directly through the threshold decryption process by a decentralized network of Keypers. These values can be accessed via API calls and used as a reliable randomness source in any off-chain or on-chain application. - -This randomness is not derived from encrypting a pre-defined value and later decrypting it—instead, the decryption key itself (produced as part of Shutter’s distributed key generation) serves as the source of randomness. Because the key is generated collaboratively through a secure threshold process, it is unpredictable, unbiased, and cannot be influenced by any single actor. - -##### Transaction Flow Overview -The Shutter API enables access to trust-minimized randomness by exposing the randomness inherent in its threshold key generation process. - - -

- ###### Identity Registration (Randomness Setup) - - A developer registers a new encryption identity with a decryption trigger condition (e.g. a future timestamp or event). - ###### Wait for Decryption (Key Generation by Keypers) - - The network of Keypers collaborates to compute a threshold decryption key. Until the condition is met, the key—and thus the randomness—is not available to anyone. - ###### Randomness Retrieval (Reveal Phase) - - Once the trigger condition is satisfied, the Keypers publish the decryption key associated with the identity. - - This decryption key itself is used as the random value, which can be consumed by applications to drive logic in games, draws, lotteries, and more. -

- - -Importantly, the randomness is not user-supplied or application-specific, making it tamper-resistant and suitable for a wide range of verifiable use cases. - -##### Real-World Applications of Randomness Generation -- **Provably Fair Blockchain Games** - - Use random values to resolve outcomes such as dice rolls, loot drops, monster spawns, or card shuffles—without giving validators or players the chance to manipulate the result. -- **NFT Minting and Trait Assignment** - - Assign rarities and attributes to NFTs using unbiased randomness. Prevents early insiders from predicting or gaming the minting process. -- **Prize Draws, Lotteries, and Raffles** - - Run secure giveaways where winners are selected based on a truly unpredictable value, with public verifiability. -- **DAO Governance and Random Selection** - - Select random committee members, grant reviewers, or jurors in decentralized governance processes. -- **Randomized Event Triggers in Smart Contracts** - - Trigger in-game or protocol-level events at unpredictable times to keep user interactions dynamic and trustless. -- **Betting Games and Gambling dApps** - - Use random outcomes to determine winners in parimutuel pools, roulette-style games, or dice games, ensuring fairness across participants. - -##### Example - -

- ###### The Dice Roll That No One Can Rig - Imagine a turn-based strategy game where players roll a die to determine how many spaces they can move. If the die roll is public or predictable, a savvy player might time their actions or manipulate the outcome in their favor. - - Now consider a die that is rolled in secret by a neutral, trusted group, and the result is only revealed once it's time to act. No one can influence or predict it—players commit to their strategies blind, and only after that is the die roll shown. - - This is what Shutter’s randomness generation achieves. The randomness comes from the threshold-generated decryption key, created by a decentralized set of Keypers. No participant or developer can bias it. It’s just fair randomness—generated collaboratively, revealed at the right time. -

- - #### Event-Triggered Game Round Completion ##### Reveal Moves When the Game Emits RoundComplete @@ -745,7 +622,7 @@ Utilize an ETD synchronized with `RoundComplete` for reveals to occur precisely

###### Register Event Trigger - - The ETD includes the game contract and the `RoundComplete` topic, and it may optionally include `roundId`. + - The ETD includes the game contract and the `RoundComplete` topic, and it may optionally include `roundId` (**register via `/register_event_identity`**). ###### Commit - Players encrypt their moves for the round and then submit them. @@ -779,7 +656,7 @@ Keep NFT visuals or traits hidden until a player accomplishes something that the

###### Register Event Trigger - - The ETD corresponds to events such as `LevelUp`, `CompletedQuest`, or similar occurrences for the player. + - The ETD corresponds to events such as `LevelUp`, `CompletedQuest`, or similar occurrences for the player (**register via `/register_event_identity`**). ###### Commit - The sensitive metadata or artwork associated with the NFT remains encrypted. @@ -953,8 +830,7 @@ Restrict access to content based on an on-chain payment detected by an ETD, such

###### Register Event Trigger - - The ETD includes the token contract address and the `Transfer` topic. - - Ensure that the match for `to` is equal to `creator` and that the `value` is greater than or equal to `price`. + - The ETD includes the token contract address and the `Transfer` topic. Ensure that the match for `to` is equal to `creator` and that the `value` is greater than or equal to `price` (**register via `/register_event_identity`**). ###### Commit - Encrypt the content key or payload associated with the buyer's identity. @@ -991,7 +867,7 @@ Decrypt new session keys only after a `SubscriptionPaid` event or staking renewa

###### Register Event Trigger - - The ETD corresponds with the membership contract event and the subscriber's address. + - The ETD corresponds with the membership contract event and the subscriber's address (**register via `/register_event_identity`**). ###### Commit - The materials for the next period are still encrypted and cannot be accessed. @@ -1025,7 +901,7 @@ Release an activation key when the `LicenseMinted` event or similar events are e

###### Register Event Trigger - - The ETD corresponds to the minting event and the buyer's address. + - The ETD corresponds to the minting event and the buyer's address (**register via `/register_event_identity`**). ###### Commit - The encrypted license or API key has been prepared for the buyer. @@ -1059,7 +935,7 @@ Disclose confidential documents when the `PaymentReleased` or `DealCompleted` ev

###### Register Event Trigger - - ETD focuses on events related to the settlement of escrow contracts. + - ETD focuses on events related to the settlement of escrow contracts (**register via `/register_event_identity`**). ###### Commit - Encrypt deliverables or intellectual property for the buyer's identity. @@ -1093,7 +969,7 @@ Require a multisig approval before revealing content, using events like `Executi

###### Register Event Trigger - - The ETD corresponds to the multisig execution event and the optional calldata hash. + - The ETD corresponds to the multisig execution event and the optional calldata hash (**register via `/register_event_identity`**). ###### Commit - Securely encrypt any shared documents or memos related to the action. @@ -1207,7 +1083,7 @@ Utilize oracle events, like `AnswerUpdated`, to initiate the decryption of forec

###### Register Event Trigger - - ETD refers to the oracle contract and event, and it may include optional filters for feed or round. + - ETD refers to the oracle contract and event, and it may include optional filters for feed or round (**register via `/register_event_identity`**). ###### Commit - Encrypt forecasts or settlement instructions. @@ -1241,7 +1117,7 @@ When a claim oracle emits the event `ClaimEvent(policyId, verified=true)`, it in

###### Register Event Trigger - - The ETD corresponds to the insurance oracle event and the `policyId`. + - The ETD corresponds to the insurance oracle event and the `policyId` (**register via `/register_event_identity`**). ###### Commit - Encrypt claim details for the beneficiary identity. @@ -1427,7 +1303,7 @@ Decrypt the roadmaps or the reward details when the campaign contract emits the

###### Register Event Trigger - - ETD focuses on the campaign contract and the goal event. + - ETD focuses on the campaign contract and the goal event (**register via `/register_event_identity`**). ###### Commit - Encrypt milestone materials for backers. @@ -1461,7 +1337,7 @@ Disclose a secret once N participants have either made a deposit or expressed in

###### Register Event Trigger - - The ETD matches the pool contract with the threshold event. + - The ETD matches the pool contract with the threshold event (**register via `/register_event_identity`**). ###### Commit - Encrypt the shared secret or content. @@ -1495,7 +1371,7 @@ Decrypt the per-user claim proofs whenever the `RewardClaimed` or `StakeComplete

###### Register Event Trigger - - ETD filters by user and action event. + - ETD filters by user and action event (**register via `/register_event_identity`**). ###### Commit - Encrypt claim proofs or reward data. From b6937040a538da4a435b88d9125c443e33022f5a Mon Sep 17 00:00:00 2001 From: "Smokyish@github.com" Date: Tue, 21 Oct 2025 15:35:34 +0300 Subject: [PATCH 2/2] Add missing content to Use Cases --- docs/protocol/api/use_cases.md | 137 ++++++++++++++++++++++++++++++--- 1 file changed, 127 insertions(+), 10 deletions(-) diff --git a/docs/protocol/api/use_cases.md b/docs/protocol/api/use_cases.md index c66b153..e641a8c 100644 --- a/docs/protocol/api/use_cases.md +++ b/docs/protocol/api/use_cases.md @@ -445,16 +445,6 @@ In an auction contract that utilizes event-based triggers, it is the contract it

-##### Example - -

- ###### The Sealed Bids and the Clockwork Bell - Picture a hall where bidders place sealed notes into a locked chest beside the auction lot. A clockwork bell is wired to the auction contract itself; when the sale officially ends, the bell strikes. Until then, the chest is visible but impossible to open—no curator, no guard, no VIP can peek inside. - - On-chain, that bell strike is the AuctionClosed event. You register its observation as the trigger (via /register_event_identity), bidders commit encrypted offers during the window, and when the event fires, Keypers publish the decryption key. All notes are read at once, the highest valid offer wins, and there was never a chance for early leaks, last-second sniping, or backroom reveals. -

- - ___ > ### Gaming @@ -613,6 +603,133 @@ This method prevents pre-reveal move sniping, ensures unpredictable randomness,

+#### Parimutuel Betting +##### Fair & Manipulation-Resistant Wagering +Parimutuel betting is a popular system used in horse racing, sports betting, and prediction markets. In this system, all bets are combined into a pool, and the winnings are distributed based on the total amount wagered. Unlike fixed-odds betting, where payouts are predetermined, parimutuel odds fluctuate dynamically according to the bets placed. However, this system can be susceptible to strategic manipulation and insider exploitation. + +:::warning[Common problems in traditional parimutuel betting] +- **Late-Stage Betting Exploits** + - Players wait until the last moment to place bets, adjusting based on the current odds. +- **Odds Manipulation** + - Early bettors can strategically place large bets to shift the odds in their favor. +- **Insider Advantage** + - Market operators or validators may see bets before they are finalized, allowing them to adjust their positions accordingly. +::: + +:::tip[With Shutter API's encrypted parimutuel betting, bets remain completely hidden until the pool closes] +- No one can adjust their bets based on the current odds. +- Bets are only revealed after the betting window closes, ensuring fairness. +- The final odds reflect true market sentiment, free from last-minute manipulation. +::: + +Consider this system as if you are placing your bet in a sealed envelope—no one can see how much you've wagered until all envelopes are opened simultaneously, ensuring that no one can manipulate the odds before the final reveal. + +##### Transaction Flow Overview +Parimutuel betting with Shutter API's commit-reveal encryption ensures that wagers remain confidential until the betting period ends. + + +

+ ###### Commitment Phase (Bet Placement) + - Players encrypt their bets before submitting them to the betting smart contract. + - The encrypted bet is stored on-chain but remains unreadable to all other players, validators, and the market operator. + ###### Waiting Period (Betting Pool Open) + - Players can see the total number of participants but not the individual bets. + - No one can adjust their wagers based on others' betting patterns. + ###### Reveal Phase (Pool Closure & Odds Calculation) + - When the betting window closes, the decryption key is released by Shutter's distributed Keyper network. + - All bets are revealed simultaneously, and final odds are calculated based on total wagers in the pool. + - The winnings are distributed fairly, based on the final odds. +

+ + +This method prevents last-minute betting exploits, guarantees privacy, and ensures that no player can manipulate the market before the final odds are locked in. + +##### Real-World Applications of Parimutuel Betting +- **Horse Racing & Traditional Sports Betting** + - Ensures fair parimutuel odds without last-minute betting exploits. + - Prevents sportsbooks from adjusting odds based on insider knowledge. +- **Decentralized Prediction Markets** + - Keeps market participants' wagers hidden until the event concludes. + - Ensures manipulation-free forecasting in political and financial markets. +- **Crypto & NFT Betting Pools** + - Allows users to place bets on NFT rarities or token price movements without others seeing their predictions. + - Prevents whales from manipulating outcomes by front-loading bets. +- **On-Chain Fantasy Sports & eSports Betting** + - Guarantees that no one can adjust their fantasy league wagers based on early game results. + - Keeps betting odds stable until all positions are locked in. +- **Yield-Based Betting & DeFi Risk Pools** + - Used in DeFi insurance pools, where participants bet on protocol risks or security events. + - Ensures fair distribution of payouts based on final pool outcomes. + +##### Example + +

+ ###### A Blindfolded Auction for Betting + Imagine a group of friends betting on a mystery box auction, where the final price is determined by the total amount wagered. If they could see each other's bids before submitting their own, they might: + - Adjust their bets to manipulate the final price. + - Wait until the last second to place their wager, ensuring they get the best possible deal. + - Use insider knowledge to game the system. + + Now, imagine instead: + - All bets are placed inside locked boxes and submitted without revealing the amounts. + - When the betting period ends, all boxes are opened at the same time, and the final price is determined fairly. + - No one knew what others were betting, so the final result was free from manipulation. + + This is exactly how Shutter API's Parimutuel Betting system works—bets remain hidden until the pool closes, ensuring fair odds and trust-minimized betting outcomes. +

+ + +#### Randomness Generation +##### Threshold-Generated Randomness for Games and Protocols +Randomness plays a critical role in gaming, lotteries, NFT mints, and many on-chain applications where fairness and unpredictability are essential. However, generating reliable randomness on a public blockchain is notoriously difficult due to its transparent and deterministic nature. Traditional approaches, such as relying on block hashes or centralized oracles, introduce vulnerabilities and trust assumptions. + +Shutter API offers a unique solution: it provides access to random values generated directly through the threshold decryption process by a decentralized network of Keypers. These values can be accessed via API calls and used as a reliable randomness source in any off-chain or on-chain application. + +This randomness is not derived from encrypting a pre-defined value and later decrypting it—instead, the decryption key itself (produced as part of Shutter’s distributed key generation) serves as the source of randomness. Because the key is generated collaboratively through a secure threshold process, it is unpredictable, unbiased, and cannot be influenced by any single actor. + +##### Transaction Flow Overview +The Shutter API enables access to trust-minimized randomness by exposing the randomness inherent in its threshold key generation process. + + +

+ ###### Identity Registration (Randomness Setup) + - A developer registers a new encryption identity with a decryption trigger condition (e.g. a future timestamp or event). + ###### Wait for Decryption (Key Generation by Keypers) + - The network of Keypers collaborates to compute a threshold decryption key. Until the condition is met, the key—and thus the randomness—is not available to anyone. + ###### Randomness Retrieval (Reveal Phase) + - Once the trigger condition is satisfied, the Keypers publish the decryption key associated with the identity. + - This decryption key itself is used as the random value, which can be consumed by applications to drive logic in games, draws, lotteries, and more. +

+ + +Importantly, the randomness is not user-supplied or application-specific, making it tamper-resistant and suitable for a wide range of verifiable use cases. + +##### Real-World Applications of Randomness Generation +- **Provably Fair Blockchain Games** + - Use random values to resolve outcomes such as dice rolls, loot drops, monster spawns, or card shuffles—without giving validators or players the chance to manipulate the result. +- **NFT Minting and Trait Assignment** + - Assign rarities and attributes to NFTs using unbiased randomness. Prevents early insiders from predicting or gaming the minting process. +- **Prize Draws, Lotteries, and Raffles** + - Run secure giveaways where winners are selected based on a truly unpredictable value, with public verifiability. +- **DAO Governance and Random Selection** + - Select random committee members, grant reviewers, or jurors in decentralized governance processes. +- **Randomized Event Triggers in Smart Contracts** + - Trigger in-game or protocol-level events at unpredictable times to keep user interactions dynamic and trustless. +- **Betting Games and Gambling dApps** + - Use random outcomes to determine winners in parimutuel pools, roulette-style games, or dice games, ensuring fairness across participants. + +##### Example + +

+ ###### The Dice Roll That No One Can Rig + Imagine a turn-based strategy game where players roll a die to determine how many spaces they can move. If the die roll is public or predictable, a savvy player might time their actions or manipulate the outcome in their favor. + + Now consider a die that is rolled in secret by a neutral, trusted group, and the result is only revealed once it's time to act. No one can influence or predict it—players commit to their strategies blind, and only after that is the die roll shown. + + This is what Shutter’s randomness generation achieves. The randomness comes from the threshold-generated decryption key, created by a decentralized set of Keypers. No participant or developer can bias it. It’s just fair randomness—generated collaboratively, revealed at the right time. +

+ + #### Event-Triggered Game Round Completion ##### Reveal Moves When the Game Emits RoundComplete