@lifi/compose-spec 0.10.0 → 0.11.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/index.ts CHANGED
@@ -10,6 +10,9 @@ export type {
10
10
  Call,
11
11
  Flow,
12
12
  Lineage,
13
+ ForwardTo,
14
+ EpilogueForward,
15
+ Epilogue,
13
16
  } from './flowSchema.js';
14
17
  export {
15
18
  EVMAddressString,
@@ -26,11 +29,15 @@ export {
26
29
  AppliedGuardSchema,
27
30
  CallSchema,
28
31
  LineageSchema,
32
+ ForwardToSchema,
33
+ EpilogueForwardSchema,
34
+ EpilogueSchema,
29
35
  UuidSchema,
30
36
  } from './flowSchema.js';
31
37
 
32
38
  export type {
33
39
  ContinuationOutcome,
40
+ CommittedOutcome,
34
41
  ContinuationIntent,
35
42
  Phase1Artifact,
36
43
  AssertionOwner,
@@ -40,6 +47,7 @@ export {
40
47
  CONTINUATION_COMMITMENT_OP_ID,
41
48
  HexStringSchema,
42
49
  ContinuationOutcomeSchema,
50
+ CommittedOutcomeSchema,
43
51
  ContinuationIntentSchema,
44
52
  Phase1ArtifactSchema,
45
53
  AssertionOwnerSchema,
@@ -78,6 +86,9 @@ export type {
78
86
  GenericComposeErrorKind,
79
87
  PreparationComposeError,
80
88
  SimulationRevertComposeError,
89
+ DeliveryComposeError,
90
+ DeliveryErrorDetails,
91
+ DeliveryErrorReason,
81
92
  GenericComposeError,
82
93
  FailedPreparedOp,
83
94
  MaterialiserInputBase,
@@ -102,7 +113,13 @@ export {
102
113
  isMaterialiserInput,
103
114
  } from './flow.js';
104
115
 
105
- export type { Availability, OutputAmount, Resource } from './resource.js';
116
+ export type {
117
+ Availability,
118
+ ERC20Resource,
119
+ NativeResource,
120
+ OutputAmount,
121
+ Resource,
122
+ } from './resource.js';
106
123
  export {
107
124
  erc20Resource,
108
125
  erc20Token,
@@ -181,6 +198,7 @@ export type {
181
198
  ManifestGuard,
182
199
  ManifestMaterialiser,
183
200
  ManifestPrecondition,
201
+ ManifestRouting,
184
202
  GuardSelector,
185
203
  GuardCompatibility,
186
204
  } from './manifest.js';
@@ -210,13 +228,15 @@ export {
210
228
  } from './chainCapabilities.js';
211
229
 
212
230
  export type {
213
- SweepTo,
214
231
  ComposeRun,
215
232
  ComposeCompileRequest,
216
233
  ComposeCompileSuccessData,
234
+ ExecutedEpilogue,
235
+ ExecutedForward,
217
236
  ComposeFill,
218
237
  ComposeFee,
219
238
  ComposeUserProgramSimulation,
239
+ ComposeWarning,
220
240
  ComposeAction,
221
241
  PriceImpact,
222
242
  SpendEntry,
@@ -294,6 +314,7 @@ export {
294
314
  ManifestGuardZod,
295
315
  ManifestMaterialiserZod,
296
316
  ManifestPreconditionZod,
317
+ ManifestRoutingZod,
297
318
  ComposeManifestZod,
298
319
  GuardSelectorZod,
299
320
  GuardCompatibilityZod,
package/src/manifest.ts CHANGED
@@ -3,6 +3,7 @@ export type {
3
3
  ManifestGuard,
4
4
  ManifestMaterialiser,
5
5
  ManifestPrecondition,
6
+ ManifestRouting,
6
7
  ComposeManifest,
7
8
  GuardSelector,
8
9
  GuardCompatibility,
package/src/output.ts CHANGED
@@ -3,21 +3,25 @@ import type { Resource } from './resource.js';
3
3
  // The per-port `outputs` record on the compose compile response, keyed
4
4
  // `<nodeId>.<portName>`. One entry exists for every linear resource output
5
5
  // port in the flow, whether a later node spends it (`consumed`) or it is
6
- // delivered to `owner` (`terminal`). An entry is omitted only when its port
7
- // declares `omitIfZero` and the simulation measured it at zero. `estimate` is
8
- // the measured value when the simulation observed the port, otherwise the
9
- // prepared op's quote, otherwise absent. `minimum` is the enforced floor: the
10
- // larger of a guard floor and an op floor when either exists, tagged `guard`
11
- // only when the guard floor is strictly larger (`op` on a tie), else the
12
- // estimate echoed when the port declares `providesMinimum` (`declared`), else
13
- // absent. A port behind pure ops carries the floor those ops pass on from the
14
- // enforced floors and declared input amounts upstream, tagged by the same
15
- // rule. There is no zero placeholder; an absent `minimum` means no floor is
16
- // known.
6
+ // delivered to `owner` (`terminal`). A resource input no node spends is a
7
+ // `terminal` too, keyed `input.<name>` (`input` is a reserved ref scope, so
8
+ // the key cannot name a node's port): the proxy holds it and the epilogue
9
+ // forwards it. An entry is omitted only when its port declares `omitIfZero`
10
+ // and the simulation measured it at zero. `estimate` is the measured value
11
+ // when the simulation observed the port, otherwise the prepared op's quote,
12
+ // otherwise absent. `minimum` is the enforced floor: the larger of a guard
13
+ // floor and an op floor when either exists, tagged `guard` only when the
14
+ // guard floor is strictly larger (`op` on a tie), else the estimate echoed
15
+ // when the port declares `providesMinimum` (`declared`), else absent. A port
16
+ // behind pure ops carries the floor those ops pass on from the enforced
17
+ // floors and declared input amounts upstream, tagged by the same rule. An
18
+ // input terminal's floor is the input's bound amount or the floor its deposit
19
+ // asserts, tagged `input`. There is no zero placeholder; an absent `minimum`
20
+ // means no floor is known.
17
21
 
18
22
  export type EstimateBasis = 'simulated' | 'quoted';
19
23
 
20
- export type MinimumBasis = 'guard' | 'op' | 'declared';
24
+ export type MinimumBasis = 'guard' | 'op' | 'input' | 'declared';
21
25
 
22
26
  export interface Estimate {
23
27
  readonly basis: EstimateBasis;
@@ -39,13 +43,16 @@ export interface Amount {
39
43
  // published, never zero. `provider` is the key of the external system that
40
44
  // delivers them — for `lifi.bridge` the LI.FI tool key, which is the `bridge`
41
45
  // parameter of LI.FI's `/v1/status` lookup; absent when the op does not name
42
- // one.
46
+ // one. `trackingId` is the id the provider's status endpoint takes — for
47
+ // `lifi-intents` the order id, the `onChainOrderId` of the order server's
48
+ // `/orders/status`; absent when the provider does not know it at compile time.
43
49
  export type Delivery =
44
50
  | { readonly when: 'now' }
45
51
  | {
46
52
  readonly when: 'future';
47
53
  readonly etaSeconds?: number;
48
54
  readonly provider?: string;
55
+ readonly trackingId?: string;
49
56
  };
50
57
 
51
58
  interface OutputBase {
package/src/resource.ts CHANGED
@@ -7,13 +7,18 @@ export interface OutputAmount {
7
7
  readonly min?: bigint;
8
8
  }
9
9
 
10
- export type Resource =
11
- | { readonly kind: 'native'; readonly chainId: number }
12
- | {
13
- readonly kind: 'erc20';
14
- readonly token: string;
15
- readonly chainId: number;
16
- };
10
+ export interface NativeResource {
11
+ readonly kind: 'native';
12
+ readonly chainId: number;
13
+ }
14
+
15
+ export interface ERC20Resource {
16
+ readonly kind: 'erc20';
17
+ readonly token: string;
18
+ readonly chainId: number;
19
+ }
20
+
21
+ export type Resource = NativeResource | ERC20Resource;
17
22
 
18
23
  export const erc20Resource = (token: string, chainId: number): Resource => ({
19
24
  kind: 'erc20',
@@ -26,49 +31,57 @@ export const nativeResource = (chainId: number): Resource => ({
26
31
  chainId,
27
32
  });
28
33
 
29
- export const isERC20Resource = (
30
- r: Resource,
31
- ): r is Extract<Resource, { kind: 'erc20' }> => r.kind === 'erc20';
34
+ export const isERC20Resource = (r: Resource): r is ERC20Resource =>
35
+ r.kind === 'erc20';
32
36
 
33
- export const isNativeResource = (
34
- r: Resource,
35
- ): r is Extract<Resource, { kind: 'native' }> => r.kind === 'native';
37
+ export const isNativeResource = (r: Resource): r is NativeResource =>
38
+ r.kind === 'native';
36
39
 
40
+ // Both switches below have no `default`: a returning function that misses a
41
+ // kind fails to compile (TS2366), which lists every branch when `Resource`
42
+ // grows. compose-spec cannot import `assertNever` from `@lifi/utils`.
37
43
  export const resourcesEqual = (a: Resource, b: Resource): boolean => {
38
- if (isNativeResource(a) && isNativeResource(b)) {
39
- return a.chainId === b.chainId;
40
- }
41
- if (isERC20Resource(a) && isERC20Resource(b)) {
42
- return (
43
- a.chainId === b.chainId && a.token.toLowerCase() === b.token.toLowerCase()
44
- );
44
+ switch (a.kind) {
45
+ case 'native':
46
+ return b.kind === 'native' && a.chainId === b.chainId;
47
+ case 'erc20':
48
+ return (
49
+ b.kind === 'erc20' &&
50
+ a.chainId === b.chainId &&
51
+ a.token.toLowerCase() === b.token.toLowerCase()
52
+ );
45
53
  }
46
- return false;
47
54
  };
48
55
 
56
+ // Each arm receives the narrowed member, so a helper that only applies to one
57
+ // kind takes that member (`ERC20Resource`) rather than its spread fields.
49
58
  export const foldResource = <R>(
50
59
  r: Resource,
51
60
  cases: {
52
- readonly native: (chainId: number) => R;
53
- readonly erc20: (token: string, chainId: number) => R;
61
+ readonly native: (r: NativeResource) => R;
62
+ readonly erc20: (r: ERC20Resource) => R;
54
63
  },
55
- ): R =>
56
- r.kind === 'native'
57
- ? cases.native(r.chainId)
58
- : cases.erc20(r.token, r.chainId);
64
+ ): R => {
65
+ switch (r.kind) {
66
+ case 'native':
67
+ return cases.native(r);
68
+ case 'erc20':
69
+ return cases.erc20(r);
70
+ }
71
+ };
59
72
 
60
73
  // Canonical address representation of a resource for consumers whose wire
61
74
  // contract uses the EVM-native sentinel rather than the Resource union.
62
75
  export const resourceToken = (r: Resource): string =>
63
76
  foldResource(r, {
64
77
  native: () => EVM_NATIVE_SENTINEL,
65
- erc20: (token) => token,
78
+ erc20: ({ token }) => token,
66
79
  });
67
80
 
68
81
  export const resourceKey = (r: Resource): string =>
69
82
  foldResource(r, {
70
- native: (chainId) => `native:${chainId}`,
71
- erc20: (token, chainId) => `erc20:${token.toLowerCase()}:${chainId}`,
83
+ native: ({ chainId }) => `native:${chainId}`,
84
+ erc20: ({ token, chainId }) => `erc20:${token.toLowerCase()}:${chainId}`,
72
85
  });
73
86
 
74
87
  export const erc20Token = (r: Resource): string => {
package/src/route.ts CHANGED
@@ -32,7 +32,8 @@
32
32
  * if either side drifts.
33
33
  */
34
34
 
35
- import type { SimulationPolicy, SweepTo } from './compile.js';
35
+ import type { SimulationPolicy } from './compile.js';
36
+ import type { ForwardTo } from './flowSchema.js';
36
37
 
37
38
  /**
38
39
  * Spend an exact amount of `fromToken`.
@@ -135,7 +136,7 @@ export interface ComposeRouteRequest {
135
136
  * Accepts an address or `{ $ref: 'context.sender' }` (which counts as
136
137
  * explicit); `{ $ref: 'context.executionAddress' }` is rejected.
137
138
  */
138
- readonly sweepTo?: SweepTo;
139
+ readonly sweepTo?: ForwardTo;
139
140
  /**
140
141
  * `'strict'` (the default) fails the request when simulation detects a
141
142
  * revert; `'allow-revert'` returns a partial result with revert diagnostics
package/src/zodSchemas.ts CHANGED
@@ -181,6 +181,16 @@ export const ManifestPreconditionZod = z.object({
181
181
  configSchema: z.unknown().optional(),
182
182
  });
183
183
 
184
+ // The deployment's planning bounds for `POST /compose/route`. `maxRouteHops`
185
+ // is the hop ceiling, swap included; `1` means the deployment never chains.
186
+ // `swapHops` is where a planned route may contain an aggregator swap: only as
187
+ // its first hop (`head`), or nowhere (`none`). The bounds are necessary, not
188
+ // sufficient: a pair inside them can still return `no_route_error`.
189
+ export const ManifestRoutingZod = z.object({
190
+ maxRouteHops: z.number().int().min(1),
191
+ swapHops: z.enum(['head', 'none']),
192
+ });
193
+
184
194
  export const ComposeManifestZod = z.object({
185
195
  manifestVersion: z.number(),
186
196
  manifestHash: z.string(),
@@ -189,6 +199,11 @@ export const ComposeManifestZod = z.object({
189
199
  guards: z.array(ManifestGuardZod),
190
200
  materialisers: z.array(ManifestMaterialiserZod),
191
201
  preconditions: z.array(ManifestPreconditionZod).optional(),
202
+ // Deployment data, not catalog data: `GET /compose/manifest` sets it from
203
+ // compose 0.10.2 on, the static catalog manifest never does, and
204
+ // `manifestHash` does not cover it. Absent means unknown bounds, not a
205
+ // default: a client must not reject a pair on bounds it was not given.
206
+ routing: ManifestRoutingZod.optional(),
192
207
  });
193
208
 
194
209
  // Prefix-only `0x` check, mirroring `HexStringSchema`; used only by the escrow
@@ -207,6 +222,7 @@ export const SettlementEscrowZod = z.object({
207
222
  token: hexStringZod,
208
223
  amount: z.string(),
209
224
  cap: z.string(),
225
+ floor: z.string(),
210
226
  owner: hexStringZod,
211
227
  refund: hexStringZod,
212
228
  expiresAtMs: z.number().int().positive(),
@@ -336,6 +352,7 @@ export type GuardCompatibility = z.infer<typeof GuardCompatibilityZod>;
336
352
  export type ManifestGuard = z.infer<typeof ManifestGuardZod>;
337
353
  export type ManifestMaterialiser = z.infer<typeof ManifestMaterialiserZod>;
338
354
  export type ManifestPrecondition = z.infer<typeof ManifestPreconditionZod>;
355
+ export type ManifestRouting = z.infer<typeof ManifestRoutingZod>;
339
356
  export type ComposeManifest = z.infer<typeof ComposeManifestZod>;
340
357
  export type SettlementEscrowWire = z.infer<typeof SettlementEscrowZod>;
341
358
  export type SettlementWire = z.infer<typeof SettlementZod>;