@lifi/compose-spec 0.6.0 → 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/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
  }