面向dApp开发者的Shutter API文档

面向 dApp 开发者的 Shutter API 文档

免责声明

此软件正处于开发的早期阶段。强烈建议用户谨慎行事，在进一步成熟和去中心化之前，不要将任何高价值的资产或敏感信息委托给此 API。

请注意，所有阈值密码学系统和多方计算 (MPC) 框架本质上都依赖于阈值信任假设。虽然 Shutter API 目前使用一组去中心化的 keyper，但该网络目前尚未完全去中心化。我们预计很快会有更多的 keyper 加入并增强网络的弹性。

本项目以开源形式发布，并按“原样”提供，不提供任何明示或暗示的保证。对于因使用或误用此 API 而引起的任何问题、损失或损害，开发者和贡献者不承担任何责任。使用风险自负。

欢迎来到 Shutter API 文档！

本指南将帮助你将 Shutter 的 Commit and Reveal Scheme 集成到你的去中心化应用程序 (dApp) 中。Shutter 系统提供安全、去中心化和防篡改的 commit-and-reveal 工作流程，确保你应用程序的完整性和机密性。

目录

1. 概述
2. 先决条件
3. 端点
   • 使用解密触发器注册身份
   • 检索加密数据
   • 检索解密密钥
   • 解密承诺
4. 未来功能
5. 常见问题解答
6. Swagger 文档
7. 支持

概述

Shutter 系统利用阈值加密、分布式密码学操作和去中心化基础设施来安全地处理承诺。核心组件包括：

• Registry Contract: 一个链上合约，客户端可以在其中注册身份并指定基于时间的解密触发器。
• Keypers: 一组分布式节点，用于监控注册合约、处理诸如分布式密钥生成之类的密码学操作，并安全地发布解密密钥。
• API: 一个 API，通过暴露用于加密和解密操作的端点来简化与 Shutter 系统的交互。

本文档将指导你完成以下操作：

• 设置身份和基于时间的解密触发器。
• 检索加密数据和解密密钥。
• 解密加密的承诺。

先决条件

• API 访问: 目前，访问是免费的，但 Gnosis Mainnet 有速率限制。你只需要在以下地址查询 API 端点：

  • Chiado: https://shutter-api.chiado.staging.shutter.network/api/[ADD_ENDPOINT]
  • Mainnet: https://shutter-api.shutter.network/api/[ADD_ENDPOINT]

• Shutter Registry Contract 的地址:

  • Chiado 地址: 0x2693a4Fb363AdD4356e6b80Ac5A27fF05FeA6D9F
  • Gnosis 地址: 0x694e5de9345d39C148DA90e6939A3fd2142267D9

• API 的地址:

  • Chiado 地址: 0xb9C303443c9af84777e60D5C987AbF0c43844918
  • Gnosis 地址: 0x228DefCF37Da29475F0EE2B9E4dfAeDc3b0746bc

速率限制 / 授权

对于未经授权的访问，Gnosis Mainnet 上的 API 受到速率限制，每个端点和远程 ip 都有以下限制：

• /register_identity 每 24 小时 5 个请求
• /get_data_for_encryption 每 24 小时 10 个请求
• /get_decryption_key 每 24 小时 20 个请求
• /decrypt_commitment 每 24 小时 10 个请求

我们建议使用 Chiado 进行开发，因为它没有速率限制。

如果你需要更高的限制，请联系 loring@brainbot.com 以申请 API 密钥。

授权请求有以下限制：

• /register_identity 每 24 小时 500 个请求
• /get_data_for_encryption 每 24 小时 1000 个请求
• /get_decryption_key 每 24 小时 2000 个请求
• /decrypt_commitment 每 24 小时 1000 个请求

授权通过在使用 API 时使用 Authorization: Bearer $API_KEY 标头来完成。

使用 /check_authentication 端点来测试你的 API 密钥。

端点

1. 使用解密触发器注册身份

要开始使用 Shutter 系统，请注册一个身份并指定一个基于时间的解密触发器。此步骤将身份链接到解密密钥，并将密钥的发布条件设置为 Unix 时间戳。

