@lifi/compose-spec 0.10.0 → 0.12.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/src/flowSchema.ts CHANGED
@@ -4,7 +4,6 @@ import { normalizeResource } from './chainCapabilities.js';
4
4
  import {
5
5
  DECIMAL_UINT,
6
6
  EVM_ADDRESS_HEX,
7
- HEX_BYTES,
8
7
  MAX_DATE_MS,
9
8
  MAX_UINT256,
10
9
  } from './hexPatterns.js';
@@ -44,17 +43,6 @@ export const EVMAddressString = Schema.String.pipe(
44
43
  description: 'EVM address: 0x followed by 40 hex characters',
45
44
  });
46
45
 
47
- // Whole-byte hex payload (`0x` + an even number of hex digits). Stricter than
48
- // builtins' `HexDataString`, which keeps odd-length acceptance for op configs:
49
- // see `HEX_BYTES`.
50
- export const HexBytesString = Schema.String.pipe(
51
- Schema.pattern(HEX_BYTES, {
52
- message: () => 'expected 0x-prefixed hex of whole bytes',
53
- }),
54
- ).annotations({
55
- description: 'Hex bytes: 0x followed by an even number of hex characters',
56
- });
57
-
58
46
  // An epoch-millisecond timestamp a `Date` can represent. Pure and
59
47
  // clock-independent, so it holds at decode; whether it is still in the future
60
48
  // is the consumer's registration-time check.
@@ -215,6 +203,28 @@ export const LineageSchema = Schema.Struct({
215
203
  parentRequestId: UuidSchema,
216
204
  });
217
205
 
