API 参考 - OpenZeppelin 文档

OpenZeppelin
发布于 2025-05-20 23:39
阅读 168

本文档提供了关于已实现 API 的信息以及使用示例，包括 Solana、EVM 和 Stellar 的 REST 调用示例。

## API 参考

本文档提供了已实现的 API 的相关信息，以及用法示例。

### 前提条件

1. API 密钥
此密钥对于大多数 API 调用至关重要。可以在 `.env` 文件中的 `API_KEY` 变量下设置它。
如果密钥发生更改，则无需重建 Docker 镜像，因为 `docker compose` 会在下次启动容器时获取更改。

此密钥应作为标头发送到大多数 API 调用：

```json hljs
Authorization: Bearer <my api key>
```

### 请求格式

默认情况下，容器监听端口 `8080`。调用应遵循以下 URL：
`http://<server_address_or_IP>:8080/api/v1/relayers/<relayer_id>/rpc`

|     |     |
| --- | --- |
|  | `relayer_id` 是在 `./config/config.json` 文件中赋予中继器配置的名称。 |

### 环境

- Solana

- EVM

- Stellar

### API 参考

- [通用操作](https://docs.openzeppelin.com/relayer/1.0.x/api_reference#common_actions)

- [Solana](https://docs.openzeppelin.com/relayer/1.0.x/api_reference#solana_api)

- [EVM](https://docs.openzeppelin.com/relayer/1.0.x/api_reference#evm_api)

- [Stellar](https://docs.openzeppelin.com/relayer/1.0.x/api_reference#stellar_api)

#### 通用操作

这是一组 Solana 和 EVM 中继器通用的 REST 调用。

|     |     |
| --- | --- |
|  | 在这些示例中，我们假设基本 URL 为 `http://localhost:8080/`。 |

##### 列出中继器

请求：`GET http://localhost:8080/api/v1/relayers/`

示例请求：

```bash hljs
curl --location --request GET 'http://localhost:8080/api/v1/relayers/' \
--header 'Authorization: Bearer <my_api_key>'
```

示例响应：

```json hljs
{
    "success": true,
    "data": [\
        {\
            "id": "sepolia-example",\
            "name": "Sepolia Example",\
            "network": "sepolia",\
            "paused": false,\
            "network_type": "evm",\
            "signer_id": "local-signer",\
            "policies": {\
                "eip1559_pricing": false,\
                "private_transactions": false,\
                "min_balance": 1\
            },\
            "address": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",\
            "notification_id": "notification-example",\
            "system_disabled": false\
        }\
    ],
    "error": null,
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_items": 1
    }
}
```

##### 获取中继器详细信息

请求：`GET http://localhost:8080/api/v1/relayers/<relayer_id>;`

- 可以通过列出中继器或检查配置文件 ( `./config/config.json`) 来找到 `relayer_id`。

示例请求：

```bash hljs
curl --location --request GET 'http://localhost:8080/api/v1/relayers/<relayer_id>' \
--header 'Authorization: Bearer <my_api_key>'
```

示例响应：

```json hljs
{
    "success": true,
    "data": {
        "id": "sepolia-example",
        "name": "Sepolia Example",
        "network": "sepolia",
        "network_type": "evm",
        "paused": false,
        "policies": {
            "eip1559_pricing": false,
            "private_transactions": false,
            "min_balance": 1
        },
        "address": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "system_disabled": false
    },
    "error": null
}
```

##### 更新中继器

请求：`PATCH http://localhost:8080/api/v1/relayers/<relayer_id>;`

暂停中继器的示例请求：

```bash hljs
curl --location --request PATCH 'http://localhost:8080/api/v1/relayers/<relayer_id>' \
--header 'Authorization: Bearer <my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "paused": true
}'
```

示例响应：

```json hljs
{
    "success": true,
    "data": {
        "id": "sepolia-example",
        "name": "Sepolia Example",
        "network": "sepolia",
        "paused": true,
        "network_type": "evm",
        "signer_id": "local-signer",
        "policies": {
            "eip1559_pricing": false,
            "private_transactions": false,
            "min_balance": 1
        },
        "address": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "notification_id": "notification-example",
        "system_disabled": false
    },
    "error": null
}
```

##### 获取中继器余额

请求：`GET http://localhost:8080/api/v1/relayers/<relayer_id>/balance`

暂停中继器的示例请求：

```bash hljs
curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/balance' \
--header 'Authorization: Bearer <api_key>'
```

示例响应：

```json hljs
{
    "success": true,
    "data": {
        "balance": 1000000000000000,
        "unit": "wei"
    },
    "error": null
}
```

##### 获取中继器状态

请求：`GET http://localhost:8080/api/v1/relayers/<relayer_id>/status`

示例请求：

```bash hljs
curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/status' \
--header 'Authorization: Bearer <api_key>'
```

EVM 中继器的示例响应：

```json hljs
{
    "success": true,
    "data": {
        "balance": "1000000000000000000",
        "pending_transactions_count": 2,
        "last_confirmed_transaction_timestamp": "2025-02-26T13:28:55.838812+00:00",
        "system_disabled": false,
        "paused": false,
        "nonce": "42"
    },
    "error": null
}
```

Stellar 中继器的示例响应：

```json hljs
{
    "success": true,
    "data": {
        "balance": "100000000",
        "pending_transactions_count": 0,
        "last_confirmed_transaction_timestamp": null,
        "system_disabled": false,
        "paused": false,
        "sequence_number": "12345678901234567890"
    },
    "error": null
}
```

响应字段：

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `balance` | 字符串 | 当前中继器余额，以最小单位表示（EVM 为 wei，Solana 为 lamports，Stellar 为 stroops） |
| `pending_transactions_count` | 数字 | 待处理、已提交或已挖掘但尚未确认的事务数 |
| `last_confirmed_transaction_timestamp` | 字符串（可选） | 最近确认的交易的 ISO 8601 时间戳，如果没有确认任何交易，则为 `null` |
| `system_disabled` | 布尔值 | 中继器是否因错误或配置问题而被系统禁用 |
| `paused` | 布尔值 | 中继器是否已手动暂停 |
| `nonce` | 字符串（仅限 EVM） | EVM 中继器的当前交易 **nonce** |
| `sequence_number` | 字符串（仅限 Stellar） | Stellar 中继器的当前序列号 |

|     |     |
| --- | --- |
|  | - 对于 Solana 中继器，当前不支持此端点，并将返回错误<br>  <br>- 网络特定字段（EVM 的 `nonce`，Stellar 的 `sequence_number`）使用 JSON 扁平化直接包含在响应中<br>  <br>- `balance` 字段将原始余额值表示为字符串，以避免大数精度损失 |

#### Solana

Solana API 实现符合 [Paymaster Spec](https://docs.google.com/document/d/1lweO5WH12QJaSAu5RG_wUistyk_nFeT6gy1CdvyCEHg/edit?tab=t.0#heading=h.4yldgprkuvav)。

Solana API

| 方法名称 | 必需参数 | 结果 | 描述 |
| --- | --- | --- | --- |
| feeEstimate | `transaction`，`fee_token` | `estimated_fee`，`conversion_rate` | 使用指定的 **token** 估算任意交易的费用。 |
| transferTransaction | `amount`，`token`，`source`，`destination` | `transaction`，`fee_in_spl`，`token`，`fee_in_lamports`，`valid_until_blockheight` | 为指定的 **token**、发送者和接收者创建转账交易。 提供的 **token** 将被假定为也用于费用的 **token**。 返回部分签名的交易。 |
| prepareTransaction | `transaction`，`fee_token` | `transaction`，`fee_in_spl`，`fee_token`，`fee_in_lamports`，`valid_until_blockheight` | 通过添加中继器特定的指令来准备交易。 返回部分签名的交易。 |
| signTransaction | `transaction` | `transaction`，`signature` | 签署已准备好的交易，而不将其提交到区块链。 |
| signAndSendTransaction | `transaction` | `transaction`，`signature` | 签署交易并将其提交到区块链。 |
| getSupportedTokens | (无) | `tokens[]` (**token** 元数据列表) | 检索中继器支持的 **token** 列表以进行费用支付。 |
| getFeaturesEnabled | (无) | `features[]` (已启用功能的列表) | 检索中继器支持的功能列表。 |

关键术语

| 键 | 描述 |
| --- | --- |
| `transaction` | Base64 编码的序列化 Solana 交易。 这可以是已签名或未签名的交易。 |
| `signature` | 可用于查找链上交易状态的唯一“交易哈希”。 |
| `source` | 源钱包地址。 中继器负责派生和 TA。 |
| `destination` | 目标钱包地址。 中继器负责派生和创建 TA（如果需要）。 |
| `fee_token` | 费用支付的 **token** **mint** 地址。 |
| `fee_in_spl` | 最终用户将支付给中继器的费用金额，以便以 spl **token** 处理交易，以 spl **token** 的最小单位表示（无小数）。 |
| `fee_in_lamports` | 中继器估计将为交易支付的 Lamports 费用金额。 |
| `valid_until_block_height` | 对时间敏感操作的到期区块高度。 |
| `tokens[]` | 支持的 **token** 元数据数组（例如，符号、**mint**、小数）。 |
| `features[]` | 中继器启用的功能数组（例如，捆绑支持、赞助）。 |

|     |     |
| --- | --- |
|  | 在这些示例中，我们假设基本 URL 为 `http://localhost:8080/`。 |

##### 获取支持的 **token**

请求：

结果：

```json hljs
{
    "jsonrpc": "2.0",
    "result": {
        "tokens": [\
            {\
                "decimals": 6,\
                "max_allowed_fee": 100000000,\
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",\
                "symbol": "USDC"\
            },\
            {\
                "decimals": 9,\
                "max_allowed_fee": null,\
                "mint": "So11111111111111111111111111111111111111112",\
                "symbol": "SOL"\
            }\
        ]
    },
    "id": 2
}
```

##### 费用估算

|     |     |
| --- | --- |
|  | 费用估算方法在 devnet 和 testnet 上返回模拟值，因为 Jupiter 服务仅在 mainnet-beta 上可用。 |

请求：

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/<solana_relayer_id>/rpc' \
--header 'Authorization: Bearer <my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "jsonrpc": "2.0",
  "method": "feeEstimate",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZzDKeiaRTZZ3ipAtgJOOmqCGhz1iUHo8A9xynrbleugBAgIAAQwCAAAAQEIPAAAAAAA=",
    "fee_token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  },
  "id": 3
}'
```

结果：

```json hljs
{
    "jsonrpc": "2.0",
    "result": {
        "conversion_rate": "142.6",
        "estimated_fee": "0.000713"
    },
    "id": 3
}
```

##### 签署交易

请求：

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/<solana_relayer_id>/rpc' \
--header 'Authorization: Bearer <my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "signTransaction",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="

},
  "id": 4
}'
```

结果：

```json hljs
{
    "jsonrpc": "2.0",
    "result": {
        "signature": "2jg9xbGLtZRsiJBrDWQnz33JuLjDkiKSZuxZPdjJ3qrJbMeTEerXFAKynkPW63J88nq63cvosDNRsg9VqHtGixvP",
        "transaction": "AVbRgFoUlj0XdlLP4gJJ2zwmr/2g2LOdeNqGPYTl4VFzY7lrX+nKNXUEU0DLJEA+2BW3uHvudQSXz5YBqd5d9gwBAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="
    },
    "id": 4
}
```

##### 签署并发送交易

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/<solana_relayer_id>/rpc' \
--header 'Authorization: Bearer <my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "signAndSendTransaction",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="
  },
  "id": 5
}'
```

结果：

##### 准备交易

|     |     |
| --- | --- |
|  | `prepareTransaction` 方法为 devnet 和 testnet 上的 fee\_in\_spl 响应字段返回一个模拟值，因为 Jupiter 服务仅在 mainnet-beta 上可用。 |

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/rpc' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "prepareTransaction",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA=",
    "fee_token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr"

},
  "id": 6
}'
```

结果：

```json hljs
{
    "jsonrpc": "2.0",
    "result": {
        "fee_in_lamports": "5000",
        "fee_in_spl": "5000",
        "fee_token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
        "transaction": "Ae7kEB+DOH8vhFDlV6SqTCcaf0mJI/Yrn1Zr/WFh8kEfdD0c99wJ1bYV3FDjt/qtwxRa5LxuVDlHR2CT+M5BIgYBAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAuTJfv3pxOOfvB3SHRW0ArtL0kkx6rVqN+d+tGrRgLIMBAgIAAQwCAAAAQEIPAAAAAAA=",
        "valid_until_blockheight": 351723643
    },
    "id": 6
}
```

##### 转账交易

|     |     |
| --- | --- |
|  | `transferTransaction` 方法为 devnet 和 testnet 上的 fee\_in\_spl 响应字段返回一个模拟值，因为 Jupiter 服务仅在 mainnet-beta 上可用。 |

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/rpc' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "transferTransaction",
  "params": {
    "token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
    "amount": 1,
    "source": "C6VBV1EK2Jx7kFgCkCD5wuDeQtEH8ct2hHGUPzEhUSc8",
    "destination": "D6VBV1EK2Jx7kFgCkCD5wuDeQtEH8ct2hHGUPzEhUSc8"

},
  "id": 7
}'
```

结果：

```json hljs
{
    "jsonrpc": "2.0",
    "result": {
        "fee_in_lamports": "5000",
        "fee_in_spl": "5000",
        "fee_token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
        "transaction": "AaQ8y7r1eIuwrmhuIWSJ7iWVJ5gAhZaZ9vd2I9wQ0PFs79GPYejdVrsVgMLm3t1c7g/WsoYhoPdt83ST1xcwdggBAAIEpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEMsnnyKbZZ5yUtDsJ/8r0KO7Li3BEwZoWs+nOJzoXwvgbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCp6Sg5VQll/9TWSsqvRtRd9zGOW09XyQxIfWBiXYKbg3tDrlnF1KFvUS/T47LoVLV2lUyLS2zrfs8g57jdLLGvWwECBAEDAQAKDAEAAAAAAAAABg==",
        "valid_until_blockheight": 351724045
    },
    "id": 7
}
```

#### EVM

| 方法 | 必需参数 | 结果 | 描述 |
| --- | --- | --- | --- |
| 发送交易 | `value`，`data`，`to`，`gas_limit` |  | 将交易提交到区块链。 |
| 列出交易 | （无） |  | 列出中继器交易。 |
| 通过 ID 获取交易 | `id` |  | 通过 ID 检索交易。 |
| 通过 **nonce** 获取交易 | `nonce` |  | 通过 **nonce** 检索交易。 |

##### 发送交易

请求：`POST http://localhost:8080/api/v1/relayers/<relayer_id>/transactions`

发送交易的示例请求：

```bash hljs
 curl --location --request POST 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "value": 1,
    "data": "0x",
    "to": "0xd9b55a2ba539031e3c18c9528b0dc3a7f603a93b",
    "gas_limit": 21000,
    "speed": "average"
}'
```

示例响应：

```json hljs
{
    "success": true,
    "data": {
        "id": "47f440b3-f4ce-4441-9489-55fc83be12cf",
        "hash": null,
        "status": "pending",
        "created_at": "2025-02-26T13:24:35.560593+00:00",
        "sent_at": null,
        "confirmed_at": null,
        "gas_price": null,
        "gas_limit": 21000,
        "nonce": 0,
        "value": "0x1",
        "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "to": "0x5e87fD270D40C47266B7E3c822f4a9d21043012D",
        "relayer_id": "sepolia-example"
    },
    "error": null
}
```

##### 列出交易

请求：`GET http://localhost:8080/api/v1/relayers/<relayer_id>/transactions`

列出中继器交易的示例请求：

```bash hljs
curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions' \
--header 'Authorization: Bearer <api_key>'
```

示例响应：

```json hljs
{
    "success": true,
     "data": [\
        {\
            "id": "bfa362dc-a84a-4466-93d0-b8487bfd40cc",\
            "hash": "0xca349b67fad7b64239f4682a231c5398b0b52a93b626d1d67cb9ec037cdd290c",\
            "status": "confirmed",\
            "created_at": "2025-02-26T13:28:46.838812+00:00",\
            "sent_at": "2025-02-26T13:28:48.838812+00:00",\
            "confirmed_at": "2025-02-26T13:28:55.838812+00:00",\
            "gas_price": 12312313123,\
            "gas_limit": 21000,\
            "nonce": 8,\
            "value": "0x1",\
            "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",\
            "to": "0x5e87fD270D40C47266B7E3c822f4a9d21043012D",\
            "relayer_id": "sepolia-example"\
        },\
    ],
    "error": null,
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_items": 0
    }
}
```

##### 通过 ID 获取交易

请求：`GET http://localhost:8080/api/v1/relayers/<relayer_id>/transactions/id`

通过 ID 获取中继器交易的示例请求：

```bash hljs
curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions/47f440b3-f4ce-4441-9489-55fc83be12cf' \
--header 'Authorization: Bearer <api_key>'
```

示例响应：

```json hljs
{
    "success": true,
    "data": {
        "id": "47f440b3-f4ce-4441-9489-55fc83be12cf",
        "hash": "0xa5759c99e99a1fc3b6e66bca75688659d583ee2556c7d185862dc8fcdaa4d5d7",
        "status": "confirmed",
        "created_at": "2025-02-26T13:28:46.838812+00:00",
        "sent_at": "2025-02-26T13:28:48.838812+00:00",
        "confirmed_at": "2025-02-26T13:28:55.838812+00:00",
        "gas_price": 35843464006,
        "gas_limit": 21000,
        "nonce": 0,
        "value": "0x1",
        "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "to": "0x5e87fD270D40C47266B7E3c822f4a9d21043012D",
        "relayer_id": "sepolia-example"
    },
    "error": null
}
```

##### 通过 **nonce** 获取交易

请求：`GET http://localhost:8080/api/v1/relayers/<relayer_id>/transactions/by-nonce/0`

通过 **nonce** 获取中继器交易的示例请求：

```bash hljs
curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions/by-nonce/0' \
--header 'Authorization: Bearer <api_key>'
```

示例响应：

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_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"} // 为服务付款
}'
```

**2. 调用合约：**

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_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"},\
        {"u64": "1000000"}\
      ],\
      "auth": {"type": "source_account"}\
    }\
  ]
}'
```