有关参数和响应的详细信息，请参阅 Swagger 文档中的 /register_identity 端点。

注意: 通过我们的 API 注册身份时，API 帐户地址用于计算将返回的身份。如果你想使用自己的地址，则需要将注册直接提交到注册合约。合约的定义可以在这里找到： ShutterRegistry.sol.

Example Request

curl -X POST https://<API_BASE_URL>/register_identity \
-H "Content-Type: application/json" \
-d '{
  "decryptionTimestamp": 1735044061,
  "identityPrefix": "0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0"
}'

Example Response

{
  "eon": 1,
  "eon_key": "0x57af5437a84ef50e5ed75772c18ae38b168bb07c50cadb65fc6136604e662255",
  "identity": "0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75",
  "identity_prefix": "0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0",
  "tx_hash": "0x3026ad202ca611551377eef069fb6ed894eae65329ce73c56f300129694f12ba"
}

2. 检索加密数据

要加密承诺，请获取与你的身份关联的加密数据。使用 /get_data_for_encryption 端点检索所有必要的加密数据。

有关此端点的详细信息，请参阅 Swagger 文档。

Example Request

curl -X GET "https://<API_BASE_URL>/get_data_for_encryption?address=0xb9C303443c9af84777e60D5C987AbF0c43844918&identityPrefix=0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0"

Example Response

{
"eon": 1,
"eon_key": "0x57af5437a84ef50e5ed75772c18ae38b168bb07c50cadb65fc6136604e662255",
"identity": "0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75",
"identity_prefix": "0x79bc8f6b4fcb02c651d6a702b7ad965c7fca19e94a9646d21ae90c8b54c030a0",
"epoch_id": "0x88f2495d1240f9c5523db589996a50a4984ee7a08a8a8f4b269e4345b383310abd2dc1cd9c9c2b8718ed3f486d5242f5"
}

在 Go 中加密承诺

以下 Go 代码演示了如何使用从 Shutter API 检索的加密数据来加密承诺：

// NOTE: This example requires the "github.com/shutter-network/shutter/shlib/shcrypto" package.
// Make sure to install it in your Go environment before running this code.
package main

import (
  "crypto/rand"
  "encoding/hex"
  "fmt"
  "log"
  "strings"

  "github.com/shutter-network/shutter/shlib/shcrypto"
)

func main() {
  // Encryption data provided by the Shutter API
  identityHex := "0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75"
  eonPublicKeyHex := "0x57af5437a84ef50e5ed75772c18ae38b168bb07c50cadb65fc6136604e662255"
  message := []byte("please hide this message")

  identityHex = strings.TrimPrefix(identityHex, "0x")
  eonPublicKeyHex = strings.TrimPrefix(eonPublicKeyHex, "0x")

  // Convert hex strings to bytes
  identity, err := hex.DecodeString(identityHex)
  if err != nil {
    log.Fatalf("Failed to decode identity: %v", err)
  }

  eonPublicKeyBytes, err := hex.DecodeString(eonPublicKeyHex)
  if err != nil {
    log.Fatalf("Failed to decode eon public key: %v", err)
  }

  // Create EonPublicKey struct from bytes
  eonPublicKey := &shcrypto.EonPublicKey{}
  if err := eonPublicKey.Unmarshal(eonPublicKeyBytes); err != nil {
    log.Fatalf("Failed to unmarshal EonPublicKey: %v", err)
  }

  // Compute the Epoch ID from the identity
  epochID := shcrypto.ComputeEpochID(identity)

  // Generate a random sigma
  sigma, err := shcrypto.RandomSigma(rand.Reader)
  if err != nil {
    log.Fatalf("Failed to generate random sigma: %v", err)
  }

  // Encrypt the message
  encryptedCommitment := shcrypto.Encrypt(message, eonPublicKey, epochID, sigma)

  // Marshal the encrypted commitment into bytes
  encryptedCommitmentBytes := encryptedCommitment.Marshal()

  // Convert to hex string
  encryptedCommitmentHex := "0x" + hex.EncodeToString(encryptedCommitmentBytes)

  // Print the encrypted commitment
  fmt.Printf("Encrypted Commitment: %s\n", encryptedCommitmentHex)
}

