> ## 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.

# Flow Schema

> Field-by-field reference for the Flow JSON document.

**Flow** 文档是你在 `POST /compose` 请求中于 `compose.flow` 下提交的 JSON 主体。本页是服务所接受的 wire format 参考。权威 schema 随 [`@lifi/composer-sdk`](https://www.npmjs.com/package/@lifi/composer-sdk) 一起发布；当此处的细节与 SDK 冲突时，以 SDK 为准，请提交 issue。

## Top-level: `Flow`

```json theme={"system"}
{
  "version": 1,
  "id": "my-flow",
  "chainId": 1,
  "inputs": [ /* FlowInput[] */ ],
  "nodes":  [ /* Call[] */ ]
}
```

| Field     | Type             | Required | Notes                                |
| --------- | ---------------- | -------- | ------------------------------------ |
| `version` | literal `1`      | yes      | 为前向兼容保留。                             |
| `id`      | `string`         | yes      | 用户定义的 flow id。省略时 SDK 生成一个 UUID。     |
| `chainId` | positive integer | yes      | 每个节点所针对的 EVM 链。                      |
| `inputs`  | `FlowInput[]`    | yes      | 可以为空。输入的 `name` 字段由用户定义。             |
| `nodes`   | `Call[]`         | yes      | 有序。节点的 `id` 字段由用户定义，是其他节点引用本节点输出的方式。 |

## `FlowInput`

**resource inputs** 与 **handle inputs** 的联合。Schema：`FlowInputSchema = Union(ResourceInputSchema, HandleInputSchema)`。

### `ResourceInput`

```json theme={"system"}
{
  "name": "amountIn",
  "resource": { "kind": "erc20", "token": "0xC02a…Cc2", "chainId": 1 }
}
```

| Field      | Type       | Notes                                                                                                 |
| ---------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| `name`     | `string`   | 在 `inputs` 内唯一。用作 `input.<name>` ref 目标。                                                              |
| `resource` | `Resource` | `{ kind: "native", chainId }` 或 `{ kind: "erc20", token, chainId }`。`chainId` 必须等于该 flow 的 `chainId`。 |

Schemas：`ResourceInputSchema`、`ResourceSchema`。

### `HandleInput`

```json theme={"system"}
{
  "name": "deadline",
  "type": "uint256"
}
```

| Field  | Type      | Notes                                                                                       |
| ------ | --------- | ------------------------------------------------------------------------------------------- |
| `name` | `string`  | 在 `inputs` 内唯一。                                                                             |
| `type` | `SolType` | `uint8..uint256`、`int128`、`int256`、`address`、`bool`、`bytes`、`bytes4`、`bytes32`、`string` 之一。 |

Schema：`HandleInputSchema`、`SolTypeSchema`。

## `Call` (node)

```json theme={"system"}
{
  "id": "swap",
  "op": "lifi.swap",
  "bind": {
    "amountIn": { "$ref": "input.amountIn" }
  },
  "config": {
    "resourceOut": { "kind": "erc20", "token": "0xA0b8…eB48", "chainId": 1 },
    "slippage": 0.03
  },
  "guards": [
    { "kind": "slippage", "port": "amountOut", "bps": 100 }
  ]
}
```

| Field    | Type                        | Notes                                                     |
| -------- | --------------------------- | --------------------------------------------------------- |
| `id`     | `string`                    | 在 flow 内唯一。不能与保留的 ref 作用域（`input`、`context`、`literal`）冲突。 |
| `op`     | `string`                    | manifest 中已注册的 op 名称。                                     |
| `bind`   | `Record<string, BindValue>` | 将输入 port 名称映射到 ref 或字面量。默认为 `{}`。                         |
| `config` | `Record<string, unknown>`   | op 专属配置。默认为 `{}`。依据该 op 的 manifest `configSchema` 进行校验。   |
| `guards` | `AppliedGuard[]`            | 可选。每一项为 `{ kind, ...config }`，携带该 guard 的配置。              |

Schemas：`CallSchema`、`AppliedGuardSchema`。

## `BindValue`

`bind` 条目为两种结构之一。Schema：`BindValueSchema = Union(RefSchema, LiteralBindingSchema)`。

### `Ref`

```json theme={"system"}
{ "$ref": "input.amountIn" }
```

`$ref` 是一个点路径（dotpath），恰好为以下三种结构之一，参见 [References](/composer/composer-api/concepts/ref-grammar)：

* `input.<name>`
* `context.<sender|executionAddress>`
* `<nodeId>.<port>`

Schema：`RefSchema`。

### `LiteralBinding`

```json theme={"system"}
{ "kind": "uint256", "value": "1000000000000000000" }
```

| Field   | Type      | Notes                                                                       |
| ------- | --------- | --------------------------------------------------------------------------- |
| `kind`  | `SolType` | 该字面量的 Solidity 类型。                                                          |
| `value` | `string`  | 整数类型为十进制；`bytes*` 为十六进制（`0x…`）；`string` 为普通字符串；`bool` 为 `"true"`/`"false"`。 |

Schema：`LiteralBindingSchema`。

## `AppliedGuard`

```json theme={"system"}
{ "kind": "slippage", "port": "amountOut", "bps": 100 }
```

| Field          | Type     | Notes                                                |
| -------------- | -------- | ---------------------------------------------------- |
| `kind`         | `string` | manifest 中注册的 guard 类型。                              |
| *(additional)* | any      | Guard 专属配置。依据该 guard 的 manifest `configSchema` 进行校验。 |

Schema：`AppliedGuardSchema`。

## `Resource`

```json theme={"system"}
{ "kind": "native", "chainId": 1 }
{ "kind": "erc20", "token": "0xA0b8…eB48", "chainId": 1 }
```

| Variant  | Fields                                |
| -------- | ------------------------------------- |
| `native` | `kind: "native"`、`chainId`            |
| `erc20`  | `kind: "erc20"`、`token`（地址）、`chainId` |

Schema：`ResourceSchema`。

## `SolType`

受支持的 Solidity 标量类型的字面量联合：`uint8`、`uint16`、`uint32`、`uint64`、`uint128`、`uint256`、`int128`、`int256`、`address`、`bool`、`bytes`、`bytes4`、`bytes32`、`string`。

Schema：`SolTypeSchema`。

## Worked example

`swap-and-zap` 快速上手会产生一个 Flow，在 `builder.build()` 之后序列化为：

```json theme={"system"}
{
  "version": 1,
  "id": "swap-and-zap-weth-to-aave",
  "chainId": 1,
  "inputs": [
    {
      "name": "amountIn",
      "resource": { "kind": "erc20", "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "chainId": 1 }
    }
  ],
  "nodes": [
    {
      "id": "swap",
      "op": "lifi.swap",
      "bind": {
        "amountIn": { "$ref": "input.amountIn" }
      },
      "config": {
        "resourceOut": { "kind": "erc20", "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "chainId": 1 },
        "slippage": 0.03
      }
    },
    {
      "id": "zap",
      "op": "lifi.zap",
      "bind": {
        "amountIn": { "$ref": "swap.amountOut" }
      },
      "config": {
        "resourceOut": { "kind": "erc20", "token": "0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c", "chainId": 1 }
      },
      "guards": [
        { "kind": "slippage", "port": "amountOut", "bps": 100 }
      ]
    }
  ]
}
```

## See also

* [Flow Structure](/composer/composer-api/concepts/flow-anatomy) —— 对相同字段的散文式讲解。
* [References](/composer/composer-api/concepts/ref-grammar) —— `$ref` 解析规则。
* [`@lifi/compose-spec`](https://unpkg.com/browse/@lifi/compose-spec/) —— 与此 wire format 匹配的 SDK 类型。