**3. 创建合约：**

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_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"\
    }\
  ]
}'
```

|     |     |
| --- | --- |
|  | 对于 create\_contract，你也可以包含可选的 `constructor_args` 数组，并对工厂模式部署使用 `"from": "contract"`。 |

**4. 上传 WASM：**

|     |     |
| --- | --- |
|  | WASM 可以以 `"type": "base64"` 或 `"type": "hex"` 编码形式提供。 |

**5. 提交预构建的未签名交易 (XDR)：**

对于高级用例，你可以提交预构建的未签名交易作为 base64 编码的 XDR：

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "transaction_xdr": "AAAAAgAAAAC0V9YG9Ks6MEexw5yB+FDD8VJwmtv5OU2BwgPN6PpZcwAAAGQCeO4pAAAAAgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAACgAAAAAAAAAAAAAAAAAAAAA=",
  "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"
}'
```

|     |     |
| --- | --- |
|  | 当提交 XDR 交易时，`operations` 字段不是必需的。 中继器将从 XDR 解析交易 |

**6. 费用补贴交易：**

要为现有签名交易提交费用补贴交易：

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "transaction_xdr": "AAAAAgAAAAC0V9YG9Ks6MEexw5yB+FDD8VJwmtv5OU2BwgPN6PpZcwAAAGQCeO4pAAAAAgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAACgAAAAAAAAAAAAAAAAAAAADN6PpZcwAAAEDtHqNhqC0V8mEZX9xXd4Gw3amGyg/aNTPKUQIH2nipnRps7H3HQTPhPiSzxwvzfXcGAz9H3hXXIkWegqJlEAoN",
  "fee_bump": true,
  "max_fee": 1000000
}'
```

|     |     |
| --- | --- |
|  | 当 `fee_bump` 为 true 时，`transaction_xdr` 应该包含一个完全签名的交易（不是费用补贴信封）。 中继器将围绕它创建一个费用补贴交易包装器，支付高达 `max_fee` （以 stroops 为单位）的额外费用。 |

示例响应：

```json hljs
{
  "success": true,
  "data": {
    "id": "5431b88c-183b-41c7-9bbb-841d38ddd866",
    "hash": null,
    "status": "pending",
    "created_at": "2025-05-19T11:26:55.188781+00:00",
    "sent_at": null,
    "confirmed_at": null,
    "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY",
    "fee": 0,
    "sequence_number": 0
  },
  "error": null
}
```

##### 获取交易详情

检索通过中继器提交的特定 Stellar 交易的详细信息。

请求： `GET http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions/<transaction_id>;`

- `<stellar_relayer_id>`：你的 Stellar 中继器配置的 ID。

- `<transaction_id>`：交易的 ID（从发送交易或从列出交易返回）。

示例请求 (cURL)：

```bash hljs
curl --location --request GET 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions/<transaction_id_example>' \
--header 'Authorization: Bearer <your_api_key>'
```

示例响应：

```json hljs
{
    "success": true,
    "data": {
        "id": "5431b88c-183b-41c7-9bbb-841d38ddd866",
        "hash": "f22e5d9a36cbedee20de01d5bf89d2e80682c102e844d72f567da1acd1944cb0",
        "status": "submitted",
        "created_at": "2025-05-19T11:26:55.188781+00:00",
        "sent_at": "2025-05-19T11:26:56.136646+00:00",
        "confirmed_at": null,
        "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY",
        "fee": 0,
        "sequence_number": 3700719915892739
    },
    "error": null
}
```

##### 列出交易

列出与 Stellar 中继器关联的交易，支持分页。

请求： `GET http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions`

示例请求 (cURL)：

```bash hljs
curl --location --request GET 'http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer <your_api_key>'
```

示例响应：

```json hljs
{
    "success": true,
    "data": [\
        {\
            "id": "5431b88c-183b-41c7-9bbb-841d38ddd866",\
            "hash": "f22e5d9a36cbedee20de01d5bf89d2e80682c102e844d72f567da1acd1944cb0",\
            "status": "submitted",\
            "created_at": "2025-05-19T11:26:55.188781+00:00",\
            "sent_at": "2025-05-19T11:26:56.136646+00:00",\
            "confirmed_at": null,\
            "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY",\
            "fee": 0,\
            "sequence_number": 3700719915892739\
        }\
    ],
    "error": null,
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_items": 1
    }
}
```

##### ScVal 参数格式

当调用合约函数时，参数必须以 JSON 格式的 ScVal 值提供。 中继器使用 stellar-xdr JSON 序列化格式。

以下是支持的 ScVal 类型及其格式：

| 类型 | 格式 | 描述 |
| --- | --- | --- |
| U64 | `{"u64": "1000000"}` | 无符号 64 位整数 |
| I64 | `{"i64": "-500"}` | 有符号 64 位整数 |
| U32 | `{"u32": 42}` | 无符号 32 位整数 |
| I32 | `{"i32": -42}` | 有符号 32 位整数 |
| Boolean | `{"bool": true}` | 布尔值 |
| String | `{"string": "hello world"}` | UTF-8 字符串 |
| Symbol | `{"symbol": "transfer"}` | 符号（用于函数名和标识符） |
| Address | `{"address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"}` | Stellar 账户或合约地址 |
| Bytes | `{"bytes": "deadbeef"}` | 十六进制编码的字节数组 |
| Vector | `{"vec": [{"u32": 1}, {"u32": 2}, {"u32": 3}]}` | ScVal 值的数组 |
| Map | `{"map": [{"key": {"symbol": "name"}, "val": {"string": "MyToken"}}]}` | ScVal 值的键值对 |
| U128 | `{"u128": {"hi": "100", "lo": "200"}}` | 无符号 128 位整数（作为高/低位部分） |
| I128 | `{"i128": {"hi": "-100", "lo": "200"}}` | 有符号 128 位整数（作为高/低位部分） |
| U256 | `{"u256": {"hi_hi": "1", "hi_lo": "2", "lo_hi": "3", "lo_lo": "4"}}` | 无符号 256 位整数（作为四个 64 位部分） |
| I256 | `{"i256": {"hi_hi": "-1", "hi_lo": "2", "lo_hi": "3", "lo_lo": "4"}}` | 有符号 256 位整数（作为四个 64 位部分） |

**地址格式说明：**
- 账户地址以 'G' 开头
- 合约地址以 'C' 开头
- 所有地址都使用 SEP-23 Strkey 编码

##### 授权模式

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

| 类型 | 描述 | 示例用法 |
| --- | --- | --- |
| `none` | 无需授权 | `"auth": {"type": "none"}` |
| `source_account` | 使用交易源账户（默认） | `"auth": {"type": "source_account"}` |
| `addresses` | 使用特定地址（未来功能） | `"auth": {"type": "addresses", "signers": ["GABC…"]}` |
| `xdr` | 高级：提供 base64 编码的 XDR 条目 | `"auth": {"type": "xdr", "entries": ["<base64>"]}` |

>- 原文链接： [docs.openzeppelin.com/re...](https://docs.openzeppelin.com/relayer/1.0.x/api_reference)
>- 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～

API 参考

本文档提供了已实现的 API 的相关信息，以及用法示例。

前提条件

API 密钥此密钥对于大多数 API 调用至关重要。可以在 .env 文件中的 API_KEY 变量下设置它。如果密钥发生更改，则无需重建 Docker 镜像，因为 docker compose 会在下次启动容器时获取更改。

此密钥应作为标头发送到大多数 API 调用：

Authorization: Bearer &lt;my api key>

请求格式

默认情况下，容器监听端口 8080。调用应遵循以下 URL： http://<server_address_or_IP>:8080/api/v1/relayers/<relayer_id>/rpc


	`relayer_id` 是在 `./config/config.json` 文件中赋予中继器配置的名称。

环境

Solana
EVM
Stellar

API 参考

通用操作

这是一组 Solana 和 EVM 中继器通用的 REST 调用。


	在这些示例中，我们假设基本 URL 为 `http://localhost:8080/`。

