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

# SDK Reference

> Public surface of @lifi/composer-sdk — the SDK factory, the FlowBuilder, handles, and supporting namespaces.

本页列举 [`@lifi/composer-sdk`](https://unpkg.com/browse/@lifi/composer-sdk/src/sdk.ts) 的公共 API。如需权威的 TypeScript 类型，请浏览包源码 [unpkg.com/browse/@lifi/composer-sdk](https://unpkg.com/browse/@lifi/composer-sdk/)。

<Note>
  **不存在 `sdk.compile()`。** compile 位于 builder 上：`builder.compile(run)`。`sdk.request(flow, run)` 是用于自定义传输的应急出口（escape hatch）。
</Note>

## `createComposeSdk(options)`

声明于 [`sdk.ts`](https://unpkg.com/browse/@lifi/composer-sdk/src/sdk.ts)。

```ts theme={"system"}
const sdk = createComposeSdk({
  baseUrl: 'https://composer.li.quest',
  apiKey: process.env.LIFI_API_KEY,
  fetch: globalThis.fetch,
});
```

### `ComposeSdkOptions`

| Field     | Type                       | Notes                                                                             |
| --------- | -------------------------- | --------------------------------------------------------------------------------- |
| `baseUrl` | `string`                   | Compose API 的基础 URL。                                                              |
| `apiKey`  | `string`                   | 技术预览期间必填。作为 `x-lifi-api-key` 头随每个请求发送。可在 [portal.li.fi](https://portal.li.fi) 获取。 |
| `fetch`   | `typeof globalThis.fetch?` | 默认为全局 `fetch`。                                                                    |

### `ComposeSdk`

成员：

| Member    | Signature                                                                   | Notes                                                                              |
| --------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `client`  | `ComposeClient`                                                             | 低层 HTTP 客户端（`compile`、`getManifest`、`getZapPacks`）。参见 [`sdk.client`](#sdk-client)。 |
| `flow`    | `<T>(chainId, options: FlowOptions<T>) => FlowBuilder<T>`                   | 创建一个新的 flow builder。                                                               |
| `request` | `<T>(flow: TypedFlow<T>, run: ComposeRunInput<T>) => ComposeCompileRequest` | 构建一个 compile 请求但不发送它。                                                              |

## `sdk.flow(chainId, options)` → `FlowBuilder`

```ts theme={"system"}
const builder = sdk.flow(1, {
  name: 'my-flow',                                 // optional; defaults to a UUID
  inputs: {
    amountIn: resources.erc20(WETH, 1),
    deadline: 'uint256',
  },
});
```

### `FlowOptions<T>`

| Field    | Type                    | Notes                                     |
| -------- | ----------------------- | ----------------------------------------- |
| `name`   | `string?`               | 人类可读的 id。默认为 `crypto.randomUUID()`。       |
| `inputs` | `T extends InputSchema` | 输入名称到 `Resource` 或 `SolType` 的记录（Record）。 |

泛型 `T` 会贯穿传递到 `builder.inputs.<name>` 上的类型化句柄。

## `FlowBuilder<T>`

`FlowBuilder` 是一个 `FlowBuilderCore<T>`（声明于 [`FlowBuilderCore.ts`](https://unpkg.com/browse/@lifi/composer-sdk/src/authoring/FlowBuilderCore.ts)），并额外增加了**每个 op 对应一个类型化方法**以及一个 `compile` 方法。

### Inherited `FlowBuilderCore` members

| Member      | Signature                                     | Notes                                                                |
| ----------- | --------------------------------------------- | -------------------------------------------------------------------- |
| `context`   | `ContextAccessor`                             | `{ sender, executionAddress }` —— 指向运行时上下文值的类型化 ref。                 |
| `inputs`    | `InputHandles<T>`                             | 每个已声明输入对应一个类型化句柄。资源输入 → `ResourceInputHandle`；标量 → `InputHandle<T>`。 |
| `untypedOp` | `(id, op, { bind, config, guards? }) => void` | 用于尚未被类型化 builder 方法覆盖的 op 的应急出口。接受原始 `Ref` 值。                        |
| `build`     | `() => TypedFlow<T>`                          | 将 builder 状态序列化为一个 Flow 文档。                                          |

### Op methods

SDK 为 Composer API 支持的每个 op 暴露一个类型化方法。示例：

* `builder.lifi.swap(id, args)`、`builder.lifi.zap(id, args)`
* `builder.core.call(id, args)`、`builder.core.asResource(id, args)`、`builder.core.balanceOf(id, args)`，以及算术方法 `builder.core.add(id, args)`、`subtract`、`multiply`、`divideDown`、`divideUp`、`bpsDown`、`bpsUp` —— 每个算术 op 一个方法。

每个方法为该 op 的输出返回一个类型化的 `Record<portName, OutputHandle>`。参见实时的 [Ops catalog](/composer/composer-api/ops)。

### `builder.compile(run)`

一步完成：调用 `build()`，经由 `sdk.request` 组成一个 `ComposeCompileRequest`，将其 POST 到 `/compose`，并返回一个 `ComposeCompileResult`。

```ts theme={"system"}
const result = await builder.compile({
  signer: '0xYourSigner',
  inputs: {
    amountIn: materialisers.directDeposit({ amount: '1000000000000000000' }),
  },
  sweepTo: builder.context.sender,
});
```

在网络、校验或服务端错误时抛出 `ComposeError`。

## `sdk.request(flow, run)` → `ComposeCompileRequest`

当你需要原始请求载荷时使用 —— 排队、服务端代理、对请求签名、在测试中检查。

```ts theme={"system"}
const flow = builder.build();
const request = sdk.request(flow, {
  signer: '0xYourSigner',
  inputs: { amountIn: materialisers.directDeposit({ amount: '1000000000000000000' }) },
});

const response = await fetch('https://composer.li.quest/compose', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(request),
});
```

## `sdk.client`

低层 HTTP 客户端。大多数集成只需要 `builder.compile()`；当你通过 `sdk.request()` 构建请求并自行提交，或需要协议/manifest 发现时，再使用该客户端。

| Method        | Signature                                                               | Notes                                                                                                                                                                                                                |
| ------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `compile`     | `(request: ComposeCompileRequest) => Promise<ComposeCompileResult>`     | `POST /compose`。`builder.compile()` 在底层调用的传输。                                                                                                                                                                        |
| `getManifest` | `() => Promise<ComposeManifest>`                                        | `GET /compose/manifest`。后端接受的 ops、materialisers 与 guards 的实时目录 —— 与为 [Ops](/composer/composer-api/ops)、[Materialisers](/composer/composer-api/materialisers) 和 [Guards](/composer/composer-api/guards) 目录提供支撑的是同一来源。 |
| `getZapPacks` | `(options?: GetZapPacksOptions) => Promise<readonly ZapPackOverview[]>` | `GET /compose/zap-packs`。动态的路由边（routing-edge）目录 —— 哪些代币可以在哪些链上被路由进哪些协议头寸。用它来发现有效的 `lifi.zap` `resourceOut` 目标。                                                                                                       |

```ts theme={"system"}
// Discover which tokens can be zapped into Aave positions.
const packs = await sdk.client.getZapPacks({ protocols: 'aave' });
for (const pack of packs) {
  for (const edge of pack.edges) {
    // edge.type ('enter-position' | 'exit-position' | …), edge.in, edge.out
  }
}
```

`getZapPacks` 接受一个可选的 `{ protocols?: string | readonly string[] }` 过滤器。结果不由 SDK 缓存 —— 请根据你的刷新需求自行缓存。参见[路由边目录](/composer/protocols-and-chains)以查看渲染后的实时视图。

## `ComposeCompileResult`

一个基于 `status` 字段的**判别联合（discriminated union）**。在访问特定结构的字段之前，先按 `result.status` 分支。

```ts theme={"system"}
type ComposeCompileResult =
  | (ComposeCompileSuccessData & { status: 'success' })
  | (ComposeCompilePartialData  & {
      status: 'partial';
      error: { kind: ComposeErrorKind; message: string };
      simulationRevert: SimulationRevert;
    });
```

* **`status: 'success'`** —— 在默认的 `simulationPolicy: 'strict'` 下，当 compile 与 simulation 都成功时返回。
* **`status: 'partial'`** —— 仅当运行时传入了 `simulationPolicy: 'allow-revert'` *且* 模拟发生了 revert 时返回。`transactionRequest` 仍然存在；revert 诊断信息被暴露出来供调用方呈现。

两种结构都携带核心字段：`transactionRequest`、`userProxy`、`producedResources`、`producedHandles`（任何标记为 `expose: true` 的输出句柄的值）、可选的 `approvals`、可选的 `priceImpact`，以及可选的 `fees`。

## `ComposeRunInput<T>`

声明于 [`run/inputs.ts`](https://unpkg.com/browse/@lifi/composer-sdk/src/run/inputs.ts)。

| Field                    | Type                                    | Notes                                                                                   |
| ------------------------ | --------------------------------------- | --------------------------------------------------------------------------------------- |
| `inputs`                 | `{ [K in keyof T]: InputSpecOf<T[K]> }` | 每个输入的值 —— `bigint`、十六进制字符串，或 materialiser 描述符。                                          |
| `signer`                 | `Address`                               | 以 `0x` 为前缀的签名者地址。                                                                       |
| `preconditions`          | `readonly Precondition[]?`              | 在执行前断言的不变量。                                                                             |
| `assumptions`            | `{ [K in keyof T]?: bigint }?`          | 当 materialiser 在执行时解析时所假定的金额。                                                           |
| `referrer`               | `string?`                               | 集成方 referrer id。                                                                        |
| `integratorFeeBps`       | `number?`                               | 以基点计的集成方费用（1bp = 0.01%，最大 `9000`）。默认为 `0`。非零值需要一个集成作用域的 API key —— 集成由 key 派生，而非由此字段派生。 |
| `maxPriceImpactBps`      | `number?`                               | 若聚合的美元价格影响超过上限则拒绝 compile。                                                              |
| `sweepTo`                | `SweepTo?`                              | 终端 proxy 持有资源的目的地。地址字面量或 `{ $ref: "context.sender" }`。                                  |
| `simulationPolicy`       | `"strict" \| "allow-revert"?`           | 默认 `"strict"`。                                                                          |
| `checkOnChainAllowances` | `boolean?`                              | 省略链上已满足的授权（approval）。                                                                   |

## Handles

声明于 [`authoring/handles.ts`](https://unpkg.com/browse/@lifi/composer-sdk/src/authoring/handles.ts)。

* **`InputHandle<T>`** —— `{ _tag: 'input', inputName, __outputKind?: T }`。以幻影类型参数（phantom type parameter）携带该输入的输出 kind。
* **`ResourceInputHandle`** —— `InputHandle<'resource'> & { resource: Resource }`。
* **`OutputHandle<T>`** —— `{ _tag: 'output', nodeId, portName, __outputKind?: T }`。
* **`Bindable<T>`** —— 类型化 bind 槽位所接受的值的联合：`InputHandle<T>`、`OutputHandle<T>`、`TypedRef<T>`。对于 `'uint256'` 槽位，`'resource'` 标记的句柄也被接受（资源即 uint256 金额）。

使用 `handleToRef`（从同一模块导出）将句柄转换为原始 ref。

## Namespaces

* **`resources`** —— 用于声明代币资源的辅助函数（`resources.erc20(token, chainId)`、`resources.native(chainId)`）。
* **`materialisers`** —— 为已注册 materialiser 生成的辅助函数（`materialisers.directDeposit({ amount })`、`materialisers.balanceOf({ ... })` 等）。
* **`guards`** —— 为已注册 guard 生成的辅助函数（`guards.slippage({ port, bps })` 等）。
* **`raw`** —— 低层应急出口：`raw.ref<T>(path)` 创建一个 `TypedRef<T>`；`raw.guard(kind, config?)` 为尚未被类型化辅助函数覆盖的 guard kind 构建一个 `AppliedGuard`；`raw.materialiser(kind, config?)` 出于同样原因构建一个 `MaterialiserInput`。

## `TypedFlow<T>`

`builder.build()` 返回的 Flow 文档。在结构上与来自 `@lifi/compose-spec` 的 `Flow` 完全相同，另带一个幻影 `__inputs?: T`，通过 TypeScript 推断携带输入 schema（`__inputs` 在运行时不存在）。

## Error types

`ComposeError`（从 `@lifi/compose-spec` 重新导出）携带：

```ts theme={"system"}
{
  kind: ComposeErrorKind;   // e.g. "validation_error" | "guard_error" | "simulation_revert" | …
  message: string;
  path?: string;
}
```

参见 [Error codes](/composer/composer-api/reference/error-codes) 了解完整目录以及每种 kind 映射到的 HTTP 状态。

## See also

* [Quickstart](/composer/composer-api/quickstart) —— 五分钟的首个 flow 讲解。
* [Build a Flow](/composer/composer-api/guides/build-a-flow) —— 生产环境的设置、输入、ops、materialisers、guards、preconditions 与提交。
* [Flow wire format](/composer/composer-api/reference/flow-wire-format) —— SDK 生成的 JSON。