@lifi/compose-spec 0.4.0 → 0.5.0

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.
@@ -4,22 +4,17 @@ import type {
4
4
  ResourceOutputPort,
5
5
  ResourcePort,
6
6
  } from './flow.js';
7
- import type { HandleInput, Ref, ResourceInput, SolType } from './flowSchema.js';
7
+ import type { HandleInput, ResourceInput, SolType } from './flowSchema.js';
8
8
  import type { Availability } from './resource.js';
9
9
  import { erc20Resource, nativeResource } from './resource.js';
10
10
  import type { HandleUnits } from './zodSchemas.js';
11
11
 
12
- export interface OpHandleOptions {
12
+ export interface OpHandleOptions<Opt extends boolean = boolean> {
13
13
  readonly expose?: boolean;
14
14
  readonly units?: HandleUnits;
15
+ readonly optional?: Opt;
15
16
  }
16
17
 
17
- export const inputRef = (port: string): Ref => ({ $ref: `input.${port}` });
18
-
19
- export const outputRef = (node: string, port: string): Ref => ({
20
- $ref: `${node}.${port}`,
21
- });
22
-
23
18
  /** Returns `{ [key]: value }` when `value` is not nullish, else `{}`. */
24
19
  const optionalProp = <K extends string, V>(
25
20
  key: K,
@@ -32,51 +27,54 @@ const optionalProp = <K extends string, V>(
32
27
  export const linear = <N extends string, T extends SolType>(
33
28
  name: N,
34
29
  type: T,
35
- ): Port & { readonly name: N; readonly type: T; readonly mode: 'linear' } =>
36
- ({ name, type, mode: 'linear', availability: 'now' }) as Port & {
37
- readonly name: N;
38
- readonly type: T;
39
- readonly mode: 'linear';
40
- };
30
+ ): Port & { readonly name: N; readonly type: T; readonly mode: 'linear' } => ({
31
+ name,
32
+ type,
33
+ mode: 'linear',
34
+ availability: 'now',
35
+ });
41
36
 
42
37
  export const copy = <N extends string, T extends SolType>(
43
38
  name: N,
44
39
  type: T,
45
- ): Port & { readonly name: N; readonly type: T; readonly mode: 'copy' } =>
46
- ({ name, type, mode: 'copy', availability: 'now' }) as Port & {
47
- readonly name: N;
48
- readonly type: T;
49
- readonly mode: 'copy';
50
- };
40
+ ): Port & { readonly name: N; readonly type: T; readonly mode: 'copy' } => ({
41
+ name,
42
+ type,
43
+ mode: 'copy',
44
+ availability: 'now',
45
+ });
51
46
 
52
47
  export const handle = <N extends string, T extends SolType>(
53
48
  name: N,
54
49
  type: T,
55
- ): HandleInput & { readonly name: N; readonly type: T } =>
56
- ({ name, type }) as HandleInput & { readonly name: N; readonly type: T };
50
+ ): HandleInput & { readonly name: N; readonly type: T } => ({ name, type });
57
51
 
58
52
  export const native = <N extends string>(
59
53
  name: N,
60
54
  chainId: number,
61
- ): ResourceInput & { readonly name: N } =>
62
- ({ name, resource: nativeResource(chainId) }) as ResourceInput & {
63
- readonly name: N;
64
- };
55
+ ): ResourceInput & { readonly name: N } => ({
56
+ name,
57
+ resource: nativeResource(chainId),
58
+ });
65
59
 
66
60
  export const erc20 = <N extends string>(
67
61
  name: N,
68
62
  token: string,
69
63
  chainId: number,
70
- ): ResourceInput & { readonly name: N } =>
71
- ({ name, resource: erc20Resource(token, chainId) }) as ResourceInput & {
72
- readonly name: N;
73
- };
64
+ ): ResourceInput & { readonly name: N } => ({
65
+ name,
66
+ resource: erc20Resource(token, chainId),
67
+ });
74
68
 