列出中继器

请求：GET http://localhost:8080/api/v1/relayers/

示例请求：

curl --location --request GET 'http://localhost:8080/api/v1/relayers/' \
--header 'Authorization: Bearer &lt;my_api_key>'

示例响应：

{
    "success": true,
    "data": [\
        {\
            "id": "sepolia-example",\
            "name": "Sepolia Example",\
            "network": "sepolia",\
            "paused": false,\
            "network_type": "evm",\
            "signer_id": "local-signer",\
            "policies": {\
                "eip1559_pricing": false,\
                "private_transactions": false,\
                "min_balance": 1\
            },\
            "address": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",\
            "notification_id": "notification-example",\
            "system_disabled": false\
        }\
    ],
    "error": null,
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_items": 1
    }
}

获取中继器详细信息

请求：GET http://localhost:8080/api/v1/relayers/<relayer_id>;

可以通过列出中继器或检查配置文件 ( ./config/config.json) 来找到 relayer_id。

示例请求：

curl --location --request GET 'http://localhost:8080/api/v1/relayers/&lt;relayer_id>' \
--header 'Authorization: Bearer &lt;my_api_key>'

示例响应：

{
    "success": true,
    "data": {
        "id": "sepolia-example",
        "name": "Sepolia Example",
        "network": "sepolia",
        "network_type": "evm",
        "paused": false,
        "policies": {
            "eip1559_pricing": false,
            "private_transactions": false,
            "min_balance": 1
        },
        "address": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "system_disabled": false
    },
    "error": null
}

更新中继器

请求：PATCH http://localhost:8080/api/v1/relayers/<relayer_id>;

暂停中继器的示例请求：

curl --location --request PATCH 'http://localhost:8080/api/v1/relayers/&lt;relayer_id>' \
--header 'Authorization: Bearer &lt;my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "paused": true
}'

