@lifi/compose-spec 0.6.1 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -751,6 +751,7 @@ var checkCompatibility = (client, server, minimum = {
751
751
  var foldMaterialiserMetadata = (meta, cases) => {
752
752
  if (meta.kind === "exact") return cases.exact(meta.amount);
753
753
  if (meta.kind === "exact-native") return cases.exactNative(meta.amount);
754
+ if (meta.kind === "capped") return cases.capped(meta.amount);
754
755
  return cases.runtime();
755
756
  };
756
757
 
package/dist/index.d.cts CHANGED
@@ -1958,10 +1958,14 @@ interface FailedPreparedOp {
1958
1958
  readonly kind: GenericComposeErrorKind;
1959
1959
  readonly message: string;
1960
1960
  readonly path?: string;
1961
+ readonly port?: string;
1962
+ readonly fix?: string;
1961
1963
  }
1962
1964
  interface ComposeErrorBase {
1963
1965
  readonly message: string;
1964
1966
  readonly path?: string;
1967
+ readonly port?: string;
1968
+ readonly fix?: string;
1965
1969
  }
1966
1970
  interface PreparationComposeError extends ComposeErrorBase {
1967
1971
  readonly kind: 'preparation_error';
@@ -2308,18 +2312,21 @@ declare const normalizeNativeTokenAddress: (token: string, chainId: number) => s
2308
2312
  * format is always a decimal string, which the SDK serialises for you.
2309
2313
  *
2310
2314
  * `/compose/route` trades authoring power for brevity. Instead of a full flow
2311
- * document it takes a single from/to token pair; the server builds a one-node
2312
- * zap flow with a `directDeposit` input on the caller's behalf and runs it
2313
- * through the same compile pipeline as `POST /compose`. It routes through
2314
- * `lifi.zap` unless the pair is reachable only asynchronously and the request
2315
- * set `allowAsyncRoutes`, in which case it uses `lifi.zapAsync`. As of today
2316
- * the flow it builds is a single zap step — one edge of the server's routing
2317
- * catalog — and it is meant to author richer flows later, which this request
2318
- * shape is deliberately agnostic about. Its response body is byte-identical to
2319
- * that of `POST /compose` — the enveloped `ComposeCompileSuccessData` on HTTP
2320
- * 200 and `ComposeCompilePartialData` on HTTP 206 — so this file declares only
2321
- * the request shape and reuses `ComposeCompileResult` from `./compile.js` for
2322
- * the result.
2315
+ * document it takes a single from/to token pair; the server plans a route for
2316
+ * that pair, builds the flow with a `directDeposit` input on the caller's
2317
+ * behalf, and runs it through the same compile pipeline as `POST /compose`.
2318
+ * The route is the shortest admissible chain of routing-catalog edges up to an
2319
+ * operator-set hop ceiling, and may begin with an aggregator swap when the
2320
+ * catalog alone cannot connect the pair. Terminal hops route through
2321
+ * `lifi.zap`, or `lifi.zapAsync` when the pair is reachable only
2322
+ * asynchronously and the request set `allowAsyncRoutes`. The route itself is
2323
+ * not disclosed: node ids are `hop0`, `hop1`, … with the terminal always
2324
+ * `zap`, so `outputs['zap.amountOut']` is the terminal output at every route
2325
+ * length and intermediate outputs carry `role: 'consumed'`. Its response body
2326
+ * is byte-identical to that of `POST /compose` — the enveloped
2327
+ * `ComposeCompileSuccessData` on HTTP 200 and `ComposeCompilePartialData` on
2328
+ * HTTP 206 — so this file declares only the request shape and reuses
2329
+ * `ComposeCompileResult` from `./compile.js` for the result.
2323
2330
  *
2324
2331
  * These are the single source of truth for the request shape, hand-authored
2325
2332
  * here for the same reason as `./compile.ts` and `./simulate.ts` rather than
@@ -2358,6 +2365,15 @@ interface RouteAmountExact {
2358
2365
  * arrives via `msg.value`, so there is no on-chain balance to sweep, and the
2359
2366
  * server rejects the combination with a `validation_error`. Use
2360
2367
  * {@link RouteAmountExact} for native inputs.
2368
+ *
2369
+ * On a route that begins with an aggregator swap the swap's input amount is
2370
+ * pinned to the quoted amount derived from `simAmount` (net of any input fee
2371
+ * when fee injection applies): a runtime balance below that pinned amount
2372
+ * reverts, and a balance above it leaves the remainder as `unspentIn`, which
2373
+ * may be most of the input and which `sweepTo` receives. Under `EXACT` the
2374
+ * deposit and the pinned quote are the same number, so the `unspentIn` output
2375
+ * is zero and omitted; any pre-existing dust of the sold token in the proxy is
2376
+ * moved to `sweepTo` by the whole-balance sweep independently of that output.
2361
2377
  */
2362
2378
  interface RouteAmountAll {
2363
2379
  readonly type: 'ALL';
@@ -2384,13 +2400,18 @@ interface ComposeRouteRequest {
2384
2400
  /** Address that funds the route and, by default, owns its output. */
2385
2401
  readonly signer: string;
2386
2402
  /**
2387
- * Slippage tolerance in basis points, applied as a guard on the route's
2388
- * output. Range 0–10000. Defaults to `100` (1%) server-side when omitted.
2403
+ * Slippage tolerance in basis points. Range 0–10000. Defaults to `100` (1%)
2404
+ * server-side when omitted. It is an end-to-end tolerance: the floor is the
2405
+ * simulated final output of the whole route, so a multi-hop route is not
2406
+ * bounded hop by hop. When the route begins with an aggregator swap the same
2407
+ * value is also the swap's own tolerance, which nests inside the end-to-end
2408
+ * floor rather than compounding with it.
2389
2409
  */
2390
2410
  readonly slippageBps?: number;
2391
2411
  /**
2392
2412
  * Reject the route when its quoted price impact exceeds this many basis
2393
- * points. Range 0–10000. Omitted ⇒ no price-impact guard is installed.
2413
+ * points. Range 0–10000. Omitted ⇒ the server's default of 500 bps applies;
2414
+ * `0` disables the check.
2394
2415
  */
2395
2416
  readonly maxPriceImpactBps?: number;
2396
2417
  /**
@@ -2402,11 +2423,20 @@ interface ComposeRouteRequest {
2402
2423
  /** Opaque referrer tag forwarded to the underlying quote provider. */
2403
2424
  readonly referrer?: string;
2404
2425
  /**
2405
- * Owner of the route's output; defaults to `signer`. Routes whose protocol
2406
- * mints to a named receiver (surfaced as `recipient: 'required'` by
2407
- * `GET /compose/zap-packs`) bind this address at mint time rather than
2408
- * transferring afterwards. Accepts an address or `{ $ref: 'context.sender' }`;
2409
- * `{ $ref: 'context.executionAddress' }` is rejected.
2426
+ * Owner of every asset the route leaves behind; defaults to `signer` on a
2427
+ * route with no aggregator swap. Routes whose protocol mints to a named
2428
+ * receiver (surfaced as `recipient: 'required'` by `GET /compose/zap-packs`)
2429
+ * and asynchronous routes bind this address at mint time rather than
2430
+ * transferring afterwards; otherwise the proxy's whole balance of each
2431
+ * asset the route leaves is transferred here.
2432
+ *
2433
+ * **Required when the route includes an aggregator swap.** Such a route can
2434
+ * leave an asset the caller did not plan for — the swap's unspent input —
2435
+ * and this address receives it alongside the terminal output, so it must be
2436
+ * named explicitly; omitting it fails with `validation_error`.
2437
+ *
2438
+ * Accepts an address or `{ $ref: 'context.sender' }` (which counts as
2439
+ * explicit); `{ $ref: 'context.executionAddress' }` is rejected.
2410
2440
  */
2411
2441
  readonly sweepTo?: SweepTo;
2412
2442
  /**
@@ -2433,6 +2463,11 @@ interface ComposeRouteRequest {
2433
2463
  * opt-in. Defaults to `false` server-side, which leaves a pair reachable
2434
2464
  * only asynchronously rejected with `no_route_error` and guarantees every
2435
2465
  * terminal output is `delivery.when: 'now'`.
2466
+ *
2467
+ * It widens reach, it is not a preference: a synchronous route wins at any
2468
+ * length, so a pair with both a one-hop asynchronous edge and a longer
2469
+ * synchronous route is served synchronously. Opting in never costs you a
2470
+ * synchronous route.
2436
2471
  */
2437
2472
  readonly allowAsyncRoutes?: boolean;
2438
2473
  }
@@ -2683,6 +2718,9 @@ type MaterialiserMetadata = {
2683
2718
  } | {
2684
2719
  readonly kind: 'exact-native';
2685
2720
  readonly amount: bigint;
2721
+ } | {
2722
+ readonly kind: 'capped';
2723
+ readonly amount: bigint;
2686
2724
  } | {
2687
2725
  readonly kind: 'runtime';
2688
2726
  };
@@ -2693,6 +2731,7 @@ interface MaterialiserResolution {
2693
2731
  declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
2694
2732
  readonly exact: (amount: bigint) => R;
2695
2733
  readonly exactNative: (amount: bigint) => R;
2734
+ readonly capped: (amount: bigint) => R;
2696
2735
  readonly runtime: () => R;
2697
2736
  }) => R;
2698
2737
 
package/dist/index.d.ts CHANGED
@@ -1958,10 +1958,14 @@ interface FailedPreparedOp {
1958
1958
  readonly kind: GenericComposeErrorKind;
1959
1959
  readonly message: string;
1960
1960
  readonly path?: string;
1961
+ readonly port?: string;
1962
+ readonly fix?: string;
1961
1963
  }
1962
1964
  interface ComposeErrorBase {
1963
1965
  readonly message: string;
1964
1966
  readonly path?: string;
1967
+ readonly port?: string;
1968
+ readonly fix?: string;
1965
1969
  }
1966
1970
  interface PreparationComposeError extends ComposeErrorBase {
1967
1971
  readonly kind: 'preparation_error';
@@ -2308,18 +2312,21 @@ declare const normalizeNativeTokenAddress: (token: string, chainId: number) => s
2308
2312
  * format is always a decimal string, which the SDK serialises for you.
2309
2313
  *
2310
2314
  * `/compose/route` trades authoring power for brevity. Instead of a full flow
2311
- * document it takes a single from/to token pair; the server builds a one-node
2312
- * zap flow with a `directDeposit` input on the caller's behalf and runs it
2313
- * through the same compile pipeline as `POST /compose`. It routes through
2314
- * `lifi.zap` unless the pair is reachable only asynchronously and the request
2315
- * set `allowAsyncRoutes`, in which case it uses `lifi.zapAsync`. As of today
2316
- * the flow it builds is a single zap step — one edge of the server's routing
2317
- * catalog — and it is meant to author richer flows later, which this request
2318
- * shape is deliberately agnostic about. Its response body is byte-identical to
2319
- * that of `POST /compose` — the enveloped `ComposeCompileSuccessData` on HTTP
2320
- * 200 and `ComposeCompilePartialData` on HTTP 206 — so this file declares only
2321
- * the request shape and reuses `ComposeCompileResult` from `./compile.js` for
2322
- * the result.
2315
+ * document it takes a single from/to token pair; the server plans a route for
2316
+ * that pair, builds the flow with a `directDeposit` input on the caller's
2317
+ * behalf, and runs it through the same compile pipeline as `POST /compose`.
2318
+ * The route is the shortest admissible chain of routing-catalog edges up to an
2319
+ * operator-set hop ceiling, and may begin with an aggregator swap when the
2320
+ * catalog alone cannot connect the pair. Terminal hops route through
2321
+ * `lifi.zap`, or `lifi.zapAsync` when the pair is reachable only
2322
+ * asynchronously and the request set `allowAsyncRoutes`. The route itself is
2323
+ * not disclosed: node ids are `hop0`, `hop1`, … with the terminal always
2324
+ * `zap`, so `outputs['zap.amountOut']` is the terminal output at every route
2325
+ * length and intermediate outputs carry `role: 'consumed'`. Its response body
2326
+ * is byte-identical to that of `POST /compose` — the enveloped
2327
+ * `ComposeCompileSuccessData` on HTTP 200 and `ComposeCompilePartialData` on
2328
+ * HTTP 206 — so this file declares only the request shape and reuses
2329
+ * `ComposeCompileResult` from `./compile.js` for the result.
2323
2330
  *
2324
2331
  * These are the single source of truth for the request shape, hand-authored
2325
2332
  * here for the same reason as `./compile.ts` and `./simulate.ts` rather than
@@ -2358,6 +2365,15 @@ interface RouteAmountExact {
2358
2365
  * arrives via `msg.value`, so there is no on-chain balance to sweep, and the
2359
2366
  * server rejects the combination with a `validation_error`. Use
2360
2367
  * {@link RouteAmountExact} for native inputs.
2368
+ *
2369
+ * On a route that begins with an aggregator swap the swap's input amount is
2370
+ * pinned to the quoted amount derived from `simAmount` (net of any input fee
2371
+ * when fee injection applies): a runtime balance below that pinned amount
2372
+ * reverts, and a balance above it leaves the remainder as `unspentIn`, which
2373
+ * may be most of the input and which `sweepTo` receives. Under `EXACT` the
2374
+ * deposit and the pinned quote are the same number, so the `unspentIn` output
2375
+ * is zero and omitted; any pre-existing dust of the sold token in the proxy is
2376
+ * moved to `sweepTo` by the whole-balance sweep independently of that output.
2361
2377
  */
2362
2378
  interface RouteAmountAll {
2363
2379
  readonly type: 'ALL';
@@ -2384,13 +2400,18 @@ interface ComposeRouteRequest {
2384
2400
  /** Address that funds the route and, by default, owns its output. */
2385
2401
  readonly signer: string;
2386
2402
  /**
2387
- * Slippage tolerance in basis points, applied as a guard on the route's
2388
- * output. Range 0–10000. Defaults to `100` (1%) server-side when omitted.
2403
+ * Slippage tolerance in basis points. Range 0–10000. Defaults to `100` (1%)
2404
+ * server-side when omitted. It is an end-to-end tolerance: the floor is the
2405
+ * simulated final output of the whole route, so a multi-hop route is not
2406
+ * bounded hop by hop. When the route begins with an aggregator swap the same
2407
+ * value is also the swap's own tolerance, which nests inside the end-to-end
2408
+ * floor rather than compounding with it.
2389
2409
  */
2390
2410
  readonly slippageBps?: number;
2391
2411
  /**
2392
2412
  * Reject the route when its quoted price impact exceeds this many basis
2393
- * points. Range 0–10000. Omitted ⇒ no price-impact guard is installed.
2413
+ * points. Range 0–10000. Omitted ⇒ the server's default of 500 bps applies;
2414
+ * `0` disables the check.
2394
2415
  */
2395
2416
  readonly maxPriceImpactBps?: number;
2396
2417
  /**
@@ -2402,11 +2423,20 @@ interface ComposeRouteRequest {
2402
2423
  /** Opaque referrer tag forwarded to the underlying quote provider. */
2403
2424
  readonly referrer?: string;
2404
2425
  /**
2405
- * Owner of the route's output; defaults to `signer`. Routes whose protocol
2406
- * mints to a named receiver (surfaced as `recipient: 'required'` by
2407
- * `GET /compose/zap-packs`) bind this address at mint time rather than
2408
- * transferring afterwards. Accepts an address or `{ $ref: 'context.sender' }`;
2409
- * `{ $ref: 'context.executionAddress' }` is rejected.
2426
+ * Owner of every asset the route leaves behind; defaults to `signer` on a
2427
+ * route with no aggregator swap. Routes whose protocol mints to a named
2428
+ * receiver (surfaced as `recipient: 'required'` by `GET /compose/zap-packs`)
2429
+ * and asynchronous routes bind this address at mint time rather than
2430
+ * transferring afterwards; otherwise the proxy's whole balance of each
2431
+ * asset the route leaves is transferred here.
2432
+ *
2433
+ * **Required when the route includes an aggregator swap.** Such a route can
2434
+ * leave an asset the caller did not plan for — the swap's unspent input —
2435
+ * and this address receives it alongside the terminal output, so it must be
2436
+ * named explicitly; omitting it fails with `validation_error`.
2437
+ *
2438
+ * Accepts an address or `{ $ref: 'context.sender' }` (which counts as
2439
+ * explicit); `{ $ref: 'context.executionAddress' }` is rejected.
2410
2440
  */
2411
2441
  readonly sweepTo?: SweepTo;
2412
2442
  /**
@@ -2433,6 +2463,11 @@ interface ComposeRouteRequest {
2433
2463
  * opt-in. Defaults to `false` server-side, which leaves a pair reachable
2434
2464
  * only asynchronously rejected with `no_route_error` and guarantees every
2435
2465
  * terminal output is `delivery.when: 'now'`.
2466
+ *
2467
+ * It widens reach, it is not a preference: a synchronous route wins at any
2468
+ * length, so a pair with both a one-hop asynchronous edge and a longer
2469
+ * synchronous route is served synchronously. Opting in never costs you a
2470
+ * synchronous route.
2436
2471
  */
2437
2472
  readonly allowAsyncRoutes?: boolean;
2438
2473
  }
@@ -2683,6 +2718,9 @@ type MaterialiserMetadata = {
2683
2718
  } | {
2684
2719
  readonly kind: 'exact-native';
2685
2720
  readonly amount: bigint;
2721
+ } | {
2722
+ readonly kind: 'capped';
2723
+ readonly amount: bigint;
2686
2724
  } | {
2687
2725
  readonly kind: 'runtime';
2688
2726
  };
@@ -2693,6 +2731,7 @@ interface MaterialiserResolution {
2693
2731
  declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
2694
2732
  readonly exact: (amount: bigint) => R;
2695
2733
  readonly exactNative: (amount: bigint) => R;
2734
+ readonly capped: (amount: bigint) => R;
2696
2735
  readonly runtime: () => R;
2697
2736
  }) => R;
2698
2737
 
package/dist/index.js CHANGED
@@ -592,6 +592,7 @@ var checkCompatibility = (client, server, minimum = {
592
592
  var foldMaterialiserMetadata = (meta, cases) => {
593
593
  if (meta.kind === "exact") return cases.exact(meta.amount);
594
594
  if (meta.kind === "exact-native") return cases.exactNative(meta.amount);
595
+ if (meta.kind === "capped") return cases.capped(meta.amount);
595
596
  return cases.runtime();
596
597
  };
597
598
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lifi/compose-spec",
3
- "version": "0.6.1",
3
+ "version": "0.6.2",
4
4
  "description": "Public wire-format types and schemas for Compose flows",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -122,6 +122,21 @@ const REGISTRY: ReadonlyMap<number, ChainCapabilities> = new Map<
122
122
  ],
123
123
  ]);
124
124
 
125
+ /**
126
+ * Every chain with a non-default policy, in registration order. The registry
127
+ * itself stays private so runtime callers go through `getChainCapabilities`;
128
+ * this is the enumeration surface for tooling that must check *all* registered
129
+ * chains against an external source (the slot-finder parity spec), where
130
+ * scanning exported `*_CHAIN_ID` constants would silently miss a chain that
131
+ * skipped the naming convention.
132
+ *
133
+ * @internal Exported only so `chainCapabilitiesSlotFinderParity.spec.ts` can
134
+ * enumerate the registry. Not part of the package barrel.
135
+ */
136
+ export const registeredChainCapabilities = (): readonly ChainCapabilities[] => [
137
+ ...REGISTRY.values(),
138
+ ];
139
+
125
140
  export const getChainCapabilities = (chainId: number): ChainCapabilities =>
126
141
  REGISTRY.get(chainId) ?? { kind: 'evm-native', chainId };
127
142
 
package/src/compile.ts CHANGED
@@ -139,8 +139,10 @@ export interface ComposeUserProgramSimulation {
139
139
  // The solver-extractable fill (verified continuations, GD-8/GD-6, seam C5),
140
140
  // present on every compiled success. Hand-mirrored to api-schemas' `fill`
141
141
  // object (the OpenAPI source of truth; this package cannot depend on it).
142
- // `spends` is what the fill consumes per funding input; `validUntilMs` is the
143
- // fill freshness bound (earliest prepared-node expiry) — ABSENT = no expiry.
142
+ // `spends` is the amount the fill may spend of each funding input — the exact
143
+ // amount, or the pull cap of a non-exact deposit whose realised deposit is
144
+ // measured on-chain; `validUntilMs` is the fill freshness bound (earliest
145
+ // prepared-node expiry) — ABSENT = no expiry.
144
146
  // The fill is transaction-scoped; the leg-scoped C4 verification echo lives in
145
147
  // the sibling `verificationByNode` record.
146
148
  export interface ComposeFill {
package/src/flow.ts CHANGED
@@ -112,11 +112,21 @@ export interface FailedPreparedOp {
112
112
  readonly kind: GenericComposeErrorKind;
113
113
  readonly message: string;
114
114
  readonly path?: string;
115
+ readonly port?: string;
116
+ readonly fix?: string;
115
117
  }
116
118
 
119
+ // `path` names the node the rejection is about, `port` the bound input port
120
+ // when the rejection is about what that port binds, and `fix` the one action
121
+ // that clears it. A `continuation.settle` authoring rejection carries `path`
122
+ // and `fix`, plus `port` when it is about a bind; other `validation_error`s may
123
+ // omit `fix`. A deployment or internal fault carries none of the three, because
124
+ // no edit to the flow clears it.
117
125
  interface ComposeErrorBase {
118
126
  readonly message: string;
119
127
  readonly path?: string;
128
+ readonly port?: string;
129
+ readonly fix?: string;
120
130
  }
121
131
 
122
132
  export interface PreparationComposeError extends ComposeErrorBase {
@@ -3,6 +3,10 @@ import type { Precondition } from './flow.js';
3
3
  export type MaterialiserMetadata =
4
4
  | { readonly kind: 'exact'; readonly amount: bigint }
5
5
  | { readonly kind: 'exact-native'; readonly amount: bigint }
6
+ // The program pulls at most `amount` and consumes the measured result;
7
+ // `amount` is what an authoriser signs and what a spend report states, not
8
+ // what was deposited.
9
+ | { readonly kind: 'capped'; readonly amount: bigint }
6
10
  | { readonly kind: 'runtime' };
7
11
 
8
12
  export interface MaterialiserResolution {
@@ -15,10 +19,12 @@ export const foldMaterialiserMetadata = <R>(
15
19
  cases: {
16
20
  readonly exact: (amount: bigint) => R;
17
21
  readonly exactNative: (amount: bigint) => R;
22
+ readonly capped: (amount: bigint) => R;
18
23
  readonly runtime: () => R;
19
24
  },
20
25
  ): R => {
21
26
  if (meta.kind === 'exact') return cases.exact(meta.amount);
22
27
  if (meta.kind === 'exact-native') return cases.exactNative(meta.amount);
28
+ if (meta.kind === 'capped') return cases.capped(meta.amount);
23
29
  return cases.runtime();
24
30
  };
package/src/route.ts CHANGED
@@ -4,18 +4,21 @@
4
4
  * format is always a decimal string, which the SDK serialises for you.
5
5
  *
6
6
  * `/compose/route` trades authoring power for brevity. Instead of a full flow
7
- * document it takes a single from/to token pair; the server builds a one-node
8
- * zap flow with a `directDeposit` input on the caller's behalf and runs it
9
- * through the same compile pipeline as `POST /compose`. It routes through
10
- * `lifi.zap` unless the pair is reachable only asynchronously and the request
11
- * set `allowAsyncRoutes`, in which case it uses `lifi.zapAsync`. As of today
12
- * the flow it builds is a single zap step — one edge of the server's routing
13
- * catalog — and it is meant to author richer flows later, which this request
14
- * shape is deliberately agnostic about. Its response body is byte-identical to
15
- * that of `POST /compose` — the enveloped `ComposeCompileSuccessData` on HTTP
16
- * 200 and `ComposeCompilePartialData` on HTTP 206 — so this file declares only
17
- * the request shape and reuses `ComposeCompileResult` from `./compile.js` for
18
- * the result.
7
+ * document it takes a single from/to token pair; the server plans a route for
8
+ * that pair, builds the flow with a `directDeposit` input on the caller's
9
+ * behalf, and runs it through the same compile pipeline as `POST /compose`.
10
+ * The route is the shortest admissible chain of routing-catalog edges up to an
11
+ * operator-set hop ceiling, and may begin with an aggregator swap when the
12
+ * catalog alone cannot connect the pair. Terminal hops route through
13
+ * `lifi.zap`, or `lifi.zapAsync` when the pair is reachable only
14
+ * asynchronously and the request set `allowAsyncRoutes`. The route itself is
15
+ * not disclosed: node ids are `hop0`, `hop1`, … with the terminal always
16
+ * `zap`, so `outputs['zap.amountOut']` is the terminal output at every route
17
+ * length and intermediate outputs carry `role: 'consumed'`. Its response body
18
+ * is byte-identical to that of `POST /compose` — the enveloped
19
+ * `ComposeCompileSuccessData` on HTTP 200 and `ComposeCompilePartialData` on
20
+ * HTTP 206 — so this file declares only the request shape and reuses
21
+ * `ComposeCompileResult` from `./compile.js` for the result.
19
22
  *
20
23
  * These are the single source of truth for the request shape, hand-authored
21
24
  * here for the same reason as `./compile.ts` and `./simulate.ts` rather than
@@ -57,6 +60,15 @@ export interface RouteAmountExact {
57
60
  * arrives via `msg.value`, so there is no on-chain balance to sweep, and the
58
61
  * server rejects the combination with a `validation_error`. Use
59
62
  * {@link RouteAmountExact} for native inputs.
63
+ *
64
+ * On a route that begins with an aggregator swap the swap's input amount is
65
+ * pinned to the quoted amount derived from `simAmount` (net of any input fee
66
+ * when fee injection applies): a runtime balance below that pinned amount
67
+ * reverts, and a balance above it leaves the remainder as `unspentIn`, which
68
+ * may be most of the input and which `sweepTo` receives. Under `EXACT` the
69
+ * deposit and the pinned quote are the same number, so the `unspentIn` output
70
+ * is zero and omitted; any pre-existing dust of the sold token in the proxy is
71
+ * moved to `sweepTo` by the whole-balance sweep independently of that output.
60
72
  */
61
73
  export interface RouteAmountAll {
62
74
  readonly type: 'ALL';
@@ -85,13 +97,18 @@ export interface ComposeRouteRequest {
85
97
  /** Address that funds the route and, by default, owns its output. */
86
98
  readonly signer: string;
87
99
  /**
88
- * Slippage tolerance in basis points, applied as a guard on the route's
89
- * output. Range 0–10000. Defaults to `100` (1%) server-side when omitted.
100
+ * Slippage tolerance in basis points. Range 0–10000. Defaults to `100` (1%)
101
+ * server-side when omitted. It is an end-to-end tolerance: the floor is the
102
+ * simulated final output of the whole route, so a multi-hop route is not
103
+ * bounded hop by hop. When the route begins with an aggregator swap the same
104
+ * value is also the swap's own tolerance, which nests inside the end-to-end
105
+ * floor rather than compounding with it.
90
106
  */
91
107
  readonly slippageBps?: number;
92
108
  /**
93
109
  * Reject the route when its quoted price impact exceeds this many basis
94
- * points. Range 0–10000. Omitted ⇒ no price-impact guard is installed.
110
+ * points. Range 0–10000. Omitted ⇒ the server's default of 500 bps applies;
111
+ * `0` disables the check.
95
112
  */
96
113
  readonly maxPriceImpactBps?: number;
97
114
  /**
@@ -103,11 +120,20 @@ export interface ComposeRouteRequest {
103
120
  /** Opaque referrer tag forwarded to the underlying quote provider. */
104
121
  readonly referrer?: string;
105
122
  /**
106
- * Owner of the route's output; defaults to `signer`. Routes whose protocol
107
- * mints to a named receiver (surfaced as `recipient: 'required'` by
108
- * `GET /compose/zap-packs`) bind this address at mint time rather than
109
- * transferring afterwards. Accepts an address or `{ $ref: 'context.sender' }`;
110
- * `{ $ref: 'context.executionAddress' }` is rejected.
123
+ * Owner of every asset the route leaves behind; defaults to `signer` on a
124
+ * route with no aggregator swap. Routes whose protocol mints to a named
125
+ * receiver (surfaced as `recipient: 'required'` by `GET /compose/zap-packs`)
126
+ * and asynchronous routes bind this address at mint time rather than
127
+ * transferring afterwards; otherwise the proxy's whole balance of each
128
+ * asset the route leaves is transferred here.
129
+ *
130
+ * **Required when the route includes an aggregator swap.** Such a route can
131
+ * leave an asset the caller did not plan for — the swap's unspent input —
132
+ * and this address receives it alongside the terminal output, so it must be
133
+ * named explicitly; omitting it fails with `validation_error`.
134
+ *
135
+ * Accepts an address or `{ $ref: 'context.sender' }` (which counts as
136
+ * explicit); `{ $ref: 'context.executionAddress' }` is rejected.
111
137
  */
112
138
  readonly sweepTo?: SweepTo;
113
139
  /**
@@ -134,6 +160,11 @@ export interface ComposeRouteRequest {
134
160
  * opt-in. Defaults to `false` server-side, which leaves a pair reachable
135
161
  * only asynchronously rejected with `no_route_error` and guarantees every
136
162
  * terminal output is `delivery.when: 'now'`.
163
+ *
164
+ * It widens reach, it is not a preference: a synchronous route wins at any
165
+ * length, so a pair with both a one-hop asynchronous edge and a longer
166
+ * synchronous route is served synchronously. Opting in never costs you a
167
+ * synchronous route.
137
168
  */
138
169
  readonly allowAsyncRoutes?: boolean;
139
170
  }