在 TypeScript 中加密承诺

你也可以使用我们的 Shutter TypeScript SDK 轻松地加密承诺：

import { encryptData } from "@shutter-network/shutter-sdk";
import { stringToHex } from "viem";

// Encryption data provided by the Shutter API
const eonKeyHex = "0x57af5437a84ef50e5ed75772c18ae38b168bb07c50cadb65fc6136604e662255";
const identityPreimageHex = "0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75";
const msgHex = stringToHex("please hide this message")

// some random sigma
const sigmaHex = "0x312c10b186086d502ba683cffc2ae650d53b508904b3c430df8e7d5aa336c0f5";

// Encrypt the message
const encryptedCommitment = await encryptData(message, eonPublicKey, identityPreimageHex, sigma);
// Print the encrypted commitment
console.log("Encrypted Commitment:", encryptedCommitment);

3. 检索解密密钥

在满足解密触发条件（即，指定的的时间戳已过）后，使用 /get_decryption_key 端点检索解密密钥。

有关详细用法，请参阅 Swagger 文档。

Example Request

curl -X GET "https://<API_BASE_URL>/get_decryption_key?identity=0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75"

Example Response

{
  "decryption_key": "0x99a805fc26812c13041126b25e91eccf3de464d1df7a95d1edca8831a9ec02dd",
  "decryption_timestamp": 1735044061,
  "identity": "0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75"
}

4. 解密承诺

获得解密密钥后，使用它来解密使用 Shutter 系统加密的承诺。/decrypt_commitment 端点启用此过程。

有关端点详细信息，请参阅 Swagger 文档。

Example Request

curl -X GET "https://<API_BASE_URL>/decrypt_commitment?identity=0x8c232eae4f957259e9d6b68301d529e9851b8642874c8f59d2bd0fb84a570c75&encryptedCommitment=0x03b5685a460a95ba628e04b24155d6722f7c4e376a1627f714a4ae9cecd2982e005eff12ac8150b8842c29f8d5eaf4d0da0b626f762b4826d779d8969b577acb28df96cab026aa57c00cd74b07ca51e8c0c1a59933e29a728311900ebfc26c6804260914c96cb10dbd6d2ed3f6cb77788a74b5aae5f4ce6f40be53310a0524d42d5a6f03b5c1517ec097553733e228276fcdfc4b569f7ef4311a461d68819d634c"

Example Response

{
  "decrypted_message": "0x706c6561736520686964652074686973206d657373616765"
}

解密后的消息以十六进制格式返回。要获取初始消息，请将解密后的消息转换为字符串。

注意: 将所有示例请求中的 <API_BASE_URL> 替换为 API 的实际基本 URL，该 URL 位于先决条件部分中，例如 https://shutter-api.shutter.network/api。

未来功能

• 基于事件和基于区块的触发器 未来版本的 Shutter 系统将支持基于事件和基于区块的解密触发器，以增强功能。

• 实时通知 计划的更新包括基于 WebSocket 的实时密钥发布通知，从而改善用户体验和交互性。

常见问题解答

如果 keyper 遇到停机时间会发生什么？

Keyper 集旨在优雅地处理停机时间。任何错过的解密密钥发布都会在恢复后发送。

Shutter 系统的安全性如何？

Shutter 系统使用阈值加密和分布式密码学操作来确保没有单个实体可以危及承诺的安全性。

Swagger 文档

有关详细的 API 规范，包括参数、响应和错误代码，请访问 Swagger 文档：

• Chiado Swagger 文档
• Mainnet Swagger 文档

支持

如需其他支持或咨询：

• 联系 Shutter 开发团队。
• 在我们的 GitHub 存储库上打开一个 issue。

感谢你使用 Shutter！ 让我们一起构建一个更安全和去中心化的未来。

• 原文链接： github.com/shutter-netwo...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～