示例响应：

{
    "success": true,
    "data": {
        "id": "sepolia-example",
        "name": "Sepolia Example",
        "network": "sepolia",
        "paused": true,
        "network_type": "evm",
        "signer_id": "local-signer",
        "policies": {
            "eip1559_pricing": false,
            "private_transactions": false,
            "min_balance": 1
        },
        "address": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "notification_id": "notification-example",
        "system_disabled": false
    },
    "error": null
}

获取中继器余额

请求：GET http://localhost:8080/api/v1/relayers/<relayer_id>/balance

暂停中继器的示例请求：

curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/balance' \
--header 'Authorization: Bearer &lt;api_key>'

示例响应：

{
    "success": true,
    "data": {
        "balance": 1000000000000000,
        "unit": "wei"
    },
    "error": null
}

获取中继器状态

请求：GET http://localhost:8080/api/v1/relayers/<relayer_id>/status

示例请求：

curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/status' \
--header 'Authorization: Bearer &lt;api_key>'

EVM 中继器的示例响应：

{
    "success": true,
    "data": {
        "balance": "1000000000000000000",
        "pending_transactions_count": 2,
        "last_confirmed_transaction_timestamp": "2025-02-26T13:28:55.838812+00:00",
        "system_disabled": false,
        "paused": false,
        "nonce": "42"
    },
    "error": null
}