206
+ // Where a post-graph forward sends a balance: a literal address or a ref the
207
+ // compiler resolves. The compiler admits `context.sender` only.
208
+ export const ForwardToSchema = Schema.Union(EVMAddressString, RefSchema);
209
+
210
+ export const EpilogueForwardSchema = Schema.Struct({
211
+ resource: ResourceSchema,
212
+ to: ForwardToSchema,
213
+ });
214
+
215
+ // The flow's post-graph forwards, run after the last node. A named forward
216
+ // moves the proxy's whole balance of one resource to one address; the
217
+ // remainder moves every other proxy-held terminal resource to one address.
218
+ // `run.sweepTo: X` is sugar for `{ remainder: X }`.
219
+ export const EpilogueSchema = Schema.Struct({
220
+ forwards: Schema.optional(Schema.NonEmptyArray(EpilogueForwardSchema)),
221
+ remainder: Schema.optional(ForwardToSchema),
222
+ }).pipe(
223
+ Schema.filter((e) => e.forwards !== undefined || e.remainder !== undefined, {
224
+ message: () => 'epilogue needs forwards, a remainder, or both',
225
+ }),
226
+ );
227
+
218
228
  export const FlowSchema = Schema.Struct({
219
229
  version: Schema.Literal(1),
220
230
  id: Schema.String,
@@ -222,6 +232,7 @@ export const FlowSchema = Schema.Struct({
222
232
  inputs: Schema.Array(FlowInputSchema),
223
233
  nodes: Schema.Array(CallSchema),
224
234
  lineage: Schema.optional(LineageSchema),
235
+ epilogue: Schema.optional(EpilogueSchema),
225
236
  });
226
237
 
227
238
  export type SolType = typeof SolTypeSchema.Type;
@@ -234,4 +245,7 @@ export type BindValue = typeof BindValueSchema.Type;
234
245
  export type AppliedGuard = typeof AppliedGuardSchema.Type;
235
246
  export type Call = typeof CallSchema.Type;
236
247
  export type Lineage = typeof LineageSchema.Type;
248
+ export type ForwardTo = typeof ForwardToSchema.Type;
249
+ export type EpilogueForward = typeof EpilogueForwardSchema.Type;
250
+ export type Epilogue = typeof EpilogueSchema.Type;
237
251
  export type Flow = typeof FlowSchema.Type;
@@ -21,11 +21,6 @@ export const BYTES32_LOWER_HEX = /^0x[0-9a-f]{64}$/;
21
21
  // checksums are mixed-case); the prefix itself must be lowercase.
22
22
  export const EVM_ADDRESS_HEX = /^0x[0-9a-fA-F]{40}$/;
23
23
 
24
- // `0x` followed by whole bytes. Calldata is decoded by `hexToBytes`, which
25
- // silently drops a trailing odd nibble, so odd-length input is rejected here
26
- // rather than compiled into a different call.
27
- export const HEX_BYTES = /^0x(?:[0-9a-fA-F]{2})*$/;
28
-
29
24
  // A decimal integer string with no sign, fraction, exponent or hex prefix.
30
25
  export const DECIMAL_UINT = /^[0-9]+$/;
31
26
 
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,28 +29,32 @@ 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,
37
44
  AssertionSpec,
45
+ CallCheckSpec,
38
46
  } from './continuation.js';
39
47
  export {
40
48
  CONTINUATION_COMMITMENT_OP_ID,
41
49
  HexStringSchema,
42
50
  ContinuationOutcomeSchema,
51
+ CommittedOutcomeSchema,
43
52
  ContinuationIntentSchema,
44
53
  Phase1ArtifactSchema,
45
54
  AssertionOwnerSchema,
46
55
  Erc20BalanceGteSpecSchema,
47
56
  NativeBalanceGteSpecSchema,
48
57
  CallCheckSpecSchema,
49
- Erc20BalanceDeltaGteSpecSchema,
50
- NativeBalanceDeltaGteSpecSchema,
51
58
  AssertionSpecSchema,
52
59
  settledOutcome,
53
60
  } from './continuation.js';
@@ -58,8 +65,6 @@ export type {
58
65
  } from './descriptor.js';
59
66
  export {
60
67
  Bytes32HexSchema,
61
- AssertedErc20BalanceGteSpecSchema,
62
- AssertedNativeBalanceGteSpecSchema,
63
68
  AssertedPredicateSchema,
64
69
  VerificationDescriptorSchema,
65
70
  canonicalAssertedPredicate,
@@ -78,6 +83,9 @@ export type {
78
83
  GenericComposeErrorKind,
79
84
  PreparationComposeError,
80
85
  SimulationRevertComposeError,
86
+ DeliveryComposeError,
87
+ DeliveryErrorDetails,
88
+ DeliveryErrorReason,
81
89
  GenericComposeError,
82
90
  FailedPreparedOp,
83
91
  MaterialiserInputBase,
@@ -102,7 +110,13 @@ export {
102
110
  isMaterialiserInput,
103
111
  } from './flow.js';
104
112
 
105
- export type { Availability, OutputAmount, Resource } from './resource.js';
113
+ export type {
114
+ Availability,
115
+ ERC20Resource,
116
+ NativeResource,
117
+ OutputAmount,
118
+ Resource,
119
+ } from './resource.js';
106
120
  export {
107
121
  erc20Resource,
108
122
  erc20Token,
@@ -181,6 +195,7 @@ export type {
181
195
  ManifestGuard,
182
196
  ManifestMaterialiser,
183
197
  ManifestPrecondition,
198
+ ManifestRouting,
184
199
  GuardSelector,
185
200
  GuardCompatibility,
186
201
  } from './manifest.js';
@@ -210,13 +225,14 @@ export {
210
225
  } from './chainCapabilities.js';
211
226
 
212
227
  export type {
213
- SweepTo,
214
228
  ComposeRun,
215
229
  ComposeCompileRequest,
216
230
  ComposeCompileSuccessData,
231
+ ExecutedEpilogue,
232
+ ExecutedForward,
217
233
  ComposeFill,
218
- ComposeFee,
219
234
  ComposeUserProgramSimulation,
235
+ ComposeWarning,
220
236
  ComposeAction,
221
237
  PriceImpact,
222
238
  SpendEntry,
@@ -294,12 +310,12 @@ export {
294
310
  ManifestGuardZod,
295
311
  ManifestMaterialiserZod,
296
312
  ManifestPreconditionZod,
313
+ ManifestRoutingZod,
297
314
  ComposeManifestZod,
298
315
  GuardSelectorZod,
299
316
  GuardCompatibilityZod,
300
317
  SettlementZod,
301
318
  AssertionSpecZod,
302
- AssertedPredicateZod,
303
319
  VerificationDescriptorZod,
304
320
  } from './zodSchemas.js';
305
321
  export type {
@@ -307,7 +323,7 @@ export type {
307
323
  StaticSolType,
308
324
  SettlementWire,
309
325
  SettlementEscrowWire,
326
+ SettlementBindingWire,
310
327
  AssertionSpecWire,
311
- AssertedPredicateWire,
312
328
  VerificationDescriptorWire,
313
329
  } from './zodSchemas.js';
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,
@@ -8,7 +8,10 @@ export type MaterialiserMetadata =
8
8
  // what was deposited. `min`, when present, is a floor the program asserts
9
9
  // on-chain right after the pull, so the deposit never lands below it.
10
10
  | { readonly kind: 'capped'; readonly amount: bigint; readonly min?: bigint }
11
- | { readonly kind: 'runtime' };
11
+ // The program pulls whatever the payer holds. `min`, when present, is a
12
+ // floor the program asserts on-chain right after the sweep, and the floor
13
+ // a compile may count on for the input.
14
+ | { readonly kind: 'runtime'; readonly min?: bigint };
12
15
 
13
16
  export interface MaterialiserResolution {
14
17
  readonly meta: MaterialiserMetadata;
@@ -21,11 +24,11 @@ export const foldMaterialiserMetadata = <R>(
21
24
  readonly exact: (amount: bigint) => R;
22
25
  readonly exactNative: (amount: bigint) => R;
23
26
  readonly capped: (amount: bigint, min: bigint | undefined) => R;
24
- readonly runtime: () => R;
27
+ readonly runtime: (min: bigint | undefined) => R;
25
28
  },
26
29
  ): R => {
27
30
  if (meta.kind === 'exact') return cases.exact(meta.amount);
28
31
  if (meta.kind === 'exact-native') return cases.exactNative(meta.amount);
29
32
  if (meta.kind === 'capped') return cases.capped(meta.amount, meta.min);
30
- return cases.runtime();
33
+ return cases.runtime(meta.min);
31
34
  };
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`.
@@ -62,13 +63,13 @@ export interface RouteAmountExact {
62
63
  * {@link RouteAmountExact} for native inputs.
63
64
  *
64
65
  * On a route that begins with an aggregator swap the swap's input amount is
65
- * pinned to the quoted amount derived from `simAmount` (net of any input fee
66
- * when fee injection applies): a runtime balance below that pinned amount
67
- * reverts, and a balance above it leaves the remainder as `unspentIn`, which
68
- * may be most of the input and which `sweepTo` receives. Under `EXACT` the
69
- * deposit and the pinned quote are the same number, so the `unspentIn` output
70
- * is zero and omitted; any pre-existing dust of the sold token in the proxy is
71
- * moved to `sweepTo` by the whole-balance sweep independently of that output.
66
+ * pinned to the quoted amount derived from `simAmount`: a runtime balance below
67
+ * that pinned amount reverts, and a balance above it leaves the remainder as
68
+ * `unspentIn`, which may be most of the input and which `sweepTo` receives.
69
+ * Under `EXACT` the deposit and the pinned quote are the same number, so the
70
+ * `unspentIn` output is zero and omitted; any pre-existing dust of the sold
71
+ * token in the proxy is moved to `sweepTo` by the whole-balance sweep
72
+ * independently of that output.
72
73
  */
73
74
  export interface RouteAmountAll {
74
75
  readonly type: 'ALL';
@@ -111,12 +112,6 @@ export interface ComposeRouteRequest {
111
112
  * `0` disables the check.
112
113
  */
113
114
  readonly maxPriceImpactBps?: number;
114
- /**
115
- * Integrator fee in basis points, taken from the input amount. Range 0–9000.
116
- * Defaults to `0` server-side when omitted. A non-zero value requires an
117
- * integration-scoped API key; the server rejects it otherwise.
118
- */
119
- readonly integratorFeeBps?: number;
120
115
  /** Opaque referrer tag forwarded to the underlying quote provider. */
121
116
  readonly referrer?: string;
122
117
  /**
@@ -135,7 +130,7 @@ export interface ComposeRouteRequest {
135
130
  * Accepts an address or `{ $ref: 'context.sender' }` (which counts as
136
131
  * explicit); `{ $ref: 'context.executionAddress' }` is rejected.
137
132
  */
138
- readonly sweepTo?: SweepTo;
133
+ readonly sweepTo?: ForwardTo;
139
134
  /**
140
135
  * `'strict'` (the default) fails the request when simulation detects a
141
136
  * revert; `'allow-revert'` returns a partial result with revert diagnostics