@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 +1 -0
- package/dist/index.d.cts +59 -20
- package/dist/index.d.ts +59 -20
- package/dist/index.js +1 -0
- package/package.json +1 -1
- package/src/chainCapabilities.ts +15 -0
- package/src/compile.ts +4 -2
- package/src/flow.ts +10 -0
- package/src/materialiserMetadata.ts +6 -0
- package/src/route.ts +51 -20
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
|
|
2312
|
-
*
|
|
2313
|
-
* through the same compile pipeline as `POST /compose`.
|
|
2314
|
-
*
|
|
2315
|
-
* set
|
|
2316
|
-
*
|
|
2317
|
-
*
|
|
2318
|
-
*
|
|
2319
|
-
*
|
|
2320
|
-
*
|
|
2321
|
-
*
|
|
2322
|
-
* the
|
|
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
|
|
2388
|
-
*
|
|
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 ⇒
|
|
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
|
|
2406
|
-
*
|
|
2407
|
-
* `GET /compose/zap-packs`)
|
|
2408
|
-
*
|
|
2409
|
-
*
|
|
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
|
|
2312
|
-
*
|
|
2313
|
-
* through the same compile pipeline as `POST /compose`.
|
|
2314
|
-
*
|
|
2315
|
-
* set
|
|
2316
|
-
*
|
|
2317
|
-
*
|
|
2318
|
-
*
|
|
2319
|
-
*
|
|
2320
|
-
*
|
|
2321
|
-
*
|
|
2322
|
-
* the
|
|
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
|
|
2388
|
-
*
|
|
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 ⇒
|
|
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
|
|
2406
|
-
*
|
|
2407
|
-
* `GET /compose/zap-packs`)
|
|
2408
|
-
*
|
|
2409
|
-
*
|
|
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
package/src/chainCapabilities.ts
CHANGED
|
@@ -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
|
|
143
|
-
//
|
|
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
|
|
8
|
-
*
|
|
9
|
-
* through the same compile pipeline as `POST /compose`.
|
|
10
|
-
*
|
|
11
|
-
* set
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
* the
|
|
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
|
|
89
|
-
*
|
|
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 ⇒
|
|
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
|
|
107
|
-
*
|
|
108
|
-
* `GET /compose/zap-packs`)
|
|
109
|
-
*
|
|
110
|
-
*
|
|
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
|
}
|