Stellar 中继器的示例响应：

{
    "success": true,
    "data": {
        "balance": "100000000",
        "pending_transactions_count": 0,
        "last_confirmed_transaction_timestamp": null,
        "system_disabled": false,
        "paused": false,
        "sequence_number": "12345678901234567890"
    },
    "error": null
}

响应字段：

字段	类型	描述
`balance`	字符串	当前中继器余额，以最小单位表示（EVM 为 wei，Solana 为 lamports，Stellar 为 stroops）
`pending_transactions_count`	数字	待处理、已提交或已挖掘但尚未确认的事务数
`last_confirmed_transaction_timestamp`	字符串（可选）	最近确认的交易的 ISO 8601 时间戳，如果没有确认任何交易，则为 `null`
`system_disabled`	布尔值	中继器是否因错误或配置问题而被系统禁用
`paused`	布尔值	中继器是否已手动暂停
`nonce`	字符串（仅限 EVM）	EVM 中继器的当前交易 nonce
`sequence_number`	字符串（仅限 Stellar）	Stellar 中继器的当前序列号


	- 对于 Solana 中继器，当前不支持此端点，并将返回错误<br> <br>- 网络特定字段（EVM 的 `nonce`，Stellar 的 `sequence_number`）使用 JSON 扁平化直接包含在响应中<br> <br>- `balance` 字段将原始余额值表示为字符串，以避免大数精度损失

Solana

Solana API 实现符合 Paymaster Spec。

Solana API

方法名称	必需参数	结果	描述
feeEstimate	`transaction`，`fee_token`	`estimated_fee`，`conversion_rate`	使用指定的 token 估算任意交易的费用。
transferTransaction	`amount`，`token`，`source`，`destination`	`transaction`，`fee_in_spl`，`token`，`fee_in_lamports`，`valid_until_blockheight`	为指定的 token、发送者和接收者创建转账交易。提供的 token 将被假定为也用于费用的 token。返回部分签名的交易。
prepareTransaction	`transaction`，`fee_token`	`transaction`，`fee_in_spl`，`fee_token`，`fee_in_lamports`，`valid_until_blockheight`	通过添加中继器特定的指令来准备交易。返回部分签名的交易。
signTransaction	`transaction`	`transaction`，`signature`	签署已准备好的交易，而不将其提交到区块链。
signAndSendTransaction	`transaction`	`transaction`，`signature`	签署交易并将其提交到区块链。
getSupportedTokens	(无)	`tokens[]` (token 元数据列表)	检索中继器支持的 token 列表以进行费用支付。
getFeaturesEnabled	(无)	`features[]` (已启用功能的列表)	检索中继器支持的功能列表。

关键术语

