> ## Documentation Index
> Fetch the complete documentation index at: https://docs.li.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# 消息流程

> LI.FI 消息流程文档

# LI.FI 消息流程文档

## 概览

LI.FI 消息流程支持与使用基于消息的 API（例如 Hyperliquid）而非传统链上交易的中心化和混合式交易所进行无缝交互。**该流程为涉及使用链下签名消息运作的协议的跨链转账提供无 gas、无需授权的操作。**

传统 DeFi 操作要求用户发送链上交易、管理 gas 费用，并为每次交互授权代币支出。消息流程通过使用链下签名消息（EIP-712）消除了这些摩擦点，这些消息通过 LI.FI 的后端基础设施中继到目标协议。

## 消息流程的核心优势

* **无需代币授权**：与基于交易的流程不同，消息流程不要求用户授权代币支出
* **无 gas 操作**：用户在链下签署消息，无需为消息本身支付 gas 费用（某些操作可能需要支付费用，但不是 gas）
* **异步执行**：消息被异步中继和处理，可通过 `taskId` 进行状态跟踪
* **无缝集成**：开箱即用地支持 LI.FI API、SDK 和 Widget

***

## 消息流程的工作原理

消息流程通过一个多步骤过程运作，用链下签名消息取代传统的链上交易：

1. **报价/路由生成**：用户使用 `executionType=message`（仅生成基于消息的路由）或 `executionType=all`（同时生成交易和消息两种选项）请求报价或路由
2. **消息创建**：LI.FI 生成一条包含操作详情的 EIP-712 类型化消息
3. **用户签名**：用户在其钱包中链下签署消息（无需 gas）
4. **消息中继**：已签名的消息被提交到 LI.FI 的 `/v1/advanced/relay` 端点
5. **后端处理**：LI.FI 后端验证并将消息转发到目标协议（例如 Hyperliquid）
6. **任务跟踪**：后端返回一个 `taskId` 用于跟踪异步操作
7. **状态监控**：可以使用 `taskId` 参数通过 `/v1/status` 端点检查状态

### 流程图

```
User Wallet → Sign EIP-712 Message (off-chain, no gas)
     ↓
LI.FI SDK/API → POST /v1/advanced/relay
     ↓
LI.FI Backend → Validates & relays to protocol
     ↓
Returns taskId → Track via GET /v1/status?taskId=...
     ↓
Protocol Execution → (e.g., Hyperliquid withdrawal)
```

***

## 与交易流程的主要区别

| 方面         | 交易流程          | 消息流程                      |
| ---------- | ------------- | ------------------------- |
| **执行类型**   | 链上交易          | 链下签名消息                    |
| **Gas 费用** | 用户为每笔交易支付 gas | 签署消息无需 gas                |
| **代币授权**   | 需要（单独的交易）     | 不需要（`skipApproval: true`） |
| **状态跟踪**   | `txHash`      | `taskId`                  |
| **用户操作**   | 发送交易          | 签署类型化消息                   |

### 重要参数

* **`estimate.skipApproval`**：对于消息流程自动设置为 `true`，表示不需要授权交易
* **`estimate.executionType`**：设置为 `"message"` 以标识使用消息流程的步骤
* **`typedData`**：包含用户需要签署的 EIP-712 消息结构

***

## executionType 参数

`executionType` 参数控制 LI.FI API 返回哪些类型的路由。此可选参数可用于：

* `GET /v1/quote`
* `POST /v1/advanced/routes`

### 取值

* **`transaction`**（默认）：仅返回使用传统链上交易的路由，**排除**消息流程路由
* **`message`**：仅返回使用消息流程的路由
* **`all`**：同时返回基于交易和基于消息的路由

### 用法示例

**仅获取基于消息的路由：**

```bash theme={"system"}
curl -X GET 'https://li.quest/v1/quote?fromChain=1337&toChain=999&fromToken=0x8F254b963e8468305d409b33aA137C6700000000&toToken=0x9FDBdA0A5e284c32744D2f17Ee5c74B284993463&fromAddress=0x552008c0f6870c2f77e5cC1d2eb9bdff03e30Ea0&fromAmount=1000000&executionType=message'
```

**获取所有可用路由（两种类型）：**

```bash theme={"system"}
curl -X GET 'https://li.quest/v1/quote?fromChain=1337&toChain=999&fromToken=0x8F254b963e8468305d409b33aA137C6700000000&toToken=0x9FDBdA0A5e284c32744D2f17Ee5c74B284993463&fromAddress=0x552008c0f6870c2f77e5cC1d2eb9bdff03e30Ea0&fromAmount=1000000&executionType=all'
```

***

## /relay 端点

### POST /v1/advanced/relay

**用途**：提交已签名的 EIP-712 消息以中继到目标协议。

**端点**：`https://li.quest/v1/advanced/relay`

### 请求体

请求体是一个 `RelayRequest` 对象，包含：

* **步骤信息**：标准的 LI.FI 步骤数据（tool、action、estimate）
* **类型化数据**：已签名的 EIP-712 消息数组
* **签名**：用户对每条消息的签名