69
+ // `NoInfer` on the return type is load-bearing: these ports land in tuples
70
+ // contextually typed by `ResourcePort`/`HandlePort`, whose `optional?: boolean`
71
+ // would otherwise win the inference race and widen `Opt` to `boolean`,
72
+ // collapsing the optional-aware binding types downstream.
75
73
  export const resource = <N extends string, Opt extends boolean = false>(
76
74
  name: N,
77
75
  accepts: 'erc20' | 'native' | 'any',
78
- options?: { optional?: Opt },
79
- ): ResourcePort & { readonly name: N; readonly optional: Opt } =>
76
+ options?: { readonly optional?: Opt },
77
+ ): ResourcePort & { readonly name: N; readonly optional: NoInfer<Opt> } =>
80
78
  ({
81
79
  kind: 'resource',
82
80
  name,
@@ -88,17 +86,26 @@ export const resource = <N extends string, Opt extends boolean = false>(
88
86
  export const readResource = <N extends string>(
89
87
  name: N,
90
88
  accepts: 'erc20' | 'native' | 'any',
91
- ): ResourcePort & { readonly name: N; readonly mode: 'copy' } =>
92
- ({ kind: 'resource', name, accepts, mode: 'copy' }) as ResourcePort & {
93
- readonly name: N;
94
- readonly mode: 'copy';
95
- };
89
+ ): ResourcePort & { readonly name: N; readonly mode: 'copy' } => ({
90
+ kind: 'resource',
91
+ name,
92
+ accepts,
93
+ mode: 'copy',
94
+ });
96
95
 
97
- export const opHandle = <N extends string, T extends SolType>(
96
+ export const opHandle = <
97
+ N extends string,
98
+ T extends SolType,
99
+ Opt extends boolean = false,
100
+ >(
98
101
  name: N,
99
102
  type: T,
100
- options?: OpHandleOptions,
101
- ): HandlePort & { readonly name: N; readonly type: T } =>
103
+ options?: OpHandleOptions<Opt>,
104
+ ): HandlePort & {
105
+ readonly name: N;
106
+ readonly type: T;
107
+ readonly optional: NoInfer<Opt>;
108
+ } =>
102
109
  ({
103
110
  kind: 'handle',
104
111
  name,
@@ -106,24 +113,67 @@ export const opHandle = <N extends string, T extends SolType>(
106
113
  mode: 'copy',
107
114
  ...optionalProp('expose', options?.expose),
108
115
  ...optionalProp('units', options?.units),
116
+ ...optionalProp('optional', options?.optional),
109
117
  }) as HandlePort & {
110
118
  readonly name: N;
111
119
  readonly type: T;
120
+ readonly optional: Opt;
112
121
  };
113
122
 
114
- export const resourceOutput = <N extends string>(
123
+ // Options accepted by `resourceOutput`: the bare `Availability` shorthand or
124
+ // the full record form.
125
+ type ResourceOutputOptions =
126
+ | Availability
127
+ | {
128
+ readonly availability?: Availability;
129
+ readonly providesMinimum?: boolean;
130
+ readonly omitIfZero?: boolean;
131
+ readonly deliveryAddressInput?: string;
132
+ };
133
+
134
+ // Resolve the *type-level* availability of a resource output from the options
135
+ // the caller passed. Preserving the availability literal is load-bearing:
136
+ // `defineOp` extracts the `'future'` port names from this literal, so widening
137
+ // it here would erase the future/now distinction the lowering contract needs.
138
+ //
139
+ // The runtime `availability` property may be ABSENT — the `'now'` cases omit it
140
+ // (see `optionalProp` below) because a missing availability already means
141
+ // `'now'` everywhere it is read. The type nonetheless reports `'now'`: a
142
+ // documented type-level fiction that treats the missing property as its
143
+ // effective value rather than surfacing `undefined`.
144
+ //
145
+ // A widened `Availability` value (neither literal) stays widened. It is not the
146
+ // `'future'` literal, so downstream treats it as non-future — a handle is
147
+ // required — which is the conservative choice (supplying a handle is always
148
+ // allowed).
149
+ type OutputAvailability<O> = [O] extends ['future']
150
+ ? 'future'
151
+ : [O] extends ['now']
152
+ ? 'now'
153
+ : [O] extends [string]
154
+ ? Availability
155
+ : O extends { readonly availability: infer A }
156
+ ? [A] extends ['future']
157
+ ? 'future'
158
+ : [A] extends ['now']
159
+ ? 'now'
160
+ : Availability
161
+ : 'now';
162
+
163
+ export const resourceOutput = <
164
+ N extends string,
165
+ const O extends ResourceOutputOptions = 'now',
166
+ >(
115
167
  name: N,
116
- options?:
117
- | Availability
118
- | {
119
- availability?: Availability;
120
- providesMinimum?: boolean;
121
- omitIfZero?: boolean;
122
- deliveryAddressInput?: string;
123
- },
124
- ): ResourceOutputPort & { readonly name: N } => {
125
- const opts =
126
- typeof options === 'string' ? { availability: options } : options;
168
+ options?: O,
169
+ ): ResourceOutputPort & {
170
+ readonly name: N;
171
+ readonly availability: OutputAvailability<O>;
172
+ } => {
173
+ // Widen away the generic before narrowing: `typeof` cannot narrow a value
174
+ // of generic type `O`, so the union members would keep their string arms.
175
+ const raw: ResourceOutputOptions | undefined = options;
176
+ const opts = typeof raw === 'string' ? { availability: raw } : raw;
127
177
  return {
128
178
  kind: 'resource_output',
129
179
  name,
@@ -132,5 +182,8 @@ export const resourceOutput = <N extends string>(
132
182
  ...optionalProp('providesMinimum', opts?.providesMinimum),
133
183
  ...optionalProp('omitIfZero', opts?.omitIfZero),
134
184
  ...optionalProp('deliveryAddressInput', opts?.deliveryAddressInput),
135
- } as ResourceOutputPort & { readonly name: N };
185
+ } as ResourceOutputPort & {
186
+ readonly name: N;
187
+ readonly availability: OutputAvailability<O>;
188
+ };
136
189
  };
@@ -63,25 +63,25 @@ export const ContinuationIntentSchema = Schema.Struct({
63
63
  validity: Schema.Struct({ expiresAtMs: Schema.Number }),
64
64
  perpetual: Schema.optional(Schema.Boolean),
65
65
  provider: Schema.optional(Schema.String),
66
+ // Funding-path mode. The HTTP wire contract is documented by
67
+ // `ComposeActionsSchema` in `@lifi/api-schemas`.
68
+ funding: Schema.optional(Schema.Literal('inline', 'external')),
66
69
  });
67
70
 
68
- // The phase-1 action a client must take after compiling a deferred flow.
69
- //
70
- // - `transaction` — a funding transaction (fund an escrow / call a protocol
71
- // open). Usually the client funds via the main response-level
72
- // `transactionRequest`; a venue whose phase-1 tx differs may instead emit an
73
- // explicit `transactionRequest` override here.
74
- // - `signables` — EIP-712 order(s) to sign (for signed-order venues; not
75
- // produced in v1, defined for the seam).
76
- // - `none` — nothing to sign now.
71
+ // Internal phase-1 artifact. The HTTP layer projects `transaction` artifacts
72
+ // to metadata and publishes real external-funding calldata through
73
+ // `ComposeActionsSchema`. The internal `transactionRequest` remains optional
74
+ // because inline funding and dry runs do not produce a submittable transfer.
77
75
  export const Phase1ArtifactSchema = Schema.Union(
78
76
  Schema.Struct({
79
77
  kind: Schema.Literal('transaction'),
78
+ funding: Schema.Literal('inline', 'external'),
80
79
  transactionRequest: Schema.optional(
81
80
  Schema.Struct({
82
81
  to: Schema.String,
83
82
  data: Schema.String,
84
83
  value: Schema.String,
84
+ chainId: Schema.Number,
85
85
  }),
86
86
  ),
87
87
  }),
package/src/flow.ts CHANGED
@@ -48,6 +48,15 @@ export const isResourceOutputPort = (
48
48
  port: OpInputPort | OpOutputPort,
49
49
  ): port is ResourceOutputPort => port.kind === 'resource_output';
50
50
 
51
+ // A resource output whose value becomes available only after the initiating
52
+ // transaction settles. Absence of `availability` means `'now'`, so the check is
53
+ // a direct comparison against the one non-default mode. Every site that asks
54
+ // "is this port's value delivered later?" goes through here, so a rename of the
55
+ // property or a new availability mode lands in one place.
56
+ export const isFutureResourceOutput = (
57
+ port: OpInputPort | OpOutputPort,
58
+ ): boolean => isResourceOutputPort(port) && port.availability === 'future';
59
+
51
60
  export type ComposeErrorKind =
52
61
  | 'decode_error'
53
62
  | 'validation_error'
@@ -57,10 +66,13 @@ export type ComposeErrorKind =
57
66
  | 'provider_error'
58
67
  | 'no_route_error'
59
68
  | 'resolution_error'
69
+ | 'resolution_rejected'
60
70
  | 'lowering_error'
61
71
  | 'empty_program'
62
72
  | 'simulation_error'
63
73
  | 'simulation_setup_error'
74
+ | 'simulation_insufficient_funds'
75
+ | 'simulation_gas_limit'
64
76
  | 'simulation_rpc_error'
65
77
  | 'simulation_revert'
66
78
  | 'subgraph_simulation_revert'
@@ -71,7 +83,9 @@ export type ComposeErrorKind =
71
83
  | 'price_impact_exceeded'
72
84
  | 'fee_resolution_error'
73
85
  | 'fee_resolution_unavailable'
74
- | 'flashloan_unauthorized';
86
+ | 'flashloan_unauthorized'
87
+ // The request exceeded its wall-clock budget and was cancelled mid-flight.
88
+ | 'deadline_exceeded';
75
89
 
76
90
  export type GenericComposeErrorKind = Exclude<
77
91
  ComposeErrorKind,
package/src/flowSchema.ts CHANGED
@@ -112,18 +112,12 @@ export const CallSchema = Schema.Struct({
112
112
  guards: Schema.optional(Schema.Array(AppliedGuardSchema)),
113
113
  });
114
114
 
115
- export const ContinuationSchema = Schema.Struct({
116
- awaits: Schema.String,
117
- flowId: Schema.String,
118
- });
119
-
120
115
  export const FlowSchema = Schema.Struct({
121
116
  version: Schema.Literal(1),
122
117
  id: Schema.String,
123
118
  chainId: ChainIdSchema,
124
119
  inputs: Schema.Array(FlowInputSchema),
125
120
  nodes: Schema.Array(CallSchema),
126
- continuations: Schema.optional(Schema.Array(ContinuationSchema)),
127
121
  });
128
122
 
129
123
  export type SolType = typeof SolTypeSchema.Type;
@@ -135,5 +129,4 @@ export type LiteralBinding = typeof LiteralBindingSchema.Type;
135
129
  export type BindValue = typeof BindValueSchema.Type;
136
130
  export type AppliedGuard = typeof AppliedGuardSchema.Type;
137
131
  export type Call = typeof CallSchema.Type;
138
- export type Continuation = typeof ContinuationSchema.Type;
139
132
  export type Flow = typeof FlowSchema.Type;
package/src/index.ts CHANGED
@@ -8,7 +8,6 @@ export type {
8
8
  BindValue,
9
9
  AppliedGuard,
10
10
  Call,
11
- Continuation,
12
11
  Flow,
13
12
  } from './flowSchema.js';
14
13
  export {
@@ -23,7 +22,6 @@ export {
23
22
  BindValueSchema,
24
23
  AppliedGuardSchema,
25
24
  CallSchema,
26
- ContinuationSchema,
27
25
  } from './flowSchema.js';
28
26
 
29
27
  export type {
@@ -101,6 +99,7 @@ export {
101
99
  isResourcePort,
102
100
  isHandlePort,
103
101
  isResourceOutputPort,
102
+ isFutureResourceOutput,
104
103
  isMaterialiserInput,
105
104
  } from './flow.js';
106
105
 
@@ -143,12 +142,17 @@ export {
143
142
  readResource,
144
143
  opHandle,
145
144
  resourceOutput,
146
- inputRef,
147
- outputRef,
148
145
  } from './constructors.js';
149
146
 
150
- export type { ParsedRef, RefScope, ContextKey } from './ref.js';
147
+ export type {
148
+ ParsedRef,
149
+ RefScope,
150
+ ContextKey,
151
+ RefPath,
152
+ RefBuilder,
153
+ } from './ref.js';
151
154
  export {
155
+ ref,
152
156
  parseRef,
153
157
  foldRef,
154
158
  refKey,
@@ -186,7 +190,10 @@ export type {
186
190
  ComposeRun,
187
191
  ComposeCompileRequest,
188
192
  ComposeCompileSuccessData,
189
- ComposeContinuation,
193
+ ComposeFill,
194
+ ComposeFee,
195
+ ComposeUserProgramSimulation,
196
+ ComposeAction,
190
197
  PriceImpact,
191
198
  SpendEntry,
192
199
  SimulationPolicy,
@@ -197,6 +204,13 @@ export type {
197
204
  ComposeCompileResult,
198
205
  } from './compile.js';
199
206
 
207
+ export type {
208
+ RouteAmountExact,
209
+ RouteAmountAll,
210
+ RouteAmount,
211
+ ComposeRouteRequest,
212
+ } from './route.js';
213
+
200
214
  export type {
201
215
  TrackedBalance,
202
216
  Erc20BalanceRequirement,
@@ -211,6 +225,18 @@ export type {
211
225
  SimulateSetupErrorResult,
212
226
  SimulateResult,
213
227
  } from './simulate.js';
228
+ export type {
229
+ Erc20BalancePrecondition,
230
+ NativeBalancePrecondition,
231
+ Erc20AllowancePrecondition,
232
+ } from './preconditions.js';
233
+ export {
234
+ erc20Balance,
235
+ nativeBalance,
236
+ erc20Allowance,
237
+ isErc20AllowancePrecondition,
238
+ isNativeBalancePrecondition,
239
+ } from './preconditions.js';
214
240
  export {
215
241
  SIMULATE_MAX_TRACKED_BALANCES,
216
242
  SIMULATE_MAX_REQUIREMENTS,
@@ -0,0 +1,51 @@
1
+ import type { Precondition } from './flow.js';
2
+
3
+ /**
4
+ * The three concrete precondition shapes the stack exchanges today. One
5
+ * definition serves every producer and consumer: op/materialiser declarations,
6
+ * `rewritePreconditions`, the simulator's funding requirements (`simulate.ts`
7
+ * aliases these as `*Requirement`), and the zap-backend approval derivation.
8
+ *
9
+ * Amounts accept `bigint | string`: the SDK serialises `bigint` to a decimal
10
+ * string; the string side covers values already stringified.
11
+ */
12
+ export type Erc20BalancePrecondition = {
13
+ readonly type: 'Erc20Balance';
14
+ readonly wallet: string;
15
+ readonly token: string;
16
+ readonly balance: bigint | string;
17
+ };
18
+
19
+ export type NativeBalancePrecondition = {
20
+ readonly type: 'NativeBalance';
21
+ readonly wallet: string;
22
+ readonly balance: bigint | string;
23
+ };
24
+
25
+ export type Erc20AllowancePrecondition = {
26
+ readonly type: 'Erc20Allowance';
27
+ readonly owner: string;
28
+ readonly spender: string;
29
+ readonly token: string;
30
+ readonly allowance: bigint | string;
31
+ };
32
+
33
+ export const erc20Balance = (
34
+ config: Omit<Erc20BalancePrecondition, 'type'>,
35
+ ): Erc20BalancePrecondition => ({ type: 'Erc20Balance', ...config });
36
+
37
+ export const nativeBalance = (
38
+ config: Omit<NativeBalancePrecondition, 'type'>,
39
+ ): NativeBalancePrecondition => ({ type: 'NativeBalance', ...config });
40
+
41
+ export const erc20Allowance = (
42
+ config: Omit<Erc20AllowancePrecondition, 'type'>,
43
+ ): Erc20AllowancePrecondition => ({ type: 'Erc20Allowance', ...config });
44
+
45
+ export const isErc20AllowancePrecondition = (
46
+ p: Precondition,
47
+ ): p is Erc20AllowancePrecondition => p.type === 'Erc20Allowance';
48
+
49
+ export const isNativeBalancePrecondition = (
50
+ p: Precondition,
51
+ ): p is NativeBalancePrecondition => p.type === 'NativeBalance';
package/src/ref.ts CHANGED
@@ -28,7 +28,7 @@ export const isRef = (v: unknown): v is Ref =>
28
28
  typeof v === 'object' &&
29
29
  v !== null &&
30
30
  '$ref' in v &&
31
- typeof (v as { $ref: unknown }).$ref === 'string';
31
+ typeof v.$ref === 'string';
32
32
 
33
33
  export const parseRef = (ref: Ref): ParsedRef => {
34
34
  const dot = ref.$ref.indexOf('.');
@@ -45,6 +45,39 @@ export const parseRef = (ref: Ref): ParsedRef => {
45
45
  return { scope: 'output', node: prefix, port: suffix };
46
46
  };
47
47
 
48
+ /** A ref path: a dotpath such as `input.amount` or `nodeId.port`. */
49
+ export type RefPath = `${string}.${string}`;
50
+
51
+ const buildRef = (path: RefPath): Ref => {
52
+ if (path.indexOf('.') < 1)
53
+ throw new Error(
54
+ `Invalid ref: "${path}" (must be a dotpath like "input.name" or "nodeId.port")`,
55
+ );
56
+ const built: Ref = { $ref: path };
57
+ parseRef(built); // rejects an unknown `context.*` key
58
+ return built;
59
+ };
60
+
61
+ /**
62
+ * Builds a bind ref. `ref.input(port)` for a flow input, `ref.context.*` for a
63
+ * context ref, and a dotpath for a node output (`ref('deposit.shares')`).
64
+ * Prefer the named forms: `parseRef` reads an unrecognised prefix as a node id,
65
+ * so a misspelled `input.`/`context.` silently becomes an output ref.
66
+ */
67
+ export interface RefBuilder {
68
+ (path: RefPath): Ref;
69
+ input(port: string): Ref;
70
+ readonly context: { readonly [K in ContextKey]: Ref };
71
+ }
72
+
73
+ export const ref: RefBuilder = Object.assign(buildRef, {
74
+ input: (port: string): Ref => buildRef(`input.${port}`),
75
+ context: {
76
+ sender: buildRef('context.sender'),
77
+ executionAddress: buildRef('context.executionAddress'),
78
+ },
79
+ });
80
+
48
81
  export const foldRef = <R>(
49
82
  ref: ParsedRef,
50
83
  cases: {
package/src/resource.ts CHANGED
@@ -17,13 +17,18 @@ export type Resource =
17
17
 
18
18
  export type SimulatedAmounts = {
19
19
  readonly amountOut: bigint;
20
- readonly amountOutMin: bigint;
20
+ readonly amountOutMin?: bigint;
21
21
  };
22
22
 
23
23
  export type ProducedResource = Resource & {
24
24
  readonly availability: Availability;
25
25
  readonly simulated?: SimulatedAmounts;
26
26
  readonly owner: string;
27
+ // Wire ETA: seconds until deferred proceeds land, echoed from the routing edge
28
+ // that produced this output. Only valid alongside `availability: 'future'`;
29
+ // absent means no published estimate, never zero. See "ETA" in
30
+ // `docs/glossary.md` (COM-1564).
31
+ readonly etaSeconds?: number;
27
32
  };
28
33
 
29
34
  export const erc20Resource = (token: string, chainId: number): Resource => ({
package/src/route.ts ADDED
@@ -0,0 +1,139 @@
1
+ /**
2
+ * Canonical request types for the `POST /compose/route` convenience endpoint.
3
+ * Amounts accept `bigint | string` for authoring convenience; the JSON wire
4
+ * format is always a decimal string, which the SDK serialises for you.
5
+ *
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.
19
+ *
20
+ * These are the single source of truth for the request shape, hand-authored
21
+ * here for the same reason as `./compile.ts` and `./simulate.ts` rather than
22
+ * derived from the validating schema: that schema is the Zod one in
23
+ * `@lifi/api-schemas` (`src/routes/composeRoute.ts`), a package that depends on
24
+ * this one, so importing its inferred types here would invert the dependency —
25
+ * and the public SDK ships this package as its only peer dependency, never the
26
+ * server's schema package. The two definitions are held in lockstep by a
27
+ * compile-time conformance assertion
28
+ * (`api-schemas/src/routes/composeRoute.typecheck.ts`), which fails the build
29
+ * if either side drifts.
30
+ */
31
+
32
+ import type { SimulationPolicy, SweepTo } from './compile.js';
33
+
34
+ /**
35
+ * Spend an exact amount of `fromToken`.
36
+ *
37
+ * `amount` is in the token's smallest unit. Accepts `bigint | string`; the wire
38
+ * format is a non-negative decimal string.
39
+ */
40
+ export interface RouteAmountExact {
41
+ readonly type: 'EXACT';
42
+ readonly amount: bigint | string;
43
+ }
44
+
45
+ /**
46
+ * Spend the signer's entire `fromToken` balance, whatever it is at execution
47
+ * time.
48
+ *
49
+ * The on-chain amount is resolved by a deposit-all materialiser, so it is not
50
+ * known when the route is compiled. `simAmount` is the stand-in the server
51
+ * quotes and simulates against — make it a realistic estimate of the balance,
52
+ * because it determines the quote and the derived preconditions, not the amount
53
+ * actually moved. Accepts `bigint | string`; the wire format is a non-negative
54
+ * decimal string.
55
+ *
56
+ * Not supported when `fromToken` is the chain's native sentinel: a gas coin
57
+ * arrives via `msg.value`, so there is no on-chain balance to sweep, and the
58
+ * server rejects the combination with a `validation_error`. Use
59
+ * {@link RouteAmountExact} for native inputs.
60
+ */
61
+ export interface RouteAmountAll {
62
+ readonly type: 'ALL';
63
+ readonly simAmount: bigint | string;
64
+ }
65
+
66
+ /**
67
+ * How much of `fromToken` a route spends. Two variants, discriminated by
68
+ * `type`.
69
+ */
70
+ export type RouteAmount = RouteAmountExact | RouteAmountAll;
71
+
72
+ /** Request body for `POST /compose/route`. */
73
+ export interface ComposeRouteRequest {
74
+ /** EVM chain id. Both tokens must live on this chain — routes are same-chain. */
75
+ readonly chainId: number;
76
+ /**
77
+ * Token to spend. Use the chain's native sentinel address for the gas coin
78
+ * (the zero address on EVM-native chains).
79
+ */
80
+ readonly fromToken: string;
81
+ /** Token to receive. */
82
+ readonly toToken: string;
83
+ /** How much of `fromToken` to spend — an exact amount or the whole balance. */
84
+ readonly amount: RouteAmount;
85
+ /** Address that funds the route and, by default, owns its output. */
86
+ readonly signer: string;
87
+ /**
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.
90
+ */
91
+ readonly slippageBps?: number;
92
+ /**
93
+ * Reject the route when its quoted price impact exceeds this many basis
94
+ * points. Range 0–10000. Omitted ⇒ no price-impact guard is installed.
95
+ */
96
+ readonly maxPriceImpactBps?: number;
97
+ /**
98
+ * Integrator fee in basis points, taken from the input amount. Range 0–9000.
99
+ * Defaults to `0` server-side when omitted. A non-zero value requires an
100
+ * integration-scoped API key; the server rejects it otherwise.
101
+ */
102
+ readonly integratorFeeBps?: number;
103
+ /** Opaque referrer tag forwarded to the underlying quote provider. */
104
+ readonly referrer?: string;
105
+ /**
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.
111
+ */
112
+ readonly sweepTo?: SweepTo;
113
+ /**
114
+ * `'strict'` (the default) fails the request when simulation detects a
115
+ * revert; `'allow-revert'` returns a partial result with revert diagnostics
116
+ * instead.
117
+ */
118
+ readonly simulationPolicy?: SimulationPolicy;
119
+ /**
120
+ * Also simulate the final user-facing transaction after the structured
121
+ * simulation succeeds. Reverts honour `simulationPolicy`. Defaults to `false`.
122
+ */
123
+ readonly simulateUserProgram?: boolean;
124
+ /**
125
+ * Filter the returned `approvals` against current on-chain allowances,
126
+ * omitting approvals that are already sufficient. Defaults to `false`.
127
+ */
128
+ readonly checkOnChainAllowances?: boolean;
129
+ /**
130
+ * Accept a route whose output is delivered only after the initiating
131
+ * transaction settles (`availability: 'future'` on the produced resource).
132
+ * Such a route obliges you to track settlement rather than treat the
133
+ * transaction as completing the job, and carries no slippage floor, so it is
134
+ * opt-in. Defaults to `false` server-side, which leaves a pair reachable
135
+ * only asynchronously rejected with `no_route_error` and guarantees every
136
+ * produced resource is `availability: 'now'`.
137
+ */
138
+ readonly allowAsyncRoutes?: boolean;
139
+ }