键	描述
`transaction`	Base64 编码的序列化 Solana 交易。这可以是已签名或未签名的交易。
`signature`	可用于查找链上交易状态的唯一“交易哈希”。
`source`	源钱包地址。中继器负责派生和 TA。
`destination`	目标钱包地址。中继器负责派生和创建 TA（如果需要）。
`fee_token`	费用支付的 token mint 地址。
`fee_in_spl`	最终用户将支付给中继器的费用金额，以便以 spl token 处理交易，以 spl token 的最小单位表示（无小数）。
`fee_in_lamports`	中继器估计将为交易支付的 Lamports 费用金额。
`valid_until_block_height`	对时间敏感操作的到期区块高度。
`tokens[]`	支持的 token 元数据数组（例如，符号、mint、小数）。
`features[]`	中继器启用的功能数组（例如，捆绑支持、赞助）。


	在这些示例中，我们假设基本 URL 为 `http://localhost:8080/`。

获取支持的 token

请求：

curl --location --request POST 'http://localhost:8080/api/v1/relayers/&lt;solana_relayer_id>/rpc' \
--header 'Authorization: Bearer &lt;my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "getSupportedTokens",
    "params": {},
    "id": 2
}'

结果：

{
    "jsonrpc": "2.0",
    "result": {
        "tokens": [\
            {\
                "decimals": 6,\
                "max_allowed_fee": 100000000,\
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",\
                "symbol": "USDC"\
            },\
            {\
                "decimals": 9,\
                "max_allowed_fee": null,\
                "mint": "So11111111111111111111111111111111111111112",\
                "symbol": "SOL"\
            }\
        ]
    },
    "id": 2
}

费用估算


	费用估算方法在 devnet 和 testnet 上返回模拟值，因为 Jupiter 服务仅在 mainnet-beta 上可用。

请求：

curl --location --request POST 'http://localhost:8080/api/v1/relayers/&lt;solana_relayer_id>/rpc' \
--header 'Authorization: Bearer &lt;my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "jsonrpc": "2.0",
  "method": "feeEstimate",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZzDKeiaRTZZ3ipAtgJOOmqCGhz1iUHo8A9xynrbleugBAgIAAQwCAAAAQEIPAAAAAAA=",
    "fee_token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  },
  "id": 3
}'

结果：

{
    "jsonrpc": "2.0",
    "result": {
        "conversion_rate": "142.6",
        "estimated_fee": "0.000713"
    },
    "id": 3
}

签署交易

请求：

curl --location --request POST 'http://localhost:8080/api/v1/relayers/&lt;solana_relayer_id>/rpc' \
--header 'Authorization: Bearer &lt;my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "signTransaction",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="

  },
  "id": 4
}'

结果：

{
    "jsonrpc": "2.0",
    "result": {
        "signature": "2jg9xbGLtZRsiJBrDWQnz33JuLjDkiKSZuxZPdjJ3qrJbMeTEerXFAKynkPW63J88nq63cvosDNRsg9VqHtGixvP",
        "transaction": "AVbRgFoUlj0XdlLP4gJJ2zwmr/2g2LOdeNqGPYTl4VFzY7lrX+nKNXUEU0DLJEA+2BW3uHvudQSXz5YBqd5d9gwBAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="
    },
    "id": 4
}

签署并发送交易

curl --location --request POST 'http://localhost:8080/api/v1/relayers/&lt;solana_relayer_id>/rpc' \
--header 'Authorization: Bearer &lt;my_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "signAndSendTransaction",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="
  },
  "id": 5
}'

结果：

{
    "jsonrpc": "2.0",
    "result": {
        "signature": "2jg9xbGLtZRsiJBrDWQnz33JuLjDkiKSZuxZPdjJ3qrJbMeTEerXFAKynkPW63J88nq63cvosDNRsg9VqHtGixvP",
        "transaction": "AVbRgFoUlj0XdlLP4gJJ2zwmr/2g2LOdeNqGPYTl4VFzY7lrX+nKNXUEU0DLJEA+2BW3uHvudQSXz5YBqd5d9gwBAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA="
    },
    "id": 5
}

准备交易


	`prepareTransaction` 方法为 devnet 和 testnet 上的 fee_in_spl 响应字段返回一个模拟值，因为 Jupiter 服务仅在 mainnet-beta 上可用。

curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/rpc' \
--header 'Authorization: Bearer &lt;api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "prepareTransaction",
  "params": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/bKmYrYtPWWI7zwiXWqAC5iFnkAkRL2D8s6lPkoJJokBAgIAAQwCAAAAQEIPAAAAAAA=",
    "fee_token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr"

  },
  "id": 6
}'

结果：

{
    "jsonrpc": "2.0",
    "result": {
        "fee_in_lamports": "5000",
        "fee_in_spl": "5000",
        "fee_token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
        "transaction": "Ae7kEB+DOH8vhFDlV6SqTCcaf0mJI/Yrn1Zr/WFh8kEfdD0c99wJ1bYV3FDjt/qtwxRa5LxuVDlHR2CT+M5BIgYBAAEDpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAuTJfv3pxOOfvB3SHRW0ArtL0kkx6rVqN+d+tGrRgLIMBAgIAAQwCAAAAQEIPAAAAAAA=",
        "valid_until_blockheight": 351723643
    },
    "id": 6
}

转账交易


	`transferTransaction` 方法为 devnet 和 testnet 上的 fee_in_spl 响应字段返回一个模拟值，因为 Jupiter 服务仅在 mainnet-beta 上可用。

curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/rpc' \
--header 'Authorization: Bearer &lt;api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "method": "transferTransaction",
  "params": {
    "token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
    "amount": 1,
    "source": "C6VBV1EK2Jx7kFgCkCD5wuDeQtEH8ct2hHGUPzEhUSc8",
    "destination": "D6VBV1EK2Jx7kFgCkCD5wuDeQtEH8ct2hHGUPzEhUSc8"

  },
  "id": 7
}'

结果：

{
    "jsonrpc": "2.0",
    "result": {
        "fee_in_lamports": "5000",
        "fee_in_spl": "5000",
        "fee_token": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
        "transaction": "AaQ8y7r1eIuwrmhuIWSJ7iWVJ5gAhZaZ9vd2I9wQ0PFs79GPYejdVrsVgMLm3t1c7g/WsoYhoPdt83ST1xcwdggBAAIEpNhTBS0w2fqEkg0sAghld4KIZNFW3kt5Co2TA75icpEMsnnyKbZZ5yUtDsJ/8r0KO7Li3BEwZoWs+nOJzoXwvgbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCp6Sg5VQll/9TWSsqvRtRd9zGOW09XyQxIfWBiXYKbg3tDrlnF1KFvUS/T47LoVLV2lUyLS2zrfs8g57jdLLGvWwECBAEDAQAKDAEAAAAAAAAABg==",
        "valid_until_blockheight": 351724045
    },
    "id": 7
}