### 请求 Schema

```typescript theme={"system"}
{
  id: string                    // Step ID
  type: 'lifi'                  // Step type
  tool: string                  // Bridge tool (e.g., 'hyperliquidSA')
  toolDetails: {                // Tool metadata
    key: string
    name: string
    logoURI: string
  }
  action: {                     // Transfer action details
    fromChainId: number
    toChainId: number
    fromToken: Token
    toToken: Token
    fromAmount: string
    fromAddress: string
    toAddress: string
    slippage?: number
  }
  estimate: {                   // Estimated results
    fromAmount: string
    toAmount: string
    toAmountMin: string
    tool: string
    executionDuration: number
    approvalAddress: string
    skipApproval: true          // Always true for messaging flow
    feeCosts: FeeCost[]
    gasCosts: GasCost[]
    executionType: string
  }
  includedSteps: Step[]         // Nested steps
  typedData: TypedData[]        // EIP-712 messages with signatures
}
```

### 响应

**成功响应**（`200 OK`）：

```json theme={"system"}
{
  "status": "ok",
  "data": {
    "taskId": "0x3078316542363633386445386335373163373837443762433234463938624641373335343235373331437c313735393438383039323538347c65646461643630632d373730392d346165312d623431652d3834643834333064306135623a30"
  }
}
```

**错误响应**（`400 Bad Request`）：

```json theme={"system"}
{
  "status": "error",
  "data": {
    "code": 400,
    "message": "Invalid request"
  }
}
```

### 响应字段

* **`status`**：`"ok"` 或 `"error"`
* **`data.taskId`**：用于跟踪消息中继操作的唯一十六进制编码标识符
* **`data.code`**：错误代码（仅在 status 为 "error" 时出现）
* **`data.message`**：错误消息（仅在 status 为 "error" 时出现）

***

## 使用 taskId 进行状态跟踪

中继消息后，你会收到一个唯一标识该操作的 `taskId`。使用它来跟踪消息处理状态。

### GET /v1/status

**端点**：`https://li.quest/v1/status`

**查询参数**：

* **`taskId`**（可选）：从 `/relay` 端点返回的任务 ID
* **`txHash`**（可选）：交易哈希（用于传统交易）
* **`toChain`**（可选）：目标链 ID 或 key
* **`bridge`**（可选）：桥接工具标识符
* **`fromChain`**（可选）：源链 ID 或 key

**注意**：你必须提供 `taskId` 或 `txHash` 之一。对于消息流程，请使用 `taskId`。

### 请求示例

```bash theme={"system"}
curl -X GET 'https://li.quest/v1/status?taskId=0x3078316542363633386445386335373163373837443762433234463938624641373335343235373331437c313735393438383039323538347c65646461643630632d373730392d346165312d623431652d3834643834333064306135623a30'
```

### 响应格式

status 端点返回转账的当前状态：

```json theme={"system"}
{
  "status": "DONE",
  "substatus": "COMPLETED",
  "sending": {
    "txHash": "0x...",
    "amount": "1000000",
    "token": {
      /* token details */
    },
    "chainId": 1337,
    "timestamp": 1234567890
  },
  "receiving": {
    "txHash": "0x...",
    "amount": "1000000",
    "token": {
      /* token details */
    },
    "chainId": 999,
    "timestamp": 1234567890
  }
}
```

## 当前用途与支持的协议

消息流程目前用于与以下协议的交互：

### 1. Hyperliquid（主要用例）

