Stellar 集成 - OpenZeppelin 文档

Stellar 集成

概述

OpenZeppelin Relayer 提供对 Stellar 网络的全面支持，从而实现安全交易中继、Soroban 智能合约操作和高级交易管理。此集成支持标准 Stellar 操作和最新的 Soroban 智能合约功能。

特性

• 完整的 Soroban 智能合约支持（调用、部署、WASM 上传）

• 标准 Stellar 支付操作

• 通过 XDR 交易提交支持所有 Stellar 操作

• 手续费补贴（Fee bump）交易支持

• 使用多个签名者后端安全交易签名

• 交易状态监控和序列号管理

• 自定义 RPC 端点和网络策略

• 指标和可观察性

支持的网络

Stellar 网络通过 JSON 配置文件定义，从而可以灵活地：

• 配置标准 Stellar 集群：mainnet、testnet

• 使用特定的 RPC 端点设置自定义的 Stellar 兼容网络

• 定义网络口令以进行正确的交易签名

Stellar 网络配置示例：

{
  "networks": [\
    {\
      "type": "stellar",\
      "network": "mainnet",\
      "rpc_urls": ["https://mainnet.sorobanrpc.com"],\
      "explorer_urls": ["https://stellar.expert/explorer/public"],\
      "average_blocktime_ms": 5000,\
      "is_testnet": false,\
      "passphrase": "Public Global Stellar Network ; September 2015"\
    },\
    {\
      "type": "stellar",\
      "network": "testnet",\
      "rpc_urls": ["https://soroban-testnet.stellar.org"],\
      "explorer_urls": ["https://stellar.expert/explorer/testnet"],\
      "average_blocktime_ms": 5000,\
      "is_testnet": true,\
      "passphrase": "Test SDF Network ; September 2015"\
    }\
  ]
}

有关详细的网络配置选项，请参阅网络配置指南。

快速入门

有关分步设置，请参阅快速入门指南。 主要先决条件：

• Rust 2021，版本 1.86 或更高版本

• Redis

• Docker（可选）

Stellar 中继器配置示例：

{
  "id": "stellar-example",
  "name": "Stellar Example",
  "network": "testnet",
  "paused": false,
  "notification_id": "notification-example",
  "signer_id": "local-signer",
  "network_type": "stellar"
}

有关更多配置示例，请访问 OpenZeppelin Relayer 示例存储库。

配置

中继器策略

Stellar 中继器支持标准中继器配置选项。在 用户文档 - 中继器 中查看所有选项。

API 参考

交易操作

Stellar API 支持各种交易操作：

支持的操作类型

交易结构

必需字段： - network: Stellar 网络（“testnet”、“mainnet”等） - operations（操作数组）或 transaction_xdr（base64 编码的 XDR）二选一 - 但不能同时存在

可选字段： - source_account: 将作为交易来源的 Stellar 账户（默认为中继器的地址） - memo: 交易备注（请参阅下面的备注类型） - valid_until: 交易过期时间（ISO 8601 格式） - transaction_xdr: 预构建的交易 XDR（base64 编码，已签名或未签名）- 与 operations 互斥 - fee_bump: 请求手续费补贴包装器的布尔标志（仅对已签名的 transaction_xdr 有效） - max_fee: 手续费补贴交易的最高费用，以 stroops 为单位（默认为 1,000,000 = 0.1 XLM）

交易输入方法

中继器支持三种提交交易的方式：

1. 基于操作: 通过指定 operations 数组来构建交易（推荐用于大多数用例）

2. Transaction XDR（未签名）: 使用 transaction_xdr 字段提交预构建的未签名交易（高级用例）

3. Transaction XDR（已签名）带有手续费补贴: 使用 transaction_xdr 提交已签名交易，并使用 fee_bump: true 将其包装在手续费补贴交易中

示例：发送交易

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [\
    {\
      "type": "payment",\
      "destination": "GD77B6LYQ5XDCW6CND7CQMA23FSV7MZQGLBAU5OMEOXQM6XFTCMWQQCJ",\
      "asset": {"type": "native"},\
      "amount": 1000000\
    }\
  ],
  "memo": {"type": "text", "value": "Payment for services"}
}'

有关完整详细信息和示例，请参阅 API 参考。

资产类型

Stellar 操作中的资产必须使用类型字段指定：

原生 XLM：

{"type": "native"}

信用资产（4 个字符或更少）：

{
  "type": "credit_alphanum4",
  "code": "USDC",
  "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

信用资产（5-12 个字符）：

{
  "type": "credit_alphanum12",
  "code": "LONGASSET",
  "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

备注类型

交易可以包含可选备注：

• 无备注: {"type": "none"}

• 文本备注: {"type": "text", "value": "Payment for services"}（最多 28 个 UTF-8 字节）

• ID 备注: {"type": "id", "value": "12345"}

• 哈希备注: {"type": "hash", "value": "deadbeef…​"}（32 字节十六进制）

• 返回备注: {"type": "return", "value": "deadbeef…​"}（32 字节十六进制）

Soroban 合约操作

调用合约

调用已部署的 Soroban 智能合约：

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [\
    {\
      "type": "invoke_contract",\
      "contract_address": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUWDA",\
      "function_name": "transfer",\
      "args": [\
        {"address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"},\
        {"address": "GD77B6LYQ5XDCW6CND7CQMA23FSV7MZQGLBAU5OMEOXQM6XFTCMWQQCJ"},\
        {"i128": {"hi": "0", "lo": "1000000"}}\
      ],\
      "auth": {"type": "source_account"}\
    }\
  ]
}'

创建合约

部署新的 Soroban 智能合约：

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [\
    {\
      "type": "create_contract",\
      "source": {\
        "from": "address",\
        "address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"\
      },\
      "wasm_hash": "d3b2f6f8a1c5e9b4a7d8c2e1f5a9b3c6e8d4f7a2b5c8e1d4f7a0b3c6e9d2f5a8",\
      "salt": "0000000000000000000000000000000000000000000000000000000000000001"\
    }\
  ]
}'

上传 WASM

将合约代码上传到 Stellar 分类账：

curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "operations": [\
    {\
      "type": "upload_wasm",\
      "wasm": {\
        "type": "base64",\
        "base64": "AGFzbQEAAAABBgFgAX8BfwMCAQAFAwEAAQcPAgVoZWxsbwAACG1lbW9yeTIDCgQAAAAL"\
      }\
    }\
  ]
}'

ScVal 参数格式

调用合约函数时，必须以 JSON 格式提供作为 ScVal 值的参数：

还支持使用多部分表示形式的其他类型，如 U128、I128、U256 和 I256。

授权模式

Soroban 操作支持不同的授权模式：

安全

• 不要将中继器直接暴露于公共互联网

• 部署在安全后端（反向代理、防火墙）之后

• 在生产系统中使用托管签名者

• 确保为交易签名配置了正确的网络口令

故障排除

• 检查环境变量和配置文件是否存在错误

• 验证网络口令是否与目标网络匹配

• 查看容器日志以查找 Stellar 特定的错误

• 确保为合约操作正确配置了 Soroban RPC 端点

路线图

• 有关即将推出的功能，请参阅项目路线图

支持

如需帮助，请加入我们的 Telegram 或在 GitHub 上提出问题。

许可

本项目在 GNU Affero General Public License v3.0 许可下获得许可。

← Solana 集成

项目结构 →

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