EVM

方法	必需参数	描述
发送交易	`value`，`data`，`to`，`gas_limit`	将交易提交到区块链。
列出交易	（无）	列出中继器交易。
通过 ID 获取交易	`id`	通过 ID 检索交易。
通过 nonce 获取交易	`nonce`	通过 nonce 检索交易。

发送交易

请求：POST http://localhost:8080/api/v1/relayers/<relayer_id>/transactions

发送交易的示例请求：

 curl --location --request POST 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions' \
--header 'Authorization: Bearer &lt;api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "value": 1,
    "data": "0x",
    "to": "0xd9b55a2ba539031e3c18c9528b0dc3a7f603a93b",
    "gas_limit": 21000,
    "speed": "average"
}'

示例响应：

{
    "success": true,
    "data": {
        "id": "47f440b3-f4ce-4441-9489-55fc83be12cf",
        "hash": null,
        "status": "pending",
        "created_at": "2025-02-26T13:24:35.560593+00:00",
        "sent_at": null,
        "confirmed_at": null,
        "gas_price": null,
        "gas_limit": 21000,
        "nonce": 0,
        "value": "0x1",
        "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "to": "0x5e87fD270D40C47266B7E3c822f4a9d21043012D",
        "relayer_id": "sepolia-example"
    },
    "error": null
}

列出交易

请求：GET http://localhost:8080/api/v1/relayers/<relayer_id>/transactions

列出中继器交易的示例请求：

curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions' \
--header 'Authorization: Bearer &lt;api_key>'

示例响应：

{
    "success": true,
     "data": [\
        {\
            "id": "bfa362dc-a84a-4466-93d0-b8487bfd40cc",\
            "hash": "0xca349b67fad7b64239f4682a231c5398b0b52a93b626d1d67cb9ec037cdd290c",\
            "status": "confirmed",\
            "created_at": "2025-02-26T13:28:46.838812+00:00",\
            "sent_at": "2025-02-26T13:28:48.838812+00:00",\
            "confirmed_at": "2025-02-26T13:28:55.838812+00:00",\
            "gas_price": 12312313123,\
            "gas_limit": 21000,\
            "nonce": 8,\
            "value": "0x1",\
            "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",\
            "to": "0x5e87fD270D40C47266B7E3c822f4a9d21043012D",\
            "relayer_id": "sepolia-example"\
        },\
    ],
    "error": null,
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_items": 0
    }
}

通过 ID 获取交易

请求：GET http://localhost:8080/api/v1/relayers/<relayer_id>/transactions/id

通过 ID 获取中继器交易的示例请求：

curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions/47f440b3-f4ce-4441-9489-55fc83be12cf' \
--header 'Authorization: Bearer &lt;api_key>'

示例响应：

{
    "success": true,
    "data": {
        "id": "47f440b3-f4ce-4441-9489-55fc83be12cf",
        "hash": "0xa5759c99e99a1fc3b6e66bca75688659d583ee2556c7d185862dc8fcdaa4d5d7",
        "status": "confirmed",
        "created_at": "2025-02-26T13:28:46.838812+00:00",
        "sent_at": "2025-02-26T13:28:48.838812+00:00",
        "confirmed_at": "2025-02-26T13:28:55.838812+00:00",
        "gas_price": 35843464006,
        "gas_limit": 21000,
        "nonce": 0,
        "value": "0x1",
        "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "to": "0x5e87fD270D40C47266B7E3c822f4a9d21043012D",
        "relayer_id": "sepolia-example"
    },
    "error": null
}

通过 nonce 获取交易

请求：GET http://localhost:8080/api/v1/relayers/<relayer_id>/transactions/by-nonce/0

通过 nonce 获取中继器交易的示例请求：

curl --location --request GET 'http://localhost:8080/api/v1/relayers/sepolia-example/transactions/by-nonce/0' \
--header 'Authorization: Bearer &lt;api_key>'

示例响应：

