@lifi/compose-spec 0.4.0 → 0.4.1
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 +52 -8
- package/dist/index.d.cts +189 -36
- package/dist/index.d.ts +189 -36
- package/dist/index.js +46 -8
- package/package.json +4 -4
- package/src/constructors.ts +105 -46
- package/src/flow.ts +15 -1
- package/src/index.ts +20 -0
- package/src/preconditions.ts +51 -0
- package/src/ref.ts +1 -1
- package/src/resource.ts +1 -1
- package/src/route.ts +127 -0
- package/src/simulate.ts +14 -23
- package/src/zodSchemas.ts +1 -0
package/src/constructors.ts
CHANGED
|
@@ -9,9 +9,10 @@ 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
18
|
export const inputRef = (port: string): Ref => ({ $ref: `input.${port}` });
|
|
@@ -32,51 +33,54 @@ const optionalProp = <K extends string, V>(
|
|
|
32
33
|
export const linear = <N extends string, T extends SolType>(
|
|
33
34
|
name: N,
|
|
34
35
|
type: T,
|
|
35
|
-
): Port & { readonly name: N; readonly type: T; readonly mode: 'linear' } =>
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
36
|
+
): Port & { readonly name: N; readonly type: T; readonly mode: 'linear' } => ({
|
|
37
|
+
name,
|
|
38
|
+
type,
|
|
39
|
+
mode: 'linear',
|
|
40
|
+
availability: 'now',
|
|
41
|
+
});
|
|
41
42
|
|
|
42
43
|
export const copy = <N extends string, T extends SolType>(
|
|
43
44
|
name: N,
|
|
44
45
|
type: T,
|
|
45
|
-
): Port & { readonly name: N; readonly type: T; readonly mode: 'copy' } =>
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
46
|
+
): Port & { readonly name: N; readonly type: T; readonly mode: 'copy' } => ({
|
|
47
|
+
name,
|
|
48
|
+
type,
|
|
49
|
+
mode: 'copy',
|
|
50
|
+
availability: 'now',
|
|
51
|
+
});
|
|
51
52
|
|
|
52
53
|
export const handle = <N extends string, T extends SolType>(
|
|
53
54
|
name: N,
|
|
54
55
|
type: T,
|
|
55
|
-
): HandleInput & { readonly name: N; readonly type: T } =>
|
|
56
|
-
({ name, type }) as HandleInput & { readonly name: N; readonly type: T };
|
|
56
|
+
): HandleInput & { readonly name: N; readonly type: T } => ({ name, type });
|
|
57
57
|
|
|
58
58
|
export const native = <N extends string>(
|
|
59
59
|
name: N,
|
|
60
60
|
chainId: number,
|
|
61
|
-
): ResourceInput & { readonly name: N } =>
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
61
|
+
): ResourceInput & { readonly name: N } => ({
|
|
62
|
+
name,
|
|
63
|
+
resource: nativeResource(chainId),
|
|
64
|
+
});
|
|
65
65
|
|
|
66
66
|
export const erc20 = <N extends string>(
|
|
67
67
|
name: N,
|
|
68
68
|
token: string,
|
|
69
69
|
chainId: number,
|
|
70
|
-
): ResourceInput & { readonly name: N } =>
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
70
|
+
): ResourceInput & { readonly name: N } => ({
|
|
71
|
+
name,
|
|
72
|
+
resource: erc20Resource(token, chainId),
|
|
73
|
+
});
|
|
74
74
|
|
|
75
|
+
// `NoInfer` on the return type is load-bearing: these ports land in tuples
|
|
76
|
+
// contextually typed by `ResourcePort`/`HandlePort`, whose `optional?: boolean`
|
|
77
|
+
// would otherwise win the inference race and widen `Opt` to `boolean`,
|
|
78
|
+
// collapsing the optional-aware binding types downstream.
|
|
75
79
|
export const resource = <N extends string, Opt extends boolean = false>(
|
|
76
80
|
name: N,
|
|
77
81
|
accepts: 'erc20' | 'native' | 'any',
|
|
78
|
-
options?: { optional?: Opt },
|
|
79
|
-
): ResourcePort & { readonly name: N; readonly optional: Opt } =>
|
|
82
|
+
options?: { readonly optional?: Opt },
|
|
83
|
+
): ResourcePort & { readonly name: N; readonly optional: NoInfer<Opt> } =>
|
|
80
84
|
({
|
|
81
85
|
kind: 'resource',
|
|
82
86
|
name,
|
|
@@ -88,17 +92,26 @@ export const resource = <N extends string, Opt extends boolean = false>(
|
|
|
88
92
|
export const readResource = <N extends string>(
|
|
89
93
|
name: N,
|
|
90
94
|
accepts: 'erc20' | 'native' | 'any',
|
|
91
|
-
): ResourcePort & { readonly name: N; readonly mode: 'copy' } =>
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
95
|
+
): ResourcePort & { readonly name: N; readonly mode: 'copy' } => ({
|
|
96
|
+
kind: 'resource',
|
|
97
|
+
name,
|
|
98
|
+
accepts,
|
|
99
|
+
mode: 'copy',
|
|
100
|
+
});
|
|
96
101
|
|
|
97
|
-
export const opHandle = <
|
|
102
|
+
export const opHandle = <
|
|
103
|
+
N extends string,
|
|
104
|
+
T extends SolType,
|
|
105
|
+
Opt extends boolean = false,
|
|
106
|
+
>(
|
|
98
107
|
name: N,
|
|
99
108
|
type: T,
|
|
100
|
-
options?: OpHandleOptions
|
|
101
|
-
): HandlePort & {
|
|
109
|
+
options?: OpHandleOptions<Opt>,
|
|
110
|
+
): HandlePort & {
|
|
111
|
+
readonly name: N;
|
|
112
|
+
readonly type: T;
|
|
113
|
+
readonly optional: NoInfer<Opt>;
|
|
114
|
+
} =>
|
|
102
115
|
({
|
|
103
116
|
kind: 'handle',
|
|
104
117
|
name,
|
|
@@ -106,24 +119,67 @@ export const opHandle = <N extends string, T extends SolType>(
|
|
|
106
119
|
mode: 'copy',
|
|
107
120
|
...optionalProp('expose', options?.expose),
|
|
108
121
|
...optionalProp('units', options?.units),
|
|
122
|
+
...optionalProp('optional', options?.optional),
|
|
109
123
|
}) as HandlePort & {
|
|
110
124
|
readonly name: N;
|
|
111
125
|
readonly type: T;
|
|
126
|
+
readonly optional: Opt;
|
|
112
127
|
};
|
|
113
128
|
|
|
114
|
-
|
|
129
|
+
// Options accepted by `resourceOutput`: the bare `Availability` shorthand or
|
|
130
|
+
// the full record form.
|
|
131
|
+
type ResourceOutputOptions =
|
|
132
|
+
| Availability
|
|
133
|
+
| {
|
|
134
|
+
readonly availability?: Availability;
|
|
135
|
+
readonly providesMinimum?: boolean;
|
|
136
|
+
readonly omitIfZero?: boolean;
|
|
137
|
+
readonly deliveryAddressInput?: string;
|
|
138
|
+
};
|
|
139
|
+
|
|
140
|
+
// Resolve the *type-level* availability of a resource output from the options
|
|
141
|
+
// the caller passed. Preserving the availability literal is load-bearing:
|
|
142
|
+
// `defineOp` extracts the `'future'` port names from this literal, so widening
|
|
143
|
+
// it here would erase the future/now distinction the lowering contract needs.
|
|
144
|
+
//
|
|
145
|
+
// The runtime `availability` property may be ABSENT — the `'now'` cases omit it
|
|
146
|
+
// (see `optionalProp` below) because a missing availability already means
|
|
147
|
+
// `'now'` everywhere it is read. The type nonetheless reports `'now'`: a
|
|
148
|
+
// documented type-level fiction that treats the missing property as its
|
|
149
|
+
// effective value rather than surfacing `undefined`.
|
|
150
|
+
//
|
|
151
|
+
// A widened `Availability` value (neither literal) stays widened. It is not the
|
|
152
|
+
// `'future'` literal, so downstream treats it as non-future — a handle is
|
|
153
|
+
// required — which is the conservative choice (supplying a handle is always
|
|
154
|
+
// allowed).
|
|
155
|
+
type OutputAvailability<O> = [O] extends ['future']
|
|
156
|
+
? 'future'
|
|
157
|
+
: [O] extends ['now']
|
|
158
|
+
? 'now'
|
|
159
|
+
: [O] extends [string]
|
|
160
|
+
? Availability
|
|
161
|
+
: O extends { readonly availability: infer A }
|
|
162
|
+
? [A] extends ['future']
|
|
163
|
+
? 'future'
|
|
164
|
+
: [A] extends ['now']
|
|
165
|
+
? 'now'
|
|
166
|
+
: Availability
|
|
167
|
+
: 'now';
|
|
168
|
+
|
|
169
|
+
export const resourceOutput = <
|
|
170
|
+
N extends string,
|
|
171
|
+
const O extends ResourceOutputOptions = 'now',
|
|
172
|
+
>(
|
|
115
173
|
name: N,
|
|
116
|
-
options?:
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
const opts =
|
|
126
|
-
typeof options === 'string' ? { availability: options } : options;
|
|
174
|
+
options?: O,
|
|
175
|
+
): ResourceOutputPort & {
|
|
176
|
+
readonly name: N;
|
|
177
|
+
readonly availability: OutputAvailability<O>;
|
|
178
|
+
} => {
|
|
179
|
+
// Widen away the generic before narrowing: `typeof` cannot narrow a value
|
|
180
|
+
// of generic type `O`, so the union members would keep their string arms.
|
|
181
|
+
const raw: ResourceOutputOptions | undefined = options;
|
|
182
|
+
const opts = typeof raw === 'string' ? { availability: raw } : raw;
|
|
127
183
|
return {
|
|
128
184
|
kind: 'resource_output',
|
|
129
185
|
name,
|
|
@@ -132,5 +188,8 @@ export const resourceOutput = <N extends string>(
|
|
|
132
188
|
...optionalProp('providesMinimum', opts?.providesMinimum),
|
|
133
189
|
...optionalProp('omitIfZero', opts?.omitIfZero),
|
|
134
190
|
...optionalProp('deliveryAddressInput', opts?.deliveryAddressInput),
|
|
135
|
-
} as ResourceOutputPort & {
|
|
191
|
+
} as ResourceOutputPort & {
|
|
192
|
+
readonly name: N;
|
|
193
|
+
readonly availability: OutputAvailability<O>;
|
|
194
|
+
};
|
|
136
195
|
};
|
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/index.ts
CHANGED
|
@@ -101,6 +101,7 @@ export {
|
|
|
101
101
|
isResourcePort,
|
|
102
102
|
isHandlePort,
|
|
103
103
|
isResourceOutputPort,
|
|
104
|
+
isFutureResourceOutput,
|
|
104
105
|
isMaterialiserInput,
|
|
105
106
|
} from './flow.js';
|
|
106
107
|
|
|
@@ -197,6 +198,13 @@ export type {
|
|
|
197
198
|
ComposeCompileResult,
|
|
198
199
|
} from './compile.js';
|
|
199
200
|
|
|
201
|
+
export type {
|
|
202
|
+
RouteAmountExact,
|
|
203
|
+
RouteAmountAll,
|
|
204
|
+
RouteAmount,
|
|
205
|
+
ComposeRouteRequest,
|
|
206
|
+
} from './route.js';
|
|
207
|
+
|
|
200
208
|
export type {
|
|
201
209
|
TrackedBalance,
|
|
202
210
|
Erc20BalanceRequirement,
|
|
@@ -211,6 +219,18 @@ export type {
|
|
|
211
219
|
SimulateSetupErrorResult,
|
|
212
220
|
SimulateResult,
|
|
213
221
|
} from './simulate.js';
|
|
222
|
+
export type {
|
|
223
|
+
Erc20BalancePrecondition,
|
|
224
|
+
NativeBalancePrecondition,
|
|
225
|
+
Erc20AllowancePrecondition,
|
|
226
|
+
} from './preconditions.js';
|
|
227
|
+
export {
|
|
228
|
+
erc20Balance,
|
|
229
|
+
nativeBalance,
|
|
230
|
+
erc20Allowance,
|
|
231
|
+
isErc20AllowancePrecondition,
|
|
232
|
+
isNativeBalancePrecondition,
|
|
233
|
+
} from './preconditions.js';
|
|
214
234
|
export {
|
|
215
235
|
SIMULATE_MAX_TRACKED_BALANCES,
|
|
216
236
|
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('.');
|
package/src/resource.ts
CHANGED
package/src/route.ts
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
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
|
|
8
|
+
* `lifi.zap` flow with a `directDeposit` input on the caller's behalf and runs
|
|
9
|
+
* it through the same compile pipeline as `POST /compose`. As of today the flow
|
|
10
|
+
* it builds is a single zap step — one edge of the server's routing catalog —
|
|
11
|
+
* and it is meant to author richer flows later, which this request shape is
|
|
12
|
+
* deliberately agnostic about. Its response body is byte-identical to that of
|
|
13
|
+
* `POST /compose` — the enveloped `ComposeCompileSuccessData` on HTTP 200 and
|
|
14
|
+
* `ComposeCompilePartialData` on HTTP 206 — so this file declares only the
|
|
15
|
+
* request shape and reuses `ComposeCompileResult` from `./compile.js` for the
|
|
16
|
+
* result.
|
|
17
|
+
*
|
|
18
|
+
* These are the single source of truth for the request shape, hand-authored
|
|
19
|
+
* here for the same reason as `./compile.ts` and `./simulate.ts` rather than
|
|
20
|
+
* derived from the validating schema: that schema is the Zod one in
|
|
21
|
+
* `@lifi/api-schemas` (`src/routes/composeRoute.ts`), a package that depends on
|
|
22
|
+
* this one, so importing its inferred types here would invert the dependency —
|
|
23
|
+
* and the public SDK ships this package as its only peer dependency, never the
|
|
24
|
+
* server's schema package. The two definitions are held in lockstep by a
|
|
25
|
+
* compile-time conformance assertion
|
|
26
|
+
* (`api-schemas/src/routes/composeRoute.typecheck.ts`), which fails the build
|
|
27
|
+
* if either side drifts.
|
|
28
|
+
*/
|
|
29
|
+
|
|
30
|
+
import type { SimulationPolicy, SweepTo } from './compile.js';
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Spend an exact amount of `fromToken`.
|
|
34
|
+
*
|
|
35
|
+
* `amount` is in the token's smallest unit. Accepts `bigint | string`; the wire
|
|
36
|
+
* format is a non-negative decimal string.
|
|
37
|
+
*/
|
|
38
|
+
export interface RouteAmountExact {
|
|
39
|
+
readonly type: 'EXACT';
|
|
40
|
+
readonly amount: bigint | string;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Spend the signer's entire `fromToken` balance, whatever it is at execution
|
|
45
|
+
* time.
|
|
46
|
+
*
|
|
47
|
+
* The on-chain amount is resolved by a deposit-all materialiser, so it is not
|
|
48
|
+
* known when the route is compiled. `simAmount` is the stand-in the server
|
|
49
|
+
* quotes and simulates against — make it a realistic estimate of the balance,
|
|
50
|
+
* because it determines the quote and the derived preconditions, not the amount
|
|
51
|
+
* actually moved. Accepts `bigint | string`; the wire format is a non-negative
|
|
52
|
+
* decimal string.
|
|
53
|
+
*
|
|
54
|
+
* Not supported when `fromToken` is the chain's native sentinel: a gas coin
|
|
55
|
+
* arrives via `msg.value`, so there is no on-chain balance to sweep, and the
|
|
56
|
+
* server rejects the combination with a `validation_error`. Use
|
|
57
|
+
* {@link RouteAmountExact} for native inputs.
|
|
58
|
+
*/
|
|
59
|
+
export interface RouteAmountAll {
|
|
60
|
+
readonly type: 'ALL';
|
|
61
|
+
readonly simAmount: bigint | string;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* How much of `fromToken` a route spends. Two variants, discriminated by
|
|
66
|
+
* `type`.
|
|
67
|
+
*/
|
|
68
|
+
export type RouteAmount = RouteAmountExact | RouteAmountAll;
|
|
69
|
+
|
|
70
|
+
/** Request body for `POST /compose/route`. */
|
|
71
|
+
export interface ComposeRouteRequest {
|
|
72
|
+
/** EVM chain id. Both tokens must live on this chain — routes are same-chain. */
|
|
73
|
+
readonly chainId: number;
|
|
74
|
+
/**
|
|
75
|
+
* Token to spend. Use the chain's native sentinel address for the gas coin
|
|
76
|
+
* (the zero address on EVM-native chains).
|
|
77
|
+
*/
|
|
78
|
+
readonly fromToken: string;
|
|
79
|
+
/** Token to receive. */
|
|
80
|
+
readonly toToken: string;
|
|
81
|
+
/** How much of `fromToken` to spend — an exact amount or the whole balance. */
|
|
82
|
+
readonly amount: RouteAmount;
|
|
83
|
+
/** Address that funds the route and, by default, owns its output. */
|
|
84
|
+
readonly signer: string;
|
|
85
|
+
/**
|
|
86
|
+
* Slippage tolerance in basis points, applied as a guard on the route's
|
|
87
|
+
* output. Range 0–10000. Defaults to `100` (1%) server-side when omitted.
|
|
88
|
+
*/
|
|
89
|
+
readonly slippageBps?: number;
|
|
90
|
+
/**
|
|
91
|
+
* Reject the route when its quoted price impact exceeds this many basis
|
|
92
|
+
* points. Range 0–10000. Omitted ⇒ no price-impact guard is installed.
|
|
93
|
+
*/
|
|
94
|
+
readonly maxPriceImpactBps?: number;
|
|
95
|
+
/**
|
|
96
|
+
* Integrator fee in basis points, taken from the input amount. Range 0–9000.
|
|
97
|
+
* Defaults to `0` server-side when omitted. A non-zero value requires an
|
|
98
|
+
* integration-scoped API key; the server rejects it otherwise.
|
|
99
|
+
*/
|
|
100
|
+
readonly integratorFeeBps?: number;
|
|
101
|
+
/** Opaque referrer tag forwarded to the underlying quote provider. */
|
|
102
|
+
readonly referrer?: string;
|
|
103
|
+
/**
|
|
104
|
+
* Owner of the route's output; defaults to `signer`. Routes whose protocol
|
|
105
|
+
* mints to a named receiver (surfaced as `recipient: 'required'` by
|
|
106
|
+
* `GET /compose/zap-packs`) bind this address at mint time rather than
|
|
107
|
+
* transferring afterwards. Accepts an address or `{ $ref: 'context.sender' }`;
|
|
108
|
+
* `{ $ref: 'context.executionAddress' }` is rejected.
|
|
109
|
+
*/
|
|
110
|
+
readonly sweepTo?: SweepTo;
|
|
111
|
+
/**
|
|
112
|
+
* `'strict'` (the default) fails the request when simulation detects a
|
|
113
|
+
* revert; `'allow-revert'` returns a partial result with revert diagnostics
|
|
114
|
+
* instead.
|
|
115
|
+
*/
|
|
116
|
+
readonly simulationPolicy?: SimulationPolicy;
|
|
117
|
+
/**
|
|
118
|
+
* Also simulate the final user-facing transaction after the structured
|
|
119
|
+
* simulation succeeds. Reverts honour `simulationPolicy`. Defaults to `false`.
|
|
120
|
+
*/
|
|
121
|
+
readonly simulateUserProgram?: boolean;
|
|
122
|
+
/**
|
|
123
|
+
* Filter the returned `approvals` against current on-chain allowances,
|
|
124
|
+
* omitting approvals that are already sufficient. Defaults to `false`.
|
|
125
|
+
*/
|
|
126
|
+
readonly checkOnChainAllowances?: boolean;
|
|
127
|
+
}
|
package/src/simulate.ts
CHANGED
|
@@ -16,6 +16,12 @@
|
|
|
16
16
|
* Mirrors the hand-authored style of `src/compile.ts`.
|
|
17
17
|
*/
|
|
18
18
|
|
|
19
|
+
import type {
|
|
20
|
+
Erc20AllowancePrecondition,
|
|
21
|
+
Erc20BalancePrecondition,
|
|
22
|
+
NativeBalancePrecondition,
|
|
23
|
+
} from './preconditions.js';
|
|
24
|
+
|
|
19
25
|
/**
|
|
20
26
|
* Maximum number of watched `(token, owner)` pairs accepted by `POST /simulate`.
|
|
21
27
|
*
|
|
@@ -47,33 +53,18 @@ export interface TrackedBalance {
|
|
|
47
53
|
readonly owner: string;
|
|
48
54
|
}
|
|
49
55
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
*/
|
|
55
|
-
export
|
|
56
|
-
readonly type: 'Erc20Balance';
|
|
57
|
-
readonly wallet: string;
|
|
58
|
-
readonly token: string;
|
|
59
|
-
readonly balance: bigint | string;
|
|
60
|
-
}
|
|
56
|
+
// The funding instructions are the precondition shapes themselves: what the
|
|
57
|
+
// simulator seeds is exactly what a compile declared. See `preconditions.ts`
|
|
58
|
+
// for the canonical definitions and constructors.
|
|
59
|
+
|
|
60
|
+
/** Funding instruction: seed an ERC-20 balance on a wallet before simulation. */
|
|
61
|
+
export type Erc20BalanceRequirement = Erc20BalancePrecondition;
|
|
61
62
|
|
|
62
63
|
/** Funding instruction: seed a native balance on a wallet before simulation. */
|
|
63
|
-
export
|
|
64
|
-
readonly type: 'NativeBalance';
|
|
65
|
-
readonly wallet: string;
|
|
66
|
-
readonly balance: bigint | string;
|
|
67
|
-
}
|
|
64
|
+
export type NativeBalanceRequirement = NativeBalancePrecondition;
|
|
68
65
|
|
|
69
66
|
/** Funding instruction: seed an ERC-20 allowance before simulation. */
|
|
70
|
-
export
|
|
71
|
-
readonly type: 'Erc20Allowance';
|
|
72
|
-
readonly owner: string;
|
|
73
|
-
readonly spender: string;
|
|
74
|
-
readonly token: string;
|
|
75
|
-
readonly allowance: bigint | string;
|
|
76
|
-
}
|
|
67
|
+
export type Erc20AllowanceRequirement = Erc20AllowancePrecondition;
|
|
77
68
|
|
|
78
69
|
/**
|
|
79
70
|
* The funding-instruction union applied before a simulation. Three variants,
|
package/src/zodSchemas.ts
CHANGED