@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.
- package/README.md +1 -1
- package/dist/index.cjs +89 -41
- package/dist/index.d.cts +266 -70
- package/dist/index.d.ts +266 -70
- package/dist/index.js +82 -38
- package/package.json +6 -13
- package/src/compile.ts +87 -21
- package/src/constructors.ts +106 -53
- package/src/continuation.ts +9 -9
- package/src/flow.ts +15 -1
- package/src/flowSchema.ts +0 -7
- package/src/index.ts +32 -6
- package/src/preconditions.ts +51 -0
- package/src/ref.ts +34 -1
- package/src/resource.ts +6 -1
- package/src/route.ts +139 -0
- package/src/simulate.ts +14 -23
- package/src/zodSchemas.ts +5 -13
package/src/constructors.ts
CHANGED
|
@@ -4,22 +4,17 @@ import type {
|
|
|
4
4
|
ResourceOutputPort,
|
|
5
5
|
ResourcePort,
|
|
6
6
|
} from './flow.js';
|
|
7
|
-
import type { HandleInput,
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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
|
-
|
|
63
|
-
|
|
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
|
-
|
|
72
|
-
|
|
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
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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 = <
|
|
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 & {
|
|
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
|
-
|
|
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
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
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 & {
|
|
185
|
+
} as ResourceOutputPort & {
|
|
186
|
+
readonly name: N;
|
|
187
|
+
readonly availability: OutputAvailability<O>;
|
|
188
|
+
};
|
|
136
189
|
};
|
package/src/continuation.ts
CHANGED
|
@@ -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
|
-
//
|
|
69
|
-
//
|
|
70
|
-
//
|
|
71
|
-
//
|
|
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 {
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
+
}
|