{
    "success": true,
    "data": {
        "id": "47f440b3-f4ce-4441-9489-55fc83be12cf",
        "hash": "0xa5759c99e99a1fc3b6e66bca75688659d583ee2556c7d185862dc8fcdaa4d5d7",
        "status": "confirmed",
        "created_at": "2025-02-26T13:28:46.838812+00:00",
        "sent_at": "2025-02-26T13:28:48.838812+00:00",
        "confirmed_at": "2025-02-26T13:28:55.838812+00:00",
        "gas_price": 35843464006,
        "gas_limit": 21000,
        "nonce": 0,
        "value": "0x1",
        "from": "0xc834dcdc9a074dbbadcc71584789ae4b463db116",
        "to": "0x5e87fD270D40C47266B7E3c822f4a9d2104**1. 支付操作：**

```bash hljs
curl --location --request POST 'http://localhost:8080/api/v1/relayers/&lt;stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer &lt;your_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"} // 为服务付款
}'

2. 调用合约：

curl --location --request POST 'http://localhost:8080/api/v1/relayers/&lt;stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer &lt;your_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"},\
        {"u64": "1000000"}\
      ],\
      "auth": {"type": "source_account"}\
    }\
  ]
}'

3. 创建合约：

curl --location --request POST 'http://localhost:8080/api/v1/relayers/&lt;stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer &lt;your_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"\
    }\
  ]
}'


	对于 create_contract，你也可以包含可选的 `constructor_args` 数组，并对工厂模式部署使用 `"from": "contract"`。

4. 上传 WASM：

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


	WASM 可以以 `"type": "base64"` 或 `"type": "hex"` 编码形式提供。

5. 提交预构建的未签名交易 (XDR)：

对于高级用例，你可以提交预构建的未签名交易作为 base64 编码的 XDR：

curl --location --request POST 'http://localhost:8080/api/v1/relayers/&lt;stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer &lt;your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "transaction_xdr": "AAAAAgAAAAC0V9YG9Ks6MEexw5yB+FDD8VJwmtv5OU2BwgPN6PpZcwAAAGQCeO4pAAAAAgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAACgAAAAAAAAAAAAAAAAAAAAA=",
  "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"
}'


	当提交 XDR 交易时，`operations` 字段不是必需的。中继器将从 XDR 解析交易

6. 费用补贴交易：

要为现有签名交易提交费用补贴交易：

curl --location --request POST 'http://localhost:8080/api/v1/relayers/&lt;stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer &lt;your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "network": "testnet",
  "transaction_xdr": "AAAAAgAAAAC0V9YG9Ks6MEexw5yB+FDD8VJwmtv5OU2BwgPN6PpZcwAAAGQCeO4pAAAAAgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAACgAAAAAAAAAAAAAAAAAAAADN6PpZcwAAAEDtHqNhqC0V8mEZX9xXd4Gw3amGyg/aNTPKUQIH2nipnRps7H3HQTPhPiSzxwvzfXcGAz9H3hXXIkWegqJlEAoN",
  "fee_bump": true,
  "max_fee": 1000000
}'


	当 `fee_bump` 为 true 时，`transaction_xdr` 应该包含一个完全签名的交易（不是费用补贴信封）。中继器将围绕它创建一个费用补贴交易包装器，支付高达 `max_fee` （以 stroops 为单位）的额外费用。

示例响应：

{
  "success": true,
  "data": {
    "id": "5431b88c-183b-41c7-9bbb-841d38ddd866",
    "hash": null,
    "status": "pending",
    "created_at": "2025-05-19T11:26:55.188781+00:00",
    "sent_at": null,
    "confirmed_at": null,
    "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY",
    "fee": 0,
    "sequence_number": 0
  },
  "error": null
}

获取交易详情

检索通过中继器提交的特定 Stellar 交易的详细信息。

请求： GET http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions/<transaction_id>;

<stellar_relayer_id>：你的 Stellar 中继器配置的 ID。
<transaction_id>：交易的 ID（从发送交易或从列出交易返回）。

示例请求 (cURL)：

curl --location --request GET 'http://localhost:8080/api/v1/relayers/&lt;stellar_relayer_id>/transactions/&lt;transaction_id_example>' \
--header 'Authorization: Bearer &lt;your_api_key>'

示例响应：

{
    "success": true,
    "data": {
        "id": "5431b88c-183b-41c7-9bbb-841d38ddd866",
        "hash": "f22e5d9a36cbedee20de01d5bf89d2e80682c102e844d72f567da1acd1944cb0",
        "status": "submitted",
        "created_at": "2025-05-19T11:26:55.188781+00:00",
        "sent_at": "2025-05-19T11:26:56.136646+00:00",
        "confirmed_at": null,
        "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY",
        "fee": 0,
        "sequence_number": 3700719915892739
    },
    "error": null
}

列出交易

列出与 Stellar 中继器关联的交易，支持分页。

请求： GET http://localhost:8080/api/v1/relayers/<stellar_relayer_id>/transactions

示例请求 (cURL)：

curl --location --request GET 'http://localhost:8080/api/v1/relayers/&lt;stellar_relayer_id>/transactions' \
--header 'Authorization: Bearer &lt;your_api_key>'

示例响应：

{
    "success": true,
    "data": [\
        {\
            "id": "5431b88c-183b-41c7-9bbb-841d38ddd866",\
            "hash": "f22e5d9a36cbedee20de01d5bf89d2e80682c102e844d72f567da1acd1944cb0",\
            "status": "submitted",\
            "created_at": "2025-05-19T11:26:55.188781+00:00",\
            "sent_at": "2025-05-19T11:26:56.136646+00:00",\
            "confirmed_at": null,\
            "source_account": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY",\
            "fee": 0,\
            "sequence_number": 3700719915892739\
        }\
    ],
    "error": null,
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_items": 1
    }
}

ScVal 参数格式

当调用合约函数时，参数必须以 JSON 格式的 ScVal 值提供。中继器使用 stellar-xdr JSON 序列化格式。

以下是支持的 ScVal 类型及其格式：

类型	格式	描述
U64	`{"u64": "1000000"}`	无符号 64 位整数
I64	`{"i64": "-500"}`	有符号 64 位整数
U32	`{"u32": 42}`	无符号 32 位整数
I32	`{"i32": -42}`	有符号 32 位整数
Boolean	`{"bool": true}`	布尔值
String	`{"string": "hello world"}`	UTF-8 字符串
Symbol	`{"symbol": "transfer"}`	符号（用于函数名和标识符）
Address	`{"address": "GCRID3RFJXOBEB73FWRYJJ4II5E5UQ413F7LTM4W5KI54NBHQDRUXVLY"}`	Stellar 账户或合约地址
Bytes	`{"bytes": "deadbeef"}`	十六进制编码的字节数组
Vector	`{"vec": [{"u32": 1}, {"u32": 2}, {"u32": 3}]}`	ScVal 值的数组
Map	`{"map": [{"key": {"symbol": "name"}, "val": {"string": "MyToken"}}]}`	ScVal 值的键值对
U128	`{"u128": {"hi": "100", "lo": "200"}}`	无符号 128 位整数（作为高/低位部分）
I128	`{"i128": {"hi": "-100", "lo": "200"}}`	有符号 128 位整数（作为高/低位部分）
U256	`{"u256": {"hi_hi": "1", "hi_lo": "2", "lo_hi": "3", "lo_lo": "4"}}`	无符号 256 位整数（作为四个 64 位部分）
I256	`{"i256": {"hi_hi": "-1", "hi_lo": "2", "lo_hi": "3", "lo_lo": "4"}}`	有符号 256 位整数（作为四个 64 位部分）

地址格式说明：

账户地址以 'G' 开头
合约地址以 'C' 开头
所有地址都使用 SEP-23 Strkey 编码

授权模式

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

类型	描述	示例用法
`none`	无需授权	`"auth": {"type": "none"}`
`source_account`	使用交易源账户（默认）	`"auth": {"type": "source_account"}`
`addresses`	使用特定地址（未来功能）	`"auth": {"type": "addresses", "signers": ["GABC…"]}`
`xdr`	高级：提供 base64 编码的 XDR 条目	`"auth": {"type": "xdr", "entries": ["<base64>"]}`

原文链接： docs.openzeppelin.com/re...

登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～

翻译
学分: 6
标签: API Relayer Solana EVM Stellar 交易

本文参与登链社区写作激励计划，好文好收益，欢迎正在阅读的你也加入。

API 参考 - OpenZeppelin 文档

API 参考

前提条件

请求格式

环境

API 参考

通用操作

列出中继器

获取中继器详细信息

更新中继器

获取中继器余额

获取中继器状态

Solana

获取支持的 token

费用估算

签署交易

签署并发送交易

准备交易

转账交易

EVM

发送交易

列出交易

通过 ID 获取交易

通过 nonce 获取交易

获取交易详情

列出交易

ScVal 参数格式

授权模式

0 条评论

文章目录