SDK Reference

本页列举 @lifi/composer-sdk 的公共 API。如需权威的 TypeScript 类型，请浏览包源码 unpkg.com/browse/@lifi/composer-sdk。

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

`createComposeSdk(options)`

声明于 sdk.ts。

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 获取。
`fetch`	`typeof globalThis.fetch?`	默认为全局 `fetch`。

`ComposeSdk`

成员：

Member	Signature	Notes
`client`	`ComposeClient`	低层 HTTP 客户端（`compile`、`getManifest`、`getZapPacks`）。参见 `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`

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），并额外增加了每个 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。

`builder.compile(run)`

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

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

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

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

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

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、Materialisers 和 Guards 目录提供支撑的是同一来源。
`getZapPacks`	`(options?: GetZapPacksOptions) => Promise<readonly ZapPackOverview[]>`	`GET /compose/zap-packs`。动态的路由边（routing-edge）目录 —— 哪些代币可以在哪些链上被路由进哪些协议头寸。用它来发现有效的 `lifi.zap` `resourceOut` 目标。

// 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 缓存 —— 请根据你的刷新需求自行缓存。参见路由边目录以查看渲染后的实时视图。

`ComposeCompileResult`

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

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。

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。

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 重新导出）携带：

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

参见 Error codes 了解完整目录以及每种 kind 映射到的 HTTP 状态。

简介

通过 Composer API 集成

通过 LI.FI API 集成

资源

SDK Reference

`createComposeSdk(options)`

`ComposeSdkOptions`

`ComposeSdk`

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

`FlowOptions<T>`

`FlowBuilder<T>`

Inherited `FlowBuilderCore` members

Op methods

`builder.compile(run)`

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

`sdk.client`

`ComposeCompileResult`

`ComposeRunInput<T>`

Handles

Namespaces

`TypedFlow<T>`

Error types

See also

​createComposeSdk(options)

​ComposeSdkOptions

​ComposeSdk

​sdk.flow(chainId, options) → FlowBuilder

​FlowOptions<T>

​FlowBuilder<T>

​Inherited FlowBuilderCore members

​Op methods

​builder.compile(run)

​sdk.request(flow, run) → ComposeCompileRequest

​sdk.client

​ComposeCompileResult

​ComposeRunInput<T>

​Handles

​Namespaces

​TypedFlow<T>

​Error types

​See also

`createComposeSdk(options)`

`ComposeSdkOptions`

`ComposeSdk`

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

`FlowOptions<T>`

`FlowBuilder<T>`

Inherited `FlowBuilderCore` members

Op methods

`builder.compile(run)`

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

`sdk.client`

`ComposeCompileResult`

`ComposeRunInput<T>`

Handles

Namespaces

`TypedFlow<T>`

Error types

See also