**协议**：[Hyperliquid](https://hyperliquid.xyz/)
**操作**：从 Hyperliquid 提现到 EVM 链
**桥接工具**：`hyperliquidSA`
**消息类型**：`SendAsset`

**工作原理**：

1. 用户在 Hyperliquid 现货账户中持有代币
2. 签署一条 `SendAsset` 消息以提现到 EVM 链
3. LI.FI 将该消息中继到 Hyperliquid 的 API
4. Hyperliquid 处理提现并将代币发送到目标链

### 2. Unit Protocol

**协议**：[Unit Protocol](https://unit.network/)
**操作**：通过 Unit 桥接提现到 Hyperliquid
**桥接工具**：`unit`
**消息类型**：`SpotSend`
**链 ID**：

* 来源：1337（Hyperliquid/Hypercore）
* 目标：EVM 链、Bitcoin、Solana

***

## 支持的消息类型

### Hyperliquid

LI.FI 消息流程支持两种用于 Hyperliquid 操作的 EIP-712 消息类型。每种消息类型遵循特定的结构，用于不同的操作。

#### 1. SpotSend

**用途**：现货代币转账
**用例**：由 Unit 协议用于向 Hyperliquid 存款
**桥接工具**：`unit`

**消息结构**：

```typescript theme={"system"}
{
  type: 'spotSend',
  signatureChainId: '0x1',
  hyperliquidChain: 'Mainnet',
  destination: '0x...',           // Recipient address
  token: 'USOL:0x49b67c39...',   // Token identifier
  amount: '1.0',                  // Amount to transfer
  time: 1234567890                // Timestamp in milliseconds
}
```

#### 2. SendAsset

**用途**：DEX（现货账户）之间的资产转账
**用例**：用于从 Hyperliquid 提现到 EVM 链
**桥接工具**：`hyperliquidSA`

**消息结构**：

```typescript theme={"system"}
{
  type: 'sendAsset',
  signatureChainId: '0x1',
  hyperliquidChain: 'Mainnet',
  destination: '0x2000...00fe',        // System address
  sourceDex: 'spot',                    // Source DEX type
  destinationDex: 'spot',               // Destination DEX type
  token: 'USOL:0x49b67c39...',         // Token identifier
  amount: '1.0',                        // Amount to transfer
  fromSubAccount: '',                   // Agent wallet address (if used)
  nonce: 1757944034747                  // Timestamp/nonce
}
```

**注意**：所有消息都遵循 EIP-712 类型化数据标准并包含域信息：

```typescript theme={"system"}
{
  domain: {
    name: 'HyperliquidSignTransaction',
    version: '1',
    chainId: 999,
    verifyingContract: '0x0000000000000000000000000000000000000000'
  },
  types: { /* EIP712Domain and message types */ },
  primaryType: 'HyperliquidTransaction:SendAsset',
  message: { /* message content */ }
}
```

***

## 集成指南

### 直接使用 API

**步骤 1：获取报价/路由**

使用 `executionType=message` 或 `executionType=all` 请求报价：

```bash theme={"system"}
curl -X GET 'https://li.quest/v1/quote?fromChain=1337&toChain=999&fromToken=0x8F254b963e8468305d409b33aA137C6700000000&toToken=0x9FDBdA0A5e284c32744D2f17Ee5c74B284993463&fromAddress=0x552008c0f6870c2f77e5cC1d2eb9bdff03e30Ea0&fromAmount=1000000&executionType=all'
```

**步骤 2：识别消息步骤**

检查路由中带有 `estimate.executionType === "message"` 和 `estimate.skipApproval === true` 的步骤。

**步骤 3：签署消息**

使用路由中的 `typedData` 向用户的钱包请求签名：

```typescript theme={"system"}
const signature = await walletClient.signTypedData({
  domain: typedData.domain,
  types: typedData.types,
  primaryType: typedData.primaryType,
  message: typedData.message,
})
```

**步骤 4：中继消息**

将已签名的消息提交到 `/relay` 端点：

```bash theme={"system"}
curl -X POST 'https://li.quest/v1/advanced/relay' \
  -H 'Content-Type: application/json' \
  -H 'x-lifi-api-key: YOUR_API_KEY' \
  -d '{
    "id": "step-id",
    "typedData": [{
      ...typedData,
      "signature": "0x..."
    }],
    ...stepData
  }'
```

**步骤 5：跟踪状态**

使用返回的 `taskId` 检查状态：

```bash theme={"system"}
curl -X GET 'https://li.quest/v1/status?taskId=RETURNED_TASK_ID'
```

***

### 最佳实践

1. **始终检查 `estimate.skipApproval`**：如果为 true，则跳过授权交易
2. **验证签名**：确保消息在中继之前已正确签名
3. **存储 taskId**：保存从 `/relay` 返回的 taskId 以便进行状态跟踪
4. **轮询 status 端点**：定期检查状态直到完成

***

## 局限性与注意事项

### 当前局限性

* **支持的协议**：目前仅限于 Hyperliquid 和 Unit 协议

### 未来增强

随着消息流程的成熟，未来可能会支持更多协议和链。有兴趣集成的协议团队可以联系 LI.FI 团队。

***

## 常见问题

**问：使用消息流程需要做任何特殊操作吗？**
答：不需要。如果你使用 LI.FI SDK 或 Widget，消息路由会被自动包含和处理。对于直接使用 API 的情况，设置 `executionType=all` 即可查看消息路由。

**问：为什么我的路由带有 `skipApproval: true`？**
答：这表示该路由使用消息流程，不需要代币授权交易。

**问：消息处理需要多长时间？**
答：处理时间因协议而异。对于 Hyperliquid，提现通常在几秒内完成。

**问：中继后可以取消消息吗？**
答：一旦消息被中继并被协议接受，就无法通过 LI.FI 取消。请咨询具体协议了解其取消政策。

**问：如何判断路由是否使用消息流程？**
答：检查 `estimate.executionType` 字段。如果它是 `"message"`，则该路由使用消息流程。

***

## 后续步骤

* **集成**：使用 LI.FI SDK、Widget 或 API 来访问消息流程路由
* **测试**：尝试使用消息流程从 Hyperliquid 进行一笔小额提现
* **监控**：使用 `taskId` 通过 status 端点跟踪你的操作
* **联系**：如需协议集成请求，请联系 [LI.FI 团队](https://li.fi/contact-us/)

有关更多信息，请访问 [LI.FI 文档](https://docs.li.fi/)。